Names a default request library used by REQUEST clauses in exchange steps of a task.

Format

DEFAULT REQUEST LIBRARY IS request-library-name ;

Parameter

request-library-name

The name assigned to the request library using the WITH NAME keywords in the REQUEST LIBRARY clause of the task group definition.

Clause Default

The DEFAULT REQUEST LIBRARY clause is optional. You can name, in the REQUEST clause of an exchange step, the request library used by that step. If you do not specify the request library in an exchange step, and you do not use the DEFAULT REQUEST LIBRARY clause, ACMS uses the first request library declared in the task group definition.

Notes

If you name a default request library for a task, you must use the DEFAULT REQUEST LIBRARY clause before you define a block or processing step for that task.

When you use the DEFAULT REQUEST LIBRARY clause, you do not have to name a request library in individual exchange steps unless one of those steps uses a request from a different request library.

If you name a request library with the DEFAULT REQUEST LIBRARY clause, ACMS searches that library. If you do not use the DEFAULT REQUEST LIBRARY clause, and the request library is not specified in the exchange step of the task, ACMS searches the first library declared in the task group definition.

You can use the IN REQUEST LIBRARY keywords in the REQUEST clause of an exchange step to override a request library named by the DEFAULT REQUEST LIBRARY clause.

Example

DEFAULT REQUEST LIBRARY DEPART_REQUEST_LIBRARY; 
      

This names DEPART_REQUEST_LIBRARY as the default request library for this task. The exchange steps in the task use requests from this library unless specified otherwise in individual exchange steps.

Names a default server to handle processing and canceling actions for the step or steps in a task.

Format

DEFAULT SERVER IS server-name ;

Parameter

server-name

The name of a server defined in the task group definition. The server-name is a 1- to 31-character identifier.

Clause Default

The DEFAULT SERVER clause is optional. If you do not use the DEFAULT SERVER clause in a task definition, you must use the IN SERVER keywords in each processing step of the task to name the server that you want to handle the work for that step.

Notes

If you name a default server for a task, you must use the DEFAULT SERVER clause before you define a block or processing step for that task.

When you use the DEFAULT SERVER clause, you do not have to name a server in individual processing steps unless one of those steps requires a different server.

You can use the IN SERVER keywords of a processing work clause in a processing step to override a server named in the DEFAULT SERVER clause.

If a task is keeping context in a server and a step in that task names another server, the task must release context of the first server before using the second server.

A task can use more than one server. However, you can retain context only within one server at a time. A task can also use both DCL and procedure servers.

Example

DEFAULT SERVER IS DEPARTMENT_SERVER; 
      

This names DEPARTMENT_SERVER as the default server for this task. The processing steps in the task use the DEPARTMENT_SERVER unless specified otherwise in individual processing steps.

Controls whether or not ACMS pauses after a task finishes running before clearing the screen and displaying the ACMS menu.

Format

[ NO ] DELAY ;

Clause Default

The ACMS-supplied default is NO DELAY. This clause is optional.

Notes

You cannot use a DELAY clause and a WAIT clause in the same definition.

The DELAY clause always delays clearing the screen for 3 seconds. You cannot change the time of the delay.

This clause differs from the WAIT clause, which requires users to press [Return] to have ACMS redisplay the menu.

The WAIT and DELAY clauses determine how quickly ACMS returns user control to a menu when a task ends. For example, if a user runs a task that displays the time of day with the SHOW TIME command, by default ACMS displays the time, but then immediately clears the screen and returns the user to the menu. Both clauses let you delay the time between when the task ends and when ACMS returns to the selection menu.

WAIT and DELAY attributes specified in a task, task group, or application definition are overridden by WAIT and DELAY clauses in a menu definition.

Example

DELAY; 
      

ACMS waits 3 seconds before clearing the final screen of the task and returning the user to a menu.

Describes the actions to be taken to recover from one or more exceptions.

Format

EXCEPTION HANDLER ACTION IS <action-clause> ... ;

Parameters

action-clause

Describes the actions taken to recover from an exception raised in the same step or in a step within the block step. Section 3.8 explains action clauses.

Clause Default

The EXCEPTION HANDLER clause is optional. If you do not include the EXCEPTION HANDLER clause in the task definition, and an exception is raised, ACMS cancels the task.

Notes

If you specify the EXCEPTION HANDLER clause, it must appear after the work part of the step and the action part of the step. The action part of the step is optional.

You can include the following types of action clauses: workspace manipulation, server context, and task sequencing. At a minimum, you must include a task sequencing action clause because ACMS does not provide a default sequencing action for the exception handler action part of a step. You cannot specify transaction action clauses.

As in the action part of a step, you can use conditional clauses in the exception handler action part of a step.

Regardless of the order in which you specify the action clauses, ACMS executes them in the following order:

1. Workspace manipulation
2. Server context
3. Task sequencing

When an exception is raised, ACMS interrupts the task execution, and searches for an exception handler on the step in which the exception was raised. If the current step does not contain an exception handler, ACMS searches the outer block steps, beginning with the nearest block step and heading towards the root block step. After ACMS finds an exception handler, it stores the exception code in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS system workspace.

If ACMS does not find an exception handler, it cancels the task. If ACMS finds an exception handler, but the exception handler does not specify the particular exception code raised, ACMS raises another step exception and searches outer block steps for another exception handler.

For more information on exception handling, see Compaq ACMS for OpenVMS Writing Applications.

Example

EXCHANGE 
   RECEIVE ORDER_LINE_RECORD IN ORDER_FORM 
      RECEIVING ORDER_LINE_RECORD 
         WITH TIMEOUT 42; 
EXCEPTION ACTION IS 
   IF (ACMS$L_STATUS = FORMS$_TIMEOUT) 
   THEN 
      GOTO STEP HANDLE_FORM_TIMEOUT; 
   ELSE 
      CANCEL TASK RETURNING ACMS$L_STATUS; 
   END IF; 
      

The exchange step specifies that the terminal operator must complete the DECforms panel within 42 seconds; otherwise, DECforms raises a timeout exception. The exception handler action part of the step tests for the FORMS$_TIMEOUT exception code in the ACMS$L_STATUS workspace field. If DECforms raises the timeout exception, ACMS passes control to the HANDLE_FORM_TIMEOUT step. If any other exception is raised, ACMS cancels the task.

Describes the interaction between the application and the terminal user.

Format

Parameters

exchange-clause

Describes the work done in an exchange step. Section 3.5 explains exchange step clauses.

action-clause

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

Clause Default

The EXCHANGE clause is optional. However, if your task uses FORM I/O, you must use an exchange step.

Example

DISPLAY_EMPLOYEES: 
  EXCHANGE 
    SEND FORM RECORD REVIEW_SCHEDULE_RECORD 
      SENDING REVIEW_SCHEDULE_WKSP; 
      

The DISPLAY_EMPLOYEES exchange step sends the REVIEW_SCHEDULE_WKSP workspace to a DECforms form.

Transfers control of the task to the action part of the block step or to the next block in the task definition.

Format

EXIT BLOCK ;

Clause Default

The EXIT BLOCK clause is optional. The default sequencing action for a step within a block is GOTO NEXT STEP. The default sequencing action for a block step or a processing step in a single-step task is EXIT TASK.

Note

If you use the EXIT BLOCK clause in the action part of an exchange or processing step, ACMS transfers control to the action part of the block. If you use the EXIT BLOCK clause in the action part of a block step, ACMS transfers control to the next block in the task definition.

Example

DISPLAY_EMPLOYEES: 
  EXCHANGE 
    SEND FORM RECORD REVIEW_SCHEDULE_RECORD 
      SENDING REVIEW_SCHEDULE_WKSP 
      WITH RECEIVE CONTROL TEST_WORKSPACE; 
    CONTROL FIELD IS TEST_WORKSPACE.TEST_KEY 
      " FMOR"   :  GOTO PREVIOUS PROCESSING; 
      " FCAN"   :  EXIT BLOCK; 
    END CONTROL FIELD;    
ACTION 
  REPEAT STEP; 
      

In the DISPLAY_EMPLOYEES exchange step, DECforms uses the form record REVIEW_SCHEDULE_RECORD to display a panel to the user. If the user presses a key that returns a value " FMOR" to the TEST_KEY field of TEST_WORKSPACE, ACMS processes the previous processing step. If the user presses a key that returns a value " FCAN" to the TEST_KEY field, ACMS exits the block and returns control to the action part of the block step. Because the REPEAT STEP clause is in the action part of the block step, ACMS repeats the task.

Ends the current task.

Format

Parameters

message-number

A number identifying a user-defined status value to be displayed when a task ends.

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 accessible by the task group associated with the task. The workspace containing this field must be named in either the WORKSPACES or the USE WORKSPACES clause in the task definition.

global-symbol

A valid global symbol identifying a status value to be displayed when a task ends. 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 EXIT TASK clause is optional. The default sequencing action for a step within a block is GOTO NEXT STEP. The default sequencing action for a block step or a processing step in a single-step task is EXIT TASK.

Notes

When you use the EXIT TASK clause, the default recovery action is COMMIT IF ACTIVE RECOVERY UNIT, and the default context action is RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT.

Because a distributed transaction must end in the action part of the step on which it starts, you cannot specify EXIT TASK on the action part of a step within a distributed transaction.

If you use the EXIT TASK clause, you cannot declare the following clauses in the same action specification:

• RETAIN RECOVERY UNIT
• RETAIN RECOVERY UNIT IF ACTIVE RECOVERY UNIT
• RETAIN SERVER CONTEXT
• RETAIN SERVER CONTEXT IF ACTIVE SERVER CONTEXT

A task, whether called from an agent or another task, can end by exiting normally or by canceling itself. The task can return a default ACMS task status code or a user-specific status code. If you specify a return status with the EXIT TASK clause, it must be a success status.

ACMS commits a distributed transaction if you do not specify an explicit transaction action, and returns the final status value to the parent task or agent, with the contents of any workspaces that are defined as TASK ARGUMENTS with MODIFY or WRITE access.

Example

DISPLAY_EMPLOYEES: 
  EXCHANGE 
    SEND FORM RECORD REVIEW_SCHEDULE_RECORD 
      SENDING REVIEW_SCHEDULE_WKSP 
      WITH RECEIVE CONTROL TEST_WORKSPACE; 
    CONTROL FIELD IS TEST_WORKSPACE.TEST_KEY 
      " FMOR"   :  GOTO PREVIOUS PROCESSING; 
      " FEXT"   :  EXIT TASK RETURNING ACMS$_NORMAL; 
    END CONTROL FIELD;    
      

If the user presses a key that returns the value " FCAN" to the TEST_KEY field of the workspace TEST_WORKSPACE, ACMS exits the task normally without returning control to the action part of the block step definition.

Specifies that the exchange steps in a block step use DECforms to interface with the terminal user.

Format

FORM I/O

Phrase Default

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

Notes

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

If a block step uses FORM I/O, processing steps in that block step can use TERMINAL I/O to do work. However, you cannot distribute a task that does any I/O in a processing step.

If a block step uses FORM I/O, exchange steps in that block step cannot use the REQUEST, READ, or WRITE clauses to do work.

Example

BLOCK WITH FORM I/O 
      

The exchange steps in this block step use DECforms to interface with the terminal user.

Uses the OpenVMS message facility to translate a message number into a message and move that message from a message file to a workspace field. An exchange step can then display this message on the terminal screen for the terminal user. You normally use this clause to translate the return status of the last procedure into a message.

Format

Parameters

message-number

A decimal number that references a message in one of the message files declared in the task group definition. If you do not use the message-number parameter, the numeric-workspace-field parameter, or the global-symbol parameter, ACMS uses the value stored in the ACMS$PROCESSING_STATUS workspace to retrieve an error message from a message file.

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 accessible by the task group associated with the task. The workspace containing this field must be named in either the WORKSPACES or the USE WORKSPACES clause in the task definition.

global-symbol

A valid global symbol identifying a status value to be displayed. 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.

A global symbol can be resolved from a task group message file only if the .OBJ message file is specified or is part of a user-specified object library or shared image library. The object library or shared image library must be specified on the /OBJECT or /USERLIBRARY qualifiers of the BUILD GROUP command.

workspace-string-field

A string field where ACMS stores the error message after it is retrieved from an error message file. If you do not use this parameter, ACMS defaults to storing the message in the ACMS$T_STATUS_MESSAGE_LONG field of the ACMS$PROCESSING_STATUS system workspace.

Clause Default

The GET ERROR MESSAGE clause is optional. If you do not use the GET ERROR MESSAGE clause, ACMS does not move a message from a message file to a field in a workspace.

Notes

You can use the GET ERROR MESSAGE clause only in the action sections of steps within a block.

The message must be in one of the message files available to the task. These message files include:

• OpenVMS error message files
• ACMS run-time error message files
• Message files named in the task group definition

To get the message number of the message you want to return to the user, get a listing of the message file that the task uses. To get this listing, use the DCL MESSAGE command with the /LIST qualifier:

$ MESSAGE/LIST=DEPTMSG.LIS DEPT.MSG

The file you supply with the MESSAGE/LIST command is the source message file with an .MSG file type. You can name the file to which you want to output the message listing file. In this example, the name of the source message file is DEPT.MSG, and the name of the output listing file is DEPTMSG.LIS. If you do not name a listing file, the name of that file is derived from the name of the source message file.

Look at the listing file to find the hexadecimal code for the message you want to return to the user. Convert the hexadecimal code for the message to a decimal value, and use that decimal code in the GET ERROR MESSAGE clause.

Example

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; 
                   GOTO PREVIOUS EXCHANGE; 
    END CONTROL FIELD; 
      

If the REVIEW_SCHEDULE returns a status code with an error severity level of WARNING, ERROR, or FATAL, ACMS stores the value "B" in the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS workspace. In addition, ACMS uses the returned status code to retrieve a message from a message file. ACMS repeats the previous exchange, which should use a form that displays the retrieved error message.

Specifies that a task can be selected from a menu, called by an agent, or called by another task.

Format

GLOBAL ;

Clause Default

The GLOBAL clause is optional.

If no GLOBAL or LOCAL clause is specified in a task definition, ACMS uses the default application definition GLOBAL or LOCAL attribute that is in effect when the application is built. If no GLOBAL or LOCAL attribute is specified in either the task definition or the application definition, a task is global by default and can be selected from a menu, called by an agent, or called by another task.

Example

REPLACE TASK MENU_TASK 
NOT CANCELABLE; 
GLOBAL; 
WORKSPACE IS WORK_RECORD, PERS_RECORD; 
BLOCK WORK 
    PROCESSING 
        CALL PROCEDURE DISPLAY IN DISPLAY_SERVER; 
    EXCHANGE 
        READ WORK_RECORD; 
 
    PROCESSING 
        WITH CONTINUE ON BAD STATUS 
        IS 
        SELECT FIRST TRUE 
        ( WORK_RECORD.WK_NUMBER EQ 1): 
            CALL TASK ADD_EMPLOYEE; 
        ( WORK_RECORD.WK_NUMBER EQ 2): 
            CALL TASK REVIEW_UPDATE; 
        ( WORK_RECORD.WK_NUMBER EQ 3): 
            CALL TASK GET_EMPLOYEE USING WORK_RECORD, PERS_RECORD; 
        ( WORK_RECORD.WK_NUMBER EQ 4): 
            NO PROCESSING; 
        NOMATCH: 
            NO PROCESSING; 
         END SELECT ; 
      ACTION IS 
        MOVE RMS$_EOF INTO WORK_RECORD.WK_NUMBER, 
             -1 INTO WORK_RECORD.WK_NUMBER; 
END BLOCK WORK; 
 
    ACTION IS 
      SELECT FIRST TRUE OF 
        ( WORK_RECORD.WK_NUMBER NE 4): 
            REPEAT STEP; 
        ( WORK_RECORD.WK_NUMBER EQ 4): 
            EXIT TASK; 
        NOMATCH: 
            REPEAT TASK; 
         END SELECT ; 
END DEFINITION; 
      

In this example, the task definition for MENU_TASK includes a GLOBAL clause. Regardless of any LOCAL or GLOBAL task default in effect when an application using MENU_TASK is built, MENU_TASK is global and can be selected from a menu, called by an agent, or called by another task.