Using serial and print files in IMS™

Serial files must be implemented as IMS™ message queues in IMS/VS. They can be implemented as message queues, OS/VS files, VSAM files, or GSAM files for IMS™ BMP. Serial files can be implemented as OS/VS files, VSAM files, or GSAM files for z/OS® batch. The following discussion deals with using serial files for GSAM files or message queues.

Using serial files as GSAM files

EGL programs that run in the IMS™ BMP or z/OS® batch environments can implement serial files as GSAM files. You can use the add, get next, and close I/O statements for serial files that you implement as GSAM files. Here is a list of differences between GSAM and normal serial file processing:

A GSAM file requires a 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 requires the use of symbolic checkpoint and restart instead of basic checkpoint.

EGL does not support the record search argument for GSAM or undefined length records.

You identify a serial file or print file as a GSAM file by using the resource association part during generation to specify a file type of GSAM and a PCB name.

When you associate a serial file with a GSAM file, you must include the following information:

Resource name: Indicates the 1- to 44-character data set name that is used in the sample runtime JCL. The file name from the record definition is used as the DD name in the sample runtime JCL.
File type: Specifies GSAM as the file type to associate the serial file or printer output with a GSAM file.
PCB name: Specifies a PCB name for the serial file that is associated with the GSAM file. If you do not specify one, the default is the first GSAM PCB in the EGL PSB.

Using serial files as message queues

Online 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. Only a single input file can be associated with the message queue.

You can associate a serial file or print file with a message queue by using a resource association part during generation and specifying the file type and a PCB name. When you associate a serial file with a message queue, you must define the following resource information:

Resource name

You must indicate the 1- to 8-character destination ID for printer or serial file data. The name must match the ID of an IMS™ logical terminal or a transaction code that is defined in the IMS™ system definition.

The file name is the default resource name for the message queue. You can override this default in the resource association part.

If the PCB that you select is a modifiable alternate or express alternate PCB, you can override the default message queue name at run time by setting a value for record.resourceAssociation for a file or converseVar.printerAssociation for a printer in the program. record.resourceAssociation is treated as a local variable. Setting record.resourceAssociation for a record in one program does not affect record.resourceAssociation in another program. An add statement writes to the message queue identified by the setting of record.resourceAssociation for that program.

Message queue type

You can specify single-segment message queues or multiple-segment message queues.

Single-segment message queues (SMSGQs)

For a single-segment message queue, each record that you add or that you read (with a get next) from the serial file is a complete message. The generated COBOL program issues an IMS™ PURG call between records that are added to a single-segment message queue. The generated COBOL program issues an IMS™ get unique for each get next statement.

Multiple-segment message queues (MMSGQs)

For multiple-segment message queues, a series of adds to the serial file is treated as though each add statement were for a segment of a single message. The message is not ended until you issue a close statement or reach a commit point. The generated COBOL program issues an IMS™ PURG call for the close statement. You can then begin adding segments of another message and close it. Multiple-segment message queues are not valid for print files.

If you issue a get next statement for a MMSGQ serial file, the generated program issues an IMS™ get unique call to get the first segment of the message. Additional get next statements result in GN calls to get the remaining segments of the message. At the end of all the segments in a message, the generated COBOL program sets the noRecordFound record state. If you continue scanning, the generated program starts another series of get unique (GU) calls, followed by get next (GN) calls. When no more messages are found, the generated program returns an endOfFile state.

PCB name

You must also specify a PCB name for the serial file that is associated with a message queue. You must specify the name assigned to the I/O PCB as the PCB name for a serial input file. The I/O PCB is the only message queue used for input. If you use a serial input file, you must use a main batch or called batch program. The generated program handles all I/O PCB logic for main textUI programs.

You can specify the PCB name for a serial output file. The PCB name must be the name assigned to an alternate PCB record. The default PCB name is the name of the first alternate PCB in the PSB. You can only send output to the I/O PCB by using one of the following system functions:

vgLib.VGTDLI()
dliLib.AIBTDLI()
dliLib.EGLTDLI()

Defining records to use with message queues

When you define a serial record to associate with a message queue, you should define only the program data. 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 a serial file is associated with a message queue or GSAM database, the generated program issues a DL/I call to implement the I/O operation. When the DL/I call completes, Rational® COBOL Runtime for zSeries® 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 first get next statement for a serial file defined as a multiple-segment message queue (MMSGQ), and at 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 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. You should 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

Using print files as message queues

For IMS/VS you must associate print files with message queues. For IMS™ BMP, you can associate print files with message queues. You associate print files with message queues the same way you associate serial files with message queues, with the exception that SMSGQ is the only valid file type for a resource association whose file name is "printer". In your IMS™ system definition, you must define the message queue name that you use in the runtime environment as a logical terminal. You can use converseVar.printerAssociation to change the printer destination at run time. For example, you could define a table of user IDs and the printer ID that each user normally uses. By setting converseVar.printerAssociation, you can route the printer output to a printer near the program user.