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.

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

BLOCK WORK WITH NO TERMINAL I/O 
      

This block step does no terminal I/O.

Processing Step Example

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.

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.

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.

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.

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.

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

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.

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.

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.