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:

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:

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