1 RSTSOPEN
  RSTSOPEN (RSO) is a group of callable modules for BASIC programs used to
  augment BASIC's OPEN statement using the USEROPEN clause.  When used, the
  programmer can include various qualifiers appended directly onto the
  filename for processing by RSTSOPEN prior the doing the OPEN itself.
  RSTSOPEN is supplied through the VAX SIG Library of the U.S. Chapter
  of DECUS, courtesy of Victor Lindsey (of VLSystems, Inc., 2691 Richter
  Ave., Suite 118, Irvine, California, USA 92714 -- 714/660-8855).
  Neither Mr. Lindsey nor VLSystems assumes any responsibility for the
  suitability or correctness of this code.  RSTSOPEN runs on VMS version
  4.1 or MicroVMS version 4.1M and should be compatible with later versions
  of these operating systems.
2 Philosophy
  The purpose of RSTSOPEN is two-fold: [1] to provide an easy means to
  write code using advanced file functions, that works the same way on both
  VMS and RSTS/E (a DEC operating system which runs exclusively under
  PDP-11s); and [2] to provide an easy and flexible way to access some of
  the more powerful features of VMS/RMS.  Under RSTS/E, both BASIC-PLUS and
  BASIC-PLUS-2 (from which VMS BASIC was first modeled after) allow qual-
  ifiers to be appended to filename in their OPEN statements.  By taking
  advantage of VMS BASIC's USEROPEN clause, we can emulate to a large
  degree, those features found on RSTS/E as well as many of the RMS
  features that belong exclusively to VMS.  Since RSTS/E permits its quali-
  fiers to be abbreviated to just two characters, RSTSOPEN also permits
  this kind of abbreviation--EVEN WHEN OBVIOUS AMBIGUITIES RESULT.  In the
  case of ambiguities, RSTSOPEN arbitrarily chooses the most commonly used
  qualifier meaning.  Thus, to absolutely avoid ambiguities, it is recom-
  mended that the program provide enough characters to make the qualifier
  unique.  Since RSTS/E has certain qualifiers with no direct correspond-
  ence to VMS, the program must evaluate them first before an actual OPEN
  is done (see Parse_only under Modules for the use of RSO_OPENX).  By
  including the use of BASIC compiler constructs, you can write truly
  sophisticated BASIC programs where one source will work on both RSTS/E
  as well as VMS!  All code and documentation are located in the directory
  described by the RSTSOPEN system logical.
2 Modules
  RSTSOPEN consists of two object modules generated from the following
  code: [1] RSO_OPEN.MAR (MACRO-32) containing entry points for RSO_OPENX,
  RSO_OPENI, and RSO_OPENO; and [2] RSO_MSG.MSG containing the message
  vectors required by RSTSOPEN to display error messages.  In addition,
  a third module called RSO_CLOSE.MAR is provided to provide selective
  updating of revision dates, protection codes, and UIC.  All RSTSOPEN
  related files may be found in the RSTSOPEN: directory.
3 OPEN_FOR_INPUT
  To use RSTSOPEN in an "OPEN FOR INPUT" statement, you must use the
  RSO_OPENI reference in the USEROPEN clause.  For example:
              OPEN "FILE.DAT" FOR INPUT AS FILE #1%, &
               ORGANIZATION VIRTUAL, &
               USEROPEN RSO_OPENI
  Note: Use of RSO_OPENI will convert an "OPEN FOR OUTPUT" statement
  to an "OPEN FOR INPUT" statement.
3 OPEN_FOR_OUTPUT
  To use RSTSOPEN in an "OPEN FOR OUTPUT" statement, you must use the
  RSO_OPENO reference in the USEROPEN clause.  For example:
              OPEN "FILE.DAT" FOR OUTPUT AS FILE #1%, &
               ORGANIZATION VIRTUAL, &
               USEROPEN RSO_OPENO
  Note: Use of RSO_OPENO forces the OPEN statement to become an "OPEN
  FOR OUTPUT" statement, even if the "FOR OUTPUT" clause is omitted or
  the "FOR INPUT" clause is given instead.
3 OPEN
  To use RSTSOPEN in an "OPEN" statement WITHOUT either "FOR INPUT" or
  "FOR OUTPUT" clauses, you must use the RSO_OPENI reference in the
  USEROPEN clause.  For example:
              OPEN "FILE.DAT" AS FILE #1%, &
               ORGANIZATION VIRTUAL, &
               USEROPEN RSO_OPENI
3 Parse_only
  Sometimes, it is useful to evaluate the qualifiers of a filename and
  identify the various components of the filename without actually doing
  an OPEN.  To do this, you must use the RSO_OPENX reference in the
  USEROPEN clause.  For example:
              OPEN "FILE.DAT" AS FILE #1%, &
               ORGANIZATION VIRTUAL, &
               USEROPEN RSO_OPENX
  Note: Use of RSO_OPENX causes the "FOR INPUT" or "FOR OUTPUT"
  clauses to be ignored if they are included in the OPEN statement
  itself.
3 RSO_CLOSE
  RSO_CLOSE does a "behind BASIC's back" CLOSEing of a file in order to
  allow you to alter any combination of its revision date, number of
  revisions, file ownership (UIC), and protection code.  Such values
  frequently come from earlier executions of RSTSOPEN routines.  The
  format is:

  QUAD val = RSO_CLOSE(WORD arg1 by ref, [QUAD arg2 by ref, &
              [WORD arg3 by ref], [LONG arg4 by ref], &
              [WORD arg5 by ref])

  where the low order LONGWORD of "QUAD val" is the RMS condition code
  (65537 means success), high order LONGWORD of "QUAD val" is the
  system condition code (useful should the RMS condition code be vague
  about RSO_CLOSE's problem), and arg1 is the required internal file
  identifier RMS gave BASIC when the file was OPENed--this value is
  returned by RSO_OPENI or RSO_OPENO in the RSO_GW_FAB_IFI global vari-
  able and is required by RSO_CLOSE.  The remaining four arguments, if
  given, will establish new values for revision date, number of revi-
  sions, UIC, and protection code--in that order.  Values should be
  given in the same format as given for RSO_GQ_REVISION_DATE, RSO_GW_-
  N.REVISIONS, RSO_GL_UIC, and RSO_GW_PROTECTION_CODE.

  Because BASIC doesn't know the channel is CLOSEd, the program must
  immediately try and OPEN the channel again and trap for the inevitable
  "?Fatal system I/O error" that results.  Failure to do so leaves the
  channel unuseable for the remainder of the program's execution; and
  when the program exits, BASIC will cause your program to blow up.
  This is because BASIC declares an autoCLOSEing exit handler for each
  file OPENed--a handler which does not expect an OPENed file to be
  closed without the use of the CLOSE statement--which is executed for
  any channel BASIC still thinks is OPENed when your program terminates.
  For an example of the use of RSO_CLOSE, look at the RSOTEST.BAS sample
  program in RSTSOPEN:.
3 Libraries
  RSTSOPEN was written such that it can be included in executable librar-
  ies.  An example of how to build such a library is found in RSTSOPEN:
  directory under the files LIBR.OPT and LIBR.MAR.
3 How_RSTSOPEN_works
  In brief, the steps taken by RSTSOPEN are as follows:
   (1) After zeroing the RSO_xxx variables, scan the contents of the
       filename passed to OPEN.  If the filename contains a "/" (the
       beginning of qualifiers) or a ">" just before the end of the file-
       name string (or just before a "/"), then parse the "extra stuff" on
       the filename to evaluate additional RMS options desired and place
       the results in RSO_xxx variables.  If RSO_OPENX, then RSTSOPEN
       exits immediately after completion of the parse--no OPEN is per-
       formed.  This parsing is accomplished by use of the LIB$TPARSE RTL
       routine.
   (2) Construct any additional RMS structures required (called XABs) and
       then do the OPEN (RMS $CREATE or $OPEN services), with the filename
       stripped of any qualifiers.  If successful, update the contents of
       RSO_xxx variables; else exit.
   (3) Do the RMS $CONNECT service to establish an I/O stream to the file
       just OPENed.  A /FOP=UFO causes RSTSOPEN to bypass this step.
   (4) Exit, deallocating any additional RMS structures added on, and
       return informing BASIC of any error conditions encountered.  Note:
       unusual errors not normally encountered by BASIC are treated as
       ERR=162 meaning "Cannot open file"--more detailed error information
       is returned in the varaibles RSO_GL_RMS_STS and RSO_GL_RMS_STV.
2 Data_returned
  All data evaluated by RSTSOPEN (and RMS) is returned through global
  variables starting with RSO_G....  RSO_GB... are BYTE values; RSO_GW...
  are WORD values; RSO_GL... and RSO_GA... are LONGWORD values; RSO_GQ...
  are QUADWORD values; and RSO_GT... and fixed length text STRINGs.  For
  example of how to evaluated these values, refer to the sample program
  RSOTEST.BAS in the RSTSOPEN: directory.  If brief, they are as follows:

  Variable name                Descriptions
---------------------------- -----------------------------------------------
RSO_GT_ACL                   512-byte buffer for ACL of file opened (if any)
RSO_GW_ACLLEN                Total length of ACL in bytes (can exceed 512)
RSO_GL_ACL_CONTEXT           ACE sequence number to start at for RSO_GT_ACL
RSO_GL_ACL_STS               VMS status for reading ACL
RSO_GQ_BACKUP_DATE           VMS last backup date
RSO_GW_BLOCK_SIZE            RMS blocksize for device (usually magtape)
RSO_GW_BUFFER_COUNT          from /BUFFER_COUNT
RSO_GB_CHAN_MODE             Channel mode, from /CHAN_MODE
RSO_GQ_CREATION_DATE         VMS creation date
RSO_GL_DEVCHR                Primary Device Characteristics from RMS
RSO_GL_DEVCHR2               Secondary Device Characteristics from RMS
RSO_GW_DEV_LEN               Length of device name in RSO_GT_FILENAME
RSO_GW_DEV_OFF               Offset to device name in RSO_GT_FILENAME
RSO_GW_DID1                  1st word of directory's file ID
RSO_GW_DID2                  2nd word of directory's file ID
RSO_GW_DID3                  3rd word of directory's file ID
RSO_GW_DIR_LEN               Length of directory name in RSO_GT_FILENAME
RSO_GW_DIR_OFF               Offset to directory name in RSO_GT_FILENAME
RSO_GT_DVI                   .ASCIC (counted string), 1st byte describes
                             length of text in the remaining 15 bytes
RSO_GQ_EXPIRATION_DATE       VMS expiration date
RSO_GB_FAB_FAC               FAB's File ACcess byte, from OPEN and /FAC
RSO_GL_FAB_FOP               FAB's File OPtion, from OPEN and /FOP
RSO_GW_FAB_IFI               Internal File ID (FAB), returned by RMS
RSO_GB_FAB_SHR               FAB's SHaRable byte, from OPEN and /SHR
RSO_GW_FID1                  1st word of file's file ID
RSO_GW_FID2                  2nd word of file's file ID
RSO_GW_FID3                  3rd word of file's file ID
RSO_GT_FILENAME              Full RMS evaluation of filename (max 255 bytes)
RSO_GL_FILESIZE              Allocated block size, from /FILESIZE or /SIZE
RSO_GW_FILE_EXTENT           from /EXTENT=nn
RSO_GB_FILE_MODE             File mode, from /FILE_MODE
RSO_GW_GLOBAL_BUFFER         Number of global buffer, from /GLOBAL_BUFFERS
RSO_GW_LEN                   Length of filename returned in RSO_GT_FILENAME
RSO_GB_LNM_MODE              Logical name translation mode, from /LNM_MODE
RSO_GB_MTACC                 Magtape accessibility byte for ANSI HDR1 record
RSO_GW_MULTI_BLOCK           from /MULTI_BLOCK
RSO_GW_N.REVISIONS           Number of revisions, from /REVISION_NUMBER=nn
RSO_GW_NAME_LEN              Length of file name in RSO_GT_FILENAME
RSO_GW_NAME_OFF              Offset to file name in RSO_GT_FILENAME
RSO_GL_NEXT_NEW_BLOCK        Block number where next byte is to be appended
RSO_GW_NEXT_NEW_BYTE         Byte offset in above block
RSO_GW_NODE_LEN              Length of node name in RSO_GT_FILENAME
RSO_GW_NODE_OFF              Offset to node name in RSO_GT_FILENAME
RSO_GW_PROTECTION_CODE       Bit map of VMS protection code, /PROT=(...)
RSO_GA_RAB_ADDR              Virtual address of RAB block (32-bit value)
RSO_GW_RAB_ISI               Internal Stream ID (RAB), returned by RMS
RSO_GL_RAB_ROP               RAB's Record OPtion, from OPEN and /ROP
RSO_GQ_REVISION_DATE         VMS revision date
RSO_GL_RMS_STS               VMS error code
RSO_GL_RMS_STV               VMS system error code when above code from RMS
RSO_GL_RSTS_CLUSTER          from /CLUSTERSIZE
RSO_GL_RSTS_MODE             from /MODE or /RONLY (makes mode=8192)
RSO_GL_RSTS_POSITION         from /POSITION
RSO_GL_RSTS_PROTECTION_CODE  from <nnn> evaluation or /PROTECTION=nnn
RSO_GW_TYPE_LEN              Length of file type in RSO_GT_FILENAME
RSO_GW_TYPE_OFF              Offset to file type in RSO_GT_FILENAME
RSO_GL_UIC                   UIC of file
RSO_GW_VERSION_LIMIT         Version limit, from /VERSION_LIMIT=nn
RSO_GW_VER_LEN               Length of version number in RSO_GT_FILENAME
RSO_GW_VER_OFF               Offset to version number in RSO_GT_FILENAME
RSO_GW_WINDOWSIZE            Retrieval pointers windowsize, from /WINDOWSIZE
2 Errors
  When BASIC encounters errors from RMS during an OPEN, it evaluates the
  RMS error returned.  If not too unusual, BASIC converts it into an error
  value (returned in the ERR variable) and signals the error by initiating
  an ON ERROR GOTO trap.  For unusual errors, BASIC selects ERR=162 meaning
  "?Cannot OPEN file" or blows up.  One of the most useful features of
  RSTSOPEN is that if the error returned is not a usual one (ERR equal 2,
  4, 5, 10), and if not suppressed by a /MESSAGE=NEVER qualifier, RSTSOPEN
  will display a detailed error analysis allowing the user of the program to
  quickly come to terms with the problem at hand--then continue execution
  through an ON ERROR GOTO trap.  A typical error display looks like this:

     %RSTSOPEN-F, FAB$L_STS=%X0001C134, FAB$L_STV=%X00000014 at $OPEN
     -RMS-F, ENQ system service request failed
     -SYSTEM-F, exceeded quota
     -RSTSOPEN-F, error on channel 1, for file A00128.DAT/RO

  Note that RSTSOPEN's error behavior can be modified by either supplying
  /MESSAGE=xxx or /ABORT=xxx qualifiers, or by changing the default values
  of these qualifiers before compiling the RSTSOPEN module.
2 Qualifiers
  RSTSOPEN understands the following qualifiers when appended to the file-
  name given in a BASIC OPEN statement using the USEROPEN clause and one
  of three RSTSOPEN references: RSO_OPENI (for OPEN FOR INPUTs and just
  plain OPENs), RSO_OPENO (for OPEN FOR OUTPUTs), and RSO_OPENX (for eval-
  uating these qualifiers without doing an actual OPEN).  In all cases
  below, qualifier delimiters may either be an equal sign "=" or a colon
  ":".  For numeric arguments (excluding /OWNER), the number may be positive
  or negative, octal (indicated by a preceding pound sign "#" before the
  number, but after the colon ":" or equal sign "=") or decimal (optionally
  followed by a decimal point ".").

  In addition, RSTSOPEN also attempts to evaluate <n>, <nn>, or <nnn> as a
  RSTS/E protection code if it appears at the end of a filename but before
  the qualifiers (if any).  If such a RSTS/E protection code is detected,
  RSTSOPEN returns the value found in RSO_GL_RSTS_PROTECTION_CODE.

/ABORT

 /ABORT=option                            default is NEVER

  Controls how the OPEN statements using RSTSOPEN should respond to an
  error.  Options are:
     NEVER    Never issue a fatal abort, always return control to the
              program whether or not an error of any kind is encountered.
              ON ERROR GOTO behavior is normal.
     UNUSUAL  If an unusual error (ERR not equal to 2, 4, 5, or 10) is
              encountered, RSTSOPEN will cause a fatal error and abort the
              program with traceback information if possible.  Note that
              this is never invoked if BASIC traps the error before calling
              the RSTSOPEN routine e.g., ERR=168 (?Illegal ALLOW clause).
     ALWAYS   If any error is encountered, RSTSOPEN will cause a fatal error
              and abort the program with traceback information if possible.
              As with UNUSUAL, if BASIC traps the error before calling the
              RSTSOPEN routine, RSTSOPEN will not abort the program.

/ACL_CONTEXT

 /ACL_CONTEXT=nn

  In extreme cases, there could be more ACE's in the ACL than the 512-
  byte ACL buffer RSO_GT_ACL can contain.  For those cases, you can
  use the ACL context number returned in RSO_GL_ACL_CONTEXT in sub-
  sequent OPENs to retrieve the rest of the ACL.  This context number
  tells RMS where it left off so that when supplied in the subsequent
  OPEN using /ACL_CONTEXT, RMS can return more of the ACE's.  When
  %SYSTEM-W-NOMOREACE error message is returned in RSO_GL_ACL_STS,
  you will know that all ACE's have been retrieved.

/BACKUP

 /BACKUP=date_time

  If supplied on OPEN FOR OUTPUT, the file created will have the BACKUP
  date corresponding to the date_time (absolute format only) given.  A
  valid example of date_time is "25-Feb-1985:15:33"--note the colon ":"
  used as a separator between date and time.  No spaces are allowed.

/BLOCK_SIZE

 /BLOCK_SIZE=nn                      default is BASIC's RECORDSIZE

  Number of bytes in a device record--called a block.  THIS IS NOT THE
  SAME AS BLOCKSIZE USED IN OPEN BY BASIC--but is related.  For disk,
  this is always 512.  For magtape, the values can range from 20 to
  65535 for ANSI tapes, 14 to 65532 for tapes MOUNTed /FOREIGN.  Through
  use of large /BLOCK_SIZE on magtapes, one can store many records per
  block thus making better utilization of magtape storage capacity
  (larger blocks mean fewer space-wasting inter-record gaps).  For
  terminals, this is the WIDTH setting; for mailboxes, this is the
  maximum message length.  Use of /BLOCK_SIZE will supersede the
  number-of-records-per-block given in BLOCKSIZE option of an OPEN
  statement.

/BUFFER_COUNT

 /BUFFER_COUNT=nn                    default is set by last SET RMS command

  When RSTSOPEN establishes the I/O stream (RMS $CONNECT service), this
  value is used to tell RMS how many I/O data buffers (subject to BYTLM
  quota) are are to remain in memory at one time.  This is the way that
  private data caching is accomplished.  Same as BUFFER option used in
  OPEN statement.

/CHAN_MODE

 /CHAN_MODE=mode                        default is EXECUTIVE mode

  Describes what process mode the channel assignment (see $ASSIGN system
  service) is made.  Valid values for mode are: USER, SUPERVISOR, or
  EXECUTIVE.

/CLUSTERSIZE

 /CLUSTERSIZE:nn                        (RSTS/E only)

  Evaluated only and returned in RSO_GL_RSTS_CLUSTERSIZE.

/CREATION

 /CREATION=date_time

  If supplied on OPEN FOR OUTPUT, the file created will have the CREATION
  date corresponding to the date_time (absolute format only) given.  A
  valid example of date_time is "25-Feb-1985:15:33"--note the colon ":"
  used as a separator between date and time.  No spaces are allowed.

/DID

 /DID=(nnn,nnn,nnn)

  Directory's file ID.  While RSTSOPEN evaluates it, it is always superseded
  by the $CREATE or $OPEN RMS services.  Only when using RSO_OPENX in the
  USEROPEN clause will the value given by the /DID qualifier be returned in
  RSO_GW_DID1 through RSO_GW_DID3.

/DVI

 /DVI=phydev

  RMS uses this value as the physical device name for the file being OPENed.
  Use of /DVI supersedes any device designation implied or supplied by a
  device name or logical name given in the filename itself.  Can be used in
  conjuction with the /FID qualifier.  A valid example of phydev is "_DUA0".

/EXTENT

 /EXTENT=nn   default set by last SET RMS command or default of disk mounted

  When given during file creation (OPEN FOR OUTPUT), /EXTENT will set the
  override default on the file itself thus superseding the above defaults.
  When given on OPEN of an existing file (OPEN FOR INPUT), /EXTENT will
  override all other EXTENT defaults being subject only to the VMS cluster-
  size of the disk, disk quotas, and available disk space.  An extent
  occurs whenever the disk space allocated for a file is insufficient to
  satisfy a write beyond current allocated size--in which case the new file
  allocation will be extended, at minimum, to the EXTENT size blocks.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /EXPIRATION qualifier, this /EXTENT qualifier will be
  assumed.

/EXPIRATION

 /EXPIRATION=date_time

  If supplied on OPEN FOR OUTPUT, the file created will have the EXPIRATION
  date corresponding to the date_time (absolute format only) given.  A
  valid example of date_time is "25-Feb-1985:15:33"--note the colon ":"
  used as a separator between date and time.  No spaces are allowed.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /EXTENT qualifier, the /EXTENT qualifier will be
  assumed--NOT /EXPIRATION.

/FAC

 /FAC=(option[,...])               default is whatever BASIC's OPEN sets up

  This is the File ACess byte that BASIC's ACCESS clause manipulates.  This
  qualifier adds to or subtracts from any of the values already established
  by BASIC.  The options are:
     ALL     Grant yourself all access operations
     BIO     Grant yourself only RMS block I/O operations
     BRO     Grant yourself RMS block I/O or RMS record I/O
     DEL     Grant yourself delete operations
     GET     Grant yourself GET or FIND operations
     NONE    Deny yourself all access operations
     PUT     Grant yourself PUT and EXTEND operations
     TRN     Grant yourself trancate operations
     UPD     Grant yourself UPDATE operations
  Note: All options (except NONE) may be negated by placing "NO" on the
  front of the option (e.g., NOBIO).  NONE cannot be abbreviated because
  RSTSOPEN internally treates it as NO-NE (there is no NE option).

  For more information on these options, consult VAX Record Management
  Services Reference Manual, section 5.13.

/FID

 /FID=(nnn,nnn,nnn)

  When supplied to RSTSOPEN, all directory searches are circumvented and
  a faster direct access to the INDEXF.SYS master index table is made.
  Since every file on VMS has a unique FID, this can be used to increase
  performance on file OPENing.  One side effect of using this option is
  that RMS cannot return the file's full name in RSO_GT_FILENAME.  Can be
  used in conjunction with the /DVI qualifier to make file OPENing even
  faster.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /FILESIZE and /FILE_MODE qualifiers, the /FILESIZE
  qualifier will be assumed--NOT /FILE_MODE or /FID.

/FILESIZE

 /FILESIZE:nn (same as /SIZE)

  When creating a file, RSTSOPEN will pre-extend a file to the size speci-
  fied by nn.  /FILESIZE is the same as the filesize qualifier found on
  RSTS/E.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /FILE_MODE and /FID qualifiers, this /FILESIZE
  qualifier will be assumed--NOT /FILE_MODE or /FID.

/FILE_MODE

 /FILE_MODE=mode

  Describes what process mode the filename will be created and/or OPENed
  in.  Currently not implemented by RMS.  Valid values for mode are: USER,
  SUPERVISOR, and EXECUTIVE.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /FILESIZE and /FID qualifiers, the /FILESIZE qualifier
  will be assumed--NOT /FILE_MODE or /FID.

/FOP

 /FOP=(option[,...])                default is whatever BASIC's OPEN sets up

  This is the File OPtion longword that BASIC uses to establish various
  options during each OPEN.  Such options as TEMPORARY, CONTIGUOUS, and
  UNLOCK EXPLICIT sets bits in this RMS field.  This qualifier adds to or
  subtracts from any of the values already established by BASIC.  The
  options are:
     ALL     Enable all options
     CBT     Contiguous best try
     CIF     Create if non-existent (OPEN without FOR INPUT/OUTPUT sets
             this bit)
     CTG     Contiguous
     DFW     Deferred write
     DLT     Delete file on CLOSE
     MXV     Maximize version number
     NAM     Use NAM block inputs
     NEF     No end-of-file positioning (magtape)
     NFS     Non-file-structured mode
     NONE    Disable all options
     OFP     Output file parse, use related filespec for default directory/-
             file_name/file_type--cannot be used under RSTSOPEN
     POS     Position magtape after next file before file creation
     RCK     Invoke read-read-and-compare to verify all read operations
     RWC     Rewind magtape when file is CLOSEd
     RWO     Rewind magtape prior to open or creation of a file
     SCF     Submit file to batch (SYS$BATCH) when CLOSEd
     SQO     Sequential I/O only--RMS will optimize I/O, even on DECnet
     SPL     Spool file to printer (SYS$PRINT) when CLOSEd
     SUP     Supersede existing file (/MODE:128 clears this bit)
     TEF     Truncate at end-of-file: deallocate unused blocks when CLOSEd
     TMD     Temporary file marked for deletion when CLOSEd, supersedes TMP
     TMP     Temporary file retained on CLOSE, but make no directory entry
     UFO     User file open only, (ORGANIZATION UNDEFINED sets this bit)
     WCK     Invoke read-after-write-compare to verify all write operations
  Note: All options (except NONE) may be negated by placing "NO" on the
  front of the option (e.g., NOSUP).  NONE cannot be abbreviated because
  RSTSOPEN internally treates it as NO-NE; thus you must specify all five
  characters of NONEF if you want to avoid confusing it with NONE.  Also,
  many of these options are superseded by those established in the /MODE
  qualifier.

  For more information on these options, consult VAX Record Management
  Services Reference Manual, section 5.16.

/GLOBAL_BUFFERS

 /GLOBAL_BUFFERS=nn

  The global buffer count of the file being OPENed.  Upon file creation,
  this qualifier makes the specifed value the default number of global
  buffers to use for the new file.  Upon OPENing of an existing file, this
  qualifier overrides the current default originally set on the file, or
  on any other defaults in effect at that time.  This number represents an
  upper limit to the number of I/O buffers that users throughout the
  system may share amoungst one another, and may not be fully granted due
  to limitations imposed by system parameters of GBLSECTIONS, GBLPAGES,
  GBLPAGFIL, RMS_GBLBUFQUO and currently available system resources.

/LNM_MODE

 /LNM_MODE=mode                         default is EXECUTIVE mode

  The maximum mode level at which logical name translation will be perfor-
  med.  Valid values for mode are USER, SUPERVISOR, and EXECUTIVE.

/MESSAGE

 /MESSAGE=option                        default is UNUSUAL

  Controls how the OPEN statements using RSTSOPEN should respond to an
  error.  The options are:
     NEVER    Never print a detailed error message of the error (if an error
              was detected by RSTSOPEN).
     UNUSUAL  If an unusual error (ERR not equal to 2, 4, 5, or 10) is
              encountered, RSTSOPEN will print a detailed error message of
              the error.  Note that this is never invoked if BASIC traps the
              error before calling the RSTSOPEN routine e.g., ERR=168
              (?Illegal ALLOW clause).
     ALWAYS   If any error is encountered, RSTSOPEN will always print a
              detailed error message.  As with UNUSUAL, if BASIC traps the
              error before calling the RSTSOPEN routine, RSTSOPEN will not
              print an error message.

/MODE

 /MODE:nnn                              (emulate RSTS/E mode qualifier)

  This RSTS/E qualifier is a WORD length bit map representing various
  options which describe the kind of OPEN desired.  For VMS, RSTSOPEN
  interprets some, but not all, of these values and sets the appropriate
  options to emulate the condition and returns the value given in
  RSO_GL_RSTS_MODE.  The mode value nnn is the sum of selected options
  described below:
     1        Update mode: make sure file organization is 512-byte fixed
              sequential (ORGANIZATION VIRTUAL), and neccessary share bits
              are set to permit read/write access by other users of the file
     2        Append mode: equivalent to /ROP=EOF
     1+4      Guarded update mode: treated as /MODE:1
     8        Keep UFD current: ignored by RSTSOPEN
     16       Contiguous: equivalent to /FOP=CTG
     32       Temporary: equivalent to /FOP=TMD
     64       Conditionally contiguous: equivalent to /FOP=CBT
     128      No supersede: equivalent to /FOP=NOSUP
     256      Enable data caching: ignored by RSTSOPEN
     512      Place file at end of directory: ignored by RSTSOPEN
     1024+512 Place file at head of directory: ignored by RSTSOPEN
     2048+256 Sequential data caching: ignored by RSTSOPEN
     4096     Read-regardless: equivalent to /ROP=RRL
     8192     Read-only (same as /RONLY): permit only GETs on file, allow
              other users full access to file, set RRL in ROP
     16384    Open UFD: ignored by RSTSOPEN

  Use of this qualifier can supersede other options selected by the /FOP,
  /ROP or /SHR qualifiers.

/MTACC

 /MTACC=nn                           default is 32 (ASCII <SPACE>)

  Magtape accessibility byte value.  Enables you to access HDR1 labels
  for ANSI labeled magtapes in compliance with ANSI standards.  The value
  is normally expressed as an ASCII code whose valid values include A-Z,
  0-9, <SPACE> ! % & ' ( ) * + , - . / : ; < = > ?.  If omitted, a space
  will be automatically specified in HDR1.

/MULTI_BLOCK

 /MULTI_BLOCK=nn                     default is set by last SET RMS command

  When RSTSOPEN establishes the I/O stream (RMS $CONNECT service), this
  value is used to tell RMS how many 512-byte blocks (subject to BYTLM
  quota) are are to remain in memory at one time.  This is one way to
  reduce I/O by reading and writing in larger and (hopefully) fewer block
  groups.

/NUMBER_OF_REVISIONS

 /NUMBER_OF_REVISIONS=nn

  For file creation only (or for RSO_CLOSE): establish nn as the number
  of times this file has been revised.  Same as /N_REVISIONS.

/N_REVISIONS

 /N_REVISIONS=nn

  For file creation only (or for RSO_CLOSE): establish nn as the number
  of times this file has been revised.  Same as /NUMBER_OF_REVISIONS.

/OWNER

 /OWNER=[nnn,nnn]
   -or-

 /OWNER=[identifier]

  For file creation only (or for RSO_CLOSE): establish [nnn,nnn] or
  [identifier] as the owner of the FILE.  Usually requires GRPPRV or
  SYSPRV privileges.

/POSITION

 /POSITION:nn                           (RSTS/E only)

  Evaluated only and returned in RSO_GL_RSTS_POSITION.

/PROTECTION

 /PROTECTION:nn                         (RSTS/E only)

 /PROTECTION=(class:itemlst[,...])      (VMS only)

  If a single number is detected, RSTSOPEN evaluates the argument as a
  RSTS/E protection code and does nothing with it other than place the
  value into RSO_GL_RSTS_PROTECTION_CODE.  On the other hand, if a
  VMS-style protection code is detected (e.g. (S:RW,O:RWED,G:R,W)), then
  RSTSOPEN establishes this protection code on the file if and only if
  the file is being created.  In the latter case, the value returned in
  RSO_GW_PROTECTION_CODE can also be used in the RSO_CLOSE call.

/REVISION

 /REVISION=date_time

  If supplied on OPEN FOR OUTPUT, the file created will have the REVISION
  date corresponding to the date_time (absolute format only) given.  A
  valid example of date_time is "25-Feb-1985:15:33"--note the colon ":"
  used as a separator between date and time.  No spaces are allowed.  Note
  that the value returned in RSO_GQ_REVISION_DATE can also be used in the
  RSO_CLOSE call.

/RONLY

 /RONLY

  Same as though setting the bit corresponding to 8192 in the /MODE quali-
  fier.  Net effect if to permit only GETs on the file, allow other users
  full access to the file, and setting of RRL (read-regardless) in ROP.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /ROP qualifier, this /RONLY qualifier will be
  assumed.

/ROP

 /ROP=(option[,...])                default is whatever BASIC's OPEN sets up

  This is the Record OPtion longword that BASIC uses to establish various
  options during each OPEN.  This qualifier adds to or subtracts from any of
  the values already established by BASIC.  The options are:
     ALL     Enable all options
     ASY     Asyncronous I/O
     BIO     Block I/O
     CCO     Cancel Control-O (terminal only)
     CVT     Convert lowercase to uppercase (terminal only)
     EOF     Position to end-of-file, set by /MODE:2 (append)
     ETO     Extended terminal operation: use XABTRM for extended terminal
             characteristics--cannot be used under RSTSOPEN
     FDL     Fast delete on index deletions
     KGE     Used by BASIC's GET or FIND on index keys greater-than-or-equal
             as in "GET #chan, KEY #key-num GE string-val"
     KGT     Used by BASIC's GET or FIND on index keys greater-than; as in
             "GET #chan, KEY #key-num GT string-val"
     LIM     Compare current index record, success if that record is greater
             than the key provided as a "limit" key
     LOA     Load index buckets according to fill size established at
             creation time
     NLK     Used in BASIC's GET to do read-with-no-record-locking; as in
             "GET #chan, KEY #key-num EQ string-val, ALLOW MODIFY"
     NXR     Allow processing of a nonexistent record, relative file only
     PMT     Use prompt buffer (terminals only)
     PTA     Purge type-ahead (terminals only)
     RAH     Read-ahead, start asyncronous reads to fill up multiple buffers
     REA     Used in BASIC's GET to do read-with-read-lock; as in
             "GET #chan, KEY #key-num EQ string-val, ALLOW READ"
     RLK     Used in BASIC's GET to do read-with-write-lock; as in
             "GET #chan, KEY #key-num EQ string-val, ALLOW NONE"
     RNE     Read no echo (terminal only)
     RNF     Read no filter (terminal only), CTRL/U, CTRL/R, and DEL are not
             special characters, pass them on as regular delimiters
     RRL     Used in BASIC's GET to do read-regardles-of-locks; as in
             "GET #chan, KEY #key-num EQ string-val, REGARDLESS"
     TMO     Timeout (terminal only), equivalent to using input after WAIT
     TPT     Truncate on put, used by BASIC for the SCRATCH command
     UIF     Update-if, convert PUT on existing record to UPDATE
     ULK     Manual unlocking, established by UNLOCK EXPLICIT in OPEN
     WAT     Wait; if requested record locked by another user, wait until
             that lock is released, then proceed to fetch it
     WBH     Write-behind; start asyncronous writes with multiple buffers
             for high speed output
  Note: All options (except NONE) may be negated by placing "NO" on the
  front of the option (e.g., NOSUP).  NONE cannot be abbreviated because
  RSTSOPEN internally treates it as NO-NE (there is no NE option).  Many
  of these options have no application for an OPEN statement because they
  are used by I/O statements such as GET, FIND, UPDATE,....  Also, some of
  these options are superseded by those established in the /MODE or /RONLY
  qualifiers.

  Note: If only two characters are given for this qualifier, thus being
  ambiguous with the /RONLY qualifier, the /RONLY qualifier will be
  assumed--NOT /ROP.

  For more information on these options, consult VAX Record Management
  Services Reference Manual, section 7.19.

/SHR

 /SHR=(option[,...])                default is whatever BASIC's OPEN sets up

  This is the share access byte that BASIC's ALLOW clause manipulates.  This
  qualifier adds to or subtracts from any of the values already established
  by BASIC.  The options are:
     ALL     Allow others all access operations
     BIO     Allow others only RMS block I/O operations
     BRO     Allow others RMS block I/O or RMS record I/O
     DEL     Allow others delete operations
     GET     Allow others GET or FIND operations
     NONE    Prohibit all other access operations
     PUT     Allow others PUT and EXTEND operations
     TRN     Allow others trancate operations
     UPD     Allow others UPDATE operations
  Note: All options (except NONE) may be negated by placing "NO" on the
  front of the option (e.g., NOBIO).  NONE cannot be abbreviated because
  RSTSOPEN internally treates it as NO-NE (there is no NE option).  Also,
  many of these options are superseded by those established in the /MODE
  or /RONLY qualifiers.

  For more information on these options, consult VAX Record Management
  Services Reference Manual, section 5.29.

/SIZE

 /SIZE:nn (same as /FILESIZE)

  When creating a file, RSTSOPEN will pre-extend a file to the size speci-
  fied by nn.  /SIZE is the same as the filesize qualifier found on RSTS/E.

/VERSION_LIMIT

 /VERSION_LIMIT=nnn           default is the version limit of the previous
                              version of the file being created; or that
                              of the directory that the file is being
                              created into if no previous version exists

  Establishes a maximum-number-of-versions limit on the file being created
  so that when the number of newer versions of this file exceeds this limit
  (because of a subsequent file creations), this file will automatically be
  deleted.  The version limit of the highest existing version of the file-
  to-be-created determines whether or not an older version of the file
  should first be deleted.

  ******* Currently, this option appears to have no effect.  If you *******
  ******* you can identify the problem and its solution, Victor at ********
  ******* at VLSystems would appreciate hearing about it. *****************

/WINDOWSIZE

 /WINDOWSIZE=nn

  The number of retrieval pointers (describing the blocks of storage for
  the file being OPENed) to maintain in memory at one time.  Valid values
  are from 0 to 127, and 255 (map as many retrieval pointers as you can).
