| Previous | Contents | Index |
Several terms are used throughout this manual in a specialized manner. The following sections explain the usage for each of these terms:
Several ADU clauses use identifiers in their syntax. Identifiers are names you create, such as request library file names and task names. Identifiers can have a maximum of 31 characters, but no spaces. You can use the following characters:
The first character of an identifier must be a letter, a dollar sign, or an underscore. By convention, identifiers containing dollar signs are reserved for Compaq use.
ACMS converts all lowercase letters to uppercase. |
When creating an identifier, do not use the ACMS reserved words ARE, IS, USING, or WITH. In addition, some commands or clauses have special restrictions for identifiers, such as whether the identifier must be unique within a definition. These restrictions are included with the description of the command or clause.
Identifier is also an OpenVMS term used to describe a special name that
a user is allowed to hold. Some identifiers represent the user names
and user identification codes (UICs). Others are more general names
that a group of users holds. During login, OpenVMS identifiers are
copied into a rights list that becomes part of the OpenVMS process.
Access control lists (ACLs) associate identifiers with the type of
access to be granted or denied to a system object such as a file or
logical name table. The application definition ACCESS clause uses ACLs
to grant and deny access to ACMS tasks. For more information about
OpenVMS identifiers see the OpenVMS documentation set.
1.4.2 File Specification
A file specification can be either an identifier (for logical names) or a quoted string. The contents of the quoted string must be an OpenVMS file specification. A valid OpenVMS file specification can contain all or a subset of the following fields:
node"access-string"::device-name:[directory-spec]file-name.file-type;version-number |
| node | Identifies the system on which the file resides. Node names are optional. |
| access-string | Contains information that enables access to files that are otherwise protected. Access control strings are optional. However, when you include one in a file specification, you must enclose it within quotation marks and precede it with the appropriate node name. |
| device-name | Identifies the physical device where the file is located. The device name can be the device code or a logical name specifying the device. Device names are optional, but you must include one if you specify a node name. |
| [directory-spec] | Identifies the directory in which the file is located. Directory specifications are enclosed within square brackets ([ ]). Directory specifications are optional, but you must include one if you specify a device name. The device name and the directory specification go together in a single logical name. |
| file-name | Specifies the name of the file. The file name field is required. |
| file-type | Specifies the type of file. Always use a period (.) to separate the file type from the file name. File types are optional. |
| version-number | Specifies which version of the file you want. Always use a semicolon (;) to separate the version number from the file type. Version numbers are optional. When specifying a version number, always specify the file type and file name. |
See OpenVMS DCL Dictionary for information about file specification defaults and
default file types.
1.4.3 Workspace Field Name
You refer to a workspace field name by specifying a sequence of identifiers which are separated by periods. A full workspace field name consists of the workspace name followed by the structure names and ending with the name of the elementary data item. Refer to the CDD documentation for more information on structure names.
Any identifiers in the full workspace field name can be omitted, except for the name of the elementary data item, as long as the result is a unique field name. For example, the following is a valid CDO record definition:
DEFINE RECORD SALARY_RECORD.
SALARY STRUCTURE.
EMPLOYEE_ID.
PAY STRUCTURE.
JOB_CLASS.
WEEKLY_PAY.
END PAY STRUCTURE.
END SALARY STRUCTURE.
END SALARY_RECORD RECORD.
|
There are four different ways to reference the WEEKLY_PAY field in the SALARY_RECORD example:
A text string contains a sequence of characters that are enclosed within single (' ') or double (" ") quotation marks. Text strings can include the following:
To include quotation marks in a string that is enclosed by the same quotation mark (either single or double), use two quotation marks; for example, "a text string ""with"" embedded quotation marks".
The HEADER clause of the menu definition uses text strings to define the menu title. For example:
HEADER " ACMS",
" EMPLOYEE SAMPLE APPLICATION";
|
The TEXT subclause in the menu definition also uses text strings.
When two or more legal text strings are joined by an ampersand (&), ACMS concatenates the strings and treats the result as a single text string. This technique can be used to break quoted strings that are too long to fit on one line without wrapping. For example, certain SQL Data Manipulation Language (DML) strings do not fit on a single line:
PROCESSING WITH
SQL RECOVERY "SET TRANSACTION READ WRITE " &
"RESERVING DEPART, ADMIN FOR PROTECTED WRITE"
|
ACMS concatenates the string into "SET TRANSACTION READ WRITE RESERVING DEPART, ADMIN FOR PROTECTED WRITE" before passing it to Rdb. When using the ampersand character to join lines, be sure to include all necessary spaces. The following example results in a string that cannot be interpreted correctly:
BLOCK WITH SQL RECOVERY
"SET TRANSACTION READ WRITE RESERVING" &
"EMPLOYEES FOR SHARED READ," &
"SALARY_HISTORY FOR SHARED WRITE," &
"JOBS FOR EXCLUSIVE WRITE"
|
ACMS concatenates the above example into the string "SET TRANSACTION READ WRITE RESERVINGEMPLOYEES FOR SHARED READ,SALARY_HISTORY FOR SHARED WRITE,JOBS FOR EXCLUSIVE WRITE" before passing it to Rdb. To send Rdb the correct string, add spaces before the end quotation marks:
BLOCK WITH SQL RECOVERY
"SET TRANSACTION READ WRITE RESERVING " &
"EMPLOYEES FOR SHARED READ, " &
"SALARY_HISTORY FOR SHARED WRITE, " &
"JOBS FOR EXCLUSIVE WRITE"
|
The new version translates to "SET TRANSACTION READ WRITE
RESERVING EMPLOYEES FOR SHARED READ, SALARY_HISTORY FOR SHARED WRITE,
JOBS FOR EXCLUSIVE WRITE". Rdb can now interpret the example
correctly.
1.5 Creating and Processing Definitions
When you use ADU to create an application, first write the definitions that compose the application and then process those definitions. There are four kinds of definitions in an ACMS application: task, task group, application, and menu. In each case, first create the definition of an element and then process it. Either write a definition in a file and then submit the file to ADU for processing, or write a definition interactively in ADU.
In general, it is easier to write a definition in a file and then
process it, than to create the definition interactively. The file
method offers more control over modifying and reorganizing the
definition. Creating a definition file and then processing it is
analogous to writing a source file for a computer program and then
compiling the source code.
1.6 How ACMS Uses Definitions
When you write the definitions for ACMS tasks, task groups, applications, and menus using ADU, ACMS stores the definitions in CDD. The definitions must then be translated into binary format. At run time, the definitions are represented by databases. For example, a task group definition is represented by a task group database, or .TDB, that contains a binary representation of the task group definition, including descriptions of the tasks in the group. Similarly, an application definition is represented by an application database (.ADB), and a menu definition is represented by a menu database (.MDB).
Use the ADU CREATE and BUILD commands to process task group, application, and menu definitions. CREATE stores the definitions in CDD, and BUILD creates the databases that ACMS uses at run time.
Figure 1-1 shows how to process each type of definition to create the three database files.
Figure 1-1 Creation of Definition Database Files
Using the CREATE or REPLACE command is like compiling a program. Using the BUILD command is like linking a program.
The next three sections present an overview of writing ADU definition
files and processing those files.
1.6.1 Creating ADU Definition Files
To create ADU definition files, use an OpenVMS text editor (for example, EDT, TPU, or the Language-Sensitive Editor) to enter the definition clauses. At the end of each definition, include the END DEFINITION clause. Use a semicolon (;) to mark the end of each clause. Indent the clauses to make it easy to understand the code. Use an exclamation mark (!) to introduce comments.
The following example shows a complete menu definition:
! Title for the menu
HEADER IS " REVIEW MENU";
! User Selections
ENTRIES ARE
HISTORY : TASK IS REVIEW_HISTORY IN PERSONNEL;
TEXT IS "Display Review Histories";
SCHEDULE : TASK IS REVIEW_SCHEDULE IN PERSONNEL;
TEXT IS "Display Review Schedules";
END ENTRIES;
END DEFINITION;
|
After creating a definition, process the file with the BUILD command. Figure 1-2 shows how the menu appears on the terminal screen after the definition file has been built.
Figure 1-2 The Review Menu
The ADU REPLACE command replaces the previous version of a CDD entity that describes an ACMS definition. Either the ADU REPLACE or ADU CREATE command creates a CDD entity when you first place an ACMS definition in the dictionary:
To submit a file containing a task group definition, enter:
ADU> CREATE GROUP CUSTOMERS_GROUP CUSTOMERS.GDF/LIST=CUSTOMERS |
This command tells ADU:
The following example uses REPLACE instead of CREATE to take the task group definition in the file CUSTOMERS. GDF and store the CUSTOMERS_GROUP task group entity in the CDD directory DISK1:[CDDPLUS]AVERTZ. The GROUP keyword indicates that the definition file is for a task group.
ADU> REPLACE GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP CUSTOMERS.GDF |
To continue an ADU command on a second line, use the hyphen (-) as the continuation character just for DCL commands. You can abbreviate keywords, such as GROUP, according to the DCL convention.
Instead of entering the CREATE or REPLACE command at the ADU> prompt each time you process a source definition, you can include the entire command line at the beginning of the source definition file. When including the command line in your source definition files, use the REPLACE command instead of the CREATE command, as Example 1-3 shows.
| Example 1-3 REPLACE Command in a Source Definition File |
|---|
REPLACE GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP SERVER IS CUSTOMER_SERVER : DCL PROCESS; END SERVER; TASKS ARE ADD : PROCESSING IS IMAGE IS "SYS$SAMPLE:CUSTOMERS.EXE"; DATR : PROCESSING IS DCL COMMAND IS "$MCR DTR32"; END TASKS; END DEFINITION; |
Use the REPLACE command to store in the dictionary a definition that does not already exist or to replace one that does. The CREATE command processes only definitions for which no dictionary location exists. Using the REPLACE command saves you from having to change the CREATE command to REPLACE when you change a definition and process it again.
After you include the REPLACE command in the source file, you then can use the at sign (@) to submit this file to ADU.
ADU> @CUSTOMERS.GDF |
After using the CREATE or REPLACE command to create a CDD entity for an ACMS definition, you use the ADU BUILD command to build a binary database of each ACMS task group, application, and menu definition for use by ACMS at run time.
In the following example, the ADU BUILD command uses the GROUP keyword to take the CDD CUSTOMER task group entity and create the CUSTOMER.TDB task group file. ACMS displays messages indicating the work being done and the size of the file. The resulting .TDB file is located in your default directory.
ADU> BUILD GROUP DISK1:[CDDPLUS]AVERTZ.CUSTOMERS_GROUP CUSTOMERS.TDB |
If the BUILD command detects any errors, you can correct them in the definition source file. You must process the revised definition before you reissue the BUILD command to create the database file. Use the REPLACE command to process and store the revised definition in the same CDD location. If the revised definition has no errors, the REPLACE command replaces the old definition with the new version.
You process application and menu definitions the same way as task group
definitions. Use the CREATE and REPLACE commands with task definitions,
but not the BUILD command. Task definitions are not built; they are
included in task group files (.TDBs) when task groups are built.
1.6.3 Annotating Definitions
You can include comments in ADU definitions the same as when writing programs. ADU uses the exclamation point (!) as the comment character. All text to the right of an exclamation point is ignored. Either begin a comment line with an exclamation point or insert an exclamation point at the end of a clause and add a comment on the same line. The following example includes both types of comments:
!--------------------------------------------------------------
! Notes included in a definition help document the definition's
! use. Notes can make it easier to maintain the source
| definition file.
!--------------------------------------------------------------
!
! There is one server in this SERVERS clause.
!
SERVERS ARE ! More servers will be added later.
UTILITY_SERVER : DCL PROCESS;
REUSABLE;
END SERVERS;
!
! There are three tasks in this TASKS clause.
!
TASKS ARE ! More tasks will be added later.
DATR : DCL COMMAND IS "$MCR DTR32";
EDITOR : DCL COMMAND IS "$EDIT/EDT 'P1'";
RESTORE : DCL COMMAND IS "$@ACMS$EXAMPLES:RESTORE.COM";
END TASKS;
END DEFINITION;
|
All ADU commands and keywords can be abbreviated to the first four characters. Shorten command names and keywords to fewer characters as long as the abbreviation is unique. For example, abbreviate the BUILD command to the letter B, because no other ADU command begins with B. The GROUP keyword can also be abbreviated to a single letter, G, because no other keyword begins with G. The following ADU command calls for ACMS to build the group EMPLOYEE_GROUP and assign it the name EMPLOYEE:
ADU> B G EMPLOYEE_GROUP EMPLOYEE |
A number of ADU commands include a definition component type as a keyword. These commands include: BUILD, COPY, CREATE, DELETE, LIST, MODIFY, and REPLACE. The definition component keywords are APPLICATION, GROUP, MENU, and TASK.
When including qualifiers with these commands, always place the qualifier after the keyword. For example:
ADU> BUILD GROUP /LOG DISK1:[CDDPLUS]PERSONNEL - ADU>_ PERSONNEL.TDB |
You can place the qualifier after other elements in the command line, between parameters, or at the end of the line. For example:
ADU> BUILD GROUP DISK1:[CDDPLUS]PERSONNEL /LOG - ADU>_ PERSONNEL.TDB /PRINT |
ADU commands can have a maximum of 256 characters. However, only 132 characters can be on a single line. When entering commands interactively, use the command continuation character, the hyphen (-), to enter long commands on several lines. Of course, you do not have to wait until you have entered 132 characters on a line before making a break. Break your command at any convenient place.
When you reach the point for a break on the command line, enter a hyphen and then press [Return]. ADU responds with the continuation prompt, ADU>_. Now continue typing the command line.
The following example breaks the BUILD command onto several lines:
ADU> BUILD MENU - DISK1:[CDDPLUS]DALLAS.PERSONNEL.EMPLOYEE_MENU- ADU>_ MENU.MDB- ADU>_ /LOG- ADU>_ /LIST=MENU_DATABASE_BUILD.LIST |
It is convenient to enter the command qualifiers last, with each one on a separate line, as shown in the previous example.
Note that ACMS concatenates to the contents of the previous line
whatever you type in response to the continuation prompt. If elements
need to be separated with spaces, always include those spaces at the
beginning of the next line. In the preceding example, it was necessary
to include a space before the name of the menu database file MENU.MDB.
No spaces were needed before the /LOG and /LIST qualifiers, although
inserting spaces before them is permissible. Be sure to insert spaces
wherever the syntax requires them.
1.6.7 Responding to Command Prompts
When you enter an ADU command, ADU can supply prompts for the command parameters. This feature is helpful to those not sure of the order of the parameters or not sure of which ones are needed. To have ADU supply prompts for the required parameters, press [Return] at the end each input. In the following example, the user entered the BUILD command and pressed [Return]. ADU first prompts for the definition component type:
ADU> BUILD [Return] Component_type : |
You can enter the component type and the dictionary path name in response to this prompt, as well as include a database file specification and any desired qualifiers. When you press [Return] after entering the component type, ADU supplies prompts for the dictionary path name.
ADU does not prompt you for the database file specification or for any qualifiers. These elements are not required. Enter the optional elements when responding to a prompt for a required element.
| Previous | Next | Contents | Index |