HP OpenVMS Systems Documentation

Compaq ACMS for OpenVMSWriting Applications

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.

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.

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:

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.

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.

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.

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.

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.

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:

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.

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:

You use workspaces to pass the information from the form that
collects it.

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.

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:

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: