Server Command Execution

#### Search Results

Search

# Server Command Execution

The SYSRPC utility provides the server execution commands ping and terminate. They are used to control active servers that have been defined in the service directory. The ping command sends an internal message to the server to verify a server connection. Terminate either sends an internal message to the server requesting termination of a single server task, or issues a command to EntireX Broker requesting termination of all server tasks associated with an EntireX Broker service.

The server execution commands reference the service directory in the library that is defined with the `NTRPC`/`RPC` keyword subparameter `RPCSDIR` (see the Parameter Reference documentation). If `RPCSDIR` is not set (this is the default), the library where you are currently logged on is used. The name of the library is indicated in the upper right corner of the Server Command Execution screen shown in the following section.

This section covers the following topics:

- Using Server Command Execution

- Pinging an RPC Server

- Terminating an RPC Server

- Executing Commands for RPC Server Tasks

## Using Server Command Execution

To use Server Command Execution

1. In the Code field of the Client Maintenance menu, enter the following command:

       XC

2. Choose ENTER.

   The standard view of the Server Command Execution screen appears similar to the following example:

        15:16:30            ***** NATURAL SYSRPC UTILITY *****              2016-07-18
                                 - Server Command Execution -         Library SAGTRPC2

           Cmd Node                         Server                           Message
        1      ETB045
        2   __                              NRPC001                          Natural
        3   __                              NRPC002

       Command ===>

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  ERR   Exit        -H    +H    -P    +P    TOP   BOT    >     Canc

   The standard view displays the columns Node, Server and Message. The fields under the column Message are truncated and display a maximum of 8 characters.

3. If you choose PF11 or enter the greater than (>) sign in the Command line at the bottom of the screen, the extended message view of the Server Command Execution screen is displayed similar to the following example:

        16:36:39            ***** NATURAL SYSRPC UTILITY *****              2016-07-18
                                 - Server Command Execution -         Library SAGTRPC2

           Cmd  Server            Message
        1
        2   __  NRPC001           Natural RPC Server 8.3.7 on WNT-x86
        3   __  NRPC002

       Command ===>

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  ERR   Exit        -H    +H    -P    +P    TOP   BOT   <    Canc

4. The extended view allows you to display a maximum of 50 characters of message text in the Message column. This view does not display the Node column and the fields under the Server column are truncated and display a maximum of 16 characters (the standard view shows 30 characters).

5. If you choose PF11 once more or enter the less than (<) sign in the Command line, the standard view of the Server Command Execution screen is displayed again as shown in Example of a Standard View.

This section covers the following topics:

- Line Commands: Server Command Execution

### Line Commands: Server Command Execution

The line commands available on the Server Command Execution screen depend on whether they are executed on an EntireX Broker node or an RPC server. In the following table, an X indicates whether a command is available for a node (Broker) and/or Server.

Line Command | Description | Broker | Server
--- | --- | --- | ---
`PI` | Broker node: Pings all RPC servers defined for the selected EntireX Broker. Server: Pings the selected RPC server. See also the `SYSRPC PING` direct command. | X | X
`TE` | Terminates a server task of the selected RPC server. See also Terminating an RPC Server. |  | X
`TS` | Terminates all server tasks of the selected RPC server (EntireX Broker service). See also Terminating an RPC Server. |  | X
`TI` | Trace information. Gets the current value of the trace level. Broker node: Shows trace information for all RPC servers defined for the selected EntireX Broker. Server: Shows trace information for the selected RPC server. | X | X
`Tn` | Dynamically sets the trace level for the selected RPC server to n, where n can be a value between `0` and `9`. `T0` means that tracing is disabled. |  | X
`T*` | Opens a window to enter the trace level n and the write-on-error option (`E`) for the selected RPC server. |  | X
`LN` | Lists all server tasks with their sequence number for a selected RPC server. You can execute a command for a single server task from this list. Or you can execute a command for all server tasks. See also Executing Commands for RPC Server Tasks. |  | X
`LS` | Lists RPC servers registered on the selected EntireX Broker. See also the `SRVLIST` direct command. | X | X
`IV` | Lists the versions of the selected EntireX Broker and its Command and Information Services (CIS) and the version of the EntireX Broker stub. | X | X

## Pinging an RPC Server

You can ping an RPC server from the standard or extended message view of the Server Command Execution screen or by using the `SYSRPC PING` direct command.

For information on pinging an RPC server by using the Application Programming Interface USR2073N, see the appropriate Natural RPC (Remote Procedure Call) documentation.

The following section provides instructions for pinging an RPC server from the standard view of the Server Command Execution screen.

To ping an RPC server from the Server Command Execution screen

1. In the Cmd column next to the server(s) to be pinged, enter the following line command:

       PI

   as shown in the example of a Server Command Execution screen below:

        16:41:32            ***** NATURAL SYSRPC UTILITY *****              2016-07-18
                                 - Server Command Execution -         Library SAGTRPC2

           Cmd Node                         Server                           Message
        1   __ ETB045
        2   PI                                NRPC001
        3   PI                                NRPC002

       Command ===>

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  ERR   Exit        -H    +H    -P    +P    TOP   BOT    >    Canc

2. Choose ENTER. The server(s) return the message:

       Server version on operating system

   where

   Server denotes the type of server; version denotes the version operating system denotes on which operating system the server runs.

   Example message:

       Natural RPC Server 8.3.7.0 on WNT-x86

   If pinging the server fails and an error occurs instead, you can choose PF2 (ERR) to display RPC-related Natural and EntireX Broker messages as described in Using the RPCERR Program (Monitoring the Status of an RPC Session, Natural RPC (Remote Procedure Call) documentation).

   The full messages are automatically displayed in the extended message view of the Server Command Execution screen (and PF11 is set to the less (<) sign).

3. If you choose PF11 once more or enter the less (<) sign in the Command line at the bottom of the screen, the standard view of the Server Command Execution screen is shown again (see also Example of a Standard View).

This section covers the following topic:

- Using the SYSRPC PING Direct Command

### Using the SYSRPC PING Direct Command

You can ping an RPC server by using the `SYSRPC PING` direct command in online or batch mode.

The following command syntax applies:

`SYSRPC PING` |  | `server-name` `ON` `broker-name` `[[``PORT``]` `port-number``][``TRANSPORT` `{TCP|SSL|NET}]` `ALL` |

The symbols used in the syntax diagram are explained in the section Syntax Symbols in the Statements documentation.

The syntax elements are explained in the following table:

Syntax Element | Format/Length | Description
--- | --- | ---
`server-name` | A32 | Name of an RPC server or a range of names An asterisk (`*`) selects all names, asterisk notation selects all names that start with the specified value.
`broker-name` | A32 | Name of the EntireX Broker or a range of names An asterisk (`*`) selects all names, asterisk notation selects all names that start with the specified value.
`port-number` | N5 | Port number of the network address used for the server connection Valid values: `0` to `65535`
`TRANSPORT` | A3 | Transport method used by EntireX Broker:
`TCP` | TCP/IP protocol
`SSL` | SSL or TLS
`NET` | Entire Net-Work (not supported on Linux or Windows)
`ALL` | n/a | Pings all RPC servers defined in the service directory of the current library.

## Terminating an RPC Server

The following commands are available to terminate an RPC server or EntireX Broker service from the standard or extended message view of the Server Command Execution screen:

`TE`: | Terminates a single RPC server task by sending an internal message to the RPC server. If an RPC server is associated with multiple RPC server tasks (including replica on z/OS platforms), you can either terminate each RPC server task separately by using `TE`, or terminate all RPC server tasks in one go by using the `TS` command.
`TS`: | Terminates all server tasks associated with an EntireX Broker service by calling EntireX Broker's Command and Information Services (ETBCIS; for details, see the EntireX documentation). The term `service` here summarizes all server tasks that run with the same server name on the same or on different platforms.

The following section provides instructions for terminating a single RPC server task or an EntireX Broker service from the standard view.

For alternative methods of terminating servers, see Terminating a Natural RPC Server described in the Natural RPC (Remote Procedure Call) documentation.

To terminate a single RPC server task

1. In the Code field of the Client Maintenance menu, enter the following command:

       XC

   The standard view of the Server Command Execution screen is displayed.

2. In the Cmd column, next to the server(s) to be terminated, enter the following line command:

       TE

   (This is similar to entering the command `PI` as shown in the example of pinging a server.)

3. Choose ENTER.

   The server returns the message:

       Terminating Server version on operating system

   where

   Server denotes the type of server; version denotes the four or five-digit product number; operating system denotes the operating system the server runs.

   Example message:

       Terminating Natural RPC Server 6.3.1.0 on WNT-x86

   If terminating the server fails and an error occurs instead, you can choose PF2 (ERR) to display RPC-related Natural and EntireX Broker messages as described in Using the RPCERR Program (Monitoring the Status of an RPC Session, Natural RPC (Remote Procedure Call) documentation).

   The full messages are automatically displayed in the extended message view of the Server Command Execution screen (and PF11 is set to the less (<) sign).

4. If you choose PF11 once more or enter the less (<) sign in the Command line at the bottom of the screen, the standard view of the Server Command Execution screen is shown again (see also Example of a Standard View).

5. If the Logon option is set in the service directory, logon data (user ID, password and library name) is sent to the server with the `TE` command, as is usual for remote `CALLNAT` execution. The Security Token Data window pops up and requests input of user ID and password if no Natural Security is installed on the client side and no logon data is set with the Application Programming Interface USR1071N for the current Natural session. See also USR1071N described in Using Security, Using Natural RPC with Natural Security, in the Natural RPC (Remote Procedure Call) documentation.

   If `LOGONRQ=ON` (see also Using Security in the Natural RPC (Remote Procedure Call) documentation) has been set on the server side, logon data must be sent from the client with the `TE` command.

   If Natural Security is installed on the server, the logon data transferred must enable a logon to the Natural system library SYSRPC.

To terminate an EntireX Broker service

1. In the Code field of the Client Maintenance menu, enter the following command:

       XC

   The standard view of the Server Command Execution screen is displayed.

2. In the empty column between the sequence number and the Node column, in the line which belongs to the server to be terminated, enter the following command:

       TS

   (This is similar to entering the command `PI` as shown in the example of pinging a server.)

3. Choose ENTER.

   The SYSRPC - Terminating EntireX Broker Service window appears.

4. If required for the logon, enter the appropriate user ID and password for EntireX Broker.

   If you want to terminate server tasks that are involved in a conversation, in the Terminate immediately field, enter a `Y` to request immediate termination. If you enter an `N` (this is the default setting), all server tasks involved in a conversation remain operational.

   If you do not want this window to appear repeatedly during the current SYSRPC session, choose Do not show this window again.

5. Choose ENTER to terminate the EntireX Broker service.

## Executing Commands for RPC Server Tasks

First, get an overview of all available RPC server tasks for an RPC server on the same or on different platforms registered on an EntireX Broker.

To get a list of all RPC server tasks with sequence number

1. In the Code field of the Client Maintenance menu, enter the following command:

       XC

   Choose ENTER.

   The standard view of the Server Command Execution screen is displayed.

2. In the Cmd column next to the servers, enter the following line command to list all server tasks:

       LN

   Choose ENTER.

   The Server Command Execution screen on server task level is displayed with the list of all server tasks for an RPC server. The following information is shown:

   Column | Description
   --- | ---
   SequenceNo | The number assigned to the server task in the sequence in which the task was registered on EntireX Broker.
   Date | The date and time (UTC) when the server task was started.
   Time
   Host Name | The node where the server is hosted.
   Status | The status of the server. Possible status values are: `idle`, `busy`, `term` (for terminated), or `active` (for ping and trace commands).

   The application name and IP address (if available) are indicated in the line below each numbered row.

   The application name depends on the environment where the server runs. It can be the name of a Natural image (on Linux), an LPAR (on z/OS) or a CICS started task, for example.

   The IP address shows the IPv4 or IPv6 address of the node.

   You can use PF keys to navigate in the screen and return to the list of all servers on the Server Command Execution screen (PF3) or the Client Maintenance menu (PF12).

3. Do one of the following:

   - For a single server task
     In the Cmd column, next to the sequence number of the server task, enter one of the following commands.

   - For all server tasks
     Press PF4 (Cmds) and enter one of the following commands into the input window.

   For information on executing a command for an RPC server task by using the Application Programming Interface USR9204N, see the appropriate Natural RPC (Remote Procedure Call) documentation.

   Command | Description
   --- | ---
   `PI` | Pings a single server task or all server tasks of an RPC server.
   `TE` | Terminates a single server task or all server tasks of an RPC server.
   `TI` | Trace information. Gets the current value of the trace level for a single server task or for all server tasks of an RPC server.
   `Tn` | Dynamically sets the trace level for a single server task or for all server tasks of an RPC server to n, where n can be a value between `0` and `9`. `T0` means that tracing is disabled.
   `T*` | Opens a window to enter the trace level n and the write-on-error option (`E`) for a single server task of an RPC server. You can also set the trace levels `T1E` to `T9E` for all server tasks of an RPC server using the PF4 (Cmds) key.

   Wichtig
   The commands `PI`, `TI`, `T0`, `T1` to `T9`, and `T1E` to `T9E` are rejected if the CIS version used by the current Natural session is not high enough to support the requested EntireX command (required: EntireX Broker 11.0 with CIS version 13 and higher). You can check the CIS version of the EntireX Broker using the `IV` command on the Client Maintenance menu.

   Choose ENTER.

   The RPC server returns the message, the error message and the changed status for the requested server tasks.

   On the first information line of the server task, the message would be `Successful response` (after terminate), the ping information, or the trace level.

   On the second information line of the server task, the error message is shown with the error number and an error text, such as `Participant not found` (when the server task is already terminated), `Function disallowed by Natural Security`, or `Command SEND-COMMAND not supported` (when the CIS version does not yet support the command, see the important note above).

### On this page

- Using Server Command Execution
- Pinging an RPC Server
- Terminating an RPC Server
- Executing Commands for RPC Server Tasks