Service programs, copy books, system reference file

Generally speaking, a well- but not over-engineering naming convention will
serve you well over time. Death to program names like ORDENT and its
b*st*rd stepchildren ORDENTA, ORDENTNEW, and their spawn. Using a naming
convention has allowed me to write dozens of programmer/development tools.

Using /COPY or /INCLUDE is another smart software engineering move. If
you're putting together a prototype app, hard-code constants into copy
books. That's technical debt and you pay that off by replacing the
hard-coding with calls to a service program that pulls the values from a
system reference file. This might appear to be overengineering for an
in-house app; it's absolutely required for any app executing in multiple
systems (internal or customers).

*A system reference file is a programmer's tool.* A key design feature is
the ability to have lots of different data stored in the file(s), like the
Windows Registry; I have over 1,000 data types (state codes, province
codes, units of weights and volume as well as standard conversion factors,
period codes, aging day ranges, "last used" sequence numbers, currency
codes, and void reason codes) in my system reference file. All that data
is supported by one maintenance program and a few inquiries. The economics
can't be debated!

The short version of my system reference setup: the control file has a
"table key", data descriptions, and control information. This file is used
to control setting up entries in the detail file, where the details live.

The details file is keyed by the table name, two alpha key fields, two
numeric key fields, and (if you want to get serious about this) effective
and expiration dates. I include extra alpha and numeric fields to support
additional functions like replacing an entered value with a preferred
value, tracking "last used" numbers, and so on.

Example: for the terms code, the control file is keyed on TERMS. The
details file is keyed on TERMS and records with the values: P, C, PPD, CIA,
COL, DRC, NOC. The app passes in TERMS (the table name) and the value in
the app: "DRC". If that TERMS-DRC record exists, the edit passes. But you
can do way more: additional fields in the detail record can return other
helpful information. I have descriptions in the detail file and have a
generic pop-up window that displays, and allows the user to select, from
the list of codes. When you add a new value, the users see it if you
didn't use the "do not display" option.

Besides adding usability to the app, you're also creating documentation.
You can enter additional information in the details. Example, I assigned
another column with the terms type. P, PPD, and CIA are all "prepaid" and
have a P in the terms type column. C, COL, and DRC are collect terms and
the type column has a C. NOC is a non-revenue term and gets a "*" in the
type field. When a Canadian customer noted they used OCS for non-revenue
items, it was a 15-second task to add OCS to the table, type the
user-friendly description, and add the "*" terms type. The same customer
wanted non-standard weight pounds-to-kilogram conversions (as in not the
reciprocal value) with two-decimal precision (0.45 instead of 0.45359; 2.2
instead of 2.205). Those factors went into extra (numeric) fields in the
details file: no hard-coding, no source scans, no custom versions of
programs. Another example: "M"ale and "F"emale may not be inclusive in
today's world; defining and validating additional values becomes easier
when it's a configuration change and not a programming change.

Again: this is a programmer's tool...but I have added a provision to allow
certain users access to certain keys. The freight claims folks often want
to maintain their item category list and giving power users in that
department the ability to tweak their list empowered them and removed a
stream of small tasks from the development team's to-do list.

While you can accomplish quite a lot with the "one size fits all data"
approach, there are some "simple" data types that are too complex for the
system reference structure. My table of shipment delivery status codes
(delivered okay, delivered short, delivered over, etc.) is an example of
data that could fit into the system reference file world but it would be
messy. Each delivery status code has values to indicate the delivered/not
delivered status, reporting requirements, EDI status, and EDI reason
codes. That table and its varying data required a dedicated maintenance
program.