Using Substitution Variables

Whenever a substitution variable is used in a command or message string, it must be typed in the following format:

&name;
& Ampersand denotes the start of a substitution variable. Use ‘&&’ to include ‘&’ as part of the text. i.e ‘Hello && Goodbye’ = Hello & Goodbye
name Name of the substitution variable
; Optional semi-colon denotes the end of a substitution variable
NOTE: The semi-colon may be omitted if the character immediately following the variable name is not upper case A-Z or 0-9.
Example

Assuming that the substitution variable NAME has the value of JOHN then:

A text entry of “User is &NAME.” or “User is &NAME;.” results in “User is JOHN.”

Using Substitution Variables in Character Strings

Care must be taken when using substitution variables in character strings as the naming convention permits the use of underscores(_) and periods(.). If a substitution variable ends in a character other than a letter or number then the extra characters are ‘stripped-back’ until the last character is an alphanumeric. Therefore entering a substitution variable that ends in any character other than an alphanumeric into a character string can return unexpected results. In order to prevent this, it is recommended that you use a semi-colon (;) to manually mark the end of the substitution variable within the string.

Examples

Specifying an output *STMF path of:

/Halcyon/HALPROD/&FILE_&USRDTA_ABCTEST.PDF

results in:

/Halcyon/HALPROD/PRTCMNRSC_&USRDTA_ABCTEST.PDF

This is because the underscore after &USRDTA is treated as a continuation of the variable, therefore resulting in the variable being named &USRDTA_ABC (10 characters from ‘&’). Because this variable does not exist, it is then treated as a literal resulting in the string being incorrectly formed. To counteract this, specify:

/Halcyon/HALPROD/&FILE;_&USRDTA;_ABCTEST.PDF

Parameters on the Work with Substitution Variables display

The following parameters are available on the Work with Substitution Variables display.

Name

Displays the name of the substitution variable.

NOTE: The convention ‘&V1’ to ‘&V99’ relates to specific data within the message (for example £1 to £99). When you work with, or list substitution variables, only ‘&V’ is displayed, which returns all message data.
Class

Displays the class of the substitution variable. There are two different classes:

SYS System variable. System variables are pre-defined and cannot be created, changed or deleted by the user
USR User variable. User variables are created and maintained by the user
Type

Displays the type of value returned by the substitution variable. There are five different types:

*CHAR Character variable. Returns a character string with a maximum length of 1024. Character variables can be a blank value
*DEC Numeric variable. Returns a packed decimal value with a maximum of 15 digits of which up to 5 may be decimal digits
*DATE Date variable. Returns a packed decimal value with 8 digits containing a date in yyyymmdd format
*PROT Protected character variable. Defines a protected character string with a maximum length of 128. This type is used for storing passwords. Once created, the value can be changed but the current value cannot be displayed. The value is encrypted when stored. Only the commands listed within the ‘Password’ parameter support this function.

*PROT Substitution Variables can only be resolved by the specific Halcyon commands that allow their use. Use of a *PROT Substitution Variable in any other area of Halcyon causes an unresolvable error.

If using with the INSTALL command you are required you to set the Password parameter to *VAR which then opens an additional parameter for the *PROT variable name and the Environment that contains the variable.
*TIME Time variable. Returns a packed decimal value with 6 digits containing a time in hhmmss format
Attribute (Attr)

Displays the length of the return value in characters or digits. For *DEC, *DATE and *TIME variables, the number after the comma is the number of decimal places.

Description

Displays the description of the substitution variable.