Terminating a Natural RPC Server

#### Search Results

Search

# Terminating a Natural RPC Server

This section describes how to terminate a Natural RPC server. This can be done either by terminating a single RPC server replica or the EntireX Broker service supporting the RPC connection. Several methods exist.

- Using SYSRPC

- Using EntireX System Management Hub

- Using Application Programming Interface USR2073N

- Using Application Programming Interface USR2075N

- Using Application Programming Interface USR8208N

- Using Application Programming Interface USR8213N

- Using Application Programming Interface USR8220N

- Using Application Programming Interface USR9175N

- Using Application Programming Interface USR9176N

- Using Application Programming Interface USR9177N

- Server Termination When Using an Attach Manager

- User Exit NATRPC99

## Using SYSRPC

This method can either be applied to a single RPC server replica or the EntireX Broker service:

- Using SYSRPC to Terminate a Single RPC Server Replica

- Using SYSRPC to Terminate a Single RPC Replica by Sequence Number

- Using SYSRPC to Terminate an EntireX Broker Service

### Using SYSRPC to Terminate a Single RPC Server Replica

Use the Terminate Server command of the `SYSRPC` utility as described in Terminating an RPC Server in the SYSRPC Utility documentation.

Note
A Natural RPC server can only be terminated if the server is currently neither executing a remote `CALLNAT` nor waiting for the next `CALLNAT` request in a conversation.

### Using SYSRPC to Terminate a Single RPC Replica by Sequence Number

You can use the Terminate Server with Sequence Number command to select the severs to be terminated with the Terminate Server command from a detailed list of replicas that contains the sequence number assigned to a server. For more information, see Terminating an RPC Server in the SYSRPC Utility documentation.

### Using SYSRPC to Terminate an EntireX Broker Service

Use the Terminate EntireX Broker Service command of the `SYSRPC` utility as described in Terminating an RPC Server in the SYSRPC Utility documentation.

## Using EntireX System Management Hub

Use the Deregister button in the Server subtree of the EntireX System Management Hub. You can also use the Deregister button in the Service subtree of the EntireX System Management Hub.

## Using Application Programming Interface USR2073N

The Application Programming Interface (API) `USR2073N` enables you to ping or terminate a Natural RPC server.

The interface sends a ping or terminate command to an RPC server specified by node name and server name. The returned message contains the following information:

- the version of the running server (`PING`) or

- the acknowledgment of termination (`TERMINATE`) or

- an error message.

To make use of `USR2073N`

1. Copy the subprogram `USR2073N` from library `SYSEXT` to the library `SYSTEM` or to the steplib library or to any application in the server environment.

2. Using a `DEFINE DATA` statement in structured mode or a `RESET` statement in reporting mode, specify the following parameters:

   Parameter | Format | I/O | Description
   --- | --- | --- | ---
   `FUNCTION` | A10 | I | `PING` | Asks the RPC server for its version.
   `TERMINATE` | Initiates the finishing of the Natural RPC server task.
   `SRVNODE` | A192 | I | Node name. See the profile parameter `SRVNODE`.
   `SRVNAME` | A32 | I | Server name. See the profile parameter `SRVNAME` .
   `LOGON` | A1 | I | The logon flag `Y` (yes) indicates that logon data must be transmitted to the Natural RPC server.
   `USER-ID` | A8 | I | If `LOGON=Y`, then user ID and password are the logon data for Natural Security. If the client does not run under Natural Security (NSC) and the logon flag is set, the user ID and password have to be specified unless the data have been entered via Application Programming Interface `USR1071N`. See Using Security, Using Natural RPC with Natural Security.
   `PASSWORD`
   `MSG` | A79 | O | Message returned.
   `RC` | I2 | O | Response code; possible values are:
   `0` | `MSG` contains a normal message from RPC server or EntireX Broker.
   `1` | `MSG` contains an error message from RPC server or EntireX Broker.
   `2` | `MSG` contains an error message from the interface.
   `3` | Natural Security error.

3. Before invoking the API, fill the input variables listed above.

## Using Application Programming Interface USR2075N

The Application Programming Interface (API) `USR2075N` enables you to terminate an EntireX Broker Service from within your application.

With the command `TERMINATE-SERVICE` the interface uses the command and information service of EntireX to fulfill the task. First of all, it sends a logon request to the EntireX Broker. Then it gets a list of all servers specified by server class, server name, and service type. Finally, it sends a shutdown request to each server. A message indicates how many servers were terminated.

With the command `PING` the identification string of a server is returned.

To make use of `USR2075N`

1. Copy the subprogram `USR2075N` from library `SYSEXT` to the library `SYSTEM` or to the steplib library or to any application in the server environment.

2. Using a `DEFINE DATA` statement in structured mode or a `RESET` statement in reporting mode, specify the following parameters:

   Parameter | Format | I/O | Description
   --- | --- | --- | ---
   `FUNCTION` | A17 | I | Specify `TERMINATE-SERVICE`. This sends a shutdown request to each server specified with the parameters `SRVCLASS`, `SRVNAME`, and `SERVICE` (service type), see below. or: Specify `PING` This returns the identification string of a server.
   `SRVNODE` | A192 | I | Specify the node name. See the profile parameter `SRVNODE`.
   `SRVCLASS` | A32 | I | Specify the server class. For Natural RPC servers, this is `RPC`.
   `SRVNAME` | A32 | I | Server name. See the profile parameter `SRVNAME`
   `SERVICE` | A32 | I | Specify the type of service. For Natural RPC servers, this is `CALLNAT`.
   `IMMEDIATE` | L |  | `TRUE` | Immediately terminate all conversations for the specified server.
   `FALSE` | Existing conversations are allowed to end normally; no new conversations are accepted.
   `USER-ID` | A32 | I | Specify the user ID to logon to the EntireX Broker.
   `PASSWORD` | A32 | I | Specify the password to the EntireX Broker if EntireX Broker security is active. If EntireX Broker security is active, you must specify a password. If EntireX Broker security uses the trusted user ID mechanism (on z/OS only), you can use the reserved password `*TRUSTED` instead of a user password.
   `MSG` | A (dynamic) | O | Message returned.
   `RC` | I2 | O | Response code; possible values:
   `0` | `MSG` contains a normal message from the EntireX Broker.
   `1` | `MSG` contains an error message from the EntireX Broker.
   `3` | `MSG` contains an error message from Natural Security on the client side.

3. Before invoking the API, fill the input variables listed above.

## Using Application Programming Interface USR8208N

The Application Programming Interface (API) `USR8208N` is an enhanced version of API `USR2075N` with the following new features:

- With the command `TERMINATE-SERVICE` the interface uses the Command and Information Service of EntireX to fulfill the task. The `SHUTDOWN-SERVICE` command is sent to the EntireX Broker if its version is 5 or above. It returns version information on the EntireX Broker and the Command and Information Service itself. Otherwise, the same method is used as in `USR2075N`.

- With the command `INFO-SERVICE` additional information on the specified service(s) is returned from the EntireX Broker such as `SERVER-CLASS`, `SERVER-NAME`, `SERVICE`, `TRANS`, `CONV-NONACT` etc. For a detailed description, see webMethods EntireX V9.0.1 documentation > Components and Features of EntireX > ACI Programming > Broker CIS Data Structures > Information Reply Structures > SERVICE-OBJECT (Struct INFO_SV).

To make use of `USR8208N`

- See the similar instruction To make use of `USR2075N`.

## Using Application Programming Interface USR8213N

The Application Programming Interface (API) `USR8213N` shuts down a server on an EntireX Broker node.

This interface firstly retrieves a list of RPC server replica registered on a specified EntireX Broker. For each server, the list indicates the start date/time, host name, application name and IP address (if available). It also indicates the sequence number assigned to each server during registration. The interface then sends a shutdown request with the sequence number to the EntireX Broker.

To make use of `USR8213N`

- Copy the subprogram `USR8213N` from the library SYSEXT to the library SYSTEM or to the steplib library, or to any application in the Natural RPC server environment and proceed as described on the text object `USR8213T` in the library `SYSEXT`.

## Using Application Programming Interface USR8220N

The Application Programming Interface (API) `USR8220N` triggers the server-side termination of the Natural RPC server that is running this API. After calling `USR8220N`, you can send a confirmation message to the RPC client. This API is useful to explicitly terminate the Natural RPC server when severe errors occur.

To make use of `USR8220N`

1. Copy the subprogram `USR8220N` from the library SYSEXT to the library SYSTEM or to the steplib library, or to any application in the Natural RPC server environment.

2. Create a Natural RPC server subprogram that calls `USR8220N` and that sends an optional confirmation message to the RPC client program.

## Using Application Programming Interface USR9175N

The Application Programming Interface (API) `USR9175N` is an enhanced version of API `USR2073N` with an extended `PASSWORD` parameter (format A128) and the additional values for the `FUNCTION` parameter:

Parameter | Format | I/O | Description
--- | --- | --- | ---
`FUNCTION` | A10 | I | `PING` | Asks the RPC server for its version.
`TERMINATE` | Initiates the finishing of the Natural RPC server task.
`TRACEINFO` | Retrieves the state of the Natural RPC server trace.
`TRACE0` | Disables the Natural RPC server trace.
`TRACEn` | Enables the Natural RPC server trace with level n, where n=1-9.
`TRACEnE` | Enables the Natural RPC server trace with level n, where n=1-9, and sets the flag to trace in the event of an error only.

For further information about the possible trace settings, see TRACE - Define Trace Level for Natural RPC Servers.

To make use of `USR9175N`

1. See the similar instruction To make use of `USR2073N`.

2. When using trace, the print file for the trace must be defined with the start of the Natural RPC server.

## Using Application Programming Interface USR9176N

The Application Programming Interface (API) `USR9176N` is an enhanced version of API `USR8208N` with an extended `PASSWORD` parameter (format A128).

To make use of `USR9176N`

- See the similar instruction To make use of `USR8208N`.

## Using Application Programming Interface USR9177N

The Application Programming Interface (API) `USR9177N` is an enhanced version of API `USR8213N` with the an extended `PASSWORD` parameter (format A128).

To make use of `USR9177N`

- See the similar instruction To make use of `USR8213N`.

## Server Termination When Using an Attach Manager

The profile parameter `SRVTERM` influences the termination behavior of a Natural RPC server. By default, a server is never terminated (`SRVTERM=NEVER`) unless one of the termination methods described before is applied.

If you use an Attach Manager to dynamically start Natural RPC servers on request, you should set `SRVTERM` to `TIMEOUT`. With this parameter setting, a Natural RPC server is automatically terminated if the wait time for the next client request outside of an RPC conversation is exceeded.

## User Exit NATRPC99

This exit is called after the Natural RPC server has deregistered and logged off from the server node.

- If no `NATRPC99` program is found, the server terminates immediately as usual.

- If the program `NATRPC99` is found, the server continues to run as a normal Natural session.

`NATRPC99` is called with a `FETCH` statement without any parameters, that is, no data is put on the Natural stack before `NATRPC99` has been called.

You may add any coding to `NATRPC99`, including transfer control statements (`FETCH`, `CALLNAT`, `PERFORM`) and statements that terminate the program (`STOP`, `ESCAPE`, `TERMINATE`).

If `NATRPC99` is terminated with a `RETURN` or `STOP` statement, Natural returns to the `NEXT` prompt. If the `NEXT` prompt is not supported in the environment used (profile parameter `CM``=OFF`, asynchronous Natural session, etc.) the session terminates. Otherwise, the session tries to read the next command from the primary input file/dataset for Natural commands and `INPUT` data.

#### Important Notes:

1. `NATRPC99` must be a Natural program.

2. `NATRPC99` must be located in the library `SYSTEM` on system file `FUSER`. The steplib concatenation of the library to which the server currently is logged on is not evaluated to find `NATRPC99`.

3. Natural objects that are called by `NATRPC99` (`FETCH`, `CALLNAT`, `PERFORM`) must be located either in the library to which the server is logged on or in one of its steplibs (including `SYSTEM` on system file `FUSER`).

4. `NATRPC99` is called for all kinds of normal Natural RPC server terminations. It is not called in case of abends.

### On this page

- Using SYSRPC
- Using EntireX System Management Hub
- Using Application Programming Interface USR2073N
- Using Application Programming Interface USR2075N
- Using Application Programming Interface USR8208N
- Using Application Programming Interface USR8213N
- Using Application Programming Interface USR8220N
- Using Application Programming Interface USR9175N
- Using Application Programming Interface USR9176N
- Using Application Programming Interface USR9177N
- Server Termination When Using an Attach Manager
- User Exit NATRPC99