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.

Possible settings See RPC Parameter Syntax.
Default setting none See:

Keyword Subparameters for Client and Server
Keyword Subparameters for Client Only
Keyword Subparameters for Server Only

Dynamic specification yes This parameter can only be specified dynamically. In the Natural parameter module, the macro NTRPC is used instead.
Specification within session no  

The following topics are covered below:

Note:
For information on Natural RPC, see the Natural RPC (Remote Procedure Call) documentation and Setting Up a Natural RPC Environment.


RPC Parameter Syntax

The parameter syntax of RPC is as follows:

RPC=(keyword-subparameter=value,keyword-subparameter=value,...)

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.

Possible settings 1 - 9 Single-digit number, identifying the API version.

Note:
The higher the version, the more features are available. For details, see Set the API Version in the Natural RPC (Remote Procedure Call) documentation.

Default setting 2 API Version 2 is used.
Dynamic specification yes  
Specification within session no  

CPRPC - Define Code Page Name

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

Note:
Currently, it applies only to the Natural RPC facility when the transport protocol ACI (that is EntireX Broker) is used.

Possible settings 1 - 40 characters Valid code page name of EntireX Broker.
Default setting none  
Dynamic specification yes  
Specification within session no  

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.

Possible settings 1 - 2097147, but less than or equal to RPCSIZE=value - 4 Default buffer size in KB.

The default buffer size must be equal to or less than the value (minus 4) specified with the keyword subparameter RPCSIZE (for the server side, see Dependency on Number of Parameters on Server Side).

0 No buffer is allocated.
Default setting 0  
Dynamic specification yes  
Specification within session no  

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.

Possible settings 1 - 2097151 Buffer size in KB.

Note:
If the specified size is not large enough, the buffer will be increased on request.

0 Natural RPC cannot be used.
Default setting 0  
Dynamic specification yes  
Specification within session no  

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.

Possible settings ON The Natural session will be started as an RPC server session.
OFF The Natural session will not be started as an RPC server session.
Default setting OFF  
Dynamic specification yes  
Specification within session no  

Keyword Subparameters for Client Only

The following keyword subparameters are available for the client only:

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

Note:
See also Set the RPC Client-Specific Natural Parameters in the Natural RPC (Remote Procedure Call) documentation.

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).

Possible settings ON Natural RPC will automatically try to execute it remotely.
OFF Natural RPC will not automatically try to execute it remotely.

Note:
With AUTORPC=OFF, you can execute CALLNATs remotely using interface objects.

Default setting OFF  
Dynamic specification yes  
Specification within session yes At runtime, this value can be overwritten using the Parameter Maintenance function of the SYSRPC utility.

Note:
If you want to use a remote CALLNAT statement to execute a subprogram on an EntireX RPC server, we strongly recommend that you set AUTORPC=OFF and use an interface object. For details, see Interface Objects and Automatic RPC Execution in the Natural RPC (Remote Procedure Call) documentation.

COMPR - Set RPC Buffer Compression

COMPR=value sets the RPC buffer compression.

Possible settings 0 No compression will be performed.
1 The send buffer contains modifiable fields and output fields and the format buffer. The reply buffer contains modifiable fields and input fields.
2 Same as COMPR=1, additionally the reply buffer also contains the format buffer.
Default setting 1  
Dynamic specification yes  
Specification within session yes At runtime, this value can be overwritten using the Parameter Maintenance function of the SYSRPC utility.

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.

Possible settings See DFS Subparameter Syntax.
Default setting none See DFS Subparameter Syntax.
Dynamic specification yes  
Specification within session yes At runtime, this value can be overwritten using the Natural application programming interface USR2007N.
Application programming interface USR2007N See Application Programming Interfaces for Use with Natural RPC in the Natural RPC (Remote Procedure Call) documentation and SYSEXT - Natural Application Programming Interfaces in the Utilities documentation.

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.

Possible settings See RDS Subparameter Syntax.
Default setting none See RDS Subparameter Syntax.
Dynamic specification yes  
Specification within session no  

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.

Possible settings 1 - 8 characters Valid Natural library name.
Default setting none  
Dynamic specification yes  
Specification within session no  

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.

Possible settings 0 -32767 Timeout in seconds.

Note:
If this time is exceeded, the remote procedure call will be terminated with a corresponding error message.

Default setting 55  
Dynamic specification yes  
Specification within session yes At runtime, this value can be overwritten using the Parameter Maintenance function of the SYSRPC utility.

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.

Possible settings ON If a request could not be executed on the node you specified, the RPC client tries to find an alternative server address to send that request to.
OFF No such attempt will be made.
Default setting OFF  
Dynamic specification yes  
Specification within session yes At runtime, this value can be overwritten using the Parameter Maintenance function of the SYSRPC utility.

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

Note:
See also Set the RPC Server-Specific Natural Parameters in the Natural RPC (Remote Procedure Call) documentation.

LOGONRQ - Logon for RPC Server Request Required

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

Possible settings ON A logon is required; that is, the server only accepts requests from clients which include logon data in the RPC server request. For conversational requests, the logon data is only necessary when the conversation is opened.

Note:
If the Natural RPC server runs under Natural Security, you are strongly recommended to set LOGONRQ=ON. For further information, see Using Natural RPC with Natural Security in the Natural RPC (Remote Procedure Call) documentation.

OFF A logon is not required. Logon data will be processed nevertheless.
Default setting OFF  
Dynamic specification yes  
Specification within session no  

Note:
For Natural clients, the logon data can be requested either by setting the LOGON option of the SYSRPC Service Directory Maintenance or by using the logon indicator of the keyword subparameter DFS.

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.

Possible settings See NTASKS Subparameter Syntax.
Default setting 1,1  
Dynamic specification yes  
Specification within session no  

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

NTASKS=(min,max)

Or:

NTASKS=min

Where:

Syntax Element Value Explanation
min 1 - 99 Minimum number of server tasks to be started during server initialization.
max

1 - n

0 (unlimited)

Maximum number of server tasks that may be active at any time.

Note:
The maximum number max of server tasks applies only to servers started by an RPC server front-end.

Note:
If you do not specify a max value, max defaults to 1 if min is set to 1, and it defaults to 0 if min is set to a value greater than 1.

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.

Possible settings ON The name of the remote CALLNAT subprogram to be executed by the Natural RPC server will be translated into upper case before the CALLNAT is invoked.

With this option, non-Natural RPC clients are supported that use mixed case characters in their subprogram names.

Note:
On UNIX and Windows platforms, an implicit upper case translation is already done by Natural itself. RPCUCT=ON is therefore the compatibility mode for Natural RPC servers on mainframes and Natural RPC servers on UNIX and Windows platforms.

OFF The name of the remote CALLNAT to be executed by the Natural RPC server is not changed. If the name contains lower case characters a NAT00082 error message is to be expected.
Default setting ON  
Dynamic specification yes  
Specification within session no  

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.

Possible settings B The Natural RPC server automatically commits a database transaction before the reply is sent to the client.

Note:
If the reply fails, the database transaction is already committed.

A The Natural RPC server automatically commits a database transaction after the reply has been successfully sent to the client.

Note:
If the reply fails, the database transaction is rolled back.

Default setting B  
Dynamic specification yes  
Specification within session no  

Note:
This parameter is only evaluated if the profile parameter ETEOP is set to ON.

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.

Possible settings 1 - 32 characters Valid server name.

In case of an EntireX Broker node, the value of SRVNAME corresponds to the value of the SERVER attribute of a service entry in the broker attribute file, as shown below:

CLASS=RPC, SERVICE=CALLNAT, SERVER=srvname

See Example.

Default setting none  
Dynamic specification yes  
Specification within session no  

Example:

SRVNAME='PRODUCTION_SERVER'

SRVNODE - Name of Node

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

Possible settings 1 - 192 characters Node name.

In case of an EntireX Broker node, a node name may refer to an Entire Net-Work node or to an TCP/IP address. Note that the EntireX Broker stub in use must support the naming notation. For details about the structure of node names and their support by the EntireX Broker stubs, refer to the EntireX documentation.

See Examples.

Default setting none  
Dynamic specification yes  
Specification within session no  

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.

Possible settings See SRVRTRY Subparameter Syntax.
Default setting 0,60 No attempts.
Dynamic specification yes  
Specification within session no  
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:

  1. 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.
  2. 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.

Note:
For further information, see the Natural Natural RPC (Remote Procedure Call) documentation, and especially Considerations for Mainframe Natural RPC Servers with Replicas.

SRVTERM - Server Termination Event

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

Possible settings NEVER A Natural RPC server is never automatically terminated.

Note:
To terminate a Natural RPC server, refer to Terminating a Natural RPC Server and Using Application Programming Interface USR2075N (for the EntireX Broker Service) in the Natural RPC (Remote Procedure Call) documentation.

TIMEOUT A Natural RPC server is automatically terminated if the wait time for the next client request outside of an RPC conversation is exceeded.

Note:
TIMEOUT should only be set if you use an Attach Manager to dynamically start Natural RPC servers on request.

Default setting NEVER  
Dynamic specification yes  
Specification within session no  

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.

Note:
In case of an EntireX Broker node, SRVUSER is also used to logon to the EntireX Broker. A password is either taken from Natural Security (see *NSC below) or specified via the application programming interface USR2072N.

Possible settings user-ID Valid user ID. 1 to16 characters.
*USER If SRVUSER is set to *USER, the Natural server uses the current Natural user ID (see system variable *USER) to logon to the node.
*NSC If SRVUSER is set to *NSC and Natural Security is installed, the Natural server uses the current Natural user ID (see system variable *USER) and the password defined for this user ID in Natural Security to logon to the node.
Default setting timestamp If the user ID is omitted, the timestamp will be used.
Dynamic specification yes  
Specification within session no  

SRVWAIT - Wait Time of RPC Server

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

Possible settings

0
or
1 - 32767

Wait time in seconds.

Notes:

  1. If this time is exceeded, the RPC server is informed by the node to which the RPC server has registered. The RPC server writes a corresponding message to the Natural RPC server trace file, and continues to wait for an RPC client request.
  2. If TCP/IP is used to communicate with the node, a non-zero value will also avoid an indefinite wait in TCP/IP if the node cannot respond for any reason.
Default setting 0 Unlimited wait time.

Note:
In case of an EntireX Broker node, the wait time is set to the SERVER-NONACT value of the corresponding Entirex Broker attribute file.

Dynamic specification yes  
Specification within session no  

TRACE - Define Trace Level for Natural RPC Servers

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

Possible settings 0 Nothing is traced.
1 Only messages (inclusive Natural errors) are traced.
(1,E) Messages are traced in the event of an error only.
2 All messages and data from/to client are traced.
(2,E) Messages and data from/to client are traced in the event of an error only.
3 - 9 The values 3 - 9 are also accepted. These values are for future use and behave like TRACE=2.
Default setting 0  
Dynamic specification yes  
Specification within session no  

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.

Note:
The use of TRANSP is no longer required as you may now specify the full node name with SRVNODE. It is still supported for compatibility reasons.

Possible settings ACI ACI is used. The transport method is defined by the EntireX Broker.
(ACI,TCP) ACI is used with TCP/IP.
(ACI,NET) ACI is used with Entire Net-work, i.e. using the Adabas protocol.
(ACI,TCP-NET) Trying to use ACI with TCP. If not available, ACI is used with NET.
(ACI,NET-TCP) Trying to use ACI with NET. If not available, ACI is used with TCP.
Default setting ACI  
Dynamic specification yes  
Specification within session no  

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