set format

set trn_tran_process_count=concurrent-transaction-branch-count
[set trn_recovery_process_count=parallel-recovery-process-count]
[set trn_expiration_time=transaction-branch-expiry-time]
[set trn_expiration_time_suspend=Y|N|F]
[set trn_tran_statistics=Y|N]
[set trn_tran_recovery_list=Y|N]
[set trn_cpu_time=transaction-branch-CPU-check-time]
[set trn_statistics_item=statistical-information-item
                         [,statistical-information-item]...]
[set trn_max_subordinate_count=maximum-number-of-
                               childtransaction-branches]
[set trn_rm_open_close_scope=process|transaction]
[set trn_optimum_item=transaction-optimization-item[,transaction-
                      optimization-item]...]
[set trn_processing_in_rm_error=down|retry|force]
[set trn_recovery_list_remove=normal|force|no]
[set trn_recovery_list_remove_level=delete-level-for-undecided-
                                    transaction-information-file]
[set trn_crm_use=Y|N]
[set trn_max_crm_subordinate_count=maximum-number-of-childtrans-
                                   action-branches-through-CRM]
[set  trn_watch_time=maximum-communication-wait-time-for-
                    synchronization-point-processing-of-transactions]
[set trn_rollback_information_put=no|self|remote|all]
[set trn_limit_time=maximum-time-to-execute-transaction-branch]
[set trn_rollback_response_receive=Y|N]
[set trn_partial_recovery_type=type1|type2|type3]
[set max_socket_descriptors=maximum-number-of-file-descriptors-for-
                            sockets]
[set trn_recovery_failmsg_interval=minimum-interval-between-
                                   issuing-messages-containing-
                                   information-about-incomplete-
                                   transactions]
[set trn_wait_rm_open=continue|stop|retry
                      continue|retry_stop]
[set trn_retry_interval_rm_open=retry-interval-for-issuing-xa_open-
                                function]
[set trn_retry_count_rm_open=number-of-retries-for-issuing-xa_open-
                             function]

[set thread_stack_size=size-of-thread-stack -area-used-within-OpenTP1]
[set polling_control_data=Y|N]
[set thread_yield_interval=Interval-for-issuing-a-trigger-to-receive-a-
                           socket-reuse-instruction]
[set groups=group-identifier [,group-identifier]...]
[set trn_xar_use=Y|N]
[set trn_start_recovery_mode=stop|wait|continue]
[set trn_start_recovery_watch_time=elapsed-retry-time]
[set trn_start_recovery_interval=retry-interval]
[set trn_xa_commit_error=down|force]
[set trn_prf_event_trace_level=acquisition-level-of-TRN-event-trace]
[set trn_prf_event_trace_condition=trace-acquisition-type[,trace-
                                   acquisition-type]]
[set trn_completion_limit_time=time-limit-for-completing-transaction]
[set trn_extend_function=facility-extension-level-of-the-transaction-service]
[set watch_time=maximum-response-waiting-time]

command format

trnstring -n resource-manager-name
             [-I resource-manager-extension[,resource-manager-
              extension]...]
             [-o "transaction-service-xa_open-function-character-
              string"]
             [-c "transaction-service-xa_close-function-character-
              string"]
             [-O "user-server-xa_open-function-character-string"]
             [-C "user-server-xa_close-function-character-string"][-d]
             [-e][-m][-r]

putenv format

{{[putenv environment-variable-name environment-variable-value]}}

dcputenv format

{{[dcputenv environment-variable-name environment-variable-value]}}

The transaction service definition defines the execution environment to manage transactions.

trn_tran_process_count=concurrent-transaction-branch-count ~<unsigned integer>> ((1-8192^#))

#:

The range of specifiable values applicable when the MCF service is used is as follows:

• 32-bit environment: 1-7484
• 64-bit environment: 1-6893

Specify the number of transaction branches to be started simultaneously.

The number you specify is the sum of the number of user server processes for processing transactions, the number of recovery processes, and the number of transaction branches waiting for recovery.

Should the user server process that generated the transaction branch terminate abnormally, that transaction branch could enter a recovery-wait state while other transaction branches are being recovered. If this waiting state is prolonged, the number of transaction branches which can be started could be reduced. Accordingly, the number of transaction branches should be set taking into account the disposal of user server processes which can generate a transaction branch after an abnormal termination, and the frequency of abnormal terminations.

Thus the specification should satisfy the following condition:

(Number of user server processes executing transactions + number of recovery processes)

< Transaction branch count specification

[(Number of user server processes executing transactions x 2) + number of recovery processes]

Take note that the larger the number of transactions, the lower will be the efficiency of the memory resources.

trn_recovery_process_count=parallel-recovery-process-count~<unsigned integer> ((1-128)) <<4>>

Specify the number of transaction branches that can be recovered in parallel should they terminate abnormally.

If the transaction branch terminates abnormally, its recovery processes are carried out in parallel the specified number of times.

trn_expiration_time=transaction-branch-expiration-time~<unsigned integer> ((0-65535)) <<0>> (Unit: seconds)

Specify the maximum time to monitor processing of a transaction branch. OpenTP1 abnormally terminates and rolls back the transaction branch when processing goes beyond the specified time. Specify 0 to have no time check.

Whether the service or service group is to be shut down if a UAP terminates abnormally depends on the specification of the hold and term_watch_time operands. For details, see the descriptions of the hold and term_watch_time operands of the user service definition.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition. The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

A time check can also be specified with other functions. For details of these functions, see the OpenTP1 Programming Guide.

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_expiration_time operand in the client environment definition or client service definition.

trn_expiration_time_suspend=Y|N|F~<<N>>

Specify whether the next processing time is to be included in the specified time check of the processing of a transaction branch.

1. Time required for the monitored transaction branch to call another transaction branch using the RPC facility and wait until its processing is terminated
2. Time required for the server UAP called with the chained RPC to wait for the next service request
3. Time required for the monitored transaction branch to call another transaction branch using the asynchronous RPC facility and receive the result of processing
   

   Y

   The monitoring time includes all of 1., 2., and 3.

   N

   The monitoring time includes only 3.

   F

   The monitoring time includes none of 1., 2., and 3.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition. The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

For details about the relationship between this operand and the timer monitoring options, see A.2 Time monitoring for transactions.

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_expiration_time_suspend operand in the client environment definition or client service definition.

trn_tran_statistics=Y|N~<<N>>

Specify whether statistical information is to be collected for each transaction branch.

Y

Statistical information is collected.

N

Statistical information is not collected.

If Y is specified, the system collects statistics of the transaction branches executed by the user server for which other than nothing was specified in the trn_statistics_item operand of the user service definition during the time from startup to termination of the OpenTP1 system.

The trnstics command can also specify the start or termination of collecting statistics. If this command is used, the specification of this operand becomes invalid.

The more the types of statistics collected, the lower the transaction performance. It is recommended to collect statistics only during system tuning or when checking on trouble when transaction performance is not a problem.

trn_tran_recovery_list=Y|N~<<N>>

Specify whether undecided transactions information is to be recovered during full recovery of an OpenTP1 system. The OpenTP1 system creates a file under $DCDIR/spool/dctrninf and outputs this information whenever the system recovers entirely. Delete unnecessary files.

Y

Undecided transactions information is collected.

N

Undecided transactions information is not collected.

trn_cpu_time=transaction-branch-CPU-check-time~<unsigned integer> ((0-65535)) <<0>> (Unit: seconds)

Specify the CPU time that can be used by a transaction branch until synchronous point processing. If 0 is specified, no time check is performed. If the specified time is exceeded, the transaction branch process terminates abnormally and rolls back.

Whether the service or service group is to be shut down if a UAP terminates abnormally depends on the specification of the hold and term_watch_time operands. For details, see the descriptions of the hold and term_watch_time operands of the user service definition.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_cpu_time operand in the client environment definition or client service definition.

trn_statistics_item=statistical-information-item[,statistical-information-item]...~<<executiontime>>

Specify an item that collects statistics of a transaction branch.

nothing

Statistics are not collected.

base

The following is collected as basic information.

• Transaction branch identifier
• Transaction branch decision results
• Execution process type of transaction branch
• Execution server name of transaction branch
• Execution service name of transaction branch

executiontime

The basic information and the execution time information of the transaction branch are collected.

cputime

The basic information and the transaction branch CPU check time information are collected.

Only one nothing is specified. If nothing and other statistics concurrently, specifying nothing will be invalid.

When collecting statistics about transactions, use either of the following two ways:

• Specify Y in the trn_tran_statistics operand.
• Specify the -s option of the trnstics command.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_statistics_item operand in the client environment definition or client service definition.

trn_max_subordinate_count=maximum-number-of-childtransaction-branches~<unsigned integer> ((0-1024)) <<32>>

Specify the maximum number of childtransaction branches that are generated from one transaction branch under OpenTP1. It is the maximum number of dc_rpc_call function (s) issued from one transaction branch (but which are updated or uj-output at the calling side).

trn_rm_open_close_scope=process|transaction~<<process>>

Specify the issuing timing of the two functions (xa_open and xa_close) which are the XA interfaces to the resource manager that other than the OpenTP1 system offers.

process

The xa_open function is issued when issuing the dc_rpc_open function and the xa_close function is issued when issuing the dc_rpc_close function.

transaction

The xa_open function is issued when starting the transaction and the xa_close function is issued when terminating the transaction.

If process is specified, the resource for the resource manager is occupied from the issue of the dc_rpc_open function to the issue of the dc_rpc_close function. If the transaction performance is focused on, specify process.

If transaction is specified, the xa_open and xa_close functions will be issued whenever the transaction starts and terminates. Therefore, if the resource of the resource manager must be used efficiently, specify transaction.

This operand can also be specified to the user service definition, and the user service default definition.

The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition
2. User service default definition
3. Transaction definition

trn_optimum_item=transaction-optimization-item[,transaction-optimization-item]...~<<base>>

The items to be optimized are specified with the following character strings to improve the performance of the global transaction distributed to multiple user servers.

base

The entire synchronization point processing (prepare processing, commit, and rollback) is optimized. Since the OpenTP1 transaction control uses the two-phase commit method, the commit control between two transaction branches requires an inter-process communication four times.

However, when all the following conditions are satisfied, the four occurrences of inter-process communications required for the commit control can be eliminated by having the parent transaction branch execute the commit of the childtransaction branch, instead.

1. The parent transaction branch and the childtransaction branch are under control of the same OpenTP1.
2. The parent transaction branch has called the childtransaction branch by the synchronous-response RPC.
3. The XA interface object for the resource manager accessed with the childtransaction branch is linked also to the parent transaction branch.

asyncprepare

If optimization of the entire synchronization point processing cannot be performed because the specification conditions of base are not satisfied, only the prepare processing is optimized.

When all the following conditions are satisfied and the childtransaction branch issues a service request by the RPC issued by the parent transaction branch, two-time inter-process communications can be eliminated by executing the preparation before the RPC is returned.

1. The optimization by specifying base cannot be performed.
2. The parent transaction branch has called the childtransaction branch by the synchronous-response RPC.
   Performing this optimization shows the response of the synchronous-response RPC issued by the parent transaction branch. For the childtransaction branch, the interval between the prepare processing and commit (the status in which the transaction cannot be determined without the instruction from the parent transaction branch) becomes longer. If the OpenTP1 of the parent transaction branch fails, disabling the communication between transaction branches, the swapping of the journal file and the validating of the checkpoint dump file are slowed and the OpenTP1 of the childtransaction branch may also fail.
   

More than one transaction optimization item can be specified. When both of them are specified, the specification takes precedence according to the following priority (1.>2.):

1. base
2. asyncprepare

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values in decreasing order are as follows (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_optimum_item operand in the client environment definition or client service definition.

trn_processing_in_rm_error=down|retry|force~<<down>>

Specify the action of OpenTP1 if an error is returned with the code (XAER_INVAL(-5), XAER_PROTO(-6)) indicating that the XA function (xa_commit function, xa_forget function, xa_rollback function) issued to the resource manager cannot continue to be processed during the transaction recovery by the transaction recovery service.

This error occurs in the following cases. If this error occurs, there may be a resource inconsistency.

• If an error occurs on the resource manager
• When the transaction control facility provided by the resource manager that is communicating with the XA interface under transaction control of OpenTP1
• When a facility not allowed by the resource manager is used during communication with the XA interface

If this error occurs, messages KFCA00907-E and KFCA00908-E are output.

down

Shuts down the OpenTP1 system. After the shutdown, recover all the resources to the normal status and force the OpenTP1 system to start normally.

retry

Instructs the resource manager on which the error occurred to periodically determine the transaction until the transaction is determined.

Specify retry when the resource manager can be recovered from the error by some method or when checking the resource manager status to take an action such as prohibiting the access before changing the specification to force.

force

Ignores the faulty resource manager and determines the transaction forcibly.

After the transaction is determined forcibly, specify force if another transaction can access the resource manager on which the error occurred.

This operand can be changed during an online session to determine the error handling. Therefore, it is possible to specify retry at the system startup, take an appropriate action on the faulty resource manager if an error occurs, and then change the specification to force.

trn_recovery_list_remove=normal|force|no~<<no>>

Specify whether to delete undecided transaction information files at the start of OpenTP1.

normal

Undecided transaction information files are deleted at normal start of OpenTP1.

force

Undecided transaction information files are deleted at start of OpenTP1.

no

Undecided transaction information files are not deleted at start of OpenTP1.

trn_recovery_list_remove_level=delete-level-for-undecided-transaction-information-file~<unsigned integer> ((0-24855)) <<0>> (Unit: days)

Specify the delete level for the undecided transaction information files. This operand is valid when normal or force is specified by the trn_recovery_list_remove operand.

0

All files are deleted.

1-24855

The files created specified-value x 24 or more hours before the transaction service start time are deleted.

trn_crm_use=Y|N~<<N>>

Specify whether to use the communication resource manager (CRM).

Y

The CRM is used.

N

The CRM is not used.

trn_max_crm_subordinate_count=maximum-number-of-childtransaction-branches-through-CRM~<unsigned integer> ((0-1024)) <<8>>

Specify the maximum number of RPCs through the CRM that are created by a single transaction branch under OpenTP1.

trn_watch_time=maximum-communication-wait-time-for-synchronization-point-processing-of-transactions~<unsigned integer> ((1-65535)) <<120>> (Unit: seconds)

Specify the maximum waiting time for receiving the communication (such as a prepare instruction, commit instruction, rollback instruction, and response) performed between transaction branches during the synchronization point processing of transactions.

If no instruction or response is made after the specified time, the transaction branch will be rolled back if it is before completion of the first phase of two-phase commit. If the first phase is completed, the system process of the transaction service retries to terminate the transaction.

You can also specify this operand with the user service definition or RAP-processing listener service definition, and user service default definition.

Priority is given to the specified values in the following order (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. User transaction service definition

Omitting this operand in all of these definitions assumes the watch_time value of the user server involving the transaction. Note that you cannot specify 0 in trn_watch_time. If you specify 0 in the watch_time operand on the user server, 120 (seconds), which is the default value of trn_watch_time, is used.

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_watch_time operand in the client environment definition or client service definition.

trn_rollback_information_put=no|self|remote|all~<<no>>

Specify whether to log information on the cause of rollback when transaction branches are rolled back.

no

Rollback information is not logged.

self

Rollback information is logged only for the transaction branch that caused rollback.

remote

In addition to information of self, rollback information is logged for transaction branches for which the remote node transaction branch requested rollback.

all

In addition to information of remote, rollback information is logged for transaction branches for which the local node transaction branch requested rollback.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values is (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_rollback_information_put operand in the client environment definition or client service definition.

You will be able to investigate errors more easily by using the log data acquired when this operand is specified. If no or nothing is specified for this operand, we recommend that you specify all instead.

trn_limit_time=maximum-time-to-execute-transaction-branch~<unsigned integer> ((0-65535)) <<0>> (Unit: seconds)

Specify the maximum time to execute a transaction branch. The expiration time is automatically specified for the dc_rpc_call and dc_rpc_poll_any_replies functions and for the communication during the synchronization point processing as shown below, so that the time between startup of a transaction branch and termination of the synchronization point processing does not exceed the value specified in this operand.

• Expiration time for the dc_rpc_call function and the dc_rpc_poll_any_replies function
  For K Value of the operand, the system returns a timeout error without executing the requested processing.
  For K < Value of the operand, and (Value of the operand) - K W, W is set for the expiration time.
  For K < Value of the operand, and (Value of the operand) - K < W, the value of the operand minus K is set for the expiration time.
  

  K

  (Current time) - (Transaction branch startup time)

  W

  Value specified in the watch_time operand for the dc_rpc_call function, or value of the timeout argument for the dc_rpc_poll_any_replies function

• Expiration time for the communication during the synchronization point processing
  For K Value of the operand, the expiration time is 1 second.
  For K < Value of the operand, and (Value of the operand) - K W, W is set for the expiration time.
  For K < Value of the operand, and (Value of the operand) - K < W, the value of the operand minus K is set for the expiration time.
  

  K

  (Current time) - (Transaction branch startup time)

  W

  Value specified in the trn_watch_time operand, or in the watch_time operand if the trn_watch_time operand is not specified

If processing other than above takes a long time, the transaction branch may not terminate within the specified time.

If the time specified with this operand has expired before the synchronization point processing starts, the transaction will be rolled back. Specify 0 to have no time check.

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values is (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_limit_time operand in the client environment definition or client service definition.

trn_rollback_response_receive=Y|N~<<Y>>

Specify whether to receive a rollback completion report after sending a rollback instruction to the RPC destination transaction branch. Specify N to terminate the local transaction branch without receiving the rollback completion report from the RPC destination transaction branch (i.e., without waiting for the RPC destination transaction branch to complete rollback processing).

This operand can also be specified with the user service definition or RAP-processing listener service definition, and the user service default definition.

The priority of the specified values is (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_rollback_response_receive operand in the client environment definition or client service definition.

trn_partial_recovery_type=type1|type2|type3~ <<type1>>

This specifies the method of processing transaction synchronization points when there is a UAP error.

If, because of an RPC timeout, the address of a process to which the RPC is issued fails to be settled or the UAP where a transaction is underway goes down, the communication between transaction branches will become degraded so that it may take time to settle transactions.

With this operand, the method of processing transaction synchronization points depending on different faults is selected among from the three methods shown in specified values.

Error 1

When there is an RPC timeout:

In this case, the RPC-issuing transaction branch cannot identify the process in which the service request is being executed. Because the RPC-issuing transaction branch cannot identify the process, it cannot send a message about the transaction synchronization point to the RPC-receiving transaction branch. Therefore, both the RPC-issuing and RPC-receiving transaction branches have to wait for the transaction synchronization point message and that wait requires time to settle the transaction.

Error 2

When the RPC-issuing UAP goes down before receiving an RPC response:

In this case, the RPC-issuing transaction branch cannot identify the process in which the service request is being executed. Because the RPC-issuing branch cannot identify the process, it cannot send a message about the transaction synchronization point to the RPC-receiving transaction branch. Therefore, the RPC-receiving transaction branch has to wait for the transaction synchronization point message and that wait requires time to settle the transaction.

Error 3

When the RPC-issuing UAP and the RPC-receiving UAP go down almost simultaneously after the reception of a response from the RPC-receiving UAP:

In this case, the transaction recovery process taking over both of the transaction branches does not know that the other party's UAP process is down. The transaction recovery process will send a transaction synchronization point message to a non-existing UAP process and that action may require time to settle the transaction.

type1

If Error 1 occurs, the RPC-issuing transaction branch and the RPC-receiving transaction branch both settle the transaction when the processing of the transaction synchronization point message gets a timeout.

If Error 2 occurs, the RPC-issuing transaction branch settles the transaction without sending the transaction synchronization point message to the RPC-receiving transaction branch. The RPC-receiving transaction branch settles the transaction when the processing of the transaction synchronization point message causes a timeout.

If Error 3 occurs, the RPC-issuing transaction branch and the RPC-receiving transaction branch both settle the transaction when the processing of the transaction synchronization point message causes a timeout.

type2

If Error 1 occurs and transaction is committed, the procedure is the same as type1.

If Error 1 occurs and the transaction is rolled back or if Error 2 occurs, the RPC-issuing transaction branch sends the transaction synchronization point message to the transaction service process at the node where the RPC-receiving transaction branch exists. Then the RPC-issuing transaction branch settles the transaction. When the transaction service process receives the transaction synchronization point message, the transaction service process sends a transaction synchronization point instruction to the process that is currently processing the transaction branch.

If Error 3 occurs, the RPC-issuing transaction branch and the RPC-receiving transaction branch both settle the transaction when the processing of the transaction synchronization point message cause a timeout.

type3

If Error 1 occurs and transaction is committed, the procedure is the same as type1.

If Error 1 occurs and the transaction is rolled back, or if Error 2 occurs, or if Error 3 occurs, the RPC-issuing transaction branch sends the transaction synchronization point message to the transaction service process at the node where the other party's transaction branch exists. Then RPC-issuing transaction branch settles the transaction. When the transaction service process receives the transaction synchronization point message, the transaction service process sends a transaction synchronization point instruction to the process that is currently processing the transaction branch.

In the following cases, even if this operand is given type2 or type3, the transaction may take time to settle.

1. During an RPC execution, the RPC-receiving UAP undergoes a status change (such as a load increase, UAP termination, or UAP blocking) and a service request is retransferred to the same UAP of another node.
2. In this version, this option does not support the other party's OpenTP1.
3. The other party's transaction branch takes time other than in the reception of the transaction synchronization point message.

It is possible to specify this operand even in the user service definition or RAP-processing listener service definition, and user service default definition.

Priority is given to the specified values in the following order (1.>2.>3.).

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. User transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_partial_recovery_type operand in the client environment definition or client service definition.

max_socket_descriptors=maximum-number-of-file-descriptors-for-sockets~<unsigned integer> ((32-2032))

Specify the maximum number of file descriptors to be used for sockets by the processes under control of OpenTP1^#.

The processes under control of OpenTP1^# exchange the process information with the system servers or user servers through the TCP/IP communication using sockets. Therefore, you must change the maximum number of file descriptors for sockets depending on the number of UAP processes that run concurrently and the number of other nodes to communicate with.

#

Use this operand for OpenTP1 processes other than the MCF services (MCF manager service, MCF communication service, and application startup service). For the MCF services, see System service information definition and System service common information definition.

Use the following formula for calculating the maximum number of file descriptors for sockets:

(Number of UAP processes in the local node^#1 + number of trn system processes in the nodes that request the transaction service^#2 + number of system service processes^#3)/0.8

: Rounded up to the nearest whole integer.

#1: The number of UAP processes in the local node is the sum of the following values:

• Number of UAP processes in the local OpenTP1 that use a transactional RPC for sending a service request
• Number of UAP processes in another node that use a transactional RPC for requesting a service from the local OpenTP1.
• Number of transactions to be started concurrently by the CUP (value of the parallel_count operand specified in the client service definition)

#2: The number of trn system processes in the nodes that request the transaction service is the sum of the following values:

• Of the nodes specified in the all_node operand for the local OpenTP1, the value of the trn_recovery_process_count operand plus 1 in the transaction service definition of the node using a transactional RPC to extend the transaction from the local OpenTP1
• Of other nodes that specify the local node name in the all_node operand for OpenTP1, the value of the trn_recovery_process_count operand plus 1 in the transaction service definition of the node using a transactional RPC to extend the transaction to the local OpenTP1

#3: The number of system service processes in the local OpenTP1.

If the value specified for this operand is too small, the connection cannot be set with other processes under control of OpenTP1. The process terminates abnormally after outputting the KFCA00307-E error message.

If this operand is omitted, the system assumes the value in the system common definition.

trn_recovery_failmsg_interval=minimum-interval-between-issuing-messages-containing-information-about-the-incomplete-transaction~<unsigned integer>((0-65535))<<1800>> (unit: seconds)

Specify the interval between outputs of the KFCA00960-I message.

If the system cannot recover a transaction and the length of time specified in this operand is exceeded after the previous KFCA00960-I message was output, the same message is output again. However, the KFCA00960-I message is output immediately for the following cases:

• If the system fails to recover the transaction at the outset after the transaction starts.
• If the system fails to recover the transaction at the outset after the start of OpenTP1 termination processing.
• If the system fails to recover the transaction at the outset after the restart of OpenTP1.

If you specify 0 for this operand, the KFCA00960-I message will not be output.

If you are currently recovering multiple transaction branches, this operand is applied to each transaction branch. Only messages from the same transaction branch are output at the interval specified in this operand.

The KFCA00960-I message may sometimes be output twice or more for a single transaction recovery failure. This occurs when there are multiple reasons for the failure. The KFCA00960-I message may sometimes be output after the KFCA00990-I message.

trn_wait_rm_open=continue|stop|retry_continue|retry_stop~ <<continue>>

This operand specifies the action to be taken if an error occurs while a resource manager provided by other than OpenTP1 is opened (xa_open function) when OpenTP1 starts.

continue

Ignores the xa_open function error and continues the OpenTP1 start processing.

stop

Stops the OpenTP1 start processing if the xa_open function error occurs.

retry_continue

Suspends the OpenTP1 start processing if the xa_open function error occurs and retries to issue the xa_open function for the number of times specified in the trn_retry_count_rm_open operand at the interval specified in the trn_retry_interval_rm_open operand. If the xa_open function error does not go away, retry_continue ignores the error and continues the OpenTP1 start processing.

retry_stop

Suspends the OpenTP1 start processing if the xa_open function error occurs and retries to issue the xa_open function for the number of times specified in the trn_retry_count_rm_open operand at the interval specified in the trn_retry_interval_rm_open operand. If the xa_open function error does not go away, retry_stop cancels the OpenTP1 start processing.

trn_retry_interval_rm_open=retry-interval-for-issuing-xa_open-function ~<unsigned integer>((1-3600))<<10>> (unit: seconds)

This operand specifies the retry interval for issuing the xa_open function when retry_continue or retry_stop is specified in the trn_wait_rm_open operand.

trn_retry_count_rm_open=number-of-retries-for-issuing-xa_open-function ~<unsinged integer>((1-65535))<<18>>

This operand specifies the number of retires for issuing the xa_open function when retry_continue or retry_stop is specified in the trn_wait_rm_open operand.

thread_stack_size=size-of-thread-stack -area-used-within-OpenTP1~<unsigned integer>((1024-524288))<<49152^#>> (unit: bytes)

#

For the AIX version of uCosminexus TP1/Server Base(64), the default value is 65536.

This operand specifies the thread stack area that OpenTP1 uses internally. The size of the thread stack area for the resource manager monitoring service has been expanded to 262,144 bytes. Therefore, specify this operand only when a thread stack area larger than 262,144 bytes is required for the resource manager for which you want to use XA linkage. You can use the following formula to calculate the amount of memory required when this operand is specified:

Thread stack area size (bytes) = (value of the trn_recovery_process_count operand in the transaction service definition + 2) x (value of the thread_stack_size operand) x 2

polling_control_data=Y|N~<<N>>

This operand specifies whether to regularly poll into the waiting status where the transaction recovery daemon is waiting for a transaction recovery request. Specify Y to check whether a temporary closing request has arrived.

Y

Regularly polls into the waiting status for a transaction recovery request and checks whether a temporary closing request has arrived.

N

Does not poll into the waiting status for a transaction recovery request, and keeps the waiting status until a service request arrives.

thread_yield_interval=interval-for-issuing-a-trigger-to -receive-a-socket-reuse-instruction~<unsigned integer>((1-86400))<<90>>(unit: seconds)

Specify the interval in seconds for polling into the waiting status where the transaction recovery daemon is waiting for a transaction recovery request. This specification checks whether a temporary closing request has arrived.

If the transaction recovery requests are accepted one after another without waiting, the system checks whether a temporary closing request has arrived when the time period in which transaction recovery requests are accepted successively exceeds a predetermined time. This operand is also used as the interval. (No signal interrupt occurs for checking whether a temporary closing request has arrived, when the time period in which transaction recovery requests are accepted successively exceeds the value specified in this operand.)

Specify a smaller value than the time period in which a process issuing a temporary closing request waits for a response (180 seconds: default of ipc_socket1_watchtime operand).

The facility of checking whether a temporary closing request has arrived by polling into the transaction recovery request waiting status becomes active only when Y is specified in the polling_control_data operand. The facility of checking whether a temporary closing request has arrived when successive services are accepted becomes active regardless of the value specified in the polling_control_data.

If the maximum value is specified in this operand, the system does not check whether a temporary closing request has arrived, regardless of the value specified in the polling_control_data operand.

groups=group-identifier [,group-identifier]...]~<unsigned integer>((0-4294967294))

Sets a group access list of the service groups.

Specify group IDs cataloged in the operating system. You can specify up to 16 group IDs.

The setgid() system call automatically sets the group ID for the OpenTP1 administrator regardless of the specified value in this operand.

Since the maximum value depends on the operating system, see the documentation for your operating system.

trn_xar_use=Y|N~<<N>>

Specify whether to use the XA resource service. To use the XA resource service, you need to define the execution environment in the XA resource service definition. Note that if Y is specified for the jnl_fileless_option operand in the system common definition, the XA resource service cannot be used.

Y

The XA resource service is used.

N

The XA resource service is not used.

trn_start_recovery_mode=stop|wait|continue~<<stop>>

Specify the transaction recovery processing method used by the resource manager, specified in the -m option in the trnstring definition command, during its OpenTP1 startup processing. This operand can be changed or deleted at the restart.

stop

Stops the OpenTP1 startup processing if recovery processing does not finish within the retry processing in a specified length of time (value specified in the trn_start_recovery_watch_time operand). In this case, the system outputs abort code t860004.

wait

Continues retry processing until all the transaction recovery processing for OpenTP1 finishes in the resource manager specified in the -m option in the trnstring definition command. To cancel this retry processing, use the dcstop command to forcibly terminate OpenTP1.

continue

Cancels recovery processing if it does not finish within the retry processing in a specified length of time (value specified in the trn_start_recovery_watch_time operand), and continues OpenTP1 startup processing.

trn_start_recovery_watch_time=elapsed-retry-time~<unsigned integer> ((0-65535))<<600>> (units: seconds)

Specify the upper retry time limit until pre-online recovery processing finishes when the -m option is specified in the trnstring definition command. When you specify 0, no retry is performed. This operand is valid when a value other than wait is specified in the trn_start_recovery_mode operand. This operand can be changed or deleted at restart.

trn_start_recovery_interval=retry-interval~<unsigned integer> ((0-65535))<<3>> (units: seconds)

Specify the retry interval before pre-online recovery processing finishes when the -m option is specified in the trnstring definition command. When you specify 0, the next retry is performed immediately. When you specify 0 for the trn_start_recovery_watch_time operand, the value specified for the trn_start_recovery_interval operand is invalid. This operand can be changed or deleted at restart.

trn_xa_commit_error=down|force~<<down>>

Specify the processing to be performed^# if a resource manager becomes unable to commit a transaction that accesses multiple resources after the commitment of the transaction is determined.

If this error occurs, the resources accessed by the applicable transaction may become inconsistent.

#

When the xa_commit function issued to the resource manager is returned with a rollback code (code beginning with XAER_RMERR or XA_RB)

down

Shuts down the OpenTP1 system.

Recover the consistency of resources after the system goes down and forcibly start OpenTP1.

force

Continues the system, disregarding the resource inconsistency.

In this case, the function that performs a commitment (dc_trn_chained_commit, dc_trn_unchained_commit(), tx_commit()) ends normally. Specify this operand if resource inconsistency is not a problem or during a test.

trn_prf_event_trace_level=acquisition-level-of-TRN-event-trace~ ((00000000-00000007)) <<00000007>>

Specify the acquisition level of the TRN event trace. This operand controls the event trace acquisition feature. If you do not specify this operand, entry information, normal exit information, and error exit information are acquired as trace data. For details about the TRN event trace, see the description about the trace feature in the manual OpenTP1 Description.

00000000

Does not acquire the TRN event trace.

00000001

Acquires the trace at the entry of an event (entry information).

00000002

Acquires the trace at the exit of an event (normal exit information).

When you specify xafunc for the trn_prf_event_trace_condition operand, the trace is acquired when the return value of the XA function is 0 or greater.

00000004

Acquires the trace if an error occurs at the exit of an event (error exit information).

00000007

Acquires the trace at the entry and exit of an event (including the case when an error occurs) (entry information, normal exit information, and error exit information).

To output the acquired trace data to a file or edit the trace data, use the prfget command or the prfed command. The result of file output is stored in $DCDIR/spool/dctrninf/trace/prf. For details about the prfget command or the prfed command, see the manual OpenTP1 Operation.

TP1/Extension 1 must be installed to use this operand. If TP1/Extension 1 is not installed, the operation is not guaranteed.

trn_prf_event_trace_condition=trace-acquisition-type[,trace-acquisition-type]~<<xafunc>>

Specify the type of the TRN event trace to be acquired. You can specify multiple types depending on the trace you want to acquire. If you do not specify this operand, the trace about XA functions is acquired.

xafunc

Acquires the trace about XA functions.

trnservice

Acquires the trace about the operating status of the transaction service.

TP1/Extension 1 must be installed to use this operand. If TP1/Extension 1 is not installed, the operation is not guaranteed.

trn_completion_limit_time=time-limit-for-completing-transaction~<unsigned integer> ((0-65535))<<0>>(units: seconds)

Specify the maximum time for execution of a transaction branch. If the execution time of a transaction branch reaches the maximum, the transaction branch process terminates abnormally, and the recovery process commits or rolls back the transaction branch. If 0 is specified, the execution time of the transaction branch is not monitored for this purpose.

Whether an abnormally terminated UAP is shut down depends on the specification of the hold and term_watch_time operands. For details, see the descriptions of these user service definition operands.

Monitoring of the execution time specified by this operand starts when a transaction is started by invoking the dc_trn_begin function or by starting a service function. The monitoring ends when the transaction branch terminates after acquisition of information about the synchronization point processing of the transaction (TJ). However, if the transaction is optimized, monitoring of the transaction branch on the server terminates after a response is returned to the client. For details about the section for which the execution time specified by this operand is monitored and about the relationship between this operand and timer monitoring options, see A.2 Time monitoring for transactions.

Note that this operand can also be specified in the user service definition (or RAP-processing listener service definition) and user service default definition.

The priority of the specified values is 1 > 2 > 3.

1. User service definition or RAP-processing listener service definition
2. User service default definition
3. Transaction service definition

To apply this operand in a transactional RPC executing process (clttrnd) or CUP executing process (cltcond), you must specify the trn_completion_limit_time operand in the client service definition.

If the execution time of the process of a child transaction branch reaches the time specified by this operand and the process terminates abnormally, the RPC caller may wait until the time to wait for a response expires.

trn_extend_function=facility-extension-level-of-the-transaction-service~<hexadecimal number> ((00000000-00000001))<<00000000>>

Specify the facility extension level of the transaction service.

The following describes the values you can specify in this operand. To specify multiple extension levels, specify the logical sum of the values.

00000000

The transaction service facility is not extended.

00000001

Specify this value in the transaction service definitions on all OpenTP1 nodes to which the transaction branch is related.

When this value is not specified on any OpenTP1 node to which the transaction branch is related, if the resource manager returns XAER_NOTA for a one-phase commit, the return value of the root transaction branch does not change.

The following table lists the values returned by functions when the resource manager returns XAER_NOTA for a one-phase commit.

Function	Return value
	When trn_extend_function= 00000000	When trn_extend_function= 00000001
dc_trn_chained_commit (CBLDCTRN('C-COMMIT'))	DC_OK (00000)	DCTRNER_HAZARD (00904), DCTRNER_HAZARD_NO_BEGIN (00927)
dc_trn_unchained_commit (CBLDCTRN('U-COMMIT'))	DC_OK (00000)	DCTRNER_HAZARD (00904)
tx_commit (TXCOMMIT)	TX_OK (TX-OK)	TX_HAZARD (TX-HAZARD), TX_HAZARD_NO_BEGIN (TX-HAZARD-NO-BEGIN)
dc_mcf_commit (CBLDCMCF('COMMIT'))	DCMCFRTN_00000 (00000)	DCMCFRTN_HAZARD (70908)

Note

The alphanumeric characters in parentheses indicate the functions and status codes in COBOL.

watch_time=maximum-response-waiting-time~<unsigned integer> ((0-65535)) (Unit: seconds)

Specify the maximum waiting time between sending a service request and receipt of a response when communicating between processes by RPC.

OpenTP1 may suspend termination processing for the length of time specified in this operand. Therefore, if you specify a large value, the termination processing of OpenTP1 may take some time.

If no response is received within the specified time, RPC returns a transmission timeout error.

Specify 0 if the system is to wait for a response. When you specify 0, OpenTP1 may not terminate.

If this operand is omitted, the value specified with the watch_time operand of the system common definition is assumed.

Use the default of the watch_time operand of the system common definition for this operand.

We recommend that you do not change the operand unless special tuning is necessary.

If a value that is much greater or smaller than the default of the watch_time operand of the system common definition is specified, a failure may occur causing OpenTP1 to go down.

Described on the following pages.

environment-variable-name environment-variable-value~<character string>

Specify the environment variable that the transaction recovery service and resource manager monitoring service require to access the resource manager for linkage with the resource manager via the XA interface.

The name and value of the environment variable you specify depend on the resource manager.

In OpenTP1, do not use any environment variable name that begins with dc.

environment-variable-name environment-variable-value~<character string>

Specify the environment variable that the transaction recovery service and resource manager monitoring service require to access the resource manager for linkage with the resource manager via the XA interface. If the name of an environment variable is specified as the environment variable value, the environment variable is replaced with its value.

The name and value of the environment variable you specify depend on the resource manager.

In OpenTP1, do not use any environment variable name that begins with dc.