add considerations for file I/O

In the context of file I/O that does not involve databases, the EGL add statement places a record in a file.

The precise behavior of the command, and the location where the new record is placed, depend on the stereotype of the record you use with the command. For more information, see the individual sections in this topic.

Syntax

Syntax diagram for the add statement using file I/O
recordVariable
Variable that contains the record data to add to an indexed, relative, or serial file.

CSV record

When you add a record with the CSVRecord stereotype, the record is placed at the end of the file.

If the current record is the first written to the file, EGL checks the labels property for the record. If the property is not null, EGL writes the headers for the columns, separated by the character in the delimiter property.

For each data line, EGL uses the existing conversion rules to convert the values to strings. The one exception is for BOOLEAN values, which EGL converts to the string "true" or the string "false" as appropriate. EGL then concatenates the strings, with delimiter characters between them, into a row of data. Finally, EGL writes the row to the end of the file, then writes the appropriate end-of-line character for the system ("\n", "\r", or "\r\n").

You can specify an array of records with the add statement. A null array causes a NullValueException. Otherwise, EGL loops through the array, doing an add for each member of the array. The file remains open for further writing; you can use the close statement with CSV records.

Indexed record

When you add a record with the IndexedRecord stereotype, the key in the record determines the logical position of the record in the file. Adding a record to a file position that is already in use results in the hard I/O error unique or (if duplicates are allowed) in the soft I/O error duplicate.

Relative record

When you add a record with the RelativeRecord stereotype, the value of the record number field (specified in the recordNumberItem property) determines the position of the record in the file. Adding a record to a file position that is already in use results in the hard I/O error unique.

The record number field must be available to any function that uses the record and can be any of the following fields:
  • A field in the same record.
  • A field in a record that is global to the program or is local to the function that is running the add statement.
  • A variable that is global to the program or is local to the function that is running the add statement.

Serial record

When you add a record with the SerialRecord stereotype, the record is placed at the end of the file.

EGL closes and reopens the file whenever the program changes from writing to reading or from reading to writing the file. For example, EGL closes the file if you use an add statement to write to a serial record and then use a get next statement to read data from the same file. An add that follows a get next statement adds a record to the beginning of the file. A get next statement that follows an add statement reads the first record in the file. This behavior also occurs when the get next and add statements are in different programs, and one program calls another.

Do not open the same file in more than one program at the same time.

Example

	if (userRequest == "A")
		try 
			add record1;
		onException(fileErr FileIOException)
			myErrorHandler(fileErr);
		end
	end

Compatibility

Table 1. Compatibility considerations for file I/O add statement
Platform Issue
VSAM If your program uses an add statement to write to an Entry Sequence Data Set and issues a get next statement to read data from the same file, EGL closes and reopens the file whenever the program changes from writing to reading the file or from reading to writing the file. Therefore, a get next statement that follows an add statement reads the first record in the file. Similarly, an add that follows a get next statement adds a record to the beginning of the file. This behavior also occurs when the get next and add statements are in different programs, and one program calls another.

Feedback