ANSI Standard PL/B Language and Visual PL/B

MMCC Programming Standards

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
  • Z:COMMONWK.PLS
  
  
  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

---

v1.10