RPC - Remote-Procedure-Call Settings

This Natural profile parameter is used to control the handling of Natural RPC. It corresponds to the macro NTRPC in the Natural parameter module.

The following topics are covered below:

• RPC Parameter Syntax

• NTRPC Macro Syntax

• Keyword Subparameters for Client and Server

• Keyword Subparameters for Client Only

• Keyword Subparameters for Server Only

• RPC Parameter Example

• NTRPC Macro Example

RPC Parameter Syntax

The parameter syntax of RPC is as follows:

For names and values of keyword-subparameter, see Keyword Subparameters for Client and Server, Keyword Subparameters for Client Only and Keyword Subparameters for Server Only.

NTRPC Macro Syntax

On the client side, the syntax of the NTRPC macro in the Natural parameter module is as follows:

         NTRPC ACIVERS=value,                                          *
               AUTORPC=value,                                          *
               COMPR=value,                                            *
               CPRPC=value,                                            *
               DFS=value,                                              *
               MAXBUFF=value,                                          *
               RDS=value,                                              *
               RPCSDIR=value,                                          *
               RPCSIZE=value,                                          *
               SERVER=value,                                           *
               TIMEOUT=value,                                          *
               TRYALT=value

On the server side, the syntax of the NTRPC macro in the Natural parameter module is as follows:

         NTRPC ACIVERS=value,                                          *
               CPRPC=value,                                            *
               LOGONRQ=value,                                          *
               MAXBUFF=value,                                          *
               NTASKS=value,                                           *
               RPCSIZE=value,                                          *
               RPCUCT=value,                                           *
               SERVER=value,                                           *
               SRVCMIT=value,                                          *
               SRVNAME=value,                                          *
               SRVNODE=value,                                          *
               SRVRTRY=value,                                          *
               SRVTERM=value,                                          *
               SRVUSER=value,                                          *
               SRVWAIT=value,                                          *
               TRACE=value,                                            *
               TRANSP=value

See Keyword Subparameters for Client and Server, Keyword Subparameters for Client Only and Keyword Subparameters for Server Only.

Keyword Subparameters for Client and Server

The following keyword subparameters are available for both client and server:

ACIVERS | CPRPC | MAXBUFF | RPCSIZE | SERVER

ACIVERS - Define API Version for Use with EntireX Broker ACI

This keyword subparameter is obsolete and ignored on z/OS and z/VSE.

ACIVERS=value specifies the API version to be used for the ACI functions of the EntireX Broker.

The EntireX Broker stub in use as well as the called EntireX Broker must support the API version defined here. Refer to the EntireX documentation for the supported API versions. The setting of ACIVERS enables special features of the EntireX Broker, depending on the API version you are using. For details, see Setting Up an EntireX Broker Access in the Natural RPC (Remote Procedure Call) documentation.

On z/OS and z/VSE platforms, the highest API version supported by the used EntireX Broker stub and the called EntireX Broker are determined automatically.

CPRPC - Define Code Page Name

CPRPC=value specifies the name of the code page used by the EntireX Broker.

Notes:

1. For information on the EntireX Broker, refer to the section about Software AG's Internationalization in the EntireX Broker documentation.
2. See also Unicode and Code Page Support, Configuration and Administration of the Unicode/Code Page Environment and Profile Parameters and Macros.

MAXBUFF - Default Buffer Size

MAXBUFF=value specifies the default buffer sizes in a Natural RPC environment.

Notes:

1. On the server side, MAXBUFF determines the size of the buffer provided by the server to receive the client request and send back the result. The buffer must be large enough to hold the largest data area received by all client requests and all results sent back to the client. If the size of the buffer is too small for a request, a temporary buffer with the required size is allocated and used for this request. For further information, see Interface Objects and Automatic RPC Execution in the Natural RPC (Remote Procedure Call) documentation.
2. On the client side, MAXBUFF determines the size of the buffer provided for the execution of Natural RPC calls. This buffer is used to build the client request and receive the result from the server. The buffer must be large enough to hold the largest data area received by all client requests and all results sent back to the client. If the size of the buffer is too small for a request, a temporary buffer with the required size is allocated and used for this request.
3. On the client side, you need not specify MAXBUFF if you use an interface object generated with the SYSRPC utility and COMPAT NONE, and if the parameters neither contain dynamic fields, nor X-arrays or group structures.
4. The size of the data exchanged between the client and server is provided by the Interface Object Generation function of the SYSRPC utility.

Dependency on Number of Parameters on Server Side

On the server side, the difference between RPCSIZE and MAXBUFF depends on the maximum number of parameters n in the PDA and can be calculated as follows:

• If group structures are present:

  MAXBUFF = RPCSIZE - (3 + n/10)

• If no group structures are present:

  MAXBUFF = RPCSIZE - (3 + n/20)

  Example:

  If n=100 and RPCSIZE=128, then MAXBUFF=120.

RPCSIZE - Size of Buffer Used by Natural RPC

RPCSIZE=value specifies the size of the buffer used by the Natural RPC.

SERVER - Start Natural Session as an RPC Server Session

SERVER=value specifies whether or not the Natural session will be started as an RPC server session.

Keyword Subparameters for Client Only

The following keyword subparameters are available for the client only:

AUTORPC | COMPR | DFS | RDS | RPCSDIR | TIMEOUT | TRYALT

AUTORPC - Automatic Natural RPC Execution

AUTORPC=value determines whether or not Natural RPC will automatically try to execute a subprogram remotely (on the server side) which was not found locally (on the client side).

COMPR - Set RPC Buffer Compression

COMPR=value sets the RPC buffer compression.

COMPR is effective only, if the automatic Natural RPC execution is used (AUTORPC=ON) and the CALLNAT is executed without an interface object. If an interface object is used, the compression has already been set during interface object generation. For details, see Using Compression in the Natural RPC (Remote Procedure Call) documentation.

DFS - Specify RPC Client's Default Server Address

DFS=value defines an RPC default server address by specifying up to 5 positional subparameters.

DFS determines the server name, the server node, the logon indicator and the transport protocol. The default server address will be used only if no appropriate server is found in the service directory. For further information, see Specifying RPC Server Addresses in the Natural RPC (Remote Procedure Call) documentation.

DFS Subparameter Syntax

The DFS syntax is as follows:

DFS=(server-name,server-node,logon-indicator,transport-protocol-name,service-directory-indicator)

Where:

Syntax Element	Value	Explanation
server-name	1 - 32 characters	Valid server name. See also the keyword subparameter SRVNAME. There is no default, the value must be specified.
server-node	1 - 192 characters	Node name. See also the keyword subparameter SRVNODE. There is no default, the value must be specified.
logon-indicator	L	The client initiates a Natural logon to the server with the library name of the current library on the client. On Windows platforms: Instead of specifying L, check the selection box.
	(blank)	Blank means that no server logon will be executed. If nothing is specified, this is the default.
transport-protocol-name	ACI	The transport protocol to be used. ACI is the only possible value and the default.
service-directory-indicator	SERVDIR	A service directory must be present before the keyword subparameter DFS is evaluated.
	NOSERVDIR	No service directory is used before the keyword subparameter DFS is evaluated; that is, a service directory needs not be available on the client side. If nothing is specified, SERVDIR is the default.

RDS - Define Remote Directory Server

RDS=value allows you to define up to 10 remote directory servers in a Natural RPC environment. For each remote directory server, you can specify up to 5 positional subparameters.

RDS Subparameter Syntax

The RDS syntax is as follows:

For 1 Server:

RDS=(server-name,server-node-name,subprogram,logon-indicator,transport-protocol-name)

For 2 to 10 Servers:

RDS=((server-name,server-node-name,subprogram,logon-indicator,transport-protocol-name)(server-name,server-node name,subprogram,logon-indicator,transport-protocol-name)...(server-name,server-node-name,subprogram,logon-indicator,transport-protocol-name))

Where:

Syntax Element	Value	Explanation
server-name	1 - 8 characters	The server name. There is no default, the value must be specified.
server-node-name	1 - 8 characters	The server node name. There is no default, the value must be specified.
subprogram	1 - 8 characters	The name of the subprogram titled CALLNAT, which is to be used as an interface. The default name is RDSSCDIR.
logon-indicator	L	The client initiates a Natural logon to the server with the library name of the current library on the client. On Windows platforms: Instead of specifying L, check the selection box.
	(blank)	Blank means that no server logon will be executed. If nothing is specified, this is the default.
transport-protocol-name	ACI	The name of the transport protocol to be used. ACI is the only possible value and the default.

RPCSDIR - Library for Service Directory

RPCSDIR=value specifies the name of the Natural library (or one of its steplibs) used by the RPC client at runtime.

RPCSDIR is evaluated by the SYSRPC utility functions Service Directory Maintenance and Server Command Execution.

TIMEOUT - Wait Time for RPC Server Response

TIMEOUT=value specifies the number of seconds the client is to wait for an RPC server response.

TRYALT - Try Alternative Server Address

TRYALT=value specifies whether an RPC client should try to execute an RPC request on an alternative server or not.

For further information, see Specifying RPC Server Addresses in the Natural RPC (Remote Procedure Call) documentation.

Keyword Subparameters for Server Only

The following keyword subparameters are available for the server only:

LOGONRQ | NTASKS | RPCUCT | SRVCMIT | SRVNAME | SRVNODE | SRVRTRY | SRVTERM | SRVUSER | SRVWAIT | TRACE | TRANSP

LOGONRQ - Logon for RPC Server Request Required

LOGONRQ=value determines whether or not logon data are required for an RPC server request.

NTASKS - Number of Server Tasks to be Started

NTASKS=value specifies the minimum number of server tasks to be started during server initialization, and the maximum number of server tasks that max be active at any time.

Notes:

1. NTASKS applies only to servers started in batch mode under z/OS or z/VSE, and to servers started by an RPC server front-end under CICS.
2. If the server has to handle a large number of client requests, you can use this keyword subparameter to improve the throughput by starting multiple (identically named) replicas of the same server task.
3. For further information, see the Natural RPC (Remote Procedure Call) documentation, and especially Considerations for Mainframe Natural RPC Servers with Replicas.

NTASKS Subparameter Syntax

Or:

Where:

RPCUCT - Translate Subprogram Name into Upper Case

RPCUCT=value specifies whether or not the Natural RPC server will translate the name of the remote CALLNAT subprogram to be executed into upper case.

SRVCMIT - Server Commit Time

SRVCMIT=value specifies the time at which a Natural RPC server automatically commits an RPC conversation or a non-conversational RPC request.

SRVNAME - Name of RPC Server

SRVNAME=value specifies the name of the RPC server, with which it registers on the node specified with the keyword subparameter SRVNODE.

CLASS=RPC, SERVICE=CALLNAT, SERVER=srvname

Example:

SRVNAME='PRODUCTION_SERVER'

SRVNODE - Name of Node

SRVNODE=value specifies the name of the node upon which an RPC server registers.

Examples:

The examples below are based on the EntireX notation.

SRVNODE=ETB001                             /* Entire Net-Work node */
SRVNODE=PCBROKER                           /* host name for a TCP/IP address */
SRVNODE=’157.189.160.95:1958:TCP’          /* TCP/IP address with port number */
SRVNODE=’tcpip://host.com:1958’            /* host name with port number */

Notes:

1. If a host name is used for the TCP/IP address, the name must either be known to your DNS server or it must be defined in the hosts file of your TCP/IP configuration.
2. If the port number is omitted, either a default port number is used by the EntireX Broker stub or a host name must be used, and the host name must be known to your DNS server or must be defined in the services file of your TCP/IP configuration.

SRVRTRY - Number of Connect/Reconnect Attempts

SRVRTRY=value specifies the number of attempts for an RPC server to connect/reconnect (REGISTER) to an EntireX Broker that is not active, and the wait time between two successive attempts.

SRVRTRY Subparameter Syntax

The SRVRTRY syntax is as follows:

SRVRTRY=(attempts,wait-time)

Or:

SRVRTRY=attempts

Note:
If only a value for attempts is specified, the parentheses may be omitted.

Where:

Syntax Element	Value	Explanation
attempts	0 or 1 - 2147483647	Number of attempts to connect/reconnect to an EntireX Broker that is not active (EntireX Broker message 02150148). Notes: The specification of attempts enables you to start a Natural RPC server before the required EntireX Broker has been started and to shutdown an EntireX Broker temporarily without implicitly terminating all Natural RPC servers. If the EntireX Broker is still not active after the number of attempts specified in attempts or if attempts is zero, the RPC server terminates.
wait-time	0 or 1 - 3600	Wait time in seconds between two successive attempts.

Examples:

1. RPC=(SRVRTRY=(20,10))

   Or:

            NTRPC SRVRTRY=(20,10)

   20 attempts with a wait time of 10 seconds between two successive attempts.

2. RPC=(SRVRTRY=500)

   Or:

            NTRPC SRVRTRY=500

   500 attempts with a wait time of 60 seconds between two successive attempts.

SRVTERM - Server Termination Event

SRVTERM=value specifies the event at which a Natural RPC server is automatically terminated.

SRVUSER - User ID for RPC Server Registry

SRVUSER=value specifies the user ID needed to register a Natural RPC server on the node specified with the keyword subparameter SVRNODE.

SRVWAIT - Wait Time of RPC Server

SRVWAIT=value specifies the number of seconds the server is to wait for a Natural RPC client request.

TRACE - Define Trace Level for Natural RPC Servers

TRACE=value activates the Natural RPC trace facility and determines the trace level to be used.

For further information, see Using the Server Trace Facility in the Natural RPC (Remote Procedure Call) documentation.

TRANSP - Server Transport Protocol

TRANSP=value specifies which server transport protocol is used. If ACI is used, you can additionally specify the transport method.

RPC Parameter Example

For the client:

RPC=(RPCSIZE=80,MAXBUFF=30,AUTORPC=ON,DFS=(MYSERV,MYNODE,,ACI))

For the server:

RPC=(RPCSIZE=80,MAXBUFF=30,SRVNAME=MYSERV,SRVNODE=MYNODE,SERVER=ON)

NTRPC Macro Example

For the client:

         NTRPC RPCSIZE=80,                                             *
               MAXBUFF=30,                                             *
               AUTORPC=ON,                                             *
               DFS=(MYSERV,MYNODE1,,ACI),                              *
               RDS=((SRVX,NODEX),(SRVY,NODEY))

For the server:

         NTRPC RPCSIZE=80,                                             *
               MAXBUFF=30,                                             *
               SRVNAME=MYSERV,                                         *
               SRVNODE=MYNODE,                                         *
               SERVER=ON