Using spool files in VSE CICS®

EGL programs generated for VSE batch or CICS® for VSE can create and write to a VSE/POWER queue member by setting the fileType property to spool in the resource association for the serial or print file at generation.

A serial or print output file associated as a spool file type can be created and routed to the RDR, LST, or PUN VSE/POWER queue. EGL programs generated for CICS® for VSE can also read from a VSE/POWER queue member by associating a serial file as the spool file type at generation.

The first add statement for a record that is associated with a spool file creates a new VSE/POWER queue member and adds the data to the beginning of the file. Later add statements place data following the previously added data until the file is closed. A close statement issued for a spool file closes the VSE/POWER queue member.

Once a spool file is closed, a later add statement for a record with the same file name creates a new VSE/POWER queue member. When adding data to a spool file that is to be routed to the LST VSE/POWER queue, you must be aware of the following: VSE/POWER LST queue members are opened by IBM® Rational® COBOL Runtime for zSeries® with the ASA option. This specifies that the report is created using an ANSI printer-control character at the beginning of each line of data. If the file is a serial file, you must ensure that valid carriage control characters are used. If the file is a print file, then Rational® COBOL Runtime adds the printer-control characters for you.

A spool file is closed in any of the following circumstances:
  • The program ends.
  • A close statement references the file.
  • Recoverable resources are committed (sysLib.commit(), sysLib.rollback(), end of transaction or segment).

Any close indicates the end of the file.

Because you have a choice of a VSE/POWER queue destination when creating an output spool file, you have the ability to create a file that is placed on the VSE/POWER RDR queue as a batch job. Note that a close statement that refers to a spool file that is a RDR queue member indicates the end of the file. A subsequent add to the RDR queue file creates a new RDR queue member to be processed as a separate batch job. Also note that when creating jobs, if a POWER® EOJ statement is output, the POWER® job is made available to run before the spool file is closed.

System resource name format for VSE spool file

In z/VSE®, the system resource name for a spool file depends on whether the file is used for input or output. An input spool file can only be used for CICS® for z/VSE®, not for zVSE batch.
Note:
Rational® COBOL Runtime performs no error checking to ensure that a correct combination of values is specified for the qualifiers in the system resource name. Rational® COBOL Runtime sends the values for each of the system resource name qualifiers "as is" to VSE/POWER. If the v60ExceptionCompatibility program property is set to YES, Rational® COBOL Runtime places the return code from VSE/POWER in sysVar.errorCode. If the v60ExceptionCompatibility program property is set to NO, a file I/O exception is thrown.
Input file
Maximum 10-byte name in the format userid.class
userid
A 1- to 8-character VSE/POWER identifier of the program or user that will process the report. The identifier must not include blank or null characters. There is no default for this value.
class
A 1-character spool class. The class component is optional; the default is "A". You cannot use an asterisk to cause EGL to use a default class for an input spool file. The input spool file is read from the VSE/POWER PRT or PUN queue.
Output file
Maximum 65-byte name in the format jobname.queue.class.disp.form.node.userid.parm
Note:
The jobname parameter must be specified, or the default must be explicitly requested by specifying an asterisk (*). All other parameters can request the default value by specifying an asterisk (*) or a blank. However, if you request a default value for a parameter by using a blank, default values are used for all subsequent parameters.
jobname
A 1- to 8-character name that defines the jobname for the VSE/POWER queue member. This value is used when the CICS® Report Control Facility (RCF) is being used; an asterisk (*) in this field causes the EGL file name to be used for the record or EZEPRINT for a print file. When RCF is not being used (for example, when the queue is PUN or LST), the value in jobname is ignored, and the VSE/POWER queue member jobname is the CICS® for z/VSE® program ID.
queue
A 3-character name that identifies the destination VSE/POWER queue for the file. The following values are valid:
  • RDR for job output
  • LST for list output
  • PUN for punch output
  • PRT for list output (using RCF)
Using any other characters for queue causes a spool name error. An asterisk (*) or a blank in this field causes the PRT queue to be used.
When queue is set to RDR or PRT, RCF is used to access the file. When queue is set to PUN or LST, basic CICS® SPOOL support is used. Note that both LST and PRT specify that the file is to be a part of the VSE/POWER LST queue, but PRT uses RCF commands while LST does not.
If you attempt to use RCF when you do not have RCF installed on your CICS® system, CICS® returns an error message. This might be an AEY9 transaction abend, a NOSPOOL condition, or the message "SPOOLING SYSTEM IS NOT AVAILABLE".
When the queue value is PRT or LST, Rational® COBOL Runtime for z/VSE® opens the file with the ASA option. This option specifies that the report is created using an American National Standard printer-control character at the beginning of each line of data. If you are using a serial file, you must ensure that valid carriage control characters are used. If the file is a print file, Rational® COBOL Runtime for z/VSE® automatically adds the American National Standard printer-control characters for you.
class
A single character that specifies class. An asterisk (*) or blank in this field causes the default of a null string to be used.
disp
A single character that specifies the VSE/POWER disposition status of the queue member once it is closed. The following values are valid:
D
Process the job and delete it after processing.
H
Hold the job in queue until released.
K
Process the job and keep it in the queue after processing.
L
Let the job stay in the queue until released.
Using any other character for disp causes a spool name error. This field is not applicable when queue is LST or PUN. An asterisk (*) or blank in this field causes the default of "D" to be used.
form
A 4-character name that identifies the form number for print output. An asterisk (*) or a blank in this field causes the default of your location's standard form to be used.
node
A 1- to 8-character name that specifies the system node ID. An asterisk (*) or a blank in this field defaults to the current system node ID.
userid
A 1- to 8-character VSE/POWER identifier of the program or user that will process the report. It must not include blanks or null characters.
Under CICS® for z/VSE®, an asterisk (*) or a blank in userid is handled in the following way:
  • If you are signed on to CICS®, then userid defaults to the contents of sysVar.userID.
  • If you are not signed on to CICS®, then userid remains an asterisk (or, if blank, is changed to an asterisk).
  • If userid is set to ANY, it is reset to an asterisk.
Under z/VSE® Batch, an asterisk (*) or blank in the userid defaults to ANY.
parm
A string of characters used to specify additional information when queue is set to LST or PRT. The format of parm varies in the following way depending on the runtime environment and the value of queue:
  • If the runtime environment is VSECICS:
    • If queue is set to LST, parm is set to outdescr as described later in this section.
    • If queue is set to PRT, parm is set to fcbname.copies as described later in this section.
  • If the runtime environment is VSEBATCH:
    • If queue is set to LST or PRT, parm is set to fcbname.copies.
outdescr
A string that is passed to CICS® in the OUTDESCR option of the CICS® for z/VSE® SPOOLOPEN OUTPUT command. The characters must be specified in the correct format for the OUTDESCR option. The parameters use the same keywords and values as are used on the VSE/POWER LST statement for user-defined output operands, but the syntax varies slightly. The following example shows how you can use FORMDEF FORM1 and PAGEDEF PAGE1 as the parm string:
FORMDEF(FORM1) PAGEDEF(PAGE1)
The following example shows how that parm might be used in the corresponding spool file name:
JOBNAME1.LST.*.*.*.*.*.FORMDEF(FORM1) PAGEDEF(PAGE1)
Rational® COBOL Runtime for z/VSE® handles the calculation and insertion of the length area at the beginning of the string as required by CICS® for z/VSE®. The maximum length of the parm string is variable and depends on the length of the spool file specification up to this point; the total length of the spool file specification cannot be over 65 characters.
fcbname
The name of the FCB-image phase which VSE/POWER uses for printing the related job output. The name phase must be cataloged in a sublibrary accessible from the VSE/POWER partition. The name can be up to 8 alphanumeric characters (letters, numbers, and special characters). If omitted, the system default FCB is used. The default name can be specified with an asterisk (*).
copies
A number from 1 to 255 that specifies the number of copies to be printed. The default is 1.

Do not use spool files as temporary files for a program that writes to a file and then reads the file. You can specify the same resource name for an output and input file, but the resource name represents a destination rather than a specific file. If you write to a spool destination and close the file, the file might not be immediately available as an input file from that destination and might be queued behind other files sent to the same destination.

For more information on spool file access in CICS®, see the CICS® customization manual.

Spool files are opened on first access and closed in one of the following circumstances:
  • The program ends.
  • A close statement refers to the file.
  • Recoverable resources are committed (sysLib.commit(), sysLib.rollback(), end of transaction or segment).