# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# SET VERIFY (ADU>)

> Displays commands and source definitions as they are processed from a command file you execute with the @ (at sign) command. The SET VERIFY command is useful in showing which commands, clauses, or phrases in source files compile with syntax errors.

> The SET VERIFY command also writes batch input commands and source definitions to the batch log. The SET NOVERIFY command suppresses the display.

## Format

> SET VERIFY

> SET NOVERIFY

## Default

> SET NOVERIFY is the default in interactive mode. SET VERIFY is the default in batch mode.

## Note

> When you turn on or turn off verification, the setting stays in effect until the end of the ADU session or until you change the setting again.

##

### Examples

#1
    ADU> SET VERIFY
    ADU> @CMDFILE.COM
    SET LOG
    SHOW LOG
    logging to file EXAMPLES$:[EXAMPLES]ADULOG
    ADU>

> This example displays the commands that ADU runs from the indirect command file CMDFILE.COM. ADU displays each command as it processes the command file. As the example shows, the two commands in the command file CMDFILE.COM were SET LOG and SHOW LOG. The log file ADULOG.LOG is on the default device pointed to by the logical EXAMPLES$, and in the default directory EXAMPLES. After processing the command file, ADU returns you to the ADU> prompt.

#2
    ADU> SET NOVERIFY
    ADU> @CMDFILE.COM
    ADU>

> This SET NOVERIFY command prevents the display of commands and definition clauses that ADU processes from the CMDFILE.COM indirect command file.

# SHOW DEFAULT (ADU>)

> Displays your current default dictionary directory.

## Format

> SHOW DEFAULT

## Notes

> You can change the CDD default directory by using:
> - ADU SET DEFAULT while you are using ADU
> - DCL DEFINE in your LOGIN.COM file to set the logical CDD$DEFAULT to the new default directory
> - The /PATH qualifier with the MCR ACMSADU or ADU startup command
> - ADU SET DEFAULT in your ADUINI.COM file

##

### Examples

#1
    ADU> SHOW DEFAULT
    current CDD default path is 'DISK1:[CDDPLUS]BIGGS'
    ADU>

> The SHOW DEFAULT command shows that the current default setting for CDD$DEFAULT is DISK1:[CDDPLUS]BIGGS.

#2
    ADU> SET DEFAULT DISK1:[CDDPLUS]BIGGS.APPLICATION
    ADU> SHOW
    Show What        : DEFAULT
    current CDD default path is 'DISK1:[CDDPLUS]BIGGS.APPLICATION'
    ADU>

> This SET DEFAULT command assigns DISK1:[CDDPLUS]BIGGS.APPLICATION as the default CDD path name. If you press `[Return]` immediately after the SHOW command, ADU prompts you for the command keyword. Enter DEFAULT at the prompt to check the current dictionary default.

# SHOW LOG (ADU>)

> Displays information about logging, which you enable with the SET LOG command. Use this command to see if logging is taking place and to find the name of the file where you are logging data.

## Format

> SHOW LOG

## Notes

> If logging is not active, the SHOW LOG command displays a message about the current file specification. The SET LOG command uses that file specification the next time you enable logging, unless you name a new file.

##

### Examples

#1
    $ ADU
    ADU> SET LOG
    ADU> SHOW LOG
    logging to file EXAMPLES$:[EXAMPLES]ADULOG
    ADU> SET LOG LOGFILE.LOG
    ADU> SHOW LOG
    logging to file EXAMPLES$:[EXAMPLES]LOGFILE.LOG;1
    ADU>

> The SET LOG command uses the default file ADULOG.LOG in your default directory. The second SET LOG command includes a file name, LOGFILE.LOG. This file remains the log file until you either exit ADU or assign another file. Reassign the default log file ADULOG.LOG by naming that file again with the SET LOG command.

#2
    $ ADU
    ADU> SET LOG
    ADU> SHOW LOG
    logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;1
    ADU> SET NOLOG
    ADU> SHOW LOG
    not logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;1
    ADU> SET LOG
    logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;2
    ADU>

> This example shows that the SET LOG command increases the version number of the default log file each time you enable logging. The SHOW LOG command indicates when logging is active and when it is not.

# SHOW VERSION (ADU>)

> Displays the current software version number of ADU.

## Format

> SHOW VERSION

## Note

> The SHOW VERSION command displays the version number in the form:

>     ACMS ADU Vn.n

##

### Examples

#1
    $ ADU
    ADU> SHOW VERSION
    ACMS ADU V4.2
    ADU>

> In this example, the SHOW VERSION command displays the current ADU version number and returns control to the ADU> prompt.

#2
    $ ADU
    ADU> SHOW
    Show what        : VERSION
    ACMS ADU V4.2
    ADU>

> ADU displays a prompt when you press `[Return]` immediately after you enter the SHOW command. Enter the VERSION keyword to get a display of the current ADU version number.

# SPAWN (ADU>)

> Creates a subprocess of the current process and transfers control of your job to the subprocess. Use this command to leave ADU temporarily to perform other tasks without exiting ADU.

## Format

> SPAWN [command] [/qualifiers]

> Command Qualifiers | Defaults
> --- | ---
> /INPUT [=file-spec] | /INPUT=SYS$INPUT
> /[NO]LOGICAL_NAMES | /LOGICAL_NAMES
> /OUTPUT [=file-spec] | /OUTPUT=SYS$OUTPUT
> /NOOUTPUT |
> /PROCESS [=subprocess-name] |
> /[NO]SYMBOLS | /SYMBOLS
> /[NO]WAIT | /WAIT

## Parameter

> ### command

> The DCL command to be executed in the subprocess that the SPAWN command creates. After executing the DCL command, the subprocess ends and control returns to ADU. If you do not specify a command, ADU presents you with a DCL prompt.

## Qualifiers

> ### /INPUT [=file-spec]

> Names a file containing DCL commands to be executed in the subprocess. If you do not specify an input file with the /INPUT qualifier, the subprocess accepts input from the terminal (SYS$INPUT).

> If you specify input from both a command and a file, the subprocess executes the command first, then the file.

> ### /[NO]LOGICAL_NAMES

> Tells ADU to copy all the logical names of the parent process to the subprocess. It is faster to create a subprocess without copying the logical names.

> The default is /LOGICAL_NAMES.

> ### /OUTPUT [=file-spec]
> /NOOUTPUT

> Names the file to contain output from the subprocess that the SPAWN command creates. If you do not use the /OUTPUT qualifier, the subprocess directs output to the terminal (SYS$OUTPUT).

> The /NOOUTPUT qualifier suppresses all output from the subprocess.

> If you direct output to the terminal, specify the /NOWAIT qualifier to delay the display of output while you are entering commands.

> By default, the subprocess sends output to the terminal.

> ### /PROCESS [=subprocess-name]

> Specifies the name of the subprocess to be created.

> USERNAME_n is the default subprocess name if you do not include the qualifier.

> ### /[NO]SYMBOLS

> Tells the system whether or not to pass DCL global and local symbols to the subprocess.

> The default is /SYMBOLS.

> ### /[NO]WAIT

> Controls whether or not the system waits until the current subprocess is completed before allowing more commands to be issued in the parent process.

> Use the /NOWAIT qualifier with the /OUTPUT qualifier so output from the subprocess goes to a file, not your terminal. Otherwise, output from the subprocess interrupts output from your parent process.

> The default is /WAIT.

## Notes

> Use the SPAWN command when you need to read mail, check the contents of an OpenVMS file, or run a different utility without exiting ADU. If you return to your ADU session by logging out of the subprocess, the subprocess is terminated. To return to your ADU session without terminating the subprocess, use the DCL ATTACH command. You can then return to your subprocess from ADU with the ADU ATTACH command.

> Use the ADU SPAWN command the way you use the DCL SPAWN command.

##

### Examples

#1
    ADU> SPAWN
    $

> The SPAWN command creates a subprocess and transfers control of your job to that process.

#2
    ADU> SPAWN TYPE VR_RENTAL_CLASSES_WKSP.CDO
    !
    !                       VR_RENTAL_CLASSES_WKSP.CDO
    !
    DEFINE RECORD AVERTZ_CDD_WKSP:VR_RENTAL_CLASSES_WKSP
      DESCRIPTION IS /* This workspace maps the fields in the */
                     /* RENTAL_CLASSES table in the VEHICLE_RENTALS */
                     /* database.  This is a small table that is used */
                     /* to keep track of the 3 AVERTZ types of vehicles -- */
                     /* economy, mid-size, and full-size.  This workspace */
                     /* is used to pass data between the forms and */
                     /* procedures. */.
            AVERTZ_CDD_FIELD:COUNTRY_ID.
            AVERTZ_CDD_FIELD:REQUESTED_RENTAL_CLASS_ID.
            AVERTZ_CDD_FIELD:DAY_RENTAL_RATE_AMT.
            AVERTZ_CDD_FIELD:WEEK_RENTAL_RATE_AMT.
            AVERTZ_CDD_FIELD:MONTH_RENTAL_RATE_AMT.
    END RECORD.
    ADU>

> In this example, ADU creates a subprocess and executes the DCL command TYPE VR_RENTAL_CLASSES_WKSP.CDO. Because the SPAWN command does not include the /NOWAIT qualifier, ADU waits for the command to execute before returning control to the parent process, thus terminating the subprocess.

#3
    ADU> SPAWN/NOWAIT/OUTPUT=LIST_FORM.LOG FDU LIST FORM PERSONNEL_FORM
    ADU>

> In this example, ADU creates a subprocess and executes the FDU command LIST FORM PERSONNEL_FORM in that process. The /NOWAIT qualifier allows you to issue commands to ADU without waiting for the subprocess to complete. The /OUTPUT qualifier specifies that output from the FDU command is written to the LIST_FORM.LOG file.

# Chapter 2
%INCLUDE

Many definitions share common parts. For example, suppose you always include certain default characteristics in an application definition. Instead of rewriting the same part of a definition many times, you can use %INCLUDE to put the contents of a file in a source definition.

# %INCLUDE

> Includes the contents of a file in a source definition. The %INCLUDE directive saves you from repeating clauses you use in many definitions; you can place the clauses in a file and use %INCLUDE to bring them into the source definition.

## Format

> %INCLUDE "file-spec"

## Parameter

> ### file-spec

> The name of the file containing the information you want to include in another definition. You must enclose the file specification in quotation marks (" "). The default file type is .COM. If you do not name a device and directory, ACMS searches your default device and directory for the file you name.

## Notes

> The percent sign (%) differentiates %INCLUDE from definition keywords, component names, and component identifiers you can use in the definition.

> Text in a file that you want to include in a definition at a later time must follow the same syntax rules as it would if it were part of the source at that point in the definition.

> The %INCLUDE directive can appear on any line before the END DEFINITION keywords.

> If you have used the SET LOG command, ADU puts the text of the include file in the log beginning with !%INC>.

> If you specify that a list file be created, ADU puts the text of the file named with %INCLUDE and any associated error messages in the list file. It also shows that the text originated from the included file.

## Example

    ADU> CREATE APPLICATION PERSONNEL
    ADUDFN> %INCLUDE "PERSAPPL.COM"

> In this example, ACMS uses the contents of the PERSAPPL.COM file in the current default device and directory to create the definition for the Personnel application.

# Chapter 3
Task Definition Clauses

This chapter explains the ADU clauses you use to write task definitions. You use these clauses with the CREATE, MODIFY, REPLACE, or EDIT commands.

A task definition is made up of clauses describing the attributes of a task and the work done when a user selects a task. Task attribute clauses can define either the implementation characteristics or the control attributes of a task.

Task attribute clauses describe general characteristics of a task such as the workspaces used by task steps or a default server that handles processing work. You can override some characteristics by specifying the same clause with a different attribute in a step definition.

The work part of a task is defined in either a processing step or a block step made up of processing and exchange steps. You can define a single-step task or use the BLOCK WORK clause to define multiple-step tasks.

Valid characters for task identifiers include the following:

- A through Z
- a through z
- 0 through 9
- Dollar sign ($)
- Underscore ()

If you use an invalid character in an ACMS definition, ADU terminates after giving the following error message:

    %ACMSTDU-F-TKN_INVALID, Invalid token class 1 detected by
    PARSER-CMU-F-INROUTINE, error detected in routine <routine-name>

Table 3-1 lists the task clauses and gives a brief description of each.

Table 3-1 Task Clauses
Clause | Description
--- | ---
Task Implementation Attribute Clauses
DEFAULT FORM | Names a default DECforms form used by the SEND, RECEIVE, and TRANSCEIVE clauses in exchange steps of a task.
DEFAULT REQUEST LIBRARY | Names a default TDMS request library used by exchange steps in a task.
DEFAULT SERVER | Names a default server to handle processing steps and canceling actions in a task.
USE WORKSPACES | Names one or more group-level workspaces the task uses.
WORKSPACES | Declares one or more workspaces used by steps in the task.
Task Control Attribute Clauses
DELAY | Causes a three-second delay before ACMS clears the final screen the task displays.
WAIT | Causes ACMS to wait for the user to press `[Return]` before clearing the final screen a task displays.
Task-Call-Task Attribute Clauses
GLOBAL | Specifies that a task can either be selected from a menu or called by another task.
LOCAL | Specifies that a task can be called by or chained to another task, but cannot be selected from a menu.
CANCELABLE | Specifies whether a task can be canceled by a task submitter.
TASK ARGUMENTS | Specifies the list of workspaces that are passed to a task during a Task-Call-Task operation or by an agent calling a task.
Task Work Clauses
BLOCK | Describes, in terms of block, exchange, processing, and action clauses, the work done in a block step.
EXCHANGE | Describes the work done to interact with the terminal user, typically through DECforms form records.
PROCESSING | Describes the computation and database I/O work that the task performs.

Figure 3-1 shows the syntax you use to define a task.

Figure 3-1 Task Syntax

If a task consists of a single processing step, you must use the PROCESSING clause in the task definition to describe the work done by the task. However, if the task contains multiple steps or an exchange step, you must use the BLOCK clause to describe the work done by the task. You can use an EXCHANGE clause only within a block step.

The following examples illustrate how to use the clauses described in this chapter to write task definitions. Example 3-1 shows the definition for a single-step task. The definition for the task is stored in the dictionary as DTR_TASK in the default CDD directory.

Example 3-1 Simple Task Definition (Single-Step)

    REPLACE TASK DTR_TASK
      DELAY;
      PROCESSING IS DCL COMMAND "MCR DTR32" IN UTILITY_SERVER;
    END DEFINITION;

When a user selects this task from a menu, ACMS processes the DCL command MCR DTR32, which runs DATATRIEVE. Because this is a DCL command, the task must run in a DCL server. You can also define single-step tasks that use procedure servers. The DELAY clause causes ACMS to wait 3 seconds before clearing the final screen of the task and returning the user to a selection menu.

Note Although you can write single-step task definitions, it is more efficient to use multiple-step tasks. ACMS also lets you define single-step processing tasks in the task group definition. Example 4-1 shows how to do this.

Example 3-2 shows an example of a multiple-step task definition. REVIEW_SCHEDULE_TASK is an inquiry task that lets the terminal operator view employees' performance review schedules.

The task definition contains three steps grouped into a block step. The workspaces REVIEW_SCHEDULE_WKSP and CONTROL_WKSP are available to all the steps in the block. The default form that contains the form records used by exchange steps in the block is DEPART_FORM. The keywords BLOCK WORK signal the beginning of the work done in the block. FORM I/O indicates that the exchange steps in the block use DECforms as the interface to the terminal operator.

Example 3-2 More Complex Task Definition (Multiple-Step)

    REPLACE TASK REVIEW_SCHEDULE_TASK

      DEFAULT FORM IS DEPART_FORM;
      WORKSPACES ARE REVIEW_SCHEDULE_WKSP, CONTROL_WKSP;

      BLOCK
        WORK WITH FORM I/O

    (1)GET_DEPT_NUMBER:
           EXCHANGE
           TRANSCEIVE FORM RECORD REVIEW_SCHEDULE_REC,
                                  REVIEW_SCHEDULE_REC
               SENDING REVIEW_SCHEDULE_WKSP
               RECEIVING REVIEW_SCHEDULE_WKSP
               WITH RECEIVE CONTROL CONTROL_WKSP;
             CONTROL FIELD IS CONTROL_WKSP.CTRL_KEY
               " FEXT"    : EXIT TASK;
             END CONTROL FIELD;

    (2)GET_FIVE_EMPLOYEES:
           PROCESSING
             CALL REVIEW_SCHEDULE_GET IN DEPARTMENT_SERVER
               USING REVIEW_SCHEDULE_WKSP;
             CONTROL FIELD ACMS$T_STATUS_TYPE
               "B"        : GET ERROR MESSAGE;
                            GOTO PREVIOUS EXCHANGE;
             END CONTROL FIELD;

    (3)DISPLAY_EMPLOYEES:
           EXCHANGE
             SEND FORM RECORD REVIEW_SCHEDULE_REC
               SENDING REVIEW_SCHEDULE_WKSP
               WITH RECEIVE CONTROL CONTROL_WKSP;
             CONTROL FIELD IS CONTROL_WKSP.CTRL_KEY
               " FMOR"    : GOTO PREVIOUS PROCESSING;
               " FEXT"    : EXIT TASK;
             END CONTROL FIELD;

       END BLOCK WORK;
       ACTION
         REPEAT TASK;
     END DEFINITION;

The following numbered explanations correspond to the numbers in Example 3-2:

Previous | Next | Contents | Index