Follow

How to Start an Execution Package from the Command Line

Introduction

Most often, you will execute projects from within TX DWA or on a schedule defined in TX DWA. It is, however, also possible to execute a project from the command line. This can be useful if you wish to trigger execution of projects in a script or on custom events.

Arguments and exit codes

The TX executable, timexetender.exe, can be run with two parameters: ProjectName and ExecutionPackage.

It returns the following exit codes:

  • -1 = Execution failed; please refer either to the trace log file or Windows event log for details 
  • 0 = Project or execution package was not found
  • > 0 = A positive integer value indicates a successful execution, referring to the batch ID that was assigned. Please refer to table ExecutionLogs for details about execution times.

Example

The following example shows you how you can execute a project and review the exit code on the command line or in a batch file.

Start /Wait timextender.exe <ProjectName> <Execution Package Name>
Echo %ERRORLEVEL%

Additional considerations

Spaces

If your project or execution package name has spaces in its name, you must surround the name with double quotation marks.  An example would appear like so:

Start /Wait timextender.exe "My Project Name" "My Execution Package Name"

Qualifying the execution file path

The basic example above makes a call on "timextender.exe."  In most cases this will not work as written, as the command will not be able to locate the file. 

There are two ways around this issue.  The first is to change directory to the folder that contains the TimeXtender executable before making the call.  The full command might look like this:

CD C:\Program Files\TX DWA Server\<TX DWA Server Version>
Start /Wait timextender.exe <Project Name> <Execution Package Name>
Echo %ERRORLEVEL%

Additionally, you can also fully qualify the call on timextender.exe.  If you do this, you must also pass in an additional string as a title parameter.  Since the title is not required for the command to run, you may pass in an empty string.  This modified command might look like this:

Start /Wait "" "C:\Program Files\TX DWA Server\<TX DWA Server Version>\timextender.exe" <ProjectName> <Execution Package Name>
Echo %ERRORLEVEL%

Permissions

If the command is going to be part of a .bat file or run by a third-party scheduling service, you must keep permissions in mind if you want the command to run successfully.  This is because the command inherits the permissions of the account that runs it.  While the necessary permissions will differ depending on your setup, the account that runs the command must have:

  • Permission to run an executable
  • Permissions to read and write in the repository and all other involved databases
  • Permission to read from the involved data sources

Without these permissions, the command may not start or may fail after starting.

User Configuration

When a user opens TX DWA, the software generates that user a configuration file that records the last project repository that user had open.  Much like permissions, the command inherits these configuration settings from the account that runs it as well.  In order to ensure that the execution package is run in the correct environment, the config file for that user must reference the correct repository. 

The file can also be edited manually.  The default extension for the file is:

C:\Users\<UserName>\AppData\Roaming\TX DWA Server\TX DWA Server\<TX DWA Version>\config.xml

Note that if an environment has a service user running a TX DWA Server service, that user will have the proper permissions and configuration to run command line executions by default.

Note on deployed versions

When executing a package from the command line, TX DWA will execute the last deployed version of the project.  A deployed version is a version of the project TX DWA is certain has been fully saved and implemented.  To ensure that your do not get a 0 exit code, be sure to either deploy a table in your project to create a deployed version, or save your project as a deployed version manually (TX DWA 14.6.1 and later).


This article applies to: timeXtender 4.5, tX2012, TX2014, TX DWA.

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

5 Comments

  • 0
    Avatar
    Zanoni Labuschagne

    Hi

     

    Is it possible to publish a list of all command prompt parameters TX can accept? I noticed "TimeXtender.exe /?" doesn't  show anything...

     

    Thanks,

     

    Zanoni

  • 0
    Avatar
    CALM - Co Support

    Hello,

    Have there been any improvements / additions in SR2 for the Command Line?

    KR,

    Wim

  • 0
    Avatar
    Thomas Hjermitslev

    Hi,

    SR2 has not brought any changes to using TX from the command line. Executing a project, using the two parameters described above, is still the entire functionality.

    If there's any particular functionality you'd like added, please feel free to post your idea in the  Suggestions and feature requests forum.

     

    Cheers,

    Thomas

     

     

  • 0
    Avatar
    Padarthi, Satish

    I have an error showing timextender.exe is not located on the machine I am using cmd prompt. Does this remote control to be installed on the machine?

  • 0
    Avatar
    Joseph Treadwell

    Hi Thomas, 

    I worked with Satish and his team yesterday and we were able to resolve his problem. The issue was two fold;

    1. The name of the repository was different from the default.
    2. The service user that ran their scheduling tool (UC4) was different than the TX Service user. 

    Solution: We modified the config file nested under the UC4 service users appdata folder to point to their active repository. This resolved the issue. 

    Can you update this article to include this important piece of info?

Please sign in to leave a comment.