Integrator from the Command Line

The Integrator command line has the following syntax:

integ <scriptname> [options]

Integ Command Line Options

Option Description
-first <n>

Limits each task in the script to output the given number of rows. This option allows for easy testing of scripts with only a sample of the output data. For example:

integ testone.int -first 100

This starts execution of the Integrator script testone.int, limiting each task in the script to output at most 100 rows. Any error messages are displayed on the screen. Do not confuse this run time option with the first attribute available when defining Input objects. The latter limits what is read in and the former what is written out.
-define <parm name>=<parm value>

or

-D <parm name>=<parm value>

Allows parameters to be included in a script so the same script can be used for multiple situations by supplying values at run time. Each -define argument defines a parameter and value. Multiple parameters can be defined by specifying a separate -define option for each parameter/value pair you want to include when executing the script. Parameter names cannot contain spaces or other special characters other than underscores. There are no spaces around the equal sign (=). For example, you can issue the following from a command line:

integ test.int -define COSTCOLS=true -define "DATADIR=D:\\sales"

This runs the test.int script, passing a value of true for the COSTCOLS parameter, and a value of D:\\sales for the DATADIR parameter.

The -define option is case-sensitive. -D can also be used in place of -define, but not -d or -Define.

Examples:

integ test.int -D COSTCOLS=true -D "DATADIR=C:\sales"

integ test.int -D supplier=xxx -D customer=xxx

integ Billing.int -define month=07

integ sales.int -define month="07" -define year="2013"

integ mergeqtrs.int -D file1="Q12010" -D file2="Q12012" -D file3="Q12013"

Any parameter defined as an array parameter can only be passed on the command line by referring to a file containing array values.
-task taskname

Runs a single task from the description file if specified. Other tasks in the task list will still be checked for proper Task objects and Output objects.
-disable_execute

Disables Execute and Execrows objects. This is used by Workbench to implement the security requirements for Project Administrators. See User Management.

NOTE: This setting does not apply to Tunnel scripts—Tunnels are always run with execute enabled.
-save_connect_file

Provides a way to hide an SQL connect string in a binary file so that the user name and password cannot be recovered without substantial effort. When run, Integrator prompts for a connect string as shown in the following example.

integ -save_connect_file sql-server.cfile

Data Integrator 7.1 (1) 64-bit

Copyright (C) 1991-2019 by Dimensional Insight, Inc

Enter connect string:

DSN=mydb;uid=master;pwd=secret

 

When the -save_connect_file option is given, Integrator only writes the connect file. No Integrator script is run.

Integrator's SQL Input, Process, and Output objects can use this connect file as an alternative to specifying the connect string in plain text in the script itself. Spectre's odbc-input block can also use this connect file.

NOTE: Access to this binary file should be restricted to authorized users.

See also: Options for ODBC Login Credentials.
-project <project_name>

Sets the Workbench project for running scripts. For example:

integ -project account-sales <scriptname>

-parm_encoding

Defines how parameters are encoded in the object language. Available with Integrator 7.1(18) or higher.

NOTE: On Windows systems, command-line arguments are passed in as Unicode strings. In general, Unix systems pass characters as they find them, and let programs interpret them however they want.

The -parm_encoding argument takes the string "latin1", "utf-8", or "default". The default parameter encoding is "default" which implies no conversion.

  • If the value of this argument is "latin1", the Integrator will assume that the command-line arguments are Unicode, and will convert them to Latin1 before substituting the parameter values into the Integrator script.

  • If the value of this argument is "utf-8", the Integrator will substitute the parameter values without any conversion.

  • If the value of this argument is "default", the Integrator will substitute the parameter values without any conversion.

Example:

integ qa-testcase.int -define dimname=åäö -parm_encoding "latin1"

Here the Unicode dimension name is converted to Latin1 before it is used in the Integrator script.

In order to run in 7.x, Integrator needs to be aware of DiveLine's dataroot and the Project name. Set the latter using the -project option with the execution, as shown in the table above. For the dataroot, check the current setting for the environment variable DI_HOME. For example, on Windows:

  1. Open a command prompt.

    Start > CMD.exe

  2. Type echo %DI_HOME%

    If the variable is not set or incorrect, set it to the appropriate data root.

  3. For example, type set DI_HOME=C:\DI\Solution\dl-dataroot70

    You can then start Integrator using the -project option.

  4. For example, enter:

    integ -project MyProject /programs/my-script.int

Additional Considerations

At execution time, standard output can be redirected to a file. This can make it easier to debug or audit scripts. For example, on Windows, command line output can be redirected from the console to a file by using the angle brackets (> or >>) on the command line. The > creates a new file, while >> appends to an existing file if it exists, or creates a new file if it does not exist.

Example

integ prod.int >stdout.log

All informational and error output from Integrator executing the script prod.int would be written to stdout.log.

Automated error reporting is available in Integrator and should only be enabled upon a request by Dimensional Insight. This reporting is enabled with the following syntax:

integ problem.int -error_report_id "<source id>"

Below are some representative error messages that may occur (and their causes).

When doing a lookup with an inner join, duplicate values of the join keys will result in warning messages. For example:

Warning: Duplicate value "xxx" found in join column on row nn for lookup object aaa.

—will occur when Integrator has encountered a duplicate lookup record in a single column case.

Warning: Duplicate values "xxx,yyy,zzz" found in join columns on row nn for lookup object aaa.

—will occur when Integrator has encountered a duplicate lookup record in a multicolumn case when using multijoins.