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 or with the application programming
interface USR2076N .
|
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 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 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 |
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 |
|
'*NSC' |
If If Natural is running under Natural SAF Security, you must not use
|
|
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