1 FERMILIB
  The object library FERMILIB.OLB appears in both SYS$LIBRARY: and
  FERMI$LIB and contains various locally written (and DECUS) routines.
  This object library is used like any library by including the
  following in the LINK command (or options input):

	...,FERMI$LIB:FERMILIB/LIBRARY...

  Sources for the modules in FERMILIB may be found on the system disk
  in the directory FERMI$ROOT:[LIBRARY.SOURCES.ROUTINES].

  In addition, the macro library FERMILIB.MLB in the same areas contains
  several generally useful macros.  The commented sources for these
  macros may be found in FERMI$ROOT:[LIBRARY.MACROS].

2 LIB_

      LIB_ procedures

3 ARGPTR
 Return a pointer to the argument list in the call to the outer
 (caller) procedure.

 address.wl.v = LIB_ARGPTR( [number.rl.v] )

  address  longword return the virtual memory address of the part
           of the argument list as specified by the argument to
           this procedure.

  number   longword determining which argument's address is to be
           returned.  If not specified or defaulted (value of 0),
           the address of the argument count (start of the argument
           list) is returned.  Otherwise this is the number of the
           argument whose address is returned (as a pointer to a
           portion of the argument list).  Passed by value.

 If the number parameter exceeds the count of the arguments in the
 argument list being referenced, then 0 is returned as the pointer.
 The argument pointer (AP) saved in the stack frame is assumed to
 point to the caller's argument list.

3 CHK_ARGS
 Check for required number of arguments to the caller of this
 procedure.

 ret-sts.wlc.v = LIB_CHK_ARGS( nreq.rl.r )

  nreq    minimum number of arguments that are required to be in
          the argument list of caller of LIB_CHK_ARGS.  Byte passed
          by reference.

  ret-sts completion status.  SS$_NORMAL is returned if at least
          the number of required arguments is present in the caller's
          argument list.  SS$_INSFARG is returned if too few
          arguments are in the caller's argument list or if a
          required argument is defaulted.  Passed by value.


3 CLR_BIT
 Clears a bit in the bit array (string).

 CALL LIB_CLR_BIT( bitno.rl.r, bits.mv.ra )

  bitno   longword containing the number of the bit to be cleared.
          Passed by reference

  bits    first byte of the bit string (or array).  The bit specified
          by bitno is modified.  Passed by reference.

3 CLR_LOCK
 Clears an interlock bit in the bit string and returns the previous
 value of the bit.

 value.wlu.v = LIB_CLR_LOCK( bitno.rl.r, bits.mv.ra )

  value   previous value of specified bit returned as TRUE (-1) if the
          bit was set or FALSE (0) if the bit was clear.  Passed by
          value.

  bitno   longword containing the number of the bit to be cleared.
          Passed by reference.

  bits    first byte of the bit string (or array).  The bit specified
          by bitno is modified.  Passed by reference.

3 CMPC3
	LIB_CMPC3 will compare two byte arrays until the given length is
	satisfied. This function uses the VAX-11 CMPC3 instruction.

 ret-status.wlu.v = LIB_CMPC3( length.rwu.r,array1.rz.r,array2.rz.r )

 ret-status  The return status has the same meaning as the Real Time
             Library routine STR$COMPARE.  This is an integer longword
             value:
                      -1   array1 < array2
                       0   array1 = array2
                      +1   array1 > array2

 length      Address of integer value containing the length of the
             two byte arrays to compare.

 array1      Address of first byte array to compare.

 array2      Address of second byte array to compare.


3 CMPC5
	LIB_CMPC5 will compare two byte arrays until the given length is
	satisfied. If one of the two arrays is shorter than the other,
	the fill byte will be used compare against the longer array.
	This function uses the VAX-11 CMPC5 instruction.

 ret-status.wlu.v = LIB_CMPC3( array1_length.rwu.r,array1.rz.r,
				fill.rb.r,
				array2_length.rwu.r,array2.rz.r )

 ret-status  The return status has the same meaning as the Real Time
             Library routine STR$COMPARE.  This is an integer longword
             value:
                      -1   array1 < array2
                       0   array1 = array2
                      +1   array1 > array2

 array1_length Address of integer value containing the length of the
               first byte array to compare.

 array1        Address of first byte array to compare.

 fill          Address of byte value containing the filler value used
               for the continued compare in the event that one array
               is shorter than the other.

 array2_length Address of integer value containing the length of the
               second byte array to compare.

 array2        Address of second byte array to compare.


3 FAOL_OUTPUT
 Format and output to SYS$OUTPUT a string of text using the $FAOL
 system service and a list of parameters.

    status.wlc.v = LIB_FAOL_OUTPUT( ctrstr.rt.dx, pl.rz.ra )

 status   returned completion status code.

 ctrstr   the control string for the $FAO service passed by
          descriptor.  Any string descriptor class may be used.

 pl       List of longword parameters used by the format directives
          as (or to access) data.  Passed by reference.

 The resulting string is limited to 255 characters.

3 FAO_OUTPUT
 Format and output to SYS$OUTPUT a string of text using the $FAO
 system service and a set of parameters specified in the calling
 sequence.

    status.wlc.v = LIB_FAO_OUTPUT( ctrstr.rt.dx, [p1.rz.v,...])

 status   returned completion status code.

 ctrstr   the control string for the $FAO service passed by
          descriptor.  Any string descriptor class may be used.

 p1...pn  Optional parameters for the formatting directives.
          Passed by value or reference as determined from the
          format directive.

 The resulting string is limited to 255 characters.

3 FILE_TRNLOG
 Translate any logical names in a file specification, returning
 as the result a file specification string in which no logical
 names are used.

 status.wlc.v = LIB_FILE_TRNLOG(filein.rt.dx1, rslbuf.wt.dx1,
                                [rsllen.ww.r], [dsbmsk.rlu.v])

  filein   input file specification.  Passed by descriptor.

  rslbuf   output file specification string.  Passed by descriptor.

  rsllen   (optional) word in which the actual length of the
           output file specification string is returned.  Passed
           by reference.

  dsbmsk   value of the logical name table search disable mask.
           Passed by value.


3 FRAMEP
 Return a pointer to the stack frame of the outer procedure (the
 caller to LIB_FRAMEP).

 framep.wl.va = LIB_FRAMEP()

  framep   longword returning the virtual memory address of the stack
           frame of the caller of this procedure.

 The argument pointer (FP) saved in the stack frame is assumed to
 point to the caller's stack frame.

3 GETZE_BYTE
 Return a byte value from a memory location or an indexed array.

 value.wlu.v = LIB_GETZE_BYTE( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the byte in memory
            or of the start of the array of bytes.  Passed by reference.

  index     is an optional argument which indicates that an array of
            bytes is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the byte
            in the array.  If the index argument is not used, then
            location gives the address of the byte itself.  Passed by
            reference.

  value     the byte data value is returned as a zero-extended or
            unsigned longword in register R0.  Passed by value.


3 GETZE_WORD
 Return a word value from a memory location or an indexed array.

 value.wlu.v = LIB_GETZE_WORD( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the word in memory
            or of the start of the array of words.  Passed by reference.

  index     is an optional argument which indicates that an array of
            words is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the word
            in the array.  If the index argument is not used, then
            location gives the address of the word itself.  Passed by
            reference.

  value     the word data value is returned as a zero-extended or
            unsigned longword in register R0.  Passed by value.


3 GET_BYTE
 Return a byte value from a memory location or an indexed array.

 value.wb.v = LIB_GET_BYTE( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the byte in memory
            or of the start of the array of bytes.  Passed by reference.

  index     is an optional argument which indicates that an array of
            bytes is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the byte
            in the array.  If the index argument is not used, then
            location gives the address of the byte itself.  Passed by
            reference.

  value     the byte data value is returned as a sign-extended longword.
            Passed by value.


3 GET_DISK_QUOTA
 Get disk quota and usage information.

 status.wlc.v = LIB_GET_DISK_QUOTA( usage.wlu.r, perm.wlu.r
				    [,disk.rt.dx1] [,uic.mlu.r]
				    [,chan.mwu.r] [,over.wlu.r] )

  status  returns completion status.  Passed by value.

  usage   returns the current disk usage (in blocks).  Passed by
          reference.

  perm    returns the permanent disk quota (in blocks).  Passed by
          reference.

  disk    optionally specifies the name of the disk (or a logical
          name) on which the quota entry to be returned resides.
          If defaulted, "SYS$DISK:" is used.  Passed by scalar
          descriptor.

  uic     optionally specifies the UIC for the quota entry.  If
          defaulted, the current UIC of the process is used.  If
          a longword value of 0 is specified, the current UIC is
          again used and then returned in the longword (replacing
          the 0) for use in later calls.

  chan    optionally specifies a word in which the channel number
          assigned to the disk device.  If defaulted, a channel is
          assigned and then deassigned for each call.  If specified
          with a value of 0, a channel is assigned and returned in
          the argument for use with later calls.

  over    optionally returns the overdraft disk quota (in blocks).
          Passed by reference.

4 Examples
 These are some examples of the use of this routine.

 To get the disk usage and permanent quota of the current UIC on the
 current default disk (sort of once only):

        status = LIB_GET_DISK_QUOTA( dusage,dperm )

 To get the disk usage and permanent quota of the current UIC on some
 specified device (given by a logical name):

        status = LIB_GET_DISK_QUOTA( dusage,dperm,'OTHER_DISK:' )

 To repeated call to monitor disk usage and remaining quota on a disk
 for the current UIC, where in the initialization code the variables
 thisuic and qchannel were initialized to 0:

        status = LIB_GET_DISK_QUOTA( dusage,dperm,'APPLE_DISK:',
                                     thisuic,qchannel )

 On the first call, thisuic and qchannel will be written with the
 current UIC and the channel on which APPLE_DISK has been opened.
 These variables are then saved (non-stack variables) to eliminate
 the overhead to lookup UIC and open disk channel on subsequent
 calls.

4 Status
 Some of the completion status codes returned are:

    SS$_NORMAL      success
    SS$_ACCVIO      device string or descriptor cannot be read
    SS$_BADQFILE    invalid disk quota file format
    SS$_DEVALLOC    device is allocated to another process
    SS$_DEVOFFLINE  device is offline
    SS$_IVCHAN      invalid channel number
    SS$_IVDEVNAM    invalid or non-existant device name
    SS$_IVLOGNAM    invalid logical name
    SS$_NODISKQUOTA no disk quota entry for UIC
    SS$_NOIOCHAN    no I/O channel is available for assignment
    SS$_NOPRIV      non-existant channel or no privilege to
                    read quota file
    SS$_NOSUCHDEV   (warning) no such device
    SS$_QFNOTACT    disk quota file is not active


3 GET_LONG
 Return a longword value from a memory location or an indexed array.

 value.wl.v = LIB_GET_LONG( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the longword in
            memory or of the start of the array of longwords.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            longwords is to be accessed by indexed addressing.  The
            index argument is a longword which contains the index of
            the longword in the array.  If the index argument is not
            used, then location gives the address of the longword
            itself.  Passed by reference.

  value     the returned longword data value.  Passed by value.


3 GET_QUAD
 Return a quadword value from a memory location or an indexed array.

 value.wq.v = LIB_GET_QUAD( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the quadword in
            memory or of the start of the array of quadwords.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            quadwords is to be accessed by indexed addressing.  The
            index argument is a longword which contains the index of
            the quadword in the array.  If the index argument is not
            used, then location gives the address of the quadword
            itself.  Passed by reference.

  value     the returned quadword data value.  Passed by value.


3 GET_WORD
 Return a word value from a memory location or an indexed array.

 value.ww.v = LIB_GET_WORD( location.ra.r [,index.rl.r] )

  location  longword which contains the address of the word in memory
            or of the start of the array of words.  Passed by reference.

  index     is an optional argument which indicates that an array of
            words is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the word
            in the array.  If the index argument is not used, then
            location gives the address of the word itself.  Passed by
            reference.

  value     the word data value is returned as a sign-extended longword.
            Passed by value.


3 INIT_QHDR
 Initialize the queue header of an absolute queue to empty.

 CALL LIB_INIT_QHDR( header.mqu.ra )

  header       the quadword queue header (an array of two longwords)
               for the absolute queue.  Passed by reference.


3 INSQUE
 Insert an entry onto an absolute queue using the VAX-11 INSQUE
 instruction.

 ret-status.wlc.v = LIB_INSQUE( entry.mqu.ra, pred.ra.r )

  ret-status   completion status code for routine, passed by value:
               SS$_NORMAL      successful completion.
               LIB$_ONEENTQUE  entry is the first in the queue.

  entry        an array that must be at least 8 bytes long.  Any bytes
               following the first 8 bytes may be used for any purpose
               by the calling module (the first 8 bytes are reserved
               for the forward and backward links of the queue). Passed
               by reference.

  pred         longword containing the absolute address of the current
               queue entry before which the new entry is to be inserted.
               Passed by reference.  Queues referenced by two processes
               or by both AST and non-AST code must insert at the head 
               or tail only.

4 Header
 An absolute queue is described by a header consisting of two longwords.
 Each entry in the queue also consists of (at least) two longwords which
 contain the forward and backward link pointers of the queue as absolute
 addresses of the predecessor and trailing queue entries.  The link
 pointers of the queue header point to the first and last queue entries.

 An empty queue consists of just the queue header in which both the
 forward (first longword) and backward (second longword) link pointers
 point to the queue header itself (addresses of the first longword of
 the queue header).

 If more than 1 process (or both AST and non-AST level code within a VMS
 process) can perform operations on a queue simultaneously, then
 insertions and removals should only be done at the head or tail of the
 queue.  If only a single process and code level can perform operations
 on a queue, then insertions and removals can be made at other than the
 head or tail of the queue.
4 Examples
 If the queue header has been declared as:

       INTEGER*4 header(2)

 then an entry may be inserted at the head of the queue by:

          LIB_INSQUE(new_entry, header)      or
          LIB_INSQUE(new_entry, header(1))

 and at the tail of the queue by either of:

          LIB_INSQUE(new_entry, %VAL(header(2)))  or
          LIB_INSQUE_TAIL(new_entry, header)

 or after an old entry by doing:

	   LIB_INSQUE(new_entry, old_entry)

 where new_entry and old_entry are the arrays themselves.  If the
 address of the new queue entry is stored in a longword (entry),
 then to insert onto the head of the queue do:

          LIB_INSQUE(%VAL(entry), header(1))

 and so forth.

3 INSQUE_TAIL
 Insert an entry onto the tail of an absolute queue using the
 VAX-11 INSQUE instruction.

 ret-status.wlc.v = LIB_INSQUE_TAIL( entry.mqu.ra, header.mqu.r )

  ret-status   completion status code for routine, passed by value:
               SS$_NORMAL      successful completion.
               LIB$_ONEENTQUE  entry is the first in the queue.

  entry        an array that must be at least 8 bytes long.  Any bytes
               following the first 8 bytes may be used for any purpose
               by the calling module (the first 8 bytes are reserved
               for the forward and backward links of the queue). Passed
               by reference.

  header       the quadword queue header (an array of two longwords)
               for the absolute queue.  Passed by reference.  Queues
               referenced by two processes or by AST and non-AST code
		must insert at the head or tail only.

 See also LIB_INSQUE.

3 LOCB
 Locate a byte value in an array of bytes (similar to LIB$LOCC except
 that the search value and array are specified by reference rather than
 by descriptor).

 index.wlu.v = LIB_LOCB( schval.rbu.r, len.rwu.r, array.rbu.ra )

  index   returns the index of the byte in the array (if found) or
          zero if search value is not found in the array.  The index
          is relative to the beginning of the array, treating the
          first element as index 1.

  schval  the byte-long search value passed by reference.

  len     length of the array (count of bytes in it).  Passed by
          reference.

  array   the array of bytes to be searched, passed by reference.

3 LOG_SIGNALS
 Initialize and (by default) establish a condition handler to log
 signals to system operator(s) and the operator log file.

 CALL LIB_LOG_SIGNALS([ctstr1.rt.dx [,ctstr2.rt.dx [,tgtops.rlu.r
                      [,flags.rlu.v]]]])

  ctstr1   ...
  ctstr2   $FAO input control strings used to setup the report
           string.  See the "Control_Strings" subtopic for more
           information.  Passed by descriptor.

  tgtops   longword in which the low order 24 bits are the bit mask
           describing to which system operators the report message
           is to be sent.  Default is all operators.  Passed by
           reference.

  flags    control flag bits passed by value.  Default is 0 (all
           bits are OFF).  See subtopic "F;ags" for more detail.

 LIB_LOG_SIGNALS will not generate a message for OPCOM if the signal
 is SS$_OPRABORT.
4 Control_Strings
 The default $FAO control string used to format the first report
 message is "<process-name> Bugcheck !AS. PC=!XL" (text inside the
 quotation marks except that <process-name> is replaced by the actual
 process name).  A user-supplied control string must also include a
 "!AS" FAO directive to insert the signal name text (given by address
 of a string descriptor) and a "!XL" directive (or equivalent) to
 insert the address where the signal was generated (usually the next
 byte after the CALL to LIB$STOP or LIB$SIGNAL).

 The first control string may inlcude an additional a "!XL" directive 
 to insert the process status longword in the output.  Thus an example
 of the first control string could be:
	"DINGOXX aborted with !AS at PC=!XL and PSL=!XL"

 The default $FAO control string used to format the second report
 message is "<process-name>: !AS" where the "!AS" directive in this
 case is used to insert the signal description text.  The user-
 supplied control string must also include a "!AS" directive.
4 Flags
 The bits of the flags longword parameter have the following uses:
  Bit#     Flag     Use
  ----     ----     ---
    0      noestb   0 (the default) in this flag causes the routine
                    LIB_SIGLOGGER to be setup as the condition
                    handler for the outer procedure (caller of the
                    LIB_LOG_SIGNALS procedure).  Set to 1 to disabl
                    establishing the condition handler (must be
                    done explicitly elsewhere in the program).

    1      nostr1   If 1, then the first OPCOM message (using the
                    ctstr1 control string) is skipped.

    2      nostr2   If 1, then the OPCOM messages using the ctstr2
                    control string are not sent.

    3      noinfo   If 1, then INFORMATIONAL and SUCCESS messages will
                    not be displayed via OPCOM.

4 LIB_SIGLOGGER
 The condition handler for reporting the signals to the system
 operators is called LIB_SIGLOGGER.  It is called with the normal
 condition handler arguments (the signal array address and the
 mechanism array address).  It uses the implicit arguments of
 the currently set target operator mask and the report message
 control string descriptor addresses.


3 NARGS
 Return the number of arguments in the call to the outer procedure
 (caller of LIB_NARGS).

 number.wl.v = LIB_NARGS( [number.wl.r] )

  number   longword returning number of arguments (0-255) in
           the argument list passed to the outer procedure (the
           procedure in which LIB_NARGS is called).

 The result may be returned in the optional argument as well as via
 the function value.  The argument pointer (AP) saved in the stack
 frame is assumed to point to the caller's argument list.

3 OPRMSG
 Send message to system operator consoles and log file.

    ret-sts.wlc.v = LIB_OPRMSG( text.rt.dx )

 ret-sts   returned completion status.  SS$_NORMAL is returned on
           success.  LIB$_INVSTRDES for an invalid string descriptor.
           See the description of the $SNDOPR system service for other
           returned condition codes.  Returned by value.

 text      descriptor of the message text to be sent to the operator.
           Passed by descriptor.

 The message is sent to the CENTRL operator.

3 PUT_BYTE
 Store a byte value into a memory location or an indexed array.

 CALL LIB_PUT_BYTE( value.rb.r, location.ra.r [,index.rl.r] )

  value     value to be stored at the specified location in memory
            or an indirectly-referenced array.  Passed by reference.

  location  is the longword which contains the address of the byte
            in memory or of the start of the array of bytes.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            bytes is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the byte
            in the array.  If the index argument is not used, then
            location gives the address of where to store the byte.
            Passed by reference.

3 PUT_LONG
 Store a longword value into a memory location or an indexed array.

 CALL LIB_PUT_LONG( value.rl.r, location.ra.r [,index.rl.r] )

  value     value to be stored at the specified location in memory
            or an indirectly-referenced array.  Passed by reference.

  location  is the longword which contains the address of the longword
            in memory or of the start of the array of longwords.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            longwords is to be accessed by indexed addressing.  The
            index argument is a longword which contains the index of
            the longword in the array.  If the index argument is not
            used, then location gives the address of where to store
            the longword.  Passed by reference.

3 PUT_QUAD
 Store a quadword value into a memory location or an indexed array.

 CALL LIB_PUT_QUAD( value.rq.r, location.ra.r [,index.rl.r] )

  value     value to be stored at the specified location in memory
            or an indirectly-referenced array.  Passed by reference.

  location  is the longword which contains the address of the quadword
            in memory or of the start of the array of quadwords.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            quadwords is to be accessed by indexed addressing.  The
            index argument is a longword which contains the index of
            the quadword in the array.  If the index argument is not
            used, then location gives the address of where to store
            the quadword.  Passed by reference.

3 PUT_WORD
 Store a word value into a memory location or an indexed array.

 CALL LIB_PUT_WORD( value.rw.r, location.ra.r [,index.rl.r] )

  value     value to be stored at the specified location in memory
            or an indirectly-referenced array.  Passed by reference.

  location  is the longword which contains the address of the word
            in memory or of the start of the array of words.
            Passed by reference.

  index     is an optional argument which indicates that an array of
            words is to be accessed by indexed addressing.  The index
            argument is a longword which contains the index of the word
            in the array.  If the index argument is not used, then
            location gives the address of where to store the word.
            Passed by reference.

3 REMQUE
 Remove an entry from an absolute queue using the VAX-11 REMQUE
 instruction.

 ret-status.wlc.v = LIB_REMQUE( link.mqu.ra, remque-adr.wa.r )

  ret-status   completion status code for routine, passed by value:
               SS$_NORMAL      successful completion.
               LIB$_ONEENTQUE  entry was the last entry in the queue.
               LIB$_QUEWASEMP  queue was already empty (remque-adr is
                               meaningless).

  link         longword containing the absolute address of the entry
               to be removed from the queue.  Passed by reference.
               Queues referenced by two processes or by both AST and
               and non-AST code must remove from the head or tail only.

  remque-adr   longword in which the address of the removed entry is
               returned.  Passed by reference.

4 Header
 An absolute queue is described by a header consisting of two longwords.
 Each entry in the queue also consists of (at least) two longwords which
 contain the forward and backward link pointers of the queue as absolute
 addresses of the predecessor and trailing queue entries.  The link
 pointers of the queue header point to the first and last queue entries.

 An empty queue consists of just the queue header in which both the
 forward (first longword) and backward (second longword) link pointers
 point to the queue header itself (addresses of the first longword of
 the queue header).

 If more than 1 process (or both AST and non-AST level code within a VMS
 process) can perform operations on a queue simultaneously, then
 insertions and removals should only be done at the head or tail of the
 queue.  If only a single process and code level can perform operations
 on a queue, then insertions and removals can be made at other than the
 head or tail of the queue.
4 Examples
 If the queue header and an entry pointer have been declared as:

       INTEGER*4 header(2), entry

 then the entry at the head of the queue is removed by:

          LIB_REMQUE(header(1), entry)

 and the entry at the tail is removed by:

	   LIB_REMQUE(header(2), entry)

 If entry contains the address of a particular entry on the queue,
 then that entry can be removed by:

          LIB_REMQUE(entry, entry)


3 SECTION_UFO
 This routine opens a file to be used as a private/global section file
 (the channel number returned is used in a later call to $CRMPSC).  An
 RMS $OPEN or $CREATE is performed with user-file-open (UFO) set in the
 file options (FOP) of the File Access Block (FAB).  An existing file
 may be opened (for writing, or readonly) or a new file created.

 status.wlc.v = LIB_SECTION_UFO( filnam.rt.dx, chan.ww.r [,dftnam.rt.dx]
                                 [,blkcre.rl.r] [,rdonly.rl.v]
                                 [,blkopn.wl.r] )

  filnam  file name string.  By descriptor.
  chan    longword in which the channel number of the opened file is
          returned for use by $CRMPSC or, if an RMS error occurs, the
          STV field from the FAB is returned.  By reference.
  dftnam  optional default file name string.  By descriptor.
  blkcre  optional file creation block count:
            <0 create new file 
            =0 (or non-existant) open existing file
            >0 open existing file, create if no such file
          The absolute value is size of new file in blocks.  By reference.
  rdonly  if non-zero, opens existing file for readonly access (only if
          the blkcre parameter is 0 or non-existant).  By value.
  blkopn  optional longword in which the size of the opened file (in
          blocks) is returned.  By reference.

 An internal static FAB is used to open the file.  This can be reused
 on subsequent calls but means that this program is non-reentrant.

3 SET_BIT
 Sets a bit in the bit array (string).

 CALL LIB_SET_BIT( bitno.rl.r, bits.mv.ra )

  bitno   longword containing the number of the bit to be set.
          Passed by reference

  bits    first byte of the bit string (or array).  The bit specified
          by bitno is modified.  Passed by reference.

3 SET_LOCK
 Sets an interlock bit in the bit string and returns the previous
 value of the bit.

 value.wlu.v = LIB_SET_LOCK( bitno.rl.r, bits.mv.ra )

  value   previous value of specified bit returned as TRUE (-1) if the
          bit was set or FALSE (0) if the bit was clear.  Passed by
          value.

  bitno   longword containing the number of the bit to be set.
          Passed by reference.

  bits    first byte of the bit string (or array).  The bit specified
          by bitno is modified.  Passed by reference.

3 SLEEP
 Put process to sleep until an absolute time or delay process
 execution for a specified amount of time.

  status.wlc.v = LIB_SLEEP( time.rq.r )

 status    completion status (returned in R0) from the $SCHDWK
           system service.

 time      quadword containing system-format time or delta-time
           which specifies the delay (or sleep-until) time.

 Note, $HIBER is used so sleep time may be shortened by a $WAKE
 done in another process or by an AST of this process.

3 SLEEP_MILLISEC
 Put process to sleep for a specified number of milliseconds.

  status.wlc.v = LIB_SLEEP_MILLISECS( msecs.rlu.r )

 status    completion status (returned in R0) from the $SCHDWK
           system service.

 msecs     unsigned quantity giving the number of milliseconds to
           delay before continuing execution.

 Note, $HIBER is used so sleep time may be shortened by a $WAKE
 done in another process or by an AST of this process.

3 SLEEP_SECONDS
 Put process to sleep for a specified number of seconds.

  status.wlc.v = LIB_SLEEP_SECONDS( seconds.rlu.r )

 status    completion status (returned in R0) from the $SCHDWK
           system service.

 seconds   unsigned quantity giving the number of seconds to delay
           before continuing execution.

 Note, $HIBER is used so sleep time may be shortened by a $WAKE
 done in another process or by an AST of this process.

3 STDESCR
 Function returns a string descriptor created from the input array
 descriptor:

 st_descr.wdsc.v = LIB_STDESCR(array_descr.rbu.da [,length.rwu.r])

  st_descr      output string descriptor (static, fixed-length) is
                returned in registers R0 and R1 (declare as REAL*8
                in FORTRAN).  Passed by value.

  array_descr   the byte array as passed by array descriptor (in
                FORTRAN specify the argument as %DESCR(array) to
                create the array descriptor).

  length        optional, a word containing the length in bytes for
                the output string descriptor.  If not given, the
                array length from the array descriptor is used.
                Passed by reference.

3 TST_ARG_DFT
 Test that a specific argument in the argument list of the outer
 (caller of LIB_TST_ARG_DFT) procedure exists and is not defaulted.

 exists.wlu.v = LIB_TST_ARG_DFT( n.rbu.r )

  n       byte which contains the argument number to tested for.
          Passed by reference.

  exists  longword value returned as -1 (TRUE) if the n'th argument
          is given in the outer procedure argument list and is not
          defaulted (argument value is non-zero).  If n is greater
          than the number of arguments to the outer procedure or if
          the value of the n'th argument is zero, then 0 (FALSE) is
          returned.  Passed by value.

 The argument pointer (AP) saved in the stack frame is assumed to
 point to the caller's argument list.

3 TST_BIT
 Tests the value of a bit in a bit array (string).

 value.wlu.v = LIB_TST_BIT( bitno.rl.r, bits.rv.ra )

  value   value of specified bit returned as TRUE (-1) if the bit is
          set or FALSE (0) if the bit is clear.  Passed by value.

  bitno   longword containing the number of the bit to be tested.
          Passed by reference.

  bits    first byte of the bit string (or array).  Passed by reference.

3 UNDESCR
 Function to return the address of the byte array from a descriptor.

 pointer.wa.v = LIB_UNDESCR( descr.rx.dx [,length.wl.r] )

  pointer   byte array address returned from the array or string
            descriptor (returned in register R0).  Passed by value.

  descr     array, string or varying string.  Both static and
            dynamic strings are handled.  Passed by descriptor.

  length    (optional) longword in which the length of the string
            or array is returned.  For varying strings, the current
            length is returned.  Passed by reference.

3 XNARGX
 Return the number of arguments passed to procedure in the current
 list of stack frames:

 number.wl.v = LIB_XNARGX([depth.rl.v])

  number   longword value with the number of arguments (0-255) in
           the argument list passed to the specified procedure.
           Passed by value.

  depth    longword value indicating the depth in stack frames
           (outside the stack frame for LIB_XNARGX itself) to the
           calling procedure whose argument count is desired.
           Passed by value.

 If the depth is zero, then LIB_XNARGX(0) returns the same value
 as LIB_NARGS(), the number of arguments passed to the procedure
 which called LIB_XNARGX.  If the depth is 1, then LIB_XNARGX(1)
 returns the number of arguments passed to the procedure which
 called the procedure which called LIB_XNARGX (caller of the
 caller of LIB_XNARGX), and so forth.  No checks are made for
 exceeding current stack frame depth (probably result in an access
 violation).


2 MTH_

    MTH_ procedures.

3 QUAD_ADD
 Add two quadword integers.

 CALL MTH_QUAD_ADD( addend1.rq.r, addend2.rq.r, sum.wq.r )

  addend1   1st quadword to be added.  Passed by reference.

  addend2   2nd quadword to be added.  Passed by reference.

  sum       quadword in which resultant sum is returned.
            Passed by reference.

3 QUAD_CMP
 Compare two quadword integers.

 cmp.wl.v = MTH_QUAD_CMP( quad1.rq.r, quad2.rq.r )

  quad1   first quadword integer.  Passed by reference.

  quad2   second quadword integer.  Passed by reference.

  cmp     (longword) result of the quadword comparison:
                       -1 if quad1 < quad2
                        0 if quad1 = quad2
                       +1 if quad1 > quad2
          Passed by value.

3 QUAD_DIV
 Divide one quadword integer by another and return their quadword
 quotient and (optionally) the quadword remainder.

 CALL MTH_QUAD_DIV( divd.rq.r, divr.rq.r, quot.wq.r [,rem.wq.r] )

  divd    quadword containing the dividend to be divided by the
          divisor.  Passed by reference.

  divr    quadword containing the divisor.  Passed by reference.

  quot    quadword in which the quotient of the division is
          returned.  Passed by reference.

  rem     optional quadword in which the remainder from the
          division may be returned.  Passed by reference.


3 QUAD_EDIV
 Divide a quadword integer by a longword and return the longword
 quotient and (optionally) the longword remainder.

 CALL MTH_QUAD_EDIV( divd.rq.r, divr.rl.r, quot.wl.r [,rem.wl.r] )

  divd    quadword containing the dividend to be divided by the
          divisor.  Passed by reference.

  divr    longword containing the divisor.  Passed by reference.

  quot    longword in which the quotient of the division is returned.
          Passed by reference.

  rem     optional longword in which the remainder from the division
          may be returned.  Passed by reference.


3 QUAD_EMUL
 Multiply two longword integers and return a quadword integer as
 the result.

 CALL MTH_QUAD_EMUL( multr.rl.r, multd.rl.r, prod.wq.r )

  multr   longword with the multiplier.  Passed by reference.

  multd   longword with the multiplicand.  Passed by reference.

  prod    quadword in which the product is returned.  Passed by
          reference.


3 QUAD_FLOAT
 Convert quadword integer to floating point.

 result.wl.v = MTH_QUAD_FLOAT( quad.rq.r )
 result.wq.v = MTH_QUAD_DOUBLE( quad.rq.r )

  quad     quadword to be converted to floating point.  Passed by
           reference.

  result   returned floating point result (either single or double
           precision).  Passed by value.

3 QUAD_MUL
 Multiply two quadword integers.

 CALL MTH_QUAD_MUL( multr.rq.r, multd.rq.r, prod.wq.r )

  multr   quadword with the multiplier.  Passed by reference.

  multd   quadword with the multiplicand.  Passed by reference.

  prod    quadword in which the product is returned.  Passed by
          reference.


3 QUAD_SUB
 Subtract two quadword integers.

 CALL MTH_QUAD_SUB( min.rq.r, sub.rq.r, dif.wq.r )

  min     quadword with the minuend (from which the subtrahend
          is subtracted).  Passed by reference.

  sub     quadword with the subtrahend.  Passed by reference.

  dif     quadword in which the difference is returned.  Passed
          by reference.


3 X530FP
 Converts a Xerox 530 48-bit floating point value to VAX REAL*4
 format, and returns the result to the outer (caller) procedure.

 number.wf.v = MTH_X530FP( x530.rv.r, flag.rbu.r, ierr.ww.r )

  number	Converted floating-point number (REAL*4)

  x530		6-byte array containing Xerox floating point value.
		The first two bytes contain the most significant part
		of the mantissa.  The middle two bytes contain the
		least significant part of the mantissa.  The last two
		bytes contain the binary exponent.  Passed by reference.

  flag		A logical flag which controls byte-swapping.  If TRUE,
		each of the 3 X530 words will be byte-swapped before
		conversion.  Passed by reference.

  ierr		A 2-byte return code (passed by reference):
		 0	Successful conversion.
		+1	Underflow.  The Xerox value contained an exponent
			which was too small. The function returns zero.
		+2	Lost precision. The Xerox mantissa contains 7 more
			bits than the VAX mantissa. One or more of these
			bits were non-zero and discarded.  This warning
			can generally be ignored.
		-1	Overflow.  The Xerox value contained an exponent
			which was too big. The function returns +/-.17E+39.
		-2	Un-normalized value. The Xerox value is probably
			corrupted.  Try inverting the swap flag argument.
			The function returns zero.

2 RMS_

    RMS_ procedures.

3 ANYWILD
 After a call to RMS_PARSE, test if there were any wild cards in the
 parsed file specification.

 result.wlu.v = RMS_ANYWILD( [fil_nam_sts.wlu.r] )

  result       a longword value of TRUE (-1) is returned if the parsed
               file specification included any wildcards.  Otherwise
               the value of FALSE (0) is returned.  Passed by value.

  fil_nam_sts  (optional) longword in which the file name status bits
               are returned.  Passed by reference.


3 FILESPEC
 Return specified fields of the file specification resulting from a
 previous call to RMS_PARSE or RMS_SEARCH.

 status.wlc.v = RMS_FILESPEC( keyword.rt.dx, string.wt.dx
                              [,length.ww.r])

  status   completion status code returned in register R0.  Passed
           by value.

  keyword  text string specifying one of the file specification
           field keywords.  Passed by descriptor.

  string   string in which the field of the file specification
           indicated by the keyword argument is returned.  Passed by
           descriptor.

  length   word in which the length of the above string is also
           optionally returned.  Passed by reference.

4 Keywords
 The recognized keywords to be used in the keyword argument and the
 file specification fields they return are:

   DEVICE     returns the device name (including trailing ":").
   DIRECTORY  returns the directory specification (including the
              enclosing brackets, "[]" or "<>").
   NODE       returns the node name (including trailing "::").
   NAME       returns the file name.
   TYPE       returns the file type with a leading ".".
   VERSION    returns the file version with a leading ";".

 The keywords may be abbreviated to the first 2 characters of the
 name.

4 Condition_codes

  SS$_NORMAL      Success.
  LIB$_STRTRU     Success, some returned text truncated to fit in its
                  output string.
  LIB$_FATERRLIB  Fatal internal library error.
  LIB$_INSVIRMEM  Insufficient virtual memory.
  LIB$_INVSTRDES  Invalid string descriptor.
  LIB$_UNRKEY     Unrecognized keyword.
 

3 GET_VRNSIZ
 Open a specified file using RMS and return the file's version
 number and size (in blocks).

 status.wlc.v = RMS_GET_VRNSIZ( filespec.rt.dx, [dftspec.rt.dx],
                                version.wl.r, length.wl.r )

  filespec   file specification string.  Passed by descriptor.

  dftspec    optional default file specification string.  Used
             by RMS to fill in missing fields in the input file
             specification.  Passed by descriptor.

  version    longword in which the file's version number (in
             binary) is returned.  Passed by reference.

  length     longword in which the file's size (in blocks) is
             returned.  This is actually the virtual block number
             of the last used block (possibly the EOF virtual
             block number).  Passed by reference.

  status     completion status code.  The RMS error condition code is
             returned if the OPEN fails.  Passed by value.


3 PARSE
 Provide High Level Language access to the RMS $PARSE service to allow
 the parsing (include default resolution) of file specifications.  In
 addition the RMS_PARSE routine prepares a file specification containing
 wilcards for the RMS_SEARCH routine.

 status.wlc.v = RMS_PARSE(file_spec.rt.dx [,dft_spec.rt.dx]
                          [,rtn_spec.wt.dx] [,rtn_len.ww.r])

  status     completion status code.  Passed by value.

  file_spec  file specification string to be parsed (may include wild
             cards).  Passed by descriptor.

  dft_spec   (optional) a second file specification string to provide
             defaults.  Passed by descriptor.

  rtn_spec   (optional) returns the expanded file specification string.
             Passed by descriptor.

  rtn_len    (optional) word in which the length of the expanded file
             specification string is be returned.  Passed by reference.

4 Condition_codes

  RMS$_NORMAL     Success (no rtn_spec argument).
  SS$_NORMAL      Success (expanded specification returned in rtn_spec).
  LIB$_STRTRU     Success, expanded string truncated to fit in output
                  parameter string (rtn_spec).
  LIB$_FATERRLIB  Fatal internal library error.
  LIB$_INSVIRMEM  Insufficient virtual memory.
  LIB$_INVSTRDES  Invalid string descriptor.
  RMS$_DNF        Directory not found.
  RMS$_DNR        Device not ready or not mounted.
  RMS$_WCC        Invalid wild card context value
 

3 RELATED
 Used before a call to RMS_PARSE to setup a related file name block (NAM)
 for the $PARSE operation to be done in the RMS_PARSE.

 status.wlc.v = RMS_RELATED( file_spec.rt.dx [,dft_spec.rt.dx]
                             [,inp_type.rlu.v] )

  status     completion status code.  Passed by value.

  file_spec  the file specification used to form the related file
             specification.  Passed by descriptor.

  dft_spec   (optional) a second file specification to provide defaults.
             Passed by descriptor.

  inp_type   (optional) if value is TRUE (1), then the RMS_PARSE call
             is considered to be for an input file and the Output File
             Parse (OFP) in the file options will not be set.
             Passed by value.

 By default, the following RMS_PARSE call is considered to be for an
 output file parse and so the OFP file option is enabled (override with
 the inp_type argument).

4 Condition_codes

  RMS$_NORMAL     Success (no rtn_spec argument).
  SS$_NORMAL      Success (expanded specification returned in rtn_spec).
  LIB$_STRTRU     Success, expanded string truncated to fit in output
                  parameter string (rtn_spec).
  LIB$_FATERRLIB  Fatal internal library error.
  LIB$_INSVIRMEM  Insufficient virtual memory.
  LIB$_INVSTRDES  Invalid string descriptor.
  RMS$_DNF        Directory not found.
  RMS$_DNR        Device not ready or not mounted.
  RMS$_WCC        Invalid wild card context value
 

3 RENAME
 This routine renames a file (can also change the directory in which the
 file is entered) by calling the RMS $RENAME service.

 status.wlc.v = RMS_RENAME( oldfil.rt.dx, newfil.rt.dx
                            [,olddft.rt.dx] [,newdft.rt.dx]
                            [,stv.wlu.r] )

  status  any status returned by RMS or LIB$ANALYZE_SDESC.
  oldfil  current file specification string.  By descriptor.
  newfil  new file specification string.  By descriptor.
  olddft  (optional) default file specification string for old file.
          By descriptor.
  newdft  (optional) default file specification string for new file.
          By descriptor.
  stv     (optional) secondary status value returned from the FAB
          (FAB$L_STV, see the "RMS Reference Manual").

 The current version of this routine will not work with wildcards in the
 file specifications (oldfil or newfil).  This routine is not re-entrant
 due to the use of static internal data structures.

3 SEARCH
 Provide High Level Language access to the RMS $SEARCH service to process
 wild cards in file specifications.  Before RMS_SEARCH can be called, the
 RMS_PARSE routine must be called to initialize internal storage.

 status.wlc.v = RMS_SEARCH( res_spec.wt.dx [,res_len.ww.r] )

  status    completion status code.  Passed by value.

  res_spec  returns the resultant file specification (with all wild
            cards and defaults resolved).  Passed by descriptor.

  res_len   (optional) word in which the length of the resultant file
            specification string is returned.  Passed by reference.

 To process wildcard file specifications, call RMS_PARSE to initialize
 the internal storage then call RMS_SEARCH in a loop.  Each call to
 RMS_SEARCH will return a valid file specification until the status of
 RMS$_NMF is returned.  This status code (an error) indicates that the
 wild card search has been exhausted.

4 Condition_codes

  SS$_NORMAL      Operation successful.
  LIB$_STRTRU     Success, resultant string truncated to fit in output
                  parameter string (res_spec).
  LIB$_FATERRLIB  Fatal internal library error.
  LIB$_INSVIRMEM  Insufficient virtual memory.
  LIB$_INVSTRDES  Invalid string descriptor.
  RMS$_DNF        Directory not found
  RMS$_DNR        Device not ready or not mounted
  RMS$_FND        ACP file or directory lookup failed
  RMS$_FNF        File not found
  RMS$_NMF        No more files found (wildcard search completion)
  RMS$_PRV        Insufficient privilege or file protection violation
  RMS$_WCC        Invalid wild card context value


2 STR_

    STR_ procedures.

3 SQUEEZE
 Squeeze spaces and tabs from a string.  All tabs are converted to
 spaces and all trailing spaces (except for padding in fixed-length
 strings) are removed.  

 CALL STR_SQUEEZE( string.mt.dx [,mode.rlu.v] [,outlen.ww.r])

  string    the input and output strings.  Passed by descriptor.

  mode      optional mode control.  If low bit is 0 (or if the
            argument is defaulted) then multiple spaces are replaced
            by single spaces.  If low bit is 1 then all spaces are
            removed.  Passed by value.

  outlen    (optional) word in which the length of the output string
            is returned (not including padding blanks).  Passed by
            reference.

