(a) TP1/Client/W

_s version of the function

 
#include <dcvrpc.h>
DCLONG dc_rpc_call_s(DCCLT_ID cltid, char *group,
                     char *service, char *in,
                     DCULONG *in_len, char *out,
                     DCULONG *out_len, DCLONG flags)
 

Non-_s version of the function

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

(b) TP1/Client/P

_s version of the function

 
#include <dcvrpc.h>
DCLONG dc_rpc_call_s(DCCLT_ID cltid, char CLTFAR *group,
                  char CLTFAR *service, char CLTFAR *in,
                  DCULONG CLTFAR *in_len, char CLTFAR *out,
                  DCULONG CLTFAR *out_len, DCLONG flags)
 

Non-_s version of the function

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

Requests an SPP service. Calls a service function, specifying the service group name and service name, and receives a response from the service function.

OpenTP1 must be running on the server UAP node to which the service request is sent. The dc_rpc_call_s function returns a DCRPCER_NET_DOWN, DCRPCER_OLTF_NOT_UP, or DCRPCER_OLTF_INITIALIZING error if OpenTP1 is not running (or is initializing).

The function returns a DCRPCER_SERVICE_CLOSED error if the target service group is shut down when the dc_rpc_call_s function is executed.

If the target service group is terminating or has been terminated by commands such as the dcsvstop command, the function returns a DCRPCER_SERVICE_TERMINATING, DCRPCER_SERVICE_CLOSED, or DCRPCER_NO_SUCH_SERVICE_GROUP error. The actual value returned depends on the timing of the dc_rpc_call_s function call.

A socket-receiving type server concurrently controls messages by specifying max_socket_msg and max_socket_msglen in the user service definition. This sometimes prevents the user from receiving a service request. If a service request cannot be received, the dc_rpc_call_s function returns with a DCRPCER_SERVER_BUSY error. If this value is returned, the CUP may make a service request by reexecuting the process after a certain time.

To communicate with XDM/DCCM3 in the normal communication mode, specify the host name and port number of the XDM/DCCM3 logical terminal in DCCLTSERVICEGROUPLIST in the client environment definition, and then execute the dc_rpc_call_s function.

(a) Setting arguments

The CUP reserves an area (out) for the service function response. The CUP also sets the following values for the dc_rpc_call_s function:

• Input parameter (in)
• Input parameter length (in_len)
• Response length (out_len)

The input parameter, input parameter length, and response length values set for the dc_rpc_call_s function by the CUP are transferred to the service function without modification. The response length is ignored if the function requests a no-response type service.

The maximum values for in_len and out_len are defined with DCRPC_MAX_MESSAGE_SIZE^# in the dcvrpc.h header file.

# If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

(b) Referencing arguments

The following values are available after the completion of service function processing.

• Service function response (out)
• Service function response length (out_len)

out_len contains the actual length of the response returned from the service function.

For synchronous response type RPCs (DCNOFLAGS set in flags), out and out_len can be referenced after the dc_rpc_call_s function returns. For no-response type RPCs (DCRPC_NOREPLY set in flags), out and out_len cannot be referenced. Also, out and out_len cannot be referenced when the dc_rpc_call or function returns an error.

The function returns a DCRPCER_REPLY_TOO_BIG error if the response is larger than the response area (out) reserved by the CUP.

• cltid
  Set the client ID received by the dc_clt_cltin_s function.
  
• group
  Set the service group name as a null-terminated character string up to 31 bytes in length.
  
• service
  Set the service name as a null-terminated character string up to 31 bytes in length.
  
• in
  Set the service input parameter.
  
• in_len
  Set the length of the service input parameter as a value between 1 and DCRPC_MAX_MESSAGE_SIZE^#.
  

  # If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• out
  Set the area for receiving the service response.
  
• out_len
  Set the length of the service response as a value between 1 and DCRPC_MAX_MESSAGE_SIZE^#.
  

  # If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• flags
  Set the RPC type.
  

  DCNOFLAGS

  Synchronous response type RPC

  DCRPC_NOREPLY

  No-response type RPC

  DCRPC_CHAINED

  Chained RPC

  If DCNOFLAGS or DCRPC_CHAINED is set, the dc_rpc_call_s function does not return until a response is received or until a response timeout error occurs. The response timeout period is specified by DCWATCHTIM in the client environment definition. When the request destination SPP aborts, the function immediately returns an error. The error accompanies either of the following values depending on the response wait time specified for DCWATCHTIM.
  
  • DCWATCHTIM = 1-65535: DCRPCER_TIMED_OUT
  • DCWATCHTIM = 0 (wait indefinitely): DCRPCER_SERVICE_NOT_UP
  You can change the response wait time while the CUP is executing. To do this, execute the dc_rpc_set_watch_time_s function before executing the dc_rpc_call_s function.
  You can specify DCRPC_CHAINED only when a transaction or permanent connection is active.
  If DCRPC_NOREPLY is set, the requested service is treated as a no-response type service. The dc_rpc_call_s function returns immediately without waiting for the service to complete execution. The response (out) and response length (out_len) cannot be referenced. Also, the CUP cannot determine whether the service function actually executed or not.
  An RPC from transaction processing can be changed to a service request for no-transaction. If DCRPC_TPNOTRAN is specified in the RPC type parameter, the service request of the applicable dc_rpc_call_s function becomes free from transaction processing.
  Example:
  

   
  DCNOFLAGS|DCRPC_TPNOTRAN
   

  You can specify this service request only in the transaction processing. If you specify it outside the transaction, the dc_rpc_call_s function returns a DCRPCER_INVALID_ARGS error.
  

• out
  The response set by the service function. This value is not returned when DCRPC_NOREPLY is specified in the flags argument.
  
• out_len
  The length of the response set by the service function. This value is not returned when DCRPC_NOREPLY is specified in the flags argument.
  

Return Value	Value (decimal)	Meaning
DC_OK	0	Normal termination
DCRPCER_INVALID_ARGS	-2401	Invalid argument
DCRPCER_PROTO	-2402	The dc_rpc_open_s function has not been executed.
DCRPCER_NO_BUFS	-2404	A sufficient amount of buffer could not be secured or resources became insufficient.
DCRPCER_NET_DOWN	-2406	Network error
DCRPCER_TIMED_OUT	-2407	The dc_rpc_call_s function processing timeout. Alternatively the service-requesting SPP aborted before completion of the processing.
DCRPCER_MESSAGE_TOO_BIG	-2408	Input parameter length exceeds the maximum.
DCRPCER_REPLY_TOO_BIG	-2409	Returned response length exceeds the area provided by the CUP.
DCRPCER_NO_SUCH_SERVICE_GROUP	-2410	Possible causes are as follows: An undefined service group name was specified. Although TP1/Client needs to communicate with TP1/Server, Y is specified for DCCLTNOSERVER of the client environment definition.
DCRPCER_NO_SUCH_SERVICE	-2411	An undefined service name was specified.
DCRPCER_SERVICE_CLOSED	-2412	Service group containing the specified service is shut down.
DCRPCER_SERVICE_TERMINATING	-2413	Specified service is terminating.
DCRPCER_SERVICE_NOT_UP	-2414	The SPP requested to provide a service was not started, or terminated abnormally before completing the processing. This value is returned when 0 is specified for DCWATCHTIM in the client environment definition (infinite response wait time is specified).
DCRPCER_OLTF_NOT_UP	-2415	OpenTP1 is not running on the specified service node. Alternatively, communication is impossible because the TP1/Client is disconnected from the server during a transaction.
DCRPCER_SYSERR_AT_SERVER	-2416	A system error occurred for the specified service.
DCRPCER_NO_BUFS_AT_SERVER	-2417	Insufficient memory for the specified service
DCRPCER_SYSERR	-2418	System error
DCRPCER_INVALID_REPLY	-2419	Response length returned to OpenTP1 from the service function is not within the range: 1 to DCRPC_MAX_MESSAGE_SIZE#.
DCRPCER_OLTF_INITIALIZING	-2420	OpenTP1 is initializing on the specified service node.
DCRPCER_NO_BUFS_RB	-2423	Insufficient memory
DCRPCER_SYSERR_RB	-2424	System error
DCRPCER_SYSERR_AT_SERVER_RB	-2425	A system error occurred for the specified service.
DCRPCER_REPLY_TOO_BIG_RB	-2426	Returned response cannot be contained in the area allocated by the CUP.
DCRPCER_TRNCHK	-2427	Transaction attribute mismatch is found among SPPs in the environment of the inter-node load balancing function. Alternatively, the version of OpenTP1 on the node used for load balancing is too old to execute the inter-node load balancing function. The return value comes only when a service request is made to the SPPs using the inter-node load balancing function.
DCRPCER_CONNFREE	-2442	The permanent connection has been released.
DCRPCER_PORT_IN_USE	-2547	The specified port number is in use, or port numbers that can be assigned automatically by the operating system are insufficient.
DCRPCER_SERVER_BUSY	-2456	The target server that receives requests from socket cannot receive a service request.
DCRPCER_TESTMODE	-2466	A service request was issued to an SPP for which test_mode=no was specified in the user service definition in an environment where DCUTOKEY was specified in the client environment definition. Alternatively, a function was called in an environment where all of the following conditions existed: DCUTOKEY was specified in the client environment definition. A permanent connection with the CUP executing process was being established. The service request was issued outside the transaction. A service request was issued to an SPP for which a value other than test_mode=no was specified in the user service definition.
DCRPCER_NOT_TRN_EXTEND	-2467	After a chained RPC has been used for transaction processing, the dc_rpc_call_s function that has DCRPC_TPNORTAN set for flags issues a service request.
DCRPCER_SECCHK	-2470	The service-requested SPP is protected by the security feature. The UAP that called the dc_rpc_call_s function has no access privilege for the server UAP.
DCRPCER_TRNCHK_EXTEND	-2472	Transaction branch cannot be started because the number of transaction branches that can be started concurrently has been exceeded, or, because the maximum number of child transaction branches that can be started from one transaction branch has been exceeded. Alternatively, DCRPC_TPNOTRAN is not set at flags in a service request qualified by a domain in a transaction.
DCRPCER_SERVICE_TERMINATED	-2478	The SPP requested to provide a service terminated abnormally before completing the processing. This value is returned when 00000001 is specified for DCEXTENDFUNCTION in the client environment definition. If 00000000 is specified or the specification is omitted, DCRPCER_TIMED_OUT or DCRPCER_SERVICE_NOT_UP returns as the return value.
DCRPCER_VERSION_CHECK	-2479	Since the version of service-requested TP1/Server Base is old (before 03-03), the data compression cannot be used. This return value returns when the service is requested within the range of the transaction.
DCCLTER_INVALID_CLTID	-2544	The client ID specified in cltid differs from the client ID received by the dc_clt_cltin_s function.
DCRPCER_PORT_IN_USE	-2547	The specified port number is in use. Alternatively, port numbers that can be assigned automatically by the operating system are insufficient.

# If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• Do not specify the same buffer for the input parameters (in) and service function response (out).
• None of the following return values are returned if flags is set to DCRPC_NOREPLY.
  Errors that never occur:
  DCRPCER_REPLY_TOO_BIG
  DCRPCER_INVALID_REPLY
  Errors that cannot be detected:
  DCRPCER_NO_SUCH_SERVICE
  DCRPCER_SERVICE_CLOSED
  DCRPCER_SERVICE_TERMINATING
  DCRPCER_SYSERR_AT_SERVER
  DCRPCER_NO_BUFS_AT_SERVER
  DCRPCER_OLTF_INITIALIZING
  
• The possible factor for the return value DCRPCER_TIMED_OUT is that:
  The maximum response-wait time specified in the client environment definition is insufficient;
  The service function issued by the SPP requested to initiate service terminated abnormally;
  An error occurred with the node at which the SPP requested to initiate service exists; or
  The service-requesting SPP aborted before completion of the processing.
  A network error occurred.
  If any of the above problems occurs, the transaction started from the SPP requested to initiate service may have been committed and the database updated. Check whether the database has been updated.
  
• If the CUP issued the dc_rpc_call_s function following the dc_trn_begin_s function and one of the following return values was returned, then issue a rollback request function as necessary:
  DCRPCER_TIMED_OUT
  DCRPCER_NO_SUCH_SERVICE
  DCRPCER_NO_BUFS_AT_SERVER
  DCRPCER_INVALID_REPLY
  DCRPCER_NO_BUFS_RB
  DCRPCER_SYSERR_RB
  DCRPCER_SYSERR_AT_SERVER_RB
  DCRPCER_REPLY_TOO_BIG_RB