SPOOLOPEN OUTPUT

Open a spool report for output.

SPOOLOPEN OUTPUT

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:

A GETMAIN has failed within the JES interface subtask(DFHPSPSS).
RESP2 gives the GETMAIN register 15 return code.
Insufficient storage was available to copy and modify the OUTDESCR argument string.

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:

The macro OUTADD or OUTDEL (invoked as a result of the OUTDESCR specification) failed.
RESP2 gives the reason code from the OUTADD or OUTDEL macro. See the z/OS MVS Programming: Assembler Services Guide for descriptions of codes.

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:

A FREEMAIN has failed within the JES interface subtask (DFHPSPSS).
RESP2 gives the FREEMAIN register 15 return code.