| Previous | Contents | Index |
This part explains how to define transaction-processing applications using Compaq ACMS for OpenVMS (ACMS) software. In particular, this part describes:
One of the primary features of ACMS is the Application Definition Utility (ADU). The ADU is the principal tool used to create and process the definitions that comprise an ACMS application. You use ADU commands to write definitions for ACMS tasks, task groups, menus, and applications. When processing these definitions, ACMS builds the task group, menu, and application databases that it uses at run time to operate the application.
This book contains tutorial information showing how to use ADU to create ACMS applications. The Compaq ACMS for OpenVMS ADU Reference Manual, the companion volume, contains reference material for all the ADU commands. Together these books contain much of the information needed to create and build ACMS applications.
Chapter 1 contains the information on how to use ADU. Topics covered include:
This section explains how to invoke the Application Definition Utility
(ADU) and exit from it.
1.1.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:
$ MCR ACMSADU ADU> |
$ ADU :== $ACMSADU |
$ ADU ADU> |
$ ADU /COMMAND=RESERVATIONS |
$ RUN SYS$SYSTEM:ACMSADU ADU> |
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.
| Qualifier | Function |
|---|---|
|
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. |
|
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. |
|
Assigns a CDD directory. If you do not specify a path name, ADU uses the default CDD directory. |
|
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. |
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.
| 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. |
Two ADU commands, EDIT and MODIFY, require a text editor. By default, ADU uses the OpenVMS EDT editor. If you plan to use an editor other than EDT, you must set up a logical name, ADU$EDIT, to point to a command file naming the editor you want to use. You can use the DCL DEFINE or ASSIGN command to set up a pointer to the command file. For example:
$ DEFINE ADU$EDIT MYDISK$:[MYDIRECT]ADUEDIT.COM |
This command assigns the logical name ADU$EDIT to the ADUEDIT.COM command file in the directory MYDIRECT on the device MYDISK$. Including this command in your LOGIN.COM file defines in the ADUEDIT.COM the editor you want. If the ADUEDIT.COM file is not in your default directory, be sure to include the disk and directory specification.
The following example demonstrates how to name TPU by using the EDT interface as the default editor. To set up the ADUEDIT.COM file, enter the following commands into a file named ADUEDIT.COM:
$ ASSIGN/USER 'F$LOGICAL("SYS$OUTPUT")' SYS$INPUT
$ IF P1 .EQS. "" THEN GOTO INPUT
$ EDIT/TPU/SECTION=EDTSECINI/OUTPUT='P2' 'P1'
$ EXIT
$ NOINPUT:
$ EDIT/TPU/SECTION=EDTSECINI 'P2'
|
The third and last lines of this command procedure name TPU with the EDT interface as the editing environment. You can change these lines to name any other OpenVMS editor you want to use. See Section 1.6.10 for information on using the Language-Sensitive Editor (LSE).
For information on DCL commands, see OpenVMS DCL Dictionary. Guide to Using VMS Command Procedures has
information on writing command and startup procedures.
1.2 ACMS and the Data Dictionary
Prior to ACMS Version 3.1, the ADU Utility placed ACMS definitions in the CDD dictionary in DMU format. Within CDD the definitions are called dictionary objects.
With ACMS Version 3.1 and higher, ADU places ACMS definitions in the CDD dictionary in CDO format. Within CDD the definitions are called entities.
Specify a dictionary path name either in DMU or CDO format. In either case, ACMS stores the dictionary object in CDO format.
You can continue to use DMU-format objects created with earlier
versions of ACMS, whether or not you create new CDO format entities
with ACMS. However, you cannot use CDO to manipulate previously created
DMU-format objects. Nor can you use DMU to manipulate CDO-format
objects.
1.2.1 Dictionary Path Names
Every dictionary definition has a path name that uniquely identifies it. The naming conventions for DMU and CDO differ only in their specification of the dictionary origin.
To refer to CDD dictionary definitions, list all dictionary directory given names. Begin with CDD$TOP and end with the dictionary directory or dictionary object you want to identify. Separate names by periods. In the following example, the path name indicates that the RESERVATION_TASK dictionary object is located in the CUSTOMERS directory, which in turn resides in the AVERTZ directory. The AVERTZ directory is in the top-level directory CDD$TOP.
CDD$TOP.AVERTZ.CUSTOMERS.RESERVATION_TASK |
Refer to CDD dictionary entities by specifying a dictionary anchor and a path name. A dictionary anchor specifies the OpenVMS directory where the CDD hierarchy is stored. DISK1:[CDDPLUS] is an example of an anchor. The anchor is followed by the dictionary path. A dictionary path consists of dictionary names separated by periods. All but the last name are dictionary directory names. The last is an entity name. The following example illustrates the full CDD path name for the RESERVATION_TASK dictionary entity:
DISK1:[CDDPLUS]AVERTZ.CUSTOMERS.RESERVATION_TASK |
DISK1:[CDDPLUS] is the anchor. RESERVATION_TASK is the entity in the CUSTOMERS directory, which is located in the AVERTZ directory.
A CDD name can consist of given names containing a maximum of 31 characters. Characters can include the letters A through Z, digits 0 through 9, underscores (_), and dollar signs ($). The first character of each given name must be a letter. The last character can be either a letter or a digit. All lowercase letters are translated to uppercase.
Identify a dictionary object with a full or relative path name. If a default dictionary directory exists, use a relative path name. Relative path names include the portion of the path name that is not part of the default dictionary definition.
Suppose, for example, that the following command establishes your default directory:
$ DEFINE CDD$DEFAULT DISK1:[CDDPLUS]AVERTZ.CUSTOMERS |
With AVERTZ.CUSTOMERS as the default dictionary directory, the relative path name is simply the object name itself: RESERVATION_TASK. If the default directory is [CDDPLUS], the relative dictionary path name is AVERTZ.CUSTOMERS.RESERVATION_TASK.
In DMU, you can assign a password to each dictionary directory, subdirectory, and object in a path name. You cannot assign passwords to CDO entities. When specifying the path name, put the password in parentheses and attach it to the end of the given name to which it applies.
Passwords can contain a maximum of 64 printable ASCII characters, including spaces and tabs. Eight-bit characters from the DEC Multinational Character Set can also be used in passwords. Full support for the 8-bit character set requires software and hardware support. For instance, the display terminal and printer used must both support the 8-bit character set. Lowercase letters are translated to uppercase. The only printable characters you cannot include in path name passwords are parentheses, either left or right, and periods.
The following are legal given names with passwords:
JONES(ACMSPASS) SMITH(CAPT JOHN) |
The following example shows a path name with a password associated with a dictionary directory:
CDD$TOP.PERSONNEL.MENU(ACMSPASS).MENU_WORK |
You can also specify CDD dictionary specifications for ACMS workspaces. These workspace specifications are stored in the CDD dictionary.
OpenVMS logical names may be used in all or part of a path name. For example, if you define PERSONNEL_CDD as DISK1:[CDDPLUS]PERSONNEL, you can use PERSONNEL_CDD.MENU as a path name.
For more information on CDD path names, see the appropriate CDD
documentation.
1.2.2 Creating CDO Directories and Establishing Directory and Entity Protection
Before you create a new ACMS definition or replace an existing one that is in DMU format, you must first create a CDO directory in which to store the dictionary entity. This practice contrasts with the DMU behavior, in which the creation of a dictionary object also created the dictionary directory, if one did not exist. ADU returns an error if you attempt to create an entity in a CDO directory that does not exist.
Default protection for CDO directories and entities is stricter beginning with CDD Version 4.0. When you create a CDO directory or when you create or replace ACMS definitions in CDO format, be aware of the following protection issues:
The ACMS default protection scheme uses the logical name ACMS$ADU_ACL_DEFAULT. Define this process logical to point to an access control list (ACL) file specification.
ACMS also provides the ACMS$ADU_ACL_DEFAULT.COM command procedure in the SYS$MANAGER directory to automate the definition of the logical and the creation or modification of the file to which it points. ACMS$ADU_ACL_DEFAULT.COM consists of a series of menus and forms that allow you to:
Following is an example of an ACL file with three ACE entries. You can create this file by using SYS$MANAGER:ACMS$ADU_ACL_DEFAULT.COM. The example was generated by issuing the CDD command DIR/FULL.
(IDENTIFIER=[ACMS,RICK],ACCESS=READ+WRITE+MODIFY+ERASE+SHOW+DEFINE+CHANGE+
DELETE+CONTROL+OPERATOR+ADMINISTRATOR)
(IDENTIFIER=[ACMS,HEINZ],ACCESS=READ+WRITE+DELETE)
(IDENTIFIER=[*,*],ACCESS=READ+WRITE+MODIFY+ERASE+SHOW+OPERATOR+ADMINISTRATOR)
|
Access is determined by the first ACE encountered that applies to the creator of the entity. See the CDD documentation and OpenVMS Systems Services documentation for more information about ACLs for dictionary entities.
Table 1-3 summarizes the determination of entity protection.
| Action | DMU (ACMS Version 3.0) | CDO (ACMS Version 3.1 or higher) | DMU to CDO Migration |
|---|---|---|---|
| Adding a new object or entity (ADU CREATE, ADU REPLACE, ADU COPY) | Inherits directory's ACL | Use logical; if not, takes CDO default | N/A |
| Modifying an existing object or entity (ADU REPLACE, ADU MODIFY) | Inherits object's ACL | Inherits entity's ACL | Error if CDO directory does not exist; else, use logical. If no logical, use CDO default. |
To set up certain characteristics for the ACMS environment, you can create an initialization command file called ADUINI.COM, in which you can put commands for ADU to run at startup. You can include commands assigning the CDD default directory, logging information to a log file, displaying commands processed from an indirect command file, and so forth. Creating the ADUINI.COM file eliminates the need to type the commands each time ADU starts. This command file serves the same purpose for ADU that the LOGIN.COM file serves for the OpenVMS operating system.
Before displaying the ADU> prompt at the beginning of a terminal session, ADU searches for the logical name ADUINI in the logical name table. If it finds the logical name ADUINI, ADU uses it with the default file type .COM. To define the logical name ADUINI, place a line similar to the following in your LOGIN.COM:
DEFINE ADUINI MYDISK:[MYDIRECT]MYADUINI.COM |
If your LOGIN.COM file contains a line similar to this one, ACMS looks for ADU commands at ADU startup in the file MYADUINI.COM located in the directory MYDIRECT on the disk pointed to by the logical name MYDISK. When you use the DEFINE or ASSIGN DCL commands to assign the logical ADUINI to a disk, directory, and file, ACMS can find the file containing your startup commands.
If you do not assign a logical name using DEFINE or ASSIGN, ADU searches for the ADUINI.COM file in your default directory (SYS$LOGIN). If it finds the file there, ADU automatically runs it from that location. Table 1-4 lists the commands commonly included in the ADUINI.COM file.
| Command | Description |
|---|---|
| SET DEFAULT | Assigns a default CDD directory. |
| SET [NO]LOG | Starts or stops logging of information to a log file. |
| SET [NO]VERIFY | Controls whether or not ADU displays commands it runs from an indirect command file. |
| SHOW DEFAULT | Displays your current CDD default directory on your terminal screen. |
| SHOW LOG | Displays a message on your terminal screen telling you if logging is active or inactive and the name of the log file. |
To create the file ADUINI.COM, use a text editor such as EDT. Include in the file any commands you want ADU to run when you start the utility. Because ADUINI.COM is an ADU startup file and not a DCL command file, do not begin the commands with the DCL prompt. Example 1-1 shows a sample ADUINI.COM file.
| Example 1-1 A Sample ADUINI.COM File |
|---|
SET VERIFY SET LOG [ACMS.SAMPLE]DEFINE.LOG !Change default directory from CDD$DEFAULT SET DEFAULT DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.DEPARTMENT SHOW DEFAULT |
Start the ADUINI.COM file with the SET VERIFY command. The SET VERIFY command displays any commands or definition clauses that ADU processes from an indirect command file. For example, if you write a menu definition in a source definition file and include the ADU REPLACE command, you can submit that file to ADU as an indirect command procedure by using the at sign (@). The SET VERIFY command displays each command or clause as it processes that source definition file, as Example 1-2 shows.
| Example 1-2 SET VERIFY Display |
|---|
ADU> @MENU.COM
REPLACE MENU MENU_FIVE
APPLICATION IS APPLONE;
HEADER IS "P E R S O N N E L D E P A R T M E N T",
" M E N U";
ENTRIES ARE
DATR : TASK IS DATR;
TEXT IS "Datatrieve";
DUE : TASK IS DUE;
TEXT IS "Display Reviews Due";
END ENTRIES;
END DEFINITION;
|
If you use ADU often, you can also include the SET DEFAULT command in your ADUINI.COM file. This command names the CDD directory in which you want ADU commands, such as CREATE and REPLACE, to put definitions. Because some CDD path names can be long, setting the default directory in the ADUINI.COM file saves you from typing long CDD path names before beginning each utility session.
The SET DEFAULT command overrides the CDD default defined by the CDD$DEFAULT logical name. By defining this logical name, you can set your default directory. However, you cannot define CDD$DEFAULT in your ADUINI.COM file or while running ADU. Define CDD$DEFAULT only from DCL command level.
You can include the SHOW DEFAULT command in your ADUINI.COM file after the SET DEFAULT command. Use the SHOW DEFAULT command to see the directory to which your default is set when you start ADU. For example:
$ ADU current CDD default path is 'DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.DEPARTMENT' ADU> |
Because the SET DEFAULT command is in ADUINI.COM, ADU sets the default to the DISK1:[CDDPLUS]ACMS$DIR.ACMS$SAMPLE.DEPARTMENT directory. With the SHOW DEFAULT command in ADUINI.COM, ADU displays the default directory you assigned with the SET DEFAULT command before it displays the ADU> prompt.
Even if you set the default directory in the ADUINI.COM file, you can always override the default. Use the SET DEFAULT command to change the default while you use the utility. Remember that an interactive SET DEFAULT command changes the default directory for only the current utility session.
By using SET LOG, you can record your use of the utility. The command creates the file ADULOG.LOG if you do not include a file name with the command. With logging in effect, ADU copies the following information to the log file while you run the utility:
The SET NOLOG command is the default. Unless you either include the SET LOG command in ADUINI.COM or enter the command during a utility session, ADU does not record session information in a log file. If you put in ADUINI.COM either the SET LOG command to enable logging or the SET NOLOG command to disable logging, you should also include the SHOW LOG command, which indicates:
| Previous | Next | Contents | Index |