home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
PROG_GEN
/
PEO.ZIP
/
MANUAL.DOC
< prev
next >
Wrap
Text File
|
1994-02-10
|
61KB
|
1,299 lines
JAMES W. YOUNG & ASSOCIATES, INC.
1403 5th Street, Suite G
Davis, California 95616
(916)756-3051
Dear Professional:
Thank you for taking a look at James W. Young & Associates,
Inc.'s COBOL system analysis tool, Program Entity Organizer
(PEO). This is the same version of PEO we use to provide top
notch services and support for our clients.
TERMINOLOGY
PEO refers to the screens which the user works with to analyze
the COBOL programs. However, in general, PEO refers to the
entire system; i.e., the batch programs (the supporting software)
and the screens.
SEO refers to the batch portion of PEO. SEO is the supporting
software for PEO. SEO consists of a preprocessor and a parser.
MACHY refers to the group of senior programmer/analysts that
developed the PEO and SEO software. It is also the name of the
main directory that is created at installation.
Application identifier is an important part of PEO. It
represents a particular group of COBOL programs and their
copybooks. Each application identifier (i.e., a unique set
of COBOL programs and copybooks) must be created as a
subdirectory of MACHY. The actual source code does not have
to be in the subdirectory. The first application identifier
subdirectory is created at install time.
Publisher refers to James W. Young & Associates.
Author refers to the copyright holders for the PEO and SEO
software.
WHAT IS PEO?
PEO is a COBOL source code analysis and documentation tool.
It replaces the compiler output as the primary analysis tool.
It gives you a huge leap in productivity and confidence;
productivity, because PEO handles the cross reference grunt
work and bundles main programs and all their subprograms
into a single package for analysis;
confidence, because you can be sure you've covered everything!
Anything you can do with a compile listing you can do many times
faster with PEO and with virtual one-hundred percent accuracy.
You can identify and document business functions in a fraction
of the time formerly required.
You can identify and document program control functions in a
fraction of the time formerly required.
PEO is a custom tool used by James W. Young & Associates and
clients for more than two years. It was designed and developed
by four senior programmer analysts with over 90 years combined
experience with mainframe COBOL systems. It's designed for the
real world of esoteric (spaghetti) code; numerous modifications;
numerous subprograms; alternate entry points; a plethora of
GO TO's, ALTER's; superfluous group moves and group parameters;
AND modern, structured code.
THE PEO DEMONSTRATION
PEODEMO is a very tiny COBOL program with no function other
than demonstrate the look and feel of PEO; and, to show you
some of the features of PEO. Don't let the small size of the
demo fool you; there's no size limit on programs as long as
you have the DASD. Copy the demonstration and peo.exe files
to a hard drive to get an accurate idea of the speed of PEO.
Change to the drive and directory containing peo.exe and the
PEODEMO.* files. You MUST do this to run the demonstration.
Select PEODEMO from the first screen.
The PEODEMO.HIH file is output from the parser and shows the
call hierarchy, alternate entry points, and source files
containing the entry point (if different from the entry name).
The PEODEMO.DTE file is an example of a data element name
filter. The string "YYMM" was the filter. The file contains
the selected names which met the criterion. These names can be
used with the PEO screens to analyze their use in the COBOL
system. You may specify multiple filters.
DISCLAIMER - AGREEMENT
USERS OF PROGRAM ENTITY ORGANIZER (PEO) AND ITS SUPPORTING
SOFTWARE, THROUGHOUT THIS DOCUMENT, REFERRED TO AS SEO, MUST
ACCEPT THIS DISCLAIMER OF WARRANTY:
PROGRAM ENTITY ORGANIZER (PEO) AND SEO ARE SUPPLIED AS IS.
THE AUTHOR AND PUBLISHER DISCLAIM ALL WARRANTIES, EXPRESSED
OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF
MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR
AND PUBLISHER ASSUME NO LIABILITY FOR DAMAGES, DIRECT OR
CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF PROGRAM ENTITY
ORGANIZER (PEO) AND SEO. THE USER MUST ASSUME THE ENTIRE RISK
OF USING THE PROGRAM. ANY LIABILITY OF THE AUTHOR AND PUBLISHER
WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF
PURCHASE PRICE.
CONTENTS:
I. Some Information About Getting Started
II. The Outline of the User's Manual
III. Draft Copy of the User's Manual.
IV. JWY&Assoc., Inc.'s support for PEO.
V. qikstart
I. Some Information About Getting Started
Here is some information which should get you started without
having to look at very much of the User's Manual. The install
information is at the very end of this file.
PEO is as easy to use as 1, 2, 3:
1. preprocess all the COBOL source code in the
directory,
2. parse the program(s) and load into the PEO data
base, and
3. analyze the program.
Step one must be done at least one time during the "life-cycle"
of PEO for a particular set of COBOL programs. You repeat step
one only when a program is added to the directory or when
program names or alternate entry point names have been added or
changed; or, internal/external file definition names have been
added or changed.
Step two depends upon step one being run at least one time.
Step two must be done when you choose a program for analysis
for the first time. Usually, you will not have to do step two
more than once for each project. The capabilities PEO gives
you make it possible to do a thorough analysis, make the
changes to the program, and forget about the program until
the next project.
Step three depends upon step two before a program can be analyzed.
Step three is repeated as often as necessary to analyze the
program(s).
All three steps depend upon a certain configuration of DOS
directories. The main working directory is created at install
time. It is named, MACHY. The preprocessor and parser are
copied to this directory by install.bat. A particular set of
COBOL source code (referred to here as an application or
application ID) must be given a name by the user. The application
ID is used to create a subdirectory of MACHY. The application
ID is a required command line parameter when you run install.bat.
The third directory required by PEO is named EXS and is created
by install.bat as a subdirectory of application ID. The PEO.exe
file is copied to the EXS subdirectory by install.bat. Here is a
representation of the DOS directories:
root the c: drive
|
MACHY the preprocessor and parser are here
|
application ID the working directory for a set of COBOL
| code
|
EXS the peo screens (peo.exe) reside here
The install.bat file also creates a COBOL and a COPY sub
directory of application ID. These are the default directories
for the COBOL source code. You can copy the COBOL programs and
copybooks to these directories, respectively. Otherwise, you
must use the SEOCOBOL and SEOCOPY DOS environment variables to
point the preprocessor and parser to the COBOL source code.
(Notice, that is SEO..., not PEO.... The preprocessor and parser
are referred to as SEO.) SEO does require .cbl and .cpy file
extensions for your COBOL programs and copybooks, respectively.
Please see "Naming conventions for your source code" in the
User's Manual.
All three steps depend upon the DOS command line to be
executed. (step three is an exception, see next paragraph.)
The first two steps depend upon command line parameters.
Step three, PEO, does not require any command line parameters.
You will be asked by the first PEO screen to provide the
information PEO needs. The first two steps are batch jobs and
should be run from the DOS command line only. PEO is not a
batch job and can run under Microsoft's Windows (R) or similar
product; we have not, however, run PEO under any system other
than DOS and Windows.
To run the first two steps you must always provide the
application ID as the first command line parameter. The
application ID is the only parameter for step one, the
preprocessor. Step two, the parser, requires the application
ID and the main program name(s), i.e., the file name(s) in
the COBOL directory, with or without the file name extension.
If you omit the main program name(s), the parser will process
all the COBOL programs in the directory. You do not have to
provide the names of any subprograms; that is the job of the
preprocessor. You can parse "main" programs only. The parser
will include all subprograms automatically based upon the
latest information supplied by the preprocessor.
All three steps correspond to executable files:
prepro
seoexp00
peo.
Step one is prepro.bat which executes the two preprocessor
programs, seopre00.exe and seopsu00.exe. The application ID
is a required command line parameter.
Step two is seoexp00.exe (the parser). The application ID is
a required command line parameter. It must be the first
parameter. The second parameter is the file name of the main
program to be parsed. If you run seoexp00.exe with only the
application ID, it will parse all the programs in the COBOL
directory. The third, fourth, etc. parameters are file names
of other main programs to be included (along with all their
subprograms) in a single analysis package; seoexp00.exe will
ask you to type in a one to eight byte name for the analysis
package if you type more than one program name on the command
line. The name you type in is the name you provide step three
(peo.exe) to load into the PEO data bases; otherwise, if there
is only one main program you provide step three with the
program name.
Step three is peo.exe (the user interface). The first screen
you see will ask you to choose to view a program which already
exists in the PEO data bases or to choose to load a new program.
If you choose to load a new version of an existing program, you
will be asked to permit PEO to overlay the old version.The name
you provide to PEO is the main COBOL program name; or, if you
combined programs into one analysis package, it's the name you
typed into step two, seoexp00.exe.
The first two steps, the batch preprocessor and parser, produce
a *.seo file. You should check these for such things as missing
copybooks, missing subprograms, unknown data element names, and
unknown procedure names. Other messages are information which
may indicate the parser failed to recognize something because of
an unusual condition; e.g., a missing period separator. More
arcane messages are rare and would require product support. The
preprocessor *.seo file is named SEOPREP.SEO and is in the
application ID subdirectory. The parser *.SEO file is named by
the COBOL program's name with a .SEO extension. This file is in
the EXS subdirectory of the application ID.
All three steps have screens. The two batch steps, steps one
and two, will show the first few lines of the program being
processed and the identity of the main program, subprogram,
and copybook currently being processed. In addition, the
running line count is displayed. PEO's screens are described
in the User's Manual.
If you've installed the SEO and PEO files and read through
the above, you're ready to put PEO to work. The instructions
for installing the software are at the very end of this file.
Here's how it works. It's likely your COBOL source code is
already installed in a directory; or, you do not want to put
the programs and copybooks in a PEO directory. If either is
true, type in
set SEOCOBOL=drive[path]
set SEOCOPY=drive[path]
where drive is the letter of the drive containing the COBOL
source code and [path] is the path to the directory of the
source code. If you did put the COBOL programs into the COBOL
subdirectory of application ID and you put the copybooks in
the COPY subdirectory of the application ID, you will not have
to set the environment variables (SEOCOBOL and SEOCOPY). If
you did one and not the other, use the appropriate environment
variable.
Before you proceed, check the information in the User's
Manual ("Naming conventions for your source code"). The COBOL
programs must have a .cbl file extension and the copy books
must have a .cpy file extension.
Next, you're ready to run the preprocessor. Remember, you
will not have to run the preprocessor every time. Please
refer to the description of the preprocessor above and in
the User's Manual. You run the preprocessor by typing in:
prepro applid
where prepro in the batch file which executes the two
preprocessor programs and applid is the application ID. It
should take about fifteen minutes for each 100,000 lines of
code in the COBOL program and copybook directories.
After the preprocessor is finished, check the seoprep.seo
file in the application ID directory. It will tell you if
any copybooks are missing.
Now, run the parser. In this example there will be only one
main program to parse. You parse the program by typing in
seoexp00 applid mainprogramid
where seoexp00 is the parser, applid is the application ID,
and mainprogramid is the file name (with or without the file
extension) of the main program. How long will the parser
take? It depends upon the size of the program and how the
program is coded. Another factor is a RAM drive, see
"PERFORMANCE CONSIDERATIONS" in the User's Manual. Obviously,
a large program is going to take longer than a small program.
The parser works at about a thousand lines per minute. But,
a COBOL program with a lot of group-level activity; e.g.,
group MOVE's and group parameters, can take a longer than a
program of similar size but little group-level activity.
Before loading the program into PEO, check the *.seo file
produced by the parser. It is named by using the main program
name and a .seo extension. The file will be in the EXS sub
directory of applid. The main things to look for are missing
files; e.g., copybooks and subprograms. Messages like, UNKNOWN
DATA ELEMENT, are also important. If all the parts for the
program were there, the file will contain only the header
record.
Now load the program into the PEO data bases. This is done by
invoking PEO. If you did not put PEO (peo.exe) into Windows (R),
PEO can be executed by switching to the EXS subdirectory of
applid and typing in
peo
The first screen you see will let you load the COBOL program
into the PEO data bases. Once the program is loaded, you will
see the program's name in PEO's window of program names. Please
see "USING THE PEO SCREENS" in the User's Manual; or, just go
ahead and do it. You'll find the process to load the COBOL into
the PEO data bases very easy and, when PEO is done, you can go
right into the analysis screens. You'll find the analysis screens
fairly intuitive.
One final note. PEO was designed for mainframe COBOL; e.g., ANS74,
ANS85, OS/VS, and COBOL II. It does not support many of the
extensions found in PC-based COBOL. See the file CAUTION.DOC.
JAMES W. YOUNG & ASSOCIATES, INC.
1403 5th Street, Suite G
Davis, California 95616
(916)756-3051
II. The Outline of the User's Manual
HARDWARE AND SOFTWARE REQUIREMENTS
GETTING STARTED
Tools required.
Installing PEO.
What the install process does.
INSTALLING THE COBOL SOURCE CODE
Naming conventions for your source code.
Paths to your source code.
Adding new source code (after installation).
Clean compiles only, please.
PREPARING DATA FOR PEO.
The preprocessor
Main Programs
The SEOPREP.SEO file
The <progid>.seo file
Loading output from the parser into PEO.
USING THE PEO SCREENS
No training required.
The PEO Screens.
The PEO Data Element Selection Screen
The PEO Source Display Screen.
The PEO Element Display Screen
The target element and affected elements
Picking a target
Linking CALL and ENTRY PT relations.
The PEO Multiple Element Selection Screen
CAUTIONS.
ADDITIONAL INFORMATION
TYPE RELATIONS CODES
PERFORMANCE CONSIDERATIONS
RESERVED WORDS
III. Draft Copy of the User's Manual.
HARDWARE AND SOFTWARE REQUIREMENTS
The basic PC platform required to run the preprocessor and parser
portions (i.e., SEO) would be a 80386 or 80486 PC with at least
4MB of memory and a substantial hard disk... say 200MB or larger,
if you have a large number of COBOL programs. A removable storage
medium, such as a Bernoulli Box would make an ideal environment...
and a tape backup would be desirable. Once the files have been
created by the parser, they may be loaded on any available plat-
form that has sufficient disk storage. We have run the screens
(PEO) on 8088 and 8086 machines with 640K of memory and 40MB hard
disks. In most cases, the preprocessor and the parser run with
about 550K of memory; it's only when the number of elements in a
record exceed approximately 2300 that the parser runs out of
memory. Using DOS 5.0 or higher is desirable because most system
programs can be loaded into high memory leaving well over 600,000
bytes available for applications like the parser, SEO.
PEO and SEO both run under DOS. PEO is very well behaved
under Windows, as a DOS application; in fact, we recommend
running PEO under Windows. The preprocessor and parser (SEO)
are both batch jobs which should not be run under Windows.
GETTING STARTED
Tools required.
It does require some tools (knowledge of DOS commands) to
install and use PEO and SEO. Specifically, you should under-
stand the basic DOS concepts of directories, "paths", command
line parameters, file names, and extensions. You may need to
know how to use the RENAME, MD, and SET commands.
Installing PEO. Please refer to "How to install" at the end of
this readme.doc file.
What the install process does.
The install process creates a subdirectory of the hard drive.
The subdirectory is named, MACHY. The SEO software is copied
to the MACHY directory. The install process then creates a sub
directory for the application identifier. This is a subdirectory
of MACHY. Then the install process creates three subdirectories
of the application identifier: id COBOL, COPY, and EXS. Here's
how it looks
root
|
MACHY
|- application identifier
|- COBOL
|- COPY
|- EXS
The PEO software (peo.exe) is copied to the EXS subdirectory.
The software installation process is now complete. The MACHY
directory is the working directory for the SEO software (pre-
processor and parser) and EXS is the working (default) directory
for peo.exe.
INSTALLING THE COBOL SOURCE CODE
You must now give access to your COBOL source code to the SEO
reprocessor and parser. The "simplest" way is to copy the COBOL
source code to the COBOL subdirectory of the application identifier
created by the install process. The copybooks must be copied to
the COPY subdirectory of the application identifier. However, as
you will see in "Paths to your source code", you do not have to
use the default directories.
Naming conventions for your source code.
The SEO preprocessor and parser require a .CBL extension for
the COBOL source code and a .CPY extension for the copybooks.
You can use the DOS RENAME command to add the extension (or
change to the extension). If you are not familiar with the
RENAME command, you can add/change extensions for all members
of a directory with just one RENAME command. Please refer to
the RENAME command in the DOS manual.
Paths to your source code.
Just like all DOS applications, the MacHY Group's software has
access to directories via "paths". The default paths are
described above. If you do not wish to use the default paths
to get to your COBOL source code and copybooks, you can change
the paths. The names of the paths (environment variables) for
the COBOL source code and copybooks are SEOCOBOL and SEOCOPY,
respectively. How you're able to change paths is beyond the
scope of this document. Please refer to your DOS manual (SET
command).
Adding new source code (after installation).
There are two ways of adding new COBOL programs: add programs
to an existing application identifier or create a whole new set
of programs for a new application identifier. You add programs
to an existing application identifier by simply copying them
to the appropriate directories; but, you must run the preproces-
sor again before you can parse the new programs and load them
into PEO. This does not apply to copybooks. You do not have to
re-run the preprocessor when you add copy books - - unless the
copy books contain the ENTRY statement or SELECT ... ASSIGN TO
.... statements. You add a new application identifier by (1)
creating a sub directory of MACHY for the new application
identifier and (2) creating three subdirectories of the ap-
plication identifier: COBOL, COPY, and EXS. You use the DOS MD
(make directory) command to create directories. You provide
the value for application identifier. It's a name to describe
the group of programs just like the one mentioned in "Installing
PEO". Even if the paths to your source code and copybooks will
not be defaults (i.e., they will not lead to the COBOL and COPY
subdirectories of the new application identifier), you MUST
create the application identifier subdirectory of MACHY and an
EXS subdirectory of application identifier. And, you must run
the preprocessor for the new application identifier.
ASCII files only.
All source code input to the preprocessor and parser must be
ASCII and must have columns one through six and column seven
present. The COBOL statements must be in columns eight through
72. Of course, a LF/CR can terminate the record in any column,
including column one (to indicate a blank line). Basically,
what this means is there can be no TAB characters.
Clean compiles only, please.
PEO/SEO is not designed to help find potential compile errors.
It's designed to replace the need to research static code in
the traditional ways. It's not intended to replace Animate or
any other execution-time debugging tools, just as doing re-
search on static code has never done away with the need for
run-time debugging tools. Nor, has run-time debugging done
away with the need for "code walk-through".
PREPARING DATA FOR PEO.
Every thing has its price in order to get its benefits. PEO's
price is the preprocessor and parser. The preprocessor saves
you the task (often very difficult) of identifying the COBOL
programs which contain the alternate entry points called by
other programs; and it obtains other information about your
COBOL programs that is required by the parser. The preprocessor
"bundles" information about the various COBOL source files and
passes the information to the parser. The parser identifies
the relations and prepares data for PEO. Finally, the data are
loaded into PEO.
The preprocessor
The preprocessor must be run at least one time for each applica-
tion identifier. It will process every COBOL program and copy
book in the COBOL and COPY subdirectories (or, alternate sub
directories, see "Paths to your source code"). If you do not
add new programs or add/change CALL, ENTRY, or FD statements,
you should not have to run the preprocessor more than once for
an application identifier. Run the preprocessor by changing to
the MACHY directory and typing
PREPRO application-identifier
where, application-identifier, is the name you provided for the
set of COBOL programs at installation time. Of course, applica-
tion identifier can also be any name you've added to the MACHY
directory since installation.
Main Programs
The preprocessor identifies all the main programs in the applica-
tion identifier directory. The preprocessor identifies a "main"
program by finding a program which no other program CALLs, either
directly or by alternate entry points. A main program should have
no alternate entry points (except, DLITCBL) and it must have a
PROGRAM-ID name which matches the source file name. If the pre-
processor cannot identify any main programs, no files are produced
for the parser.
The SEOPREP.SEO file
This file lists the things encountered by the preprocessor. The
things important to the user are limited to identifying missing
components; e.g., copybooks. The file is in the application
identifier sub directory of MACHY.
The parser
The parser must be run every time you wish to add a program to
PEO, or every time you make major changes to a program which
require all the new relations in the changed program to be re-
identified. Run the parser by entering
seoexp00 applid program-id
Applid is the same as described in "The preprocessor". Program
id is the file name of the COBOL program. You do not have to
include the .CBL extension. If you omit the program name the
parser will parse all programs in the COBOL source code direc-
tory. If you include more than one program name, the parser
will ask you to input a one to eight byte name; all the programs
will be parsed together and you will have to use the name to
load the parser files into PEO. The parser is executed from the
MACHY directory.
The progid.seo file
If the parser detects any things it cannot handle it writes
messages to a file identified by the program name and .seo
extension. You should check this file for missing subprograms
or copybooks, unknown data element names, or anything which
might affect the ability to analyze the program. If you parsed
a group of programs together, the file name will be the name
you provided to the parser plus the .seo extension. The files
are in the EXS sub directory of the application identifier.
Loading output from the parser into PEO.
When PEO is invoked you will be asked to choose to load a
program or select a program already in PEO to view. If you
choose to load a program and the program already exists in
PEO, you will be asked to permit PEO to overlay the old
program. Once the program is loaded, you will see the orig-
inal screen, The PEO (Program Entity Organizer) SCREEN
(Figure 1). You can select the program you wish to view.
You invoke PEO by entering PEO on the DOS command line. You
must, however, first change to the EXS sub directory of the
application identifier. The peo.exe file can reside in any
directory; but, when it's in the EXS sub directory it can
use default paths to load data files from the parser. PEO
works with Microsoft Windows. It's recommended you add PEO
to Windows.
USING THE PEO SCREENS
Note: the illustrations of the PEO screens and the PEO demo
referenced beloware not included with the shareware "test
drive" version.
No training required.
Anyone can use the PEO screens with just a few minutes of
practice. It's best to have an actual application; i.e.,
don't expect to peruse code for the sole purpose of seeing
how PEO works. The amount of information provided by PEO can
overwhelm the senses. But, if you start with a specific task
in mind you'll quickly get up to speed. That's why we have
included a speed learning exercise with this manual. Please
see, The PEO Demo. (Not included with this package.)
Here is some information, followed by some guidelines, which
will help you learn even faster. First, here is a brief
description of the PEO screens.
The PEO Screens.
The first screen you see after peo.exe is executed is
the PEO (Program Entity Organizer) SCREEN (Figure 1).
This screen has a little pop-up window in the right side.
The window gives you the option of loading a new program
(including overlaying an existing program) or you can
elect to view a program already loaded. Use the arrow
keys and Enter to select.
The PEO Data Element Selection Screen
The next screen is the PEO DATA ELEMENT SELECTION SCREEN
(Figure 2). This screen is used to select any element
(entity) in the program. Elements include data element
names, procedure names, program names, subprogram names,
entry points, copy books, etc. You must do one of three
things:
1. type in the whole name,
2. type in a partial name and
press F-7, or
3. press F-7
If you pressed F-7, you will see a pop-up window containing
a list of element names. Use the arrow and page keys and
press enter to make a selection. The pop-up window disappears
and the selected name remains on the screen. Now you must do
one of two things:
1. press F-5 to see how other entities in the program
relate to the selected element or
2. press F-6 to see the source code.
If you pressed F-6, you will see the PEO SOURCE DISPLAY SCREEN
(Figure 3).
If you pressed F-5, the next screen you see is the PEO ELEMENT
DISPLAY SCREEN (Figure 4).
The PEO SOURCE DISPLAY SCREEN.
If you pressed F-6, the PEO SOURCE DISPLAY SCREEN (Figure 3),
you have two options:
1. use the arrow, page-up, and page-down keys to
view the source code or
2. press Esc or Enter to return to the prior screen,
the PEO DATA ELEMENT SELECTION SCREEN (Figure 2).
The PEO Element Display Screen
If you pressed F-5, you have the PEO ELEMENT DISPLAY SCREEN
Figure 4). The PEO ELEMENT DISPLAY SCREEN (Figure 4) is the
main working screen to view and trace relations. This screen
is also referred to as the element relations screen. This is
the main working screen. It is what PEO is about. The screen
has three main parts:
1. the target element,
2. elements that affect the target, and
3. elements affected by the target.
The target element and affected elements
The target element is the element you selected on the PEO DATA
ELEMENT SELECTION SCREEN (Figure 2). The part of the screen
which shows the elements that affect the target is a list of
elements and the nature of their affect. The part of the
screen which shows the elements affected by the target
is a list of elements and the nature of the target's affect.
Both pars scroll and both parts show some additional informa-
tion. This is, in effect, an enhanced cross reference. This
shows the target, the elements directly related to it, and
the nature of the relation.
Picking a target
Before you can decide which new target to view, it will be
likely you'll need to see the source code associated with
each of the relations listed on the screen. To see the source
code, use the arrow keys to select the related element and
press F-6. This brings up the PEO SOURCE DISPLAY SCREEN
(Figure 3). The PEO SOURCE DISPLAY SCREEN (Figure 3) gives
you the same two options described above:
1. use the arrow, page-up, and page-down keys to
view the source code or
2. press Esc or Enter to return to the prior screen,
the PEO ELEMENT DIS PLAY SCREEN (Figure 4).
Linking CALL and ENTRY PT relations.
There are several relations for the CALL and ENTRY verbs.
The relations involve data passed between modules and the
passing of control to a subprogram. The relations for data
elements are ALIAS, GRPPARM, PRM:CALL, and ARG:ENTR. Please
refer to the discussion of relations for a description of
these types of relations. The purpose of this discussion is
to describe the usage of relations when following the passage
of control from one program to another. These relations are:
CALL:PRC, CALL, and ENTRY PT. The CALL:PRC relations indicates
there is a CALL verb in a named procedure, e.g., a paragraph.
You get this type of relation on the PEO ELEMENT DISPLAY
SCREEN (Figure 4) when a procedure is the target and the
procedure contains a CALL verb. To get detailed information
about the call, place the cursor on the line containing the
CALL:PRC type of relation and press enter. This makes the CALL
statement the new target. The PEO ELEMENT DISPLAY SCREEN
(Figure 4) for the new target will contain a detailed de-
scription of the CALL; including, the ENTRY PT type of
relation. But, ENTRY PT will be there only in the case of
the first call to the particular entry point. Press F-6 with
the cursor on the ENTRY PT type of relation to see the source
code at the entry point. (Note: by "first call", we mean it
is the first call encountered by the parser as it read
through the program sequentially; not necessarily, the first
call executed if the program were running.) When there are
multiple calls to the same entry point in a program, only the
first instance of the call will have the ENTRY PT type of
relation. You cannot use F-6 to get to the source code at
the entry point. (F-6 will show you the call to the entry
point.) You must place the cursor on the CALL type of rela-
tion and press Enter; the new target will be the called sub
program. This is the only way you can view the called sub
program's source code when there is no ENTRY PT type of relation.
The PEO Multiple Element Selection Screen
This screen comes in the form of a pop-up window on the PEO DATA
ELEMENT SELECTION SCREEN (Figure 2). You get this when an element
name is used to define more than one entity in the program. You
are provided with the subprogram name and the name of the copy
book (if any) to help you make a selection.
CAUTIONS.
Here are some important things you should know.
The SEO parser and preprocessor use temporary files. These files
are deleted at the end of the run. The temporary files are
created in the default (working) directory, unless the default
directory is overridden by an environment variable. The files
in the directory used by the SEO preprocessor and parser have
.cpt, .nha, .wrk, .inx, .idx, .f1, .f2, .f1s, .f2s, .sw*, .mg*,
and .tmp extensions. Future versions of PEO/SEO may add to this
list of temporary file extensions. ALL WORK FILES IN THE DIREC-
TORY USED BY THE SEO PREPROCESSOR AND PARSER WHICH HAVE THESE
EXTENSIONS WILL BE DELETED! Make sure you always run PEO/SEO in
a directory which does NOT contain any of your files.
ADDITIONAL INFORMATION
Here are a few things you should know. In no particular order
they are:
PEO's target has always been mainframe COBOL programs; especially,
old poorly-structured code. This, of course, happens because
programs that old have been changed through the years by a variety
of programmers. The developers of the preprocessor and parser did
not include the capability to recognize some PC COBOL features;
e.g., MicroFocus call-by-number and call-by-name features. Nor,
is COBOL II nested subprograms supported. The parser is not
designed for any particular release of COBOL. It attempts to avoid
problems by recognizing reserved words from all releases and stops
running when one of the words is used as a data element name. If
one of the reserved words is used as a procedure name (such as,
END-SEARCH where the paragraph name may be the exit for a para-
graph containing a SEARCH verb) the parser writes a message to
the program's .seo file and ignores the name. See "RESERVED
WORDS".
CALL is supported; but, if the CALL is to a variable name and
the variable name is not identical to the CALLed program's entry
point, the parser cannot recognize the subprogram.
COPY ... REPLACING .... is supported; but, the source code you
see on the PEO SOURCE screens does not show the effects of the
changes -- even though, the changes are shown on the PEO DATA
ELEMENT SELECTION (Figure 2) and PEO ELEMENT DISPLAY (Figure 4)
screens.
The following COBOL reserved words are recognized but are not
processed by the current version of the parser:
EXHIBIT, CANCEL, CLOSE,
ENTER, CONTINUE, SEEK, TALLY, USE
Data definitions must end with a period and space. A LF/CR may
follow the period in lieu of a space.
Procedures must end with a period and space. A LF/CR may follow
the period in lieu of a space.
TITLE. EJECT, SKIP1, SKIP2, SKIP3, REPLACE, -INC, and
++INCLUDE are ignored.
TAB characters cause the parser to terminate early. The COPY
directive is the only compiler directive supported.
The PC COBOL SELECT ... ASSIGN TO .... options are not
recognized by SEO and the name SEO picks for the DDNAME is
unpredictable.
Lower case letters are converted to upper case letters.
The COBOL II, READ ... AT END imperative-statement
NOT AT END imperative-statement
results in NOT AT END being considered as data element names
and they are flagged as UNKNOWN DATA ELEMENT's and written to
the program's .seo file.
TYPE RELATIONS CODES
See TYPE column on the PEO ELEMENT DISPLAY SCREEN (Figure 4).
ACCEPT ACCEPT. Indicates the data element name is related
to an ACCEPT verb. The data element may be a component of a group
referenced by the ACCEPT.
ADD ADD. The element is a term in an ADD statement.
ADDCORR ADD CORRESPONDING. The element is a member of a
group referenced in an ADD ... CORR statement.
ALIAS PARAMETER RELATED TO ARGUMENT. Shows the data
element used in the subprogram when the TARGET is the data
element in the calling program. Shows the data element used in
the calling program when the TARGET is the data element in the
CALLed program.
ARG:ENTR ARGUMENTS RELATED TO AN ENTRY POINT. This
appears on the PEO ELEMENT DISPLAY SCREEN when the target is
a CALLed entry point. It provides a connection between the
entry point and the arguments.
CALL CALL. Indicates a call to an entry point.
CALL:PRC CALL RELATED TO PROCEDURE NAME. The call to the
subprogram is contained in the procedure and the procedure is
the TARGET.
COMPUTE COMPUTE. Indicates the data element is part of a
COMPUTE statement.
CONDITIN CONDITION NAME. This is the 88-level condition
name and the variable name which it names.
DISPLAY DISPLAY. Indicates the data element name is
related to an DISPLAY verb. The data element may be a component
of a group referenced by the DISPLAY.
DIVIDE DIVIDE. The element is a term in a DIVIDE
statement.
DEPEND DEPENDING ON. Indicates the data element is used
in a GO TO ... DEPENDING ON data-element-name statement.
ELEM:GRP ELEMENT RELATED TO GROUP. This is the data
definition for a component/group relation. It points to the
data definition for the group containing the element.
ENTRY PT ENTRY POINT. Indicates an entry point invoked
by the corresponding CALL type.
EVALUATE EVALUATE. The element is in a EVALUATE condition
phrase.
FALLTHRU FALL THROUGH. This indicates the procedure
immediately preceding another procedure had no statements and
control falls through to the second procedure. This was
included as a relation because, often, a program will perform
a section name. Immediately following the section name is a
paragraph name. FALLTHRU makes it possible to identify the
paragraph name without having to view the source code first.
FLOW IN ELEMENT FLOWS INTO PROCEDURE NAME. The element
is contained in the procedure (TARGET) and is not modified.
FLOW OUT ELEMENT FLOWS FROM PROCEDURE NAME. The element
is contained in the procedure (TARGET) and is modified by the
procedure; or, in the case of a DISPLAY, WRITE, etc., the data
are output from the procedure.
GRPMOVE GROUP MOVE. Indicates the element is a member
of a group referenced in a MOVE statement.
GRPPARM GROUP PARAMETER. Indicates the element is a
member of a group which is referenced in a CALL, ENTRY, or
PROCEDURE DIVISION USING statement.
GRPREAD GROUP READ. Indicates the element is a
member of a group referenced in a READ/RETURN statement.
GRPWRITE GROUP WRITE. Indicates the element is a
member of a group referenced in a WRITE/REWRITE/RELEASE
statement.
IF IF. Indicates the element is used in an
IF statement.
JCL PARM JCL PARAMETER. This appears on the screen,
along with the type relation which points to the beginning
of the source file's PROCEDURE DIVISION. It represents the
data element names passed to the main program via MVS JCL
PARM=parameters sub-element of the EXEC card.
KEY KEY. The data element is used as a key for
a READ direct or START statement.
MULTIPLY MULTIPLY. The element is a term in a MULTIPLY
statement.
OPEN IN OPEN INPUT. This connects the DD name to the file
in an OPEN INPUT statement. If there is an OPEN I-O there will an
OPEN output relation, also.
OPEN OUT OPEN OUTPUT. This connects the DD name to the file
in an OPEN OUTPUT statement. If there is an OPEN I-O there will be
an OPEN input relation, also.
PERFORM PERFORM PROCEDURE. This points to where the PERFORM
statement is coded.
PERFORMP PERFORM TEXT. This points to where the PERFORMed
procedure is located; i.e., this is the text of the procedure.
PRM:CALL PARAMETERS RELATED TO A CALL VERB. This appears on
the PEO ELEMENT DISPLAY SCREEN when the target is a CALLed
entry point. It provides a connection between the CALL verb and the
parameters.
READ READ. Identifies the record in a READ statement.
RELEASE RELEASE STATEMENT. The TARGET element is referenced
in a RELEASE verb.
REMAINDR REMAINDER. The data element is referenced as the
remainder in a DIVIDE statement.
REDEFINE REDEFINES. This indicates a redefines condition.
RENAMES RENAMES. This is the renames condition.
RETURN RETURN STATEMENT. The TARGET element is referenced
in a SORT RETURN verb.
REWRITE REWRITE STATEMENT. The TARGET is referenced in a
REWRITE statement.
SEARCH SEARCH. Indicates the data element is used in a
SEARCH statement.
SET SET. Indicates the data element is referenced
in a SET statement.
SORT IN SORT INPUT PROCEDURE. This points to where the
SORT statement is coded.
SORT INP SORT INPUT PROCEDURE. This points to where the
SORT INPUT PROCEDURE is located.
SORT OP SORT OUTPUT PROCEDURE. This points to where the
SORT statement is coded.
SORT OPP SORT OUTPUT PROCEDURE. This points to where the
SORT OUTPUT PROCEDURE is located.
SRCEFILE SOURCE FILE. This points to the beginning of the
PROCEDURE DIVISION of the main program.
STRING STRING. Indicates the data element is used in a
STRING statement.
SUBCORR SUBTRACT CORRESPONDING. The element is a member
of a group referenced in a SUBTRACT ... CORR statement.
SUBSCRPT SUBSCRIPT. Indicates the data element is used
as a sugscript.
SUBTRACT SUBTRACT. The element is a term in a SUBTRACT
statement.
UNSTRING UNSTRING. Indicates the data element is used
in a STRING statement.
WRITE WRITE. Identifies the record in a write statement.
PERFORMANCE CONSIDERATIONS
You will note the PEO screens are extremely fast, no matter
how big the COBOL program is. But, the parser's performance
is affected by the size of a program and contents of a program;
especially, if the program contains a number of "group" MOVEs
(i.e., the number of groups moved, read, written, or passed as
parameters). Each element in the sending group is matched to a
corresponding element in the receiving group. This requires
extra time, especially in older programs where it's common to
move groups frequently in and out of save areas and pass entire
groups of elements to subprograms.
There is no good solution short of turning off the group move
logic; but, then there a risk of losing critical information.
A RAM drive can improve the performance of the parser.
Ram drives
Put some of the temporary files used by the parser on a RAM
drive. This is done by setting the paths to the temporary
files to the RAM drive. The environment variable names for
the temporary files are: SEOIDX, SEOINX, SEOINXHI, SEOMST,
and SEOSORT. If you don't have enough memory to put all these
files on a RAM drive, SEOIDX and SEOMST are the two most
important ones.
How big should the RAM drive be? As a rule of thumb, try one
meg for every 10,000 lines of code in the COBOL program. You
may have to estimate the size; because, the size is not the
size of the main source file. The size is the total lines of
code for all source files and copybooks in the entire program.
The factor that dictates the storage requirements is actually
the number of data elements in the program. It takes about
500 bytes per data element, mostly due to the sortwork files,
SEOSORT. The two most important files are SEOIDX and SEOMST.
The SEOSORT environment variable is for the sortwork files. If
they default to the hard drive it just means the sort will take
a little longer. A sort occurs at the end of each DATA DIVISION
and at the end of each PROCEDURE DIVISION. The SEOINXHI will
usually be core resident. Also, if your program contains 10 or
more modules (separately compiled subprograms) you may have to
specify additional directory space when you define the RAM
drive. The parser creates several work files for the main
program and for each subprogram. Please refer to your DOS manual
for information about defining RAM drives.
Output from the preprocessor and parser.
The output from the preprocessor is usually quite small. There
are two files which the parser uses, execprgm.prg and entrypt.eps.
Both of these files, along with the seoprep.seo file, are in the
application ID subdirectory of MACHY. The output from the parser
is usually quite large and is written to the EXS subdirectory of
the application ID. The parser creates three files for PEO to
load into its data bases. The three files are: <progid>.dat,
<progid>.exp, and <progid>.prc. Once PEO has loaded these data
into its data bases you can delete the three files. (If you
combined programs for analysis, the three files will be named
after the name you provided to the parser.) The amount of storage
required for these three files depend upon the size of the
program(s) and the amount of group activity in the COBOL
programs. E.g., one program we've worked with had over 50,000
lines of code (including subprograms) and required about
10,000,000 bytes of storage for the three files. Another program
had 34,000 lines of code, but it required about 20,000,000 bytes
of storage. The difference was, the second program did almost
everything at the group level, MOVE's, parameters, etc. The
parser attempts to relate the elements in the sending and
receiving groups, meaning there were several hundred relations
for each group activity. So, it's a good idea to delete the
.dat, .exp, and .prc files once they've been loaded into the
PEO data bases.
RESERVED WORDS
COBOL reserved words from the various versions of COBOL
must not be used as data element names or procedure names.
IV. JWY&Assoc., Inc.'s support for PEO.
JAMES W. YOUNG & ASSOCIATES, INC. provides three month's mail
and CompuServe support in accordance with the Association of
Shareware Professionals' policy of support for registered
software, applicable to JWY&Assoc, Inc.'s PEO.
After that period, support can be continued by licensee paying
ten (10) percent of the original registration price (ten percent
of $119.00, or $11.90, annually. Customization of SEO (the
parser) and PEO is available, on-site and off-site. Please
contact JWY&Assoc, Inc. for more information.
V. qikstart
DISCLAIMER - AGREEMENT
USERS OF PROGRAM ENTITY ORGANIZER (PEO) AND ITS SUPPORTING
SOFTWARE, THROUGHOUT THIS DOCUMENT, REFERRED TO AS SEO, MUST
ACCEPT THIS DISCLAIMER OF WARRANTY:
PROGRAM ENTITY ORGANIZER (PEO) AND SEO ARE SUPPLIED AS IS.
THE AUTHOR AND PUBLISHER DISCLAIM ALL WARRANTIES, EXPRESSED
OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF
MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR
AND PUBLISHER ASSUME NO LIABILITY FOR DAMAGES, DIRECT OR
CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF PROGRAM ENTITY
ORGANIZER (PEO) AND SEO. THE USER MUST ASSUME THE ENTIRE RISK
OF USING THE PROGRAM. ANY LIABILITY OF THE AUTHOR AND PUBLISHER
WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF
PURCHASE PRICE.
How to install PEO.
Run the install batch file by changing to the directory
containing the file and type the following
install x applicationID
where, x is the target hard drive letter (WITHOUT THE COLON)
and applicationID is a one to eight byte name you give to your
set of COBOL programs.
The install.bat file will create a directory called, MACHY.
The install.bat file then copies the PEO files to the MACHY
directory. The install.bat file creates a sub directory of
MACHY by using the one to eight byte applicationID.
Install.bat will create three sub directories of the
application ID: COBOL, COPY, and EXS. The peo.exe file is
copied to the EXS sub directory. The EXS sub directory is
used by the parser to pass files to peo.exe. The COBOL and
COPY sub directories are defaults for the application ID's
source code.
Here's what the directories look like after install.bat is run:
root the c: drive
|
MACHY the preprocessor and parser are here
|
application ID the working directory for a set of COBOL
| code
|
|_ EXS the peo.exe file resides here
|
|_ COBOL the default for the COBOL source files
|
|_ COPY the default for the copy books
How to start using PEO.
PEO is as easy to use as 1, 2, 3:
1. preprocess all the COBOL source code and copy books,
2. parse the program(s), and
3. load into the PEO data base, then analyze the program.
Step one must be done at least one time during the "life-cycle"
of PEO for a particular set of COBOL programs.
Step two parses the COBOL program and prepares it for PEO.
Step three, PEO, loads the COBOL program's output from the
parser and interacts with the user with easy to use screens
to do the analysis and documentation.
How to execute the programs. From the MACHY directory:
Type
prepro applicationID
where applicationID is the same as above. This is step one.
After step one finishes, type
seoexp00 applicationID programname
where applicationId is the same as above and programname is
the name of the COBOL source file. This is step two.
Change to the \MACHY\applicationID\EXS directory and type
peo
Follow the instructions on the PEO screens to load the program
and select the program for analysis and documentation. The PEO
screens are intuitive and you'll recognize immediately how
similar they are to using a compile listing for analysis.
It's likely your COBOL source code is already installed in
a directory; or, you do not want to put the programs and
copybooks in the PEO default directory. If either is true,
you must set the DOS environment variables listed below; type
set SEOCOBOL=drive[path]
set SEOCOPY=drive[path]
where drive is the letter of the drive containing the COBOL
source code and [path] is the path to the directory of the
source code.
The COBOL programs must have a .cbl file extension and the
copy books must have a .cpy file extension. The DOS RENAME
command can add/change extensions for all files in a single
directory. Please refer to the DOS manual.
The DETAILS.DOC file contains a deeper explanation of these
procedures and a discussion of performance considerations.
One final note. PEO was designed for mainframe COBOL; e.g.,
ANS74, ANS85, OS/VS, and most of COBOL II. It does not support
many of the language extensions found in PC-based COBOL. See
the file CAUTION.DOC.