The ON...GOTO statement transfers program control to one of several lines or targets, depending on the value of a control expression.

Format

Syntax Rules

1. Int-exp determines which target BASIC selects as the GOTO argument. If int-exp equals 1, BASIC selects the first target. If int-exp equals 2, BASIC selects the second target, and so on.
2. Target must be a valid BASIC line number or a label and must exist in the current program unit.

Remarks

1. Control cannot be transferred into a statement block (such as FOR...NEXT, UNTIL...NEXT, WHILE...NEXT, DEF...END DEF, SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END HANDLER).
2. If there is an OTHERWISE clause, and if int-exp is less than one or greater than the number of targets in the list, BASIC transfers control to the target of the OTHERWISE clause.
3. If there is no OTHERWISE clause, and if int-exp is less than 1 or greater than the number of line numbers in the list, BASIC signals "ON statement out of range" (ERR=58).
4. If a target specifies a nonexecutable statement, BASIC transfers control to the first executable statement that lexically follows the target.
5. You can only use the ON...GOTO statement inside a handler if all the targets are contained within the handler.
6. You can specify the ON...GOTO statement inside a WHEN block if the ON...GOTO target is in the same protected region, an outer protected region, or in a nonprotected region.
7. You cannot specify an ON...GOTO statement inside a WHEN block if the ON...GOTO target already resides in another protected region that does not contain the most current protected region.

Example

ON INDEX% GOTO 700,800,900 OTHERWISE finish . . . finish: END PROGRAM

The OPEN statement opens a file for processing. It transfers user-specified file characteristics to OpenVMS Record Management Services (RMS) and verifies the results.

Format

Syntax Rules

1. File-spec1 specifies the file to be opened and associated with chnl-exp. It can be any valid string expression and must be a valid VMS file specification. BASIC passes these values to RMS without editing, alteration, or validity checks.
   BASIC does not supply any default file specifications, unless you include the DEFAULTNAME clause in the OPEN statement.
2. The FOR clause determines how BASIC opens a file.
   • If you open a file with FOR INPUT, the file must exist or BASIC signals an error.
   • If you open a file with FOR OUTPUT, BASIC creates the file if it does not exist. If the file does exist, BASIC creates a new version of the file.
   • If you do not use FOR INPUT or FOR OUTPUT to open an indexed file, you must specify a primary key in the event the file does not exist.
   • If you do not specify either FOR INPUT or FOR OUTPUT, BASIC tries to open an existing file. If there is no such file, BASIC creates one.
3. Chnl-exp is a numeric expression that specifies a channel number to be associated with the file being opened. It can be preceded by an optional number sign (#) and must be in the range of 1 to 119. Note that channels 100 to 119 are usually reserved for allocation by the RTL routines, LIB$GET_LUN and LIB$FREE_LUN.
4. A statement that accesses a file cannot execute until you open that file and associate it with a channel.

Remarks

1. The OPEN statement does not retrieve records.
2. Channel #0, the terminal, is always open. If you try to open channel zero, BASIC signals the error "Illegal I/O channel" (ERR=46).
3. If a program opens a file on a channel already associated with an open file, BASIC closes the previously opened file and opens the new one.
4. The ACCESS clause determines how the program can use the file.
   • ACCESS READ allows only FIND, GET, or other input statements on the file. The OPEN statement cannot create a file if the ACCESS READ clause is specified.
   • ACCESS WRITE allows only PUT, UPDATE, or other output statements on the file.
   • ACCESS MODIFY allows any I/O statement except SCRATCH on the file. ACCESS MODIFY is the default.
   • ACCESS SCRATCH allows any I/O statement valid for a sequential or terminal-format file.
   • ACCESS APPEND is the same as ACCESS WRITE for sequential files, except that BASIC positions the file pointer after the last record when it opens the file. You cannot use ACCESS APPEND on relative or indexed files.
   
   For an illustration of the interaction of ACCESS and ALLOW, see No. 5.
5. The ALLOW clause can be used in the OPEN statement to specify file sharing of relative, indexed, sequential, and virtual files.
   • ALLOW NONE lets no other users access the file. This is the default if any access other than READ is specified. Note that you must have write access to the file to specify ALLOW NONE.
   • ALLOW READ lets other users have read access to the file.
   • ALLOW WRITE lets other users have write access to the file.
   • ALLOW MODIFY lets other users have unlimited access to the file.
   
   The following scenario may help clarify the interaction of the ACCESS and ALLOW clauses: Suppose you specify ACCESS WRITE and ALLOW READ for a file. Your program then can access and write to the file, but other users (both new and preexisting) can only read the file. However, if another user has already opened the file for writing, an error is signaled. For further information, refer to the OpenVMS Record Management Services (RMS) documentation.
6. The BUFFER clause can be used with all file organizations except UNDEFINED.
   • For RELATIVE and INDEXED files, int-exp4 specifies the number of device or file buffers RMS uses for file processing.
   • For SEQUENTIAL files, int-exp4 specifies the size of the buffer; for example, BUFFER 8 for a SEQUENTIAL file sets the buffer size to eight 512-byte blocks.
   • It is recommended that you accept the system defaults or change the defaults with the DCL SET RMS_DEFAULT command.
7. The CONTIGUOUS clause causes RMS to try to create the file as a contiguous-best-try sequence of disk blocks. The CONTIGUOUS clause does not affect existing files or nondisk files.
   The CONTIGUOUS clause does not guarantee that the file will occupy contiguous disk space. If RMS can locate the file in a contiguous area, it will do so. However, if there is not enough free contiguous space for a file, RMS allocates the largest possible contiguous space and does not signal an error. See the OpenVMS Record Management Services Reference Manual for more information about contiguous disk allocation.
8. The DEFAULTNAME clause lets you supply a default file specification. If file-spec1 is not a complete file specification, file-spec2 in the DEFAULTNAME clause supplies the missing parts. For example:

   10 INPUT 'FILE NAME';fnam$ 20 OPEN fnam$ FOR INPUT AS FILE #1%, & DEFAULTNAME "USER$$DISK:.DAT"

   
   If you type "ABC" for the file name, BASIC tries to open
   USER$$DISK:[]ABC.DAT.

9. The EXTENDSIZE clause lets you specify the increment by which RMS extends a file after its initial allocation is filled. The value of int-exp5 is in 512-byte disk blocks. The EXTENDSIZE clause has no effect on an existing file.
10. The FILESIZE clause lets you pre-extend a new file to a specified size.
    • The value of int-exp2 is the initial allocation of disk blocks.
    • The FILESIZE clause has no effect on an existing file.
11. The MAP clause specifies that a previously declared map is associated with the file's record buffer. The MAP clause determines the record buffer's address and length unless overridden by the RECORDSIZE clause.
    • The size of the specified map must be as large or larger than the longest record length or maximum record size. For files with a fixed record size, the specified map must match exactly.
    • The size of the largest MAP with the same map name in the current program unit becomes the file's record size if the OPEN statement does not include a RECORDSIZE clause.
    • It is recommended that you do not use both the MAP and RECORDSIZE clauses in an OPEN statement. However, if you do use both the MAP and RECORDSIZE clauses in an OPEN statement, the following rules apply:
      • The RECORDSIZE clause overrides the record size set by the MAP clause.
      • The map must be as large or larger than the specified RECORDSIZE.
    • If there is no MAP clause, the record buffer space that BASIC allocates is not directly accessible; therefore, MOVE statements are needed to access data in the record buffer.
    • You must have a MAP clause when creating an indexed file; you cannot use KEY clauses without MAP statements because keys serve as offsets into the buffer.
    • The size of the specified map cannot exceed 32,767 bytes.
12. The ORGANIZATION clause specifies the file organization. When present, it must precede all other clauses. When you specify an ORGANIZATION clause, you must also specify one of the following organization options: VIRTUAL, UNDEFINED, INDEXED, SEQUENTIAL or RELATIVE. Specify ORGANIZATION UNDEFINED if you do not know the actual organization of the file. If you do not specify an ORGANIZATION clause, BASIC opens a terminal format file by default.
    • When you specify ORGANIZATION VIRTUAL, you create a sequentially fixed file with a record size of 512 (or a multiple of 512). You can then access the file with the FIND, GET, PUT, or UPDATE statements or through one or more virtual arrays. BASIC allows you to overwrite existing records in a file not containing virtual arrays and opened as ORGANIZATION VIRTUAL by using the PUT statement with a RECORD clause. All other organizations require the UPDATE statement to change an existing record. It is recommended that you also use the UPDATE statement to change existing records in VIRTUAL files that do not contain virtual arrays.
    • When you do not know the organization of a file, you can open a file for input and specify ORGANIZATION UNDEFINED. You can then use the FSP$ function or a USEROPEN routine to determine the attributes of the file. You will usually want to specify the RECORDTYPE ANY clause with the ORGANIZATION UNDEFINED clause. The combination of these two clauses should allow you to access any file sequentially.
    • When you specify ORGANIZATION INDEXED, you create an indexed file whose data records are sorted in ascending or descending order according to a primary index key value.
      • Use a PRIMARY KEY clause in the OPEN statement.
      • The index keys you specify determine the order in which records are stored.
      • Index keys must be variables declared in a MAP statement associated with the OPEN statement for the file.
      • BASIC allows you to specify an indexed file as either variable or fixed length.
    • When you specify ORGANIZATION SEQUENTIAL, you create a file that stores records in the order that they are written.
      • Sequential files can contain records of any valid BASIC record format: fixed-length, variable-length, or stream.
      • If you open an existing file using stream as a record format option, the file must be one of the following stream record formats defined by RMS:
        • STREAM records can be delimited by any special character.
        • STREAM_LF must be delimited by a line-feed character.
        • STREAM_CR must be delimited by a carriage return.
        
        If the file is not one of these stream formats, BASIC signals the error "RECATTNOT, record attributes not matched."
    • When you specify ORGANIZATION RELATIVE, you create a file that contains a series of records that are numbered consecutively. BASIC allows you to specify either fixed-length or variable-length records.
    • If you omit the ORGANIZATION clause entirely, a terminal-format file is opened.
      • Terminal-format files are implemented as RMS sequential variable files and store ASCII characters in variable-length records.
      • Carriage control is performed by the operating system; the record does not contain carriage returns or line feeds.
      • You use essentially the same syntax to access terminal-format files as when reading from or writing to the terminal (INPUT and PRINT).
13. The RECORDSIZE clause specifies the file's record size. Note that there are restrictions on the maximum record size allowed for various file and record formats. See the OpenVMS Record Management Services Reference Manual for more information.
    • For fixed-length records, int-exp1 specifies the size of all records.
    • For variable-length records, int-exp1 specifies the size of the largest record.
    • It is recommended that you do not use both the MAP and RECORDSIZE clauses in an OPEN statement. However, if you do use both the MAP and RECORDSIZE clauses in an OPEN statement, the following rules apply:
      • The RECORDSIZE clause overrides the record size set by the MAP clause.
      • The map must be as large or larger than the specified RECORDSIZE.
    • If you specify a MAP clause but no RECORDSIZE clause, the record size is equal to the map size.
    • If there is no MAP clause, the RECORDSIZE clause determines the record size.
    • When creating a relative or indexed file, you must specify either a MAP or RECORDSIZE clause; otherwise, BASIC signals an error.
    • For fixed files, the record size must match exactly.
    • If you do not specify a RECORDSIZE clause when opening an existing file, BASIC retrieves the record size value from the file.
    • When you print to a terminal-format file, you must supply a record size if the margin is to exceed 72 characters. For example, if you want to print a 132-character line, specify RECORDSIZE 132 or use the MARGIN and NOMARGIN statements.
    • When creating SEQUENTIAL files, BASIC supplies a default record size of 132.
    • The record size is always 512 for VIRTUAL files, unless you specify a RECORDSIZE.
14. The RECORDTYPE clause specifies the file's record attributes.
    • LIST specifies implied carriage control, <CR>. This is the default for all file organizations except VIRTUAL.
    • FORTRAN specifies a control character in the record's first byte.
    • NONE specifies no attributes. This is the default for VIRTUAL files.
      If you open a terminal-format file with RECORDTYPE NONE, you must explicitly insert carriage control characters into the records your program writes to the file.
    • ANY specifies a match with any file attributes when opening an existing file. If you create a new file, ANY is treated as LIST for all organizations except VIRTUAL. For VIRTUAL, it is treated as None.
15. The TEMPORARY clause causes BASIC to delete the output file as soon as the program closes it.
16. The UNLOCK EXPLICIT clause allows you to retain locks on records until they are explicitly unlocked.
    • The type of lock you impose on a record with a GET or FIND statement remains in effect until you explicitly unlock the record or file with a FREE or UNLOCK statement or until you close the file.
    • If you specify UNLOCK EXPLICIT, and do not specify an ALLOW clause with a GET or FIND statement, BASIC imposes the ALLOW NONE lock by default and the next GET or FIND operation does not unlock the previously locked record.
    • You must open a file with UNLOCK EXPLICIT before you can explicitly lock records with the ALLOW clause on GET and FIND statements. See the sections on GET and FIND and the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about explicit record locking and unlocking.
17. The USEROPEN clause lets you open a file with your own FUNCTION subprogram.
    • Func-name must be a separately compiled FUNCTION subprogram and must conform to FUNCTION statement rules for naming subprograms.
    • You do not need to declare the USEROPEN routine as an external function.
    • BASIC calls the user program after it fills the FAB (File Access Block), the RAB (Record Access Block), and the XABs (Extended Attribute Blocks). The subprogram must issue the appropriate RMS calls, including $OPEN and $CONNECT, and return the RMS status as the value of the function. See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about the USEROPEN routine.

    Note Future releases of the OpenVMS Run-Time Library may alter the use of some RMS fields. Therefore, you may have to alter your USEROPEN procedures accordingly.

18. The WINDOWSIZE clause followed by int-exp3 lets you specify the number of block retrieval pointers you want to maintain in memory for the file.
    Retrieval pointers are associated with the file header and point to contiguous blocks on disk.
    • By keeping retrieval pointers in memory you can reduce the I/O associated with locating a record, as the operating system does not have to access the file header for pointers as frequently.
    • The number of retrieval pointers in memory at any one time is determined by the system default or by the WINDOWSIZE clause.
    • The default number of retrieval pointers on OpenVMS systems is 7.
    • A value of zero specifies the default number of retrieval pointers. A value of -1 means to map the entire file, if possible. Values from -128 to -2 are reserved.
19. The BLOCKSIZE clause specifies the physical block size of magnetic tape files. The BLOCKSIZE clause can be used for magnetic tape files only.
    • The value of int-exp8 is the number of records in a block. Therefore, the block size in bytes is the product of the RECORDSIZE and the BLOCKSIZE value.
    • The default blocksize is one record.
20. The NOREWIND clause controls tape positioning on magnetic tape files. The NOREWIND clause can be used for magnetic tape files only.
    • If you specify NOREWIND, the OPEN statement does not position the tape at the beginning. Your program can search for records from the current position.
    • If you do not specify either ACCESS APPEND or NOREWIND, the OPEN statement positions the tape at its beginning and then searches for the file.
21. The NOSPAN clause specifies that sequential records cannot cross block boundaries.
    • SPAN specifies that records can cross block boundaries. SPAN is the default.
    • The NOSPAN clause does not affect nondisk files.
22. The BUCKETSIZE clause applies only to relative and indexed files. It specifies the size of an RMS bucket in terms of the number of records one bucket should hold.
    • The value of int-exp9 is the number of records in a bucket.
    • The default is one record.
23. The CONNECT clause permits multiple record streams to be connected to the file.
    • The CONNECT clause must specify an INDEXED file already opened on chnl-exp2 with the primary OPEN statement.
    • You cannot connect to a connected channel; you can connect only to the initially opened channel.
    • You can connect more than one stream to an open channel.
    • All clauses of the two files to be connected must be identical except MAP, CONNECT, and USEROPEN.
    • Do not use the CONNECT clause when accessing files over DECnet or BASIC will signal the error "Cannot open file" (ERR=162).
24. The PRIMARY KEY clause lets you specify an indexed file's key. You must specify a primary key when opening an indexed file. The ALTERNATE KEY clause lets you specify up to 254 alternate keys. The ALTERNATE KEY clause is optional.
    • RMS creates one index list for each primary and alternate key you specify. These indexes are part of the file and contain pointers to the records. Each key you specify corresponds to a sorted list of record pointers.
    • You can specify each key as ASCENDING or DESCENDING; ASCENDING is the default. In an ASCENDING key, lower key values occur toward the beginning of the index. In a DESCENDING key, higher key values occur toward the beginning of the index.
    • The keys you specify determine the order in which records in the file are stored. All keys must be variables declared in the file's corresponding MAP statement. The position of the key in the MAP statement determines its position in the record. The data type and size of the key are as declared in the MAP statement.
    • A key can be an unsubscripted string, a WORD, LONG, QUAD, or packed decimal variable, or a record or group that is exactly eight bytes long.
    • You can also create a segmented index key for string keys by separating the string variable names with commas and enclosing them in parentheses. You can then reference a segment of the specified key by referencing one of the string variables instead of the entire key. A string key can have up to eight segments.
    • The order of appearance of keys determines key numbers. The primary key, which must appear first, is key #0. The first alternate key is #1, and so on.
    • DUPLICATES in the PRIMARY and ALTERNATE key clauses specifies that two or more records can have the same key value. If you do not specify DUPLICATES, the key value must be unique in all records.
    • CHANGES in the ALTERNATE KEY clause specifies that you can change the value of an alternate key when updating records. If you do not specify CHANGES when creating the file, you cannot change the value of a key. You cannot specify CHANGES with the PRIMARY KEY clause.
    • KEY clauses are optional for existing files. If you do specify a key, it must match a key in the file.

Examples

Example 1

OPEN "FILE.DAT" AS FILE #4

Example 2

OPEN "INPUT.DAT" FOR INPUT AS FILE #4, & ORGANIZATION SEQUENTIAL FIXED, & RECORDSIZE 200, & MAP ABC, & ALLOW MODIFY, ACCESS MODIFY OPEN Newfile$ FOR OUTPUT AS FILE #3, & INDEXED VARIABLE, & MAP Emp_name, & DEFAULTNAME "USER$$DISK:.DAT", & PRIMARY KEY Last$ DUPLICATES, & ALTERNATE KEY First$ CHANGES MAP (SEGKEY) STRING last_name = 15, & MI = 1, first_name = 15 OPEN "NAMES.IND" FOR OUTPUT AS FILE #1, & ORGANIZATION INDEXED, & PRIMARY KEY (last_name, first_name, MI), & MAP SEGKEY