HP OpenVMS Systems Documentation

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

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.

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.

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

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.

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.

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

Action Clause	Block Step Attribute
	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

BLOCK WITH NO SERVER CONTEXT
      

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

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.

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.

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.

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.

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.

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.