OpenTP1 Version 7 System Definition

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

RAP-processing listener service definition

Format

set format

set rap_listen_port=RAP-processing-listener-port-number
[set rap_parallel_server=number-of-RAP-processing-servers]
[set rap_watch_time=maximum-monitor-time-for-message-send/receive]
[set rap_inquire_time=maximum-inquiry-interval]
[set nice=change-in-process-priority]
[set uap_trace_max=maximum-number-of-UAP-traces-stored]
 set uid=user-identifier-for-OpenTP1-system-administrator
[set rpc_response_statistics=Y|N]
[set rpc_trace=Y|N]
[set rpc_trace_name="RPC-trace-output-file"]
[set rpc_trace_size=size-of-RPC-trace-output-file]
[set trn_expiration_time=transaction-branch-timeout]
[set trn_expiration_time_suspend=Y|N|F]
[set trn_cpu_time=transaction-branch-CPU-time]
[set trf_put=Y|N]
[set trn_statistics_item=statistical-information-item[,statistical-
                         information-item]...]
[set trn_optimum_item=transaction-optimization-level
                      [,transaction-optimization-level]...]
[set trn_watch_time=timeout-of-transaction-synchronization-point-
                    processing]
[set trn_rollback_information_put=no|self|remote|all]
[set trn_limit_time=maximum-execution-time-of-transaction-branch]
[set trn_rollback_response_receive=Y|N]
[set trn_partial_recovery_type=type1|type2|type3]
[set rap_inquire_timeout_message=Y|N]
[set rap_connection_assign_type=dynamic|static]
[set rap_max_client=maximum-number-of-clients-simultaneously-
                    connected-to-RAP-processing-listener]
[set rap_notify=Y|N]
[set rap_client_manager_node="host-name:port-number"
                             [,"host-name:port-number"]...]
[set rap_max_buff_size=socket-window-size]
[set rap_io_retry_interval=interval-between-retries-to-send/receive-
                           a-message]
[set rap_sock_count=number-of-retries-to-create-a-socket]
[set rap_sock_interval=interval-of-retries-to-create-a-socket]
[set rap_connect_retry_count=number-of-retries-to-establish-a-
                             connection]
[set rap_connect_retry_interval=interval-between-retries-to-
                                establish-a-connection]
[set rap_listen_backlog=maximum-number-of-requests-that-can-be-
                        stored-in-connection-waiting-queue]
[set rap_msg_output_interval=interval-between-output-client-count-
                             messages]
[set rap_recovery_server=number-of-standby-RAP-processing-servers-
                         for-recovery-requests]
[set rap_connect_interval=interval-between-attempts-to-establish-
                          connection]
[set rpc_extend_function=RPC-service-facility-extension-level]
[set max_socket_descriptors=maximum-number-of-file-descriptors-
                            for-sockets]
[set trn_completion_limit_time=time-limit-for-completing-transaction]
[set rap_message_id_change_level=message-ID-change-level]
[set rap_term_disconnect_time=wait-time-for-disconnection-when-the-RAP-processing-listener-terminates]
[set rap_stay_watch_time=maximum-monitoring-time-for-a-request-waiting-for-allocation-of-an-RAP-processing-server]
[set rap_stay_warning_interval=interval-for-outputting-a-warning-message-for-a-request-remaining-in-the-queue]
[set log_audit_out_suppress=Y|N]
[set log_audit_message=message-ID-for-an-item-for-which-audit-log-data-is-to-be-acquired
                     [,message-ID-for-an-item-for-which-audit-log-data-is-to-be-acquired]...]
[set ipc_sockctl_highwater= percentage-of-sockets-at-which-temporary-closing-starts
                    [,percentage-of-sockets-for-which-temporary-closing-is-not-performed]]
[set ipc_sockctl_watchtime=length-of-time-to-wait-until-the-sockets-are-reusable]
[set watch_time=maximum-time-to-wait-for-a-response]

Command format

None.

Function

This definition specifies the RAP-processing listener service for using the remote API facility. With this definition specified, executing the rapdfgen command automatically creates a user service definition for the RAP-processing listener user service definition and the RAP-processing service user service definition for the RAP-processing server required for the use of the remote API facility.

Explanation

set format

rap_listen_port=RAP-processing-listener-port-number~ <unsigned integer> ((5001-65535))

This operand specifies the well-known port number used by a RAP-processing listener and a RAP-processing server. In case you activate more than one RAP-processing listener, be sure to specify different port numbers.

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.

rap_parallel_server=number-of-RAP-processing-servers~ <unsigned integer> ((1-1024)) <<1>>

This operand specifies the number of RAP-processing servers under the control of the related RAP-processing listener.

rap_watch_time=maximum-monitor-time-for-message-send/receive~ <unsigned integer> ((0-65535)) <<180>> (unit: seconds)

This operand specifies the monitor time between starting and completing a message send/receive operation between a RAP-processing listener and a RAP-processing server. In case the message send/receive operation is not completed after the specified monitor time has elapsed, the system issues a message and takes correction action in the manner as a network error.

Specifying a value of 0 means that the time monitoring did not provide.

rap_inquire_time=maximum-inquiry-interval~ <unsigned integer> ((0-1048575)) <<180>> (unit: seconds)

This operand specifies the maximum of the wait interval between inquiry responses from the client to the RAP-processing listener and RAP-processing server. This value is a timer that the RAP-processing listener and RAP-processing server monitors. If there is no inquiry even after the specified time has been exceeded, the system considers the client to have gone down.

Specifying a value of 0 means that the time interval is infinite.

When using the remote API facility from the resident SPP, do not specify 0 in this operand or the rpc_rap_inquire_time operand in the user service definition. If 0 is specified, the OpenTP1 system waits an unlimited amount of time for the resident SPP to terminate, because the RAP-processing listener cannot be terminated even if you try to terminate the OpenTP1 system of the node where the RAP-processing listener resides.

When the rpc_rap_inquire_time operand is omitted in the user service definition for an SPP or SUP, the value specified in this operand is regarded as the maximum amount of wait time. When both are omitted, 180 seconds is assumed.

nice=change-in-process-priority~ <unsigned integer> ((0-39)) <<0>>

This operand specifies the value to add to the nice value in this service group process. The process's nice value is a positive integer; the larger the value, the lower the CPU priority. For details about the nice value, see the manual for your operating system.

uap_trace_max=maximum-UAP-trace-count~ <unsigned integer> ((0-4095)) <<32>>

This operand specifies the number of records in UAP tracing.

If the UAP terminates abnormally, the system saves into the save core file the flow of the UAP's processing up to the point the error occurred.

When 0 is specified:
The UAP trace is not acquired.

When 1 or a greater value is specified:
The UAP trace of the specified value + 1 is acquired.

uid=user-identifier-for-OpenTP1-system-administrator~<unsigned integer> ((0-4294967294))

This operand specifies the user identifier that refers to the process owner of the service group.

In this case, specify the user identifier of the OpenTP1 manager.

The maximum value depends on the operating system. Check the documentation for your operating system.

rpc_response_statistics=Y|N~ <<N>>

This operand specifies whether or not to collect response statistics.

Y
Response statistics are collected.

N
Response statistics are not collected.

The response statistics include the response time for RPC calls, the execution time for services, and the CPU time for the server.

rpc_service_retry_count=maximum-number-of-service-retries~ <unsigned integer> ((0-65535)) <<0>>

This operand specifies the maximum number of times you can retry the service function using the service retry facility.

Specifying a value of 0 means not to use the service retry facility. Therefore, the dc_rpc_service_retry function returns an error; the service function will not be retried.

With a non-0 value specified, the service function is retried according to the count specified. If the dc_rpc_service_retry function is called after there has been more retries than the specified count, the function returns an error; the service function will not be retried.

rpc_trace=Y|N

Specify whether to acquire the RPC trace.

Y
Acquires the RPC trace.

N
Does not acquire the RPC trace.

You can also specify this operand in the system common definition or in the user service default definition.

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

  1. RAP-processing listener service definition
  2. User service default definition
  3. System common definition

When an RPC trace is acquired, the processing speed may be reduced and the RPC may return an error due to a timeout. In this case, increase either of the following values, which are the maximum amount of response waiting time (default: 180 sec.), to an appropriate value:

  1. The maximum response waiting time specified in the watch_time operand of the system common definition, user service definition, or user service default definition
  2. The maximum response waiting time that the RAP-processing server inherited from the client

Whether the RAP-processing server inherits the maximum response waiting time from the client is specified in the DCWATCHTIMINHERIT operand of the client environment definition (for TP1/Client/W or TP1/Client/P) or in the dcwatchtiminherit operand of the TP1/Client/J environment definition (for TP1/Client/J).

If Y is specified in the DCWATCHTIMINHERIT or dcwatchtiminherit operand, use the maximum response waiting time indicated in 2 above.

If N is specified in the DCWATCHTIMINHERIT or dcwatchtiminherit operand, or if these operands are not specified, use the maximum response waiting time indicated in 1 above.

Specifying the rpc_trace operand in the RAP-processing listener service acquires only the messages received or sent regarding the service requests that the RAP-processing server executed by proxy. The messages do not include those that the RAP-processing server received from the RAP-processing client.

rpc_trace_name="RPC-trace-output-file"~<path name>

Specify the path name of the file for storing the RPC trace.

In the path name, the maximum length of the name of the file for acquiring the RPC trace is 13 characters. The default file name is rpctr.

To specify an environment variable in a path name, make sure that the path name begins with the environment variable (example: $DCDIR/tmp/file-name).

You can also specify this operand in the system common definition. If you specify this operand both in the RAP-processing listener service definition and in the system common definition, the value of the operand in the RAP-processing listener service definition prevails.

rpc_trace_size=size-of-RPC-trace-output-file~<unsigned integer> ((1024-2147483648)) (units: bytes)

Specify the size of the file for storing the RPC trace.

You can also specify this operand in the system common definition. If you specify this operand both in the RAP-processing listener service definition and in the system common definition, the value of the operand in the RAP-processing listener service definition prevails.

trn_expiration_time=transaction-branch-timeout~<unsigned integer> ((0-65535)) (units: seconds)

Specify the timeout of the transaction branch processing. If a timeout occurs, the system abnormally terminates the process of the transaction branch and performs a rollback. If you specify 0, a timeout does not occur.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

Instead of specifying this operand, you can also specify the timeout by issuing a function. For details on functions, see the OpenTP1 Programming Guide.

trn_expiration_time_suspend=Y|N|F

When performing the time monitoring of transaction branch processing, specify whether to include the following periods of time:

  1. The time that the monitored transaction branch uses the RPC facility to call another transaction branch and waits until the called transaction branch terminates
  2. The time that a server UAP called by chained RPCs waits for the next service request
  3. The time that the monitored transaction branch uses an asynchronous RPC to call another transaction branch and then to receive the processing result
    Y
    Includes all of the periods of time in 1., 2. and 3. above.
    N
    Includes only 3.
    F
    Includes none of 1., 2., and 3.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

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

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

Specify the CPU time that the transaction branch can use before the synchronization point processing. If you specify 0, the system does not monitor the CPU time. If the specified CPU time expires, the system abnormally terminates the process of the transaction branch and performs a rollback.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

trf_put=Y|N

Specify whether the journal output by the transaction started on the server should be output to the transaction recovery journal file.

Y
Outputs the journal to the transaction recovery journal file.

N
Does not output the journal to the transaction recovery journal file.

When the transaction recovery journal file is created, you can prevent a journal error from occurring caused by a long-term transaction. You can also reduce the rerun time. On the other hand, this function causes an overhead for performance and memory. Therefore, you should create the transaction recovery journal file for a server that uses a transaction for a long time.

In the OpenTP1 system that uses the system switchover function, you cannot use this function. Therefore, specify N for the trf_put operand in the RAP-processing listener service definition and the user service definition.

trn_statistics_item=statistical-information-item[,statistical-information-item]...

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:

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

trn_optimum_item=transaction-optimization-level[,transaction-optimization-level]...

You can specify the level of optimizing the performance of the global transaction consisting of multiple user servers.

base
Optimizes all the processing of synchronization point acquisition (prepare, commit, and rollback). Since OpenTP1 uses the two-phase commit method to control transactions, a commit between two transaction branches requires inter-process communication four times.
This optimization eliminates inter-process communication that occurs four times per commit by referring the commit execution of a child transaction branch to its parent transaction branch when all the following conditions are satisfied:
  1. A parent transaction branch and its child transaction branch belong to the same OpenTP1 system.
  2. A parent transaction branch uses a synchronous-response RPC to call the child transaction branch.
  3. An object which a child transaction branch accessed for the XA interface of the resource manager is linked with the parent transaction branch.

asyncprepare
Optimizes only the prepare processing if optimization of the entire processing of synchronization point acquisition is impossible because not all of the conditions are satisfied.
When a service request is executed by a child transaction branch called by an RPC from the parent transaction branch, inter-process communication occurs twice. This optimization eliminates this inter-process communication by executing the prepare processing before returning the RPC. This optimization is possible when all the following conditions are satisfied:
  1. The optimization for all the processing of synchronization point acquisition by specifying the keyword base cannot be performed.
  2. A parent transaction branch uses a synchronous-response RPC to call the child transaction branch.
    Note that executing this optimization (asyncprepare) slows the response of the synchronous-response RPC issued by the parent transaction branch. For the child transaction branch, the interval between the prepare processing and the commit processing becomes longer (because the child transaction branch cannot be resolved until the parent transaction branch makes an instruction). If a system failure occurs in the OpenTP1 system of a parent transaction branch, the communication between transaction branches also fails.
    This slows swapping the journal file and applying the checkpoint dump file, thus possibly causing the OpenTP1 system of the child transaction branch to fail.

If you specify more than one keyword, the priorities of the keywords are (1.>2.):

  1. base
  2. asyncprepare

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

trn_watch_time=timeout-of-transaction-synchronization-point-processing~<unsigned integer> ((1-65535)) (units: seconds)

Specify the timeout of communication between transaction branches (timeout of waiting for an instruction or response about the prepare, commit, or rollback processing).

If an instruction or response is not received until the specified time expires, OpenTP1 rolls back the transaction branch (if the phase-1 commit is not completed yet) or uses the system process of the transaction service to retry resolving the transaction (if the phase-1 commit is completed).

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

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

trn_rollback_information_put=no|self|remote|all

If a rollback of a transaction branch occurs, you can log the information about the cause of the rollback.

no
Does not log the rollback information.

self
Logs the rollback information about only the transaction branches where the cause of the rollback occurred.

remote
In addition to the information logged by specifying the keyword self, OpenTP1 logs the rollback information about the transaction branches for which a rollback request was sent by a transaction branch of the remote node.

all
In addition to the information logged by specifying the keyword remote, OpenTP1 logs the rollback information about the transaction branches for which a rollback request was sent by a transaction branch of your own node.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

trn_limit_time=maximum-execution-time-of-transaction-branch~ <unsigned integer> ((0-65535)) (units: seconds)

Specify the time that can be used for executing the transaction branch. The timeouts of the communication for the function dc_rpc_call(), for the function dc_rpc_poll_any_replies() and for the synchronization point processing are automatically set as shown below so that the time period from the start of the transaction branch until completion of the synchronization point processing does not exceed the value specified in this operand.

If a long time is also taken for other processing than the above timeout, the transaction branch may not be terminated in the time specified in this operand.

If the value specified in this operand expires before starting the synchronization point processing, the transaction is rolled back.

If you specify 0, the time monitoring is not performed.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

trn_rollback_response_receive=Y|N~<<Y>>

After sending a rollback instruction to the RPC destination transaction branch, you can be notified of completion of the rollback. When you specify N, your transaction branch terminates without receiving the notification of the rollback completion from the RPC destination transaction branch (without waiting until the rollback of the RPC destination transaction branch is completed).

If you omit this specification here and in the user service default definition, the system assumes the value in the transaction service definition.

trn_partial_recovery_type=type1|type2|type3

Specify how to handle the transaction synchronization-point processing if the UAP fails.

If the timeout of an RPC prevents the transaction from determining the address of the process that issued the RPC or the timeout causes the UAP executing the transaction to fail, communication between transaction branches cannot be performed smoothly. As a result, it may take a long time to resolve the transaction.

There are three kinds of processing at the transaction synchronization point for the following errors.

Error 1
The timeout of an RPC occurs
In this case, the transaction branch that issued the RPC does not know which process executed the service request. Therefore, the transaction branch that issued the RPC cannot send a transaction synchronization-point message to the RPC-destination transaction branch. This causes both transaction branches to wait a transaction synchronization-point message. As a result, it takes a long time to resolve the transaction.

Error 2
The UAP that issued an RPC fails before receiving the response of the RPC
In this case, the transaction branch that issued the RPC does not know which process executed the service request. Therefore, the transaction branch that issued the RPC cannot send a transaction synchronization-point message to the RPC-destination transaction branch. This causes the RPC-destination transaction branch to wait a transaction synchronization-point message. As a result, it takes a long time to resolve the transaction.

Error 3
After reception of the response from the RPC-destination UAP, both the RPC-issuer UAP and the RPC-destination UAP fail at nearly the same time
In this case, a transaction recovery process is activated to inherit the transaction branch for each UAP process, but each of the transaction recovery processes is not notified that the other UAP process has failed. This causes the transaction recovery processes to send a transaction synchronization-point message to the UAP processes that no longer exist. As a result, it may take a long time to resolve the transaction.
You can specify one of the following three types of error handling:

type1
If error 1 occurs, a timeout is applied to reception of the transaction synchronization-point message for the transaction branch that issued the RPC and for the RPC-destination transaction branch. The transaction can be resolved after the timeout.
If error 2 occurs, the transaction branch that issued the RPC resolves the transaction without sending a transaction synchronization-point message to the RPC-destination transaction branch. The RPC-destination transaction branch resolves the transaction when a timeout occurs for reception of the transaction synchronization-point message.
If error 3 occurs, the transaction branch that issued the RPC and the RPC-destination transaction branch resolve the transaction when a timeout occurs for reception of the transaction synchronization-point message.

type2
For error 1, the error handling is the same as type1 when performing a commit for the transaction. If a rollback of the transaction should be performed due to error 1 or if error 2 occurs, the transaction branch that issued the RPC sends a transaction synchronization-point message to the transaction service process of the node where the RPC-destination transaction branch exists. Then, transaction branch that issued the RPC resolves the transaction. Receiving the message, the transaction service process sends an instruction of transaction synchronization-point processing to the process that is executing the transaction branch.
If error 3 occurs, the transaction branch that issued the RPC and the RPC-destination transaction branch resolve the transaction when a timeout occurs for reception of the transaction synchronization-point message.

type3
For error 1, the error handling is the same as type1 when performing a commit for the transaction.
If a rollback of the transaction should be performed due to error 1, if error 2 occurs, or if error 3 occurs, the transaction branch sends a transaction synchronization-point message to the transaction service process of the node where the other transaction branch exists. Receiving the message, the transaction service process sends an instruction of transaction synchronization-point processing to the process that is executing the transaction branch.

In the following cases, it may take a long time to resolve the transaction even when you specify type2 or type3:

  1. During execution of the RPC, the status of the UAP that issued the RPC is changed (the load is increased, the UAP is terminated, the UAP is shut down, etc.) and the service request is re-transferred to the same UAP running on another node.
  2. The OpenTP1 of the other transaction branch is not a version supporting this option.
  3. It takes a long time for the other transaction branch to execute processing other than reception of a transaction synchronization-point message.

You can also specify this operand in the transaction service definition or in the user service default definition.

The priorities of the definitions are (1.>2.>3.):

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

rap_inquire_timeout_message=Y|N~<<Y>>

This operand specifies whether to output an error message if the system detects that the maximum wait time for a request from a client has been reached. An error message is output if you specify Y for this operand or if you specify nothing.

Y
Outputs an error message if the system detects that the maximum wait time for a request from a client has been reached.

N
Does not output an error message if the system detects that the maximum wait time for a request from a client has been reached.

This operand suppresses the following messages:

rap_connection_assign_type=dynamic|static~<<static>>

This operand specifies whether to use the dynamic connection schedule facility.

dynamic
Uses the dynamic connection schedule facility.

static
Does not use the dynamic connection schedule facility.

If you use the dynamic connection schedule facility and the server load increases, the response performance may decrease compared to the static connection schedule facility. When you are using the dynamic connection schedule facility, the RAP-processing server processes the requests other than connect requests (the RAP-processing listener processes connect requests). If there is no RAP-processing server to be allocated when a client issues a request, the request will remain in the RAP-processing listener. Check the number of running RAP-processing servers if the dc_rpc_call() that the RAP-processing server requests to execute elsewhere takes too much time or if there is a client in the transaction status. If too few RAP-processing servers are running, requests from clients may time out and return an error.

rap_max_client=maximum-number-of-clients-simultaneously-connected-to-RAP-processing-listener~<unsigned integer>((128-1024))<<256>>

This operand specifies the maximum number of clients that are simultaneously connected to the RAP-processing listener.

rap_notify=Y|N~<<N>>

Specify whether to issue a startup notification to the RAP-processing client manager to be started in the node specified in the rap_client_manager_node operand when the RAP-processing listener in the local node starts up.

Y
Issues a startup notification.

N
Does not issue a startup notification

When Y is specified, the rap_client_manager_node operand cannot be omitted.

rap_client_manager_node="host-name:port-number" [,"host-name:port-number"]...

When Y is specified in the rap_notify operand to use the startup notification facility, a startup notification is issued to the RAP-processing client manager of OpenTP1 to be started in the node specified in this operand. With the startup notification facility, you can manage the time when a connection is established. This ensures that messages are transmitted.

When Y is specified in the rap_notify operand, this operand cannot be omitted.

host-name~<1-255 alphanumeric characters, including periods and hyphens>
Specifies the host name of the OpenTP1 system having the RAP-processing client which connects to the RAP-processing listener in the local node. Use the host name defined in /etc/hosts.

port-number~<unsigned integer> ((1-65535))
Specifies the port number of the RAP-processing client manager of the OpenTP1 system having the RAP-processing client which connects to the RAP-processing listener in the local node.

rap_max_buff_size=socket-window-size~<unsigne dinteger> ((4-2147483647))<<4>>(unit: kilobytes)

Specify the window size of the socket.

rap_io_retry_interval=interval-between-retries-to-send/receive-a-message~<unsigned integer>((1-999))<<35>>(unit: milliseconds)

Specify the interval between retries to send or receive a message.

rap_sock_count=number-of-retries-to-create-a-socket~<unsigned integer> ((0-65535))<<1>>

Specify the number of retries to create a socket if an EAGAIN or EWOULDBLOCK error occurs during socket creation.

rap_sock_interval=interval-of-retries-to-create-a-socket~<unsigned integer> ((15-500))<<30>>(unit: milliseconds)

Specify the interval between retries to create a socket if an EAGAIN or EWOULDBLOCK error occurs during socket creation.

rap_connect_retry_count=number-of-retries-to-establish-a-connection~<unsigned integer>((8-2147483647))<<8>>

Specify the number of retries to establish a connection if an ECONNREFUSED error occurs during connection establishment of the communication control part.

rap_connect_retry_interval=interval-between-retries-to-establish-a-connection~<unsigned integer>((10-999))<<100>>(unit: milliseconds)

Specify the interval between retries to establish a connection if an ECONNREFUSED error occurs during connection establishment of the communication control part.

rap_listen_backlog=maximum-number-of-requests-that-can-be-stored-in-connection-waiting-queue~<unsigned integer>((SOMAXCONN to 2147483647)) <<SOMAXCONN>>

Specify the maximum number of requests held in the connection waiting queue. SOMAXCONN that is used as the minimum value and default value of the rap_listen_backlog operand is the value of SOMAXCONN in the environment in which OpenTP1 was compiled. For details, see the Release Notes.

Note that the setting of this operand takes effect only when the following condition is satisfied:

The value of SOMAXCONN in the environment in which OpenTP1 was compiled [Figure] the value of SOMAXCONN in the production environment

The value specified in this operand is only set in the backlog count of the listen() system call that the RAP-processing listener issues, and the actual control of backlog depends on the OS.

Different OSs may provide different defaults. For details about OS-specific defaults (real number values), see the Release Notes.

rap_msg_output_interval=interval-between-output-client-count-messages~<unsigned integer>((0-32767))<<0>> (unit: minutes)

Specify the interval between messages indicating the number of clients. These messages are output when a client is connected when the RAP-processing listener is ending. When a client is connected even after this message is output and the length of time specified in this operand is exceeded, another message indicating the number of clients is output.

When you specify 0 for this operand, the message indicating the number of clients is output only once.

Note that the RAP-processing listener monitors events every three seconds.

rap_recovery_server=number-of-standby-RAP-processing-servers-for-recovery-requests~<unsigned integer>((0-value specified in the rap_parallel_server operand - 1)) <<0>>

Specify the number of standby RAP-processing servers that are waiting for recovery requests from clients when the XA resource service is used. These RAP-processing servers receive only recovery requests, and do not receive normal service requests. The recommended number of standby RAP-processing servers for recovery requests is one per J2EE server.

rap_connect_interval=interval-between-attempts-to-establish-connection~<unsigned integer>((0-999))<<40>> (unit: milliseconds)

Specify the interval at which an attempt is made to establish a connection between a RAP-processing listener and a RAP-processing server when the remote API service starts.

Connection is established at the interval specified in this operand for the maximum number of requests that can be queued in the connection wait queue.

rpc_extend_function=RPC-service-facility-extension-level~<hexadecimal number>((00000000-0000000F))<<00000000>>

Specify an extension level of the RPC service facility from the following.

If you want to specify multiple extension levels, specify a logical OR for the specified values.

00000000
The RPC service facility is not extended.

00000001
If the SPP that is currently executing a service request terminates abnormally, the dc_rpc_call, dc_rpc_call_to and dc_rpc_poll_any_replies functions return DCRPCER_SERVICE_TERMINATED (00378).

00000002
Non-transaction chained RPC calls (made by using the dc_rpc_call or dc_rpc_call_to function with DCRPC_TPNOTRAN set in flags) started in a transaction do not stop at synchronization point processing. The non-transaction chained RPC calls continue until they are explicitly terminated by using the dc_rpc_call or dc_rpc_call_to function with DCNOFLAGS specified in flags.

00000004
The response message of the asynchronous response RPC with the non-transaction attribute is not discarded when the response message of the asynchronous response RPC is not received and the asynchronous point processing of the transaction is performed. Only the response message of the asynchronous response RPC with the transaction attribute is deleted.

00000008
The KFCA00339-W message is output when processing stops and the service request is discarded because the response to the dc_rpc_call or dc_rpc_call_to function caller times out in the SPP process.

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.

#: OpenTP1 processes other than the MCF services (MCF manager service, MCF communication service, and application startup service). For the MCF services, see the sections on the system service information definition and the system service common information definition.

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

[Figure](Number of UAP processes communicated by the user server#1 + number of system service processes#2)/0.8[Figure]

[Figure] [Figure]: Rounded up to the nearest whole integer.

#1: The number of UAP processes communicated by the user server is the sum of the following values:
  • Number of UAP processes in the local OpenTP1 the user server communicates with
  • Number of UAP processes in other nodes the user server communicates with

#2: 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.

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

  1. RAP-processing listener service definition
  2. User service default definition
  3. System common definition

If this operand is omitted here and in the user service default definition, the system assumes the value in the system common definition.

trn_completion_limit_time=time-limit-for-completing-transaction~<unsigned integer> ((0-65535)) (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 the 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 RAP-processing server alternatively executes an API function such as dc_trn_begin to start a transaction. The monitoring ends when the transaction branch terminates after acquisition of information about the synchronization point processing of the transaction (TJ). 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.

Note that the trn_completion_limit_time operand can be specified in the transaction service definition or user service default definition.

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

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

rap_message_id_change_level=message-ID-change-level ~<unsigned integer> ((0-2))

For an error message that is likely to be output when the remote API facility is used, you can specify level 0 to 2 to change the message ID in order to change the message type from E to W. Each level is described below.

Use this operand when you monitor the message log and use it to change the management method depending on whether the message type is E or W.

Note that specification of this operand changes only the message ID, and does not change the message text.

0
The message ID is not changed. The message is output with its original message ID.

1
The message ID is changed in order to change the message type from E to W under conditions in which a specific reason code is output.

2
The message ID is always changed in order to change the message type from E to W.

The following table shows how the message to be output changes according to the value of this operand.

Table 3-7 Values of the rap_message_id_change_level operand and the messages to be output

Possible message ID change From KFCA26965-E to KFCA27790-W From KFCA26970-E to KFCA27791-W From KFCA26971-E to KFCA27792-W
Value of the rap_message_id_change_level operand 0 1 2 0 1 2 0 1 2
Reason code 8 -- -- -- E W W -- -- --
22 E E E E E E E E E
24 -- -- -- E E E -- -- --
31 E E W E E W E E W
32 E E W E E W E E W
35 E E W -- -- -- E E E
36 E W W E W W E W W
37 E E E E E E E E E
38 -- -- -- E W W -- -- --
71 E W W -- -- -- -- -- --
81 -- -- -- E E E -- -- --
82 -- -- -- E W W -- -- --
83 -- -- -- E E E -- -- --
91 E W W -- -- -- -- -- --

Legend:
E: A message with type E is output.
W: A message with type W is output.
--: Not applicable

If specification of this operand is omitted, the corresponding specification in the user service default definition is assumed.

rap_term_disconnect_time=wait-time-for-disconnection-when-the-RAP-processing-listener-terminates ~<unsigned integer> ((0-3600)) <<0>> (units: seconds)

Specify the time to wait for RAP-processing client disconnection when the RAP-processing listener terminates. When the time specified in this operand has elapsed following termination of the RAP-processing listener, the connection is closed and either message KFCA27763-W or FCA27765-W is output. However, the connection is not closed if the RAP-processing server is alternatively executing an API function. If this operand is omitted or specified as 0, the connection is not closed until a disconnection request from the RAP-processing client arrives or the maximum inquiry interval expires.

For this operand, we recommend that you specify a value smaller than the value of the system_terminate_watch_time operand in the system environment definition. In the following cases, the dcstop command might time out because it is waiting for termination of the RAP-processing listener:

Note that because the RAP-processing listener performs an event check at three-second intervals, there might be a maximum error of three seconds for the time specified in this operand.

rap_stay_watch_time=maximum-monitoring-time-for-a-request-waiting-for-allocation-of-an-RAP-processing-server ~<unsigned integer> ((0-65535)) <<30>> (units: seconds)

Specify the monitoring time for a RAP-processing client request that remains in the queue. If no RAP-processing servers that can process a request from an RAP-processing client are available, the request waits until an RAP-processing server becomes available. If the time that the request waits for allocation exceeds the time specified in this operand, the KFCA27764-W message is output. If 0 is specified in this operand, no time monitoring is performed.

For this operand, we recommend that you specify a value smaller than the maximum response wait time specified on the RAP-processing client. If the value of this operand is greater than the maximum response wait time specified on the RAP-processing client, the KFCA27764-W message might be output even for a request that the client has already assumed to have timed out.

Note that because the RAP-processing listener performs an event check at three-second intervals, there might be a maximum error of three seconds for the time specified in this operand.

rap_stay_warning_interval=interval-for-outputting-a-warning-message-for-a-request-remaining-in-the-queue ~<unsigned integer> ((3-65535)) <<180>> (units: seconds)

Specify the interval for outputting the KFCA27764-W message if a request from a RAP-processing client is queued for a long time. After the KFCA27764-W message is output, the message is not output again until the time specified in this operand elapses. This operand is ignored if 0 is specified for the rap_stay_watch_time operand.

Note that because the RAP-processing listener performs an event check at three-second intervals, there might be a maximum error of three seconds for the time specified in this operand.

log_audit_out_suppress>=Y|N ~<<N>>

Specify whether to suppress output of audit log data from the RAP-processing listener and server.

Y
Output of audit log data from the RAP-processing listener and server is suppressed.

N
Output of audit log data from the RAP-processing listener and server is not suppressed.

This operand takes effect only when Y is set for the log_audit_out operand in the log service definition.

log_audit_message=message-ID-for-an-item-for-which-audit-log-data-is-to-be-acquired[,message-ID-for-an-item-for-which-audit-log-data-is-to-be-acquired]... ~<unsigned integer> ((33400-99999))

Specify the message IDs for audit log data items that are acquired by OpenTP1 and that can be specified in the RAP-processing listener service definition. You can specify a maximum of 2048 message IDs.

For the message IDs that can be specified in this operand, see Appendix C.

If this operand is omitted in the RAP-processing listener service definition when it is also omitted in the user service default definition, the value of this operand in the log service definition is assumed. This operand takes effect when Y is specified for the log_audit_out operand in the log service definition and N is specified for the log_audit_out_suppress operand in the RAP-processing listener service definition.

ipc_sockctl_highwater=percentage-of-sockets-at-which-temporary-closing-starts[,percentage-of-sockets-for-which-temporary-closing-is-not-performed]

~<unsigned integer>((0-100))

For the max_socket_descriptors operand specification value, specify a percentage of sockets at which temporary closing starts.

When the number of file descriptors that are used for the sockets in a process exceeds the following value, OpenTP1 starts temporary closing.

value-specified-in-the-max_socket_descriptors-operand x (percentage-of-sockets-at-which-temporary-closing-starts [Figure] 100)

If you specify 0 for the percentage of sockets at which temporary closing starts, temporary closing is executed each time a connection is established. For details about temporary closing, see the manual OpenTP1 Description.

You can also specify the percentage of connections that are not to be temporarily closed. The system calculates the number of connections that are not to be temporarily closed as follows:

value-specified-in-the-max_socket_descriptors-operand x (percentage-of-sockets-for-which-temporary-closing-is-not-performed [Figure] 100)

The percentage of sockets for which temporary closing is not performed should be less than the percentage of sockets at which temporary closing starts. If you specify a value greater than the percentage of sockets at which temporary closing starts, the system assumes the same value as the percentage of sockets at which temporary closing starts.

OpenTP1 chronologically manages the connections that are established within a process. When you specify the percentage of sockets for which temporary closing is not performed, the temporary closing requests are sent starting with the earliest connection that was established.

This operand is used to specify the percentage of sockets at which temporary closing starts, as a percentage of the value specified in the max_socket_descriptors operand. If a small value is specified for the max_socket_descriptors operand and also for this operand (the percentage of sockets at which temporary closing starts), many temporary closing requests occur, affecting performance or causing communications failures.

If you omit this specification here and in the user service default definition, the system assumes the value in the system common definition.

ipc_sockctl_watchtime=length-of-time-to-wait-until-the-sockets-are-reusable

~<unsigned integer>((0-65535)) (Unit: seconds)

Specify the length of time (seconds) to wait, from the moment the number of file descriptors used for the sockets in the process reaches the value specified in the max_socket_descriptors operand until the sockets become reusable due to temporary closing.

Since temporary closing uses mutual agreement to disconnect the connection between processes, the process that sends the request for temporary closing cannot disconnect the connection until it receives the response. When the process receives the response, the connection is disconnected, and the sockets can be reused.

If no process returns a response to the request for temporary closing after the length of time specified in the ipc_sockctl_watchtime operand is exceeded, the process that sent the request is forcibly terminated. If you specify 0 for the ipc_sockctl_watchtime operand, the wait time is unlimited.

If you omit this specification here and in the user service default definition, the system assumes the value in the system common definition.

watch_time=maximum-time-to-wait-for-a-response ~<unsigned integer> ((0-65535)) (units: seconds)

Specify the maximum time to wait from the time that a service request is sent until a service response is returned when the RAP-processing server alternatively executes an RPC.

OpenTP1 termination processing might wait for the time specified in this operand. Therefore, if you specify a large value in this operand, OpenTP1 termination processing might take time.

If there is no response for the specified period of time, the RPC returns a timeout error. If 0 is specified, OpenTP1 waits until it receives a response. Note also that if 0 is specified, OpenTP1 might not be able to terminate.

Make sure that you use this operand as the default value for the watch_time operand in the system common definition.

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

Note that if the value of this operand is very much larger or smaller than the default value of the watch_time operand in the system common definition, difficulties that can cause OpenTP1 to fail might occur.

If this operand is omitted in the RAP-processing listener service definition when it is also omitted in the user service default definition, the value of this operand in the system common definition is assumed. However, if the RAP-processing client has been set so that the maximum time to wait for a response is inherited, the value set on the RAP-processing client is used.

Command format

None.

Cautions