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 has been deprecated and is ignored. The highest possible API version is negotiated dynamically by the RPC nucleus and EntireX.
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
value = RPCSIZE - 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.
SYSRPC CSMASS
command; see
Calculating
Size Requirements in the SYSRPC
Utility documentation.
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