ANSI C, C++

#include <dcrpc.h>
int  dc_rpc_call (char *group, char *service, char *in,
                  DCULONG *in_len, char *out,
                  DCULONG *out_len, DCLONG flags)

K&R C

#include <dcrpc.h>
int  dc_rpc_call (group, service, in, in_len, out, out_len,
                  flags)
char       *group;
char       *service;
char       *in;
DCULONG    *in_len;
char       *out;
DCULONG    *out_len;
DCLONG     flags;

The function dc_rpc_call() requests an SPP service. This function can be called without consideration of the node containing the requesting service.

Specify a service group name and service name as arguments of the function dc_rpc_call() to request a service. A service request is addressed to the service function corresponding to the specified names.

A UAP which calls the function dc_rpc_call() can be used regardless of whether it has been executed as a transaction. When a service is requested by the function dc_rpc_call() from the process which has been executed as a transaction, the requested service process runs as a transaction branch.

Before this function can be used, the OpenTP1 at the node containing the server UAP to which the service request is addressed must be active.

Receiving a signal while waiting for a response after execution of the function dc_rpc_call() does not cause the function to be returned.

The following items are described after the list of return values. See each description For details on the function dc_rpc_call().

(1) Arguments of the function dc_rpc_call()

(2) Error cases of the function dc_rpc_call()

(3) Timing when the function dc_rpc_call() results in error

(4) Specification for reexecuting the service request if the function dc_rpc_call() results in error

(5) When a priority is given to a service request

(6) Difference between return values DCRPCER_NO_SUCH_SERVICE_GROUP and DCRPCER_NET_DOWN

(7) Specification for returning the value DCRPCER_SERVICE_TERMINATED

(8) Relationship between return values and synchronization point processing

(9) Notes on requesting a service

(10) When a service is requested with domain qualification

group

Specify the SPP service group name with an ASCII character string of up to 31 bytes. End the character string with a null character. The null character is not counted in the length of the character string.

When requesting a service with domain qualification, specify the service group name suffixed by an at mark (@) and the DNS domain name, and end the character string with a null character.

service

Specify the SPP service name with an ASCII character string of up to 31 bytes. End the character string with a null character. The null character is not counted in the length of the character string.

in

Specify the input parameter of the service.

in_len

Specify the input parameter length of the service within the range from 1 to DCRPC_MAX_MESSAGE_SIZE^#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

out

Specify the area for the response from the service function. This area will receive the response from the service function.

out_len

Specify the length of the response from the service function within the range from 1 to DCRPC_MAX_MESSAGE_SIZE^#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Even if the RPC is the non response-type, you must specify the address of the area for which the length of the response from the service is specified. If it is, the length of the response from the service must be 0.

flags

Specify the RPC mode and option in the following format:

{DCNOFLAGS|DCRPC_NOWAIT|DCRPC_NOREPLY|DCRPC_CHAINED}
[|DCRPC_TPNOTRAN][|DCRPC_DOMAIN]

DCNOFLAGS

Synchronous response-type RPC

DCRPC_NOWAIT

Asynchronous response-type RPC

DCRPC_NOREPLY

Nonresponse-type RPC

DCRPC_CHAINED

Chained RPC

DCRPC_TPNOTRAN

Specify this option not to handle the requested processing as a transaction. When DCRPC_TPNOTRAN is specified, the processing of the service function is not handled as a transaction even if the service is requested from the transaction.

DCRPC_DOMAIN

Specify this option when the service group name is specified with domain qualification. An RPC with domain qualification cannot be a transaction branch. Therefore, specify this option together with DCRPC_TPNOTRAN whenever the function dc_rpc_call() is used from the transaction.

Specify DCRPC_TPNOTRAN and/or DCRPC_DOMAIN together with the RPC mode.

Example 1:

When a nontransaction service is requested by using a synchronous response-type RPC, specify for flags as follows:

DCNOFLAGS|DCRPC_TPNOTRAN

Example 2:

When a service is requested by using a synchronous response-type RPC with domain qualification from the transaction, specify for flags as follows:

DCNOFLAGS|DCRPC_TPNOTRAN|DCRPC_DOMAIN

out

The response set by the service function is returned.

out_len

The length of the response set by the service function is returned.

The following return values are returned from the OpenTP1, not from the service function.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Arguments of the function dc_rpc_call() are explained below.

Values passed to server UAP

Allocate an area (out) for the response from the service function before requesting a service. The client UAP sets the following values in the function dc_rpc_call().

• Input parameter (in)
• Input parameter length (in_len)
• Response length (out_len)
  The input parameter, input parameter length, and response length values which are set in the function dc_rpc_call() of the client UAP are passed to the service function as is. Change the notation of character codes or digits in the processing of the client UAP or requested service function if required. If a service request is addressed to the service function which does not return any response, the specified response length is ignored.
  The maximum values of input parameter length and response length are declared as DCRPC_MAX_MESSAGE_SIZE^# in the header file dcrpc.h. See the contents of dcrpc.h to confirm the maximum values.
  

  #: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Values returned from server UAP

When the service function terminates and response is returned, the following values can be referenced:

• Response from service function (out)
• Length of response from service function (out_len)

The value of out_len is the length of the response which is actually returned from the service function. The values of out and out_len can be referenced in the following cases depending on the RPC mode:

• In the case of synchronous response-type RPC and chained RPC
  The values of out and out_len can be referenced when the function dc_rpc_call() returns.
  
• In the case of asynchronous response-type RPC
  The value of out can be referenced when the function dc_rpc_poll_any_replies() which receives the response returns. The value of out_len cannot be referenced.
  
• In the case of nonresponse-type RPC
  The values of out and out_len cannot be referenced.
  

If the function dc_rpc_call() or dc_rpc_poll_any_replies() returns with an error, the values of out and out_len cannot be referenced.

If the returned response is larger than the response area acquired by the client UAP, the function returns with an error, giving the return value DCRPCER_REPLY_TOO_BIG.

Value specified for flags

The value specified for flags and the execution result of the function dc_rpc_call() are explained below.

• Synchronous response-type RPC (when DCNOFLAGS is specified for flags)
  The function dc_rpc_call() will not return until a response returns or a communication error occurs.
  
• Asynchronous response-type RPC (when DCRPC_NOWAIT is specified for flags)
  The function dc_rpc_call() will return immediately. The response can be referenced after the response is received asynchronously in the function dc_rpc_poll_any_replies(). Do not free the response storage area (out) until the asynchronous response-type RPC is terminated due to one of the following causes:
  
• A response is received by the function dc_rpc_poll_any_replies()
• The receiving of responses is rejected by the function dc_rpc_discard_further_replies()
• Commitment or rollback is performed when a service is requested from a transaction.
  When an asynchronous response-type RPC is used in a transaction, receive responses by using the function dc_rpc_poll_any_replies() before performing the synchronization point processing (commitment or rollback). No response can be received by the function dc_rpc_poll_any_replies() after the synchronization point processing. To designate a specific response received by the function dc_rpc_poll_any_replies(), specify the positive integer (descriptor), which is returned by the function dc_rpc_call(), as the argument of the function dc_rpc_poll_any_replies(). Thus, hold the return value of the function dc_rpc_call() to designate a specific response received.
  To receive responses after the synchronization point processing while in non-transaction processing, specify the corresponding option in the rpc_extend_function operand of the system service definition.
  For details about rpc_extend_function, see the manual OpenTP1 System Definition.
  
• Nonresponse-type RPC (when DCRPC_NOREPLY is specified for flags)
  The function dc_rpc_call() will return immediately without waiting for completion of the service function processing. The service function is treated as a function which does not return any response. Therefore, the UAP requesting a service cannot determine whether the service function has been performed. With this specification, the response (out) and its length (out_len) cannot be referenced.
  
• Chained RPC (when DCRPC_CHAINED is specified for flags)
  The function dc_rpc_call() will not return until a response is returned or a communication error occurs. If two or more services belonging to the same service group in chained RPCs are requested, the subsequent services can be handled in the same process as for the service requested first.
  

There are the following restrictions on the use of chained RPCs:

1. The shutdown state of the user server or service cannot be detected by the second and subsequent calls of the function dc_rpc_call().
2. The entire user server enters in shutdown state if an error occurs during the service function processing of the second and subsequent calls of the function dc_rpc_call(). Services do not enter in shutdown state individually.

Reasons why the function dc_rpc_call() returns with an error are explained below.

If the OpenTP1 at the node containing the server UAP is not active

If the OpenTP1 to which the service request is addressed is not active, the function dc_rpc_call() returns with an error, giving one of the following return values:

• DCRPCER_NET_DOWN
• DCRPCER_SERVICE_NOT_UP
• DCRPCER_OLTF_NOT_UP
• DCRPCER_OLTF_INITIALIZING

If the server UAP is not active

When the server UAP is a multiserver, the service request is dealt with a new process which is activated by the OpenTP1 even if the server UAP is being terminated abnormally or being partially recovered. However, the function dc_rpc_call() returns with an error in the following cases:

1. No service request can be addressed to the SPP in shutdown state. If the service group is shut down, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_SERVICE_CLOSED.
2. If the SPP is being terminated or has been terminated by the stop command for the user server (dcsvstop command) or for OpenTP1 (dcstop command), the dc_rpc_call() function returns with an error and sets one of the following status code values:
   
   • DCRPCER_SERVICE_TERMINATING
   • DCRPCER_SERVICE_CLOSED
   • DCRPCER_NO_SUCH_SERVICE_GROUP
   The value that is returned depends on the timing of calling the dc_rpc_call() function.
   
3. If the OpenTP1 is being started, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_OLTF_INITIALIZING. In this case, a service may be requested normally after activation of the server UAP or OpenTP1 is completed. Since activation of the OpenTP1 is completed when a message log with the message ID KFCA01809-I is output, request a service again after this message appears.

When a service is requested in the environment for the internode load-balancing facility and the extended internode load-balancing facility

In the environment for the internode load-balancing facility and the extended internode load-balancing facility, if the schedule of the applicable service is closed, OpenTP1 automatically transfers a service request to another node. However, the function dc_rpc_call returns DCRPCER_TRNCHK, and control is returned due to an error under either of the following conditions:

1. For transaction processing, the transaction attribute of the service on the transfer destination node does not match the closed service.
2. The version of the OpenTP1 on the transfer destination node is earlier than that of the node for the OpenTP1 that requested the service.

When control is returned as a result of the foregoing error, take the following actions:

1. Force the transaction attributes of the SPPs making up the internode load-balancing facility and the extended internode load-balancing facility to match.
2. Force the OpenTP1 versions making up the internode load-balancing facility and the extended internode load-balancing facility to match.

When a service request is addressed to the server that receives requests from socket

The server that receives requests from socket controls message congestion according to the specified values for max_socket_msg and max_socket_msglen in the user service definition. It is probable that service requests cannot be accepted if a message exceeds the defined value. In this case, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_SERVER_BUSY. If this value is returned, the client UAP can sometimes reissue the service request successfully after waiting for a while.

When a chained RPC is used

If the function dc_rpc_call() which is not a transaction is called from the UAP using a chained RPC which is processed as a transaction to the same server UAP, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_NOT_TRN_EXTEND.

When the online tester is used

If the online tester is in use and the function dc_rpc_call() is called from a UAP in test mode to a UAP in nontest mode or vice versa, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_TESTMODE.

When the security facility is used

If the desired service is protected with the security facility when the function dc_rpc_call() is called and the client UAP which called the function does not have the access permission for the SPP, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_SECCHK.

The following explains the timing when an error is returned to the client UAP if the SPP to which the service request is addressed terminates abnormally.

• Synchronous response-type RPC or chained RPC (when DCNOFLAGS or DCRPC_CHAINED is specified for flags)
  If an SPP which executes a service terminates abnormally before completion of the processing, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_TIMED_OUT. If an infinite period of time is specified in the watch_time operand in the user service definition of the client UAP, the function returns with an error, giving the return value DCRPCER_SERVICE_NOT_UP.
  
• Asynchronous response-type RPC (when DCRPC_NOWAIT is specified for flags)
  If an SPP which executes a service terminates abnormally before completion of the processing, the function dc_rpc_poll_any_replies() returns with an error, giving the return value DCRPCER_TIMED_OUT. If an infinite period of time is specified in the watch_time operand in the user service definition of the client UAP, the function returns with an error, giving the return value DCRPCER_SERVICE_NOT_UP.
  
• Nonresponse-type RPC (when DCRPC_NOREPLY is specified for flags)
  The client UAP cannot detect abnormal termination of server UAP.
  

When the function dc_rpc_call() results in error due to time monitoring of the client UAP

In the following cases, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_TIMED_OUT, after the time specified in the watch_time operand in the user service definition of the client UAP has elapsed:

• The entire OpenTP1 at the node containing the SPP terminates abnormally.
• An error occurs before the server UAP receives service request data or before the client UAP receives the result after the server UAP processing is completed.

Even if the OpenTP1 to which the service request is issued is not active because it is being started or is engaged in system switching, you can have the OpenTP1 re-execute the requested search and service request transmission without treating the dc_rpc_call() function processing as an error.

To re-execute the requested search and service request transmission, specify Y in the rpc_retry operand in the system common definition. You use the rpc_retry_count and rpc_retry_interval operands to specify the re-execution count and re-execution interval, respectively, for a requested search and service request transmission. If this count value exceeds the re-execution count value specified in the system common definition, the dc_rpc_call() function returns with an error and sets one of the following status code values:

• DCRPCER_INVALID_ARGS
• DCRPCER_NET_DOWN
• DCRPCER_SERVICE_NOT_UP
• DCRPCER_NO_SUCH_SERVICE_GROUP
• DCRPCER_OLTF_NOT_UP
• DCRPCER_OLTF_INITIALIZING

To specify a schedule priority for a service request, call the function dc_rpc_set_service_prio() immediately before the function dc_rpc_call(). If no schedule priority is specified, the priority of the service request is determined according to the default interpretation of the schedule service.

These return values are returned if the user server corresponding to the service group name is not found.

• DCRPCER_NO_SUCH_SERVICE_GROUP
  Indicates the user server is not found after searching all nodes specified for all_node in the system common definition.
  
• DCRPCER_NET_DOWN
  Indicates a communication error occurred on one or more nodes specified for all_node during the search. This return value may indicate the corresponding OpenTP1 system is not found.
  

You may want to determine whether the SPP that requested a service terminated abnormally before completion of processing based on a returned value other than DCRPCER_TIMED_OUT or DCRPCER_SERVICE_NOT_UP. If so, specify 00000001 in the rpc_extend_function operand of the user service definition. This specification returns DCRPCER_SERVICE_TERMINATED if the above error occurs. If 00000000 is specified in the rpc_extend_function operand, or the operand is omitted, DCRPCER_TIMED_OUT or DCRPCER_SERVICE _NOT_UP is returned rather than DCRPCER_SERVICE_TERMINATED.

The relationship between return values of the function dc_rpc_call() and synchronization point processing (commitment and rollback) is explained below. The description applies to the service request which is a transaction, rather than the service request which is not a transaction (including the case when DCRPC_TPNOTRAN is specified for flags).

When commitment is performed even though the function dc_rpc_call() returns with an error

The return value DCRPCER_TIMED_OUT may be returned due to abnormal termination of the service function which the service request is addressed, a node error, or network error. However, when the client UAP is not a transaction, the service function to which the service request is addressed may terminate normally and database may be updated.

Error return values which require rollback processing

If the function dc_rpc_call() called from a transaction returns with an error, some return values always require rollback processing for the transaction (the server UAP enters rollback_only state). In this case, rollback processing is always performed even if either of the commitment function or rollback function is used. The following return values of the function dc_rpc_call() always require rollback processing for the transaction:

• DCRPCER_INVALID_REPLY
• DCRPCER_NO_BUFS_AT_SERVER
• DCRPCER_NO_SUCH_SERVICE
• DCRPCER_REPLY_TOO_BIG_RB

1. Define the service group name and service name at server UAP environment setup. These names are set in the function dc_rpc_call(). If a service is requested while invalid service group name or service name is set in the function dc_rpc_call(), the function returns with an error, giving the return value DCRPCER_NO_SUCH_SERVICE_GROUP or DCRPCER_NO_SUCH_SERVICE. If the service function does not return response, the function dc_rpc_call() does not return with an error, giving the return value DCRPCER_NO_SUCH_SERVICE.
2. The process of the server UAP is different from that of the client UAP. Therefore, the following matters are different from ordinary function calls and procedure calls:
   
   • Attributes (such as environment variables, schedule priority (nice value)) which are given to the process of the client UAP by the OS are not passed on to the server UAP.
   • Environment settings (such as existence of specification of transaction attribute, time limit of transaction branch, schedule priority) of the OpenTP1 specified at the node of the client UAP are not passed on to the OpenTP1 of the server UAP.
3. Do not specify the same buffer area for the input parameter (in) and the response from the service function (out).
4. If DCRPC_NOREPLY is specified for flags, the following return values will not return:
   
   • Errors which never occur
     DCRPCER_REPLY_TOO_BIG
     DCRPCER_INVALID_REPLY
     
   • Errors which cannot be detected even though they could occur
     DCRPCER_NO_SUCH_SERVICE
     DCRPCER_SERVICE_CLOSED
     DCRPCER_SERVICE_TERMINATING
     DCRPCER_SYSERR_AT_SERVER
     DCRPCER_NO_BUFS_AT_SERVER
     DCRPCER_OLTF_INITIALIZING
     DCRPCER_SECCHK
     
   In addition, OpenTP1 does not output a message when an error occurs. If errors must be detected, consider specifying DCNOFLAGS for flags (synchronous-response-type RPC).
   
5. When a service group is requested by the function dc_rpc_call() from a transaction, an SPP is occupied until the transaction terminates. When the same service is requested more than once by the function dc_rpc_call() from one transaction, do the following:
   
   • Re-estimate the values specified for the balance_count operand and parallel_count operand in the user service definition according to the number of usages.
   • Request a service by using chained RPCs so that the number of processes will not increase.
   If the values specified for the balance_count operand and parallel_count operand are incorrect, the transaction will shut down abnormally and a deadlock may occur.
   
6. When an asynchronous response-type RPC is used, the server UAP may be occupied until the function dc_rpc_poll_any_replies() receives all asynchronous responses or the function dc_rpc_discard_further_replies() rejects the receiving of asynchronous responses. This may occur regardless of whether it is a transaction or not. Increase the number of resident processes according to how many times an asynchronous response-type RPC is used.
   An asynchronous response-type RPC requires many resources in addition to occupying the server UAP. To prevent responses from degrading performance of UAP processing and activation of unnecessary SPPs, ensure that responses are received or the receiving of responses is rejected after the function dc_rpc_call() of an asynchronous response-type RPC is used.
   
7. When a response is received after an asynchronous response-type RPC is used twice or more consecutively, specify a separate response storage area (out) for each. If the same area is specified, a correct response cannot be received since the second and succeeding responses override the area.
8. The server UAP (SPP) that requested a service using an asynchronous response-type RPC sends a response soon after the service function is executed, regardless of whether the process that executed the asynchronous response-type RPC issued the function dc_rpc_poll_any_replies. If the same asynchronous response-type RPC is executed numerous times simultaneously without the function dc_rpc_poll_any_replies being issued, the response sent by the SPP may stay in the TCP/IP buffer and the SPP may fail to send a response. If the SPP fails to send a response, no response can be received from the SPP even if the source of the asynchronous response-type RPC issues the function dc_rpc_poll_any_replies.
9. If a large number of asynchronous response-type RPCs or non-response type RPCs having the transaction attribute are executed, messages about transactions sent by the SPP can no longer be received. In this case, the transactions may roll back.

Specifying a service group name with domain qualification enables requesting an OpenTP1 service in the DNS domain. Specify the service group name suffixed by an at mark (@) and the DNS domain name for domain qualification.

Notes on requesting a service with domain qualification

1. To request a service with domain qualification, specify DCRPC_DOMAIN for flags of the function dc_rpc_call(). If the service group name with domain qualification is specified without DCRPC_DOMAIN, the function dc_rpc_call() returns with an error, giving the return value DCRPCER_NO_SUCH_SERVICE_GROUP.
2. If an RPC with domain qualification is used, a transaction cannot be extended even if the process which called the function dc_rpc_call() is a transaction. Therefore, to request a service with domain qualification from a transaction, specify DCRPC_NOTRAN for flags not to extend the transaction. When the local domain is specified for the domain name, the transaction also cannot be extended.
3. When an RPC with domain qualification is used, a service request can be addressed only to a server that receives requests from queue, rather than a server that receives requests from socket.
4. A service request with domain qualification is sent to the domain-alternate schedule service which is activated on the host registered with the namdomainsetup command. Obtain the port number of the domain-alternate schedule service from /etc/services. If an error occurs while transferring the service request and multiple host names are registered with the namdomainsetup command, transfer of the service request is attempted to other hosts sequentially. Even if the RPC with domain qualification terminates normally, an error may occur during transfer to the domain-alternate schedule service.

Preparation for requesting a service with domain qualification

Perform the following environment setup for an RPC with domain qualification:

1. Register the name of the host on which the domain alternate schedule service is activated in the DNS domain data file by using the namdomainsetup command.
2. Define the port number of the domain alternate schedule service in /etc/services of the host on which the OpenTP1 which requests a service with domain qualification is activated as follows:
   

   OpenTP1scd port-number/tcp

3. Specify the well-known port of the domain alternate schedule service for the scd_port operand in the schedule service definition for the OpenTP1 which activates the domain-alternate schedule service.

Assume that you want to perform a transactional RPC on an OpenTP1 system other than the domain specified in the all_node clause of the system common definition. In this case, you must ensure that the node identifiers (node_id clause of the system common definition) of all OpenTP1 systems in the local domain and remote domain are unique. In addition, all the OpenTP1 systems must be version 03-02 or later. If these conditions are not met, the transaction may not recover properly.