Setting Up a Natural RPC Environment

#### Search Results

Search

# Setting Up a Natural RPC Environment

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.

- Setting Up Natural RPC with Natural Security

- Setting Up a Natural Client

- Setting Up a Natural Server

- Setting Up an EntireX Broker Access

- Setting Up an EntireX Broker Environment

- Set Application Error on RPC Server

## Setting Up Natural RPC with Natural Security

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>

## Setting Up a Natural Client

Unless otherwise noted, this instruction applies to all environments.

To set up a Natural client, perform the following steps:

- Define the Server Name

- Generate an Interface Object

- Set the RPC Client-Specific Natural Parameters

### Define the Server Name

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:

- #### Address a default server

  See Specifying a Default Server Address within a Natural Session, or profile parameter `DFS`.

- #### Use a remote directory server

  See Using a Remote Directory Server, or profile parameter `RDS`.

### Generate a Client Interface Object

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 RPC Client-Specific Natural Parameters

Set the Natural profile parameters which are relevant to the client-specific handling of remote procedure calls.

#### Mandatory Parameters:

Parameter | Function
--- | ---
`MAXBUFF` | Maximum buffer size (for automatic RPC execution only)
`RPCSIZE` | Size of buffer used by Natural RPC (for z/OS clients only)

#### Optional Parameters:

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:

1. The names specified with the `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.
2. The wait time specified with `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.

## Setting Up a Natural Server

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 RPC Server-Specific Natural Parameters

- Ensure Command Mode Usage in Server Session

- Ensure Unique Adabas ETID Usage

- Start a Natural Server

### Set the RPC Server-Specific Natural Parameters

Set the platform-dependent Natural parameters which are relevant to the general and server-specific handling of remote procedure calls for the server Natural.

#### For z/OS Servers:

1. Create an RPC-specific Natural parameter module.

2. Set the keyword subparameters of profile parameter `RPC` or parameter macro `NTRPC` (see table below) as desired.

#### For Windows and Linux Servers:

1. Create an RPC-specific Natural parameter file.

2. Set the Natural profile parameters (see table below) as desired.

#### Mandatory Parameters:

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.

#### Optional Parameters:

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 trace level for Natural RPC servers
`TRANSP` | Server transport protocol (no longer required)

The following notes apply to the use of the EntireX Broker.

Notes:

1. The name specified with `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.
2. The wait time specified with the `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.
3. If you have set the number of attempts for an RPC server to connect or reconnect to an EntireX Broker to a value greater than zero, the RPC server will no longer terminate immediately if the EntireX Broker is shut down (for example, for an IPL or a prolonged maintenance period). In this case, you must explicitly terminate the RPC server before you shut down the EntireX Broker using one of the following ways: Use the Terminate Service (`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.

### Ensure Command Mode Usage in Server Session

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).

#### Warning

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 Unique Adabas ETID Usage

Ensure that the Adabas `ETID` used by the Natural server session is unique within a certain Adabas nucleus.

### Start a Natural Server

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:

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.

## Setting Up an EntireX Broker Access

To set up an EntireX Broker interface, perform the steps described below:

- Provide Access to the EntireX Broker Stub

- The API Version

- Using TCP/IP as Transport Method

### Provide Access to the EntireX Broker Stub

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 API Version

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.

### Using TCP/IP as Transport Method

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.

## Setting Up an EntireX Broker Environment

In the EntireX Broker Attribute File, add the following:

1. For each Natural RPC server, a service definition must be specified as follows:

   `CLASS=RPC, SERVICE=CALLNAT, SERVER=servername`.

2. If you want to use the conversion services, set `CONVERSION=userexit`. In this case, you must set the profile parameter `CPRPC` 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.

## Set Application Error on RPC Server

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`.

### On this page

- Setting Up Natural RPC with Natural Security
- Setting Up a Natural Client
- Setting Up a Natural Server
- Setting Up an EntireX Broker Access
- Setting Up an EntireX Broker Environment
- Set Application Error on RPC Server