A command macro is a text file that contains one or more commands and/or command macro statements and that has a name ending with the suffix .cm. You invoke a macro by entering its name. The operating system then sequentially executes the commands and macro statements in the file.
A command macro is useful to replace one of the following:
a long command string that you issue frequently
a group of internal commands, command macros, and/or program modules that together perform an operation you regularly require
a sequence of internal commands, command macros, and/or program modules that you execute in a certain way depending on external factors
2. Command macro
A command macro is a text file that contains one or more commands and/or
command macro statements and that has a name ending with the suffix .cm. You
invoke a macro by entering its name. The operating system then sequentially
executes the commands and macro statements in the file
3. Command line
A command line is a set of one or more command strings, separated by
semicolons. A command string is a command name and any of the command's
arguments you select. If you want to issue a command with the same name as the
command macro, include the .pm suffix in the command name. Otherwise, the
command macro will be called recursively.
4. Macro line
A macro line can be one of the following:
a command macro statement
a comment line
a parameter declaration.
5. Comment Line
A comment line is either a line that begins with an ampersand (&) followed by a
space or a line that consists only of an ampersand. The characters that follow the
ampersand on the line, if any, are taken to be the comment. The command
processor ignores all comment lines.
Ex:
& This command macro is named set_cursor.cm.
&
7. Parameter
The macro can take parameters. A parameter in a command macro is a named
variable that is declared within the parameter declaration section of a command
macro. A parameter receives its initial value from an argument specified in the
command string that calls the macro or from a default value specified within the
macro.
The macro processor stores parameters as character strings. When the value of
a parameter is converted, it is treated as numeric if it can be converted to a
number; otherwise the value is treated as a string.
8. 3 Parameter Types
There are three types of parameters: positional, optional, and switch parameters.
These correspond to the three types of command arguments described earlier in
this section.
A positional parameter is a parameter that the macro processor identifies in a
command line by the position of its value (rather than by a keyword).
An optional parameter is a parameter that the macro processor identifies in a
command line by a keyword that begins with a hyphen and is followed by a value.
You can specify allowed values (which the user can then cycle through in the
display form). You can also specify a default value.
A switch parameter is a parameter that has only two possible values: yes or no.
It is used like a command switch argument.
10. Parameter Declaration
A parameter declaration is a line in a command macro that appears between the
macro statements &begin_parameters and &end_parameters. It must
contain the name of a parameter and it can contain a parameter descriptor
(described later in this section). The form of a parameter declaration follows.
parameter_name [parameter_descriptor]
That portion of a macro from the &begin_parameters statement to the
&end_parameters statement is called the parameter declaration section. The
parameter declaration section must begin on the first line of the macro that is not
a comment line.
11. Parameter Label
A label is an optional element of a parameter descriptor. Its purpose is to provide
a descriptive term that will be useful to the user of a macro. It has the following
form:
label:
12. Contd...
The label, if specified, must be the first component of the parameter descriptor. The colon following
label must be the only colon in the descriptor.
Depending on the type of the parameter, the label appears in the display form, the command line form,
both of these, or neither of these. The information provided by label is used differently depending on
the type of the parameter.
For a positional parameter, it labels the parameter's field in the display form. It also provides a label
in the command line form when you give the command macro with the -usage option.
For an optional parameter, it labels the parameter's field in the command line form only.
For a switch parameter, there is no purpose for specifying a label, since it is used in neither the
display form nor the command line form.
13. Input Line
To supply input to a program in a macro, you must include the following
elements in the macro in the order shown:
the &attach_input macro statement, which allows the program to accept
input directly from the macro file
the command to invoke the program
input to the program (probably including a request such as quit to exit from
the program)
the &detach_input macro statement, which prevents any further program
input from coming from the macro
14. Command Function
A command function is a self-contained function that you can use as an
argument in a command line. Before executing the rest of the command line in
which a command function appears, the command processor evaluates the
command function and replaces it with a value. The value returned becomes part
of the command line. For example, to display the current time, you could enter
the following command line with the command function (time):
display_line (time)
The output for the preceding example could be 13:10:59, which specifies the
current hour (13, in 24-hour format), minutes (10), and seconds (59).
15. Library Path
The operating system maintains a set of library paths for each process. Library
paths specify where the operating system searches for external commands,
include files, object files, or message files. The libraries are referred to as the
command, include, object, and message libraries.
Library paths fall into two categories. Default library paths are set for an entire
module. All processes automatically include all default library paths in their
library search paths. These library paths are generally set using the
add_default_library_path command in module_start_up.cm. Typically
these are library paths that all or almost all processes on the system will need
(such as >system>command_library).