# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# NO SERVER CONTEXT ACTION Clause (Action)

> Maintains the current state of any server context associated with the task.

## Format

> NO SERVER CONTEXT ACTION ;

## Clause Default

> The NO SERVER CONTEXT ACTION clause is optional. Table 3-17 shows the default context actions associated with different cases of a task definition.

## Note

> If there is active server context and you use the NO SERVER CONTEXT ACTION clause, ACMS retains that context. If there is no active server context and you use the NO SERVER CONTEXT ACTION clause, ACMS takes no action regarding server context.

## Example

    BLOCK WITH
     FORM I/O
     SERVER CONTEXT
     GET_DEPT_NUMBER:
       EXCHANGE
          RECEIVE FORM RECORD REVIEW_SCHEDULE
          RECEIVING REVIEW_SCHEDULE_WKSP
          WITH RECEIVE CONTROL QUIT_WORKSPACE;
          CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
            " FCAN"   : CANCEL TASK;
          END CONTROL FIELD;

     GET_FIVE_EMPLOYEES:
       PROCESSING
         CALL REVIEW_SCHEDULE_GET IN DEPARTMENT_SERVER
            USING REVIEW_SCHEDULE_WKSP;
         CONTROL FIELD ACMS$T_STATUS_TYPE
           "B"        : GET ERROR MESSAGE;
                        RELEASE SERVER CONTEXT;
                        GOTO PREVIOUS EXCHANGE;
           "G"        : NO CONTEXT ACTION;
                        GOTO NEXT STEP;
         END CONTROL FIELD;

> If the REVIEW_SCHEDULE_GET procedure is successful in retrieving review schedule information for a department, ACMS returns the value "G" to the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS system workspace. To maintain file pointers, use the NO CONTEXT ACTION clause to maintain the current state of server context.

# NO TERMINAL I/O Phrase (Block, Processing)

> States that the block or processing step does no terminal I/O.

## Format

> NO TERMINAL USER I/O

## Phrase Default

> The NO TERMINAL I/O phrase is optional.

> The default communication method for a block step is REQUEST I/O.

> If you are defining a single-step task that uses a processing step, the default communication method for that task 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 NO TERMINAL I/O phrase in a block step definition, the only clause you can use in any exchange steps in that block is the NO EXCHANGE clause. If you use the NO TERMINAL I/O phrase in a block step clause, you cannot use the FORM I/O, REQUEST I/O, or STREAM I/O phrase in the same block step clause.

> You cannot use the NO TERMINAL I/O phrase with a nested block.

> You can use the TERMINAL I/O phrase in a processing step to override the NO TERMINAL I/O phrase for that block step.

> If you use the NO TERMINAL I/O phrase in a processing step, you cannot use the REQUEST I/O, STREAM I/O, or TERMINAL I/O phrase in the same step. If you use NO TERMINAL I/O, the processing step cannot perform any terminal input or output.

> If you use the NO TERMINAL I/O phrase in a processing step that uses a DCL server, ACMS assigns SYS$OUTPUT and SYS$ERROR to the null device.

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

## Block Step Example

#1
    BLOCK WORK WITH NO TERMINAL I/O

> This block step does no terminal I/O.

## Processing Step Example

#1
    WRITE_EMPLOYEE_RECORD:
      PROCESSING WITH NO TERMINAL I/O
        CALL PERSADD IN PERSONNEL
          USING ADD_WORKSPACE, PERS_RECORD;
        CONTROL FIELD ACMS$T_STATUS_TYPE
          "B"        : GET ERROR MESSAGE;
                       GOTO PREVIOUS EXCHANGE;
        END CONTROL FIELD;

> The WRITE_EMPLOYEE_RECORD step uses the PERSONNEL procedure server to run the PERSADD procedure. There is no communication with the terminal user in the step.

# NONPARTICIPATING SERVER Phrase (Processing)

> Excludes a processing step from participating in an existing distributed transaction.

## Format

> NONPARTICIPATING SERVER

## Phrase Default

> The NONPARTICIPATING SERVER phrase is optional. If you do not specify NONPARTICIPATING SERVER on a processing step within a distributed transaction, the processing step participates in the transaction, and any database or file updates performed by the processing step will be committed or rolled back.

## Notes

> You can specify the NONPARTICIPATING SERVER phrase only on a processing step within a previously-started distributed transaction.

> You cannot specify the NONPARTICIPATING SERVER and TRANSACTION phrases on the same processing step.

> Because a task can only retain context in multiple servers if each server participates in a single distributed transaction, ACMS automatically releases server context for a processing step that specifies NONPARTICIPATING SERVER. You cannot specify the RETAIN SERVER CONTEXT or NO SERVER CONTEXT clause in the action part of a processing step that specifies NONPARTICIPATING SERVER.

> You must specify the NONPARTICIPATING SERVER phrase on steps that perform DCL processing within a distributed transaction.

## Example

    BLOCK WORK WITH DISTRIBUTED TRANSACTION
       PROCESSING WITH NONPARTICIPATING SERVER
         CALL WRITE_EMPLOYEE_MODIFIED_RECORD IN SECURITY_LOG_SERVER
         USING EMPLOYEE_ID_RECORD, ACMS$TASK_INFORMATION;
       PROCESSING
         CALL MODIFY_EMPLOYEE_INFO IN EMPLOYEE_DB_SERVER
         USING EMPLOYEE_INFO_RECORD;
       PROCESSING
         CALL MODIFY_EMPLOYEE_INFO IN ACCOUNT_DB_SERVER
         USING EMPLOYEE_INFO_RECORD;
    END BLOCK;

> This example starts a distributed transaction on the block step and performs three processing steps. The first processing step calls a procedure to write information to a security log. Because it is important for the information written to the security log to survive even if the transaction is rolled back, the processing step includes the NONPARTICIPATING SERVER phrase to exclude it from the distributed transaction.

# PROCESSING Clause (Task)

> Describes work done in a single-step processing task.

## Format

## Parameters

> ### processing-phrase

> Describes an attribute of a processing step. If you use one or more processing phrases, you must define them before defining the processing clause for the task. Section 3.6 explains processing phrases.

> ### processing-clause

> Describes the work done in a processing step. Section 3.6 explains processing clauses.

> ### action-clause

> Describes the unconditional or conditional action to take when the processing work is completed. Section 3.8 explains action clauses.

## Clause Default

> You must use either the PROCESSING clause or the BLOCK clause to define the work a task does.

## Example

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

> This task uses a DCL command to run TPU. The processing work uses the TERMINAL I/O processing phrase. This phrase indicates that the task, consisting of a single processing step, interacts with the terminal user.

# RAISE EXCEPTION Clause (Action)

> Raises a step exception and passes control to the exception handler action part of the step.

## Format

## Parameters

> ### message-number

> A literal number identifying a user-defined status value to be stored in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS system workspace.

> ### numeric-workspace-field

> A workspace field with a CDD signed longword data type. The contents of the field must be the binary longword equivalent of the message symbol for the message you want ACMS to display. ACMS uses the contents of the field to identify a message in one of the message files that can be accessed by the task group associated with the task. The workspace containing this field must be named in either the WORKSPACES or USE WORKSPACES clause in the task definition.

> ### global-symbol

> A valid global symbol identifying a status value to be stored in the ACMS$L_STATUS workspace field. The symbol is resolved to a longword value from the files specified by the /USERLIBRARY, /OBJECT, /SYSLIB, and /SYSSHR qualifiers of the BUILD GROUP command.

## Clause Default

> The RAISE EXCEPTION action clause is optional. If you do not use the RAISE EXCEPTION clause, and an exception is not raised from another source, ACMS does not pass control to the exception handler action part of the step.

## Notes

> When you raise a step exception, ACMS interrupts task execution and searches for an exception handler on the step that raised the exception. If the current step does not contain an exception handler, ACMS searches outer block steps, beginning with the nearest block step and heading towards the root block step.

> When ACMS finds an exception handler, it stores the exception code in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS workspace. ACMS then evaluates the conditional clause, if present, and performs the action clauses.

> If ACMS does not find an exception handler, it raises a nonrecoverable exception and cancels the task.

> You do not have to specify an exception code with the RAISE EXCEPTION clause. If you do include an exception code, it must be a failure status. If you specify a success status, ACMS cancels the task with a status of ACMSEXC-E-INVSTPEXCPTNCODE. If you do not specify an exception code, ACMS provides a default exception code of ACMS$_EXCPTN_TASKACTN.

## Example

    PROCESSING
       CALL ENTER_ORDER IN DIST_CTR_DATABASE_UPDATE_SERVER
          USING ORDER_ENTRY_RECORD, RESTOCK_RECORD, STATUS_RECORD;
    ACTION IS
       IF (DATA_IS_VALID <> "Y")
       THEN
          RAISE EXCEPTION APPL_INVALID_DATA
       END IF;
    EXCEPTION ACTION IS
       IF (ACMS$L_STATUS = APPL_INVALID_DATA)
       THEN
          GOTO STEP REENTER_DATA;
       END IF;

> This example includes a processing step that calls a procedure to update a database. If the ENTER_ORDER procedure is unable to perform the update, it returns a failure status in the DATA_IS_VALID workspace field. ACMS raises a step exception and stores the APPL_INVALID_DATA exception code in the ACMS$L_STATUS system workspace field. ACMS then performs the GOTO STEP action clause in the exception handler action part of the step.

# READ Clause (Exchange)

> If the block step uses STREAM I/O, the READ clause reads from an ACMS stream into a workspace. If the block step uses REQUEST I/O, the READ clause passes information from the exception line (line 24) on the terminal screen to a workspace.

## Format

## Parameters

> ### read-workspace-name

> The given name of the workspace into which you want to read information.

> ### prompt-workspace-name

> The given name of the workspace containing the prompt to be displayed on the screen (for a block step using REQUEST I/O) or passed to the stream (for a block step using STREAM I/O). The name you use must correspond to a workspace declared in the task definition by the WORKSPACES or the USE WORKSPACES clause. The length of the workspace must not exceed the width of the terminal screen. If the I/O method is STREAM I/O, there is no length restriction.

> ### literal-string

> The prompt that displays on the terminal screen (for a block step using REQUEST I/O) or is passed to the stream (for a block step 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. If the I/O method is STREAM I/O, there is no length restriction.

## Clause Default

> The READ clause is optional. If you do not use the READ clause, ACMS does not pass information from the terminal exception line to a workspace or from a stream to a workspace.

## Example

    READ PERS_TEXT_NUMBER

      WITH PROMPT "What is the next employee number?";

> In this example, the quoted string displays on the terminal, and the user's response is passed as input to the PERS_TEXT_NUMBER workspace.

# RECEIVE Clause (Exchange)

> Transfers information from form data to your task workspace.

## Format

## Parameters

> ### record-identifier

> The name of the form record that defines how data is transferred between form data items and your task workspace. 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.

> ### 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 at all.

> ### receive-control-workspace

> The given name of the workspace that contains status information about the completed RECEIVE 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 the 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, either create a workspace field that contains the number of seconds, or 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, either create a workspace field that contains the number of seconds, or 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 RECEIVE clause is optional.

## Notes

> If you do not specify the form in the RECEIVE 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
    RECEIVE FORM RECORD EMPLOYEE_INFO_RECORD IN EMPLOYEE_INFO_LABEL
       RECEIVING EMPLOYEE_INFO_WKSP  SHADOW IS EMPLOYEE_INFO_SHADOW
          WITH TIMEOUT 30;

> 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. EMPLOYEE_INFO_SHADOW is the receive shadow workspace that identifies which fields in EMPLOYEE_INFO_WKSP have changed as a result of the exchange with the form.

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

#2
    EXCHANGE
         RECEIVE RECORD MY_RECORD
             RECEIVING MY_RECORD
             WITH 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.

# RELEASE SERVER CONTEXT Clause (Action)

> Releases the server process allocated for a task.

## Format

> RELEASE SERVER CONTEXT [ IF ACTIVE SERVER CONTEXT ] ;

## Keywords

> ### IF ACTIVE SERVER CONTEXT

> Releases server context only if there is active server context. If you use the RELEASE SERVER CONTEXT clause without the IF ACTIVE SERVER CONTEXT keywords and there is no active server context, ACMS cancels the task.

## Clause Default

> The RELEASE SERVER CONTEXT clause is optional. Table 3-17 shows the default context actions taken in a task definition.

## Notes

> When you use the RELEASE SERVER CONTEXT clause or RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT clause on a step that does not start or participate in a distributed transaction, the default recovery action is COMMIT IF ACTIVE RECOVERY UNIT.

> The default transaction action for a step that starts a distributed transaction is COMMIT TRANSACTION.

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

## Example

    BLOCK WITH
      FORM I/O
      SERVER CONTEXT
      GET_DEPT_NUMBER:
        EXCHANGE
          RECEIVE FORM RECORD REVIEW_SCHEDULE
            RECEIVING REVIEW_SCHEDULE_WKSP
            WITH RECEIVE CONTROL QUIT_WORKSPACE;
          CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
            " FCAN"   : CANCEL TASK;
          END CONTROL FIELD;
      GET_FIVE_EMPLOYEES:
        PROCESSING
          CALL REVIEW_SCHEDULE_GET IN DEPARTMENT_SERVER
            USING REVIEW_SCHEDULE_WKSP;
          CONTROL FIELD ACMS$T_STATUS_TYPE
            "B"        : GET ERROR MESSAGE;
                         RELEASE SERVER CONTEXT;
                         GOTO PREVIOUS EXCHANGE;
            "G"        : NO CONTEXT ACTION;
                         GOTO NEXT STEP;
          END CONTROL FIELD;

> If the REVIEW_SCHEDULE_GET procedure is unsuccessful in reading review schedule information for a department, ACMS returns the value "B" to the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS workspace. In this task, if the procedure is successful, the user can choose to see the next records in the file. Therefore, you must normally retain file pointers, a part of server context, to keep track of the user's file location. However, when the procedure is unsuccessful, you do not need to retain these pointers and can, therefore, release server context.

Previous | Next | Contents | Index