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
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.
You can use the LN (List Server with
Sequence Number) command to select the severs to be
terminated with the TE
(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.
Use the TS (Terminate
EntireX Broker Service) command of the SYSRPC
utility as described in
Terminating
an RPC 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 | Node name.
See the profile parameter
|
|
SRVNAME |
A32 | I | Server name.
See the profile parameter
|
|
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 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. | |||
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.
With the command PING the identification
string of a server is returned.
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 |
A17 | I | Specify
TERMINATE-SERVICE.
This sends a shutdown request to each server specified with the
parameters or: SpecifyPING
This returns the identification string of a server. |
|
SRVNODE |
A192 | I | Specify the node name.
See the profile parameter
|
|
SRVCLASS |
A32 | I | Specify the server class. For
Natural RPC servers, this is RPC.
|
|
SRVNAME |
A32 | I | Server name.
See the profile parameter
|
|
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
mainframes only), you can use the reserved 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.
|
|||
Before invoking the API, fill the input variables listed above.
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.
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.
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.
To make use of USR8220N
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.
Create a Natural RPC server subprogram that calls
USR8220N and that sends an optional confirmation message to the
RPC client program.
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).
NATRPC99 is called for all kinds of normal Natural RPC
server terminations. It is not called in case of abends.