The description file contains rules that describe how the components
of your system are related and how MMS is to build them. You create
and modify a description file with any text editor (or by using
MMS/GENERATE); once the description file exists, you need issue only
a simple MMS command to update your system.
A description file contains dependency rules and can also contain
macro definitions, directives, and user-defined rules.
1 – Dependency rules
Dependency rules describe the relationships among the files in a
software system and specify the actions MMS is to perform in updating
those files.
Format:
target,... : source,... [! comment]
action line [! comment]
Targets and sources are OpenVMS file specifications or mnemonic
names. A target is the file you want updated. A source is a file
from which the target is built and can be optional. You must begin a
target/source line in column 1 of the line, and you must include at
least one space or tab on each side of the colon. A comment is
simply a string of text that documents the description file.
An action line contains a CLI command that specifies how the target
is to be built from the source. An action line must be indented by
at least one space or tab below the corresponding target/source line.
When you run MMS, all action lines, including any comments you
specified in the description file, are written to SYS$OUTPUT (or to
the file specified by the /OUTPUT qualifier) as they are executed.
MMS supplies some default, or "built-in," dependency rules. You can
also define your own rules.
1.1 – Built-in Rules
MMS uses built-in rules when you omit the action line or the source,
or both, from a dependency rule. Built-in rules allow MMS to assume
dependencies that are not stated in the description file and to
perform actions necessary to update the target. To decide which
built-in rule to apply to a dependency, MMS also uses the suffixes
precedence list.
Built-in rules also allow you to access files stored in OpenVMS,
CMS, FMS libraries and records stored in the Common Data Dictionary.
1.2 – User-defined Rules
You can define your own rules in a description file if MMS does not
supply a built-in rule that meets your needs. Once you define a new
rule, MMS uses it every time it builds your system with that
description file.
Format:
.SRC.TAR [! comment]
action line... [! comment]
.SRC is the source file type, and .TAR is the target file type. The
comment is a string of text that documents your rule. The action
lines specify the CLI commands that MMS should execute to update a
file of the target type from a file of the source type. Both the
source and target file types must appear in the suffixes precedence
list.
1.3 – Suffixes precedence list
The suffixes precedence list is a list of all the file types MMS
recognizes, arranged in a predetermined order. MMS uses the list to
decide which built-in rule to apply based on the order of the types
in the list, the file type of the target currently being updated, and
the existence of source files in the specified directory.
You can alter the suffixes precedence list by using one of the
.SUFFIXES... directives.
2 – Macros
A macro is a name that represents a character string. You can define
a macro at the beginning of the description file or on the MMS
command line and then use its name anywhere in the description file
in place of the equivalent string. A macro must be defined before
you use it.
Format:
name = string
The name identifies the macro, and the string is the text that
replaces the name when the macro is expanded. A macro definition
must begin in column 1 of the line. To invoke a macro, type:
$(name)
You can define a macro on the command line with the /MACRO qualifier;
you can also use a CLI symbol as a macro.
If a macro is not defined in the description file, MMS looks in its
environment for macro definitions. To find them, it looks at symbols
defined by the CLI assignment statement, scanning the CLI symbol
table for the body of the macro. If the body of the macro is not in
the CLI symbol table, MMS substitutes a null string for all
invocations of the macro.
MMS supplies some default, or "built-in," macro definitions and some
"special" macros for use in action lines.
3 – Reserved-Macros
MMS Used to invoke MMS from a description file.
MMSALPHA Defined as 'Alpha' if MMS is running on Alpha.
MMSARCH_NAME The architecture name on which MMS is running
(i.e. 'IA64', 'Alpha' or 'VAX').
MMSDESCRIPTION_FILE The full file specification of the description
file specified (or implied) by the command line.
MMSIA64 Defined as 'IA64' if MMS is running on IA64.
MMSQUALIFIERS The command line qualifiers used to invoke MMS.
MMSTARGETS The target list specified on the command line.
MMSVAX Defined as 'VAX' if MMS is running on VAX.
Note: the MMSIA64, MMSVAX and MMSALPHA macros can be used with the
.IF directive to include description file lines that should
only be processed for the appropriate architecture.
4 – Special-Macros
MMS$TARGET $@ The current target
MMS$TARGET_NAME $* The current target (excluding file type)
MMS$SOURCE $< The source file specification
MMS$SOURCE_LIST $+ Comma-separated list of all sources
MMS$CHANGED_LIST $? Comma-separated list of sources that are
newer than the current target
MMS$TARGET_SPEC $> The current target
If the target is a module in an OpenVMS library...
MMS$LIB_ELEMENT $% Element spec (i.e., module=alias)
MMS$TARGET $@ The library file specification
MMS$TARGET_NAME $* The module name
MMS$TARGET_SPEC $> The library file specification
If the source is a CMS element...
MMS$CMS_ELEMENT $< The CMS element
MMS$CMS_GEN $& The CMS generation
MMS$CMS_LIBRARY $@ The CMS library specification
5 – Directives
A directive is a word that instructs MMS to take a certain action as
it processes a description file. A directive can appear on any line
in the description file, but it affects how the entire description
file is processed. A directive must start in column 1 of the line.
The MMS directives and their functions are:
Directive Function
.ACTION_STATUS Introduces a user-defined severity rule; select
'Description_File' subtopic 'User_Defined_Severity'
for more information.
.DEFAULT Indicates actions to be performed if MMS built-in
rules or user-defined rules do not specify how to
update a target.
.ELSE Causes subsequent lines of a description file to be
processed if the boolean-expressions for the .IF
and all the preceding .ELSIF directives are false.
.ELSIF Causes subsequent lines of a description file to be
processed if the boolean-expressions for the .IF
and all the preceding .ELSIF directives are false
and the specified boolean-expression is true.
.ENDIF Terminates the set of lines in the description file
whose processing is controlled by .IF, .ELSIF and
.ELSE.
.FIRST Indicates actions to be performed before MMS has
executed any action lines to update the target.
.IF Causes subsequent lines of a description file to be
processed only if the specified boolean-expression
is true; select 'Description_File' subtopic
'Using_Conditionals' for more information.
.IFDEF Causes subsequent lines of a description file to be
processed only if the specified macro is defined
(obsolete, use .IF instead).
.IGNORE Causes MMS to ignore all errors generated by all
action lines and to continue processing the
description file.
.INCLUDE Includes the specified file in the description file.
.LAST Indicates actions to be performed after MMS has
executed all the action lines that update the target.
.SILENT Suppresses the writing of all action lines to the
output file (whether to SYS$OUTPUT or to the file
specified by the /OUTPUT qualifier).
.SUFFIXES Clears or appends to the suffixes-precedence list.
.SUFFIXES_DELETE Clears or deletes types from the suffixes-precedence
list.
.SUFFIXES_AFTER Inserts types into the suffixes-precedence list
after the first type specified.
.SUFFIXES_BEFORE Inserts types into the suffixes-precedence list
before the first type specified.
6 – Action line prefixes
An action line prefix is a modifier that controls the processing of a
single action line in a description file. The action line prefixes
are:
Prefix Function
- (Ignore) Causes MMS to ignore errors generated by the action
line on which the prefix appears.
@ (Silent) Suppresses the writing to the output file of the
action line on which the prefix appears. (The output
file can be either SYS$OUTPUT or the file specified
by the /OUTPUT qualifier).
?name (Severity) Use named user-defined severity rule to convert the
status returned by the action line to the equivalent
OpenVMS severity. Select 'Description_File' subtopic
'User_Defined_Severity' for more information.
An action line prefix must appear as the first character on an action
line. The rest of the action line must be separated from the prefix
by at least one space or tab. To use more than one prefix on the
same action line, type them next to each other with no intervening
spaces; they must be separated from the rest of the action line with at
least one space or tab.
7 – Predefined functions
Predefined functions can be used to perform text processing operations,
operate on file specifications and determine the origin of macros. Note
that, predefined functions can only be used if extended syntax has been
enabled (use /EXTENDED_SYNTAX qualifier when invoking MMS or, in
DECwindows MMS, check the Extended Syntax check box in the Build
Definitions/Directives Options dialog box).
Where a parameter to a function is considered to be a list of words,
a word is defined as any sequence of characters, not containing
white-space characters, that is terminated by a white-space character
or ')'. White-space characters are space and tab. Functions that
generate word lists will produce lists that are white-space
compressed (i.e. no leading or trailing spaces and a single space
character between each word in the list).
7.1 – Text operations
The following functions perform text processing operations:
7.1.1 – ADDPREFIX
$(ADDPREFIX prefix,text)
Prepends to text. 'prefix' is prepended to the start of each word
in 'text'.
7.1.2 – ADDSUFFIX
$(ADDSUFFIX suffix,text)
Appends to text. 'suffix' is appended to the end of each word in
'text'.
7.1.3 – FILTER
$(FILTER pattern...,text)
Filters text. Any word in 'text' that does not match any 'pattern'
word is removed. 'pattern' words may contain the wildcard
characters * and %.
7.1.4 – FILTER-OUT
$(FILTER-OUT pattern...,text)
Filters text. Any word in 'text' that matches any 'pattern' word
is removed. 'pattern' words may contain the wildcard characters
* and %.
7.1.5 – FINDSTRING
$(FINDSTRING find,text)
String search. If 'find' occurs in 'text', the value is 'find';
otherwise, the value is empty.
7.1.6 – FIRSTWORD
$(FIRSTWORD text)
Returns the first word in 'text'.
7.1.7 – FOREACH
$(FOREACH macro,list,text)
Repeatedly expands text. For each word in 'list', 'text' is
repeated with the value of 'macro' defined as the word from 'list'.
7.1.8 – JOIN
$(JOIN list,text)
Concatenates word by word. Each word in 'text' is appended to the
corresponding word in 'list' to form a word in the result. When
the number of words in 'list' and 'text' are not the same, the
remaining words from the longer list are simply appended to the
result.
7.1.9 – PATSUBST
$(PATSUBST pattern...,to,text)
Pattern substitution. Each word in 'text' that matches any
'pattern' word is replaced by 'to'. 'pattern' words may contain
the wildcard characters * and %. If 'to' also contains wildcard
characters, they will be replaced by the text that matched the
wildcard characters in 'pattern'.
7.1.10 – SORT
$(SORT text)
Sorts text. Words in 'text' are sorted into lexical order;
duplicated words are removed.
7.1.11 – STRIP
$(STRIP text)
White-space compression. Leading and trailing white-space is
removed from 'text' and each internal sequence of white-space
characters is replaced by a single space.
7.1.12 – SUBST
$(SUBST from,to,text)
String substitution. Each occurrence of 'from' in 'text' is
replaced by 'to'.
7.1.13 – WORD
$(WORD n,text)
Returns the n'th word from 'text'. 'n' should be in the range 1 to the
number of words in the list; when 'n' is not in this range, the result
is empty.
7.1.14 – WORDS
$(WORDS text)
Returns the number of words in 'text'.
7.2 – File operations
The following functions operate on file specifications; each has a
single parameter which is a list of words where each word is
considered to be a file specification:
7.2.1 – BASENAME
$(BASENAME text)
Returns directory and name part. For each file specification in
'text', returns that part of the file specification that is not
the type or version.
7.2.2 – DIR
$(DIR text)
Returns directory part. For each file specification in 'text',
returns that part of the file specification that is not the name,
type or version.
7.2.3 – FILETYPE
$(FILETYPE text)
Returns type part. For each file specification in 'text', returns
the type part of the file specification.
7.2.4 – FILEVERSION
$(FILEVERSION text)
Returns version part. For each file specification in 'text',
returns the version part of the file specification.
7.2.5 – NOTDIR
$(NOTDIR text)
Returns name/type part. For each file specification in 'text',
returns the name and type part of the file specification.
7.2.6 – WILDCARD
$(WILDCARD text)
File search. Result is the name and type part of all existing files
that match any of the file specifications in 'text'. The file
specifications may contain the wildcard characters * and %.
7.3 – Other operations
Other miscellaneous operations:
7.3.1 – ORIGIN
$(ORIGIN macro)
Result is the origin of 'macro' as follows:
"FILE" defined in a description file
"COMMAND LINE" defined on the command line
"SPECIAL" a special macro
"DEFAULT" a default macro
"CLI SYMBOL" a CLI symbol
"TEMPORARY" defined by function FOREACH
"UNDEFINED" 'macro' is not defined
8 – User Defined Severity
When an action line returns a value that is not a standard OpenVMS
status, the .ACTION_STATUS directive can be used to define how the
equivalent OpenVMS severity can be determined from the foreign status
value.
The action line prefix, ?name, indicates those action lines for which
the severity must be determined according to the named ACTION_STATUS
directive.
The ACTION_STATUS directive has the following form:
(use the line continuation character '-' if the directive uses more
than one line)
.ACTION_STATUS name [ .MASK m ]
[ .SUCCESS { s1,s2,... | OTHERS } ]
[ .INFORMATION { i1,i2,... | OTHERS } ]
[ .WARNING { w1,w2,... | OTHERS } ]
[ .ERROR { e1,e2,... | OTHERS } ]
[ .FATAL { f1,f2,... | OTHERS } ]
where,
Name is any sequence of characters not starting with a punctuation
character and terminated by comma, space or tab (punctuation
characters are ! : ; , # ).
m,s,i,w,e,f are decimal, octal or hex numbers
(octal numbers are 0... and hex numbers are %x... or 0x...).
Space, tab or comma can be used as the separators in a list of
numbers.
OTHERS can only be specified for one severity.
If OTHERS is not specified, it will default to the least severe of
any undefined severity (or ERROR if all severity values are
defined).
The directive is effective over the entire file.
It is an error to specify two ACTION_STATUS directives with the same
name.
MMS will then interpret the status returned from an action line
prefixed by ?name as follows:
If mask is specified, extract value from the action line status
using the mask value; the extracted value is shifted right to match
the first bit in the mask.
If mask is not specified, extracted value is the action line status.
Determine the severity associated with the extracted value.
MMS will then continue, treating this severity as if it were a standard
OpenVMS $SEVERITY.
9 – Using Conditionals
The directives .IF, .ELSIF, .ELSE and .ENDIF are used to instruct MMS
to process selected lines in your description file.
The .IF directive has the following format:
.IF boolean-expression
[description file line] ...
{.ELSIF boolean-expression}
[description file line] ...
[.ELSE]
[description file line] ...
.ENDIF
In this syntax, the "description file line" is zero or more
description file lines that may include further .IF directives. The
.IF directive may be followed by zero or any number of .ELSIF
directives, and zero or one .ELSE directive. The .IF directive must
always be accompanied by a matching .ENDIF directive.
MMS evaluates the 'boolean-expression' specified with the .IF
directive. If true, the lines of the description file between the .IF
directive and a corresponding .ELSIF, .ELSE or .ENDIF are processed;
then, if either .ELSIF or .ELSE were detected, all description file
lines from this line to the corresponding .ENDIF directive are
ignored. When the boolean-expression specified with the .IF directive
is false, all description file lines from this point to a
corresponding .ELSE, .ENDIF or .ELSIF whose associated
'boolean-expression' is true, are ignored.
The 'boolean-expression' specified in .IF and .ELSIF directives is
defined as follows:
boolean-expression
:== [ .NOT ] boolean-operation |
[ .NOT ] boolean-operation boolean-operator boolean-expression
boolean-operation :== ( boolean-expression ) |
word |
word comparison-operator word
word :== null |
any sequence of characters, terminated by space, and not
starting with '.', '(' or ')'.
boolean-operator :== .AND | .OR
comparison-operator :== .EQ | .NE | .GE | .LE | .GT | .LT
The operands in the 'boolean-expression' take one of two forms:
.IF word
or,
.IF word1 .EQ word2
In the first case, MMS checks to see if 'word' is a macro that has
been defined to a non-null value; the expression is true if it is,
false otherwise. (NOTE: this is precisely the same functionality as
that of the obsolete .IFDEF directive). For example, to check that
the macro FRUIT is defined, write:
.IF FRUIT
In the second case, MMS performs the requested comparison between
'word1' and 'word2' to determine the expression value; the comparison
operation is case-sensitive. Note that, when using macros and
functions in expressions of this form, you must reference the macro
or function in the standard way, in $(). For example, to check that
the macro FRUIT is defined to be BANANAS, write:
.IF $(FRUIT) .EQ BANANAS
If you need to compare words that start with the characters '.', '('
or ')' or text containing layout characters then, enclose the
words or text (on both sides of the comparison operator) in
quotation-marks. For example, to check that the macro FILETYPE is
defined as .MMS, and that the macro VERSION is not defined as
'Version 3.2', you must write:
.IF "$(FILETYPE)" .EQ ".MMS" .AND "$(VERSION)" .NE "Version 3.2"