Compaq ACMS for OpenVMS
Quick Reference Guide

Chapter 1
ADU Commands and Clauses

This chapter contains syntax for the commands and clauses of the ACMS Application Definition Utility (ADU). ADU commands allow you to create or change definitions for ACMS tasks, task groups, applications, and menus. The definitions themselves are made up of ADU clauses and phrases. See the Compaq ACMS for OpenVMS ADU Reference Manual for more information about ADU commands and clauses.

1.1 ADU Commands

Use ADU commands to create or change the definitions an ACMS application uses, or to gather information about 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, use ADU commands to reset your data dictionary default directory during a session, as well as write, change, copy, delete, and compile definitions for tasks, task groups, menus, and applications. Use other ADU commands to 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. See the Compaq ACMS for OpenVMS ADU Reference Manual for a detailed explanation of the syntax of ADU commands.

Table 1-1 lists the ADU startup command qualifiers.

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.

**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.1.1 @ (At sign) Command (ADU>)

Executes a command file containing either ADU commands or ACMS definitions. If you do not specify a file type, ACMS supplies .COM as the default.
@ command-file-spec

1.1.2 ATTACH Command (ADU>)

Transfers control from your process to another process in your job.
ATTACH process-name

1.1.3 BUILD Command (ADU>)

Converts object definitions from the dictionary into binary database files that ACMS uses at run time.

1.1.4 COMPILE Command (ADU>)

Checks an application, task group, menu, or task definition for syntax errors, and writes the compilation results to a file.

1.1.5 COPY Command (ADU>)

Creates a copy of a definition.

1.1.6 CREATE Command (ADU>)

Checks an application, task group, menu, or task definition for syntax errors, and stores valid new definitions in the dictionary.

1.1.7 DELETE Command (ADU>)

Removes a definition from the dictionary.

1.1.8 DUMP Command (ADU>)

Displays the contents of an application, menu, or task group database file.

1.1.9 EDIT Command (ADU>)

Invokes a text editor to let you make changes to the last command you entered.
EDIT

1.1.10 EXIT Command (ADU>)

Ends the current ADU session and returns you to the DCL prompt.
EXIT

1.1.11 HELP Command (ADU>)

Displays information about ADU commands and clauses.
HELP [/qualifier] [topic]

Command Qualifiers Defaults

/[NO]PROMPT /PROMPT

Command Qualifiers	Defaults
/[NO]PROMPT	/PROMPT

1.1.12 LINK Command (ADU>)

Converts object definitions from OpenVMS files into binary database files that ACMS uses at run time.

1.1.13 LIST Command (ADU>)

Displays the contents of a definition in a dictionary directory.

1.1.14 MODIFY Command (ADU>)

Retrieves a definition from the dictionary and runs a text editor so you can change the definition.

1.1.15 REPLACE Command (ADU>)

Replaces an old dictionary definition with a new one.

1.1.16 SAVE Command (ADU>)

Puts the last command you entered in the file you designate.
SAVE save-file-spec

1.1.17 SET DEFAULT Command (ADU>)

Assigns your default directory in the dictionary.
SET DEFAULT cdd-path-spec

1.1.18 SET LOG Command (ADU>)

Creates a log file of an interactive ADU session you enable with the SET LOG command. The SET NOLOG command disables logging.
SET LOG [log-file-spec]
SET NOLOG

1.1.19 SET VERIFY Command (ADU>)

Displays commands and source definitions as they are processed from a command file you execute with the @ (At sign) command. The SET NOVERIFY command disables the displaying of processed commands and source definitions.
SET VERIFY
SET NOVERIFY

1.1.20 SHOW DEFAULT Command (ADU>)

Displays your current default dictionary directory.
SHOW DEFAULT

1.1.21 SHOW LOG Command (ADU>)

Displays information about logging you enable with the SET LOG command. The SET NOLOG command disables logging.
SHOW LOG

1.1.22 SHOW VERSION Command (ADU>)

Displays the current software version number of ADU.
SHOW VERSION

1.1.23 SPAWN Command (ADU>)

Creates a subprocess of the current process and transfers job control to the subprocess.
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

1.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.

1.2.1 %INCLUDE

Includes the contents of a file in a source definition. If you do not specify a file type, ACMS supplies the .COM default.
%INCLUDE "file-spec"

1.3 Task Definition Clauses

This section lists the syntax for the ADU clauses and phrases you use to write task definitions. You use these clauses with the ADU 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 either define 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 either in 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. ACMS lets you nest block steps so that a task can contain multiple blocks.

This section begins with overview syntax for tasks, block step phrases, exchange steps, processing steps, action clauses, and exception handler action clauses. The overview syntax is followed by syntax for individual task definition clauses and phrases.

1.3.1 Task Syntax

1.3.2 Block Step Phrases Syntax

1.3.3 Exchange Step Syntax

1.3.4 Processing Step Syntax

1.3.5 Action Clauses Syntax

1.3.6 BLOCK Clause (Block)

Describes the work done in a block step in terms of block, exchange, processing, and action clauses.

1.3.7 CALL Clause (Processing)

Names a procedure in a procedure server to do the work for a processing step. Also names any workspaces used by that procedure.
CALL PROCEDURE entry-point-name [IN server-name] [USING workspace-name [,... ]];

1.3.8 CALL TASK Clause (Processing)

Names a task called by a processing step and any workspaces supplied to the called task.
CALL TASK task-name [ USING workspace-name [ ,... ] ] ;

1.3.9 CANCEL ACTION Phrase (Block)

Specifies processing ACMS does when a task is canceled.
CANCEL ACTION IS <processing-clause>

1.3.10 CANCEL TASK Clause (Action)

Stops the task in the action part of the current step by canceling the current task instance.

1.3.11 CANCELABLE Clause (Task)

Specifies whether or not a task can be canceled by a user or task submitter.

1.3.12 COMMIT TRANSACTION Clause (Action)

Signals the end of a distributed transaction and makes permanent any file or database operations performed within the distributed transaction.
COMMIT TRANSACTION;

1.3.13 CONTROL FIELD Clause (Action, Block, Exchange, Processing)

Performs a step or action based on a condition.

1.3.14 DATATRIEVE COMMAND Clause (Processing)

Names a DATATRIEVE command to do work for a processing step.

1.3.15 DCL COMMAND Clause (Processing)

Names a DCL command to do work for a processing step.
DCL COMMAND IS dcl-command-string [ IN server-name ] ;

1.3.16 DEFAULT FORM Clause (Task)

Names a default form used by the SEND, RECEIVE, and TRANSCEIVE clauses in exchange steps of a task.
DEFAULT FORM IS form-label-name;

1.3.17 DEFAULT REQUEST LIBRARY Clause (Task)

Names a default request library used by REQUEST clauses in exchange steps of a task.
DEFAULT REQUEST LIBRARY IS request-library-name ;

1.3.18 DEFAULT SERVER Clause (Task)

Names a default server to handle processing and cancel actions for the step or steps in a task.
DEFAULT SERVER IS server-name ;

1.3.19 DELAY Clause (Task)

Controls whether or not ACMS pauses after a task finishes running before clearing the screen and displaying the ACMS menu.
[ NO ] DELAY ;

1.3.20 EXCEPTION HANDLER Clause (Block, Exchange, Processing)

Describes the actions to be taken to recover from one or more exceptions.
EXCEPTION HANDLER ACTION IS <action-clause> ... ;

1.3.21 EXCHANGE Clause (Task)

Describes the interaction between the application and the user.

1.3.22 EXIT BLOCK Clause (Action)

Transfers control of the task to the action part of the block step definition.
EXIT BLOCK ;

1.3.23 EXIT TASK Clause (Action)

Ends the current task.

1.3.24 FORM I/O Phrase (Block)

Specifies that the exchange steps in a block step use DECforms to interface with the user.
FORM I/O

1.3.25 GET ERROR MESSAGE Clause (Action)

Uses the OpenVMS message facility to translate a message number into a message and move that message from a message file to a workspace field.

1.3.26 GLOBAL Clause (Task)

Specifies that a task can be selected from a menu, called by an agent, or called by another task.
GLOBAL ;

1.3.27 GOTO STEP Clause (Action)

In the action part of a step definition, specifies which block, exchange, or processing step to execute next.

1.3.28 IF THEN ELSE Clause (Action, Block, Exchange, Processing)

Takes action based on values you test with Boolean expressions. Use the IF THEN ELSE clause to start a block, exchange, or processing step (thereby creating a conditional block, exchange, or processing step), or to start an action clause (thereby creating a conditional action clause).

IF (boolean-expression)
THEN <clause>
[ ELSE <clause> ]
END IF;

1.3.29 IMAGE Clause (Processing)

Names an OpenVMS image to do work for a processing step.
IMAGE IS image-file-spec [ IN server-name ] ;

1.3.30 LOCAL Clause (Task)

Specifies that a task can be called by or chained to another task, but not selected from a menu or called by an agent.
LOCAL ;

1.3.31 MOVE Clause (Action)

Specifies that a number, the numeric value of a global symbol, workspace field, or quoted string is to move into another workspace field or fields.

1.3.32 NO EXCHANGE Clause (Exchange)

Specifies that an exchange step does not do any work.
NO EXCHANGE ;

1.3.33 NO PROCESSING Clause (Processing)

Specifies that the step does not do any processing work.
NO PROCESSING ;

1.3.34 NO SERVER CONTEXT ACTION Clause (Action)

Maintains the current state of any server context associated with the task.
NO SERVER CONTEXT ACTION ;

1.3.35 NO TERMINAL I/O Phrase (Block, Processing)

States that the block or processing step does no terminal I/O.
NO TERMINAL USER I/O

1.3.36 NONPARTICIPATING SERVER Phrase (Processing)

Excludes a processing step from participating in an existing distributed transaction.
NONPARTICIPATING SERVER

1.3.37 PROCESSING Clause (Task)

Describes work done in a single-step processing task.

1.3.38 RAISE EXCEPTION Clause (Action)

Raises a step exception and passes control to the exception handler action part of the step.

1.3.39 READ Clause (Exchange)

If the block step uses STREAM I/O, the READ clause reads from an ACMS stream into a workspace. If the block step uses REQUEST I/O, the READ clause passes information from the exception line (line 24) on the terminal screen to a workspace.

1.3.40 RECEIVE Clause (Exchange)

Transfers information from form data items to your task workspace.

1.3.41 RELEASE SERVER CONTEXT Clause (Action)

Releases the server process allocated for a task.
RELEASE SERVER CONTEXT [ IF ACTIVE SERVER CONTEXT ] ;

1.3.42 REPEAT STEP Clause (Action)

Repeats the current exchange, processing, or block step.
REPEAT STEP ;

1.3.43 REQUEST Clause (Exchange)

Names a TDMS request that does input and output for an exchange step.
REQUEST IS request-name [ IN request-library] [ USING workspace-name [,...] ] ;

1.3.44 REQUEST I/O Phrase (Block, Processing)

Specifies using TDMS to communicate with the user. Specify the REQUEST I/O phrase at the block or processing step level.
REQUEST I/O

1.3.45 RETAIN SERVER CONTEXT Clause (Action)

Retains the server context within the current server.
RETAIN SERVER CONTEXT [ IF ACTIVE SERVER CONTEXT ] ;

1.3.46 ROLLBACK TRANSACTION Clause (Action)

Marks the end of a distributed transaction and returns any files and databases within the transaction to the state they were in before the transaction started.
ROLLBACK TRANSACTION ;

1.3.47 SELECT FIRST Clause (Action, Block, Exchange, Processing)

Takes action based on values you test with Boolean expressions. Use a SELECT FIRST clause to start a block, exchange, or processing step (thereby creating a conditional block, exchange, or processing step), or to start an action clause (thereby creating a conditional action clause).

Index

Compaq ACMS for OpenVMSQuick Reference Guide

Chapter 1ADU Commands and Clauses