previous next top contents index framed top this page unframed
Sections 29.2 and 29.3 describe the PROCEDURE qualifiers $BUILTIN and SPECIAL. These qualifiers apply only to system PROCEDUREs (the programmer cannot use them to declare new PROCEDUREs) and are described to help the user understand the system PROCEDURE declarations.
Section 29.5 gives a summary of the system PROCEDUREs, macros, and variables. The remaining sections give the PROCEDURE, macro, and variable descriptions in alphabetic order, except that the load PROCEDUREs (named xLoad, where x is a data type abbreviation) are grouped together under “L” and the get PROCEDUREs (named $xGet, where x is a data type abbreviation) are grouped together under “G”. The complete headers of the PROCEDUREs are specified, providing sufficient information (e.g., about parameters) for a programmer to know how to call the PROCEDUREs.
Macro declarations are shown as if they were PROCEDUREs, except that <macro> is used instead of PROCEDURE. COMPILETIME is shown before the declaration of macros evaluated at compiletime; other macros should be assumed to be evaluated at runtime. XIDAK reserves the right to replace macros with equivalently declared variables or PROCEDUREs and vice versa without notice.
System variables are marked with the comment “# system variable”.
Many of the system PROCEDUREs are GENERIC. In the PROCEDURE descriptions, only the GENERIC names are listed. XIDAK reserves the right to change the instance PROCEDURE names without notice. XIDAK may also change a PROCEDURE that is not a GENERIC into a GENERIC PROCEDURE without notice. In the description of a GENERIC PROCEDURE, the instances of the PROCEDURE are listed in the order in which they appear in the GENERIC declaration.
Type codes are listed in Appendix A.
The USES, PRODUCES, and MODIFIES parameter qualifiers are described in Section 7.5. OPTIONAL is discussed in Section 7.5.5, and REPEATABLE in Section 7.5.6.
Some PROCEDUREs may have OPTIONAL parameters that are not mentioned in the PROCEDURE descriptions. If the user specifies a non-Zero value for such a parameter, the effect is undefined.
When a PROCEDURE description refers to “the (only) valid bits” in a (LONG) BITS parameter b, only the bits specified should ever be set in b. Setting bits not mentioned in the description has undefined consequences.
29.1. System PROCEDUREs and Garbage Collection
Macros and
the PROCEDUREs qualified with $BUILTIN cannot trigger a garbage
collection,
nor can those qualified with COMPILETIME when all their arguments
are constants,
except as noted in the description.
It may be assumed (unless otherwise noted in the description) that any
other system PROCEDUREs and macros
may cause a collection to occur before returning.
If an error or an exception occurs during a call to a PROCEDURE or macro, a garbage collection may occur regardless of whether the PROCEDURE's or macro's description says it cannot trigger a collection. Furthermore, if you use MAINDEBUG to single-step through a system PROCEDURE compiled debuggable, it is possible for a garbage collection to occur within the debugger at each single step.
ss := cvu(s,myArea)
puts the text into myArea if any characters are converted to upper case; if no characters change case, then the text referenced by ss may or may not refer to the same area as the text referenced by s. To ensure that text for a STRING is in a particular area, use $getInArea. In this example, to ensure that the output from cvu is in myArea, use:
ss := $getInArea(cvu(s,myArea),myArea)
29.5. System Procedures, Variables, and Macros Summary
Table 29–1 contains a summary of MAINSAIL system procedures,
variables, and macros.
Table 29–1. System Procedures, Macros, and Variables Summary
| Identifier | Function |
|---|---|
| open | open a file |
| $reOpen | open a file with new open bits |
| close | close a file |
| $closedFile | determine whether a file has been closed |
| $createUniqueFile | create file with unique name |
| $devModBrk | device module name break character |
| $devModBrkStr | string consisting of $devModBrk |
| $delete | delete a file |
| $rename | rename a file |
| $copyFile | copy (part of) one file to another |
| $truncateFile | truncate a file to given length |
| getPos | get file position |
| setPos | set file position |
| relPos | set relative file position |
| $getEofPos | get end-of-file position of byte-stream file |
| $gotValue | TRUE if positioned beyond end-of-file |
| eof | TRUE when positioned at or beyond end-of-file; superseded by $gotValue |
| read | read values |
| write | write values |
| $storageUnitRead | read a number of data efficiently from a file |
| $storageUnitWrite | write a number of data efficiently to a file |
| $characterRead | read a number of characters efficiently from a file |
| $characterWrite | write a number of characters efficiently to a file |
| $pageRead | read a page of data from a file |
| $pageWrite | write a page of data to a file |
| $structureCompare, $structureCopy, $structureDataToText, $structureDispose, $structureInfo, $structureRead, $structureSetUp, $structureTextToData, $structureUnSetUp, $structureWrite | read/write/etc. entire data structures |
| cRead | read a character from file, STRING, or CHARADR |
| cWrite | write characters to file, STRING, or CHARADR |
| $clearFileCache | uncache all or part of file |
| $queryFileCacheParms | information about file cache |
| $setFileCacheParms | control file cache |
| $flush | write all buffers for file |
| $concat | concatenate strings (same as & operator) |
| $dup | perform multiple concatenations |
| rcRead | reverse character read (from the end of a STRING) |
| rcWrite | reverse character write (to the beginning of a STRING) |
| fldRead | read a STRING field |
| fldWrite | write a STRING field |
| ttyRead | read a line from TTY |
| ttyWrite | write values to TTY |
| ttycWrite | write characters to TTY |
| $ttyMod, $ttyCls | MODULE pointer, CLASS for terminal I/O interception |
| $boGet, $iGet, $liGet, $rGet, $lrGet, $bGet, $lbGet, $sGet | prompt to logFile for value of specified type; read from cmdFile |
| $removeBoolean | parse BOOLEAN STRING |
| $removeBits | parse BITS STRING |
| $removeInteger | parse INTEGER STRING |
| $removeReal | parse REAL STRING |
| confirm | get yes/no confirmation from cmdFile |
| cmdMatch | match a command (command recognition) |
| errMsg | raise an exception and/or write a message and get a response |
| cmdFile | standard input file |
| logFile | standard output file |
| enterLogicalName | establish logical file name |
| lookUpLogicalName | find logical file name |
| $setSearchPath | set file searchpath |
| $getSearchPath, $applySearchPath | use these two procedures together to examine a file searchpath |
| $globalLookup, $stringGlobalLookup | look up global symbol |
| $globalEnter, $stringGlobalEnter | enter global symbol |
| $globalRemove | remove global symbol |
| $readParms | process parameter file |
| $findGroup | find parameter group from parameter file |
| $nextParm | traverse parameter group |
| $mslParms | standard parameter group list |
| $registerException | register an exception name so that it can be raised in response to an errMsg prompt |
| $deRegisterException | undo $registerException |
| $newException | assign a unique exception name |
| $raise | raise an exception |
| $raiseReturn | terminate an exception handler |
| $exceptionBits | return information about current exception |
| $exceptionName | return name of current exception |
| $exceptionCoroutine | return raising coroutine of current exception |
| $exceptionPointerArg | return pointer argument of current exception |
| $exceptionStringArg1, $exceptionStringArg2 | return a STRING argument of current exception |
| scanSet | set up scan bit |
| $scanSet | set up scan integer |
| scanRel | release scan bits or integers |
| scan | scan a file or string according to a scan specification |
| $cScan | faster version of scan when scanning for a single character |
| $removeLeadingBlankSpace, $removeTrailingBlankSpace | remove blank space from STRING |
| $removeWord | remove non-blank chars from STRING |
| $removeLastWord | remove trailing non-blank chars |
| $formParagraph | fill and justify STRING |
| generateQuickSort, generateMultipleQuickSort, sort | sort ARRAYs or lists |
| $cvbo | convert to BOOLEAN |
| cvi | convert to INTEGER |
| cvli | convert to LONG INTEGER |
| cvr | convert to REAL |
| cvlr | convert to LONG REAL |
| cvb | convert to BITS |
| cvlb | convert to LONG BITS |
| cvs | convert to STRING |
| cvp | convert to POINTER |
| cva | convert to ADDRESS |
| cvc | convert to CHARADR |
| cvAry | convert to (dynamic) ARRAY |
| cvcs | convert a character code to a single-character STRING |
| cvu | convert to upper case |
| cvl | convert to lower case |
| $length | length of result of cvs |
| first | first character of a STRING |
| last | last character of a STRING |
| $nth | nth character of a STRING |
| length | number of characters in a STRING |
| compare | -1, 0, or 1 as result of (optionally “caseless”) comparison of two STRINGs |
| equ | checks (optionally “caseless”) equality of two STRINGs |
| isLowerCase | TRUE if argument is a lowercase letter (a through z) |
| isUpperCase | TRUE if argument is an uppercase letter (A through Z) |
| isAlpha | TRUE if argument is a letter (A through Z or a through z) |
| $printingChar | TRUE if printing character |
| $isBlankSpaceChar | TRUE if whitespace character |
| nextAlpha | alphabetically next character after argument character |
| prevAlpha | alphabetically previous character before argument character |
| isNul | TRUE if argument is a “null” character |
| $treatLikeNul | TRUE if argument is discarded on input like a “null” character |
| copy | copy a dynamic record, dynamic ARRAY, memory, or characters |
| clear | clear a record, ARRAY, memory, or characters |
| newUpperBound | adjust the upper bound of a one-dimensional dynamic ARRAY |
| $adrOfFirstElement | get the address of the first element of a dynamic ARRAY |
| new | allocate a dynamic object (record, ARRAY, or data section) |
| $newRecords | allocate multiple dynamic records |
| dispose | deallocate a dynamic object (record, ARRAY, data section, or MODULE) |
| $reclaim | low-level deallocation of STRING text |
| bind | bind a MODULE |
| unBind | unbind a MODULE |
| $canFindModule | whether a MODULE can be allocated without error |
| $isBound | whether a MODULE is already bound |
| $invokeModule | invoke a MODULE the way MAINEX does |
| $useProgramInterface | TRUE if bound because an interface PROCEDURE called |
| $programName | name under which MAINSAIL was invoked |
| $getCommandLine | get program arguments |
| $setCommandLine | set program arguments |
| $nextCommandLineArg, $lastCommandLineArg | parse program arguments |
| thisDataSection | return POINTER to current data section |
| $moduleName | return name of MODULE, given data section POINTER |
| $newProcVar | create an unmodeled $PROCVAR |
| $searchCallChain | find caller from particular MODULE |
| $writeCalls | show call stack of coroutine |
| $fieldInfo, $fieldInfoExtended | return information about a dynamic record or data section field |
| $className | return name of CLASS of a POINTER |
| $classInfo, $classInfoExtended | return names and types of dynamic record or data section fields |
| $dscrPtr | CLASS descriptor for POINTER |
| $classDscrFor | CLASS descriptor for a given CLASS |
| $isArray | TRUE if POINTER points to a dynamic ARRAY |
| $createClassDscr, $createClassDscrExtended | create a new CLASS at runtime |
| $createRecord | create a dynamic record given a CLASS descriptor |
| $createParameterizedRecord | create a $parameterizedRecord |
| $isParameterizedRecord | tell whether a POINTER points to a $parameterizedRecord |
| $def | convenience macro for defining sequential-valued constants |
| openLibrary | open a MODULE library file |
| closeLibrary | close a MODULE library file |
| setModName | set a MODULE name association |
| relModName | release a MODULE name association |
| setFileName | set a MODULE file name association |
| relFileName | release a MODULE file name association |
| exit | orderly exit from MAINSAIL |
| fastExit | fast exit from MAINSAIL |
| $exitingMainsail | test whether currently exiting MAINSAIL |
| $setExitCode | set exit code for operating system |
| floor | largest (LONG) INTEGER not exceeding a (LONG) REAL |
| ceiling | smallest (LONG) INTEGER not exceeded by a (LONG) REAL |
| truncate | truncate a (LONG) REAL to a (LONG) INTEGER |
| abs | absolute value of a (LONG) INTEGER or (LONG) REAL |
| bMask | form a BITS mask (sequence of 1-bits) |
| lbMask | form a LONG BITS mask (sequence of 1-bits) |
| $lbOnes | LONG BITS value consisting of all 1-bits) |
| sin | (LONG) REAL sine |
| cos | (LONG) REAL cosine |
| tan | (LONG) REAL tangent |
| $cot | (LONG) REAL cotangent |
| aSin | (LONG) REAL arcsine |
| aCos | (LONG) REAL arccosine |
| aTan | (LONG) REAL arctangent |
| $atan2 | (LONG) REAL two-argument arctangent |
| sinh | (LONG) REAL hyperbolic sine |
| cosh | (LONG) REAL hyperbolic cosine |
| tanh | (LONG) REAL hyperbolic tangent |
| exp | (LONG) REAL exponential |
| ln | (LONG) REAL natural logarithm |
| log | (LONG) REAL base-10 logarithm |
| sqrt | (LONG) REAL square root |
| $log2 | truncated base 2 logarithm of constant |
| $rand, $sRand | pseudorandom number generators |
| $initRand, $initSRand | initialize pseudorandom number generators |
| $hash | compute hash code |
| hshMod | MODULE for maintaing hash tables |
| size, $lSize, $sizeOfValue, $sizeInBits, $lSizeInBits | size of a CLASS, data type, or value |
| $sizeOfField | size of a field |
| $ioSize | size of data type when written to file |
| $bitsPerStorageUnit | bits in a storage unit |
| $bitsPerChar | bits in a character unit |
| $typeName | name of a type, given type code |
| $baseType | base type, given extended type code |
| displace | displace a POINTER, ADDRESS, or CHARADR |
| displacement, lDisplacement | distance from one ADDRESS or CHARADR to another |
| eol | end-of-line STRING |
| eop | end-of-page STRING |
| tab | tab STRING |
| $nulChar | null character |
| $cr | carriage return |
| $lf | linefeed |
| $pageSize | storage units per page |
| $charsPerPage | character units per page |
| $charsPerStorageUnit | character units per storage unit |
| xLoad | load a value (of type x) from an ADDRESS |
| cLoad | load a character from a CHARADR |
| $xLoadSized | load an explicitly sized value (of type x) from an ADDRESS |
| store | store a value into an ADDRESS or CHARADR |
| $storeSized | store an explicitly sized value into an ADDRESS |
| newString | make a STRING from a CHARADR and an INTEGER (length) |
| $getInArea | put a STRING in an area's STRING space |
| $getToTop | put a STRING at top of STRING space |
| newPage | get some pages |
| pageDispose | dispose of pages |
| newScratch | get some scratch space |
| $newScratchChars | get some scratch space measured in chars |
| scratchDispose | dispose of scratch space |
| $date | get the date |
| $time | get the time |
| $dateAndTime | get the date and time simultaneously |
| $setTheDate | set the date, if necessary |
| $assembleDate | convert year-month-date combination into standard representation |
| $assembleTime | convert hour-minute-second combination into standard representation |
| $assembleDateAndTime | combined $assembleDate and $assembleTime |
| $disassembleDate | convert standard representation into year-month-date combination |
| $disassembleTime | convert standard representation into hour-minute-second combination |
| $disassembleDateAndTime | $disassembleDate and $disassembleTime |
| $dateToStr | convert date representation to STRING |
| $timeToStr | convert time representation to STRING |
| $dateAndTimeToStr | combined $dateToStr and $timeToStr |
| $strToDate | convert STRING to date representation |
| $strToTime | convert STRING to time representation |
| $strToDateAndTime | combined $strToDate and $strToTime |
| $removeDateAndTime | parse date and time STRING |
| $addToDateAndTime | add two dates and times |
| $dateAndTimeDifference | subtract two dates and times |
| $dateAndTimeCompare | compare two dates and times |
| $dateFormat | whether date is GMT, local, or difference |
| $timeFormat | whether time is GMT, local, or difference |
| $convertDateAndTime | convert GMT time to local or vice versa |
| $addDefinedTimeZone | add time zone to those MAINSAIL knows |
| $getDefinedTimeZones | get list of time zones MAINSAIL knows |
| $getDstStartRule, $getDstEndRule, $setDstStartRule, $setDstEndRule | get/set rule for start or end of Daylight Savings Time |
| $getDstName | get local Daylight Savings Time zone name |
| $setDstName | set local Daylight Savings Time zone name |
| $getDSTOffset, $getGMTOffset, $setDSTOffset, $setGMTOffset | get/set Daylight Savings Time, Greenwich Mean Time difference from local Standard Time |
| $timeSubcommandsSet | whether GMT conversion info available |
| $cpuTime | get system-dependent CPU time for current program |
| $cpuTimeResolution | number of $cpuTime units per second |
| $timeout | pause for specified period |
| $userID | return the system-dependent user ID, if available |
| $cpuID | return the system-dependent CPU ID, if available |
| $currentDirectory | name of system-dependent current working or connected file directory or catalog |
| $homeDirectory | home directory or catalog of current user |
| $directory | list files in a directory |
| $fileInfo | return information about a file |
| $setCurrentDirectory | change the current directory |
| $createDirectory | create a directory |
| $deleteDirectory | delete a directory |
| $renameDirectory | rename a directory |
| $copyDirectory | copy a directory |
| $composePath | compose a directory name from its path name components |
| $decomposePath | reduce a directory name to its path name components |
| $composeFileName | compose a file name from its path name components |
| $decomposeFileName | reduce a file name to its path name components |
| $targetSystemBaseFileNameSuffix | get system-dependent part of MAINSAIL object file name |
| $moduleInfo, $intmodInfo | information about objmod or intmod |
| $compareIntmods, $compareObjmods | compare two intmods or two objmods |
| $collect | perform a garbage collection |
| $memoryManagementInfo | advise garbage collector |
| $checkConsistency | verify that MAINSAIL data structures are in order |
| $addMemMngModule | specify module to invoke before memory management operations |
| $removeMemMngModule | undo $addMemMngModule |
| $collectLock | used to prevent/permit garbage collections |
| $overheadPercentExitValue | used to prevent thrashing |
| $areaOf | determine area of POINTER or STRING |
| $clearArea | empty an area |
| $clearStrSpc | empty an area's STRING space |
| $defaultArea | default area |
| $disposeArea | reclaim an area |
| $disposeDataSecsInArea | dispose only data sections in area |
| $findArea | find area with given title |
| $inArea | determine if POINTER or STRING in given area |
| $newArea | allocate area |
| $changeAreaParms | change area characteristics |
| $mergeArea | merge two areas |
| $createCoroutine | create a coroutine |
| $resumeCoroutine | continue or start execution in a coroutine |
| $killCoroutine | get rid of a coroutine |
| $killedCoroutine | determine whether a coroutine has been killed |
| $moveCoroutine | move coroutine to another point in tree |
| $findCoroutine | return a POINTER to a coroutine record, given its name |
| $thisCoroutine | current coroutine |
| $okToMixCoroutinesAndForeignCalls | determine compatibility of coroutines with Foreign Language Interface |
| $majorVersion, $minorVersion | get MAINSAIL version number |
| $maxChar | maximum character code |
| $maxInteger | maximum INTEGER |
| $maxLongInteger | maximum LONG INTEGER |
| $minInteger | minimum INTEGER |
| $minLongInteger | minimum LONG INTEGER |
| $minReal, $maxReal | minimum, maximum REAL |
| $minLongReal, $maxLongReal | minimum, maximum LONG REAL |
| $maxStringLength | maximum allowable length of STRING |
| $nextReal, $nextLongReal | next representable REAL, LONG REAL |
| $prevReal, $prevLongReal | previous representable REAL, LONG REAL |
| $platformNameAbbreviation, $platformNameFull, $platformNumber | identify target platform |
| $systemNameAbbreviation, $systemNameFull, $systemNumber | identify target operating system |
| $processorNameAbbreviation, $processorNameFull, $processorNumber | identify target processor |
| $attributes | attributes of target system |
| $charSet | character set of target operating system |
| $preferredRadix | “natural” radix for addresses, etc. |
| $compileTimeValue | information about current compilation |
| $thisFileName | file name currently being compiled |
| $clrConfigurationBit | clear bit governing runtime system |
| $clrSystemBit | clear bit governing runtime system |
| $setConfigurationBit | set bit governing runtime system |
| $setSystemBit | set bit governing runtime system |
| $tstConfigurationBit | examine bit governing runtime system |
| $tstSystemBit | examine bit governing runtime system |
| $startRigging, $stopRigging | control “rigging” to track dangling POINTER and STRING bugs |
| $riggedAdrBits, $riggedCharadrBits | bit patterns for rigging |
| $setDelayPtrRigging, $clearDelayPtrRigging | control delayed POINTER rigging on SUPERCHECK platforms |
| $compile | invoke COMPIL to compile a MAINSAIL module |
| $executeIntlibCommands | invoke INTLIB |
| $executeMainpmCommands | invoke MAINPM |
| $startMonitoring, $stopMonitoring, $statisticsInfo | control MAINPM monitoring |
| $executeModlibCommands | invoke MODLIB |
| $executeStampCommands | invoke STAMP |
| $mainsailExec | invoke MAINEX executive |
| $getSubcommands | invoke MAINEX subcommand mode |
| $msStrInPlace, $msStr, $cvFieldToStringInPlace, $cvFieldToString | make C string into MAINSAIL string |
| $nulcStr | empty C string |
| $cStr | make MAINSAIL string into C string |
| $copyStringToField | copy MAINSAIL string to C field |