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 keyword subparameter |
|
SRVNAME |
A32 | I | Server name.
See the keyword subparameter |
|
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 keyword subparameter |
|
SRVCLASS |
A32 | I | Specify the server class. For Natural RPC
servers, this is RPC.
|
|
SRVNAME |
A32 | I | Server name.
See the keyword subparameter |
|
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 |
|
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
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
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 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
See the similar instruction To make use of
USR2073N.
When using trace, the print file for the trace must be defined with the start of the Natural RPC server.
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.
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.
The keyword
subparameter SRVTERM of profile parameter RPC or parameter
macro NTRPC 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.
