# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# REPEAT STEP Clause (Action)

> Repeats the current exchange, processing, or block step.

## Format

> REPEAT STEP ;

## Clause Default

> The REPEAT STEP clause is optional. The default sequencing action for a step within a root block is GOTO NEXT STEP. The default sequencing action for a root block or a processing step in a single-step task is EXIT TASK.

## Note

> If you specify the REPEAT STEP clause in the action part of a root block, that task cannot be called by a parent task to participate in a distributed transaction.

## Example

    EXCHANGE
      SEND FORM RECORD DISPLAY_DEPARTMENT_RECORD

        SENDING DISPLAY_DEPARTMENT_WKSP
        WITH RECEIVE CONTROL TEST_WORKSPACE;
      CONTROL FIELD IS TEST_WORKSPACE.TEST_KEY
        " FMOR"   :  REPEAT STEP;
        " FCAN"   :  CANCEL TASK;
      END CONTROL FIELD;

> In this example, DECforms uses the DISPLAY_DEPARTMENT_RECORD form record to display a panel to the user. If the user presses a function key to see more information, ACMS repeats the exchange step.

# REQUEST Clause (Exchange)

> Names a TDMS request that does input and output for an exchange step. The REQUEST clause also names any workspaces the request uses.

## Format

> REQUEST IS request-name [ IN request-library] [ USING {workspace-name} [,...] ] ;

## Parameters

> ### request-name

> The name by which the TDMS request is known in the request library referenced by the REQUEST LIBRARY clause in the task definition. If you are using the Request Interface, it is the name of the user request procedure in the shared image file. The request name is the run-time name of the request or user request procedure, not a CDD path name.

> ### request-library

> The name, as defined in the task group definition, of the request library containing the request named in the REQUEST clause. The request library you name overrides the request library named in the DEFAULT REQUEST LIBRARY clause for the task. You can name different request libraries in different exchange steps or in exchange clauses listed for different values of a CONTROL FIELD clause.

> ### workspace-name

> The name of the workspace you want to pass to the request. Use the unique name of each workspace. If you list more than one workspace name, you must separate the names with commas. All workspace names must be defined by the WORKSPACES clause in the task group definition or task definition.

> The order of the workspaces you name with the USING keyword must correspond to the order in which the equivalent buffers are listed in the RECORD IS clauses of the request definition. The record names used in the request definition and the workspaces named in the task definition need not be the same; the CDD descriptions for the records should, however, be the same.

> You must include the USING keyword and all the records named in the request definition even if the request is not using all of the records in a given exchange step.

## Clause Default

> The REQUEST clause is optional. If you do not name a request in an exchange step, ACMS does not process a request for that step.

## Note

> If you do not name a request library in the REQUEST clause, and you do not name a default request library in the task definition, ACMS uses the first request library named in the task group definition.

##

### Examples

#1
    EXCHANGE
      REQUEST IS ADD_EMPLOYEE_REQUEST USING PERS_RECORD;

> This exchange step uses the request ADD_EMPLOYEE_REQUEST. The request uses the workspace with the given name PERS_RECORD.

#2
    WORKSPACES ARE ADD_WORKSPACE,PERS_RECORD;
    BLOCK
      EXCHANGE

        REQUEST IS ADD_EMPLOYEE_REQUEST
          USING ACMS$PROCESSING_STATUS,
                ADD_WORKSPACE, PERS_RECORD;
          CONTROL FIELD PROGRAM_REQUEST_KEY
           "CANCEL"    : CANCEL TASK;
          END CONTROL FIELD;

> In this step, ADD_EMPLOYEE_REQUEST displays a form. If the user presses a program request key to cancel the task, ADD_EMPLOYEE_REQUEST returns the value "CANCEL" to the PROGRAM_REQUEST_KEY field in ADD_WORKSPACE.

# REQUEST I/O Phrase (Block, Processing)

> Specifies that you use TDMS to communicate with the terminal user. You can specify the REQUEST I/O phrase at the block or processing step level.

## Format

> REQUEST I/O

## Phrase Default

> The default input/output method for exchange steps in a block step is REQUEST I/O.

> If you are defining a single-step task that uses a processing step, the default communication method for that step is TERMINAL I/O. If you are defining a task that includes a block step, the default communication method for processing steps in that task is NO TERMINAL I/O, even if the block includes only one processing step.

## Notes

> If you use the REQUEST I/O phrase in a block or processing step, you cannot use the FORM I/O, NO TERMINAL I/O, or STREAM I/O phrase in the same step.

> You cannot chain from a task using TERMINAL or REQUEST I/O to a task using STREAM I/O, or from a task using STREAM I/O to a task using TERMINAL or REQUEST I/O. If you do, the task is canceled and one of the following messages is displayed:

> - "Cancel resulted from tt not passed to processing step as expected"--- if a stream task chains to a task with a processing step that does TERMINAL I/O.
> - "Cancel results from a TDMS error"--- if a stream task chains to a task using REQUEST I/O.
> - "Cancel results from an ACMS internal logic error in Task Processing"--- if a task using REQUEST I/O chains to a task using STREAM I/O.

> You cannot distribute a task that does any I/O in a processing step. For further information on I/O restrictions on tasks to be accessed remotely, see Section 3.11.

> You cannot specify the REQUEST I/O phrase on a nested block.

> You can use the REQUEST I/O phrase only in processing steps that use a procedure server.

## Block Step Example

#1
    BLOCK WITH REQUEST I/O

> The exchange steps in this block step use TDMS requests to communicate with the terminal user.

## Processing Step Example

#1
    PROCESSING
      WITH REQUEST I/O
      CALL ADD_EMPLOYEE IN PERSONNEL;

> This processing step uses TDMS to communicate with the terminal user.

# RETAIN SERVER CONTEXT Clause (Action)

> Retains server context within the current server.

## Format

> RETAIN SERVER CONTEXT [ IF ACTIVE SERVER CONTEXT ] ;

## Keywords

> ### IF ACTIVE SERVER CONTEXT

> Retains server context only if there is active process context. If you use the RETAIN SERVER CONTEXT clause without the IF ACTIVE SERVER CONTEXT keywords, and there is no active server context, ACMS cancels the task.

## Clause Default

> The RETAIN SERVER CONTEXT clause is optional. Table 3-17 shows the default context actions for a task.

## Notes

> When you retain server context between processing steps that are not within a distributed transaction, those processing steps must use the same server. The server can be either a reusable procedure server or a reusable DCL server. The server cannot be nonreusable. You can use the RETAIN SERVER CONTEXT clause only in the action specifications of steps within a block.

> See Compaq ACMS for OpenVMS Concepts and Design Guidelines for a discussion of the performance advantages of retaining server context.

## Example

    BLOCK
     WORK WITH FORM I/O
      GET_DEPT_NUMBER:
        EXCHANGE
          RECEIVE FORM RECORD REVIEW_SCHEDULE
            RECEIVING REVIEW_SCHEDULE_WKSP
            WITH RECEIVE CONTROL QUIT_WORKSPACE;
          CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
            " FCAN"   : CANCEL TASK;
          END CONTROL FIELD;
      GET_FIVE_EMPLOYEES:
        PROCESSING
          CALL REVIEW_SCHEDULE_GET IN DEPARTMENT_SERVER
            USING REVIEW_SCHEDULE_WKSP;
          CONTROL FIELD ACMS$T_STATUS_TYPE
            "B"        : GET ERROR MESSAGE;
                         RELEASE SERVER CONTEXT;
                         GOTO PREVIOUS EXCHANGE;
            "G"        : RETAIN CONTEXT;
                         GOTO NEXT STEP;
          END CONTROL FIELD;

> If the REVIEW_SCHEDULE_GET procedure is unsuccessful in reading review schedule information for a department, ACMS returns the value "B" to the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS workspace. In this task, if the procedure is successful, the user can choose to see the next five records in the file. Therefore, you must normally retain file pointers, a part of server context, to keep track of the user's file location. You use the RETAIN SERVER CONTEXT clause to retain these pointers.

# ROLLBACK TRANSACTION Clause (Action)

> Signals the end of a distributed transaction and returns any files and databases within the transaction to the state they were in before the transaction started.

## Format

> ROLLBACK TRANSACTION ;

## Clause Default

> The ROLLBACK TRANSACTION clause is optional. If you do not explicitly end a distributed transaction by specifying COMMIT TRANSACTION or ROLLBACK TRANSACTION, ACMS commits the transaction. However, if the action part of the step that started the transaction specifies CANCEL TASK or RAISE EXCEPTION, ACMS rolls back the transaction.

## Notes

> You can specify ROLLBACK TRANSACTION in the action part of a root block, nested block, root processing step, or a processing step that is part of a multiple-step task.

> Because a distributed transaction must end in the action part of the step that starts the transaction, you cannot specify ROLLBACK TRANSACTION in a step within a distributed transaction.

> Table 3-19 shows the default transaction actions for different situations in a task definition.

## Example

    BLOCK WORK WITH FORMS I/O
       EXCHANGE
          RECEIVE FORM RECORD ORDER_ENTRY_RECORD IN ORDER_ENTRY_FORM
            RECEIVING ORDER_ENTRY_RECORD;
       BLOCK WORK WITH DISTRIBUTED TRANSACTION
          PROCESSING
             CALL ENTER_ORDER IN DIST_CTR_DATABASE_UPDATE_SERVER
               USING ORDER_ENTRY_RECORD, RESTOCK_RECORD;
          PROCESSING
             SELECT FIRST TRUE OF
               ( ( PRIORITY_ORDER = "Y" ) AND
                 ( ORDERED_AMOUNT > IN_STOCK_AMOUNT ) ):
                    CALL PRIORITY_ORDER IN MASTER_DATABASE_SERVER
                      USING ORDER_ENTRY_RECORD, RESTOCK_RECORD,
                           STATUS_RECORD;
               ( ORDERED_AMOUNT > IN_STOCK_AMOUNT ):
                   CALL QUEUE_REPLENISH_INVENTORY_TASK IN QUEUE_SERVER
                     USING RESTOCK_RECORD;
             END SELECT;
       END BLOCK WORK;
          ACTION IS
            IF ( ORDER_SATISFIED = "Y" )
            THEN
                COMMIT TRANSACTION;
                EXIT TASK;
            ELSE
                ROLLBACK TRANSACTION;
            END IF;
    END BLOCK WORK;

> In this example, the Order Entry task starts a distributed transaction on the nested block. The processing step calls a procedure to write an order record to the distribution center's database. If the distribution center cannot immediately satisfy the order, the processing step checks to see if the order is a priority order. If it is a priority order, the processing step checks the master database to see if the manufacturing plant can satisfy the order. If it is not a priority order, the processing step inserts a queued task into a queue file. If the order is handled successfully, the action part of the nested block commits the transaction. Otherwise, it ends the transaction by rolling back any database updates performed within the transaction.

# SELECT FIRST Clause (Block, Exchange, Processing, Action)

> Takes action based on values that you test with Boolean expressions.

> You can use a SELECT FIRST clause to start a block, exchange, or processing step (thereby creating a conditional block, processing, or exchange step), or to start an action clause (thereby creating a conditional action clause).

> The SELECT FIRST clause compares workspace fields using Boolean expressions and takes actions based on the results of the expressions. The first expression to evaluate to true is the one that determines which action to take. Use the NOMATCH keyword to specify an action to take if no expression evaluates to true.

## Format

## Parameters

> ### boolean-expression

> Either a Boolean expression in parentheses or the keyword NOMATCH.

> See Section 3.10 for a description of Boolean expressions.

> The Boolean expression must be an expression that ACMS can evaluate as either true or false. If the Boolean expression is true, ACMS does the work or action defined by the associated clause. If the expression is false, ACMS evaluates the next Boolean expression until it either finds a true expression or reaches the end of the Boolean expression list. If ACMS does not find any true expressions, it performs the work or action associated with the NOMATCH keyword. If ACMS does not find any true expressions, and you did not specify the NOMATCH keyword, it performs the default work or action.

> ### clause

> One of the following, depending on the placement of your SELECT FIRST clause:

> `block`

> The start of a nested block with the keywords, BLOCK WORK, or the start of an exchange or processing step with the keywords, EXCHANGE WORK or PROCESSING WORK, respectively. When you use the SELECT FIRST clause at the block step level, you can specify multiple block, exchange, and processing steps for each Boolean expression or NOMATCH you list.

> At the block step level, you can use the SELECT FIRST clause only at the top of the block; you cannot use it between steps within the block.

> `exchange-clause`

> Any unconditional exchange clause compatible with the I/O method the block step uses. For example, if a block step uses FORM I/O, exchange steps in that block step can use one of the DECforms clauses (SEND, RECEIVE, or TRANSCEIVE) or NO EXCHANGE, but cannot use a TDMS clause (READ, WRITE, or REQUEST). There can be only one exchange clause for each Boolean expression or NOMATCH you list in the SELECT FIRST clause.

> `processing-clause`

> Any unconditional processing clause. There can be only one processing clause for each Boolean expression or NOMATCH you list in the SELECT FIRST clause.

> `action-clause`

> Any unconditional action clause. ACMS provides four types of unconditional action clauses: workspace manipulation, transaction action, server context, and task sequencing. For each Boolean expression or NOMATCH you list in the SELECT FIRST clause, you can specify one or both of the workspace manipulation clauses, and one of each of the other three types of action clauses.

> You can use action clauses at the end of a block, exchange, or processing step.

> Table 3_15 and Table 3-16 summarize the clauses that you can use within the SELECT FIRST clause at each step.

> Table 3-16 lists the action clauses you can use with the SELECT FIRST clause.

> Table 3-15 Clauses Compatible with the SELECT FIRST Clause
> At This Step | You Can Specify |  |
> --- | --- | --- | ---
> BLOCK | Multiple of: |  |
> | BLOCK WORK EXCHANGE WORK PROCESSING WORK |  |
> PROCESSING | One of: |  |
> | CALL [PROCEDURE] CALL TASK DTR COMMAND DCL COMMAND IMAGE NO PROCESSING |  |
> EXCHANGE | If task uses FORM I/O | If task uses REQUEST I/O | If task uses STREAM I/O
> | One of: | One of: | One of:
> | NO EXCHANGE RECEIVE SEND TRANSCEIVE | NO EXCHANGE READ REQUEST WRITE | NO EXCHANGE READ WRITE

> Table 3-16 Action Clauses Compatible with the SELECT FIRST Clause
> For each Boolean expression or NOMATCH you list in the SELECT FIRST clause, you can specify:
> Workspace Actions | Transaction Actions | Server Context Actions | Sequencing Actions
> --- | --- | --- | ---
> Both: | One of: | One of: | One of:
> MOVE GET ERROR MESSAGE | COMMIT TRANSACTION ROLLBACK TRANSACTION | NO SERVER CONTEXT ACTION RELEASE SERVER CONTEXT RETAIN SERVER CONTEXT | CANCEL TASK EXIT BLOCK EXIT TASK GOTO STEP RAISE EXCEPTION REPEAT STEP

## Keyword

> ### NOMATCH

> Does the processing associated with the NOMATCH keyword if no Boolean expression is true. The NOMATCH keyword must be the last value you list in the SELECT FIRST clause. Do not enclose the NOMATCH keyword in parentheses.

## Clause Default

> The SELECT FIRST clause is optional. If you do not use the SELECT FIRST clause or one of the other three conditional clauses, ACMS processes your exchange, processing, or action work unconditionally.

## Notes

> You must end each subclause in a SELECT FIRST clause with a semicolon (;), and you must end the SELECT FIRST clause with END SELECT and a semicolon (;).

> The type of clause you can use within a SELECT FIRST clause depends on the type of step that you are defining. For example, if you are using SELECT FIRST to define an exchange step, you can only use exchange clauses.

> If you use SELECT FIRST at the block step level, you can only use it at the top of the block; you cannot specify it between steps within the block.

> ACMS takes the action associated with the first Boolean expression that evaluates to true.

## Block Clause Example

#1
    BLOCK WORK
      SELECT FIRST TRUE OF
        (RENTAL_STATUS = "N") : EXCHANGE
                                  SEND RECORD RESERVE
                                    SENDING RESERVE_WKSP;
        (RENTAL_STATUS = "Y") : PROCESSING
                                  CALL BILL_CALC
                                    USING RATE_DATA_WKSP;
                                  ACTION IS
                                    REPEAT STEP;
      END SELECT;

> ACMS tests the RENTAL_STATUS workspace field. If the first Boolean expression evaluates to true, ACMS performs the corresponding exchange step. If the second Boolean expression is true, ACMS performs the processing step. Otherwise, ACMS passes control to the next clause in the definition.

## Exchange Clause Example

#1
    EXCHANGE
      SELECT FIRST TRUE OF
        ((TEST_FIELD EQ "SKIP") OR
          (OLD_WORKSPACE == NEW_WORKSPACE)) : NO EXCHANGE;
        (OLD_WORKSPACE <<>> NEW_WORKSPACE)  : SEND RECORD CONFIRM_CHANGES
                                                SENDING NEW_WORKSPACE;
      END SELECT;
      ACTION IS
        EXIT TASK;

> ACMS tests the contents of TEST_FIELD, OLD_WORKSPACE, and NEW_WORKSPACE. If either Boolean operand in the first expression is true, ACMS does not do any input or output. If neither operand is true, ACMS evaluates the second expression. If the second expression is true, ACMS performs the exchange step associated with that expression. Otherwise, it drops through to the next clause in the definition.

## Processing Clause Example

#1
    PROCESSING
      SELECT FIRST
       (AGE_ENTERED >= 21 AND EMP_STATUS = "Y"
         AND NOT (PAY GT BASE_PAY OR HOURS_WORKED GT 44))
                                        : CALL STANDARD_PROCESSING
                                            USING WAGE_HOUR_DATA;
       (AGE_ENTERED < 21)               : CALL YOUTH_PROCESSING
                                            USING WAGE_HOUR_DATA;
       (EMP_STATUS = "Y" AND
         HOURS_WORKED GT 44)            : CALL OT_PROCESSING
                                            USING WAGE_HOUR_DATA;
       (EMP_STATUS = "N" AND
          PAY GT BASE_PAY)              : CALL SECURITY_ALERT
                                            USING WAGE_HOUR_DATA;
    END SELECT;

> This SELECT FIRST clause uses four Boolean expressions to test the contents of workspaces. When ACMS can evaluate an expression as true, it performs the processing step associated with that expression. If ACMS finds a Boolean expression is false, it evaluates the next expression until it finds a true expression or reaches the end of the list.

## Action Clause Example

#1
    ACTION
      SELECT FIRST TRUE OF
        (RESERVE_WKSP.FUNC_KEY EQ " FCAN")    : CANCEL TASK;
        (WK_MARITAL EQ "Y" OR WK_DEPENDENT EQ "Y")
                                              : GOTO STEP GET_FAMILY_INPUT2
        (WK_DEPENDENT EQ "N")                 : GOTO STEP GET_WK_FAMILY_FLAG;
      END SELECT;

> In this example, if the user presses `[PF1]` to cancel the task, DECforms returns the value " FCAN" to the FUNC_KEY field in the RESERVE_WKSP workspace. If " FCAN" is in that field when ACMS processes the SELECT FIRST clause, ACMS cancels the task. Otherwise, ACMS processes the next Boolean expression until it evaluates an expression as true or reaches the end of the expressions to evaluate.

Previous | Next | Contents | Index