There are three ways to invoke ADU. Two methods use startup qualifiers; the third allows you to enter the utility only in default mode. After invoking the utility, ACMS displays the ADU> prompt.

Table 1.1, ''Startup Qualifiers and Their Functions'' lists the startup command qualifiers and their functions. Use these qualifiers when invoking ADU with the MCR command or a foreign command.

$ DEFINE ADU$EDIT MYDISK$:[MYDIRECT]ADUEDIT.COM

This command assigns the logical name ADU$EDIT to the ADUEDIT.COM command file in the directory MYDIRECT on the device MYDISK$. Including this command in your LOGIN.COM file defines in the ADUEDIT.COM the editor you want. If the ADUEDIT.COM file is not in your default directory, be sure to include the disk and directory specification.

$ ASSIGN/USER 'F$LOGICAL("SYS$OUTPUT")' SYS$INPUT
$ IF P1 .EQS. "" THEN GOTO INPUT
$ EDIT/TPU/SECTION=EDTSECINI/OUTPUT='P2' 'P1'
$ EXIT
$ NOINPUT:
$ EDIT/TPU/SECTION=EDTSECINI 'P2'

The third and last lines of this command procedure name TPU with the EDT interface as the editing environment. You can change these lines to name any other OpenVMS editor you want to use. See Section 1.6.10, ''Using the Language-Sensitive Editor to Create Definition Files'' for information on using the Language-Sensitive Editor (LSE).

For information on DCL commands, see VSI OpenVMS DCL Dictionary: A–M. VSI OpenVMS User's Manual has information on writing command and startup procedures.

Every dictionary definition has a path name that uniquely identifies it. The naming conventions for DMU and CDO differ only in their specification of the dictionary origin.

CDD$TOP.AVERTZ.CUSTOMERS.RESERVATION_TASK

DISK1:[CDDPLUS]AVERTZ.CUSTOMERS.RESERVATION_TASK

DISK1:[CDDPLUS] is the anchor. RESERVATION_TASK is the entity in the CUSTOMERS directory, which is located in the AVERTZ directory.

A CDD name can consist of given names containing a maximum of 31 characters. Characters can include the letters A through Z, digits 0 through 9, underscores (_), and dollar signs ($). The first character of each given name must be a letter. The last character can be either a letter or a digit. All lowercase letters are translated to uppercase.

Identify a dictionary object with a full or relative path name. If a default dictionary directory exists, use a relative path name. Relative path names include the portion of the path name that is not part of the default dictionary definition.

$ DEFINE CDD$DEFAULT DISK1:[CDDPLUS]AVERTZ.CUSTOMERS

With AVERTZ.CUSTOMERS as the default dictionary directory, the relative path name is simply the object name itself: RESERVATION_TASK. If the default directory is [CDDPLUS], the relative dictionary path name is AVERTZ.CUSTOMERS.RESERVATION_TASK.

In DMU, you can assign a password to each dictionary directory, subdirectory, and object in a path name. You cannot assign passwords to CDO entities. When specifying the path name, put the password in parentheses and attach it to the end of the given name to which it applies.

Passwords can contain a maximum of 64 printable ASCII characters, including spaces and tabs. Eight-bit characters from the DEC Multinational Character Set can also be used in passwords. Full support for the 8-bit character set requires software and hardware support. For instance, the display terminal and printer used must both support the 8-bit character set. Lowercase letters are translated to uppercase. The only printable characters you cannot include in path name passwords are parentheses, either left or right, and periods.

JONES(ACMSPASS)
 
SMITH(CAPT JOHN)

CDD$TOP.PERSONNEL.MENU(ACMSPASS).MENU_WORK

You can also specify CDD dictionary specifications for ACMS workspaces. These workspace specifications are stored in the CDD dictionary.

OpenVMS logical names may be used in all or part of a path name. For example, if you define PERSONNEL_CDD as DISK1:[CDDPLUS]PERSONNEL, you can use PERSONNEL_CDD.MENU as a path name.

For more information on CDD path names, see the appropriate CDD documentation.

Before you create a new ACMS definition or replace an existing one that is in DMU format, you must first create a CDO directory in which to store the dictionary entity. This practice contrasts with the DMU behavior, in which the creation of a dictionary object also created the dictionary directory, if one did not exist. ADU returns an error if you attempt to create an entity in a CDO directory that does not exist.

The ACMS default protection scheme uses the logical name ACMS$ADU_ACL_DEFAULT. Define this process logical to point to an access control list (ACL) file specification.

(IDENTIFIER=[ACMS,RICK],ACCESS=READ+WRITE+MODIFY+ERASE+SHOW+DEFINE+CHANGE+
             DELETE+CONTROL+OPERATOR+ADMINISTRATOR)
(IDENTIFIER=[ACMS,HEINZ],ACCESS=READ+WRITE+DELETE)
(IDENTIFIER=[*,*],ACCESS=READ+WRITE+MODIFY+ERASE+SHOW+OPERATOR+ADMINISTRATOR)

Access is determined by the first ACE encountered that applies to the creator of the entity. See the CDD documentation and OpenVMS Systems Services documentation for more information about ACLs for dictionary entities.

When creating an identifier, do not use the ACMS reserved words ARE, IS, USING, or WITH. In addition, some commands or clauses have special restrictions for identifiers, such as whether the identifier must be unique within a definition. These restrictions are included with the description of the command or clause.

Identifier is also an OpenVMS term used to describe a special name that a user is allowed to hold. Some identifiers represent the user names and user identification codes (UICs). Others are more general names that a group of users holds. During login, OpenVMS identifiers are copied into a rights list that becomes part of the OpenVMS process. Access control lists (ACLs) associate identifiers with the type of access to be granted or denied to a system object such as a file or logical name table. The application definition ACCESS clause uses ACLs to grant and deny access to ACMS tasks. For more information about OpenVMS identifiers see the OpenVMS documentation set.

node"access-string"::device-name:[directory-spec]file-name.file-type;version-number

See VSI OpenVMS DCL Dictionary: A–M for information about file specification defaults and default file types.

You refer to a workspace field name by specifying a sequence of identifiers which are separated by periods. A full workspace field name consists of the workspace name followed by the structure names and ending with the name of the elementary data item. Refer to the CDD documentation for more information on structure names.

DEFINE RECORD SALARY_RECORD.
SALARY STRUCTURE.
     EMPLOYEE_ID.
     PAY STRUCTURE.
         JOB_CLASS.
         WEEKLY_PAY.
     END PAY STRUCTURE.
END SALARY STRUCTURE.
END SALARY_RECORD RECORD.

To include quotation marks in a string that is enclosed by the same quotation mark (either single or double), use two quotation marks; for example, "a text string" "with" " embedded quotation marks".

HEADER "                    ACMS",
        "          EMPLOYEE SAMPLE APPLICATION";

The TEXT subclause in the menu definition also uses text strings.

PROCESSING WITH
     SQL RECOVERY "SET TRANSACTION READ WRITE " &
                      "RESERVING DEPART, ADMIN FOR PROTECTED WRITE"

BLOCK WITH SQL RECOVERY
     "SET TRANSACTION READ WRITE RESERVING"   &
          "EMPLOYEES FOR SHARED READ,"          &
          "SALARY_HISTORY FOR SHARED WRITE,"    &
          "JOBS FOR EXCLUSIVE WRITE"

BLOCK WITH SQL RECOVERY
     "SET TRANSACTION READ WRITE RESERVING "   &
          "EMPLOYEES FOR SHARED READ, "          &
          "SALARY_HISTORY FOR SHARED WRITE, "    &
          "JOBS FOR EXCLUSIVE WRITE"

The new version translates to "SET TRANSACTION READ WRITE RESERVING EMPLOYEES FOR SHARED READ, SALARY_HISTORY FOR SHARED WRITE, sJOBS FOR EXCLUSIVE WRITE". Rdb can now interpret the example correctly.

To create ADU definition files, use an OpenVMS text editor (for example, EDT, TPU, or the Language-Sensitive Editor) to enter the definition clauses. At the end of each definition, include the END DEFINITION clause. Use a semicolon (;) to mark the end of each clause. Indent the clauses to make it easy to understand the code. Use an exclamation mark (!) to introduce comments.

! Title for the menu
HEADER IS   "                    REVIEW MENU";
! User Selections
ENTRIES ARE
   HISTORY  : TASK IS REVIEW_HISTORY IN PERSONNEL;
              TEXT IS "Display Review Histories";
   SCHEDULE : TASK IS REVIEW_SCHEDULE IN PERSONNEL;
              TEXT IS "Display Review Schedules";
END ENTRIES;
END DEFINITION;

After creating a definition, process the file with the BUILD command. Figure 1.2, ''The Review Menu'' shows how the menu appears on the terminal screen after the definition file has been built.

ADU> CREATE GROUP CUSTOMERS_GROUP CUSTOMERS.GDF/LIST=CUSTOMERS

ADU> REPLACE GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP CUSTOMERS.GDF

To continue an ADU command on a second line, use the hyphen (-) as the continuation character just for DCL commands. You can abbreviate keywords, such as GROUP, according to the DCL convention.

REPLACE GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP
SERVER IS
   CUSTOMER_SERVER : DCL PROCESS;
END SERVER;
TASKS ARE
   ADD  : PROCESSING IS IMAGE IS "SYS$SAMPLE:CUSTOMERS.EXE";
   DATR : PROCESSING IS DCL COMMAND IS "$MCR DTR32";
END TASKS;
END DEFINITION;

Use the REPLACE command to store in the dictionary a definition that does not already exist or to replace one that does. The CREATE command processes only definitions for which no dictionary location exists. Using the REPLACE command saves you from having to change the CREATE command to REPLACE when you change a definition and process it again.

ADU> @CUSTOMERS.GDF

After using the CREATE or REPLACE command to create a CDD entity for an ACMS definition, you use the ADU BUILD command to build a binary database of each ACMS task group, application, and menu definition for use by ACMS at run time.

ADU> BUILD GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP CUSTOMERS.TDB

If the BUILD command detects any errors, you can correct them in the definition source file. You must process the revised definition before you reissue the BUILD command to create the database file. Use the REPLACE command to process and store the revised definition in the same CDD location. If the revised definition has no errors, the REPLACE command replaces the old definition with the new version.

You process application and menu definitions the same way as task group definitions. Use the CREATE and REPLACE commands with task definitions, but not the BUILD command. Task definitions are not built; they are included in task group files (.TDBs) when task groups are built.

A number of ADU commands include a definition component type as a keyword. These commands include: BUILD, COPY, CREATE, DELETE, LIST, MODIFY, and REPLACE. The definition component keywords are APPLICATION, GROUP, MENU, and TASK.

ADU> BUILD GROUP /LOG DISK1:[CDDPLUS]PERSONNEL -
ADU>_ PERSONNEL.TDB

ADU> BUILD GROUP DISK1:[CDDPLUS]PERSONNEL /LOG -
ADU>_ PERSONNEL.TDB /PRINT

ADU commands can have a maximum of 256 characters. However, only 132 characters can be on a single line. When entering commands interactively, use the command continuation character, the hyphen (-), to enter long commands on several lines. Of course, you do not have to wait until you have entered 132 characters on a line before making a break. Break your command at any convenient place.

When you reach the point for a break on the command line, enter a hyphen and then press Return. ADU responds with the continuation prompt, ADU>_. Now continue typing the command line.

ADU> BUILD MENU -
DISK1:[CDDPLUS]DALLAS.PERSONNEL.EMPLOYEE_MENU-
ADU>_ MENU.MDB-
ADU>_ /LOG-
ADU>_ /LIST=MENU_DATABASE_BUILD.LIST

It is convenient to enter the command qualifiers last, with each one on a separate line, as shown in the previous example.

Note that ACMS concatenates to the contents of the previous line whatever you type in response to the continuation prompt. If elements need to be separated with spaces, always include those spaces at the beginning of the next line. In the preceding example, it was necessary to include a space before the name of the menu database file MENU.MDB. No spaces were needed before the /LOG and /LIST qualifiers, although inserting spaces before them is permissible. Be sure to insert spaces wherever the syntax requires them.

ADU> BUILD Return
Component_type   :

You can enter the component type and the dictionary path name in response to this prompt, as well as include a database file specification and any desired qualifiers. When you press Return after entering the component type, ADU supplies prompts for the dictionary path name.

ADU does not prompt you for the database file specification or for any qualifiers. These elements are not required. Enter the optional elements when responding to a prompt for a required element.

The ADU SPAWN command works the same way as the DCL SPAWN command. It allows you to temporarily leave ADU to do other work and then return to the same place. The SPAWN command creates a subprocess and attaches the terminal to it. You can then issue other commands to do such things as invoke DCL commands, get information about dictionary objects, or check how something works in DECforms or DATATRIEVE. When you finish that work, you need to log out of the subprocess or use the ADU ATTACH command to return to your ADU session. The ADU ATTACH command allows you to switch control of your terminal back and forth to previously created processes.

ADU> SPAWN
%DCL-S-SPAWNED, process VIV_1 spawned

If you include a command on the line with SPAWN, that command is executed and you return to your ADU session. By including the /NOWAIT qualifier with the SPAWN command, you return to your ADU session immediately. You can resume your ADU session while the subprocess session processes your command.

For more details, see the descriptions of the SPAWN and ATTACH commands in this manual.

ADU> CREATE GROUP CUSTOMERS
ADUDFN>

At this prompt, you enter definition clauses, line by line. After entering a clause or part of a clause, you press Return again to display the ADUDFN> prompt. As you write the definition, ADU checks each definition clause and displays error messages as it finds them, although ADU might not display an error message until several lines after the line causing the error.

If you write a definition that has errors in it, ADU does not create that definition in the CDD. It does, however, store the definition so that you can edit it with the ADU EDIT command. You can also get a copy of the incorrect definition if you enable the logging facility. Logging saves all output that ADU sends to your terminal and keeps a copy of all commands and definitions you enter during one run of the utility. The log file lets you see the definition or definitions you wrote and lets you make changes to them. As a result of the structure of the log file, you can also use the at sign (@) to process with ADU any definitions included in the log file.

ADU> SET LOG AUG18.LOG

In this example, ADU uses the log file, AUG18.LOG. If you do not specify a device or directory, ADU creates the file in your default directory. If you omit the file specification, ADU creates the file ADULOG.LOG on your default device and in your default directory. You can create an ADUINI.COM file that includes the SET LOG command. This enables logging every time you start ADU.

In addition to using SET LOG to save definitions that have errors, you can use the EDIT or SAVE command after you finish writing the definition.

ADU displays errors automatically when you are creating definitions interactively. During processing, use the SET VERIFY command. This command lets you see where errors are occurring and thus lets you correct them more easily. You can put the SET VERIFY command in the ADUINI.COM file to have ADU keep track of errors automatically during processing.

Refer to the VSI ACMS for OpenVMS ADU Reference Manual for information about these commands.

The Language-Sensitive Editor (LSE) contains five templates used for creating ADU definitions. These templates are especially helpful if you are unfamiliar with ADU syntax or cannot recall the exact definition clause syntax needed. The templates cover all four types of ADU definitions, and they contain online help about ADU phrases and clauses, plus optional diagnostics files. To use LSE, the Language-Sensitive Editor software must be installed on your system.

The ACMS LSE templates supply syntax keywords for inserting directly into the definition file you are creating. After you select the keyword, LSE prompts you for the required parameters. Use the templates to choose syntax paths and to expand subclause entries until they are complete.

LSE generates messages that explain syntax errors in the ADU definitions. When you use the /DIAGNOSTICS qualifier with the ADU CREATE, MODIFY, or REPLACE command, ADU outputs these messages to a file that you can review by using the LSE REVIEW command. ACMS lets you use the LSE COMPILE command from within an LSE editing session to create, modify, or replace a task, task group, application, or menu definition. See Appendix D, "Using LSE with ACMS" for information on using the COMPILE command.

$ LSEDIT UPDATE_TASK.TDF

$ ASSIGN/USER 'F$LOGICAL("SYS$OUTPUT")' SYS$INPUT
$ IF P1 .EQS. "" THEN GOTO NOINPUT
$ EDIT /OUTPUT ='P2' 'P1'
$ EXIT
$ NOINPUT:
$ EDIT 'P2'

$ ASSIGN/USER 'F$LOGICAL("SYS$OUTPUT")' SYS$INPUT
$ IF P1 .EQS. "" THEN GOTO NOINPUT
$ LSEDIT /LANGUAGE=ACMSADU /OUTPUT ='P2' 'P1'
$ EXIT
$ NOINPUT:
$ LSEDIT /LANGUAGE=ACMSADU 'P2'

See Appendix D, "Using LSE with ACMS" and VSI DECset for OpenVMS Language-Sensitive Editor/Source Code Analyzer Reference Manual for more information on using LSE. VSI ACMS Version 5.0 for OpenVMS Installation Guide contains information on installing ACMS with the LSE option.

A workspace is a buffer that the task uses to store information and pass information between steps. Every workspace has a record definition, created by using the Common Dictionary Operator (CDO), that describes the workspace layout. The CDD documentation explains how to use the CDO. In the Add Car Reservation task, you need a workspace to pass the new car rental information from ADD_RESERVE_FORM_REC to the WRITE_RESERVE_PROC procedure. Figure 2.2, ''The Workspace Used to Pass Information'' shows how the form and the procedure use the workspace to pass information.

Definition of record ADD_RESERVE_WKSP
|   Contains field          CUST_NUMBER
|   |  Datatype                 signed longword
|   Contains field          CUST_NAME
|   |  Datatype                 text size is 30 characters
|   Contains field          CUST_STREET_ADDRESS
|   |  Datatype                 text size is 30 characters
|   Contains field          CUST_CITY
|   |  Datatype                 text size is 20 characters
|   Contains field          CUST_STATE
|   |  Datatype                 text size is 2 characters
|   Contains field          CUST_ZIP
|   |  Datatype                 text size is 5 characters
|   Contains field          CUST_PHONE
|   |  Datatype                 text size is 10 characters
|   Contains field          CAR_TYPE
|   |  Datatype                 text size is 3 characters
|   Contains field          RENTAL_DATE
|   |  Datatype                 text size is 6 characters
|   Contains field          RETURN_DATE
|   |  Datatype                 text size is 6 characters

COPY
   DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.ADD_RESERVE_WKSP 
         FROM DICTIONARY
END COPY

A workspace name can be different from the name of the record in the record definition for that workspace. For example, the record name in Example 2.1, ''Definition of ADD_RESERVE_WKSP Fields'' does not have to be ADD_RESERVE_WKSP. See the VSI ACMS for OpenVMS ADU Reference Manual for more information on workspace names and resolution of workspace field names.

Because both the exchange step and the processing step use the ADD_RESERVE_WKSP workspace, you must include the workspace name in both the TRANSCEIVE and PROCEDURE clauses in the task definition.

The definition for the record layout of a workspace is stored in the CDD dictionary. When you first declare a workspace in a task definition, you must use the CDD path name of the record definition for that workspace. When referring to the workspace from within the definition, you use the given name or unique name of the workspace specified by the WORKSPACES ARE clause.

GET_RENTAL_INFORMATION:
   EXCHANGE
     TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC
      SENDING ADD_RESERVE_WKSP
      RECEIVING ADD_RESERVE_WKSP;
WRITE_RESERVATION_INFORMATION:
   PROCESSING
     CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
      USING ADD_RESERVE_WKSP; 
END BLOCK WORK;

This definition assigns the ADD_RESERVE_WKSP workspace for use by both the form and the procedure. The definition of the form record ADD_RESERVE_FORM_REC must correspond with the record definition of the ADD_RESERVE_WKSP workspace.

WORKSPACE IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.ADD_RESERVE_WKSP
   WITH NAME ADD_RESERVE_WKSP_1;

GET_RENTAL_INFORMATION:
   EXCHANGE
     TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC
      SENDING ADD_RESERVE_WKSP_1
      RECEIVING ADD_RESERVE_WKSP_1;
WRITE_RESERVATION_INFORMATION:
   PROCESSING
     CALL WRITE_RESERVE_PROC IN RESERVE_SERVER USING ADD_RESERVE_WKSP_1;
END BLOCK WORK;

The USING keyword names the workspace or workspaces that you want the form and the procedure to use.

Chapter 8, "Handling Task Execution Errors" describes how to use exception handlers.

In the attributes part of the block step, you must indicate that the task uses DECforms to interface with the terminal by adding the keywords FORM I/O to the definition.

BLOCK WORK
   WITH FORM I/O
   GET_RENTAL_INFORMATION:
     EXCHANGE
       TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC
        SENDING ADD_RESERVE_WKSP
        RECEIVING ADD_RESERVE_WKSP;
   WRITE_RESERVATION_INFORMATION:
     PROCESSING
       CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
        USING ADD_RESERVE_WKSP; 
   END BLOCK WORK;

You use the BLOCK clause to start the work for the task. The END BLOCK WORK keywords indicate the end of that work. Include a semicolon (;) after the END BLOCK WORK keywords.

A task definition must also describe the task characteristics. You use the task part of a definition to set up characteristics for the block step and for steps within the block step.

The most important characteristic of a simple data entry task is the workspace or workspaces used by the steps in the task. You use the WORKSPACES clause to name the workspace or workspaces used by the steps in the task. You must use the CDD path name of the record description for each workspace you name. The CDD given names of the path names you declare must match the given names of the workspaces referred to by the TRANSCEIVE and CALL clauses in the task definition.

WORKSPACE IS DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.ADD_RESERVE_WKSP;

WORKSPACE IS ADD_RESERVE_WKSP;

If many programmers are working on a project, you might want to use the full path name, rather than the given name, because different programmers might use different CDD defaults.

WORKSPACE IS ADD_RESERVE_WKSP;
 BLOCK
   WORK WITH FORM I/O 
   GET_RENTAL_INFORMATION:
     EXCHANGE
       TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC
        SENDING ADD_RESERVE_WKSP
        RECEIVING ADD_RESERVE_WKSP;  
   WRITE_RESERVATION_INFORMATION;
     PROCESSING
       CALL WRITE_RESERVE_PROC IN RESERVE_SERVER USING ADD_RESERVE_WKSP;
   END BLOCK WORK;
END DEFINITION;

You must end every definition with the END DEFINITION keywords and a semicolon (;).

WORKSPACE IS ADD_RESERVE_WKSP WITH NAME ADD;

Use the WITH NAME keyword carefully. In general, if you need to use the same record definition, under different names, in multiple parts of your application, it is easier to maintain the application if you assign unique workspace names than if you use WITH NAME.

Once you have written the task definition, you can use either the ADU CREATE or ADU REPLACE command to store that definition in the dictionary.

ADU>CREATE TASK ADD_CAR_RESERVATION_TASK ADDCAR.TDF

This CREATE command processes the definition in the file ADDCAR.TDF. If there are no errors in the definition, ADU stores it in the dictionary in the default directory defined by CDD$DEFAULT.

You can insert the REPLACE command at the beginning of the source definition file and submit it to ADU as a command file. When you submit definitions as command files, use the REPLACE command rather than the CREATE command to save yourself the effort of changing the command when you resubmit the file to ADU.

SET VERIFY
REPLACE TASK ADD_CAR_RESERVATION_TASK
   WORKSPACE IS ADD_RESERVE_WKSP;
   BLOCK
     WORK WITH FORM I/O
 
   GET_RENTAL_INFORMATION:
     EXCHANGE
       TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC
        SENDING ADD_RESERVE_WKSP
        RECEIVING ADD_RESERVE_WKSP;
   WRITE_RESERVATION_INFORMATION:
     PROCESSING
       CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
        USING ADD_RESERVE_WKSP; 
   END BLOCK WORK;
END DEFINITION;

You can include the SET VERIFY command with a source definition you are submitting as a command file. This command displays each line of the definition as it is processed by ADU, letting you see where errors in the definition occur.

ADU>@ADDCAR.COM

So far, the sample task definition does not handle two considerations that you want to address when solving most business problems: handling processing errors and making the task easy to use.

Once you have broken the problem down into these parts, you can begin putting together the definition. To handle errors that might occur in the processing step, you might need to add another exchange step to the task definition. To handle errors and special conditions in both the exchange and processing steps, you also might need to increase the number of workspaces and change some task characteristics.

2.2.5.1. Using ACMS Workspaces

When you want to handle errors in a task, you test the contents of a field in a workspace and take action based on the contents. For example, a procedure can return a value to a field in a workspace. You can use the CONTROL FIELD clause to test the contents of that field. Then you use action clauses to take action based on those contents. In addition to the CONTROL FIELD clause, ACMS provides three other conditional clauses for testing workspace fields:

• IF THEN ELSE

• SELECT FIRST

• WHILE DO

The CONTROL FIELD clause can test the contents of a control field in either of two workspaces:

• An ACMS system workspace, especially ACMS$PROCESSING_STATUS

• A workspace you define

You can use any of the ACMS system workspaces with a conditional clause. However, the ACMS$PROCESSING_STATUS system workspace is especially useful for handling results of procedures in processing steps. Workspaces you define are especially useful for handling information passed to a form.

There are three ACMS system workspaces; each workspace handles a different kind of information. The VSI ACMS for OpenVMS ADU Reference Manual lists all the system workspaces and gives a brief description of each.

The first exchange step in the Add Car Reservation task uses the CONTROL FIELD clause to test a workspace that you define, while the processing step uses the IF THEN ELSE clause to test a system workspace field.

The ACMS$PROCESSING_STATUS system workspace has four fields:

• ACMS$L_STATUS

• ACMS$T_SEVERITY_LEVEL

• ACMS$T_STATUS_TYPE

• ACMS$T_STATUS_MESSAGE_LONG or ACMS$T_STATUS_MESSAGE

All processing work returns a final status value. For example, when a procedure exits, ACMS places its return status in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS workspace. ACMS translates that value and performs the following operations:

1. Stores in the ACMS$T_SEVERITY_LEVEL field a single character string indicating the severity level of the error. These characters are:
   

   • S – SUCCESS

   • I – INFORMATION

   • W – WARNING

   • E – ERROR

   • F – FATAL

   If the error returned by the procedure does not match any of these error severities, ACMS stores a question mark (?) in the ACMS$T_SEVERITY_LEVEL field.

2. Stores in the ACMS$T_STATUS_TYPE field a single character string indicating whether the severity level of the error is good or bad. These characters are:
   

   • G – GOOD

   • B – BAD

   If the severity level of the return status of the procedure is SUCCESS or INFORMATION, ACMS stores a G in the ACMS$T_STATUS_TYPE field. If the severity level is WARNING, ERROR, or FATAL, ACMS stores a B in that field.

ACMS can also use the return status value in the ACMS$L_STATUS field to get an error message from a message file. By default, it stores that message in the ACMS$T_STATUS_MESSAGE_LONG field. To retrieve the error message, you must use the GET ERROR MESSAGE clause, as explained later in this chapter.

Whether the conditional clause tests a field in a system workspace or in a workspace you define, the values it tests must be literal strings and the datatype of the field must be text. Table 2.2, ''Field and Values Tested by Conditional Clauses'' summarizes the fields and values that conditional clauses can test.

Workspace	Field	Value
User-defined	Any	Quoted string
ACMS$PROCESSING_STATUS	ACMS$T_SEVERITY_LEVEL	S,I,W,E,F,?
ACMS$PROCESSING_STATUS	ACMS$T_STATUS_TYPE	G,B

The initial value of the ACMS$T_SEVERITY_LEVEL workspace is S. The initial value of the ACMS$T_STATUS_TYPE field is G.

2.2.5.1.1. Using the CONTROL FIELD Clause in an Exchange Step

One special condition you want to allow for is letting the terminal user press a key to stop running the task. The form stores a value associated with that key in a workspace field. You can then use the CONTROL FIELD clause to test the contents of that field.

In the Add Car Reservation task, you want to let the user stop running the task when the form displays a panel asking for rental information. To do this, you need to define a key, such as the PF4 key, as the exit or quit key. DECforms refers to such a key as a function key. In your form definition, you must make the function declaration after the LAYOUT specification. In the following example, the function is PF4 and its name is QUIT_KEY.

FORM ADD_RESERVE_FORM
 .
 .
 .
   Layout VT_LAYOUT
       .
       .
       .
       Size 24 lines by 80 columns
 
       Function QUIT_KEY
           is %PF4
       End Function

You must also declare a function response in the IFDL source file. A function response alters the way DECforms processes the form. In this example, when the terminal user presses PF4, the function response directs DECforms to return the value "QUIT" to an ACMS workspace. Place the function response at the beginning of the panel declaration.

        Panel ADD_RESERVE_PANEL
            Function Response QUIT_KEY
                 Let QUIT_KEY = "QUIT"
                 Return Immediate
            End Response

For more information about declaring function responses, see VSI DECforms Guide to Developing an Application.

In your exchange step, you need to identify the workspace where DECforms stores the value "QUIT". In the example below, the QUIT_KEY field is in the QUIT_CTRL_WKSP workspace. The form record used for the receive part of the exchange is a record list. ADD_RESERVE_FORM_REC_LIS contains form records for ADD_RESERVE_WKSP and QUIT_CTRL_WKSP. Then, in the action part of the exchange step, you can use the CONTROL FIELD clause to test the workspace field. For example:

EXCHANGE
   TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, 
                          ADD_RESERVE_FORM_REC_LIS
    SENDING ADD_RESERVE_WKSP 
    RECEIVING ADD_RESERVE_WKSP, QUIT_CTRL_WKSP;
 ACTION IS
    CONTROL FIELD QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;

The CONTROL FIELD clause tests the QUIT_KEY field of QUIT_CTRL_WKSP. When you use the CONTROL FIELD clause, you can name the workspace and the workspace field, or just the workspace field. ACMS checks all of the workspaces defined for the task until it finds the field named in the CONTROL FIELD clause. However, including the workspace name is a good way to keep track of the location of information that the task uses. When you name the workspace in the CONTROL FIELD clause, use a period to separate it from the name of the control field.

If the value "QUIT" is in the QUIT_KEY field, ACMS exits or stops processing the task. Otherwise, ACMS goes on to process the next step in the definition. You must end each action clause, such as EXIT TASK, with a semicolon (;). End the CONTROL FIELD clause with the keywords END CONTROL FIELD and a semicolon (;).

When ACMS processes the EXIT TASK clause, it ends the task and returns the user to a selection menu without returning a message to the user. You can also use the CANCEL TASK clause to end a task. When ACMS processes the CANCEL TASK clause, it records the ending of the task as an abnormal ending or interruption, and returns a message to the user before returning the user to a selection menu.

In general, you use the EXIT TASK clause if the user wants to end the task and if there is no chance that data will be left in an inconsistent state. You use the CANCEL TASK clause if there is an abnormal reason for ending the task.

2.2.5.1.2. Using the IF THEN ELSE Clause in a Processing Step

Suppose the user does not cancel the task in the first step of the task but types information and presses Return or Enter. In this case, the processing step calls a procedure to write that information to a file. This procedure can encounter errors.

You want the task to take different actions depending on the kind of error encountered. There are two kinds of errors: recoverable errors and nonrecoverable errors. Recoverable errors are those a user can correct, such as typing the wrong customer number. Nonrecoverable errors are those a user cannot correct. For example, "file not found" is a nonrecoverable error in the Add Car Reservation task.

When a procedure encounters a recoverable error, you can tell the user about the error and let the user do something to correct the error. In the case of a nonrecoverable error, you generally want the procedure to cancel the task.

When a procedure runs, it returns a status value to ACMS. ACMS puts this value in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS system workspace. ACMS translates the return status value and stores, in the ACMS$T_SEVERITY_LEVEL field, a value indicating the severity level of the error. ACMS also stores in the ACMS$T_STATUS_TYPE field a GOOD or BAD value. You can use the IF THEN ELSE clause to test the contents of the ACMS$T_STATUS_TYPE field.

ACMS can also use the return status value in ACMS$L_STATUS field to retrieve an error message from a message file and then store that message in the ACMS$T_STATUS_MESSAGE field.

Suppose now that WRITE_RESERVE_PROC tries to write a reservation record to a file, but a record for that customer already exists. This is a recoverable error because the user can try a different customer number or enter information for a different customer. In this case, you want to tell the user about the error and let the user try again. Here is the processing step of the Add Car Reservation task:

PROCESSING
   CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
     USING ADD_RESERVE_WKSP;
   IF (ACMS$T_STATUS_TYPE EQ "B")
   THEN  GET ERROR MESSAGE;
         MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
         GOTO STEP ERROR_PROCESS_MSG; 
   ELSE  GOTO PREVIOUS EXCHANGE;
   END IF;

In this step, WRITE_RESERVE_PROC tries to write the information in the ADD_RESERVE_WKSP workspace to a file. It returns a status value to the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS workspace. ACMS translates that value and stores a B or G in the ACMS$T_STATUS_TYPE field. If the record already exists, the value in that field is a B.

The IF THEN ELSE clause tests a Boolean expression to determine which course of action to follow. You must enclose the Boolean expression within parentheses. See the VSI ACMS for OpenVMS ADU Reference Manual for more information about using Boolean expressions. If the Boolean expression evaluates to true, ACMS performs the actions associated with the THEN keyword. In this example, if the record already exists, ACMS performs the following steps:

1. Retrieves the error message from a message file

2. Stores the error message in the MESSAGE_PANEL field of the MSG_WKSP workspace

3. Goes to the ERROR_PROCESS_MSG exchange step in the task

To display the error message to the terminal user, you need to include the following exchange step in your task definition:

ERROR_PROCESS_MSG:
  EXCHANGE WORK
   SEND FORM RECORD MSG_FORM_REC
    SENDING MSG_WKSP;

This exchange step sends the error message stored in the MSG_WKSP workspace to the MSG_FORM_REC form record for display. The IFDL file for the ADD_RESERVE_FORM form must include the form record definition for MSG_FORM_REC.

If the Boolean expression evaluates to false, ACMS performs the actions associated with the ELSE keyword. In this example, the GOTO PREVIOUS EXCHANGE clause directs ACMS to repeat the task. You must end the IF THEN ELSE clause with the END IF keywords and a semicolon (;).

Figure 2.3, ''Retrieving Messages'' shows the process of retrieving and displaying error messages.

Although you can use action clauses in any order you want, ACMS always processes them in the same order. For example, ACMS always processes the GET ERROR MESSAGE clause before any sequencing clauses, such as GOTO PREVIOUS EXCHANGE.

For more information on returning status and using the system workspace ACMS$PROCESSING_STATUS, see VSI ACMS for OpenVMS Writing Server Procedures.

2.2.5.1.3. Additional Workspace Definitions

Because the error handling described in the preceding sections named new workspaces, you must enter these definitions into the dictionary. In the first exchange step, the CONTROL FIELD clause tests the QUIT_KEY field of the QUIT_CTRL_WKSP workspace.

In the processing step, the IF THEN ELSE clause uses an ACMS system workspace and the MSG_WKSP workspace. You do not need to do anything with the system workspace, but you have to enter the MSG_WKSP definition into the dictionary.

In your task definition, you must include QUIT_CTRL_WKSP and MSG_WKSP in the WORKSPACES clause.

REPLACE TASK ADD_CAR_RESERVATION_TASK
WORKSPACES ARE ADD_RESERVE_WKSP, QUIT_CTRL_WKSP, MSG_WKSP;
 
BLOCK WORK WITH FORM I/O IS
  
  GET_RENTAL_INFORMATION:
   EXCHANGE WORK IS
    TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, 
                           ADD_RESERVE_FORM_REC_LIS
     SENDING ADD_RESERVE_WKSP 
     RECEIVING ADD_RESERVE_WKSP, QUIT_CTRL_WKSP;
   ACTION IS
    CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;
 
  WRITE_RESERVATION_INFORMATION:
   PROCESSING WORK IS
    CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
    USING ADD_RESERVE_WKSP;
   ACTION IS
    IF (ACMS$T_STATUS_TYPE EQ "B")
    THEN GET ERROR MESSAGE;
         MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
         GOTO NEXT EXCHANGE;
    ELSE GOTO PREVIOUS EXCHANGE;
    END IF;
 
  ERROR_PROCESS_MSG:
   EXCHANGE WORK IS
    SEND FORM RECORD MSG_FORM_REC
    SENDING MSG_WKSP;
 
END BLOCK WORK;
ACTION IS
  REPEAT TASK;
 
END DEFINITION;

The first step of both data entry and inquiry tasks involves getting information from the user. In the Review Car Rates task, the terminal user types in a code indicating the class of car (compact, midsize, and so on) that the customer wants to rent and presses Return or Enter to proceed to the next step. Otherwise, the terminal user can press PF4to exit from the task and return to the menu.

DETERMINE_RENTAL_CLASS:
   EXCHANGE
    TRANSCEIVE FORM RECORD RENTAL_CLASSES_FORM_REC, 
                           RENTAL_CLASSES_FORM_REC_LIS
     SENDING RENTAL_CLASSES_WKSP 
     RECEIVING RENTAL_CLASSES_WKSP, QUIT_CTRL_WKSP;
   ACTION
    CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;   

Definition of record RENTAL_CLASSES_WKSP
|   Contains field          COUNTRY_ID
|   |  Datatype                 signed longword
|   Contains field          REQUESTED_RENTAL_CLASS_ID
|   |  Datatype                 text size is 2 characters
|   Contains field          DAY_RENTAL_RATE_AMT
|   |  Datatype                 text size is 5 characters
|   Contains field          WEEK_RENTAL_RATE_AMT
|   |  Datatype                 text size is 7 characters
|   Contains field          MONTH_RENTAL_RATE_AMT
|   |  Datatype                 text size is 7 characters

As in the data entry task, you can use the DECforms COPY statement in the RENTAL_CLASSES_FORM IFDL code to create the RENTAL_CLASSES_FORM_REC form record that corresponds to the application workspace.

The second part of data entry and inquiry involves interaction with a file. You accomplish this interaction by using a procedure in a processing step. In a data entry task, a procedure writes data to a file; in an inquiry task, a procedure reads data from a file.

Both of these errors are recoverable; the user can type a new number if the record did not exist or can retry the inquiry if the record was locked. Any other errors in reading the record are treated as nonrecoverable, and the procedure cancels the task.

Both recoverable errors cause the procedure to return an error code with a severity level of WARNING or ERROR. Both of these severity levels are handled by the value B (BAD) in the ACMS$T_STATUS_TYPE field in the workspace ACMS$PROCESSING_STATUS. Therefore, you can use the IF THEN ELSE clause to test the contents of that field and handle errors for the task.

GET_RENTAL_RATES:
   PROCESSING
     CALL GET_RATES_PROC IN RENTAL_SERVER
       USING RENTAL_CLASSES_WKSP;
   ACTION IS
     IF (ACMS$T_STATUS_TYPE EQ "B")
     THEN GET ERROR MESSAGE;
          MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
          GOTO NEXT EXCHANGE;
     ELSE GOTO STEP DISPLAY_RENTAL_RATES;
     END IF;  

If ACMS evaluates the Boolean expression in the IF THEN ELSE clause to be false, it performs the action associated with the ELSE keyword. In this case, it passes control to the DISPLAY_RENTAL_RATES exchange step.

NO_RC_MSG:
   EXCHANGE
     TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
      SENDING MSG_WKSP
      RECEIVING QUIT_CTRL_WKSP;
   ACTION IS
     IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
     THEN EXIT TASK;
     ELSE GOTO STEP DETERMINE_RENTAL_CLASS;
     END IF; 

As in the data entry task, you must define the additional workspaces that you use for error handling, QUIT_CTRL_WKSP and MSG_WKSP. Because the NO_RC_MSG exchange step sends the error message from MSG_WKSP to the form, you also need to include the form record definition for MSG_FORM_REC in the IFDL code. QUIT_CTRL_FORM_REC is the form record that corresponds to the QUIT_CTRL_WKSP workspace.

The NO_RC_MSG exchange step uses an IF THEN ELSE clause in the action part of the step to test whether or not the terminal user wants to exit from the task. If the user does not want to exit, ACMS passes control to the DETERMINE_RENTAL_CLASS exchange step so that the user can enter another rental class code.

In a data entry task, once a procedure has written the information to a file, the task is complete. For an inquiry task, however, once the procedure has read information from a file, you must display that information to the terminal user.

DISPLAY_RENTAL_RATES:
   EXCHANGE WORK IS
    TRANSCEIVE FORM RECORD RENTAL_CLASSES_FORM_REC, QUIT_CTRL_FORM_REC
     SENDING RENTAL_CLASSES_WKSP
     RECEIVING QUIT_CTRL_WKSP;
   ACTION
    CONTROL FIELD QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"   :   EXIT TASK;
    END CONTROL FIELD; 

Once the DISPLAY_RENTAL_RATES step has displayed the car rates, ACMS returns control to the block step part of the definition.

Like the Add Car Reservation task, the Review Car Rates task uses DECforms to communicate with the terminal user. Therefore, you need to assign the FORM I/O attribute to the block step.

You define the start of the block step with the BLOCK WORK keywords. You use the END BLOCK WORK keywords to signal the end of the work done in the block and to separate the block work from the block action.

For inquiry tasks, terminal users are likely to want to look at more than one record without having to reselect the task from a menu. You can let them do this by using the REPEAT TASK clause in the action part of the block step definition.

WORKSPACES ARE RENTAL_CLASSES_WKSP, QUIT_CTRL_WKSP, MSG_WKSP;

REPLACE TASK REVIEW_CAR_RATES_TASK /LIST=CARRTRV.LIS
 
WORKSPACES ARE RENTAL_CLASSES_WKSP, QUIT_CTRL_WKSP, MSG_WKSP;
BLOCK WORK WITH FORM I/O
  
DETERMINE_RENTAL_CLASS:
   EXCHANGE
    TRANSCEIVE FORM RECORD RENTAL_CLASSES_FORM_REC, 
                           RENTAL_CLASSES_FORM_REC_LIS
     SENDING RENTAL_CLASSES_WKSP
     RECEIVING RENTAL_CLASSES_WKSP, QUIT_CTRL_WKSP;
   ACTION
    CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;   
 
GET_RENTAL_RATES:
   PROCESSING
     CALL GET_RATES_PROC IN RENTAL_SERVER
       USING RENTAL_CLASSES_WKSP;
   ACTION IS
     IF (ACMS$T_STATUS_TYPE EQ "B")
     THEN GET ERROR MESSAGE;
          MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
          GOTO NEXT EXCHANGE;
     ELSE GOTO STEP DISPLAY_RENTAL_RATES;
     END IF;  
 
NO_RC_MSG:
   EXCHANGE
     TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
      SENDING MSG_WKSP
      RECEIVING QUIT_CTRL_WKSP;
   ACTION IS
     IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
     THEN EXIT TASK;
     ELSE GOTO STEP DETERMINE_RENTAL_CLASS;
     END IF; 
 
DISPLAY_RENTAL_RATES:
   EXCHANGE WORK IS
    TRANSCEIVE FORM RECORD RENTAL_CLASSES_FORM_REC, QUIT_CTRL_FROM_REC
     SENDING RENTAL_CLASSES_WKSP
     RECEIVING QUIT_CTRL_WKSP;
   ACTION
    CONTROL FIELD QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"   :   EXIT TASK;
    END CONTROL FIELD; 
END BLOCK WORK;
 
ACTION 
   REPEAT TASK;
 
END DEFINITION;

When making changes to the definition, use the REPLACE command on the first line in the file to minimize the changes that you have to make to the file later. If you want to produce a listing file when submitting the file to ADU, you must include the /LIST qualifier in the file itself, because you cannot use it with the at sign character (@). The listing file shows you the source definition file and errors encountered by ADU when that definition was processed with the CREATE or REPLACE command.

ADU> @REVIEW_CAR_RATES_TASK.COM

If there are no syntax errors in the definition, ADU stores it in the dictionary. If there are errors in the definition, you can edit the source definition file and resubmit it to ADU as a command file.

The previous sections show how to define a simple inquiry task, Review Car Rates. That task displayed a single record from a file. However, you might want to define a task that lets a user display many records at the same time. Also, all the records requested by the user might not fit on a single screen.

For example, a car rental agency that handles many corporate car rentals needs to be able to review all the current reservation records for a particular company's employees. The Review Reservation task lets a terminal user display the reservation records for employees in a particular company. The task displays only five records at a time. However, it lets the terminal user display five more records without redisplaying the initial panel.

GET_COMPANY_ID:
   EXCHANGE
     TRANSCEIVE FROM RECORD CO_RESERVE_FORM_REC, 
                            CO_RESERVE_FORM_REC_LIS
      SENDING CO_RESERVE_WKSP
      RECEIVING CO_RESERVE_WKSP, QUIT_CTRL_WKSP;
   ACTION IS
     CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
       "QUIT"     : EXIT TASK;
     END CONTROL FIELD;

Definition of record CO_RESERVE_WKSP
|   Contains field           COMP_ID
|   |  Datatype                  text size is 5 characters
|   Contains field           COMP_NAME
|   |  Datatype                  text size is 20 characters
|   Contains field           WK_ERR_MSG
|   |  Datatype                  text size is 4 characters
|   Contains field           WK_SAVE_NUMBER
|   |  Datatype                  signed longword 
|   Contains record          EMPL
|   |  Row_major array           1:5
|   |  Contains field            EMPL_NAME
|   |  |  Datatype                   text size is 30 characters
|   |  Contains field            EMPL_PHONE
|   |  |  Datatype                   text size is 10 characters
|   |  Contains field            CAR_TYPE
|   |  |  Datatype                   text size is 3 characters
|   |  Contains field            RENTAL_DATE
|   |  |  Datatype                   text size is 6 characters
|   |  Contains field            RETURN_DATE
|   |  |  Datatype                   text size is 6 characters  

GET_FIVE_RESERVATIONS:
   PROCESSING
     CALL REVIEW_RESERVATION_PROC IN RESERVATION_SERVER
       USING CO_RESERVE_WKSP;
   ACTION IS
     IF (ACMS$STATUS_TYPE EQ "B")
     THEN GET ERROR MESSAGE;
          MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
          GOTO NEXT EXCHANGE;
     ELSE GOTO STEP DISPLAY_RESERVATIONS;
     END IF;  

DISPLAY_ERROR:
    EXCHANGE
     TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
      SENDING MSG_WKSP
      RECEIVING QUIT_CTRL_WKSP.QUIT_KEY;
     ACTION
      IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
      THEN EXIT TASK;
      ELSE GOTO STEP GET_COMPANY_ID;
      END IF; 

DISPLAY_RESERVATION:
   EXCHANGE
    TRANSCEIVE FORM RECORD CO_RESERVE_FORM_REC, QUIT_CTRL_FORM_REC 
     SENDING CO_RESERVE_WKSP
     RECEIVING QUIT_CTRL_WKSP;
    ACTION IS
     CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
     "QUIT"   :   EXIT TASK;
     "MORE"   :   GOTO PREVIOUS PROCESSING;
     END CONTROL FIELD; 

 .
 .
 .
END BLOCK WORK;
 
ACTION
   REPEAT TASK;

REPLACE TASK REVIEW_RESERVATION_TASK /LIST=RVRSV.LIS
   WORKSPACES ARE CO_RESERVE_WKSP, QUIT_CTRL_WKSP, MSG_WKSP;
  
BLOCK WORK WITH FORM I/O
 
   GET_COMPANY_ID:
   EXCHANGE
     TRANSCEIVE FROM RECORD CO_RESERVE_FORM_REC, 
                            CO_RESERVE_FORM_REC_LIS
      SENDING CO_RESERVE_WKSP
      RECEIVING CO_RESERVE_WKSP, QUIT_CTRL_WKSP;
   ACTION IS
     CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
       "QUIT"     : EXIT TASK;
     END CONTROL FIELD;
 
   GET_FIVE_RESERVATIONS:
     PROCESSING
       CALL REVIEW_RESERVATION_PROC IN RESERVATION_SERVER
         USING CO_RESERVE_WKSP;
     ACTION IS
       IF (ACMS$STATUS_TYPE EQ "B")
       THEN GET ERROR MESSAGE;
            MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
            GOTO NEXT EXCHANGE;
       ELSE GOTO STEP DISPLAY_RESERVATIONS;
       END IF;  
 
   DISPLAY_ERROR:
    EXCHANGE
     TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
      SENDING MSG_WKSP
      RECEIVING QUIT_CTRL_WKSP;
     ACTION
      IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
      THEN EXIT TASK;
      ELSE GOTO STEP GET_COMPANY_ID;
      END IF; 
 
   DISPLAY_RESERVATION:
   EXCHANGE
    TRANSCEIVE FORM RECORD CO_RESERVE_FORM_REC, QUIT_CTRL_FORM_REC 
     SENDING CO_RESERVE_WKSP
     RECEIVING QUIT_CTRL_WKSP;
    ACTION IS
     CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
     "QUIT"   :   EXIT TASK;
     "MORE"   :   GOTO PREVIOUS PROCESSING;
     END CONTROL FIELD; 
 
END BLOCK WORK;
ACTION
   REPEAT TASK;
END DEFINITION;

FIND_RESERVATION:
   PROCESSING
    CALL FIND_RESERVE_PROC IN RESERVE_SERVER
     USING RESERVE_WKSP;
   ACTION
    IF (ACMS$T_STATUS_TYPE EQ "B")
    THEN GET ERROR MESSAGE;
         MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
         GOTO NEXT EXCHANGE;
    ELSE GOTO STEP DISPLAY_RESERVATION;
    END IF;

When you update information, it is important that the contents of a record do not change from the time those contents are displayed to the user for update until the time you write the changed record back to the file. This is especially important in a multiuser application in which another user might update the record while it is being displayed on the terminal screen for the first user.

One way of ensuring the integrity of the record you are updating is to have the procedure lock the record and then retain server context between processing steps. However, it is much more efficient to release server context between processing steps. When you update a record, to ensure the integrity of the record without locking the record and retaining server context, you need to check whether the record was updated by someone else before writing the first user's changes to the file. See VSI ACMS for OpenVMS Writing Server Procedures for further discussion on releasing server context.

DISPLAY_ERROR:
   EXCHANGE
    TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
     SENDING MSG_WKSP
     RECEIVING QUIT_CTRL_WKSP;
    ACTION
     IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
     THEN EXIT TASK;
     ELSE GOTO STEP GET_CUSTOMER_NAME;
     END IF;

This exchange step sends the error message stored in MSG_WKSP to the MSG_FORM_REC form record for display to the terminal screen. The action part of this step tests the QUIT_KEY field of the QUIT_CTRL_WKSP workspace to see whether or not the terminal user wants to exit from the task. If the user presses the PF4 key, DECforms returns the value "QUIT" to the workspace, and ACMS ends the task and returns the user to the menu. Otherwise, ACMS passes control to the first step in the task definition.

Once a procedure has read information from a file, you can display that information to the terminal user. The user can then supply information, in the form of changes, to be written back to the file. You use an exchange step to call a form record to display information to the user and to accept changes.

DISPLAY_RESERVATION:
   EXCHANGE
    TRANSCEIVE FORM RECORD RESERVE_FORM_REC, RESERVE_FORM_REC_LIS
     SENDING RESERVE_WKSP
     RECEIVING RESERVE_WKSP, QUIT_CTRL_WKSP  
               SHADOW IS RESERVE_SHADOW_WKSP;
   ACTION
    CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;

For an inquiry task, such as Review Reservation, this second exchange step is the final step in the task. However, in an update task, the user can make changes to the information displayed.

The DISPLAY_RESERVATION step uses RESERVE_WKSP to send the information read by the FIND_RESERVE_PROC procedure to the form for display. The step also uses RESERVE_WKSP to store the information that the terminal user returns.

Unlike exchange steps in the data entry and inquiry tasks, this step uses a shadow workspace to determine whether or not the terminal user changed any information in the reservation record. When you declare a shadow workspace, DECforms returns a value to that workspace that indicates whether or not the user changed any data in the record. In this exchange step, RESERVE_SHADOW_WKSP is the shadow workspace for the RESERVE_WKSP workspace.

Definition of record RESERVE_SHADOW_WKSP
|   Contains field          REC_STATUS
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_NAME_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_STREET_ADDRESS_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_CITY_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_STATE_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_ZIP_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CUST_PHONE_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          CAR_TYPE_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          RENTAL_DATE_SHADOW
|   |  Datatype                 text size is 1 character 
|   Contains field          RETURN_DATE_SHADOW
|   |  Datatype                 text size is 1 character 

If the terminal user changed any data in RESERVE_WKSP, ACMS stores a 1 in the REC_STATUS field of RESERVE_SHADOW_WKSP when the transceive operation completes. The status field in the shadow workspace must be the first field in your record definition. In your DECforms IFDL code, you must assign the TRACKED attribute to the fields of shadow workspaces. See the DECforms documentation for information on using this attribute.

After the DISPLAY_RESERVATION step ends, you need to check the shadow workspace to see whether or not the reservation record has changed. If it has, write the new record to the Reservation file and display a message on the terminal screen confirming the update.

By using a nested block step, you can group processing and exchange steps and have ACMS process them only if a certain condition is met. You introduce a nested block the same way you introduce a block, with the BLOCK WORK keywords. As with other steps, you can assign a label to a nested block and refer to it from elsewhere in the task definition.

CHECK_RESERVE_CHANGES:
   BLOCK WORK
    IF (RESERVE_SHADOW_WKSP.REC_STATUS EQ "1")
    THEN
      PROCESSING  
       CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
        USING RESERVE_WKSP; 
      ACTION
       MOVE "RESERVATION RECORD UPDATED" TO MSG_WKSP.MESSAGE_PANEL;
 
      EXCHANGE
       SEND FORM RECORD MSG_FORM_REC
        SENDING MSG_WKSP;
    END IF;
   END BLOCK;

In the CHECK_RESERVE_CHANGES step, an IF THEN ELSE block conditional clause tests the shadow workspace. If the REC_STATUS field equals 1, ACMS processes the processing and exchange steps that follow the THEN keyword. The processing step calls the WRITE_RESERVE_PROC procedure, which writes the new reservation record to the Reservation file.

The action part of the processing step moves the message "RESERVATION RECORD UPDATED" to the MSG_WKSP workspace, and the exchange step then sends that message to DECforms for display.

If the shadow record indicates that the terminal user did not change any data in the reservation record, ACMS does not perform the processing and exchange steps in the CHECK_RESERVE_CHANGES block step. Note that you do not need to include the ELSE keyword in the IF THEN ELSE clause. ACMS passes control to the clause following the END IF keywords. Be sure to end the nested block with the END BLOCK keywords.

The Review Update task uses DECforms to interface with the terminal; therefore, you need to assign the FORM I/O attribute to the block. Nested blocks inherit the attributes that you assign to their parent blocks; so, you do not need to include the FORM I/O keywords with the CHECK_RESERVE_CHANGES step.

Because you want to repeat this task automatically rather than make the terminal user choose the task again from the menu, include the REPEAT TASK clause in the action part of the parent block.

WORKSPACES ARE RESERVE_WKSP, RESERVE_SHADOW_WKSP, QUIT_CTRL_WKSP, MSG_WKSP;

REPLACE TASK REVIEW_UPDATE_TASK /LIST=RVSCHED.LIS
   WORKSPACES ARE RESERVE_WKSP, QUIT_CTRL_WKSP, MSG_WKSP,
                  RESERVE_SHADOW_WKSP;
 
BLOCK WORK WITH FORM I/O
 
GET_CUSTOMER_NAME:
   EXCHANGE
    TRANSCEIVE FORM RECORD RESERVE_FORM_REC, RESERVE_FORM_REC_LIS
     SENDING RESERVE_WKSP
     RECEIVING RESERVE_WKSP, QUIT_CTRL_WKSP;
   ACTION
     CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
     "QUIT"   :   EXIT TASK;
     END CONTROL FIELD;
 
FIND_RESERVATION:
   PROCESSING
    CALL FIND_RESERVE_PROC IN RESERVE_SERVER
     USING RESERVE_WKSP;
   ACTION
    IF (ACMS$T_STATUS_TYPE EQ "B")
    THEN GET ERROR MESSAGE;
         MOVE ACMS$T_STATUS_MESSAGE TO MSG_WKSP.MESSAGE_PANEL;
         GOTO NEXT EXCHANGE;
    ELSE GOTO STEP DISPLAY_RESERVATION;
    END IF;
 
DISPLAY_ERROR:
   EXCHANGE
    TRANSCEIVE FORM RECORD MSG_FORM_REC, QUIT_CTRL_FORM_REC
     SENDING MSG_WKSP
     RECEIVING QUIT_CTRL_WKSP;
    ACTION
     IF (QUIT_CTRL_WKSP.QUIT_KEY EQ "QUIT")
     THEN EXIT TASK;
     ELSE GOTO STEP GET_CUSTOMER_NAME;
     END IF;
 
DISPLAY_RESERVATION:
   EXCHANGE
    TRANSCEIVE FORM RECORD RESERVE_FORM_REC, RESERVE_FORM_REC_LIS
     SENDING RESERVE_WKSP
     RECEIVING RESERVE_WKSP, QUIT_CTRL_WKSP 
               SHADOW IS RESERVE_SHADOW_WKSP;
   ACTION
    CONTROL FIELD IS QUIT_CTRL_WKSP.QUIT_KEY
    "QUIT"  :  EXIT TASK;
    END CONTROL FIELD;
 
CHECK_RESERVE_CHANGES:
   BLOCK WORK
    IF (RESERVE_SHADOW_WKSP.REC_STATUS EQ "1")
    THEN
      PROCESSING  
       CALL WRITE_RESERVE_PROC IN RESERVE_SERVER
        USING RESERVE_WKSP; 
      ACTION
       MOVE "RESERVATION RECORD UPDATED" TO MSG_WKSP.MESSAGE_PANEL;
 
      EXCHANGE
       SEND FORM RECORD MSG_FORM_REC
        SENDING MSG_WKSP;
    END IF;
   END BLOCK;
END BLOCK;
ACTION
   REPEAT TASK;
END DEFINITION;

In processing external requests, DECforms follows a specific order of steps, called phases. See VSI DECforms Programmer's Reference Manual for more details on how phases proceed with DECforms.

With DECforms, use responses to control the operation of forms processing. You can think of a DECforms response as a way of directing how DECforms responds or behaves. By declaring responses, you can determine much of what DECforms does in its interaction with the user's terminal, the form, and the ACMS application.

***************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. EMPLOYEE_COUNT.

***************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.         VAX-11.
OBJECT-COMPUTER.         VAX-11.

***************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.

LINKAGE SECTION.
01 EMPL_COUNT                     PIC S9(9) COMP.

***************************************************
PROCEDURE DIVISION USING COUNTER. 

00-DO-ADD.

        ADD 1 TO COUNTER.
        END PROGRAM EMPLOYEE_COUNT.

One use for the COUNTER value is to display its value on a panel after a message such as "Total number of employees is."

$ COBOL employee_count

RECEIVE RESPONSE EMPLOYEE_INFO_FORM  
     DISPLAY EMPLOYEE_INFO_PANEL_1
     CALL 'EMPLOYEE_COUNT' USING EMPL_NUMBER 
END RESPONSE

In the previous example, the CALL response step calls the escape unit EMPLOYEE_COUNT and passes the form data item EMPL_NUMBER to the escape unit. For each EMPL_NUMBER sent to it, the escape unit adds 1 to the COUNTER variable and returns the new value to the form. When the escape unit finishes, DECforms ends the response.

Certain agents, such as the CP agent that ACMS supplies, run in a privileged environment. Any escape units that execute in a privileged agent also execute in the same privileged environment. Be sure to develop escape units to execute in a privileged agent in the same way as you develop any other privileged code. Carefully review the code for any possible security violations before you run it live on the system.

Place the escape unit images in a write-protected directory; also write-protect the images themselves. After you place the file in a protected directory, you can define the logical names that make the escape units available to the agent process.

You may not, however, need to place the escape units executed by a nonprivileged agent in a protected directory. In some cases, such as debugging, you may want the person running the CP agent to be able to change the escape units executed. Use the methods described in this section to make the escape unit images available to the CP agent.

If you need to change a DECforms file in binary format (.FORM), stop the application and restart it before using the new file. This procedure ensures that EXC has the correct file information for caching purposes.

DECforms files in image format (.EXE) require different treatment. Before using a new form image file for DECforms files in image format, stop the terminal subsystem so that the CP can map the new version of the form image. This action is necessary because OpenVMS maps these images into the processes that are using them, and there is no way to unmap the images.

Form image files are recommended for production environments, because they require fewer resources in multithreaded environments than files in binary format. The following procedure is suggested for customers who need to replace form image files without stopping the agent process.

The ACMS task group definition must specify the form file with a logical name rather than a file specification. Define the logical name outside ACMS in a logical name table accessed by both the EXC process and the application manager.

When you follow this procedure, the application picks up the new name of the form file and passes it to the agent. The agent then asks OpenVMS to map the renamed file. Because the OpenVMS image activation code sees the new name of the form file, it considers the file to be different from any files that are already mapped in. The renamed form file is mapped in, and the agent process begins to use it.

Note that the OpenVMS image activation code uses only the file name portion of the file specification to determine whether or not it is a new image. Changing other parts of the file specification (for example, device, directory, file extension, or version number) has no effect. Each image can be activated only once in a process. If an image file has been activated, then a different image file with the same name is not activated.

REPLACE TASK ENTER_ORDER 
.
.
.
   PROCESSING
     CALL TASK ORDER_LINES USING
       CUSTOMER_INFO_RECORD,
       CUSTOMER_ACCOUNT_RECORD,
       ORDER_DATA_RECORD;
.
.
.

In this example, the processing step calls the ORDER_LINES task, passing the CUSTOMER_INFO_RECORD, CUSTOMER_ACCOUNT_RECORD, and ORDER_DATA_RECORD workspaces. The task name specified in a CALL TASK clause must be a group task name, not an application task name.

REPLACE TASK ORDER_LINES
 
WORKSPACES ARE
     CUSTOMER_INFO_RECORD,
     CUSTOMER_ACCOUNT_RECORD,
     ORDER_DATA_RECORD,
     TASK_CONTROL_RECORD;
 
TASK ARGUMENTS ARE
     CUSTOMER_INFO_RECORD WITH ACCESS READ,
     CUSTOMER_ACCOUNT_RECORD WITH ACCESS MODIFY,
     ORDER_DATA_RECORD WITH ACCESS WRITE;

The ENTER_ORDER task controls the entry of general information about the order (such as customer name and address, shipping address, type of order, sales representative, and so on) and then passes control to the ORDER_LINES task. The ORDER_LINES task receives customer information in the CUSTOMER_INFO_RECORD, updates the customer's accounts information in the CUSTOMER_ACCOUNT_RECORD, and returns line totals in the ORDER_DATA_RECORD.

Workspaces you use as task call arguments must be defined as task workspaces (the default) in the called task. Workspaces received by the called task must be listed in the TASK ARGUMENTS statement in the order in which the calling task passes them. You can specify MODIFY, READ, or WRITE access to those workspaces for the calling task. Use MODIFY to pass and return data, READ to pass data only, and WRITE to return data only.

You must be careful not to unintentionally overwrite data when accessing group and user workspaces from both the parent task and the called task. See Section 5.1.3, ''Passing Workspaces'' for further information on using workspaces.

This section presents a complete example of how to use the task calling feature. The example shows a simple order-entry transaction. The example is limited to ACMS task definition syntax, with one exception: a BASIC program the order-detail task uses.

REPLACE TASK ENTER_ORDER
 
WORKSPACES ARE          
     HEADER_DATA_WSP,
     MSG_WKSP,
     ORDER_DATA_RECORD, 
     TASK_CTL_WSP;
 
DEFAULT SERVER IS ORDER_SERVER;
DEFAULT FORM IS ORDER_FORM;
GLOBAL;
 
BLOCK WORK WITH FORM I/O
 
     EXCHANGE
         RECEIVE FORM RECORD HEADER_DATA_FORM_REC_LIS
           RECEIVING HEADER_DATA_WSP, TASK_CTL_WSP;
         ACTION IS
           CONTROL FIELD TASK_CTL_WSP.TASK_CTL_FIELD
           "QUIT"  :  EXIT TASK;
           END CONTROL FIELD;  
 
     PROCESSING
         CALL WRITE_ORDER_HEADER_DATA USING HEADER_DATA_WSP;
 
DO_ORDER_LINE:
     PROCESSING
         CALL TASK PROCESS_ORDER_LINE USING
             ORDER_DATA_RECORD,
             TASK_CTL_WSP, MSG_WKSP;
         ACTION IS
           CONTROL FIELD TASK_CTL_WSP.TASK_CTL_FIELD
           "QUIT"  :  MOVE "Order completed successfully" TO
                       MSG_WKSP.MESSAGE_PANEL; 
                       GOTO STEP END_ORDER;
           END CONTROL FIELD;  
 
     PROCESSING
         CALL INCREMENT_ORDER_TOTALS USING
             ORDER_DATA_RECORD,
             HEADER_DATA_WSP;
         ACTION IS 
           GOTO STEP DO_ORDER_LINE;
 
END_ORDER:
     EXCHANGE
         SEND FORM RECORD MSG_WKSP_FORM_REC
           SENDING MSG_WKSP;
 
END BLOCK WORK;

The first exchange step in Example 5.1, ''Task ENTER_ORDER'' displays the order entry panel and uses the HEADER_DATA_WSP to store the data the user types in. If the TASK_CTL_FIELD contains the word "QUIT" (which the user can place there by using a DECforms-defined function key), the task exits. Otherwise, the first processing step calls a server procedure to write the contents of HEADER_DATA_WSP to a file.

The second processing step calls the PROCESS_ORDER_LINE task, passing the ORDER_DATA_RECORD and TASK_CTL_WSP workspaces. Control passes from this point in the task definition to the PROCESS_ORDER_LINE task (see Example 5.2, ''Task PROCESS_ORDER_LINE'').

When control returns to the ENTER_ORDER task, the TASK_CTL_FIELD is again checked for the word "QUIT". If the user did not press the QUIT function key, the third processing step in the ENTER_ORDER task increments the order totals and passes control back to the DO_ORDER_LINE step, which calls the PROCESS_ORDER_LINE task to input the next line of the order.

REPLACE TASK PROCESS_ORDER_LINE
 
WORKSPACES ARE
     DATA_RECORD,
     MSG_WKSP,
     ORDER_DATA_RECORD,
     TASK_CTL_WSP;
 
DEFAULT SERVER ORDER_SERVER;
DEFAULT FORM ORDER_FORM;
 
LOCAL;
 
TASK ARGUMENTS ARE
     ORDER_DATA_RECORD WITH ACCESS MODIFY,
     TASK_CTL_WSP WITH ACCESS WRITE;
     MSG_WKSP WITH ACCESS WRITE;
 
BLOCK WORK WITH FORM I/O
 
     EXCHANGE
         RECEIVE FORM RECORD INPUT_DATA_FORM_REC_LIS
           RECEIVING DATA_RECORD, TASK_CTL_WSP;
         ACTION IS
             CONTROL FIELD TASK_CTL_WSP.TASK_CTL_FIELD
             "QUIT"  :  EXIT TASK;
             END CONTROL FIELD;
 
     PROCESSING
         CALL WRITE_ORDER_LINE USING
             DATA_RECORD,
             ORDER_DATA_RECORD,
             TASK_CTL_WSP;
         ACTION IS
             SELECT FIRST TRUE
             ( TASK_CTL_FIELD = "DUPL" ): GOTO PREVIOUS EXCHANGE;
             NOMATCH  : MOVE "Order line record successfully 
                        added to database" TO MSG_WKSP.MESSAGE_PANEL;
             END SELECT;
 
     EXCHANGE
         SEND FORM RECORD MSG_WKSP_FORM_REC
           SENDING MSG_WKSP;
         ACTION IS
             EXIT TASK;
 
END BLOCK WORK;

The PROCESS_ORDER_LINE task is a LOCAL task, which means that it can be called only from another task. It cannot be initiated by using a menu selection. You assign the LOCAL attribute in the application definition.

The TASK ARGUMENTS clause lists the workspaces the PROCESS_ORDER_LINE task can receive when called from another task. ORDER_DATA_RECORD is defined as a modify-access workspace; that is, any data written to it by the PROCESS_ORDER_LINE task can be modified, and is returned to the calling task. TASK_CTL_WSP and MSG_WKSP are defined as write-only workspaces; that is, no data are passed into them from the calling task, but any data written to them by the PROCESS_ORDER_LINE task is returned to the calling task. This way of passing workspaces is more efficient than using MODIFY (or read-write) access.

The PROCESS_ORDER_LINE task calls a DECforms form to display the order-lines panel and accept data that the user types in. After accepting data from the user, the task calls the WRITE_ORDER_LINE procedure (see Example 5.3, ''Procedure WRITE_ORDER_LINE (in BASIC)'') by using data from the order header as well as data from the order line.

The WRITE_ORDER_LINE procedure checks for a duplicate key value and returns to the first exchange step if it finds one. If the order line is written successfully to the file, a second exchange step writes a success message, the task exits, and control returns to the ENTER_ORDER task.

When the user presses the QUIT key, the task exits, and control returns immediately to the ENTER_ORDER task, without calling the server procedure or the second exchange step.

10 SUB WRITE_ORDER_LINE( DATA_RECORD DATA_REC,            &
                          ORDER_DATA_RECORD ORD_VALUE_REC, &
                          TASK_CTL_WSP TASK_CTL )
    %INCLUDE %FROM %CDD "DATA_RECORD"
    %INCLUDE %FROM %CDD "ORD_VALUE_REC"
    %INCLUDE %FROM %CDD "TASK_CTL_WSP"
    MAP (DATA_FILE) DATA_RECORD FILE_REC
 
    FILE_REC = DATA_REC             ! Transfer data to file buffer
    ON ERROR GOTO 20                ! Set up an error trap
    PUT #1%                         ! Store the data
    ORD_VALUE_REC::ORD_LINE_TOTAL = DATA_REC::PRICE * DATA_REC::QTY
                                    ! Calculate order line total
    TASK_CTL::TASK_CTL_FIELD = "OK" ! It all worked so return success
    EXIT SUB                        ! And exit
 
20 IF ERR = 134% THEN              ! If duplicate key detected then
      TASK_CTL::TASK_CTL_FIELD = "DUPL" ! Return failure indicator
      RESUME 99                     !     And exit
 
    ELSE                            ! Otherwise
      CALL ACMSAD$REQ_CANCEL        !     Something serious occurred
    END IF                          !     so cancel the task.
 
99 END SUB

The procedure shown in Example 5.3, ''Procedure WRITE_ORDER_LINE (in BASIC)'' moves the data from the workspace to the file buffer and then writes a record to the file. If the write operation succeeds, the procedure returns a success code in a task control workspace. If it detects a duplicate key, which indicates that a duplicate item exists in the same order, the procedure returns a failure code to the task. Any other error causes the procedure to cancel the task.

If there are any unexpected errors (such as a device-full RMS error) or the server process terminates unexpectedly while the WRITE_ORDER_LINE procedure is running, ACMS automatically cancels the PROCESS_ORDER_LINE task. When a called task is canceled, ACMS by default also cancels the parent task.

When a called task is canceled, by default the calling task also is canceled. For information on how to override this default so that ACMS does not automatically cancel the calling task when the called task is canceled, see Chapter 8, "Handling Task Execution Errors".

This section presents the rules for passing ACMS workspaces to and from a task you call from another task.

A task passes workspaces to a called task by position. That is, the contents of the first workspace identified by the USING phrase in the parent task is moved to the first workspace named in TASK ARGUMENTS clause in the called task, and so on, for each workspace named in the USING phrase. This is the same as the method for passing workspaces to routines in procedure servers or to DECforms forms.

ACMSWSP-E-NONESUCH, INTERNAL ERROR: SPECIFIED BLOCK DOES NOT EXIST

A called task can accept arguments using task workspaces only. You cannot pass arguments into group, user, or system workspaces. Special rules apply for accessing group, user, and system workspaces in called tasks.

You can omit a workspace when you call a task. If you do, ACMS initializes the workspace in the called task with its default contents from the CDD workspace definition stored in the task database (.TDB file). If there are no default contents, ACMS initializes the workspace with zeros.

Specifying READ access on task workspace arguments can provide performance benefits for tasks calling other tasks, because ACMS does not have to update the workspace in the parent task when the called task completes.

In creating workspaces for task calls, bear in mind the trade-off between workspace size and the various access types. For large workspaces, it is more efficient to pass data using a READ workspace and return data using a WRITE workspace than it is to pass and return data in a single MODIFY workspace. Conversely, it is more efficient to pass a single MODIFY workspace containing a small amount of data than it is to pass several separate READ and WRITE workspaces.

You may specify any workspace type (task, user, group, or system) as an argument and pass it to the called task with the USING phrase. However, note that the parent task may supply only workspaces to task workspaces in the called task. See Section 5.1.3.2, ''Handling User and Group Workspaces'' for further information on accessing group and user workspaces.

WORKSPACES ARE
     TASK_WSP1,
     TASK_WSP2,
     USER_WSP WITH TYPE USER;
 
 
 
TASKS ARE
     PARENT_TASK: TASK DEFINITION IS PARENT_TASK;
     CALLED_TASK: TASK DEFINITION IS CALLED_TASK;
END TASKS;
 

DEFINE TASK PARENT_TASK

USE WORKSPACES
     TASK_WSP1,
     USER_WSP WITH UPDATE LOCK;
     .
     .
     .
 
PROCESSING
     CALL TASK CALLED_TASK USING
         TASK_WSP1,
         USER_WSP;
     .
     .
     .
 
END DEFINITION;
 
 
DEFINE TASK CALLED_TASK
 
USE WORKSPACES
     TASK_WSP1,
     TASK_WSP2,
WORKSPACE IS
     USER_WSP;
TASK ARGUMENTS ARE
     TASK_WSP1 WITH ACCESS MODIFY,
     USER_WSP WITH ACCESS MODIFY;
     .
     .
     .
 
PROCESSING
     CALL UPDATE_PROCEDURE USING
         TASK_WSP1,
         TASK_WSP2,
         USER_WSP;
     .
     .
     .
 
END DEFINITION;

USE WORKSPACES
     TASK_WSP1,
     TASK_WSP2,
     USER_WSP;
WORKSPACE IS
     USER_WSP WITH NAME USER_WSP_COPY;
TASK ARGUMENTS ARE
     TASK_WSP1,
     USER_WSP_COPY;
 
BLOCK WORK
PROCESSING
     NO PROCESSING;
     SELECT FIRST TRUE
         ( ACMS$L_CALL_SEQUENCE_NUMBER <> 0 ):
             MOVE USER_WSP_COPY TO USER_WSP;
     END SELECT;
 
 
 
PROCESSING
     CALL update_procedure USING
         TASK_WSP1,
         TASK_WSP2,
         USER_WSP;
 
 
 
END BLOCK WORK;
ACTION IS
     SELECT FIRST TRUE
         ( ACMS$L_CALL_SEQUENCE_NUMBER <> 0 ):
             MOVE USER_WSP TO USER_WSP_COPY;
     END SELECT;

This section describes various mechanisms for controlling tasks that are called by other tasks. You can pass control information in a workspace that you define, use the EXIT task clause, or test ACMS system workspace fields.

WORKSPACES ARE
     DATA_WSP1,
     DATA_WSP2,
     DATA_WSP3;
 
BLOCK WORK
 
 
 
PROCESSING
     CALL PROC_1 USING
         DATA_WSP1,
         DATA_WSP2;
     MOVE ACMS$T_TASK_NAME TO PARENT_TASK_NAME,
         "BATCH_JOB_1.COM" TO ACMS$T_SELECTION_STRING;
 
 
 
PROCESSING
     CALL TASK B USING
         DATA_WSP1,
         DATA_WSP2,
         DATA_WSP3;
 
 
 
PROCESSING
     CALL PROC_2 USING
         DATA_WSP2,
         DATA_WSP3;
 
END BLOCK WORK;
 
 
 
WORKSPACES ARE
     DATA_WSP1,
     DATA_WSP2,
     DATA_WSP3;
 
TASK ARGUMENTS ARE
     DATA_WSP1 WITH ACCESS READ,
     DATA_WSP2 WITH ACCESS MODIFY,
     DATA_WSP3 WITH ACCESS WRITE;
 
BLOCK WORK
 
 
 
PROCESSING
     CALL PROC_3 IN SVR1 USING
         DATA_WSP1,
         DATA_WSP2,
         DATA_WSP3;
 
 
 
PROCESSING WITH NO IO
     DCL COMMAND IS "SUBMIT 'P1" IN SVR2;
 
 
 
END BLOCK WORK;

PROCESSING
   CALL STORE_NEW_CUSTOMER USING  
       CUST_RECORD;
   SELECT FIRST TRUE
       (TASK_STATUS = "OK"):
         EXIT TASK RETURNING APPLMSG_CUST_ADDED;
       (TASK_STATUS = "DUPL"):
         CANCEL TASK RETURNING APPLMSG_DUPL_CUST;
   END SELECT;

PROCESSING 
   CALL TASK ENTER_ORDER;
   ACTION IS
     SELECT FIRST TRUE OF
        ( ACMS$L_STATUS = ACMS$_CALL_CANCELLED ):
            GOTO STEP SUBMITTER_CANCEL;
        ( ACMS$L_STATUS = ACMS$_OPR_CANCELLED ):
            GOTO STEP OPERATOR_CANCEL;
     END SELECT;
 
 

You can define a task as LOCAL or GLOBAL. GLOBAL tasks can be either selected from a menu or called from another task. LOCAL tasks can only be called from another task.

GLOBAL is the default task type. You can select a GLOBAL task from a menu or with the SELECT command in CP, or you can call or chain to a GLOBAL task from another task. However, you can access LOCAL tasks only by calling or chaining to them from another task.

You cannot override the LOCAL/GLOBAL task attribute by using a task group definition, if you define the task in a separate task definition.

ACMS allows a called task to use a different I/O method than that of the parent task. For example, a task using DECforms I/O can call tasks that use terminal I/O in DCL servers or ACMS stream I/O as well as other DECforms I/O tasks.

In order for a task using DECforms or terminal I/O to call a task using stream I/O, the user-written agent must associate a stream ID with a submitter ID. Note that the ACMS CP performs this association automatically. For more information on agents, streams, and submitted IDs, see VSI ACMS for OpenVMS Systems Interface Programming.

Although you can associate a stream ID with a submitter ID, you cannot associate a terminal device specification with a stream ID. Therefore, if an agent calls a task defined to use stream I/O, the called task can only call or chain to other stream I/O tasks or tasks that do not perform I/O. If an agent calls a task defined to use stream I/O, that task cannot call a task that performs local requests, remote requests, or terminal I/O from a server.

A similar rule also applies to tasks that do not perform I/O and are, therefore, defined WITH NO I/O. Because no I/O information is passed to the task when an agent calls it, a NO I/O task may only call or chain to other NO I/O tasks.

You cannot retain server context when calling a task from another task.

If a task that is retaining context in a server process attempts to call another task, ACMS unconditionally cancels the calling task.

TDMS does not support multiple sessions to the same device and limits form context to a request using the same form as the previous request. Therefore, called tasks using TDMS I/O always share form context with the parent task.

Depending on the type of task, you might sometimes want to prevent a task from being canceled by the terminal user. To accomplish this, ACMS lets you specify the NOT CANCELABLE BY TASK SUBMITTER clause in your task definition. The NOT CANCELABLE BY TASK SUBMITTER clause tells ACMS to ignore a submitter cancel request generated in situations such as when a terminal user presses Ctrl/Y. This clause affects a task only when it is currently executing.

WORKSPACE IS
     TASK_CTL_WSP;
 
 NOT CANCELABLE BY TASK SUBMITTER;
 
BLOCK WORK
 
     EXCHANGE
         RECEIVE FORM RECORD GET_SELECTION_FORM_REC_LIS
           RECEIVING TASK_CTL_WSP, TASK_CTL_WSP;
         ACTION IS
           CONTROL FIELD TASK_CTL_WSP.TASK_CTL_FIELD 
           "QUIT"  :  EXIT TASK;
           END CONTROL FIELD; 
 
     PROCESSING 
         SELECT FIRST TRUE
             ( TASK_NUMBER = 1 ): CALL TASK ADD_CUSTOMER;
             ( TASK_NUMBER = 2 ): CALL TASK MODIFY_CUSTOMER;
             ( TASK_NUMBER = 3 ): CALL TASK ENTER_ORDER;
             ( TASK_NUMBER = 4 ): CALL TASK MODIFY_ORDER;
             ( TASK_NUMBER = 5 ): CALL TASK DISPATCH_ORDERS;
         END SELECT;
 
         ACTION IS
             CONTROL FIELD IS ACMS$T_STATUS_TYPE
                 "T":
                     GOTO PREVIOUS EXCHANGE;
                 NOMATCH:
                     GET ERROR MESSAGE;
                     GOTO PREVIOUS EXCHANGE;
             END CONTROL FIELD;
 
END BLOCK WORK;

If a called task returns a success status, the menu task prompts for another task selection. If a called task returns a failure status, the MAIN_MENU task uses the GET MESSAGE phrase to retrieve the error text associated with the returned status value, so that the task selection form can display the message for the user. The NOT CANCELABLE BY TASK SUBMITTER clause prevents the user from canceling the menu task itself by typing Ctrl/Y.

This section describes how to audit and operate task-calling applications.

$ ACMS/SHOW USER TESTU1/FULL
ACMS V5.0       CURRENT USERS                   Time: 19-DEC-2005 12:40:52.53 
 
 
User Name:   TESTU1             Submitter ID: GROW::00010025
   Agent PID: 21C0043F           Device:       RTA3:
 
   Task Name:    VR_CHECKIN_TASK
     Task ID:    GROW::00010025-00000005
     Appl Name:  VR_APPL
     Appl Node:  GROW::

$ ACMS/SHOW TASKS
ACMS V5.0       CURRENT TASKS                   Time: 19-DEC-2005 12:41:27.60 
Task Name: VR_CHECKIN_TASK
   State:        Active; Executing PROCESSING step WORK
   Step Label:   GET_RESV
   Task ID:      GROW::00010025-00000005
   Application:  VR_APPL                                 User Name: TESTU1
   Submitter ID: GROW::00010025                          Device:    RTA3:
   Called Task:  VR_GETRESV_TASK
     State:      Active; Executing EXCHANGE step WORK
     Step Label: CHANGE_INFO
     Task ID:    GROW::00010025-00000005-00000001

$ ACMS/CANCEL TASK/IDENTIFIER=GROW::00010025-00000005

$ ACMS/CANCEL TASK/IDENTIFIER=GROW::10025-5-1

ACMS typically does interactive processing of the tasks in your applications, but certain tasks capture data that does not require immediate processing. Detached tasks provide ACMS applications with a mechanism to start a task with an ACMS operator command, while allowing the task to execute in an unattended, noninteractive manner once it has started.

In the interactive work flow mode, ACMS tasks collect requests from a user and process the requests while the user waits for a response. Users interact with the executing task through a terminal or device. A typical task has an exchange step to accept data from a user, followed by a processing step to process the data. The next exchange step returns control to the terminal to complete the task, or to continue to request input from the terminal.

The detached processing mode is similar to batch-style processing, where no user interaction occurs through a terminal or device, from a task executing within the Application Execution Controller (EXC). A task that executes in this mode is called a detached task.

To illustrate the two modes of task execution, consider the following example involving a manufacturing and distribution company. The company has its headquarters and manufacturing facility based in one location, and multiple distribution centers located remotely. At its headquarters, the company maintains a master database, using Rdb, that holds information about its entire operation. In addition, smaller Rdb databases, located at each distribution center, hold information specific to that segment of the business.

During the day, changes are made to the distribution center databases. These changes necessitate updates to the master database. As the changes are made to the distribution center database, records are queued to a queue database on the distribution center's system. The records are then forwarded to the central system. To update the distribution center databases, an employee executes a task through a terminal device. This is an example of the interactive work flow mode.

Subsequently, a task running continuously in the background without any human interaction is executed to update the master database at the central system. This task is a detached task, and shows how an application uses the detached processing mode.

To start a detached task, use the ACMS/START TASK command. When starting a detached task, specify the task name and the application name where the task executes. You can also specify a retry limit, retry wait timer, user name, and a selection string to pass workspace data.

$ ACMS/START TASK task-name application-name

                                               
Type     : TASK            Time : 19-DEC-2005 12:41:27.60
Appl     : DIST_APPL
Task     : DEQUEUE_TASK
User     : SMITH
ID       : MYNODE::00020013-00000001-B985D5E0-009576B2
Sub      : MYNODE::00020013-00000000-B985D5E0-009576B2
Text     : Detached task started

See VSI ACMS for OpenVMS Managing Applications for more information about the ACMS/START TASK operator command.

The retry wait timer indicates the number of seconds ACMS waits before retrying the detached task after a task failure. The default value is 5 seconds. The minimum value is 1 second, and the maximum is 65,535 seconds. If the detached task is started with a retry limit of 0, or if the task completes successfully, the retry wait timer is not used.

The following sections describe two operator commands that allow you to determine if a detached task is active, and whether the task has started and has not completed.

$ ACMS/SHOW TASK task-name 

ACMS V5.0     CURRENT TASKS           Time:19-DEC-2005 12:42:36.02
 
Task Name:    DEQUEUE_TASK   ***Detached Task***
   State:        Active; Executing PROCESSING step WORK
   Step Label:   $STEP_3
   Task ID:      MYNODE::00020016-00000001
   Application:  DIST_APPL                              User Name:  JONES
   Submitter ID: MYNODE::00020016                       Device: NL:

$ ACMS/SHOW APPLICATION/DETACHED_TASKS

ACMS V5.0       CURRENT APPLICATIONS          Time: 19-DEC-2005 12:43:01.62
 
Application Name: DIST_APPL                               State:  STARTED
 
   Task Name:  DEQUEUE_TASK
     Task State:       Active
     Submitter ID:     MYNODE::00020016                Username:    JONES
     Retry Limit:      10                              Retry Count: 2
     Retry Wait Timer: 60
 
   Task Name:  UPDATE_CENTRAL_TASK
     Task State:       Waiting to Retry
     Submitter ID:     MYNODE::00020017                Username:    SMITH
     Retry Limit:      10                              Retry Count: 0
     Retry Wait Timer: 60

Use the ACMS/CANCEL TASK or ACMS/CANCEL USER operator commands to stop a detached task when you need to cancel and not retry the detached task. Both operator commands cancel a detached task and the associated submitter.

ACMS treats task failures generated as a result of ACMS/CANCEL TASK and ACMS/CANCEL USER operator commands as special cases and does not retry the task. For example, you can use the ACMS/CANCEL USER operator command to stop a task accessing a queue file, so the queue file can be backed up. Once the queue file is backed up, you can start the detached task again. This is particularly important for continuous operations.

In addition, a detached task is stopped whenever the application or the ACMS system is stopped with the /CANCEL qualifier.

Type   : TASK      Time   : 19-DEC-2005 12:43:32.84
Appl   : DIST_APPL
Task   : DEQUEUE_TASK
User   : SMITH
ID     : MYNODE::00020013-00000001-B985D5E0-009576B2
Sub    : MYNODE::00020013-00000001-B985D5E0-009576B2
Text   : Detached task end
Task completion status: Task canceled by system operator
************************************************************
Type   : OTHER     Time   : 19-DEC-2005 12:43:41.42
Text   : Detached task terminated in application DIST_APPL
Detached task DEQUEUE_TASK canceled by system operator

ACMS operator terminals receive notification when a detached task is waiting to retry, and also the reason why the task is retrying.

$ ACMS/SET SYSTEM/PROCESS/OPERATOR

$ ACMS/SET SYSTEM/TERMINAL=TTE2/OPERATOR

The ACMS/SET SYSTEM/TERMINAL/OPERATOR command enables terminal TTE2 as an ACMS operator terminal for as long as ACMS is active.

%ACMS, 20-DEC-2005 12:43:41.42, Detached task DEQUEUE_TASK terminated due to
retry limit being exceeded

COMPLETE_PROC:
 
! CALL THE VR_COMPLETE_CHECKOUT_TASK TO COMPLETE THE CHECKOUT 
! TRANSACTION.
!
!
     PROCESSING
         CALL TASK       VR_COMPLETE_CHECKOUT_TASK
         USING           VR_SENDCTRL_WKSP,
                         VR_CONTROL_WKSP,
                         VR_RESERVATIONS_WKSP,
                         VR_TRANS_WKSP,
                         VR_VEHICLES_WKSP;
!
! THE DISTRIBUTED TRANSACTION IS STARTED IN THE VR_COMPLETE_CHECKOUT_TASK
! BUT IS NOT EXPLICITLY COMMITTED SINCE IT IS A COMPOSABLE TASK. THE 
! COMMIT WILL BE PERFORMED BY ACMS (DEFAULT ACTION).
!
 
     ACTION IS
         MOVE "     " TO VR_CONTROL_WKSP.CTRL_KEY,
              "ACTWT" TO VR_SENDCTRL_WKSP.SENDCTRL_KEY;
!
! RETRY IF A TIME OUT ERROR OCCURRED BEFORE CANCELING TASK.
!
     EXCEPTION HANDLER
         IF ( (ACMS$L_STATUS = ACMS$_TRANSTIMEDOUT AND
                 VR_CONTROL_WKSP.RETRY_COUNT = 0) )
         THEN
              MOVE 1       TO VR_CONTROL_WKSP.RETRY_COUNT;
              REPEAT STEP;
         ELSE
              GET MESSAGE INTO VR_CONTROL_WKSP.MESSAGEPANEL;
              MOVE "     " TO VR_CONTROL_WKSP.CTRL_KEY,
                   "ACTWT" TO VR_SENDCTRL_WKSP.SENDCTRL_KEY;
              GOTO STEP DISP_STAT;
         END IF;
 
!
! DISPLAY STATUS TO THE USER.
!
 DISP_STAT:
 
     EXCHANGE
         SEND RECORD             VR_CONTROL_WKSP
         SENDING                 VR_CONTROL_WKSP
         WITH SEND CONTROL       VR_SENDCTRL_WKSP;
              

In Example 8.4, ''Recovering from an Exception Raised in a Called Task'', the COMPLETE_PROC processing step calls the VR_COMPLETE_CHECKOUT_TASK to compute the customer's bill and perform final checkout work. The VR_COMPLETE_CHECKOUT_TASK starts a distributed transaction. Because VR_COMPLETE_CHECKOUT_TASK is a composable task, it cannot explicitly commit or roll back the distributed transaction. Because a distributed transaction must end in the action part of the step where it starts, ACMS provides the default transaction action.

The exception handler part of the parent task uses an IF THEN ELSE conditional clause to test the contents of the ACMS$L_STATUS field in the ACMS$PROCESSING_STATUS workspace. If the called task raises the ACMS$_TRANSTIMEDOUT exception code, ACMS retries the called task once.

If a called task completes without raising an exception, ACMS returns the contents of any modify-access and write-access task argument workspaces to the parent task. ACMS then resumes executing the task from the action part of the processing step that called the task.

If a called task completes with an exception, ACMS does not return the contents of task argument workspaces to the parent task. If a task, called by a parent task that does not start a distributed transaction, completes with any type of exception, ACMS raises a step exception in the parent task. If a called task that participates in a distributed transaction started by the parent task completes with a step exception, ACMS raises a step exception in the parent task. If a called task that participates in a distributed transaction completes with a transaction or nonrecoverable exception, ACMS raises a transaction exception in the parent task.

BLOCK WITH TRANSACTION
 
!+
! ONLY UPDATE CUSTOMER RECORD IF SHADOW RECORD INDICATES
! CHANGE HAS BEEN MADE ON PREVIOUS EXCHANGE.
 
     IF ( (VR_CUSTOMERS_SHADOW_WKSP.REC_STATUS = "1") OR
          (VR_TRANS_SHADOW_WKSP.REC_STATUS = "1")     OR
          (VR_SENDCTRL_WKSP.SENDCTRL_KEY = "TRAGN") ) THEN
 
         PROCESSING
 
             CALL PROCEDURE VR_STORE_CU_PROC
             IN      VR_CU_UPDATE_SERVER
             USING   VR_CONTROL_WKSP,
                     VR_CUSTOMERS_WKSP,
                     VR_TRANS_WKSP;
 
         ACTION IS
             IF (ACMS$T_STATUS_TYPE = "B") THEN
                 GET MESSAGE INTO VR_CONTROL_WKSP.MESSAGEPANEL;
                 MOVE "TRAGN" TO VR_SENDCTRL_WKSP.SENDCTRL_KEY;
                 EXIT BLOCK;
             ELSE
                 MOVE "     " TO VR_CONTROL_WKSP.CTRL_KEY,
                      "     " TO VR_SENDCTRL_WKSP.SENDCTRL_KEY;
             END IF;
     END IF;
 
 STORE_RESV:
!+
! CREATE RESERVATION NUMBER AND WRITE RESERVATION RECORD TO DB.
!-
     PROCESSING
         CALL PROCEDURE  VR_WRITE_RS_PROC
         IN      VR_UPDATE_SERVER
         USING   VR_CONTROL_WKSP,
                 VR_RESERVATIONS_WKSP,
                 VR_SITES_WKSP,
                 VR_RENTAL_CLASSES_WKSP,
                 VR_CUSTOMERS_WKSP;
 
     ACTION
         MOVE "RESERVE " TO VR_HIST_WKSP.TRANS_TYPE;
 
!+
! WRITE A RECORD TO THE HISTORY FILE TO LOG THE COMPLETED TRANSACTION
! - HISTORY RECORDS ARE RDB RECORDS (COULD BE ANY TYPE OF FILE SYSTEM
! OR DATABASE). THIS IS PART OF THE DISTRIBUTED TRANSACTION.
!-

     PROCESSING
 
         CALL PROCEDURE  VR_WRITE_HIST_RECORD_PROC
         IN      VR_LOG_SERVER
         USING   VR_HIST_WKSP,
                 VR_RESERVATIONS_WKSP;
 
!
! END OF DISTRIBUTED TRANSACTION
!
END BLOCK;
 
     ACTION  IS
         IF (ACMS$T_STATUS_TYPE = "G")
 
         THEN
                 COMMIT TRANSACTION;
                 MOVE "     " TO VR_SENDCTRL_WKSP.SENDCTRL_KEY,
                      "Y"     TO VR_CONTROL_WKSP.INCREMENT_RETRY_COUNT,
                       0      TO VR_CONTROL_WKSP.RETRY_COUNT;
         ELSE
                 ROLLBACK TRANSACTION;
                 GOTO STEP DISPLAY_CUST_INFO;
         END IF;
!
! EXCEPTION HANDLER FOR ABOVE BLOCK
!
! RETRY THE DISTRIBUTED TRANSACTION 5 TIMES (ONLY IF A 
! ACMS$_TRANSTIMEDOUT ERROR OCCURRED) BEFORE CANCELING TASK. 
! THE RETRY_COUNT IS INCREMENTED IN EITHER VR_STORE_CU_PROC 
! OR VR_WRITE_RS_PROC.
!
     EXCEPTION HANDLER
          IF (ACMS$L_STATUS = ACMS$_TRANSTIMEDOUT AND
              VR_CONTROL_WKSP.RETRY_COUNT < 5)
          THEN
             REPEAT STEP;
          ELSE
             GET MESSAGE INTO VR_CONTROL_WKSP.MESSAGEPANEL;
             MOVE "ACTWT" TO  VR_SENDCTRL_WKSP.SENDCTRL_KEY,
                  "     " TO VR_CONTROL_WKSP.CTRL_KEY;
             GOTO STEP DISP_STAT;
          END IF;
  

In this example, a nested block starts a distributed transaction and includes three processing steps. The first processing step checks to see if the user has changed any customer information. If one of the shadow workspaces indicates that information has changed, the processing step calls the VR_STORE_CU_PROC procedure to update the database.

The STORE_RESV step adds a reservation record to the reservation database. The third processing step updates a transaction log in another database.

If the three processing steps complete successfully, the action part of the nested block step commits the distributed transaction. If an error occurs that causes the distributed transaction to fail before completing, ACMS raises a transaction exception. The exception handler part of the nested block checks for the ACMS$_TRANSTIMEDOUT transaction exception code to see if the distributed transaction did not complete within the time limit specified in the application definition with the TRANSACTION TIMEOUT phrase.

If the ACMS$L_STATUS field contains the ACMS$_TRANSTIMEDOUT exception code, ACMS repeats the block step up to five times. If ACMS$L_STATUS contains any other exception code, or if the distributed transaction has already timed out five times, ACMS passes control to the DISP_STAT exchange step, which displays an error message, and ends the task.

If ACMS detects a step exception outside the bounds of a distributed transaction, ACMS first looks for an exception handler on the same step that raised the exception. If the current step does not include an exception handler, ACMS checks block steps out to the root block step for an exception handler. If ACMS does not find an exception handler, it cancels the task. If ACMS finds an exception handler, it stores the exception code in ACMS$PROCESSING_STATUS and performs the exception handler action clauses. If the exception handler does not specify how to handle the particular exception raised, ACMS searches out to the root block for another exception handler. If ACMS cannot find an exception handler that specifies how to handle the particular exception raised, ACMS raises a nonrecoverable exception and cancels the task. For example, if the exception handler specifies a recovery action only for the FORMS$_TIMEOUT exception code, and a different exception is raised, ACMS cancels the task.

If ACMS detects a step exception within a distributed transaction, ACMS searches for an exception handler on the current step. If the current step does not include an exception handler, ACMS searches any outer block steps within the distributed transaction. If ACMS finds an exception handler, ACMS performs the exception handler action clauses.

If ACMS does not find an exception handler, or if the exception is raised in a processing step that starts a distributed transaction, ACMS checks to see whether the distributed transaction was started by the current task, a parent task, or an agent. If the current task started the distributed transaction, ACMS aborts the distributed transaction and raises a transaction exception with the same exception code. If the current task is a called task that participates in a distributed transaction started by the parent task or an agent, ACMS cancels the current task and raises a transaction exception in the parent task, or returns the exception code to the agent.

As with step exceptions, when ACMS detects a transaction exception, it interrupts the task execution. If the task was not executing a COMMIT TRANSACTION clause when the transaction exception was raised, ACMS calls the server cancel procedure, if defined, for each server in which the task maintains context. If the task was executing COMMIT TRANSACTION, ACMS does not call any server cancel procedures. Before searching for an exception handler, ACMS releases context held in server processes.

ACMS then searches for an exception handler, starting on the step that started the distributed transaction and searching out to the root block.

If a step exception is raised, and the task definition does not include an exception handler to recover from the exception, ACMS raises a transaction exception or a nonrecoverable exception. If a distributed transaction was active when the step exception was raised, ACMS raises a transaction exception; otherwise, ACMS raises a nonrecoverable exception. ACMS then calls any server cancel procedures and cancels the task.

ACMS does not call server cancel procedures when a step exception is raised and the task definition includes an exception handler to recover from the exception.

PROCESSING
    CALL UPDATE_ORDER_IN ORDER_SERVER USING ORDER_RECORD;
 ACTION IS
    IF (ACMS$L_STATUS <> 1)
    THEN
       RELEASE SERVER CONTEXT;
       CANCEL TASK RETURNING ACMS$L_STATUS;
    END IF;

Because ACMS executes server context actions before sequencing actions, ACMS releases server context before canceling the task. Therefore, ACMS does not call server cancel procedures.

BLOCK WORK WITH DISTRIBUTED TRANSACTION
    PROCESSING
       CALL UPDATE_ORDER IN ORDER_SERVER
            USING ORDER_RECORD;
    ACTION IS
       IF (ACMS$L_STATUS <> 1)
       THEN
          EXIT BLOCK;
       END IF;
    PROCESSING 
       CALL WRITE_LOG_RECORD IN LOG_SERVER
            USING ORDER_RECORD;
 
END BLOCK;
ACTION IS
    IF (ACMS$L_STATUS = 1)
    THEN
       COMMIT TRANSACTION;
    ELSE
       ROLLBACK TRANSACTION;
       CANCEL TASK RETURNING ACMS$L_STATUS;
    END IF;

Example 8.6, ''Canceling a Task without Calling Server Cancel Procedures'' starts a distributed transaction on the block step. If the UPDATE_ORDER procedure returns a status value other than 1, ACMS passes control to the action part of the block step, rolls back the distributed transaction, and cancels the task. When ACMS processes the ROLLBACK TRANSACTION clause, the distributed transaction ends and ACMS releases server context. As a result, ACMS does not call server cancel procedures when it cancels the task.

When ACMS executes a COMMIT TRANSACTION clause, if a transaction exception is raised because the distributed transaction fails to prepare, ACMS does not call server cancel procedures.

In all other cases, if a transaction exception or a nonrecoverable exception is raised while the task maintains context in one or more server processes, ACMS calls server cancel procedures.

Once you have created a task queue using the ACMS Queue Manager (ACMSQUEMGR) Utility, you can queue tasks using the ACMS$QUEUE_TASK service. You place tasks onto the queue from either a step procedure or a standalone program that calls the ACMS$QUEUE_TASK service. Before calling ACMS$QUEUE_TASK, the task or standalone program gathers the information necessary to run the task. Before queuing the task, you might want to perform some of the processing, as well. If you want the queued task to be part of a distributed transaction, you must declare the start of the distributed transaction, either in the task definition by using the TRANSACTION phrase or in the standalone program by using the $START_TRANS service.

The ACMS$QUEUE_TASK service passes several parameters including the queue name (which cannot contain trailing spaces), the task name, the name of the application in which the task is to run, as well as the data to be passed in the workspaces. You can optionally include parameters that assign a priority to the queued task element, place the queued task element in a hold state (make it unavailable for dequeuing), supply a user name under which you want the task to run, and request that the ACMS$QUEUE_TASK service return a unique element ID of the queued task element. The ACMS$QUEUE_TASK service queues the task element and its parameters onto the specified queue.

Associated with each queued task element is an enqueuer user name. Provided that the QTI runs under a user name that has the ACMS agent privilege in the User Definition Utility (UDU) user authorization file, the QTI submits tasks under the enqueuer user name. Access to the task and access to the resources used by the task are granted or denied based on the access rights of this user name. By default, the enqueuer user name is the user name of the process that called the ACMS$QUEUE_TASK service. A user name other than the process user name can be passed to ACMS$QUEUE_TASK as the enqueuer user name if the process has the OpenVMS CMKRNL privilege.

As with the ACMS$QUEUE_TASK service, any process, including a procedure server process, can call the ACMS$DEQUEUE_TASK service. To have the dequeue operation coordinated with other resource manager operations, such as database updates, you must have declared the start of a distributed transaction, either in the task definition by using the TRANSACTION phrase or in the procedure by using the $START_TRANS system service. The most common use of the ACMS$DEQUEUE_TASK service is for taking queued task elements off an error queue, although it is possible to use this service to remove task elements from a task queue and perform your own processing rather than using the QTI. See Section 9.6, ''Using the QTI to Dequeue Tasks'' for more information on using the QTI.

You can dequeue tasks by highest priority (first-in-first-out within priority), by element ID, or sequentially. See ACMS$DEQUEUE_TASK for the list of parameters that you can include on the ACMS$DEQUEUE_TASK service. See Section 9.7, ''Processing Error Queues'' for an example of a procedure that uses the ACMS$DEQUEUE_TASK service to process error queues.

The next sections briefly explain these parameters. For more detail, see VSI ACMS for OpenVMS Managing Applications.

Example 9.1, ''Sample QTI Audit Entry'' shows a sample QTI audit entry.

************************************************************
Type   : COMMAND   Time   : 24-NOV-1987 16:50:28.38
User   : OPERATOR
Text   : Successful start for queue PAYROLL_QUEUE
************************************************************
Type   : ERROR     Time   : 24-NOV-1987 16:52:04.62
Queue  : PAYROLL_QUEUE
ErrQue : PAYROLL_ERROR_QUEUE
Elem Id: MYNODE::28000114-00000003-87A9ECE0-0090A5F7
Appl   : PAYROLL
Task   : HIRE_EMPLOYEE
User   : JONES
Text   : Error processing queued task
-ACMSQUE-E-ERRGETPROC, Error returned from ACMS$GET_PROCEDURE_INFO
-ACMS-E-NOSUCH_PKG, There is no such package defined
-ACMSQUE-I-QTRETRY, Queued task will be retried later
************************************************************

See Section 9.7, ''Processing Error Queues'' for information about how to process elements from an error queue.