jpctool service list

Organization of this page

Format
Function
Hosts that can execute the command
Execution permission
Installation directory
Arguments
Notes
Cautions regarding execution using Format 2
Return values
Displayed information
Usage example 1
Usage example 2
Usage example 3
Usage example 4
Output example

Format

Format 1

jpctool service list     -id service-ID
                        [-host host-name]
                        [-lhost logical-host-name]
                        [-proxy {y|n}]
                        [-stat]
                        [-v]

Format 2

jpctool service list     -key service-key
                        [-lhost logical-host-name]
                        [-proxy {y|n}]
                        [-stat]
                        [-v]

To Page Top

Function

The jpctool service list command displays the service configuration and status of a Performance Management program.

When PFM - Manager or PFM - Base and PFM - Web Console are installed on the same host, and start and stop linkage is set, execute the jpctool service list command in Format 2 to display the configuration and status for all Performance Management program services including PFM - Web Console. For details about the start and stop linkage settings for PFM - Manager, PFM - Base, and PFM - Web Console, see the chapter describing Performance Management start and stop in the JP1/Performance Management User's Guide.

To Page Top

Hosts that can execute the command

PFM - Manager
PFM - Agent
PFM - RM

To Page Top

Execution permission

In Windows:: None
In UNIX:: None

To Page Top

Installation directory

In Windows:

installation-folder\tools\

In UNIX:

/opt/jp1pc/tools/

To Page Top

Arguments

`-id` `service-ID`

Specifies a service ID. Specify a string of 1 to 258 bytes.

You can use a wildcard character to specify multiple service IDs. In this case, processing of the remaining services continues even if an error occurs on one service. If errors occur on multiple services, the command returns a value for the last error that occurred.

`-host` `host-name`

Specifies the name of the host whose service configuration and status are to be displayed. You use this argument to display the configuration and status of a Performance Management program running on a specific host. For host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. If you omit this option, the local host is assumed.

You can use a wildcard character to specify multiple host names.

`-lhost` `logical-host-name`

Format 1

Specifies a logical host name if this command is to be executed by a host in a logical host environment, not in the physical host environment. For logical-host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. If you omit this specification, the physical host is assumed. Wildcard characters cannot be used.
Format 2

When PFM - Web Console is running on a logical host environment, specify the name of the startup host (logical host name) for PFM - Web Console. For logical-host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. If you omit this specification, the physical host is assumed. Wildcard characters cannot be used.

`-proxy {y|n}`

Specifies whether or not communication is to be through PFM - Manager in the case where a remote host is specified in the -host option in an environment in which direct communication with PFM - Agent or PFM - RM on the remote host cannot be performed.

When y is specified, communication is performed through PFM - Manager.

When n is specified, communication is not performed through PFM - Manager.

`-stat`

Specifies that the status is to be displayed by communicating directly with the Status Server service at the host specified in -host host-name. You specify this option to display remote host information when the PFM - Manager is not running. The command also displays the status of the Status Server service at the remote host.

When this option is specified, wildcard characters cannot be used in -host host-name. This option cannot be specified together with -proxy {y|n}.

This option cannot be used if the status management function is disabled.

`-v`

When the product name display functionality is enabled, the service name is displayed using the product name. For details about product name display functionality, see the chapter describing Performance Management functionality in the JP1/Performance Management Planning and Configuration Guide.

`-key` `service-key`

Specifies the key of the service whose configuration and status are to be displayed. You can specify the following in service-key:

all: Displays the configuration and statuses of all Performance Management program services.
jp1pc: Displays the configuration and statuses of all PFM - Manager program services (excluding the PFM - Web Console service).
Manager or mgr: Displays the configuration and statuses of all PFM - Manager services (excluding the Action Handler service).
AH or act: Displays the configuration and status of the Action Handler service.
StatSvr or stat: Displays the configuration and status of the Status Server service.
WebConsole or wc: Displays the configuration and status of the PFM - Web Console service.

For details about the service key of the PFM - Agent or PFM - RM service, see the naming rules described in the appendix of the JP1/Performance Management Planning and Configuration Guide.

To Page Top

Notes

The command cannot display information about the service of a Performance Management program that has never been started. The same applies to a service that has never been started since the host was renamed.
Arguments must be specified in the order that they appear in the description. Otherwise, they will not be recognized correctly.
If the Name Server and Master Manager services are not running, the service configuration and status cannot be displayed for a host other than the local host. In this case, communication does not go through PFM - Manager even if y is specified in the -proxy option.
If the jpctool service list command is executed immediately after a Performance Management program starts, the service status may be displayed as Inactive even though the service process is active. In this case, the corresponding service either may be engaged in startup processing or may be temporarily in the stand-alone mode due to connection wait status. If PFM - Manager is running, wait a while, and then use the jpctool service list command to check the service status.
When the jpctool service list command is executed for the PFM - Agent or PFM - RM service, "Inactive" or "Timeout" may be displayed even though the service is running. In this case the PFM - Agent or PFM - RM service is busy collecting performance data.

To ensure the service status is displayed correctly please enable the status management function. For details about this function see the chapter that describe using the status management function to check service status in the manual JP1/Performance Management User's Guide.
If PFM - Manager is uninstalled and then re-installed on the same machine, the jpctool service list command may display two different Trap Generator services. In this case, start the PFM - Manager service and use the jpctool service delete command to delete the Trap Generator service whose status is Inactive.
If command execution is interrupted by pressing the Ctrl + C keys or by a signal, a predefined return value is not returned. Therefore, you should ignore the return value when the command was interrupted by the Ctrl + C keys or by a signal.
If the -stat option is omitted, the command does not display the Status Server service at a remote host.
If the status management function is disabled, the Status Server service is not displayed.
In the following cases, the configuration and status is not displayed for remote agents and group agents.
- The Master Manager or Name Server service is not running
- The -stat option is specified

After either of the following operations has been performed, if the information about the relevant service is not deleted, the service might be displayed when the jpctool service list command is executed:

Uninstallation of PFM - Agent, PFM - RM, or PFM - Base
Unsetup of the PFM - Agent or PFM - RM instance environment

The following table describes the situations in which the service is displayed.

Situations in which the jpctool service list command is executed		Whether service information is deleted
Target host	Whether the -stat option is specified	No	Yes
Local host	--	The service is not displayed.	The service is not displayed.
Remote host	Specified	The service is not displayed.	The service is not displayed.
Remote host	Not specified	The service is displayed.	The service is not displayed.

Legend:: --: Not applicable

After the information about a service has been deleted, if uninstallation of the service or unsetup of the service's instance environment is not performed, the service might be displayed when the jpctool service list command is executed.

The following table describes the situations in which the service is displayed.

Situations in which the jpctool service list command is executed		Whether uninstallation of the service or unsetup of the service's instance environment is performed
Target host	Whether the -stat option is specified	No	Yes
Local host	--	The service is not displayed.	The service is not displayed.
Remote host	Specified	The service is not displayed.	The service is not displayed.
Remote host	Not specified	The service is displayed.	The service is not displayed.

Legend:: --: Not applicable

Before you execute this command on a PFM - Agent or PFM - RM host, check whether the option for restricting remote operation from Agent hosts is enabled on the PFM - Manager host. If that option is enabled, you can display only the configurations and statuses of services that are running on the local host (except when the -stat option is specified). If you specify a remote host by using the -host option, the command fails.
If the option for restricting the viewing of service information from Agent hosts is enabled on the host specified by the -host option, you cannot execute this command with the -stat option.
If you want to execute this command between hosts that use different types of Internet protocol, you must execute the command from PFM - Manager, by specifying the -proxy y option. If you execute this command without specifying the -proxy y option, the string Inactive is displayed.
You cannot execute this command with the -stat option between hosts that use different types of Internet protocol.

To Page Top

Cautions regarding execution using Format 2

When anything other than all, wc or WebConsole is specified for the service key argument of the -key option, the configuration and status of the PFM - Web Console service is not displayed.
The -host option cannot be specified to display the configuration and status for remote host services.

To Page Top

Return values

`0`	The command terminated normally.
`1`	An argument specification is invalid.
`3`	The specified service has not been registered.
`100`	The Performance Management environment is invalid.
`101`	Name Server service is not active.
`102`	The specified logical host name has not been set up.
`200`	A memory shortage occurred.
`210`	A disk space shortage occurred.
`211`	A file or directory cannot be accessed.
`220`	A host name specified in the service configuration information file is invalid.
`222`	A communication error occurred.
`255`	An unexpected error occurred.

To Page Top

Displayed information

The following table describes the information that is displayed by executing the jpctool service list command:

Output information	Description
`Host Name`	Name of the host where the service is running.
`ServiceID`^#1	Service ID. Even when the product name display functionality is enabled, the product name is not displayed. If executed in Format 2, this is not displayed on the output line for PFM - Web Console service information.
`Service Name`^#1	Service name. Even when the product name display functionality is enabled, the product name is not displayed. If executed in Format 2, the fixed string `Web Console` is displayed in the PFM - Web Console service information.
`Service`^#2	Service name. The service ID is displayed for the product name.
`PID`	Indicates the service process ID. When the status management function is enabled: The process ID is displayed when `Status` is `Active`, `Busy`, `S` `Active`, `S` `Busy`, `Starting`, or `Stopping`. When the status management function is disabled or the version does not support the status management function: The process ID is displayed only when `Status` is `Active`. If executed in Format 2, this is not displayed on the output line for PFM - Web Console service information.
`Port`	Indicates the communication port number used by the service. For services other than PFM - Web Console When the status management function is enabled: The port number is displayed when `Status` is `Active`, `Busy`, `S` `Active`, or `S` `Busy`. When the status management function is disabled or the version does not support the status management function: The port number is displayed only when `Status` is `Active`. For PFM - Web Console When the `Status` is `Active` `--` is displayed. When the `Status` is not `Active` Nothing is displayed.
`Status`	Indicates the status of the service. When the status management function is enabled: Service status display when the version supports the status management function `Active`: Waiting for a request `Inactive`: Stopped `Starting`: Being started `Busy`: Processing a request `S` `Active`: Waiting for a request, stand-alone mode `S` `Busy`: Processing a request, stand-alone mode `Stopping`: Being stopped Service status display when the version does not support the status management function `Active`^#: Operating `Incomp`^#: Starting or stopping the service `Inactive`^#: Unable to connect for communication or is stopped `Comm` `Err`^#: Able to connect for communication, but not responding `Timeout`^#: Communication connection timeout `Error`^#: An error other than a communication connection timeout error occurred. For details about the error, see the common message log. However, in the following cases, the service status display of the version supporting the function is the same as in the version not supporting the status management function: • The Status Server service has stopped. • The Status Server service has started, but the status management function cannot correctly recognize the status of the service.^#3 When the status management function is disabled or the version does not support the status management function: `Active`: Operating `Inactive`: Unable to connect for communication or is stopped `Comm` `Err`: Able to connect for communication, but not responding `Timeout`: Communication connection timeout `Error`: An error other than a communication connection timeout error occurred. For details about the error, see the common message log.

#1: This is displayed when the -v option is not specified.
#2: This is displayed when the -v option is specified.
#3: For the function to correctly recognize the status of the service, the service must be restarted.

To Page Top

Usage example 1

This example displays a list of the services of all Performance Management programs in the system:

jpctool service list -id * -host *

To Page Top

Usage example 2

This example displays a list of the services at the host02 host of PFM - Agent for Platform (Windows):

jpctool service list -id * -host host02

To Page Top

Usage example 3

This example displays the service name for the product name.

jpctool service list -id * -v

To Page Top

Usage example 4

This example displays a list of all Performance Management program services including PFM - Web Console, running on the local host.

jpctool service list -key all

To Page Top

Output example

When the command is executed in Format 1 on a host that does not support status management function (when the -v option is not specified)
When the command is executed in Format 1 on a host that supports status management function (when the -v option is not specified)
When the command is executed in Format 1 on a host that supports status management function (when the -v option is specified)
When the command is executed in Format 2 on a host that supports status management function (when the all argument is specified for the -key option)

To Page Top