|
|
|
The &FILE GET verb accesses a file record or a sequence of file records.
This verb has the following format:
&FILE GET ID=fileid
[ KEY=key | KEYVAR=keyvar ]
[ OPT=type ]
[ GENLEN=nn ]
{ { ARGS | VARS=prefix* } [ RANGE (start,end) ] |
VARS={ var | (var1,var2,...,varn) |
MDO=mdoname [ MAP=mapname ] }
Operands:
Identifies the file being accessed and sets this file to be the current fileid. This operand is mandatory.
Nominates the full key value to be set for the file. The key value (after substitution) is in one of several forms:
For unquoted strings the key should consist of displayable characters only, and is delimited by the first blank.
'01SMITH J.' “03JONES PETER A” “LU A0123BC2”C 'A. B. O''MALLEY'C
The usual quote rules apply. Either single quotes (') or double quotes (”) are acceptable. Quotes must be paired and of the same type. A double quote is treated as a single quotation character when included within a string.
'0012001F'X
“0123456789ABCDEF”X
If there are no characters following the closing quote, a character string is assumed. If a single character follows the closing quote then it must be either 'C' (designating a character string), or 'X' (designating a hexadecimal string). For quoted hexadecimal strings, all characters must be valid hexadecimal characters (that is, 0 to 9, A to F).
It is the user's responsibility to understand the file key structure and determine which form of key designation is most appropriate.
Note: The &ZQUOTE built-in function can assist when building quoted strings, and that the KEYVAR operand provides a suitable alternative.
Provides an alternative way to nominate the full key value. keyvar is the name of a user or system variable, the contents of which are taken unchanged as the key value for the file set operation. There is no need to code the ampersand (&)—if it is coded, the contents of the variable specified are assumed to contain the name of the variable containing the key.
Note: If both KEY and KEYVAR are omitted, the current file key value is assumed. The KEY and KEYVAR operands are mutually exclusive. It is possible to specify the OPT= option in conjunction with KEY or KEYVAR if it is a generic option, for example, OPT=KEQ, OPT=KLE, and so on. The KEY operand is only used once. Once generic position is obtained, the key operand is ignored.
Specifies a retrieval option that determines the search argument for the record to be read.
The following options are available for the OPT operand: KGE, KEQ, KGT, KEL, KLE, KLT, FWD, BWD, SEQ, SAVE, UPD, and END.
Specifies that a record key greater than or equal to the specified partial key is returned. Using KGE permits generic retrieval where a partial key is supplied-any records with a key (or part key) equal to or greater than that specified are returned.
Specifies that a record key equal to the specified partial key is returned. Using KEQ permits generic retrieval where a partial key is supplied. Any records with a partial key equal to that specified are returned, starting with the lowest full key value and continuing forwards to the highest full key value.
After a successful retrieval by KGE or KEQ, the full key for the returned record is determined from the &FILEKEY system variable. The first &FILE GET that uses the KGE or KEQ operand establishes the starting point within the file from which records are to be retrieved. Successive &FILE GET statements specifying the KGE or KEQ operand continue returning records with a higher key. The generic retrieval is terminated by specifying the KEY= operand on an &FILE GET, &FILE SET, &FILE PUT or &FILE ADD statement, or by using the &FILE GET OPT=END operand.
Specifies that a record key greater than the specified partial key is returned. KGT is normally used to process a group of records where individual records are being updated. Updating a record during a generic retrieval process normally interrupts the generic retrieval and using KGT can avoid this. If no generic retrieval is in progress, KGT processing ensures that a record greater than the current &FILEKEY is returned. If a generic retrieval is in progress, the next key is returned. The procedure normally positions at a specific record using a KEQ call, and then continues processing using KGT calls.
Alternatively, the procedure could set a partial key lower than required and let the KGT call return the next highest record. Following successful retrieval, the full key of the record returned is determined from the &FILEKEY system variable. KGT differs from KGE processing in that a KGT call is not impacted by other file processes that interrupt a generic process, such as updates and deletes.
Generic retrieval must be terminated by specifying the KEY= operand on an &FILE GET, &FILE SET, &FILE PUT, &FILE ADD statement or by using the &FILE GET OPT=END operand.
Specifies that a record key equal to the specified partial key is returned. Using KEL permits generic retrieval where a partial key is supplied. Any records with a partial key equal to that specified are returned, starting from the highest full key value and continuing backwards to the lowest full key value.
Specifies that a record key less than or equal to the specified partial key is returned. Using KLE permits generic retrieval where a partial key is supplied-the highest record with a partial key equal to or less than that specified is returned.
After a successful retrieval by KEL or KLE, the full key for the returned record is determined from the &FILEKEY system variable. The first &FILE GET that uses the KEL or KLE operand establishes the starting point within the file from which records are to be retrieved. The first record returned is the one with the highest key that matches the partial key supplied. Successive &FILE GET statements specifying the KEL or KLE operand continue returning records with a lower key. The generic retrieval is terminated by specifying the KEY= operand on an &FILE GET, &FILE SET, &FILE PUT or a &FILE ADD statement or by using the &FILE GET OPT=END operand.
Specifies that a record key less than the specified partial key is returned. KLE is normally used when processing a group of records in backwards mode where individual records are being updated. Updating a record during a generic retrieval process normally interrupts the generic retrieval and using KLT can avoid this. If no generic retrieval is in progress, KLT processing ensures that a record less than the current &FILEKEY is returned. If a generic retrieval is in progress, the next lower key is returned.
The procedure normally positions at a specific record using a KEL call, and then continues processing using KLT calls. Alternatively, the procedure could set a partial key higher than required and let the KLT call return the next lowest record.
Following successful retrieval, the full key of the record returned is determined from the &FILEKEY system variable. KLT differs from KLE processing in that a KLT call is not impacted by other file processes that interrupt a generic process, such as updates and deletes. Generic retrieval must be terminated by specifying the KEY= operand on an &FILE GET, &FILE SET, &FILE PUT, &FILE ADD statement or by using the &FILE GET OPT=END operand.
Specifies that sequential retrieval is performed in a forward direction (that is, ascending keys for a KSDS). If no preceding &FILE GET statement has established a position within the file, retrieval starts with the lowest keyed record and subsequent &FILE GET statements return records in ascending key order until the highest keyed record has been returned.
Specifies that sequential retrieval is performed in a backward direction (that is, descending keys for a KSDS). If no preceding &FILE GET statement has established a position within the file, retrieval starts with the highest keyed record and subsequent &FILE GET statements return records in descending key order until the lowest keyed record has been returned.
To retrieve records from a specific point, first issue an &FILE GET statement to retrieve either a specific key or partial key and follow this with a series of &FILE GET FWD, or &FILE GET BWD statements to process the required record range. No &FILE GET KEY statement is required to commence sequential processing. Therefore it is not necessary to know in advance any of the keys on the data set. An &FILE GET using the KEY= operand is required if positioning to a specific point using a preliminary call with one of the generic retrieval options.
An &FILE GET FWD can directly follow an &FILE GET BWD (or KEL, KLE, KLT option) to reverse the processing direction of the file. Alternatively, an &FILE GET BWD can directly follow an &FILE GET FWD(or KEQ, KGE, KGT option) to reverse the processing direction of the file (see also the &FILE GET SEQ option next).
&FILE GET can also be used to process an ESDS VSAM file.
Specifies that sequential retrieval is performed. Sequential retrieval is an efficient way of retrieving large numbers of records. If no preceding &FILE GET statement has established a start position within the file, the &FILE GET SEQ is equivalent to &FILE GET FWD. Otherwise, sequential retrieval starts from the current file position and in the current file direction. This means that an &FILE GET SEQ following an &FILE GET FWD (or KEQ, KGE, KGT option) retrieves the records following, whereas if it follows an &FILE GET BWD (or KEL, KLE, KLT option) it retrieves the previous records.
After a successful retrieval, the full key for the returned record is determined from the &FILEKEY system variable. Sequential retrieval is terminated by one of the following methods:
OPT=END is used to explicitly terminate sequential processing.
Specifies that the current generic retrieval option is saved. This option releases VSAM positioning in the file but remembers the last partial key set by an &FILE GET KEY statement and the last full key read using &FILE GET. Since generic file retrieval involves retaining various VSAM resources, it is not good practice to hold your position in a VSAM file when an extended delay is possible (for example, whilst waiting for input from a terminal). By issuing an &FILE GET SAVE, the VSAM resources required for the generic retrieval are released; when the next generic retrieval request is received the next record is returned as though no interruption had occurred. That is, the record returned is the one that would have been returned anyway had the &FILE GET SAVE not been issued.
Since the only retrieval options on ESDS files are sequential (that is, FWD, BWD, and SEQ) and therefore hold VSAM position, the SAVE option is used effectively when browsing such files to remember the current position if a delay is expected.
Specifies that the record nominated by the KEY= operand from the preceding &FILE statement is retrieved for updating.
Using this option gives you exclusive use of the specified record, if it is not currently in use elsewhere. This ensures that no other retrieval of the same record is permitted before the record is replaced with an &FILE PUT statement.
Where multiple users can simultaneously perform record updating, use this option to ensure that no overlap in update processing is possible, and that the record is being processed uniquely by this requester.
When using this option, you are responsible for ensuring that the record is used exclusively. If another user is already processing the same record when you issue this request, it will fail with the appropriate return codes and you must then retry at a later time. If exclusive use is not obtained, the &FILERC system variable will be set to 8 and the &VSAMFDBK system variable will contain a value of 14.
Important! Procedures using this technique must not perform processing that results in excessive delays (such as prompting the terminal operator for input). Remember that other users cannot use a record while you have exclusive use of it.
Using this operand terminates a generic or sequential retrieval operation, and resets the current file position. This option should be used if a generic retrieval operation is to be halted and another generic retrieval operation performed with a different key or partial key. This operand can also be used to release exclusive control of a record obtained by the UPD operand, without needing to actually update the record. Using the &FILE CLOSE statement carries an implied &FILE GET OPT=END operation.
Note: &FILE GET OPT=END forces the flushing of all deferred I/O buffers, thereby committing any deferred update activity and ending any generic retrieval environment.
Used to set the desired generic key length independently of the key value. This length is used for a generic GET request.
(Mandatory) One of the options must be specified.
Nominates the NCL variables for the read operation. NCL variables are validly used as the target of the GET operation when the file format is DELIMITED or UNMAPPED, and when the format is MAPPED and MAP=$NCL.
Specifies the list of variables to be read from the file. NCL variables are validly used as the target of the GET operation when the file format is DELIMITED or UNMAPPED, and when the format is MAPPED and MAP=$NCL. It is possible to subscript variables in the list with a data length, and use an asterisk (*) as a place holder. For example:
VARS=(a(10),b(5),*,c)
Nominates the MDO for the read operation. An MDO is the target of the GET operation only when the file format is MAPPED.
Valid only if FORMAT=MAPPED is specified or defaulted on the &FILE OPEN statement for this file. It provides the default Mapping Services map name to be used to interpret the file contents. The map name specified should be registered within the Mapping Services Data Dictionary or the data read from the file will be effectively unmapped. The default name $NCL is a special case that allows NCL tokens to be used on PUT and GET statements instead of the MDO operand. The tokens are placed within a record structure that provides data transparency but is not compatible with the DELIMITED format files.
Return Codes:
record retrieved successfully, key in &FILEKEY variable
record not found (or end of data)
error during processing of get request
NCL or Mapping Services processing error, check &SYSMSG for details
The &VSAMFDBK system variable contains the VSAM completion code. For &FILERC=8, the &VSAMFDBK system variable is tested to determine the cause of the error. These error codes are explained in detail in your VSAM documentation. The &VSAMFDBK variable is always returned as a 2-character value.
The &SYSMSG variable can also be set to containing error message details.
For MAPPED format files, the &ZMDORC and &ZMDOFDBK system variables are set.
The &ZVARCNT is set by the verb to indicate how many variables were set by the get operation.
| Copyright © 2009 CA. All rights reserved. |
|