OpenTP1 Version 7 System Definition

[Contents][Index][Back][Next]

Client service definition

Format

set format

[set parallel_count=number-of-resident-processes [, maximum-
                    number-of-processes]]
[set balance_count=number-of-service-requests-processed-by-a-process]
[set trn_expiration_time=transaction-branch-expiration-time]
[set trn_expiration_time_suspend=Y|N|F]
[set trn_cpu_time=transaction-branch-CPU-check-time]
[set open_rm=OpenTP1_ALL|OpenTP1_NONE]
[set clt_inquire_time=maximum-time-interval-between-permanent-
                      connection-inquiries]
[set clt_port=port-number-of-client-extension-service]
[set clt_trn_conf=Y|N]
[set clt_cup_conf=Y|N]
[set cup_parallel_count=number-of-resident-processes, [maximum-
                        number-of-processes]]
[set cup_balance_count=number-of-remaining-service-requests]
[set clttrn_port=transactional-RPC-execution-process-port-number]
[set cltcon_port=CUP-execution-process-port-number]
[set trn_statistics_item=statistical-item [, statistical-item] ...]
[set trn_optimum_item=transaction-optimization-item [, transaction-
                      optimization-item] ...]
[set trn_watch_time=maximum-wait-time-for-transaction-synchronization-
                    point-processing]
[set trn_rollback_information_put=no|self|remote|all]
[set trn_limit_time=transaction-branch-maximum-executable-time]
[set trn_rollback_response_receive=Y|N]
[set trn_partial_recovery_type=type1|type2|type3]
[set trn_completion_limit_time=time-limit-for-completing-transaction]
[set message_store_buflen=size-of-the-message-storage-buffer-pool]
[set watch_time=maximum-response-wait-time]

Command format

None

Function

The client service definition defines the execution environment for a server to support the OpenTP1 client functions. The operands describes below must be specified when the CUP starts up transactions.

Explanation

set format

parallel_count=number-of-resident-processes[,maximum-number-of-processes]~<unsigned integer> ((1-1024)) <<1>>

Specify the number of transactions that are started up by CUPs (processed concurrently by the server). When this number is specified, all the specified execution processes are started up at the same time, being ready to accept a transaction startup request from a CUP. If transaction startup requests come from more than one CUP, the transactions are processed in parallel resulting in enhanced performance.

With the maximum number of processes specified, any excess is processed by dynamically starting up non-resident processes. Because server process startup is controlled within the specified maximum number of processes, OpenTP1 system performance is prevented from reducing.

The conditions for specifying the number of processes are as follows:

  1. The number of resident processes and the maximum number of processes must be not less than 1.
  2. The maximum number of processes specified must be larger than that of resident processes specified.
  3. If the maximum number of processes is not specified, all processes are assumed resident.
  4. It is impossible to use all processes as non-resident ones (to be started up as necessary).

balance_count=number-of-service-requests-processed-by-a-process~<unsigned integer> ((0-512)) <<3>>

Specify the number of service requests, which are remaining in the schedule queue corresponding to this user server, to be processed by a single process. If the number of service requests remaining in the schedule queue exceeds the value determined by (Value specified in this operand) x (Number of started processes), start non-resident processes and have them process the service requests. This operand is effective only for the service group that is specified by the parallel_count operand to start non-resident processes.

If 0 is specified, non-resident processes are started up while all processes started up upon a serve request are being service-processed.

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

Specify the expiration time for checking the processing of transaction branches.

If neither commitment nor roll-back instruction is given within the specified time after startup of transactions from a CUP, the system terminates the transaction branch process abnormally and rolls back.

This operand can also be specified in the DCCLTTREXPTM operand in the client environment definition. For the client environment definition, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

If the RPC function is used, whether the processing time for transaction branches to be executed in other processes is included in the check time can be specified by the trn_expiration_time_suspend operand.

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

Specify whether to include, in the transaction branch process check time, the time required for a transaction branch to wait until processing of another branch called by RPC terminates.

  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 monitor time includes all of 1., 2., and 3.
    N
    The monitor time includes only 3.
    F
    The monitor time includes none of 1., 2., and 3.

This operand can also be specified in the DCCLTTREXPSP operand in the client environment definition. For the client environment definition, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

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

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 synchronization 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.

This operand can also be specified in the DCCLTTRCPUTM operand in the client environment definition. For the client environment definition, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.)

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

  1. Client environment definition
  2. Client service definition

open_rm=OpenTP1_ALL|OpenTP1_NONE~<<OpenTP1_NONE>>

Specify the name of the resource manager opened by the client service executable program when the transactional RPC facility is used from CUP. This specification optimizes the synchronization point processing by the transactional RPC facility executed from CUP, improving the transaction performance.

When this operand is specified, the resource manager's resource is used as much as for the number of processes specified by the paralled_count operand.

Either of the following resource manager names can be specified:

OpenTP1_ALL
At the start of OpenTP1, all the OpenTP1-provided resource managers registered in OpenTP1 are opened by the client service executable program.

OpenTP1_NONE
At the start of OpenTP1, no resource managers are opened by the client service executable program (the synchronization point processing cannot be optimized).

clt_inquire_time=maximum-time-interval-between-permanent-connection-inquiries~<unsigned integer> ((0-1048575)) <<180>> (Unit: seconds)

Specify the maximum interval between an inquiry from the CUP to the server and the next inquiry.

The CUP execution process monitors this interval, and forcibly releases the permanent connection if no inquiry is made within the specified period of time.

If expiration of the maximum interval is detected in a transaction, the transaction is rolled back.

Specify 0 to have the system wait infinitely for an inquiry from the CUP.

This operand can also be specified in the DCCLTINQUIRETIME operand in the client environment definition. For details, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

clt_port=port-number-of-client-extension-service~<unsigned integer> ((5001-65535))

Specify the port number of the client extension service.

Specify the port number that differs from any well-known port numbers used in other system servers.

Assuming that this operand is omitted, if the rpc_port_base operand as a system common definition has been specified, the system assigns any port number in the range from the specified value of rpc_port_base to the specified value of rpc_port_base plus the prc_process_count value. If the rpc_port_base operand as a system common definition has not been specified, the system uses any assigned port number.

The port number specified using this operand must not be used by other programs.

Note that the operating system assigns certain numbers automatically. You should not use such a number for the port number. The numbers assigned by the operating system differ depending on the type and version of the operating system. For details, see the documentation for your operating system.

clt_trn_conf=Y|N

Specify whether to start the transactional RPC execution processes in the local OpenTP1 node. If nothing or Y is specified for this operand, the transactional RPC execution processes as many as those specified in the parallel_count operand are started.

clt_cup_conf=Y|N

Specify whether to start the CUP execution processes in the local OpenTP1 node. If Y is specified for this operand, the CUP execution processes as many as those specified in the cup_parallel_count operand are started.

Specify Y to establish a permanent connection from the CUP using the dc_clt_connect or dc_clt_connect_s function.

cup_parallel_count=number-of-resident-processes,[maximum-number-of-processes]~<unsigned integer> ((1-1024)) <<1>>

Specify the number of permanent connections established by CUPs (concurrently processed by the server).

When the number of resident processes is specified, all the specified CUP execution processes are started up at the same time, being ready to accept a permanent connection establishment request from a CUP. If permanent connection establishment requests come from more than one CUP, the requests are processed in parallel resulting in enhanced performance.

When the maximum number of processes is specified, any excess is processed by dynamically starting non-resident processes. Because server process startup is controlled within the specified maximum number of processes, OpenTP1 system performance is prevented from reducing.

The conditions for specifying the number of processes are as follows:

  1. The number of resident processes and maximum number of processes must be not less than 1.
  2. The maximum number of processes specified must be larger than that of resident processes specified.
  3. If the maximum number of processes is not specified, all processes are assumed resident.
  4. It is impossible to use all processes as non-resident ones (to be started up as necessary).

For the parallel_count operand of the client service definition, specify the number of resident transactional RPC execution processes and maximum number of transactional RPC execution processes.

cup_balance_count=number-of-remaining-service-requests~<unsigned integer> ((0-512)) <<3>>

Specify the number of remaining permanent connection establishment requests.

Permanent connection establishment requests sent from CUPs are entered in the scheduling queue. If the number of requests exceeds the value specified in the operand, the scheduling facility starts non-resident processes to process these requests. This operand is effective only when the maximum number of processes is specified by the cup_parallel_count operand.

Specify 0 to start non-resident processes when a permanent connection establishment request is made where all processes started have established permanent connections.

For the balance_count operand of the client service definition, specify the number of remaining service requests to be processed by the transactional RPC execution processes.

clttrn_port=port-number-for-transactional-RPC-execution-process~ <unsigned integer> ((5001-65535))

This specifies the port number for a process that executes transactional RPC.

Specify a port number different from the well-known port number used in the other system server.

Assuming that this operand is omitted, if the rpc_port_base operand as a system common definition has been specified, the system assigns any port number in the range from the specified value of rpc_port_base to the specified value of rpc_port_base plus the prc_process_count value. If the rpc_port_base operand as a system common definition has not been specified, the system uses any assigned port number.

From the port number specified here, the system assigns the number specified by the parallel_count operand as a port number. Therefore, you should make sure that the sum of the value specified by this operand and the value specified by the parallel_count operand does not exceed 65535.

The port number specified using this operand must not be used by other programs.

Note that the operating system assigns certain numbers automatically. You should not use such a number for the port number. The numbers assigned by the operating system differ depending on the type and version of the operating system. For details, see the documentation for your operating system.

cltcon_port=port-number-for-CUP-execution-process<unsigned integer> ((5001-65535))

This specifies the port number for a CUP that execution process.

Specify a port number different from the well-known port number used in the other system server.

Assuming that this operand is omitted, if the rpc_port_base operand has been specified as a system common definition, the system assigns any port number in the range from the specified value of rpc_port_base to the specified value of rpc_port_base plus the prc_process_count value.

If the rpc_port_base operand as a system common definition has not been specified, the system uses any assigned port number.

From the port number specified here, the system assigns the number specified by the cup_parallel_count operand as a port number. Therefore, you should make sure that the sum of the value specified by this operand and the value specified by the cup_parallel_count operand does not exceed 65535.

The port number specified using this operand must not be used by other programs.

Note that the operating system assigns certain numbers automatically. You should not use such a number for the port number. The numbers assigned by the operating system differ depending on the type and version of the operating system. For details, see the documentation for your operating system.

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

This specifies an item or items from which statistics regarding the transaction branch are to be obtained.

nothing
You do not obtain any statistics.

base
You obtain the following information as basic information.
  • Identifier of a transaction branch
  • Result of settlement of a transaction branch
  • Execution process type of a transaction branch
  • Execution server name of a transaction branch
  • Execution service name of a transaction branch

executiontime
You obtain both basic information and the execution time information regarding a transaction branch.

cputime
You obtain both basic information and the CPU time information regarding a transaction branch.

Note that you can specify nothing only once. Specifying nothing together with any other item of statistics will nullify the nothing assignment.

When obtaining statistics about transactions, use one of the following:

This operand can also be specified in the DCCLTTRSTATISITEM operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

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

The following character string is used to specify an optimization item or items that will improve the performance of global transactions consisting of multiple user servers.

base
This optimizes all the processing to obtain synchronization points (prepare, commit, and rollback processing). Since the transaction control of OpenTP1 is executed on a two-phase commit basis, the commit control between transaction branches requires four cycles of inter-process communication.
Under the following conditions, the parent transaction branch conducts commit processing for its child transaction branch, so that it is possible to reduce the four cycles of inter-process communication required in commit control.
  1. Both the parent and child transaction branches exist under the same OpenTP1.
  2. The parent transaction branch uses a synchronization response RPC to call the child transaction branch.
  3. The XA interface object of the resource manager that is accessed in the child transaction branch has also been linked with the parent transaction branch.

asyncprepare
This optimizes the prepare processing when it is impossible to conduct all the processing to obtain synchronization points because the conditions specified in base are not satisfied.
Under the following conditions, if the child transaction branch executes a service request in accordance with the RPC that is issued from the parent transaction branch, the prepare processing is performed before the RPC returns. This reduces two cycles of inter-process communication.
  1. It is impossible to perform optimization from the base specification.
  2. The parent transaction branch uses a synchronization response RPC to call the child transaction branch.
    However, this optimization will elongate the response time for the synchronization response RPC issued by the parent transaction branch. Meanwhile, the child transaction branch will increase the interval from the prepare processing to the commit processing (a status in which no transactions can be settled unless there is support from the parent transaction branch). If, therefore, OpenTP1 for the parent transaction branch encounters a system down and the communication between transaction branches fails, it will take more time to swap journal files and validate checkpoint dump files. As a result, OpenTP1 for the child transaction branch may encounter a system down.

You can specify the same transaction optimization items more than once. Note that the priority goes as follows.(1.>2.)

  1. base
  2. asyncprepare

This operand can also be specified in the DCCLTTROPTIITEM operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

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

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

If the transaction branch receives no instruction or response within 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 has completed, the system process of the transaction service retries to determine the transaction.

This operand can also be specified in the DCCLTTRWATCHTIME operand in the client environment definition. For details, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. 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 in the DCCLTTRRBINFO operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

trn_limit_time=maximum-executable-time-for-transaction-branch <unsigned integer> ((0-65535)) <<0>> (unit: seconds)

This specifies the maximum executable time for transaction branches. From the time a transaction branch is started until processing for the synchronization point terminates, the time does not exceed the value specified in this operand, it is necessary to automatically set the timeout values for the dc_rpc_call function, the dc_rpc_poll_any_replies function, and the communication within synchronization point processing.

If any processing other than the above receive waiting takes time, the transaction branch may not terminate within the time specified in this operand.

If the time specified in this operand has been reached before the start of synchronization point processing, the transaction undergoes a rollback.

Specifying a value of 0 means that there will be not time monitor.

This operand can also be specified in the DCCLTTRLIMITTIME operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

trn_rollback_response_receive=Y|N~ <<Y>>

This specifies whether or not to receive an end-of-rollback notice after sending a rollback information to the RPC destination transaction branch. With N specified, the system terminates its own transaction branch without receiving an end-of-rollback notice from the RPC destination transaction branch (without waiting for the rollback processing at the RPC destination transaction branch to be completed).

This operand can also be specified in the DCCLTTRRBRCV operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. 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.

Specifying this operand in a client service definition is effective only when a transaction is started from the CPU.

If an RPC timeout causes, the address of a destination process for issuing the RPC not to be settled or if the UAP where a transaction is underway fails, the communication between transaction branches will degrade so that it may take time to settle transactions.

With this operand, the method of processing transaction synchronization points for any of the following faults is selected among from the three methods shown in the specified values.

Error 1
When there is an RPC timeout
In this case, the RPC-issuing transaction branch cannot identify the process executing the service request. Since the branch cannot identify the process, sending a message about the transaction synchronization point to the RPC-receiving transaction branch is impossible. Both the RPC-issuing and RPC-receiving transaction branches have to wait for the message about the transaction synchronization point, which requires time to settle the transaction.

Error 2
When the RPC-issuing UAP fails before receiving an RPC response
In this case, the RPC-issuing transaction branch cannot identify the process executing the service request. It thus 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, so that it will take time to settle the transaction.

Error 3
When the RPC-issuing UAP and the RPC-receiving UAP fails 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 message about a transaction synchronization point to a non-existing UAP process, which may take 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 message about the transaction synchronization point causes a timeout.
If Error 2 occurs, the RPC-issuing transaction branch settles the transaction without sending the message about the transaction synchronization point to the RPC-receiving transaction branch. The RPC-receiving transaction branch settles the transaction when the processing of the message about the transaction synchronization point 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 message about the transaction synchronization point 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 message about the transaction synchronization point to the transaction service process at the node where the RPC-receiving transaction branch exists, and then settles the transaction. When the transaction service process receives the message about the transaction synchronization point, a transaction synchronization point instruction is sent 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 message about the transaction synchronization point causes 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 message about the transaction synchronization point to the transaction service process at the node where the other party's transaction branch exists, and then settles the transaction. The transaction service process, when it has received the message about the transaction synchronization point, sends an instruction for transaction synchronization point to the process that is currently processing the transaction branch.

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

  1. During an RPC execution, the RPC-receiving UAP undergoes a status change (such as load increase, UAP termination, and 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 message of the transaction synchronization point.

This operand can also be specified in the DCCLTTRRECOVERYTYPE operand in the client environment definitions. For details about client environment definitions, see the manual OpenTP1 TP1/Client User's Guide TP1/Client/W, TP1/Client/P.

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

  1. Client environment definition
  2. Client service definition

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

Specify the maximum execution time of a transaction branch. If the execution time of the 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 maximum execution time of a transaction branch is not monitored.

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 operands of the user service definition.

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 the timer monitoring options, see A.2 Time monitoring for transactions.

message_store_buflen=size-of-the-message-storage-buffer-pool~<unsigned integer> ((1024-31457280))<<8196>> (units: bytes)

Specify the size of the shared memory pool that stores transactional RPC requests and permanent connection requests from a CUP before the requests are passed to the CUP executing process.

The following shows the formula for calculating the value to be specified in tis operand:

Size of the message storage buffer pool = D x C

D: Control data size (256 bytes)

C: The number of transactional RPC requests or the number of permanent connection requests, whichever is larger.

If the result of this formula is less than 8196, you do not need to specify this operand.

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

The execution process of the client extended service executes the RPC issued from a CUP as a proxy if the CUP starts a transaction or establishes a permanent connection. In this operand, specify the maximum length of wait time from the transmission of a service request up to the return of a response from the service when processes communicate using the RPC executed by the execution process as a proxy.

If no response is returned after the specified time, a reception timeout error is returned to the CUP.

When you specify 0, the system waits until it receives a response.

If DCWATCHTIMINHERIT=Y is specified in the client environment definition, the timer value of the CUP takes precedence over the timer value specified in this operand.

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

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.

Command format

None

Notes

As many transactions started up from CUPs as the processes specified in the parallel_count operand are executed in parallel. The server name for the process is _clttrn. The trnls command enables display of the transaction condition of the process.

The server name is indicated in a message that appears when the process is cancelled because of a factor such as the transaction branch expiration time.