DEFINE STREAM command

Describing sequential I/O streams

Summary

Privileges

User 0 or system manager

Function

Describes sequential I/O streams for processing within Model 204

Syntax

DEFINE STREAM name [LIKE previousname] WITH SCOPE=SYSTEM { CONCATENATE=(stream1 [,streamn]...) | PARALLEL=(stream1 [,streamn]) MINAVAIL=n | GDG=ddname CONTROL=ddname2 | RING=(stream1 [,streamn]...) OFFLOAD=stream CONTROL=ddname [AUTOOFFLOAD=n] [CLOSE={AUTO | NOAUTO}] }

The command options are described in the following table. See also Configuring checkpoint and journal data streams.

CONCATENATE	Specifies a stream defined with a concatenated configuration. CONCATENATE, PARALLEL, GDG, and RING are mutually exclusive options.
stream1 ... streamn	Options stream1 through streamn specify the names of the streams that are members of the concatenated configuration in the order of their use. The streams referred to can be: Another stream Data set
PARALLEL	Specifies a stream defined with a parallel configuration. A PARALLEL stream requires a MINAVAIL value. CONCATENATE, PARALLEL, GDG, and RING are mutually exclusive options.
MINAVAIL	Specifies the number of members that must remain available for a parallel stream to continue as a valid output stream. MINAVAIL is valid for PARALLEL streams only. The default is the number of members specified in the PARALLEL parameter. The smallest allowable value for this option is 1. If there is an I/O error on all streams, an I/O error is displayed. If one member stream is still usable, then a value less than MINAVAIL results in the display of a file-full condition with output streams. Under the same conditions, falling below MINAVAIL results in the display of an end-of-data condition with input streams.
RING	Specifies that the stream being defined is a ring configuration. The options stream1 through streamn specify the names of the streams that are members of the ring configuration in the order of their use. The streams referred to can be: Another stream Data set CONCATENATE, PARALLEL, GDG, and RING are mutually exclusive options.
AUTOOFFLOAD	Specifies the number of members that can be filled before an offload process is started for an output RING stream. The value specified must range from one to the number of ring members minus one. If a value greater than the range maximum is specified, the DEFINE STREAM command is rejected. This option is invalid with PARALLEL and CONCATENATED streams and has no effect when specified for input RING streams. The default value is the number of ring members minus one. The system manager can start the offload process manually at any time by using the OFFLOAD command.
OFFLOAD	Specifies the name of the stream used for automatic or manual dumping of RING stream members. For an output RING, the OFFLOAD stream is opened at one of the following points: When the AUTOOFFLOAD threshold is reached. When an OFFLOAD command is issued for the RING stream. When the RING stream is closed and one or more members of the RING require offloading, unless specifically suppressed by the CLOSE=NOAUTO parameter setting. The offload stream is closed if it was concatenated. Otherwise, it is left open as long as the ring stream is left open. In the case of input, OFFLOAD specifies the stream containing data that was offloaded while writing to the ring stream. OFFLOAD is required for ring streams, and it is not valid with CONCATENATE or PARALLEL.
CLOSE	Specifies the offloading action taken when the RING stream closes. AUTO This option, the default, indicates that any data that has accumulated in ring members since the completion of the last offload process must be offloaded during close processing. If this option is selected, the offload stream is opened and the data is offloaded from the ring members to the offload stream. In addition, if the offload stream is open when EOD processing begins, it remains open even if the offload process enters an idle state before the actual closing of the stream. This allows the final offload process to continue to the same output data set. NOAUTO Specifies that the ring is not offloaded completely when the stream is closed. In this case, the offload stream does not contain a complete copy of the data on the ring. At the time the ring is closed, any offload process in progress is immediately ended without completing the offload of the member currently being offloaded. EOD processing of a ring with CLOSE=NOAUTO does not attempt to keep the offload stream open, if it is then open. The offload continues until the ring stream is closed. The table below sums up the effect of the AUTO or NOAUTO options on EOD and close processing: Effects of AUTO and NOAUTO options Option EOD processing CLOSE processing AUTO If offload process enters idle state, OFFLOAD stream remains open. Any members not offloaded before are offloaded. NOAUTO If offload process enters idle state, OFFLOAD stream is closed. If an offload process is in progress, it is terminated immediately. There is no further attempt to offload.
CONTROL	Specifies the name of a data set that contains control information for the RING stream or GDG data set. The CONTROL data set is required only for CCAJRNL RING streams and GDG data sets. SPACE=CYL,(1,1) is sufficient. You do not need to specify any DCB attributes, Model 204 sets those to: RECFM=U,LRECL=24,BLKSIZE=24 The CONTROL data set keeps track of each offload that has occurred and what the current ring member or GDG stream is. It is an output data set during the original run. If recovery is subsequently required, it is an input data set that tells recovery: For ring members, which offload data sets and in what order to read them. For GDGs, which generation data sets and in what order to read them.
GDG	Specifies a data set defined with a GDG configuration. A GDG data set requires a CONTROL data set. A GDG member must be a data set. STREAM is not supported for a GDG member. A GDG must be the lowest level of a stream and may have no subsequent levels. The GDG data set is available for only z/OS. GDG streams may only be used for journals and checkpoints. Use of GDG streams for directed output files does not work. CONCATENATE, PARALLEL, GDG, and RING are mutually exclusive options.

Example

The following example uses a series of DEFINE STREAM commands to specify a recovery stream and the underlying members of that recovery stream:

DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM - RING=(A,B,C) OFFLOAD=D CONTROL=E - AUTOOFFLOAD=2 DEFINE STREAM A WITH SCOPE=SYSTEM - PARALLEL=(JRNL1,JRNL2) DEFINE STREAM B WITH SCOPE=SYSTEM - PARALLEL=(JRNL3,JRNL4) DEFINE STREAM C WITH SCOPE=SYSTEM - PARALLEL=(JRNL5,JRNL6) DEFINE STREAM D WITH SCOPE=SYSTEM - PARALLEL=(TAPE1,TAPE2) MINAVAIL=1 DEFINE STREAM E WITH SCOPE=SYSTEM - PARALLEL=(CTL1,CTL2) MINAVAIL=1

Usage notes

The DEFINE STREAM command is only for the recovery streams CCAJLOG, CCAJRNL, CCARF, CHKPNTS, CHKPOINT, RESTART, and RESTARTS. The ring stream OFFLOAD option can also be a stream of any type or a data set. These DEFINE STREAM commands can be entered before the User 0 parameter line in the CCAIN data set. This allows them to be defined by the system manager before they are opened by the initialization routines.

For more information on sequential file processing, refer to OFFLOAD command.

Handling mutually exclusive or missing options

Each type of stream you can define — CONCATENATE, PARALLEL, RING, GDG — is mutually exclusive of the other types of streams. If you define a stream with more than one type, Model 204 issues various messages, depending on the combination of types you defined.

In the following example, CCAJRNL is defined with both the CONCATENATE and PARALLEL options:

DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM - CONCATENATE=(J01,J02) - PARALLEL=(JO3,JO4) - MINAVAIL=2 - *** 1 ****** M204.1088: CONCATENATE AND PARALLEL ARE MUTUALLY EXCLUSIVE OPTIONS *** 2 ****** M204.0630: DEFINE COMMAND REJECTED

In the following example, CCAJRNL is defined as GDG, but the CONTROL option is missing.

DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM GDG=STEP04B - *** 1 ****** M204.1471: CONTROL IS REQUIRED FOR THIS COMMAND *** 2 ****** M204.0630: DEFINE COMMAND REJECTED

In the following example, CCAJRNL is defined first as a RING stream and then as a GDG data set. Model 204 rejects this definition because it reads through to the final option, AUTOOFFLOAD, holds that, and reads backwards to find the type of stream, GDG, the last type defined. Since AUTOOFFLOAD and GDG are mismatched, an error is issued.

DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM - RING=(J01,J02) - GDG=STEP06DD - CONTROL=CTL01 - OFFLOAD=OFFJ01 - AUTOOFFLOAD=3 *** 1 ****** M204.1473: RING IS REQUIRED WHEN AUTOOFFLOAD IS SPECIFIED *** 2 ****** M204.0630: DEFINE COMMAND REJECTED

When you encounter these types of errors, the solution is to rewrite the commands.