option R on
option E on
option F on
space 12
center ISD Software Maintenance Skeleton
space 5
center MAINTSKEL VERSION 2.7
option f off
eject
space 24
center This page intentionally left blank.
option f on
setctr p,1
eject
The University of Maryland has a program-maintenance
skeleton, to which its software releases (such as ASM) are
adapted. It has clever features such as cataloguing new files to
hold one's output, but these seem to do extremely little that
would take any significant effort to do by hand. Also, it lacks
some useful features, such as the ability to use non-standard
processors (such as one's own assembler). Furthermore, it
requires an SGS describing each element in the program; this is
typical of its lack of convenient defaults.
SPACE
Our version of how to maintain programs is embodied in the
element 'MAINTSKEL': It was developed by Dan Drake, formerly of
ISD, and has been enhanced by other ISD folks since dan left. At
some point there will be a proper document describing it; in the
meantime this section should give enough information to make it
possible to use the thing.
3Features
It is assumed that you have a program file containing some
source and procs, and a file (probably the same one) with current
relocatables. You want (probably) to apply some permanent and/or
temporary changes, producing (probably) a new absolute and
(perhaps) new source.
SPACE
MAINTSKEL is designed to do all the above, with a bewildering
variety of options. It will not catalogue new files, back up files
on tape, or run test cases, as the Maryland skeleton will. In a
little more detail, the features offered are as follows:
SPACE
Distinct files can be specified for source input, source
output, procedure input, procedure output, relocatable input,
relocatable output, and absolute output. If unspecified, these
have allegedly reasonable default values, mostly defaulting to the
source input file, which defaults to TPF$.
SPACE
Because it is assumed that changes will be applied repeatedly
to the same source, no new source is produced unless requested.
(If neither source output nor procedure output is specified,
procedures are updated into a temporary file.) New source can be
produced either by a 3-field processor call or by the U option.
SPACE
Normally, DOC elements are processed first; procedures
second; MAPs last; everything else in between.
SPACE
Within each of those classes, elements will be processed
alphabetically if requested.
SPACE
Elements can be selected for processing in a variety of ways.
By default, all elements with changes are processed; but one can
select only those with temporary changes, those with both
permanent and temporary changes, everything in the file, and so
on.
SPACE
One can select whether elements will be updated by PCF, TCF,
both (default), or neither.
SPACE
Elements can be selected for listing on the basis of whether
they have changes.
SPACE
Instead of updating elements, the skeleton can merge a PCF
and TCF to make a new PCF.
SPACE
The correct processor for any element can be given explicitly
(together with options) by an SGS; it can be determined (using
standard options) from the table of contents of the source input
file; or there can be no processor specification, in which case
the element is processed by a default processor, which can be
specified by the user (via the 'LANGUAGE' SGS).
SPACE
The user can specify his own processors to replace the
standard ones. He can specify default options for all processors
including standard ones.
3Processor Call
The user is assumed to know how to call @SSG, giving sources
for SGS, PCF, and TCF input. The only special feature relevant to
this skeleton is spec2: If this is given as
SPACE
CENTER <SOURCE-INPUT-FILENAME>./TOC
SPACE
the skeleton can read the 'TOC' SGS's to determine element types
and subtypes; this determines the processor to be used for any
element which does not have a 'DESCRIBE' or 'MAP' SGS (see below).
If spec2 is not used in this way, the 'LANGUAGE' SGS gives the
processor for non-described elements.
REMAIN 20
3SGS Types
The following conventions apply in describing SGS input:
SPACE
<filename> can be either a filename or qualifier,filename.
SPACE
<elt> can be element or element,version.
SPACE
<subtype> refers to a standard element type or subtype as
defined in section 24.2.1.1 Of the Exec-8 PRM, not an actual
processor name. For procedures, therefore, one should use ASMP,
COBP, or FORP, rather than PDP; the skeleton knows about providing
the C or F option.
SPACE
[bracketed material] is optional.
REMAIN 39
4File Definition SGS's
COLUMN 2
The following SGS's are all optional. If any of them is
omitted, a (hopefully) reasonable default is used. The general
syntax is:
SPACE
CENTER <SGS name> <filename>
SPACE 2
TABLE File Definition SGS's
SPACE
COLUMN 3
SGS name Purpose Default
------------------------------------------------------------------
: : : :
: SI : Defines the file which contains : TPF$ :
: : the source input, excluding : :
: : procedures. : :
: : : :
: SO : Defines the source output file. : None. New source :
: : if <filename> is 'U' (quotes : not produced. :
: : required), U-option updating : :
: : will be done. : :
: : : :
: RI : Defines relocatable input file. : SI :
: : : :
: RO : Defines relocatable output file. : SO if given, else RI :
: : : :
: PI : Defines procedure input file. : SI :
: : : :
: PO : Defines procedure output file. : SO if given, else :
: : : RO if given, else a :
: : : temporary file. :
: : : :
: : : To force a temporary :
: : : file, use: PO 'TEMP' :
: : : :
: AO : Defines absolute output file. : RO :
: : : :
------------------------------------------------------------------
END
COLUMN 13
REMAIN 28
4DESCRIBE
Purpose: Explicitly describes an element as being part of a
package, and to explicitly define its subtype. May
optionally define the options to be used when
processing this element, and the name of the output
element, if different.
SPACE
Syntax: DESCRIBE <elt> <subtype>[,<opts>] [<output-elt>]
SPACE
Notes: If <opts> is omitted, the default options for the
processor corresponding to the given subtype will be
used. Generally, listing options (such as S) and
update options (U) are not included, but are
determined by the skeleton.
SPACE
If <output-elt> is given, this name will appear in spec
2 of the processor call card: the relocatable or
absolute or procedure output.
COLUMN 2
SPACE
Examples: DESCRIBE NEWASM ASM
DESCRIBE TEST1 ASMP TEST1,NEW
DESCRIBE E1,V1 MAP,B ABSOUT
SPACE
Default: None
COLUMN 13
REMAIN 28
4SELECT
Purpose: This SGS is used to define where the skeleton looks to
find elements to be processed.
SPACE
Syntax: SELECT <spec>
SPACE
COLUMN 24
<spec>: PCF - select elements which have PCF corrections.
TCF - select elements which have TCF corrections.
EITHER - select elements which have either PCF or TCF
corrections.
BOTH - process elements which have both PCF and TCF
corrections.
DESCRIBE - select all -and only- those elements which
apear in 'DESCRIBE' SGS's.
TOC - select all -and only- those elements which
appear in 'TOC' SGS's.
NOTHING - do not select any elements.
SPACE
Examples: SELECT PCF
SELECT TOC
SELECT DESCRIBE
SPACE
COLUMN 13
Default: SELECT EITHER
REMAIN 25
4PROCESS
Purpose: Forces the given element to be processed regardless of
the criterion in the 'SELECT' SGS. May also override
'DESCRIBE' SGS specifications for the element.
SPACE
Syntax: Two forms are possible:
SPACE
A. PROCESS <elt>
SPACE
forces processing of element <elt>.
SPACE
B. PROCESS <elt> <subtype>[,<opts>] [<output-elt>]
SPACE
Fields 2 and 3 override the respective fields of any
'DESCRIBE' SGS for this element.
SPACE
COLUMN 24
Examples: PROCESS ALWAYSELT
PROCESS NONSENSE ASM,Z NONSENSE,REL
SPACE
Default: None
COLUMN 13
REMAIN 31
4MAP
Purpose: This causes the element to be collected, regardless of
the 'SELECT' and 'DESCRIBE' SGS's.
SPACE
Syntax: MAP <elt> MAP[,<opts>] [<output-elt>]
SPACE
Notes: If there is at least one 'MAP' SGS, only elements so
specified will be collected; any other map symbolics
selected for processing will be processed by @ELT. To
prevent all collections, use just one 'MAP' SGS: Map
'NO'.
SPACE
COLUMN 25
Examples: MAP MAPSYM MAP
MAP MAPSYM MAP NEWABS
MAP MAP,NEW MAP,B ABS,NEW
MAP 'NO'
SPACE
COLUMN 13
Default: If no 'MAP' SGS's are given, all elements which are
found to be MAP symbolics (from 'PROCESS', 'DESCRIBE',
or 'TOC' SGS, in that priority) will be @MAP'ed.
REMAIN 26
4FIRST
Purpose: The skeleton processes procs first, maps last, and
everything else in between. The 'FIRST' SGS may be
used to specify that a given element or type of element
is to be processed -before- the procs.
SPACE
Syntax: FIRST <what> <elt or type>
SPACE
COLUMN 24
<what>: ELEMENT - the given <elt> (element, or
element,version) is to be processed first.
SPACE
SUBTYPE - elements with the given subtype are to be
processed first.
SPACE
COLUMN 13
Notes: The default is 'FIRST SUBTYPE DOC'. To specify that
nothing is to be processed before the procs, the
following SGS is needed: FIRST 'NO' (quotes required).
COLUMN 24
SPACE
Examples: FIRST SUBTYPE ELT
FIRST ELEMENT ME,FIRST
FIRST 'NO'
COLUMN 13
SPACE
Default: FIRST SUBTYPE DOC
REMAIN 19
4APPLY
Purpose: Determines which changes to apply in processing
elements.
SPACE
Syntax: APPLY <spec>
SPACE
COLUMN 24
<spec>: PCF - apply PCF corrections only.
TCF - apply TCF corrections only.
BOTH - apply both PCF and TCF corrections.
NEITHER - apply neither PCF nor TCF.
SPACE
Examples: APPLY PCF
APPLY BOTH
COLUMN 13
SPACE
Default: APPLY BOTH
EJECT
4PROCESSOR
Purpose: The skeleton creates a set of 'PROCESSOR' SGS's which
define the processor to be used upon encountering each
element type, the options to use in various situations,
and the spec fields required. The user may specify his
own 'PROCESSOR' SGS's, to override any of these fields.
The SGS's created by the sksleton are known as the
standard 'PROCESSOR' cards. If the user does not
specify anything for a particular subfield, the
skeleton will pick up the value from the standard
'PROCESSOR' card for this element subtype.
SPACE
It is also possible to define a different standard
'PROCESSOR' SGS. This will be explained below.
SPACE
Syntax: A. To redefine the options for a given subtype:
SPACE
PROCESSOR <subtype>,<opt1>,<opt2>,<opt3>,<opt4>
SPACE
COLUMN 24
<opt1> - defines the non-listing type options which
should be used for this subtype. If this
subfield is null, the non-listing options
from the standard 'PROCESSOR' card for this
subtype will be used. To specify that no
non-listing options at all are to be used,
specify 'NO' in this subfield (quotes
required).
<opt2> - options to be used when no listing is
desired. A null subfield results in use of
the no-list options from the standard
'PROCESSOR' card for this subtype. If you
wish to specify that no options are to be
used, specify 'NO' (quotes required).
<opt3> - options to be used for a short listing.
Otherwise, same as <opt2>.
<opt4> - options to be used for a long listing.
Otherwise, same as <opt2>.
COLUMN 13
SPACE
B. To redefine the processor to be used when processing
elements of a given subtype:
SPACE
PROCESSOR <field1> <field2> <elt> [<filename>]
SPACE
COLUMN 24
<field1> - as described aobve.
<Field2> - optional field with following syntax:
SPACE
<Subtype>[,<spec-list>]
SPACE
This second <subtype> is used as a pointer
to the standard 'PROCESSOR' card for this
subtype. It is usually the same as the
<subtype> in <field1>. It is possible to
have several 'PROCESSOR' cards for the same
subtype: The last one encountered (usually
the one supplied by the skeleton) is the
standard one, and is used to fill in any
subfields the user left null.
SPACE
If the <subtype> in <field2> is equal to the
<subtype> in <field1> of some other
'PROCESSOR' SGS, then that other 'PROCESSOR'
SGS becomes the standard 'PROCESSOR' card
for this subtype: Any subfields not
specified here will be satisfied from that
other card.
SPACE
<Spec-list> is a list of 2 or 3 subfields
with the SGS-names of the files applicable
to each spec. (Examples: ASM,SI,RO,SO or
FORP,PI,PO ).
COLUMN 13
SPACE
<Elt> and <filename> may be used to produce @<elt> or
@<filename>.<elt> in place of @<processor>. The usual
conventions apply to <elt> and <filename>.
SPACE
SPACE
Examples:
SPACE
1. PROCESSOR ASM,'NO',E,SJ,LJ
SPACE
Here, the user is redefining the options to be used
when processing ASM symbolics. No special non-listing
options are desired. When no listing is to be
generated, the user wants to use the E-option. Short
listings are to use the SJ-options, and long listings
are to use LJ. The standard PROCESSOR SGS for the
ASM subtype will be used to find the processor name,
its location, and the spec fields required.
SPACE
2. PROCESSOR ASM,'NO',E,S,S ASM OUR,ASM OUR,FILE
SPACE
Here, the user is redefining the name and location of
the processor to be used upon encountering ASM
symbolics, as well as the options. Note that he wants
'long' listings to look just like 'short' listings.
When an ASM symbolic is encountered, the skeleton will
produce '@OUR*FILE.Our/ASM' with the appropriate
options. The standard 'PROCESSOR' SGS for the ASM
subtype will still be used to find the spec fields
required.
SPACE
3. PROCESSOR ASM ASM MASM
SPACE
Here, the user is just redefining the processor to be
called when an ASM symbolic is encountered. Options
and spec fields will still be obtained from the
standard 'PROCESSOR' SGS for the ASM subtype, but the
skeleton will produce '@MASM' instead of '@ASM'.
SPACE
4. PROCESSOR ASM XXX
5. PROCESSOR XXX,Z,N,S,L XXX,SI,RO,AO YYY
SPACE
Example #5 defines a new processor, called @YYY, with
specs SI,RO,AO. 'XXX' need not be equal to any of the
canned standard subtypes. This 'PROCESSOR' SGS will
become the standard 'PROCESSOR' card for the 'XXX'
subtype, or for any other 'PROCESSOR' SGS which has
'XXX' as the <subtype> in <field2>, as does example #4.
SPACE
Default: An entire set of standard 'PROCESSOR' SGS's is
generated by the skeleton. See the skeleton for the
contents of these standard cards, since you may wish to
change them.
REMAIN 41
4LIST
Purpose: Of the elements selected for processing, determines
which ones are to be listed, and at what length.
COLUMN 24
SPACE
Syntax: LIST <what>[,<how>]
SPACE
<what>: PCF - list only the elements having PCF
corrections.
TCF - list only the elements having PCF
corrections.
EITHER - list only the elements having PCF or TCF
corrections.
BOTH - list only the elements having PCF and TCF
corrections.
ALL - list all elements selected for processing.
NONE - don't list any elements.
SPACE
COLUMN 13
Elements which are being processed but are not to be
listed will be given the <opt2> options from the proper
'PROCESSOR' SGS.
COLUMN 24
SPACE
<how>: SHORT - short listing desired. Use <opt3> options
from proper 'PROCESSOR' SGS.
LONG - long listing desired. Use <opt4> options
from proper 'PROCESSOR' SGS.
NOT - no listing desired. Use <opt2> options from
proper 'PROCESSOR' SGS.
SPACE
COLUMN 13
Notes: 'LIST NONE' is equivalent to 'LIST <x>,NOT'.
Otherwise, if <how> is not specified, 'SHORT' is
assumed. In all cases, the listing options used are in
addition to the <opt1> (default) options, or the
options from the 'MAP', 'PROCESS', or 'DESCRIBE' SGS.
SPACE
'MAP' elements are treated as a special case for
listing purposes: If 'LIST NONE' or 'LIST <x>,NOT' is
specified, the no-listing options will be used.
However, if 'LIST <PCF/TCF/BOTH/EITHER>,<how>' is
specified, 'MAP' elements will be given the specified
<how> options even if they don't have corrections of
the specified type.
COLUMN 24
SPACE
Examples: LIST ALL,LONG
LIST EITHER,SHORT
LIST NONE
COLUMN 13
SPACE
Default: LIST ALL,SHORT
REMAIN 17
4LANGUAGE
Purpose: Specifies the assumed symbolic subtype of any element
for which the subtype can not be determined from a
'MAP', 'PROCESS', 'DESCRIBE', or 'TOC' SGS. (The above
is the priority order).
SPACE
Syntax: LANGUAGE <subtype>
COLUMN 24
SPACE
Examples: LANGUAGE ELT
LANGUAGE ASM
COLUMN 13
SPACE
Default: LANGUAGE ASM
REMAIN 10
4MERGE
Purpose: If this SGS is given, elements will not be updated;
instead, the PCF and TCF will be merged to create (by
an @ELT,IL) an element of the name given.
SPACE
Syntax: MERGE <elt>
SPACE
Example: MERGE NEWPCF
SPACE
Default: Process normally, don't merge.
REMAIN 16
4UPDATE
Purpose: Specifies that an updated PCF is desired.
SPACE
Syntax: UPDATE
SPACE
Notes: If 'UPDATE' is specified, the TCF will be merged into
the PCF, updating the PCF. This is different from the
'MERGE' SGS, in that normal processing is still done.
(Rather than doing a *CORRECT for each element being
processed, a *CORRECT,PK will be done). Note that this
SGS should be used only if 'APPLY BOTH' is also used.
SPACE
Default: Process normally, do not update PCF.
REMAIN 16
4CORRECT
Purpose: If you have the corrections for a given element
separate from the PCF or TCF, or you'd like to use
these corrections rather than what's in the PCF and
TCF, you may use the 'CORRECT' SGS.
SPACE
Syntax: CORRECT <elt1> FROM <elt2> [<filename>]
SPACE
Notes: When the given <elt1> is being processed, this will
produce an '@ADD,E <elt2>' rather than a *CORRECT
<elt1>.
SPACE
Default: None
REMAIN 25
4ALPHA
Purpose: If this is specified, elements (within each class) will
be processed in alphabetical order. This SGS applies
both to updating and to merging operations.
SPACE
Syntax: ALPHA
SPACE
Notes: Because of the weaknesses of the SYMSTREAM language,
alphabetization is expensive for more than about a
dozen elements. For more than two dozen elements, it
tends to become prohibitive. Note that if change-files
are alphabetical, 'SELECT TCF' (or 'PCF') will produce
alphabetical output. To list everything alphabetically
while applying updates, it may be desirable to name all
elements in the TCF, or even to set up a full set of
'DESCRIBE' SGSses in alphabetical order. Judicious use
of the @SSG O and S-options may also help.
SPACE
We welcome any suggested algorithms for sorting with
decent efficiency.
SPACE
Default: Don't alphabetize.
REMAIN 21
4PROGRAM
Purpose: Optional SGS which may be used to add descriptive
information to the headings produced by the skeleton.
SPACE
COLUMN 24
Syntax: PROGRAM <program name>
COLUMN 13
SPACE
Notes: This SGS may have as many fields and subfields as
necessary. The contents of all fields and subfields
will be concatenated and included in the headings.
Spaces will be inserted between fields, but not between
subfields.
COLUMN 24
SPACE
Examples: PROGRAM BATCH INTER,FACE
PROGRAM MYPROG LEVEL 5,A
SPACE
COLUMN 13
Default: None
REMAIN 35
4LEVEL
Purpose: Optional SGS which may be used to add descriptive
information to the headings produced by the skeleton.
Also may be used to convey level information to the
program, through @MAP 'EQU' directives.
SPACE
Syntax: LEVEL <level #> [<level tag> <mapelt> <mapcor> ...]
SPACE
Notes: <Level number> is field 1 only, but may be composed of
several subfields. For heading purposes, a '-' will be
inserted between each subfield.
SPACE
Fields 2 through n are optional. If not given, the
'LEVEL' SGS is used only for heading purposes, and the
level number subfields may therefore contain any
character which is legal in a heading.
SPACE
If fields 2 through n are given, they have the
following meaning:
COLUMN 24
SPACE
Field 2: <Level tag> - this field should have the
same number of subfields as field 1. It
specifies the tags to be associated with
each subfield of the level number in field
1. For example:
SPACE
LEVEL 7,2,5 BASE,PCF,TCF ... ...
SPACE
Field 3: <Mapelt> - the element or element,version
name of the MAP element to which the 'EQU'
directives are to be added.
SPACE
Field 4: <Mapcor> - the desired correction card for
the MAP element given in field 3.
SPACE
Field 5-n: Same as fields 3 and 4, for additional MAP
elements.
SPACE
COLUMN 13
Note that when used for this purpose, field 1 may
contain only those characters which are acceptable for
the value in a @MAP 'EQU' directive.
SPACE
COLUMN 24
Examples: LEVEL 10,4
SPACE
This will result in '10-4' being part of the heading.
SPACE
LEVEL 7,6 BASLEV,UPDLEV MFDMAP ''-1,2''
SPACE
This would cause '7-6' to be part of the heading, and
would generate:
SPACE
*MFDMAP
-1,2
EQU BASLEV/7
EQU UPDLEV/6
SPACE
LEVEL 6 BASE MAPSYM -93 MAP,VERS ''-13,14''
SPACE
this would cause '6' to be part of the heading, and
would generate:
SPACE
*MAPSYM
-93
EQU BASE/6
*MAP/VERS
-13,14
EQU BASE/6
SPACE
Default: None
EJECT
COLUMN 2
REMAIN 20
4HEADING
Purpose: To insert options and/or print control commands
into the @HDG cards generated by the skeleton.
SPACE
Syntax: HEADING <options> [<print control>]
SPACE
Notes: If no options are desired on the @HDG card,
the options field can be set to 'NO' (quotes
included). Field 2 can contain an exec print
control image and, if used, a period will be
inserted preceeding it.
SPACE
Example: HEADING PN L,0
SPACE
This will generate:
SPACE
@HDG,PN PROGRAM: WHAT LEVEL: 1R1 ELEMENT: HUH .L,0
SPACE
Defaults: None
EJECT
4CULL
Purpose: To generate a @CULL call card after all other
processing is done.
SPACE
Syntax: CULL <opts> <type>[,<scol>,<res>] [<file> <file>...]
SPACE
Notes: <type>, <scol>, and <res> are as described in the
PRM (UP-4144.4, Volume 4).
SPACE
Fields 3 through n are filenames (with possible
qualifiers) to be culled.
SPACE
Example: CULL msw data,80 qual,file filex
SPACE
This generates:
SPACE
@CULL,MSW DATA/80,QUAL*FILE.,FILEX.
SPACE
Default: None
4CULLDATA
Purpose: If the CULL SGS is used, data cards may be passed
to the CULL processor through the CULLDATA SGS.
SPACE
Syntax: CULLDATA <string> [<string> <string> ...]
SPACE
Notes: Fields 1 through n are character strings to be
scanned by the CULL processor. Any number of
CULLDATA SGS's may appear.
SPACE
Default: None
roman on