ServiceManager - Command Line Program (CLI)

The command line program (UCYBSMCL) allows you to manage your services via batch processing. It is available for Windows and UNIX.

This page includes the following:

Overview

You can start and end services, as well as call up a list services of a computer in a ServiceManager environment.

Note: The CLI Program is case-sensitive.

All services that belong to the ServiceManager's environment can be protected with a password, thus protecting the services from being started, ended, or modified without authorization.

There are three different authorization levels:

Read

Allows you to monitor the status of the services.
Read and execute

Allows you to execute commands, such as start and stop services, and monitor the status of the services.
Read, execute, and administrate

Allows you to edit the configuration of the ServiceManager, to execute commands, and to monitor the status of the services.

Important! You require the authorization level Read, execute, and administrate to set or change passwords. For more information, see Handling Components.

You can establish a secure connection (TLS 1.2) with the ServiceManager but still support non secure connections to legacy ServiceManagers. For secure connections, you need to have CAPKI installed on the same computer in which you have installed the ServiceManager CLI. If you are using an insecure connection, the CLI executes the command towards the ServiceManager but also writes a warning message to Standard error.

If the Client Certification is enabled in the ServiceManager, the client requires a certificate for authentication. The certificate and key files for the ServiceManager - CLI have to be provided as additional command line parameters.

For more information, see CAPKI - Securing the ServiceManager.

Example

In this example, the certificate and key files are located in the .\bin directory of the ServiceManager - CLI.

ucybsmcl -c GET_PROCESS_LIST -h unixw2k01:8871 -n uc4p -certificate C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<certificatefilename>.pem -key C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<keyfilename>.pem

Some certificates may require an intermediate certificate for validation if the signing certificate authority is not trusted directly. Use the command line parameter -chain <chain file name> to point to the location of the intermediate certificate.

If the client certification is enabled and the client does not have a certificate or if the certificate validation fails, the connection is terminated. In this case, the ServiceManager writes a corresponding log entry and returns an error message to the client.

Syntax

Windows:

UCYBSMCL [.EXE] -c GET_PROCESS_LIST -h computer name -n phrase

UCYBSMCL [.EXE] -c START_PROCESS -h computer name -n phrase -s name of the service [-p password]

UCYBSMCL [.EXE] -c STOP_PROCESS -h computer name -n phrase -s name of the service [-m stop mode] [-p password]

UCYBSMCL [.EXE] -c SET_DATA -h computer name -n phrase -s name of the service -d property value [-p password]

Unix:

ucybsmcl -c GET_PROCESS_LIST -h computer name:port number -n phrase

ucybsmcl -c START_PROCESS -h computer name:port number -n phrase -s name of the service [-p password]

ucybsmcl -c STOP_PROCESS -h computer name:port number -n phrase -s name of the service [-m stop mode] [-p password]

ucybsmcl -c SET_DATA -h computer name:port number -n phrase -s name of the service -d property value [-p password]

Parameters

-c Command that is to be processed

This parameter must always be specified.

Assignment:
- GET_PROCESS_LIST: Requests a list of all services belonging to a ServiceManager environment on a computer together with the available information
- START_PROCESS: Starts a service
- STOP_PROCESS: Stops a service
- SET_DATA: Sets the properties of a service
-h Computer

This parameter must always be specified.

Assignment:
- Computer name: Name of the computer on which the ServiceManager is to be handled.
  
  A remote computer can also be used. This computer must be available from the computer which is calling it. The user must be authorized to access services on this remote computer.
- Port number: In UNIX, the port number of the ServiceManager must additionally be indicated.
-n ServiceManager environment

This parameter must always be specified.

Assignment:
- Phrase: Name of the ServiceManager environment which summarizes/outlines the various AE services on a computer. In the dialog program of the ServiceManager, this is designated as a phrase.
-s Service

This parameter must always be specified, with the sole exception of GET_PROCESS_LIST.

Assignment:
- Name of the service: Specification of the name of a service, that is:
  - displayed in the Service column of the dialog program
  - listed in the definitions file Phrase.SMD, see Setting Up an SMD File
  - available in the output of the command GET_PROCESS_LIST
  Since a service name can also contain spaces, it should always be entered within quotation marks.
-d Property value

This parameter is only required for SET_DATA.

Assignment:
- Property string: The string depends on the property that is specified.
  
  Allowed property strings:
  - Command
  - StartPath
  - UserName
  - Password
  - Domain
  - Autostart
  - Delay
  Examples
  
  ucybsmcl -c SET_DATA -h PC000666 -n Automic -s “RAFTP Agent” -d Command “java -jar -Xmx1G ucxjcitx.jar”
  
  ucybsmcl -c SET_DATA -h PC000666 -n Automic -s “RAFTP Agent” -d Autostart 1
-m End mode

This parameter is optional for STOP_PROCESS.

Assignment:
- Stop mode: Way in which a service should be ended.
  
  Allowed values: C, S, and A
  
  C: Close
  
  The service ends normally.
  
  S: Shutdown
  
  The service stops immediately independent of ongoing tasks.
  
  A: Abnormally
  
  The service is immediately stopped by the ServiceManager through a system call (kill). Use this command only when attempts by the service to stop itself were not successful.
  
  Default value: C
-p Password

This parameter is optional, depending on whether a password has been assigned to the corresponding authorization level. For instance, if a password is set for authorization level 1, a password is required even to run the GET_PROCESS_LIST.

More information:
- Handling Components
- Obfuscating Passwords
Assignment:
- Password: Password for an authorization level which covers the right to execute the command provided with parameter -c.
-sm Start mode of server work processes (WPs)

The values that are allowed for the parameter -sm depend on the service definition in the ServiceManager's SMD configuration file. For more information ,see Setting Up an SMD File.

To ensure that a specific start mode can be assigned to the WP when it starts, you must set START1=, START2=, START3= ... in the SMD file for each DEFINE of a WP service. The supplied SMD file UC4.SMD includes some sample definitions.

Assignment:
- Start mode: for example, the definition of a WP service in an SMD file (including variables):
  
  VAR SRV_STARTPATH;*OWN\..\..\Server\bin
  
  VAR WP_STARTCMD;*SRV_STARTPATH\UCsrvwp.exe *SRV_STARTPATH\ucsrv.ini -svc%port%
  
  VAR WP_STARTCMD_COLD;*WP_STARTCMD -parm"StartMode=Cold"
  
  VAR WP_STARTCMD_STOP;*WP_STARTCMD -parm"SystemStop=Yes"
  
  VAR WP_STARTCMD_COLDSTOP;*WP_STARTCMD -parm"StartMode=Cold;SystemStop=Yes"
  
  DEFINE UC4 WP2;*WP_STARTCMD;*SRV_STARTPATH;START1=(Coldstart,*WP_STARTCMD_COLD);START2=(Systemstop,*WP_STARTCMD_STOP);START3=(Coldstart with Systemstop,*WP_STARTCMD_COLDSTOP)
  
  Allowed values:
  - Coldstart: Cold start mode
  - Systemstop: Normal start
    
    The system is stopped for this purpose.
  - Coldstart with Systemstop: Cold start including a system stop.

When you call the command line program using incorrect or missing parameters, a short help text will be displayed that shows correct parameters and return codes.

Output

When you call the command line program with the GET_PROCESS_LIST command, the requested information will be displayed line by line. It corresponds to the view of the ServiceManager Dialog program.

Output format

"Service" "Status" ["ProcID" "Start time" "Runtime" "CPU Time"]

Service: Name of the service.
Status: Service's status.
- R: Running
- S: Stopped
ProcID: Service's process number.

Only information pertaining to active services (Status = R) is displayed.
Starttime: Service's start date and time.

Format: YYYY-MM-DD HH:MM

Only information pertaining to active services (Status = R) is displayed.
Runtime: Service's runtime.

Format: DD/HH:MM

Only information pertaining to active services (Status = R) is displayed.
CPU Time: CPU time required by a service.

Format: DD/HH:MM:SS:HS (HS=hundredths of seconds).

Only information pertaining to active services (Status = R) is displayed.

Return Codes

0 A command has been processed without an error.
1 An incorrect command has been entered.
2 No active ServiceManager has been located on the specified computer.

Possible reason: Either the name of the computer was not entered, or no ServiceManager is active on this computer.
3 The ServiceManager reacts to a command in an unexpected way.

Possible reason: The ServiceManager version is not up to date.
4 Errors occurred with the ServiceManager connection.
5 The specified ServiceManager environment is not present on the corresponding computer.

Possible reason: The ServiceManager for the specified ServiceManager environment is either not installed or not started.

Examples

The first example retrieves all services that belong to the computer WINW2K01 and the ServiceManager environment UC4P.

UCYBSMCL.EXE -c GET_PROCESS_LIST -h WINW2K01 -n UC4P

Output:

"UC4 CP1" "R" "1588" "2004-04-05 21:39" "0/01:11" "0/00:00:22.69"
"UC4 WP1" "R" "3388" "2004-04-05 21:39" "0/01:11" "0/00:00:22.69"
"UC4 WP2" "R" "1576" "2004-04-05 21:39" "0/01:11" "0/00:00:22.69"
"Win32-Agent WIN01" "R" "2708" "2004-04-05 21:40" "0/01:11" "0/00:00:01.31"
"Win32-Agent WIN21" "R" "2392" "2004-04-05 21:40" "0/01:10" "0/00:00:01.30"
"Win32-Agent UC4MAIL" "R" "2932" "2004-04-05 21:40" "0/01:10" "0/00:00:01.31"
"SAP Agent C46" "S"
"PeopleSoft-Agent PS01" "S"

The second example terminates a UNIX agent normally.

./ucybsmcl -c STOP_PROCESS -h unixw2k01:8871 -n uc4p -s unix01 -m Close