OPS/REXX Built-in Functions › OPSVSAM Function › Types of OPSVSAM Functions

Types of OPSVSAM Functions

The following list describes the available OPSVSAM functions:

• This function opens a VSAM file for input or output.

  var = OPSVSAM('OPEN','ddname','dsname','I' or 'O','RLS' or 'RES'
  

  One or both of these variables must be specified:

  ddname
  

  dsname
  

  If only the ddname variable is specified, the file must be preallocated to that ddname. If only the dsname variable is specified, the file is dynamically allocated to a system-generated ddname. If both the ddname and dsname variables are specified, the dsname is allocated to the specified ddname.

  Input ('I') is the default open mode. To update a file, the output mode ('O') must be specified.

  RLS (Record Level Sharing) is a feature of z/OS that allows VSAM files to be shared across systems in a sysplex. Consult your systems programming group regarding the availability of this feature. To use RLS, the VSAM file must be SMS-managed and defined with the LOG(NONE) parameter.

  Important! RES specifies that a reserve should be issued for the data set to serialize access across systems. The major name for the reserve is the ddname that is used and the minor name is SVDB. Because a reserve can cause system performance problems, consult with your systems programming group before using this option.

  The default is not to use RLS or RES.

• This function closes the VSAM file that is allocated to the specified ddname.

  var = OPSVSAM('CLOSE','ddname')
  

  If the file was an OPEN function dynamically, it is deallocated dynamically.

• This function closes the file temporarily and ensures that the following actions occur:
  • All modified VSAM records are written to DASD.
  • All catalog information is updated to reflect any changes to the high-used RBA and any additional extents that were allocated.
  • SMF usage data is generated.

    var = OPSVSAM('CLOSET','ddname')
    

  Note: An OPEN function is not required to continue file processing.

• This function issues a VSAM ENDREQ, freeing any control interval locking that a prior READUP call caused.

  var = OPSVSAM('ENDREQ','ddname')
  

• This function positions the file to the record specified by the key for subsequent sequential processing. Key length is relevant only for KSDS keys when specifying the substring length of the string that is specified in the key argument. Do not specify key length for RRDS and ESDS data sets. KEQ (key equal) is the default key match criteria. If KGE (key greater than or equal to) is specified and the key is not matched, the next higher key is pointed to.

  var = OPSVSAM('POINT','ddname','key',key length,'KGE' or 'KEQ')
  

• This function reads the next VSAM record or a specific VSAM record. If no key data is specified, sequential access is attempted. If key data is specified, direct access is attempted through the specified key. This function returns the retrieved record.

  var = OPSVSAM('READ','ddname','key',key length,'KGE' or 'KEQ')
  

• This function is the same as the READ function, except that a write request to update the record can follow. A control interval lock is obtained to prevent concurrent access to the same record by another task using shared access to the same file. ENDREQ, DELETE, UPDATE, or another READ/READUP request frees this lock.

  var = OPSVSAM('READUP','ddname','key',key length,'KGE' or 'KEQ')
  

• This function replaces the record data at the current position that a prior READUP request establishes. Specify the record data.

  var = OPSVSAM('UPDATE','ddname','record')
  

• This function deletes the record at the current position that a prior READUP request establishes.

  var = OPSVSAM('DELETE','ddname')
  

• This function adds a new record with the specified key. For KSDS data sets, you do not have to specify the key argument; the key is obtained from the record. For RRDS data sets, specify the key. For ESDS data sets, do not specify the key. All records are appended to the end of the data set.

  var = OPSVSAM('INSERT','ddname','record','KEY',key length)
  

Example: OPSVSAM

This example illustrates the performance of VSAM file operations on a VSAM KSDS with a character key length of 10 that begins in position 1 of a maximum 100-byte record:

Signal On Syntax Name VSAM_ERROR
/*  Dynamically allocate and open the VSAM file  */
vrc = Opsvsam('OPEN',,'TEST.VSAM.KSDS','O')
If opsrc > 0 Then Signal VSAM_ERROR
/*  Insert a new record with key = OPSMVS  */
newrec = Substr('OPSMVS',1,opskeyln) || 'TEST DATA RECORD'
vrc = Opsvsam('INSERT',opsdd,newrec)
If opsrc > 0 Then
  If opsrc = 8 & opsre = 8 Then
    Say 'Duplicate record:' newrec
  Else
    Signal VSAM_ERROR
/*  Retrieve and delete the record we just added  */
vrc = Opsvsam('READUP',opsdd,Substr(newrec,1,opskeyln))
If opsrc = 0 Then
  vrc = Opsvsam('DELETE',opsdd)
Else
  Signal VSAM_ERROR
/*  Clean up and exit  */
Signal ALL_DONE
/*  VSAM error procedure  */
VSAM_ERROR:
  Say 'OPSVSAM error: RC='opsrc 'REASON='opsre 'DD='opsdd
  Do While Queued() > 0
    Pull xdqmsg
    Say xdqmsg
  End
ALL_DONE:
  lrc = opsrc
  vrc = Opsvsam('CLOSE',opsdd)
  Exit lrc