(a) TP1/Client/W

_s version of the function

 
#include <dcvrpc.h>
DCLONG dc_rpc_call_to_s(
  DCCLT_ID cltid, struct DCRPC_BINDING_TBL *direction,
  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>
DCLONG dc_rpc_call_to(
       struct DCRPC_BINDING_TBL *direction,
       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_to_s(
  DCCLT_ID cltid, struct DCRPC_BINDING_TBL CLTFAR *direction,
  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>
DCLONG dc_rpc_call_to(
  struct DCRPC_BINDING_TBL CLTFAR *direction, char CLTFAR *group,
  char CLTFAR *service, char CLTFAR *in, DCULONG CLTFAR *in_len,
  char CLTFAR *out, DCULONG CLTFAR *out_len, DCLONG flags)
 

In the same way as the dc_rpc_call_s function, the dc_rpc_call_to_s function requests an SPP service. The dc_rpc_call_to_s function uses the host name, in addition to the service group name and service name, as a search key for the service function to restrict the nodes to which service requests are sent.

Before issuing the dc_rpc_call_to_s function, you must issue DCRPC_DIRECT_SCHEDULE() to create a DCRPC_BINDING_TBL structure. In the direction argument, specify the address of the DCRPC_BINDING_TBL structure. Other interfaces are the same as those for the dc_rpc_call_s function.

• cltid
  Specify the client ID acquired by using the dc_clt_cltin_s function.
  
• direction
  Specify the address of the DCRPC_BINDING_TBL structure.
  Before issuing the dc_rpc_call_to or dc_rpc_call_to_s function, you must issue DCRPC_DIRECT_SCHEDULE() to specify a value in the DCRPC_BINDING_TBL structure.
  
• group
  Specify the service group name. The service group name can have up to 31 characters and must end with a NULL character.
  
• service
  Specify the service name. The service name can have up to 31 characters and must end with a NULL character.
  
• in
  Specify the input parameter for the service.
  
• in_len
  Specify the length of the input parameter for the service. You can specify a value in the range from 1 to 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
  Specify the address of the area for containing the service response.
  
• out_len
  Specify the length of the service response. You can specify a value in the range from 1 to 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
  Specify the RPC mode.
  

  DCNOFLAGS

  Synchronous-response RPC

  DCRPC_NOREPLY

  Asynchronous-response RPC

  When DCNOFLAGS is specified in flags, the dc_rpc_call_to_s function does not return until the function receives a response or a timeout (specified with DCWATCHTIM in the client environment definition) occurs. However, if the SPP from which you requested a service aborts, the function immediately returns an error.
  In this case, the return value of this function differs depending on the timeout specified with DCWATCHTIM:
  
  • When DCWATCHTIM is 1 to 65535, DCRPCER_TIMED_OUT is returned.
  • When DCWATCHTIM is 0 (no timeout), DCRPCER_SERVICE_NOT_UP is returned.
  You can also change the timeout during execution of the CUP by executing the dc_rpc_set_watch_time_s function before executing the dc_rpc_call_to_s function.
  When DCRPC_NOREPLY is specified in flags, the function assumes that the requested service does not return a response. Therefore, the dc_rpc_call_to_s function immediately returns without waiting for the service to terminate. The CUP is not notified that the service function was successfully executed.
  

• out
  The response of the service specified in the service function is returned. This value is not returned when DCRPC_NOREPLY is specified in the flags argument.
  
• out_len
  The length of the response specified in the service function is returned. 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	An invalid value is specified for an argument.
DCRPCER_PROTO	-2402	The dc_rpc_open_s function has not been executed. Alternatively, this function was issued while a permanent connection was being established or was issued within a transaction.
DCRPCER_NO_BUFS	-2404	A sufficient amount of buffer space could not be secured or resources became insufficient.
DCRPCER_NET_DOWN	-2406	Network error
DCRPCER_TIMED_OUT	-2407	A timeout occurred during processing of the dc_rpc_call_to_s function. Alternatively, the service-requested SPP terminated abnormally before completing the processing.
DCRPCER_MESSAGE_TOO_BIG	-2408	The input parameter length exceeds the maximum.
DCRPCER_REPLY_TOO_BIG	-2409	The length of the returned response exceeds the area provided by the CUP.
DCRPCER_NO_SUCH_SERVICE_GROUP	-2410	An undefined service group name was specified. Alternatively, a service request was sent to a user server that receives requests from socket (receive_from=socket is specified in the user service definition). Alternatively, the SPP requested to provide a service was not started when N was specified for DCCLTONLYTHISNODE of the client environment definition.
DCRPCER_NO_SUCH_SERVICE	-2411	An undefined service name is specified.
DCRPCER_SERVICE_CLOSED	-2412	The service group containing the specified service is shut down.
DCRPCER_SERVICE_TERMINATING	-2413	The specified service is terminating.
DCRPCER_SERVICE_NOT_UP	-2414	The SPP requested to provide a service was not started when Y was specified for DCCLTONLYTHISNODE of the client environment definition. Alternatively, when 0 is specified for DCWATCHTIM in the client environment definition, the SPP terminated abnormally before completing the processing.
DCRPCER_OLTF_NOT_UP	-2415	OpenTP1 is not running on the node that has the specified service.
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	The length of the response returned to OpenTP1 from the service function is not in the range from 1 to the value of DCRPC_MAX_MESSAGE_SIZE#.
DCRPCER_OLTF_INITIALIZING	-2420	OpenTP1 is starting on the node to which the service request was sent.
DCRPCER_TRNCHK	-2427	The version of OpenTP1 on the node used for load balancing is too old to execute the inter-node load balancing facility. This value is returned only when a service request has been issued to the SPPs using the inter-node load balancing facility.
DCRPCER_TESTMODE	-2466	A service request was issued to an SPP for which test_mode=no was specified in the user service definition.
DCRPCER_SECCHK	-2470	The service-requested SPP is protected by the security facility. The UAP that called the dc_rpc_call_to_s function is not authorized to access the server UAP.
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 if the specification is omitted, DCRPCER_TIMED_OUT or DCRPCER_SERVICE_NOT_UP is returned as the return value.
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).

• If you use the dc_rpc_call_to_s function to send a service request to a user server that receives requests from a socket (receive_from=socket is specified in the user service definition), the function returns a DCRPCER_NO_SUCH_SERVICE_GROUP error.
• The version of OpenTP1 in the destination of a service request must be 03-02 or later. The operation is not ensured if the version is earlier than 03-02.
• If the dc_rpc_call_to_s function is issued while permanent connection is being established or issued within the scope of the transaction, the function returns a DCRPCER_PROTO error.
• The values specified in DCCACHE and DCCLTCACHE in the client environment definition do not take effect.
• The dc_rpc_call_to_s function sends a request directly to the schedule service. Therefore, the value specified in DCCLTLOADBALANCE in the client environment definition does not take effect.
• When the dc_rpc_call_to_s function is issued, DCCLTSERVICEGROUPLIST in the client environment definition is not referenced.
• When the dc_rpc_call_to_s function is issued, DCSCDDIRECT, DCSCDPORT, DCSCDMULTI, and DCSCDMULTICOUNT in the client environment definition are not referenced.
• In the client environment definition, when DCCLTONLYTHISNODE is set to N or omitted, the load balancing is performed with weights assigned to the node that accepts the service request. When DCCLTONLYTHISNODE is set to Y, load balancing is not performed.
• If the host name of the node to which to send service requests is incorrect, the dc_rpc_call_to_s function returns a DCRPCER_INVALID_ARGS error.
• The behavior of the dc_rpc_call_to_s function differs depending on the value of DCCLTONLYTHISNODE in the client environment definition, as shown below.
  

  Status of SPP		Value of DCCLTONLYTHISNODE in the client environment definition
  Specified node	Other node	N or omitted	Y
  When the SPPs in these nodes have equal loads		The job is assigned to the SPP in the specified node.	The job is assigned to the SPP in the specified node.
  When the SPP in the specified node has a heavier load than the SPP in the other node		The job is assigned to the SPP in the other node.	The job is assigned to the SPP in the specified node.
  Active	Shut down (acceptable)	Which SPP is assigned the job depends on the load level of the SPP in the specified node. When the SPP in the specified node does not have a heavy load, the job is assigned to the SPP in the specified node. If the specified node does have a heavy load, the job is assigned to the SPP in the other node.	The job is assigned to the SPP in the specified node.
  Shut down (acceptable)	Active	Which SPP is assigned the job depends on the load level of the SPP in the other node. When the SPP in the other node does not have a heavy load, the job is assigned to the SPP in the other node. If the other node does have a heavy load, the job is assigned to the SPP in the specified node.	The job is assigned to the SPP in the specified node.
  Shut down (unacceptable)	Active	The job is assigned to the SPP in the other node.	The function returns a DCRPCER_SERVICE_CLOSED error.
  Inactive	Active	The job is assigned to the SPP in the other node.	The function returns a DCRPCER_SERVICE_NOT_UP error.
  Inactive	Inactive	The function returns a DCRPCER_NO_SUCH_SERVICE_GROUP error.	The function returns a DCRPCER_SERVICE_NOT_UP error.