# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# Chapter 1
Application Definition Utility Commands

Use Application Definition Utility (ADU) commands to create or change the definitions an ACMS application uses, or to monitor your own work or that of an ACMS application. You can issue ADU commands interactively or in a command file.

To create an ACMS application, you can use ADU commands to reset your Oracle CDD default directory during a session, and write, change, copy, delete, and compile definitions for tasks, task groups, menus, and applications. Other ADU commands let you build or rebuild task group, menu, and application database files.

To gather information about your work, you can use ADU commands to check the version of ADU on your system, log an interactive session to a file in your default directory for later reference, check if logging is active, and verify the work a command file performs during execution. To gather information about an ACMS application, you can use ADU commands to list the contents of task group, application, or menu database files, so you can check the consistency of procedure names, workspaces, and servers.

# 1.1 Explanations of Reference Page Terminology

The reference pages in this and in the remaining chapters contain explanations of clauses, commands, or phrases. The following list explains the terms used in those explanations:

Name | Lists the name of the clause, command, or phrase in bold
Description | Explains what the clause, command, or phrase does
Format | Lists the syntax of the clause, command, or phrase, including optional and required parts
Keywords | List and explain ACMS reserved words
Parameters | List and explain the parts of a clause, command, or phrase you must supply
Default | Explains what ACMS does if you omit an optional clause, command, or phrase
Qualifiers | List and explain modifiers and defaults for the commands
Notes | List additional information about clauses, commands, or phrases
Examples | List and explain sample clauses, commands, or phrases

The commands and clauses are listed by alphabetical order in each chapter or section. In the reference chapters, reference information about each clause, command, or phrase begins at the top of a new page.

# 1.2 Starting and Stopping ADU

This section explains how to invoke the Application Definition Utility (ADU) and exit from it.

## 1.2.1 Starting ADU

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.

The three ways to start ADU are:

- By using the MCR command
  Start ADU by entering the following command at the DCL prompt:

      $ MCR ACMSADU
      ADU>

  Include startup command qualifiers on the MCR ACMSADU command line.
- By defining a foreign command
  Define a foreign command in your LOGIN.COM file to invoke ADU. Then, whenever you enter that command at the DCL prompt, you are in ADU.
  Before using the foreign command ADU to invoke the utility, put the following definition in your LOGIN.COM file. Then process the LOGIN.COM by entering @LOGIN.COM at the DCL prompt to make the foreign command available for the current session. After the current session, the command is automatically defined whenever you log in.
  The following definition creates ADU as the foreign command to invoke the utility:

      $ ADU :== $ACMSADU

  After defining the foreign command and processing the login file, enter ADU at the DCL prompt to invoke the utility:

      $ ADU
      ADU>

  Include startup command qualifiers on the command line by using the command:

      $ ADU /COMMAND=RESERVATIONS

- By using the RUN command
  Enter the RUN command at the DCL prompt to invoke ADU:

      $ RUN SYS$SYSTEM:ACMSADU
      ADU>

  Do not include ADU command qualifiers when invoking the utility with the RUN command.

Table 1-1 lists the startup command qualifiers and their functions. Use these qualifiers when invoking ADU with the MCR command or a foreign command.

Table 1-1 Startup Qualifiers and Their Functions
Qualifier | Function
--- | ---
/COMMAND [=file-spec] /NOCOMMAND | Tells ADU whether or not to execute a startup command file when you invoke the utility. By default, when you invoke ADU, it runs a command file named ADUINI.COM, located in your default directory. To invoke a different startup command file, include its file specification with the /COMMAND qualifier. When you specify the /NOCOMMAND qualifier, ACMS starts the ADU without executing any startup command file.
/JOURNAL /NOJOURNAL | By default, ADU creates a journal file that contains every keystroke made during your ADU session. The journal file, named ADUJNL.JOU, is located in your default directory. The journal file is saved if your ADU session is interrupted. When you exit normally (by using the EXIT command or entering `[Ctrl/Z]`), the journal file is not saved. Use the /NOJOURNAL qualifier to turn off the journaling feature.
/PATH=path-name | Assigns a CDD directory. If you do not specify a path name, ADU uses the default CDD directory.
/RECOVER /NORECOVER | If you specify the /RECOVER qualifier, ADU runs the journal file, ADLJNL.JOU, to restore an ADU session that has ended abnormally. With /RECOVER in effect, ADU replays the interrupted session to recover your work. /NORECOVER is the default.

## 1.2.2 Stopping ADU

There are three methods to stop the ADU utility. Two methods result in an orderly exit from the utility. The third method causes an abrupt exit and should be used only when the other methods fail. Table 1-2 lists the ways to end an ADU session.

Table 1-2 Ways to Exit from ADU
Command | Meaning
--- | ---
EXIT | Ends your ADU session and returns control to the DCL command level without issuing any messages. Using the EXIT command produces the same results as pressing `[Ctrl/Z]`. When you create a file of ADU commands to automatically run a session, enter only the EXIT command in the file to terminate the automated session.
`[Ctrl/Z]` | Ends your ADU session and returns control to the DCL command level without issuing any messages.
`[Ctrl/Y]` | Abruptly ends your ADU session and returns control to the DCL command level without displaying any messages. Using `[Ctrl/Y]` can leave your definitions in an inconsistent state; so, use this method of exiting from ADU only when other methods fail.

# 1.3 Command Summary

This section summarizes the ADU commands and qualifiers. Table 1-3 lists the ADU commands and qualifiers, and describes their functions.

Table 1-3 Summary of ADU Commands
Commands and Qualifiers | Function
--- | ---
@(At sign) | Runs a file containing utility commands and/or clauses. The commands in the file run as if you typed them interactively.
ATTACH | Permits you to switch control of your terminal from your current process to another process in your job.
BUILD /AUDIT [=audit-list] /NOAUDIT /[NO]DEBUG /LIST [=list-file-spec] /NOLIST /[NO]LOG /OBJECT=(file-spec [,...] ) /NOOBJECT /[NO]PRINT /[NO]STDL /[NO]SYSLIB /[NO]SYSSHR /USERLIBRARY=(file-spec [,...] ) /NOUSERLIBRARY | Creates a database file that ACMS can use at run time.
COMPILE /DIAGNOSTICS [=diagnostics-file-spec] /NODIAGNOSTICS /LIST [=list-file-spec] /NOLIST /[NO]LOG /OUTPUT [=output-file-spec] /[NO]OUTPUT /[NO]PRINT | Checks an application, task group, menu, or task definition for syntax errors, and writes the compilation results to a file.
COPY /AUDIT [=audit-list] /NOAUDIT /[NO]LOG | Creates a copy of an application, menu, task, or task group definition from the dictionary and stores it with a new name in a new location in the dictionary.
CREATE /AUDIT [=audit-list] /NOAUDIT /DIAGNOSTICS [=diagnostics-file-spec] /NODIAGNOSTICS /LIST [=list-file-spec] /NOLIST /[NO]LOG /[NO]PRINT | Checks and stores valid application, task, or task group definitions in the dictionary.
DELETE /[NO]CONFIRM /[NO]LOG | Removes an application, menu, task, or task group definition from the dictionary.
DUMP /OUTPUT [=file-spec] /NOOUTPUT /[NO]PRINT | Displays the contents of an application, menu, or task group database file.
EDIT | Recalls the last command you typed, including any definition source, and starts a text editor, making the command or command and definition available for change.
EXIT | Ends the ADU session and returns you to the DCL prompt.
HELP /[NO]PROMPT | Displays information about ADU commands and clauses.
LINK /[NO]DEBUG /LIST [=list-file-spec] /NOLIST /[NO]LOG /OBJECT=[(] file-spec [,...] [)] /NOOBJECT /OPTION=option-file-spec /[NO]PRINT /REFERENCED_OBJECT_DEFAULT=default-file-spec /[NO]SYSLIB /[NO]SYSSHR /USERLIBRARY=[(] file-spec [,...] [)] /NOUSERLIBRARY | Converts object definitions from OpenVMS files into binary database files that ACMS uses at run time.
LIST /OUTPUT [=file-spec] /NOOUTPUT /[NO]PRINT | Displays the specified application, menu, task, or task group definition stored in the dictionary.
MODIFY /AUDIT [=audit-list] /NOAUDIT /DIAGNOSTICS [=diagnostics-file-spec] /NODIAGNOSTICS /LIST [=list-file-spec] /NOLIST /[NO]LOG /[NO]PRINT | Recalls an object definition from the dictionary and runs a text editor so you can change the definition.
REPLACE /AUDIT [=audit-list] /NOAUDIT /[NO]CREATE /DIAGNOSTICS [=diagnostics-file-spec] /NODIAGNOSTICS /LIST [=list-file-spec] /NOLIST /[NO]LOG /[NO]PRINT | Creates a new definition and replaces the old definition with the new one.
SAVE | Puts the last command you typed, including any definition source, in the file you specify.
SET DEFAULT | Sets the default directory in the dictionary.
SET LOG [file-spec] SET NOLOG | Enables or disables utility logging. Logs information about the utility session to the default log file or to a file you specify.
SET VERIFY SET NOVERIFY | Enables or disables the display of commands ADU processes from an indirect command file.
SHOW DEFAULT | Displays your current dictionary default directory.
SHOW LOG | Displays whether utility logging is enabled or disabled and what the log file is.
SHOW VERSION | Displays the version number of the utility.
SPAWN /INPUT [=file-spec] /[NO]LOGICAL_NAMES /OUTPUT [=file-spec] /NOOUTPUT /PROCESS [=subprocess-name] /[NO]SYMBOLS /[NO]WAIT | Creates a subprocess of the current process. Can be used to leave ADU temporarily to execute a DCL command or run an OpenVMS image.

# 1.4 Common ADU Command Qualifiers

Several commands share common ADU qualifiers:

- The /AUDIT and /NOAUDIT command qualifiers are common to the BUILD, COPY, CREATE, MODIFY, and REPLACE commands.
- The /LIST and /NOLIST command qualifiers are common to the BUILD, COMPILE, CREATE, LINK, MODIFY, and REPLACE commands.
- The /[NO]LOG command qualifier is common to the BUILD, COMPILE, COPY, CREATE, DELETE, LINK, MODIFY, and REPLACE commands.
- The /[NO]PRINT command qualifier is common to the BUILD, COMPILE, CREATE, DUMP, LINK, LIST, MODIFY, and REPLACE commands.

Descriptions of these command qualifiers are listed here rather than under each command in the reference pages.

> ### /AUDIT [=audit-list]

> ### /NOAUDIT

> Stores audit history information about the definition you are using.

> The [=audit-list] parameter specifies either the audit information or where it comes from. The audit information can come from a default history list ADU supplies, from either the word or string specified in the audit-list parameter itself, or from the contents of one or several files specified in the audit-list parameter. The audit information can also come from a combination of these items.

> The following list explains the audit information you can specify as an audit-list parameter:

> - Single-word audit text:

>       /AUDIT=VERSION1

>   In this example, the audit information comes from the single word that follows the qualifier. Quotation marks (" ") are optional because the text is one word.
> - Multiple-word audit string:

>       /AUDIT="This is version 1"

>   In this example, the audit information comes from the multiple-word string that follows the qualifier. Quotation marks (" ") are required if the audit text contains spaces or special characters.
> - File specification:

>       /AUDIT="@YOURDISK:[USER2]AUDIT.TXT"

>   In this example, the audit information comes from the contents of a file. ADU interprets each line of the file as an audit string. The file specification must be introduced with an at sign (@) and enclosed in quotation marks (" ").
> - List of strings and/or file specifications:

>       /AUDIT=(VERSION1,"Bryan's Version","@EXTRAUD.SRC")

>   In this example, the audit information comes from a single word, a string, and a file. The entire list must be enclosed in parentheses. The items in the list must be separated with commas.

> ADU does not accept more than 64 lines, entries, or records in an audit list or in an audit string you specify in an audit file specification.

> The default history list entry that ADU supplies includes:

> - Operation the command performed
> - Name of the user
> - User UIC and process name
> - Name of the utility
> - Date and time of the operation

> The following example shows the default audit history list that accompanies an ADU BUILD command:

>     Build by MORRISSEY (UIC [MORRISSEY]) in process MORRISSEY using
>         ACMS ADU V4.0 on  9-MAR-1994 14:19:77.94 for program ADU.

> If you include an audit list with the /AUDIT qualifier, ADU supplies both the standard history list entry and the audit list you define.

> The /NOAUDIT qualifier prevents the creation of a history list entry.

> ### /LIST [=list-file-spec]

> ### /NOLIST

> Creates a list file containing messages that occurred during a command operation and the statistics for that operation. The file specification names the file in which you want to store the output listing. If you do not include a file specification, ADU derives the file specification using the full given name of the definition, including dollar signs ($) and underscores (_), and the default file type .LIS.

> The /NOLIST qualifier does not create a list file.

> The default in interactive mode is /NOLIST. The default in batch mode is /LIST.

> ### /LOG

> ### /NOLOG (default)

> Displays a message indicating whether or not the operation was successful.

> The default is /NOLOG.

> ### /PRINT

> ### /NOPRINT (default)

> Sends the list file to the SYS$PRINT queue. If you use the /PRINT qualifier without a /LIST qualifier, ADU creates, prints, and then deletes the list file.

> /NOPRINT is the default.

# @ (At sign) Command (ADU>)

> Executes a command file containing ADU commands and/or ACMS definitions. Use this command to compile a definition without writing the definition interactively in ADU.

## Format

> @ (At sign) command-file-spec

## Parameter

> ### command-file-spec

> The name of the command file containing the commands and/or definitions you are submitting to ADU.

## Notes

> By default, the ADU @ (at sign) command executes a file with a file type .COM located in your default directory. If the file type is not .COM, you must specify the file type when you execute the command.

> If the definition contains errors, ADU displays diagnostic messages and the lines containing the errors. ADU does not display each line of the command file as it executes unless you use the ADU SET VERIFY command.

## Example

    ADU> @PERS_APPL
    %ADU-I-NONODWLCR, Object 'PERS_APPL' does not exist, creating object
    ADU>

> This example executes a command file, PERS_APPL.COM, that contains the definition for the ACMS application PERS_APPL. ADU compiles the definition, stores the object in the dictionary, and returns an informational message saying that ADU is creating the object.

# ATTACH (ADU>)

> Transfers control from one process to another process in your job. Use this command if you entered ADU from a subprocess and want to return to a higher process without exiting ADU. You can also use this command to enter a lower process without exiting from the current subprocess.

## Format

> ATTACH process-name

## Parameter

> ### process-name

> The name of the process to which control is transferred.

## Notes

> The ATTACH command does not terminate the process from which you issue it. To terminate the process and return to the next higher process in the process tree in your job, log out.

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

## Example

    ADU> ATTACH NEILSEN_1
    %DCL-S-RETURNED, control returned to process NEILSEN_1

> This command returns control of your job to a previously created subprocess, NEILSEN_1. The command does not terminate the process from which you issued the ATTACH command.

Previous | Next | Contents | Index