Trailing-Edge
-
PDP-10 Archives
-
cuspbinsrc_2of2_bb-fp63b-sb
-
10,7/mic/micug.rnm
There are no other files named micug.rnm in the archive.
.nap;.lm 5;.rm 75;.ps 60,75;.ts 10,70;.variable ital,n,t;.VARIABLE META,+,- ;.variable do,Y,N
.title #####User Guide No. U6
.st #####14 November 1979
#####
.s 4
.center 80
AN INTRODUCTION TO MIC
.b 5
MIC stands for &Macro &Interpreted &Commands and is a system that allows
users to create their own system commands.
.b
This User Guide is intended as an introduction to MIC; it is not intended
as a reference document. A MIC reference manual is available for a small
fee from the Job Receptionist and a copy is held in the user area
.fn 4
This is a reprint with minor changes of the version dated 1 September 1978.
Replacement is not necessary.
.end footnote
book racks. A MIC Summary Card is also available (free) from Job Reception.
.b2
keywords: MIC, macro commands, command files
.b2;.nf
J.D. Service
A.J. Bullen
.b 3;.nf
CONTENTS page
.b
1. What MIC does 2
2. Creating MIC files 3
3. Calling MIC files 3
4. Example 4
5. Parameters in MIC macro commands 4
6. Labels and branching facilities 6
7. Error detection and processing 7
8. Silencing MIC 10
9. Manipulating parameters in a command file 11
10. Character subscripting facilities 11
11. Other useful facilities 12
12. Miscellaneous notes on MIC 13
13. Commands not covered in this guide 13
.page
.i -4;.f
^&1.##What MIC does.\&
.b 2
MIC is particularly useful if you are a regular user of the system and
find that you are frequently typing the same sequence of commands, which
is boring. What you require is a single command which performs the functions
of all of your commands. In computer jargon this is called a MACRO command, and on the DEC-10 they are known as
.b.nf
macro commands
or MIC commands
or MIC command files.
.b.f
For example if you frequently use the sequence of commands:
.b
#####.DELETE *.TMP,*.Q??
.br
#####.EX LINUS.FOR,SYS:NAGF/LIB
.b
you could create a macro command called SNOOPY, say, to perform their
combined function.
.b
To do this, SOS or TECO (see User Guide U2 for SOS or U1 for TECO) could
be used to create a file, called a MIC file, containing the two commands
(including the full stops at the start of the lines). If this file was
called SNOOPY.MIC - note the _.MIC extension - you could cause the sequence
of commands to be obeyed simply by typing the single command
.b
.in do
#####&./SNOOPY
.else do
#####&.DO SNOOPY
.endif do
.b
The commands in the MIC file will then be typed on your terminal and obeyed
as if you had typed them; all output from the commands will also be displayed on the terminal.
The file SNOOPY.MIC can then remain available for use at any time.
.b 2
MIC files may contain any number of commands, of any type, including
macro commands. In order to make MIC commands more useful, MIC files
may use many other facilities, including command arguments (or parameters)
and switches in the command call, conditional and branching statements
to enable jumps to labelled lines, and assignment statements which allow
parameters and variables to be assigned or altered during the processing
of the MIC command.
.b 3;.i -4;.tp 20
^&2.##Creating MIC files.\&
.b 2
MIC files may be created using a normal text file editor, e.g. SOS or TECO.
The file may be with or without line numbers. It will normally have the
extension _.MIC.
.b
Each line should have as its first non-space or tab character one of the
characters =, _., *, ! or _; which are interpreted as follows:
.ts 15;.b.literal
. monitor command follows
* data to be input to a program follows
= ignore carriage return at the end of this line
! comment line follows
; comment line follows (see section 8 for difference from !)
.end literal;.b.ts 10,70
.b
In order to get control characters such as control-C, control-Z, or altmode
into a MIC file, the control key and the character are replaced by the
up-arrow key followed by the character, e.g.
.b
#####_^C for control-C
.br
#####_^Z for control-Z
.br
#####_^[ for altmode (escape)
.s
The _' (single quotation mark) followed by a letter indicates a parameter in MIC (see section
5) so if quotation marks are needed in a MIC file it is advisable to use
.if ital
double quotes ("####").
.else ital
double quotes ("<text>").
.endif ital
.b
If any of the special characters described in this section is required
as itself, however, the character should be repeated, e.g.
.b
#####_^_^C########################gives _^C not control-C.
.br
#####VID:''MYTAPE'##############gives VID:'MYTAPE' not parameter M
.b
Note - the characters =, ., *, !, and ; need only be repeated if they are
required in the first character position of a line.
.b 3;.i -4;.tp 8
^&3.##Calling MIC files.\&
.b 2
MIC files are called into action with a command of the form
.s
.if ital
#####&./###:###########[###]
.ei ital
.if meta
#####&./<dev>:<micfilename>[<ppn>]
.ei meta
.if do
#####&.DO <dev>:<micfilename>[<ppn>]
.endif do
.s
where the device, ppn and file extension are optional. If the file is
in your own disk area or in the MIC library area (MIC:), the following
is sufficient:
.s
.if ital
#####&./
.ei ital
.IF META
#####&./<micfilename>
.ENDIF META
.if do
#####&.DO <micfilename>
.ei do
.s.tp 5
because the defaults are
.s
#####DSK:, or if not found, MIC:, for device
.br
.if ital
#####your own project-programmer number for [###]
.else ital
#####your own project-programmer number for [<ppn>]
.ei ital
.br
#####_.MIC for the filename extension.
.b 3
.i -4;.tp 30
^&4.##Example.\&
.b 2
The following is an example of a computer session to create and use a
MIC file to tidy up one user's disk area:
.b.lm 10;.ts 35;.nf.rm 80
&.MAKE TIDY.MIC Call TECO to make a file called TIDY.MIC.
&*I.DELETE *.BAK Insert monitor commands as shown ...
_.PROTECT *.DAT _<177_>
_.PRINT *.LST
$ $
&*EX $ $ Exit from TECO.
.b
.in do
&./TIDY Call TIDY.MIC into action.
.else do
&.DO TIDY Call TIDY.MIC into action
.ei do
^&.DELETE *.BAK\& From this point on, the system
^&FILES DELETED\& obeys your MIC file automatically.
^&FIND.BAK\& The remainder of the example has
^&10 BLOCKS FREED\& been output in its entirety by
^&.PROTECT *.DAT _<177_>\& the system with no input from you.
^&FILES RENAMED\&
^&TEST.DAT\&
^&TEST1.DAT\&
&.PRINT *.LST
.if ital
^&[LPT:########=/Seq:2601/Limit:203,4 Files]
.else ital
^&[LPT:<filename>=/Seq:2601/Limit:203,4 Files]
.ei ital
&.
.b 3;.f;.lm 5;.rm 75;.ts 10
.i -4
^&5.##Parameters in MIC macro commands.\&
.b 2;.ts 10
More generalised commands may be constructed using parameters in the
MIC file to stand for filenames or other quantities which would be
entered in the MIC command command call. The full specification of a
MIC call is
.b.nf;.rm 85
.if ital
#####&./###:###########[###]##########,##########,...
.ei ital
.if meta
#####&./<dev>:<micfilespec>[<ppn>] <parameterA>, <parameterB>, ...
.ei meta
.if do
#####&.DO <dev>:<micfilespec>[<ppn>] <parameterA>, <parameterB>, ...
.ei do
.b.f;.rm 75;.ps 60,75
A parameter may be any string of characters separated by commas (special
rules exist for brackets - see the MIC Reference Manual). Up to 26 parameters
are allowed and within the MIC file itself they are introduced by 'A,
'B, 'C ....'Z, i.e. a letter of the alphabet preceded by a single quote.
.if ital
During execution of a macro a single quote followed by the #th letter
.else ital
During execution of a macro a single quote followed by the <n>th letter
.ei ital
.if ital
of the alphabet will always be replaced by the #th parameter in the MIC
.else ital
of the alphabet will always be replaced by the <n>th parameter in the MIC
.ei ital
call.
.tp 4;.s
As an example, the TIDY macro described earlier changed the protection code of all .DAT
files to 177. The actual protection code used could have been selected
at run time by giving the required code as a parameter in the MIC call.
To do this the MIC file should contain
.s.tp 8
#####_.DELETE *.BAK
.br
#####_.PROTECT *.DAT _<'A_>
.br
#####_.PRINT *.LST
.s
To obtain a protection of 177 the MIC call is
.s
.in do
#####&./TIDY 177
.else do
#####&.DO TIDY 177
.ei do
.s
To obtain a protection of 157 the MIC call is
.s
.in do
#####&./TIDY 157
.else do
#####&.DO TIDY 157
.ei do
.s
In the first case 177 is substituted for 'A at run time; in the second
case 157 is substituted.
.b 2
Parameters are very useful when setting up MIC files which will act on
file names at run time; the parameters will then be file names. As an
example consider the problem of retrieving a file from a magnetic tape.
First the magnetic tape must be mounted, then the file copied to disk. Finally
you may want to see that the file has really been retrieved by checking your
directory listing. It is possible to write a retrieval macro called,
say, RESTOR, which would perform the task when you give a command of
the form
.s
.if ital
#####&./RESTOR ########.###
.ei ital
.if meta
#####&./RESTOR <filename>.<ext>
.ei meta
.if do
#####&.DO RESTOR <filename>.<ext>
.ei do
.s
The commands in RESTOR.MIC would be
.s;.lm 10
.nf
.literal
.MOUNT MTA:BACKUP/REELID:Y00530/VID:"FRED BLOGGS"
.R BACKUP
*RESTORE 'A
*EXIT
.DIR/FAST
.end literal
.lm 5;.s;.tp 6
When the MIC command call
.s
.in do
#####&./RESTOR PROG1.F4
.else do
#####&.DO RESTOR PROG1.F4
.ei do
.s.f
is typed, PROG1.F4 would be substituted for 'A in the processing of the
macro.
.s
The example can be further generalised by using parameters for the tape
identity. In this case RESTOR.MIC would contain
.s.lm 10;.nf;.tp 5
.literal
.MOUNT MTA:BACKUP/REELID:'B/VID:"'C"
.R BACKUP
*RESTORE 'A
*EXIT
.DIRECT/FAST
.end literal
.f.lm 5
.s
and a MIC call would be of the form
.s
.in do
#####&./RESTOR PROG2.ALG,Y00537,BILL SMITH
.else do
#####&.DO RESTOR PROG2.ALG,Y00537,BILL SMITH
.ei do
.b 3;.i -4;.tp 7
^&6.##Labels and branching facilities.\&
.b 2
The normal sequential processing of a MIC file may be interrupted by
using jump commands to labelled lines. Conditional statements, described
later, allow a conditional jump or a conditional command to be included.
.note
These jump commands and conditional statements, as well as the error
processing features described in section 7, have the same names and
functions as those used by the batch system.
.end note
^&6.1##Labels.\&
.b 2
A line in MIC may be labelled by placing the label at the beginning of
the line. A label consists of one to six alphanumeric characters and
is terminated by a double colon (::). Example -
.s
#####FRED::.DELETE *.BAK
.b 2;.tp 8
^&6.2##Jump statements.\&
.b 2
Two jump statements are available:
.b
#####.GOTO #####
.br
and# .BACKTO #####
.b
The GOTO statement is used for a forward branch and the BACKTO for a
backward branch. (`Backward' here means going to the beginning of the file and starting the search from there.)
.b.tp 10
A not to be recommended example which will perform DIRECT in an infinite
loop is
.b
#####FRED::.DIRECT
.br
#####.BACKTO FRED
.b;.tp 7
Another not very exciting example is
.b
#####.GOTO MYLAB
.br
#####.DEL *.TMP
.br
#####MYLAB::.RENAME OLD.DAT=FOR05.DAT
.b
because the _.DEL *.TMP will never be obeyed.
.b 2;.tp 4
There is one label, %FIN, which acts as a kind of `super label' and
is branched to by any GOTO or BACKTO if the %FIN occurs before the label for
which they are searching. In the following example,
.s.nf;.tp 6
.GOTO FRED
.
.
.
%FIN::.COMP MYPROG.FOR
FRED::.DIR
.s.f
the statement GOTO FRED will cause a branch to %FIN rather than FRED
because %FIN occurs before FRED.
.b 3
.i -4
^&7.##Error detection and processing.\&
.b 2
When a monitor or system program error occurs an error message is normally
output, and this is what most sensible user programs do. Conventionally
error messages are preceded by ? for fatal errors, and % for warnings,
and this `error character' always occurs as the first character of an
output line. MIC, like the batch system, allows you to monitor this first character
in the output line and take special action if your defined error character
occurs in this position.
.b
By default this facility is off, unless you are running MIC in batch. To use it, you include a command of
the form
.b
.if ital
#####&.ERROR
.else ital
#####&.ERROR <character>
.ei ital
.b
to inform MIC which character in the first character position of the
output line is to be regarded as preceding an error message. In batch, the default character is question mark (?).
This single command allows you to introduce very simple error processing
into your MIC macro. Whenever the error character specified by the command is detected, processing
of the MIC file will cease and the message
.b
#####[ABORT ON ERROR]
.b
will be displayed.
.b 2;.tp 6
For example if we modify the TIDY macro thus:
.b.literal
.ERROR ?
.DELETE *.TMP
.PROTECT *.DAT <'A>
.PRINT *.LST
.end literal;.b
then if we give an invalid argument to the macro the result will be:
.s.nf;.lm 10;.tp 10
.in do
&./TIDY 875
.else do
&.DO TIDY 875
.ei do
&.ERROR ?
&.DELETE *.TMP
^&FILES DELETED\&
^&XYZ.TMP\&
&.PROTECT *.DAT _<875_>
^&FILES RENAMED\&
^&?CMLIPC Illegal protection code: 875\&
^&[ABORT ON ERROR]\&
&.
.f.b;.lm 5
Note that the PRINT command has not been obeyed.
.b 2
While this is useful it is obviously more useful if the user can specify
what action is to be taken if an error is detected. MIC provides
three ways in which this can be done (only two of which are described
in this document) and all three may be included in the same macro.
.b 3;.i -4
^&7.1##Error labels.\&
.b 2
The first method is to include error recovery labels at suitable points
within the MIC macro. There are three special labels which may be classed
as error recovery labels; "%ERR", "%CERR", and "%FIN".
.b
On detecting an error character MIC does not actually stop processing
the MIC file immediately as was said in the last section, rather it
searches the remaining part of the MIC file for the occurrence of one
of the three error labels. Which label is searched for depends on the
following simple rule:
.b
If the error occurred in a program which came from SYS: (i.e. a systems
program) or a monitor command, the label "%CERR" is searched for,
otherwise the label "%ERR" is searched for. However "%FIN" has the
same super-label effect described in section 6.2 and if, during the
search for "%ERR" or "%CERR" a "%FIN" label is encountered, this will be
regarded as satisfying the search.
.b
Once MIC has found one of these error labels it `forgets' about the error
and continues processing the command file from a position immediately
after the error label.
.b;.tp 6
For example if our TIDY macro is modified thus:
.b.nf
_.ERROR ?
_.DELETE *.TMP
_.PROTECT *.DAT <'A>
%FIN::_.PRINT *.LST
.b.f
the print command will always be obeyed even if an error occurs in
either of the preceeding two commands.
.b.tp 6
An alternative form is:
.b.nf
_.ERROR ?
_.DELETE *.TMP
_.PROTECT *.DAT <'A>
%CERR::_.PRINT *.LST
.b.f
because DELETE and PROTECT are system commands, but
.b.nf
_.ERROR ?
_.DELETE *.TMP
_.PROTECT *.DAT <'A>
%ERR::_.PRINT *.LST
.b
is ^¬\& correct.
.tp 2;.b 2
These labels may occur as often as required in a MIC macro as the file
is always searched forward for error characters.
.b
For example the following would be a rather silly way of ignoring all
errors in TIDY:
.B.NF
_.ERROR ?
%FIN::_.DELETE *.TMP
%FIN::_.PROTECT *.DAT <'A>
%FIN::_.PRINT *.LST
.B
or
.B
_.ERROR ?
%FIN::_.DELETE *.TMP
%CERR::_.PROTECT *.DAT <'A>
%CERR::_.PRINT *.LST
.b
or any other combination of %CERR and %FIN.
.B 3;.F
^&7.2##Error conditionals.\&
.b 2
The second method of processing errors allows a much finer control over
error recovery, and to explain how it works we must once again change our
explanation of MIC's action on detecting an error.
.b;.tp 3
When an error is detected the command file is first searched for the next
monitor level line, that is the next line starting with a "_." (see section 2) and if the command on that line is
.b
.if ital
#####_.IF (ERROR)
.else ital
#####_.IF (ERROR) <argument>
.ei ital
.b
or
.b
.if ital
#####_.IF (NOERROR)
.else ital
#####_.IF (NOERROR) <argument>
.ei ital
.b
processing of the command file will recommence with that same "IF" command.
.b
If a %FIN or other appropriate error label is found during the search for
the next monitor level command the error will be treated as in the previous
section. Similarly if the first command line is not one of the two IF
commands the error will be treated as in the previous section.
.b.tp 7
Thus if we modify TIDY yet again -
.b.nf
_.ERROR ?
_.DELETE *.TMP
_.PROTECT *.DAT <'A>
_.IF (ERROR) _.DIR/F
_.PRINT *.LST
.B
.F
then if an error occurs in the PROTECT command the command IF (ERROR)
will cause the DIR/F command to be obeyed followed by the PRINT command,
but if the error occurs in the DELETE command none of the following
commands will be obeyed.
.b 2;.i -4
^&8.##Silencing MIC.\&
.b 2
Generally the commands in a MIC control file will be typed on the
terminal as they are obeyed. However this type-out can be suppressed
by the MIC command _.SILENCE or reinstated by the command _.REVIVE. For
example
.b.nf
_.SILENCE
_.R SETSRC
*NEW
_^C
.B
in a MIC file will suppress the output from the running of SETSRC.
.b
.f
The whole MIC control file may be silenced by giving it a protection code
of <2??>, i.e. any protection with the first digit a `2'. This is over-ridden
in the file by any _.REVIVE command. In the above example this
would allow the _.SILENCE command to be omitted.
.b
Note that comments preceeded by "!" will be displayed despite the SILENCE
condition; those preceeded by ";" will not.
.i -4;.b 3
^&9.##Manipulating parameters in a command file.\&
.b 2
Users' parameters to MIC command files are held within MIC as ASCII strings.
The LET statement allows a user to change parameters and define new parameters
during the processing of a MIC file by assigning a string or integer
expression to the parameter thus:
.b.nf;.tp 10
.if ital
.LET ######### ####=##########
.else ital
.LET <parameter name>=<expression>
.ei ital
.b
.if ital
where ############## is a parameter to the MIC file
.else ital
where <parameter name> is a parameter to the MIC file
.ei ital
either passed in the calling statement or newly
constructed. It must be one of the characters
A through Z.
.b
.if ital
########## is either a string expression or a
.else ital
<expression> is either a string expression or a
.ei ital
simple integer expression.
.b.f
A string expression may be a simple string such as "FRED.FOR" or have a
more complex form allowing a string to be constructed from strings in
other parameters; e.g. $A+"_."+$B is an expression which concatenates
three strings. Note the use of the $ before the parameter to indicate
that the contents of the parameter are to be treated as a string, i.e.
$A is equivalent to "'A".
.b
An integer expression may also have parameters and involve the arithmetic
operators + - * / and _^ where the normal precedence rules apply. An
example of an integer expression is 3*C+A-B.
.b
Examples:
.b
.nf;.tp 4
a) _.LET Z="THIS FORMS A NEW PARAMETER"
Whenever parameter Z is referred to in future it
will contain the text "THIS FORMS A NEW PARAMETER"
.b.tp 6
.in do
b) A calling statement /LINUS DSKD and statements in
.else do
b) A calling statement of DO LINUS DSKD and statements in
.ei do
the MIC file LINUS of
_.LET F="[1045,33]"
_.LET H=$A+"FRED.FOR"+$F
_.EX 'H
would execute the program DSKD:FRED.FOR[1045,33]
.b
c) _.LET D=A+1 will add the integer 1 to the integer
held in A. If A does not contain an integer an
error message will result.
.b 3;.f.i -4
^&10.#Character subscripting facilities.\&
.b 2
Any single character or group of characters in a string may be referred to
individually by using the subscripting facilities. These allow you to
give a MIC command which will loop around a set of monitor commands
substituting a different parameter from a sequence of parameters each
time the loop is obeyed.
.b2
A subscripted string expression used in a LET statement has the form
.b
.if ital
#####$#########.[##########,##########]
.else ital
#####$<parameter>.[<subscript1>,<subscript2>]
.ei ital
.b.tp 3
The first subscript specifies the first character to be extracted
from the string contained in the parameter, the second subscript
specifies the total number of characters to be extracted.
.s
Thus if parameter A contains the string BCDEF the subscripted string
expression $A.[2,3] refers to the string CDE.
.b.tp 4
The second subscript may be omitted and in this case the length of the
extracted string is assumed to be one character. The expression $A.[4]
refers to the 4th character in the string, i.e. character E in the above
example.
.b
Negative subscripts may be used to count backwards from the end of
the string. If A contains BCDEFG then $A.[-2] refers to
character F.
.b 3;.i -4;.tp 5
^&11.#Other useful facilities.\&
.b 2
^&11.1##The PLEASE command.\&
.b 2
A PLEASE command exists to
enable a message to be transmitted to the user of a MIC file. This
may be used to indicate progress during the operation of a silenced
MIC file or to transmit a message from the creator of a MIC file to a
user of the file.
.b
The form of the command is
.b
.if ital
#####.PLEASE ####### $
.else ital
#####.PLEASE <message> $
.ei ital
.b
The message is displayed on the terminal when the PLEASE command is
processed in the MIC file. If the terminating altmode is omitted then
MIC will suspend processing until you give instructions to proceed
by typing control-P - see section 11.2.
.b 2
^&11.2#Suspending MIC processing.\&
.b 2
The processing of a MIC file may be suspended by typing control-B. MIC will
then output the message [BREAK] and await further action from you.
.b
At this stage any monitor command or any MIC command may be typed in.
(If a MIC command is typed in, the initial `.' should be omitted.)
You may for example wish to type in LET commands to alter the values
of the parameters in the suspended MIC file or GOTO and BACKTO statements
to cause jumps to other parts of the MIC file.
.b;.tp 3
To continue processing of the MIC file type control-P. Any changes in
parameters or instructions to jump to labelled commands will be
recognised in the processing of the remainder of the MIC file.
.b;.tp 3
Note that a control-C typed in during the break period will cancel the
suspended MIC process.
.b 2;.tp 7
^&11.3#Nested MIC processes\&
.b 2
MIC command files may themselves contain MIC commands. Each file may
have its own parameters but inner processes may access the parameters
in an outer process. For further details see the ^&MIC reference manual\&.
.b 3
.i -4
^&12.#Miscellaneous notes on MIC.\&
.b 2;.i -3
a) If a job is currently executing a MIC file, type-ahead is not allowed.
The only exception is for control characters; all other type-ahead will be
discarded.
.b.i -3
b) An existing batch control file can be run as a MIC macro as long as it
does not include single quote characters which MIC will interpret as parameter indicators.
.b 3;.i -4;.tp 8
^&13.#Commands not covered in this guide.\&
.b 2
The following MIC facilities are not covered in this user guide but are
fully documented in the ^&MIC reference manual\&.
.b.literal
Multiple LET statements
IF (command) extensions
OPERATOR/NOOPERATOR commands
MIC RESPONSE command
MIC ABORT command
MIC CANCEL command
MIC BREAK command
MIC PROCEED command
MIC EXIT command
MIC RETURN command
MIC INPUT command
Obtaining system parameters such as TTY number, PPN, Job numbers
ON command
WHENEVER command
MIC SET command
MIC COJOB
Action parameters
Multiple commands on a line
.end literal
.b 2
You are advised to see the ^&MIC reference manual\& for full documentation on MIC. A copy is held in the computer building user area book rack, and copies
may also be obtained from Job Reception for a small fee.