To set up a Natural RPC environment, you must perform the steps described below for all client Naturals and server Naturals and read the platform-specific notes and considerations.
If the Natural RPC (client as well as server) is protected by Natural Security, the Natural RPC client or the Natural RPC server respectively must enable International Components for Unicode (ICU) by specifying:
CFICU=ON,CP=<valid code page>
Unless otherwise noted, this instruction applies to all environments.
To set up a Natural client, perform the following steps:
Use the Service Directory
Maintenance function of the SYSRPC utility to define the
name of the server to be used for each CALLNAT statement to be executed remotely.
For details and example screens, refer to Invoking Service Directory
Maintenance (in the SYSRPC utility
documentation).
The generated directory subprogram NATCLTGS must be made available to the
Natural client application. If you have not generated NATCLTGS in your
client library, move NATCLTGS to this library or to one of the
steplibs.
Optionally, you can use one of the following server selection techniques:
See Specifying a
Default Server Address within a Natural Session, or keyword
subparameter DFS of profile parameter RPC or
parameter macro NTRPC.
See Using a Remote
Directory Server, or keyword subparameter RDS of profile parameter RPC or
parameter macro NTRPC.
This step applies only if you do not want to or cannot work with automatic Natural RPC execution (see Operating a Natural RPC Environment, Working with Automatic Natural RPC Execution).
For each CALLNAT statement to be executed remotely, use the Interface
Object Generation function of the SYSRPC utility; see Creating Interface
Objects.
Note that the generated interface object must be made available to the Natural client environment. If you did not generate the interface object in your client library, move the interface object to this library or to one of the steplibs.
Set the keyword
subparameters of profile parameter RPC or parameter macro NTRPC which are relevant to the
client-specific handling of remote procedure calls.
| Parameter | Function |
|---|---|
MAXBUFF |
Maximum buffer size (for automatic RPC execution only) |
RPCSIZE |
Size of buffer used by Natural RPC (for z/OS clients only) |
| Parameter | Function |
|---|---|
ACIVERS |
This parameter is obsoleted and ignored. The highest ACI version is negotiated by the RPC nucleus and EntireX |
AUTORPC |
Automatic Natural RPC execution |
COMPR |
Set RPC buffer compression
See also Operating a Natural RPC Environment, Using Compression. |
CPRPC |
Define code page name |
DFS |
Specify RPC client's default server address |
RDS |
Define remote directory server |
RPCSDIR |
Specify name of Natural library in which the Service Directory is located |
TIMEOUT |
Wait time for RPC server response |
TRYALT |
Try alternative server address |
The following notes apply to the use of the EntireX Broker.
Notes:
DFS parameter must identify an active
EntireX Broker and must match a server definition in the EntireX Broker Attribute
File, see Setting Up an EntireX Broker Environment.
TIMEOUT is used to set the
WAIT field of the EntireX Broker ACI. If TIMEOUT
is set to zero, WAIT=YES is set and the client will wait for the
CLIENT-NONACT time. If the wait time has elapsed, the remote procedure
call is terminated with a corresponding error message. The use of
TIMEOUT enables you to take advantage of the transport
timeout mechanism provided by the EntireX Broker stubs.
A Natural server is a Natural task (server task) that can execute Natural subprograms (services). This Natural task is typically an asynchronous or background task (detached process). The EntireX Broker and the client identify it by using a nodename and a servername.
To set up a Natural server perform the steps described below:
Set the platform-dependent Natural parameters which are relevant to the general and server-specific handling of remote procedure calls for the server Natural.
Create an RPC-specific Natural parameter module.
Set the keyword subparameters of profile parameter RPC or
parameter macro NTRPC (see table below) as desired.
Create an RPC-specific Natural parameter file.
Set the Natural profile parameters (see table below) as desired.
| Parameter | Function |
|---|---|
MAXBUFF |
Maximum buffer size |
RPCSIZE |
Size of buffer used by Natural RPC (for z/OS servers only) |
SERVER |
Start Natural session as an RPC server session |
SRVNAME |
Name of RPC server; see Note for EntireX Broker below. |
SRVNODE |
Name of node; see Note for EntireX Broker below. |
| Parameter | Function |
|---|---|
ACIVERS |
This parameter is obsoleted and ignored. The highest ACI version is negotiated by the RPC nucleus and EntireX |
CPRPC |
Define code page name |
LOGONRQ |
Logon for RPC server request required |
NTASKS |
Minimum and maximum of the number or server replicas (for z/OS servers only) |
SRVCMIT |
Time at which a Natural RPC server automatically commits an RPC conversation or a non-conversational RPC request |
SRVRTRY |
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.
|
SRVTERM |
Server termination event |
SRVUSER |
User ID for RPC server registry |
SRVWAIT |
Wait time of RPC server for client request |
TRACE |
Define components to be traced |
TRANSP |
Server transport protocol (no longer required) |
The following notes apply to the use of the EntireX Broker.
Notes:
SRVNODE must identify an active EntireX
Broker and the name specified with SRVNAME must match a server
definition in the EntireX Broker Attribute File, see Setting Up an
EntireX Broker Environment.
SRVWAIT parameter is used to set the
WAIT field of the EntireX Broker ACI. If SRVWAIT
is not specified or set to zero, WAIT=YES is set, and the server will
wait for the SERVER-NONACT time. If the wait time has elapsed, a
corresponding message is written to the RPC server trace file, and the RPC server
continues to wait for the next client request. The use of the
SRVWAIT parameter enables you to take advantage of the
transport timeout mechanism provided by the EntireX Broker stubs.
TS) command of
the Server
Command Execution function of the SYSRPC
utility, or use the application programming interface USR2075N or
USR8208N, or use the System Management Hub for
EntireX.
To ensure that your Natural server session will enter command mode
disable Natural menu mode by setting the Natural profile parameter MENU=OFF
(applies to z/OS servers only).
Do not:
put a program onto the Natural stack which never terminates.
use a STARTUP program which never terminates.
disallow NEXT mode in Natural Security for your server library.
Ensure that the Adabas ETID used by the Natural server session is unique
within a certain Adabas nucleus.
To start a Natural server, proceed as described in the section Starting a Natural RPC Server.
This server then waits for remote CALLNAT requests from a client.
For information about servers using the keyword subparameter NTASKS of
profile parameter RPC or parameter macro NTRPC, refer to Considerations for z/OS Natural RPC Servers with
Replicas.
To set up an EntireX Broker interface, perform the steps described below:
Make the EntireX Broker stub accessible to your Natural environment. This step depends on the platform used.
Providing Access to the EntireX
Broker Stub on z/OS
Link the EntireX Broker stub NATETB23 to your Natural or specify the
profile parameter RCA=BROKER to load NATETB23
dynamically at run-time.
In the following cases NATETB23 cannot be used and you have to use a
different EntireX Broker stub:
If you want to use impersonation in z/OS batch mode, you have to use
BROKER instead.
If you want to use impersonation under CICS, you have to use
CICSETB instead.
To load BKIMBTIA, BROKER or CICSETB
dynamically at run-time, specify RCA=BROKER
RCALIAS=(BROKER,stubname).
Refer to the EntireX Communicator documentation for further details.
Note
Please check the prerequisites for the use of CICSETB regarding the
required PPT entries and the Adabas link routine.
Providing Access to the
EntireX Broker Stub on Linux
The EntireX Broker stub is made available automatically in the course of the
EntireX installation.
Providing Access to the
EntireX Broker Stub on Windows
The EntireX Broker stub is made available automatically in the course of the
EntireX installation.
The possible ACI version is negotiated by the RPC nucleus and EntireX and set to the highest possible value. This version of Natural restricts the ACI version 13, even if EntireX supports a higher ACI version.
If TCP/IP is used as transport method and you use a host name to address the server node, you have the following alternatives:
Define the server node in the Hosts and Services Directory of your TCP/IP installation.
Use a Domain Name System (DNS) for domain name resolution.
In the EntireX Broker Attribute File, add the following:
For each Natural RPC server, a service definition must be specified as follows:
CLASS=RPC, SERVICE=CALLNAT,
SERVER=servername.
If you want to use the conversion services, set
CONVERSION=userexit. In this case, you
must set the keyword
subparameter CPRPC of profile parameter RPC or parameter
macro NTRPC accordingly.
If you want to use the reliable RPC, additional settings are required for each Natural RPC server that should support reliable RPC:
The EntireX Broker attribute MAX-UOWS must be set to value greater zero.
The EntireX Broker attribute DEFERRED must be set to
YES if the client should be able to send reliable RPC messages to an
RPC server that is known to the EntireX Broker but has not yet been started.
The EntireX Broker attribute STORE must be set to
BROKER if recovery of reliable RPC messages after a system failure
should be possible. In addition, the EntireX Broker persistent store must be enabled.
The lifetime of the reliable RPC message itself (EntireX Broker attribute
UWTIME) and the lifetime of its status (EntireX
Broker attribute UWSTAT-LIFETIME) must be adapted to
your needs.
You can use the application programming interface USR4012N to force the
Natural NAT1999 error message to be returned to the RPC client with the text you specify
in the API for the case of an error in the application on the Natural RPC server.
For further information, refer to the description in text object USR4012T in
library SYSEXT.