PUT (VSAM)

Syntax:

PUT(ddname,recin[,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.
recin: contains the record to be inserted or updated. For KSDS and ESDS data sets, the records can be of varying lengths. However, the records of ESDS data sets, once loaded, cannot change lengths. If you attempt to change the length of an ESDS record VSAM will reject the request.
For RRDSs, since the record lengths are known at open time and are fixed, the Shadow REXXTOOLS VSAM interface is able to pad (with blanks) or truncate the recin argument to fit the data set. For ESDS and KSDS data sets, no padding or truncation is performed.
keyin: a character string that contains the key of the record to update or insert. If the request is for sequential (SEQ) and/or update (UPD) processing; or if the data set you are processing is a KSDS (and you are not accessing it by control interval), then the keyin argument is not required. For all other requests, the keyin argument is 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 option 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:

SWXPUT

Service Description:

The PUT function is used to update or insert records and control intervals in VSAM data sets. The operation of PUT (like GET) depends upon the processing options you specify in the options argument. Before you can call the PUT function you must first allocate and open the data set associated with the ddname argument. If you do not, an error will occur.

If you are using PUT to update a record, you must first retrieve the record using the GET function (with the UPD option). All other PUT requests are treated as insertion requests.

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 keyin 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) direct access (including skip sequential processing) the value of the key is taken directly from the key location in recin. If you supply a keyin argument for this type of access, the argument is ignored.

Returned Information:

The PUT function returns the VSAM PUT macro return code. If you CALL the PUT function, the returned value is contained in the RESULT special variable. After completion of a PUT 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 PUT return code. Zero means the operation was completed successfully.

REASON

Contains the VSAM PUT reason code.

$SWXKEY

Contains the actual value of the key for the record updated or inserted. 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 record beginning at the key offset, and continuing for the length of the full key.

$SWXRBA

Contains the Relative Byte Address (RBA) of the inserted or updated record.

$SWXRECL

Contains the length of the inserted or updated record and is fully equivalent to the following expression:

LENGTH(recin)

Examples:

Sequentially retrieve and update records from a data set starting with the first record:
```
record = get('iodd',,'upd')
do while rc = 0
  parse var record firstpart 10 salary 15 lastpart
  newsal = p2d(salary,2) * 1.1
  newrec = firstpart || d2p(newsal,5) || lastpart
  call put 'iodd', newrec
  if rc = 0 then record = get('iodd')
end
```
After the first GET, no options are required, since the UPD option stays in effect until it is changed by another request. The P2D and D2P functions (see "General REXX Extensions") are used to convert packed decimal numbers to the REXX decimal format, and vice versa.
Directly retrieve and update a KSDS record with the key 'CAT':
```
call get 'iodd', 'cat', '(key,dir,upd)'
if rc = 0 then do
  /* modify the record here */
  call put 'iodd', record
end
```
The PUT requires neither a keyin nor an options argument. Keyin is not required because for KSDS updates the key is taken from the record itself. The options argument is not required because the '(KEY,DIR,UPD)' options argument of the GET is still in effect.

Load an ESDS from a sequential file:

"execio * diskr indd (stem line. finis)"
do i = 1 to line.0
  call put 'outdd', line.i
  if rc <> 0 then leave i
end