ANSI C, C++

#include <dcrpc.h>
int 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)

K&R C

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

The function dc_rpc_call_to() requests an SPP service. Like the function dc_rpc_call(), this function sets a service group name and service name as arguments. In addition, it sets the DCRPC_BINDING_TBL structure in which a host name or node identifier is specified as an argument. The host name or node identifier specified in the DCRPC_BINDING_TBL structure is used as a search key that designates the requested service. This function requests a service from the service function that matches the setting.

However, you cannot add a domain qualification when requesting a service. In all other respects, this function is the same as the function dc_rpc_call().

TP1/Extension 1 must be installed before you can use this facility. Note that operation will be unpredictable if you run the facility while TP1/Extension 1 is not installed.

direction

Specify the address of the DCRPC_BINDING_TBL structure that is to store the search key that designates the requested service. The search key is either a host name or node identifier.

The following shows the format of the DCRPC_BINDING_TBL structure.

struct DCRPC_BINDING_TBL {
    char *nid;           /*Storage address for node identifier*/
    char *hostnm;        /*Storage address for host name*/
    short portno;        /*Port number*/
    short filler1;       /*Spare status*/
    DCLONG flags;        /*Attribute*/
    DCLONG filler2[4];   /*Spare status*/
};

• nid
  Specify the address of the area that stores the node identifier of the requested service node when you want to set a node identifier as the search key. End the character string with a null character. The null character is not counted in the length of the character string.
  The node identifier must be the name specified for node_id in the system common definition. The host name of the requested service node must exist in the global domain^# (a collection of node names specified for the all_node operand of the system common definition).
  When you do not intend to set a node identifier as the search key, specify address 0 for nid.
  
• hostnm
  Specify the address of the area that stores the host name of the requested service node when you want to set a host name as the search key. You can specify a character string containing between 1 and 255 characters as the host name. This character string can consist of alphanumeric characters and special symbols, the period, and the hyphen (except in the IP address format). End the character string with a null character. The null character is not counted in the length of the character string. The name of the specified host is one that can be mapped to an IP address with the /etc/hosts file or DNS.
  It is optional whether the host name of the requested service node is specified in the global domain^# (a collection of node names specified for the all_node operand of the system common definition).
  When you do not intend to set a host name as the search key, specify address 0 for hostnm.
  
• portno
  Specify the port number (the value specified for name_port in the system common definition) of the name service of the requested service node when you want to set a host name as the search key. The value specified for portno is valid only when DCRPC_NAMPORT is specified for flags in the DCRPC_BINDING_TBL structure. If you specify 0 for portno or specify DCNOFLAGS for flags in the DCRPC_BINDING_TBL structure, the port number of the name service at the request source and the port number of the name service at the requested service must match.
  When you set a node identifier as the search key, the value specified for portno is ignored.
  
• flags
  Specify DCNOFLAGS.
  If you specified a value for portno, specify DCRPC_NAMPORT.
  The areas filler1 and filler2 were created to allow expandability, so you need not set values for these areas. (Do not use the member names filler1 and filler2.)
  

#

This global domain means a group of the following node names.

When N is specified in the name_domain_file_use operand in the system common definition:

The global domain is a group of node names specified in the all_node and all_node_ex operands in the system common definition.

When Y is specified in the name_domain_file_use operand in the system common definition:

The global domain is a group of node names specified in the domain definition files. The domain definition files are stored under the following directories:

• Domain definition file for all_node
  $DCCONFPATH/dcnamnd-directory
  
• Domain definition file for all_node_ex
  $DCCONFPATH/dcnamndex-directory
  

You can create the DCRPC_BINDING_TBL structure to be specified for direction in the function dc_rpc_call_to() by using the DCRPC_BINDTBL_SET function or DCRPC_DIRECT_SCHEDULE function. For details, see DCRPC_BINDTBL_SET and DCRPC_DIRECT_SCHEDULE.

group

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

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 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. Note that 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]

DCNOFLAGS

Synchronous response-type RPC

DCRPC_NOWAIT

Asynchronous response-type RPC

DCRPC_NOREPLY

Non-response-type RPC

DCRPC_CHAINED

Chained RPC

DCRPC_TPNOTRAN

Specify this option to prevent processing requested from a transaction by a service request from being handled as a transaction. Alternatively, specify this option when you want to use the DCRPC_DIRECT_SCHEDULE function to create the DCRPC_BINDING_TBL structure, and to request a service from a user server with the non-transaction attribute. Here, a user server has the non-transaction attribute when N is specified for atomic_update in the user service definition or Y is set for jnl_fileless_option in the system common definition.

This value must be ORed with the type of RPC.

Example:

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

DCNOFLAGS|DCRPC_TPNOTRAN

out

The response set by the service function is returned.

out_len

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

See the return values for the function dc_rpc_call().

The return values for the function dc_rpc_call_to() include the following causes in addition to those given in the return values for the function dc_rpc_call().

#

This global domain means a group of the following node names.

When N is specified in the name_domain_file_use operand in the system common definition:

The global domain is a group of node names specified in the all_node and all_node_ex operands in the system common definition.

When Y is specified in the name_domain_file_use operand in the system common definition:

The global domain is a group of node names specified in the domain definition files. The domain definition files are stored under the following directories:

• Domain definition file for all_node
  $DCCONFPATH/dcnamnd-directory
  
• Domain definition file for all_node_ex
  $DCCONFPATH/dcnamndex-directory
  

See the items for the function dc_rpc_call().

1. Take care when specifying a value for hostnm in the DCRPC_BINDING_TBL structure, hostnm in the DCRPC_BINDING_SET function, or hostnm in the DCRPC_DIRECT_SCHEDULE function under a multi-homed host mode in which multiple LAN adaptors are connected within a single machine. In such a case, do not specify any host name on the local machine other than the host name specified for my_host in the system common definition. If you specify any other host name, _operation will be unpredictable.
2. If you specify both a host name and node identifier in the DCRPC_BINDING_TBL structure, the host name is valid and the node identifier is ignored.
3. If you specify 0 for both the host name and node identifier in the DCRPC_BINDING_TBL structure, operation is exactly the same as for the function dc_rpc_call().
4. To request a service directly from a user server managed by the schedule service, be sure to create the DCRPC_BINDING_TBL structure using the DCRPC_DIRECT_SCHEDULE function.
5. If you create the DCRPC_BINDING_TBL structure using the DCRPC_DIRECT_SCHEDULE function and request a service from a user server that receives requests from socket (socket is specified for receive_from in the user service definition), the function dc_rpc_call_to() returns with the error DCRPCER_SERVICE_NOT_UP.
6. This note applies when you call the function dc_rpc_call_to() with the DCRPC_BINDING_TBL structure created by the function DCRPC_DIRECT_SCHEDULE specified in order to request a service from a user server with the non-transaction attribute. Here, a user server has the non-transaction attribute when N is specified for the atomic_update operand in the user service definition or Y is specified for the jnl_fileless_option operand in the system common definition. In this case, you must specify a disjunction with DCRPC_TPNOTRAN in the flags argument of the function dc_rpc_call_to(). Failure to specify disjunction causes the function dc_rpc_call_to() to return the error DCRPCER_TRNCHK_EXTEND.
7. If you call the function dc_rpc_call_to() in which you specified a DCRPC_BINDING_TBL structure created using the DCRPC_DIRECT_SCHEDULE function, OpenTP1 running the requested service must be Version 03-02 or later. Operation is not guaranteed if the version is earlier than 03-02.
8. You cannot issue an RPC that has a domain qualification. Specifying DCRPC_DOMAIN for flags in the function dc_rpc_call_to() causes the function to return the error DCRPCER_INVALID_ARGS.
9. In the following case, the function dc_rpc_call_to() may return the error DCRPCER_TIMED_OUT: You used a host name as the search key when calling the function dc_rpc_call_to() from a service group on a node that is not specified in the all_node operand of the system common definition, and subsequently you stopped or restarted OpenTP1 running on the called node and again called the function dc_rpc_call_to() from the same service group using a host name as the search key.
10. When the function dc_rpc_call_to() is requested by specifying the DCRPC_BINDING_TBL structure that was created with the DCRPC_DIRECT_SCHEDULE function for direction of the function dc_rpc_call_to(), the rpc_retry operand becomes invalid.
11. The performance verification trace can be obtained when the function dc_rpc_call_to() is requested by specifying the DCRPC_BINDING_TBL structure that was created with the DCRPC_DIRECT_SCHEDULE function for direction of the function dc_rpc_call_to(), but it cannot be linked to the information about the UAP performance verification trace in the request destination. The serial number of the performance verification trace obtained with the client UAP is not inherited in the server UAP.