TDQUEUE attributes

Describes the syntax and attributes of the TDQUEUE resource.

Attributes for extrapartition queues

Attributes for intrapartition queues

TDQUEUE attributes for indirect queues

TDQUEUE attributes for remote queues of unspecified TYPE

ATIFACILITY({TERMINAL|FILE|SYSTEM}) (intrapartition queues only)

Specifies the type of destination the queue represents.

FILE: The transient data queue is to be used as a file of data records that are not associated with a particular terminal or system. ATI does not require a terminal to be available.
SYSTEM: The transient data queue is to be associated with the specified system identifier. The system must be defined to the local CICS® system using an RDO CONNECTION definition.
Specifying ATIFACILITY(SYSTEM) initiates a distributed transaction processing (DTP) session. For more information about DTP considerations in application programming, see Distributed transaction processing (DTP).
TERMINAL: The transient data queue is to be associated with the terminal. The terminal must be defined to CICS. If you do not specify TERMINAL, it defaults to the value of FACILITYID. If ATI is used, as specified in the TRANSID and TRIGGERLEVEL attributes, the transaction that is initiated is associated with the specified terminal, which must be available before the transaction can be initiated.

BLOCKFORMAT({BLOCKED|UNBLOCKED|blank}) (extrapartition queues only)

Specifies the block format of the data set. There is no default. If you specify the record format (RECORDFORMAT attribute) as undefined (or allow it to default), you cannot specify anything for the BLOCKFORMAT attribute.

blank: Indicates that no block format is defined for this data set. Leave this field blank if you leave RECORDFORMAT blank.
BLOCKED: Blocked record format.
UNBLOCKED: Unblocked record format.

You are strongly advised to specify an unblocked record format for extrapartition queues that are used as an interface to the JES internal reader. If you use a blocked record format, your job is held in the SYSOUT data set, and not sent directly to JES until one of the following actions occurs:

You follow the JES /*EOF control statement with a second /*EOF statement
Your application writes another job to the same queue
You explicitly close the queue after the job is written
You shut down CICS normally

BLOCKSIZE({length}) (extrapartition queues only)

Specifies the length of the block in bytes, in the range 0 through 32767.

The maximum value you can specify depends on whether SYSOUTCLASS is specified, either explicitly or by default, and on whether RECORDFORMAT is FIXED or VARIABLE.

If you specify SYSOUTCLASS, the maximum value of RECORDSIZE is 8968.
Each block in a variable format data set consists of a block descriptor word followed by one or more logical records. Therefore, if you specify RECORDFORMAT(VARIABLE), the value you specify for BLOCKSIZE must include 4 bytes for the block descriptor word, and space for the largest possible logical record.

These limits are summarized in the following table:

Is SYSOUTCLASS specified?

Yes

RECORDFORMAT

VARIABLE

FIXED

VARIABLE

FIXED

Maximum value of RECORDSIZE

8968

32763

32767

Maximum value of BLOCKSIZE

8972

8968

32767

DATABUFFERS({1|number}) (extrapartition queues only)

Specifies the number of buffers to be provided, up to a maximum of 255.

DDNAME(ddname)

Specifies a 1- to 8-character value that may refer to a data set defined in the startup JCL. The name must not start with the characters DFH, which are reserved for use by CICS, unless the name describes one of the standard destinations.

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

DISPOSITION({SHR|OLD|MOD}) (extrapartition queues only)

Specifies the disposition of the data set.

MOD

CICS first assumes that the data set exists. For an existing sequential data set, MOD causes the read/write mechanism to be positioned after the last record in the data set. The read/write mechanism is positioned after the last record each time the data set is opened for output.

If CICS cannot find volume information for the data set:

On the DD statement
In the catalog
Passed with the data set from a previous step

it assumes that the data set is being created in this job step. A data set allocated dynamically in this way is deleted when the queue is closed, and all records are lost.

For a new data set, MOD causes the read/write mechanism to be positioned at the beginning of the data set.

OLD

The data set existed before this job step.

SHR

The data set existed before this job step and can be read by other concurrent jobs.

DSNAME({dsname|DUMMY}) (extrapartition queues only)

Specifies the name of the QSAM data set that is to be used to store records written to this extrapartition queue.

When CICS receives a request to open an extrapartition transient data queue, the startup JCL is referenced to check if a data set definition has been created. If one is not found, the 44-character name specified on the DSNAME attribute is used to dynamically allocate the required data set.

If you have JCL that preallocates for this queue the DSCNAME value to a DSNAME value, the DSNAME value in the resource definition is overridden by the DSNAME value from the JCL. JCL allocation always takes priority.

Partitioned data sets (PDS) are not supported on the DSNAME attribute. If you want to use a PDS member for an extrapartition queue data set, code it explicitly in your JCL. Bear in mind that if you inquire upon this queue, the DSNAME value that is returned will not give you any indication of the member name.

DUMMY: A dummy data set name.
name: The 44-character name of a physical data set.
Attention: If you use log streams for extrapartition queue data sets, unpredictable results may occur.

ERROROPTION({IGNORE|SKIP}) (extrapartition queues only)

Specifies the action to be taken if an I/O error occurs. This can be one of the following:

IGNORE: The block that caused the error is accepted.
SKIP: The block that caused the error is skipped.

FACILITYID(terminal|connection) (intrapartition queues only)

Specifies a 4-character field that contains either:

The system identifier for an intrapartition queue that specifies ATIFACILITY(SYSTEM)
The terminal identifier where ATIFACILITY(TERMINAL) is specified.

If you do not specify anything in the FACILITYID field, it defaults to the name of the queue in each case.

If ATIFACILITY(FILE) is specified, the FACILITYID field must remain blank.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters: `A-Z 0-9 $ @ #` Any lowercase characters you enter are converted to uppercase.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters.

INDIRECTNAME(tdqueue) (indirect queues only)

Specifies the name of the transient data queue to which this indirect queue routes data. The transient data queue must be defined to CICS, and it can be intrapartition, extrapartition, remote, or indirect.

OPENTIME({INITIAL|DEFERRED}) (extrapartition queues only)

Specifies the initial status of the data set. The initial status can be one of the following values:

DEFERRED: The data set remains closed until you indicate that you want to open it by using the CEMT INQUIRE|SET TDQUEUE command.
INITIAL: The data set is to be opened at install time. However, if the DSNAME attribute is not specified, and the data set name is not specified in the DD statement in the startup JCL, the transient data queue is allocated to JES during CICS startup.

PRINTCONTROL({ASA|MACHINE|blank}) (extrapartition queues only)

Specifies the control characters to be used. There is no default.

If you allow RECORDFORMAT to default to blank, you cannot specify anything in the PRINTCONTROL field. You can use the following characters:

ASA: ASA control characters.
blank: No control characters are to be used.
MACHINE: Machine control characters.

RECORDFORMAT({FIXED|VARIABLE|blank) (extrapartition queues only)

Specifies the record format of the data set.

blank: If RECORDFORMAT is not specified (that is, remains blank), the BLOCKFORMAT and PRINTCONTROL fields must also remain blank. If the RECORDFORMAT is not specified in the resource definition, TD attempts to derive this attribute from the CICS startup JCL or from the QSAM data set definition at the time it attempts to open the queue. The open request will fail if this information cannot be derived from either of these sources.
FIXED: Fixed records. If you specify RECORDFormat(Fixed), you must also specify a block format.
VARIABLE: Variable records. If you specify RECORDFormat(Variable), you must also specify a block format.

RECORDSIZE({1|number}) (extrapartition and remote queues)

Specifies the record length in bytes, in the range 0 through 32767.

1: The default record length is 1 byte.
number: The record length, in bytes, up to 32767.

The maximum value you can specify depends on whether SYSOUTCLASS is specified, either explicitly or by default, and on whether RECORDFORMAT is FIXED or VARIABLE.

If you specify SYSOUTCLASS, the maximum value of RECORDSIZE is 8968.
For V format data sets, each logical record consists of a record descriptor followed by a data record. The value entered in the RECORDSIZE field must include 4 bytes for the record descriptor word (or LLBB), and should allow for the largest possible data record.

These limits are summarized in the description of the BLOCKSIZE attribute.

If the TDQUEUE is defined with RECORDSIZE(0), the record length is taken from the dataset DCB LRECL parameter for either input or output queues operations.

If the TDQUEUE is defined with a non-zero RECORDSIZE, the LENGTH parameter for the EXEC CICS READQ or the EXEC CICS WRITEQ command must equal the RECORDSIZE value, and the underlying DCB LRECL value is overridden.

RECOVSTATUS({NO|PHYSICAL|LOGICAL}) (intrapartition queues only)

Specifies the recoverability attributes of the queue in the event of an abnormal termination of either CICS or the transaction that is processing the queue. The recoverability attributes are:

LOGICAL

This queue is logically recoverable. Automatic logging is to be performed to keep track of accesses by application programs. If a transaction that accessed this queue was in-flight at the time of abnormal termination, or in the subsequent emergency restart or dynamic transaction backout, the queue is restored to the status it was in before the in-flight UOW modified it.

When this queue is accessed, the task that issued the DELETEQ TD, WRITEQ TD, or READQ TD command is enqueued on the input, the output, or both ends of the transient data queue. The enqueue is maintained until the task terminates (or issues a syncpoint request to signal the end of a UOW) to ensure the integrity of the data being accessed. This means that enqueues can be maintained for a longer time, and can result in a queue lockout if an application program accessing the queue performs more than one UOW against the queue without defining each separate UOW to CICS by issuing a syncpoint request.

Furthermore, when a DELETEQ request is issued for a logically recoverable queue, both the input and output ends of the queue are enqueued upon. This can increase the possibility of an enqueue lockout.

Note: CICS provides an enqueuing protection facility for logically recoverable (as distinct from physically recoverable) TD queues similar to that for recoverable files. However, CICS regards each logically recoverable destination as two separate recoverable resources—one for writing and one for reading.

In the case of a file record, a record is treated as a single resource and requires only one lock. The TD queue, on the other hand, has two 'ends'—the read end and the write end, and these can be enqueued on (locked) independently. This is because, to control both reading and writing from the TD queue (at the same time), CICS has to maintain two pointers (cursors)—one for reading and one for writing, and these need to be protected from conflicting transactions.

Queue records are held on one or more control intervals (CIs). Each CI is marked for release as soon as the last record on it has been read. However, the release does not occur until the end of task, or until after the next user syncpoint.

NO

This queue is not recoverable. Automatic logging is not performed to keep track of accesses to this queue. Queue records are held on one or more control intervals (CIs). Each CI is released as soon as the last record on it has been read.

PHYSICAL

This queue is physically recoverable. Automatic logging is to be performed to keep track of accesses by application programs. If emergency restart occurs, this queue is to be recovered to its status at the time CICS terminated.

The queue is not recovered to its status at the time CICS terminated if the last action on the queue was a READQ request, and if the associated unit of work (UOW) did not commit the changes. On emergency restart, the last read operation is backed out, and appears never to have taken place.

Queue records are held on one or more control intervals (CIs). Each CI is released as soon as the last record on it has been read.

REMOTENAME(tdqueue) (remote queues only)

Specifies, if the transient data queue resides on a remote system, the 4-character name by which the queue is known in the system or region on which the queue resides.

Acceptable characters: `A-Z a-z 0-9 $ @ # . / - _ % & ? ! : \| " = ¬ , ; < >`

REMOTELENGTH({1|number}) (remote queues only)

Specifies the length in bytes, in the range 1 through 32767.

For SYSOUT data sets, the value entered in the REMOTELENGTH field must not be greater than 8968 bytes (when the SYSOUTCLASS attribute has been specified).

1: The length is 1 byte.
number: The length in bytes, up to 32767.

If the queue is defined with TYPE=EXTRA, and no value is specified for REMOTELENGTH, the value on the RECORDSIZE attribute is used at installation time.

REMOTESYSTEM(connection)

Specifies the 4-character alphanumeric name of the system or region in which the remote transient data queue resides. The name entered must be the same as the name specified on the RDO CONNECTION or the first 4 characters of the name specified on an RDO IPCONN definition. For more information about the connection definitions, see CONNECTION attributes or IPCONN attributes.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

When the transient data queue definition is installed, the name entered in the REMOTESYSTEM attribute is compared with the system identifier. If the names are different, the system or region is remote. If the names are the same, the value specified in the TYPE attribute is used. If the TYPE attribute is blank, the installation fails.

REWIND({LEAVE|REREAD}) (extrapartition queues only)

Specifies the disposition of a tape data set. The disposition can be one of the following:

LEAVE: The current tape is positioned at the logical end of the data set.
REREAD: The current tape is positioned at the logical start of the data set.

SYSOUTCLASS({blank|A..Z|0..9|*}) (extrapartition queues only)

Instead of allocating an extrapartition queue to a physical data set, you can allocate it to a system output data set (referred to as SYSOUT). Use the SYSOUTCLASS attribute to specify the class of the SYSOUT data set.

blank

This is the default class.

A..Z|0..9

A single alphabetic or numeric character that represents an output class that has been set up on the z/OS system on which the CICS job is to run.

Acceptable characters: `A-Z 0-9` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

*

The class of the SYSOUT data set defaults to the class that is specified on the MSGLCASS parameter of the JOB statement for the CICS job.

You can use SYSOUTCLASS as an alternative to DSNAME. As with DSNAME, the queue may already be preallocated to SYSOUT using a JCL DD statement. A JCL DD statement overrides any specification made using the TDQUEUE resource definition.

When SYSOUT is specified for a queue in the JCL, attributes other than class can also be specified (for example, form types).

Note: Specifying SYSOUT data sets using RDO supports the class parameter only. If you require other parameters, you specify SYSOUT data sets in the JCL.

For more information about SYSOUT and its associated classes, see the z/OS MVS JCL User's Guide.

TDQUEUE(name)

Specifies the 1- to 4-character name of a transient data queue.

Acceptable characters: `A-Z a-z 0-9 $ @ # . / - _ % & ? ! : \| " = ¬ , ; < >`

If the name supplied is fewer than four characters, it is left-justified and padded with blanks up to four characters.

Note:

If you use a comma (,) in a name, you will be unable to use those commands such as
```
CEMT INQUIRE TDQUEUE(value1,value2)
CEMT SET     TDQUEUE(value1,value2)
```
where the comma serves as a list delimiter. See List of resource identifiers for information about using lists of resource identifiers.
If you protect your transient data queues using RACF®, avoid using % and & in the name. RACF commands assign a special meaning to these characters when they are used in a profile name. See Security for transient data.

TRANSID(transaction) (intrapartition queues only)

Specifies the name of the transaction that is to be automatically initiated when the trigger level is reached. Transactions are initiated in this way to read records from the queue. If the TRANSID attribute is not specified (or if TRIGGERLEVEL(0) is specified), you must use another method to schedule transactions to read records from transient data queues.

The transaction specified must not reside in a remote CICS system. If it does, transaction initiation fails and a warning message is issued to the console.

TRIGGERLEVEL({1|number}) (intrapartition queues only)

Specifies the number of records to be accumulated before a task is automatically initiated to process them. (This number is known as the trigger level.)

If you specify the TRANSID attribute, TRIGGERLEVEL defaults to 1. Specify a trigger level of 0 if you want to disable ATI processing. If you do not specify a transaction id, the trigger level is ignored.

If you have specified ATIFACILITY(TERMINAL), the task is not initiated until the specified terminal is available. If you have specified ATIFACILITY(FILE), a terminal is not necessary for the task to be initiated.

If, at maximum task, a short-on-storage or a no-space condition exists for a nonterminal destination, the task is not initiated. This is also true during stages 1 and 2 of initialization, and during the final stage of shutdown. The task is initiated when the stress condition no longer exists, and a subsequent TD WRITE occurs.

For logically recoverable transient data queues, the ATI task is not attached until the task commits forward. This may mean that the trigger level is far exceeded before ATI occurs.

If a z/OS® Communications Server terminal is defined as the destination for the CSTL transaction on two ISC CICS systems with a trigger level of 1, a performance problem may arise when both systems repeatedly acquire and release the terminal to write the session-started and session-ended messages.

You can change the trigger level when CICS is running using the CEMT transaction. If you reduce the trigger level to a number that is equal to (or less than) the number of records accumulated so far, the task is initiated when the next record is successfully put on the queue.

1: Only one record can accumulate.
number: The number of records that can accumulate (up to a maximum of 32767) before ATI occurs.

TYPE({EXTRA|INTRA|INDIRECT})

Specifies the following types of transient data queue:

EXTRA

A queue that is outside the CICS region is allocated to CICS.

Extrapartition queues are used for:

Sending data outside the CICS region: for example, data created by a transaction for processing by a batch program.
Retrieving data from outside the region: for example, data received from terminals as input to a transaction.

Extrapartition data is sequential and is managed by QSAM.

INDIRECT

An indirect queue is a queue that does not point to an actual data set, but to another queue. An indirect queue can be extrapartition, intrapartition, remote, or even another indirect queue.

For example, you can give a different symbolic name, INDIRECTDEST, to each of several different message types. You can then send all these message types to the same physical queue (INDIRECTDEST), or to different physical queues.

The DFH$TDWT sample program demonstrates how you can use indirect queues to send different categories of message to the same terminal. For programming information about DFH$TDWT, see Using the transient data write-to-terminal program (DFH$TDWT). DFH$TDWT sample definitions are given in the CICS/ESA 4.1 Sample Applications Guide.

If the QUEUE operand of an EXEC CICS WRITEQ TD, EXEC CICS READQ, or EXEC CICS DELETEQ command specifies an indirect queue, access is determined by the security setting of the final target queue.

INTRA

A queue for data that is to be stored temporarily.

An intrapartition destination can be a terminal, a file, or another system. A single data set, managed by VSAM, is used to hold the data for all intrapartition queues.

You can specify a transaction to process the records and a trigger level for each intrapartition queue. The trigger level represents a number of records that are allowed to accumulate before the specified transaction is initiated. See the description of the TRIGGERLEVEL attribute for more information about trigger levels.

The intrapartition queue can be defined as logically recoverable, physically recoverable, or not recoverable.

A logically recoverable queue is restored (after an individual transaction failure or a total system failure) to the status it had at the end of the last completed unit of work (UOW). (A UOW begins at start of task or at a syncpoint, and ends at end of task or at a syncpoint).

Physically recoverable queues are restored (after a total system failure) to the statuses they had when the system failure occurred.

TYPE=REMOTE cannot be specified on the TDQUEUE resource definition. If you want to define a remote transient data queue, leave the TYPE attribute blank and specify values for the remote attributes, REMOTELENGTH, REMOTENAME, and REMOTESYSTEM. Alternatively, you can include the remote attributes as part of the resource definitions for the other transient data queue types.

TYPEFILE({INPUT|OUTPUT|RDBACK})

Specifies the type of data set the queue is to be associated with.

INPUT: An input data set.
OUTPUT: An output data set.
RDBACK: An input data set that is to be read backward.
Note: This is appropriate only for data sets that have been defined on magnetic tape.

An extrapartition queue can be input or output, but not both.

For more information about the DCB macro fields, see z/OS DFSMS Macro Instructions for Data Sets.

USERID(userid) (intrapartition queues only)

Specifies the userid you want CICS to use for security checking when verifying the trigger-level transaction specified in the TRANSID field. The userid can be up to eight characters in length.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

The value entered in the USERID field is valid only when ATIFACILITY(FILE) is also specified.

When security is active, the trigger-level transaction runs under the authority of the specified userid. This userid must be authorized to all the resources used by the trigger-level transaction.

If you omit the userid from a transient data queue definition, CICS uses the CICS default userid, specified on the DFLTUSER system initialization parameter. Security checking takes place when you are installing an intrapartition definition containing a userid. If the security check fails, the resource definition for that intrapartition queue is not installed.

For further information about surrogate user security, see Transient data trigger-level transactions.

WAIT({YES|NO}) (intrapartition queues only)

Specifies whether an indoubt unit of work (UOW) that has modified a logically recoverable queue should wait for resynchronization with its coordinator to determine whether to commit or back out the changes.

NO: The UOW is not to wait. Any changes made to recoverable resources are to be backed out or committed, as specified by the ACTION attribute on the TRANSACTION resource definition.
YES: The UOW is to wait, and any action required while waiting is determined by the WAITACTION attribute.

This attribute overrides the WAIT attribute defined on the UOW's transaction definition. See Table 1 for an explanation of the interactions of indoubt attributes on the TDQUEUE and TRANSACTION definitions.

WAITACTION({REJECT|QUEUE}) (intrapartition queues only)

Specifies the action CICS is to take for an indoubt unit of work (UOW) if the definition for this queue specifies WAIT(YES). The possible actions are:

QUEUE

The UOW is indoubt and waiting; any locks held by the UOW for this queue remain active until the final state of the UOW is known. This means that tasks are suspended rather than receiving the LOCKED response. When the final state of the UOW is known, any changes that it has made are committed or backed out. Until then, any further requests of the following types that need one of the active locks must wait:

READQ, if the indoubt UOW had issued READQ or DELETEQ requests.
WRITEQ, if the indoubt UOW had issued WRITEQ or DELETEQ requests.
DELETEQ, if the indoubt UOW had issued READQ, WRITEQ or DELETEQ requests.

REJECT

The UOW is indoubt and is waiting. Any lock held by the UOW for this queue is retained until the final state of the UOW is known. When the final state is known, any changes the UOW has made are committed or backed out. Until then, any further request that needs one of the retained locks is rejected, and a LOCKED response is returned. WAITACTION=REJECT causes LOCKED to be raised in exactly the same circumstances as those in which QUEUE causes a transaction to wait.