# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# SEND Clause (Exchange)

> Transfers information from your task workspace to form data items.

## Format

## Parameters

> ### record-identifier

> The name of the form record that defines how data is transferred between your task workspace and form data items. The record identifier can also name a form record list.

> ### form-label-name

> The name of the form that contains the record named by the record identifier. 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 a one-character indicator that instructs the DECforms whether or not to update last-known values of form data items.

> ### receive-control-workspace

> The given name of the workspace that contains status information about the completed SEND 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 5 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 SEND clause is optional.

## Notes

> If you do not specify the form in the SEND 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.

> 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 TIMEOUT subclause. As an alternative, ACMS allows you to specify an infinite timeout value in one of the following ways:

> - You can code a zero value in the TIMEOUT subclause. A negative value is not valid in the TIMEOUT subclause and produces the following error:

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

> - Place a negative value in numeric-workspace-field.

> 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
    SEND FORM RECORD EMPLOYEE_INFO_RECORD IN EMPLOYEE_INFO_LABEL
       SENDING EMPLOYEE_INFO_WKSP  SHADOW IS EMPLOYEE_INFO_SHADOW

> 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. EMPLOYEE_INFO_SHADOW is the send-shadow workspace that instructs DECforms whether or not to update last-known values of form data items.

#2
    EXCHANGE
        SEND RECORD my_record
            WITH SEND CONTROL send_cntrl COUNT 2
                 RECEIVE CONTROL recv_cntrl ;

> In this example, two items are sent with the record my_record.

# SERVER CONTEXT Phrase (Block)

> Specifies whether or not server context is retained by default between steps in a block step.

## Format

> [ NO ] SERVER CONTEXT

## Phrase Default

> The SERVER CONTEXT phrase is optional; if you do not use the SERVER CONTEXT phrase, ACMS does not keep server context between the steps in a block step, unless the block step started a distributed transaction.

> The default server context action for the action part of a processing or block step is different for steps that start or are within a distributed transaction. Table 3-17 shows the default server context actions for steps that do not start or appear within a distributed transaction. Table 3-18 shows the default server context actions for steps that start or are within a distributed transaction.

> Table 3-17 Default Server Context Actions
> | Block Step Attribute
> --- | ---
> Action Clause | With Server Context | With No Server Context
> CANCEL TASK | NO SERVER CONTEXT ACTION | NO SERVER CONTEXT ACTION
> EXIT TASK, GOTO TASK, or REPEAT TASK | RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT | RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT
> OTHER | RETAIN SERVER CONTEXT IF ACTIVE SERVER CONTEXT | RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT

> Table 3-18 Default Server Context Actions (Distributed Transactions)
> Step Attribute | Default Server Context Action
> --- | ---
> DISTRIBUTED TRANSACTION | RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT
> Step is within a distributed transaction | RETAIN SERVER CONTEXT IF ACTIVE SERVER CONTEXT
> NONPARTICIPATING SERVER | RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT

## Note

> You cannot specify NO SERVER CONTEXT on a block step that starts a distributed transaction or on a nested block step within a distributed transaction.

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

##

### Examples

#1
    BLOCK WITH NO SERVER CONTEXT

> ACMS does not retain process context between steps in the step block.

#2
    REPLACE TASK REVIEW_SCHEDULE_TASK
      DEFAULT SERVER IS DEPARTMENT_SERVER;
      WORKSPACES ARE QUIT_WORKSPACE, REVIEW_SCHEDULE_WKSP;
        BLOCK
          WORK WITH FORM I/O
                    SERVER CONTEXT
                    DBMS RECOVERY "READY DEPART ADMIN CONCURRENT RETRIEVAL"
          GET_DEPT_NUMBER:
            EXCHANGE
              RECEIVE FORM RECORD REVIEW_SCHEDULE_INPUT_RECORD
                RECEIVING REVIEW_SCHEDULE_WKSP
                WITH RECEIVE CONTROL QUIT_WORKSPACE;
              CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
                " FEXT"   :  EXIT TASK;
              END CONTROL FIELD;
          GET_FIVE_EMPLOYEES:
            PROCESSING
              CALL REVIEW_SCHEDULE_GET
                USING REVIEW_SCHEDULE_WKSP;
              CONTROL FIELD ACMS$T_STATUS_TYPE
                "B"        : GET ERROR MESSAGE;
                             GOTO PREVIOUS EXCHANGE;
              END CONTROL FIELD;

          DISPLAY_EMPLOYEES:
            EXCHANGE
              SEND FORM RECORD REVIEW_SCHEDULE_OUTPUT_RECORD
                SENDING REVIEW_SCHEDULE_WKSP
                WITH RECEIVE CONTROL QUIT_WORKSPACE;
              CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
                " FMOR"   :  GOTO PREVIOUS PROCESSING;
                " FEXT"   :  EXIT TASK;
              END CONTROL FIELD;
          END BLOCK WORK;
          ACTION
            REPEAT STEP;
        END DEFINITION;

> In the REVIEW_SCHEDULE_TASK, the user can look at the review schedule information for a department. The user looks at five records at a time and can then indicate whether or not to see more records. To keep track of the user's location in the file, you must retain file pointers. Because file pointers are part of the context associated with a server process, you retain server context for the block.

#3
    REPLACE TASK REVIEW_UPDATE_TASK /LIST=RVSCHED.LIS
      WORKSPACES ARE EMPLOYEE_INFO_WKSP, HISTORY_WKSP, DEPT_WKSP, QUIT_
      WORKSPACE;
      DEFAULT SERVER IS DEPARTMENT_SERVER;
      BLOCK
        WORK WITH NO SERVER CONTEXT
                  FORM I/O
        GET_EMPLOYEE:
          EXCHANGE
            RECEIVE FORM RECORD REVIEW_UPDATE_INPUT_RECORD
              RECEIVING EMPLOYEE_INFO_WKSP, HISTORY_WKSP
              WITH RECEIVE CONTROL QUIT_WORKSPACE;
            CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
                          ! Message - No updates made to database
              " FCAN"   :  CANCEL TASK RETURNING 136085514;
            END CONTROL FIELD;

          PROCESSING WITH
            DBMS RECOVERY "READY DEPART ADMIN CONCURRENT UPDATE"
            CALL REVIEW_UPDATE_GET
              USING EMPLOYEE_INFO_WKSP, HISTORY_WKSP, DEPT_WKSP;
            CONTROL FIELD ACMS$T_STATUS_TYPE
              "B"        : GET ERROR MESSAGE;
                           ROLLBACK;
                           GOTO PREVIOUS EXCHANGE;
            END CONTROL FIELD;

        UPDATE_EMPLOYEE:
          EXCHANGE
            SEND FORM RECORD REVIEW_UPDATE_OUTPUT_RECORD
              SENDING HISTORY_WKSP, DEPT_WKSP
              WITH RECEIVE CONTROL QUIT_WORKSPACE;
            CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
                          ! Message - No updates made to database
              " FCAN"   :  CANCEL TASK RETURNING 136085514;
            END CONTROL FIELD;

          PROCESSING WITH
            DBMS RECOVERY "READY DEPART ADMIN CONCURRENT UPDATE"
            CALL REVIEW_UPDATE_PUT
              USING DEPT_WKSP, HISTORY_WKSP;
            CONTROL FIELD ACMS$T_SEVERITY_LEVEL
                          ! Message - Record deleted,
                          ! no update made to database
              "F"        : CANCEL TASK RETURNING 136085513;
              "E"        : GET ERROR MESSAGE;
                           ROLLBACK;
                           GOTO PREVIOUS EXCHANGE;
              NOMATCH    : EXIT BLOCK;
            END CONTROL FIELD;

       END BLOCK WORK;
       ACTION
         REPEAT STEP;
     END DEFINITION;

> In this example, REVIEW_UPDATE_TASK allows the user to retrieve, view, and update an employee's personnel record from the PERSONNEL DBMS database. Note that REVIEW_UPDATE_TASK does not retain server context.

> The DBMS RECOVERY phrase automatically starts a recovery unit in the first processing step. If the status returned from the step procedure REVIEW_UPDATE_GET is bad, the recovery unit is rolled back, and the task returns to the previous exchange step for another employee number. If the status returned is good, the default recovery action is to commit the recovery unit. Thus, server context is not retained over the exchange step UPDATE_EMPLOYEE.

> The next processing step starts a second recovery unit, again using the DBMS RECOVERY phrase. At the end of this processing step, the severity of the status returned by the REVIEW_UPDATE_PUT procedure is tested. If the severity level is F, the error is not recoverable and the task is canceled. If the severity level is E, indicating a recoverable error, the recovery unit is rolled back, and the user returns to the previous exchange to try the update again. If the severity level is neither F nor E, indicating success, the task exits, committing the recovery unit by default.

# STREAM I/O Phrase (Block)

> Specifies that the exchange steps in a block step use ACMS streams to communicate with the terminal user or other task submitter.

## Format

> STREAM I/O

## Phrase Default

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

## Notes

> You can use the STREAM I/O phrase to execute tasks on devices not supported by TDMS or DECforms.

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

> If a block step uses STREAM I/O, exchange steps in that block step cannot use DECforms clauses or the TDMS REQUEST clause to do work.

> If a block step uses STREAM I/O, NO TERMINAL I/O is the only input/output method you can define for processing steps in that block step.

> You cannot specify STREAM I/O on a nested block.

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

> For I/O restrictions on tasks accessed remotely, see Section 3.11.

## Example

    BLOCK WITH STREAM I/O

> The exchange steps in this block step use ACMS streams when doing prompted reads and writes.

# TASK ARGUMENTS Phrase (Task)

> Identifies the names and the order of the task workspace arguments that can be supplied to a called task by an agent or by another task.

## Format

## Parameter

> ### workspace-name

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

## Keywords

> ### ACCESS

> Identifies the access characteristics of a workspace. The types of access you can define are READ, WRITE, and MODIFY.

> ### READ

> A workspace argument defined for READ access is initialized with data supplied by an agent or calling task or with its default contents or zeros. The contents of the workspace are not returned to the agent or calling task when the task completes. The task can modify the contents of the workspace during execution, but any modifications are lost when the task ends.

> ### WRITE

> A workspace argument defined for WRITE access is initialized with its default contents or zeros. ACMS does not pass data stored in a workspace argument defined for WRITE access when calling a task from an agent or another task. The task can modify the contents of the workspace during execution, and any modifications are returned to the agent or calling task when the called task completes.

> ### MODIFY

> A workspace argument defined for MODIFY access is initialized with the data supplied by an agent or calling task or, if not supplied on the task call, with its default contents or with zeros. The task can modify the contents of the workspace during execution, and any modifications are returned to the agent or calling task when the called task completes.

## Clause Default

> The TASK ARGUMENT clause is optional. If a workspace identified as a TASK ARGUMENT is not supplied by a calling task or agent, ACMS initializes it with its default contents from the task group database or with zeros.

> MODIFY is the default access for TASK ARGUMENT workspaces.

## Notes

> ACMS allows a task to accept arguments into task workspaces. You cannot pass arguments into group, user, or system workspaces.

> Specifying READ access provides performance benefits for tasks that call other tasks because ACMS does not have to update the workspace in the calling task when the called task completes. Specifying READ or WRITE access provides performance benefits for agents that call tasks. ACMS does not send data in workspaces defined for WRITE access from an agent to a task, or send data in workspaces defined for READ access from a task back to the agent.

> The USE WORKSPACES or WORKSPACES clauses must precede a TASK ARGUMENTS phrase in a task definition.

> If a task that accepts data into workspaces defined as task arguments chains to another task, the workspaces with MODIFY or WRITE access are updated according to whether or not these workspaces are passed to the new task.

> If a workspace defined in the original task is passed to a chained task, any changes made to the workspace by the new task are returned to the calling task or agent when the task completes. If a workspace defined as a TASK ARGUMENT in the original task is not passed to the chained task, the contents of the workspace at the time of a GOTO TASK operation are returned to the calling task or agent.

> The data in task argument workspaces can be passed to new task instances using the PASSING phrase of the REPEAT TASK clause. If a task argument workspace is not passed using the PASSING phrase, the contents of the workspace at the end of the current task are saved and later returned to the calling task or agent. The workspaces in the repeated task instance are initialized to the initial contents as defined in the dictionary.

> If any chained tasks or repeated tasks are canceled or fail, the contents of any task argument workspaces are not updated in the parent task or agent. However, user and group workspaces are updated each time a GOTO TASK action clause is processed. For example, if a task updates a workspace and is then chained to another task, and the second task is canceled, the master copy of the workspace reflects the state at the end of the first task. Any workspaces supplied as a task argument are not updated in the calling task or agent.

> Note ADU does not recognize if you incorectly specify the same workspace-name twice. For example, the following statement should produce a syntax error, but does not:
>     TASK ARGUMENTS ARE EMPLOYEE_REC WITH ACCESS READ,
>                        EMPLOYEE_REC;
> If you select this task, it is cancelled, and the Software Event Logger includes the message "End of task-referenced workspace table" in the Audit Trail record of the task. If you attempt to dump a task group that contains this task, ADU gives an ACCVIO error.

## Example

    REPLACE TASK GET_EMPLOYEE
        CANCELABLE;
        WORKSPACE IS WORK_RECORD WITH NAME WORK,
                     PERS_RECORD WITH NAME PERSONNEL,
                     DEPT_WORKSPACE;
        TASK ARGUMENTS ARE WORK,DEPT_WORKSPACE,PERSONNEL;
        PROCESSING IS CALL DISPLAY IN DISPLAY_SERVER
            USING WORK,DEPT_WORKSPACE,PERSONNEL;
    END DEFINITION;

> In this example, the TASK ARGUMENTS phrase specifies that the three workspace arguments in the task definition for GET_EMPLOYEE can be supplied to a task. You must supply the workspace arguments in the specified order.

Previous | Next | Contents | Index