Use Command Line Tools to Run Transformations and Jobs
- Last updated
- Save as PDF
You can use PDI's command line tools to execute PDI content from outside of the PDI client (Spoon). Typically you would use these tools in the context of creating a script or a cron job to run the job or transformation based on some condition outside of the realm of Pentaho software.
Pan is the PDI command line tool for executing transformations.
Kitchen is the PDI command line tool for executing jobs.
Both of these programs are explained in detail below.
Pan Options and Syntax
Pan runs transformations, either from a PDI repository (database or enterprise), or from a local file. The syntax for the batch file and shell script are shown below. All Pan options are the same for both.
Windows systems use syntax with the forward slash (“/”) and colon (“:”). If spaces are present in the option values, use single quotes (“) and double quotes (“”) to keep spaces together, for example, "-param:MASTER_HOST=192.168.1.3" "-param:MASTER_PORT=8181"
pan.sh -option=value arg1 arg2
pan.bat /option: value arg1 arg2
| Switch | Purpose |
|---|---|
| rep | Enterprise or database repository name, if you are using one |
| user | Repository username |
| pass | Repository password |
| trans | The name of the transformation (as it appears in the repository) to launch |
| dir | The repository directory that contains the transformation, including the leading slash |
| file | If you are calling a local KTR file, this is the filename, including the path if it is not in the local directory |
| level | The logging level (Basic, Detailed, Debug, Rowlevel, Error, Nothing) |
| logfile | A local filename to write log output to |
| listdir | Lists the directories in the specified repository |
| listtrans | Lists the transformations in the specified repository directory |
| listrep | Lists the available repositories |
| exprep | Exports all repository objects to one XML file |
| norep | Prevents Pan from logging into a repository. If you have set the KETTLE_REPOSITORY, KETTLE_USER, and KETTLE_PASSWORD environment variables, then this option will enable you to prevent Pan from logging into the specified repository, assuming you would like to execute a local KTR file instead. |
| safemode | Runs in safe mode, which enables extra checking |
| version | Shows the version, revision, and build date |
| param | Set a named parameter in a name=value format. For example: -param:FOO=bar |
| listparam | List information about the defined named parameters in the specified transformation. |
| maxloglines | The maximum number of log lines that are kept internally by PDI. Set to 0 to keep all rows (default) |
| maxlogtimeout | The maximum age (in minutes) of a log line while being kept internally by PDI. Set to 0 to keep all rows indefinitely (default) |
sh pan.sh -rep=initech_pdi_repo -user=pgibbons -pass=lumburghsux -trans=TPS_reports_2011
pan.bat /rep:initech_pdi_repo /user:pgibbons /pass:lumburghsux /trans:TPS_reports_2011
Pan Status Codes
When you run Pan, there are seven possible return codes that indicate the result of the operation. All of them are defined below.
| Status code | Definition |
|---|---|
| 0 | The transformation ran without a problem. |
| 1 | Errors occurred during processing |
| 2 | An unexpected error occurred during loading / running of the transformation |
| 3 | Unable to prepare and initialize this transformation |
| 7 | The transformation couldn't be loaded from XML or the Repository |
| 8 | Error loading steps or plugins (error in loading one of the plugins mostly) |
| 9 | Command line usage printing |
Kitchen Options and Syntax
Kitchen runs jobs, either from a PDI repository (database or enterprise), or from a local file. The syntax for the batch file and shell script are shown below. All Kitchen options are the same for both.
Windows systems use syntax with the forward slash (“/”) and colon (“:”). If spaces are present in the option values, use single quotes (“) and double quotes (“”) to keep spaces together, for example, "-param:MASTER_HOST=192.168.1.3" "-param:MASTER_PORT=8181"
kitchen.sh -option=value arg1 arg2
kitchen.bat /option: value arg1 arg2
| Switch | Purpose |
|---|---|
| rep | Enterprise or database repository name, if you are using one |
| user | Repository username |
| pass | Repository password |
| job | The name of the job (as it appears in the repository) to launch |
| dir | The repository directory that contains the job, including the leading slash |
| file | If you are calling a local KJB file, this is the filename, including the path if it is not in the local directory |
| level | The logging level (Basic, Detailed, Debug, Rowlevel, Error, Nothing) |
| logfile | A local filename to write log output to |
| listdir | Lists the sub-directories within the specified repository directory |
| listjob | Lists the jobs in the specified repository directory |
| listrep | Lists the available repositories |
| export | Exports all linked resources of the specified job. The argument is the name of a ZIP file. |
| norep | Prevents Kitchen from logging into a repository. If you have set the KETTLE_REPOSITORY, KETTLE_USER, and KETTLE_PASSWORD environment variables, then this option will enable you to prevent Kitchen from logging into the specified repository, assuming you would like to execute a local KTR file instead. |
| version | Shows the version, revision, and build date |
| param | Set a named parameter in a name=value format. For example: -param:FOO=bar |
| listparam | List information about the defined named parameters in the specified job. |
| maxloglines | The maximum number of log lines that are kept internally by PDI. Set to 0 to keep all rows (default) |
| maxlogtimeout | The maximum age (in minutes) of a log line while being kept internally by PDI. Set to 0 to keep all rows indefinitely (default) |
sh kitchen.sh -rep=initech_pdi_repo -user=pgibbons -pass=lumburghsux -job=TPS_reports_2011
kitchen.bat /rep:initech_pdi_repo /user:pgibbons /pass:lumburghsux /job:TPS_reports_2011
Kitchen Status Codes
When you run Kitchen, there are seven possible return codes that indicate the result of the operation. All of them are defined below.
| Status code | Definition |
|---|---|
| 0 | The job ran without a problem. |
| 1 | Errors occurred during processing |
| 2 | An unexpected error occurred during loading or running of the job |
| 7 | The job couldn't be loaded from XML or the Repository |
| 8 | Error loading steps or plugins (error in loading one of the plugins mostly) |
| 9 | Command line usage printing |
Importing KJB or KTR Files From a Zip Archive
Both Pan and Kitchen can pull PDI content files from out of Zip files. To do this, use the ! switch, as in this example:
Kitchen.bat /file:"zip:file:///C:/Pentaho/PDI Examples/Sandbox/linked_executable_job_and_transform.zip!Hourly_Stats_Job_Unix.kjb"
If you are using Linux or Solaris, the ! must be escaped:
./kitchen.sh -file:"zip:file:////home/user/pentaho/pdi-ee/my_package/linked_executable_job_and_transform.zip\!Hourly_Stats_Job_Unix.kjb"
Connecting to a Repository with Command-Line Tools
To export repository objects into XML format using command-line tools instead of exporting repository configurations from within the PDI client, use named parameters and command-line options when calling Kitchen or Pan from a command-line prompt.
The following is an example command-line entry to execute an export job using Kitchen:
call kitchen.bat /file:C:\Pentaho_samples\repository\repository_export.kjb
"/param:rep_name=PDI2000" "/param:rep_user=admin" "/param:rep_password=password"
"/param:rep_folder=/public/dev"
"/param:target_filename=C:\Pentaho_samples\repository\export\dev.xml"
| Parameter | Description |
|---|---|
rep_folder |
Repository Folder |
rep_name |
Repository Name |
rep_password |
Repository Password |
rep_user |
Repository Username |
target_filename |
Target Filename |
It is also possible to use obfuscated passwords with Encr a command line tool for encrypting strings for storage or use by PDI.
The following is an example command-line entry to execute a complete command-line call for the export in addition to checking for errors:
@echo off
ECHO This an example of a batch file calling the repository_export.kjb
cd C:\Pentaho\pdi-ee-<filepath>--check--</filepath>{{contentVars.PDIvernum3}}>\data-integration
call kitchen.bat /file:C:\Pentaho_samples\repository\repository_export.kjb "/param:rep_name=PDI2000"
"/param:rep_user=admin" "/param:rep_password=password" "/param:rep_folder=/public/dev"
"/param:target_filename=C:\Pentaho_samples\repository\export\dev.xml"
if errorlevel 1 goto error
echo Export finished successfull.
goto finished
:error
echo ERROR: An error occured during repository export.
:finished
REM Allow the user to read the message when testing, so having a pause
pause
Exporting Content from Repositories with Command-Line Tools
To export repository objects into XML format, using command-line tools instead of exporting repository configurations from within the PDI client, use named parameters and command-line options when calling Kitchen or Pan from a command-line prompt.
The following is an example command-line entry to execute an export job using Kitchen:
call kitchen.bat /file:C:\Pentaho_samples\repository\repository_export.kjb
"/param:rep_name=PDI2000" "/param:rep_user=admin" "/param:rep_password=password"
"/param:rep_folder=/public/dev"
"/param:target_filename=C:\Pentaho_samples\repository\export\dev.xml"
|
Parameter |
Description |
|---|---|
|
rep_folder |
Repository Folder |
|
rep_name |
Repository Name |
|
rep_password |
Repository Password |
|
rep_user |
Repository Username |
|
target_filename |
Target Filename |
It is also possible to use obfuscated passwords with Encr, the command line tool for encrypting strings for storage/use by PDI. The following is an example command-line entry to execute a complete command-line call for the export in addition to checking for errors:
@echo off
ECHO This an example of a batch file calling the repository_export.kjb
cd C:\Pentaho\pdi-ee-<filepath>--check--</filepath>{{contentVars.PDIvernum3}}>\data-integration
call kitchen.bat /file:C:\Pentaho_samples\repository\repository_export.kjb "/param:rep_name=PDI2000"
"/param:rep_user=admin" "/param:rep_password=password" "/param:rep_folder=/public/dev"
"/param:target_filename=C:\Pentaho_samples\repository\export\dev.xml"
if errorlevel 1 goto error
echo Export finished successful.
goto finished
:error
echo ERROR: An error occurred during repository export.
:finished
REM Allow the user to read the message when testing, so having a pause
pause