Using pmcmd
pmcmd is a program you use to communicate with the Integration Service. With pmcmd, you can perform some of the tasks that you can also perform in the Workflow Manager, such as starting and stopping workflows and sessions.
Use pmcmd in the following modes:
- •Command line mode. You invoke and exit pmcmd each time you issue a command. You can write scripts to schedule workflows with the command line syntax. Each command you write in command line mode must include connection information to the Integration Service.
- •Interactive mode. You establish and maintain an active connection to the Integration Service. This lets you issue a series of commands.
You can use environment variables for user names and passwords with pmcmd. You can also use environment variables to customize the way pmcmd displays the date and time on the machine running the Integration Service process. Before you use pmcmd, configure these variables on the machine running the Integration Service process. The environment variables apply to pmcmd commands that run on the node.
Running Commands in Command Line Mode
Command line mode invokes and exits pmcmd each time you issue a command. Command line mode is useful if you want to run pmcmd commands through batch files, scripts, or other programs.
Use pmcmd commands with operating system scheduling tools like cron, or you can embed pmcmd commands into shell or Perl scripts.
When you run pmcmd in command line mode, you enter connection information such as domain name, Integration Service name, user name and password in each command. For example, to start the workflow “wf_SalesAvg” in folder “SalesEast,” use the following syntax:
pmcmd startworkflow -sv MyIntService -d MyDomain -u seller3 -p jackson ‑f SalesEast wf_SalesAvg
The user, seller3, with the password “jackson” sends the request to start the workflow.
If you omit or incorrectly enter one of the required options, the command fails, and
pmcmd returns a non-zero return code. For more information about all the return codes, see
pmcmd Return Codes.
To run pmcmd commands in command line mode:
1. At the command prompt, switch to the directory where the pmcmd executable is located.
By default, the PowerCenter installer installs pmcmd in the \server\bin directory.
2. Enter pmcmdfollowed by the command name and its required options and arguments:
pmcmd command_name [-option1] argument_1 [-option2] argument_2...
pmcmd Return Codes
In command line mode, pmcmd indicates the success or failure of a command with a return code. Return code “0” indicates that the command succeeded. Any other return code indicates that the command failed.
Use the DOS or UNIX echo command immediately after running a pmcmd command to see the return code for the command:
- •In a DOS shell: echo %ERRORLEVEL%
- •In a UNIX Bourne or Korn shell: echo $?
- •In a UNIX C shell: echo $status
The following table describes the return codes for pmcmd:
Code | Description |
|---|
0 | For all commands, a return value of zero indicates that the command ran successfully. You can issue the following commands in the wait or nowait mode: starttask, startworkflow, aborttask, and abortworkflow. If you issue a command in the wait mode, a return value of zero indicates the command ran successfully. If you issue a command in the nowait mode, a return value of zero indicates that the request was successfully transmitted to the Integration Service, and it acknowledged the request. |
1 | Integration Service is not available, or pmcmd cannot connect to the Integration Service. There is a problem with the TCP/IP host name or port number or with the network. |
2 | Task name, workflow name, or folder name does not exist. |
3 | An error occurred starting or running the workflow or task. |
4 | Usage error. You passed the wrong options to pmcmd. |
5 | An internal pmcmd error occurred. Contact Informatica Global Customer Support. |
7 | You used an invalid user name or password. |
8 | You do not have the appropriate permissions or privileges to perform this task. |
9 | Connection to the Integration Service timed out while sending the request. |
12 | Integration Service cannot start recovery because the session or workflow is scheduled, waiting for an event, waiting, initializing, aborting, stopping, disabled, or running. |
13 | User name environment variable is set to an empty value. |
14 | Password environment variable is set to an empty value. |
15 | User name environment variable is missing. |
16 | Password environment variable is missing. |
17 | Parameter file does not exist. |
18 | Integration Service found the parameter file, but it did not have the initial values for the session parameters, such as $input or $output. |
19 | Integration Service cannot resume the session because the workflow is configured to run continuously. |
20 | A repository error has occurred. Make sure that the Repository Service and the database are running and the number of connections to the database is not exceeded. |
21 | Integration Service is shutting down and it is not accepting new requests. |
22 | Integration Service cannot find a unique instance of the workflow/session you specified. Enter the command again with the folder name and workflow name. |
23 | There is no data available for the request. |
24 | Out of memory. |
25 | Command is cancelled. |
Running Commands in Interactive Mode
Use pmcmd in interactive mode to start and stop workflows and sessions without writing a script. When you use the interactive mode, you enter connection information such as domain name, Integration Service name, user name, and password. You can run subsequent commands without entering the connection information for each command.
For example, the following commands invoke the interactive mode, establish a connection to Integration Service “MyIntService,” and start workflows “wf_SalesAvg” and “wf_SalesTotal” in folder “SalesEast”:
pmcmd
pmcmd> connect -sv MyIntService -d MyDomain -u seller3 -p jackson
pmcmd> setfolder SalesEast
pmcmd> startworkflow wf_SalesAvg
pmcmd> startworkflow wf_SalesTotal
To run pmcmd commands in interactive mode:
1. At the command prompt, switch to the directory where the pmcmd executable is located.
By default, the PowerCenter installer installs pmcmd in the \server\bin directory.
2. At the command prompt, type pmcmd.
This starts pmcmd in interactive mode and displays the pmcmd> prompt. You do not have to type pmcmd before each command in interactive mode.
3. Enter connection information for the domain and Integration Service. For example:
connect -sv MyIntService -d MyDomain -u seller3 -p jackson
4. Type a command and its options and arguments in the following format:
command_name [-option1] argument_1 [-option2] argument_2...
pmcmd runs the command and displays the prompt again.
5. Type exit to end an interactive session.
Setting Defaults
After you connect to an Integration Service using pmcmd, you can designate default folders or conditions to use each time the Integration Service executes a command. For example, if you want to issue a series of commands or tasks in the same folder, specify the name of the folder with the setfolder command. All subsequent commands use that folder as the default.
The following table describes the commands that you use to set defaults for subsequent commands:
Command | Description |
|---|
setfolder | Designates a folder as the default folder in which to execute all subsequent commands. |
setnowait | Executes subsequent commands in the nowait mode. The pmcmd prompt is available after the Integration Service receives the previous command. The nowait mode is the default mode. |
setwait | Executes subsequent commands in the wait mode. The pmcmd prompt is available after the Integration Service completes the previous command. |
unsetfolder | Reverses the setfolder command. |
You can use pmcmd ShowSettings command to display the default settings.
Running in Wait Mode
You can run pmcmd in wait or nowait mode. In wait mode, pmcmd returns to the shell or command prompt after the command completes. You cannot run subsequent commands until the previous command completes.
For example, if you enter the following command, pmcmd starts the workflow “wf_SalesAvg” and does not return to the prompt until the workflow completes:
pmcmd startworkflow -sv MyIntService -d MyDomain -u seller3 -p jackson ‑f SalesEast -wait wf_SalesAvg
In nowait mode, pmcmd returns to the shell or command prompt immediately. You do not have to wait for one command to complete before running the next command.
For example, if you enter the following commands, pmcmd starts workflow “wf_SalesTotal” even if workflow “wf_SalesAvg” is still running:
pmcmd startworkflow -sv MyIntService -d MyDomain -u seller3 -p jackson ‑f SalesEast wf_SalesAvg
pmcmd startworkflow -sv MyIntService -d MyDomain -u seller3 -p jackson ‑f SalesEast wf_SalesTotal
By default, pmcmd executes commands in nowait mode.
You can configure the wait mode when you run in command line or interactive mode. In command line mode, use the -wait option to run a command in wait mode. In interactive mode, use the setwait or setnowait command before entering subsequent commands.
Scripting pmcmd Commands
When you use pmcmd, you might use some commands with specific options and arguments on a regular basis. For example, you might use pmcmd to check the status of the Integration Service. In this case, you can create a script or batch file to call one or more pmcmd commands including its options and arguments.
You can run scripts in command line mode. You cannot run pmcmd scripts in interactive mode.
For example, the following UNIX shell script checks the status of Integration Service “testService,” and if it is running, gets details for session “s_testSessionTask”:
#!/usr/bin/bash
# Sample pmcmd script
# Check if the service is alive
pmcmd pingservice -sv testService -d testDomain
if [ "$?" != 0 ]; then
# handle error
echo "Could not ping service"
exit
fi
# Get service properties
pmcmd getserviceproperties -sv testService -d testDomain
if [ "$?" != 0 ]; then
# handle error
echo "Could not get service properties"
exit
fi
# Get task details for session task "s_testSessionTask" of workflow
# "wf_test_workflow" in folder "testFolder"
pmcmd gettaskdetails -sv testService -d testDomain -u Administrator -p adminPass -folder testFolder -workflow wf_test_workflow s_testSessionTask
if [ "$?" != 0 ]; then
# handle error
echo "Could not get details for task s_testSessionTask"
exit
fi
Entering Command Options
pmcmd provides multiple ways to enter some of the command options and arguments. For example, to enter a password, use the following syntax:
<<-password|-p> password|<-passwordvar|-pv> passwordEnvVar>
To enter a password, precede the password with the -password or -p option:
-password ThePassword
or
-p ThePassword
If you use a password environment variable, precede the variable name with the -pv or ‑passwordvar option:
-passwordvar PASSWORD
or
-pv PASSWORD
If a command option contains spaces, use single or double quotation marks to enclose the option. For example, use single quotes in the following syntax to enclose the folder name:
abortworkflow -sv MyIntService -d MyDomain -u seller3 -p jackson ‑f 'quarterly sales' -wait wf_MyWorkflow
To denote an empty string, use two single quotes ('') or two double quotes ("").