Performs work as long as a specified Boolean expression evaluates to true.

You can use a WHILE DO clause to start a block, exchange, or processing step (thereby creating a conditional block, exchange, or processing step). The WHILE DO clause uses a Boolean expression to compare workspace fields and takes actions based on the result of the expression. As long as the expression evaluates to true, ACMS performs the action associated with the DO keyword. When the expression evaluates to false, control falls through to the next step.

Format

• WHILE (boolean-expression)
• DO <clause>
• END WHILE;

Parameters

boolean-expression

The Boolean expression must be an expression that ACMS can evaluate as either true or false. As long as the Boolean expression is true, ACMS does the work defined by the corresponding clause. When the expression evaluates to false, control falls through to the next step. You must enclose Boolean expressions in parentheses.

See Section 3.10 for a description of Boolean expressions.

clause

One of the following, depending on where you place the WHILE DO 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 WHILE DO clause at the block step level, you can specify multiple block, exchange, and processing steps to correspond with the Boolean expression.

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

exchange-clause

Any unconditional exchange clause that is 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 the Boolean expression that you specify.

processing-clause

Any unconditional processing clause. There can be only one processing clause for the Boolean expression that you specify.

Table 3-20 summarizes the clauses you can use within the WHILE DO clause at each step.

Table 3-20 Clauses Compatible with the WHILE DO 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, one of:	If task uses REQUEST I/O, one of:	If task uses STREAM I/O, one of:
	NO EXCHANGE RECEIVE SEND TRANSCEIVE	NO EXCHANGE READ REQUEST WRITE	NO EXCHANGE READ WRITE

Keywords

DO

Identifies the work to perform as long as the Boolean expression evaluates to true.

Clause Default

The WHILE DO clause is optional. If you do not use the WHILE DO clause or one of the other three conditional clauses, ACMS processes your block, exchange, or processing work unconditionally.

Notes

You must end each subclause in a WHILE DO clause with a semicolon (;), and you must end the WHILE DO clause with END WHILE and a semicolon (;).

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

If you use WHILE DO 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.

You cannot conditionalize a processing step that starts a distributed transaction by using the WHILE DO clause. Instead, you can either include a loop in the processing step's procedure, or specify WHILE DO on a block step that includes the processing step.

Block Clause Example

BLOCK WORK 
    WHILE (OLD_WORKSPACE NE NEW_WORKSPACE) 
    DO 
       EXCHANGE 
          SEND FORM RECORD EMPLOYEE_INFO_RECORD 
             SENDING EMPLOYEE_INFO_WKSP; 
       PROCESSING 
          CALL EMPLOYEE_UPDATE IN PERSONNEL 
             USING PERS_RECORD, UPDATE_WORKSPACE; 
          ACTION IS 
             MOVE 1 INTO NUMBER_WORKSPACE;  
    END WHILE; 
END BLOCK; 
      

ACMS tests the contents of OLD_WORKSPACE and NEW_WORKSPACE. As long as the Boolean expression evaluates to true, ACMS performs the exchange and processing steps associated with the DO keyword. If the expression evaluates to false, control falls through to the next step.

Exchange Clause Example

EXCHANGE 
    WHILE (EMP_CNTRL_WKSP.STATUS_FIELD EQ "INVAL") 
    DO 
       TRANSCEIVE RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD 
          SENDING EMPLOYEE_INFO_WKSP 
          RECEIVING EMPLOYEE_INFO_WKSP 
    END WHILE; 
    ACTION IS EXIT TASK; 
      

ACMS tests the value of the STATUS_FIELD in the EMP_CNTRL_WKSP workspace. As long as the value of that field is "INVAL", ACMS performs the TRANSCEIVE operation associated with the DO keyword. However, if the value of STATUS_FIELD does not equal "INVAL", ACMS passes control to the action part of the step and exits the task.

Processing Clause Example

PROCESSING 
    WHILE (AGE_ENTERED >= 21) 
    DO 
       CALL STANDARD_PROCESSING USING WAGE_HOUR_DATA; 
    
    END WHILE;  
    ACTION IS 
      GO TO STEP FIVE; 
      

This WHILE DO clause tests the AGE_ENTERED workspace; and, if the Boolean expression evaluates to true, ACMS performs the processing work associated with the DO keyword. Otherwise, ACMS passes control to the action part of the step and goes to STEP FIVE.

Names one or more workspaces used by steps in a task. When you use the WORKSPACES clause in a task definition, the workspaces you name are available only to instances of that task.

Format

Parameters

record-path-name

The CDD path name of the record description for the workspace. You must use the full CDD record path name unless you have set your CDD default to the directory where the record definition is stored. In that case, you can use just the given name of the workspace.

If you name more than one workspace, separate the record path names with commas.

unique-name

The unique name of a workspace. The given name of each workspace must be unique within the workspace declarations for the task group. If two or more given names are identical, you use the unique-name parameter to define a different name to the workspace. If you do not use the unique-name parameter, the default name of the workspace is the given name of the workspace.

Keywords

ACCESS

Identifies the access characteristics of a workspace. The types of access you can define are RETRIEVAL and UPDATE. You can only define access characteristics for GROUP and USER type workspaces. The default type of access is RETRIEVAL.

GROUP

Identifies the workspace as a GROUP type workspace. The contents of a GROUP workspace can be used by many instances of the same task. ACMS maintains these contents from application startup to application shutdown.

LOCK

Indicates that a task instance can lock the workspace from use by other tasks when the task starts and can unlock it when the task stops or is canceled. If you do not use the LOCK keyword, the workspace is not locked. The keyword applies only to GROUP and USER workspaces defined for UPDATE access.

RETRIEVAL

Indicates that a task can use and make changes to the contents of the workspace. However, when the task finishes, ACMS does not copy changes into the master copy of the workspace. RETRIEVAL is the default access for GROUP and USER workspaces.

TASK

Identifies the workspace as a TASK workspace. The contents of a TASK workspace are kept for just one instance of a task. TASK is the default type of workspace.

TYPE

Identifies the type of workspace being used by the task. The workspace types you can define are: TASK, GROUP, and USER.

UPDATE

Indicates that the task can make changes to the contents of the workspace. When the task instance finishes with an EXIT TASK, GOTO TASK, or REPEAT TASK clause, ACMS copies these changes to the master copy of the workspace. Unless you use the LOCK keyword, ACMS does not lock the workspace against updates from other tasks or users.

USER

Indicates the workspace is a USER workspace. The contents of a USER workspace can be used by a single user for many instances of the same or different tasks. A user's copy of a USER workspace exists from the time the user first requires the workspace until that user logs out of ACMS.

Clause Default

The WORKSPACES clause is optional. The default workspaces available to the task are the ACMS system workspaces ACMS$PROCESSING_STATUS (contains processing status information), ACMS$SELECTION_STRING (contains a string submitted at task selection time), and ACMS$TASK_INFORMATION (contains task information). You cannot name the system workspaces in the WORKSPACES clause. System workspaces are always used by a task and are always implicitly declared.

For a discussion of system workspaces, see Appendix B.

Notes

The unique name of a workspace can be different from the name of the record description for that workspace. For example, suppose you assign a unique name to WORK_RECORD:

WORKSPACE IS WORK_RECORD WITH NAME EXAMPLE1;

The record description for WORK_RECORD can be as follows:

DEFINE RECORD WORK_RECORD. SAMPLE STRUCTURE. A. B. END SAMPLE STRUCTURE. END WORK_RECORD.

The name of the record description, WORK_RECORD, simply indicates the location of the record in the dictionary. The unique name of the workspace, EXAMPLE1, does not have to be the same as the name of the record description or the structure, and is only used within the task definition.

In a task definition, to refer to the A field in the EXAMPLE1 workspace, you can use: EXAMPLE1.SAMPLE.A, SAMPLE.A, A, or EXAMPLE1.A.

Suppose you now add another field A to the workspace. Now the record definition looks like this:

DEFINE RECORD WORK_RECORD. SAMPLE STRUCTURE. A. B. X STRUCTURE. A. END X STRUCTURE. END SAMPLE STRUCTURE. END WORK_RECORD.

You encounter an ambiguous field reference when using the following field names in a definition: A, or EXAMPLE1.A. The reference EXAMPLE1.SAMPLE.A is still valid.

Because TASK is the default workspace type and the ACCESS keyword is valid only for GROUP and USER workspaces, you must include the TYPE keyword if you use the ACCESS keyword.

ADU lets you use the LOCK keyword when defining a TASK workspace. However, this keyword has no effect at run time.

Do not name the ACMS system workspaces in the WORKSPACES clause.

You can include more than one WORKSPACES clause in a task definition.

If you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), any other task can use the workspace with ACCESS RETRIEVAL. However, if you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), ACMS cancels, at the beginning of the task instance, any other task or instance of the same task that attempts to use the same workspace with ACCESS UPDATE (either LOCK or NOLOCK).

The sum of the sizes of workspaces referenced in a task definition must not exceed 65,535 bytes.

The ADU does not support CDD objects containing branch information. When the ADU attempts to access a CDD object (for example, an ACMS task) containing branch information, the ADU generates errors similar to the following and aborts:

%ADU-E-ESTFETNEXT, Unexpected CDD Error %CDD-W-ILLBRANCH, TSK1(1:V1:1) contains branch information

Examples

WORKSPACES ARE DEPT_WORKSPACE, HIST_RECORD, PERS_RECORD; 
      

This example assumes that CDD$DEFAULT has been set to the correct directory. The given names of the workspaces being used by the task are DEPT_WORKSPACE, HIST_RECORD, and PERS_RECORD.

WORKSPACES ARE 
  ADD_WORKSPACE,LABOR_REPORT_WORKSPACE TYPE GROUP RETRIEVAL; 
      

The given names of these workspaces are ADD_WORKSPACE and LABOR_REPORT_WORKSPACE. ADD_WORKSPACE is a TASK workspace with default UPDATE access. LABOR_REPORT_WORKSPACE is a group workspace, and the task definition using this workspace clause has retrieval access.

If the block step uses STREAM I/O, the WRITE clause writes the contents of a workspace field to a stream. If the block step uses REQUEST I/O, the WRITE clause passes a literal string or the contents of a workspace to the exception line (line 24) on the terminal screen.

Format

Parameters

workspace-name

The given name of the workspace that contains the text to be displayed on the exception line of the terminal screen (for block steps using REQUEST I/O) or to be written to a stream (for block steps using STREAM I/O). The workspace name must correspond to a workspace declared by the WORKSPACES or USE WORKSPACES clause in the task definition, or must be a system workspace.

literal-string

The text you want to display on the exception line of the terminal screen (for the block steps using REQUEST I/O) or to pass to a stream (for the block steps using STREAM I/O). You must enclose the string in quotation marks. The length of the literal string must be less than the width of the terminal screen. There is no length restriction when you use STREAM I/O.

Clause Default

The WRITE clause is optional. If you do not use the WRITE clause, ACMS does not pass a literal string or the contents of a workspace to the exception line on the terminal screen or to a stream.

Notes

When using REQUEST I/O, the maximum size of the information you pass is the length of a single line on the terminal screen, either 80 or 132 characters. There is no length restriction when you use STREAM I/O.

The sum of the sizes of all workspaces referenced in a task definition must not exceed 65,535 bytes.

Examples

WRITE PERS_MESSAGE; 
      

ACMS writes the contents of the PERS_MESSAGE workspace to the exception line on the terminal screen.

WRITE "Processing done"; 
      

ACMS writes the literal string "Processing done" on the exception line of the terminal screen.