Version 8.1.2
 —  Adabas Transaction Manager Parameters  —

Runtime Parameters

This section describes the runtime parameters used for Adabas Transaction Manager.


ATM Runtime Parameters

ATM execution is controlled mainly through ADARUN (ADARUN DDCARD input) runtime parameters. When executing the ATM transaction manager, the parameter setting ADARUN DTP=TM must be provided. All other ATM runtime parameters, all of which begin with “TM”, will be effective only when ADARUN DTP=TM is specified. They are ignored for all other values of DTP. For more information on the DTP parameter, see the Adabas Operations documentation.

Note:
Adabas databases that participate in two-phase commit processing must execute as resource managers with ADARUN DTP=RM.

Note:
ADARUN NONDES=YES (non-descriptor search allowed) is required for the ATM transaction manager.

The following section describes each ATM runtime parameter:

TMDRQ : Size of ATM Request Queue

Parameter Type Use Possible Values Default
Runtime

Sets the number of entries allowed in the transaction manager’s internal request queue.

10 - 32767 10

The ATM transaction manager uses an internal request queue for scheduling some of the tasks it needs to perform. The TMDRQ parameter determines the total number of entries in the queue that is used to service certain incoming, asynchronous requests. This queue is currently used only when the ATM RRMS interface is active.

RRMS Considerations

When the RRMS interface is in use, the ATM dynamic request queue (DRQ) is used for communication between ATM RRMS exits and the ATM manager. The value specified for the TMDRQ parameter should therefore be increased if RRMS is to be used. Consider the number of global transactions that may reach a syncpoint at the same time, and increase TMDRQ by this number. You can specify a higher value, for safety, without incurring any performance degradation.

You can use Online Services to monitor usage of the DRQ. If you specify too small a value and the DRQ becomes full, backouts resulting in response code 9 are likely to occur.

Example

ATM will allow 250 entries in its internal request queue.

ADARUN PROG=ADANUC,DTP=TM,TMDRQ=250

TMETDATA : ET Data Control

Parameter Type Use Possible Values Default
Runtime

Location of ET data

ATM | TARGETS TARGETS

The TMETDATA parameter determines the database or databases that will store ET data. The same TMETDATA parameter value must be specified for all Adabas Transaction Manager (ATM) instances on the network.

Possible values:

Value Explanation
ATM

ET data is always stored in and read from the ATM transaction manager’s database, without regard to the database ID indicated by the Adabas command.

  • treats ET data as belonging to a global transaction rather than to a database;

  • there is just one copy of a client’s ET data in a system;

  • eliminates confusion resulting from the existence of different ET data in different databases under the same ETID;

  • overrides the Natural ETDB parameter;

  • should not be used if the EmergencySerialETs runtime control will be set to YES or FORCE for any client environment in which ET data is stored or read.

TARGETS

ET data is stored during the commit process in all changed databases that are running with DTP=RM.

ET data that is stored by an ET or CL command is always stored in the database that is the target of the command, whether or not that database runs with DTP=RM. It the database runs with DTP=NO, the ET data is written to the database only after any open global transaction has been committed.

If the client storing ET data is at global transaction status, ATM is not required to carry out any commit processing; the data is simply stored in the database indicated by the Adabas command. ET data is always read from the database specified in the Adabas command.

  • treats ET data as belonging to a database or a local database transaction rather than to a global transaction;

  • a client’s ET data might exist in several databases in a system;

  • a client can have several different ET data values in different databases at the same time;

  • means that 3GL application programs using ET data must have knowledge of the database that holds ET data for a given transaction;

  • honors the Natural ETDB parameter.

Notes:

  1. The recommended setting for this parameter is the default, TARGETS. This setting eliminates the dangers associated with running in serial mode when the transaction manager is unavailable.
  2. See also the section entitled ET Data Storage in your Adabas Transaction Manager operations documentation.

Example

ET data is to be stored in the transaction manager's database only.

ADARUN PROG=ADANUC,DTP=TM,TMETDATA=ATM

TMGTT : Global Transaction Time Limit

Parameter Type Use Possible Values Default
Runtime

Sets time limit during which a global transaction can be open without being prepared.

1 - 16777215 720

The TMGTT parameter approximately specifies the maximum elapsed time, in units of 1.048576 seconds, that a global transaction can remain open without being prepared. If the limit is exceeded, ATM automatically backs out the global transaction from all affected databases. The next time the client issues a transactional Adabas command, a response code 9 is returned.

It is recommended that TMGTT be smaller than the lowest TT parameter of any database running with DTP=RM.

The TMGTT parameter does not supersede the TT parameter settings of other databases. If a database times out a client who has an unprepared global transaction open, the global transaction is subsequently backed out. A response code 9 is returned if the client then issues a transactional command.

Note:
Transaction timout can happen when a client session stops issuing commands for a period of time. In these circumstances the transaction manager has no opportunity to give a response code to the client, to indicate that the timeout has taken place. In such cases, the pending response code will be preserved and returned to the client at the first possible opportunity. For further details, please refer to Pending Response Codes in the Adabas Transaction Manager introduction.

Example

ATM will back out global transactions that are not prepared within about 600 seconds (10 minutes) of the first transactional command.

ADARUN PROG=ADANUC,DTP=TM,TMGTT=600

TMLOG : ATM Manager Logging Control

Parameter Type Use Possible Values Default
Runtime Controls the logging option for the current execution of the ATM manager. YES | NO | NEVER NO

The ATM manager can log internal events for diagnostic purposes using a dual logging system. It can

Possible values:

Value Description
YES The ATM manager writes every record to an ATMLOG dataset. The ATM manager keeps a record of the latest internal events in its global log buffer area. It also maintains the contents of log buffer areas related to open global transactions. Logging to the ATMLOG datasets can be deactivated at any time using the operator command TM NOLOG.
NO The ATM manager will not write log records to the ATMLOG datasets. Logging to the ATMLOG datasets can be activated at any time using the operator command TM LOG. The ATM manager keeps a record of the latest internal events in its global log buffer area; it also maintains the contents of log buffer areas related to open global transactions.
NEVER ATM logging is disabled for the duration of this execution of the ATM manager.

On z/OS and VSE systems, if the ATM manager writes log records to the ATMLOG (TMLOG=YES or TM LOG issued) and the dataset currently in use becomes full, the manager closes that dataset and switches to the other dataset. Automatic log switching currently does not take place on BS2000 systems. A system message might appear in the console log, indicating that the first log dataset has become full. You may also switch between the two ATMLOG datasets by using the operator command TM FEOFLOG. Whenever the ATMLOG datasets are switched, a message is displayed on the console indicating the dataset that is currently in use.

Example

The ATM manager is to maintain its internal log buffer areas and write all log records to the ATMLOG datasets.

ADARUN PROG=ADANUC,DTP=TM,TMLOG=YES

TMMSGSEV : Severity Threshold for Warning Messages

Parameter Type Use Possible Values Default
Runtime Sets severity threshold for the suppression of warning messages. 0 | 4 | 8 0

Every message that the ATM manager sends to the console and to the DDPRINT dataset has a severity level. Message severity levels are explained in the Adabas Transaction Manager Messages and Codes.

Using the TMMSGSEV parameter, you can prevent messages with low severity levels from being written to the console by the ATM manager. This parameter has no effect on messages that are issued by the ATM client proxy, or during the early part of the transaction manager’s initialization.

All messages created by the ATM manager are written to DDPRINT regardless of the TMMSGSEV specification.

Possible values:

Value Description
0 No messages are suppressed.
4 Messages of severity less than 4 are not sent to the console.
8 Messages of severity less than 8 are not sent to the console.

Example

The ATM manager should not send message of severity less than 4 to the console.

ADARUN PROG=ADANUC,DTP=TM,TMMSGEV=4

TMRESTART : ATM Restart Control

Parameter Type Use Possible Values Default
Runtime Controls restart handling of problematic transactions. NORMAL | FORCE | FORCEALL NORMAL

When an ATM manager restarts, it rebuilds its global transaction list as nearly as possible to its latest state when it was last executing. It then attempts to complete or back out any incomplete global transactions. The TMRESTART parameter determines the manager’s restart action with regard to global transactions and transaction branches that remain incomplete at the end of this process.

Possible values:

Value Description
NORMAL Any incomplete transactions remain in an incomplete state until such time as they can be completed.
FORCE ATM transfers to the suspect transaction journal (STJ) the details of every incomplete global transaction that has its root local to this ATM manager. The details of these transactions are deleted from ATM’s recovery information, the originating clients are closed, and any related internal resources are freed. ATM can no longer guarantee integrity for such global transactions.
FORCEALL Details of all unresolved global transactions and transaction branches are transferred to the STJ. The details are deleted from ATM’s recovery information, the originating clients are closed, and any related internal resources are freed. ATM can no longer guarantee integrity for the affected global transactions.

Example

After recording them in the STJ, the ATM manager is to discard details of any global transactions that it owns, and that remain incomplete at the end of its restart processing.

ADARUN PROG=ADANUC,DTP=TM,TMRESTART=FORCE

TMSYNCMGR : Support for External Transaction Coordinators

Parameter Type Use Possible Values Default
Runtime Indicates whether or not the ATM manager is to interact with an external transaction coordinator. NONE | RRMS NONE

The TMSYNCMGR parameter determines whether or not the ATM manager registers and interacts with an external transaction coordinator.

Possible values:

Value Description
NONE The ATM manager will not interact proactively with an external transaction coordinator. This setting does not preclude the use of the CICS Syncpoint Manager, which interfaces directly with the ATM’s client proxy component and not with the ATM manager.
RRMS The ATM manager will register with the IBM Recoverable Resource Management Services so that it can participate in transactions that involve other RRMS-enabled resource managers. This parameter value is valid only for z/OS systems in which RRS (a component of RRMS) is active. The current version of ATM offers participation in RRMS-coordinated two-phase commit for single-user, single-TCB batch applications and for applications running under Com-plete or IMS TM.

Example

ATM registers with RRMS so that it can take part in transactions involving other RRMS-enabled resource managers.

ADARUN PROG=ADANUC,DTP=TM,TMSYNCMGR=RRMS

TMTCIDPREF : Dynamic Client ID Prefix

Parameter Type Use Possible Values Default
Runtime Defines the first one or two characters of dynamically allocated Client IDs. up to 2 alphanumeric characters TM

To aid interpretation of Adabas Online Services displays and diagnostic logs, the ATM manager dynamically allocates an 8-byte client identifier (TCID) for each client session that engages in transactional activity. These client identifiers are simply labels, and have no operational significance.

The format of a dynamically allocated TCID is

ppnnxxxx

—where

pp is the value of the TMTCIDPREF parameter, left-justified and with trailing blanks if required.

nn is the 2-byte binary ATM database ID.

xxxx is a 4-byte binary suffix. Suffixes are allocated in sequence and are reused. The first TCID to be allocated has a suffix of zeros.

Example

ATM will assign dynamic TCIDs beginning with the string "DY".

ADARUN PROG=ADANUC,DTP=TM,TMTCIDPREF=DY

Top of page

Recommendations for Adabas Runtime Parameters when using ATM

Caution:
Before you use Adabas Transaction Manager in a production environment, the settings for Adabas runtime parameters should be reviewed and modified as necessary according to the recommendations provided in this section.

The ATM transaction manager tracks and coordinates all Adabas transactional activity. This includes:

The originating client’s transaction manager client proxy forwards these commands to the transaction manager for scrutiny.

Furthermore, the transaction manager acts as a focal point for transactional activity for all Adabas activity within the system image. Consequently, there may be times when significant load is experienced. Therefore, for production running, ATM transaction manager needs to be configured to handle high levels of concurrent activity.

Some Adabas parameters need to be reviewed. In general it is usually appropriate to take the values set for the busiest Adabas database in the system and use at least those values. In any case, setting values high, and reviewing them later, after a successful period of operation, is a reasonable safety first approach for most parameters. The following table describes the most important parameters which should be reviewed, but all other parameters should be considered also.

Adabas Parameter Description
NU

For the ATM manager, the NU parameter needs to be high enough for the maximum concurrent number of open transactions in the system, plus the value of the NT parameter.

NC The command queue size for the transaction manager needs to be set for high levels of throughput.
NAB For each concurrent activity a portion of the attached buffers is used.
NT Some transactional activity can take more time to complete than a normal Adabas command (for example, coordinating multiple databases to complete a transaction safely), so the number of threads in the ATM manager should be higher than might be expected.
TMLOG=NO Numerous I/O operations to the TM LOG dataset are performed when the TMLOG parameter is set to TMLOG=YES. In a busy system, the I/O rate for TMLOG=YES will have a significant impact on performance; in such cases, set TMLOG=NO for the ATM manager.

Before using Adabas Transaction Manager in a production environment, remember also to review the client runtime controls for jobs and TP systems that will use ATM. Pay particular attention to the setting of NumberLogRecordEntries.

Top of page

Enforced Runtime Parameters

When the transaction manager is started, certain ADARUN parameter values are enforced. If other values are supplied through the DDCARD DD statement, they are ignored and overwritten by the values preset for the manager. The enforced parameter values include the following, although other parameters might also be affected:

FASTPATH=NO
PLXID=0
READONLY=NO
SMPID=0
SPT=NO
UTIONLY=NO
VISTA=NO

Top of page