OpenTP1 Version 7 System Definition

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

dcsvgdef (Specify the service information of the destination)

Format

{{dcsvgdef -g service-group-name [, service-group-name] ...
          {-h host-name[:port-number][,host-name[:port-number]]...
          [-p port-number]
          [-t destination-reselection-interval][-w]}            }}

Function

When using SPP services under TP1/Server Base of another node via the remote API facility, the dcsvgdef command specifies the SPP service group name, and the host name and port number of the receiving side of the services of the remote API facility. This command also specifies whether to use the remote API facility.

Alternatively, when using SPP services under TP1/Server Base of a node that is not specified in the all_node operand, the dcsvgdef command specifies: the SPP service group name; the host name of a node in the global domain where the SPP resides; and the port number specified in the scd_port operand of the schedule service definition. You can specify multiple host names and port numbers (no more than one host name or port number can be specified when using the remote API facility).

The version of TP1/Server Base on the server side where SPP is running must be 03-03 or later.

This command executes the dc_rpc_call service request called by the UAP specified with namd or definition in the rpc_destination_mode operand in the user service definition, without requesting a destination search by the name server.

When namd is specified in the rpc_destination_mode operand for the UAP, the UAP executes the service request based on the information specified in this definition command if the destination search request to the name server fails. When definition is specified in the rpc_destination_mode operand and multiple hosts are specified in this definition command for the UAP, the UAP executes the service request based on the information specified in this definition command. If the request fails, the UAP requests the destination search by the name server. If only one host is specified in this definition command, the UAP does not request the destination search by the name server.

OpenTP1 searches for the service group name specified in the first argument of dc_rpc_call invoked from a UAP. This UAP has namd or definition specified in the rpc_destination_mode operand of the user service definition, which is determined out of service group names specified in the user service network definition. When OpenTP1 finds the definition having the service group name, it sends a service request to the host and port number specified in the definition.

When multiple host names are specified, OpenTP1 randomly selects a host to send a service request. If an error occurs when sending a service request, OpenTP1 randomly selects a host again from the remaining hosts. If sending the service request failed for all the hosts, dc_rpc_call returns an error. Once a service request is successful, if a destination reselection interval is not specified, the subsequent dc_rpc_call invocations made in the UAP to the same service group continue to send service requests to the same host until an error occurs. If a failure occurs while sending a service request to the same host, OpenTP1 selects a host randomly from all the hosts except the one which failed this time and sends a service request.

Note that in certain situations, OpenTP1 selects a host at random and sends a service request to the host the next time dc_rpc_call is invoked. Those situations are as follows:

When rpc_destination_mode is definition or omitted and either of the following occurs:
  • A service request is not successfully sent to any host, a destination search request to the name server fails, and, as a result, dc_rpc_call returns an error.
  • A service request is not successfully sent to any host, a destination search request to the name server is successful, and dc_rpc_call is successful.

When rpc_destination_mode is namd and all of the following conditions are satisfied:
  • A destination search request to the name server fails.
  • A service request is not successfully sent to any host.
  • dc_rpc_call returns an error.
  • Another destination search request to the name server fails the next time dc_rpc_call is invoked.

The following figure shows an example of dc_rpc_call operation when multiple host names are specified.

Figure 3-5 Example of dc_rpc_call operation when multiple host names are specified in the dcsvgdef definition command

[Figure]

If the same service group name is specified in more than one dcsvgdef definition, the first dcsvgdef definition appearing in the user service network definition file becomes effective. The -w option lets you determine whether the information is about the service requested via the remote API facility. The -w option lets you determine whether the service in a node is not specified in the all_node operand.

Do not issue a service request from the XATMI interface for the service group name specified in the dcsvgdef definition. Otherwise, the operation cannot be assured.

If dc_rpc_call is issued from the transaction to the service group (SPP) specified in the dcsvgdef definition without the -w option and with atomic_update=N specified, dc_rpc_call returns an error with DCRPCER_TRNCHK. In this case, you must specify Y in the atomic_update operand of the SPP or specify DCRPC_TPNOTRAN in the flags operand of dc_rpc_call.

If you execute dc_rpc_call for a service group name in dcsvgdef without the -w option and acquire the trace for performance verification, the acquired trace is not linked with the trace information for performance verification on the server. In other words, the serial number of the trace for performance verification acquired by the client UAP is not inherited by the server and a new serial number is output to the trace for performance verification acquired on the server.

If an asynchronous RPC is requested for the service group name specified in the dcsvgdef definition with the -w option specified, this user service network definition is regarded as invalid. If this happens, OpenTP1 processes the request using a name information search as usual. Even if a service request is issued as a transaction for the service group specified in the dcsvgdef definition with the -w option specified, it is unconditionally processed in the non-transaction mode.

If dc_rpc_call is executed for the service group specified in the dcsvgdef definition with the -w option specified, no RPC trace is acquired. For dc_rpc_call issued to the service group defined as a service on the node via the remote API facility in the user service network definition, no client trace information is acquired even if the system definition of the client UAP is set to acquire the client trace information.

If dc_rpc_call is executed for the service group specified in the dcsvgdef definition with the -w option specified, the performance verification trace information is acquired. However, the trace information does not link with the performance verification trace information of dc_rpc_call executed by proxy on the RAP-processing server. That is, the serial numbers of the performance verification trace information acquired by the client UAP are not inherited to the RAP-processing server. Therefore, the newly allocated serial numbers are output for the performance verification trace information of dc_rpc_call executed by proxy on the RAP-processing server.

If dc_rpc_call is executed for the service group specified in the dcsvgdef definition with the -w option specified, response statistics/communication delay statistics is not acquired. No statistics is acquired for dc_rpc_call to the service group defined as a service on the node via the remote API facility in the user service network definition. This happens even if the system definition is set to acquire the response statistics/communication delay statistics.

When using the remote API facility in communication to TP1/Server Base with the -w option specified (for example, performing an RPC via a gateway such as the application gateway type fire wall), even if the dc_rpc_call function is issued with a transaction attribute specified, it cannot be a transaction. Therefore, an operation to start a chain RPC from a transaction and terminate it by synchronous point processing does not perform correctly if the remote API facility is used. Explicitly terminate the chain RPC by using the dc_rpc_call function with DCNOFLAGS specified in the flags argument.

Options

-g service-group-name~ (identifier consisting of up to 31 characters)

This option specifies the service group name of either a service that is used through the remote API facility or a service on any node that is not specified by the all_node operand. Using the "SC + *" format, where SC is the starting character (or characters) of a service group name, it can collectively specify multiple service groups.

If you specify the service group name of a service on any node that is not specified by the all_node operand, this service must be the SPP in which queue is specified in the receive_from operand of a user service definition.

-h host-name:port-number~ (identifier consisting of up to 255 characters)

This option specifies the host name of the receive port for a service through the remote API facility or the host name used by the OpenTP1 communication at any node that is not specified by the all_node operand of a system common definition. The identifier you specify can consist of alphanumeric characters, periods, and hyphens. You cannot specify the identifier in an IP address format. The host name must be mapped with an IP address in the /etc/hosts file or by using DNS.

You can specify a port number after a host name by separating them with a colon. You can specify a port number between 5001 and 65535. If you do not specify a port number here, the port number specified in the -p option is assumed. You cannot omit both port numbers in the -h option and the -p option. If you do not specify either port number, the KFCA00340-W message is output.

You can specify multiple host names by separating them with a comma. When you use the remote API facility (when you specify the -w option), you cannot specify multiple host names. If you specify multiple host names when you use the remote API facility, the KFCA00340-W message is output.

When you specify only one host name in this option, the destination search request is not sent to the name server even if definition is specified in the rpc_destination_mode operand in the user service definition.

-p port-number~ <unsigned integer> ((1-65535))

This option specifies the port number of the receive port for a service through the remote API facility or the port number specified by the scd_port operand of an OpenTP1 schedule service definition at any node that is not specified by the all_node operand of a system common definition.

With the -w option specified, if you specify the port number of the receive port for a service through the remote API facility, the port number may range from 1 to 65535. Without the -w option specified, if you specify the port number specified by the scd_port operand of a schedule service definition, the port number may range from 5001 to 65535. In case the specified port number is outside the specified range, the system issues a KFCA00340-W message.

-t destination-reselection-interval~<unsigned integer> ((0-65534)) (units: seconds)

When multiple host names are specified in the -h option, enabling OpenTP1 to continue sending a service request, specify in seconds the interval at which the destination of the service request is reselected at random.

When only one host name is specified in the -h option, the value of the -t option does not take effect. After a service request is successfully sent to a destination specified in the -h option and communication with the destination starts, OpenTP1 checks whether the time specified in the -t option has expired each time a service request is sent. If the specified time has expired, OpenTP1 reselects the destination at random. Even when the specified time has expired, OpenTP1 will not reselect the destination unless there is a service request to be sent to the destination.

Note that the previous destination can be reselected again. When 0 is specified in this option, OpenTP1 reselects the destination at random each time a service request is sent. If this option is omitted, OpenTP1 continues to send service requests to the same destination that has successfully received a service request until an error occurs at the destination.

The following describes how OpenTP1 monitors the elapsed time.

-w

You can specify this option when using the remote API facility. With this option specified, the values specified in the -h and -p options refer to the information about the receive port for a service through the remote API facility.