GSAM and IMS™ message queue access

GSAM and IMS™ message queues are two examples of serial file access through EGL.

Serial files are one of the oldest but most versatile file types that EGL works with. You access a serial file one record at a time, in order. In EGL, there are three ways to implement serial files:
VSAM
Virtual storage access method; for more information, see VSAM file access.
GSAM
Stands for generalized sequential access method. IMS™ or z/OS® batch environments use this access method for batch processing.
IMS™ message queues
Not to be confused with WebSphere® MQ (formerly MQSeries®) message queues.

You associate a serial record (a record definition that carries a SerialRecord stereotype) with a particular file by using a ResourceAssociation part during generation. This process determines whether EGL uses the record for VSAM, GSAM, or IMS™ message queue access. For more information, see the EGL Generation Guide.

Serial files as GSAM files

EGL programs that run in the IMS™ BMP or z/OS® batch environments can implement serial files as GSAM (generalized sequential access method) files. This provides a very basic sort of database capability on these systems. You can use the add, get next, and close I/O statements for serial files that you implement as GSAM files.

The following characteristics apply to GSAM serial file processing:
  • A GSAM file requires a database driver (DBD).
  • A GSAM file requires a PCB in the IMS™ PSB. You must define this PCB in the IMS™ runtime PSB and in the EGL PSB definition. In your program, you must declare a record variable that is based on the PSB Record part.
  • A GSAM file is read or written through DL/I calls. The generated COBOL program handles this automatically, based on the I/O statements that you request.
  • A GSAM file is checkpointed and restarted in the same way as a DL/I database. However, to recover the GSAM file you must use a symbolic checkpoint and restart instead of basic checkpoint.
EGL does not support the record search argument for GSAM or undefined length records.

Serial files as IMS™ message queues

Programs that run in IMS/VS implement serial files as IMS™ message queues. Programs that run as IMS™ BMP programs can also implement serial files as message queues. You can use the add and get next I/O statements as well as close for output files. If you select IMS/VS or IMS™ BMP as the target runtime environment, you can define serial or print files as being associated with a message queue. You must associate all serial files and print files with message queues for IMS/VS. You can associate only a single input file with the message queue.

When you associate a serial record with a message queue, define the program data only. The generated COBOL program adds the IMS™ message header (length, ZZ, and transaction code) for an add statement and removes it for a get next statement.

Checking the results of serial file I/O statements

When you associate a serial file with a message queue or GSAM file, the generated program issues a DL/I call to implement the I/O operation. When the DL/I call completes, Rational® COBOL Runtime performs the following functions:
  • For get next statements, the record state is set based on the DL/I status code. The sysVar.sessionID and sysVar.userID fields are updated from the user ID field of the I/O PCB when the generated program issues a GU call for the I/O PCB. This happens at the following places:
    • The first get next statement for a serial file that is defined as a multiple-segment message queue (MMSGQ)
    • Each get next statement for a single-segment message queue (SMSGQ).
    The EGL sysVar.transactionID field is updated from the transaction name in the IMS™ message header after each get next statement that results in a GU call for the I/O PCB.
  • For an add or close statement, the record state is updated based on the DL/I status code.

After a DL/I call that involves either the message queue or GSAM, the dliVar fields are not updated. These fields are updated only for functions that access DL/I segment records. This allows a program that is written for a CICS® transient data queue or an OS/VS serial file to run consistently when the file is changed to a message queue or GSAM database in an IMS™ environment. Check the I/O error values to determine if endOfFile, noRecordFound, or other error occurred on the serial file. If you need more detailed information from the PCB, use the field names in the IO_PCBRecord or the ALT_PCBRecord.

Consider a situation in which your PSB variable (named myPSB) declares an ALT_PCBRecord named myAltPCB, and you used myAltPCB as the PCB name in your resource association. To reference the DL/I status code after an add statement, use myPSB.myAltPCB.statusCode.

EGL I/O error code IMS™ Messsage Queue status code Severity
endOfFile QC Soft
noRecordFound QD Soft
ioError any non-blank status code Hard or soft
hardIOError non-blank other than QC, QD, CE, CF, CG, CI, CJ, CK, CL Hard
EGL I/O error code GSAM status code Severity
endOfFile GB Soft
ioError any non-blank status code Hard or soft
hardIOError non-blank other than GB Hard