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.
This method can either be applied to a single RPC server replica or the EntireX Broker service:
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.
Use the TS (Terminate
EntireX Broker Service) command of the SYSRPC
utility as described in Terminating
a Server in the SYSRPC
Utility documentation.
Use the button in the Server subtree of the EntireX System Management Hub. You can also use the button in the Service subtree of the EntireX System Management Hub.
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
Copy the subprogram USR2073N from library
SYSEXT to the library SYSTEM or to the steplib
library or to any application in the server environment.
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 |
|
USER-ID |
A8 | I |
If 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
|
|
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. | |||
Before invoking the API, fill the input variables listed above.
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.
To make use of USR2075N
Copy the subprogram USR2075N from library
SYSEXT to the library SYSTEM or to the steplib
library or to any application in the server environment.
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 |
A18 | I | Specify
TERMINATE-SERVICE.
This sends a shutdown request to each server specified with the
parameters |
|
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 |
|
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.
|
|||
Before invoking the API, fill the input variables listed above.
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.
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.
NATRPC99 must be a Natural program.
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.
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).
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.
