Retrieving and inserting GSAM records

GSAM records can be retrieved sequentially or directly. You can also add GSAM records to a new data set or add new records to the end of an existing data set in the database.

To retrieve GSAM records sequentially, use the GN call. The only required parameters are the GSAM PCB and the I/O area for the segment. To process the whole database, issue the GN call until you get a GB status code in the GSAM PCB. This status code means that you have reached the end of the database. GSAM automatically closes the database when you reach the end of it. To add records to a new data set or to add new records to the end of an existing data set in the database, use the ISRT call. GSAM adds the records sequentially in the order in which you supply them.

You can retrieve records directly from a GSAM database by supplying a record search argument (RSA) to the GSAM database. An RSA is like a segment search argument (SSA), but it contains the exact address of the record that you want to retrieve. The specific contents and format of the RSA depend on the access method that GSAM is using. For BSAM tape data sets and VSAM data sets, the RSA contains the relative byte address (RBA). For BSAM disk data sets, the RSA contains the disk address and uses the relative track and record format.

You can change your application programs to accommodate for extra 4 bytes when retrieving a record for a large format data set by using the INIT call with an I/O area containing the character string of RSA12. The INIT RSA12 call is coded in a GSAM application program before any calls to the GSAM database are coded. When a GSAM application issues the INIT RSA12 call, it tells IMS that the program can accept a 12-byte RSA when retrieving a record for large format data sets. The INIT RSA12 call must be issued by any application that uses large format data sets. Failure to issue the INIT RSA12 call for large format data sets might cause an unexpected result. In the absence of an INIT RSA12 call, IMS continues to pass back an 8-byte RSA when retrieving a record for a basic format data set.

The following table provides more details about the format of the RSA for basic format data sets:

The following table provides more details about the format of the RSA for large format data sets:

Before you can supply an RSA in a GU call to a GSAM database, that RSA must have previously been returned to you as a result of a GN or ISRT call. For GSAM to return an RSA, the GN or ISRT call must be issued with a fourth parameter that points to an 8-byte (basic format data set) or 12-byte (large format data set) RSA save area in your program. Save this RSA until you want to retrieve that particular record.

To retrieve that particular record, issue a GU call for the record and specify the address of its RSA as a fourth parameter of the GU call. GSAM returns the record to the I/O area that you named as one of the call parameters.