OpenTP1 Version 7 System Definition

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

User service definition

Format

set format

 set service_group="service-group-name"
 set module="execution-format-program-name"
 set service="service-name=entry-point-name[;UAP-shared-library-name]"
           [,"service-name=entry-point-name[;UAP-shared-library-name]"]...
[set nice=changing-process-priority]
[set parallel_count=resident-process-count [,maximum-process-
                    count]]
[set hold=Y|N]
[set hold_recovery=Y|N]
[set deadlock_priority=deadlock-priority-position]
[set schedule_priority=schedule-priority-position]
[set message_buflen=maximum-message-length]
[set message_store_buflen=message-storage-buffer-pool-length]
[set trn_expiration_time=transaction-branch-expiration-time]
[set trn_expiration_time_suspend=Y|N|F]
[set watch_next_chain_time=chained-RPC-maximum-time-interval]
[set atomic_update=Y|N]
[set receive_from=queue|socket|none]
[set uap_trace_max=maximum-UAP-trace-count]
[set uap_trace_file_put=Y|N]
[set term_watch_time=abnormal-termination-check-expiration-time]
[set mcf_jnl_buff_size=MCF-journal-buffer-size]
[set type=other|MHP]
[set balance_count=number-of-service-requests-processed-by-a-process]
[set uid=user-ID]
[set auto_restart=Y|N]
[set critical=Y|N]
[set lck_wait_priority=lock-waiting-priority]
[set mcf_psv_id=application-startup-process-ID]
[set trn_cpu_time=transaction-branch-CPU-check-time]
[set service_hold=Y|N]
[set service_priority_control=Y|N]
[set message_cell_size=storage-cell-length-of-schedule-message]
[set max_socket_msg=maximum-number-of-messages-that-the-server-can-
                    receive-from-the-socket]
[set max_socket_msglen=maximum-length-of-messages-that-the-server-
                       can-receive-from-the socket]
[set trf_put=Y|N]
[set mcf_mgrid=application-startup-process-MCF-manager-identifier]
[set mcf_service_max_count=maximum-number-of-issued-MCF-
                           communication-functions]
[set trn_statistics_item=statistical-information-item [,statistical-
                         information-item]...]
[set node_down_restart=Y|N]
[set rpc_response_statistics=Y|N]
[set server_type="betran"|"xatmi"|"xatmi_cbl"]
[set trn_rm_open_close_scope=process|transaction]
[set trn_optimum_item=transaction-optimization-item
                      [,transaction-optimization-item]...]
[set purge_msgget=Y|N]
[set cancel_normal_terminate=Y|N]
[set prc_abort_signal=abort-signal-number]
[set rpc_service_retry_count=maximum-number-of-service-retries]
[set rpc_extend_function=facility-extension-level-of-RPC-service]
[set max_socket_descriptors=maximum-number-of-file-descriptors-for-
                            sockets]
[set max_open_fds=maximum-number-of-files-and-pipes-accessed-by-a-
                  UAP-process]
[set service_term_watch_time=abnormal-termination-check-expiration-
                             time-for-service]
[set termed_after_service=Y|N]
[set xat_trn_expiration_time=period-of-time-to-monitor-the-expiration-
                             of-synchronization-point-processing]
[set xat_osi_usr=Y|N]
[set rpc_trace=Y|N]
[set rpc_trace_name="RPC-trace-collection-file-name"]
[set rpc_trace_size=RPC-trace-collection-file-capacity]
[set trn_rollback_information_put=no|self|remote|all]
[set schedule_method=msgque|namedpipe]
[set service_wait_time=service-request-waiting-time-for-non-resident-
                       server-processes-of-the-user-server]
[set mcf_spp_oj=Y|N]
[set adm_message_option=message-output-specification]
[set trn_watch_time=maximum-communication-wait-time-for-
                    synchronization-point-processing-of-transactions]
[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 rpc_destination_mode=namdonly|namd|definition]
[set rpc_rap_auto_connect=Y|N]
[set rpc_rap_inquire_time=maximum-inquiry-interval-for-request-
                          service-using-the-remote-API-facility]
[set rpc_request_cancel_for_timedout=Y|N]
[set status_change_when_terming=Y|N]
[set service_expiration_time=execution-monitor-time-from-service-
                             function-startup-to-termination]
[set multi_schedule=Y|N]
[set make_queue_on_starting=Y|N]
[set loadcheck_interval=load-check-interval]
[set levelup_queue_count=U1,U2]
[set leveldown_queue_count=D0,D1]
[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 ipc_conn_interval=length-of-time-to-wait-until-the-connection-is-
                       established]
[set ipc_send_interval=interval-for-monitoring-data-transmission]
[set ipc_send_count=number-of-times-data-transmission-is-monitored]
[set ipc_header_recv_time=length-of-time-to-wait-until-the-
                          communication-control-data-is-received]
[set rpc_send_retry_count=number-of-retries-if-an-error-occurs-
                          during-TCP/IP-connection]
[set rpc_send_retry_interval=interval-between-retries-if-an-error-
                             occurs-during-TCP/IP-connection]
[set ipc_recvbuf_size=receive-buffer-size-of-TCP/IP]
[set ipc_sendbuf_size=send-buffer-size-of-TCP/IP]
[set ipc_listen_sockbufset=Y|N]
[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 loadlevel_message=Y|N|A]
[set ipc_backlog_count=length-of-queue-storing-connection-
                       establishment-requests]
[set rpc_buffer_pool_max=number-of-buffers-to-be-pooled]
[set schedule_delay_limit=schedule-delay-limit]
[set schedule_delay_abort=Y|N]
[set rap_autoconnect_con_error_msg=Y|N]
[set core_shm_suppress=Y|N]
[set xat_connect_resp_time=maximum-response-wait-time-for-
                           association-establishment-of-SPP-for-
                           processing-communication-events]
[set scd_poolfull_check_interval=interval-at-which-message-
                                 KFCA00853-E-is-output]
[set scd_poolfull_check_count=threshold-for-determining-whether-to-
                              output-message-KFCA00853-E]
[set scd_pool_warning_use_rate=maximum-use-rate-for-the-message-
                               storage-buffer-pool-triggering-output-
                               of-a-warning-message]
[set scd_pool_warning_interval=interval-at-which-a-warning-message-
                               is-output-if-the-use-rate-for-the-
                               message-storage-buffer-pool-is-
                               exceeded]
[set ipc_tcpnodelay=Y|N]
[set stay_watch_queue_count=number-of-service-requests-triggering-
                            the-start-of-judgment-of-the-schedule-
                            queue-accumulation-status]
[set stay_watch_check_rate=service-request-processing-rate-used-for-
                           monitoring-the-service-requests-remaining-
                           in-the-schedule-queue]
[set stay_watch_abort=Y|N]
[set stay_watch_start_interval=interval-for-checking-the-number-of-
                               service-requests-remaining-in-the-
                               schedule-queue]
[set stay_watch_check_interval=interval-for-judging-the-schedule-
                               queue-accumulation-status]
[set trn_completion_limit_time=time-limit-for-completing-transaction]
[set rap_message_id_change_level=message-ID-change-level]
[set log_audit_out_suppress=Y|N]
[set log_audit_message=message-ID-for-which-audit-log-data-is-to-be-acquired]
                      [,message-ID-for-which-audit-log-data-is-to-be-acquired]...]
[set mcf_prf_trace=Y|N]
[set watch_time=maximum-time-to-wait-for-a-response]

command format

[trnrmid -n resource-manager-name
         -i resource-manager-extension [, resource-manager-
            extension] ...]
[scdbufgrp -g schedule-buffer-group-name]
[scdmulti [-g multi-scheduler-group-name]]
[scdsvcdef [-c service-name]
            [-p number-of-services-that-can-be-executed-concurrently]
            [-n number-of-service-requests-that-can-be-queued]
            [-l length-of-the-buffer-pool-storing-messages-that-can-be-queued]]

putenv format

{{[putenv environment-variable-name environment-variable-value]}}
[putenv DCFPL_CONNECT_RETRY_COUNT number-of-retries-to-establish-
                                  a-connection]
[putenv DCFPL_CONNECT_RETRY_INTERVAL interval-between-retries-to-
                                     establish-a-connection]
[putenv XAT_CONNECT_RESP_TIME maximum-response-wait-time-for-
                              association-establishment-of-SPP-for-
                              processing-communication-events]

dcputenv format

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

Function

The user service definition defines the user server execution environment for each user server.

Specify the service group name plus the service name if requesting an RPC service. The service group name corresponds to the UAP (SPP, MHP) execution form program; and the service name corresponds to the individual functions (service functions) making up the execution form program.

OpenTP1 registers service requests into the schedule queue corresponding to each specified service group name.

File names of the user service definition become user server names. Specify these user server names in the user service configuration definition.

If the user service definition is omitted, values specified with the user service default definition are assumed.

Explanation

set format

service_group="service-group-name"~<1-31 character identifier>

Specify the service group names. Each name in all OpenTP1 systems connected to the network should be unique.

This operand need not be specified for an SUP.

module="executable-program-name"~<1-14 character identifier>

Specify the name of the execution form program to execute these service groups. This execution form program is in the directory specified with the process service definition.

When the operating system is HP-UX, if an executable file whose bind mode at the linkage is other than immediate is specified, the operation of OpenTP1 is not guaranteed. To check if the bind mode of the application is immediate, use the chatr command of the operating system.

service="service-name=entry-point-name[;UAP-shared-library-name]"[,"service-name=entry-point-name[;UAP-shared-library-name]"]...

service-name and entry-point-name ~<1-to-31-character identifier>

Specify the names of all services belonging to these service groups, and the names of all entry points providing those services. Note that a space or tab code must not be placed before or after the equal sign (=) between service-name and entry-point-name.

The entry point name is a C-language function name, and is the COBOL program or entry point name. For a service that uses a stub, specify the same entry point name as the name specified in the RPC interface definition.

Associate service names and entry point names, one to one. It is impossible to associate one entry point name to more than one service name. You can specify any number of service-name=entry-point-name entries.

UAP-shared-library-name ~<1-to-255-character path name>
Specify the path name of the UAP shared library for a service that loads service functions dynamically. Make sure that the UAP shared library names you specify do not contain a space or tab code.
Note that the definition check only checks whether UAP shared library names contain a space or tab code. If no space nor tab codes are found, the UAP shared libraries are unconditionally loaded.
If you use dynamic loading of service functions, you do not need to specify entry point names in the RPC interface definition. If no UAP shared libraries are specified, the service will use stubs.
If you use dynamic loading of service functions with the AIX version of OpenTP1, specify libbetran2.a as the linkage library for SPPs and both libbetran2.a and libmcf2.a as the linkage library for MHPs. If these libraries are not used, operation is not guaranteed. Note that for the AIX version of uCosminexus TP1/Server Base(64), both libbetran.a and libbetran2.a can be used.

For details of RPC service functions, and the RPC service definition, see the manual OpenTP1 Programming Guide.

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

Specify the nice value for these service group processes. The nice value is a positive integer, and the higher this value, the lower is the CPU priority position. For details on nice, see the appropriate manual for the operating system in use.

parallel_count=resident-process-count [,maximum-process-count]~<unsigned integer> ((0-1024))

For the services within these service groups, specify the number of processes to be processed in parallel.

Specifying the number of resident processes enables use of the multiserver function which starts several server processes concurrently to process services within the same service group. Use of the multiserver function improves processing of service requests. The multiserver function can still be used if the resident process count is 0, but the maximum process count is specified.

Specifying the maximum number of processes dynamically increases or decreases the number of non-resident processes in excess of the resident process count. This controls the startup of server processes within the specified maximum process count, thus preventing deterioration of OpenTP1 system performance.

Conditions for specifying the number of processes are as follows:

  1. 0 cannot be specified for both the resident process count and the maximum process count,
  2. the maximum process count, if specified, must be equal to or greater than the resident process count,
  3. omission of a maximum process count causes all processes to become resident processes, and
  4. to make all processes non-resident (started as required), specify the resident process count as 0, and specify the number of non-resident processes as the maximum process count.

If the resident process count is set to 0 and the maximum process count is omitted, a definition error occurs.

For the transaction processing by a service in this service group, the process of the service cannot process the next service until the current transaction terminates. Therefore, if the maximum process count is set to 1, more than one service in this service group cannot be called within one transaction.

This operand need not be specified for an SUP and an SPP server that receives requests from the socket.

hold=Y|N

Specify whether to shut down the service group or service if the server process terminates abnormally during execution of the service under this service group.

Y
The service group or service is shut down.

N
The service group or service is not shut down.

The service_hold operand specifies which service group or service to be shut down.

Shutting down a service group means that the server process is not started up in response to a schedule request from the service group. Note that, for service shutdown, the server process is started up unless another service within the same service group is shut down. In this case, the service request returns with an error to the program originating the service.

This operand does not need to be specified for SUPs, or for SPP servers that receive requests from sockets.

For MHPs, the operation specified in this operand is performed if MHPs end abnormally before the service start function is called. The operation after the start of a service depends on the specification in the application attribute definition (mcfaalcap definition command).

hold_recovery=Y|N

Specify whether service groups and services should inherit shutdown during a full recovery.

Y
Service groups and services are to inherit shutdown.

N
Service groups and services do not inherit shutdown.

This operand need not be specified for an SPP server that receives requests from the socket, SUP, and MHP.

When BEFORE is specified in the start_scheduling_timing operand of the system environment definition, the shutdown status is not carried over, regardless of the specification of the hold_recovery operand. If you want to carry over the shutdown status, specify F in the scd_hold_recovery operand of the schedule service definition. For details about operand specification for carrying over the shutdown status, see the description of the scd_hold_recovery operand of the schedule service definition.

deadlock_priority=deadlock-priority-position~<unsigned integer> ((1-127))

Specify the priority positions of UAP deadlocks. The smaller the value, the higher will be the priority position. Should a deadlock occur, an error is returned for the lock request of the UAP with the lowest priority position.

schedule_priority=schedule-priority-position~<unsigned integer> ((1-16))

Specify the priority positions of the schedules of the service groups. The smaller the value, the higher will be the priority position.

Priority positions are compared when server processes up to the maximum concurrent server process count specified with the process service definition have been started, and new service requests occur. Server processes are suspended sequentially in the service group having the lowest priority position. Server processes of service groups of higher priority are started.

This operand need not be specified for an SUP and an SPP server that receives requests from the socket.

message_buflen=maximum-message-length~<unsigned integer> ((1024-31457280)) (Unit: bytes)

Specify the size of the user data storage area for messages from the client which are in shared memory and to be received by the user servers. This area is owned by the process.

OpenTP1 adds 512 bytes to each message for control information; include this amount in specifying a value.

For SPPs other than the server that receives requests from the socket, the value you specify is (in_len value of the dc_rpc_call function + 512) bytes.

For MHPs, specify 1024 bytes.

This operand need not be specified for an SUP and an SPP server that receives requests from the socket.

message_store_buflen=message-storage-buffer-pool-length~<unsigned integer> ((1024-31457280)) (Unit: bytes)

Specify the size of a pool in shared memory for temporary storage of messages from the client. This pool is used to store the messages before transferring them to the user servers. Therefore, specify a value equal to or greater than the maximum length of the messages to be sent from the client plus 512 bytes for OpenTP1 control information.

Messages stored in the pool are transferred to the user servers by the FIFO method. If message retrieval by the user servers is delayed, messages will pile up in the pool, and service requests from the client can no longer be received. Therefore, specify a value with sufficient surplus storage.

If using any of the following functions, specify an integral multiple of the value specified in the message_cell_size operand.

If the specified value is not an integral multiple, the system rounds it up to a multiple and uses the value as the size of the buffer pool for storing schedule messages.

For SPPs except the server that receives requests from the socket, specify the value that is obtained by the following formula:

Length of the message storage buffer pool = (in_len value of the dc_rpc_call function + 512 bytes) x number of messages remaining in the queue

For MHPs, use the following formula to calculate the message storage pool length.

  1. When all the MHPs are all resident on the memory or when 0 is specified in the balance_count operand:
    Message-storage buffer pool length = C x P
  2. For the other cases:
    Message-storage buffer pool length = C x P x B
    C
    Additional control information (512 bytes)
    P
    Maximum number of processes specified in the parallel_count operand
    B
    Value specified in the balance_count operand

If the value obtained from the calculation is smaller than 1024, specify 1024.

This operand need not be specified for an SUP and an SPP server that receives requests from the socket.

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.

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

A monitoring time can also be specified by issuing other functions. For details of these functions, see the OpenTP1 Programming Guide. If using the RPC function, use the trn_expiration_time_suspend operand to specify whether the processing time of other processes executed by the transaction branch are to be included in the time check.

Use the trn_expiration_time_suspend operand to specify whether the message receiving/sending time is to be included in the monitor time when synchronous messaging is performed using the message control facility (TP1/Message Control).

trn_expiration_time_suspend=Y|N|F

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 terminates
  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
  4. Time required for the monitored transaction branch to perform synchronous messaging using the message control facility (TP1/Message Control).

Y
The monitor time includes all of 1., 2., 3., and 4.

N
The monitor time includes only 3.

F
The monitor time includes none of 1., 2., 3., and 4.

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

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

watch_next_chain_time=chained-RPC-maximum-time-interval~ <unsigned integer> ((0-65535)) (Unit: seconds)

If the server UAP is called by a chained RPC, specify in units of seconds, either:

1. the maximum time interval between return of a response to a previous service request until receipt of the next service request, or

2. the maximum time interval until the transaction terminates.

The UAP terminates abnormally should the specified time elapse.

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 specified value is effective only for the server which becomes the UAP. If 0 is specified, OpenTP1 waits indefinitely until the next chained RPC request is received, or until the transaction terminates.

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

atomic_update=Y|N

Specify whether transactions are to be generated by the process of this service group.

Y
These processes are entered into the range of transactions with either of the following:
  1. a new dc_trn_begin function was issued with this process, or
  2. the OpenTP1 system receives a service request from another UAP, and automatically enters the process.

N
This process is not entered into the transaction range. The dc_trn_begin function, dc_trn_unchained_commit function or any other transaction service function cannot be used. Journal output is also forbidden.

Note that if Y has been specified for the jnl_fileless_option operand in the system common definition, OpenTP1 assumes that the atomic_update operand has been set to N even when Y is set.

receive_from=queue|socket|none

Specify what means is to be used for receiving a message that is received by the service function.

queue
The schedule queue of the schedule service is used. Specify queue for an SPP or an MHP. Use of the schedule queue enables use of the function to start and call new server processes not started with a dc_rpc_call function. It also enables the load to be balanced with a multiple start of the same server process.

socket
The UNIX domain or internet domain is used. Specify socket for an SUP. This server can use neither on-demand startup nor inter-node load-balancing facility.

none
Neither the schedule queue of the schedule service, a UNIX domain nor internet domain is used. Specify none for an SUP.

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

Specify the number of records for a UAP trace.

The following types of information are acquired in the UAP trace data file or a core file:

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.

uap_trace_file_put=Y|N

Specify whether to acquire UAP trace information into a file.

Y
Trace information is acquired into a UAP trace data file.
If the trace information cannot be acquired into a file, it is acquired into a process-specific area.

N
Trace information is acquired into a process-specific area.

When Y is specified, a maximum of six generations of backup files for the UAP trace data file are acquired by each server when the user server fails or restarts after the termination of OpenTP1. Three generations of backup files are acquired when the applicable server is normally terminated, and also during abnormal termination accompanied by a core file output. Backup files are stored in the core file storage destination specified in the prc_coresave_path operand of the process service definition.

term_watch_time=abnormal termination-check-expiration-time~<unsigned integer> ((0-32767)) (Unit: minutes)

Specify the maximum time interval to check the number of times that a server process of this user server terminates abnormally. For SPPs except the server that receives requests from the socket, this operand is valid when N is specified in the hold operand.

For an SUP and an SPP server that receives requests from the socket, the operand is valid when Y is specified in the auto_restart operand.

In OpenTP1, UAP processes may be stopped due to a timeout. The following table lists the conditions for shutting down the server if a UAP process is stopped due to a timeout.

Table 3-11 Specification of the hold and term_watch_time operands for determining whether to shut down the server

Value of the hold operand Value of the term_watch_time operand Whether the server is shut down
Y Any (When the value of the hold operand is Y, the server is unconditionally shut down regardless of the term_watch_time operand specification.) The server is unconditionally shut down regardless of the cause of the abnormal termination.
N 0 The server is not shut down.
Other than 0 The server is shut down if it terminates abnormally three times within the time specified in the term_watch_time operand. Note that whether an abnormal termination is counted depends on the cause of the abnormal termination.

The following table shows the causes of abnormal terminations that are counted and those that are not counted.

Table 3-12 Causes of abnormal terminations that are counted and those that are not counted

Cause of abnormal termination Whether the abnormal termination is counted
A problem with a UAP Counted
Timeout value in ipc_sockctl_watchtime exceeded Counted
Timeout value in trn_cpu_time exceeded Counted
Timeout value in watch_next_chain_time exceeded Counted
Timeout value in xat_trn_expiration_time exceeded Counted
Timeout value in service_expiration_time exceeded Not counted
Timeout value in trn_expiration_time exceeded Not counted
Abnormal termination due to expiration of trn_completion_limit_time Not counted
Abnormal termination due to expiration of mcfaalcap -v ntmetim Not counted
Abnormal termination due to the prckill or dcsvstop -fd command Not counted

If the server process of this user server terminates abnormally three times consecutively within the specified time, the SPP (except the one that receives requests from the socket) shuts down the service group independently of the specification of the hold operand. An SPP server that receives requests from the socket or SUP is forced to terminate independently of the specification of auto_restart operand.

For the MHP, if the server process of the user server terminates abnormally for three consecutive times or more within the specified time before the service is started, the schedule of the service group is shut down and the user server is forcibly terminated. Specify 0 to have no time check.

The following provides an example of server behavior when the user server has terminated abnormally with the hold operand set to N and the term_watch_time operand to a non-0 value:

  1. The server terminated abnormally because the value specified in the trn_cpu_time operand was exceeded.
    This is the first abnormal termination. The server is not shut down.
  2. The server terminated abnormally because the value specified in the trn_expiration_time operand was exceeded.
    This is not counted as an abnormal termination. The server is not shut down.
  3. The server terminated abnormally due to a problem with a UAP.
    This is the second abnormal termination. The server is not shut down.
  4. The server terminated abnormally because the value specified in the trn_cpu_time operand was exceeded.
    This is the third abnormal termination. The server is shut down.

mcf_jnl_buff_size=MCF-journal-buffer-size~<unsigned integer> ((4096-131072)) (Unit: bytes)

Specify the size of the area for storing the journal data collected during MCF execution.

For details on how to calculate the value to be specified, see the description about the -j option in the mcfmuap definition command in MCF manager definition.

The larger the specified area, the fewer will be the number of read/write operations to the disc during collection.

If this operand is not specified, the value specified with the user service default definition is assumed. If not specified there, the value specified with the -j option of the mcfmuap command in the MCF communication configuration definition is assumed.

This operand is valid only for an MHP or an SPP that uses the MCF function. It need not be specified for an SUP.

type=other|MHP

Specify the type of this service group.

other: Queue-receiving SPP

MHP: MHP

This operand need not be specified for an SUP.

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

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.

Specify 0 for the following cases:

If 0 is specified, a non-resident process will be started for a service request if all active processes are processing other services.

This operand need not be specified for an SPP server that receives requests from the socket and SUP.

uid=user-ID~<unsigned integer> ((0-4294967294))

Specify the ID of the user who will be in possession of the processes of this service group. Specify an ID registered in the operating system.

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

auto_restart=Y|N

Specify the handling of service groups if a UAP terminates abnormally during execution.

Y
The process is restarted.

N
The process is not restarted.

This operand need not be specified for an SPP (except one that receives requests from the socket) and MHP.

critical=Y|N

Specify the handling of the OpenTP1 system if a UAP terminates abnormally during execution.

Y
OpenTP1 suspends processing.

N
OpenTP1 continues processing.

lck_wait_priority=lock-waiting-priority~<unsigned integer> ((0-127))

Specify the priority with which a wait-type lock request issued by an user server enters the wait state.

The smaller the specified value, the higher will be the priority position; the lock state is released starting from requests of lower priority. Specify 0 to have requests registered last in the waiting queue.

Take note that setting the priority position too low could cause a request to be preceded by a lock request issued later but of higher priority.

mcf_psv_id=application-startup-process-ID~<hexadecimal number> ((01-ff))

Specify the identifier of the process to start an application.

This operand must be specified for all SPPs which are to start an application. It need not be specified for an SUP, MHP, or SPP which will not start an application.

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 is terminated and rolled back.

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

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.

service_hold=Y|N

Specify whether service-based shutdown control is carried out for the services under the indicated service group.

Y
Service-based shutdown control is carried out.

N
Service-based shutdown control is not carried out.

When Y is specified for this operand, the specification in the message_cell_size operand takes effect.

Service-based shutdown control enables each service to be shut down when the server terminates abnormally or to be shut down by an operation command. Note that shutting down a service when the server terminates abnormally is valid only when the hold operand has Y specified or when the service_term_watch_time operand is specified.

If receiving a schedule request for the service, it is returned with an error to the program originating the request.

This operand need not be specified for an SPP server that receives requests from the socket, SUP and MHP.

service_priority_control=Y|N

Specify whether scheduling is to be made according to the priority specified for each service request.

Y
Scheduling is made according to the priority specified for each service request.

N
Scheduling is not made according to the priority specified for each service request.

When Y is specified for this operand, the specification in the message_cell_size operand takes effect. This operand need not be specified for an SPP server that receives requests from the socket, SUP and MHP.

message_cell_size=storage-cell-length-of-schedule-message~<unsigned integer> ((512-31457280)) (Unit: bytes)

In either of the following cases, the schedule-message storage buffer pool specified in the message_store_buflen operand is divided into cells to store the messages. Specify the cell size in this operand.

When specifying the cell size, note that a cell control table (16 bytes) is created in each cell of the schedule message storage pool.

Specify an integer multiple of 8 in this operand. If the specified value is not an integral multiple of 8, the value is rounded up to an integer multiple of 8.

The value of the message_store_buflen operand must be an integral multiple of message_cell_size. If it is not, the system rounds it up to a multiple and uses the rounded-up value as the size of the buffer pool for storing schedule messages.

If both the service_priority_control and service_hold operands have been set to N, and the scdsvcdef operand has been omitted, you do not need to specify the message_cell_size operand.

It need not be specified, either, for an SPP server that receives requests from the socket, SUP and MHP.

max_socket_msg=maximum-number-of-messages-that-the-server-can-receive-from-the-socket~<unsigned integer> ((1-500))

Specify the maximum number of messages that the server receives request from the socket.

When not ready to accept services (while waiting for transaction commitment or roll-back direction, waiting for a response to an RPC nest call, or during chained RPC), the server that receives requests from the socket stores new service requests without processing them promptly until normal service acceptance state is reached.

If the number of messages received by the server exceeds the value specified in this operand, the dc_rpc_call function returns with a DCRPCER_SERVER_BUSY error.

This operand need not be specified for an SPP (except the server that receives requests from the socket), SUP, and MHP.

max_socket_msglen=maximum-length-of-messages-that-the-server-can-receive-from-the socket~<unsigned integer> ((1-30270)) (Unit: kilobytes)

Specify the maximum length of messages that the server receives request from the socket.

If the total length of messages received by the server exceeds the value specified in this operand, the dc_rpc_call function returns with a DCRPCER_SERVER_BUSY error.

The value to be specified must be greater than the maximum length of messages that are sent to the server. Also, the size of control information appended to messages (0.3 Kbytes approximately) must be added to the value specified.

This operand need not be specified for an SPP (except the server that receives requests from the socket), SUP, and MHP.

trf_put=Y|N

Specify whether a journal output from the transaction started up by the server is to be output to the transaction recovery journal.

Y
The journal is output to the transaction recovery journal.

N
The journal is not output to the transaction recovery journal.

A transaction recovery journal file prevents a journal error from being caused by a long-time transaction and reduces rerun time. Note that this function is needed only for a server that uses transactions for a long time because it places a lot of overhead on performance and memory.

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.

mcf_mgrid=application-startup-process-MCF-manager-identifier~<identifier> ((A-Z, a-z))

Specify the identifier of the MCF manager belonging to the application startup process.

This operand need not be specified for an SUP, MHP and SPP that does not start up an application.

mcf_service_max_count=maximum-number-of-issued-MCF-communication-functions~<unsigned integer> ((0-65535))

Specify the maximum number of MCF communication functions issued by UAPs to check UAP overrun.

If the number of MCF communication functions issued exceeds the value specified in the operand, the UAP terminates abnormally.

If 0 is specified, the number of issued communication functions is not checked. If it is omitted, the value in the mcf_service_max_count operand of the user service default definition is assumed.

For an MHP, if both options are omitted, the value in the -d option of the mcfmuap command of the MCF manager definition is assumed.

For an SPP, if both options are omitted, no check is performed.

The operand is valid only for an MHP and an SPP that uses the MCF function.

This operand need not be specified for an SUP.

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

Specify the items that collect the statistics in the transaction branch.

nothing
Statistics in the transaction branch are not collected.

base
The following information in the transaction branch is collected as basic information.
  • Identifier in the transaction branch
  • Decision results in the transaction branch
  • Execution process type in the transaction branch
  • Execution server name in the transaction branch
  • Execution service name in the transaction branch

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

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

Specifying to nothing must be one. If nothing and other statistical item are specified simultaneously, specifying to nothing will be nullified.

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

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

The more types of statistics are 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.

node_down_restart=Y|N

Specify whether to start up the user server automatically when an OpenTP1 system restarts.

This specification is invalid if the applicable user server normally terminates before the dcstop command is executed. In the following cases, whether a normally terminated user server will be started is decided based on the specification in the status_change_when_terming operand:

Y
The user server is automatically started up.

N
The user server is not automatically started up.

When an attempt is made to restart (rerun) OpenTP1 that has terminated abnormally, the user servers for which the node_down_restart operand has been set to N are not restarted. If an attempt is made to normally stop OpenTP1 when there are user servers that have terminated abnormally, OpenTP1 stops abnormally. If OpenTP1 has stopped abnormally, take either of the following actions:

rpc_response_statistics=Y|N

Specify whether to collect response statistics.

Y
Response statistics are collected.

N
Response statistics are not collected.

The response statistics contain the RPC call response time, service execution time, and server CPU time.

This operand can be specified by each individual client server of dc_rpc_call function. Response statistics collected by a synchronous response RPC (including a chained RPC) and an asynchronous response RPC.

server type="betran"|"xatmi"|"xatmi_cbl"

Specify whether the service function is to be called according to the OpenTP1 paradigm or the XATMI paradigm.

"betran"
The service function is called according to the OpenTP1 paradigm and the XATMI functions cannot be used.

"xatmi"
The service function is called according to the XATMI paradigm.

"xatmi_cbl"
The service function is called according to the COBOL service paradigm of XATMI.

This operand need not be specified for an SUP and MHP.

trn_rm_open_close_scope=process|transaction

Specify the issue timing of the two functions (xa_open and xa_close functions) that are an XA interface to the resource manager 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 the transaction starts and the xa_close function is issued when the transaction terminates.

If process is specified, the resource of 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 are issued whenever the transaction starts and terminates. If the resource of the resource manager must be used efficiently, specify transaction.

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

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

Specify the items to be optimized, 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 prepare processing 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.
    When this optimization is performed, the response of the synchronous-response RPC issued by the parent transaction branch is slowed. 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

If this operand is omitted in both the user service default definition and the user service definition, the default of the transaction service definition is used.

purge_msgget=Y|N

If the server process for a nonresident server is not found, specify whether OpenTP1 releases the message queue of the operating system allocated to the service group (by the msgget system call).

Y
The message queue of the operating system is released if the server process is not found.

N
The message queue of the operating system is not released even if the server process is not found.

Specifying Y by this operand can eliminate a waste of the message queue of the operating system. The message queue is released when no service request is issued for ten seconds after the server process disappears. When a service request is issued after the message queue of the operating system is released, the message queue is re-allocated to process the service request.

When specifying Y by this operand, specify Y for the other service groups. This is because there is one message queue of the operating system for one service group. Therefore, specify Y also by the purge_msgget operand in the user service default definition.

This operand is valid for only the service group for which queue is specified by the receive_from operand and the parallel_count operand (resident process count) is set to 0 in the user service definition. This operand is ignored for the other service groups.

Note that re-allocation of the message queue of the operating system takes tens of milliseconds. Do not forget this when using the system for which that level of delay affects its performance.

cancel_normal_terminate=Y|N

Specify whether to cancel the normal termination for the dcsvstop command in this user server.

Y
The normal termination is canceled.

N
The normal termination is not canceled.

When Y is specified, this user server accepts only the forced termination by the dcsvstop command and the termination by the dcstop command.

prc_abort_signal=abort-signal-number~<unsigned integer> ((1-128))

Specify the signal number that is used when aborting a server under OpenTP1. As the abort signal number, specify the signal number that performs core file output. If such a signal number is not specified, the core file will not be created when the forced termination is performed by the dcstop command and dcsvstop command even if the -d option is specified.

The signal number specified in the prc_abort_signal operand is sent to a server as shown in the following table.

Table 3-13 Time and destination for sending the signal number

Time when the signal number is sent Server to which the signal number is sent
When any of the following times expires:
  • Transaction branch expiration time (specified in the trn_expiration_time operand)
  • Period of time for monitoring the execution between startup and termination of a service function (specified in the service_expiration_time operand)
  • Time limit for completing a transaction (specified in the trn_completion_limit_time operand)
  • Non-transaction MHP expiration time (specified in the ntmetim operand of the -v option in the mcfaalcap command)
Server for which the time monitoring expired
When an attempt is made to forcibly stop the server by using any of the following methods:
  • Executing the prckill command
  • Executing the dcsvstop command with the -df option specified
  • Executing the dcstop command with the -fd option specified
Server to be forcibly stopped

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

Specify the maximum number of service function retries performed by the service retry facility. When 0 is specified, the service retry facility is not used. Therefore, the dc_rpc_service_retry functions returns an error and the service function is not retried.

When a number other than 0 is specified, the service function is retried for the specified number of times consecutively. The dc_rpc_service_retry function that is called exceeding the specified number of times returns an error and the service function is not retried.

Only the SPP can use the service retry facility.

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

Specify one of the following as the extension level of the RPC service facility.

To specify two or more extension levels, specify logical ADD of the values specified.

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 (dc_rpc_call and dc_rpc_call_to functions with DCRPC_TPNOTRAN set as 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 and dc_rpc_call_to functions with DCNOFLAGS specified as flags.

00000004
When the synchronization point processing of transactions is performed with no response message received from an asynchronous-response type RPC, only the response messages of the transactional attribute asynchronous-response type RPC are deleted without aborting those of the non-transactional attribute asynchronous-response type RPC.

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 the OpenTP1 control#.

The processes under the OpenTP1 control# exchange the process information with the system service or user server 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.

For this operand, specify a value that satisfies the following condition:

Value specified in this operand + value specified in the max_open_fds operand in the same definition [Figure] 2048

If you specify a value that does not satisfy the above condition, the value specified in this operand is forcibly corrected as follows:

Value specified in this operand + value specified in the max_open_fds operand in the same definition = 2048

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

Calculate the maximum number of file descriptors for sockets using the following formula.

[Figure](Number of UAP processes that communicate with 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 that communicate with the user server is the sum of the following values:
  • Number of UAP processes in the local OpenTP1 that communicate with the user server
  • Number of UAP processes in the other nodes that communicate with the user server

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

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

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

  1. User service definition
  2. User service default definition
  3. System common definition

If the specification is omitted here and in the user service default definition, the value in the system common definition is assumed.

max_open_fds=maximum-number-of-files-and-pipes-accessed-by-a-UAP-process~<unsigned integer> ((16-2016))

Specify the maximum number of files and pipes that are accessed by a user server process.

File descriptors are used to access files and pipes.

When the user server process accesses too many files, the number of file descriptors for sockets that are used to exchange the process information with the system server or user server becomes insufficient. Therefore, the number of files and pipes to be accessed needs to be set beforehand.

Calculate the maximum number of files and pipes that are accessed by a user server process using the following formula.

(Total number of OpenTP1 file systems that are specified in the system definitions of the DAM service, TAM service, journal service, and status service#1) + (Number of ISAM keys) + 20#2 + (Number of user files#3)

#1: Number of OpenTP1 file system areas that are used online

#2: When making a service request using the remote API facility, add 16 to the fixed number of 20.

#3: Files not under the OpenTP1 control and those that are independently used by users

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

service_term_watch_time=abnormal-termination-check-expiration-time-for-service~<unsigned integer> ((0-32767)) (Unit: minutes)

Specify the period of time to monitor the number of times the server process of this user server terminates abnormally during the same service execution. When zero is specified, this operand is assumed to be not specified and the monitoring is not performed.

When this operand is specified, if the server process terminates abnormally three times during the same service execution (in the dc_rpc_mainloop function) within the specified time, that service is shut down. If the server process terminates abnormally three times other than during the service execution (other than in the dc_rpc_mainloop function), the service group is shut down.

This operand is valid when managing the service shutdown without shutting down the service group even if the server process terminates abnormally (when N is specified in the hold operand and Y is specified in the service_hold operand). This operand is ignored even if it is specified for the SPP server that receives requests from the socket, SUP, and MHP.

If a value other than 0 is specified in this operand, the number of abnormal terminations is monitored for each service. Therefore, the term_watch_time operand is ignored even if it is specified.

See the following table for the relationship among the service_term_watch_time operand specification and the specification of the hold operand, service_hold operand, and term_watch_time operand.

Operand specification Number of abnormal terminations of the server process and OpenTP1 processing
hold service_hold term_watch_time service_term_watch_time 1st time 2nd time 3rd time
Y Y U U Service shutdown -- --
N U U Service group shutdown -- --
N Y 0 Not specified Process restart Process restart Process restart
Other than 0 Not specified Process restart Process restart Service group shutdown
0 0 Process restart Process restart Process restart
 
 
 
 
 
 
Other than 0 0 Process restart Process restart Service group shutdown
U Other than 0 Process restart Process restart Service shutdown#
N 0 U Process restart Process restart Process restart
Other than 0 U Process restart Process restart Service group shutdown

Legend:
U: Unspecifiable (ignored even if specified)
--: Nothing is performed.

#: If the server process terminates abnormally three times during other than the service execution (other than in the dc_rpc_mainloop function), the service group is shut down.

termed_after_service=Y|N

Specify whether to terminate the non-resident process when the load is decreased at the termination of the service in this user server.

Y
The non-resident process is terminated.

N
The unnecessary non-resident process is terminated by the schedule service at an interval.

Normally, OpenTP1 checks the status of processes regularly (every 10 seconds) and terminates unnecessary non-resident processes. However, in a system with many servers, the number of processes to be terminated at the same time increases, which decreases the processing performance of the service request that occurs at the same time when a process is terminated.

Specifying Y in this operand checks the status of processes at the termination of the service. This reduces the number of processes to be terminated at the same time and prevents degrading the processing performance of the service request that occurs when a process is terminated. In addition, by reducing the number of processes started in the system, the load of the system can be reduced.

However, since the process status is checked each time the service is terminated, the processing performance of service requests degrades each time. In addition, depending on the system type, the non-resident processes start and terminate so frequently that the processing performance of service requests may degrade.

This operand is ignored even if it is specified for the SPP server that receives requests from the socket and for the SUP.

xat_trn_expiration_time=period-of-time-to-monitor-the-expiration-of-synchronization-point-processing~<unsigned integer> ((1-2147483647)) (Unit: seconds)

Specify the period of time to monitor the expiration of the synchronization point processing with the remote system when executing OSI/TP communication with XATMI interface using TP1/NET/OSI-TP-Extended.

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.

For the MHP, this operand is ignored even if it is specified.

xat_osi_usr=Y|N

Specify whether to use the stub for OSI TP communication with XATMI interface using TP1/NET/OSI-TP-Extended in this server.

Y
The stub for OSI TP communication is used.

N
The stub for OSI TP communication is not used.

When N is specified, the OSI TP communication with XATMI interface using TP1/NET/OSI-TP-Extended cannot be performed.

For the MHP, this operand is ignored even if it is specified.

rpc_trace=Y|N

Specify whether an RPC trace is to be collected.

Y
An RPC trace is collected.

N
An RPC trace is not collected.

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.

When the remote API facility is used, the RPC trace for RAP-processing clients cannot be acquired if Y is specified in this operand.

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

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

  1. User service definition
  2. User service default definition
  3. System common definition

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

Specify the path name of the file for collection of 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).

rpc_trace_size=RPC-trace-collection-file-capacity~<unsigned integer> ((1024-2147483648)) (Unit: bytes)

Specify the capacity of the file for collection of the RPC trace.

Even if you specify 4096 or less for this operand, if the length of the transmitted text exceeds the specified value, the size of the trace file to be created may be larger than the value specified by this operand.

trn_rollback_information_put=no|self|remote|all

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.

If this operand is omitted in both the user service definition and the user service default definition, the default of the transaction service definition is used.

schedule_method=msgque|namedpipe

Specify the scheduling method of the user server.

msgque
The message facility of the operating system is used for scheduling service requests.

namedpipe
The named pipe of the operating system is used for scheduling service requests.

Specify namedpipe when you specify the service_wait_time operand in the user service definition.

Note that the namedpipe specification:

This operand does not need to be specified for the SPP server that receives requests from the socket and for the SUP.

service_wait_time=service-request-waiting-time-for-non-resident-server-processes-of-the-user-server~<unsigned integer> ((1-4096)) (Unit: seconds)

Specify the period of time for non-resident server process of the user server should wait for a service request.

The non-resident processes of the user server which specified this operand should wait for service requests for the specified period of time, and will be terminated if no service request is sent.

If this operand is not specified, the scheduling service monitors the load on the server at a regular interval and terminates non-resident processes.

This operand is effective when namedpipe is specified for the schedule_method operand of the user service definition. Specifying the service_wait_time operand invalidates the specification of the termed_after_service operand of the user service definition.

This operand does not need to be specified for the SPP server that receives requests from the socket and for the SUP.

mcf_spp_oj=Y|N

Specify whether OJ historical information is to be collected when the SPP requests branch message transmission, application startup, or message retransmission.

Y
OJ historical information is collected.

N
OJ historical information is not collected.

adm_message_option=message-output-specification~<one-digit hexadecimal number>

Specify with the logical AND of bit masks whether to output the following messages. A message with the bit mask turned on will be output. A message with the bit mask turned off will not be output.

Message ID Bit mask (hex.) Contents of the message
KFCA01811-I 1 Server starting
KFCA01813-I 2 Server online
KFCA01842-I 4 Server terminating
KFCA01843-I 8 Server suspended

Example
To output the KFCA01813-I and KFCA01843-I messages, specify set adm_message_option=A.

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

Specify the maximum waiting time for receiving the communication (such as an instruction of prepare, commit, or rollback, and a 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 determine the transaction.

If this operand is omitted in both the user service definition and the user service default definition, the default of the transaction service definition is used.

If you also omit this operand in the transaction service definition, the system assumes the watch_time value of the user server that executed the transaction. However, if you specify 0 for watch_time, the system assumes 120 seconds.

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

Specify the maximum time to execute a transaction branch. The expiration time are 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.

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.

If this operand is omitted in both the user service definition and the user service default definition, the default of the transaction service definition is used.

trn_rollback_response_receive=Y|N

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

If this operand is omitted in both the user service definition and the user service default definition, the default of the transaction service definition is used.

trn_partial_recovery_type=type1|type2|type3

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

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 transaction synchronization point message, which 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 executing the service request. Since the branch cannot identify the process it cannot send a message about the transaction synchronization point to the RPC-receiving transaction branch. The RPC-receiving transaction branch has to wait for the transaction synchronization point message, which 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. That recovery process will send a transaction synchronization point message to a non-existing UAP process, which requires 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 causes 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 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. Upon receiving 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 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 or 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, and then settles the transaction. When the transaction service process has received 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, 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 transaction synchronization point message.

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

rpc_destination_mode=namdonly|namd|definition

This operand specifies which of the information obtained from the name service and the value specified in the user service network definition is to be given priority when determining the destination of a service required by the dc_rpc_call function.

namdonly
As before, the system sends the service to the address selected from the name service information. However, the system never search the value specified in the user service network definition.

namd
The system sends the service to the address selected from the name service information. It searches the value specified in the user service network definition only when it has failed to find the service in the name service information.

definition
The system sends the service to the address searched from the value specified in the user service network definition. The system requests the name service to make an address search only when the system failed to find the service in the user service network definition.

Specify this operand to use an SUP, SPP, or MHP to call the dc_rpc_call function.

With namd or definition specified in this operand, the system searches the value in the user service network definition and sends a service request. If service information defined at a node was not specified in the all_node operand of a system common definition, the service requested after restarting any down OpenTP1 at this node may encounter a timeout error.

rpc_rap_auto_connect=Y|N

This operand specifies whether or not the connection between the UAP and the remote API control process is under the automatic control of OpenTP1 when a service request is issued using a resident connection in the remote API facility.

Y
Autoconnect mode; the connection between the UAP and the remote API control process is under the automatic control of OpenTP1.

N
Non-autoconnect mode; the connection between the UAP and the remote API control process is controlled by the user using the dc_rap_connect or dc_rap_disconnect function.

rpc_rap_inquire_time=maximum-inquiry-interval-for-request-service- using-the-remote-API-facility~ <unsigned integer> ((0-1048575)) (unit: seconds)

This operand specifies the maximum wait time for processing of the next service request after the remote API control process executes a service request issued from the UAP using the remote API facility. The remote API control process monitors this timer value. In case there is no more service request when the specified time has elapsed, the remote API control process assumes that the UAP to have gone down and continues processing.

Specifying a value of 0 means that the value specified by the remote API control process definition is valid.

Specify this operand when using SUP, SPP, or MHP to call the dc_rpc_call function using the remote API facility.

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 RAP-processing listener 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 of the RAP-processing listener service definition is regarded as the maximum amount of wait time. When both are omitted, 180 seconds is assumed.

rpc_request_cancel_for_timedout=Y|N

This operand specifies whether or not make the server recognize that the client is in wait status by taking over the service response wait time after sending the service request. This wait time is set with the client UAP.

Once the server takes over the response wait time for client UAP, it is possible to prevent the server from executing the service or waiting for execution of point processing if a timeout occurs at the client UAP.

Y
Makes the server be aware of the response wait time for client UAP.

N
Does not make the server be aware of the response wait time for client UAP.

Set N, however, if the version of TP1/Server Base of the server is 03-02 and if the domain-specified synchronous dc_rpc_call function is used. Otherwise, an RPC error will result.

status_change_when_terming=Y|N

This operand specifies whether or not to reflect the server status at the next restart when the system has gone down after the user server normally terminated during normal system termination or when SUP normally terminated before the termination processing with the dcstop command during scheduled system termination.

Y
Reflects the final status change.
Normally-ended user servers are not restarted at the next OpenTP1 restart.

N
Does not reflect the final status change.
Normally-ended user servers are restarted at the next OpenTP1 restart.

service_expiration_time=execution-monitor-time-from-service-function-startup-to-termination~<unsigned integer> ((0-65535)) (units: seconds)

This operand specifies the period of time to monitor the execution of a service function between its startup and termination in an SPP process. If the service function does not return within the specified period of time, OpenTP1 forcibly stops this process.

Specify 0 to have no time monitoring.

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.

multi_schedule=Y|N

This operand specifies whether to schedule a service request using the multi-scheduler facility. When you use the multi-scheduler facility, specify this operand on the user server on the RPC sending side.

Y
Uses the multi-scheduler facility to schedule a service request.

N
Does not use the multi-scheduler facility to schedule a service request.

When the multi-scheduler facility is enabled, if a service group in the OpenTP1 system contains some user servers that use the facility and some that do not, service requests are distributed first to the user servers that use the facility.

If the user servers that use the multi-scheduler facility are inactive or the facility cannot perform scheduling (because of, for example, a shutdown or a message buffer shortage), service requests are distributed to the other user servers.

To use the multi-scheduler facility, you must specify this operand and scdmulti definition command of the schedule service definition and user service definition on the RPC receiving side.

You can use this facility when TP1/Extension 1 is already installed. If TP1/Extension 1 is not installed, the operation of this facility cannot be assured.

make_queue_on_starting=Y|N

This operand specifies whether a schedule queue that OpenTP1 allocates to a non-resident service group should be allocated at the start of the server.

Y
Allocates a schedule queue at the start of the server.

N
Does not allocate a schedule queue at the start of the server.

When you specify this operand, you can detect a status in which the non-resident server cannot schedule service requests because the system resource is insufficient, at the start of the server.

However, even if the system fails to allocate a schedule queue, the system does not cancel starting the server.

This operand is ignored when you specify purge_msgget=Y in the user service definition or in the user service default definition, or when you specify a value other than 0 as the number of resident processes in the parallel_count operand.

loadcheck_interval=load-check-interval~<unsigned integer>((0-65535))(unit: seconds)

Specify the interval between checks on the load level of the current service group. If the load level is changed during a load check, the server information is reported to the name service of each node. Therefore, in the worst case, the server information is sent out to the network at each load check interval. To prevent this, do not specify a short interval unless it is necessary. If you specify scd_announce_server_status=N in the schedule service definition, this operand is ignored even if it is specified. If you specify 0, load levels are not checked.

If you do not specify this operand, the load check interval will be 30 seconds. Whether to check the load is determined every 10 seconds. In other words, a load check is executed at every third check.

When you specify this operand, the value specified in this operand is the load check interval. This value determines whether the load check is executed at the interval that is calculated from the largest common factor of 10 and the value specified in this operand for each user server. For example, when you specify 3 for the loadcheck_interval operand of SPP1 and 5 for the loadcheck_interval operand of SPP2, the interval of the check is 1 second since 1 is the largest common factor of 10, 3, and 5. The load check of SPP1 is executed at every third check. The load check of SPP2 is executed at every fifth check.

Therefore, to keep the influence to the system to the minimum, specify a multiple of 5 as the value to be specified for the loadcheck_interval operand.

You do not need to specify this operand for the MHP, the SPP that receives requests from the socket, and the SUP. The operand will be ignored even if you specify it.

You can use this definition command when TP1/Extension 1 is already installed. If TP1/Extension 1 is not installed, the operation of this definition command cannot be assured.

levelup_queue_count=U1,U2

leveldown_queue_count=D0,D1~<unsigned integer>((0-32767))

Specify the number of remaining service requests, which determines the load level of the current service group.

U1
Number of remaining service requests, which determines that the server's load level is upgraded to LEVEL1

U2
Number of remaining service requests, which determines that the server's load level is upgraded to LEVEL2

D0
Number of remaining service requests, which determines that the server's load level is downgraded to LEVEL0

D1
Number of remaining service requests, which determines that the server's load level is downgraded to LEVEL1

The values specified in the levelup_queue_count operand and the leveldown_queue_count operand must satisfy the following condition:

Condition: 0[Figure]D0<U1[Figure]D1<U2

If the specified values do not satisfy the condition, a definition error occurs when you start the server and the startup will fail.

If you specify scd_announce_server_status=N in the schedule service definition, this operand will be ignored even if you specify it. The leveldown_queue_count operand is valid only when the levelup_queue_count operand is specified. The leveldown_queue_count operand will be ignored if the levelup_queue_count operand is not specified. However, when the levelup_queue_count operand is specified, you can omit the leveldown_queue_count operand. In this case, the values to be specified in the leveldown_queue_count operand are assumed as follows:

D0=U1/2

D1=U1+(U2 - U1)/2 (fractions are discarded for both D0 and D1)

You do not need to specify this operand for the MHP, the SPP that receives requests from the socket, and the SUP. The operand will be ignored even if you specify it.

You can use this definition command when TP1/Extension 1 is already installed. If TP1/Extension 1 is not installed, the operation of this definition command cannot be assured.

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 the 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/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 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/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 oldest 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 the performance or causing communication 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.

Whether the service group or service 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.

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.

ipc_conn_interval=length-of-time-to-wait-until-the-connection-is-established~<unsigned integer>((8-65535)) (unit: seconds)

Specify the length of time to wait in seconds until the connection is established when you send data.

Specify the length of time to wait until the system receives the response to the connect() system call that is called in the nonblocking mode.

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

ipc_send_interval=interval-for-monitoring-data-transmission~<unsigned integer>((5-32767)) (unit: seconds)

Specify the interval for monitoring data transmission.

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

ipc_send_count=number-of-times-data-transmission-is-monitored~ <unsigned integer>((1-32767))

Specify the number of times data transmission is monitored until data transmission is completed.

The system monitors the data transmission monitoring time for OpenTP1 which is calculated in seconds as follows:

Value specified in the ipc_send_interval operand x Value specified in the ipc_send_count operand

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

ipc_header_recv_time=length-of-time-to-wait-until-the-communication-control-data-is-received~<unsigned integer>((5-32767)) (unit: seconds)

Specify the length of time to wait from when OpenTP1 is notified by TCP/IP that data reception is started until OpenTP1 receives the communication control data.

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

rpc_send_retry_count=number-of-retries-if-an-error-occurs-during-TCP/IP-connection~<unsigned integer>((0-65535))

Even if any of the errors ECONNREFUSED (239), EHOSTUNREACH (242), and ENETUNREACH (229) occurs during a TCP/IP connection when the server sends a response, you may be able to avoid the error by specifying the number of retries in this operand.

When you specify 0 for this operand, no retry is performed even if any of the above errors occurs during a TCP/IP connection.

When you specify 1 to 65535 and if any of the errors occurs during a TCP/IP connection, retries are performed after waiting for the period of time specified in the rpc_send_retry_interval operand.

If you do not specify this operand here or in the user service definition, the system assumes the value in the system common definition.

rpc_send_retry_interval=interval-between-retries-if-an-error-occurs-during-TCP/IP-connection~<unsigned integer>((0-300000)) (Unit: milliseconds)

Even if any of the errors ECONNREFUSED (239), EHOSTUNREACH (242), and ENETUNREACH (229) occurs during a TCP/IP connection when the server sends a response, you may be able to avoid the error by specifying the interval in milliseconds between retries in this operand.

When you specify 0 for this operand, no interval is taken between retries to establish a TCP/IP connection. You cannot specify 1 to 19. If any value of 1 to 19 is specified, a retry is performed to establish a TCP/IP connection after 20 milliseconds.

This operand becomes valid when any value of 1 to 65535 is specified in the rpc_send_retry_count operand.

If you do not specify this operand here or in the user service definition, the system assumes the value in the system common definition.

ipc_listen_sockbufset=Y|N ~<<N>>

Specify whether to set the TCP/IP send and receive buffer sizes for the listen socket that OpenTP1 uses for inter-process communication during generation of the socket as specified in the ipc_sendbuf_size and ipc_recvbuf_size operands.

Y
Sets the TCP/IP send and receive buffer sizes for the listen socket.

N
Does not set the TCP/IP send and receive buffer sizes for the listen socket.

The TCP/IP send and receive buffer sizes specified in the ipc_sendbuf_size and ipc_recvbuf_size operands are applied after the OpenTP1 process receives a connection establishment request and establishes a connection. Because the buffer sizes are changed after the connection is established, the buffer sizes differences between the connection source and destination might cause a communication delay.

If TP1/Client communicates with TP1/Server Base on the same node, Hitachi recommends that you specify Y in this operand.

If the ipc_listen_sockbufset operand is omitted in both the user service definition and the user service default definition, the value of the ipc_listen_sockbufset operand in the system common definition is used.

ipc_recvbuf_size=receive-buffer-size-of-TCP/IP~<unsigned integer> ((8192-1048576)) (unit: bytes)

Specify the size of the receive buffer of TCP/IP allocated for each connection. When using devices with high speed communication or using a large MTU, the performance can be improved if the value in this operand is increased.

Notes:
TCP returns a delivery acknowledge (ACK) packet in response to the received data. If the length of the received data is much smaller than the size of the receive buffer, TCP may not return ACK immediately (delayed ACK).
If a great value is specified in this operand and a small amount of data is exchanged, the performance may be degraded due to delayed ACK. For details about delayed ACK, see the TCP/IP documentation.
When you specify the operand, make sure that the value does not exceed the maximum TCP/IP receive buffer size that can be specified in the OS.

For the user server, if you do not specify this operand here or in the user service definition, the system assumes the value in the system common definition.

ipc_sendbuf_size=send-buffer-size-of-TCP/IP~<unsigned integer> ((8192-1048576)) (unit: bytes)

Specify the size of the send buffer of TCP/IP allocated for each connection. When using devices with high speed communication or using a large MTU, the performance can be improved if the value in this operand is increased.

Note:
When you specify the operand, make sure that the value does not exceed the maximum TCP/IP send buffer size that can be specified in the OS.

For the user server, if you do not specify this operand here or in the user service definition, the system assumes the value in the system common definition.

polling_control_data=Y|N

This operand specifies whether to regularly poll into the waiting status where an SPP or MHP under OpenTP1 is waiting for a service request. Specify Y to check whether a temporary closing request has arrived.

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

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

You must specify Y in this operand for a resident UAP where no service request occurs for a long time.

For a system that varies in its application traffic depending on the time zone, you must specify Y in this operand of the user service definition of a resident UAP.

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

Specify the interval in seconds for polling into the waiting status where an SPP or MHP under OpenTP1 is waiting for a service request. This specification checks whether a temporary closing request has arrived.

If the services are accepted one after another without waiting, the system checks whether a temporary closing request has arrived when the time period in which service requests are accepted successively exceeds a predetermined time. This operand is also used to specify this interval. (No signal interrupt occurs for checking whether a temporary closing request has arrived, when the time period in which service 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 service 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 group.

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 value specified in this operand.

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

loadlevel_message=Y|N|A

Specify whether to output the load level notification message KFCA00849-W when the load level of the server is changed.

Y
Outputs a notification message when the load level of the server rises to a high-load status (LEVEL2) or when it drops to the normal status (LEVEL0).

N
Does not output a notification message even if the load level of the server is changed.

A
Outputs a notification message when the load level of the server is changed.

The time to output notification messages varies depending on the value of the load monitoring interval specified in the loadcheck_interval operand. If no load monitoring interval is specified, 30 seconds is assumed.

ipc_backlog_count=length-of-queue-storing-connection-establishment-requests~<unsigned integer>((0-4096))

Specify the length of the queue storing connection establishment requests. (Number of backlogged listen system calls)

The actual number to be specified as the number of backlogged listen system calls when 0 (default) is specified depends on the OS. For details, see the Release Notes.

The actual length of the queue may be longer than the specified value.

The upper and lower limits on the length vary depending on the OS. If the length of the queue is restricted with the upper and lower limits by the OS, the specified value may not be valid. For details about the queue storing connection establishment requests, see your OS or TCP/IP documentation.

If you do not specify this operand here and in the user service default definition, the system assumes the value in the system common definition.

rpc_buffer_pool_max=number-of-buffers-to-be-pooled~<unsigned integer>((1-64))

Specify the number of buffers to be pooled when a message is created during the message reception processing by the RPC.

The buffers to be used in the message reception processing are secured in the process-specific area and pooled when they become unnecessary. At this time, if the number of buffers in the buffer pool exceeds the value specified in this operand, the smallest buffer in the buffer pool, including the buffers that are pooled newly, is released.

If you specify a value smaller than the default for this operand, the number of buffers to be used in the message reception processing exceeds the number specified in this operand. Note the following in that case:

This operand can also be specified in the user service default definition.

If you do not specify this operand, the system assumes the value in the user service default definition.

schedule_delay_limit=schedule-delay-limit~<unsigned integer>((0-32767))(unit: seconds)

Specify the delay limit time for scheduling using the schedule queue.

If a timeout occurs due to this operand when service requests are left unfetched in the schedule queue, message KFCA00838-W is output to each application server. At this time, when Y is specified for the schedule_delay_abort operand, the SCD daemon ends abnormally and OpenTP1 goes down.

If you omit this operand or specify 0, schedule delay is not monitored.

The schedule service monitors for schedule delay at a 10-second interval. Therefore, it may take up to 10 seconds to detect schedule delay.

For this operand, specify a value greater than the startup processing time and the service processing time of the applicable server.

This operand is ignored when it is specified for an MHP, SPP that receives requests from sockets, and SUP.

schedule_delay_abort=Y|N

Specify whether to allow the system to go down when the schedule is delayed.

Y
The system goes down when the schedule is delayed.

N
The system does not go down when the schedule is delayed.

If a timeout has occurred due to the schedule_delay_limit operand when service requests are left in the schedule queue and Y is specified in the schedule_delay_abort operand, OpenTP1 outputs message KFCA00839-E. After output of the message, the SCD daemon terminates abnormally and OpenTP1 goes down.

If you omit the schedule_delay_limit operand or specify 0, the specification of the schedule_delay_abort operand is ignored.

This operand is ignored when it is specified for an MHP, SPP that receives requests from sockets, or SUP.

rap_autoconnect_con_error_msg=Y|N

Specify whether to output an error message if the RAP-processing server is disconnected when substitution execution for API functions is requested even though (1) the RAP-processing client is using the auto connect mode and (2) the connection with the RAP-processing server is already established.

An error message is output when you specify Y for this operand or omit this operand.

Y
An error message is output when the connection with the RAP-processing server is severed when substitution execution for API functions is requested.

N
An error message is not output when the connection with the RAP-processing server is severed when substitutional execution for API functions is requested.

The following message is suppressed by this operand:

core_shm_suppress=Y|N

Specify whether to suppress output of the shared memory dump to the core file.

Y
Suppresses output of the OpenTP1 shared memory dump to the core file.

N
Does not suppress output of the OpenTP1 shared memory dump to the core file.

If a process ends abnormally with a KFCA00105-E message, the currently attached shared memory dump may be output to the core file depending on the OS.

When you specify Y for this operand, the OS suppresses the output of the OpenTP1 shared memory dump to the core file. By doing so, the following problems can be avoided:

If a process ends abnormally with a KFCA00105-E message before this operand is enabled, the currently attached OpenTP1 shared memory dump is output to the core file. (Only OSs that output the shared memory dump to a core file do this.)

In addition, even when Y is specified for this operand, if monitoring of the CPU time times out and a process ends abnormally with a KFCA00105-E message, the currently attached OpenTP1 shared memory dump is output to the core file. Note that only OSs that output the shared memory dump to a core file do this.

Note:
The OpenTP1 shared memory dump is output only when the system goes down. Therefore, if a UAP detects an abnormality and ends, the shared memory dump is not output. When the OS outputs the shared memory dump to the core file, the shared memory dump in the core file is useful data. When you specify Y for this operand, the shared memory dump is not output, making troubleshooting difficult.

xat_connect_resp_time=maximum-response-wait-time-for-association-establishment-of-SPP-for-processing-communication-events~<unsigned integer> <<0-65535>> (units: seconds)

Specify the maximum response wait time for an association establishment request (dc_xat_connect function) in the SPP for processing communication events during the communication that uses OSI TP as the protocol. When you specify 0, the system waits for a response indefinitely.

You can specify the same setting in the XAT_CONNECT_RESP_TIME operand of the putenv format. The following table shows the relationship between the xat_connect_resp_time operand and the XAT_CONNECT_RESP_TIME operand of the putenv format.

Table 3-14 xat_connect_resp_time operand of the set format and XAT_CONNECT_RESP_TIME operand of the putenv format

Specification of xat_connect_resp_time operand of set format Specification of XAT_CONNECT_RESP_TIME operand of putenv format Valid value(unit: seconds)
Y N Value specified in the xat_connect_resp_time operand of the set format
N Y Value specified in the XAT_CONNECT_RESP_TIME operand of the putenv format
Y Y Value specified in the xat_connect_resp_time operand of the set format
N N 180#

Legend:
Y: Specified.
N: Not specified.

#: If you omit both the specification of the xat_connect_resp_time operand of the set format and the XAT_CONNECT_RESP_TIME operand of the putenv format, 180 seconds is assumed.

scd_poolfull_check_interval=interval-at-which-message-KFCA00853-E-is-output~<unsigned integer> ((0-32767)) (units: seconds)

Specify the interval at which message KFCA00853-E is output if successive memory shortages occur for the message storage buffer pool.

If the number of memory shortages occurring for the message storage buffer pool reaches the value of the scd_poolfull_check_count operand within the time specified in the scd_poolfull_check_interval operand, one KFCA00853-E message is output.

The timer for the scd_poolfull_check_interval operand starts when a memory shortage for the message storage buffer pool has occurred. The timer is reset when another memory shortage occurs after the timer has expired.

If you specify 0 in this operand, message KFCA00853-E is not output.

This operand can be specified only for SPPs that receive requests from queues, and will be ignored if specified for other user servers.

scd_poolfull_check_count=threshold-for-determining-whether-to-output-message-KFCA00853-E~<unsigned integer> ((1-32767)) (units: times)

Specify the threshold for determining whether to output message KFCA00853-E if successive memory shortages for the message storage buffer pool occur.

If the number of memory shortages occurring for the message storage buffer pool reaches the value of the scd_poolfull_check_count operand within the time specified in the scd_poolfull_check_interval operand, message KFCA00853-E is output.

This operand can be specified only for SPPs that receive requests from queues, and will be ignored if specified for other user servers.

scd_pool_warning_use_rate=maximum-use-rate-for-the-message-storage-buffer-pool-triggering-output-of-a-warning-message~<unsigned integer> ((0-99)) (units: %)

Specify the use rate for the message storage buffer pool that triggers output of a warning message.

The value to be specified is the percentage of the used memory area in the message storage buffer pool. The size of the buffer pool is specified in the message_store_buflen operand of the user service definition or specified by the definition command scdbufgrp.

Whether warning message KFCA00829-W is to be output is determined by the use rate of the message storage buffer pool at the moment that a service request is put in the schedule queue. Once the message is output, it will not be output again until the use rate falls below and then exceeds again the value of this operand.

If 0 is specified in this operand or if this operand is not specified, the warning message is not output.

If the message storage buffer pool has been shared by multiple user servers on the basis of the schedule buffer group, the use rate is calculated with the size of area used by all user servers that share the buffer pool. This means that warning message KFCA00829-W may be output even when the use rate for a specific user server is below the value of this operand.

Regardless of the specification of this operand, if a memory shortage for the message storage buffer pool occurs, error message KFCA00854-E, not warning message KFCA00829-W, is output.

You can specify this operand only for queue-receiving SPPs. If you specify the operand for other SPPs, the operand is ignored.

scd_pool_warning_interval=interval-at-which-a-warning-message-is-output-if-the-use-rate-for-the-message-storage-buffer-pool-is-exceeded~<unsigned integer> ((0-32767)) (units: seconds)

Specify the interval at which a warning message (KFCA00829-W) is output if the use rate for the message storage buffer pool (specified in the scd_pool_warning_use_rate operand) is exceeded.

When this operand has been specified, once warning message KFCA00829-W has been output, it is not output again until the time specified in this operand elapses, even if the use rate for the message storage buffer pool exceeds scd_pool_warning_use_rate.

ipc_tcpnodelay=Y|N

Specify whether to use the TCP_NODELAY option for the socket that OpenTP1 uses for inter-node communication (INET domain).

When the TCP_NODELAY option is used (that is, when Y is specified in this operand), the Nagle algorithm is disabled. When the algorithm is disabled, you can send data without delay even during a wait for a response to data that has been sent. Note that if this option is used, the efficiency of sending data in INET domain communication may be degraded and the network load may increase. Before using the option, carefully consider whether the option is necessary by taking into account the ipc_sendbuf_size operand, the ipc_recvbuf_size operand, the network bandwidth, and other factors.

stay_watch_queue_count=number-of-service-requests-triggering-the-start-of-judgment-of-the-schedule-queue-accumulation-status~<unsigned integer> ((0-32767))

Specify the number of service requests triggering the start of judgment of the schedule queue accumulation status.

If the number of service requests in the schedule queue exceeds the value of this operand, monitoring of service requests remaining in the schedule queue starts. The interval for checking the number of service requests remaining in the schedule queue is specified in the stay_watch_start_interval operand. Once the judgment starts, the number of service requests remaining in the schedule queue is checked at the interval specified in the stay_watch_check_interval operand. When the number of remaining service requests falls below the value of this operand, judgment ends. When the number of remaining service requests reaches the value of this operand again, judgment starts again.

If 0 is specified in the stay_watch_queue_count operand, OpenTP1 does not monitor the number of service requests remaining in the schedule queue. This operand is ignored if specified for an RAP, an MHP, an SPP that receives messages from sockets, or an SUP.

For details about the monitoring of service requests remaining in the schedule queue, see the manual OpenTP1 Operation.

stay_watch_check_rate=service-request-processing-rate-used-for-monitoring-the-service-requests-remaining-in-the-schedule-queue~<unsigned integer> ((1-100)) (units: %)

Specify the service request processing rate used for monitoring the service requests remaining in the schedule queue.

Judgment of the schedule queue accumulation status uses the following conditional expression to output message KFCA00833-W to each applicable server if the condition evaluates to true.

Conditional expression for judgment of the schedule queue accumulation status:
Number of processed service requests < value of this operand x number of service requests remaining in the schedule queue

If this condition evaluates to true when Y is specified in the stay_watch_abort operand, the SCD daemon terminates abnormally (abort code hclen001 is output) and OpenTP1 stops.

If the stay_watch_queue_count operand is not specified or if 0 is specified in the operand, the stay_watch_check_rate operand is ignored.

The stay_watch_check_rate operand is ignored if specified for an RAP, an MHP, an SPP that receives messages from sockets, or an SUP.

For details about the monitoring of service requests remaining in the schedule queue, see the manual OpenTP1 Operation.

stay_watch_abort=Y|N

Specify whether to shut down OpenTP1 if the conditional expression for judging the schedule queue accumulation status evaluates to true.

Y
If the conditional expression evaluates to true, messages KFCA00833-W and KFCA00834-E are output. OpenTP1 goes down after forcibly terminating the relevant user server and the SCD daemon (abort code hclen001 is output).

N
If the conditional expression evaluates to true, message KFCA00833-W is output. OpenTP1 does not go down.

If the stay_watch_queue_count operand is not specified or if 0 is specified in the operand, the stay_watch_abort operand is ignored. Also, the stay_watch_abort operand is ignored if specified for an RAP, an MHP, an SPP that receives messages from sockets, or an SUP.

For details about the monitoring of service requests remaining in the schedule queue, see the manual OpenTP1 Operation.

stay_watch_start_interval=interval-for-checking-the-number-of-service-requests-remaining-in-the-schedule-queue~<unsigned integer> ((1-32767)) (units: seconds)

Specify the interval for checking the number of service requests remaining in the schedule queue.

If the stay_watch_queue_count operand is not specified or if 0 is specified in the operand, the stay_watch_start_interval operand is ignored. Also, the stay_watch_start_interval operand is ignored if specified for an RAP, an MHP, an SPP that receives messages from sockets, or an SUP.

Normally, the SCD daemon checks the load every 10 seconds. When the stay_watch_start_interval operand has been specified, the daemon checks the load at the interval equal to the greatest common measure of the following values (in seconds): (1) 10, (2) the values of the stay_watch_start_interval operands of the user servers, and (3) the values of the stay_watch_check_interval operands of the user servers. To minimize the impact on the OpenTP1 system, Hitachi recommends that you specify a multiple of 5 in the stay_watch_start_interval operand.

For details about the monitoring of service requests remaining in the schedule queue, see the manual OpenTP1 Operation.

stay_watch_check_interval=interval-for-judging-the-schedule-queue-accumulation-status~<unsigned integer> ((1-65534)) (units: seconds)

Specify the interval for judging the schedule queue accumulation status by using the conditional expression for this judgment.

This judgment starts when the number of service requests remaining in the schedule queue exceeds the value of the stay_watch_queue_count operand.

If the stay_watch_queue_count operand is not specified or if 0 is specified in the operand, the stay_watch_check_interval operand is ignored. Also, the stay_watch_check_interval operand is ignored if specified for an RAP, an MHP, an SPP that receives messages from sockets, or an SUP.

Normally, the SCD daemon checks the load every 10 seconds. When the stay_watch_check_interval operand has been specified, the daemon checks the load at the interval equal to the greatest common measure of the following values (in seconds): (1) 10, (2) the values of the stay_watch_start_interval operands of the user servers, and (3) the values of the stay_watch_check_interval operands of the user servers. To minimize the impact on the OpenTP1 system, Hitachi recommends that you specify a multiple of 5 in the stay_watch_check_interval operand.

For details about the monitoring of service requests remaining in the schedule queue, see the manual OpenTP1 Operation.

trn_completion_limit_time=time-limit-for-completing-transaction~<unsigned integer> ((0-65535)) (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.

If the trn_completion_limit_time operand is omitted in both the user service definition and the user service default definition, the value of the trn_completion_limit_time operand in the transaction service definition is used.

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

For the correspondence between the values of this operand and the messages that will be output, see the description of the rap_message_id_change_level operand of the RAP-processing listener service definition.

log_audit_out_suppress=Y|N ~<<N>>

Specify whether to suppress output of audit log data from this user server.

Y
Output of audit log data from this user server is suppressed.

N
Output of audit log data from this user 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 items for which you want to acquire audit log data. You can specify message IDs in the range from 33400 to 99999. The maximum number of message IDs you can specify is 2048.

You can specify the following audit log message IDs:

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

If this operand is omitted in the user service definition when this operand 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 user service definition.

mcf_prf_trace=Y|N

~<<Y>>

Specify whether to acquire MCF performance verification trace information for each user server. To enable the value specified in this operand, specify 00000001 in the mcf_prf_trace_level operand of the system service common information definition.

Y
MCF performance verification trace information is acquired.

N
MCF performance verification trace information is not acquired.

You can also specify this operand with the user service default definition.

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

  1. User service definition
  2. User service default definition

If the operand specification or the value specified in it is invalid, the user server abnormally terminates during startup.

The table below shows the relationship between the value specified in the mcf_prf_trace_level operand (whether the MCF performance verification trace information is acquired) in the user server and the value specified in the mcf_prf_trace operand.

Table 3-15 Relationship between the value specified in the mcf_prf_trace_level operand (whether the MCF performance verification trace information is acquired by the user server) in the user server and the value specified in the mcf_prf_trace operand

System service common information definition
mcf_prf_trace_level operand specification value
User service definition
mcf_prf_trace operand specification value
Y N
00000000 Not acquired Not acquired
00000001 Acquired Not acquired

Use this definition only when TP1/Extension 1 is installed. If TP1/Extension 1 is not installed, the definition might not work correctly.

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

Specify the maximum time to wait for a response to a service request sent in inter-process communication that uses RPCs.

OpenTP1 might wait for the time specified in this operand during termination processing. 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 in this operand, OpenTP1 waits until it receives a response. 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.

command format

Described on the following pages.

putenv format

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

Set values for the environment variables specified with the processes of these service groups.

OpenTP1 activates a COBOL operating environment, hence this operand is used for setting the COBOL environment. An unique environment variable can be allocated for each UAP execution form program. See the standard C library putenv for details.

When PATH is set here, the specification of the prcsvpath operand in the process service definition and the specification of the operation command prcpath become invalid for this service group and the value of PATH is used. When setting PATH, include the directory where the load module of the service group is placed.

For OpenTP1, do not use environment variable names beginning with dc.

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

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

Specify a value equal to or greater than 8 in this operand. If an ECONNREFUSED error occurs during connection establishment of the communication control part, the system waits for the time period specified in the DCFPL_CONNECT_RETRY_INTERVAL operand and retries to establish a connection.

When this operand is omitted or a value smaller than 8 is specified, 8 is assumed.

DCFPL_CONNECT_RETRY_INTERVAL interval-between-retries-to-establish-a-connection~<unsigned integer>((10-999))(Unit: milliseconds)

Specify the interval in milliseconds between retries to establish a connection if an ECONNREFUSED error occurs during connection establishment of the communication control part when using the remote API facility.

When this operand is omitted or a value out of the range from 10 to 999 is specified, 100 is assumed.

XAT_CONNECT_RESP_TIME=maximum-response-wait-time-for-association-establishment-of-SPP-for-processing-communication-events~<unsigned integer>((0-65535))(units: seconds)

Specify the maximum response wait time for an association establishment request (dc_xat_connect function) in the SPP for processing communication events during the communication that uses OSI TP as the protocol. When you specify 0, the system waits for a response indefinitely.

You can specify the same setting in the xat_connect_resp_time operand of the set format. For the relationship between this operand and the xat_connect_resp_time operand in set format, see Table 3-14.

dcputenv format

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

Set values for the environment variables specified in the processes of these service groups. When an environment variable name is specified as the environment variable value, the value of the environment variable name is also acquired.

For OpenTP1, do not use any environment variable name beginning with dc.