[1,1]SYSLIB.OLB and [1,1]VMLIB.OLB contains a large number of 'System Library Routines' for use from MACRO-11 programs. These fall into a number of separate categories as listed below. HELP SYSLIB will list all the routines in a given category, and HELP SYSLIB will give details on a specific routine. The categories are:- ARITHMETIC DYNAMIC-MEMORY-MANAGEMENT FORMATTING INPUT-DATA-CONVERSION OUTPUT-DATA-CONVERSION REGISTER-HANDLING VIRTUAL-MEMORY-MANAGEMENT 2 ARITHMETIC Possible Arithmetic Routines are:- $DDIV Double-Precision Divide $DIV Integer Divide $DMUL Double-Precision Multiply $MUL Integer Multiply 2 DYNAMIC-MEMORY-MANAGEMENT Possible Dynamic Memory Management Routines are:- $INIDM Initialize Dynamic Memory $RLCB Release Core Block $RQCB Request Core Block 2 FORMATTING Possible Output Formatting Routines are:- $CVTUC Convert lower-case characters to upper-case $DAT Convert a date $EDMSG Generalised Edit Message routine $TIM Convert a time 2 INPUT-DATA-CONVERSION Possible Input Data Conversion Routines are:- $CAT5 Convert ASCII to RAD50 $CAT5B Convert ASCII with blanks to RAD50 $CDTB Convert Decimal to Binary $COTB Convert Octal to Binary .DD2CT Convert Decimal to Binary Double Word .OD2CT Convert Octal to Binary Double Word 2 OUTPUT-DATA-CONVERSION Possible Output Data Conversion Routines are:- $C5TA Convert RAD50 to ASCII $CBDAT Convert a Binary Date $CBDMG Convert Binary to Decimal Magnitude $CBDSG Convert Binary to Signed Decimal $CBOMG Convert Binary to Octal Magnitude $CBOSG Convert Binary to Signed Octal $CBTA General Purpose Binary to ASCII conversion $CBTMG Convert Binary Byte to Octal Magnitude $CDDMG Convert Double-Precision Binary to Decimal 2 REGISTER-HANDLING Possible Register Handling Routines are:- $SAVAL Save/Restore Registers R0-R5 .SAVR1 Save/Restore Registers R1-R5 $SAVRG Save/Restore Registers R3-R5 $SAVVR Save/Restore Registers R0-R2 2 VIRTUAL-MEMORY-MANAGEMENT Possible Virtual Memory Management Routines are:- $ALBLK Allocate Core Block $ALSVB Allocate Small Virtual Block $ALVRT Allocate Virtual Memory $CVLOK Convert and Lock Page $CVRL Convert Virtual to Real Address $EXTSK Extend Task $FNDPG Find Page $GTCOR Get Core $INIVM Initialize Virtual Memory $LCKPG Lock Page $RDPAG Read Page $UNLPG Unlock Page $WRMPG Write-mark Page $WRPAG Write Page Note that these routines are in [1,1]VMLIB.OLB. 2 $ALBLK $ALBLK Allocate Core Block Determine whether a block of memory storage can be allocated from the free dynamic memory, and if so clear it and return the address to the calling program. Inputs: R1 = size (max 512) in bytes of block required Outputs: R0 = dynamic memory address of allocated cleared block Other Effects: If unsuccessful the user's error routine $ERMSG is called with: R1 = E$R4, S$V2 R2 = address of free memory header ($FRHD) 2 $ALSVB $ALSVB Allocate Small Virtual Block Allocate a small virtual page block within large page blocks of memory and disk storage. Inputs: R1 = size of block to allocate in bytes (max 512) or 0 on first call to initialize the routine The user program must also contain a word location named N$DLGH which defines the size of a large page block in bytes. Outputs: R0 = dynamic memory address of the allocated page block R1 = the virtual address of the allocated block Other Effects: R2 is destroyed If the allocation fails the user error routine $ERMSG is called with: R1 = E$R76,S$V2 2 $ALVRT $ALVRT Allocate Virtual Memory Determine whether a page block of virtual storage can be allocated on the user's disk work file. If so allocate an equal amount of memory storage, update page control and address tables, and return disk and memory addresses to user. Inputs: R1 = Size in bytes (max 512) of disk storage block to allocate Outputs: R0 = Memory address of allocated page block R1 = Disk address of allocated page block Other Effects: R2 is destroyed If the allocation fails the user error routine $ERMSG is called with: R1 = E$R76,S$V2 2 $C5TA $C5TA Convert RAD50 to ASCII Convert a RAD50 word into an ASCII string. Inputs: R0 = Address at which to store converted data R1 = RAD50 value to convert Outputs: R0 = Address of next byte after last character stored Other Effects: The converted data is stored in the specified output area 2 $CAT5 $CAT5 Convert ASCII to RAD50 Convert a three-character ASCII string, not including blank characters, to a 16-bit RAD50 value. Inputs: R0 = Address of first character to be converted R1 = Period disposition flag (0 if period is terminator, 1 if period is legal RAD50 character) Outputs: R0 = Address of next character in the input buffer R1 = Converted RAD50 value R2 = Terminating character (last character in string converted, or invalid character that caused premature termination) C-bit = clear if conversion was complete, set otherwise Other Effects: None 2 $CAT5B $CAT5B Convert ASCII with blanks to RAD50 $CAT5 Convert ASCII to RAD50 Convert a three-character ASCII string, including blank characters, to a 16-bit RAD50 value. Inputs: R0 = Address of first character to be converted R1 = Period disposition flag (0 if period is terminator, 1 if period is legal RAD50 character) Outputs: R0 = Address of next character in the input buffer R1 = Converted RAD50 value R2 = Terminating character (last character in string converted, or invalid character that caused premature termination) C-bit = clear if conversion was complete, set otherwise Other Effects: None 2 $CBDAT $CBDAT Convert a Binary Date Convert an internally stored binary date to a 2-digit decimal number. Inputs: R0 = Starting address of output area in which to store the date R1 = Binary date to convert (1-31) R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted date is stored in the user area 2 $CBDMG $CBDMG Convert Binary to Decimal Magnitude Convert an internally stored binary number to a 5-digit unsigned ASCII decimal magnitude number. Inputs: R0 = Starting address of output area in which to store the number R1 = Number to be converted R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CBDSG $CBDSG Convert Binary to Signed Decimal Convert an internally stored binary number to a 5-digit signed ASCII decimal number. Inputs: R0 = Starting address of output area in which to store the number R1 = Number to be converted R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CBOMG $CBOMG Convert Binary to Octal Magnitude Convert an internally stored binary number to a 6-digit unsigned ASCII octal magnitude number. Inputs: R0 = Starting address of output area in which to store the number R1 = Number to be converted R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CBOSG $CBOSG Convert Binary to Signed Octal Convert an internally stored binary number to a 6-digit signed ASCII octal number. Inputs: R0 = Starting address of output area in which to store the number R1 = Number to be converted R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CBTA $CBTA General Purpose Binary to ASCII conversion Convert internally stored binary numbers to an ASCII format that depends on user-defined parameters. Inputs: R0 = Starting address of output area in which to store the number R1 = Binary value to be converted R2 = Conversion parameters as follows:- Bits 0-7 : Conversion Radix (2 - 10.) Bit 8 : Sign flag. 0 for unsigned values, 1 for signed Bit 9 : Zero Suppression Flag. 0 to suppress zeroes, 1 to allow leading zeroes Bit 10 : Blank Fill Flag. 1 to specify replacement of leading zeroes with blanks if Bit 9 = 1. 0 to specify no replacement of leading zeroes. Bits 11-15: Field Width in bytes (1 - 32.) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CBTMG Convert an internally stored binary byte to a 3-digit unsigned ASCII octal magnitude number. Inputs: R0 = Starting address of output area in which to store the number R1 = Number to be converted (in low order byte) R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) Outputs: R0 = Next available address in output area R1 = Low order byte unchanged, high order byte zero Other Effects: R2 are destroyed The converted number is stored in the user area $CBTMG Convert Binary Byte to Octal Magnitude 2 $CDDMG $CDDMG Convert Double-Precision Binary to Decimal Convert an double-precision binary number to a 9-digit unsigned ASCII decimal magnitude number. (If the number contains more than 9 digits the routine inserts five ASCII asterisk symbols in the output area.) Inputs: R0 = Starting address of output area in which to store the number R1 = Address of two-word input area containing the double-precision number R2 = Zero suppression indicator (0 = suppress leading zeroes, 1 = do not suppress leading zeroes) (Note that if the five most significant digits are zeroes, they will be automatically suppressed regardless of the suppression indicator setting.) Outputs: R0 = Next available address in output area Other Effects: R1 and R2 are destroyed The converted number is stored in the user area 2 $CDTB $CDTB Convert Decimal to Binary Convert an unsigned decimal ASCII number to binary. The number may consist only of the characters 0-9, terminated by any other character. The maximum value that can be converted is 65535 - larger numbers will cause indeterminate results. Inputs: R0 = Address of ASCII string to be converted Outputs: R0 = Address of next byte (after terminator) in input buffer R1 = Converted number R2 = Terminating character Other Effects: None 2 $COTB $COTB Convert Octal to Binary Convert an unsigned octal ASCII number to binary. The number may consist only of the characters 0-7, terminated by any other character. The maximum value that can be converted is 177777 - larger numbers will cause indeterminate results. Inputs: R0 = Address of ASCII string to be converted Outputs: R0 = Address of next byte (after terminator) in input buffer R1 = Converted number R2 = Terminating character Other Effects: None 2 $CVLOK $CVLOK Convert and Lock Page Convert a virtual address to a memory address and lock the page in memory. Inputs: R1 = Virtual address to be converted Outputs: R0 = Converted memory address R1 = Virtual address C-bit = Clear if address was converted and page locked, set otherwise Other Effects: If there was insufficient memory for the page, the user's routine $ERMSG is invoked with: R1 = E$R4,S$V2 R2 = Address of free memory header ($FRHD) 2 $CVRL $CVRL Convert Virtual to Real Address Convert a virtual address to a dynamic memory address. Inputs: R1 = Virtual address to be converted Outputs: R0 = Converted memory address R1 = Virtual address Other Effects: If there was insufficient memory for the page, the user's routine $ERMSG is invoked with: R1 = E$R4,S$V2 R2 = Address of free memory header ($FRHD) 2 $CVTUC $CVTUC Convert lower-case characters to upper-case Convert lower case ASCII text to upper case. Inputs: R0 = Address of text string to be converted R1 = Address of output area for upper case string (may be the same as R0) R2 = Number of bytes to be converted Outputs: R0 = Address of next byte in input string R1 = Address of next byte in output string Other Effects: R2 is destroyed 2 $DAT $DAT Convert a date Convert the three-word internal binary date to the standard 8/9 character ASCII date in the format dd-mmm-yy. Inputs: R0 = Address of output area into which the converted date is to be stored R1 = Address of three-word input area containing:- word 1 = last two digits of year word 2 = month of year (1 - 12) word 3 = day of month (1 - 31) Outputs: R0 = Next available byte in the output buffer R1 = Next address in the input buffer Other Effects: R2 is destroyed 2 .DD2CT #DD2CT 2 $DD2CT .DD2CT Convert Decimal to Binary Double Word Convert a signed ASCII decimal number to a two-word signed integer. The routine accepts leading + or - signs and a trailing decimal point. A preceding # sign is allowed but will force octal conversion. A # symbol and a period in the same string is invalid. Acceptable characters in the string are the numbers 0 - 9, and will be prematurely terminated by any other character. The value range that can be converted is -2**31 to +2**31 - 1. Inputs: R3 = Address of two-word field in which to store the number (high order first) R4 = Number of characters in the string to be converted R5 = Address of character string to be converted Outputs: C-bit = Clear if conversion was successful, set otherwise Other Effects: The converted number is stored in the user data area 2 $DDIV $DDIV Double-Precision Divide Divide an unsigned double-precision integer dividend by an unsigned single-precision divisor to produce an unsigned double-precision result. Inputs: R0 = The unsigned divisor R1 = High-order part of unsigned dividend R2 = Low-order part of unsigned dividend Outputs: R0 = Remainder R1 = High-order part of quotient R2 = Low-order part of quotient Other Effects: None 2 $DIV $DIV Integer Divide Divide an unsigned integer dividend by an unsigned integer divisor to produce an unsigned integer result. Inputs: R0 = The dividend R1 = The divisor Outputs: R0 = The quotient R1 = The remainder Other Effects: None 2 $DMUL $DMUL Double-Precision Multiply Multiply an unsigned double-precision integer value by an unsigned single-precision value to produce an unsigned double-precision product. Inputs: R0 = The single-precision multiplier R2 = High-order part of unsigned double-precision multiplicand R3 = Low-order part of unsigned double-precision multiplicand Outputs: R0 = High-order part of product R1 = Low-order part of product Other Effects: R2 & R3 are destroyed 2 $EDMSG $EDMSG Generalised Edit Message routine Edit internally formatted data, in an argument block, to external format and store it in the calling tasks output block. Inputs: R0 = Starting address of output area R1 = Address of input string containing editing directives and/or ASCII strings, delimited by a null R2 = Starting address of argument block Outputs: R0 = Address of next available byte in the output buffer R1 = Number of bytes transferred to the output buffer R2 = Address of next argument in the argument block Other Effects: The converted string is stored in the user area. For a brief guide to the editing directives type HELP SYSLIB $EDMSG DIRECTIVES, but note that this contains several screensful of information. 3 DIRECTIVES Editing directives must be of the form: %l, %nl or %Vl where: % = delimiter to indicate editing directive n = optional repeat count (decimal) specifying how many times the operation is to be repeated. (If n is zero or is omitted, 1 is assumed.) V = indication that the repeat count is a value in the next word in the argument block l = alphabetic letter specifying the editing operation required. In the following list ARGBLK represents the user's argument block, and all converted strings are assumed stored in the user's output area. Note that some of the directives (A,B,E,I,T) require ARGBLK to contan an address that points to the data to be converted. A,nA,VA = Move ASCII text unchanged from address in ARGBLK B,nB,VB = Convert binary byte(s) from address in ARGBLK to octal D,nD,VD = Convert binary value(s) in ARGBLK to signed decimal E,nE,VE = Move extended ASCII text from address in ARGBLK, changing any non-printing characters to spaces F,nF,VF = Insert form feed character(s) I = Insert ASCIZ string from address in ARGBLK M,nM,VM = Convert binary value(s) in ARGBLK to decimal magnitude with leading zeroes suppressed N,nN,VN = Insert CRLF pair(s) O,nO,VO = Convert binary value(s) in ARGBLK to signed octal P,nP,VP = Convert binary value(s) in ARGBLK to unsigned octal R,nR,VR = Convert RAD50 value(s) in ARGBLK to ASCII S,nS,VS = Insert space(s) T,nT,VT = Convert unsigned double-precision binary value(s) from address in ARGBLK to decimal U,nU,VU = Convert binary value(s) in ARGBLK to decimal magnitude with no leading zeroes suppressed X,nX,VX = Convert RAD50 filename string(s) in ARGBLK to ASCII followed by converting binary version number (if non-zero) in ARGBLK to unsigned octal. Each filename string is five words long - Words 1-3 = Filename, Word 4 = File type, Word 5 = Version Y = Convert next three binary words in ARGBLK to ASCII date in form dd-mmm-yy. The words must contain the year since 1900, month number and day number in that order. 0Z,1Z = Convert binary hour-of-day in next word of ARGBLK to ASCII in form HH 2Z = Convert binary hour-of-day and minute-of-hour in the next two words of ARGBLK to ASCII in the form HH:MM 3Z = Convert binary hour-of-day, minute-of-hour and second-of-minute in the next three words of ARGBLK and store in the form HH:MM:SS 4Z,5Z = Convert binary hour-of-day, minute-of-hour, second-of-minute, tick-of-second and ticks-per-second in the next five words of ARGBLK and store in the form HH:MM:SS.S n< = Insert n spaces followed by a field mark (NUL) character, and reset the pointer to point to the first space n> = Increment the pointer until a field mark is reached, or the n repeat count is exceeded 2 $EXTSK $EXTSK Extend Task Extend the current region of the task to increase the amount of available memory for allocation. The task region is extended by the specified size rounded to the next 32-word boundary. Inputs: R1 = Size in bytes (max 512) of memory storage block to be alocated Outputs: R1 = Actual extension size in bytes C-bit = Clear if extension was succesful, set otherwise Other Effects: None 2 $FNDPG $FNDPG Find Page Search an internal page address list to determine whether a virtual page has already been transferred into an allocated memory page block. Inputs: R1 = Virtual Page Address Outputs: R0 = Memory page block address at which page is resident R1 = Virtual page address C-bit = Clear if page is resident, set otherwise Other Effects: None 2 $GTCOR $GTCOR Get Core Try to allocate dynamic memory either from existing available memory, by extending the task to obtain more available memory or by swapping out unlocked pages. Inputs: R1 = Size in bytes (max 512) of dynamic memory block to allocate Outputs: R0 = Memory address of block if allocated C-bit = Clear if allocation is successful, set otherwise Other Effects: None 2 $INIDM $INIDM Initialize Dynamic Memory Establish the initial state of free dynamic memory available to the task - this consists of all memory from the end of the task code to the highest virtual address used by the task. Inputs: R0 = Address of free memory listhead Outputs: R0 = First address in the task R1 = First address following the task image R2 = Size of free dynamic memory Other Effects: None 2 $INIVM $INIVM Initialize Virtual Memory Initialize the task's free dynamic memory, set up the page address control list, and initialize the user's disk work file to enable memory-to-disk page swapping. Disk wirk file capacity is 64K words. Inputs: A two-word field labelled $FRHD (global) must exist in the task and the first word should be set to the starting address of the free dynamic memory A global symbol W$KLUN must be defined in the task, defining the LUN to be used for the work file. (This must already have been assigned to the relevant disk.) A global symbol W$KEXT must be defined in the task, defining the work file extension size (in blocks). A negative number implies contiguous allocation. A global symbol N$MPAG must be defined in the task, defining the number of pages to be kept memory-resident (if there is enough room). R1 = Highest address of task's free dynamic memory Outputs: R0 = Success indicator (0 = Success, -2 = Work File open failure, -1 = work file mark-for-deletion failure) C-bit = Clear if initialization successful, set otherwise Other Effects: R1 & R2 are destroyed 2 $LCKPG $LCKPG Lock Page Set a lock byte in a memory-resident page to prevent its being swapped out of memory. Inputs: R1 = Virtual address in page to be locked Outputs: C-bit = Cleared if page was found and locked, set otherwise Other Effects: None 2 $MUL $MUL Integer Multiply Multiply two unsigned integers to produce an unsigned double-precision result. Inputs: R0 = The multiplier R1 = The multiplicand Outputs: R0 = High-order part of product R1 = Low-order part of product Other Effects: None 2 .OD2CT #OD2CT 2 $OD2CT .OD2CT Convert Octal to Binary Double Word Convert a signed ASCII octal number to a two-word signed integer. The routine accepts leading + or - signs and a preceding # symbol. A trailing decimal point is allowed but will force decimal conversion. A # symbol and a period in the same string is invalid. Acceptable characters in the string are the numbers 0 - 7, and will be prematurely terminated by any other character. The value range that can be converted is -2**31 to +2**31 - 1. Inputs: R3 = Address of two-word field in which to store the number (high order first) R4 = Number of characters in the string to be converted R5 = Address of character string to be converted Outputs: C-bit = Clear if conversion was successful, set otherwise Other Effects: The converted number is stored in the user data area 2 $RDPAG $RDPAG Read Page Effect the transfer of a dsik page from the work file to the dynamic memory. Inputs: R0 = Disk address of page to be transferred Outputs: C-bit = Clear to indicate transfer successful Other Effects: If the transfer fails the user's routine $ERMSG is invoked with: R1 = E$R73, S$V2 2 $RLCB $RLCB Release Core Block Release a block of previously allocated dynamic memory to the free memory list. Inputs: R0 = Address of free memory listhead R1 = Size in bytes of block to be released R2 = Memory address of block to be released Outputs: R0 = Address of free memory listhead Other Effects: R1 & R2 are destroyed The free memory list is updated 2 $RQCB $RQCB Request Core Block Determine whether there is enough space available in the free dynamic memory to satisfy an executing task's memory allocation request and if so allocate the block. Inputs: R0 = Address of free memory listhead R1 = Size in bytes of block to be allocated (if positive then best fit allocation is performed, if negative then firs fit) Outputs: R0 = Dynamic memory address of allocated block R1 = Actual size of allocated block (requested size rounded up to 2-word boundary) C-bit = Clear if allocaion successful, set otherwise Other Effects: R2 is destroyed 2 $SAVAL $SAVAL Save/Restore Registers R0-R5 Save, and subsequently restore, Registers 0-5. Inputs: None Outputs: None Other Effects: The Registers 0-5 are stored on the user's stack, and later restored (this is a coroutine). 2 .SAVR1 #SAVR1 2 $SAVR1 .SAVR1 Save/Restore Registers R1-R5 Save, and subsequently restore, Registers 1-5. Note that this routine Must be invoked by: JSR R5,.SAVR1 Inputs: None Outputs: None Other Effects: The Registers 1-5 are stored on the user's stack, and later restored (this is a coroutine). 2 $SAVRG $SAVRG Save/Restore Registers R3-R5 Save, and subsequently restore, Registers 3-5. Note that this routine Must be invoked by: JSR R5,$SAVRG Inputs: None Outputs: None Other Effects: The Registers 3-5 are stored on the user's stack, and later restored (this is a coroutine). 2 $SAVVR $SAVVR Save/Restore Registers R0-R2 Save, and subsequently restore, Registers 0-2. Note that this routine Must be invoked by: JSR R2,$SAVVR Inputs: None Outputs: None Other Effects: The Registers 0-2 are stored on the user's stack, and later restored (this is a coroutine). 2 $TIM $TIM Convert a time Convert the binary time, in the standard 5-word binary format, to an ASCII output string of the form HH:MM:SS.S Inputs: R0 = Address of output area in which the converted time is to be stored R1 = Address of input area holding time in binary R2 = Parameter count, where: R2 = 0 or 1 => Convert the hour only to HH R2 = 2 => Convert hours & minutes to HH:MM R2 = 3 => Convert hours, minutes & seconds to HH:MM:SS R2 = 4 or 5 => Convert whole block to HH:MM:SS.S Outputs: R0 = Address of next available byte in output area R1 = Address of next word in input area Other Effects: R2 is destroyed The converted date is stored in the user data area 2 $UNLPG Clear a lock byte in a memory-resident page to allow it to be swapped out of memory. Inputs: R1 = Virtual address in page to be unlocked Outputs: C-bit = Cleared if page was found and unlocked, set otherwise Other Effects: None $UNLPG Unlock Page 2 $WRMPG $WRMPG Write-mark Page Set the 'written-into' flag of the specified page in dynamic memory. Inputs: R1 = Virtual address of the page Outputs: C-bit = clear if the operation was successful, set otherwise Other Effects: The 'written-into'flag of the specified page is set. 2 $WRPAG $WRPAG Write Page Transfer a memory page to the disk work file. Inputs: R2 = Dynamic memory address of page to be written Outputs: C-bit = Clear if operation successful Other Effects: If the operation failed the user's routine $ERMSG is invoked with: R1 = E$R73, S$V2