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