READ, READTAB, READLK (AFILE)

ANSI

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

(1)	[label]	READ	{afile},{{key},[...]};[{list}][;]
(2)	[label]	READ	{afile},{{key},[...]};[columnname={variable}][,...][;]
(3)	[label]	READTAB	{afile},{{key},[...]};[{list}][;]
(4)	[label]	READTAB	{afile},{{key},[...]};[columnname={variable}][,...][;]
(5)	[label]	READLK	{afile},{{key},[...]};[{list}][;]
(6)	[label]	READLK	{afile},{{key},[...]};[columnname={variable}][,...][;]

Where:

label

Optional. A Program Execution Label.

afile

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

key

Required. One or more previously defined Character String Variables or VARLISTs of Character String Variables, or a single numeric variable that selects the record to read.

list

Optional. Any combination of previously defined Character String Variables or Numeric Variables, string or numeric ARRAYs, individual array elements, VARLISTs of string or numeric variables, or valid Disk I/O List Controls.

;

Optional unless list not specified. A semicolon indicating Partial I/O.

columnname

Required. The column name as specified in the VIEW that was assigned to the file variable by the OPEN or PREPARE instruction. The column named is not case sensitive.

variable

Required. The variable that has been previously declared and is loaded with data read.

Flags Affected: LESS, OVER, ZERO

Note the following:

READ and READTAB are synonyms.
If the manual record locking mode is in effect, the READLK form locks the record as it is read.
If manual record locking is in effect, a READ performs a traditional read operation with an implied FILEPI and temporarily locks the data record only for the duration of the READ statement. The READ clears the temporary record lock when the operation is completed. The READ in this case honors the WAIT mode as expected for the record locking operations.
If the automatic record locking mode is in effect, all forms of this instruction lock the record as it is read.
If {key} is a numeric variable equal to or greater than zero, it designates a sector in the file for random or direct access. If it is a negative numeric variable equal to -1, -2, -3 or -4, sequential file processing is indicated ( see READ (FILE), Random Access Method, or Sequential Access Method for more information).
If {key} is one or more valid character string variables, it designates an AAM READ instruction is desired. However, only the Logical String of each character string variable is used.
The individual key specifications must be separated from other key specifications by commas.
Each key is constructed as 'nnt{data}' with the format is as follows:

Value	Designates ...
nn	the key field number for the search. Each key specification or range is a unique key field number (i.e., using the key specifications '1-10,11-20,21-30' / 1-10 would be key field number 1, 11-20 would be key field number 2 and 21-30 key field number 3). nn must be two numeric digits and left zero-filled.
t	the type of search performed (i.e., X for eXact, R for Right, L for Left and F for Free - the search type character must be in upper case).
{data}	the actual string of data to search for. The search string specified must conform to the requirements for the search type being used. The only exception to the rules is when the `U' option has been specified during the AAM file creation (through the PREPARE instruction or the AAMDEX utility). The `U' option specifies that upper and lower case characters are treated as equal during any searches.

The valid search types are as follows:

Type	Search
X	Exact, the search string must match all data within the key field specified. If the search string size is not equal to the key field size, it is treated as if it were truncated or blank-filled, as appropriate, to match the key field size. The wildcard character may be part of the search string, if at least three contiguous non-blank, non-wildcard characters have been specified except if the field size is less than 3 characters.
R	Right, the search string must match the right most data in the key field. If the search string size is larger than the key field size, the search string is truncated and the search is treated as an Exact (X) search. The wildcard character may be part of the search string, if it is not the right most search character and at least one non-blank, non-wildcard character has been specified.
L	Left, the search string must match the left most data in the key field. If the search string size is larger than the key field size, the search string is truncated and the search is treated as an Exact (X) search. The wildcard character may be part of the search string, if it is not the left most search character and at least one non-blank, non-wildcard character has been specified. If a blank is the leftmost character in the key, three non-blank, non-wildcard characters are required at some point following the blank or blanks. Otherwise, only one non-blank, non-wildcard character is required for a left search.
F	Free, the search string must be matched somewhere within the key field (a free floating check is made). This search type requires at least 3 bytes of search string data or an I/O error occurs. If the search string size is larger than the key field size, the search string is truncated and the search is treated as an Exact (X) search. The wildcard character may be part of the search string, if at least three contiguous non-blank, non-wildcard characters have been specified.

Any Null String key specifications in {keys} are ignored. However, if all of the key specifications are null an attempt is made to re-read the last record retrieved by any AAM read instruction (READ, READKG, or READKGP). If a valid AAM read has not been previously performed, an I/O error occurs.
Use of an excluded key (X option during AAMDEX) requires at least one valid AAM key specification be given.
{list} may be any combination of character string and/or numeric variables (including arrayed items), character string and/or numeric literals and/or supported list controls separated by commas. If an ARRAY variable is given without a specific array element designated, all elements of the array are processed.
{list} may be optionally excluded if two semi-colons (;;) are specified after {key}. This technique only positions the file pointer to the beginning of the record/sector without actually reading any data.
When reading a data field into a FORM variable, any non-leading white space characters read are converted to zero characters. This read IO behavior exists because this was the legacy behavior that existed for the original Databus IO read instructions. As an example, if the data being read is 's1s2s3', where the 's' character is a white space, the resulting FORM variable value would be 's10203' where 's' character is a white space. This read IO behavior is the default for Sunbelt runtimes. For runtime versions 9.4D or later, this behavior can be changed using the PLB_ANSIIO runtime keyword or the SETMODE *PLBANSIIO keyword to force a FORMAT error when non-leading white space characters are encountered.
The supported list controls are as follows:

Control	Function
*ABSON	Enable absolute transfer of file data
*ABSOFF	Disable *ABSON
*CDFOFF	Disable *CDFON
*CDFON	Enable comma-delimited Field support
*EDIOFF	Disable *EDION
*EDION	Enable Electronic Data Information support
*LC	Disable *UC (default)
*LL	Set the Length Pointer to last non-blank character
*{n}	Tab to the {n}'th character offset in the given record
*PL	Disable *LL (default)
*TAB={n}	Tab to the {n}'th character offset in the given record
*UC	Convert lower case data to upper case

When using tabbing (*TAB=n or *n) in an AAM file, the tab position is relative to the first position in the record being processed.
Attempting to read a nonexistent AAM record sets the OVER Condition Flag (TRUE) and clears the LESS Condition Flag (FALSE). All variables are left in their original state unless the PLB_RDCLR environment variable is set for PLBCMP. That keyword clears all DIM fields and zeros all FORM fields.
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, 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 (the Form Pointer FP is set to 0).
If a semi-colon (;) terminates the list, the rules relevant to partial reads apply (see Partial I/O).
If deleted characters are found (Hex/Octal 00), the ZERO Condition Flag is set.
If a FORMAT error occurs, the record pointer is returned to its original position prior to the read.
None of the key fields that are used in the READ instruction may be changed between the READ and a future READKG or READKGP instruction.
When using the single unlocking mode, a READ to a record that is not locked unlocks the currently locked record before the READ is attempted.
If a locking conflict occurs, the read fails and the following actions take place.

The LESS Condition Flag is set and the OVER Condition Flag is cleared.
All variables are left in their original state unless the PLB_RDCLR environment variable is set for PLBCMP. That keyword clears all DIM fields and zeros all FORM fields.
The current data file position and the sequential data file position are set to the position of the locked record.
The update data file position is set to invalid.
The index file position is set to the position in the retrieval set of the locked record.

Record Locking was added in version 8.2 and is not available when using the PLBCE runtime.
When a view schema is assigned to an AFILE variable (9.4), the READ instruction can optionally use the column name syntax (format 2, 4, and 6 above). When the column name syntax is being used, all variables used in the instruction variable list must have column names specified. When the column name syntax is not being used, no variables in the instruction variable list can have column names.

If the column name syntax specified with the 'columnname' parameter is being used, the 'columnname' parameter can be one of the following:

Column name as specified by the VIEW column definitions.

@{svar} where {svar} is a variable that contains the column name as specified by the VIEW column definitions.

Example:

AFILE AFILE

myKey DIM 10

myProdid DIM 10

myParam DIM 50

...

. Both of these READ syntax formats give the same results when

. using a VIEW definition column name of 'PRODID' and the AFILE

. is opened with VIEW definition being used.

READ AFILE, myKey; PRODID=myProdid

MOVE "PRODID", myParam

READ AFILE, myKey; @myParam=myProdid

If the column name syntax format is being used, partial IO using the ';' character is allowed.
If the column name syntax format is being used, the data is retrieved from the data record using the VIEW data type, location, and field size that has been defined for a column. After the column data field is retrieved, the data is moved into the final destination variable specified by {variable}.

AAM Key Examples:

Key	Definition
`01FSunbelt'	is a Free search within key field 1 for the string `Sunbelt'. The record matches if `Sunbelt' is located anywhere within key field 1. If the `U' option was specified during the creation of the file (through PREPARE or AAMDEX), the search is not case sensitive so upper and lower case is treated equally (i.e., `sunbelt', `Sunbelt', `SUNbelt', etc., would also generate a match).
`02XSunbelt'	is an Exact search of key field 2 for the word `Sunbelt'. If key field 2 contained the string `Sunbelt' only or `Sunbelt' followed by spaces (due to blank-filling of Exact keys that are shorter than the key field), a match would be generated. Case sensitivity would be disabled for the search if the `U' option was used when the file was created.
`03LSun'	is a search of the left most positions within key field 3 is made for records matching the string `Sun'. Any records in which key field 3 begins with `Sun' generates a match (i.e., Sunbelt, Sunset, Sundown, etc.). Case sensitivity would be disabled for the search if the `U' option was used when the file was created.

The runtimes allow an AFILE READ operation to be aborted. This feature was implemented such that an end-user can abort an AFILE READ that is taking an excessively long time before finding a record. By default, the runtimes do not allow an AFILE READ to be aborted. The ability to abort an AFILE READ can be enabled using a new keyword named PLB_AAMCANCELCHAR keyword in a runtime INI file or by using the SETMODE *AAMCANCELCHAR instruction. If an AFILE READ is aborted by using the AAM Cancel character/key, the OVER flag is set. A GETFILE AAMCANCELFLAG keyword retrieves an AAM Cancel character/key flag that indicates whether the AFILE READ was aborted. Also, there are keywords for the AFILE OPEN and PREPARE instructions that allow individual AFILE variables to invoke the use of the AAM Cancel character support. (9.6)

Note:

The AAM Cancel support must be enabled before the OPEN/PREP action of an AFILE variable. When the AFILE is opened or prepared the current AAM Cancel support is enabled for the AFILE accessing an AAM file. Changing the runtime AFILE READ default settings after an AFILE is opened does not change the AFILE AAM Cancel support being used.
The CHAIN instruction resets to current program AAM Cancel character value back to the default setting specified by the PLB_AAMCANCELCHAR INI keyword.