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 |
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.
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.
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.
The following keyword subparameters are available for both client and server:
ACIVERS
|
CPRPC
|
MAXBUFF
|
RPCSIZE
|
SERVER
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: |
---|---|---|
Default setting | 2 |
API Version 2 is used. |
Dynamic specification | yes | |
Specification within session | no |
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:
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
|
---|---|---|
0 |
No buffer is allocated. | |
Default setting | 0 |
|
Dynamic specification | yes | |
Specification within session | no |
Notes:
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.
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.
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.
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=value
specifies the
size of the buffer used by the Natural RPC.
Possible settings | 1 - 2097151 |
Buffer size in KB.
Note: |
---|---|---|
0 |
Natural RPC cannot be used. | |
Default setting | 0 |
|
Dynamic specification | yes | |
Specification within session | no |
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 |
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=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: |
|
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=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=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=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 |
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:
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=value
specifies the
number of seconds the client is to wait for an RPC server response.
Possible settings | 0 -32767 |
Timeout in seconds.
Note: |
---|---|---|
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=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.
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=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: |
---|---|---|
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=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:
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.
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 |
|
Maximum number of server tasks that may be
active at any time.
Note: |
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=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: |
---|---|---|
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=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: |
---|---|---|
A |
The Natural RPC server automatically commits a database
transaction after the reply has been successfully sent to the client.
Note: |
|
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=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
CLASS=RPC, SERVICE=CALLNAT, SERVER=srvname See Example. |
---|---|---|
Default setting | none | |
Dynamic specification | yes | |
Specification within session | no |
SRVNAME='PRODUCTION_SERVER'
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 a 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 |
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:
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 forattempts
is specified, the parentheses may be omitted.Where:
RPC=(SRVRTRY=(20,10))
Or:
NTRPC SRVRTRY=(20,10)
20 attempts with a wait time of 10 seconds between two successive attempts.
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=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: |
---|---|---|
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: |
|
Default setting | NEVER |
|
Dynamic specification | yes | |
Specification within session | no |
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=value
specifies the
number of seconds the server is to wait for a Natural RPC client request.
Possible settings |
|
Wait time in seconds.
Notes:
|
---|---|---|
Default setting | 0 |
Unlimited wait time.
Note: |
Dynamic specification | yes | |
Specification within session | no |
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=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 |
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)
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