==============================================================================


TRANTOR LTD                         Home/Office   01639-633072
GREEN HEDGES BUNGALOW               International 44-1639-633072
NEATH ROAD                          Mobile        0467-434849
BRYNCOCH                            Email         cobform@email.com
NEATH  SA10 7XW
WEST GLAMORGAN                      Directors:
SOUTH WALES, UK                     N.H.Jennings, B.Sc., CEng, MBCS, FIAP
                                    D.P.Jennings


COMPUSERVE Id: 100040,471

----------------------------------------------------------------------------

                                  COBXREF
                                VERSION 1.30
                                 USER GUIDE

                      Copyright (c) TRANTOR LTD, 1993 & 2000
----------------------------------------------------------------------------



CONTENTS



Chapter 1. Introduction

Chapter 2. Description

Chapter 3. Restrictions

Chapter 4. Running the Program

Chapter 5. The Future

Chapter 6. Registration

Appendix A. Reformatting Table definition

Appendix B. Latest changes



















----------------------------------------------------------------------------

                               CHAPTER ONE

----------------------------------------------------------------------------

INTRODUCTION

This  program  is  a  utility  which is intended to assist in analysing and
documenting COBOL source.

It is NOT a toy or a demo, but a fully working program  which  is  intended
for  daily use by the professional COBOL programmer. It can be used on a PC
to cross reference COBOL code from ANY machine.

Command-line parameters are provided, so that COBXREF can be used within  a
BAT file.



----------------------------------------------------------------------------

                                CHAPTER TWO

-----------------------------------------------------------------------------

Description
===========

This is a simple cross reference program for COBOL source. Since it is not
part of a COBOL compiler, it does not perform a full parse and syntax
analysis of the source. It can recognize certain types of COBOL item,
including comments, literals, paragraph names, punctuation, verbs and
reserved words,

It is, however, very simple-minded, and will report anything which it does
not understand. This should not be a problem to most users, except that
prints may be larger than necessary.

COBOL verbs and Reserved words are only recognised because they  are  found
in  a  table.  You  can  edit this table to include or exclude other items.
There is a limit of 600 lines in the table.

Paragraph and Data names are recognised by various checks, not from the 
table.

COBOL comments are not included in the cross reference.

References
==========

All references are to the input record number, NOT the sequence number. Due
to  the  asynchronous  nature of the internal processing, the reported line
number may sometimes be out by 1.

Format
======

You can  choose  either  a  79-column  or  132-column  format  by  the  XREF
parameter.

You can also choose to view the cross reference on the screen, as well as
creating a report.



----------------------------------------------------------------------------

                                CHAPTER THREE

----------------------------------------------------------------------------

Known restrictions
==================

Big Red Switch
--------------

COBXREF  can   occasionally   cause   the   machine   to   hang   -   exact
circumstances  are  not  known, but it is believed to be caused by a bug in
the COBOL compiler which results in working storage becoming corrupted.

It will also hang if the input file contains only comment lines, ie no
COBOL text.


Size of source
--------------
This version will  allow  source  programs  of  up  to  about  9000  lines,
depending  on  the  number  of  items  (maximum  3000)  and  the  number of
references to those items (maximum 12000). With these restrictions, the EXE
file size is almost 500kb.

If either table overflows, the fact will be displayed, but processing will
continue. The line number at which overflow occurs will also be reported.
The cross reference produced will be incomplete, but may still be of use.
The counts at the end of the run will show by how much the table overflowed.
                                                                     
Case
----

COBXREF will currently report upper and lower case versions of the same
word separately, even though the COBOL compiler should treat them as
identical.

Print Formatting
----------------

Currently,  no  print  formatting (headings, page throws, page numbers)  is
included in the output file - it is a plain ASCII text file.

Miscellaneous quirks
--------------------

COBXREF currently includes COBOL PICTURE clauses such as X(132). I will fix
this later.

Numeric  literals  are  also included, although  non-numeric  literals  may
optionally be suppressed.

Non-numeric  literals  will  be  truncated  to 30 characters, including the
initial quote or apostrophe. This may lead to references  to  two  or  more
similar literals being combined.

Some  COBOL  operators  and  punctuation,  such  as  -  and  *  (in COMPUTE
statements) will be included. I will also fix this later.




----------------------------------------------------------------------------

                                CHAPTER FOUR

----------------------------------------------------------------------------

Running the program
===================

Run  the  program  by typing COBXREF, followed by any required command-line
parameters, at the MS-DOS prompt. The Input filee is the most commonly used
parameters:

   COBXREF  IN=REMTEST.STR

If you do not enter an input filename, you will be asked for it.

Provided  that  the  input  file  is  specified,  the REGISTERED version is
suitable for inclusion in a batch (.BAT) file, and will not ask  for  input
from the keyboard.

Parameters
----------

The  following command line parameters are available. If the parameters are
given in the order shown, the keywords for the first  three  are  optional,
but they should be used for compatibility with future releases.

Note that the keywords shown (ie before the equals sign) may be in upper or
lower case.

Main Parameters
===============


IN=     Input filename. The default extension, CBL, will be added if not
        supplied

XREF=   Type of cross reference required. Up to two characters.

        First character - cross reference type

        The following types are available

        1  (Default)    Verbs,  reserved  words  and  most  literals  are
                        excluded

        2               Currently the same as 1.

        3               Includes only Datanames, Paragraph and Section
                        names.

        9               All  items,  including verbs, reserved words and
                        literals are included

        Second Character - Print/display format

        V or v          Narrow format list (79 cols) and also display on
                        screen

        S or s          Narrow format list

        Space           Wide format list, 132 columns

        Example: XREF=2S

TAB=    Reformatting table name. Default extension is TBL



CIN=    Input source format.

        This parameter is in two parts

        Part 1 (1 digit)
                Number of columns reserved for sequence  numbers  on  input
                source. Default is 6, valid numbers are 0 to 6

        Part 2 (optional - 3 digits)
                Size  of  COBOL  text  area  from Margin-B to Margin-R. For
                standard 80-column COBOL, this will be 061, as Margin-B  is
                12 and Margin-R is 72.

                Maximum value is 132, default is 061.

PRINT=filename

   The print file to which the cross reference is written.

DIAG=n  Diagnostic parameter

   This  invokes  diagnostic  displays if set to  certain  values.

   It should not normally be used, as it is mainly for our use in
   diagnosing bugs. If used, it is recommended that SYSOUT is directed to a
   file, as follows

       COBXREF INFILE DIAG=3 > TRACE

   You  may then have to hit return a few times, because you cannot see the
   console prompts - they are diverted to the file!

EXAMPLE:

     COBXREF  IN=PROGRAM  TAB=COBTABLE.TXT  CIN=4061

Further parameters
===================

These  do  not have any useful effect, they are simply retained because the
program was created from COBFORM. As is often the case in this kind of
development, it was easier to leave them in than take them out.

LEV=       Indentation (default 3)

MDIR=      MACRO directory

PATH=      Insert Trace and Path Analysis code

FST=       Same line after full stop or comma if N (default Y)

INC=ABC    Record selection

SECT=      Display section names

COUT=

STR=

USAGE=


----------------------------------------------------------------------------

                               CHAPTER FIVE

----------------------------------------------------------------------------

The Future
==========

Plans for further enhancements include the following:

        Recognition of Paragraph and Datanames

        A minimum XREF which includes only Paragraph and Datanames

        Recognition and optional exclusion of Picture clauses




----------------------------------------------------------------------------

                               CHAPTER SIX

----------------------------------------------------------------------------

Registration
=============

In common with most Shareware, registration on the following terms is
allowed for personal use only. All rights are retained, and Corporate
users, and those using this software in the course of a business, are
expected (and legally obliged) to purchase a commercial licence, which is
reasonably priced.

This software has taken many years to develop, and I would like to see some
return on the investment in effort, before COBOL is finally buried!

Please send 12 Pounds Sterling for the registered version of any of our PC
programs, to the address given at the start of this file. This includes VAT
and post & packing, and a VAT receipt can be supplied on request. (UK only)

In return for registration, I will supply some or all of the following,
depending on the particular product:

   The latest version, without the advertising screens
   Compuserve support
   Telephone support (UK office hours only please)
   Special enhancements on request

Prices correct as at 1st of June 1993, but we reserve the right to change
them without notice.

(Note that after paying for post, packing and media, phone and COMPUSERVE
costs, VAT and personal taxes, I end up with less than 6 pounds per sale
for my efforts. I don't think that is unreasonable.)

For non-UK users:

  Please send $25 or equivalent. This is because
  a)  Overseas mailing costs more
  b)  the bank charges a minimum of $4 for currency conversion (cash) or $9
      for cashing a foreign cheque (check).

   Where possible, I would prefer the cash, because I can batch it up and
   pay only one conversion charge for several registrations. (Always the
   optimist!)

   Overseas cheques should be made payable to N. Jennings, NOT TRANTOR



----------------------------------------------------------------------------

                                   APPENDIX A

----------------------------------------------------------------------------

Reformatting table definition
-----------------------------

Table contents
--------------

Column 1

COBOL Division code, I, E, D, P or space. An item will  only  match  if  it
occurs in the specified division. If space, it will match in any division.


Columns 2-31

The item, a COBOL word, paragraph or dataname


Column 32

Item type,
             V=verb
             J=structure verb (COBFORM only)
             L=level number
             R=Reserved word
Other values are documentary only

Columns 33-34

Default alignment, 2 digits or spaces if no special alignment is required
(COBFORM only)

Columns 35-36

Length  of textual replacement, or spaces if no replacement is required. It
is only necessary to specify a length if the textual  replacement  contains
embedded spaces. (Not used by COBXREF)


Columns 37-66

Textual replacement, if any. (Not used by COBXREF)



----------------------------------------------------------------------------

                                APPENDIX B.

----------------------------------------------------------------------------

Latest changes
==============

Version 1.30
============

Minor corrections and updates to the messages displayed.

Version 1.11
============

This is the first version released for general use. Previous versions  were
for test only.
