# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# TERMINAL I/O Phrase (Processing)

> Specifies that a processing step communicates directly with the terminal by means of programming statements, OpenVMS services, or TDMS requests.

## Format

> TERMINAL I/O

## Phrase Default

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

## Notes

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

> You cannot distribute a task that does any I/O in a processing step.

> If you use the TERMINAL I/O phrase in a processing step that runs in a procedure server, the procedure named by the CALL clause in that step must open and close the terminal channels needed by the step. The opening and closing of channels must be done by some method other than with COBOL ACCEPT and DISPLAY statements, and BASIC INPUT and PRINT statements, or with the RTL LIB$GET_INPUT service, the LIB$PUT_OUTPUT service, and screen procedures. Open a channel to the terminal using SYS$INPUT as a file name and perform I/O over the channel.

> You cannot use the STREAM I/O phrase in a processing step.

> You can use the TERMINAL I/O phrase in processing steps that use either procedure or DCL servers.

> When you use the TERMINAL I/O phrase in a processing step, ACMS assigns the terminal to SYS$INPUT, SYS$COMMAND, SYS$OUTPUT, and SYS$ERROR.

> 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.

## Example

    PROCESSING WITH TERMINAL I/O
      DCL COMMAND IS "$EDIT/TPU 'P1'"
      IN PRIVATE_UTILITY_SERVER;

> This processing step uses the server PRIVATE_UTILITY_SERVER to execute a DCL command that invokes TPU. The command uses a parameter the user supplies as P1. Because PRIVATE_UTILITY_SERVER is a DCL server, the processing step does input and output with the terminal.

# TRANSACTION Phrase (Block, Processing)

> Identifies the block or processing step as a transaction; all work within the step must complete successfully or be rolled back.

## Format

> DISTRIBUTED TRANSACTION

## Phrase Default

> The TRANSACTION phrase is optional. If you do not include it, ACMS does not process the step as a transaction.

## Notes

> You can start a distributed transaction on a root block, nested block, root processing step, or a processing step that is part of a multiple-step task. A distributed transaction must end in the action part of the step that started the transaction. Use the COMMIT TRANSACTION clause to make permanent the file or database operations performed within the distributed transaction. Use the ROLLBACK TRANSACTION clause to return files and databases to the state they were in before the start of the distributed transaction.

> If you do not specify COMMIT TRANSACTION or ROLLBACK TRANSACTION in the action part of a step that starts a distributed transaction, ACMS commits the distributed transaction. However, if the action part of the step specifies CANCEL TASK or RAISE EXCEPTION, ACMS rolls back the distributed transaction.

> If a distributed transaction fails to complete successfully, ACMS cancels the task. Depending upon the reason for the failure, you might want the task to continue to execute instead of canceling. See EXCEPTION HANDLER Clause (Block, Exchange, Processing) and Compaq ACMS for OpenVMS Writing Applications for information on using the EXCEPTION HANDLER ACTION clause to recover from transaction failures.

> You can include a called task within a distributed transaction started by the parent task. For a called task to be able to participate in a distributed transaction, it must conform to the following rules:

> - The root block or root processing step must specify the TRANSACTION phrase.
> - The action part of the root block or root processing step cannot specify any sequencing action clauses other than EXIT TASK, CANCEL TASK, or RAISE EXCEPTION.
> - The action part of the root block or root processing step cannot specify COMMIT TRANSACTION or ROLLBACK TRANSACTION.
> - The root block or root processing step cannot contain an EXCEPTION HANDLER ACTION component.
> - The root block or root processing step cannot specify the CANCEL ACTION phrase.

> A task that conforms to the above rules is a composable task.

> Because a distributed transaction must end in the action part of the step on which it started, you cannot specify EXIT TASK, GOTO TASK, or REPEAT TASK on a step within a distributed transaction.

> 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.

> You cannot declare an RMS file or a database recovery unit within a distributed transaction by specifying RMS RECOVERY, DBMS RECOVERY, RDB RECOVERY, or SQL RECOVERY in the task definition. You can, however, declare a recovery unit in the procedure.

> ACMS automatically retains server context between steps within a distributed transaction. Therefore, you cannot specify the RELEASE SERVER CONTEXT action clause within a distributed transaction. When a transaction ends, ACMS automatically releases server context. You cannot specify the RETAIN SERVER CONTEXT or NO SERVER CONTEXT ACTION clause in the action part of the step that started a distributed transaction.

> Within a distributed transaction, you can exclude a processing step from participating in the transaction by specifying the NONPARTICIPATING SERVER phrase. See NONPARTICIPATING SERVER Phrase (Processing) for information on how to use this phrase.

> You can choose to start and end a distributed transaction in a procedure, rather than in the task definition, by using the $START_TRANS, $END_TRANS, and $ABORT_TRANS system services.

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

Table 3-19 Default Transaction Actions
| Default Transaction Action
--- | ---
Action Clause | If you started the distributed transaction in the current step | If you did not start the distributed transaction in the current step
CANCEL TASK, RAISE EXCEPTION | ROLLBACK TRANSACTION | No transaction action
OTHER | COMMIT TRANSACTION | No transaction action

## 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
             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 inserts a queued task into a queue file. However, if it is a priority order, the processing step checks the master database to see if the manufacturing plant can satisfy the order. 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.

# TRANSCEIVE Clause (Exchange)

> Combines the SEND and RECEIVE operations. First, DECforms sends information from your task workspace to form data items. Then, it moves data from the form to your task workspace.

## Format

## Parameters

> ### send-record-identifier

> The name of the form record that defines how data is sent from your task workspace to form data items. The record identifier can also name a form record list.

> ### receive-record-identifier

> The name of the form record that defines how your task workspace receives data from form data items. The record identifier can also name a form record list.

> ### form-label-name

> The name of the form that contains the records named by the record identifiers. This is the name assigned to the form by using the WITH NAME keywords in the FORMS clause of the task group definition.

> ### send-workspace-name

> The given name of the workspace that contains the information you want to transfer to the form.

> ### send-shadow-workspace

> The given name of the workspace that can contain an indicator that instructs the DECforms whether or not to update last-known values of form data items.

> ### receive-workspace-name

> The given name of the task workspace that receives data from the form.

> ### receive-shadow-workspace

> The given name of the workspace that contains indicators about which fields in the receive workspace have changed as a result of the exchange with the form. The first field in the workspace must be a one-character field into which DECforms can store a value indicating whether or not the receive workspace has changed.

> ### receive-control-workspace

> The given name of the workspace that contains status information about the completed TRANSCEIVE operation. DECforms returns status information in the form of receive control text items. Each receive control text item is five characters long.

> ### numeric-workspace-field2

> The name of a workspace field that contains the number of receive control text items in the receive control workspace. This number indicates the number of receive control text items returned by DECforms. Each item is five bytes in length. The data type of the workspace field must be signed or unsigned longword. The value of the field is set after the DECforms request is completed.

> ### send-control-workspace

> The given name of the workspace that contains up to five send control text items to be passed to DECforms. For each send control text item, you must define a corresponding control text response within the form.

> ### numeric-workspace-field3

> The name of a workspace field that contains the number of send control text items in the send control workspace. You specify the number of control text items in the send control workspace. The data type of the workspace field must be signed or unsigned longword. The value of the field must be set before the DECforms request is executed.

> ### send-control-count

> The number of send control text items in the send control workspace. You specify the number of control text items in the send control workspace.

> ### numeric-workspace-field

> The given name of the workspace field that identifies the maximum time allowed between operator entries. To specify a time limit, you can either create a workspace field that contains the number of seconds, or you can hardcode the number of seconds in the exchange step clause.

> The workspace field is in the workspace that you name in the task definition with the WORKSPACES clause. If you name more than one workspace with the WORKSPACES clause, you must name the workspace and the field in the TIMEOUT argument.

> DECforms allows you to specify an infinite number of seconds as a timeout value for a panel or icon by specifying a zero or negative value with the DECforms TIMEOUT subclause. As an alternative, ACMS allows you to specify an infinite timeout value with a negative value for numeric-workspace-field in the TIMEOUT subclause.

> ### seconds

> The maximum number of seconds that can elapse between operator entries. To specify a time limit, you can either create a workspace field that contains the number of seconds, or you can hardcode the number of seconds in the exchange step clause.

> DECforms allows you to specify an infinite number of seconds as a timeout value for a panel or icon by specifying a zero or negative value with the DECforms TIMEOUT subclause. As an alternative, ACMS allows you to specify an infinite timeout value by giving a zero value of seconds. A negative value of seconds produces the following error:

>     %ACMSTDU-E-SYNTAXERR: Found '-' when expecting ';'

## Clause Default

> The TRANSCEIVE clause is optional.

## Notes

> If you do not specify the form in the TRANSCEIVE clause, and you do not name a default form in the task definition, ACMS uses the first form named in the task group definition.

> If the operator does not make an entry within the TIMEOUT limit, ACMS cancels the task. If you omit the TIMEOUT argument or if you specify zero seconds, the operator has unlimited time between entries.

> To use the control text COUNT clauses at run time, both the submitter node and application node must have ACMS Version 3.3 or higher installed. If the application node has ACMS Version 3.3 or higher, and the submitter node has a previous version of ACMS, then ACMS cannot pass the control text count values between the application node and the submitter node. In this case, a step exception is raised in the task with the TPS$_NOCNTRLCNTSUB error status.

> If the application node has a version of ACMS lower than Version 3.3, then the control text COUNT clause is ignored at run time, and cannot be updated.

## Examples

#1
    TRANSCEIVE FORM RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD
       IN EMPLOYEE_INFO_LABEL
          SENDING EMPLOYEE_INFO_WKSP  SHADOW IS SEND_EMPLOYEE_INFO_SHADOW
          RECEIVING EMPLOYEE_INFO_WKSP  SHADOW IS REC_EMPLOYEE_INFO_SHADOW
             WITH TIMEOUT 30;

> The SEND part of this step uses the form record EMPLOYEE_INFO_RECORD to move data from the task workspace EMPLOYEE_INFO_WKSP to the form data items stored in the form EMPLOYEE_INFO_LABEL. SEND_EMPLOYEE_INFO_SHADOW is the send-shadow-workspace that instructs DECforms whether or not to update last-known values of form data items.

> The RECEIVE part of this step uses the form record EMPLOYEE_INFO_RECORD to move data from form data items stored in the form EMPLOYEE_INFO_LABEL to the task workspace EMPLOYEE_INFO_WKSP. REC_EMPLOYEE_INFO_SHADOW is the receive-shadow-workspace that identifies which fields in EMPLOYEE_INFO_WKSP have changed because of the exchange with the form.

> The TIMEOUT argument establishes 30 seconds as the maximum time that can elapse between operator entries.

> You can use a TRANSCEIVE clause that sends and receives the same form record and task workspace to let the operator display and then update form data items.

#2
    EXCHANGE
         TRANSCEIVE RECORD MY_RECORD, MY_RECORD
             SENDING MY_RECORD
             RECEIVING MY_RECORD
             WITH SEND CONTROL SEND_CNTRL COUNT CNTRL_COUNTS.SEND_COUNT
                  RECEIVE CONTROL RECV_CNTRL COUNT CNTRL_COUNTS.RECV_COUNT;

> When this request completes, DECforms returns the control text items into the RECV_CNTRL workspace, and returns the number of control items into the CNTRL_COUNTS.RECV_COUNT field. For instance, if DECforms returns two control text items, which are " F001" and " F002", the contents of the workspace RECV_CNTRL become " F001 F002", and the field CNTRL_COUNTS.RECV_COUNT equals 2.

# USE WORKSPACES Clause (Task)

> Names one or more workspaces, declared in the task group, to which a task needs access.

## Format

## Parameter

> ### workspace-name

> The given name or assigned name of the workspace declared in the WORKSPACES clause of the task group definition. It is not a CDD path name. Use commas to separate workspaces you declare. Any workspaces you declare must be named in a WORKSPACES clause of the task group definition.

## 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 access type is specified in the WORKSPACES clause in the task group definition. If you do not specify an access type in the WORKSPACES clause, the default access type is RETRIEVAL.

> ### 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 to have 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.

> ### UPDATE

> Indicates that the task can make changes to the contents of the workspace. When the task finishes, 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 by other tasks or users.

## Clause Default

> The USE WORKSPACES clause is optional. If you do not use the USE WORKSPACES clause, workspaces declared in the task group are not available to the task.

## Notes

> You can use the USE WORKSPACES clause multiple times in a single task definition.

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

> You cannot declare a workspace type for workspaces you name in a USE WORKSPACES clause.

> Do not name the ACMS system workspaces in the USE WORKSPACES clause. ACMS system workspaces are available to each task by default.

> 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 all workspaces referenced in a task definition must not exceed 65,535 bytes.

##

### Examples

#1
    USE WORKSPACE DEPT_WORKSPACE WITH RETRIEVAL;

> In this example, the name of the workspace in the task group definition is DEPT_WORKSPACE. The task can only read and use the contents of this workspace. It cannot make changes to the contents.

#2
    USE WORKSPACE DEPT_WORKSPACE WITH UPDATE LOCK;

> In this example, the task has update access to the DEPT_WORKSPACE workspace and locks the workspace from access by other tasks.

# WAIT Clause (Task)

> Controls whether or not ACMS displays a message prompting users to press `[Return]`. Pressing `[Return]` clears the terminal screen and displays the previous ACMS menu.

## Format

> [ NO ] WAIT ;

## Clause Default

> The ACMS-supplied default is NO WAIT. This clause is optional.

## Notes

> If you use the WAIT clause in a task definition, you must include it before the processing or block step for that definition.

> You cannot use the WAIT clause and the DELAY clause in the same definition.

> The WAIT and DELAY clauses determine how quickly ACMS returns user control to a menu when a task ends. If a user runs a task that displays the time of day, for example, with the SHOW TIME command, by default ACMS displays the time, but then immediately clears the screen and returns to the menu. Both clauses let you delay the time between the end of a task and the return to the selection menu.

> If you do not specify a WAIT clause or set the wait attribute in an application definition TASK ATTRIBUTES clause, ACMS uses the setting you assign in the task group definition. If you do not make an assignment there, ACMS uses the NO WAIT default.

> WAIT and DELAY clauses in a menu definition override attributes specified in a task, task group, or application definition.

## Example

    WAIT;

> ACMS waits for the user to press `[Return]` before clearing the final screen of the task and returning the user to a menu.

Previous | Next | Contents | Index