within the first source file, the value specified by this qualifier is ignored. /OBJECT_LIBRARY /OBJECT_LIBRARY=filespec Specifies the object library to be included in the LINK command in the description file. Object files from the compilations are inserted into this object library. /OPTIONS_FILE /OPTIONS_FILE=filespec[,...] Specifies user-written options files to be included in the LINK command in the description file. /SWITCHES /SWITCHES=COMPILE="/qualifier..." /SWITCHES=LINK="/qualifier..." /SWITCHES=(COMPILE="/qualifier...",LINK="/qualifier...") Specifies additional command line qualifiers to be included in the generated description file for all compilation and/or link commands. Additional compilation switches can not be specified when /BUILTIN_RULES_APPLY has been specified. /TARGET /TARGET=name Specifies a name for the build target. If this qualifier is not specified, the target defaults to the first file specified. This lets you specify an executable name that is different from the file name. 2 Description_File 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. 3 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. 4 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. 4 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. 4 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. 3 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. 3 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 3 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. 3 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. 3 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). 4 Text_operations The following functions perform text processing operations: 5 ADDPREFIX $(ADDPREFIX prefix,text) Prepends to text. 'prefix' is prepended to the start of each word in 'text'. 5 ADDSUFFIX $(ADDSUFFIX suffix,text) Appends to text. 'suffix' is appended to the end of each word in 'text'. 5 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 %. 5 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 %. 5 FINDSTRING $(FINDSTRING find,text) String search. If 'find' occurs in 'text', the value is 'find'; otherwise, the value is empty. 5 FIRSTWORD $(FIRSTWORD text) Returns the first word in 'text'. 5 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'. 5 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. 5 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'. 5 SORT $(SORT text) Sorts text. Words in 'text' are sorted into lexical order; duplicated words are removed. 5 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. 5 SUBST $(SUBST from,to,text) String substitution. Each occurrence of 'from' in 'text' is replaced by 'to'. 5 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. 5 WORDS $(WORDS text) Returns the number of words in 'text'. 4 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: 5 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. 5 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. 5 FILETYPE $(FILETYPE text) Returns type part. For each file specification in 'text', returns the type part of the file specification. 5 FILEVERSION $(FILEVERSION text) Returns version part. For each file specification in 'text', returns the version part of the file specification. 5 NOTDIR $(NOTDIR text) Returns name/type part. For each file specification in 'text', returns the name and type part of the file specification. 5 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 %. 4 Other_operations Other miscellaneous operations: 5 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 3 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. 3 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" 2 Examples 3 Description_File The following description file directs MMS to build MYPROG.EXE using the appropriate architecture-dependent *_DEFS.REQ: ! Macro definitions LIBRARYMODULES = A, B, C, D, E LIBRARIES = MYPROG.OLB($(LIBRARYMODULES)) - ! project library SYS$LIBRARY:CRTLIB.OLB ! C Runtime Library ! Dependencies MYPROG.EXE : $(LIBRARIES) LINK/EXEC=MYPROG MYPROG/LIB/INCLUDE=(A) .IF MMSIA64 A.OBJ, B.OBJ : IA64_DEFS.REQ .ELSIF MMSALPHA A.OBJ, B.OBJ : ALPHA_DEFS.REQ .ELSE A.OBJ, B.OBJ : VAX_DEFS.REQ .ENDIF D.OBJ, E.OBJ : COMMON.H E.OBJ : DATA.H If this file is named DESCRIP.MMS, the following command causes MMS to use the file to build MYPROG.EXE: $ MMS 3 MMS_Actions If the current default directory contains the following files: A.BLI;1 B.BLI;1 C.MAR;1 COMMON.H;1 D.C;1 DATA.H;1 DEFS.REQ;1 DESCRIP.MMS;1 E.C;1 MMS will execute the following actions as it processes the sample description file: BLISS A.BLI IF "''F$SEARCH("MYPROG.OLB")'" .EQS. "" THEN LIBRARY/CREATE MYPROG.OLB LIBRARY/REPLACE MYPROG.OLB A.OBJ BLISS B.BLI IF "''F$SEARCH("MYPROG.OLB")'" .EQS. "" THEN LIBRARY/CREATE MYPROG.OLB LIBRARY/REPLACE MYPROG.OLB B.OBJ MACRO C.MAR IF "''F$SEARCH("MYPROG.OLB")'" .EQS. "" THEN LIBRARY/CREATE MYPROG.OLB LIBRARY/REPLACE MYPROG.OLB C.OBJ CC /NOLIST D.C IF "''F$SEARCH("MYPROG.OLB")'" .EQS. "" THEN LIBRARY/CREATE MYPROG.OLB LIBRARY/REPLACE MYPROG.OLB D.OBJ CC /NOLIST E.C IF "''F$SEARCH("MYPROG.OLB")'" .EQS. "" THEN LIBRARY/CREATE MYPROG.OLB LIBRARY/REPLACE MYPROG.OLB E.OBJ LINK/EXEC=MYPROG MYPROG/LIB/INCLUDE=(A) These actions result in the production of all the intermediate files needed to produce MYPROG.EXE. If you then delete all the object files (.OBJ), and run MMS again using the /SKIP qualifier, MMS informs you that the target MYPROG.EXE is already up-to-date. 2 CMS If CMS is installed on your system and your source files are in the current default CMS library, MYPROG.EXE may be built from the CMS library when you issue the following command: $ MMS/CMS This command causes MMS to fetch the description file, if necessary, and source files from the CMS library, and perform the actions needed to create an up-to-date MYPROG.EXE. If a module, for example A.BLI, is replaced in the CMS library (by you or anyone else), thus causing a later version of A.BLI to exist in the library, the command $ MMS/CMS causes MMS to fetch the new CMS element A.BLI, compile it, add it to the MYPROG.OLB library, and produce a new MYPROG.EXE by executing the LINK command. 2 FMS If FMS (Forms Management System) is installed on your system, you can use MMS to access forms stored in FMS libraries. To specify an FMS form in a dependency rule, use the same syntax as for files in OpenVMS libraries. The file type .FLB after the library name informs FMS that the library contains FMS forms. The default file type for FMS forms is .FRM. The MMS default macro FMSFLAGS invokes FMS with the /REPLACE qualifier. MMS uses the insertion time of a form in an FMS library to determine whether a source is newer than the target. You cannot use the /REVISE_DATE qualifier with references to FMS forms. 2 MMS$STATUS Unless the qualifiers /CHECK_STATUS or /REVISE_DATE have been selected, when MMS completes, the symbol MMS$STATUS is set to the status value($STATUS) of the last action line executed. 2 MMS$SEVEREST_STATUS When MMS completes, the symbol MMS$SEVEREST_STATUS is set to the 'severest' status value($STATUS) of all action lines executed. If the status values of more than one action line have the same severity, then the resulting value of MMS$SEVEREST_STATUS will be that of the last of these action lines. 2 Oracle_CDD/Plus If the Oracle Common Data Dictionary (CDD/Plus) is installed on your system, you can use MMS to access records and other definitions stored in CDD/Plus. In a dependency rule, you follow the path name of a CDD/Plus definition with a caret (^) to inform MMS that the source is stored in CDD/Plus. For example: A.PAS : CDD$TOP.B.C.D.E^ ! CDD record that updates A.PAS ! action to update A.PAS To insert a remark in the CDD/Plus history list when MMS accesses a CDD/Plus definition, use the /AUDIT qualifier after the caret in the CDD/Plus specification. Follow the /AUDIT qualifier with a quoted string that contains the remark to be inserted in the CDD/Plus history file. For example: A : CDD$TOP.B.C.D.E^/AUDIT="Accessed by MMS to update A" ! action to update A The MMS default macro CDDFLAGS is initially defined to be the null string, but you can redefine it so that the same remark is written to the history file for all accesses to CDD/Plus entities. You cannot use the /REVISE_DATE qualifier with references to CDD/Plus definitions. The /NOACTION qualifier does not affect the /AUDIT qualifier; that is, remarks are written to the CDD/Plus history file even if action lines are not being executed. 2 Release_Notes The release notes for MMS Version 4.0 are contained in the file: SYS$HELP:MMS040.RELEASE_NOTES You can type or print this file to read the release note information. If you have installed prior versions of MMS, the associated release notes up to and including Version 4.0 can be found in SYS$HELP:MMSvvu.RELEASE_NOTES, where vv is the major version number, and u is the update number.