HP OpenVMS Systems Documentation

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.

The following command creates the subprocess VIV_1 and transfers control of your terminal to that process:

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.

1.6.9 Using ADU Interactively

When you want to use ADU interactively, enter the CREATE or REPLACE command but do not include a source definition file specification. Then ADU displays the ADUDFN> prompt. For example:

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.

To enable logging, enter SET LOG in response to the ADU> prompt. You can specify the file you want ADU to use for logging:

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 Compaq ACMS for OpenVMS ADU Reference Manual for information about these commands.

1.6.10 Using the Language-Sensitive Editor to Create Definition Files

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 for information on using the COMPILE command.

To invoke LSE at the DCL prompt, issue the LSEDIT command followed by a file name with one of the following file extensions:

• .ADF -- Invokes LSE with the template for application definitions.
• .GDF -- Invokes LSE with the template for task group definitions.
• .TDF -- Invokes LSE with the template for task definitions.
• .MDF -- Invokes LSE with the template for menu definitions.
• .ADU -- Invokes LSE with a template for any of the four preceding ACMS definitions. You can include more than one type of ACMS definition in a file with a .ADU extension.

The following example invokes LSE to create or edit a file called UPDATE_TASK.TDF. The .TDF file type tells LSE to use the task definition template.

$ LSEDIT UPDATE_TASK.TDF

By default, the ADU EDIT and MODIFY commands invoke the EDT editor. You can change that default to automatically invoke LSE. The ACMS system logical, ADU$EDIT, points to a DCL command file that ADU runs when you invoke the utility. The command file, in turn, invokes the text editor that the EDIT and MODIFY commands use. The command file contains the following DCL code:

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

To invoke LSE automatically, replace the previous command lines with the following code:

$ 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 and VAX Language-Sensitive Editor and VAX Source Code Analyzer User Manual for more information on using LSE. Compaq ACMS Version 4.3 for OpenVMS Installation Guide contains information on installing ACMS with the LSE option.

1.7 Getting Help

When you are running ADU and need information about its commands and clauses, use the ADU HELP command. ADU HELP works the same way as HELP for the OpenVMS operating system. Enter HELP in response to the ADU> prompt:

ADU> HELP

ADU then displays a list of topics on which you can get help. When finished with the help information, press [Return] repeatedly until the ADU> prompt returns. To return immediately to the ADU> prompt, press [Ctrl/Z].

If you know the topic about which you want information, you can enter that topic after the HELP command. For example, if you want information on the CREATE command and you do not want to see the list of available topics, type:

ADU> HELP CREATE

ADU displays information about the CREATE command, and issues the CREATE Subtopic? prompt. At this prompt, you can type PARAMETERS for information about CREATE parameters or type QUALIFIERS to get information about its qualifiers. If you do not need any further information about CREATE, press [Return] once to return to the TOPIC prompt. Press [Return] twice to return to the ADU> prompt.

To return immediately to the ADU> prompt after obtaining information about a command or clause, use the /NOPROMPT qualifier:

ADU> HELP/NOPROMPT CREATE

ADU then displays information about the CREATE command. Rather than display the Topic prompt, however, ADU returns to the ADU> prompt so that you can continue the utility session.

For more information on help systems available in ACMS, consult the Preface.

Chapter 2 explains how you can use ADU syntax to define the components of an ACMS task. The examples in this chapter show tasks that a car rental agency might use in a typical car reservation transaction processing application.

2.1 Structure of an ACMS Task

The central part of a task definition is made up of a sequence of exchange and processing steps that are grouped into a block step.

In a simple data entry task, there is just one exchange of information with the terminal user and one processing step. Therefore, you define the task to have just two steps within the block step. You can use the ACMS Application Definition Utility (ADU) to define three parts for each block, exchange, and processing step:

• Attributes that describe processing characteristics for the steps in the block
• Work done in the step
• Action taken as a result of that work

The work of a block step consists of the exchange and processing steps that it contains. The task itself contains overall characteristics that affect the block step and its work. Figure 2-1 shows the structure of a task definition and, in addition to an exchange and processing step, includes a block step that contains attributes and actions taken as a result of the work done.

Figure 2-1 Structure of a Task Definition

A data entry task can record information about a car reservation, a new part in inventory, or a day's events. This section discusses the case of adding information to a database. The name of this sample task is Add Car Reservation task.

A simple data entry task requires just one exchange step and one processing step. To display errors that might occur during the data entry task, you might want to add another exchange step to the task definition. Table 2-1 summarizes the steps and keywords you use to describe each step in the task definition.

To begin the task definition, you can assign names, or labels, to these steps. In the Add Car Reservation task, the step labels are GET_RENTAL_INFORMATION, WRITE_RESERVATION_INFORMATION, and ERROR_PROCESS_MSG:

You need a step label only if the step is referred to by name elsewhere in the task definition. However, step labels often help you to identify the function of steps in a definition.

GET_RENTAL_INFORMATION:
  EXCHANGE ...
WRITE_RESERVATION_INFORMATION:
  PROCESSING ...
ERROR_PROCESS_MSG:
  EXCHANGE...

You can use any step labels you want. A step label begins with an alphabetic character and can contain as many as 31 alphanumeric characters, including dollar signs ($) and underscores (_). A step label cannot contain spaces. You follow the step label with a colon (:) and the definition for that step.

Always use the keywords EXCHANGE and PROCESSING to identify the type of step you are defining. The GET_RENTAL_INFORMATION and the ERROR_PROCESS_MSG steps are exchange steps, and the WRITE_RESERVATION_INFORMATION step is a processing step.

You use the TRANSCEIVE clause in an exchange step to accomplish two operations, a send followed by a receive. First, the TRANSCEIVE clause instructs DECforms to display a panel asking the terminal user for information about the customer's car reservation plans. Then the TRANSCEIVE clause instructs DECforms to return that information in an ACMS workspace.

GET_RENTAL_INFORMATION:
  EXCHANGE
    TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC...
WRITE_RESERVATION_INFORMATION:
  PROCESSING ...

In this example, the name of the DECforms form record is ADD_RESERVE_FORM_REC. This is the name of the run-time form record definition in the form; it is not a CDD path name or CDD given name. DECforms uses the form record as a map of form data items and their corresponding workspace fields when transferring data between the form and your task.

You can use a task definition to identify the form in which a form record belongs. If you do not name a form, ACMS uses the first form named in the task group definition. Chapter 10 explains how to define task groups. The Compaq ACMS for OpenVMS ADU Reference Manual explains in detail how to name forms as part of the exchange step.

In DECforms, you use the Form Development Environment (FDE) to create a form. Based on your input, the FDE generates an Independent Form Description Language (IFDL) file. Because of the length of the IFDL code, this chapter does not show the definition of the ADD_RESERVE_FORM that this data entry task uses. When the terminal user fills in the fields of a DECforms panel and presses [Enter], the DECforms passes the data from the form data items to their corresponding fields in your application workspaces. See DECforms Guide to Developing an Application for more information on defining forms.

After a form displays a panel that gets information from the terminal user, the first part of the task is done. To do the second part of the data entry task, you call an ACMS procedure to write that information to the database. A procedure server contains procedures, or subroutines. You call the procedure in the processing step:

GET_RENTAL_INFORMATION:
  EXCHANGE
    TRANSCEIVE FORM RECORD ADD_RESERVE_FORM_REC, ADD_RESERVE_FORM_REC...
WRITE_RESERVATION_INFORMATION:
  PROCESSING
    CALL WRITE_RESERVE_PROC IN RESERVE_SERVER...
 END BLOCK WORK;
END DEFINITION;

You use the CALL clause to name the procedure you want to run. In this example, the procedure named WRITE_RESERVE_PROC is the program, entry point, or routine name, such as the Program-ID for a COBOL subprogram; it is not a CDD path name, CDD given name, or file name. Compaq ACMS for OpenVMS Writing Server Procedures explains in detail how to write a procedure to run in the processing step of a multiple-step task.

As part of the CALL clause, you also name the server that contains the step procedure to run. When you include the server name, you use the name assigned to the server in the SERVERS ARE clause of the task group definition. This clause is explained in Chapter 10.

The name of the server that includes the procedure WRITE_RESERVE_PROC is RESERVE_SERVER. If a task contains many processing steps, and they all use the same server, you can define a default server for the task. Compaq ACMS for OpenVMS ADU Reference Manual explains how to define a default server for a task.

2.2.1 Using Workspaces to Pass Data Between Steps

After you get the information from the terminal user, you need to transfer the information to the procedure so that the procedure can write it to the database. This process consists of two steps:

1. You use workspaces to pass the information from the form that collects it.
2. A procedure receives the information from the workspaces and writes it to the database.

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 shows how the form and the procedure use the workspace to pass information.

Figure 2-2 The Workspace Used to Pass Information

Both the form and the procedure in the definition use the workspace: the form stores the information supplied by the terminal user in the workspace, the procedure reads the information from the workspace and writes it to the database. To define a workspace record in CDO, you must define the fields separate from the record. Example 2-1 shows the definition of the ADD_RESERVE_WKSP workspace.

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

When you define the ADD_RESERVE_FORM form using DECforms, the form data items must correspond to the fields in the ADD_RESERVE_WKSP definition. At run time, DECforms uses the form record to map form data items to workspace fields. The easiest way to define the form record in your IFDL code is to include a statement that instructs DECforms to copy the workspace definition from the CDD dictionary into the IFDL file:

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 does not have to be ADD_RESERVE_WKSP. See the Compaq 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.

Suppose that the full CDD path name of the record description for the workspace is DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.ADD_RESERVE_WKSP. When you are writing step definitions, you use only the given name of the record description for a workspace, ADD_RESERVE_WKSP. For example:

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.

You may want to use the same record definition for more than one workspace and assign different workspace names to that record definition. When you first declare the workspace in the task definition, you can assign a unique name to that workspace. For example:

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

To refer to this workspace from within the task definition, you use the unique 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.