Version 5.3.1	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

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

• Define Servers

• Manage Servers

Types of Servers

The three types of servers are:

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:

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:

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

Define Servers

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

• attach

• server

• client

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

• Identify the Server

• Define Broker Service Settings

• Define Server Start Parameters and Routines

• Define Server Settings and Program Parameters

• Change the Broker Attribute File

• Add a Natural Profile

Access the Maintain Servers Panels

To 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:

   • Disable a trusted user

   • Provide a user ID and password for the broker

   • Designate an attach server and provide the attach server name. Servers that are linked to an attach server must use the same Broker ID as the attach server. When the Broker ID for an attach server is modified, the Broker ID for all related servers will be updated automatically.

     Note:
     Broker service settings configure the server to register itself by a specific name with a specific broker. You must define settings for servers of type A (attach) and S (server).

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:

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:

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:

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
• Activation Policies
• Runtime Error Handling

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
• Use the START Command to Initiate Servers Online or in Batch Mode

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
• BATCHJOB Server Start Routine
• SUBTASKB Server Start Routine

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:

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:

• BATCHJCL (z/OS)

• BATCHDCL (z/VSE)

• BATCHBCL (BS2000/OSD)

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:

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

To 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:

This section covers the following topics:

• Sample SUBTASKB Routines
• Write to Print and Work Files
• Generate Trace Output

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:

• Enter a valid Natural user ID and password

• Enter the *USER-ID and *PASSWORD keywords to use the values specified in the Broker Service Settings portion of the first Maintain Servers panel. For example:

  Server Start Parameters    
  > NATPARM='FNAT=(1,2),PROFILE=SYSBIZ,AUTO=OFF,
  > STACK=(LOGON SYSBIZ,*USER-ID,*PASSWORD;START)'

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:

SECURITY-SERVER=server-name

SECURITY-MODE=value

CONVERSATION-FACTORY=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.

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.

To 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

• DEBUG Command

• ENDJOB Command

• ENDSERVICE Command

• ENVIRONMENT Command

• INITIATE Command

• PING Command

• REFRESH Command

• SHUTDOWN Command

• STEPLIBS Command

• SYSPROF Command

• Access the Communications Logs

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:

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.

To 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:

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:

• A single replica

• All replicas

• All servers within a single job

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:

• To end any replica of server S2, send the CMD SHUTDOWN command to the server.

• To end server S2 replica 5, send the CMD SHUTDOWN,RID=5 command to the server to be shut down until you receive a successful response.

• To end all replicas of server S2, send the PROCESS SHUTDOWN SERVER S2 command to either attach server.

• To end all servers beginning with S2, send the PROCESS SHUTDOWN SERVER S2* command to attach server A1. Note that this command will shut down server S2 regardless of which attach server S2 is running under.

• To end all servers beginning with S2 and running batch job AM654321, send the PROCESS SHUTDOWN SUBTASK S2*,RID=2 command to the attach server. Continue to send the command until it is received by replica 2.

• To end batch job AM123456, send the PROCESS SHUTDOWN SUBTASK *,RID=1 command to the attach server A1. Enter the command until it is satisfied by the desired replica.

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.

www.softwareag.com

Copyright © 2006-2010 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT