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).