! CAM help file for VMS
! Nick de Smith
!
1 CAM
 CAM is a utility written in C to  reduce  relocatable  DEC
 format  object  modules  to macro. A great many formatting
 options are available such that MAC type listing files may
 be  produced  as well as assembler  code that  can be used 
 without  modification  as input for MAC/MACR to re-produce
 an identical object module.
!
2 Brief_Flags
 Flag     Action
  s       Output absolute global defs sorted
  t       Don't output 'ascii' of opcodes/data
  e       Treat EMT 377 as RSX DIR$. Default is to use RSTS name
  a       Don't output list of absolute global defs
  l       Don't output line numbers
  f       Treat floating opcodes as data
  r       Don't output list of referenced globals
  o       Don't output octal of opcodes/data
  m       Don't do 'macro' translation on opcodes
  n *     Attempt to resolve numeric constants
  i       Ignore 'load address mismatch' errors
  b       Output all binary as .word or .byte (no opcodes)
  c       Don't output opcodes/data
  k       Treat all kernal mode opcodes as data
  p       Output list of psects in order of declaration
  d       Set debug mode
  q       Output table of psect internal data

* Not in this release
2 Verbose_Flags
 Flags are single characters preceeded by '-'.  Several flags
 may   be  concatanated  preceeded  by  a  single  '-'.   eg.
 '-fkol'.  No two flags conflict with each other.

 On VMS '/' may be used instead of '-'. eg. '/fkol'.

/f (Flt.Pt.)
 Treat floating point instructions as data.  If you
 think  that  there  shouldn't  be  any  FP11/KEF11
 instructions in the object file, use this flag.

/k (Kernal mode)
 Treat kernal mode opcodes as data.   Use  of  this
 flag  disables  decoding  of  instructions such as
 'halt' and  'wait'.   If  you  are  processing  an
 object  module  that  was designed for use in user
 space, then use this flag.

/e (EMT handling)
 By default, CAM will interpret 'emt'  instructions
 and  translate  them  to their RSTS equivalent (if
 there is one).  Use of  this  flag  disables  this
 feature and makes 'emt 377' appear as 'dir$'.  Use
 this flag if the object module did not  come  from
 RSTS.

/l (Line #)
 Don't output line numbers.

/o (Octal)
 Don't   output   the   octal   of   the    decoded
 instructions.

/b (Binary)
 Disable opcode output. All data is output as .word
 or .byte data items.

/c (Code)
 Don't output the decoded  instructions.   This  is
 useful if you just want referenced globals etc.

/r (Ref. Globals)
 Don't output the list of referenced globals.

/a (Abs. Globals)
 Don't  output  the   list   of   absolute   global
 definitions.

/t (Text)
 Don't output the 'ascii' of the data.  By default,
 CAM  will  output (in the comment field) the ascii
 of   any   printable   character   (or   '.'   for
 un-printable ones) in the data fields.

/s (Sort)
 Output the list  of  absolute  global  definitions
 sorted  by psect and offset within each psect.  By
 default, CAM outputs  this  list  (unless  -a  was
 used)  in  the  order  in  which  the globals were
 encountered in the object file.  Use of this  flag
 can  save  a  considerable  amount of space if you
 find CAM runs out of memory and the object  module
 contains a lot of absolute globals.

/m (Macros)
 Disable the 'macro' feature.  By default, CAM will
 translate  certain  instructions  into macro calls
 such  as  those  found  in  'common.mac'.   Macros
 currently  supported  include:  return, push, pop,
 call, callx and jmpx.  The  definitions  of  these
 macros  can  be found in the file CAMPRE.MAC.  Use
 of this flag will cause the actual instructions to
 be output.

/q (Quaggy)
 Output a table of all  the  psects  found  in  the
 object  module,  their  segment number, length and
 attributes.  This flag was originally provided for
 debugging  purposes,  but  some people may find it
 useful.

/p (Psects)
 Output a list of  all  the  psects  found  in  the
 object module, along with their attributes, in the
 order in which they were encountered.  Use of this
 flag  will  ensure that, if the dis-assembled code
 is re-assembled, the  psects  in  the  new  object
 module will have the same segment numbers as those
 in  the  old  module.   This  is   not   generally
 important,  but  some code depends on psects being
 declared in a particular order.

/i (Ignore)
 Ignore  load  address  mismatches.   This  is   an
 absolute  hack.   Certain  object modules, such as
 those  TKB  produces  for  resident  library  .stb
 files,  contain very strange record formats.  This
 flag should never be needed on a  standard  object
 module.  Don't use it (please).

/d (Debug)
 Set debug mode.  Use  this  if  you  want,  but  I
 shan't say what it does!

/n (Numbers)
 Attempt  to  resolve  numerical  constants  in   a
 supplied  STB file.  This feature is not available
 in the current release version.
2 Tested_Versions
 Currently CAM can handle object modules produced under RSX-11,
 RSX-11M+, RSTS/E RSX and RT-11 emulation, RT-11 native mode,
 VMS compatability mode, VAX-11 RSX (VMS V4.1) and IAS.
 CAM  has  only  been  tested actually running on RSX native mode,
 RSTS/E RSX emulation and VMS compatability mode with native RSX-11,
 RSTS/E RSX, RT-11 (*) and VMS compatability mode input files.

 It might even work on PO/S.

 * There is a rumour (though of course I can't confirm it!), that the
   whole of a RSTS/E object system has been reduced to MACRO and
   re-assembled without error.
2 Invoking
 CAM is invoked as a foreign command of the form:

	$ cam file.typ -flags

 where 'file.typ'  is  the  object  module  to  examine,  and
 'flags'  represents  a  combination  of  the flags specified
 below.  By default the output is  to  the  user's  terminal,
 however output to a file may be specified by using a command
 of the form:

              cam file.typ -flags >output.fil

 where 'output.fil' is the required output file specification
 which must be preceeded by a '>' character.
2 Problems
 31-Jan-84

 There is one current problem area for CAM:

 Psects consisting just of allocated space with a symbol in
    the middle, eg.

            .psect jim

            .blkb 42
    Bar:    .blkb 30

            .end

    May have problems. If a problem does appear, it will manifest
    itself as either a psect that has not been extended to its
    maximum length, eg.

            .psect jim

            .blkb 42
    Bar:
            .end

    or the label will not be output, eg.

            .psect jim

            .blkb 72

            .end

    Only rarely does this situation arise, eg. in a BASIC+ 2 main
    program (sometimes). Whatever happens, you will get an error
    when you try to re-assemble the code (undefined label probably).
    It is possible to fix the problem manually when this happens
    by looking at the '-q' table output and the pseudo assembler
    output listing.

    No obvious fix is at hand, but I will do something about it
    if someone complains loudly enough.
2 Bugs
 Refer all problems/questions/idle chat to:

	Nick de Smith (CAM SPR)
	Applied Telematics Services Ltd.
	7 Vale Avenue
	Tunbridge Wells
	Kent TN1 1DJ
	England

 Enclosing the CAM output/original input etc etc etc.

 I promise that I might do something about it sometime!
2 Future_Features
 Several features/enhancements are to be added:

  1) Resolution of numeric constants in supplied symbol tables.

  2) Output of small negative numbers in signed format. eg.
     177776 becomes -2 etc. Maybe all numbers in the range -128 to
     +127 should be dealt with this way.

  3) Collapsing of block data, especially zeroes. eg. a block of
     100 null bytes will become .BlkB0 100 and not, as currently
     a list of .Word 0 and .Byte 0 pseudo-ops. This will mean adding
     .Blkb0 to the CAMPRE.MAC file.

  4) (add your ideas here)
