File handling in SCL

A number of procedures now exist to enable file manipulation within SCL. These allow files to be opened, closed, read and written. There is also a facility to write a number of STRING variables to a file, which saves specifically opening and closing the file.

OPEN_FILE (OPF)

This command opens a file for record-level access. It returns a channel that can be used to read or write records and perform other actions on the file using the commands described in the text cross-reference.

The file may have been previously assigned by the caller. Pre-selective Access Method may be used provided the local-name used for pre-selection is supplied to this command.

OPEN_FILE (
@ literal @ NAME = @ mandatory @,
@ ref int @ CHANNEL= @ mandatory @,
@ literal @ ACCESS = "R",
@ superliteral @ OPTIONS = "",
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
NAME Identifies the file to be opened. It is assigned by this command. If the caller has previously assigned the file or the file has been given a local name as a parameter, NAME may take the form *localname. In this case ACCESS must be allowed by the assignment. The use of *localname is mandatory if the caller wishes to use Pre-selective Access Method or non-default sharing with other jobs. The default sharing is that read can share with other read accesses but other forms of access are exclusive.

= filename

The parameter is mandatory
CHANNEL Specifies an integer to contain a channel identifier for subsequent operations on the file

= channel-variable

The parameter is mandatory
ACCESS Specifies a particular form of access to the file

= R or READ
The file is to be read but not changed. The file is initially aligned at the beginning-of-file

= W or WRITE
The file may be both read and changed. The file is initially aligned at beginning-of-file

= A or APPEND
As for W, but the file is initially aligned at end-of-file

= O or OVERWRITE
As for W, but any records are destroyed by a successful open

= U or UPDATE
As for W, but all changes must be updates of existing records

R
OPTIONS Each element of the OPTIONS parameter is of the form:

keyword or keyword/value

At least three characters of a keyword must be supplied

= keyword FIXED_RECORD_AREAS
There is no value field. If the option is supplied the READ commands will not adjust the length of the RECORD_AREA job space variables. See READ_RECORD command (RECORD_AREA)

= keyword WAIT
Value is an unsigned integer followed by a time unit, e.g. WAIT/5SECS. The only time units allowed are:

  • MSECS (microseconds)
  • SECS or SEC (seconds)
  • MINS or MIN (minutes)

= keyword MODE
This value should be used under the guidance of ICL only

No options

READ_RECORD (RDR)

This command reads the next record from a file previously opened by OPEN_FILE. After a successful read the file is left positioned ready to read the following record.

READ_RECORD (
@ int @ CHANNEL = @ mandatory @,
@ ref string @ RECORD_AREA = @ mandatory @,
@ ref int @ R_LENGTH = NIL,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel returned from a previous call of OPEN_FILE. After a successful read the file is left positioned ready to read the following record.

= channel-identifier

The parameter is mandatory
RECORD_AREA Specifies an SCL string variable or superstring element to receive the record. The string will be adjusted in length so that it exactly contains the record read, unless:

OPTIONS=FIXED_RECORDS_AREAS was specified on OPEN_FILE. The string will be declared if it does not exist.

If OPTIONS=FIXED_RECORD_AREAS was specified on OPEN_FILE, the record is returned left-justified and space filled in RECORD_AREA

= string-variable or superstring

The parameter is mandatory
R_LENGTH If supplied, this parameter is set to the length of the record read prior to any space filling. If the record is longer than RECORD_AREA, the value of R_LENGTH is undefined NIL

READ_RECORD_BY_KEY (RDRK)

This command reads a record by finding its key in an ordered serial, indexed sequential or hashed random file. The key must be supplied.

The record may be anywhere in an indexed sequential or hashed random file.

The record must be after the current position in an ordered serial file.

READ_RECORD_BY_KEY (
@ int @ CHANNEL = @ mandatory @,
@ ref string @ RECORD_AREA = @ mandatory @,
@ ref int @ R_LENGTH = NIL,
@ string @ KEY = ,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD_AREA Specifies an SCL string variable or superstring element to receive the record. The string will be adjusted in length so that it exactly contains the record read, unless:

OPTIONS=FIXED_RECORDS_AREAS was specified on OPEN_FILE. The string will be declared if it does not exist.

If OPTIONS=FIXED_RECORD_AREAS was specified on OPEN_FILE, the record is returned left-justified and space filled in RECORD_AREA

= string-variable or superstring

The parameter is mandatory
R_LENGTH If supplied, this parameter is set to the length of the record read prior to any space filling. If the record is longer than RECORD_AREA, the value of R_LENGTH is undefined NIL

READ_RECORD_BY_MATCH (RDRM)

This command reads the next record in the file that contains a supplied string.

READ_RECORD_BY_MATCH (
@ int @ CHANNEL = @ mandatory @,
@ ref string @ RECORD_AREA = @ mandatory @,
@ ref int @ R_LENGTH = NIL,
@ string @ MATCH_WITH = ,
@ int @ POSITION = 0,
@ literal @ ALGORITHM = "",
@ ref int @ RETURNED_R_NUMBER = NIL,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD_AREA Specifies an SCL string variable or superstring element to receive the record. The string will be adjusted in length so that it exactly contains the record read, unless:

OPTIONS=FIXED_RECORDS_AREAS was specified on OPEN_FILE. The string will be declared if it does not exist.

If OPTIONS=FIXED_RECORD_AREAS was specified on OPEN_FILE, the record is returned left-justified and space filled in RECORD_AREA.

= string-variable or superstring

The parameter is mandatory
R_LENGTH If supplied, this parameter is set to the length of the record read prior to any space filling. If the record is longer than RECORD_AREA, the value of R_LENGTH is undefined NIL
MATCH_WITH Specifies the characters to be matched in the record The parameter is mandatory
POSITION The position in the record at which the matching string is to be found. 1 = first byte of the record.

If a record is too short to contain POSITION, or a match starting at POSITION, it is treated as not matching and the next record is examined.

The match may occur anywhere in the record
ALGORITHM Not used
RETURNED_R_NUMBER May supply an integer into which the command returns the number of the record to be read by this call. -1 is returned if the record is not known.

Record number is never available for indexed sequential and hashed random files. Record numbers become unknown after access by key to ordered serial files and after a WRITE_RECORD or REPOSITION_FILE to end-of-file on any serial file.

= integer

The record number is not returned

READ_RECORD_BY_NUMBER (RDRN)

This command allows a random access method of reading records in a serial or relative file, and backwards processing of a serial file. Access to a serial file is achieved by a series of single record skips. The position may be specified either absolutely by record wihin file or relatively by a displacement from the last record read or updated.

READ_RECORD_BY_NUMBER (
@ int @ CHANNEL = @ mandatory @,
@ ref string @ RECORD_AREA = @ mandatory @,
@ ref int @ R_LENGTH = NIL,
@ int @ R_NUMBER = -1,
@ int @ RELATIVE_R_NUMBER = 0,
@ ref int @ RETURNED_R_NUMBER = NIL,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD_AREA Specifies an SCL string variable or superstring element to receive the record. The string will be adjusted in length so that it exactly contains the record read, unless:

OPTIONS=FIXED_RECORDS_AREAS was specified on OPEN_FILE. The string will be declared if it does not exist.

If OPTIONS=FIXED_RECORD_AREAS was specified on OPEN_FILE, the record is returned left-justified and space filled in RECORD_AREA.

= string-variable or superstring

The parameter is mandatory
R_LENGTH If supplied, this parameter is set to the length of the record read prior to any space filling. If the record is longer than RECORD_AREA, the value of R_LENGTH is undefined. NIL
R_NUMBER This parameter gives the number within the file of the record to be read. For direct and serial files the first record is number 1, the second is number 2 and so on. For relative files the number of a record is its key and consecutive records do not always have consecutive keys. Note that for serial files, except direct serial, access to the record will be by serial reading through the file.

= integer

The record to be read is specified by RELATIVE_R_NUMBER relative to the the latest record read
RELATIVE_R_NUMBER This parameter identifies the record to be read by its position relative to the current position in the file

= 1
Read the next record. If at BOF read the first record.

= 0
Re-read the last record read.

= -1
Read the previous record (used for reading backwards). If at EOF read the last record in the file.

= +n, -n
Read the nth record following or preceding the last record read.

A negative value may be supplied only for a serial file. If R_NUMBER is supplied, this parameter must be defaulted.

0. Note that if R_NUMBER is supplied this value must be 0 or 1
RETURNED_R_NUMBER This parameter supplies an integer into which the command returns the number of the record read by this call. -1 is returned if the record number is not known. The record number is never available for indexed sequential and hashed random files. The record number becomes unknown after access by key to ordered serial files and after a WRITE_RECORD or REPOSITION_FILE to end-of-file on any serial file.

= integer

The record number is not returned

UPDATE_RECORD (UPR)

This command allows an existing record in a file to be overwritten. For serial files the length of the record may not be changed.

This command is only available for disc files with unspanned records. The command is used following a read command. The supplied RECORD replaces the last record read.

UPDATE_RECORD (
@ int @ CHANNEL = @ mandatory @,
@ string @ RECORD = @ mandatory @,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD Specifies the new contents of the record. For indexed sequential and hashed random files the key must appear at its correct position in the record and must be the same as the key of the record being written.

= string

The parameter is mandatory

WRITE_RECORD (WRR)

This command writes a new record to a file. In the case of serial files the file must already be positioned at EOF, or at BOF if the file is empty, and is left positioned ready to write another new record. In the case of indexed sequential or hashed random files the key is taken from the supplied record and the record is added to the file at the position appropriate to its key.

When an indexed sequential file is first written-to, the new records must be written in ascending order of key to avoid long overflow chains. All records written to an ordered serial file must be written in ascending order of key to allow subsequent keyed reading, but this is not enforced.

To prevent accidental corruption of an existing record, this command will not update a record that is already in use; use UPDATE_RECORD to change an existing record.

WRITE_RECORD (
@ int @ CHANNEL = @ mandatory @,
@ string @ RECORD = @ mandatory @,
@ response @ RESPONSE = RESULT )

= string

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD Specifies the record to be written to the file.

Supplying "" will write a zero-length record to the file, providing that zero-length records are allowed.

For ordered serial, indexed sequential and hashed random files, the key must appear at its correct position in the record.

 The parameter is mandatory

WRITE_RECORD_BY_NUMBER (WRRN)

WRITE_RECORD_BY_NUMBER writes a new record to a relative (relativev) file. The record is inserted into the file at the position given by R_NUMBER.

WRITE_RECORD_BY_NUMBER (
@ int @ CHANNEL = @ mandatory @,
@ string @ RECORD = @ mandatory @,
@ int @ R_NUMBER = @ mandatory @,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory
RECORD Specifies the record to be writen to the file.

Supplying "" will write a zero-length record to the file.

 The parameter is mandatory
R_NUMBER Specifies the key of a record

= record-key

The parameter is mandatory

CLOSE_FILE (CLOF)

This command closes a file opened by OPEN_FILE. The command always succeeds provided that a valid channel is supplied, but its response parameter indicates the state of the file rather than a result of CLOSE.

Note: The synonym is CLOF not CLF. CLF is the short form for CANCEL_LISTFILE.

CLOSE_FILE (
@ int @ CHANNEL = @ mandatory @,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
CHANNEL Specifies the channel identifier specified in a previous call of OPEN_FILE

= channel-variable

The parameter is mandatory

READ_FILE (RDF)

This command reads the records from a requested file and returns them as a superstring, RECORDS. Each record is from the file occupies a separate superstring element of RECORDS. The records are read sequentially from the start of the file and returned in this order.

READ_FILE (
@ literal @ NAME = @ mandatory @,
@ superstring @ RECORDS = @ mandatory @,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
NAME Identifies the file to be read.

= filename

The parameter is mandatory.
RECORDS Specifies a row of records to be read from the file specified in NAME. If the read fails, a null superstring value is returned. The parameter is mandatory

WRITE_FILE (WRF)

This command copies a superstring to a file. Each element of the superstring supplies one record. The command is normally used with an empty file. If there are already records in the file the command appends the supplied records.

WRITE_FILE (
@ literal @ NAME = @ mandatory @,
@ superstring @ RECORDS = @ mandatory @,
@ response @ RESPONSE = RESULT )

Keyword Meaning Default
NAME Identifies the file to be written to. It is assigned by this command. If the caller has previously assigned the file or has been given a local name as a parameter, NAME may take the form *localname. In this case the assignment must allow write access.

= filename

The parameter is mandatory.
RECORDS Specifies the records to be written to the file, each record being separated by ampersands

=record-name&record-name&.... etc

The parameter is mandatory