Version 5.3.1
 —  Natural Business Services Administration  —

Defining and Managing Servers

Servers automate the interaction between business service components and EntireX, freeing developers from the task of coding calls. Servers also control such application-independent facilities as security and error recovery. EntireX controls the compression, encryption, and data translation facilities.

Natural Business Services provides predefined dispatch, security, and attach servers you can modify to suit your needs. You choose how the servers are initiated (for example, in individual batch jobs or as subtasks of an attach server). You can also create your own servers.

Once you have modified or created servers for your system, you can test, initiate, shut down, and ping them (determine if they are running). You can also view query information about the servers.

Note:
If you are using SPoD for development only, you do not need to define and manage the servers until the code is required at runtime (for example, to execute a business service from Visual Studio, Java, or a Web service).

This section covers the following topics:


Types of Servers

The three types of servers are:

Server Type Description
Attach Server that starts other servers. When defining dispatch, security, or user-defined servers, you can associate them with an attach server. If a server is intended to execute as a subtask, the attach server must be executing before the servers associated with it can be started. Attach servers can be used to automatically start other servers on demand.

Note:
For more information, see Attach Servers.

Server Program that registers a service with EntireX and enters a receive loop waiting for clients to request its services. Initiating a server causes the common start facility (SPSSTART) to automatically logon and register with EntireX. Servers can also act as Broker clients. Servers implement two kinds of interfaces: main and command.

Note:
For more information, see Main and Command Interface Services.

Client User of services. Client servers do not register services with EntireX, but request the use of services by sending a message to a server. When clients are started, no implicit commands are executed. Normally, client servers are only used to define a Broker ID, user ID, and password required to logon to EntireX.

Main and Command Interface Services

All servers implement two interface services: main and command. The main interface service is defined on the Maintain Servers panel, where the service field always contains the value, MAIN. The command interface service uses the same server class and server name, but it uses the CMD Broker service name. For example:

Interface Server Class Server Name Broker Service Name
Main BUSINESS DISPATCH MAIN
Command BUSINESS DISPATCH CMD

Note:
The Server class, Server name, and Broker service name must be defined in the Broker attribute file.

The main interface service implements commands that are specific to the server. The command interface service implements commands that are independent of servers; that is, commands that are generic and applicable to all servers, such as PING and SHUTDOWN. Having separate servers allows you to automate the server startup process in response to some server services but not others. For example, a dispatch server should be automatically started when a dispatch request is received, but commands such as PING and SHUTDOWN should not cause a new server to be launched.

The command interface services are:

Command Description
PING Determines whether a server is available.
ENVIRONMENT Retrieves information about the environment in which the server is running.
TRACE Sets trace options to help debug a server or service.
CALLNAT Executes a user-supplied subprogram.
SHUTDOWN Ends a server.
ERROR Triggers a runtime error in the server.
STEPLIBS Lists the steplibs associated with the server.
SYSPROF Returns information about the system files used by a server.

Note:
When sending command interface services programmatically, use the syntax: CMD command, where command is one of the commands listed above.

Top of page

Define Servers

Use the Maintain Servers panels in the Business Service Administration subsystem to define servers. You can create the following types of servers:

This section describes how to access and use the Maintain Servers panels. It also describes how to add information to the Broker attribute file and create a Natural profile to initialize a server at runtime.

The following topics are covered:

Access the Maintain Servers Panels

Start of instruction setTo access the Maintain Servers panels:

  1. Enter "SA" in Function on the Business Service Administration Subsystem main menu.

    The System Administration main menu is displayed.

  2. Enter "MM" in Function on the System Administration main menu.

    The System Administration Maintenance menu is displayed.

  3. Enter "SE" in Function on the System Administration Maintenance menu.

    The first Maintain Servers panel is displayed. For example:

     SPBSMD     ***** Business Service Administration Subsystem *****      SPBSMD11 
     Feb 14,06                   - Maintain Servers -                      1 more > 
                                                                                    
      Action (A,B,C,D,M,N,P)    _ Name: ________________________________            
                                  Desc: ________________________________________    
     +- Broker Server Settings ---------------------------------------------------+  
     | Broker ID...............: ________________________________                 | 
     | Server class............: ________________________________                 | 
     | Server name.............: ________________________________                 | 
     | Broker service name.....:                                                  | 
     | Disable trusted user....: _     **Watch size and case for userid password  | 
     | User ID.................: ________________________________                 | 
     | Password................:                                                  | 
     | Attach Server name......: ________________________________ * Attach..: _   | 
     +- Server Start Parameters --------------------------------------------------+ 
     |>                                                                           | 
     |>                                                                           | 
     |>                                                                           | 
     | Server start routine....: ________ *       Source          Object          | 
     +----------------------------------------------------------------------------+ 
     Command: ____________________________________________________________          
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
     confm help  retrn quit        flip  pref                    left  right main   
                                                                                    
    
  4. Provide a name for the server and specify the Broker server settings.

    For information, see Identify the Server and Define Broker Service Settings.

    Optionally, you can specify the following settings; not all of these settings are appropriate to all types of services:

  5. Assign a server start routine for the server.

    For information, see Use Server Start Routines.

  6. Press PF11 (right).

    The second Maintain Servers panel is displayed. For example:

    SPBSMD     ***** Business Service Administration Subsystem *****      SPBSMD21 
    < 1 more                    - Maintain Servers -                       8:52 PM 
                                                                                   
     Action (A,B,C,D,M,N,P)    _ Name: ________________________________            
                                 Desc: ________________________________________    
    +- Server Settings ----------------------------------------------------------+ 
    | Server type.............: _ (Server, Attach server, Client)                | 
    |                                                                            | 
    | Default language........: __    Server Version.....: ___                   | 
    |                                                                            | 
    | Server timeout..........: _____                                            | 
    |                                                                            | 
    | Unique ID...............:                                                  | 
    +----------------------------------------------------------------------------+ 
    +- Program Parameters -------------------------------------------------------+ 
    |>                                                                           | 
    |>                                                                           | 
    |>                                                                           | 
    | Natural program name....: ________         Source          Object          | 
    +----------------------------------------------------------------------------+ 
    Command: ____________________________________________________________          
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
    confm help  retrn quit        flip  pref                    left  right main   
    
  7. Define the server timeout value, default language, and program parameters.

    These settings configure the server internally. Depending on the server type, you must define some or all of these settings. For information, see Define Server Settings and Program Parameters.

  8. Press Enter to confirm the settings.

Identify the Server

Use the following fields on the first Maintain Servers panel to identify and describe the server:

Field Description
Name Unique identifier for the server.
Desc Brief description that assists you in identifying the server. Be sure to make the description distinctive, since it is used on other panels to help identify the server.

Define Broker Service Settings

Use the following fields on the first Maintain Servers panel to specify the parameters the server needs to register with EntireX:

Field Description
Broker ID Broker identifier. Each installation of EntireX is assigned a Broker ID. This number uniquely identifies EntireX to your network. If you do not know the Broker ID, see your organization’s network administrator.

Specify the ID number for the broker being used. For example, if you are using EntireX designated as number 45, the Broker ID must contain 045 somewhere in the ID, such as BKR045, BID045, or B045NODE. Ensure that the Broker ID only contains one such numeric component.

Note:
If a type S server specifies an attach server, there is no need to supply a Broker ID because it is automatically assigned to match the Broker ID for the attach server.

Server class Name of the Broker class used to logically organize the environment in which the servers are running. For example, BUSINESS-PROD for production services or BUSINESS-TEST for services running in a test environment.
Server name Name of the Broker server used to logically describe a server (rather than the name of the program that implements the server). This allows you to change the program name without affecting the client programs that use the service. For information, see Supplied Server Names.
Broker service name Name of the Broker service. This field is always assigned the value, MAIN. For information, see Main and Command Interface Services.

The Server class, Server name, and MAIN and CMD Broker service names must be defined in the Broker attribute file for the specified broker. For information, see Change the Broker Attribute File.

User ID and Password Values corresponding to values the server will use to assign the corresponding fields in the EntireX control block when making calls using the EntireX ACI (Advanced Communication Interface).
Attach server name Name of the attach server used for type S servers.
  • If the server is initiated automatically on demand, specify the name of the attach server used to launch the server and mark Attach.

  • If the server is initiated manually, only specify the name of the attach server; do not mark Attach.

Note:
For information on attach servers, see Attach Servers.

Attach If this field is marked, the server is initiated automatically on demand. If this field is blank, the server is initiated manually.

On startup, a server uses these parameters to tell EntireX that it is running and ready to handle requests. Later, you will add some of this information to the Broker attribute file.

Note:
For information, see Change the Broker Attribute File.

Supplied Server Names

The following table shows the server names supplied with Natural Business Services, along with the name of the Natural program that implements the service:

Server Name Natural Program Description
ATTACH SPSATT Attach server
DISPATCH SPSDISP Dispatch CALLNAT requests
SECURITY SPSSEC Security server
TIMESTAMP SPSTIMS Timestamp demo service

Attach Servers

EntireX supports an automated server startup mechanism by means of an attach server. An attach server typically registers its own service with EntireX and then registers other servers it is capable of starting using an attach option. When a request is made for an attach server and no server is available (waiting in a receive state), EntireX notifies the attach server that a request is pending. Normally, that attach server launches a new server to satisfy the request.

This section covers the following topics:

Link Servers to an Attach Server

An attach server must be defined on the second Maintain Servers panel using Server type A (attach). All servers that the attach server automatically launches must specify the name of the attach server and have Attach marked on the first Maintain Servers panel. This tells the attach server to register the current main interface service with EntireX using the Attach option.

Note:
For servers that are only to be launched manually, specify the attach server name without marking Attach.

The combination of Server class, Server name, and Broker service name must be unique for all servers that are linked to an attach server and have Attach marked.

An attach server can launch servers as separate batch jobs or as subtasks of the attach server. For information, see Use Server Start Routines.

Note:
The attach server only registers the main interface for servers it is capable of launching. Therefore, commands such as PING and SHUTDOWN (which go to the command interface) will not cause a server to be launched.

Activation Policies

Each time EntireX calls an attach server to satisfy an attach request, the attach server launches one instance of the requested server. This server continues to run indefinitely as long as it is satisfying server requests. If the server stays idle for longer than its timeout period (specified on the second Maintain Servers panel), it shuts down.

Runtime Error Handling

If a server receives a runtime error, its restart policy depends on whether it is linked to an attach server. If the server is not linked to an attach server, it attempts to recover from the error. Otherwise, the server shuts down as a result of the error.

Common Server Startup Interface

The main method of starting servers is using the START command. This section describes the different parameters you can use with the START command, depending on the type of server and the method of initiating it.

For servers of type S or A, the START command takes care of logging onto EntireX and registering the required Broker services. It then invokes the Natural program specified on the second Maintain Servers panel.

This section covers the following topics:

Use the START Command to Initiate Servers as Subtasks

When you are using an attach server to initiate a server, the START command does not require any parameters. The system automatically uses the name of the server being defined. For example, the following parameters can be used to start the current server as a subtask of an attach server:

Server Start Parameters                                                   
 > NATPARM='FNAT=(1,2),PROFILE=SYSBIZ                                        
 > STACK=(LOGON SYSBIZ;START)'                                               
 >                                                                            
  Server start routine...: SUBTASKB *       Source SYSBIZ  Object SYSBIZ
Use the START Command to Initiate Servers Online or in Batch Mode

To start a server online (from the Next prompt) or in an individual batch job, the START command must have at least one parameter: the name of the server to use for configuration on startup. For example:

START DISPATCHER

where DISPATCHER is the name of the server definition used for configuration.

Note:
The START command is a front-end to the SPSSTART program. When running servers from outside the SYSBIZ library, use SPSSTART rather than START to ensure access to the proper environment.

Define Server Start Parameters and Routines

Most servers are assigned a start routine to initiate the server in an individual batch job or through an attach server. The server start parameters and start routine fields are located at the bottom of the first Maintain Servers panel. The server start parameters differ depending on which server start routine is used: BATCHJOB or SUBTASKB.

Although the server start parameters are shown on three lines, internally these lines are treated as one long string value. To define parameters that span multiple lines, continue the parameter on the next line. For example:

 Server Start Parameters                                                  
 > JCL=BATCHTXT,JOB-PREFIX=AS,NATPARM='IM=D,PROFILE=SYSBIZ,
 > STACK=(LOGON SYSBIZ,MYUSERID,MYPWD)'                                           
 >                                                                           
 Server start routine...: BATCHJOB *       Source SYSBIZ  Object SYSBIZ  

We recommend that you use commas to delimit parameters, although you can also use blank characters. If a parameter ends on the last character of a line, and it is not to be concatenated with the parameter beginning on the next line, include a comma (or blank character) at the beginning of the next line.

This section covers the following topics:

Use Server Start Routines

All servers must be assigned a start routine (specified in Server start routine on the first Maintain Servers panel). The start routine defines how the Natural session that will host the server is initiated. Two start routines are supplied with Natural Business Services in source form. You can use one or both of these in most environments, or use them as examples for writing your own routine.

The supplied start routines are:

Start Routine Description
BATCHJOB Calls NATRJE to launch a batch job to host the server.
SUBTASKB Calls CMTASK to start a Natural subtask. This routine can only be used in Natural environments that support subtasks. In such environments, BATCHJOB is typically used to start attach servers and SUBTASKB is used to start other servers.

BATCHJOB Server Start Routine

The BATCHJOB server start routine launches a separate Natural batch job to host the server. All attach servers are started using this routine.

A Natural source member in the SYSBIZ library contains JCL templates you can copy and modify to create a customized BATCHTXT member. These templates are:

Note:
For more information, see Activate the Business Service Administration Subsystem.

The server start parameters must specify the name of the source member that contains the JCL template. The source member is identified by the JCL keyword and must exist in the library where the attach server that launches the server is running (usually the SYSBIZ library).

In most cases, you can use the default values defined in the BATCHJOB program or hardcoded in the JCL. For example, you can use the following parameters to start up a batch job:

JCL=BATCHTXT,JOB-PREFIX=XX

You can insert &keyword place holders in the JCL templates to create the JCL member. The place holders will be replaced with the keyword values. The keywords are:

Keyword Description
JOB-PREFIX Two-character prefix used with JOB-NAME to associate the job with the server. If JOB-NAME is to be uniquely generated, you can specify a two-character JOB-PREFIX keyword for each server. This value defaults to SP.
JOB-NAME Name of the job. Use the JOB-NAME keyword to explicitly name the job. In the JCL template, the &JOB-PREFIX&JOB-NR keyword is used to represent JOB-NAME.

Note:
Some operating systems do not allow multiple jobs with the same name to be run concurrently. Therefore, using the JOB-NAME keyword rather than the JOB-PREFIX keyword may cause a conflict.

TRANSACTION Name of the Natural nucleus under which the server runs. This nucleus must be linked to Natural Business Services load modules. The default transaction is NATBAT. You can also hardcode the desired transaction within the JCL member.

Note:
You can change the transaction name using CSRLOAD. For information, see Activate the Business Service Administration Subsystem.

NATPARM Natural parameters used when initiating the server. The default NATPARM is: 'IM=D, PROFILE=SYSBIZ'.
LIBRARY Name of the library to which you want to logon. This value defaults to SYSBIZ.
USER-ID Natural user ID used to logon to Natural. This keyword only applies to servers running under Natural Security. If the USER-ID value matches the user ID specified in the server settings, use *USER-ID.
PASSWORD Natural Security password associated with USER-ID. If this password matches the one specified in the server settings, use *PASSWORD (which prevents the password from being displayed on the current panel).
PROGPARM If the invoked server program accepts additional parameter values, they can be substituted for the PROGPARM keyword. These parameters can also be re-substituted with parameter values passed into SPCATT, which is used to launch a remote server from a client.

The following example supplies a full JOB-NAME, rather than just the prefix. It also overrides the NATPARM. Because the statement contains special characters, it must be embedded within quotes. For example:

JCL=MYJCL,JOB-NAME=TESTJOB,USER-ID=*USER-ID,PASSWORD=*PASSWORD, 
NATPARM='IM=D,FNAT=(1,2),PROFILE=QA'
Run Under Natural Security

If the server runs under Natural Security, you can include a user ID and password. The following example uses the user ID and password specified in the Broker service settings:

Service.................: MAIN
User ID.................: TECH1
Password................:
Initiate Multiple Dispatchers During Startup

During startup, the attach server can automatically initiate instances of another server (typically the dispatcher).

Start of instruction setTo initiate multiple dispatchers during startup:

  1. Add continuation characters after the &Q-CONV-ID parameter in the JCL member.

  2. Insert two lines.

  3. Type the logical name of the server to be initiated by the attach server on the first line.

    Include the continuation characters.

  4. Type the number of instances of the server to initiate on the second line.

    For example, see lines 0890, 0900, and 0910 below:

    0770 LOGON &LIBRARY                                                    
    0780 SPSSTART                                                           
    0790 &BUSINESS-SERVICE,%                                                
    0800 &USER-ID,%                                                         
    0810 %*                                                                 
    0820 &PASSWORD,%                                                        
    0830 &TRACE-OPTION,%                                                    
    0840 &TRACE-LOCATION,%                                                  
    0850 &Q-BROKER-ID,%                                                     
    0860 &Q-USER-ID,%                                                       
    0870 &Q-TOKEN,%                                                         
    0880 &Q-SECURITY-TOKEN,%                                                
    0890 &Q-CONV-ID,%
    0900 DISPATCH,%
    0910 5                                                        
    0920 &PROGPARM                                                          
    0930 FIN                                             
    

    Note:
    No error will occur if these two values are not specified.

SUBTASKB Server Start Routine

The SUBTASKB server start routine accesses, by means of EntireX, an attach server running in batch mode. The request to start the specific task is transmitted to the attach server. The attach server uses the data to start the requested server as an attached task inside the batch region.

Use this routine if you want the server to be executed as a subtask of an attach server. You must also specify an attach server name. To launch the current server, the attach server must be running.

Note:
For operating systems that support Natural’s subtasking feature, this is the preferred approach because fewer batch jobs need to be initiated.

When using SUBTASKB, specify the parameters required to start the subtask. The STACK parameter should include a LOGON to the SYSBIZ library and the required stack program. To only launch the current server, use the START keyword.

Note:
The STACK parameter differs depending on whether servers run under Natural Security or which AUTO parameter is specified in your NATPARM.

The SUBTASKB server start routine supports the following keywords:

Keyword Description
TRANSACTION Name of the Natural nucleus under which the server runs. This defaults to the same transaction as used by the attach server that launches the substask.
NATPARM Natural parameters used to initiate the server. The parameters can be any value allowed when initiating a Natural session.

This section covers the following topics:

Sample SUBTASKB Routines

The NATPARM is usually the only required parameter. The format of this parameter varies depending on whether or not you are using Natural Security.

The following example shows the SUBTASKB parameters without Natural Security:

Server Start Parameters
> NATPARM='FNAT=(1020,1000),PROFILE=SYSBIZ,
> STACK=(LOGON SYSBIZ;START)'

Because it contains special characters, the NATPARM parameter must be within quotes. In the example above, the START keyword invokes the common server startup facility. Once Natural is started, the Natural program name defined on the second Maintain Servers panel is invoked.

Under Natural Security, the Natural startup parameters are based on the value of the AUTO parameter in the NATPARM. The following example uses AUTO=OFF so that the user ID and password must be supplied. You can do one of the following:

Write to Print and Work Files

Programs executed by a dispatch server running in batch mode can write information to a print or work file. When doing so, the batch job that initiates the server (the attach job if you are using an attach server) must define the necessary output devices. For example: CMPRTnn and CMWKFmm.

Generate Trace Output

If you experience problems initiating or running servers, you can trace the flow of the Natural Business Services software to help uncover the problem or to provide additional information to Software AG support. To generate trace output, stack the TRACE command prior to initiating the desired server.

Note:
If you intend to use the Trace function, printer 2 and 3 must be assigned to batch mode. For information, see Define the NATPARM.

The following example shows the parameters to enable tracing:

 Server Start Parameters                                                   
 > NATPARM='FNAT=(1,2),PROFILE=SYSBIZ,                                       
 > STACK=(LOGON SYSBIZ;TRACE;START)'

You can also pass a number from one to five to the TRACE command, which causes the trace output to be written to CMPRT01 through CMPRT05, respectively. Or, you can pass W1 through W5, which causes the trace output to be written to CMWKF01 through CMWKF05, respectively.

Note:
You can also write additional server start routines that are applicable to other environments. Use the BATCHJOB and SUBTASKB programs as templates.

Define Server Settings and Program Parameters

Use the second Maintain Servers panel to define the server settings used internally to configure the server (for an example of this panel, see Access the Maintain Servers Panels). The fields on this panel are:

Field Description
Server type Type of server. Specify one of the following:
  • A (attach)

  • S (normal)

  • C (client )

The START program automatically performs a broker Logon and Register for type A or S servers.

Default language Value assigned to the Natural *Language system variable on server startup.

The server uses this value to determine which language to use when returning messages to the client. The client can override this value when making a request, but the server always returns to the default value after servicing a client.

Server timeout Amount of time the server will continue to run after the last time it serviced a client request.

Normally, attach servers should never time out, as they are required to launch all other servers. Therefore, specify a high timeout value, such as 9999H, for attach servers.

The problem with allowing other servers to time out is that users may experience a slight delay whenever a new server must be started to satisfy a request. But high timeout values may result in many idle servers consuming system resources. For most servers, 30 to 60 minutes is recommended.

The server timeout value is specified as a numeric value or as a number suffixed with an interval. If there is no interval suffix, the number is assumed to specify seconds. Valid interval suffixes are:

  • S (seconds, for example, 3600S)

  • M (minutes, for example, 60M)

  • H (hours, for example, 3H)

Unique ID 16-character unique ID. This derived value is used as the prefix for the TOKEN field in the Broker control block. This allows Natural Business Services to associate a running server with a server record.
Program Parameters Additional parameters to allow servers to configure themselves. The following program parameters are required by the supplied servers:
  Dispatch server
SECURITY-SERVER=server-name

Name of the server that the dispatch server communicates with to retrieve security information.

SECURITY-MODE=value

Parameter used to disable/enable security checking by specifying the security mode. When security is disabled, the security server is only used to look up program names and library information. When enabled, the security server uses the security mode to initiate the security check. This parameter can have the following values:

  • NONE

    No security; program names and libraries are checked

  • APPL

    Natural Business Services authenticates users and checks authorizations and application-level security

  • NSC

    Natural Security authenticates users and checks authorizations

  • SAF

    EntireX authenticates users and checks authorizations

  • SAF-APPL or SAF-NSC

    Hybrid security server is used (for information, see Use a Hybrid Security Server with Natural Business Services)

By default, SECURITY-MODE=NONE. If you change the SECURITY-MODE value, clear the security cache record.

  Attach server
CONVERSATION-FACTORY=server

This parameter identifies the server record that defines the Broker settings used to generate conversations when using the SQU* API.

Natural program name When the START command is used, this parameter identifies the program invoked by the common start facility to implement the server.

Change the Broker Attribute File

The values specified in the Server class, Server name, and Broker service name fields on the first Maintain Servers panel must also be defined in the Broker attribute file for each server. EntireX requires these attributes to identify servers and their characteristics. In addition, you must add the Broker server definitions required by the command interface services. These are the same as the main interface services, with the Broker service name of CMD instead of MAIN.

Notes:

  1. Each EntireX Broker has its own attribute file, so be sure to add the Broker service definition to the appropriate attribute file.
  2. You do not have to change the Broker attribute file until you start the server. Before doing that, someone with access authority must update the file. For information, refer to the EntireX documentation.

Add a Natural Profile

You can use Natural profiles to fully define a Natural environment. They are useful for reducing the amount of information you must supply when starting a Natural session. These profiles can be set up using the Natural SYSPARM utility.

Profiles can be useful when defining servers in the Administration subsystem. As part of defining a server, specify the server start parameters. Use the NATPARM keyword to identify the system file used to store the Natural profile.

Notes:

  1. For information on the SYSPARM utility, refer to the Natural Utilities documentation.
  2. For an example of creating a Natural profile, see Natural Business Services Installation on Mainframes.

Top of page

Manage Servers

Use the Manage Servers panel to initiate attach servers. Since all other servers can be initiated automatically (on demand) by an attach server, it is usually not necessary to initiate other servers in advance of their use.

When servers fail to start, you can also use the Manage Servers panel to help diagnose the problem. Additionally, you can use this panel to send inquiry commands to various servers to determine the environment in which they are running. Finally, you can use the Manage Servers panel to shut down servers.

Note:
You can also use a GUI application called the Server Monitor to manage servers. For information on using the Server Monitor, see NBS Server Monitor.

Start of instruction setTo access the Manage Servers panel:

  1. Enter "SA" in Function on the Business Service Administration Subsystem main menu.

    The System Administration main menu is displayed.

  2. Enter "MS" in Function on the System Administration main menu.

    The Manage Servers panel is displayed. For example:

     SPCMS      ***** Business Service Administration Subsystem *****        SPCMS0 
     Feb 14,06                    - Manage Servers -                        8:58 PM 
                                                                                    
     Action Server                           Type    Attach Manager                 
     ------ -------------------------------- ------- ------------------------------ 
      ___   ATTACH-51-EXX                    Attach                                 
      ___   ATTACH-51-EXX-SECURE             Attach                                 
      ___   DISPATCH-51-EXX                  Server                                 
      ___   DISPATCH-51-EXX-BATCH            Server  ATTACH-51-EXX                  
      ___   DISPATCH-51-EXX-SECURE           Server  ATTACH-51-EXX-SECURE           
      ___   DISPATCH-51-EXXTEST              Server                                 
      ___   SECURITY-51-EXX                  Server                                 
      ___   SECURITY-51-EXX-BATCH            Server  ATTACH-51-EXX                  
      ___   SECURITY-51-EXX-SECURE           Server  ATTACH-51-EXX-SECURE           
     Server .....: ________________________________ Server type ..: _               
     Replica ID .: ________________________________ Repeat command: _               
     Last command:                                                                  
     Respondent .:                                                                  
                                                                                    
                                                                                    
     Direct Command: ____________________________________________________________   
     Debug      EndJob     EndService EnVironmnt Initiate   Ping       Refresh      
     SHutdown   STeplibs   SYsprof    (PF4=CLog) (PF5=flip)                         
    

    Use this panel to send commands to servers, display the replies returned from the servers, or initiate new servers. By default, this panel displays Type S (server) and A (attach) servers.

  3. Use the following fields to specify options for servers:

    Field Description
    Action Indicates the command to be sent to the corresponding server. To send a command to a server, enter the upper case letter(s) of the command (shown at the bottom of the panel) in the appropriate Action field.

    These commands can also be used in the Broker Driver program.

    Server Repositions the displayed information to the server specified in this field.
    Server type Indicates the type of server. Do one of the following:
    • Enter "*" to show all servers.

    • Enter the code for the type of server you want to display. Valid codes are:

      • A (attach)

      • S (server)

      • C (client)

    • Leave the field blank to show servers of type A and S.

    Replica ID Identification for each unique server. EntireX allows many different servers to provide the same Broker services. Each unique server is known as a replica and is identified by a unique 32-character replica ID.

    For most requests, the client does not care which replica satisfies the request. Occasionally, you may want to target a specific replica (for example, to run a server online to output debugging statements such as Input, Print, etc.). When testing is completed, you will want to shut down the replica. This can be done by including the desired replica ID as an option on the SHUTDOWN command.

    For example, using the SHUTDOWN command for a server without specifying a replica ID shuts down any replica offering the server. Specifying a replica ID and using the SHUTDOWN command causes all other servers to ignore the command. You must continue to send the command until the desired respondent replies.

    All commands support a replica ID option and the Respondent field indicates which replica responded to the command. Information about a replica can be retrieved using the ENVIRONMENT command.

    Repeat command Number of times to repeat the command. You can execute the command multiple times. For example, to initiate three dispatch servers, type "I" beside the dispatch server and enter "3" in this field.

    You can determine the number of servers that are running by repeating a PING command and analyzing the replica IDs of the respondents.

    Tip:
    A better method of determining the number of servers available is by using the EntireX Control Center.

    Last command Text that was sent to the server to execute the most recent command. This string could also be sent to the server programmatically or using the Broker Driver program.
    Respondent Server and replica ID of the server that responded to the most recent command. The respondent is followed by the response text.

    Note:
    Commands are always sent to the Broker service associated with the specified server. If multiple servers specify the same Broker service, the command may be directed to an alternate server.

You can also access the communications logs to view system messages. For information, see Access the Communications Logs.

This section covers the following topics:

Overview of Server Commands

Some commands are sent directly to the main interface (MAIN) for the associated server. Other commands are sent to the command interface (CMD) for the server. Still others are sent to the attach server associated with the server.

The following table summarizes the commands and how they are processed:

Command Applies to: Sent to:
DEBUG Services of type S or C that are linked to an attach server. MAIN interface for the attach server.
ENDJOB Attach servers that launch subtasks. MAIN interface for the attach server. The attach server sends SHUTDOWN requests to linked servers.
ENDSERVICE Servers of type S that are linked to an attach server. MAIN interface for the attach server. The attach server sends SHUTDOWN requests to the specified server.
ENVIRONMENT All servers of type S or A. CMD interface for the server.
INITIATE All server types. If the service has an attach server, the command is sent to the attach server; otherwise, the server start routines are called directly to initiate the service.
PING All servers of type S or A. CMD interface for the server.
REFRESH All servers of type A. MAIN interface for the attach server.
SHUTDOWN All servers of type S or A. CMD interface for the server.
STEPLIBS All servers of type S or A. CMD interface for the server.
SYSPROF All servers of type S or A. CMD interface for the server.

The Attach Server column shows the name of the attach server capable of starting the server. Servers showing highlighted attach server names are those that will automatically start in response to an EntireX attach request. The following sections describe these commands in detail.

DEBUG Command

Use this command to help diagnose problems in starting servers.

The DEBUG command only applies to servers that use an attach server. The DEBUG command returns information related to the Natural startup process. When you use the START command, the START program detects if it is in debug mode and writes out additional diagnostics. As the server is not intended to start up in debug mode, the server program is not FETCHED.

How the DEBUG Command Works

When a server is launched in debug mode, the CMPRINT dataset (where Natural writes initialization errors) is mapped to work file 7 (CMWKF07). After launching the server, the attach server pauses for three seconds and attempts to read the contents of work file 7. The contents of the file are sent back to the client.

Tip:
If you experience I/O errors when using the DEBUG command, try repeating the command.

Debug Unix Batch Servers

The process of debugging batch servers can be difficult, as they run in the background in non-interactive mode. Whenever they fail to start up or respond to client requests, the last resort is to analyze the output written to the CMPRINT file assigned to the Natural batch session. However, if all Natural Business Services servers run with the same CMPRINT file, they will overwrite each other’s output, possibly ruining the debugging information. To prevent this problem, CSRLOAD generates server definitions with a dedicated CMPRINT file for each Natural Business Services server.

Tip:
To prevent multiple instances of the same server from overwriting each other’s CMPRINT output, we recommend that you only initiate one request at a time while debugging.

ENDJOB Command

The ENDJOB command only applies to attach servers. More specifically, it applies to attach servers that launch other services as subtasks. When the ENDJOB command is sent to the attach server, the attach server sends SHUTDOWN commands to each server it has launched.

As part of the SHUTDOWN command, the attach server includes the PARENT-RID option so only subtasks of the attach server respect the shutdown request.

Normally, the ENDJOB command causes the batch job that hosts the attach server and its subtasks to end. However, there may still be subtasks busy processing requests and therefore unable to receive the shutdown notification. In this case, the batch job continues to run until all subtasks time out or are shut down explicitly.

ENDSERVICE Command

The ENDSERVICE command can only be used with servers that have an attach server. In response to this command, the attach server continues to send shutdown requests to the specified server until no further servers respond.

Note that, while one attach server broadcasts the SHUTDOWN command to all replicas of the service, these replicas could be running within other jobs or environments. Unlike the ENDJOB command, the ENDSERVICE command does not use the PARENT-RID to restrict the servers that carry out the shutdown request.

ENVIRONMENT Command

The ENVIRONMENT command returns information about when a server was started, as well as many of the Natural system variable values assigned within the server. You can use this information to help diagnose problems with a server and to identify the environment in which the server is running.

If the ENVIRONMENT command returns a non-blank PARENT-RID value, the service is running as a subtask. The PARENT-RID value identifies the attach server replica that hosts the server.

INITIATE Command

Use the INITIATE command to start servers. You can start as many servers as needed, to the maximum defined in the GLOBAL DEFAULTS section of the Broker attribute file. If you want to start a server or client service that uses an attach server, ensure that the attach server is running.

Start of instruction setTo initiate (start) a server:

  1. Enter "P" in Action for the server.

    If the system responds that the PING command was successful, there is a server with that name available on the network. If the message indicates that the server is not registered, or if you require an additional copy, continue to the next step.

  2. Enter "I" in Action for the server.

    It can take up to 15 seconds (depending on system load) for the server to start and register with EntireX.

    Note:
    If the server runs as a batch job, note the name of the batch job when it is displayed as you may need it later.

  3. Do one of the following:

    Option Description
    Use the PING command to determine whether or not the server started properly.
    • If the PING command is successful, the server is now available.

    • If the PING command fails, press PF4 (CLog) to review the communications logs. These logs contain messages that are not communicated back to the client, such as startup errors. Use this information to determine and rectify the problem.

    If this is not the first copy of the server, repeat the PING command to determine the number of replicas running (based on replica IDs). If the server fails to start and the communication log does not reveal why, use the EntireX Control Center to determine the number of servers available or do one of the following:
    • For attach servers or servers that are not started by an attach server, it may be a problem with the JCL that is submitted. Review the batch job output and correct the JCL within the specified JCL member.

    • For servers started by an attach server, it may be a problem with the startup commands sent to Natural. Use the DEBUG command to try to identify the problem.

PING Command

Use the PING command to determine whether or not servers are running and available on the network. When a server is pinged, one of the following messages is returned:

Message Indicates
ETB Error 215/148 (NET: Connection Error) The Broker ID specified in the server definition is not currently running or responding.
ETB Error 7/7 (server not registered) You have requested a valid server, but there are no servers running to satisfy the request. If this error is preceded by a message, such as “Sending command to attach server: servername”, the attach server associated with the current server is not registered.
ETB Error 20/216 (API: Invalid BROKER-ID) The Broker ID specified for the server is not valid.
PING of server server name was successful At least one copy of the server that was pinged is running and available.
ETB Error 74/74 (Wait timeout occurred) Either all servers are busy or a server has ended without properly de-registering.

REFRESH Command

The REFRESH command can only be sent to an attach server. When an attach server is started, it determines all servers to be registered with the Attach option by reading the server records. While the server is running, you can modify the server records and alter the set of servers that are linked to the attach server. These changes are not reflected in running attach servers until an explicit REFRESH command has been sent to all such servers.

SHUTDOWN Command

The SHUTDOWN command shuts down servers. There are three ways to shut down servers. The method you choose depends on whether you want to shut down:

Shutdown a Single Replica

To end a single server replica, use the SHUTDOWN command with the service to be ended. To shut down a specific instance of a server, also specify the replica ID.

Shutdown All Replicas of a Server

To end multiple replicas of a server, send the End Service (ES) request to the attach server used to start the server.

Shutdown All Servers in a Batch Job

To end all servers running within a certain batch job, enter the ENDJOB command in Action for the attach server to be shut down. Use this option if your servers execute as subtasks of an attach server.

Example of Shutting Down Servers in a Batch Job

In addition to using the Manage Servers panel, you can also send commands directly to servers using the EntireX Driver program. This section describes the commands to implement a variety of shutdown options.

The following diagram shows an example of two batch jobs:

graphics/shutdown-servers-batch.png

STEPLIBS Command

The STEPLIBS command returns information about the associated Natural step libraries used by the server.

SYSPROF Command

The SYSPROF command returns information about the Natural system files used by a server.

Standard Response Protocol

Most servers acknowledge or respond to standard protocol. This protocol is identified by the MSG111 signature at the beginning of the message.

Access the Communications Logs

Access the communications logs from the Query Communications Logs panel. To access this panel, press PF4 (CLog) on the Manage Servers panel. Because each INITIATE and SHUTDOWN command generates an entry in the communications logs, this PF-key gives you quick access to the messages. Pressing PF4 (MSrvc) on the Query Communications Logs panel returns you to the Manage Servers panel.

Note:
For information on the communication logs, see Queries and Logs for Servers.

Top of page