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

SAM()

This function performs I/O operations on sequential and partitioned data sets.

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)

Parameters

dcb

Value that identifies a file and an associated internal workspace.

OBTAIN

Obtains a new DCB.

scope

Scope of the data set. Specify:

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.

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. The GLOBAL files must be explicitly closed, and the DCBs must be explicitly freed.

Default: LOCAL

Usage Notes

• Using the SAM() function requires the following steps:
  1. Obtain and initialize a DCB (data control block). The DCB is a value that identifies the file and permits ISERVE to remember certain aspects of how you are using it.
  2. To establish a connection between the DCB and the file, open the file.
  3. Perform I/O operations on the file. These operations 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 action is especially important for files that are used for output. 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 that the DCB and associated data buffers occupy.
• Close and release operations are automatically performed at the end of the IMOD task, except when the OBTAIN specified perm.
• Multiple IMOD tasks cannot use a particular DCB 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 the data previously occupied. To recover this space, 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 destroy that PDS.

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. To write the desired records, use the PUT operand.
5. To create a directory entry, use the STOW operand. Do not specify a ttr value; the default is the first record that is written after the last STOW.
6. To write a file mark and update all records to disk, use the TCLOSE operand.
7. To create more members, continue as though 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 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 lets rmits you simulate appending data to a PDS member:

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