HCL Workload Automation, Version 9.4

Variable and parameter definition

Variables and parameters are objects to which you assign different values.

Variables and parameters are useful when you have values that change depending on your job streams and jobs. Job stream, job, and prompt definitions that use them are updated automatically either at the start of the production cycle or at the time the job runs depending on the format used when the variable is specified.

Use variables and parameters as substitutes for repetitive values when defining prompts, jobs, and job streams. For example, using variables for user logon and script file names in job definitions and for file and prompt dependencies permits the use of values that can be maintained centrally in the database on the master.

While variables are scheduling objects that are defined in the HCL Workload Automation database and can be used by any authorized users in the domain, parameters are defined and used locally on individual agents.

The following sections describe variables and parameters in detail.

Variables

Variables are defined as scheduling objects in the database. Variables can be defined individually with the following command:

$parm
[tablename.]variablename “variablevalue”
...

where:

tablename: Is the name of the variable table that is to contain the new variable. The variable table must be already defined. If you do not specify a variable table name, the variable is added to the default table.
variablename: Is the name of the variable. The name can contain up to 64 alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter.
value: Is the value assigned to the variable. The value can contain up to 1024 alphanumeric characters. Do not include the names of other variables.

However, the recommended way to define variables is to use a Variable table definition. In any case, all variables are placed in a variable table. If you define a variable and do not specify the name of a variable table, it is included in the default variable table.

Variables can be used in job and job stream definitions. They are resolved; that is, they are replaced with their assigned value when the production plan is generated or extended, or when you submit a job or a job stream for running. The format used to specify a variable also determines when the variable is resolved with a value. The following formats can be used when specifying a variable:

^variablename^: Specify the variable in this format if you want it resolved when the plan is generated or extended.
${variablename}: Specify the variable in this format if you want it resolved or overwritten when the job or job stream is submitted to be run. An option in the job definition that indicates to resolve variables at the job run time must also be specified. If this variable is present only in the default variable table, the variable cannot be resolved. See an example of an application of this kind of variable in the section Examples.
Attention: When submitting a job stream from the Self-Service Catalog that contains variables or that has a variable table associated to it, variables specified in this format, ${variablename}, are not supported. They must be specified in the ^variablename^ format.

For details on variable resolution, see Variable resolution.

The variable names specified in these definitions are first resolved against variable table definitions and then on local parameters if the variables are not found.

When you specify a variable, enclose the entire string containing the variable in quotation marks.

If the variable contains a portion of a path, ensure that the caret characters are not immediately preceded by a backslash (\) because, in that case, the \^ sequence could be wrongly interpreted as an escape sequence and resolved by the parser as caret character. If necessary, move the backslash into the definition of the variable between carets to avoid bad interpretation of the backslash character. For example, the following table shows the correct way for defining and using a variable named MYDIR in the default variable table:

Wrong way Right way

Table 1. How to handle a backslash in variable substitution
Wrong way	Right way
Define the `MYDIR` variable as: `$PARM MYDIR "scripts"` Use it in this way: `job01 scriptname "c:\operid\^MYDIR^\test.cmd"` Use it in this way: `job01 scriptname "c:\operid\${MYDIR}\test.cmd"`	Define the `MYDIR` variable as: `$PARM MYDIR "\scripts"` Use it in this way: `job01 scriptname "c:\operid^MYDIR^\test.cmd"` Use it in this way: `job01 scriptname "c:\operid${MYDIR}\test.cmd"`

Define the MYDIR variable as:
```
$PARM 
MYDIR "scripts" 
```

Use it in this way:

job01 scriptname
"c:\operid\^MYDIR^\test.cmd"

Use it in this way:

job01 scriptname
"c:\operid\${MYDIR}\test.cmd"

Define the MYDIR variable as:
```
$PARM 
MYDIR "\scripts" 
```

Use it in this way:

job01 scriptname
"c:\operid^MYDIR^\test.cmd"

Use it in this way:

job01 scriptname
"c:\operid${MYDIR}\test.cmd"

This is true for all command line commands, graphical user interfaces, and APIs through which you use variable substitution.

Parameters

Local parameters are defined in a local database on the workstation where the jobs using them will run. To define them, you do not use this composer command but the parms utility command.

Local parameters can be used in:

JCL
Log on
Prompts dependencies
File dependencies
Recovery prompts

A local parameter is defined within these keywords or from within the invoked job script using the following syntax:

'bin\parms PARAMETERNAME'

Local parameters are resolved using the definitions stored in the local PARMS database as follows:

At run time on the workstation where job processing occurs.

At submission time on the workstation where the job or job stream is submitted from the conman command line. Table 2 summarizes in which submit command keyword you can use parameters.

Table 2. Keywords that can take local parameters in submit commands
Keyword	submit docommand (sbd command)	submit file (sbf command)	submit job (sbj command)	submit job stream (sbs command)
abendprompt	✓	✓	✓
scriptname		✓
docommand	✓
logon	✓	✓
opens	✓	✓	✓	✓
prompt	✓	✓	✓	✓

For more information on how to submit jobs and job streams in production from the conman command line refer to Managing objects in the plan - conman.

On UNIX, when you define a job or job stream in the database, you must enclose the string

path/parms parametername

between ' ' characters to ensure the parameter is solved at run time on the workstation even if a parameter with the same name is defined as a global parameter in the HCL Workload Automation database. For example, if you add to the database the following job definition:

$jobs
myjob 
  docommand "ls ^MYDIR^"
  streamlogon "^MYUSER^"

and two parameters named MYDIR and MYUSER are defined in the database, then, as the production plan is created or extended, the two parameters are resolved using the definitions contained in the database and their corresponding values are carried with the Symphony file. If you define in the database myjob as follows:

$jobs
myjob 
  docommand "ls 'bin/parms MYDIR'"
  streamlogon "'bin MYUSER'"

then as the production plan is created or extended the only action that is performed against the two parameters in the definition of myjob is the removal of the ' ' characters, the parameters are carried in the Symphony file unresolved and then are resolved at run time locally on the target workstation using the value stored in the PARMS database.

Examples

Two parameters, glpah and gllogon, are defined as follows:

$parm
glpath     "/glfiles/daily"
gllogon     "gluser"

The glpath and gllogon parameters are used in the gljob2 job of theglsched job stream:

schedule glsched on weekdays
:
gljob2
     scriptname "/usr/gl^glpath^"
     streamlogon "^gllogon^"
     opens "^glpath^/datafile"
     prompt ":^glpath^ started by ^gllogon^"
end

An example of a variable used with the docommand keyword is:

docommand "ls ^MY_HOME^"

The following example demonstrates how specifying variables in different formats allow for variables to have different values because they are resolved at different times. It also demonstrates how variables can be passed from job to job in a job stream. The variable, SWITCH_VAR is defined in the variable table, STATETABLE, with an initial default value of on. The job, UPDATE1, is responsible for changing the value of the SWITCH_VAR variable in the STATETABLE variable table to off. The job stream PROCJS contains two identical jobs, PROC1 and PROC2, in which the SWITCH_VAR variable has been specified in two different formats. The first sets off the variable with the caret (^) symbol ^var_name^, and the second, uses the format ${var_name}:

<jsdle:script>echo ^SWITCH_VAR^:${SWITCH_VAR}</jsdle:script>

The order in which these jobs run is the following:

SCHEDULE NC117126#PROCJS
VARTABLE STATETABLE
:
NC117126_1# PROC1

NC117126_1# PROC2
 FOLLOWS UPDATE1

NC117126_1# UPDATE1
 FOLLOWS  PROC1
END

When the job stream is added to the plan, SWITCH_VAR, defined in both PROC1 and PROC2, immediately assumes the default value assigned in the variable table, on. When the job stream is submitted to be run, the first job to be submitted is PROC1 and the variable defined as SWITCH_VAR is resolved to on so that the variables in the PROC1 job are resolved as:

<jsdle:script>echo on:onjsdle:script>echo on:on</jsdle:script>

UPDATE1 then runs setting the value of SWITCH_VAR in the variable table to off so that when PROC2 runs, the variables are resolved as:

<jsdle:script>echo on:onjsdle:script>echo on:off</jsdle:script>

The variable specified as ^SWITCH_VAR^ in the job maintains the value of on because variables in this format are resolved when the job stream is added to the plan and are not refreshed when the job is submitted to run. Instead, the variable specified in the format, ${SWITCH_VAR}, which was previously set to on is now updated with the new value in the variable table off.

Creating a variable definition using the Dynamic Workload Console

To create a variable definition in the Dynamic Workload Console, you must add it to a variable table definition:

Click HCL Workload Automation→Workload→Design→Create Workload Definitions
Select an engine name and click Go
Open in edit mode an existing variable table from the Quick Open pane, or create a new variable table as described in Variable table definition
In the Properties - Variable Table panel, click the Variables tab and add new variable definitions by clicking the "+" (Add) icon and specifying variable names and values

For more information, see Customizing your workload using variable tables.