User Guide : Using Runtime Engine : Runtime Engine Command Line Interface : Command Line Syntax and Usage
 
Share this page             
Command Line Syntax and Usage
This section provides the command line syntax and details to run artifacts in JSON and XML formats.
If the map or process runs successfully, error messages are not displayed and the command prompt appears. For further confirmation that the run has completed without errors, review the log file.
If the return code is zero, it indicates successful execution. If it is non-zero, it indicates that the log may contain error messages.
Note:  You can stop the process execution by pressing <CTRL+C>.

If any changes are required in the map or process file, to resolve errors, it is recommended to use the Studio IDE in a development environment and follow your organization's lifecycle promotion practices prior to re-deploying any modifications to a production environment.
Running a Map
To a run a map in JSON format, use the following syntax:
djengine -RC {fullPathAndFileNameOfMapRTC}
This runs the map using the settings exactly as they appear in the map runtime configuration file.
When RTC and Map files are in the same directory
If the map RTC file is in the same directory you are running djengine from, then {fullPathAndFileNameOfMapRTC} can be only the file name of the map RTC and the full path is not required. The entry point is only the map file name. For example:
djengine -RC c:\temp\Package\SimpleMap.map.rtc
Map RTC file content:
"entryPoint" : "SimpleMap.map"
When RTC and Map files are not in the same directory
If the map file is not in the same directory as the map RTC file, the RTC's entry point must be a relative path from the RTC file or absolute path. For example:
djengine -RC c:\temp\Package\SimpleMap.map.rtc
Map RTC file content:
"entryPoint" : "c:/temp/mymaps/SimpleMap.map" OR "../../SimpleMap.map"
Running a Process
To a run a process in JSON format, use the following syntax:
djengine -RC {fullPathAndFileNameOfProcessRTC}
This runs the process using the settings exactly as they appear in the process runtime configuration file.
When RTC and Process files are in the same directory
If the process RTC file is in the same directory you are running djengine from, then {fullPathAndFileNameOfProcessRTC} can be only the file name of the process RTC and the full path is not required. The entry point is only the process file name. For example:
djengine -RC c:\temp\Package\SimpleProcess.process.rtc
Process RTC file content:
"entryPoint" : "SimpleProcess.process"
When RTC and Process files are not in the same directory
If the process file is not in the same directory as the process RTC file, then {fullPathAndFileNameOfProcessRTC} is the full path of the process RTC file. The entry point is the a relative path to the rtc file or the absolute path. For example:
djengine -RC c:\temp\Package\SimpleProcess.process.rtc
Process RTC file content:
"entryPoint" : "c:/temp/myprocesses/SimpleProcess.process" OR "../../SimpleProcess.process"
Running Multiple Maps or Processes
To run multiple maps or processes (in JSON format) from the command line, the syntax is:
djengine -RC {fullPathAndFileNameOfProcessRTCFile1} -RC {fullPathAndFileNameOfProcessRTCFile2}
Running a Map or Process in djar
The map or the process RTC file can be inside or outside the djar file.
The djengine.exe must be in your path and DJLIB must be set to point to the engine's cosmos.ini file. The cosmos.ini must have a valid license file specified in the LicenseFile property. For more information, see Invoking Runtime Engine Using CLI.
To run a map or process that is inside the .djar, use the following syntax:
djengine -RC {fullPathAndFileNameOfInternalRTCStartingWithTheJarLocation}
For example:
djengine -RC c:\temp\Package\SimpleMap1.0.djar\SimpleMap-1.0\SimpleMap.map.rtc
djengine -RC c:\temp\Package\SimpleProcess\SimpleProcess1.0.djar\SimpleProcess-1.0\SimpleProcess.process.rtc
To run a map or process that is outside the .djar, use the following syntax:
djengine -RC {fullPathAndFileNameOfExternalRTC}
The entry point must be:
"entryPoint" : {OptionalPath}{FileNameOfDjar}/{folderPathstoRunnableArtifact}/{RunnableArtifactFileName}
Map Example
djengine -RC c:\temp\Package\SimpleMap\SimpleMap_djar.map.rtc
Map RTC content:
"entryPoint" : "SimpleMap1.0.djar/SimpleMap-1.0/SimpleMap.map",
Process Example
djengine -RC c:\temp\Package\SimpleProcess\SimpleProcess_djar.process.rtc
Process RTC content:
"entryPoint" : "SimpleProcess1.0.djar/SimpleProcess-1.0/SimpleProcess.process",
Running a Map or Process (XML)
To run a map (XML format) from the command line, the syntax is:
djengine [map_file.tf.xml]
This runs the map using the settings exactly as they appear in map_file.tf.xml.
Enter the global options before the map or process file name on the command line:
djengine [global options] [map/process specifications]
To run a process (XML format) from the command line, the syntax is:
djengine process_file.ip.xml
The process runs using the settings in the file process_file.ip.xml.
To change or add settings, use global options but you must specify that you are running a process first using the process execute –pe option:
djengine [global options] -pe [process options] [process specifications]
For example:
djengine -option1 -pe process_file.ip.xml
Running Multiple Maps and Processes (XML)
You can run more than one map or process from a single command line. They are executed sequentially from left to right. Processes with options must be preceded by –pe. The options that is applied to each map or process must be specified immediately before that map or process. For example, the following command line indicates to run map_1 map and then called process_1 process:
djengine map_1.tf.xml –pe process_1.ip.xml
Any options specified before the map_1 applies to the map and any option specified after ‑pe, but before process_1 applies to the process. Therefore, in the command line:
djengine –option1 –option2 map_1.tf.xml –pe -option3 process_1.ip.xml –option4 map_2.tf.xml
Items -option1 and -option2 apply to map_1, -option3 applies to process_1, and ‑option4 applies to map_2.
Specification Files
If you want to build complex collections of options and save these for repeated use, you can create a specification file. This is an ASCII text file containing as many global options as required plus the map or process file name. Specification files were previously known as optfiles.
To read a specification file, prefix the file path name with an ampersand @:
djengine @specification_file
You can use additional global options with a specification file. Also, additional specification files may be used (usage is not restricted to a single specification file).
Note:  The @specification_file syntax must be on a single line with no carriage returns.
Additional Information
Options must be prefixed with a hyphen (or a forward slash on non-Linux versions).
Options can be abbreviated but must have enough characters to be unique. For example, Verbose can be shortened to “Verb”, but not “Ver”, because that can be interpreted as Version.
Long option names are not case-sensitive. For instance, -error and -Error are the same. However, certain short names are case-sensitive. For example, -V for Version and -v for verbose.
When duplicate options are encountered on the command line or in the option file, the last option overrides any previous duplicate option. The exceptions to this are the following options:
-Source_Filter_Expr
-Target_Filter_Expr
Each of these options encountered add a new filter to the map or process.
Quotes and Escape Characters
Parameter values containing spaces, special characters, and binary values must be used in quotation marks. If a value contains no special characters, then quotes is optional. Runtime Engine supports several quote conventions for representing data:
Single Quotes
Double Quotes
Control Characters in Double Quotes
Override Strings Enclosed in Double Quotes
Single Quotes
Single quotes indicate to use the values enclosed in single quotes literally. No escaping is used with single quotes. Single quotes (') are used around text values that include blanks, equal signs (=), or semicolons (;). For example:
'InstallDir\ProductName\Data Directory'FieldSeparator=';'
Double Quotes
Enclose multi-word values (containing spaces or special characters) in quotes, otherwise only the characters prior to the space or special character is used. For example, C:\Program Files\MyData is read as C:\Program unless the string is enclosed in quotes.
Double quotes enable escaping through the use of the backslash (\). For example, if the special character semicolon is a value that is in double quotes, it must be represented as backslash semicolon (\;) so that the Runtime Engine uses the actual value (;).
Sometimes values are already enclosed in double quotes. In this case, the backslash character must be used prior to the special characters. For example:
"File=\"C:\\Program Files\\InstallDir\\Data\
Directory\";FieldSeparator=\";\";
Control Characters in Double Quotes
If the data includes control characters or binary values, double quotes (") must be used. When enclosed by double quotes, the backslash (\) can be used as the escape mechanism. This escaping convention is similar to the one used in the C language. When a backslash appears in the text, it indicates the start of an escape sequence. The following escape sequences are supported:
 
Escape Sequence
Description
\\
Backslash
\''
Double quote
\n
ASCII line feed
\r
ASCII carriage return
\t
ASCII tab
\0
ASCII null
\ddd
Decimal representation of character
\xdd
Hex representation of character
Override Strings Enclosed in Double Quotes
If an option file override string is enclosed in double quotes, then Runtime Engine uses backslash as an escape character. To avoid errors, you can do any of the following:
Use the override string on the command line rather than in an option file
Use forward slashes in the path name rather than backslashes
Enclose the override string in single quotes rather than double
Use a double backslash as the escape character for backslash.