Administering the EntireX RPC Servers using System Management Hub

The System Management Hub RPC server agent provides a user-friendly interface for managing and monitoring the EntireX RPC servers.

The System Management Hub is Software AG's cross-product and cross-platform product management framework. This section assumes that you are familiar with the System Management Hub software. The basic concepts of this product, its installation and the System Management Hub features common to all Software AG products are described in the separate System Management Hub documentation.

This document covers the following topics:


Introduction

The RPC server agent distinguishes between two kinds of RPC server, based on their locations:

  • Local
    A local RPC server needs to run on a machine where the SMH is installed. In addition to starting and stopping RPC servers, the RPC agent provides support for editing the configuration file and monitoring the server data.

  • Remote
    Remote RPC server functionality is only available for RPC server platforms where the SMH is not available, such as z/OS and IBM i. For remote RPC servers the System Management Hub RPC server agent provides monitoring functionality only. Starting and stopping RPC servers and editing an RPC server's configuration file are not supported.

Adding a Local RPC Server

Start of instruction setTo add a local RPC server

  1. Select the root node of the RPC server tree in the tree-view frame.

  2. From the context menu, choose Add Local. The following dialog window will be displayed.

    add local server

Server

This name will be displayed in the RPC server tree.

SMH Control Port

Set an SMH Control Port for the RPC server configuration port. This TCP/IP port must be unused on your machine and unique to the RPC server settings. This port is required for intercommunication between the RPC server and the RPC server agent. The C RPC Server as well as the Java RPC-based server has a corresponding parameter in the configuration/property file. The SMH Control Port option in the Add Local RPC Server dialog will be used as command-line parameter while starting the RPC Server.

Since the command-line parameters have higher priority, the configuration/property file settings will be ignored if command-line parameters are used. See Customizing the Java RPC Server under UNIX | Windows and Configuring the RPC Server under UNIX | Windows.

Properties, Configuration

Enter the full path name of your RPC server's configuration file and/or property file. The System Management Hub agent requires this file name to open it in the editor. See also Command Functions for Local RPC Servers under Operating and Monitoring the RPC Servers using System Management Hub. For example: the EntireX XML/SOAP RPC Server requires a configuration file as well as a property file. It is useful to enter both names to edit and view these files. The edit command buttons will only be available if the corresponding field is filled. See EntireX\config directory for some examples of configuration and property files.

Note:
Use an absolute path for the file name. See also Working Directory.

Start Script

The start script will be called when the RPC server is started.

The SMH RPC server agent uses the execute script in the Start Script line to start the RPC server. Only a batch or command script file under Windows and a shell script file under UNIX to start the RPC server, where other settings will be made, such as the CLASSPATH setting for the Java server or Configuration file settings for the C RPC Server, are allowed. Some example files are provided in the directory <EntireX installation Directory>\SMH\scripts.

The SMH RPC server agent only allows files with the file extensions in the table below to start scripts. Other file extensions will cause a starting error. If the file extension is changed, the RPC server agent does not check the contents of the file to determine whether the file format matches the file extension.

Operating System File Extension
Windows

.bat
.cmd

UNIX

.sh
.csh
.bsh
.ksh

The start script option may only contain the name of the batch or shell script for starting the RPC Server. If additional parameters are required, use the Start Option line to submit these to the start script.

This start script line will be extended with the parameter -smhport port number (from the SMH Control Port option) as the first parameter when starting the RPC server.

Note:
Use an absolute path for the file name. See also Working Directory.

Start Options

The start options will be connected to the start script as a start parameter.

For example: use the start option cfg=path\server.cfg to start the rpcserver with a configuration file. The entries on the Configuration and Property files will not be used automatically as start parameters.

For the corresponding start parameters of the RPC Server, see Customizing the Java RPC Server under UNIX | Windows and Configuring the RPC Server under UNIX | Windows.

Note:
If the path includes blank spaces, the entire option must be enclosed in quotation marks. All path names used must be absolute path names. The RPC server agent does not try to resolve relative path names.

Logging

If the Logging option has been entered, the Start script line will be extended with a pipe to redirect the standard out and standard error to these files. These log files can be viewed with the SMH's built-in viewer.

Working Directory

The working directory will be set by the RPC Agent when the start script is called. Relative file names in the option Properties, Configuration, Start script and Logging will be extended with the working directory while saving. If the working directory line is empty, the path of the SMH service (Windows) / daemons (UNIX) will be used as default.

Save

After confirming the settings for the new RPC Server Item with Save, the server is ready for use with the System Management Hub.

Adding a Remote RPC Server

Remotely configured servers can only run on platforms where SMH is not available. Therefore the RPC server needs to be started and stopped by the owner of the RPC server. The RPC server does not have the monitoring functionality enabled automatically. It must be started with the start parameter -smhport unique tpc/ip port to enable the monitoring functionality.

Start of instruction setTo add a remote RPC server

  1. Select the root node of the RPC server tree in the tree-view frame.

  2. From the context menu, choose Add Remote. The following dialog window will be displayed.

    add remote server

Server

This name will be displayed in the RPC server tree.

Host

This is the network name or the IP address of the host system where RPC server runs.

SMH Control Port

System Management Hub Control port on which the RPC server listens. The owner of the server must configure the RPC server on this TCP/IP port. Please see the corresponding RPC server documentation. See also Customizing the Java RPC Server under UNIX | Windows and Configuring the RPC Server under UNIX | Windows.

Note:
The hostname and TCP/IP port will not be checked for validation. The user is responsible for the input in these fields. If the same hostname and port are used for server entries twice or more, the same status will be displayed for each server.

Operating and Monitoring the RPC Servers using System Management Hub

The System Management Hub RPC server agent distinguishes between local and remote RPC servers. The functionality changes depending on the location. For local RPC servers, the System Management Hub GUI environment provides full control. For remote RPC servers, only monitoring functionality is provided.

This section covers the following topics:

Select Root Node of the RPC Server

Once the root node of the RPC server has been selected, the RPC server agent retrieves the following information and displays it in a table. This information is available for both locally and remotely monitored RPC servers regardless of the RPC server type. See SNMP Support for EntireX and SNMP Interface in the separate System Management Hub documentation.

Property Description Note
Server Name of the Server.
This is the name of the server in the SMH interface which was entered when the RPC Server was added.
 
Status Status of the server.
Running, Down, Retry.
1,2
Started Start-time of the server.  
Worker Current number of worker threads.  
High Worker threads high watermark.  
Name Host name / JES job name. 3
Address Network address. 4

Notes:

  1. The status may be "Init" and "Shutdown" for the XML Servers. The status "Down" will be generated in the System Management Hub RPC server agent if communication with the RPC server is not available.

  2. Status
    Status Description
    Running The server is running normally.
    Down The server is not running or the RPC server was started without the System Management Hub control port option. The System Management Hub RPC server agent cannot connect to the RPC Server.
    Retry The RPC Server has no connection to the Broker and is trying to connect or reconnect.
    Init The RPC server is just starting and is not yet ready on the RPC interface.
    Shutdown The RPC server is just shutting down and will be down in a moment.
    Error Any error that could not be recovered and leads to shutdown of the server, for example: 0021 0043: ATTR: Service definition not found.
  3. This display depends on the RPC Server and the platform where the server is running. On UNIX and Windows (local servers) only the Hostname will be displayed. Under IBM i, the RPC Server will also display the JES job name if available.

  4. This display shows the IP or Net-Work address of the RPC Server where the server is running.

Select an RPC Server

Each RPC server has a common, scalable part and a server-specific part. Therefore the property information may differ for each server type.

For local servers, the top of the display in the right-hand panel is generated by the System Management Hub RPC server agent and represents the input made when the RPC server was added. For remote RPC servers, the first three lines are generated by the System Management Hub RPC server agent and also represent the input made when the RPC server was added.

The subsequent empty line separates the information generated by System Management Hub RPC server agent from the retrieved information.

See also EntireX RPC Servers, Listeners and Bridges.

Each RPC server may also have subtables which depend on the RPC Server type and the platform where the RPC server is running. If the RPC servers have subtables, the RPC server node is expandable and shows a "+" (plus sign) in front of the node name.

Command Functions for Local RPC Servers

Once a local RPC server has been selected in the SMH tree view, the following RPC Server control commands will be available:

Function Description
Modify Opens a dialog window to modify the selected RPC server settings which were made when the local RPC server was added to the SMH environment. (See note below.)
Delete Removes the name of the selected RPC server from the RPC server tree. No files will be removed with this action. (See note below.)
Start Starts the selected RPC server. This function calls the entry from the Start script input line. (See note below.)
Stop Sends a terminate command to the selected RPC server. (See note below.)
Edit Properties Opens the properties file of the selected RPC server which was entered in the Property File line. (See note below.)
Edit Configuration Opens the configuration file of the selected RPC server which was entered in the Configuration File line. (See note below.)
Edit Start Procedure Opens the file which was entered in the Start script line for the selected RPC server, if this file was an editable file. (See note below.)
Tracelevel Opens a dialog window to select the trace level and sends a change trace level command with the selected trace level to the RPC server.

Note:
The System Management Hub employs the multi-user concept. If more than one user modifies, deletes or edits the same RPC Server Item at the same time, the data of the user who saves last will overwrite the modifications of any previous user(s). Start and Stop commands may also be used by multiple users. We recommend using the Refresh command to update the status of the RPC Server before starting or stopping it.

Command Functions for Remote RPC Servers

Once a remote RPC server has been selected in the SMH tree view, the following RPC Server control commands are available:

Function Description
Modify Opens a dialog window to modify the selected RPC server settings which were made when the remote RPC server was added to the SMH environment. (See note below.)
Delete Removes the name of the selected RPC server from the RPC server tree. No files will be removed with this action. (See note below.)
Tracelevel Opens a dialog window to select the trace level and sends a change trace level command with the selected trace level to the RPC server.

The commands Start and Stop for the RPC server are not available for remotely managed RPC servers. The System Management Hub RPC server agent provides only monitoring functionality for this kind of server; it does not provide the Edit and View Configuration functions or the Start Batch Files function.

Note:
The System Management Hub employs the multi-user concept. If more than one user modifies, deletes or edits the same RPC Server Item at the same time, the data of the user who saves last will overwrite the modifications of any previous user(s).

Tracing Hints

UNIX

The trace will work under UNIX as usual.

Windows

If the C RPC Server under Windows was used, the trace destination may change. If the TraceDestination option was not defined in the configuration file, the C RPC Server under Windows will write its trace file for the user SAGUSER. The System Management Hub will start the RPC Servers on behalf of the user SAGUSER.

For more information on the tracing location, see table entry Trace File/Location on the corresponding RPC server. The table entry will only be available if the RPC server is running.

See also Activating Tracing for the RPC Server under z/OS (CICS, Batch, IMS) | UNIX | Windows | z/VSE (CICS, Batch) | IBM i.

Batch Interface

The RPC server agent supports the System Management Hub's batch interface. The table below contains the corresponding batch commands.

Task Batch Command Note
List all defined RPC servers on the managed host. show rpcserverlist  
Show detailed information on the <rpc server> show rpcserver name=<rpc server name>  
Start the <rpc server> start rpcserver name=<rpc server name> 1
Stop the <rpc server> stop rpcserver name=<rpc server name> 1

Note:

(1) Only local RPC server can be started or stopped with this command. Attempts to start and stop remote RPC servers will fail.

Example:

Assume that your RPC Server is defined with the node name "RPC Server1" in your SMH environment. Enter the argbatch command with the following parameters to execute the batch command.

argbatch show rpcserver user=[userid] password=[passwd] target=[managed host name] "product=webMethods EntireX 9.9" "name=RPC Server1"

Note:
argbatch is part of the System Management Hub software. It is located in the bin directory of the System Management Hub installation.

See The System Management Hub Batch Interface in the System Management Hub for EntireX documentation.