MMCC PL/B Program Organization

MMCC's PL/B notes

Notes home

Intro

History

Article index

MMCC Standards

v1.10

Mid-Michigan Computer Consultants, Inc.
509 Center
Bay City, Michigan
Sales (989) 892-9242 Support (989) 686-8860

ANSI Standard PL/B Language
MMCC Programming Standards

NOTE TO OUR READERS This web resource is written for our own use. But we feel strongly that the PL/B language should be shared with the software community. So feel free to use this at will! BUT PLEASE... if you find errors or omissions or have a better way to do something. TELL US! Dialog helps us all. Send e-mail to: support@mmcctech.com

Back to Standards Index

PL/B PROGRAM ORGANIZATION

Every MMCC program has a similar organization. Understanding this general consistency makes it easier to maintain programs that one is not familiar with or has not worked on in years.

The standards now in use have been used since the early 1980's. Every effort has been made to insure that old programs do not break as new standards are added. That has the less desirable effect of sometimes making new programs look archaic or causing them to use an older form that could be done better with newer forms. We accept that as a necessary evil.

This article includes the following topics:

Program structure
Standard include modules
Field Name conventions

Back to Standards Index

PROGRAM STRUCTURE

The typical MMCC PL/B program organization is:
.......................................... . program name date written . . general description of what it does . TRAPTIME EQU 0 General EQU's for special routines. OLDSTUFF EQU 0 (more described below) GHCCOMMON EQU 0 . INCLUDE Z:COMMON Standard include units INCLUDE REVISION.DBS (more described below) INCLUDE PLBEQU.INC INCLUDE PLBMETH.INC INCLUDE Z:PRINT-WK . Local "working storage" items and variables . MAIN_FORM PLFORM xxxxxx ... other plforms here . ALIO EQU 0 File equate list CFIO EQU 1 (more described below) HCIO EQU 2 XCIO EQU 3 . INCLUDE xxxxIOFD.pls File descriptions for ALL files . INCLUDE Z:DATEGREG Date routines . INCLUDE xxxxOPEN file opening routines . ....................... . Program initialization Mainline calls to processing sub-routines end of job wrapup MOVE CURRPROG, PRIORPG MOVE NEXTPROT, CURRPROG CHAIN CURRPROG . ....................... . Processing sub-routines . ....................... . INCLUDE xxxxIO.pls standard I/O routines INCLUDE Z:TRAPNEW.PLS INCLUDE Z:GO-SLOW.PLS INCLUDE xxxx other general purpose routines. . ....................... .pagehead INCLUDE Z:PRINT-DO .... program specific page headings RETURN . ....................... . print_do_trailer .... program specific page bottom if needed RETURN
Each of the above items is defined below.

Top lines: general description of what it does.

We always start by giving the name of the program and the date it was written. This is followed by at least a short description of the program. Often that's a one-liner. Many times it's paragraphs of documentation:

...................................................
. FM-X1240                                      10/09/2003
.           FORMAT 2 LISTING VIEWER
.                 Browser Style
.                    LOADMOD
.   This program does.....
.

General EQU's for special routines.

MMCC PL/B programs take advantage of the compiler's "conditional" statements to control what appears in a program. Typically the program will have structures like:

   %IF  OLDSTUFF > 0
      old code that's left in for example
   %ENDIF

There are a number of standard EQU's which apprear in almost all programs. The most frequently used are listed below and then described:

    INC_PLBWIN_WORK EQU    1
    COLOR_PLS       EQU   1
    TRAPTIME        EQU  0     ;throwback to old DOS "TRAPNEW" include
    OLDSTUFF        EQU  0     ;
    EXAMPLE         EQU  0

INC_PLBWIN_WORK tells the COMMONWK routine if we need all the PLBWIN work areas. The old DOS programs don't need those and to have them in a program waste space in that old, memory sensitive environment.

This INC_PLBWIN_WORK equate is normally found in the PRIVCOM include unit. Common storage can't be used in "loadmods" (separately compiled sub routines) so the EQU will be seen in loadmod programs.

COLOR_PLS tells the COLORWIN.PLS include unit to CREATE a group of standard color objects. Some programs do this in their own code, or they are old DOS programs and can't create colors. This equate allows one to turn off the CREATEs yet keep the include of COLORWIN.PLS in the program.

This COLOR_PLS equate is normally found in the PRIVCOM include unit. Common storage can't be used in "loadmods" (separately compiled sub routines) so the EQU will be seen in loadmod programs.

TRAPTIME is a throwback to the earliest DOS programs. It tells the TRAPSET routine, which is called before every KEYIN instruction, to display the current time at the top of the screen. We keep it so that old programs won't break, but for years it's been set to ZERO.

OLDSTUFF / EXAMPLE are used to "comment out" old code and example code within the program. For example, one might want to drop an old routine from the program but not physically delete it. By putting a %IF enclosure around the code, it effectively goes away but is still there for reference. By the same token, we sometimes pull in a pile of code from another program and just use it as an example for cutting and pasting. We use EXAMPLE to "comment out" this code:

   %IF  OLDSTUFF > 0
      .... old code
   %ENDIF

STANDARD INCLUDE UNITS:

MMCC PL/B programs are heavy users of "INCLUDE" units. These are pre-written blocks of code which are read into the source by the compiler when an INCLUDE directive is encountered.

INCLUDE units may be nested, and we do a lot of that.

The MMCC INCLUDE units typically use the %IF compiler directives to selectively exclude some code. This allows a universal include unit to be tailored for a specific program's requirements.

INCLUDE Z:COMMON A single COMMON storage definition is used for every MMCC system. This include unit is stored in the central SUNDB folder.

There are actually TWO common units, one for PLBWIN and one for the older DOS style SUNDBSYS programs. The two routines are almost identical but there are some very minor differences.
- COMMON.pls is used for PLBWIN programs.
- COMMON.dbs is used for DOS PL/B programs.
We normally do not enter the extension when coding these include units. The SUNDB86A compiler for DOS defaults to the .DBS file extension for includes. The PLBWIN compiler uses .PLS file extensions. This means that the correct include unit is used automatically by the compiler. The same program could be compiled under either compiler and the correct include would be used.

The COMMON include unit defines the base common storage items. These are available to every program in the system. When the first program loads it is designated the "master" for the session. COMMON storage items are automatically initialized. From that point on, they are visible to all programs that load and can be changed by any program.

NOTE Common storage is a memory mapped structure. When the first program in a session loads it initializes common memory. That block is not released or changed until the entire session ends. Each subsequent program in the session must have been compiled with exactly the same common memory definition. If any program differs you get a run-time error.

The effective result of this is twofold. First the INCLUDE unit insures that common is the same in every program. Second, it means that if the common unit changes, then EVERY program must be re-compiled.

The COMMON include unit does nested includes of two more standard code units:
PRIVCOM
The COMMON unit resides in the SUNDB folder and is the same for every MMCC system. This is boog, but we found we needed some way to have different common storage in certain systems. Point of Sale might need something that Dental does not.

The PRIVCOM inlude unit is the answer. It allows individual systems to append additional common storage items to the standard common items. All common storage must be defined at the top of the program. Having COMMON include PRIVCOM keeps all the common items together. Because it's also the first item in every program, common is preserved and protected in all programs within a system.
COMMONWK
Besides common storage items, there are many working areas that are useful in almost all of our programs. Some things are as simple as the variable ONE which is just the number one. Others include SPACE and SPACES, and the large string TITLE_LINE.

Z:COMMONWK defines all of these commonly used data variables and constants. They are not in common storage, but are just part of the user data area of memory.

The COMMONWK unit is found in the SUNDB folder so the same common work items are available to every program and every system.

COMMONWK.PLS is a PLS unit. Both COMMON.DBS and COMMON.PLS include COMMONWK.PLS using the full name. This allows us to have a single unit which is included in all programs.
INC_PLBWIN_WORK EQU
Old DOS programs do not have a large UDA (User Data Area). It was easy to run out of RAM in DOS programs. PLBWIN, on the other hand, has lots of UDA memory!

The COMMONWK unit uses a %IF compiler directive to selectively exclude variables which have evolved in the Windows era from the old DOS programs. The EQU is defined in the COMMON.DBS and COMMON.PLS units.

For normal programs it is not necessary to define the INC_PLBWIN_WORK equate since it's in the COMMON unit. "Loadmods" (separately compiled programs) are not allowed to define or acccess common storage so they do not include the COMMON unit. Therefore they must define the INC_PLBWIN_WORK explictely.
Back to
Standards Index
INCLUDE REVISION.dbs
In the early days of the DOS PL/B compiler, there was no way to get at the date and time that a compile was done.

We wanted to have a revision date which could be shown on screen. To acomplish that, we wrote a little PL/B program which would get the system time stamp and write it into a tiny include unit called REVISION.DBS.

This little REVDATE program was built into the standard compile batch file so that it would run before every compile. The program being compiled would then include the new REVISION.DBS file which would give it the timestampl of when the complile was run. This data is shown on the top of the screen by every program!

(Note that the PLBWIN compiler saves the timestamp and a number of other interesting items in the compiled program and makes that data available to the program. We continue to use the REVDATE item because it's in so many programs!)

Back to Standards Index
INCLUDE PLBEQU.inc
PLBEQU.inc is an include unit provided with the PLBWIN compiler. It resides in the folder with the other distribution items. Besides containing many useful equates, it also contains a great deal of PLBWIN documentation as comments. We include this in most programs.

Back to Standards Index
INCLUDE PLBMETH.inc
PLBMETH.inc is an include unit provided with the PLBWIN compiler. It resides in the folder with the other distribution items. Besides containing many useful method definitions and code, it also contains a great deal of PLBWIN documentation as comments. We include this in most programs.

Back to Standards Index
Local "working storage" items and variables
Every program is built around its own set of variables. This part of each program is unique to the needs of that program.

Because many of our programs are cloned from other, similar programs, many variables have a generally consistent definition and form. But we enforce no rules in this area.

Back to Standards Index
PLFORMs
PLFORMS are the definition of screen "forms" as defined by the Sunbelt "Forms Designer" and the PLBWIN IDE environment. We generally include the PLFORMs in the same area in the program.

See the section on forms handling for information on how we work with forms.

Back to Standards Index
FILE EQUATE list before the xxxxIOFD include.
INCLUDE xxxxIOFD.pls at the end of the user data area.
INCLUDE xxxxOPEN in the initialization area.
INCLUDE xxxxIO at the end of the program.

The file equates identify how each of the system's data files are to be used.
- EQU 0 the file is not used.
- EQU 1 Just include the file description, but no processing
- EQU 2 Open the file for READ mode and include READ routines.
- EQU 3 Open the file for SHARE mode and include all I/O routines.
The entire file handling process is defined in the I/O coding standards page.

Back to Standards Index
INCLUDE DATEGREG.PLS
general date processing routine.

Back to Standards Index
Program initialization
Mainline which calls processing sub-routines
Processing sub-routines

Back to Standards Index
INCLUDE TRAPNEW.PLS routine.

Back to Standards Index
INCLUDE GO-SLOW.PLS routine.

Back to Standards Index
Include other general purpose routines.

Back to Standards Index

STANDARD INCLUDE MODULES

FIELD NAME CONVENTIONS

CONTENTS

v1.10

Send e-mail to MMCC.

Write to MMCC Technical Support at:
MMCC, Inc.
600 W. Midland
Bay City, MI 48708
(989) 686-8860
| Home |
© 2003 MMCC, Inc. All Rights Reserved.
Report problems or suggestions to support@mmcctech.com
Started 06/20/2003