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 TSO/E Command Reference manual (SC28-1991-0).
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 32760 bytes) to be written to the spool. This is the
default setting. This is included for compatibility with the spool support
provided with CICS/DOS/VS and 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® JCL User's Guide.
Conditions
Note: There are no default actions.
- 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:
Authorized Assembler Services Guide, SA22-7608.
- ILLOGIC
- occurs
in any of the following situations:
- Invalid CLASS value specified.
- 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.
- LENGERR
- occurs
in any of the following situations:
- RECORDLENGTH not in the range 0 through 32760. RESP2 shows the incorrect
value.
- 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:
Authorized Assembler Services Guide, SA22-7608.
- NOSPOOL
- RESP2
values:
- 4
- No subsystem present.
- 8
- Interface being disabled; CICS is quiescing.
- 12
- Interface has been stopped.
- NOSTG
- occurs
in any of the following situations:
- NOTFND
- RESP2
values:
- 4
- No data sets could be located for retrieval for the specified external
writer name.
- NOTOPEN
- RESP2
values:
- 8
- Data set has not been opened.
- 1024
- Subtask OPEN macro failure.
- 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.
- OUTDESCRERR
- occurs
in any of the following situations:
- 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.
- STRELERR
- occurs
in the following situation: