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.
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.
Note for Windows, UNIX and OpenVMS Environments:
Predict servers are not maintained in the SYSRPC utility.
For information on how to connect to a Predict server, see the profile
parameter USEDIC or the
Dictionary Server
Assignments function in the Global Configuration File.
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 Stub Generation function of the SYSRPC utility; see
Creating Stub
Subprograms.
Note that the generated stub must be made available to the Natural client environment. If you did not generate the stub subprogram (interface object) in your client library, move the stub subprogram 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 mainframe clients only) |
| Parameter | Function |
|---|---|
ACIVERS |
Define ACI version for use with EntireX Broker ACI |
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 (for mainframe, UNIX and OpenVMS servers only) |
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 mainframe 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 |
Define ACI version for use with EntireX Broker ACI |
CPRPC |
Define code page name |
LOGONRQ |
Logon for RPC server request required |
NTASKS |
Minimum and maximum of the number or server replicas (for mainframe servers only) |
SRVCMIT |
Time at which a Natural RPC server automatically commits an RPC conversation or a non-conversational RPC request |
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.
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 mainframe servers only).
 |
Do not:
|
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.
Note for Natural in Batch Mode on z/OS or on z/VSE:
For information about servers using the keyword subparameter
NTASKS of profile
parameter RPC or parameter macro
NTRPC, refer to
Considerations
for Mainframe 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.
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
must use a different Broker stub:
If you want to use the TCP/IP protocol under BS2000/OSD, you must
use BKIMBTIA instead.
If you want to use impersonation in z/OS batch mode, you must use
BKIMBTSO instead.
If you want to use impersonation under CICS, you must use
CICSETB instead.
Note:
You must link CICSETB to your Natural CICS
interface nucleus.
To load BKIMBTIA or BKIMBTSO dynamically at
run-time, specify RCA=BROKER
RCALIAS=(BROKER,stubname).
It is currently not possible to load CICSETB dynamically
at run-time.
Refer to the EntireX Communicator documentation for further details.
Copy the Natural-specific broker stub natetb.so /
natetb.sl from the directory $EXXDIR/$EXX/VERS/lib to
the directory specified with NATEXTLIB in the Local Configuration
File NATURAL.INI.
The EntireX Broker stub is made available automatically in the course of the EntireX installation.
Set the keyword subparameter ACIVERS of profile parameter RPC or
parameter macro
NTRPC
according to your requirements.
Note:
The ACIVERS value set in the Natural
parameter module (mainframe) or parameter file (Windows, UNIX or OpenVMS) can
only work if also the EntireX Broker and the EntireX Broker stub support this
version.
The table below contains only those ACIVERS
values which are associated with a feature that is relevant for the Natural
RPC.
| Setting | Function |
|---|---|
ACIVERS=2 |
(Default) Support of the EntireX Broker functions
The server performs a This does not imply any security checks, but it is a pure EntireX
Broker management function, see EntireX Broker function |
ACIVERS=3 |
Support of EntireX Broker non-numeric conversation IDs and data volume > 30 KB. When If a Natural client issues an Therefore, make sure that both the Natural client and the server support the corresponding ACI version. In addition, with EntireX Broker ACI Version 3 or higher, the data volume which can be exchanged between client and server in a single request may exceed 30 KB if transport method TCP/IP is used. Notes:
|
ACIVERS=4 |
Support of code pages and (for servers only) Natural Security. With EntireX Broker ACI Version 4 or higher, the Natural RPC
supports code pages. For this, the name of the code page can be specified in
the keyword
subparameter The evaluation of the code page is done by the EntireX Broker. The EntireX Broker translates the RPC data sent according to the code page of client and server to the corresponding target code page. The keyword subparameter The server is enabled to logon to the EntireX Broker using a qualified user ID. If the keyword subparameter |
ACIVERS=6 |
Support of EntireX Encryption ( With EntireX Broker ACI Version 6 or higher, the application
programming interface |
ACIVERS=7 |
Support of EntireX compression (COMPRESSLEVEL).
With EntireX Broker ACI Version 7 or higher, the application
programming interface |
ACIVERS=8 |
Support of EntireX Security without stub exits (mainframe
only).
With EntireX Broker ACI Version 8 or higher, the Natural RPC
server issues a |
ACIVERS=9 |
Support of EntireX application identification of the client and
server environment and (for servers only) of the Integrated Authentication
Framework (IAF).
With EntireX Broker ACI Version 9 or higher, the EntireX Broker stubs send environmental information about client and server (for example, job name) to the EntireX Broker. With EntireX Broker ACI Version 9 or higher, the Natural RPC server can optionally use IAF for client authentication. For details, refer to the current EntireX documentation. |
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.
Note:
If AUTOLOGON=NO or SECURITY=YES is set in
the EntireX Attribute File, you must set ACIVERS=2 or
higher.