Using the PATHCOM Interface
Starting and Restarting a Process
Monitoring Status
Modifying Global Parameters Based on Changing Requirements
Reconfiguring Server Pools
You configure NonStop DOM system server processes using the services of NonStop TS/MP. Processes defined through NonStop TS/MP run under the control of a NonStop TS/MP monitor, the PATHMON process.
PATHCOM provides the interface to the PATHMON process.
You begin a PATHCOM process from the TACL prompt in the Guardian environment. For detailed instructions on starting these processes, and for complete syntax and descriptions for all PATHCOM commands, refer to the NonStop TS/MP System Management Manual.
This topic gives an overview of how you can use PATHCOM to alter global and process-specific configuration parameters in the NonStop TS/MP configuration.
Maintenance and fine-tuning tasks for NonStop DOM system and application processes include the following:
The OSS scripts supplied with NonStop DOM enable you to execute a single command to start (or stop) a NonStop TS/MP configuration. Although these scripts are good for cold-starting and stopping all NonStop DOM system processes, they lack the control you need to properly administer a running system.
The nsdstart script issues a cold-start to boot the configuration, causing PATHMON to re-create the entire NonStop TS/MP configuration file–a potentially lengthy process. If your global configuration parameters have not changed, there would be no need to re-create this configuration file.
Using PATHCOM, you can directly administer a PATHMON process without re-creating the existing NonStop TS/MP system configuration.
To issue PATHCOM commands, you must first start a PATHCOM process to communicate with the PATHMON process that controls your NonStop TS/MP environment. Type the following from the TACL prompt:
> PATHCOM $pmon
This command begins a PATHCOM session using the PATHMON process names in the $pmon parameter, for example, $nsdm. The system responds by returning the PATHCOM prompt:
=
One thing you can use the PATHCOM interface for is restarting a NonStop DOM system process. To do so,
Consider the following commands:
> PATHMON /NAME $NSDM, NOWAIT/ > PATHCOM $NSDM = START PATHWAY COOL
The first TACL command starts a PATHMON process named $NSDM. The second starts a PATHCOM process to communicate with the running PATHMON process.
From the PATHCOM prompt, you restart the $NSDM configuration using the existing configuration file. This is accomplished by using the COOL start option of the START PATHWAY command
The COOL command directs the PATHMON process to start any specified PATHMON backup process and use the existing configuration file as a basis for creating the operating environment. The existing configuration file contains the PATHMON configuration at the time the system stopped (due to shutdown or failure).
The PATHMON process maintains information about process configurations, process status, and operations statistics. Table 1 illustrates the PATHCOM commands and their effects:
| PATHCOM Command | Effect |
|---|---|
| INFO | Returns current configuration information |
| STATUS | Returns the current state of a process, for example: RUNNING, STOPPED, or SUSPENDED |
| STATS | Returns process usage statistics |
Most status and statistics information collected by these commands is collected by the Pathsend API and the LINKMON process.
The Pathsend API provides procedure calls that are used by Tandem based clients to access NonStop TS/MP server processes. The LINKMON process is a link manager that provides link management functions for Pathsend requests.
Note: Statistics information is not available for the Comm Server and the LSD because they are not accessed by the Pathsend API or the LINKMON process, which collect the information. Status and statistics information is available, however, for the Naming Server and Event Server and for all NonStop TS/MP application server processes.
Use the INFO command to display configuration information. You can display configuration information about your overall NonStop TS/MP environment, about the PATHMON process, or about specific server pools in the environment using the following commands:
To display global parameters for the overall NonStop TS/MP environment, type the following:
= INFO PATHWAY
The example below illustrates the information displayed when you execute the INFO PATHWAY command for the NonStop TS/MP environment running NonStop DOM system processes:
=info pathway PATHWAY MAXASSIGNS 8 [CURRENTLY 0] MAXDEFINES 27 [CURRENTLY 4] MAXEXTERNALTCPS 0 [CURRENTLY 0] MAXLINKMONS 16 [CURRENTLY 0] MAXPARAMS 4 [CURRENTLY 0] MAXPATHCOMS 8 [CURRENTLY 1] MAXPROGRAMS 4 [CURRENTLY 0] MAXSERVERCLASSES 4 [CURRENTLY 4] MAXSERVERPROCESSES 40 [CURRENTLY 8] MAXSPI 8 [CURRENTLY 0] MAXSTARTUPS 4 [CURRENTLY 0] MAXTCPS 0 [CURRENTLY 0] MAXTELLQUEUE 4 MAXTELLS 32 [CURRENTLY 0] MAXTERMS 0 [CURRENTLY 0] MAXTMFRESTARTS 5 OWNER \OSS2.190,0 SECURITY "N" = |
This output shows current values of the global NonStop TS/MP environment variables. These variables are set by the nsdstart shell script, or by manually entering values using the SET PATHWAY command.
Note: Several parameters are not relevant for NonStop DOM applications, and should be set to zero when you configure the NonStop DOM system. These include MAXEXTERNALTCPS, MAXTCPS, and MAXTERMS.
Executing the INFO command lets you determine whether current global limits are being reached, because the display shows maximum limits on the left and actual current totals on the right. In the above example, the configuration allows a maximum of 40 server processes to be running at any given time. The current total is 8 server processes running. To see complete syntax and descriptions for all global parameters, refer to the NonStop TS/MP System Management Manual.
To display information about parameters set for the PATHMON process, type the following PATHCOM command:
= INFO PATHMON
Following is an example of what might be displayed when you execute the INFO PATHMON command:
PATHMON BACKUPCPU 4 DUMP ON (FILE \SYS.$VOL1.TESTING.MONDUMP) |
This sample display shows the PATHMON backup process running in CPU 4. If the PATHMON process encounters an internal error, it will write data stack information to \SYS.$VOL1.TESTING.MONDUMP.
Following is an example of the command you type to display the configuration parameters for a single server pool:
= INFO SERVER CS
In this command, CS is the logical name defined for the server in the NonStop TS/MP configuration. In this example, the command displays parameters for the Comm Server. These are the attributes defined with the SET SERVER command when the NonStop TS/MP configuration was created by the nsdstart script or through the PATHCOM interface.
= info server cs
SERVER CS
PROCESSTYPE OSS
AUTORESTART 10
CREATEDELAY 0 SECS
CWD /cust7/r1488.user/tandem/nsd2.0/nsd.e05
DEBUG OFF
DEFINE =_SRL_01,CLASS MAP,
FILE \OSS2.$DATA07.NSDE5.NSDSRL
DELETEDELAY 0 SECS
ENV NSDOM_CFG_DBM=$DATA07.NSDE5.NSDCFGDB
HIGHPIN OFF
HOMETERM \OSS2.$ZTN0.#PTPFULC
LINKDEPTH 1
MAXLINKS 16
MAXSERVERS 2
NUMSTATIC 2
OWNER \OSS2.190,0
PRI 150
PROCESS $YC01 (CPUS 0:1)
PROCESS $YC02 (CPUS 1:0)
PROGRAM /cust7/tandem/nsd2.0/nsd.e05/bin/cs
SECURITY "N"
STDERR /cust7/tandem/nsd2.0/nsd.e05/log/cs.out
STDIN /dev/null
STDOUT /cust7/tandem/nsd2.0/nsd.e05/log/cs.out
TIMEOUT 0 SECS
TMF OFF
VOLUME \OSS2.$DATA07.DEREK
=
|
Use the STATUS command to display status information about your NonStop TS/MP environment, the PATHMON process itself, and server objects.
To display status for the overall NonStop TS/MP environment, issue the following PATHCOM command:
= STATUS PATHWAY
The following command gives you a display showing the state of the environment (for example, RUNNING). The display also shows how many server pools, server processes, and LINKMON processes are running, stopped, thawed, and so on:
= status pathway
PATHWAY -- STATE=RUNNING
RUNNING
EXTERNALTCPS 0
LINKMONS 0
PATHCOMS 1
SPI 0
FREEZE
RUNNING STOPPED THAWED FROZEN PENDING
SERVERCLASSES 3 1 4 0 0
RUNNING STOPPED PENDING
SERVERPROCESSES 7 1 0
TCPS 0 0 0
RUNNING STOPPED PENDING SUSPENDED
TERMS 0 0 0 0
=
|
To display information about the PATHMON process, type the following:
= STATUS PATHMON
The STATUS command displays information about where the PATHMON process is running, where the PATHMON control files are located, and whether log files are open:
= status pathmon PATHMON \OSS2.$YNSD2 -- STATE=RUNNING CPUS 1:0 PATHCTL (OPEN) $DATA07.DEREK.PATHCTL LOG1 S (CLOSED) \OSS2.$Z6GR.#INTER ERROR=201 LOG2 (CLOSED) REQNUM FILE PID PAID WAIT 1 PATHCOM $Z7YJ 190,0 = |
To display status information for a single server pool named ORDR-1, type the following:
= STATUS SERVER ORDR-1
You get a display showing the number of server processes running, frozen, thawed, or stopped. You also can execute the STATUS SERVER command with additional options. For example, the command can provide detailed information about each process running in the server pool or show status for more than one server pool.
One useful variant of the STATUS SERVER command, the the PROCESSES option, allows you to list the LINKMON processes that currently link to a server process, as shown here:
= STATUS SERVER <server-name>, PROCESSES
Here, <server-name> is the name of the server for which you want information.
In the next example, the command output displays links for the OSS server pool ORDR-2. The server pool has five processes running: $ZTX0, $ZTX1, $ZTX2, $ZTX3, and $ZTX4. Another server process is stopped: $ZTX6. Note that several of the running processes have links with more than one LINKMON process (listed in the LINKER column).
SERVER #RUNNING ERROR INFO
ORDR-2 4
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX0 RUNNING 5 11
LINKER LINK COUNT
L\SYS.$ZL12 003
L\SYS.$ZL13 002
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX1 RUNNING 3 08
LINKER LINK COUNT
L\SYS.$ZL14 003
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX2 RUNNING 2 05
LINKER LINK COUNT
L\SYS.$ZL15 001
L\SYS.$ZL10 001
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX3 RUNNING 6 12
LINKER LINK COUNT
L\SYS.$ZL08 003
L\SYS.$ZL09 003
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX4 RUNNING 3 07
LINKER LINK COUNT
L\SYS.$ZL01 001
L\SYS.$ZL02 002
PROCESS STATE ERROR INFO #LINKS WEIGHT
$ZTX6 STOPPED 0 0
|
Using the STATUS SERVER command with the PROCESSES option can help you determine whether links are evenly allocated and balanced among server processes in your NonStop DOM application environment.
The #LINKS field shows the total number of current links to a given server process. The WEIGHT field indicates how heavily the server process is used relative to how heavily other processes in the server pool are used. In the example above, process $ZTX3 has six links and a weight of 12; thus, $ZTX3 is the hardest working process in the server pool at the moment.
To display statistical information about a PATHMON process, type the following PATHCOM command:
= STATS PATHMON
Refer to the PATHMON manual for details on interperting the output from this command.
As your application needs change, requirements for your NonStop TS/MP configuration will change. If your application grows, adjustments might be necessary to satisfy your transaction throughput and response time requirements and to update or expand the system to provide needed resources.
For example, you might need to increase the maximum possible number of application server processes to satisfy a growing demand for links to servers. In response to your changing requirements, you might need to specify not just new attributes for your server pools but also new global limits and parameters for the NonStop TS/MP environment.
Caution: You cannot specify new global parameters while the PATHMON environment is running. You must first shut down the entire configuration before you can install the new parameters.
Because a system shutdown can result in considerable downtime if your application is complex, it is recommended that when you first configure your environment you specify global limits that are high enough to allow for growth.
If you discover that you must reconfigure the global parameters, thereby forcing a shutdown, you must respecify all limits, not just the ones you are changing. For this reason, you might find it more efficient to change global parameters by editing the nsdstart script rather than specifying each specific parameter using PATHCOM.
If you change global parameters by editing the relevant parameters in the nsdstart script, execute the script to cold-start the NonStop TS/MP environment with the new parameters.
If you use PATHCOM to respecify all parameters, be sure to use the COLD start option of the SET PATHWAY command to restart the NonStop TS/MP environment.
Changing application requirements or performance queues can necessitate a reconfiguration of your server resources. For example, you may find that one application server pool is handling many more requests than expected while another does not receive the expected number of requests. One way to address this situation would be to increase the maximum number of processes that can be started for the first server pool. A more complex approach might be to review link access to the first server pool and modify link-related server attributes such as LINKDEPTH and MAXLINKS.
For a discussion of these attributes and ways to use them to achieve successful load balancing across server processes, refer to Load Balancing for Application Server Processes.
You do not need to shut down the environment to reconfigure server pools. Because editing and running the nsdstart script requires a complete environment shutdown, you will likely find it more efficient to reconfigure server pools using the appropriate PATHCOM commands.
To add a server pool, use the SET SERVER and ADD SERVER commands. Then use the START SERVER command to start it. For details on how this is done, refer to the nsdstart script.
To remove or alter a running server pool, you must:
Before you can modify a running server pool, you must stop it. First, use the FREEZE SERVER command to disable server communications with other processes in the environment. After a server pool is frozen, you can stop it by issuing a STOP SERVER command.
For example, the following commands stop all server processes in server pool SVR-2:
= FREEZE SERVER SVR-2 = STOP SERVER SVR-2
To stop all server pools in your NonStop TS/MP configuration, use the following two commands:
= FREEZE SERVER * = STOP SERVER *
To confirm that server pools are frozen or stopped, use the STATUS SERVER command.
Once the server pool is stopped, you can use PATHCOM commands to either delete the server pool or modify the server attributes.
To restart server pool SVR-2, you must first thaw the server, then start it, as shown with the following two commands:
= THAW SERVER SVR-2 = START SERVER SVR-2
The following commands restart all server processes:
= THAW SERVER * = START SERVER *
Alter a server pool by using the ALTER SERVER command. For example, the following series of commands changes the priority at which the server TRANS-1 runs:
= FREEZE SERVER TRANS-1 = STOP SERVER TRANS-1 = ALTER SERVER TRANS-1, PRI 50 = THAW SERVER TRANS-1 = START SERVER TRANS-1 |
Note that the FREEZE command precedes the STOP and ALTER commands; and how the THAW command must precede the START command.