READ (XFILE)

9.0D

The READ instruction retrieves information from an xfile and transfers that information into data variables. The statement format is as follows:

Where:

label

Optional. A Program Execution Label.

xfile

Required. A previously defined and opened XFILE variable from which data is read.

key

Required. A previously defined Character String Variable, Numeric Variable, or Expression that selects the record to read.

field

Optional. The name of a field.

var

Optional. A previously defined Character String Variable, Numeric Variable, string or numeric ARRAY, or individual array element.

rs

Optional. The name of a recordset.

listctl

Optional. A supported list control.

;

Optional. indicates Partial I/O.

Flags Affected: EOS, LESS, OVER, ZERO

Note the following:

1. If {key} is a numeric variable and is equal to or greater than zero, it designates a record for random or direct access. The first record in the recordset is zero (0).

2. If {key} is a numeric variable and is a negative number equal to -1, -2, -3 or -4, it indicates sequential record set processing (see Sequential Access Method). The differences are as follows:

 

Value	Action
-1	Sequential forward processing
-2	Sequential forward processing
-3	Position to End Of File (EOF) prior to processing
-4	Sequential backward processing

 

3. If {key} is a character string variable, the character data is treated as a record filter string and the first matching record is returned. If no matching record is found, the OVER flag is set. See the XML Record Filter Support topic for a description of the record filter string syntax that can be used in the READ XFILE {key}.

Example:

XFile XFILE

Key INIT "NAME='Bill'"

dName DIM 25

dAddress DIM 50

...

         READ XFile, Key; NAME=dName,ADDRESS=dAddress

 

4. If the input data size is too large for a program DIM or FORM variable, the EOS flag is set to indicate that data was truncated.

5. When reading with a NULL {key}, the last read record is read again.

6. If a READ with character string variable for the {key} is successful, the READKG and READKGP instructions moves forward and backward within the recordset using the same record matching criteria.

7. {field} is an identifier for data to be read into the {var} variable. The syntax for {field} can be one of the following:

 

field name

$field name

@{svar} where {svar} is a variable that contains the field name

 

7. If a $ precedes the field name, the $ character is stripped off and the field name references an attribute field.

8. If no $ character precedes the field name, the field name references an element field or an attribute field.

9. If no {field} is specified, the name of the {var} variable is the field name.

10. {rs} is an identifier for a recordset to associated with the referenced the {xfile} variable. The syntax for {rs} can be one of the following:

 

recordset name

@{svar} where {svar} is a variable that contains the recordset name

 

11. If no {rs} is specified, the variable name associated with the {xfile} variable is the recordset name.

12. When a recordset is associated with an XFILE during a read, any previous associated recordset is cleared and a new association is created as if an OPEN operation has occurred.

13. The supported {listctl} controls are as follows:

 

Control	Function
*LC	Disable *UC (default)
*LL	Set the Length Pointer to last non-blank character
*PL	Disable *LL (default)
*UC	Convert lower-case data to upper-case

 

14. {list} may be excluded if two semi-colons (;;) are specified after {record}. This technique only positions the file pointer to the beginning of the record without actually reading any data.

15. If an attempt is made to read past the End Of File (EOF) indicator (using -1 or -2) or if an attempt is made to read before the beginning of the file (using -4), the OVER Condition Flag is set and the LESS Condition Flag is cleared. All numeric variables in the list are set to zero (0) and all character string variables in the list are blank-filled and CLEARed.

16. If a semi-colon (;) terminates the list, the rules relevant to partial reads apply (see Partial I/O).

17. If a FORMAT error occurs, the record pointer is returned to its original position prior to the read.

18. READ supports the 'Record_Text=' internal data tag reference. This allows a given XML tag to contain both an attribute and data. The 'Record_Text' tag is not case sensitive.

See Also: XML Support