System Calls

System Calls System calls are used to communicate between the NitrOS9 operating system and assembly-language programs. There are two major types of calls—I/O calls and function calls.

Function calls include user mode calls and system mode calls.

Each system call has a mnemonic name. Names of I/O calls start with I$. For example, the Change Directory call is I$ChgDir. Names of function calls start with F$. For example, the Allocate Bits call is F$AllBit. The names are defined in the assembler-input conditions equate file called OS9Defs.

System mode calls are privileged. You can execute them only while NitrOS9 is in the system state (when it is processing another system call, executing a file manager or device driver, and so on).

System mode calls are included in this manual primarily for programmers writing device drivers and other system-level applications. Calling Procedure To execute any system calls, you need to use an SWI2 instruction: Load the 6809 registers with any appropriate parameters. Execute an SWI instruction, followed immediately by a constant byte, which is the request code. In the references in this chapter, the first line is the system call name (for example Close Path) and the second line contains the call’s mnemonic name (for example I$Close), the software interrupt Code 2 (103F), and the call’s request code (for example, 8F) in hexadecimal. After NitrOS9 processes the call, it returns any parameters in the 6809 registers. If an error occurs, the C bit of the condition code register is set and Register B contains the appropriate error code. This feature permits a BCS or BCC instruction immediately following the system call to branch either if there is an error or if no error occurs.

As an example, here is the Close system call:

LDA PATHNUM SWI2 FCB $8F BCS ERROR

You can use the assembler’s OS9 directive to simplify the call, as follows:

LDA PATHNUM OS9 I$Close BCS ERROR

The ASM assembler allows any combination of upper- or lowercase letters. The RMA assembler, included in the OS-9 Level Two Development Pak, is case sensitive. The names in this manual have been spelled with upper and lower case letters, matching the defs for RMA. I/O System Calls NitrOS9’s I/O calls are easier to use than many other systems’ I/O calls. This is because the calling program does not have to allocate and set up file control blocks, sector buffers, and so on.

Instead, NitrOS9 returns a 1-byte path number whenever a process opens a path to a file or device. Until the path is closed, you can use this path number in later I/O requests to identify the file or device.

In addition, NitrOS9 allocates and maintains its own data structures; so, you need not deal with them. System Call Descriptions The rest of this chapter consists of the system call descriptions. At the top of each description is the system call name, followed by its mnemonic name, the SWI2 code, and the request code. Next are the call’s entry and exit conditions, followed by additional information about the code where appropriate.

In the system call descriptions, registers not specified as entry or exit conditions are not altered. Strings passed as parameters are normally terminated with a space character and end-of-line character, or with Bit 7 of the last character set.

If an error occurs on a system call, the C bit of Register CC is set and Register B contains the error code. If no error occurs, the C bit is clear and Register B contains a value of zero. User Mode System Calls Quick Reference Following is a summary of the User Mode System Calls referenced in this chapter:

F$AllBit Sets bits in an allocation bit map F$Chain Chains a process to a new module F$CmpNam Compares two names F$CpyMem Copies external memory F$CRC Generates a cyclic redundancy check F$DelBit Deallocates bits in an allocation bit map F$Exit Terminates a process F$Fork Starts a new process F$GBlkMp Gets a copy of a system block map F$GPrDsc Gets a copy of a process descriptor F$Icpt Set a signal intercept trap F$ID Returns a process ID F$Link Links to a memory module F$Load Loads a module from mass storage F$Mem Changes a process’s data area size F$NMLink Links to a module; does not map the module into the user’s address space F$NMLoad Loads a module but does not map it into the user’s address space F$PErr Prints an error message F$PrsNam Parses a pathlist name F$SchBit Searches a bit map F$Send Sends a signal to a process F$Sleep Suspends a process F$SPrior Sets a process’s priority F$SSWI Sets a software interrupt vector F$STime Sets a system time F$SUser Sets a user ID number F$Time Returns the current time F$Unlink Unlinks a module F$Unload Unlinks a module by name F$Wait Waits for a signal I$Attach Attaches to an I/O device I$ChgDir Changes a working directory I$Close Closes a path I$Create Creates a new file I$Delete Deletes a file I$DeletX Deletes a file from the execution directory I$Detach Detaches an I/O device I$Dup Duplicates a path I$GetStt Gets a device’s status I$MakDir Creates a directory file I$Open Opens a path to an existing file I$Read Reads data from a device I$ReadLn Reads a line of data from a device I$Seek Positions a file pointer I$SetStt Sets a device’s status I$Write Writes data to a device I$WritLn Writes a data line to a device System Mode Calls Quick Reference Following is a summary of the System Mode Calls referenced in this chapter:

F$Alarm Sets up an alarm F$All64 Allocates a 64-byte memory block F$AllHRAM Allocates high RAM F$AllImg Allocates image RAM blocks F$AllPrc Allocates a process descriptor F$AllRAM Allocates RAM blocks F$AllTsk Allocates a process task number F$AProc Enters active process queue F$Boot Performs a system bootstrap F$BtMem Performs a memory request bootstrap F$ClrBlk Clears the specified block of memory F$DATLog Converts a DAT block offset to a logical address F$DelImg Deallocates image RAM blocks F$DelPrc Deallocates a process descriptor F$DelRAM Deallocates RAM blocks F$DelTsk Deallocates a process task number F$ELink Links modules using a module directory entry F$FModul Finds a module directory entry F$Find64 Finds a 64-byte memory block F$FreeHB Gets a free high block F$FreeLB Gets a free low block F$GCMDir Compacts module directory entries F$GProcP Gets a process’s pointer F$IODel Deletes an I/O module F$IOQu Puts an entry into an I/O queue F$IRQ Makes an entry into IRQ polling table F$LDABX Loads Register A from 0,X in Task B F$LDAXY Loads A[X,[Y]] F$LDDDXY Loads D[D+X,[Y]] F$MapBlk Maps the specified blocks F$Move Moves data to a different address space F$NProc Starts the next process F$RelTsk Releases a task number F$ResTsk Reserves a task number F$Ret64 Returns a 64-byte memory block F$SetImg Sets a process DAT image F$SetTsk Sets a process’s task DAT registers F$Slink Performs a system link F$SRqMem Performs a system memory request F$SRtMem Performs a system memory return F$SSvc Installs a function request F$STABX Stores Register A at 0,X in Task B F$VIRQ Makes an entry in a virtual IRQ polling table F$VModul Validates a module �User System Calls

"

Allocate Bits" Sets bits in an allocation bit map OS9 F$AllBit 103F 13

Entry Conditions D number of the first bit to set X starting address of the allocation bit map Y number of bits to set

Error Output CC carry set on error B error code (if any)

Additional Information Bit numbers range from 0 to n-1, where n is the number of bits in the allocation bit map. Warning: Do not issue the Allocate Bits call with Register Y set to 0 (a bit count of 0). � Chain Loads and executes a new primary module without creating a new process OS9 F$Chain 103F 05

Entry Conditions A language/type code B size of the area (in pages); must be at ??? X address of the module name or filename Y parameter area size (in pages); defaults to zero if not specified U starting address of the parameter area; must be at least one page

Error Output CC carry set on error B error code (if any)

Additional Information Chain loads and executes a new primary module, but does not create a new process. A Chain system call is similar to a Fork followed by an Exit, but it has less processing overhead. Chain resets the calling process program and data memory areas and begins executing a new primary module. It does not affect open paths. This is a user mode system call. Warning: Make sure that the hardware stack pointer (Register SP) is located in the direct page before Chain executes. Otherwise the system might crash or return a suicide attempt error. This precaution also prevents a suicide in the event that the new module requires a smaller data area than that in use. Allow approximately 200 bytes of stack space for execution of the Chain system call. Chain performs the following steps: It causes NitOS9 to unlink the process’s old primary module. NitOS9 parses the name string of the new process’s primary module (the program that is to be executed first). Then, it causes NitrOS9 to search the system module directory to see if a module with the same name, type, and language is already in memory. If the module is in memory, it links to it. If the module is not in memory, it uses the name string as the pathlist of a file to load into memory. Then, it links to the first module in this file. (Several modules can be loaded from a single file.) It reconfigures the data memory area to the size specified in the new primary module’s header. It intercepts and erases any pending signals.

The following diagram shows how Chain sets up the data memory area and registers for the new module.

" Parameter Area"  Y (highest address) "

Data Area

"  X,SP "

Direct Page

" "

 V,DP (lowest address)"

D parameter area size PC module entry point absolute address CC F=0, I=0; others are undefined

Registers Y and U (the top-of-memory and bottom-of-memory pointers, respectively) always have values at page boundaries. If the parent process does not specify a size for the parameter area, the size (Register D) defaults to zero. The data area must be at least one page.

(For more information, see the Fork system call.) � Compare Names Compares two strings for a match OS9 F$CmpNam 103F 11

Entry Conditions B length of string1 X address of string1 Y address of string2

Exit Conditions CC carry clear if the strings match

Additional Information The Compare Names call compares two strings and indicates whether they match. Use this call with the Parse Name system call. The second string must have the most significant bit (Bit 7) of the last character set. � Copy External Memory Reads external memory into the user’s buffer for inspection OS9 F$CpyMem 103F 1B

Entry Conditions D DAT image pointer X offset in block to begin copy Y byte count U caller’s destination buffer

Error Output CC carry set on error B error code (if any)

Additional Information You can view any system memory through the use of the Copy External Memory call. The call assumes Register X is the address of the 64K address space described by the DAT image given. If you pass the entire DAT image of a process, place a value in Register X that equals the address in the process space. If you pass a partial DAT image (the upper half), place a value in Register X that equals the offset from the beginning of the DAT image ($8000). The support module for this call is KrnP2. � CRC Calculates the CRC of a modle OS9 F$CRC 103F 17

Entry Conditions X starting byte address Y number of bytes U address of the 3-byte CRC accumulator

Exit Conditions Updates the CRC accumulator.

Additional Information The CRC call calculates the CRC (cyclic redundancy count) for use by compilers, assemblers, or other module generators. The calculation begins at the starting byte address and continues over the specified number of bytes. You need not cover an entire module in one call since the CRC can be accumulated over several calls. The CRC accumulator can be any 3-byte memory area. You must initialize it to $FFFFFF before the first CRC call. The updated accumulator does not include the last three bytes of the module. The three CRC bytes are stored there. Be sure to initialize the CRC accumulator only once for each module check by CRC. � Deallocate Bits Clears allocation map bits OS9 F$DelBit 103F 14

Entry Conditions D number of the first bit to clear X starting address of the allocation bit map Y number of bits to clear

Exit Conditions None

Additional Information The Deallocate Bits call clears bits in the allocation bit map pointed to by Register X. Bit numbers are in the range 0 to n-1, where n is the number of bits in the allocation bit map. Warning: Do not call Deallocate Bits with Register Y set to zero (a bit count of zero). � "

Exit" Terminates the calling process OS9 F$Exit 103F 06

Entry Conditions B status code to return to the parent process

Exit Conditions The process is terminated.

Additional Information The Exit system call is the only way a process can terminate itself. Exit deallocates the process’s data memory area and unlinks the process’s primary module. It also closes all open paths automatically. The Wait system call always returns to the parent the status code passed by the child in its Exit call. Therefore, if the parent executes a Wait and receives the status code, it knows the child has died. Exit unlinks only the primary module. Unlink any module that is loaded or linked to by the process before calling Exit. � "

Fork" Creates a child process OS9 F$Fork 103F 03

Entry Conditions A language/type code B size of the optional data area (in pages) X address of the module name or filename (See the following example) Y size of the parameter area (in pages); defaults to zero if not specified U starting address of the parameter area; must be at least one page

Exit Conditions X address of the last byte of the name + 1 (See the following example) A new process I/O number

Error Output CC carry set on error B error code (if any)

Additional Information Fork creates a new process, a child of the calling process. Fork also sets up the child process’s memory and 6809 registers and standard I/O paths. Before the Fork call: T E S T $0D "↑ X" After the Fork call: T E S T $0D "↑ X" This is the sequence of Fork’s operations NitOS9 parses the name string of the new process’s primary module (the program that NitrOS9 executes first). Then, it searches the system module directory to see if the program already is in memory. The next step depends on whether or not the program is already in memory. If the program is in memory, NitrOS9 links the module to the process and executes it. If the program is not in memory, NitrOS9 uses the name as the pathlist of the file that is to be loaded into memory. Then, the first module in the this file is linked to and executed. (Several modules can be loaded from one file.) NitrOS9 uses the primary module’s header to determine the initial size of the process’s data area. It then tries to allocate a contiguous RAM area of that size. (This area includes the parameter passing area, which is copied from the parent process’s data area.) The new process’s data memory area and registers are set up as show in the following diagram. NitrOS9 uses the execution offset given in the module header to set the program counter to the module’s entry point.

" Parameter Area"  Y (highest address) "

Data Area

"  X,SP "

Direct Page

" "

 V,DP (lowest address)"

D size of the parameter area PC module entry point absolute address CC F=0, I=0, other condition code flags are undefined

Registers Y and U (the top-of-memory and bottom-of-memory pointers, respectively) always have values at page boundaries.

As stated earlier, if the parent does not specify the size of the parameter area, the size defaults to zero. The minimum overall data area size is one page.

When the shell processes a command line, it passes a string in the parameter area. The string is a copy of the parameter part of the command line. To simplify string-oriented processing, the shell also inserts an end-of-line character at the end of the parameter string.

Register X points to the start byte of the parameter string. If the command line includes the optional memory size specification (#n or #nK), the shell passes that size as the requested memory size when executing the Fork. If any of the preceding operations is unsuccessful, the Fork is terminated and NitrOS9 returns an error to the caller. The child and parent processes execute at the same time unless the parent executes a Wait system call immediately after the Fork. In this case, the parent waits until the child dies before it resumes execution. Be careful when recursively calling a program that uses the Fork system call. Another child can be created with each new execution. This continues until the process table becomes full. Do not fork a process with a memory size of zero. � "

Get System Block Map" Gets a copy of the system block map OS9 F$GBlkMp 103F 19

Entry Conditions X pointer to the 1024-byte buffer

Exit Conditions D number of bytes per block ($2000) (MMU block size dependent) Y system memory block map size

Error Output CC carry set on error B error code (if any)

Additional Information The Get System block Map call copies the system’s memory block map into the user’s buffer for inspection. The NitrOS9 MFREE command uses this call to find out how much free memory exists. The support module for this call is KrnP2. � Get Module Directory Gets a copy of the system module directory OS9 F$GModDr 103F 1A

Entry Conditions X pointer to the 2048-byte buffer Y end of copied module directory U start address of the system module directory

Error Output CC carry set on error B error code (if any)

Additional Information The Get Module Directory call copies the system’s module directory into the user’s buffer for inspection. The NitrOS9 MDIR command uses this call to read the module directory. The support module for this call is KrnP2. � "

Get Process Descriptor" Gets a copy of the process’s process descriptor OS9 F$GPrDsc 103F 18

Entry Conditions A requested process ID X pointer to a 512-byte buffer

Error Output CC carry set on error X error code (if any)

Additional Information The Get Process Descriptor call copies a process descriptor into the calling process’s buffer for inspection. The data in the process descriptor cannot be changed. The NitrOS9 PROCS command uses this call to get information about each existing process. The support module for this call is KrnP2. � "

Intercept" Sets a signal intercept trap OS9 F$Icpt 103F 09

Entry Conditions X address of the intercept routine U starting address of the routine’s memory area

Exit Conditions Signals sent to the process cause the intercept routine to be called instead of the process being killed.

Additional Information Intercept tells NitrOS9 to set a signal intercept trap. Then, whenever the process receives a signal, NitrOS9 executes the process’s intercept routing. Store the address of the signal handler routine in Register X and the base address of the routine’s storage area in Register U. Once the signal trap is set, NitrOS9 can execute the intercept routine at any time because a signal can occur at any time. Terminate the intercept routine with an RTI instruction. If a process has not used the Intercept system call to set a signal trap, the process terminates if it receives a signal. This is the order in which F$Icpt operates: When the process receives a signal, NitrOS9 sets Registers U and B as follows:

U starting address of the intercept routine’s memory area B signal code (process’s termination status)

Note: The value of Register DP cannot be the same as it was when the Intercept call was made. After setting the registers, NitrOS9 transfers execution to the intercept routine. � "

Get ID" Returns a caller’s process ID and user ID OS9 F$ID 103F 0C

Entry Conditions None

Exit Conditions A process ID Y user ID

Additional Information The process ID is a byte value in the range 1 to 255. NitrOS9 assigns each process a unique process ID. The user ID is an integer from 0 to 65,535. It is defined in the system password file, and is used by the file security system and a few other functions. Several processes can have the same user ID. On a single user system (such as the Color Computer 3), the user ID is inherited from CC3Go, which forks the initial shell. � "

Link" Links to a memory module that has the specified name, language, and type OS9 F$Link 103F 00

Entry Conditions A type/language byte X address of the module name (See the following example)

Exit Conditions A type/language code B attributes / revision level (if no error) X address of the last byte of the module name + 1 (See the following example) U module header absolute address

Error Output CC carry set on error B error code (if any)

Additional Information The module’s link count increases by one whenever Link references its name. Incrementing in this manner keeps track of how many processes are using the module. If the module requested is not shareable (not re-entrant), only one process can link to it at a time. Before the Fork call: T E S T $0D "↑ X" After the Fork call: T E S T $0D "↑ X" This is the order in which the Link call operates: NitrOS9 searches the module directory for a module that has the specified name, language, and type. If NitrOS9 finds the module, the address of the module’s header is returned in Register U and the absolute address of the module’s execution entry point is returned in Register Y. (This, and other information, is contained in the module header.) If NitrOS9 does not find the module or if the type/language codes in the entry and exit conditions do not math, NitrOS9 returns one of the following errors Module not found Module busy (not shareable and in use) Incorrect or defective module header � "

Load" Loads a module or modules from a file OS9 F$Load 103F 01

Entry Conditions A type / language code; 0 = any language / type X address of the pathlist (filename) (See the following example)

Exit Conditions A language / type code B attributes / revision level (if no error) X address of the last byte of the pathlist (filename) + 1 (See the following example) Y primary module entry point address U address of the module header Error Output CC carry set on error B error code (if any)

Additional Information The Load call loads one or more modules from the file specified by a complete pathlist or from the working execution directory (if an incomplete pathlist is given). The file must have the execute access bit set. It also must contain one or more modules with proper module headers. NitrOS9 adds all modules loaded to the system module directory. It links the first module read. The exit conditions apply only to the first module loaded. Before the Load call: / D 0 / A C C T S R C V $0D "↑ X"

After the Load call: / D 0 / A C C T S R C V $0D "↑ X"

Possible errors: Module directory full Memory full Errors that occur on the Open, Read, Close, and Link system calls. � Memory Changes process’s data area size OS9 F$Mem 103F 07

Entry Conditions D size of the new memory area (in bytes); 0 = return current size and upper bound

Exit Conditions Y address of the new memory area upper bound D actual size of the new memory (in bytes)

Error Output CC carry set on error B error code (if any)

Additional Information The Memory call expands or contracts the process’s data memory area to the specified size. Or, if you specify zero as the new size, the call returns the current size and upper boundaries of data memory. NitrOS9 rounds off the size to the next page boundary. In allocating additional memory, NitrOS9 continues upward from the previous highest address. In deallocating unneeded memory, it continues downward from that address. � Link to a module Links to a module; does not map the module into the user’s address space OS9 F$NMLink 103F 21

Entry Conditions A type / language byte X address of the module name

Exit Conditions A type / language code B module revision X address of the last byte of the module name + 1; any trailing blanks are skipped Y storage requirement for the module

Error Output CC carry set on error B error code (if any)

Additional Information Although this call is similar to F$Link, it does not map the specified module into the user’s address space but does return the memory requirement for the module. A calling process can use this memory requirement information to fork a program with a maximum amount of space. F$NMLink can therefore fork larger programs than can be forked by F$Link. � Load a module Loads one or more modules from a file but does not map the module into the user’s address space OS9 F$NMLoad 103F 22

Entry Conditions A type / language byte X address of the pathlist

Exit Conditions A type / language code B module revision X address of the last byte of the pathlist + 1 Y storage requirement for the module

Error Output CC carry set on error B error code (if any)

Additional Information If you do not provide a full pathlist for this call, it attempts to load from a file in the current execution directory. Although this call is similar to F$Load, it does not map the specified module into the user’s address space but does return the memory requirement for the module. A calling process can use this memory requirement information to fork a program with a maximum amount of space. F$NMLoad can therefore fork larger programs than can be forked by F$Load. � Print Error Writes an error message to a specified path OS9 F$PErr 103F 0F

Entry Conditions B error code

Error Output CC carry set on error B error code (if any)

Additional Information Print Error writes an error message to the standard error path for the specified process. By default, NitrOS9 shows:

ERROR #decimal number

The error reporting routine is vectored. Using the Set SVC system call, you can replace it with a more elaborate reporting module. To replace this routine use the Set SVC system call. � Parse Name Scans an input string for a valid NitrOS9 name OS9 F$PrsNam 103F 10

Entry Conditions X address of the pathlist (See the following example)

Exit Conditions X address of the optional slash + 1 Y address of the last character of the name + 1 A trailing byte (delimiter character) B length of the name

Error Output CC carry set on error B error code (if any) Y address of the first non-delimiter character in the string

Additional Information Parses, or scans, the input text string for a legal NitrOS9 name. It terminates the name with any character that is not a legal name character. Parse Name is useful for processing pathlist arguments passed to a new process. Because Parse Name processes only one name, you might need several calls to process a pathlist that has more than one name. As you can see from the following example, Parse Name finishes with Register Y in position for the next parse. If Register Y was at the end of a pathlist, Parse Name returns a bad name error. It then moves the pointer in Register Y past any space characters so that it can parse the next pathlist in a command line. Before the Parse Name call:

/ D 0 / P A Y R O L L "↑ X"

After the Parse Name call: / D 0 / P A Y R O L L "↑ X" "↑ Y" B=2 � "

Search Bits" Searches a specified memory allocation bit map for a free memory block of a specified size OS9 F$SchBit 103F 12

Entry Conditions D starting bit number X starting address of the map Y bit count (free bit block size) U ending address of the map

Exit Conditions D starting bit number Y bit count

Error Output CC carry set on error B error code (if any)

Additional Information The Search Bit call searches the specified allocation bit map for a free block (cleared bits) of the required length. The search starts at the starting bit number. If no block of the specified size exists, the call returns with the carry set, starting bit number, and size of the largest block. � "

Send" Sends a signal to a specified process OS9 F$Send 103F 08

Entry Conditions A destination process ID B signal code

Error Output CC carry set on error B error code (if any)

Additional Information The signal code is a single byte value in the rage 0 through 255. If the destination process is sleeping or waiting, NitrOS9 activates the process so that the process can process the signal. If a signal trap is set up, F$Send executes the signal processing routing (Intercept). If none was set up, the signal terminates the destination process and the signal code becomes the exit status. (See the Wait system call.) An exception is the wakeup signal; that signal does not cause the signal intercept routine to be executed. Signal codes are defined as follows:

0 System terminate (cannot be intercepted) 1 Wake up the process 2 Keyboard terminate 3 Keyboard interrupt 128-255 User defined

If you try to send a signal to a process that has a signal pending, NitrOS9 cancels the current Send call and returns an error. Issue a Sleep call for a few ticks; then, try again. The Sleep call saves CPU time. See the Intercept, Wait, and Sleep system calls for more information. � Sleep Temporarily turns off the calling process OS9 F$Sleep 103F 0A

Entry Conditions X One of the following: sleep time (in ticks) 0 = sleep indefinitely 1 = sleep for the remainder of the current time slice

Exit Conditions X sleep time minus the number of ticks that the process was asleep

Error Output CC carry set on error B error code (if any)

Additional Information If Register X contains zero, NitrOS9 turns the process off until it receives a signal. Putting a process to sleep is a good way to wait for a signal or interrupt without wasting CPU time. If Register X contains one, NitrOS9 turns the process off for the remainder of the process’s current time slice. It inserts the process into the active process queue immediately. The process resumes execution when it reaches the front of the queue. If Register X contains an integer in the rage 2-255, NitrOS9 turns off the process for the specified number of ticks, n. It inserts the process into the active process queue after n-1 ticks. The process resumes execution when it reaches the front of the queue. If the process receives a signal, it awakens before the time has elapsed. When you select processes among multiple windows, you might need to sleep for two ticks. � Set Priority Changes the priority of a process OS9 F$SPrior 103F 0D

Entry Conditions A process ID B priority 0 lowest 255 highest

Error Output CC carry set on error B error code (if any)

Additional Information Set Priority changes the process’s priority to the priority specified. A process can change another process’s priority only if it has the same user ID. � "

Set SWI" Sets the SWI, SWI2, and SWI3 vectors OS9 F$SSWI 103F 0E

Entry Conditions A SWI type code X address of the user software interrupt routine

Error Output C carry set on error B error code (if any)

Additional Information Sets the interrupt vectors for SWI, SWI2, and SWI3 instructions. Each process has its own local vectors. Each Set SWI call sets one type of vector according to the code number passed in Register A:

1 SWI 2 SWI2 3 SWI3

When NitrOS9 creates a process, it initializes all three vectors with the address of the NitrOS9 service call processor. Warning: Microware-supplied software uses SWI2 to call NitrOS9. If you reset this vector, these programs cannot work. If you change all three vectors, you cannot call NitrOS9 at all. � Set Time Sets the system time and date OS9 F$STime 103F 16

Entry Conditions X relative address of the time packet

Error Output CC carry set on error B error code (if any)

Additional Information Set Time sets the current system date and time and starts the system real-time clock. The date and time are passed in a time packet as follows:

"Relative Address" Value 0 year 1 month 2 day 3 hours 4 minutes 5 seconds

Then, the call makes a link system call to find the clock. If the link is successful, NitrOS9 calls the clock initialization. The clock initialization: Sets up hardware dependent functions Sets up the F$Time system call via F$SSVc � Set User ID Number Changes the current user ID without checking for errors or checking the ID number of the caller OS9 F$SUser 103F 1C

Entry Conditions Y desired user ID number

Error Output CC carry set on error B error code (if any)

Additional Information The support module for this call is Krn. � "

Time" Gets the system date and time OS9 F$Time 103F 15

Entry Conditions X address of the area in which to store the date and time packet

Exit Conditions X date and time

Error Output CC carry set on error B error code (if any)

Additional Information The Time call returns the current system date and time in the form of a 6-byte packet (in binary). NitrOS9 copies the packet to the address passed in Register X. The packet looks like this:

Time is a part of the clock module and it does not exist if no previous call to F$STime has been made. � "

Unlink" Unlinks (removes from memory) a module that is not in use and that has a link count of zero OS9 F$UnLink 103F 02

Entry Conditions U address of the module header

Error Output CC carry set on error B error code (if any)

Additional Information Unlink unlinks a module from the current process’s address space, decreases its link count by one, and, if the link count becomes zero, returns the memory where the module was located to the system for use by other processes. You cannot unlink system modules or device drivers that are in use. Unlink operates in the following order: Unlink tells NitrOS9 that the calling process no longer needs the module. NitrOS9 decreases the module’s link count by one. When the resulting link count is zero, NitrOS9 destroys the module.

If any other process is using the module, the module’s link count cannot fall to zero. Therefore, NitrOS9 does not destroy the module.

If you pass a bad address, Unlink cannot find a module in the module directory and does not return an error. � "

Unlink a Module By Name" Decrements a specified module’s link count, and removes the module from memory if the resulting link count is zero OS9 F$UnLoad 103F 1D

Entry Conditions A module type X pointer to module name

Error Output CC carry set on error B error code (if any)

Additional Information This system call differs from Unlink in that it uses a pointer to the module name instead of the address of the module header. The support module for this call is KrnP2. � "

Wait" Temporarily turns off a calling process OS9 F$Wait 103F 04

Entry Conditions None

Exit Conditions A deceased child process’s ID B deceased child process’s exist status (if no error)

Error Output CC carry set on error B error code, if any

Additional Information The Wait call turns off the calling process until a child process dies, either by exiting an Exit system call, or by receiving a signal. The Wait call helps you save system time. NitrOS9 returns the child’s process ID and exit status to the parent. If the child died because of a signal, the exit status byte (Register B) contains the signal code. If the caller has several children, NitrOS9 activates the caller when the first one dies. Therefore, you need to use one Wait system call to detect the termination of each child. NitrOS9 immediately reactivates the caller if a child dies before the Wait call. If the caller has no children, Wait returns an error. (See the Exit system call for more information.) If the Wait call returns with the carry bit set, the Wait function was not successful. If the carry bit is cleared, Wait functioned normally and any error that occurred in the child process is returned in Register B.

�I/O User System Calls

"

Attach" Attaches a device to the system or verifies device attachment. OS9 I$Attach 103F 80

Entry Conditions A access mode X address of the device name string

Exit Conditions X updated past device name U address of the device table entry

Error Output CC carry set on error B error code, if any

Additional Information Attach does not reserve the device. It only prepares the device for later use by any process. NitrOS9 installs most devices automatically on startup. Therefore, you need to use Attach only when installing a device dynamically or when verifying the existence of a device. You need not use the Attach system call to perform routing I/O. The access mode parameter specifies the read and/or write operations to be allowed. These are:

0 = Use any special device capabilities 1 = Read only 2 = Write only 3 = Update (read and write)

Attach operates in this sequence: NitrOS9 searches the system module to see if any memory contains a device descriptor that has the same name as the device. NitrOS9’s next operation depends on whether or not the device is already attached. If NitrOS9 finds the descriptor and if the device is not already attached, NitrOS9 link the device’s file manager and device driver. It then places the address of the manager and the driver in a new device table entry. NitrOS9 then allocates any memory needed by the device driver, and calls the driver’s initialization routine, which initializes the hardware. If NitrOS9 finds the descriptor, and if the device is already attached, NitrOS9 verifies the attachment. � "

Change Directory" Changes the working directory of a process to a directory specified by a pathlist. OS9 I$ChgDir 103F 86

Entry Conditions A access mode X address of the pathlist

Exit Conditions X updated past pathlist

Error Output CC carry set on error B error code, if any

Additional Information If the access mode is read, write, or update, NitrOS9 changes the current data directory. If the access mode is execute, NitrOS9 changes the current execution directory. The calling process must have read access to the directory specified (public read if the directory is not owned by the calling process). The access modes are:

0 = Use any special device capabilities 1 = Read only 2 = Write only 3 = Update (read and write) � Close Path Terminates an I/O path OS9 I$Close 103F 8F

Entry Conditions A path number

Error Output CC carry set on error B error code, if any

Additional Information Close Path terminates the I/O path to the file or device specified by path number. Until you use another Open, Dup, or Create system call for that path, you can no longer perform I/O to the file or device. If you close a path to a single-user device, the device becomes available to other requesting processes. NitrOS9 deallocates internally managed buffers and descriptors. The Exit system call automatically closes all open paths. Therefore, you might not need to use the Close Path system call to close some paths. Do not close a standard I/O path unless you want to change the file or device to which it corresponds. Close Path performs an implied I$Detach call. If it causes the device link count to become 0, the device termination routine is executed. See I$Detach for additional information. � Create File Creates and opens a disk file OS9 I$Create 103F 83

Entry Conditions A access mode (write or update) B file attributes X address of the pathlist

Exit Conditions A path number X address of the last byte of the pathlist + 1; skips any trailing blanks

Error Output CC carry set on error B error code, if any

Additional Information NitrOS9 parses the pathlist and enters the new filename in the specified directory. If you do not specify a directory, NitrOS9 enters the new filename in the working directory. NitrOS9 gives the file the attributes passed in Register B, which has bits defined as follows:

Bit Definition 0 Read 1 Write 2 Execute 3 Public read 4 Public write 5 Public execute 6 Shareable file

These access mode parameters passed in Register A must have the write bit set if any data is to be written. These access codes are defined as follows: 2 = write, 3 = update. The mode affects the file only until the file is closed. You can reopen the file in any access mode allowed by the file attributes. (See the Open system call.) Files opened for write can allow faster data transfer than those opened for update because update sometimes needs to pre-read sectors. If the execute bit (Bit 2) is set, the file is created in the working execution directory instead of the working data directory. Create File causes an implicit I$Attach call. If the device has not previously been attached, the device’s initialization routine is called. Later I/O calls use the path number to identify the file, until the file is closed. NitrOS9 does not allocate data storage for a file at creation. Instead, it allocates the storage either automatically when you first issue a write or explicitly by the SetStat subroutine. If the filename already exists in the directory, an error occurs. If the call specifies a non-multiple file device (such as a printer or terminal), Create behaves the same as Open. You cannot use Create to make directories. (See the Make Directory system call for instructions on how to make directories.) Before the Create File call:

/ D 0 / W O R K $0D "↑ X"

After the Create File call: / D 0 / W O R K $0D "↑ X"

� Delete File Deletes a specified disk file OS9 I$Delete 103F 87

Entry Conditions X address of the pathlist

Exit Conditions X address of the last byte of the pathlist + 1; skips any trailing blanks

Error Output CC carry set on error B error code, if any

Additional Information The Delete File call deletes the disk file specified by the pathlist. The file must have write permission attributes (public write, if the calling process is not the owner). An attempt to delete a device results in an error. The caller must have non-shareable write access to the file or an error results.

Example Before the Delete File call:

/ D 0 / W O R K M E M O $0d "↑ X"

After the Delete File Call / D 0 / W O R K M E M O $0d "↑ X"

� Delete A File Deletes a file from the current data or current execution directory OS9 I$DeletX 103F 90

Entry Conditions A access mode X address of the pathlist

Exit Conditions X address of the last byte of the pathlist + 1; skips any trailing blanks

Error Output CC carry set on error B error code, if any

Additional Information The Delete A File call removes the disk file specified by the selected pathlist. This function is similar to I$Delete except that it access an access mode byte. If the access mode is execute, the call selects the current execution directory. Otherwise, it selects the current data directory. If a complete pathlist is provided (the pathlist begins with a slash (/)), the access mode of the call ignores the access mode. Only use this call to delete a file. If you attempt to use I$DeletX to delete a device, the system returns an error. � Detach Device Removes a device from the system device table OS9 I$Detach 103F 81

Entry Conditions U address of the device table entry

Error Output CC carry set on error B error code, if any

Additional Information The Detach Device call removes a device from both the system and the system device table, assuming the device is not being used by another process. You must use this call to detach devices attached using the Attach system call. Attach and Detach are both used mainly by the I/O manager. SCF also uses Attach and Detach to set up its second device (echo device). This is the sequence of the operation of Detach Device: Detach Device calls the device driver’s termination routine. Then, NitrOS9 deallocates any memory assigned to the driver. NitrOS9 unlinks the associated device driver and file manager modules. NitrOS9 then removes the driver, as long as no other module is using that driver. � Duplicate Path Returns a synonymous path number OS9 I$Dup 103F 82

Entry Conditions A old path number (number of path to duplicate)

Exit Conditions A new path number (if no error)

Error Output CC carry set on error B error code, if any

Additional Information The Duplicate Path returns another, synonymous path number for the file or device specified by the old path number. The shell uses the Duplicate Path call when it redirects I/O. System calls can use either path number (old or new) to operate on the same file or device. Makes sure that no more than one process is performing I/O on any one path at the same time. Concurrent I/O on the same path can cause unpredictable results with RBF files. The I$Dup call always uses the lowest available path number. This lets you manipulate standard I/O paths to contain any desired paths. � Get Status Returns the status of a file or device OS9 I$GetStt 103F 8D

Entry Conditions A path number B function code

Error Output CC carry set on error B error code, if any

Additional Information The Status is a wildcard call. Use it to handle device parameters that: Are not the same for all devices Are highly hardware-dependent Must be user-changeable The exact operation of the Get Status system call depends on the device driver and file manager associated with the path. A typical use is to determine a terminal’s parameters for such functions as backspace character and echo on/off. The Get Status call is commonly used with the Set Status call. The Get Status function codes that are currently defined are listed in the “Get Status System Calls” section. � Make Directory Creates and initializes a directory OS9 I$MakDir 103F 85

Entry Conditions B directory attributes X address of the pathlist

Exit Conditions X address of the last byte of the pathlist + 1; skips any trailing blanks

Error Output CC carry set on error B error code, if any

Additional Information The Make Directory call creates and initializes a directory as specified by the pathlist. The directory contains only two entries, one for itself (.) and one for its parent directory (..). NitrOS9 makes the calling process the owner of the directory. Because the Make Directory call does not open the directory, it does not return a path number. The new directory automatically has its directory bit set in the access permission attributes. The remaining attributes are specified by the byte passed in Register B. The bits are defined as follows:

Bit Definition 0 Read 1 Write 2 Execute 3 Public read 4 Public write 5 Public execute 6 Single-user 7 Don’t care

� Open Path Opens a path to an existing file or device as specified by the pathlist OS9 I$Open 103F 84

Entry Conditions A access mode (D S PE PW PR E W R) X address of the pathlist

Exit Conditions A path number X address of the last byte of the pathlist + 1; skips any trailing blanks

Error Output CC carry set on error B error code, if any

Additional Information NitrOS9 searches for the file in one of the following: The directory specified by the pathlist if the pathlist begins with a slash. The working data directory, if the pathlist does not begin with a slash. The working execution directory, if the pathlist does not begin with a slash and if the execution bit is set in the access mode. NitrOS9 returns a path number for later system calls to use to identify the file. The access mode parameter lets you specify which read and/or write operations are to be permitted. When set, each access mode bit enables one of the following: Write, Read, Read and Write, Update, Directory I/O. The access mode must conform to the access permission attributes associated with the file or device. (See the Create system call.) Only the owner can access a file unless the appropriate public permission bits are set. The update mode might be slightly slower than the others because it might require pre-reading of sectors for random access of bytes within sectors. Several processes (users) can open files at the same time. Each device has an attribute that specifies whether or not it is shareable. If the single-user bit is set, the file opened for singer-user access regardless of the settings of the file’s permission bits. You must open directory files for read or write if the directory bit (Bit 7) is set in the access mode. Open Path always uses the lowest path number available for the process.

� Read Read n bytes from a specified path OS9 I$Read 103F 89

Entry Conditions A path number X address in which to store the data Y number of bytes to read

Exit Conditions Y number of bytes read

Error Output CC carry set on error B error code, if any

Additional Information The Read call reads the specified number of bytes from the specified path. It returns the data exactly as read from the file/device without additional processing or editing. The path must be opened in the read or update mode. If there is not enough data in the specified file to satisfy the read request, the read call reads fewer bytes than requested but an end-of-file error is not returned. After all data in file is read, the next I$Read call returns an end-of-file error. If the specified file is open for update, the record read is locked out on RBF-type devices. The keyboard terminate, keyboard interrupt, and end-of-file characters are filtered out of the Entry Conditions data on SCF-type devices unless the corresponding entries in the descriptor have been set to zero. You might want to modify the device descriptor so that these values are initialized to zero when the path is opened. The call reads the number of bytes requested unless Read encounters any of the following: An end-of-file character An end-of-record character (SCF only) An error � Read Line With Editing Reads a text line with editing OS9 I$ReadLn 103F 8B

Entry Conditions A path number X address at which to store data Y maximum number of bytes to read

Exit Conditions Y number of bytes read

Error Output CC carry set on error B error code, if any

Additional Information Read Line is similar to Read. The difference is that Read Line reads the input file or device until it encounters a carriage return character or until it reaches the maximum byte count specified, whichever comes first. The Read Line also automatically activates line editing on character oriented devices, such as terminals and printers. The line editing refers to auto line feed, null padding at the end of the line, backspacing, line deleting, and so on. SCF requires that the last byte entered be an end-of-record character (usually a carriage return). If more data is entered than the maximum specified, Read Line does not accept it and a PD.OVF character (usually a bell) is echoed. After one Read Line call reads all the data in a file, the next Read Line call generates an end-of-file error. For more information about line editing, see “SCF Line Editing Functions” in Chapter 6. � Seek Repositions a file pointer OS9 I$Seek 103F 88

Entry Conditions A path number X MS 16 bits of the desired file position Y LS 16 bits of the desired file position

Error Output CC carry set on error B error code, if any

Additional Information The Seek call repositions the path’s logical file pointer, the 32-bit address of the next byte in the file to be read from or written to. You can perform a seek to any value, regardless of the file’s size. Later writes automatically expand the file to the required size (if possible). Later reads, however, return an end-of-file condition. Note that a seek to Address 0 is the same as a rewind operation. NitrOS9 usually ignores seeks to non-random access devices, and returns without error. On RBF devices, seeking to a new disk sector causes the internal disk buffer to be rewritten to disk if it has been modified. Seek does not change the state of record locking. � Set Status Sets the status of a file or device OS9 I$SetStt 103F 8E

Entry Conditions A path number B function code Other registers depend on the function code

Error Output CC carry set on error B error code, if any Other registers depend on the function code

Additional Information Set Status is a wildcard call. Use it to handle device parameters that: Are not the same for all devices Are highly hardware-dependent Must be user-changeable The exact operation of the Set Status system call depends on the device driver and file manager associated with the path. A typical use is to set a terminal’s parameters for such functions as backspace character and echo on/off. The Set Status call is commonly used with the Get Status call. The Set Status function codes that are currently defined are listed in the “Set Status System Calls” section. � Write Writes to a file or device OS9 I$Write 103F 8A

Entry Conditions A path number X starting address of data to write Y number of bytes to write

Exit Conditions Y number of bytes written

Error Output CC carry set on error B error code, if any

Additional Information The Write system call writes to the file or device associated with the path number specified. Before using Write, be sure the path is opened or created in the write or update access mode. NitrOS9 writes data to the file or device without processing or editing the data. NitrOS9 automatically expands the file if you write data path the present end-of-file. � Write Line Writes to a file or device until it encounters a carriage return OS9 I$WritLn 103F 8C

Entry Conditions A path number X address of the data to write Y maximum number of bytes to read

Exit Conditions Y number of bytes written

Error Output CC carry set on error B error code, if any

Additional Information Writes to the file or device that is associated with the path number specified. Write Line is similar to Write. The difference is that Write Line writes data until it encounters a carriage return character. It also activates line editing for character-oriented devices, such as terminals and printers. The line editing refers to auto line feed, null padding at the end of the line, backspacing, line deleting, and so on. Before using Write Line, be sure the path opened or created in the write or update access mode. For more information about line editing, see “SCF Line Editing Functions” in Chapter 6.

�Privileged System Mode Calls

Set an Alarm Sets an alarm to ring the bell at a specified time OS9 F$Alarm 103F 1E

Entry Conditions X relative address of time packet

Error Output CC carry set on error B error code, if any

Additional Information When the system reaches the specified alarm time, it rings the bell for 15 seconds. The time packet is identical to the packet used in the F$STime call. See F$STime for additional information on the format of the packet. All alarms begin at the start of a minute and any seconds in the packet are ignored. The system is limited to one alarm at a time. � Allocate 64 Dynamically allocates 64-byte blocks of memory OS9 F$All64 103F 30

Entry Conditions X base address of the page table; 0 = the page table has not been allocated

Exit Conditions A block number X base address of the page table Y address of the block

Error Output CC carry set on error B error code, if any

Additional Information The Allocate 64 system call allocates the 64-byte blocks of memory by splitting pages (256-byte sections) into four sections. NitrOS9 uses the first 64 bytes of the base page as a page table. This table contains the page number (most significant byte of the address) of all pages in the memory structure. If Register X passes a value of zero, the call allocates a new base page and the first 64-byte memory block. Whenever a new page is needed, a Request System Memory system call (F$SRqMem) executes automatically. The first byte of each block contains the block number. Routines that use the Allocate 64 call should not alter this byte. The following diagram shows how seven blocks might be allocated:

Any Memory Page Any Memory Page Base Page  " Page Table (64 bytes)" "X Block 4 (64 bytes)" "X Block 1 (64 bytes)" "X Block 5 (64 bytes)" "X Block 2 (64 bytes)" "X Block 6 (64 bytes)" "X Block 3 (64 bytes)" "X Block 7 (64 bytes)" � Allocate High RAM Allocate system memory from high physical memory OS9 F$AllHRam

Entry Conditions B number of blocks

Error Output CC carry set on error B error code, if any

Additional Information This call searches for the desired number of contiguous free RAM blocks, starting its search at the top of memory. F$AllHRam is similar to F$AllRAM except F$AllRAM begins its search at the bottom of memory. Screen allocation routines use this call to provide a better chance of finding the necessary memory for a screen. � Allocate Image Allocates RAM blocks for process DAT image OS9 F$AllImg 103F 3A

Entry Conditions A starting block number B number of blocks X process descriptor pointer

Error Output CC carry set on error B error code, if any

Additional Information Use the Allocate Image system call to allocate a data area for a process. The blocks that Allocate Image define might not be contiguous. The support module for this system call is Krn. � Allocate Process Descriptor Allocates and initializes a 512-byte process descriptor OS9 F$AllPrc 103F 4B

Entry Conditions None

Exit Conditions U process descriptor pointer

Error Output CC carry set on error B error code, if any

Additional Information The process descriptor table houses the address of the descriptor. Initialization of the process descriptor consists of clearing the first 256 bytes of the descriptor, setting up the state as a system state, and marking as unallocated as much of the DAT image as the system allows—typically, 60-64 kilobytes. The support module for this system call is KrnP2. The call also brances to the F$SRqMem call. � Allocate RAM Searches the memory block map for the desired number of contiguous free RAM blocks OS9 F$AllRAM 103F 39

Entry Conditions B number of blocks

Error Output CC carry set on error B error code, if any

Additional Information The support module for this system call is Krn. � Allocate Process Task Number Determines whether NitrOS9 has assigned a task number to the specified process OS9 F$AllTsk 103F 3F

Entry Conditions X process descriptor pointer

Error Output CC carry set on error B error code, if any

Additional Information If the process does not have a task number, NitrOS9 allocates a task number and copies the DAT image into the DAT hardware. The support module for this call is Krn. Allocate Process Task Number also branches to F$ResTsk and F$SetTsk. � Insert Process Inserts a process into the queue for execution OS9 F$AProc 103F 2C

Entry Conditions X address of the process descriptor

Error Output CC carry set on error B error code, if any

Additional Information The Insert Process system call inserts a process into the active process queue so that NitrOS9 can schedule the process for execution. NitrOS9 sorts all processes in the queue by process age (the count of how many process switches have occurred since the process’s last time slice). When a process is moved to the active process queue, NitrOS9 sets its age according to its priority—the higher the priority, the higher the age. An exception is a newly active process that was deactivated while in the system state. NitrOS9 gives such a process higher priority because the process usually is executing critical routines that affect shared system resources. � Bootstrap System Links either the module named Boot or the module specified in the INIT module OS9 F$Boot 103F 35

Entry Conditions None

Error Output CC carry set on error B error code, if any

Additional Information When it calls the linked module, Boot expects to receive a pointer giving it the location and size of an area in which to search for the new module. The support module for this call is Krn. Bootstrap System also branches to the F$Link and F$VModul system calls. � Bootstrap Memory Request Allocates the requested memory (rounded to the nearest block) as contiguous memory in the system’s address space OS9 F$BtMem 103F 36

Entry Conditions D byte count requested

Exit Conditions D byte count granted U pointer to allocated memory

Error Output CC carry set on error B error code, if any

Additional Information This call is identical to F$SRqMem. The Bootstrap Memory Request support module is Krn.

� Clear Specified Block Marks blocks in the process DAT image as unallocated OS9 F$ClrBlk 103F 50

Entry Conditions B number of blocks U address of first block

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information After Clear Specified Block deallocates blocks, the blocks are free for the process to use for other data or program areas. If the block address passed to Clear Specified Block is invalid or if the call attempts to clear the stack area, it return E$IBA. The support module for the call is KrnP2.

� DAT to Logical Address Converts a DAT image block number and block offset to its equivalent logical address OS9 F$DATLog 103F 44

Entry Conditions B DAT image offset X block offset

Exit Conditions X logical address

Error Output CC carry set on error B error code, if any

Additional Information Following is a sample conversion:

"

" " 2000 - 2FFF " "Input: B = 2

          X = $0329"

" 1000 - 1FFF " Output: X=$2329 " 0 - FFF "

The support module for this call is Krn.

� Deallocate Image RAM Blocks Deallocates image RAM blocks OS9 F$DelImg 103F 3B

Entry Conditions A number of starting block B block count X process descriptor pointer

Error Output CC carry set on error B error code, if any

Additional Information This system call deallocates memory from a process’s address space. It frees the RAM for system use and frees the DAT image for the process. Its main use is to let the system clean up after a process death. The support module for this call is KrnP2.

� Deallocate Process Descriptor Returns a process descriptor’s memory to a free memory pool OS9 F$DelPrc 103F 4C

Entry Conditions A process ID

Error Output CC carry set on error B error code, if any

Additional Information Use this call to clear the system scratch memory and stack area associated with the process. The support module for this call is KrnP2.

� Deallocate RAM blocks Clears a block’s RAM In Use flag in the system memory block map OS9 F$DelRAM 103F 51

Entry Conditions B number of blocks X starting block number

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The Deallocate RAM Blocks call assumes the blocks being deallocated are not associated with any DAT image. The support module for this call is KrnP2.

� Deallocate Task Number Releases the task number that the process specified by the passed descriptor pointer OS9 F$DelTsk 103F 40

Entry Conditions X process descriptor pointer

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The support module for this call is Krn.

� Link Using Module Directory Entry Performs a link using a pointer to a module directory entry OS9 F$ELink 103F 4D

Entry Conditions B module type X pointer to module directory entry

Exit Conditions U module header address Y module entry point

Error Output CC carry set on error B error code, if any

Additional Information This call differs from Link in that you supply a pointer to the module directory entry rather than a pointer to a module name. The support module for this call is Krn.

� Find Module Directory Entry Returns a pointer to the module directory entry OS9 F$FModul 103F 4E

Entry Conditions A module type X pointer to the name string Y DAT image pointer (for name)

Exit Conditions A module type B module revision number X updated name string (if Register A contains 0 on entry) U module directory entry pointer

Error Output CC carry set on error B error code, if any

Additional Information The Find Module Directory Entry call returns a pointer to the module directory entry for the first module that has a name and type matching the specified name and type. If you pass a module type of zero, the system call finds any module. The support module for this call is Krn.

� Find 64 Returns the address of a 64-byte memory block OS9 F$Find64 103F 2F

Entry Conditions A block number X address of the block

Exit Conditions Y address of the block CC carry set if block not allowed or not in use

Error Output CC carry set on error B error code, if any

Additional Information NitrOS9 uses Find 64 to find path descriptors when given their block number. The block number can be any positive integer.

� Get Free High Block Searches the DAT image for the highest set of contiguous free blocks of the specified size OS9 F$FreeHB 103F 3E

Entry Conditions B block count Y DAT image pointer

Exit Conditions A starting block number

Error Output CC carry set on error B error code, if any

Additional Information The Get Free High Block call returns the block number of the beginning memory address of the free blocks. The support module for this system call is Krn.

� Get Free Low Block Searches the DAT image for the lowest set of contiguous free blocks of the specified size OS9 F$FreeLB 103F 3D

Entry Conditions B block count Y DAT image pointer

Exit Conditions A starting block number

Error Output CC carry set on error B error code, if any

Additional Information The Get Free Low Block call returns the block number of the beginning memory address of the free blocks. The support module for this system call is Krn.

� Compact Module Directory Compacts the entries in the module directory OS9 F$GCMDir 103F 52

Entry Conditions None

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information This function is only for internal NitrOS9 system use. You should never call it from a program.

� Get Process Pointer Gets a pointer to a process OS9 F$GProcP 103F 37

Entry Conditions A process ID

Exit Conditions B pointer to process descriptor (if no error)

Error Output CC carry set on error B error code, if any

Additional Information The Get Process Pointer call translates a process ID number to the address of its process descriptor in the system address space. Process descriptors exist only in the system task address space. Because of this, the address space returned only refers to system address space. The support module for this call is KrnP2.

� I/O Delete Deletes an I/O module that is not being used OS9 F$IODel 103F 33

Entry Conditions X address of an I/O module

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The I/O Delete call deletes the specified I/O module from the system, if the module is not in use. This system call is used mainly by the I/O Manager, and can be of limited or no use for other applications. This is the order in which I/O Delete operates: Register X passes the address of a device descriptor module, device driver module, or file manager module. NitrOS9 searches the device table for the address. If NitrOS9 finds the address, it checks the module’s use count. If the count is zero, the module is not being used; NitrOS9 deletes it. If the count is not zero, the module is being used; NitrOS9 returns an error. I/O Delete returns information to the Unlink system call after determining whether a device is busy. � I/O Queue Inserts the calling process into another process’s I/O queue, and puts the calling process to sleep OS9 F$IOQu 103F 2B

Entry Conditions A process ID

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The I/O Queue call links the calling process into the I/O queue of the specified process and performs an untimed sleep. The I/O Manager and the file managers are primary and extensive users of I/O Queue. Routines associated with the specified process send a wake-up signal to the calling process.

� Set IRQ Adds a device to or removes it from the polling table OS9 F$IRQ 103F 2A

Entry Conditions D address of the device status register X 0 (to remove a device) or the address of a packet (to add a device) the address at X is the flip byte the address at X + 1 is the mask byte the address at X + 2 is the priority byte Y address of the device IRQ service routine U address of the service routine’s memory area

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Set IRQ is used mainly by device driver routines. (See “Interrupt Processing” in Chapter 2 for a complete discussion of the interrupt polling system.) Packet Definitions: The Flip Byte. Determines whether the bits in the device status register indicate active when set or active when cleared. If a bit in the flip byte is set, it indicates that the task is active whenever the corresponding bit in the status register is clear (and vice versa). The Mask Byte. Selects one or more bits within the device status register that are interrupt request flag(s). One or more set bits identify which task or device is active. The Priority Byte. Contains the device priority number (0 = lowest priority, 255 = highest priority).

� Load A From Task B Loads A from 0,X in task B OS9 F$LDABX 103F 49

Entry Conditions B task number X pointer to data

Exit Conditions A byte at 0,X in task address space

Error Output CC carry set on error B error code, if any

Additional Information The value in Register X is an offset value from the beginning address of the Task module. The Load A from Task B call returns one byte from this logical address. Use this system call to get one byte from the current process’s memory in a system state routine.

� Get One Byte Loads A from [X,[Y]] OS9 F$LDAXY 103F 46

Entry Conditions X block offset Y DAT image pointer

Exit Conditions A contents of byte at DAT image (Y) offset X

Error Output CC carry set on error B error code, if any

Additional Information The Get One Byte system call gets the contents of one byte in the specified memory block. The block is specified by the DAT image in (Y), offset by (X). The call assumes that the DAT image pointer is to the actual block desired, and that X is only an offset within the DAT block. The value in Register X must be less than the size of the DAT block. NitrOS9 does not check to see if X is out of range.

� Get Two Bytes Load D from [D+X],[Y] OS9 F$LDDDXY 103F 48

Entry Conditions D offset to the offset within the DAT image X offset within the DAT image Y DAT image pointer

Exit Conditions D contents of two bytes at [D+X],[Y]

Error Output CC carry set on error B error code, if any

Additional Information Get Two Bytes loads two bytes from the address space described by the DAT image pointer. If the DAT image pointer is to the entire DAT, make D+X equal to the process address for data. If the DAT image is not the entire image (64K), you must adjust D+X relative to the beginning of the DAT image. Using D+X lets you keep a local pointer within a block, and also lets you point to an offset within the DAT image that points to a specified block number.

� Map Specific Block Maps the specified block(s) into unallocated blocks of process space OS9 F$MapBlk 103F 4F

Entry Conditions X starting block number B number of blocks

Exit Conditions U address of first block

Error Output CC carry set on error B error code, if any

Additional Information The system maps blocks from the top down. It maps new blocks into the highest available addresses in the address space. See Clear Specified Block for information on unmapping.

� Move Data Moves data bytes from one address space to another OS9 F$Move 103F 38

Entry Conditions A source task number B destination task number X source pointer Y byte count U destination pointer

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information You can use the Move Data system call to move data bytes from one address space to another, usually from system to user, or vice versa. The support module for this call is Krn.

� Next Process Executes the next process in the active process queue OS9 F$NProc 103F 2D

Entry Conditions None

Exit Conditions Control does not return to caller.

Additional Information The Next Process system call takes the next process out of the active process queue and initiates its execution. If the queue contains no process, NitrOS9 waits for an interrupt and then checks the queue again. The process calling Next Process must already be in one of the three process queues. If it is not, it becomes unknown to the system even though the process descriptor still exists and can be displayed by the PROCS command.

� Release a Task Releases a specified DAT task number from use by a process, making the task’s DAT hardware available for use by another task OS9 F$RelTsk 103F 43

Entry Conditions B task number

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The support module for this call is Krn.

� Reserve Task Number Reserves a DAT task number OS9 F$ResTsk 103F 42

Entry Conditions None

Exit Conditions B task number (if no error)

Error Output CC carry set on error B error code, if any

Additional Information The Reserve Task Number call finds a free DAT task number, reserves it, and returns the task number to the caller. The caller often then assigns the task number to a process. The support module for this call is Krn.

� Return 64 Deallocates a 64-byte block of memory OS9 F$Ret64 103F 31

Entry Conditions A block number X address of the base page

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information See the Allocate 64 system call for more information.

� Set Process DAT Image Copies all or part of the DAT image into a process descriptor OS9 F$SetImg 103F 3C

Entry Conditions A starting image block number B block count X process descriptor pointer U new image pointer

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information While copying part or all of the DAT image, this system call also sets an image change flag in the process descriptor. This flag guarantees that as a process returns from the system. The call updates the hardware to match the new process DAT image. The support module for this call is Krn.

� Set Process Task DAT Registers Writes to the hardware DAT registers OS9 F$SetTsk 103F 41

Entry Conditions X pointer to process descriptor

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information This system call sets the process task hardware DAT registers, and clears the image change flag in the process descriptor. It also writes to DAT RAM the process’s segment address information. The support module for this call is Krn.

� System Link Adds a module from outside the current address space into the current address space OS9 F$SLink 103F 34

Entry Conditions A module type X module name string pointer Y name string DAT image pointer

Exit Conditions A module type B module revision (if no error) X updated name string pointer Y module entry point U module pointer

Error Output CC carry set on error B error code, if any

Additional Information The I/O system uses the System Link call to link into the current process’s address space those modules specified by a device name in a user call. User calls such as Create File and Open Path use this system call. The support module for this call is Krn.

� Request System Memory Allocates a block of memory of the specified size from the top of available RAM OS9 F$SRqMem 103F 28

Entry Conditions D byte count

Exit Conditions D new memory size U starting address of the memory area

Error Output CC carry set on error B error code, if any

Additional Information The Request System Memory call rounds the size request to the next page boundary. This call allocates memory only for system address space.

� Return System Memory Deallocates a block of contiguous pages OS9 F$SRtMem 103F 29

Entry Conditions D number of bytes to return U starting address of memory to return; must point to an even page boundary

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Register U must point to an event page boundary. This call deallocates memory for system address space only.

� Set SVC Adds or replaces a system call OS9 F$SSvc 103F 32

Entry Conditions Y address of the system call initialization table

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Set SVC adds or replaces a system call, which you have written, to NitrOS9’s user and system mode system call tables. Register Y passes the address of a table, which contains the function codes and offsets, to the corresponding system call handler routines. This table has the following format:

"Relative Address" Use $00 Function Code  First entry "$01 $02" "Offset From Byte 3 To Function Handler" $03 Function Code  Second entry "$04 $05" "Offset From Byte 6 To Function Handler" "

More Entries

" "

 More entries" $80 End-of-table mark

If the most significant bit of the function code is set, NitrOS9 updates the system table. If the most significant bit of the function code is not set, NitrOS9 updates the system and user tables. The function request codes are in the range $29-$34. I/O calls are in the range $80-$90. To use a privileged system call, you must be executing a program that resides in the system map and that executes in the system state. The system call handler routine must process the system call and return from the subroutine with an RTS instruction. The handler routing might alter all CPU registers (except Register SP). Register U passes the address of the register stack to the system call hander as shown in the following diagram:

"Relative Address" Name U  CC $00 R$CC A $01 R$A (R$D) B 02 R$B DP $03 R$DP X $04 R$X Y $06 R$Y U $08 R$U PC $0A R$PC

Codes $70-$7F are reserved for user definition.

� Store A Byte In A Task Stores A at 0,X in Task B OS9 F$STABX 103F 4A

Entry Conditions A byte to store B destination task number X logical destination address

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information This system call is similar to the assembly language instruction “STA 0,X”. The difference is that in the system call, X refers to an address in the given task’s address space instead of the current address space. The support module for this system call is Krn.

� Install Virtual Interrupt Installs a virtual interrupt handler routine OS9 F$VIRQ 103F 27

Entry Conditions D initial count value X 0 to delete entry 1 to install entry Y address of 5-byte packet

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Install VIRQ for use with devices in the Multi-Pak Expansion Interface. This call is explained in detail in Chapter 2.

� Validate Module Checks the module header parity and CRC bytes of a module OS9 F$VModul 103F 2E

Entry Conditions D DAT image pointer X new module block offset

Exit Conditions U address of the module directory entry

Error Output CC carry set on error B error code, if any

Additional Information If the values of the specified module are valid, NitrOS9 searches the module directory for a module with the same name. If one exists, NitrOS9 keeps in memory the module that has the higher revision level. If both modules have the same revision level, NitrOS9 retains the module in memory.

�Get Status System Calls You use the Get Status system calls with the RBF manager subroutine GETSTA. The NitrOS9 Level Two system reserves the function codes 7-127 for use by Microware. You can define codes 128-255 and their parameter-passing conventions for your own use. (See the sections on device drivers in Chapters 4, 5, and 6.)

The Get Status routine passes the register stack and the specified function code to the device driver.

Following are the Get Status functions and their codes.

� SS.OPT Reads the option section of the path descriptor, and passes it into the 32-byte area pointed to by Register X Function Code $00

Entry Conditions A path number B $00 X address to receive status packet

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Use SS.OPT to determine the current settings for editing functions, such as echo and auto line feed.

� SS.RDY Tests for data available on SCF-supported devices Function Code $01

Entry Conditions A path number B $01

Exit Conditions If the device is ready: CC carry clear B $00

On devices that support it (both VTIO and ACIPAK support this), Register B returns the number of characters that are ready to be read.

If the device is ready: CC carry set B $F6 (E$SRNDY)

Error Output CC carry set on error B error code, if any

� SS.SIZ Gets the current file size (RBF-supported devices only) Function Code $02

Entry Conditions A path number B $02

Exit Conditions X most significant 16 bits of the current file size U least significant 16 bytes of the current file size

Error Output CC carry set on error B error code, if any

� SS.POS Gets the current file position (RBF-supported devices only) Function Code $05

Entry Conditions A path number B $05

Exit Conditions X most significant 16 bits of the current file position U least significant 16 bits of the current file position

Error Output CC carry set on error B error code, if any

� SS.EOF Tests for the end of file (EOF) Function Code $06

Entry Conditions A path number B $06

Exit Conditions If there is no EOF: CC carry clear B $00

If there is an EOF: CC carry set B $D3 (E$EOF)

Error Output CC carry set on error B error code, if any

� SS.DevNm Returns a device name Function Code $0E

Entry Conditions A path number B $0E X address of 32-byte buffer for name

Exit Conditions X address of buffer, name moved to buffer

Error Output CC carry set on error B error code, if any

� SS.DSTAT Returns the display status Function Code $12

Entry Conditions A path number B $12

Exit Conditions A color code of the pixel at the cursor address X address of the graphics display memory Y graphics cursor address: X = MSB, Y = LSB

Error Output CC carry set on error B error code, if any

Additional Information This function is supported only with the CoVDG module and deals with VDG-compatible graphics screens. See SS.AAGBf for information regarding Level Two operation.

� SS.JOY Returns the joystick values Function Code $13

Entry Conditions A path number B $13 X joystick number 0 = right joystick 1 = left joystick

Exit Conditions A fire button down 0 = none 1 = Button 1 2 = Button 2 3 = Button 1 and Button 2 X selected joystick x value (0-63) Y selected joystick y value (0-63) Note: Under Level 1, the following values are returned by this call: A fire button status $FF = fire button is on $00 = fire button is off

Error Output CC carry set on error B error code, if any

� SS.AlfaS Returns VDG alpha screen memory information Function Code $1C

Entry Conditions A path number B $1C

Exit Conditions A caps lock status $00 = lower case $FF = upper case X memory address of the buffer Y memory address of the cursor

Error Output CC carry set on error B error code, if any

Additional Information SS.AlfaS maps the screen into the user address space. The call requires a full block of memory for screen mapping. This call is only for use with VDG text screens handled by CoVDG. The support module for this call is CoVDG. Warning: Use extreme care when poking the screen since other system variables reside in screen memory. Do not change any addresses outside of the screen.

� SS.Cursr Returns VDG alpha screen cursor information Function Code $25

Entry Conditions A path number B $25

Exit Conditions A character code of the character at the current cursor address X cursor X position (column) Y cursor Y position (row)

Error Output CC carry set on error B error code, if any

Additional Information SS.Cursr returns the character at the current cursor position. It also returns the X-Y address of the cursor relative to the current device’s window or screen. SS.Cursr works only with text screens. The support module for this call is CoVDG.

� SS.ScSiz Returns the window or screen size Function Code $26

Entry Conditions A path number B $26

Exit Conditions X number of columns on screen/window Y number of rows on screen/window

Error Output CC carry set on error B error code, if any

Additional Information Use this call to determine the size of an output screen. The values returned depend on the device in use: For non-CCIO devices, the call returns the values following the XON/XOFF bytes in the device descriptor. For CCIO devices, the call returns the size of the window or screen in use by the specified device. For window devices, the call returns the size of the current working area of the window. The support modules for this call are CoVDG, CoGrf, and CoWin.

� SS.KySns Returns key down status Function Code $27

Entry Conditions A path number B $27

Exit Conditions A keyboard scan information

Additional Information Accumulator A returns with a bit pattern representing eight keys. With each keyboard scan, NitrOS9 updates this bit pattern. A set bit (1) indicates that a key was pressed since the last scan. A clear bit (0) indicates that a key was not pressed. Definitions for the bits are as follows:

Bit Key 0 SHIFT 1 CTRL or CLEAR 2 ALT or @ 3 Up arrow 4 Down arrow 5 Left arrow 6 Right arrow 7 Space Bar

The bits can be makes with the following equates:

SHIFTBIT equ %00000001 CNTRLBIT equ %00000010 ALTERBIT equ %00000100 UPBIT equ %00001000 DOWNBIT equ %00010000 LEFTBIT equ %00100000 RIGHTBT equ %01000000 SPACEBIT equ %10000000

The support module for this call is VTIO.

� SS.ComSt Returns serial port configuration information Function Code $28

Entry Conditions A path number B $28

Exit Conditions Y high byte: parity low byte: baud (See the SetStat call SS.ComSt for values)

Error Output CC carry set on error B error code, if any

Additional Information The SCF manager uses this call when performing an SS.Opt GetStat on an SCF-type device. Use calls to SS.ComSt do not update the path descriptor. Use the SS.OPT GetStat call for most applications because it automatically updates the path descriptor.

� SS.MnSel Requests that the high-level menu handler take control of menu selection Function Code $87

Entry Conditions A path number B $87

Exit Conditions A Menu ID (if valid selection) 0 (if invalid selection) B item number of menu (if valid selection)

Error Output CC carry set on error B error code, if any

Additional Information After detecting a valid a valid mouse click (when the mouse is pointing to a control area on a window), a process needs to call SS.MnSel. This call tells the enhanced window interface to handle any menu selection being made. If accumulator A returns with 0, no selection has been made. The calling process needs to test and handle other returned values. A condition where Register A returns a valid menu ID number and Register B returns 0 signals the selection of a menu with no items. The application can now take over and do a special graphics pull down of its own. The menu title remains highlighted until the application calls the SS.UMBar SetStat to update the menu bar. The support module for this call is CoWin.

� SS.Mouse Gets mouse status Function Code $89

Entry Conditions A path number B $89 X data storage area address Y mouse port select: 0 = automatic selection 1 = right side 2 = left side

Exit Conditions X data storage area address

Error Output CC carry set on error B error code, if any

�Additional Information SS.Mouse returns information on the current mouse and its fire button. The following list defines the 32-byte data packet that SS.Mouse creates:

Pt.Valid rmb 1 Is returned info valid? (0 = no, 1 = yes) Pt.Actv rmb 1 Active side (0 = off, 1 = right, 2 = left) Pt.ToTm rmb 1 Timeout initial value rmb 2 Reserved Pt.TTTo rmb 1 Time until timeout rmb 2 Reserved Pt.TSSt rmb 2 Time since counter start Pt.CBSA rmb 1 Current button state (Button A) Pt.CBSB rmb 1 Current button state (Button B) Pt.CCtA rmb 1 Click count (Button A) Pt.CCtB rmb 1 Click count (Button B) Pt.TTSA rmb 1 Time this state counter (Button A) Pt.TTSB rmb 1 Time this state counter (Button B) Pt.TLSA rmb 1 Time last state counter (Button A) Pt.TLSB rmb 1 Time last state counter (Button B) rmb 2 Reserved Pt.BDX rmb 2 Button down frozen Actual X Pt.BDY rmb 2 Button down frozen Actual Y Pt.Stat rmb 1 Window pointer type location Pt.Res rmb 1 Resolution (0-640 by 0=10/1=1) Pt.AcX rmb 2 Actual X value Pt.AcY rmb 2 Actual Y value Pt.WRX rmb 2 Window relative X Pt.WRY rmb 2 Window relative Y Pt.Siz equ . Packet size 32 bytes

Button Information:

Pt.Valid. The valid byte gives the caller an indication of whether the information contained in the returned packet is accurate. The information returned by this call is only valid if the process is running on the current interactive window. If the process is on a non-interactive window, the byte is zero and the process can ignore the information returned. Pt.Actv. This byte shows which port is selected for use by all mouse functions. The default value is Right (1). You can change this value with the SS.GIP SetStat call. Pt.ToTm. This is the initial value used by Pt.TTTo. Pt.TTTo. This is the count down value (as of the instant the GetStat call is made). This value starts at the value contained in the Pt.ToTim and counts down to zero at a rate of 60 counts per second. The system maintains all counters until this value reaches 0, at which point it sets all counters and states to 0. The mouse scan routine changes into a quiet mode, which requires less overhead than when the mouse is active. The timeout begins when both buttons are in the up (open) state. The timer is reinitialized to the value in Pt.ToTm when either button goes down (closed). Pt.TSSt. This counter is constantly increasing, beginning when either button is pressed while the mouse is in the quiet state. All counts are a number of ticks (60 per second). The timer counts to $FFFF, then stays at that value if additional ticks occur. Pt.CBSA/Pt.CBSB. These flag bytes indicate the state of the button at the last system clock tick. A value of 0 indicates that the button is up (open). A value other than zero indicates that the button is down (closed). Button A is available on all Tandy joysticks and mice. Button B is only available for products that have two buttons. The system scans the mouse buttons each time it scans the keyboard. Pt.CCtA/Pt.CCtB. This is the number of clicks that have occurred since the mouse went into an active state. A click is defined as pressing (closing) the button, then releasing (opening) the button. The system counts the clicks as the button is released. Pt.TTSA/Pt.TTSB. This counter is the number of ticks that have occurred during the current state, as defined by Pt.CBSx. This counter starts at one (counts the tick when the state changes) and increases by one for each tick that occurs while the button remains in the same state (open or closed). Pt.TSLA/Pt.TLSB. This counter is the number of ticks that have occurred during the time that a button is in a state opposite of the current state. Using this count and the TTSA/TTSB count, you can determine how a button was in the previous state, even if the system returns the packet after the state has changed. Use these counters, along with the state and click count values, to define any type of click, drag, or hold convention you want. Reserved. Two packet bytes are reserved for future expansion of the returned data. Position Information: Pt.BDX/Pt.BDY. These values are copies of the Pt.AcX and Pt.AcY values when either of the buttons change from an open state to a closed state. Pt.Stat. This byte contains information about the area of the screen on which the mouse is positioned. Pt.Valid must be a value other than 0 for this information to be accurate. If Pt.Valid is 0, this value is also 0 and not accurate. Three types of areas are currently defined: 0 = content region or current working area of the window 1 = control region (for use by Multi-View) 2 = off window, or on an area of the screen that is not part of the window. Pt.Res. This value is the current resolution for the mouse. The mouse must always return coordinates in the range of 0-639 for the X axis and 0-191 for the Y axis. If the system is so configured, you can use the high-resolution mouse adapter that provides a 1-to-1 ratio with these values plus 1. If the adapter is not in use, the resolution is a ration of 1-to-10 on the X axis and 1-to-3 on the Y axis. The keyboard mouse provides a resolution of 1-to-1. The values in Pt.Res are: 0 = low res (x:10, y:3) 1 = high res (x,y:1) Pt.AcX/PT.AcY. the values read from the mouse returned in the resolution as described under Pt.Res. Pt.WRX/Pt.WRY. The values read from the mouse minus the starting coordinates of the current window’s working area. These values return the coordinates in numbers relative to the type of screen. For example, the X axis is in the range 0-639 for high-resolution screens and 0-319 for low resolution screens. You can divide the window relative values by 8 to obtain absolute character positions. These values are most helpful when working in non-scaled modes. The support modules for this call are VTIO, CoGrf, and CoWin.

� SS.Palet Gets palette information Function Code $91

Entry Conditions A path number B $91 X pointer to the 16-byte palette information buffer

Exit Conditions X pointer to the 16-byte palette information buffer

Error Output CC carry set on error B error code, if any

Additional Information SS.Palet reads the contents of the 16 screen palette registers, and stores them in a 16-byte buffer. When you make the call, be sure the X register points to the desired buffer location. The pointer is retained on exit. The palette values returned are specific to the screen on which the call is made. The support modules for this call are CoVDG, CoGrf, and CoWin.

� SS.ScTyp Returns the type of a screen to a calling program Function Code $93

Entry Conditions A path number B $93

Exit Conditions A screen type code 1 = 40 x 24 text screen 2 = 80 x 24 text screen 3 = not used 4 = not used 5 = 640 x 192, 2-color graphics screen 6 = 320 x 192, 4-color graphics screen 7 = 640 x 192, 4-color graphics screen 8 = 320 x 192, 16-color graphics screen

Error Output CC carry set on error B error code, if any

Additional Information Support modules for this system call are CoGrf and CoWin.

� SS.FBRgs Returns the foreground, background, and border palette registers for a window Function Code $96

Entry Conditions A path number B $96

Exit Conditions A foreground palette register number B background palette register number (if carry clear) X least significant byte of border palette register number

Error Output CC carry set on error B error code, if any

Additional Information Support modules for SS.FBRgs are CoGrf and CoWin.

� SS.DFPal Returns the default palette register settings Function Code $97

Entry Conditions A path number B $97 X pointer to 16-byte data space

Exit Conditions X default palette data moved to use space

Error Output CC carry set on error B error code, if any

Additional Information You can use SS.DFPal to find the values of the default palette registers that are used when a new screen is allocated by CoGrf or CoWin. The corresponding SetStat can alter the default registers. This GetStat/SetStat pair is for system configuration utilities and should not be used by general applications.

�Set Status System Calls Use the Set Status system calls with the RBF manager subroutine SETSTA. The NitrOS9 Level Two system reserves function codes 7-127 for use by Microware. You can define codes 200-255 and their parameter-passing conventions for your own use. (See the section on device drivers in Chapters 4, 5, and 6.)

Following are the Set Status functions and their codes.

� SS.OPT Writes the option section of the path descriptor Function Code $00

Entry Conditions A path number B $00

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information SS.OPT writes the option section of the path descriptor from the 32-byte status packet pointed to by Register X. Use this system call to set the device operating parameters, such as echo and line feed. � SS.SIZ Changes the size of a file for RBF-type devices Function Code $02

Entry Conditions A path number B $02 X most significant 16 bits of the desired file size U least significant 16 bits of the desired file size

Exit Conditions None

Error Output CC carry set on error B error code, if any � SS.RESET Restores the disk drive head to Track 0 in preparation for formatting and error recovery (use only with RBF-type devices) Function Code $03

Entry Conditions A path number B $03

Exit Conditions None

Error Output CC carry set on error B error code, if any � SS.WTRK Formats (writes) a track on a disk (RBF-type devices only) Function Code $04

Entry Conditions A path number B $04 U track number (least significant 8 bits) X address of the track buffer Y side/density Bit 0 = side 0 = side 0 1 = side 1 Bit 1 = density 0 = single 1 = double

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information For hard disks or floppy disks that have a “format entire diskette” command, SS.WTRK formats the entire disk only when the track number is zero. � SS.SQD Starts the shutdown procedure for a hard disk that has sequence-down requirements prior to removal of power. (Use only with RBF-type devices.) Function Code $0C

Entry Conditions A path number B $0C

Exit Conditions None

Error Output CC carry set on error B error code, if any � SS.KySns Turns the key sense function on and off Function Code $27

Entry Conditions A path number B $27 X key sense switch value 0 = normal key operation 1 = key sense operation

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information When SS.KySns switches the keyboard to key sense mode, the VTIO module suspends transmission of keyboard characters to the SCF manager and the user. While the computer is in key sense mode, the only way to detect key press is with SS.KySns. The support module for this call is VTIO.

� SS.ComSt Used by the SCF manager to configure a serial port Function Code $28

Entry Conditions A path number B $28 Y high byte: parity low byte: baud rate

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Baud Configuration. The high order byte of Y determines the baud rate, the word length, and the number of stop bits. The byte is configured as follows:

Bit 0-3 Baud rate Bit 4 reserved Bit 5-6 Word length Bit 7 Stop bits

Stop bits: 0 = 1 1 = 2

Word length: 00 = 8 bit 01 = 7 bit

Baud rate: 0000 = 110 0001 = 300 0010 = 600 0011 = 1200 0100 = 2400 0101 = 4800 0110 = 9600 0111 = 19,200 1xxx = undefined

Parity Configuration. The low order byte of Y determines parity. The byte is configured as follows:

Bits 0-4 Special use Bits 5-7 Parity

Parity: xx0 = none 001 = odd (ACIAPAK and MODPAK only) 011 = even (ACIAPAK and MODPAK only) 101 = transmit: mark receive: ignore 111 = transmit: space receive: ignore

The SCF manager uses SS.ComSt to inform a driver that serial port configuration information has been changed in the path descriptor. After calling SS.ComSt, a user routine must call the SS.OPT SetStat to correctly update the path descriptor. This call is for the use of the SCF manager. Use SS.OPT for changing baud, stop bit, and parity values.

� SS.Close Informs a device driver that a path is closed Function Code $2A

Entry Conditions A path number B $2A

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information This call is used internally by NitrOS9’s SCF file manager and is not available for user programs. It can be used only by device drivers and file managers.

� SS.AAGBf Reserves an additional graphics buffer Function Code $80

Entry Conditions A path number B $80

Exit Conditions X buffer address Y buffer number (1-2)

Error Output CC carry set on error B error code, if any

Additional Information SS.AAGBf allocates an additional 8K graphics buffer. The first buffer (Buffer 0) must be allocated by using the Display Graphics command. To use the Display Graphics command, send control code $0F to the standard terminal driver. SS.AAGBf can allocate up to two additional buffers (Buffers 1 and 2), one at a time. After calling SS.AAGBf, Register X contains the address of the new buffer. Register Y contains the buffer number. To deallocate all graphics buffers, use the End Graphics control code. When SS.AAGBf allocates a buffer, it also maps the buffer into the application’s address space. Each buffer uses 8K of the available memory in the application’s address space. Also, if SS.DStat is called, Buffer 0 is also mapped into the application’s address space. Allocation of all three buffers reduces the application’s free memory by 24K. The support module for this call is CoVDG.

� SS.SLGBf Selects a graphics buffer Function Code $81

Entry Conditions A path number B $81 X $00 select buffer for use $01-$FF select buffer for use and display Y buffer number (0-2)

Exit Conditions X unchanged from entry Y unchanged from entry

Error Output CC carry set on error B error code, if any

Additional Information Use Display Graphics to allocate the first graphics buffer. Use SS.AAGBf to allocate the second and third graphics buffers. Save each return address when writing directly to a screen. It is not necessary to save return addresses when using operating system graphics commands. SS.SLBGf does not update hardware information until the next vertical retrace (60Hz rate). Programs that use SS.AAGBf to change current draw buffers need to wait long enough to ensure that NitrOS9 has moved the current buffer to the screen. The screen shows the buffer only if the buffer is selected as the interactive device. If the device does not possess the keyboard, NitrOS9 stores the information until the device is selected as the interactive device. When the device is selected as the interactive device, the display shows the selected device’s screen. The support module for this call is CoVDG.

� SS.MpGPB Maps the Get/Put buffer into a user address space Function Code $84

Entry Conditions A path number B $84 X high byte: buffer group number low byte: buffer number Y action to take: 1 = map buffer 0 = unmap buffer

Exit Conditions X address of the mapped buffer Y number of bytes in buffer

Error Output CC carry set on error B error code, if any

Additional Information SS.MpGPB maps a Get/Put buffer into the user address space. You can then save the buffer to disk or directly modify the pixel data contained in the buffer. Use extreme care when modifying the buffer so that you do not write outside of the buffer data area.

� SS.WnSet Set up a high level window handler Function Code $86

Entry Conditions A path number B $86 X window data pointer (if Y=WT.FSWin or WT.Win) Y window type code

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information The C language data structures for windowing are defined in the wind.h file in the DEFS directory of the system disk. The support module for this call is CoWin.

� SS.SBar Puts a scroll block at a specified position Function Code $88

Entry Conditions A path number B $88 X horizontal position of scroll block Y vertical position of scroll block

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information WT.FSWin-type windows have areas at the bottom and right sides to indicate their relative positions within a larger area. These areas are called scroll bars. SS.SBar gives an application the ability to maintain relative position markers within the scroll bars. The markers indicate the location of the current screen within a larger screen. Calling SS.SBar updates both scroll markers. The support module for this call is CoWin.

� SS.MsSig Sends a signal to a process when the mouse button is pressed Function Code $8A

Entry Conditions A path number B $8A X user defined signal code (low byte only)

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information SS.MsSig sends the process a signal the next time a mouse button changes state (from open to closed). Once SS.MsSig sends the signal, the process must repeat the SetStat each time that it needs to set up the signal. Processes using SS.MsSig should have an intercept routine to trap the signal. By intercepting the signal, other processes can be notified when the change occurs. Therefore, the other processes do not need to continually poll the mouse. The SS.Relea SetStat clears the pending signal request, if desired. It also clears any pending signal from SS.SSig. Because of this, if you want to clear only one signal, you must reset the other signal after calling SS.MsSig. The support module for this call is VTIO.

� SS.AScrn Allocates and maps a high-resolution screen into an application address space Function Code $8B

Entry Conditions A path number B $8B X screen type 0 = 640 x 192 x 2 colors (16K) 1 = 320 x 192 x 4 colors (16K) 2 = 160 x 192 x 16 colors (16K) 3 = 640 x 192 x 4 colors (32K) 4 = 320 x 192 x 16 colors (32K)

Exit Conditions X application address space of screen Y screen number (1-3)

Error Output CC carry set on error B error code, if any

Additional Information SS.AScrn is particularly useful in systems with minimal memory when you want to allocate a high resolution graphics screen with all screen updating handled by a process. The call uses CoVDG (CoGrf is not required). All screens are allocated in multiples of 8K blocks. You can allocate a maximum of three buffers at one time. To select between buffers, use the SS.DScrn SetStat call. Screen memory is allocated but not cleared. The application using the screen must do this. Screens must be allocated from a VDG-type device—a standard 32-column text screen must be available for the device. The support module for this call is CoVDG.

� SS.DScrn Causes CoVDG to display a screen that was allocated by SS.AScrn Function Code $8C

Entry Conditions A path number B $8C Y screen number 0 = text screen (32 x 16) 1-3 = high resolution screen number

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information SS.DScrn shows the requested screen if the requested screen is the current interactive device. Screen 0 (text screen) should be selected before using SS.FScrn to free all high resolution screen memory. The support module for this call is CoVDG.

� SS.FScrn Frees the memory of a screen allocated by SS.AScrn Function Code $8D

Entry Conditions A path number B $8D Y screen number (1-3)

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Do not attempt to free a screen that is currently on the display. SS.FScrn returns the screen memory to the system and removes it from an application’s address space. The support module for this call is CoVDG.

� SS.PScrn Converts a screen to a different type Function Code $8E

Entry Conditions A path number B $8E X new screen type 0 = 640 x 192 x 2 colors (16K) 1 = 320 x 192 x 4 colors (16K) 2 = 160 x 192 x 16 colors (16K) 3 = 640 x 192 x 4 colors (32K) 4 = 320 x 192 x 16 colors (32K)

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information SS.PScrn changes a screen allocated by SS.AScrn to a new screen type. You can change a 32K screen to either a 32K screen or a 16K screen. You can change a 16K screen only to another 16K screen type. SS.PScrn updates the current display screen at the next clock interrupt. If you change a 32K screen to a 16K screen, NitrOS9 does not reclaim the extra 16K of memory. This means that you can later change the 16K screen back to a 32K screen. The support module for this call is CoVDG.

� SS.Montr Sets the monitor type Function Code $92

Entry Conditions A path number B $92 X monitor type 0 = color composite 1 = analog RGB 2 = monochrome composite

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information SS.Montr loads the hardware palette registers with the codes for the default color set for three types of monitors. The system default initializes the palette for a composite color monitor. The monochrome mode removes color information from the signals sent to a monitor. When a composite monitor is in use, a conversion table maps colors from RGB color numbers. In RGB and monochrome modes, the system uses the RGB color numbers directly. The support modules for this call are CoVDG and GrfDrv.

� SS.GIP Sets the system wide mouse and key repeat parameters Function Code $94

Entry Conditions A path number B $94 X mouse resolution; in the most significant byte 0 = low resolution mouse 1 = optional high resolution adapter Mouse port location; in the least significant byte 1 = right port 2 = left port Y key repeat start constant; in the most significant byte key repeat delay; in the least significant byte 00XX = no repeat FFFF = unchanged

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information Because this function affects system-wide settings, it is best to use it from system configuration utilities and not from general application programs. The support module for this call is VTIO.

� SS.UMBar Requests the high level menu manager to update the menu bar Function Code $95

Entry Conditions A path number B $95

Exit Conditions None

Error Output CC carry set on error B error code, if any

Additional Information An application can call SS.UMBar when it needs to redraw menu bar information, such as when it enables or disables menus, or when it completes a window pull down and needs to restore the menu. The support module for this call is CoWin.

� SS.DFPal Sets the default palette register values Function Code $97

Entry Conditions A path number B $97 X pointer to 16 bytes of palette data

Exit Conditions X unchanged, bytes moved to system defaults

Error Output CC carry set on error B error code, if any

Additional Information Use SS.DFPal to alter the system-wide palette register defaults. The system uses these defaults when it allocates a new screen using the DWSet command. Because this function affects system wide settings, it is best to use it from system configuration utilities, not general application programs.

� SS.Tone Creates a sound through the terminal output device Function Code $98

Entry Conditions A path number B $98 X duration and amplitude of the tone LSB = duration in ticks (60-sec) in the range 0-255 MSB = amplitude of tone in the range 0-63 Y relative frequency counter (0=low, 4095=high)

Exit Conditions These are the same as the entry conditions.

Error Output There are no error conditions.

Additional Information This call produces a programmed I/O tone through the speaker of the monitor used by the terminal device. You can make the call on any valid path open to term to a window device. The system does not mask interrupts during the time the tone is being produced. The frequency of the tone is a relative number ranging from 0 for a low frequency to 4095 for a high frequency. The widest variation of tones occurs at the high range of the scale.