Transient Data Definitions (TDD)

Transient Data Definitions (TDD) define each of the symbolic destinations to which, or from which, transient data is routed in the region. The name of every transient data queue that is available to the region must be defined to CICS® before the queue can be used by an application program. You can define remote and local queues in the TDD. Unlike temporary storage queues, transient data queues cannot be dynamically created by an EXEC CICS WRITEQ command from an application. The following attributes of the Transient Data Definitions (TDD) are described in this topic:
Note: Attribute names appear as they are used on the command line, followed in parentheses by the descriptions that are used by the AIX® System Management Interface Tool (SMIT).
<Key>
This attribute specifies the name of the transient data queue, and is the key for the TDD entry. CICS uses this name in the transient data operations to specify the destinations. Queue names are not supported by National Language Support (NLS) and can contain a maximum of four characters, from ! to ~ (33 through 126 decimal). The queue name must not start with the letter C or the letters “DFH” because these are reserved for defining the destinations that some CICS facilities require. For all the permanent database operations, and on a runtime database insert operation, CICS performs class-specific validation of the bytes that form the database key.

If you are using SMIT (CICS for AIX) to set this value, see Restrictions on the use of characters.

ActivateOnStartup (Activate the resource at cold start?)
This attribute specifies whether a resource definition is always copied from the permanent database to the runtime database at the cold start of a region. If the attribute is set to yes, the resource definition is always copied from the permanent database to the runtime database. If the attribute is set to no, the resource definition is not copied to the runtime database, unless its group has been specified in the Groups attribute of the Region Definitions (RD). The default value is yes.
AmendCounter (Number of updates)
This attribute is reserved for CICS internal use.
DestType (Type of Queue)
This attribute specifies whether the transient data queue is intrapartition, extrapartition, indirect, or remote. For further information, see About Transient Data Queues (TDQ). The default value is intrapartition.
ExtrapartitionFile (Filename or path for EP queue data file)
This attribute specifies the path and filename for the extrapartition queue. The file must be owned by cics. The default value is "".
FacilityId (System/Terminal for a triggered task)
This attribute specifies the identifier of the terminal or logical unit that caused a transaction to start (known as the principal facility). It can be a system identifier or terminal identifier, depending upon the value of the FacilityType attribute. If FacilityType is set to file, do not specify a value for FacilityId. The shorthand notations %R, %H, and %S are not expanded for FacilityId. For example, a value of “%H” really means the string “%H”. The default value is "". The FacilityId attribute is applicable only to intrapartition queues.
FacilityType (Type of facility allocated for triggered task)
This attribute specifies the type of principal facility that is allocated for a triggered task. The possible values are terminal, system, or file. If the value terminal is specified, the triggered transaction runs on the terminal that is specified by the FacilityId attribute. The terminal must exist for the transaction to run. If system is specified, CICS allocates a Distributed Transaction Processing (DTP) conversation with the remote system that is specified by FacilityId, before starting it up. The value file means that the triggered transaction runs as a nonfacility or background task, and does not have a terminal. The value of the FacilityId attribute is ignored. The default value is file.
GroupName (Group to which resource belongs)
This attribute specifies the name of a group to which this resource definition belongs. The name is specified in an 8-byte string. For cold starts, you can specify that CICS copies, from the permanent database to the runtime database, resource definitions that belong to groups that are named in the Groups attribute of the Region Definitions (RD). (This can be done in addition to setting the ActivateOnStartup attribute to yes for resources whose definitions are to be copied on startup from the permanent database to the runtime database.) The default value is "", which specifies no group.
IndirectQueueId (Indirect Queue Name)
This attribute specifies an alias for the transient data queue. The indirect destination does not point to an actual file, but to another destination, which can be extrapartition, intrapartition, or remote. It can even be another indirect destination. Specify a value for this attribute if an indirect queue is required. The value is specified in ASCII text. The shorthand notations %R, %H, and %S are not expanded for this attribute. For example, a value of “%H” really means the string “%H”. The default value is "".
IOMode (Input/Output Mode of EP Queue)
This attribute specifies whether an extrapartition queue is read-only (that is, data is read from the queue), or write-only (that is, data is written to the queue). The value input specifies that data is read, and the value output specifies that data is written to the queue. The default value is output.
MaxSize (Maximum size of the EP queue data file)
This attribute specifies the size of the file associated with the queue defined by the ExtrapartitionFile in bytes. If the value is set to 0, no check is made for the file size while writing to the ExtrapartitionFile. If the value is greater than 0, a check is made each time the transaction writes some data to the extrapartition file through EXEC CICS WRITEQ TD call. If the extrapartition file size is greater than this value, then ExtrapartitionFile is backed up as ExtrapartitionFile.timestamp. A new file is then opened as ExtrapartitionFile and the record is written to the new file. This attribute is only applicable for queues opened in output mode and will be ignored for the queues opened in input mode. The default value is 0. The maximum value is 4294967296, which is 4GB.

The size of CSMT.out file, which is defined as an extrapartition file in the TDD stanza, can be restricted by setting MaxSize attribute. Whenever the size of CSMT.out reaches the value mentioned in MaxSize, the file is backed-up and a new CSMT.out file will be created. In Windows, you may sometimes get "System error 13 while taking backup of CSMT.out file" in the console log if the CSMT.out file is used by some other application. This file is also used by the cicstail utility shipped with TXSeries. So when you see this message in the console log, closing the cicstail application temporarily for some time would allow the backup to complete.

OpenMode (Open EP output files truncated or append)
This attribute specifies whether CICS empties the output extrapartition transient data queue or appends data to it. The possible values are truncate, which specifies that the queue is emptied on startup or upon closing and reopening, and append, which specifies that data is always appended to the queue. The default value is truncate.
Note that CICS does not empty queues for which this attribute is set to append and MaxSize is set to 0, so those that grow too large must be emptied administratively. If CICS is offline, delete the file that is associated with the queue; the file is specified in the ExtrapartitionFile attribute. If CICS is online:
  1. Close and disable the queue by using the transaction CEMT SET TDQUEUE or the CICS command EXEC CICS SET TDQUEUE.
  2. Delete the file that is associated with the queue.
  3. Open and re-enable the queue by using the transaction CEMT SET TDQUEUE or the command EXEC CICS SET TDQUEUE.
For information about the transaction CEMT SET TDQUEUE, see CEMT INQ/SET TDQUEUE ; for information about the command EXEC CICS SET TDQUEUE, see SET TDQUEUE .

If MaxSize for this queue is greater than 0, CICS takes a backup of the existing file associated with the queue, as soon as the size of the file exceeds the MaxSize value. ExtrapartitionFile is closed and backed up as ExtrapartitionFile.timestamp. A new ExtrapartitionFile is opened and any further EXEC CICS WRITEQ TD calls will write to the newly opened file.

Permanent (Protect resource from modification?)
This attribute specifies whether amending or deleting the permanent database entry is permitted. If the attribute is set to no, the entry can be amended or deleted. If the attribute is set to yes, an entry cannot be modified or deleted. To change the entry, reset the attribute to no. After amending the entry, set the attribute back to yes. The default value is no.
RecordLen (Record length for fixed length EP queue)
This attribute specifies a numeric value for the length of records in files that store the extrapartition transient data queue. The value is used only if the DestType attribute is set to extrapartition and the RecordType attribute is set to fixed_length. The default value is 1024.
RecordTerminator (ASCII value of terminator for fixed length queue)
This attribute specifies the record delimiter of transient data queue records in a three-digit ASCII number. This value is used only if the DestType attribute is set to extrapartition and the RecordType attribute is set to byte_terminated. The default value is 000.
RecordType (Record organization for EP queue data file)
This attribute specifies the format of the file that is used to store the extrapartition transient data queue. The possible values are fixed_length, variable_length, line_oriented, null_terminated, and byte_terminated. The default value is fixed_length.
RecoveryType (Recoverability type of IP queue)
This attribute specifies whether an intrapartition destination is logically recoverable, physically recoverable, or not recoverable. The possible values are logical, physical, and none.

Logically recoverable destinations are restored (after the abnormal termination of an individual transaction or the region) to their status at the end of the last completed Logical Unit of Work (LUW).

CICS restores physically recoverable destinations (after an abnormal termination of the region) to their status at the time when the abnormal termination occurred. CICS restores the last record read, enabling it to be read again if a possibility exists that the reader did not have a chance to process it. The default value is logical.

RemoteName (Remote Queue Name)
This attribute specifies the name by which a queue that resides in a remote region is known there. The value is specified by four ASCII characters. If a value is not specified for this attribute, CICS sends the local identifier to the remote region. If more than one region has a destination with the same name, the local key allows the definition of an alias that routes a transient data request to a specific region. A transient data request that is using the alias identifies the remote name and the region to which the request is shipped. The shorthand notations %R, %H, and %S are not expanded for this attribute. For example, a value of “%H” really means the string “%H”. The default value is "".
RemoteSysId (Remote System Identifier)
This attribute specifies the name of a Communications Definitions (CD) entry that defines a connection to the remote region for a queue that is located on a remote region. The default value is "", meaning that the file queue resides on the local region.
ResourceDescription (Resource description)
This attribute specifies this TDD entry with a 30-byte string. The default value is “Transient Data Definition”.
RSLKey (Resource Level Security Key)
This attribute specifies the resource security key for this transient data queue, in the range 1 through 24. If a transaction issues a request to write to this journal, and the user of the transaction does not have this RSLKey value in the RSLKeyList attribute in the user's User Definitions (UD) entry, CICS raises the NOTAUTH condition. Alternatively, you can specify the value public or private. With public, any user can access the queue. With private, CICS allows access to the queue only from transactions that have the attribute RSLCheck set to none in their Transaction Definitions (TD) entries. The default value is private.

For more information about resource security, see Authorizing user access to CICS resources.

TemplateDefined (Is a user conversion template defined?)
This attribute specifies whether or not a conversion template exists that describes the transient data record. The possible values are yes and no. If this transient data queue can be accessed from a non-ASCII region, or if the queue contains binary or user-defined data, you must define such a template. If such a template exists, set this attribute to yes; otherwise set it to no. The default value is no.
TriggeredTransId (Triggered Transaction Identifier)
This attribute specifies the transaction that is automatically initiated when the value of the TriggerLevel attribute is reached. The purpose of transactions that are initiated in this way is to read records from the destination. If you do not specify a value for this attribute, or if a value of zero is set for the TriggerLevel attribute, another way must be used to schedule transactions to read records from the destination. This transaction must not reside in a remote CICS region. If it does, an abnormal termination occurs when an attempt is made to initiate it. The default value is "". The TriggeredTransId attribute is applicable only to intrapartition queues.
TriggerLevel (Trigger Level)
This attribute specifies the number of committed records that are accumulated before a task is automatically initiated to process them. The value is set in the range 0 through 32767. The default value is 0. The TriggerLevel attribute is applicable only to intrapartition queues.
WhenOpened (Time at which queue is to be opened)
This attribute specifies whether CICS opens the transient data queue at startup or on request. It applies to extrapartition queues only. The possible settings are at_startup and on_request. The default value is at_startup. Note that you must use CEMT to open and close a TD queue. See CEMT INQ/SET TDQUEUE for more information.