GET (VSAM)

Syntax:

GET(ddname[,keyin][,options])

Arguments:

ddname: is the 1 to 8 character name that identifies the data set you want to process. This name needs to have been previously associated with the data set, either via the ALLOCATE command or JCL DD statement, and opened via the OPEN function.
keyin: a character string that contains the key of the record to retrieve. The keyin argument is required for GET function calls that specify the DIR or SKP options (see options argument below). However, if the LRD (last record positioning request) option is specified, the keyin argument is not required. If you specify keyin, and it is not required, the argument is ignored. Alternatively, if you omit the keyin argument and it is required, an error will occur.
Note: The format of the keyin argument is different for different types of data sets and data set accesses. Please see "Specifying the Keyin Argument" below for more information.
options: a character string describing the processing options for this request. You may specify the options in any order. If multiple options are coded, they must be enclosed in parentheses and separated by commas. The groups, their options, and descriptions are given in the section "Request Parameter List (RPL) Options" . From each RPL option group you may select one (and only one) option.

Module Name:

SWXGET

Service Description:

The GET function is used to retrieve records and control intervals from VSAM data sets. Before you can use the GET function you must first allocate and open (using the OPEN function) the data set associated with the ddname argument. If you do not, an error will occur. GET may be used to retrieve records either sequentially or directly, depending upon the processing options you specify in the options argument. If you are using a direct form of access (either DIR or SKP) you must specify the keyin argument.

GET is also used to update and delete records. If you wish to update or delete a record, you must first call the GET function using the UPD (update) option.

Specifying the Keyin Argument:

The format of the keyin argument varies, depending upon the type of data set you are processing and the type of access you have requested. If you are using addressed access (the ADR option), or if you are processing by control interval (the CNV option), the value of key must be a relative byte address (RBA) in REXX printable integer format. Similarly, if you are processing an ESDS using direct access, the argument must be a RBA. For RRDSs the value of keyin must be a relative record number (RRN) in REXX printable integer format.

For KSDS keyed (but not addressed) access, the value of keyin must be either a full-length (option FKS) or generic (option GEN) key. Generic keys are used to find records that have the same prefix characters. For example, the generic key 'D' matches with 'DAVID', 'DOG', and 'DAD'. As this example demonstrates, generic keys usually have fewer characters than full keys, although this is not a requirement. If you specify a key that is longer than the full key length, the value is truncated on the right. If you specify a key that is shorter than the full key length and you have not specified the GEN option, the key is padded on the right with binary zeros up to the length of the full key.

Returned Information:

The GET function, if successful, returns the record requested. If the GET request fails, a null string (zero length) is returned. If the GET function is CALLed, the REXX special variable, RESULT, will contain the returned record.

After completion of a GET function call, the RC and REASON variables will contain return code information. If the function call was successful, several other special REXX variables are created. You should treat these variables as "read only" and make no attempt to modify any of them. The variables are:

RC

Contains the VSAM GET return code. Zero means the operation was completed successfully.

REASON

Contains the VSAM GET reason code.

$SWXKEY

Contains the actual value of the key for the record retrieved. For ESDSs and any type of data set that is being processed by control interval (option CNV), the value of the key is the RBA of the record. For RRDSs the value of the key is the RRN. For KSDSs not being processed by control interval, the key is the bytes extracted from the retrieved record beginning at the key offset, and continuing for the length of the full key.

$SWXRBA

Contains the Relative Byte Address (RBA) of the retrieved record.

$SWXRECL

Contains the actual length of the returned record and is fully equivalent to the following expression:

LENGTH(RESULT)

Examples:

Sequentially retrieve records from a data set starting with the first record:

parsestmt = "parse value get('indd')",
            "with name +30 ssn +11",
            "empno +10 salary +11"
interpret parsestmt
do while rc = 0
  say 'Name:' name
  say 'SSN: ' ssn
  say 'Emp. No.:' empno
  interpret parsestmt
end

Note that no options are specified because '(KEY,SEQ,FWD)' are defaults.

Directly retrieve the first record from a KSDS which has a key that begins with the letters 'PA':

searcharg = 'PA'
parse value get('indd',searcharg,'(gen,key,dir)'),
      with accountno +11 fname +15 lname +15,
           birthday +8 age + 3

Retrieve the fifth record from a relative record data set:
```
record = get('indd',5,'(dir)')
```