POINT (VSAM)

Syntax:

POINT(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 all invocations of POINT except when the LRD (last record positioning request) option is specified. 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" . The RPL option groups are all alternative option groups. From each group you may select only one option.

Module Name:

SWXPOINT

Service Description:

The POINT function is used to position VSAM at specific records and control intervals in VSAM data sets. Before you can use the POINT 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. POINT does not actually retrieve a record. If you want to retrieve a record that you have POINTed to, you must use the GET function.

The primary use of POINT is to position VSAM for subsequent sequential access (beginning at a location that is not the first record of the data set).

Note: POINT is especially useful for switching between forward and backward sequential processing without closing the data set.

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 POINT function returns the VSAM POINT macro return code. If you CALL the POINT function, the returned value is contained in the RESULT special variable.

After completion of a POINT 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 POINT return code. Zero means the operation was completed successfully.
REASON: Contains the VSAM POINT reason code.

Examples:

Sequentially retrieve records from a data set starting with the last record and proceeding to the first record:
```
call point 'indd', , '(lrd,bwd)'
do while rc = 0
  call get 'indd'
  say 'result='result
end
```
After the POINT, options do not need to be re-specified, since the BWD option stays in effect until it is changed by another request.