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

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

Use the Terminate Server command of the SYSRPC utility as described in Terminating a 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 an EntireX Broker Service

Use the Terminate EntireX Broker Service command of the SYSRPC utility as described in Terminating a 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.

Start of instruction setTo 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 Specify the node name or * if the server name represents a Location Transparency of EntireX or a logical broker node name as LOGBROKER=nodename). See the profile parameter SRVNODE .
    SRVNAME A192 I Server name or EntireX Location Transparency. 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 Broker.
    1 MSG contains an error message from RPC server or 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.

Start of instruction setTo 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.

    SRVNODE A192 I Specify the Broker name or an asterisk (*) if the server name represents a Location Transparency of EntireX or a logical Broker node name as LOGBROKER=nodename).

    See the profile parameter SRVNODE.

    SRVCLASS A32 I Specify the server class. For Natural RPC servers, this is RPC.
    SRVNAME A32/A192 I Server name (A32) or EntireX Location Transparency (A192). 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 for EntireX Broker Security, if it is used on the EntireX Broker side.
    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.

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. With Natural Version 6.3.13 and above, NATRPC99 is called for all kinds of normal Natural RPC server terminations. It is not called in case of abends.