Trailing-Edge - PDP-10 Archives - bb-d549g-sb - crf53.doc
There are no other files named crf53.doc in the archive.

CREF.DOC -- Changes from V52(27) to V53(53)
January 1977

Copyright (C) 1972,1974,1976,1977
Digital Equipment Corporation, Maynard, Mass.

This software is furnished under a license for use only  on  a  single
computer system and may be copied only 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 except for
use on such system and to one  who  agrees  to  these  license  terms.
Title  to  and  ownership of the software shall at all times remain in

The information in this software is subject to change  without  notice
and  should  not  be  construed  as  a commitment by Digital Equipment

DEC assumes no responsibility  for  the  use  or  reliability  of  its
software on equipment which is not supplied by DEC.
CRF53.DOC                                                       Page 2

CREF.DOC -- Changes from V52(27) to V53(53)
January 1977


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

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.


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 3

     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

     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

     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 4


         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 5

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

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.)


         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 6

     3.  New Messages

         CREF  53(53)  has  the  following  new  messages   for   your

         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 7

         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).


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
CRF53.DOC                                                       Page 8


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.


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

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

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 9

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

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 10


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

[End of CRF53.DOC]

[CRF51.DOC is appended as an integral part of CRF53.DOC]
CRF51.DOC                                                      Page 11

CREF.DOC -- Changes from V47 to V51(20)
September 1974


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

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.


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.


CREF V51 has no known bugs or deficiencies.




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

CREF now supports  a  terminating  character  to  allow  the  user  to
terminate  CREF  information  without inserting either line numbers or
CRF51.DOC                                                      Page 12

tabs into the output listing (thus making it possible to have multiple
blocks of CREF information of a line).

An  additional  terminating  character  for  program  break  has  been

The following are the edits made:


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 13

CREF.DOC -- V47(16)
November 1972


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

DSK:  is the default output device when an explicit output  file  name
is present.


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



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.
CRF47.DOC                                                      Page 14

Proper operation would store the filenames of all the input files  and
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.




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

All of CREF's internal "RPG" symbols were edited  to  change  them  to
"CCL" symbols to make them more mnemonic.

[End of CREF47.DOC]