CREF.DOC -- Changes from V53(53) to V53B(71)
July 1980
COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION
1972,1974,1976,1977,1980,1986.
ALL RIGHTS RESERVED.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION
OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER COPIES
THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER
PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND
SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
CRF53B.DOC Page 2
CREF.DOC -- Changes from V53(53) to V53B(71)
July 1980
1.0 SUMMARY
This is a maintenance release of CREF, a program for generating cross
reference listings.
Version 53B of CREF must be loaded with the field image version of
HELPER.
CREF version 53B is supported by Digital Equipment Corporation, and runs
on all supported monitors as released. Version 53B fully supercedes all
previous versions, and includes edits up to #71.
Documentation for using CREF is contained in the help file CREF.HLP, and
in the Operating System Commands Manual and the specifications section
of the TOPS-10 Software Notebooks.
2.0 EXTERNAL CHANGES
1. When a CRLF is typed in response to the CREF prompt "*", CREF
will still search for CREF.CRF but will no longer complain if
it is not found, it will simply reprompt. If CREF.CRF is
found, the file will be processed in the normal way with the
appropriate messages.
2. It is worth noting that CREF should now process long symbols
(i.e. symbols of length greater than six characters)
correctly.
3.0 KNOWN BUGS AND DEFICIENCIES
1. There are no known bugs in CREF 53B(71) as of 15-Jul-80.
2. The command scanner in CREF, which has not been changed since
version 53, still does not recognize all the errors a user
might type.
3. The "/R" switch applied to multiple FORTRAN input listings may
or may not do what the user intended. The meaning of the
switch in this case is somewhat ambiguous - does the user want
each separate subroutine to be restarted at the specified line
or does the user want the line-printer output to be restarted
at the physical printed line specified?
CRF53B.DOC Page 3
4.0 INSTALLATION INSTRUCTIONS
Files involved:
CREF.MAC -- source file which makes up this product.
CREF.EXE -- the executable file.
CREF.HLP -- the help file.
CREF.DOC -- the documentation file
To install CREF Version 53B on your system, copy the file CREF.EXE to
SYS:.
To quickly create a new version of CREF.EXE simply LOAD CREF.MAC and
then, if the system is TOPS-10, SSAVE CREF.EXE, or if the system is
TOPS-20, SAVE CREF.EXE.
This assumes that HELPER.REL is on REL:.
5.0 INTERNAL CHANGES
Edit Description
54 Allow differential line numbers to be negative, so
nonmonotonic line numbers won't bother CREF. This removes
edits 22, 25, 26.
55 Don't eat type-ahead if nothing returned from rescan.
56 Fix CREFing of FAIL output - broken by edit 22.
57 Don't try to put listing creation date in the future.
60 Update copyright date, and release as CREF %53A(60).
61 A null line no longer produces an error message.
62 CREFed long FORTRAN instructions no longer contain garbage.
63 One underbar error message per command line and no longer
caused by SWITCH.INI.
64 Addition to edit 61 for DEC-20s.
65 CREF only sorts first six characters of long symbol names.
66 CREF loops infinitely when handling symbols with leading
spaces. Disallow spaces in symbols (remove them). Also fix
edit 62.
67 CREF uses excess CRLFs when CREFing long symbols.
CRF53B.DOC Page 4
70 Change lowercase symbols to uppercase before converting to
sixbit.
71 If a comment line preceeds a CREF line in SWITCH.INI, the CREF
line will not be read.
[End of CRF53B.DOC]
[CRF53.DOC is appended as an integral part of CRF53B.DOC]
CRF53.DOC Page 5
CREF.DOC -- Changes from V52(27) to V53(53)
January 1977
1.0 SUMMARY
CREF 53(53) is CREF %52A(27) with a somewhat-enhanced command scanning
and parsing routine, plus general edits to clean up the overall
user-interface. There have been no changes made to the actual inner
workings of how CREF processes input files to generate the cref listing.
CREF %52A(27) runs on all supported 5 and 6 series monitors up to and
including 6.03. CREF 53(53) is fully upwards compatible with CREF
%52A(27) except for its more stringent requirements on commands
(previous illegal or illogical commands which could slip through earlier
versions will be flagged as errors by this version - also old altmodes
are no longer treated as break characters but rather as normal ASCII
graphic characters; the "_" character is being phased out and replaced
by the "=" character).
CREF is documented in Software Notebook Vol. 8.
2.0 EXTERNAL CHANGES
The major difference between CREF 53(53) and earlier versions of CREF is
in the interface with the terminal user (typed-in commands, error
messages, etc.).
2.1 The Saved Core Image
CREF %52A(27) had non-zero data in it's low seg and so had a .LOW file.
Since this can cause lots of unnecessary overhead (forces the monitor to
always go to disk to get the core image rather than being able to read
it directly off the swapping area - which is much faster) CREF 53(53)
has moved all this data into it's high seg.
2.2 Typed-In Commands
CREF's command scanner has been enhanced and modified to be more closely
compatible with the rest of the TOPS10 world. Specifically, the
conventions used by SCAN have been adopted wherever applicable.
CRF53.DOC Page 6
1. Command Syntax
Many illegal or otherwise illogical syntaxes that earlier
versions of CREF would accept have been dis-allowed. This in
no way affects otherwise legal command constructions. For
example CREF %52A(27) would allow you to specify device DSK:
and ppn [1,2] by typing "DS[1,2]K:" but the (legal to SCAN)
command ".FOO MUMBLE BLAH:" (to specify file BLAH:MUMBLE.FOO)
would be interpreted by CREF as meaning FOOMUM:CREF.CRF!
2. Old Altmodes
The ASCII characters - (tilde and right curly brace - octal
codes 175 and 176 respectively) are, in keeping with modern
standards, no longer considered to be break characters - the
so-called old altmodes. They are now just 2 other ASCII
printing characters like the letters or "%". If the user
wishes to continue using the (tilde and right curly brace) as
old altmodes then he may use the monitor command ".TTY ALTMODE"
to pass them as <ESC> (octal code 33) to his programs.
3. Destination - Source Specifier
In keeping with modern conventions the "_" character
(underscore or left-arrow - octal code 137) is no longer used
to delimit the destination or output file specs from the source
or input file specs. The user should now use the "=" (equal
sign, octal code 075) for this purpose. The "_" character is
dedicated to use in network node specifications. For the time
being, CREF will continue to accept "_" but will issue a
warning message to annoy you.
4. Default PPN Specifications
You may now type constructs like "[,] or "[,4321]" (i.e., null
project or programmer fields) to specify default (logged-in)
ppn attributes. "[-]" means use the job's default path. SFD
fields in the path specification may not be left null. The
trailing "]" is needed only if further file specs follow which
need to be delimited from the path specification.
5. Random Illegal Control Characters
Characters such as Control-A or Control-F are no longer allowed
(Syntax error) in command strings.
CRF53.DOC Page 7
6. Comments
The ";" (semicolon) character is now recognized as a comment
character. When a ";" is encountered in the command input
stream then it and all text up to the next break character will
be ignored. Note that the sometimes comment character "!" is
still used for specifying a "RUN" command to the file whose
file specs it terminates.
7. Continuation
Following SCAN's conventions, if a "-" character is the last
non-blank non-comment character on a command line then both it
and the break character (and any comments) will be ignored and
CREF will continue to accept command input. If the command
device is the user TTY and a line of input has not already been
typed (as in typed ahead) then CREF will output a "#" character
to prompt you.
8. SFD's
CREF 53(53) will now accept SFD path specifications in all file
path specs. Null SFD's are illegal.
9. Command Files
CREF will now recognize the "@" character as meaning that the
current file specs are to be treated as an indirect command
file. The "@" may appear anywhere in the file specs. If an
indirect command file is to be used then it must be the first
set of file specs on that command line (everything following
will be ignored).
10. CCL Entry and the Monitor CREF Command
The user may now type optional arguments to the CREF monitor
command. If no arguments are specified then the command works
just as it did with earlier versions. The arguments may be
either CREF switches or file specifications (with optional
switches).
If the user specifies just CREF switches in the CREF command
(e.g., ".CREF/O/R") then those switches will be remembered and
applied to all files being processed in the current CCL request
(typically following a COMPILE/CREF monitor command).
If the user types file specifications in the CREF command
(e.g., ".CREF LPT0:=BLAH/P") then the rest of the line
following the "CREF" command will be treated as if the user had
first typed ".R CREF" then typed the rest of the command
("LPT0:=BLAH/P"). After the command has been processed CREF
will exit - no attempt will be made to also look for CCL
command files to read.
CRF53.DOC Page 8
2.3 Multiple Input Files
When multiple input files are specified to CREF all files in the command
string (the input files of course) will now be deleted. Formerly, only
the last file specified got deleted. Due to the vagaries of CREF's
command scanner all processing switches (e.g., "/O" or "/K") must be
given no later than the first input file spec. Switches such as "/A"
and "/B" work on the indivividual file spec to which they are attached.
Note especially that to preserve the input files (if they are not
otherwise protected against being deleted) the "/P" switch must be
specified no later than the first complete file spec!
One other thing the user should be aware of is that if CREF finds a
syntax error in the command string (e.g., ".DSK:") then the entire
command will be aborted - any files that have already been processed for
that command will have been deleted, and the output will be lost (the
user will have to regenerate the input .CRF files again).
2.4 Error Message Typeout
The handling of error messages by CREF has been cleared up somewhat to
provide a nicer and more consistent error facility, again maintaining
compatibility with SCAN.
1. Upper/Lower Case
All error messages now appear in the standard DEC format of
leading character ["?", "%", or "["] followed by the
six-character error code or "prefix" followed by the text body
of the error message itself (followed by a "]" to terminate the
message if it was lead off with a "["). All error messages
appear in upper and lower case for neatness. (The prefix is
always uuper case only, as are all file specs that are typed
out.)
2. /MESSAGE:(PREFIX,FIRST,CONTIN)
The standard (error) message output format is adhered to. The
"/MESSAGE" setting in the user's watch word is used to
determine which fields are actually to be printed on the user's
TTY. If all settings are blank then PREFIX and FIRST are
assumed. (Note that CREF does not have a /MESSAGE switch - it
can only read the watch word to see what the user job has set.)
CRF53.DOC Page 9
3. New Messages
CREF 53(53) has the following new messages for your amusement:
a. %CRFPUE Please Use "=" Rather Than "_"
The underscore (or left arrow on some TTY's - octal code
137) is reserved for use by network protocal to specify
nodes. The "=" character should be used instead.
b. %CRFSIH "/H" or "/R" Switch Illegal In SWITCH.INI
The two switches "/R" and "/H" are illegal when specified
in SWITCH.INI defaulting. The "/H" would never let you get
any work done - the philosophy of the HELP switch is that
when it is encountered the help message is output to the
user's TTY and the current command is aborted. The "/R"
switch has no complement and so can not be turned off once
you have set it (it's cleared at the start of every command
but if it's also set every command you're stuck) so it has
been made illegal.
c. %CRFSII Syntax Error In SWITCH.INI Defaults
CREF is unable to read SWITCH.INI due to some construct in
SWITCH.INI which is illegal (for example trying to give
file specs). SWITCH.INI will be ignored.
d. %CRFSIO I/O Error While Reading SWITCH.INI
In process of reading SWITCH.INI CREF got an I/O error of
some type. SWITCH.INI will be ignored, defaulting will not
occur.
e. ?CRFUKS Unknown Switch
The user (or SWITCH.INI) specified an illegal switch. If
the illegal switch appeared in SWITCH.INI then the fact
will be noted in the message.
f. ?CRFCDN Can't Get Command File Device
The device specified in the command stream as the new
indirect command file device cannot be OPENed by CREF.
g. ?CRFCLC Can't LOOKUP Command File
The indirect command file specified in the input stream
cannot be found for reading by CREF.
CRF53.DOC Page 10
h. ?CRFIBP Input Buffer Size Phase Error
This error can only happen on multiple input files. Since
the input buffers are allocated before the file is
processed, files later in the command string must not use
more buffer space than the first input file (or buffers
would overwrite the various symbol tables CREF is
building). Should this happen (for example reading first a
file on disk - with 200 (octal) word buffers - then a file
on a magtape written with 2K word buffers) then this error
message will be issued and the current command will be
aborted.
2.5 SWITCH.INI Switch Defaulting
CREF 53(53) now supports basic switch defaulting via the file
DSK:SWITCH.INI[,]. The user may put in any switches other than "/H" or
"/R" but should be cautioned that tape-positioning commands "/A" and
"/B" will not be effected more than once per file spec (i.e., the
sequence "/A" or "/A/A/A/A" appearing in SWITCH.IN would have an
identical effect - the "/A" function would be applied once to each file
spec the user typed. The user may not specify file specifications in
SWITCH.INI.
SWITCH.INI is read when CREF is started and a "map" of the switches
specified is made and remembered, then applied as needed for successive
user commands (either CCL or regular typed-in commands).
The switch "/C" Cancels SWITCH.INI defaulting; the switch "/D" restores
SWITCH.INI defaulting (note that to completely cancel SWITCH.INI
defaulting the "/C" switch should be issued on the output file specs).
3.0 KNOWN BUGS AND DEFICIENCIES
There are no known bugs in CREF 53(53) as of 6-Dec-76.
The command scanner in CREF still isn't very smart, and can bomb you out
rather inelegantly.
The "/R" switch applied to multiple FORTRAN input listings may or may
not do what the user intended. The meaning of the switch in this case
is somewhat ambiguous - does the user want each seperate subroutine to
be restarted at the specified line or does the user want the
line-printer output to be restarted at the physical printed line
specified?
CRF53.DOC Page 11
4.0 INSTALLATION INSTRUCTIONS
The source file for CREF is standalone (it does not need any external
parameter files) so simply compile it with MACRO-10.
CREF needs the standard HELP processor HELPER.REL when being loaded.
5.0 INTERNAL CHANGES
EDIT SPR WHAT AND WHY
30 none General cosmetic edits to make the listing prettier and
easier to read.
31 none Move the data introduced into the low segment into the
high segment so as to allow CREF to be resident on the
swapping space and much easier on the monitor. The
data (introduced by the TOPS20 compatibility edits)
will be BLT'd down at program start time.
32 none Add code to recognize and handle SFD's in file path
specifications.
33 none Add code to allow user to type in file specs to be used
as indirect command file.
34 none Convert all messages from SIXBIT to ASCII and put them
in mixed upper/lower case for neat appearance.
35 none Begin change over to using "=" rather than the older
"_" character to delimit input and output file
specifications. The "_" character is reserved for
network usage (specifying nodes).
36 none Generally clean up the low level command input code.
Treat the old altmode characters "~" and "}" as regular
ASCII characters.
37 none Teach cref about comments (";") and continuation lines
("-"). Use SCAN's conventions regarding such
constructs as "BLAH - ;comment comment" (this case
would be considered a continuation line).
40 none Teach CREF about the /MESSAGE bits in the job's watch
word. Output the various messages in the appropriate
format.
41 none Make non-break control characters before <LF> be syntax
error (formerly would treat as pseudo-break characters
and internally delimit the command).
42 none Make illegal switch processing more elegant, put in
"?CRFUKS Unknown Switch" message.
CRF53.DOC Page 12
43 none Do a RESCAN on CCL entry so can allow users to type
monitor command of form ".CREF/P" to make the "/P"
switch sticky on all CCL processing. Also allow
commands of form ".CREF TTY:=BLAH/S/O/P" etc.
44 none Support DSK:SWITCH.INI[,] for defaulting switches.
45 none Bug in "/R" processing, conflicts with "/R" in CCL file
and "/R" in ".CREF/R" commands, with ".CREF A=B/R"
commands.
46 none Some code got moved around, if indirect command file
didn't exist could get into the RUN processor rather
than the error message processor.
47 none Look for SWITCH.INI on logged in PPN rather than
default path. This is the way SCAN does it and we
should try to be compatible.
50 none When reading multiple input files delete each one as we
go rather than just the last one. (Be sure not to
delete any of them if the "/P" switch was given!)
51 none Make the command scanner even more picky
(unconditionally cause error message if syntax error -
don't try to find files based on the partial specs
built up before the error) yet more flexible as to
constructs of the form ".FOO MUMBLE blah:" a la SCAN.
Make the monitor-level command "CREF/H" EXIT after
having typed the help text.
52 10-18277 Must wait to setup input buffers until have setup
output buffers so as not to reset .JBFF below the
output buffers (and thereby timeshare them with the
symbol chain being built in "free core"). Also, for
multiple
53 none Edit 50 went too far: only delete input file if
extension is .LST or .CRF. input files make sure
successive files do not use more buffer space than the
first file used - or the input buffers will run into
the already-extant (and allocated!) "free core" area
(issue the ?CRFIBP error message in this case).
CRF53.DOC Page 13
6.0 SUGGESTIONS
It would be nice if CREF were smarter in how it handled command errors -
say "Duplicate device illegal" instead of the general catch-all "Syntax
error". Especially, CREF should not go trapsing around looking for
things to do if the user only typed <CR><LF>, it should just give out
another "*" and let it go at that.
Put in SCAN and WILD for true compatibility with other DEC software
(like DIRECT), also give ability to use wildcards (e.g., ".CREF
*/SINCE:YESTERDAY/O" etc.).
[End of CRF53.DOC]
[CRF51.DOC is appended as an integral part of CRF53.DOC]
CRF51.DOC Page 14
CREF.DOC -- Changes from V47 to V51(20)
September 1974
1.0 SUMMARY
The reasons for this release are:
A) To provide support for FORTRAN-10 version 2.
B) To correct outstanding bugs in CREF version 47.
C) Define error mnemonic per DECsystem-10 error message standard.
CREF version 51 is CREF version 47 with edits 17 and 20. This version
fully replaces all earlier versions of CREF and is upward compatible.
2.0 EXTERNAL CHANGES
All messages typed by CREF are preceded by appropriate error mnemonics
per the DECsystem-10 error message standard.
The command scanner will exit on an EOF from the input stream.
3.0 KNOWN BUGS AND DEFICIENCIES
CREF V51 has no known bugs or deficiencies.
4.0 INSTALLATION INSTRUCTIONS
None.
5.0 INTERNAL CHANGES
CREF now includes routines to read line numbers from the input file for
use in generating cross reference information.
Unsupported feature test switches have been added for FAIL format CREF
files and for the TENEX file system.
A new SORT routine has been added to speed up sorting the CREF listing.
CREF now supports a terminating character to allow the user to terminate
CREF information without inserting either line numbers or tabs into the
output listing (thus making it possible to have multiple blocks of CREF
information of a line).
CRF51.DOC Page 15
An additional terminating character for program break has been defined.
The following are the edits made:
EDIT #
17 HPW - Implement new features for FORTRAN-10 version 2. Define error
mnemonics.
20 ASM - Add features for the TENEX file system.
[End of CRF51.DOC]
[CRF47.DOC is appended as an integral part of CRF51.DOC]
CRF47.DOC Page 16
CREF.DOC -- V47(16)
November 1972
1.0 SUMMARY
CREF's command language features have been cleaned up:
CREF publishes its name "CREF: " and the names of the input files when
running in CCL mode, and "NAME!" is accepted to run another program.
DSK: is the default output device when an explicit output file name is
present.
2.0 EXTERNAL CHANGES
CREF publishes its name on the user terminal when running in Command
Language mode.
When an explicit output filename is present, DSK: is the default output
device. If no explicit output file name is present, LPT: remains the
default output device.
A lookup failure on an input file (such as if the file does not exist)
no longer causes CREF to abort operation. CREF will continue scanning
input files and creating the cross reference listing(s), minus the
missing input file. The "?CANNOT FIND FILE ... " message will be typed
for each occurance of a missing file. (if the missing file is the first
input file not in CCL mode, that is, typed in by hand, CREF will still
abort, allowing the user to retype the command.) This change allows CCL
files to run to completion even if one small part fails, and allows CREF
to delete the command file at the end, thus precluding the same missing
input file from causing messages and terminated operation on any
following CREF commands. If any file is missing, CREF sets the /P
switch so no input file will be deleted.
There is a "HELP" text. Typing "/H" will cause the file SYS:CREF.HLP to
be typed on the users terminal.
"NAME! will run the program SYS:NAME".
The "?COMMAND ERROR" message now reads
"?COMMAND ERROR--TYPE /H FOR HELP".
3.0 KNOWN BUGS AND DEFICIENCIES
When more than one input file is combined into a single cref listing,
CREF deletes only the last input file instead of all the input files.
Proper operation would store the filenames of all the input files and
CRF47.DOC Page 17
delete them only after all the input files are read and the output file
is closed with no errors.
CREF still won't accept a command file with @filename.
4.0 INSTALLATION INSTRUCTIONS
None.
5.0 INTERNAL CHANGES
A KI10 core allocation bug is fixed. At the beginning of each input
file, the switch allowing only the new CREF special codes is cleared so
that older programs and FORTAN listings may be combined with the newer
listings produced by MACRO. An old monitor bug has been fixed. This
bug caused an output file to be deleted if an input file of the same
name was deleted. CREF's defensive code to avoid deleting input files
in this case has been removed. Since the monitor bug has been fixed for
two years, hopefully this will cause no problems.
A general cleanup of the cref listing was done. The standard TECO macro
to format the listing and allign the comments was used. FILCOM's /B/C
switches make comparing the old and new versions reasonable.
All of CREF's internal "RPG" symbols were edited to change them to "CCL"
symbols to make them more mnemonic.
[End of CREF47.DOC]