Referring to Variables

Referring to Variables and Members of Variable Groups

Normally, you must enclose each reference to a variable or member of a variable group in backslashes (\).You can omit the backslashes when referring to a variable within an expression. However, if you are referring to a variable within a string that is within an expression, or if you are referring to partial text, you must enclose the reference in backslashes.

You cannot refer to a variable or a variable group in a MESSAGE or TOKEN command.

Format

\variable-ref\

where variable-ref is the name of either a user-defined variable or a predefined variable.

Example

The following example refer to the current date and time:

\_DT\

The following examples refers to the values of the variables Count and filename in expressions:

SET Command = "ls -l  \filename\"
SET Current = filename
SET Count = Count+1

Referring to Variables Within Strings

To refer to a variable within a string, you must enclose the variable name within backslashes (\variable-name\).

Examples

The following example refers to the value of the variable DISKNAME in a string:

"The name of the disk is \DISKNAME\"

The following example refers to the value of a variable group member within a string. Assume that the name of each member of the variable group, ErrorText, is actually a numeric error code (for example, 1 or 2). The value of each member is a text description of the error code. For example, member 1 has the value "EPERM Not owner", and member 2 has the value "ENOENT No such file or directory." This example inserts the text description for error code 1 into a string.

"ERRNO error code 1 (\ErrorText:"1"\) occurred"

After substitution, the resulting string is

"ERRNO error code 1 (EPERM Not owner) occurred"

Now assume that the error code is stored in the variable ErrorCode. The following example generically refers to the error code and error text:

"ERRNO error code \ErrorCode\ (\ErrorText:ErrorCode\) occurred"

If ErrorCode has a value of 1, the results of the two example strings are identical. ErrorCode can be an integer or string variable; the results are the same in either case.

Referring to Members of Variable Groups

Format

variable-group:member-name

where:

variable-group

is the name of a user-defined variable group.

member-name

is the name of the member to which you want to refer. A member name can be a fixed-string constant or the name of a variable.

Requirements

To refer to a member, you need to specify both the member name and the name of its variable group. You can refer to the name of a variable group member using a variable or using a fixed-string constant. Variable group member names have a maximum length of 128 characters; longer names are truncated.

References to Variables

A variable reference is the name of a user-defined or a predefined variable.

References to Fixed-String Constants

A fixed-string constant is a set of characters in quotation marks (“ ”). A fixed-string constant cannot include substitution. For example, “file” is a valid fixed-string constant that you can use to refer to a member name, but “file \file-name\” is not.

Examples

The following example uses a fixed-string constant to set the member “DN” in the variable group ApplStatus to the value “down”:

SET ApplStatus:"DN" = "down"

An equivalent reference uses a user-defined string variable, StatusName, as shown in this example.

SET StatusName = "DN"
SET ApplStatus:StatusName = "down"

Note: In the following example, value within the variable StatusName will not be substituted. Instead, "\StatusName\" itself will be considered as a fixed-string constant:

SET ApplStatus:"\StatusName\" = "down"

The following example refers to the same member “DN” from the variable group ApplStatus within a string. Note that when referring to a variable group member within a string, you must enclose both the group name and the member name within backslashes (\).

"Application \_TOKEN1\ is \ApplStatus:"DN"\"

The preceding example is more meaningful if the member name is extracted from message text rather than specified as a fixed-string constant. For the following example, assume that the message text is “myappl DN”. In this case, you can use the second token from this message to refer to the variable group member. This reference causes the device status of "DN" to become the more meaningful word, down.

"Application \_TOKEN1\ is \ApplStatus:_TOKEN2\"

After text substitution occurs, the resulting string is

"Application myappl is down"

The following example refers to the value of a member of a variable group. The member name is contained in the third message token, _token3; therefore, the reference results in the value of the member named by the value of the third message token in the variable group ApplName.

\ApplName:_token3\

Referring to All Members of a Variable Group

In some cases, you may want to refer to all members of a variable group. Do this using the predefined variable _ALL.

You can use _ALL as the target of the following commands:

Command	Summary
DESTROY	Destroys all members of the specified variable group
SET	Sets all members of the specified variable group to the specified value
RESET	Resets all members of the specified variable group to the default value of that variable group

You can also use _ALL within an expression or string. The result of this reference is a string that includes all member names, each separated from the preceding by two spaces.

Examples

The following example resets all members in variable group ApplErrors to their common default value:

RESET ApplErrors:_ALL

The following example generates a string that contains all member names in the variable group DiskErrors:

ACTION COMMAND "echo DISKERRORS contains: \DiskErrors:_ALL\"

If DiskErrors has three members named DISK01, DISK02, and DISK03, the resulting string is

"echo DISKERRORS contains: DISK01  DISK02  DISK03"

Variable References as the Targets of Actions

You can refer to a user-defined variable as the target of SET, RESET, CREATE, and DESTROY actions.

Rules for Referring to a Variable as a Target

The following rules apply when referring to the target variable of one of the actions listed above:

The variable reference cannot include a partial text reference.
You cannot enclose the variable reference within backslashes (\).
You cannot refer to a predefined variable as the target of a command. However, you can use a predefined variable name to refer to a member of a variable group.

Examples

Assume that _TOKEN1 has the value of PRD10C. The value of PRD10C is used as the name of a member of the variable group DiskErrors. In this example, the member PRD10C is reset to its default value.

RESET DiskErrors:_TOKEN1

The following example refers to the variable FILENAME, which is set to the value of the third token of the message:

SET FILENAME = "\_TOKEN3\"

In this example, FILENAME is the target of the SET command and is therefore not enclosed in backslashes, whereas _TOKEN3 is referred to as part of the string and therefore must be enclosed in backslashes.

Partial Text References

A partial text reference extracts only a portion of a variable value. You can extract subtokens, characters at specified positions, or a combination of both for use in action text, variable strings, and expressions.

Format

Note: The starting and ending character positions must be enclosed in brackets ([ ]). These brackets are shown in bold to distinguish them from brackets that show optional syntax.

\identifier "list" subtoken\

\identifier {set} subtoken\

\identifier "list" subtoken [start,end]\

\identifier {set} subtoken [start,end]\

\identifier [start,end]\

where:

identifier

is the name of a predefined or user-defined variable, a member reference, a token number (nn), or a negative token number (-nn).

list

is a delimiter list, within quotation marks (" "). The delimiters separate the identifier value into subtokens.

set

is a delimiter set, within braces ({ }). The delimiters separate the identifier value into subtokens.

subtoken

is an integer that indicates the portion of text you want to reference. Subtokens are numbered left to right unless the number is preceded by a minus sign (-); then the subtokens are numbered right to left.

start

is an integer that indicates the starting character position within the identifier value. Character positions are numbered from left to right, starting at 1. The starting character position cannot be greater than the total number of characters of the identifier value.

end

is an integer that indicates the ending character position within the identifier value. The ending character position must be greater than or equal to the beginning character position. Character positions are numbered from left to right, starting at 1. If the ending character position is greater than the total number of characters in the identifier value, the last character position of the value is used.

Subtoken Extraction

Subtoken extraction separates the substitution text into smaller portions of text, called subtokens.

Examples

Assume the following device error message is matched using standard delimiters (spaces):

Tokens:  could not open: /usr/acct/spo/file1
         --1--*-2-*--3--*---------4---------

The following specification extracts the rightmost subtoken, the file name (file1) from the fourth token, /usr/acct/spo/file1:

\_TOKEN4 {/} -1\

The value of the identifier _TOKEN4 is the fourth token: /usr/acct/spo/file1. When the delimiter / is used, the following subtokens result:

Subtokens:  /usr/acct/spo/file1
            *-1-*-2--*-3-*--4--

When the delimiter / is used, the subtoken specification (-1) extracts file1 from the token text. In this example the file name is the fourth subtoken, but in general, the subtoken position of the file name depends on the directory structure.

Note: Positive token numbering can also be used with subtoken extraction.

The following example extracts part of the text value of a member of a variable group. The substring [1,4] is applied to the value of the variable group member referred to by DiskName:_token3.

\DiskName:_token3 [1,4]\

The following example extracts the first five characters from the third token of the predefined variable MESSAGE:

\_MESSAGE { } 3 [1,5]\

The following examples show how to use subtoken substitution to convert real numbers into integers by stripping off the decimal point.

Assume that the second token of a message is a real number of the form xxx.yyy, where xxx is the integer portion of the number and yyy is the fractional portion. The integer portion can be extracted by using the following subtoken specification:

\_TOKEN2 "." 1\

The result of this operation is xxx in string format. The result could be used as an integer by specifying the # operator, as in

#\_TOKEN2 "." 1\

To extract the fractional portion of the number, use the following subtoken specification:

\_TOKEN2 "." 2\

In this case, the result is yyy in string format. Note that this example assumes that there are always digits before the decimal point. If the string consists of only a fractional portion such as .yyy, this example fails. Failure occurs because only one subtoken exists after the decimal point (.) delimiter is applied. Therefore, a reference to subtoken 2 results in error. A more complete method to extract the fractional portion is

\_TOKEN2 "." -1\

In this case, the rightmost subtoken is obtained whether one or two subtokens exist after the delimiter is applied.

In some cases, it can be beneficial to extract a decimal point from a real number and combine both the integer and fractional portions of the number, as in the following example:

\_TOKEN2 "." 1\\_TOKEN2 "." 2\

This example results in the string xxxyyy with no decimal point. It assumes that the number has a leading integer portion. This example fails if the number is of the form .yyy. Using -1 as a subtoken reference to extract the fractional portion works, but the resulting string of yyyyyy is undesirable. A more general solution requires the use of conditional logic.

The following example uses conditional logic to strip a decimal point from a real number, whether or not it has digits before the decimal point. The result is assigned to the user-defined string variable named Stripped.

IF \_TOKEN2[1,1]\ = "."            /* If the first char is a decimal point, */
    Stripped = \_TOKEN2 "." -1\    /* there is no leading integer value  */          
ELSE
    Stripped = "\TOKEN2 "." 1\\_TOKEN2 "." 2\"         
ENDIF

Use caution when converting fractional portions of real numbers to integers. To ensure accuracy, all fractional portions must be specified to the same decimal place. For example, if .1 and .001 are stripped and converted to integers using these commands, the result is 1 in both cases. If .1 is specified to 3 decimal places as .100, the result is 100.

Character Position Extraction

Character position extraction removes characters at specified positions from a text string. You must enclose the integers representing the start and end character positions in brackets ([ ]) and separate these integers with a comma.

Examples

The following example extracts the third and fourth characters from the date string “MMDDYY HHMMSS”:

\DT[3,4]\

As a result, only the DD portion of the date is extracted.

If only one character is desired, specify the start and end characters as the same:

\DT[6,6]\

As a result, only the last digit of the year is extracted.

The starting character position must be less than or equal to the total number of characters, but the ending position can be greater than the total number of characters.

For example, if you use [20,40] to extract part of a message that is 30 characters long, characters 20 through 30 are extracted. However if you specify [41,50], an error results because the starting character position is greater than the total number of characters. The predefined variable _STATUS is set to -1 in this case.

Combining Character Position and Subtoken Extraction

A partial text reference can combine subtoken and character position extraction.

Examples

Assume the following device error message is matched using the standard delimiters (spaces):

Tokens:  could not open: /usr/acct/spo/file1
         --1--*-2-*-3---*---------4---------

The following subtoken extraction combined with character position extraction, extracts only the first three characters of the file name:

\4 {/} 4[1,3]\

The following example extracts the fourth and fifth characters of the second token of the member of the variable group ErrorText named by the third token in the matched message. The backslashes are required because a partial text reference is specified.

\ErrorText:_token3 { } 2[4,5]\

Assume this reference is part of a pattern that matches the following message:

"Operator: Enter E002 most recent bag number. "

The value of _token3 is E002. Within the variable group ErrorText, there is a member called E002. If the value of E002 is “undefined bag65”, then 6 and 5 are the fourth and fifth characters of the second subtoken (bag65).

The following example extracts the fourth and fifth characters of the third subtoken of the variable ErrorText as a string:

"The error code is \ErrorText { } 3[4,5]\ "