Write

The Write (WR) statement may be used to add or insert a record into an existing linked list or external or internal file.

Comments and Examples

Before Write can be used, an internal or external file must already be opened and assigned a file number. WRITE can be used with files opened, as OUTPUT or OUTIN, but not INPUT. In the following example, the file TRANSFER is opened as #5, then a new record is added in line 3950:

03940 OPEN #5: "NAME=TRANSFER", INTERNAL, OUTPUT
03950 WRITE #5,USING 3960: COMPANY$, AMT
03960 FORM C 10, N 7.2

WRITE may be used with internal files that are accessed SEQUENTIAL, RELATIVE or KEYED. Similarly, WRITE may be used with external files that are accessed SEQUENTIAL or RELATIVE.

Syntax

WRITE #<file number> [, USING {<string expression>|<line ref>}] {[, REC=<numeric expression>]|[, POS=<numeric expression>]} [, {RESERVE|RELEASE}] : [{Mat <array name>|}][,...]  [<error condition> <line ref>][,...]

Defaults

1.) Unformatted.

2.) Add to the end of the file.

3.) Release all previous record locks; write and unlock current record.

4.) Interrupt the program if an error occurs and "ON error" is not active.

Parameters

"File-num" is an integer or numeric expression that matches the WRITE statement with a file of the same number that is already identified in an OPEN statement. The "USING" keyword is part of a clause that specifies either the "line-ref" of a FORM statement or a "string-expr" containing a FORM statement. This parameter formats the output.

The "POS = num-expr" clause is only used with external files opened for RELATIVE processing; its purpose is to position to a specified byte before writing. After the numeric expression is evaluated and rounded to an integer, the system attempts to write a complete record beginning at the specified byte number. The only valid value for POS is the first byte after the end of the file.

The optional "REC = num-expr" clause is used with internal or external files opened for RELATIVE processing; its purpose is to position to a specified record number before writing. After the numeric expression is evaluated and rounded to an integer, the system tries to write that record number.

"RESERVE" and "RELEASE" specify record locking rules for multi-user environments. "RESERVE" instructs the system to hold all previous record locks and lock the current record. "RELEASE" releases all previously locked records then releases the current record as soon as the WRITE is complete.

The "MAT array-name" and "data-item" parameters represent a list of items to be written to the new record. If more than one is specified, they must be separated by commas.

WRITE allows error processing with the optional "error-cond line-ref" parameter. See Error Conditions for more information.

Linked Lists

The Write (WR) statement may be used to add or insert a record into an existing linked list or external or internal file. (A linked list is not considered to be "existing" unless an anchor point has been established for it with a RESTORE statement.)

For example, the RESTORE statement in the following code fragment establishes a new anchor point for a new linked list. The WRITE statement is then used to write the anchor record.

01000 RESTORE #1:
02000 WRITE #1, USING "FORM X 8,C 18":"NEW LINKED LIST"

Keep in mind that the first eight bytes of a linked record are always reserved for the next and previous record pointers. Business Rules will not produce an error if a program attempts to write to these positions. This is a potential danger in that your program could potentially overwrite this crucial information. However, it is also an advantage in that you are allowed to write to these fields and potentially modify, combine or correct existing lists.

With linked files, it is possible to insert a new record between two existing records in the file. However, it is important to note that the new record will still use a record number that is assigned sequentially based on all records in the file. Consider, for example, a linked list file that has had 1000 records written to it. If a program were to insert a new record between existing records with record numbers of 9 and 10 respectively, the new record would still be assigned a record number of 1001. The resulting order of these records would therefore be 9, 1001, 10. This is the reason that it is important to make sure that the record number of a linked list's anchor record always be updated to the master file.

TO INSERT A RECORD INTO THE LINKED LIST, It is necessary to first position the file pointer to the desired insertion point. Typically, a program would issue a RESTORE REC=(anchor) statement to get to the anchor point of the desired list, then read sequentially to get to the desired insertion point. However, using RESTORE REC= to position into the middle of a chain is permissible. Such an insertion will occur ahead of the record pointed at by the restore operation. At the end of each read or write operation the "write" file position is advanced to just beyond the last record processed.

A RESTORE REC=(anchor) followed directly by a WRITE statement will insert a new record at the beginning of the linked list. Thus the old anchor record will become a linked record and the newly inserted record will become the new anchor record. Also, KREC will be updated to return the record number of the new anchor record (see the KREC function description).

Business Rules! will automatically update the next and previous record pointers (held in the first eight bytes of each linked record) of the affected records when a linked list record is added

Technical Considerations

1.) Relevant error conditions are: CONV, DUPREC, EOF (disk full), ERROR, EXIT, IOERR, LOCKED, NOREC, and SOFLOW.

2.) If a string-expr is used with a USING clause, it must begin with "FORM ". This technique executes relatively slowly because the string is compiled on each execution of the WRITE statement.

3.) Omitting the USING clause allows unformatted file processing. See File I/O for more information.

4.) Record positions that are not written to are blanks.

5.) With an internal file, WRITE statements can only write to existing records that have been marked for deletion. The location following the last record in the file is considered a deleted record. Thus, with RELATIVE processing of internal files, WRITE statements usually refer to writing to the end of the file -either implicitly (without a REC= clause) or explicitly (with a REC= clause). However, especially on multi-user systems, programmers should avoid adding records to the end of a file with a WRITE statement with a REC= clause; it is better to let the system determine the current last record by omitting the REC= clause. The reason for this is that the specified record (frequently calculated as LREC+1) could be written to by another user between its computation and the actual WRITE. See the Multi-user Programming section for additional information.

6.) With RELATIVE processing of internal or external files, the DUPREC error condition can be used to trap errors when a record already exists (and is not deleted) for the relative record number that the program is trying to write.

7.) With RELATIVE processing of internal or external files, the NOREC error condition can be used to trap errors when the record does not exist. On a WRITE, this means it is past the end of the file (rather than the last record plus one).

8.) When using the POS= clause with external files opened for RELATIVE processing, the only valid value for POS is the first byte after the end of the file. Thus, WRITE can only add new records at the end of the file.

9.) WRITE cannot have a KEY clause.

10.) When using KEYED processing, records output with a WRITE statement are located at the end of the master file.

11.) With KEYED processing, the index files specified in the OPEN statement are updated as part of the WRITE. Thus, the record is immediately available for a READ with a KEY clause on the same file-num. Similarly, if multiple index files are being used simultaneously; other index files are also updated immediately. For more information about multiple index files, see the Index Facility chapter.

12.) WRITE REC= to a keyed file is permissible and causes both the data record and keys to be added.

13.) There is no automatic system error checking to assure that duplicate keys are not created when a record is written. If duplicate keys are not desired, you should precede each WRITE with a READ using a KEY= clause; only if the READ generates a NOKEY should you execute the WRITE. Since many application programs already include a check for duplicate record keys, this feature allows programmers to save considerable system overhead. It also allows duplicate keys if an application uses them.

14.) When OPTION INVP is in effect, the normal output of commas and periods is interchanged in PIC, N, NZ, G and GZ format specifications to produce European-style numbers. See the OPTION statement for details