PCB masks for GSAM databases

For the most part, you process GSAM databases in the same way that you process other IMS databases. You use calls that are very similar to DL/I calls to communicate your requests. GSAM describes the results of those calls in a GSAM DB PCB.

Calls to GSAM databases can use either the AIBTDLI or the PCB interface.

The DB PCB mask for a GSAM database serves the same purpose as it does for other IMS databases. The program references the fields of the DB PCB through the GSAM DB PCB mask. The GSAM DB PCB mask must contain the same fields as the GSAM DB PCB and must be of the same length.

Some differences exist between a DB PCB for a GSAM database and one for other IMS databases. Some of the fields are different, and the GSAM DB PCB has one field that the other PCBs do not. Because GSAM is not a hierarchical database, some fields in a PCB mask for other IMS databases do not have meanings in a GSAM PCB mask. The fields that are not used when you access GSAM databases are:

The second field: segment level number
The sixth field: segment name
The eighth field: number of sensitive segments

Even though GSAM does not use these fields, you must define them in the order and length shown in the following table in the GSAM DB PCB mask.

When you code the fields in a DB PCB mask, name the area that contains all the fields as you do for a DB PCB. The entry statement associates each DB PCB mask in your program with a DB PCB in your program's PSB based on the order of the PCBs in the PSB. The entry statement refers to the DB PCB mask in your program by the name of the mask or by a pointer.

When you code the entry statement in:

COBOL, Java™, Pascal, C, and assembler language programs, the entry statement must list the names of the DB PCB masks in your program.
PL/I programs, the entry statement must list the pointers to the DB PCB masks in your program.

The first PCB name or pointer in the entry statement corresponds to the first PCB. The second name or pointer in the entry statement corresponds to the second PCB, and so on.

Table 1. GSAM DB PCB mask
Descriptor	Byte length	DB/DC	DBCTL	DCCTL	DB batch	TM batch
Database name¹	8	X	X	X	X	X
Segment level number²	2	N/A	N/A	N/A	N/A	N/A
Status code³	2	X	X	X	X	X
Processing options⁴	4	X	X	X	X	X
Reserved for IMS⁵	4	X	X	X	X	X
Segment name⁶	8	N/A	N/A	N/A	N/A	N/A
Length of key feedback area and undefined-length records area⁷	4	X	X	X	X	X
Number of sensitive segments⁸	4	N/A	N/A	N/A	N/A	N/A
Key feedback area⁹	8 or 12 for large data sets.	X	X	X	X	X
Length of undefined-length records¹⁰	4	X	X	X	X	X

Note:

Database Name. The name of the GSAM DBD. This field is 8 bytes and contains character data.
Segment Level Number. Not used by GSAM, but you must code it. It is 2 bytes.
Status Code. IMS places a two-character status code in this field after each call to a GSAM database. This code describes the results of the call. IMS updates this field after each call and does not clear it between calls. The application program should test this field after each call to find out whether the call was successful. If the call was completed successfully, this field contains blanks.
Processing Options. This is a 4-byte field containing a code that tells IMS the types of calls this program can issue. It is a security mechanism in that it can prevent a particular program from updating the database, even though the program can read the database. This value is coded in the PROCOPT parameter of the PCB statement when generating the PSB for the application program. The value does not change. For GSAM, the values are G, GS, L, or LS.
Reserved for IMS. This 4-byte field is used by IMS for internal linkage. It is not used by the application program.
Segment Name. This field is not used by GSAM, but it must be coded as part of the GSAM DB PCB mask. It is 8 bytes.
Length of Key Feedback Area and Undefined-Length Records Area. This is a 4-byte field that contains the decimal value of 12 (or 16 for large format data sets). This is the sum of the lengths of the Key Feedback Area and Undefined-Length Records Area.
Number of Sensitive Segments. This field is not used by GSAM, but it should be coded as part of the GSAM DB PCB mask. This field is 4 bytes.
Key Feedback Area. After a successful retrieval call, GSAM places the address of the record that is returned to your program in this field. This is called a record search argument (RSA). You can use it later if you want to retrieve that record directly by including it as one of the parameters on a GU call. This field is 8 bytes for basic format data sets or 12 bytes for large format data sets.
Undefined-Length Records Area. If you use undefined-length records (RECFM=U), the length in binary of the record you are processing is passed between your program and GSAM in this field. This field is 4 bytes long. When you issue a GU or GN call, GSAM places the binary length of the retrieved record in this field. When you issue an ISRT call, put the binary length of the record you are inserting in this field before issuing the ISRT call.