home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR9 / COBXREF.ZIP / COBXREF.DOC < prev    next >
Text File  |  1993-06-16  |  13KB  |  464 lines
  1. ----------------------------------------------------------------------------
  2.  
  3.                                   COBXREF
  4.                                 VERSION 1.11
  5.                                  USER GUIDE
  6.  
  7.                       Copyright (c) TRANTOR LTD, 1993
  8. ----------------------------------------------------------------------------
  9.  
  10.  
  11.  
  12. CONTENTS
  13.  
  14.  
  15.  
  16. Chapter 1. Introduction
  17.  
  18. Chapter 2. Description
  19.  
  20. Chapter 3. Restrictions
  21.  
  22. Chapter 4. Running the Program
  23.  
  24. Chapter 5. The Future
  25.  
  26. Chapter 6. Registration
  27.  
  28. Appendix A. Reformatting Table definition
  29.  
  30. Appendix B. Latest changes
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52. ==============================================================================
  53. TRANTOR LTD                         Home/Office    0639-633072
  54. GREEN HEDGES BUNGALOW               International  44-639-633072
  55. PONTARDAWE ROAD                     Mobile         0836-795445
  56. BRYNCOCH                            Fax            (manual switch, on request)
  57. NEATH  SA10 7YL                     Compuserve     100040,471
  58. WEST GLAMORGAN                      Directors:
  59. SOUTH WALES                         N.H.Jennings, B.Sc., CEng, MBCS, FIAP
  60. UK                                  D.P.Jennings
  61. ==============================================================================
  62.  
  63.  
  64.  
  65. ----------------------------------------------------------------------------
  66.  
  67.                                CHAPTER ONE
  68.  
  69. ----------------------------------------------------------------------------
  70.  
  71. INTRODUCTION
  72.  
  73. This  program  is  a  utility  which is intended to assist in analysing and
  74. documenting COBOL source.
  75.  
  76. It is NOT a toy or a demo, but a fully working program  which  is  intended
  77. for  daily use by the professional COBOL programmer. It can be used on a PC
  78. to cross reference COBOL code from ANY machine.
  79.  
  80. Command-line parameters are provided, so that COBXREF can be used within  a
  81. BAT file.
  82.  
  83.  
  84.  
  85. ----------------------------------------------------------------------------
  86.  
  87.                                 CHAPTER TWO
  88.  
  89. -----------------------------------------------------------------------------
  90.  
  91. Description
  92. ===========
  93.  
  94. This is a simple cross reference program for COBOL source. Since it is not
  95. part of a COBOL compiler, it does not perform a full parse and syntax
  96. analysis of the source. It can recognize certain types of COBOL item,
  97. including comments, literals, paragraph names, punctuation, verbs and
  98. reserved words,
  99.  
  100. It is, however, very simple-minded, and will report anything which it does
  101. not understand. This should not be a problem to most users, except that
  102. prints may be larger than necessary.
  103.  
  104. COBOL verbs and Reserved words are only recognised because they  are  found
  105. in  a  table.  You  can  edit this table to include or exclude other items.
  106. There is a limit of 600 lines in the table.
  107.  
  108. Paragraph and Data names are recognised by various checks, not from the 
  109. table.
  110.  
  111. COBOL comments are not included in the cross reference.
  112.  
  113. References
  114. ==========
  115.  
  116. All references are to the input record number, NOT the sequence number. Due
  117. to  the  asynchronous  nature of the internal processing, the reported line
  118. number may sometimes be out by 1.
  119.  
  120. Format
  121. ======
  122.  
  123. You can  choose  either  a  79-column  or  132-column  format  by  the  XREF
  124. parameter.
  125.  
  126. You can also choose to view the cross reference on the screen, as well as
  127. creating a report.
  128.  
  129.  
  130.  
  131. ----------------------------------------------------------------------------
  132.  
  133.                                 CHAPTER THREE
  134.  
  135. ----------------------------------------------------------------------------
  136.  
  137. Known restrictions
  138. ==================
  139.  
  140. Big Red Switch
  141. --------------
  142.  
  143. COBXREF  can   occasionally   cause   the   machine   to   hang   -   exact
  144. circumstances  are  not  known, but it is believed to be caused by a bug in
  145. the COBOL compiler which results in working storage becoming corrupted.
  146.  
  147. It will also hang if the input file contains only comment lines, ie no
  148. COBOL text.
  149.  
  150.  
  151. Size of source
  152. --------------
  153. This version will  allow  source  programs  of  up  to  about  9000  lines,
  154. depending  on  the  number  of  items  (maximum  3000)  and  the  number of
  155. references to those items (maximum 12000). With these restrictions, the EXE
  156. file size is almost 500kb.
  157.  
  158. If either table overflows, the fact will be displayed, but processing will
  159. continue. The line number at which overflow occurs will also be reported.
  160. The cross reference produced will be incomplete, but may still be of use.
  161. The counts at the end of the run will show by how much the table overflowed.
  162.                                                                      
  163. Case
  164. ----
  165.  
  166. COBXREF will currently report upper and lower case versions of the same
  167. word separately, even though the COBOL compiler should treat them as
  168. identical.
  169.  
  170. Print Formatting
  171. ----------------
  172.  
  173. Currently,  no  print  formatting (headings, page throws, page numbers)  is
  174. included in the output file - it is a plain ASCII text file.
  175.  
  176. Miscellaneous quirks
  177. --------------------
  178.  
  179. COBXREF currently includes COBOL PICTURE clauses such as X(132). I will fix
  180. this later.
  181.  
  182. Numeric  literals  are  also included, although  non-numeric  literals  may
  183. optionally be suppressed.
  184.  
  185. Non-numeric  literals  will  be  truncated  to 30 characters, including the
  186. initial quote or apostrophe. This may lead to references  to  two  or  more
  187. similar literals being combined.
  188.  
  189. Some  COBOL  operators  and  punctuation,  such  as  -  and  *  (in COMPUTE
  190. statements) will be included. I will also fix this later.
  191.  
  192.  
  193.  
  194.  
  195. ----------------------------------------------------------------------------
  196.  
  197.                                 CHAPTER FOUR
  198.  
  199. ----------------------------------------------------------------------------
  200.  
  201. Running the program
  202. ===================
  203.  
  204. Run  the  program  by typing COBXREF, followed by any required command-line
  205. parameters, at the MS-DOS prompt. The Input filee is the most commonly used
  206. parameters:
  207.  
  208.    COBXREF  IN=REMTEST.STR
  209.  
  210. If you do not enter an input filename, you will be asked for it.
  211.  
  212. Provided  that  the  input  file  is  specified,  the REGISTERED version is
  213. suitable for inclusion in a batch (.BAT) file, and will not ask  for  input
  214. from the keyboard.
  215.  
  216. Parameters
  217. ----------
  218.  
  219. The  following command line parameters are available. If the parameters are
  220. given in the order shown, the keywords for the first  three  are  optional,
  221. but they should be used for compatibility with future releases.
  222.  
  223. Note that the keywords shown (ie before the equals sign) may be in upper or
  224. lower case.
  225.  
  226. Main Parameters
  227. ===============
  228.  
  229.  
  230. IN=     Input filename. The default extension, CBL, will be added if not
  231.         supplied
  232.  
  233. XREF=   Type of cross reference required. Up to two characters.
  234.  
  235.         First character - cross reference type
  236.  
  237.         The following types are available
  238.  
  239.         1  (Default)    Verbs,  reserved  words  and  most  literals  are
  240.                         excluded
  241.  
  242.         2               Currently the same as 1.
  243.  
  244.         3               Includes only Datanames, Paragraph and Section
  245.                         names.
  246.  
  247.         9               All  items,  including verbs, reserved words and
  248.                         literals are included
  249.  
  250.         Second Character - Print/display format
  251.  
  252.         V or v          Narrow format list (79 cols) and also display on
  253.                         screen
  254.  
  255.         S or s          Narrow format list
  256.  
  257.         Space           Wide format list, 132 columns
  258.  
  259.         Example: XREF=2S
  260.  
  261. TAB=    Reformatting table name. Default extension is TBL
  262.  
  263.  
  264.  
  265. CIN=    Input source format.
  266.  
  267.         This parameter is in two parts
  268.  
  269.         Part 1 (1 digit)
  270.                 Number of columns reserved for sequence  numbers  on  input
  271.                 source. Default is 6, valid numbers are 0 to 6
  272.  
  273.         Part 2 (optional - 3 digits)
  274.                 Size  of  COBOL  text  area  from Margin-B to Margin-R. For
  275.                 standard 80-column COBOL, this will be 061, as Margin-B  is
  276.                 12 and Margin-R is 72.
  277.  
  278.                 Maximum value is 132, default is 061.
  279.  
  280. PRINT=filename
  281.  
  282.    The print file to which the cross reference is written.
  283.  
  284. DIAG=n  Diagnostic parameter
  285.  
  286.    This  invokes  diagnostic  displays if set to  certain  values.
  287.  
  288.    It should not normally be used, as it is mainly for our use in
  289.    diagnosing bugs. If used, it is recommended that SYSOUT is directed to a
  290.    file, as follows
  291.  
  292.        COBXREF INFILE DIAG=3 > TRACE
  293.  
  294.    You  may then have to hit return a few times, because you cannot see the
  295.    console prompts - they are diverted to the file!
  296.  
  297. EXAMPLE:
  298.  
  299.      COBXREF  IN=PROGRAM  TAB=COBTABLE.TXT  CIN=4061
  300.  
  301. Further parameters
  302. ===================
  303.  
  304. These  do  not have any useful effect, they are simply retained because the
  305. program was created from COBFORM. As is often the case in this kind of
  306. development, it was easier to leave them in than take them out.
  307.  
  308. LEV=       Indentation (default 3)
  309.  
  310. MDIR=      MACRO directory
  311.  
  312. PATH=      Insert Trace and Path Analysis code
  313.  
  314. FST=       Same line after full stop or comma if N (default Y)
  315.  
  316. INC=ABC    Record selection
  317.  
  318. SECT=      Display section names
  319.  
  320. COUT=
  321.  
  322. STR=
  323.  
  324. USAGE=
  325.  
  326.  
  327. ----------------------------------------------------------------------------
  328.  
  329.                                CHAPTER FIVE
  330.  
  331. ----------------------------------------------------------------------------
  332.  
  333. The Future
  334. ==========
  335.  
  336. Plans for further enhancements include the following:
  337.  
  338.         Recognition of Paragraph and Datanames
  339.  
  340.         A minimum XREF which includes only Paragraph and Datanames
  341.  
  342.         Recognition and optional exclusion of Picture clauses
  343.  
  344.  
  345.  
  346.  
  347. ----------------------------------------------------------------------------
  348.  
  349.                                CHAPTER SIX
  350.  
  351. ----------------------------------------------------------------------------
  352.  
  353. Registration
  354. =============
  355.  
  356. In common with most Shareware, registration on the following terms is
  357. allowed for personal use only. All rights are retained, and Corporate
  358. users, and those using this software in the course of a business, are
  359. expected (and legally obliged) to purchase a commercial licence, which is
  360. reasonably priced.
  361.  
  362. This software has taken many years to develop, and I would like to see some
  363. return on the investment in effort, before COBOL is finally buried!
  364.  
  365. Please send 12 Pounds Sterling for the registered version of any of our PC
  366. programs, to the address given at the start of this file. This includes VAT
  367. and post & packing, and a VAT receipt can be supplied on request. (UK only)
  368.  
  369. In return for registration, I will supply some or all of the following,
  370. depending on the particular product:
  371.  
  372.    The latest version, without the advertising screens
  373.    Compuserve support
  374.    Telephone support (UK office hours only please)
  375.    Special enhancements on request
  376.  
  377. Prices correct as at 1st of June 1993, but we reserve the right to change
  378. them without notice.
  379.  
  380. (Note that after paying for post, packing and media, phone and COMPUSERVE
  381. costs, VAT and personal taxes, I end up with less than 6 pounds per sale
  382. for my efforts. I don't think that is unreasonable.)
  383.  
  384. For non-UK users:
  385.  
  386.   Please send $25 or equivalent. This is because
  387.   a)  Overseas mailing costs more
  388.   b)  the bank charges a minimum of $4 for currency conversion (cash) or $9
  389.       for cashing a foreign cheque (check).
  390.  
  391.    Where possible, I would prefer the cash, because I can batch it up and
  392.    pay only one conversion charge for several registrations. (Always the
  393.    optimist!)
  394.  
  395.    Overseas cheques should be made payable to N. Jennings, NOT TRANTOR
  396.  
  397.  
  398.  
  399. ----------------------------------------------------------------------------
  400.  
  401.                                    APPENDIX A
  402.  
  403. ----------------------------------------------------------------------------
  404.  
  405. Reformatting table definition
  406. -----------------------------
  407.  
  408. Table contents
  409. --------------
  410.  
  411. Column 1
  412.  
  413. COBOL Division code, I, E, D, P or space. An item will  only  match  if  it
  414. occurs in the specified division. If space, it will match in any division.
  415.  
  416.  
  417. Columns 2-31
  418.  
  419. The item, a COBOL word, paragraph or dataname
  420.  
  421.  
  422. Column 32
  423.  
  424. Item type,
  425.              V=verb
  426.              J=structure verb (COBFORM only)
  427.              L=level number
  428.              R=Reserved word
  429. Other values are documentary only
  430.  
  431. Columns 33-34
  432.  
  433. Default alignment, 2 digits or spaces if no special alignment is required
  434. (COBFORM only)
  435.  
  436. Columns 35-36
  437.  
  438. Length  of textual replacement, or spaces if no replacement is required. It
  439. is only necessary to specify a length if the textual  replacement  contains
  440. embedded spaces. (Not used by COBXREF)
  441.  
  442.  
  443. Columns 37-66
  444.  
  445. Textual replacement, if any. (Not used by COBXREF)
  446.  
  447.  
  448.  
  449. ----------------------------------------------------------------------------
  450.  
  451.                                 APPENDIX B.
  452.  
  453. ----------------------------------------------------------------------------
  454.  
  455. Latest changes
  456. ==============
  457.  
  458. Version 1.11
  459. ============
  460.  
  461. This is the first version released for general use. Previous versions  were
  462. for test only.
  463.  
  464.