Transaction definition attributes

The transaction definition attribute descriptions are:

Action
specifies the action to be taken when a CICS® region fails, or loses connectivity with its coordinator, during two-phase commit processing after the unit of work has entered the in-doubt period. The action depends on the WAIT attribute. If WAIT specifies YES, ACTION has no effect unless the WAITTIME expires before recovery from the failure.

If WAIT specifies NO, the action taken is one of the following:

BACKOUT
All changes made to recoverable resources are backed out, and the resources are returned to the state they were in before the start of the UOW.
COMMIT
All changes made to recoverable resources are committed, and the UOW is marked as completed.
Alias
allows you to specify an alias transaction name for this transaction. The name may be up to four characters in length.
Brexit
This parameter is a name which may be up to 8 characters in length. If you specify a value for Brexit then you must not also specify a value for Remotename or Remotesystem. You also must not specify Dynamic(YES) or Restart(YES).

CICS for CICS Transaction Server Release 2 uses Brexit in a different way to the way in which CICS in subsequent releases uses Brexit. For CICS Transaction Server Release 2, this is an optional parameter that defines the name of the bridge exit associated with this bridge transaction. The presence of a Brexit value identifies the transaction as a bridge transaction. Brexit should not be specified for a user transaction.

For CICS Transaction Server for z/OS®, Version 3 Release 1 and subsequent releases, this is an optional parameter that defines the name of the default bridge exit to be associated with this transaction, if it is started in the 3270 bridge environment with a START BREXIT command, and BREXIT specifies no name. These differences mean that transaction definitions that include the Brexit keyword are slightly different depending upon whether you intend to install the transaction definition into a CICS system that runs at CICS Transaction Server Release 2 or into a CICS system at a subsequent release. The difference affects the way in which the Program keyword is specified.

If you intend to install your transaction definition into a CICS system running CICS Transaction Server Release 2, you must not specify the Program keyword. If you intend to install your transaction definition into a CICS system running a higher level of the CICS Transaction Server, you must specify the Program keyword.

Cmdesc
specifies whether security checking is to be applied on system programming commands. For programming information on the system programming commands, see the CICS System Programming Reference.
NO
No check is made. The commands are always executed.
YES
A call is made to the external security manager (ESM). CICS either authorizes or prevents access. If the ESM cannot identify the resource or resource type, access is prevented.
Description
(Optional.) Specifies a 1- to 30-character description of the resource.
Dtimeout
specifies whether deadlock time-out is be applied to the task. If the execution of the task gets suspended (for example, through lack of storage), a purge of the task is initiated if the task stays suspended for longer than the Dtimout value.
Confdata
specifies whether CICS is to suppress user data from CICS trace entries when the CONFDATA system initialization parameter specifies HIDETC.
Dump
specifies whether a call is to be made to the dump domain to produce a transaction dump if the transaction terminates abnormally.
YES
CICS calls the dump domain to produce a transaction dump.
NO
No call is made to the dump domain, suppressing any potential transaction dump.
Dynamic
specifies whether the transaction can be dynamically routed to a remote region, using the CICS dynamic transaction routing facility.
NO
Creates a local or remote definition according to the REMOTESYSTEM attribute.
YES
Allows the dynamic transaction routing program to determine the local or remote status dynamically at invocation time. For programming information about the dynamic transaction routing program, see the CICS Customization Guide.
Extsec
For systems running CICS/MVS™ 2.1.2, specify YES or NO to indicate whether an external security manager (ESM) is to be used for transaction or resource security checking. If the Extsec value does not apply to this definition, specify N/A.
Indoubt
For systems running a version of CICS prior to CICS TS for OS/390, specify the action required if the transaction is using intercommunication and abends at a critical time during syncpoint or abend processing:
BACKOUT
The effects of the transaction are backed out.
COMMIT
The effects of the transaction are committed.
WAIT
Changes to recoverable temporary storage are locked until the session is recovered. The resources are then committed or backed out in step with the remote system.
Isolate
specifies whether CICS is to isolate the transaction’s user-key task-lifetime storage to provide transaction-to-transaction protection. (See the TASKDATAKEY attribute for a description of user-key storage.) Isolation means that the user-key task-lifetime storage is protected from both reading and writing by the user-key programs of other transactions--that is, from programs defined with EXECKEY(USER).
Notes:
  1. The ISOLATE attribute does not provide any protection against application programs that execute in CICS key--that is, from programs defined with EXECKEY(CICS).
  2. VSAM nonshared resources (NSR) are not supported for transactions that use transaction isolation. You should specify ISOLATE(NO) when you define transactions that access VSAM files using NSR.
YES
The transaction’s user-key task-lifetime storage is isolated from the user-key programs of all other transactions--that is, from programs defined with EXECKEY(USER), but not from programs defined with EXECKEY(CICS).

Also, the user-key task-lifetime storage of all other transactions is protected from the user-key programs of transactions defined with ISOLATE(YES).

NO
If you specify ISOLATE(NO), the transaction’s task-lifetime storage is isolated from the user-key programs of those transactions defined with ISOLATE(YES). The transaction’s storage is not, however, isolated from user-key programs of other transactions that also specify ISOLATE(NO) because, with this option, the transactions are all allocated to the common subspace.

Note also that the user-key task-lifetime storage of all transactions defined with ISOLATE(YES) is protected from the user-key programs of transactions defined with ISOLATE(NO).

Specify ISOLATE(NO) for those transactions that share any part of their user-key task-lifetime storage.

Localq
specifies whether queuing on the local system is to be performed.
NO
No local queuing is to be performed.
YES
Local queuing can be attempted for an EXEC START NOCHECK request when the system is not available and the system name is valid.
N/A
The Localq attribute does not apply to this definition.
Name
Specify a 1- to 4-character ID for the transaction definition.
OTSTimout
specifies, in hours, minutes, and seconds, the length of time for which an Object Transaction Service (OTS) transaction, created in an enterprise beans environment and executing as a task under this CICS transaction, is allowed to execute before the initiator of the OTS transaction must take a syncpoint or roll back the transaction. If the specified period expires, CICS purges the task.

The initiator of the OTS transaction may be:

Methods of session beans that manage their own OTS transactions can override the default timeout value by using the setTransactionTimeout method of the javax.Transaction.UserTransaction interface.

NO
OTS transactions will not time out. This is the default.
1-240000
The period of time (in HHMMSS format) before the task is purged. The maximum period is 24 hours (240000).
Partitionset
specifies the name of the partition set that is to be the default application partition set. The name can be up to eight characters in length.
PrimedSize
For systems running CICS/MVS 2.1.2, identify the primed storage allocation size in bytes:
0
CICS will handle storage for the control blocks.
value
A storage allocation, in the range 1 through 65520.
If you leave this field blank, CICSPlex® SM uses the default value for your CICS environment, if there is one.
Priority
specifies the transaction priority. This 1-to 3-digit decimal value from 0 to 255 is used in establishing the overall transaction processing priority. If you leave this field blank, CICSPlex SM uses the default value for your CICS environment, if there is one.
Profile
is the name of the PROFILE definition that specifies the processing options used in conjunction with the terminal that initiated the transaction.
The default is DFHCICST.

The name may be up to 8 characters in length.

Program
specifies the name of the program to which CICS gives control to process this transaction. The name can be up to eight characters in length.

If this transaction definition is for use on a remote program link request, the program name you specify in this attribute must be the name of the CICS mirror program, DFHMIRS.

Remotename
specifies the name of this transaction as it is known in a remote system, if it is to be executed in a remote system or region using intersystem communication. The remote system can be another CICS region or an IMS™ system. REMOTENAME can be 1 through 4 characters in length if the REMOTESYSTEM attribute specifies another CICS region, or 1 through 8 characters in length if REMOTESYSTEM specifies an IMS system.

If you specify a remote name, CICSPlex SM uses that name when assigning the transaction to a related system. If you specify a remote system but not a remote name, the local name (that is, the name of this transaction definition) is used in both the target and related systems.

Note:
If you specify a value for Brexit than you must not also specify a value for Remotename.
Remote Sysid

(Optional.) specify the name of the connection that links the target system to the related system where the transaction resides. If this parameter is not supplied, the connection name is derived directly from the CICS sytsem id of the related system.

The name may be up to 4 characters in length.

CICSPlex SM uses this system ID only if the transaction is part of a resource group that is directly associated with a resource description (via RESINDSC). If the transaction is being assigned by a resource assignmnet (RASGNDEF), CICSPlex SM uses the actual CICS system ID of the related system.

Note:
One, and only one, of the fields Program, Remote Sysid, and Brexit must be specified.
RESGROUP
(Optional.) Specify the name of an existing resource group to which the definition is to be automatically added.
Ressec
specifies whether resource security checking is to be used for resources accessed by this transaction.
NO
All resources are available to any user who has the authority to use this transaction.
YES
An external security manager is used.
Restart
specifies whether the transaction restart facility is to be used to restart those tasks that terminate abnormally and are subsequently backed out by the dynamic transaction backout facility.
Routable
specifies whether, if the transaction is the subject of an eligible EXEC CICS START command, it will be routed using the enhanced routing method.
NO
If the transaction is the subject of a START command, it will be routed using the "traditional" method.

The transaction should not be dynamically routed.

YES
If the transaction is the subject of an eligible START command, it will be routed using the enhanced method.

The transaction should be dynamically routed.

If you specify ROUTABLE(YES), you must not also specify LOCALQ(YES).

For details of the enhanced and "traditional" methods of routing transactions invoked by EXEC CICS START commands, see the CICS Intercommunication Guide.

The RSL attribute is not valid in CICS Transaction Server for z/OS. See the CICS Resource Definition Guide for information.
Runaway
The amount of time, in milliseconds, for which any task running under this transaction definition can have control of the processor before it is assumed to be in a runaway condition (logical loop). When this interval expires, CICS can abnormally terminate the task.
SYSTEM
CICS is to use the ICVR system initialization parameter value as the runaway time limit for this transaction.
0
There is no limit and no runaway task detection is required for the transaction.
0-2700000
The runaway time limit in the range 0 through 2700000.

If this field is blank CICSPlex SM uses the default value for your CICS environment if there is one.

Shutdown
applies to transactions associated with a terminal, and indicates whether the transaction can be run during CICS shutdown. This supplements the XLT option on EXEC CICS PERFORM SHUTDOWN. For a transaction to be attached during shutdown, it must either be defined as SHUTDOWN(ENABLED) or be named in the XLT specified in the EXEC CICS SHUTDOWN command.
DISABLED
The transaction is disabled from running during CICS shutdown.
ENABLED
The transaction is enabled to run during CICS shutdown.
Spurge
specifies whether the transaction is initially "system purgeable" or not.

SPURGE=NO prevents a transaction being purged by the deadlock time-out (DTIMOUT) facility, an EXEC CICS ... PURGE command, TWAOCT (Cancel Task) being set in the node error program (NEP), or a CEMT SET ... PURGE command.

SPURGE=YES allows such purges to go ahead as far as the user is concerned. CICS may, however, prevent the purge if it is not safe to allow a purge at the point the transaction has reached.

Note that SPURGE=NO does not prevent a transaction being purged by the read time-out (RTIMOUT) facility, an EXEC CICS SET ... FORCEPURGE command, or a CEMT SET TRANSACTION(tranid) FORCEPURGE command. SPURGE determines only the initial value, which can be changed by the transaction while it is running.

NO
The transaction is not initially system purgeable.
YES
The transaction is initially system purgeable.
Status
specifies the transaction status.
ENABLED
Allows the transaction to be executed normally.
DISABLED
Prevents the transaction being executed.
Storageclear
specifies whether task-lifetime storage for this transaction is to be cleared on release. This can be used to prevent other tasks accidentally viewing any confidential or sensitive data that was being stored by this transaction in task lifetime storage.
Taskdatakey
specifies the storage key of the storage CICS allocates at task initialization for the duration of the task (task-lifetime storage), and which is accessible by the application. These storage areas are the EXEC interface block (EIB) and the transaction work area (TWA).

TASKDATAKEY also specifies the key of the storage that CICS obtains on behalf of all programs that run under the transaction. The program-related storage that CICS allocates in the specified key includes:

You must specify TASKDATAKEY(USER) if any of the programs in the transaction is defined with EXECKEY(USER). If you specify TASKDATAKEY(CICS) for a transaction, an attempt to run any program in user key under this transaction leads to a task abend, with abend code AEZD.

USER
CICS obtains user-key storage for this transaction. Application programs executing in any key can both read and modify these storage areas.
Note:
User-key programs of transactions defined with ISOLATE(YES) have access only to the user-key task-lifetime storage of their own tasks.

User-key programs of transactions defined with ISOLATE(NO) also have access to the user-key task-lifetime storage of other tasks defined with ISOLATE(NO).

See the description of the EXECKEY attribute on the PROGRAM definition for more information about task storage protection.

CICS
CICS obtains CICS-key storage for this transaction. Application programs executing in CICS key can both read and modify these storage areas. Application programs executing in user key can only read these storage areas.
Taskdataloc
specifies whether task life-time storage acquired by CICS for the duration of the transaction can be located above the 16MB line in virtual storage. These areas, which relate to specific CICS tasks, include the EXEC interface block (EIB) and the transaction work area (TWA).

You must specify TASKDATALOC(BELOW) if any of the programs that make up the transaction runs in 24-bit addressing mode (this also applies to task-related user exits running on behalf of the transaction).

For transactions that do not satisfy any of these conditions, you can specify ANY to obtain the associated virtual storage constraint relief.

CICS polices the use of TASKDATALOC(ANY). In particular:

BELOW
Storage areas that CICS acquires for the transaction must be located below the 16MB line.
ANY
Storage areas that CICS acquires for the transaction can be located above the 16MB line in virtual storage.
Taskreq
specifies whether a transaction is to be initiated by pressing a PF key, by using a light pen, or by using a card. Possible values are:

Here are some notes on the use of PF and PA keys:

Tclass
As a result of the introduction of TRANCLASS, the TCLASS attribute is obsolete in CICS Transaction Server for z/OS. If you already use TCLASS, you can still access it by using compatibility mode (see the CICS Resource Definition Guide for information). See the CICS Resource Definition Guide for a description of TCLASS.
TPname
specifies the name of the transaction that may be used by an APPC partner if the 4-character length limitation of the TRANSACTION attribute is too restrictive. This name can be up to 64 characters in length.
Tpurge
specifies (for non-VTAM terminals only) whether the transaction can be purged because of a terminal error.
NO
The task cannot be purged when a terminal error occurs.
YES
The task can be purged when a terminal error occurs.
Trace
specifies whether the activity of this transaction is to be traced.
YES
Trace the activity for this transaction.
NO
Do not trace the activity for this transaction.
Tranclass
specifies the name of the transaction class to which the transaction belongs. Transactions belonging to a transaction class are subject to scheduling constraints before they are allowed to execute. The reserved TRANCLASS name DFHTCL00 is used to indicate that the transaction does not belong to any transaction class.

The name may be up to 8 characters in length.

Transec
The TRANSEC attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. See the CICS Resource Definition Guide for more information.
Trprof
specifies for remote transactions the name of the PROFILE for the session that carries intersystem flows during ISC transaction routing. The name can be up to eight characters in length.

The default is DFHCICSS>

TWAsize
specifies the size (in bytes) of the transaction work area to be acquired for this transaction. Specify a 1-to 5-digit decimal value in the range 0 through 32767.
Notes:
  1. Your storage may be corrupted if your TWASIZE is too small.
  2. Do not change the TWASIZE of the CICS-supplied transactions.
User data
(Optional.) Three 8-character fields provided for any site-specific data related to the transaction. CICSPlex SM makes no use of this user data.
Version
(Optional.) Specify an integer in the range 1 through 15. Specify 0 or leave blank for CICSPlex SM to assign the first available version id in the range 1 through 15.
Wait
specifies whether an in-doubt unit of work (UOW) is to wait, pending recovery from a failure that occurs after the UOW has entered the in-doubt state.
YES
The UOW is to wait, pending recovery from the failure, to resolve its in-doubt state and determine whether recoverable resources are to be backed out or committed. In other words, the UOW is to be shunted.
NO
The UOW is not to wait. CICS immediately takes whatever action is specified on the ACTION attribute.
Waittime
specifies how long a transaction is to wait before taking an arbitrary decision about an in-doubt unit of work, based on what is specified in the ACTION attribute.
00,00,00
The transaction waits indefinitely.
dd,hh,mm
The time, in days, hours, and minutes, for which the transaction is to wait. The maximum value is 93,23,59.

WAITTIME takes effect only if WAIT(YES) is specified.

If you leave these fields blank, CICSPlex SM uses the default values for your CICS environment, if there are any.

XTPname
This attribute may be used as an alternative to TPNAME. Enter a hexadecimal string up to 128 characters in length, representing the name of the transaction that may be used by an APPC partner. All hexadecimal combinations are acceptable except X'40'.
XTRANID(value)
You can use this optional attribute to specify another name to be used instead of the TRANSACTION name for initiating transactions. The name may be up to eight hexadecimal digits in length. Because XTRANID is specified in hexadecimal form, you can use a name that contains characters that you cannot specify in the TRANSACTION attribute.

(See also TASKREQ, another transaction alias that can be specified.)

value
A 4-byte transaction identifier in hexadecimal notation (the identifier therefore uses up to eight hexadecimal digits). If you specify fewer than eight hexadecimal digits, the identifier is padded on the right with blanks.

Certain values are reserved for use by CICS, and so there are restrictions on the values you can specify:

  • The first byte must not be X'C3'.
  • The first byte must not be less than or equal to X'40'.
  • The value must not be X'00000000'.
  • The last three bytes must not be X'FFFFFF'.

Avoid using values in the range X'00' through X'3F' in the second, third and fouth bytes if the transaction is to be attached by unsolicited data received from a terminal defined as a 3270 device, because CICS will interpret these values as control characters, and not as part of the transaction identifier. For example, if you issue EXEC CICS RETURN or EXEC CICS START and specify TRANSID(X'41303238'), then the correct transaction will be attached. However, if you issue EXEC CICS RETURN without specifying a TRANSID, and the 3270 device transmits data that begins with X'41303238', CICS will attempt to attach a transaction as if X'41404040' had been transmitted.

Additional attributes required for systems running CICS/MVS 2.1.2 or CICS/ESA 3.3 only are:

Tclass
For systems running CICS/MVS 2.1.2 or CICS/ESA 3.3, identify the class associated with the task:
NO
No class is assigned to the task.
value
A class value, in the range 1 through 10.
If you leave this field blank, CICSPlex SM uses the default value for your CICS environment, if there is one.
PrimedSize
For systems running CICS/MVS 2.1.2, identify the primed storage allocation size in bytes:
0
CICS will handle storage for the control blocks.
value
A storage allocation, in the range 1 through 65520.
If you leave this field blank, CICSPlex SM uses the default value for your CICS environment, if there is one.
Extsec
For systems running CICS/MVS 2.1.2, specify YES or NO to indicate whether an external security manager (ESM) is to be used for transaction or resource security checking. If the Extsec value does not apply to this definition, specify N/A.
Transec
For systems running CICS/MVS 2.1.2, specify a transaction security value in the range 1 through 64. A value of 1 means the transaction is not secured.

If you leave this field blank, CICSPlex SM uses the default value for your CICS environment, if there is one.

Rsl
For CICS/MVS 2.1.2 systems, specify the resource security value to be associated with the transaction:
0
Transactions with RSL checking specified are not allowed to access the transaction.
value
A resource security value, in the range 1 through 24.
PUBLIC
Any transaction is allowed to access the transaction.
If you leave this field blank, CICSPlex SM uses the default value for your CICS environment, if there is one.
Routable
Specify whether or not the transaction, when invoked using an EXEC CICS START TERMID TRANSID command, is eligible for shipping to the TOR (the routing region) for dynamic routing.
YES
The transaction is eligible for shipping to the TOR for dynamic routing.
NO
The transaction is not eligible for shipping to the TOR for dynamic routing.

Related concepts
Transaction resource definitions
CICS Resource Definition Guide
Related tasks
Accessing BAS transaction definitions
Working with the TRANDEF view
Defining transactions using BAS
Installing BAS transaction definitions
[[ Contents Previous Page | Next Page Index ]]