
IFOP Information

This file contains general programming and operating documentation for IFOP.

 1. License
 2. Background
 3. Terminology
 4. Operating instructions
 5. Program organization
 6. MENUS.TXT
 7. Naming and usage conventions
 8. Printing and exporting
 9. Jumps and labels
10. File operations
11. Miscellaneous programming notes
12. Program maintenance
13. REPLACE statements and IFCOBREP
14. IFMAINT
15. IFCREATE and running IFOP


1. License

The software in the IFOP.ZIP package is free, and is distributed under the
terms of the GNU General Public License version 3.0, as published by the Free
Software Foundation. The full text of this license (copied from
http://www.gnu.org/licenses/) is included in LICENSE.TXT.


2. Background

IFOP is a customized MRP II system (Manufacturing Resource Planning),
developed for Irvine Fasteners (Ontario, Canada), a manufacturer of
industrial fasteners (bolts and nuts, mostly for the North American
automotive industry). It is also used by two related companies: Irvine Nuts,
which manufactures nuts, and Irvine Tools, which manufactures tools for
fastener production machines, especially for Irvine Fasteners. The computer
(Vax 4100 with OpenVMS and RMS) is located at Irvine Fasteners, and the other
companies use it remotely through a network. Each company uses the set of
data files defined in IFOP.COB, but the files reside in separate directories
and are unrelated. IFOP is designed for fastener manufacturing, so Irvine
Tools uses only some of its functions. The program employs logical variables
(IFAST, INUT, ITOOL, set at startup from information passed by VMS) to
identify the company, in order to select or bypass certain operations when
the requirements differ. A few operations use files from two companies at the
same time.

Note: Due to business confidentiality, the names mentioned above are not the
real names of these companies. Also, data embedded in the program and related
to these companies (names of persons, phone numbers, addresses, account
numbers, etc.) has been replaced with fictitious values.


3. Terminology

I use COBOL, as much as possible, the same way as other languages, so I
prefer common terms to the formal COBOL ones. Thus, the data items defined in
FILE SECTION are called "fields" (i.e., the fields in the records of data
files). Those defined in WORKING-STORAGE SECTION too are called "fields"
(since they are used in the same way), but they are also called "variables."
Thus, "fields" without the "file" qualifier implies both types. Paragraph
names are called "labels" when used as the destination of a jump. Otherwise
they function as the name of "procedures," which are "called" or "invoked"
from various places in the program (by means of PERFORM). There are no real
"parameters" or "returned values" for these procedures, but they are
simulated with variables, so those terms are still used. Similarly, although
there are no "local variables" in COBOL, this term is used for variables
purposely restricted to specific parts of the program. Finally, I refer to
the various menu entries as "functions," and to the program parts that
correspond to these functions or to other logical units as "sections" (but
these are unrelated to the formal COBOL sections).


4. Operating instructions

Refer to the file MENUS.TXT, which shows the IFOP functions as they appear in
menus, as well as the section labels corresponding to these functions.

There are three levels of menus. The main menu is what you see when starting
IFOP: the entries G, S, I, etc. Selecting under "function" one of these
letters (upper or lower case) takes you to a submenu, or second-level menu
("G: GENERAL", "S: SHIPPING", etc.), where you enter under "function" one of
the numbers listed. In that function, to return to the submenu, you typically
press PF4 (function key 4) in the first input field there (customer no.,
product no., etc.), or enter all 9's in that field (if working from a
terminal with no VT function key emulation). Some functions create a listing,
or perform an updating operation; in this case, after specifying the run
parameters, there is the prompt "OK"; enter "OK" (upper case) to execute the
function (returns to the submenu when finished), or nothing to cancel it
(returns to the submenu immediately). Note that, like "OK", all prompts
("YES", "Y", "ADD", "DEL", "CAN", etc.) must be answered in upper case.

To go directly to another submenu from the current submenu, enter the new
letter (G, S, I, etc.) as "function." If you forgot the letters, enter PF4 or
99 to return to the main menu, where the letters and submenu descriptions are
shown. If you know the letter and the function number, you can enter them
directly in any submenu, or in the main menu, without going first to the new
submenu; for example, G17, P2, T16, M24. This lets you jump quickly from one
function to another (but not to the Z functions).

The submenu "Z: BATCH AND OTHER" is special. It is for functions like reports
and updates that may take some time to execute, but it also includes other
functions, kept here for various reasons.

First, five of the functions (16 to 20) are in fact third-level menus (e.g.,
"16: FINANCIALS MENU"), so when you select them as "function" you get a menu,
where you select the final function from a list.

Second, the Z menu has the "batch" feature, which allows you to queue up to
30 functions to be executed automatically, one after the other. (This feature
currently applies only to about ninety of the functions in the Z menu and its
submenus). It is typically used in the evening, to execute various reports
and updates that take together several hours, and which must run at the end
of the day. If you enter anything (e.g., "Y") in the BATCH field, then, after
entering the run parameters for that function (e.g., date range, print file
number) and "OK" to start, the system saves the information in a table,
without executing the function; it returns to the Z menu, where you can
specify the next function, and so on. When finished, enter 77 as "function"
to start the batch execution. Between batch function entries, you can still
execute any function normally, by leaving the batch field blank, or go to the
submenus G, S, I, etc., as long as you don't exit IFOP (since the table is
stored only in memory).


5. Program organization

Although IFOP.COB is large, its structure is simple and consistent, so it is
easy to navigate. Starting with the file definitions, the files are listed in
the same order with the SELECT's (in INPUT-OUTPUT SECTION) and with the FD's
(in FILE SECTION). In WORKING-STORAGE SECTION, the first half consists of
global variables, used throughout the program, grouped by function; the
second half (starting at line "* G: GENERAL FUNCTIONS") consists of variables
used only in specific sections, grouped by section, in the same order as the
sections themselves (but not all sections have their own variables).

PROCEDURE DIVISION includes display procedures, global procedures, the
initialization section, the menu section, and several hundred sections
corresponding to the menu functions and related operations. The
initialization section (executed at startup) starts at label MN0; it is
followed by the RDxx procedures (static display data); then, starting with
WRT and grouped by function, the global procedures (used throughout the
program); then, starting with MN-AXFUNC, the menu section and its procedures;
finally, from line "* G: GENERAL FUNCTIONS" to the end of the program, the
sections for the menu functions and their procedures, along with related
sections, in the order shown in MENUS.TXT.

As additional help in navigation, the menu title lines "* G: GENERAL
FUNCTIONS", "* S: SHIPPING FUNCTIONS", etc., are inserted where the functions
of the respective menus start, for both variables (in WORKING-STORAGE
SECTION) and sections (in PROCEDURE DIVISION).


6. MENUS.TXT

The file MENUS.TXT contains the menus of IFOP and the section labels
corresponding to the functions depicted in these menus. The order in which
the menus are listed, as well as the order of the functions within each menu,
is also the order in which the respective sections appear in IFOP.COB.

Below each menu are listed the labels for the sections belonging to that menu
(arranged in rows of ten, so it is easy to match labels and menu entries).
They are simply copied from IFOP.COB: the menus are from RDxx procedures
(except the scanner menu, found at label MW1), and the labels are from GO
DEPENDING statements in the menu section. But their arrangement in MENUS.TXT
is usually more convenient than searching for menus and labels in IFOP.COB.
For example, if you want to find in the program the section for a certain
menu entry, you can search first for that entry in MENUS.TXT, read the label,
then search for the label in the program.

A few sections in IFOP.COB are not functions invoked from a menu, but
procedures invoked from other sections. They are located among the regular
sections because they are similar to, and closely related to, the menu
functions. Since their labels do not appear in the lists of section labels,
they are shown in MENUS.TXT below these lists in lines like "after KG1: LG1
(LG-GEN-EXTEN)", which means that the procedure LG-GEN-EXTEN, with label LG1,
is located in the program after the section KG1. The two scanner sections,
IW1 and LW1, are implemented as regular sections and are found in a labels
list below the scanner menu, but are also shown as "after" lines in other
menus, because they are located in the program after IV1 and LZ1,
respectively, to which they are closely related.

In addition to the menus, MENUS.TXT includes, at the end, an inventory of the
name prefixes used in IFOP.COB for sections, procedures, fields, and
variables (see "Naming and usage conventions"). Only the one- and two-letter
prefixes are shown. Together with the lists of section labels, the lists of
prefixes function as reference: by searching MENUS.TXT for a given prefix you
can quickly determine whether and how it is used in the program.


7. Naming and usage conventions

Names are known in COBOL throughout the program, but it is possible to avoid
conflicts by restricting them to specific uses. In IFOP.COB this is
accomplished by means of name prefixes. Most prefixes have two letters; there
are a few one-letter prefixes, many three-letter prefixes, and a few
four-letter prefixes. In general, names used more frequently are assigned
shorter prefixes. Names designate fields, variables, procedures, and labels.
Whenever possible, there is no dash (FA387, IA25, TF324, TPOS, WN1, BI3,
FH23, LC45, etc.); but most prefixes need a dash (RP-F29, SR-F162, O-TER,
FL-QTY, D-DAYS, LAS-PAGE, A-A1, PROC-PACK, MS-OP, ID-OLD, TN-PAGE, DRW-E3,
CST-NT2, etc.).

Each section has its own, two-letter prefix, used for all labels within the
section. Thus, for prefix XY, the labels are named XY1 to XY9. There is a
jump to XY1 from the menu section, and a jump back to the menu section from a
statement following XY9. Any procedures associated exclusively with this
section are listed following it, and their names start with XY-. If such a
procedure has labels, they are named XY-z1 to XY-z9, where z is one to three
letters. Any variables used exclusively in this section are grouped under a
level 01 item named XY-FIELDS in WORKING-STORAGE SECTION, and their names
start with XY-.

Global procedures (used throughout the program and listed at the front of the
program) have one- to four-letter prefixes (very rarely, more than four). If
a procedure has labels, they are named (assuming prefix XY) XY-z1 to XY-z9,
where z is one to three letters. Related procedures typically use the same
prefix and are listed together. Any variables associated with such a prefix
are grouped under a level 01 item named xxx-FIELDS (where xxx is usually a
word describing their use) in WORKING-STORAGE SECTION, and their names start
with XY-. These variables, however, may be used throughout the program, not
just in these procedures. Conversely, there are some global variables defined
in this manner, whose prefix is not associated with any procedures.

The fields of files have one- to four-letter prefixes, and these prefixes are
not shared with any variables, procedures, or sections.

In addition to providing some documentation, prefixes create in effect what
is known in other languages as local variables: items are used, whenever
possible, in only one section, or in only a set of related procedures, which
eliminates the risk of conflicts when modifying the program. Similarly, each
RDxx procedure (display of static data) is used in only one place.

The same convention applies to fields used in work files (MFA-Fxx, MFB-Fxx,
RP-Fxx, SR-Fxx, SC-Fxx), in print files (FAxx, FDxx, FFxx, FGxx, FJxx), in
user input (IAxx, IExx), and in display (TFxx, THxx). In these names, xx
stands for a number of one to three digits. The numbers have no significance
-- they are simply assigned sequentially, as new fields are created. The
fields are used in sets unrelated to one another: the fields comprising a
file's record, or the input data from a screen, or a printed line, or a
display line. Thus, although there are many fields with these prefixes, each
set is used in only one place in the program, so we can modify or delete its
fields without worrying about conflicts. For example, even when two display
lines are identical, if used in different places they have different sets of
fields.

There are about ten exceptions to this convention, occurring when certain
operations are performed in two related sections but are not global in
nature. In this case some fields or procedures local to one section are
simply used also in the second one. For example, procedures in MR are also
used in IT, procedures and fields in IV are also used in IW, the same RDxx
procedure is used in FK and VX. All exceptions are documented with notes in
the program.

The Wxx variables grouped under WORK-FIELDS (WA1, WN1, etc.) are used
throughout the program, but in a local way: their purpose is to store
temporary values when needed in operations spanning just a few statements.
This is a very common requirement, and using the same variables eliminates
the need for hundreds of local variables. Since they are used in a small
portion of the program at a time, and usually only at nesting level 0 (i.e.,
not in procedures), it is easy to ensure that there are no conflicts.

The A-xx variables grouped under PARAMETER-FIELDS (A-A1, A-N1, etc.) are used
to simulate parameters and returned values when calling procedures. Many
procedures need no parameters, but when needed, values are assigned to one or
more of these variables before the call; and if a returned value is needed,
the procedure assigns a value to one of these variables. In simple
situations, these variables also function as local variables in the
procedure, but in general, local variables defined through the prefix method
are preferable. To avoid the risk of conflicts, A-xx variables are used only
for calls at nesting level 0. In the case of nested calls or many related
procedures, local variables, or global variables that have a specific role,
are used for parameters and returned values.


8. Printing and exporting

There are four print files: PRINTFL creates files for the main printer, which
is defined as line-printer with fixed-length 132-character lines. DOCFL
creates files with variable length lines, mainly for dot-matrix printers, but
also for laser printers when the text is simple and can be created in line
(rather than page) mode. The file is normally created for either dot-matrix
or laser, with the initialization and formatting codes specific to each type.
LASFL creates files with continuous data (text and graphics) for laser
printers, using PCL commands. LABFL creates files with variable length lines
for Zebra printers (barcoded labels), using ZPL commands.

The name of a print file consists of a prefix, a file number, and the
extension PRN. The prefix can be PR, PA, or PB (depending on the user) for
PRINTFL and DOCFL, LAS for LASFL, and LAB for LABFL. The file number can be
00 to 99. Thus, the file may be PR06.PRN, PA23.PRN, LAS01.PRN, LAB09.PRN,
etc. For PRINTFL and DOCFL, the file number is specified by the user
(typically, each user is restricted to a range of numbers, to avoid
conflicts). Thus, reports can be created as files, and printed later (with
G-6 PRINT A FILE or with the PRINT command in VMS). For LASFL and LABFL, the
file number is assigned by the program, depending on the function: for LABFL,
only a few numbers are needed, and they are shown with the function; for
LASFL, the numbers are not shown, since the file is printed directly by the
program (by invoking the VMS PRINT command) as soon as it is created. For
DOCFL and LABFL, too, in a few functions, the file is printed directly by the
program; in this case the file name is PP or LLL, respectively, and the
number is assigned by the program. There are several laser, label, and
dot-matrix printers, and the particular printer needed in each case is
specified through the QUEUE feature of VMS.

Some reports, in addition to (or instead of) a print file, create an export
file (EXPFL). This is an ASCII file with tab-delimited fields and a header
line describing the fields, typically used as input to spreadsheets or other
systems on a PC. The fields may not be identical to those in the print
report. For these reports, the phrase "also export file" (or "only export
file") appears in the screen where the report is selected. The name of the
export file has the prefix FL, the extension PRN, and the number specified by
the user for the print file.


9. Jumps and labels

Jumps in the flow of execution are implemented with the GO TO statement
(abbreviated as GO). Jumps are used to streamline, simplify, and clarify
certain conditional and iterative constructs; in particular, those involving
large blocks of statements or nested constructs. GO TO provides the means to
implement explicit jumps, as opposed to the implicit ones found in the
standard, built-in flow-control constructs. The use of GO TO has been the
subject of misguided criticism for many years, and I have discussed this at
length in my book, "Software and Mind," in the section on structured
programming, and especially in the subsection "The GO TO Delusion" (which is
included as an extract in the IFOP package). As I demonstrate there, all it
takes to answer the objections to GO TO is a consistent system of jumps and
label names. With such a system, rather than confusing us, the jumps improve
and document the program's flow of execution. The system used in IFOP.COB is
as follows.

Jumps are always internal to a given section or procedure. Also, jumps are
restricted to specific purposes. Backward jumps are used to return to the
beginning of a loop or other repetitive operation. Forward jumps are used to
bypass blocks of statements; exit from, or go to the end of, a loop or other
repetitive operation; go to the end of the section or procedure; and go to a
common logical point. Labels are numbered consecutively within a section or
procedure, using the same prefix. Thus, in a section with prefix XY, the
sequence of labels might be: XY1 XY23 XY29 XY3 XY4 XY42 XY63 XY68 XY8 XY9.
Backward jumps are always to a label ending with an odd digit, and forward
jumps are always to a label ending with an even digit. There are no unused
labels -- each label is the destination of at least one jump.

The following exceptions apply to these rules: In a section, the label XY1 is
also used as entry point, for a jump from the menu section; at the end of the
section there is a jump back to the menu section; and in sections where the
user specifies run parameters, there is a jump there back to the menu section
in case of errors or as part of the batch feature. Labels ending with 9
(XY29, XY469, XY9, etc.) are always used for forward jumps (since they
designate the end of some logic). All sections have a label XY9 to indicate
their end, even if there are no jumps to it. The statement GO DEPENDING with
a list of labels always consists of forward jumps; but the labels, if within
a couple of lines of each other so there can be no confusion, use a natural
sequence (e.g., XY51 XY52 XY53 XY54) rather than all ending with an even
digit; if they are many lines apart, all end with an even digit. The labels
MN1, MN9, MW1, MW9, MX1, and MX9 in the menu section are special, because,
apart from jumps within the menu section itself, they are the destination of
jumps from elsewhere in the program: MN1 and MW1 for jumps from the startup
section; MN9, MW9, MX1, and MX9 for jumps that return to the menu from a
section. MN0 is only used to mark the first section in the program.

These exceptions apply also to procedures, when relevant. Procedures are
accessed only with PERFORM, through their name. A procedure has labels only
if it requires internal jumps, and then it takes the form shown below. All
returns are through XY-P9. A procedure with no labels ends and returns simply
after the statement preceding the next procedure or section label.

XY-PROC. PERFORM XY-P1 THRU XY-P9.
XY-P1. ...
    ...
XY-P9. EXIT.

Very rarely, to keep a short procedure simple, the name of the procedure is
also used as label for an internal backward jump (for example, in the RDLK-xx
procedures).


10. File operations

10.1 IFOP accesses files only through COBOL statements (READ, READ NEXT,
START, WRITE, REWRITE, DELETE). Most files are indexed data files, and a few
are sequential or relative. When reading a series of records, the operations
involving indexed files are based on the concept of a file scanning loop:
START defines the first record, and READ NEXT is used repetitively in a loop
to scan the records in the sequence established by the index. Conditional
statements can be used in the loop to select or skip records. File
relationships are established by nesting their scanning loops and selecting
records in the inner loop based on the current record in the outer loop. The
operations involving indexed data files are described in detail in my book,
"Software and Mind," in the subsection "The Basic File Operations" (which is
included as an extract in the IFOP package).

10.2 When reading a record, the program locks it only if it is going to be
modified, and only if other users may also attempt to modify it at the same
time (which could corrupt some fields). In most situations this cannot occur,
so most READ's do not lock the record even if the record will be modified.
(To read and lock a record, the procedures RDLK-CUSTOMER, RDLK-VENDOR, etc.,
are used, and the record is kept locked as briefly as possible.) The reason a
record can be safely modified in most situations without locking is that it
is known which menu functions that modify the same files might be accessed at
the same time by other users.

10.3 The OLD-xx variables grouped under OLDKEY-FIELDS (OLD-N, OLD-M, etc.)
are used to manage record breaks when scanning indexed data files, especially
in reports. As many of these fields are needed as there are key fields in the
file's key, and there is a different break operation (typically, printing and
clearing subtotals) for each field; for example, three operations in the
sales history file, for date within product within customer. The fields are
initialized before the file scanning loop with some values that do not occur
in the file, and are compared in the loop with the key fields in the current
record, starting with the most significant field. When different, the break
operation is performed, first for the less significant fields, if any, and
then for the field just compared. Then the OLD-xx fields are assigned the
current values, to prepare them for the following records. After the last
record is read, all break operations are performed.

10.4 Many inquiry functions employ the "more/end" logic (sections ON, CO, AQ,
LO, PB, etc.). There are variations, but the basic operation of these
functions is the same. Two related files are involved: transactions by
customer, purchase orders by vendor, production orders by product, etc. You
are asked to enter a starting value for the key of the main file (customer
number, order number, etc.), and the program displays some data for this
record and a number of related records from the secondary file. Up to about
17 lines can be displayed. The message is "MORE" if there are more, or "END"
if the last of these records was displayed. If more, press Enter to display
the next set of records, or enter another value for the key of the main file.
This can be repeated any number of times. When "END" is displayed, enter
another value for the key of the main file, or press Enter to continue with
the next value in the indexing sequence.

10.5 There is a bug in RMS, affecting record deletion in indexed data files:
when deleting many records with consecutive keys (for example, with READ NEXT
and DELETE in a loop), sometimes the system stops at a particular record with
the error message "record not found" infinitely repeated. In places where
this problem may occur, the following method has been adopted to prevent it:
the deletion loop is enclosed in another loop, which includes the START; the
records are counted, and when reaching 100 (typically), the file is closed
and reopened, and START is again executed, specifying the last record
deleted. There are several examples of this logic in the RL section (where
RL-IXD is the counter, and RL-OA is used to save the current record key for
START).

10.6 MAINTA is a sequential work file, used for temporary storage when
manipulating files or when collecting data. MAINTB and MAINTC are identical,
and are used when two or three such files are needed at the same time.

REPFL is a work indexed data file used to create sorted records, especially
for reports. It is needed when one of the main data files must be scanned in
a sequence different from those provided by existing indexes, or when a
special file is needed, with fields collected from several data files. The
typical operation has two stages: first, the main file is scanned in a loop
and REPFL is created; then, REPFL is scanned in a second loop and the report
is created. The required sorting sequence determines the REPFL key fields.
Additional fields are included: the actual data for the report columns if
only a few fields are needed, or values to identify the records of the main
file so as to read them again when creating the report.

SORTFL is similar to REPFL, but is used in any situation where temporary
sorted records are required, including inquiries; for example, for data
analysis. It is often used together with REPFL. SORCFL is identical to
SORTFL, and is used in the rare cases where two such files are needed at the
same time.

The names of these work files on disk consist of the names shown here plus a
10-digit suffix representing the user number and the time IFOP was started.
Thus, only one actual file exists within each IFOP run, no matter how many
times it is created. These files are deleted in IFOP if the functions using
them end normally.


11. Miscellaneous programming notes

11.1 The compiler used is OpenVMS COBOL v. 5.6, which is COBOL 85 with
extensions (especially for ACCEPT and DISPLAY, and for the file operations).
IFOP compiles in 8 minutes on a Vax 4100. (Interestingly, it takes much
longer on a more powerful 64-bit Alpha system, because RISC compilers are
very slow with large programs.)

11.2 Most optional COBOL keywords are omitted. Here are some of the
abbreviations (with the omitted keywords in parentheses): GO (GO TO), GO
DEPENDING (GO TO DEPENDING ON), READ ... END (READ ... RECORD ... AT END),
... REGARDLESS (... REGARDLESS OF LOCK), ... ALLOWING NO (... ALLOWING NO
OTHERS), ... INVALID (... INVALID KEY), SELECT ... ASSIGN ... STATUS ...
ORGANIZATION ... ACCESS (SELECT ... ASSIGN TO ... FILE STATUS IS ...
ORGANIZATION IS ... ACCESS MODE IS).

The period is the preferred statement terminator. Keywords like END-IF,
END-COMPUTE, and END-READ are used only when required syntactically or to
prevent misinterpretation (for example, when the respective statements are
nested in an IF statement).

11.3 Numeric fields are defined as COMP-3 (a kind of packed decimal format),
rather than COMP (which turns fields into words, double-words, or quad-words,
depending on the number of digits), because that is a better match for their
usage. There is no measurable difference between the two formats in execution
time, and negligible difference in overall storage space.

11.4 The batch logic (described in "Operating instructions") is implemented by
means of the S-xx variables (found under 01 BATCH-FIELDS). The logical
variables S-DEF and S-BAT control the flow of execution: S-DEF is set when in
batch definition mode, and S-BAT when in batch execution mode. A function
that supports the batch feature checks these variables; if S-DEF is set, once
the run parameters are entered the function saves them (in S-xx variables)
and returns to the menu; if S-BAT is set, the function retrieves the saved
parameters instead of asking for them, then continues normally. Only
parameters specific to each function need to be saved by the function, since
those for "from-to" range pairs, print file number, and standard selection
options are saved by default for all functions. Currently only 89 functions
in the Z menu and its submenus support the batch feature (these functions can
be recognized by the statement "IF S-BAT" at the beginning).

11.5 The RDxx procedures create the static display data for the display
screens by moving whole lines, as character strings, into TD-SCREEN (which
is large enough to contain 25 lines of 80 or 132 columns). WRT is then called
to display the screen. (The operation of WRT is explained in a documentation
note there.) The variable data is usually added field by field, wherever
needed on the screen. It may be added to TD-SCREEN with MOVE statements
before calling WRT, or displayed with DISPLAY statements when the static data
is already displayed. Sometimes there is little difference between static and
variable data, so static data too may be displayed with DISPLAY statements.
Variations of these methods are found when parts of the screen must change
after the initial display.

11.6 Engineering drawings for finished products and for tools are stored on
the Vax so that they can be conveniently displayed or printed by any user,
directly or as part of other functions. The drawings are stored in two
different formats, in separate data files: DRAWINGS for display (originally
on VT330 terminals, now on PC's with VT emulation software), and PDRAWINGS
for printing (on laser printers). The record key in these files consists of
drawing number, page number (drawings have one or two pages), and line number
within the page. The lines contain the graphics data. To produce a particular
drawing, the program reads the records with that drawing number, one by one,
and displays or prints the line data. For display, the format is sixel
graphics; each line represents 6 pixel lines encoded as ASCII characters, and
varies in length (due to compression). For print, the format is PCL raster
graphics with adaptive compression; each line is simply a block of 512 bytes
of binary data.

The drawings are created on a PC with AutoCAD. To transfer them to the Vax,
they are exported in PCX graphics format, converted on the PC using C
programs into the two formats needed on the Vax and merged into two separate
files, then read in IFOP with T-6 READ DRAWINGS INPUT FILE. These operations
are performed automatically a couple of times a day through a batch program,
which selects each time the new and modified drawings. (The two C conversion
programs are not included in the IFOP package, but they are available under
the GNU license if there is serious interest.)

11.7 Dates are treated as numeric values (the number of days since Dec 31,
1869), but are entered and displayed/printed as MMDDYY, YYMMDD, etc. The date
procedures and the associated variables (found under 01 DATE-FIELDS) are
named D-xx. Several documentation notes (starting at AX-SYS-DATE) explain the
date operations.

11.8 Consecutive statements are kept on one line whenever possible, but only
when it is logical to do so. They are separated with spaces. A period is used
as separator only when required syntactically or to prevent misinterpretation
(for example, to end an IF statement). But a period is always used at the end
of a line if the statement ends there. If there is no period at the end of a
line, it means that the statement is continued onto the next line, and the
next line is indented. Blocks of statements are indented only if there are no
intervening periods or labels. Thus, loops created with PERFORM are indented,
but loops created with explicit jumps are not (the matching label and jump
document then the beginning and end). Indentation is normally two character
positions per level, but it may be more, or only one character, depending on
the surrounding lines. If the indented line would start too far from the left
margin, reverse indentation is used instead. Blank lines are used sparingly,
usually to indicate a logical break.

This coding style, along with the use of short names and keeping the
documentation notes in a separate file, makes it possible to see at a glance
larger parts of the program, which clarifies logical structures like loops,
conditions, blocks of statements, and declarations of variables.


11.9 The following VMS batch file may be used to compile IFOP:

$ COBOL IFOP/NOLIST/NODEBUG
$ LINK IFOP/NOMAP/NOTRACEBACK

The following batch file is needed to compile IFOP if IFCOBREP is used (see
below, section "REPLACE statements and IFCOBREP").

$ DEFINE OLDFL IFOP.COB
$ DEFINE NEWFL IFOPREP.COB
$ RUN IFCOBREP
$ DEASSIGN OLDFL
$ DEASSIGN NEWFL
$ COBOL IFOPREP/NOLIST/NODEBUG
$ LINK IFOPREP/NOMAP/NOTRACEBACK
$ REN IFOPREP.EXE IFOP.EXE

The following lines may be added at the end of the batch file to optimize the
use of IFOP in a multiuser environment (IFOP runs in directory IFMAIN):

$ SET DEFAULT SYS$SYSTEM
$ INSTALL REPLACE/SHARED DUA1:[IFMAIN]IFOP
$ SET DEFAULT DUA1:[IFMAIN]

IFCOBREP, IFMAINT, and IFCREATE can be compiled directly; for example:

COBOL IFCOBREP
LINK IFCOBREP


12. Program maintenance

12.1 I have maintained IFOP for many years on a PC, working in a home office,
using an editor I developed myself. The editor has many features which are
not found in commercial systems, but which I consider essential; in
particular, versatile search and replace functions, the ability to work with
several files and different parts of one file at the same time, and
programmability. I access the Vax remotely, through VT terminal emulation
software running on the PC. It is always the IFOP copy on the PC that I
modify; the editor creates a file with the modified parts, which I upload to
the Vax, where a program reads it and updates IFOP.COB. I compile it and test
the changes. Print files I examine online, or download and print on the PC.

12.2 MENUS.TXT is a convenient reference for the section labels and for the
one- and two-letter name prefixes, as noted earlier. But to remain accurate,
the label lists and the prefix lists must be updated whenever a change in
IFOP.COB demands it.

12.3 The name of fields used to specify print or display lines, work file
records, and user input consists of a prefix and a number, as noted earlier:
FAxx, FDxx, TFxx, SR-Fxx, RP-Fxx, etc. (where xx is a number of one to three
digits). These fields are used in sets, and to keep their neat appearance,
they must be properly maintained. When a field is deleted, a gap is left in
the sequence. When a field must be inserted in an existing set, the suffix A,
B, etc. is used (e.g., TF63 TF63A TF63B TF64). But when there are too many
gaps or too many suffixes, the whole set is moved to the end of the sequence
and assigned new numbers. When sets are moved or deleted, the gap is marked
and reused later for new sets. The ultimate goal is to have few gaps and
suffixes. Since each set is used in only one place in the program, these
editing operations are quite simple, and with a good editor they can be
largely automated.

12.4 The output for the print files LASFL (laser printers) and LABFL (Zebra
bar-coded label printers) consists of PCL and ZPL commands, respectively
(e.g., section QH and the BAR-LAB-xx procedures). The simplest way to develop
these functions is to create the output file with the editor as a text file
using some test values in the variable fields, and test it on a printer
connected to the PC. To convert it to COBOL code, the text lines are turned
into character strings, STRING and MOVE statements are added, and the test
values are replaced with the names of variables. Additional operations may be
needed for complex files. The resulting code is then incorporated into the
program and tested. The text file is kept and reused later in the same way to
implement changes, and also as a starting point for similar files.

12.5 There are two ways to handle values that change infrequently: embed
(hard-code) them in the program and, when they change, modify the program; or
store them in a data file and add a function in the program to allow the
users to modify them. The first method is much simpler and is the preferred
one in IFOP. Unlike commercial applications, IFOP is enhanced and modified
continuously, so modifying from time to time also certain values embedded in
the program is a trivial task. These values are usually defined in
WORKING-STORAGE, but sometimes are found as part of COBOL statements. In
general, only when a value changes regularly, especially if more than about
once a year, is a maintenance function provided. Most of these values are
stored in two files, INFOFL and TABLES (which contains 24 different tables),
and maintained through Z-23 and Z-24.

12.6 The numbered documentation notes (the actual text is in NOTES.TXT)
provide explanations and clarifications in complex or unusual situations. It
is both impossible and unnecessary to document every piece of logic in the
program. In general, understanding IFOP must rely on its consistent
programming style, and on a good editor. Fast and convenient search
operations, and the ability to see several parts of the programs at once,
help you to understand a piece of logic by discovering the uses of a certain
field or procedure, by linking display screens with variables and with the
statements that use them, and so on.

Notes generally refer to the line immediately preceding or following, but
many refer to a piece of logic encompassing several lines in its vicinity.
For example, a note preceding a loop may refer to statements in the loop.
Some notes refer to several items following it (for example, several related
procedures). Note numbers have suffixes when they deal with the same issue
but appear in different places in the program (e.g., 87.1, 87.2, 87.3).


13. REPLACE statements and IFCOBREP

IFOP.COB uses REPLACE statements (text substitution macros) to shorten and
simplify the source code wherever possible. However, a certain limitation
related to REPLACE in version 5.6 of the compiler has been preventing it from
working properly since IFOP.COB exceeded about 45,000 lines. To solve this
problem, a small utility, IFCOBREP (source included in the IFOP package), was
developed to process the REPLACE statements before compilation.

To keep the utility simple, there are certain assumptions and limitations for
the REPLACE statements: from/to string lengths maximum 20/150 characters;
only one from/to pair definition per line, and each from/to pair definition
takes only one line; up to five from/to pair definitions per REPLACE; REPLACE
starts in position 5 and has one space before the ==; each REPLACE is matched
by a REPLACE OFF, and all are syntactically correct; strings cannot start/end
with spaces; the logic is plain string substitution (unlike the compiler,
which recognizes whole words).

Programming notes: To compensate for the deficiency of the plain string
substitution logic, string pairs are sorted in the STBL table in descending
"from" string length order, so that when searching the table, if the
beginning of a longer string is the same as a whole shorter string, the
longer one is seen first and is used for substitution. The sixth entry in the
STBL table is used only as work area. The REPLACE lines, once used, are
canceled by writing "*" in column 1, to hide them from the compiler.

Example of use:

Input:
    REPLACE ==AAA== BY ==BBB BBB==
            ==CCCC== BY ==DDDD DDDD DDDD==.
    ...
    XXX XXX AAA XXX XXX CCCC XXX XXX
    ...
    REPLACE OFF.

Output:
*   REPLACE ==AAA== BY ==BBB BBB==
*           ==CCCC== BY ==DDDD DDDD DDDD==.
    ...
    XXX XXX BBB BBB XXX XXX DDDD DDDD DDDD XXX XXX
    ...
*   REPLACE OFF.


14. IFMAINT

IFMAINT performs data file maintenance at year end for the most active data
files, and must be used after running Z-21 MONTH-END FILE UPDATE for
December. For each file, the program creates a new version and copies the
records from the old version. This is the simplest way to reduce the space
taken by a file when records are deleted during the year, and is necessary
because RMS uses for new records the space freed by deleted records only if
the new records have key values identical to the deleted ones. Related files
are processed together, to ensure that no spurious records are retained.

In addition, for those files that must retain past records only for a certain
number of years back, the old records that must be discarded are omitted in
the copy operation. The limit dates change every year and are specified
within the program (see the notes at label L0), so IFMAINT must be recompiled
every year.


15. IFCREATE and running IFOP

If you wish to run IFOP, you must run first IFCREATE to create the data
files. (Although some versions of VMS create them automatically when IFOP
attempts to open them, you must still use IFCREATE, for reasons explained
below.)

IFOP expects to find the data files in directory DUA1:[IFMAIN]. A few
functions in IFOP use 3 files from the payroll system, and these must be in
directory DUA1:[PAY30]. You must create these two directories, and then run
IFCREATE in DUA1:[IFMAIN]. It creates 84 files there and 3 files in
DUA1:[PAY30]. All files are empty, with the following exceptions.

INFOFL and EDINFO contain various system variables in one record, and these
records are created with null values.

USERS contains the access authorization tables, and one record is created,
for user id USER1, to enable you to access the various menu functions (all
functions in all menus are set to YES for this user). In IFCREATE.COB, near
the end, in the statement MOVE "USER1", the string is the VMS id of the
person using the program; so you must modify this value accordingly and
recompile IFCREATE before executing it. Once the functions are accessible,
you can maintain these tables in Z-24, function 80 (note that this function
is deliberately not shown in the menu there). One more point: if you have the
special user id SYSTEM, you must enter KZX (in upper case, just once) in the
function field in the main menu, else "FUNCTION NOT AUTHORIZED" is returned
by all functions regardless of the table settings.

Note that some functions may cause various VMS runtime errors when performed
with empty data files.

