# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# 3.7 Step Labels

You can assign a label to each step you define to help use the ACMS Task Debugger to debug task definitions. A label is a 1- to 31-character identifier. Separate the label from the beginning of the step definition with a colon (:). ACMS generates a label that begins with a dollar sign ($) if you do not assign a label to a step. To refer to a step label with the GOTO STEP clause, you must assign your own label; you cannot use labels generated by ACMS with the GOTO STEP clause. You cannot assign a label to a root block or root processing step. A root processing step is the processing step in a single-step task.

When you build the task group associated with the task, ACMS assigns step labels to those steps you did not label. ACMS generates step labels of the form $STEP_nnn, where nnn is a decimal number that starts at 1 for the first step and increases by 1 for each new step encountered in the task definition, whether or not you assigned a label for that step. For example, the following could be the labels for the steps in a task after the task group definition is built:

    $STEP_1
    USER_LABEL_1
    $STEP_3
    $STEP_4
    USER_LABEL_2
    $STEP_6

In this example, the steps USER_LABEL_1 and USER_LABEL_2 would be $STEP_2 and $STEP_5, if the labels were generated by ACMS. You can display step labels by using the DUMP GROUP command.

# 3.8 Action Clauses

Use action clauses to define the actions you want ACMS to take at the end of an exchange step, a processing step, or a block step. These clauses do not make up a separate step in a task definition; they are a part of the step you are defining.

The five types of action clauses, which each perform a different kind of function, are:

- Conditional action
- Workspace manipulation
- Transaction action
- Server context action
- Sequencing action

Table 3-7 lists the action clauses, separated by function, and gives a brief description of each. You cannot use the clauses followed by an asterisk (*) when defining the action part of a root block or root processing step.

Table 3-7 Action Clauses
Clause | Description
--- | ---
Conditional Action
CONTROL FIELD | Names a text field that ACMS tests before doing work for the step.
IF THEN ELSE | Specifies a Boolean expression that ACMS tests before doing work for the step.
SELECT FIRST | Specifies one or more Boolean expressions that ACMS tests before doing work for the step.
Workspace Manipulation
GET ERROR MESSAGE (*) | Translates a message number into a message string.
MOVE | Specifies that a number, the numeric value of a global symbol, a workspace field, or a quoted string, is to be moved into another workspace field or fields.
Transaction Action
COMMIT TRANSACTION | Ends the transaction, making database changes permanent.
ROLLBACK TRANSACTION | Returns all work to its state at the beginning of the transaction and ends the transaction.
Server Context Action
NO SERVER CONTEXT ACTION | Specifies that no server context is taken at the end of a step.
RELEASE SERVER CONTEXT | Discards the server context of the current step.
RETAIN SERVER CONTEXT | Keeps the process context of the current step for the next step.
Sequencing Action
CANCEL TASK | Stops the task without returning control to the action part of the definition.
EXIT BLOCK (*) | Transfers control to the action part of a block step or to the next block in the task.
EXIT TASK | Causes the current task to end normally.
GOTO STEP (*) | Transfers control to another exchange, processing, or block step.
RAISE EXCEPTION | Raises a step exception and passes control to the exception handler action part of the step.
REPEAT STEP | Reexecutes the current exchange, processing, or block step.

You can use the action clauses in any order. However, when the work for a step is finished, ACMS always processes the actions in the following order:

1. Transaction actions
2. Workspace manipulation
3. Server process context actions
4. Task sequencing actions

Refer to Table 3-17 for the default server context actions.

The action you define for a step must be either unconditional (one or more of the action clauses except CONTROL FIELD, IF THEN ELSE, and SELECT FIRST) or conditional (one or more action clauses used with the CONTROL FIELD, IF THEN ELSE, or SELECT FIRST clause).

The action part of a step, if conditional, can include one or both of the workspace manipulation clauses and one of each of the other four types of action clauses.

Figure 3-10 shows the syntax you use to define actions for a step.

The ACTION keyword is optional; ACMS performs the actions described by the action clauses if you omit it, but you might want to include it to make the task definition easier to read.

Figure 3-10 Action Syntax

# 3.9 Exception Handler Action Clauses

In addition to using action clauses in the action part of a step, you can use action clauses in the exception handler action part of an exchange, processing, or block step. The exception handler action part of a step lets you recover from errors, known as exceptions, that prevent the task from completing normally. Specifically, you can use the exception handler feature to recover from a distributed transaction that aborts unexpectedly or fails to commit.

Like the action part of a step, the exception handler action part is optional. Exception handler action clauses must follow action clauses, if present, or the work part of the step, if there are no action clauses. You must introduce any exception handler actions with the EXCEPTION HANDLER keywords.

At a minimum, you must include a sequencing action clause in the exception handler action part of a step. Transaction action clauses are not allowed. You can use conditional clauses in the same way you use them in the action part of a step.

Regardless of the order in which the exception handler action clauses appear in the task definition, ACMS executes the clauses in the following order:

1. Workspace manipulation
2. Server process context action
3. Task sequencing actions

For more details on using exception handling, see EXCEPTION HANDLER Clause (Block, Exchange, Processing) in Section 3.12, and Compaq ACMS for OpenVMS Writing Applications.

# 3.10 Boolean Expressions

This section describes the Boolean expressions you use to define conditional tests for the IF THEN ELSE, SELECT FIRST, and WHILE DO clauses.

Boolean expressions can be simple or complex. The simplest Boolean expression consists of a single relational expression such as this one:

(FIELD = "1")

## 3.10.1 Relational Expressions

A relational expression consists of two values separated by a relational operator that is used to test the value of a field. The format for a relational expression is:

`(value <relational-operator> value)`

The relational expression (FIELD = "1") uses the equal sign (=) as the relational operator that separates FIELD from the literal "1". Be sure to create relational expressions that ACMS can evaluate as either true or false.

The values you use in a relational expression can be workspace fields, workspaces, global symbols, quoted strings, or signed (decimal) literals.

See Section 3.10.7 for valid data type comparisons.

## 3.10.2 Types of Boolean Expressions

More complex Boolean expressions have more than one relational expression connected by the Boolean operators NOT, AND, and OR. The following are examples:

- NOT (FIELD = "2")
- (GO = "1") OR (STOP = "2")
- (GO = "1") AND (STOP = "2")
- NOT (FIELD = "5") AND (GO = "1") AND (STOP = "2")

When used to create Boolean expressions, relational expressions are referred to as Boolean operands. For example, a single relational expression can be called a Boolean operand, a Boolean expression, or a relational expression, depending on its context, that is, on how you use it.

## 3.10.3 Relational Operators

Relational operators that you use to create relational expressions can be any of the symbols listed in Table 3-8. Each relational operator can test the contents of workspace field names, workspace names, quoted strings, or signed literals.

See Section 3.10.7 for valid data type comparisons.

When comparing values of data-type text strings, you can test values that are either sensitive or not sensitive to case. Use operators that are not case-sensitive when it does not matter if an uppercase "Y" (for example) equals the letter "y" in lowercase. Use case-sensitive operators when you want to distinguish between uppercase and lowercase letters. You can use either the case-sensitive or case-insensitive operators when you are comparing values whose data type is not a text string.

Table 3-8 Relational Operators
Operator Meaning | Relational Operator Symbols
--- | ---
| Case-Insensitive | Case-Sensitive
Equal to | EQ = | EQ_EXACT ==
Not equal to | NE <> | NE_EXACT <<>>
Greater than | GT > | GT_EXACT >>
Greater than or equal to | GE >= => | GE_EXACT >>== ==>>
Less than | LT < | LT_EXACT <<
Less than or equal to | LE <= =< | LE_EXACT <<== ==<<

## 3.10.4 Boolean Operators and Associativity

The NOT Boolean operator tests the negation of a relational expression. It processes the clause associated with the expression if the negation of the relational expression is true. Expressions of the type NOT (boolean-operand) are right-associative, meaning that ACMS evaluates the relational expression to the right of the NOT operator. With an expression of the type NOT (NOT (boolean-operand)), ACMS first processes the Boolean operand in parentheses before evaluating the entire Boolean expression.

The AND Boolean operator ties Boolean expressions together. It processes the clause associated with the expression only if all Boolean operands in the expression are true. Expressions of the type (boolean-operand AND boolean-operand) are left-associative. In the following example, three Boolean operands are connected by two AND Boolean operators:

(boolean1) AND (boolean2) AND (boolean3)

Because the AND expression is left-associative, ACMS evaluates the example as follows:

((boolean1) AND (boolean2)) AND (boolean3)

ACMS evaluates each Boolean operand first, evaluates the combination of boolean1 and boolean2 next, and then evaluates the result with boolean3.

The OR Boolean operator processes the clause associated with the expression when either value in the Boolean expression is true. Expressions of the type (boolean-operand OR boolean-operand) are left-associative and follow the same order of evaluation as Boolean expressions connected with the AND Boolean operator.

## 3.10.5 Precedence

You can use the AND and OR Boolean operators to combine many Boolean operands or expressions into one large Boolean expression. To decide whether such an expression is true or false, ACMS evaluates the Boolean expression in order. The order depends on the use of parentheses and operator precedence. Table 3-9 shows Boolean expression precedence in descending order.

Table 3-9 Boolean Precedence
Operator | Operator Example
--- | ---
Expressions in parentheses | (A = 1)
All relational operators | (FIELD = "1")
Boolean operator NOT | NOT (FIELD = "1")
Boolean operator AND | (FIELD = "1") AND (FIELD = "2")
Boolean operator OR | (FIELD = "1") OR (FIELD = "2")

ACMS evaluates all expressions enclosed in parentheses first. Each operator has a position in the hierarchy of operators. The operator's position in this hierarchy indicates when ACMS has to perform the operation called for by the operator.

Parentheses can change the order of precedence of ACMS operators. It is important to know how ACMS processes Boolean expressions so you can use parentheses to make sure your Boolean expressions are evaluated the way you intend. For example, the following Boolean expression contains no parentheses except to enclose each operand. It has three Boolean operands, two Boolean operators, and three relational operators:

(OPERAND1 = "1") AND (OPERAND2 = "1") OR (OPERAND3 = "2")

In processing this expression, ACMS evaluates all operands with relational operators to find their truth value. Suppose the first operand evaluates to false and the second and third operands evaluate to true. ACMS then evaluates:

1. The first and second operands connected by the AND operator to find their truth value. The AND operator requires that each operand in the expression must be true to be evaluated as true, so ACMS evaluates this expression as false (false AND true = false).
2. The first result (false) with the third operand. The OR operator evaluates an expression as true if either of the operands in the expression is true. So, because the first and second operand evaluate to false and the third operand is true, ACMS evaluates the entire expression as true.

To illustrate how parentheses can change the truth value of a Boolean expression, suppose you use parentheses in the previous example:

(OPERAND1 = "1") AND ((OPERAND2 = "1") OR (OPERAND3= "2"))

Suppose the first operand is false, the second is true, and the third is true. After evaluating each individual operand, ACMS evaluates:

1. The second and third operands, connected with the OR operator and enclosed in parentheses, as true (true OR true = true)
2. The first operand (false) with the result of the evaluation of the second and third operands (true) and finds the expression to be false (false AND true = false)

Without parentheses, ACMS follows the rules of precedence and evaluates the expression as true. With parentheses, it evaluates the expression as false. Using parentheses to indicate how you want Boolean expressions evaluated ensures that your expressions are processed as you intend.

## 3.10.6 Parentheses

When using parentheses, use the following rules to construct Boolean expressions:

- Enclose each Boolean expression in parentheses. For example:

            SELECT FIRST TRUE OF
      (FIELD1 EQ "1") : GOTO STEP_4;
            END SELECT;

- Enclose the operand you include with the NOT operator in parentheses. For example:

            SELECT FIRST TRUE OF
      (FIELD1 = "1")           : GOTO STEP_4;
      (NOT (FIELD = "1"))      : GOTO STEP_5;
      (NOT (NOT (FIELD = 2"))) : GOTO STEP_6;
            END SELECT;

- Parentheses can change the ACMS order of precedence as described in Section 3.10.5.
- Never enclose the NOMATCH keyword in parentheses.

## 3.10.7 Comparisons

ACMS makes comparisons when working with Boolean expressions in the following ways:

- Compares only the following data types: signed longwords, text strings, and CDD structure fields of type UNSPECIFIED.
- Compares expressions of the same data type only. For example, you can compare signed longwords only with signed longwords, text strings only with text strings, and so forth. You cannot compare expressions of different data types, such as signed longwords with text strings.
- Allows comparisons involving global symbols, which ACMS resolves to a signed longword value using the files specified on the /OBJECT, /USERLIBRARY, /SYSLIB, and /SYSSHR qualifiers of the BUILD GROUP command. ACMS does not resolve user-defined symbols using files specified by the task group MESSAGE FILES clause.
- Compares text strings of unequal length by padding the shorter field with spaces.
- Makes all comparisons between text strings using the OpenVMS run-time library STR$COMPARE_MULTI routine. This routine can use one of several different ordering tables. The default is the DIGITAL Multinational Character Set. In this ordering, both uppercase and lowercase versions of a letter are grouped together. For example, variants of A (A,a) precede variants of b (B, b), and so forth. In the set of variants, lowercase precedes uppercase. Thus, the order of alphanumeric characters is 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, A, b, B, and so on. See OpenVMS RTL String Manipulation (STR$) Manual for further information on STR$COMPARE_MULTI. See OpenVMS User's Manual for further information on the DIGITAL Multinational Character Set and the multinational collating sequence.
- Allows comparisons between composite fields and quoted strings only if the composite field has the TEXT data type.
- Enables you to use CDD structure fields of the UNSPECIFIED type to compare the contents of two workspaces. ACMS makes comparisons between items of type UNSPECIFIED as unsigned byte comparisons, byte by byte, from left to right. Unequal-length fields are compared by extending the shorter field with null characters.

If the operand in a Boolean expression is a workspace name (rather than a workspace field name), ACMS tests the top-level item (structure or elementary item) of the record definition associated with the workspace.

Boolean expressions that you use with the Boolean operators AND, OR, and NOT must be expressions that can be evaluated as either true or false. For example, the expression (FIELD1 AND 1) is not valid.

Boolean expressions that you use with the Boolean operators AND or OR are processed by ACMS from left to right, and Boolean expressions with the NOT operator are processed from right to left. However, this associativity does not have any effect on the truth value of the expression.

# 3.11 I/O Restrictions for Distributed Processing

Because a task that does I/O in a processing step uses a terminal for input and output and terminals cannot be passed from one process to another over a network, tasks that do I/O in a processing step cannot be called remotely. ACMS cancels tasks that attempt to pass the terminal from the process running the task on the application system to the calling process on the submitter node.

If you plan to make your tasks available to users on a remote node, you need to take into consideration the I/O methods that can be called remotely:

- If a task does only STREAM I/O, the task can be called remotely or locally.
- If a task does only FORM I/O from exchange steps, the task can be called remotely or locally.
- If a task does only REQUEST I/O from exchange steps, the task can be called remotely or locally.
- If TERMINAL I/O or REQUEST I/O is specified in the processing step of a task, the task cannot be called remotely because using an I/O option in a processing step requires a terminal.

Table 3-10 shows the legal combinations of I/O attributes on block and processing steps and whether or not the resulting task is available to a user on a remote node.

Table 3-10 I/O Attributes for Distributed Processing
Block | Processing | When Permitted
--- | --- | ---
No BLOCK step | NO I/O | Local/Remote
| TERMINAL I/O | Local only
| REQUEST I/O | Local only
BLOCK WITH NO I/O | NO I/O | Local/Remote
| TERMINAL I/O | Local only
| REQUEST I/O | Local only
BLOCK WITH FORM I/O | NO I/O | Local/Remote
| TERMINAL I/O | Local only
BLOCK WITH REQUEST I/O | NO I/O | Local/Remote
| TERMINAL I/O | Local only
| REQUEST I/O | Local only
BLOCK WITH STREAM I/O | NO I/O | Local/Remote

Previous | Next | Contents | Index