Command Line Utilities

 

The Abatset command allows a Job to pass parameters and/or variables (and their values) to Jobs that will be triggered through the Completion Trigger A completion trigger provides the ability for a Job or Plan to trigger another Job or Plan after it completes. You can determine which jobs or plans to trigger based on how your Job or Plan completes. For example, you can trigger one set of jobs if your Job completes successfully, and another set if your Job fails. facility. The Abatset command can also be used to update a Plan's variables. This command can be used in a script or process Job type, and in some Jobs Library Job steps, which includes the EmbeddedScript, ShellCommand and ExecutePowerShellScript steps. The syntax used to call an Abatset.exe will depend on the scripting language you are using.

 

Note: If the variables are not present on the downstream Job or Plan, they are added. If they are present, they are updated. All this happens runtime. The object definitions are not modified in any way. See the instance's history where variable inserts and updates are recorded.

 

Format:

ABATSET [/current] [/success | /failure] [/param parameter-list] [/env var=value,…] [/var var=value,…]

Qualifiers:

/current

If specified, the Job’s current parameters and locally defined variables are passed to the completion triggered Jobs. If a local variable has the "export as Job environment" property checked, you can optionally access the variable on the downstream Job as an environment variable (in addition to accessing it as an ActiveBatch variable using ${} syntax). When the Job's current parameter is passed, it is automatically set as the input parameter of the downstream Job. For example, if JobA has an input parameter named "Dept1", the downstream Job will have the same parameter (Dept1) automatically added as its input parameter, runtime.

/success | /failure

These qualifiers are used in conjunction with /env, /var, and /param. They are not applicable when updating a Plan variable and using /current. If specified, the respective qualifier indicates which completion trigger list should be used for the parameters and/or variables. For example, if /success is specified, then the parameters/variables specified are used for completion trigger success processing. If neither /success or /failure are specified then both completion trigger lists are used. Please note that if you need to specify different parameters/variables for both lists you will need to specify two (2) separate abatset commands.

/param

This optional qualifier indicates the parameters that you would like to pass to the completion triggered Jobs. Each parameter is delimited by a space. If you need to pass an embedded space then the shell rules for your operating system apply (for example, “ “, or \”).  This qualifier differs from /current because you are not passing the current Job's parameter, but rather you are setting the parameter(s) to pass to a downstream Job.  For example, the command abatset /param "2023 PO31" will pass two input parameters to the downstream Job - 2023 and PO31. This example is calling abatset using a .cmd or .sh script.

/env var=value and /var var=value

The above optional qualifiers do the same work. They pass variables on a completion trigger, and update a Plan's variables (depending on the syntax used).

 

Note: /env and /var can be used interchangeably on a Windows system; the same exact work is done, there is no programmatic difference. Non Windows Agents (e.g. Linux/UNIX) must use /env only - as /var is not supported).

 

When passing a variable to a downstream Job on a completion trigger, the variable can be accessed as an ActiveBatch variable ($ Varname} or as an environment variable. This is true using either /var and /env. This does not apply to updating a Plan's variables (they cannot be accessed as environment variables).

 

The /env and /var qualifiers specify the variable name and its value that will be passed to a downstream Job on a completion trigger, or used to update a Plan variable. Using /var VarName=value, “VarName” indicates the variable name and “value” indicates the variable value. If the value contains an embedded space, then the shell rules for your operating system apply. If the variable name as specified is already a part of the Job’s variables, then the variable is updated with the new value. If the variable isn’t a part of the Job’s environment, then the variable name and value is added.

 

If you wish to update a Plan variable, use the ../ syntax as follows: /env ../PlanVar=test (/var will work as well, only on Windows systems). This would access the variable named PlanVar on the upstream Plan and add the variable if it is not currently defined on the definition, or update it with the new value (i.e. "test") if it does exist. In order for this to work, the Plan must be triggered. As a reminder, any variable updates and additions are done runtime only. Object definitions are not modified in any way.

Additional notes

• Abatset qualifiers are generally not mutually exclusive. For example, abatset /var VarName="Test" /current will pass to a downstream Job: VarName, its local variables, and its input parameters. But, as an exception, since /param and /current both pass input parameters, /param will override /current, but you could still use both if you wanted the local variables passed (/current) in addition to setting input parameters using /param.

• To avoid a race condition, make sure the first Job in the flow calling abatset has completed before the next Job that needs to access the variable runs. It is up to the script calling abatset to wait for the complete execution of the abatset process. ActiveBatch has no way of monitoring the sub process created when abatset is called.

• Similar functionality is available in the Jobs Library SetVariable and SetVariables Jobs Library Job steps. The steps do not provide all the features of abatset, but it includes key functionality. You can use these steps to pass variables to a downstream Job on a completion trigger and to update a Plan's variables.

 

This command allows you to control the high-availability features of ActiveBatch’s Job Scheduler system, if you have purchased ASCI's non-cluster failover license. These features are only available if licensed and enabled.

 

With abatavlmgr you can designate preference order in terms of active and standby Job Scheduler machines, failover a Job Scheduler manually, stop a Job Scheduler service and also list the active set of Job Scheduler machines.

 

Format:

ABATAVLMGR   command   [qualifiers]

Parameters:

command

 

This required argument specifies the action to be performed. Valid commands are: ABORT, ACTIVE, CONFIG, FAILOVER, LIST, START and STOP.

Qualifiers:

-d connect_str

 

This qualifier is required for all commands except START and STOP. This qualifier indicates the connection string information or ODBC system DSN to use to access the ActiveBatch database.

 

-p password

 

This optional qualifier indicates the password for a –u qualifier. This qualifier may be required if your database access uses database rather than Windows authentication.

 

-u username

 

This optional qualifier indicates the username that abatavlmgr should use when accessing the database. This qualifier and –password may be required if your database access requires Database rather than Windows authentication.

Example:

Abatavlmgr list –d abatdemo

 

This command lists the status of the Job Scheduler failover set for the database accessed through DSN abatdemo.

 

This command allows you to either associate persistent data with a Job instance for the purposes of possible restart/checkpoint or you can send progress information as to where a Job may currently be executing.

 

Format:

ABATCHKPT  data

Parameters:

data

 

This mandatory parameter contains the information to either be checkpointed as persistent data or the progress information as to where a Job is currently executing.

Example:

Abatchkpt   “Test 1 of 15”

 

This command allows you to perform date arithmetic and substitution from a base source file that contains date arithmetic tags and creates an output file with the computed dates in place of the tags.

 

Format:

ABATDATESUB    source-file   output-file   [date]

Parameters:

Source-file

 

This mandatory parameter indicates the file specification of the input source file. This file should contain date arithmetic tags (although it is not a requirement).

 

Output-file

 

This mandatory parameter indicates the output file specification. This file will contain the computed dates in place of the tags.

 

Date

 

When specified, this optional parameter, will be used to load the <DATE> tag. The format of this parameter is DDMMMYYYY. If this parameter is omitted, today’s date is used.

Example:

Abatdatesub   c:\template.dat  c:\output.dat

 

This command allows you to create, update or remove an encrypted DB Password associated with an ActiveBatch backend database. During the product installation you were given an opportunity to indicate what type of authentication you supported for access to the ActiveBatch database. For database authentication you needed to specify a user account and a password. This utility command allows you to change the encrypted version of that password. This may be necessary if you have to change the password associated with the user account.

 

Format:

ABATDBPWD   [password]

Parameter:

password

 

This optional argument specifies the password to be encrypted. If it is omitted, the utility will prompt twice (with echo disabled) for a new password. If you specify a NULL argument (i.e. “”), the password registry item is deleted. This is what you would do if you decided to have an account with no password (i.e. password is blank).

Example:

abatdbpwd   password

 

This command encrypts the word “password” and stores that encrypted form in the ActiveBatch Job Scheduler registry.

 

This command allows you to execute streams of SQL statements.

 

Format:

ABATEXECSQL   connect-str    script.sql [username] [password] [-s]

Parameters:

connect-str

 

This required parameter provides either a connection string or a data source name (DSN) to use to access the database.

 

script.sql

 

This required parameter indicates the file specification containing the SQL statements.

 

username

 

This optional argument specifies the username to be used when accessing the database. By default, Windows authentication is assumed and the current logon security credentials are used. If your database uses the native authentication scheme you will want to specify a username and password.

 

password

 

This optional argument specifies the password to be used in conjunction with the specified username.

Qualifiers:

-s

 

This optional qualifier enables silent mode operation.  Silent mode disables all message logging (including errors).

Remarks:

While you can specify a DSN, you may see a performance penalty since a new layer (ADO) has been introduced to support the connection-string method of attaching to a database. To avoid this penalty, we recommend that you use the connection-string method instead of a DSN. This causes ADO to use OLE/DB instead of ODBC.

Examples:

abatexecsql “file name=activebatch.udl” c:\test.sql

 

This command executes a series of SQL statements contained in the file “c:\test.sql”. The Microsoft DataLink file, ActiveBatch.udl, contains the server, database and authentication information necessary to successfully connect to the database. Note: Microsoft Data Link requires that the UDL file be Unicode.

 

abatexecsql   abattest    c:\test.sql

 

This command executes a series of SQL statements contained in the file “c:\test.sql” and applies those commands to the database as denoted by its DSN “abattest”.

 

This command, for UNIX-based machines only, allows you to execute a program that requires a tty.

 

Format:

abatpty [-d driver] [-einv] program-specification  [arguments,..]

Parameter:

program-specification

 

This required parameter specifies the location of the program that is to be executed under the newly created ptty device.

Qualifiers:

–d  driver

 

This optional qualifier indicates what driver is to be used for stdin/stdout.

 

–e

 

This optional qualifier indicates noecho for child pty.

 

–n

 

This optional qualifier indicates not interactive

 

–i

 

This optional qualifier indicates that EOF is to be ignored on standard input.

 

–v

 

This optional qualifier indicates verbose (for abatpty debugging).

Usage and Remarks:

This command is useful when a program requires a tty (or in this case a “ptty”) for proper operation. To use this program with an ActiveBatch Job, place “abatpty” in the script filename portion of a Process type Job and then place any abatpty qualifiers, your program specification and any arguments in the parameters field of the Job. If you’re uncertain as to what abatpty qualifiers are to be used you should typically specify “–i”.

This program was adapted from a UNIX freeware program named “pty”.

 

Example:

abatpty –i sample

This command executes the program “sample” under a newly created ptty.

 

This command allows you to generate ActiveBatch reports from pre-existing Report Definition files using ODBC/OLE-DB access (highly recommended). The Report Definition files were created using the Reporting Facility (see Tools > Reporting Facility).

 

Format:

ABATRPTGEN   -r ReportFile –o OutputFile –d OdbcConnect [ -t OutputType]

Qualifiers:

-c ReportFile

 

This qualifier may be used to convert Report definition files (.ABR) from a prior version.

 

-r ReportFile

 

This required qualifier provides the Report definition file (.ABR) specification.

 

-o OutputFile

 

This required qualifier provides the output file specification of the report file itself.

 

-d OdbcConnect

 

This required qualifier provides the connection information for ODBC to connect to your selected database. (See Section 13.3.1 and the comment concerning ODBC Connection String)

 

-t OutputType

 

This optional qualifier indicates the type of report file produced. By default, HTML is used. You can also specify CSV or XML.

Example:

abatrptgen  -r  “c:\program files\asci\activebatch\reports\SampleReport.abr”  -o SampleReport.html  -d  “Driver=SQL Server;Server=ENGSERVER1;Database=ASCIABAT”

 

This convenient command not only generates report files but can also generate a CSV file which can be used to import the report data into a variety of other third-party tools. AbatRptGen can also generate an XML file for simplified parsing and data formatting.

 

This command allows you to generate ActiveBatch reports from pre-existing Report Definition files using the COM method. This method is only recommended if you want to generate a report concerning future activity. The Report Definition files were created using the Reporting Facility (see Tools > Reporting Facility).

 

Format:

ABATRPTGEN   -r ReportFile –o OutputFile –j JSSMachine [-u Username] [p Password]  [ -t OutputType]

Qualifiers:

-r ReportFile

 

This required qualifier provides the Report definition file (.ABR) specification.

 

-o OutputFile

 

This required qualifier provides the output file specification of the report file itself.

 

-j JSSMachine

 

This required qualifier provides the Job Scheduler machine name (or IP address) for connection through ActiveBatch COM.

 

-u Username

 

This optional qualifier allows you to specify an alternative username for COM security purposes when connecting to the Job Scheduler. By default, your logon credentials are used.

 

-p Password

 

This optional qualifier (typically used in conjunction with –u above) allows you to specify a password for the username specified with the –u qualifier.

 

-t OutputType

 

This optional qualifier indicates the type of report file produced. By default, HTML is used. You can also specify CSV or XML.

Example:

abatrptgen  -r  “c:\program files\asci\activebatch\reports\SampleReport.abr”  -o SampleReport.html      -j  ASCI52

 

This command allows you to maintain your stored user accounts on Microsoft Windows systems. Stored user accounts and passwords are those in which the “Save/Remember Password” checkbox has been enabled. This checkbox is presented whenever security credentials are required and allow the convenience of saving a user account and password rather than having to re-enter the data. This is similar to saving passwords when using a web browser. AbatUpdPwd allows you to otherwise maintain (add, replace, delete, list) those stored user accounts. Please note that you can only access these stored accounts that are associated with your current Windows security credentials. In other words, User A cannot access User B’s stored accounts.

 

Format:

ABATUPDPWD password [user-account] [machine-queue] [/ADD | /REPLACE]

ABATUPDPWD user-account [machine-queue] /DELETE

ABATUPDPWD /DELETEALL

ABATUPDPWD /LIST

Qualifiers:

machine-queue

 

This parameter further qualifies the user-account parameter since two or more machines may have the same useraccount but different passwords (in which case they are really different accounts). If the user-account is a domain account then a domain should be specified in this parameter. If the user-account is specific for a given machine then the machine name should be specified here. Rather than specify a machine you can specify an ActiveBatch queue name that is to provide context in distinguish similar usernames that actually represent different accounts for different machines. Typically the queue would be a Generic Queue since the machine associated with an Execution Queue would avoid any username ambiguity.

 

password

 

This mandatory parameter is the password to be associated with a user-account.

 

user-account

 

This parameter indicates the user-account that is to be stored or deleted. The User Account is entered using the same syntax that would be specified and is acceptable on the target machine it is expected to be used on. For Windows machines, domain\user or machine\user is typically specified. For other platforms, the username would be specified.

Example:

Abatupdpwd  newpassword  sample\user

 

This command updates the User Account (sample\user) with a new password.