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 TE (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 TS (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 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.

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.

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

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

Start of instruction setTo make use of USR8208N

Using Application Programming Interface USR8220N

The Application Programming Interface (API) USR8220N triggers the termination of the Natural RPC server. 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.

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

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.