CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › SAM()

SAM()

Use SAM() to perform I/O operations on sequential and partitioned data sets.

Syntax

The SAM() function has this syntax:

Form 1:

dcb = SAM(OBTAIN,[scope],ddname,[use])

Form 2:

SAM(action1,dcb)

Form 3:

SAM(RELEASE,dcb)

Form 4:

record = SAM(GET,dcb)

Form 5:

SAM(PUT,dcb,record,[pad])

Form 6:

SAM(OPTION,dcb,[recfm1,][lrecl],[blksize])

Form 7:

SAM(FIND,dcb,member)

Form 8:

ttr = SAM(NOTE,dcb)

Form 9:

entry = SAM(BLDL,dcb,member)

Form 10:

entry = SAM(STOW,dcb,member,[ttr],[action2],[ALIAS],[newname],[ttrn],[data])

Form 11:

state = SAM(STATUS,dcb)

Form 12:

dsorg recfm2 lrecl blksize = SAM(INFO,dcb)

Arguments

The SAM() function takes these arguments:

dcb

Value that identifies a file and an associated internal workspace.

OBTAIN

Obtains a new DCB.

scope

Scope of the data set. Specify one of the following:

LOCAL

Indicates that the file DCB is local to the IMOD; the DCB is automatically closed, and the DCB is released at the conclusion of the IMOD. LOCAL is the default.

GLOBAL

Indicates that the file is not automatically closed and the DCB is not automatically freed at IMOD termination. Instead, other IMODs can use the DCB to continue processing the same data set. Only one IMOD task can use the GLOBAL DCB at a time. GLOBAL files must be explicitly closed, and the DCBs must be explicitly freed.

Usage Notes

• Using the SAM() function requires the following steps:
  1. Obtain and initialize a DCB (data control block), which is a value that identifies the file and permits ISERVE to remember certain aspects of how you are using it.
  2. Open the file to establish a connection between the DCB and the file.
  3. Perform I/O operations on the file. These must be consistent with the type of data set you are accessing and the manner in which you initialized the DCB.
  4. Close the file. This is especially important for files used for output because physical data updates are not necessarily completed until a CLOSE is performed.
  5. Release the DCB when all processing is concluded. This action frees the storage occupied by the DCB and associated data buffers.
• Close and release operations are automatically performed at the end of the IMOD task, except when the OBTAIN specified perm.
• A particular DCB may not be used by multiple IMOD tasks simultaneously, even if GLOBAL was specified. Once any I/O operation is performed on a GLOBAL DCB, that DCB is assigned to the IMOD task for its duration.
• If multiple open DCBs specify the same ddname, the results are unpredictable.
• If the same data set is being updated from multiple IMOD tasks, the results are unpredictable.
• To replace the contents of a PDS member, perform all of the steps to create a new member. When issuing the STOW, specify REPLACE.
• Deleting or replacing a member in a PDS does not release the space previously occupied by the data. To recover this space, you must perform a compress operation, using the IEBCOPY utility program. This restriction does not apply if your installation licenses CA PDSMAN PDS Library Management space reuse feature.
• The directory of a PDS occupies the first tracks and records in the data set. If you open a PDS as a sequential data set with a DISP of OLD or SHR, in output mode, you will destroy that PDS.

Return Codes

The SAM() function produces these return codes:

101 - 109 ARG n MISSING OR INVALID

121 ALREADY OPEN

122 OPEN FAILED

123 FILE NOT OPEN

124 FILE OPEN FOR OUTPUT

125 ATTEMPTING TO READ PAST EOF

126 EOF

127 FILE OPEN FOR INPUT

128 INVALID FILE HANDLE

129 FILE NOT CLOSED

130 MEMBER NOT FOUND

131 DATASET NOT PARTITIONED

132 TRUNCATED

133 INVALID FILE HANDLE

134 READ FAILURE

135 DUPLICATE NAME

136 MEMBER NOT FOUND

137 NO DIRECTORY SPACE

138 PERMANENT I/O ERROR

139 DCB CLOSED OR OPEN FOR INPUT

140 INSUFFICIENT VIRTUAL STORAGE

141 STOW FAILED

142 NOTE FAILED

143 LRECL IS INVALID

144 BLKSIZE IS INVALID

145 RECFM IS UNDEFINED

146 LRECL IS UNDEFINED

147 BLKSIZE IS UNDEFINED

148 DDNAME MISSING

Adding a Member to a PDS

To add a member to the PDS

1. Allocate the PDS file with a DISP of MOD (see ALLOC()).
2. OBTAIN a DCB, specifying PDSOUT.
3. Open the file.
4. Use the PUT operand to write the desired records.
5. Use the STOW operand to create a directory entry. Do not specify a ttr value; the default is the first record written since the last STOW.
6. Use the TCLOSE operand to write a file mark and update all records to disk.
7. If you want to create additional members, you may continue as if the data set had just been opened.

Example

      /* DD name JUNK was already allocated */
dcb = sam('OBTAIN',,'JUNK','PDSIN')  /* Obtain a dcb for a PDS   */
sam('open',dcb) == ''                /* Open the PDS             */
sam('find',dcb,'QSGSS') == ''        /* Find the member QSGSS    */
sam('get',dcb) == 'The first record of the member' /* Get record */
      /* The next two calls are automatically done at IMOD end   */
sam('close',dcb)   == ''             /* Clean up                 */
sam('release',dcb) == ''             /* Clean up                 */

Appending Data to a PDS Member

If you consider the physical structure of a PDS, you will quickly see that it is not possible simply to add data to the end of a member. Such data would overlay the next physical member. However, the following procedure permits you to simulate appending data to a PDS member:

• Allocate the target member (OLDMEM) for input (DDNAME1).
• Using a different ddname (DDNAME2), allocate a new member (TEMPNAME) in the same data set.
• Read all records from DDNAME1 and write them to DDNAME2.
• Close DDNAME1.
• Write records to be appended to DDNAME2.
• Cause TEMPNAME to be added as member name.
• Delete OLDMEM from data set.
• Rename TEMPNAME to OLDMEM.