Open a spool report for output.
SPOOLOPEN OUTPUT
>>-SPOOLOPEN OUTPUT--TOKEN(data-area)--USERID(data-value)------->
>--NODE(data-value)--+-------------------+---------------------->
'-CLASS(data-value)-'
.-NOCC-.
>--+-------------------+--+------+------------------------------>
'-OUTDESCR(ptr-ref)-' +-ASA--+
'-MCC--'
.-PRINT-------------------------------.
>--+-------------------------------------+---------------------->
+-PRINT--+--------------------------+-+
| '-RECORDLENGTH(data-value)-' |
'-PUNCH-------------------------------'
.---------------------.
V |
>----+-NOHANDLE--------+-+-------------------------------------><
'-RESP--+-------+-'
'-RESP2-'
Conditions: ALLOCERR, ILLOGIC, INVREQ, LENGERR, NODEIDERR,
NOSPOOL, NOSTG, NOTFND, NOTOPEN, OPENERR, OUTDESCERR, SPOLBUSY, STRELERR
Description
The SPOOLOPEN OUTPUT command
opens a spool report for output from CICS® to
the system spooler and defines its characteristics.
It results in a dynamic allocation of
the output file using the nodeid to specify the remote destination
and the userid to specify the remote user. As this is a multithread
output request, requesters of this service could interleave. This
SPOOLOPEN OUTPUT command enables users to acquire the token for a
report that it expects to create (write). This token is used to identify
the report in later SPOOLWRITE and SPOOLCLOSE commands.
When
printing on a local device, use the NOCC|ASA|MCC options to control
output formatting. If you do not specify a format, the default value
of NOCC is used. NODE and USERID can be used to write the data set
directly to the local spool file only if specified with a value of
'*'.
If you do not issue SPOOLCLOSE before the end of the transaction,
CICS performs an implicit SPOOLCLOSE DELETE and writes a message to
CSMT to alert you to the possible unnecessary retention of resources.
Note: If
you retrieve a formatted data set, the system spooler could have changed
the data set format. For example, the system spooler could have converted
an MCC format data set to ASA format during data set creation. This
does not affect the final printed output.
Options
- ASA
- specifies
that the report has each record prefixed with an ASA carriage-control
character, and this character must be used by the operating system
to control formatting when the report is printed.
- CLASS(data-value)
- specifies
a 1-character class designation. If it is omitted, class A is assumed.
- MCC
- specifies
that the report has each record prefixed with an IBM® machine
command code carriage-control character, and this character must be
used by the operating system to control formatting when the report
is printed.
- NOCC
- specifies
that the report has no internal formatting controls. When the report
is printed, the operating system prefixes each record with a carriage-control
character that causes page skipping according to the default operating
system lines-per-page value.
- NODE(data-value)
- specifies
the 8-character identifier of a destination node that the system spooler
uses to route the file. It is a sender field. If you want to specify
the local spool file and to enable the OUTDESCR operand to override
the NODE and USERID operands, code NODE('*') and also USERID('*').
(Do not use NODE('*') with any other userid.) Otherwise, code the
actual NODE, which is the name of the operating system (for example,
MVS, VM) as that system is known to VTAM in the MVS system in which
your CICS is executing. NODE(LOCAL) is also a valid specification.
Validity
checking is performed for NODE. Checks are made for blanks (X'40'),
and nulls (X'00').
- OUTDESCR(ptr-ref)
- (MVS/SP—JES2
Version 3, or JES3 Version 4.2.1 only, or a later upward-compatible
release) specifies a pointer variable to be set to the address of
a field that contains the address of a string of parameters to the
OUTPUT statement of JCL. This is called double indirect addressing.
The user must set up the pointer, the address field, and the string.
This means that the OUTDESCR option cannot be used from within CECI.
The format of the string is:
Offset Length Contents
0 4 Length (n) of following text string
4 n OUTPUT statement parameters
The parameters use
the same keywords and values as the OUTPUT statement but the syntax
varies slightly. The following is the format of the OUTDESCR parameter
string:
keyword1(value1) [keyword2(value2)]
[keyword3(value3,value4)] ...
This corresponds
to the following OUTPUT statement parameter string:
keyword1=value1 [keyword2=value2]
[keyword3=(value3,value4)] ...
For details of
valid keywords and values, see the z/OS TSO/E System Programming
Command Reference.
The
OUTDESCR operand:
- Can override the NODE and USERID operands only if they are specified
with a value of '*'.
- Cannot override the CLASS operand, even if it is omitted and defaults
to class A.
Use this operand to set additional attributes for the
spool data set.
- PRINT
- allows
large records (maximum 32 760 bytes) to be written to the spool. This
is the default setting. This is included for compatibility with the
spool support provided with CICS Transaction Server for z/OS.
- PUNCH
- must
be specified if the CLASS parameter for the output data set implies
punch, and the data set is destined for a VM/RSCS node. This ensures
that the record length indicator is set to 80, which is a requirement
of VM/RSCS for punch files.
- RECORDLENGTH(data-value)
- specifies,
as a halfword binary variable, the maximum length of record to write
to a print data set. The default value is 32 760.
- TOKEN(data-area)
- specifies
the 8-character CICS-allocated token used to identify a report.
- USERID(data-value)
- specifies
the 8-character identifier of the destination userid that processes
the report. The report carries this identifier, which is used to select
the report at its destination. It is a sender field and must be declared
with a length of 8 characters.
If you want to specify the local
spool file and to enable the OUTDESCR operand to override the NODE
and USERID operands, code USERID('*') and also NODE('*'). Otherwise,
code the actual USERID. The meaning of USERID varies with the operating
system. In VM, it is a particular user; in MVS, it might be a JES
external writer or another JES destination, a TSO user, or another
job executing on that system. One such destination is the JES internal
reader, which normally has the reserved name INTRDR. If you code an
actual USERID, do not use NODE('*'); code the actual NODE instead.
The
USERID parameter is equivalent to the WRITER parameter in JES.
Validity
checking is performed for USERID. Checks are made for blanks (X'40'),
and nulls (X'00').
Sending the internal reader buffer directly
to JES: Instead of waiting for the buffer in your address space
to fill up, send the contents of the internal reader buffer directly
to JES by coding as your last record:
/*EOF
This
control statement delimits the job in the data set, and makes it eligible
for immediate processing.
For more information about using
the internal reader, and about other /* control statements, see the z/OS MVS JCL User's Guide.
Restriction: You must specify the RESP or NOHANDLE option
on the EXEC CICS SPOOLOPEN command.
Conditions
Note: There are no default
actions.
- 85 ALLOCERR
- occurs
in any of the following situations:
- Dynamic allocation has rejected a request to allocate an input
data set.
RESP2 gives the dynamic allocation response code that
denotes this error. The first two characters are the information reason
code (S99INFO), and the second two are the error reason code (S99ERROR),
as defined in the z/OS MVS Programming: Assembler
Services Guide.
- 21 ILLOGIC
- occurs
in any of the following situations:
- Invalid CLASS value specified.
- 16 INVREQ
- RESP2
values:
- 4
- Unsupported language.
- 8
- Unsupported function.
- 16
- USERID missing.
- 20
- NODE missing.
- 36
- INPUT|OUTPUT missing.
- 40
- Subsystem interface already enabled.
Note: Errors 1024 and over
are internal, and should not occur. If one of these error codes is
returned, contact your IBM support center.
- 44
- Error in the OUTDESCR string.
- 48
- OUTDESCR specified but function not available (wrong level of
CICS or JES).
- 52
- OUTDESCR specified but bad pointer found on keyword or in OUTDESCR
condition.
- 22 LENGERR
- occurs
in any of the following situations:
- RECORDLENGTH not in the range 0 through 32760. RESP2 shows the
incorrect value.
- 90 NODEIDERR
- occurs
in any of the following situations:
- JES cannot identify the NODE/USERID combination specified on SPOOLOPEN
OUTPUT.
RESP2 gives the dynamic allocation response code that
denotes this error. The first two characters are the information reason
code (S99INFO), and the second two are the error reason code (S99ERROR),
as defined in the z/OS MVS Programming: Assembler
Services Guide.
- 80 NOSPOOL
- RESP2
values:
- 4
- No subsystem present.
- 8
- Interface being disabled; CICS is quiescing.
- 12
- Interface has been stopped.
- 42 NOSTG
- occurs
in any of the following situations:
- 13 NOTFND
- RESP2
values:
- 4
- No data sets could be located for retrieval for the specified
external writer name.
- 19 NOTOPEN
- RESP2
values:
- 8
- Data set has not been opened.
- 1024
- Subtask OPEN macro failure.
- 87 OPENERR
- RESP2
values:
- 4
- A VSAM SHOWCB macro failed to return the lengths of the VSAM control
blocks used to access the JES spool file.
Also occurs (RESP2 not set) in any of the following
situations:
- An internal error occurred during SPOOLOPEN processing that has
forced the request to fail.
- 96 OUTDESCRERR
- occurs
in any of the following situations:
- 88 SPOLBUSY
- RESP2
values:
- 4
- Interface already in use by another task.
- 8
- Interface already in use by current task.
Also occurs in the following situation: - The JES/input single thread within the JES interface was not available.
- 86 STRELERR
- occurs
in the following situation: