View
223
Download
2
Category
Preview:
Citation preview
8/3/2019 Progress Programming Standards
1/74
FAST 4GL SYSTEMS, INC.
Corporate Technical Documentation
Progress
Coding
Version
1
8/3/2019 Progress Programming Standards
2/74
StandardsManual
2
8/3/2019 Progress Programming Standards
3/74
CORPORATE TECHNICAL DOCUMENTATION
Progress Coding Standards Manual
Fast 4GL Systems, Inc.http://www.fast4gl.com/220 White Horse Pike Audubon, NJ 08106
Phone +1 877 327-8445 Fax +1 609 547-7876By: Christopher Schreiber
(chris@fast4gl.com)
Thanks to all that contributed their knowledge to the creationof this document. I would especially like to thank Donald Christie (don@cat-it.co.nz)
from Catalyst IT Limited (http://www.cat-it.co.nz)
http://www.fast4gl.com/mailto:chris@fast4gl.commailto:don@cat-it.co.nzhttp://www.cat-it.co.nz/http://www.fast4gl.com/mailto:chris@fast4gl.commailto:don@cat-it.co.nzhttp://www.cat-it.co.nz/8/3/2019 Progress Programming Standards
4/74
Table of Contents
Document Overview...............................................................................................iv
This Manual is intended to..........................................................................................iv
This Manual is not intended to.....................................................................................v
Database Design Considerations............................................................................v
Definition............................................................................................................... ........v
Tables (or Files)...........................................................................................................vii
Fields (or Columns)...................................................................................................viii
Indexes.................................................................................................................. .........x
Referential Integrity....................................................................................................xi
Naming Conventions............................................................................................xii
General Naming Conventions....................................................................................xii
Procedures...................................................................................................................xii
Variables.....................................................................................................................xivWidgets........................................................................................................................xv
Frames................................................................................................................... .....xvi
Buffers.........................................................................................................................xvi
Streams.......................................................................................................................xvi
Blocks.........................................................................................................................xvii
Workfiles and Temp Tables......................................................................................xix
External References................................................................................................. ...xx
Procedure Structure.............................................................................................xx
General Outline...........................................................................................................xx
Program Header............................................................................................. ..........xxii
Variables...................................................................................................................xxiii
Other Defines.............................................................................................................xxv
iProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
5/74
Forms........................................................................................................................xxvi
Startup Routines........................................................................................... ..........xxvii
Procedure Style.................................................................................................xxvii
Indentation..............................................................................................................xxvii
Statements Per Line.................................................................................................xxix
Capitalization......................................................................................................... ..xxix
Block Labels................................................................................................. ............xxix
Punctuation...............................................................................................................xxix
Comments............................................................................................................... ...xxx
Dictionary Formats and Labels...............................................................................xxxi
Include Files.............................................................................................................xxxii
If / Then / Else........................................................................................... .............xxxiv
Case Statement......................................................................................................xxxvii
Program Exits.......................................................................................... .............xxxvii
Listing Field Names.............................................................................................xxxviii
Listing Format Phrase Options.............................................................................xxxix
Listing Frame Phrase Options........................................................................... ...xxxix
Keywords to Not Use....................................................................................................xl
Keywords to Avoid.......................................................................................................xl
Abbreviations..............................................................................................................xli
Miscellaneous.............................................................................................................xlii
Frames..................................................................................................................... ..xliv
Transactions............................................................................................................. ..xlv
Error Handling...........................................................................................................xlv
Record Reading.........................................................................................................xlvi
Record Locking..............................................................................................................l
Portability.................................................................................................................l
Terminals........................................................................................................................l
Names.................................................................................................................. .........lii
Workfiles................................................................................................................... ...lii
Operating Systems......................................................................................................liii
Color......................................................................................................................... ...liii
Operating System Specific............................................................................ .............liii
Performance..........................................................................................................liv
iiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
6/74
Coding Techniques......................................................................................................liv
Multi-Database....................................................................................................lvii
Using Multiple Databases..........................................................................................lvii
Understanding Transactions..............................................................................lviii
Transaction Scope Overview....................................................................................lviii
Default Block Scope....................................................................................................lix
Controlling Transactions............................................................................................lxi
Sub-transactions............................................................................................... ........lxiii
Record Locks and Scope.....................................................................................lxiv
Record Locks.............................................................................................................lxiv
Record Scope..............................................................................................................lxv
Using XREF and Listings................................................................................lxviii
Listings............................................................................................................... .....lxviii
XREF.................................................................................................................. ........lxx
ii iProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
7/74
Document OverviewThese are the reasons why this ProgressCoding Standards Manual was created.
In order to ease Progress program readability and futuremaintenance, it is important to identify and encourage aconsistent coding style. This document does not attempt toaddress every possible issue because our experience has shown
us that the longer the standard is the less compliance there is.We don't expect everyone to agree with the standards outlinedhere. However, these are the standards and guidelines that comefrom years of experience and should not be deviated from, exceptunder special situations.
No document of this nature should ever be written in a vacuum.We would encourage you let us know of any omissions and weakspots that we can make the necessary changes and help othersget off to a good start in their Progress applications.
This Manual is intended to Set design and programming standards for Progress
programmers
Provide guidelines for team and project leaders during codereviews
It should be a straightforward matter to apply the standards setforth here to all new programs. The aim is to introduce anefficient style of coding that will improve readability, maintenanceand performance.
ivProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
1
I C O N K E Y
Valuableinformation
Notes and
comments
Progress code
Other
references
8/3/2019 Progress Programming Standards
8/74
This Manual is not intended to
Teach anyone how to program in Progress.
This document does not suggest any standard or style forSmartobjects and GUI programming in general. It covers thedevelopment of 4GL code and data dictionary only.
Database Design
ConsiderationsProper Database Design and Namingconventions are probably the mostimportant part of the applicationdevelopment process.
In order for Progress code to be easily readable and maintainable,extensive forethought must go into the design and naming
conventions for the database itself.
Definition
Foreign key fields have the same field name as they do in their original table.
Duplicate field names should not be used except where a foreign key is being
defined.
With field and table names, underscores (_) not hyphens (-) should be used to
avoid potential problems with third party SQL implementations.
Field level help should be entered.
Table and field descriptions should be entered.
Default field formats are entered.
There should always be one unique primary index per table.
vProgress Coding Standards Manual Fast 4GL Systems, Inc.
Entering all the
informa
tioncorrectl
y in the
data
dictiona
ry will
lead to
not
having
to
override
these in
allprocedu
res.
D E F I N I T I O N
Chapter
2
8/3/2019 Progress Programming Standards
9/74
The field that repeats the most should be the first component followed by the next
most repeating field. This makes searching much more efficient and helps with
index compression (note: the most repeating field is the one whose value changes
the least over multiple records!).
Do not add or delete fields / tables / indices without carrying out impact analysis
to anticipate all the effects of the change.
viProgress Coding Standards Manual Fast 4GL Systems, Inc.
Using a cross-
referen
ce tool
such as
Roundta
ble, can
ease
applicat
ion
develop
ment.
8/3/2019 Progress Programming Standards
10/74
Tables (or Files)
If DOS compatibility is desired, file names should be limited to8 characters even though Progress allows 32. This restriction islifted in Progress Version 6 with the addition of an 8 character"dump" name to the dictionary.
Another reason to keep file names short is that Progress storesthese names literally in the compiled R-code. Therefore, longnames have a direct impact on R-code size. This also appliesto field, variable, and workfile names.
Use include files for the dictionary deletion validation. Thisallows the deletion criteria to be changed even if a databasemay be in use by other users. Simply edit the include file andrecompile the affected procedures.
viiProgress Coding Standards Manual Fast 4GL Systems, Inc.
T A B L E
N A
M I
N G
Even though table
names
should
be kept
as short
as
possible
, they
should
also be
long
enough
to be
easily
underst
ood
8/3/2019 Progress Programming Standards
11/74
Fields (or Columns)
It is recommended that field names be limited to 12characters, even though Progress allows 32.
Be aware of the limitations of using the RECID datatype.During a data dump using EXPORT, Progress converts theRECID to the unknown value (?) . Using stored RECIDsnormally requires the developer to write custom dump andload procedures.
For DECIMAL fields, the number of decimals stored shouldmatch, or exceed the number of decimals displayed in theformat.
The use ofSIDE-LABELS will cause DECIMAL fields using theformatting ">" character to lose decimal alignment depending
upon the size of the number displayed (even if the format isthe same size). Therefore, the use of the "z" formattingcharacter is recommended.
The formats for logical data types should always have thepositive format on the left and the negative on the right. Aformat of "No/Yes" could cause severe logic problems.
For character field formats, avoid using the "!" and "9"formatting characters unless a character MUST be enteredbecause Progress does not allow a blank or non-alphabetic
character when using this format.
The length of a label should be limited to 14 so that the labelwill not be truncated when displaying WITH 1 COLUMN or WITH2 COLUMNS. If 3 or 4 COLUMNS are used frequently, the labelshould not exceed 12 characters.
Column-Labels should be the same width or less than theformat of the field to act as a "short label" for tight reports andscreens. If screen space is limited don't stack column labelsmore than 2 levels deep.
viiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
F I E L D N A M I N G
Make sure to
always
note,
and
change
if
needed,
thenumber
of
decimal
s
stored.
This is
separat
e from
the
display
format.
Avoid using ! and
9
formatti
ng,
since
these
force
the user
to enter
a
specific
value.
It is
better
to use a
flexible
format,
and
validate
this.
8/3/2019 Progress Programming Standards
12/74
Avoid using the unknown value (?) as an initial value exceptfor dates. In numeric fields, calculations involving theunknown value usually result in an unknown result.
Example
UPDATE qty price. /* user enters 5 and ? */ASSIGN total = qty * price. /* total now equals ? */
The initial value for a logical field should always be yes or no.Consider the following:
Example
Format: N/G
Label: Net or GrossInitial: N
The "N" in Initial might lead the uninitiated into believing that thedefault is going the be "Net" when actually it will default to alogical No or "G" for "Gross".
Mandatory should generally be set to YES for fields where theunknown value might cause a problem. This is to prevent thelogical data corruption described in the previous example.
Progress does not check the syntax of a validation expression
until a procedure is compiled that utilizes that expression.Whenever a valexp is entered or modified, upon exiting thedictionary test the validation by using:
Example
INSERT customer.
This will check the syntax of all validation expressions in the file.Also remember that the dictionary validation only applies to data entrystatements (UPDATE, SET and PROMPT-FOR).
ixProgress Coding Standards Manual Fast 4GL Systems, Inc.
Always check for
the
unknown value
(?) as
this can
cause
unexpe
cted
results.
When defining
logical
fields,
list
positivevalue
first,
then the
negativ
e. The
field
should
be
named
after
the
positiveconditio
n.
Always check data
dictiona
ry
validati
on after
making
any
change
s.
8/3/2019 Progress Programming Standards
13/74
Indexes
The primary index should be the index that is used most oftenfor traversing a file with a FOR EACH, not the index mainly usedfor random access. This will cause the data to be dumped inthat order. When the data is subsequently reloaded into a newdatabase, the RECIDs are assigned sequentially to the recordsduring the load. When the primary index is built, it will bebuild with references to these sequential recids. All otherindexes for that will be built with the recids in non-sequentialorder.
Character index components should be defined as Abbreviateset to 'yes' (unless the component is not the last component ofthe index). This will allow the use of a PROMPT-FOR / FINDUSING combination without using the BEGINS function.
Do not create indexes that share the same components.
Example
Index-A Index-BField-A Field-AField-B Field-BField-C
Index-A would be considered redundant in this example, unless if Index-A was unique and Index-B was not.
It is recommended that index names be limited to 12characters.
xProgress Coding Standards Manual Fast 4GL Systems, Inc.
I N D E X N A M I N G
Never create an
index
just
becaus
e it
might
be
needed
in the
future.
Beforecreating
any
index,
determi
ne what
you
needs
are.
8/3/2019 Progress Programming Standards
14/74
Referential IntegrityReferential integrity means ensuring that all foreign keys fieldscan be resolved to a valid entry in an associated table.
This implies that when these foreign key fields are populated acheck must be made to ensure the valid entry exists. If an entry
is deleted then a check should be made for entries in any tablethat may use its fields as foreign keys. If such relations exist thenthe deletion should be disallowed.
Typically referential integrity checks must be put in place when:
a value is input to a foreign key field during user interaction
an entry is written to the database
an entry is being deleted
Referential integrity can carried out in three places, the datadictionary, database triggers (CREATE, FIND, ASSIGN, WRITE andDELETE) and the application code itself.
Use the DELETE trigger to enforce deletion integrity and audit andthe WRITE trigger for audit.
xiProgress Coding Standards Manual Fast 4GL Systems, Inc.
R E F E R E N T I A L
I N T
E G
R I T
Y
Using triggers can
make
sure
Referen
tial
Integrit
y is
always
maintai
ned.
8/3/2019 Progress Programming Standards
15/74
Naming ConventionsFollowing basic Naming Conventions willgreatly enhance code readability.
In order to ease Progress program readability and futuremaintenance, it is important to identify and encourage aconsistent coding style. This document does not attempt toaddress every possible issue because our experience has shown
us that the longer the standard is the less compliance there is.
We don't expect everyone to agree with the standards outlinedhere. However, these are the standards and guidelines that comefrom years of experience and should not be deviated from, exceptunder special situations.
General Naming Conventions
All PROGRESS reserved words must be entirely in upper case.Other programming entities, such as variable names, will useeither lower case or a mixture of upper and lower case, as
described below for various specific instances. For thoseinstances not discussed below, all lower case is the preferredoption.
Field and Table names will commence with an upper caseletter, and will use lower case letters for the remainder ofsingle word names. For multiple word names, each of thewords will be separated by the underscore (_) character andeach word will start with an upper case letter.
Procedures
If compatibility with Progress conventions is desired, thefollowing file name extensions should be used:
File Name Extensions
xi iProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
3
G E N E R A L
N A
M I
N G
C O
N V
E N
T I O
N S
P R O C E D U R E S
Follow the
Progres
s
standar
d
filenam
es of
.p, .i
and.w.
8/3/2019 Progress Programming Standards
16/74
.p Procedure
.i Include File
.w Window
xiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
17/74
Variables
To distinguish variables from database fields, it isrecommended that a prefix or suffix be used to set the actualname off. This makes it much easier for the maintenanceprogrammer to track variables through a chain of procedures.If the variable is defined LIKE a field, the field name should becontained in the variable name.
Variable Naming
DEFINE VARIABLE vDate AS DATE NO-UNDO.DEFINE VARIABLE vItem_no LIKE Item.Item_no NO-UNDO.DEFINE INPUT PARAMETER ipUpdate AS LOGICAL NO-UNDO.DEFINE SHARED VARIABLE sGLCode AS CHARACTER NO-UNDO.DEFINE GLOBAL SHARED VARIABLE gsCompany AS INTEGER NO-UNDO.
Because Version 6 allows the construct db.file.field, it isrecommended that database names and file/buffers names bedistinct to prevent confusion over database.file and file.field.
xivProgress Coding Standards Manual Fast 4GL Systems, Inc.
V A R I A B L E S
Always prefix
variable
names
with an
identific
ation of
what
type of
variable
you aredefining
.
8/3/2019 Progress Programming Standards
18/74
Widgets
A number of other widgets are available in V7&V8. Thenaming conventions for these should be the same as for fieldand file names but with a prefix indicating what type of objectis being referred to. These are as follows:
Widget Naming
br Browsequ Querycb Combo Boxed Editor Boxtg Toggle Boxrs Radio Setsl Selection List
Widget Examples
DEFINE QUERY quOffice_Header FOR Office_Header.
DEFINE BROWSE brOffice_Header QUERY quOffice_HeaderDISPLAY Office_Header.Office_Number
Office_Header.Office_TypeWITH TITLE Select a Office 8 DOWN.
DEFINE VARIABLE cbHist_Date AS DATE FORMAT 99/99/9999VIEW-AS COMBO-BOXLIST-ITEMS 04/07/1066, 20/01/1966/27/10/1991.
xvProgress Coding Standards Manual Fast 4GL Systems, Inc.
W I D G E T S
8/3/2019 Progress Programming Standards
19/74
Frames
As with variables, frame names should also have a prefix orsuffix to set them off. In addition the frame should beidentified by type (local or shared). In multi-screenconversations, the frame may also need to be numbered.
Frame Naming
DEFINE FRAME fMain.
Buffers
Buffers should also have a suffix/prefix and be identified asshared or local. The database file name that the bufferrepresents should be contained in the name.
Buffer Naming
DEFINE BUFFER bCustomer FOR Customer.
Streams
Streams should have a suffix or prefix.
Stream Naming
DEFINE STREAM sReport.
xviProgress Coding Standards Manual Fast 4GL Systems, Inc.
F R A M E S
B U F F E R S
S T R E A M S
8/3/2019 Progress Programming Standards
20/74
Blocks
Block labels are to be on a separate line above the blockstatement.
Block Labels
MAIN-LOOP:REPEAT:
DISPLAY Customer.Name.END. /* MAIN-LOOP: */
Block labels should have a suffix or prefix and give someindication as to the nesting level of the block being labeled.
Block Label Names
MAIN-LOOP:REPEAT:
/* user interaction */TRANS-LOOP:
/* update transaction */END. /* TRANS-LOOP: */
END. /* MAIN-LOOP: */
xviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
B L O C K S
All large blocks
should
be
named
for
easier
readabil
ity.
8/3/2019 Progress Programming Standards
21/74
Labeled blocks should have the block label as a comment nextto the END statement for the block, include the colon in theblock label for quick/easy access to the beginning and endingof the block.
Block Label Comments
MAIN-LOOP:DO:
/* block code here */END. /* MAIN-LOOP: */
Progress allows duplicate block labels in the same procedure,however, this practice is discouraged because of the potentialfor confusion.
xviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
Always comment
theend.
stateme
nt with
the
block
label, so
finding
the
ending
to a
block of
code iseasier.
8/3/2019 Progress Programming Standards
22/74
Workfiles and Temp Tables
To distinguish workfiles from database fields, a prefix shouldbe used. If the workfile represents a dictionary file, the workfilename should contain the dictionary file name. This will make iteasier to locate when doing text searches.
Workfile and Temp Table Naming
DEFINE TEMP-TABLE ttCustomer LIKE Customer.DEFINE WORKFILE wfCustomer LIKE Customer.
When an index consists of only one field, the name of theindex should be the same as the field.
When an index has more than one component, the index
should attempt to paraphrase the fields used in the index.
Index Naming
Index Name: cust-ord
Index containing cust-num and ord-no fields.
xixProgress Coding Standards Manual Fast 4GL Systems, Inc.
W O R K F I L E S
A N
D
T E
M P
T A
B L
E S
8/3/2019 Progress Programming Standards
23/74
External References
When Progress output is directed to an ASCII file, the followingnaming conventions should apply.
For portability, the file name should not exceed 8 characterswith a 3 character suffix.
To prevent collisions with other users who may also be writingASCII files to disk, one of the following conventions can beused:
Write to the user's home directory or specially designatedtemporary directory.
Make the name of the file unique. Usually the ETIME functionwith a tie breaker such as USERID is sufficient to prevent nameconflicts.
Use a .d suffix for files that contain EXPORTed data.
Procedure StructureFollowing these Procedure Structure guidelineswill allow for being able to track the programsflow more easily.
General OutlineThe general outline or flow of a program should be as follows:
General Outline
1. Header
2. Variables
xxProgress Coding Standards Manual Fast 4GL Systems, Inc.
E X T E R N A L
R E
F E
R E
N C
E SAlways keep in
mind to
code
and test
for all
deploye
d
platfor
ms, and
minimiz
e
operatin
g
system
calls.
Chapter
4
G E N E R A L
P R
O C
E D
U R
E
O U
T L I
N E
8/3/2019 Progress Programming Standards
24/74
3. Other Definitions
4. Forms
5. Procedure Body
6. Exit Point
xxiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
25/74
Program HeaderThe header of each program shall be organized as follows:
Program Header
1. Program Name
2. Application Name / Module
3. Program Location / Directory
4. Copyright notice
5. Modification History / Revisions / Initials / Date
6. Reasons for each change
7. Include file list
8. Files read (Input)
9. Files written (Output)
10. Purpose and general description of program
xxiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
P R O G R A M
H E
A D
E R
8/3/2019 Progress Programming Standards
26/74
VariablesVariable should be arranged in the following order:
Variables
System wide include file variables.Application specific include file variables.new global sharednew sharedsharedlocal
Variables should be listed alphabetically to make locating them easier.
All variables, workfiles, and define parameters should bedefined as no-undo. All exceptions must be commented toavoid future changes that will cause problems.
Variables should always be defined LIKE file.field-namewhenever appropriate for self-documentation and ease ofmaintenance. One possible disadvantage is that LIKE requiresthat a session be connected to the appropriate database.
Variables should not have the same name as a database fieldor a database (Version 6) for clarity.
All NEW SHARED/SHARED variables should be stored in includefiles passing NEW as a parameter in the procedure where
initially defined. This will make maintenance easier and alsoprevent problems with conflicts in DATATYPE, NO-UNDO,EXTENT, etc.
xxiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
V A R I A B L E S
Almost all
variable
s should
be
defined
as NO-
UNDO
to
reduce
writes
to the
local
before-
image
file and
enhanc
e
perform
ance.
Use shared
variable
s
sparingl
y. All
shared
variable
s should
be in
include
files.
8/3/2019 Progress Programming Standards
27/74
When defining variables, all definition options should bealigned for readability.
Variable Alignment
DEFINE VARIABLE vName AS CHARACTER FORMAT x(10)LABEL Name NO-UNDO.DEFINE VARIABLE vKey AS INTEGER FORMAT zz9 NO-UNDO.
No variables should be defined in a statement other than aDEFINE statement. Progress allows variable definitions inDISPLAY, UPDATE, FORM and other data handling statements,but they are difficult to locate and maintain when DEFINEd inthis way.
xxivProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
28/74
Other DefinesOther definitions will be described in the following order:
Other Defines
1. new global shared stream
2. new shared stream
3. shared stream
4. stream
5. new shared buffer
6. shared buffer
7. buffer
8. new shared workfile
9. shared workfile
10. workfile
11. new shared frame
12. shared frame
13. input parameter
14. output parameter
15. input-output parameter
xxvProgress Coding Standards Manual Fast 4GL Systems, Inc.
O T H E R
D E
F I N
E S
8/3/2019 Progress Programming Standards
29/74
FormsForms definitions will be listed in the following order:
Forms
1. New shared frame include file forms
2. Shared frame include file forms
3. Include file forms
4. Local forms
All FRAME Phrase options associated with a frame should belisted only on the FORM statement for ease of maintenance.
All forms described in a program should be given explicitframe names. This is particularly important when FORMs areplaced at the beginning of a procedure, scoping them to theprocedure block.
xxviProgress Coding Standards Manual Fast 4GL Systems, Inc.
F O R M S
8/3/2019 Progress Programming Standards
30/74
Startup Routines
Any include file startup routines such as screen headings andsecurity checks should be listed together.
Variable initialization should also done in this section. ExitPoint:
All procedures should have a common exit point. This isusually a RETURN statement on the last line of the procedure.A RETURN anywhere else in the procedure is similar to a GOTO
statement in another language. The only difference is thatRETURN can only go back to the calling procedure.
This exit point should also be used to HIDE any frames that donot need to be visible when returning to the calling procedureand initialize any shared variables that need to be.
Procedure StyleProcedure Style is unique to each programmer.However, following these suggestions will allowthe programs that you write to be more easilymaintained.
Indentation
Recommended indentation is 3 spaces.
When the level of block nesting gets to the point where linesare being "broken" prematurely, 2 space indentation isallowed, although this can be a symptom of poor programdesign.
All statements contained within a block must be indented:
xxviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
S T A R T U P
R O
U T I
N E
S
Chapter
5
I N D E N T A T I O N
Properly indented
code is
easier
to read
and
maintai
n.
8/3/2019 Progress Programming Standards
31/74
Indentation Example
MAIN-BLOCK:FOR EACH Customer:
DISPLAY Customer.ORDER-BLOCK:
FOR EACH Order WHEREOrder.Cust_Num = Customer.Cust_NumNO-LOCK:
DISPLAY Order.END. /* ORDER-BLOCK: */
END. /* MAIN-BLOCK: */
END statements will always line up with the block statementthey are ending.
xxviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
32/74
Statements Per Line
Only one statement per line is allowed for readability.
A statement may not be extended by use of the tilde (~).
Capitalization
All code will be in lower case with the exception of the blocklabels and text inside a comment.
Block Labels
Major REPEAT and FOR EACH blocks should be preceded with ablock label that describes the function of the block.
The label should be on a line by itself above the block header(see preceding example).
DO blocks only require labels when they are used for somepurpose other than grouping statements together such asdefining a new frame or changing transaction scope; or whenthey are more than 10-12 lines long.
Any block that is subject to a NEXT, LEAVE, or UNDO statementmust have a block label. The NEXT, LEAVE, or UNDO statementshould explicitly reference that label.
Punctuation
All Progress statements are terminated with periods exceptblock labels and block headers (REPEAT/FOR/DO) which areterminated with a colon.
xxixProgress Coding Standards Manual Fast 4GL Systems, Inc.
S T A T E M E N T S
P E
R
L I N
E
C A P I T A L I Z A -
T I O
N
B L O C K L A B E L S
P U N C T U A T I O N
8/3/2019 Progress Programming Standards
33/74
Comments
All block headers (FOR EACH/REPEAT) should be preceded witha comment describing the purpose of the block, especially ifthat block is a transaction block.
All END statements for blocks should be followed with acomment that "matches" the END to the block headerstatement. The only exceptions would be blocks that containvery few statements
Comments Example
/* Update Customer Records */CUST-UPDATE-BLOCK:REPEAT:
PROMPT-FOR Customer.Cust_Num.FIND Customer USING Customer.Cust_Num.UPDATE Customer WITH 1 COLUMN.
END. /* CUST-UPDATE-BLOCK: */
Multi-line comments should be in the form:
Multi-Line Comments Example
/* This line is the first comments line** and this is the second line */
Single-line comments should be in the form:
Single-Line Comments Example
/* This is a one line comment */
No need to comment the END statement:
No need to Comment the END
IF true-condition THENDO:
MESSAGE True .END.
xxxProgress Coding Standards Manual Fast 4GL Systems, Inc.
C O M M E N T S
Proper and
extensi
ve
comme
nts will
help in
docume
nting
and
reading
code.
This will
allow
for
easier
mainten
ance
and
debuggi
ng later
on.
8/3/2019 Progress Programming Standards
34/74
Dictionary Formats and Labels
Labels, formats, validation and help from the dictionary shouldbe used rather than overriding in the procedure.
When overriding dictionary labels, do so on the FORM or DEFINEFRAME statement if one is being used to define the frame.
For variables specify LABEL and FORMAT in the DEFINE or FORMstatement rather than on data handling statements such asDISPLAY and UPDATE.
Use LABEL when defining side-labels and COLUMN-LABEL whendefining column labels. Keep the width of the COLUMN-LABELthe same as the FORMAT.
Column-Label Example
LastDate Last DateInvoiced Last Date Invoiced Invoiced-------- ------------------ ---------12/31/99 12/31/99 12/31/99
In this example, Last!Date!Invoiced may be the best for theconvservation of horizontial space at the cost of one line of verticalspace.
xxxiProgress Coding Standards Manual Fast 4GL Systems, Inc.
D I C T I O N A R Y
F O
R M
A T
S
A N
D
L A
B E
L S
8/3/2019 Progress Programming Standards
35/74
Include Files
When overriding dictionary labels, do so on the FORM or DEFINEFRAME statement if one is being used to define the frame.
Use system include files whenever possible.
System include files used across multiple applications arelocated in the "include" directory.
Application specific include files are located in thatapplication's subdirectory (e.g. ar/).
Named parameters rather than positional parameters will beused whenever parameters need to be passed to an includefile.
It is recommended that include files not be nested more than 3
levels deep as debugging can be difficult. Also the "explosion"of the include files seen when using the COMPILE/LISTINGoption makes the code difficult to read.
Include file coding style, simple includes:
Simple Include Files
{std-var.i}
Include file coding style, simple parameters:
Simple Parameter Include Files
{std-var.i &var-type = NEW}
Include file coding style, multiple parameters:
Multiple Parameter Include Files
{ lookup.i&file-name = Customer&frame-attr = NO-BOX 2 COLUMNS&key = Customer.Cust_Num
}
xxxiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
I N C L U D E
F I L
E S
Using named
paramet
ers,
such as
{&file}
, areeasier
to
debug
then
using
position
al
paramet
ers,
such as
{1}.
8/3/2019 Progress Programming Standards
36/74
Include files should not terminate a block started outside ofthe include file. Conversely, an include file should not start ablock that ends outside of the include file.
Do not hardcode a path name into the include file reference.PROPATH can be used (and dynamically adjusted as
necessary) to change the directories at compile time.
Do not put comments within curly brackets of an include filecall, as the compiler tends to get confused.
Do NOT Use Comments Within an Include File Reference
{ lookup.i /* This may blow up! */¶m = value
}
xxxiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
Never hardcode
OS
specificpath
names
into any
program
or
include.
8/3/2019 Progress Programming Standards
37/74
If / Then / Else
The use ofNOT should be avoided. Good style dictates testinga positive condition whenever possible. Okay to use whentesting logical functions and variables.
Mixed AND and OR conditions should be avoided, but if used theorder of evaluation should be explicitly noted through the useof parentheses. Put each condition on a separate line aligningthe AND/ORs vertically.
Mixed AND / OR Conditions Example
IF true-cond1 ANDtrue-cond2 AND(true-cond3 ORtrue-cond4) THEN
For a group of conditions connected by AND, the most unlikelycondition(s) should be tested first.
For a group of conditions connected by OR, the most likelycondition(s) should be tested first.
xxxivProgress Coding Standards Manual Fast 4GL Systems, Inc.
I F T H E N E L S E
S T
A T
E M
E N
T S
Instead of using a
nested
IF/THEN
/ELSE
stateme
nt,
conside
r usingthe
CASE
stateme
nt.
8/3/2019 Progress Programming Standards
38/74
Every branch of an IF/THEN/ELSE will use a DO block to enclosethe code even if there is only one statement. The cost is aslight increase in R-code size. This will prevent errors if otherstatements are added to the branch later on.
Example of when to use DO: END. with an IF Statement
IF true-condition THEN {include.i}.
If this include file originally had only one statement and more wereadded later, the new statement would not be conditionally executed.Instead you should use:
IF true-condition THENDO:
{include.i}END.
The only exception would be a nested IF/THEN/ELSE whenthere was only one possible statement.
Example of when not to use DO: END. with an IF Statement
IF selection = A THEN RUN add.p.ELSEIF selection = C THEN RUN change.p.ELSEIF selection = D THEN RUN delete.p.
xxxvProgress Coding Standards Manual Fast 4GL Systems, Inc.
Always place a
DO/ENDblock
around
any
include
file
referen
ce.
8/3/2019 Progress Programming Standards
39/74
ELSE statements should appear on separate lines, aligned withthe IF statements to which they apply.
For compound tests, align the ORs and ANDs.
Compound AND / OR Example
IF condition ANDvBegDate > Order.Order_Date ANDvEndDate < Order.Order_Date THEN
DO:/* Statements */
END.
When testing logical fields or variables, do not use TRUE,FALSE, YES, and NO for comparisons because of reducedperformance and larger R-code.
Use the Progress CASE statement (V7) when ever possible. If itis necessary to use nested IF statements, use the followingconstructs:
Multiple IF / THEN / ELSE Example
IF condition ANDvBegDate > Order.Order_Date ANDvEndDate < Order.Order_Date THEN
DO:/* Statements */
END.ELSEIF NOT (condition) THENDO:
/* Statements */END.
The use of "null" THENs and ELSEs is not allowed.
Null THEN / ELSE Example
IF condition THEN . ELSE .
This code does compile and illustrates what a null THEN or ELSE is.
xxxviProgress Coding Standards Manual Fast 4GL Systems, Inc.
Never use null
THEN/E
LSE
stateme
nts,
whichcan
lead to
confusi
on.
8/3/2019 Progress Programming Standards
40/74
Case Statement
In Version 7 Progress use the CASE statement, instead ofnested IF/THEN/ELSE statements.
Example of the CASE statement
CASE selectionWHEN A THEN RUN add.p.WHEN C THEN RUN change.p.WHEN D THEN RUN delete.p.OTHERWISE MESSAGE Incorrect Selection..
END CASE.
Program Exits
All procedures should have a single exit point. The laststatement of every program should be a RETURN and this
should be the only RETURN used in a program. To "goto" aRETURN from within the program, use the LEAVE statement.
Example of Program Exits
MAIN:REPEAT:
PROMPT-FOR Customer.Cust_Num.FIND Customer USING Customer.Cust_Num NO-ERROR.IF NOT(AVAILABLE(Customer)) THEN LEAVE MAIN.UPDATE Customer WITH 2 COLUMNS.
END. /* MAIN */RETURN.
xxxviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
C A S E
S T
A T
E M
E N
T
P R O G R A M
E X I
T S
8/3/2019 Progress Programming Standards
41/74
Listing Field Names
All field names should be "qualified" and typed in asfilename.field-name.
If common file names are used between multiple databases,the convention dbname.filename.fieldname should be used.
Lists of field names in a DISPLAY, UPDATE, FORM, etc. shouldbe shown as follows:
All names can fit all on one line:
Example of Fields on one line
DISPLAY Customer.Cust_Num Customer.Name.
Multi-line listing: One field per line indented 3 spaces. Also ifthe FRAME Phrase is used, it will be aligned with thefields/variables.
Example of Fields on multiple lines
UPDATECustomer.Cust_NumCustomer.NameCustomer.AddressCustomer.Phone
WITH FRAME fCustFrame.
When displaying a subset of an array, use the followingnotation:
Example of Using an Array
DISPLAY array[1 FOR 5].
This method is easier to read and maintain than listing out eachindividual array element.
xxxviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
L I S T I N G F I E L D
N A
M E
S
Listing field names
verticall
y eases
readabil
ity and
makes
it
simple
to add
or
delete
fields
later.
8/3/2019 Progress Programming Standards
42/74
Listing Format Phrase Options
When FORMAT Phrase options are used, they should bealigned vertically or horizontally.
Example of Format Phrase Options
UPDATECustomer.Name
HELP Enter Customer NameVALIDATE (Customer.Name NE ,Customer Name Must Be Entered)
Customer.ContactAT 20HELP Enter Customer Contact.
UPDATEvStartDate AT 10 HELP Enter Start DatevEndDate AT 50 HELP Enter Ending Date
UPDATECustomer.Name HELP Enter Customer Name
VALIDATE (Customer.Name NE ,Error)
Customer.Contact AT 20HELP Enter Customer Contact.
Listing Frame Phrase Options
Arrange frame phrase options in a manner that avoidsplacement of two integers together for different options.
Example of Frame Phrase Options to Avoid
UPDATECustomer.NameCustomer.PhoneWITH RETAIN 1 8 DOWN ROW 2 2 COLUMNS.
Example of Frame Phrase Options Preferred
UPDATECustomer.NameCustomer.PhoneWITH 2 COLUMNS 8 DOWN ROW 2 RETAIN 1.
xxxixProgress Coding Standards Manual Fast 4GL Systems, Inc.
L I S T I N G
F O
R M
A T
P H
R A
S E
O P
T I O
N S
L I S T I N G
F R
A M
E
P H
R A
S E
O P
T I O
N S
8/3/2019 Progress Programming Standards
43/74
Keywords to Not Use
STOP statement: Useful for testing only.
USE-INDEX option: Essentially hard-codes an index name into aprocedure. Don't use unless knowledge of data distributionshows that Progress' automatic index selection will beincorrect. Should never be used in Version 7 Progress.
Keywords to Avoid
OF: OF makes code easier to read, but hides the name of thefield(s) being used to relate the files together. Ok to use whenthere are no further qualifications necessary for recordselection. Do not use OF and WHERE together.
ENTERED function: The ENTERED flag is easily cleared by anUNDO, RETRY and could lead to incorrect results.
RELEASE statement: Use of this statement within aTRANSACTION might indicate a lack of understanding recordand/or transaction scope. RELEASE cannot release SHARE-LOCKor EXCLUSIVE-LOCKs within a transaction.
OR operator: Use in a WHERE clause can negate the efficient useof an index.
xlProgress Coding Standards Manual Fast 4GL Systems, Inc.
K E Y W O R D S
N O
T
T O
U S
E
K E Y W O R D S T O
A V
O I D
Using RELEASE
inside
of a
transac
tion will
not
release
the lock
on the
record.
8/3/2019 Progress Programming Standards
44/74
Abbreviations
The abbreviation of variables, file and field names is notallowed.
The following keywords should not be abbreviated, becausethe minimum allowed abbreviation is too short:
Keywords to NOT Abbreviate
ACCUMULATEAVAILABLEAVERAGEALL COLORS (BLACK, BLUE, CYAN, ETC.)BLINKDATELIGHTNO-VALIDATEPROMPT-FORRECID
SUB-AVERAGETRANSACTIONUNDERLINE
The following keywords may be abbreviated, but not as muchas Progress allows:
Keywords that can be Abbreviated
KEYWORD ALLOWEDCHARACTER CHAR
DECIMAL DECDESCENDING DESCENDINTEGER INTLOGICAL LOG
All other Progress supported abbreviations are allowed.
xl iProgress Coding Standards Manual Fast 4GL Systems, Inc.
A B B R E V I A -
T I O
N S
8/3/2019 Progress Programming Standards
45/74
Miscellaneous
Hard coding of values into any program is discouraged withthe following exceptions: Parameters passed to an include fileand unchanging constants (e.g. 12 months in a year).
Do not hardcode keylabels into a procedure.
Example of Coding Keylabels
MESSAGE Enter Data and Press + KBLABEL(GO).
Long MESSAGEs that will not fit on one line should be coded:
Example of Long Messages
MESSAGE This is a very long message that will not fit on oneline in the code. .
Note in the preceding example that the message string isdelimited with a blank on each end. This suggestion alsopertains to TITLEs.
Example of Titles
FORMCustomer.Cust_NumCustomer.NameWITH TITLE Customer Information CENTERED.
xliiProgress Coding Standards Manual Fast 4GL Systems, Inc.
M I S C E L L A N -
E O
U S
8/3/2019 Progress Programming Standards
46/74
Algebraic style logical operators are preferred over theFORTRAN style. Either style is acceptable.
Example of Operators
Preferred Instead Ofa b a NE ba = b a GE ba > b a GT ba < b a LT ba = b a EQ b
When using DO WHILE/REPEAT WHILE loops, always test for a"less than" or "greater than" condition rather than "equal to".This prevents infinite looping if the "equal to" condition isnever met.
Example of an Acceptable Check
TEST-BLOCK:DO WHILE TRUE:
/* statements */IF vCounter
8/3/2019 Progress Programming Standards
47/74
TRIM character field sensitive to leading blanks (i.e. sort fields).
The fields in a FORM statement should be listed vertically oneper line for ease of maintenance.
Example of a Form Statement
FORMCustomer.Cust_NumCustomer.NameCustomer.PhoneWITH CENTERED ROW 2.
Example of an Unacceptable Form Statement
FORM Customer.Cust_Num Customer.Name Customer.Phone WITH CENTERED.
Frames
Frames should be standardized using the default box or NO-BOX. Frames used for printed output should use NO-BOX torecover the blank line (and columns) that Progress allocatesfor the "invisible" graphics box at the top of the frame.
For standardized frame widths on reports, use standardWIDTHs that match the characters per inch normally used onthe printer:
Frame Widths
10 CPI: 75/12512 CPI: 90/140etc.
Avoid widths that exceed 132 columns particularly becausethis compromises the ability for a user to send a wide report totheir terminal (using the TERMINAL statement) withoutwrapping. In addition, it means that there is not need tosupport condensed/compressed print for a potentially varietyof printers.
To make maximum use of paper, but still leave an adequatemargin, use PAGE-SIZE 60.
xlivProgress Coding Standards Manual Fast 4GL Systems, Inc.
F R A M E S
8/3/2019 Progress Programming Standards
48/74
Transactions
Block headers that define a transaction should explicitly usethe TRANSACTION keyword for self-documentation. This willallow the compiler to catch possible transaction errors.
Error Handling A Progress error (e.g. entering a duplicate key into a unique
index) should not send the user back to the beginning of theblock which is the Progress default (UNDO, RETRY). Instead,more localized DO ON ERROR blocks along with NEXT-PROMPTshould be used to keep the cursor on the field where the erroroccurred.
The UNDO statement should never be used without a RETRY,NEXT, LEAVE or RETURN even though Progress allows it. Alwaysfollow the UNDO with the appropriate action (NEXT, LEAVE,
RETRY, RETURN) and a label if appropriate. Although Progressallows the use of RETURN, as stated earlier this is to beavoided.
xlvProgress Coding Standards Manual Fast 4GL Systems, Inc.
T R A N S -
A C
T I O
N S
E R R O R
H A
N D
L I N
G
8/3/2019 Progress Programming Standards
49/74
Record Reading
Always use WHERE instead ofOF so that whoever is looking atthe code always knows which fields are being used to join files,unless there are no further conditions necessary for recordselection. Do not use OF and WHERE together.
Example of Acceptable Record Reading
ORDER-BLOCK:FOR EACH Order WHERE
Order.Cust_Num = 1000NO-LOCK:
DISPLAYOrder.Cust_NumOrder.Ord_Num.
ITEM-BLOCK:FOR EACH Order_Line
OF OrderNO-LOCK:
DISPLAYOrder_Line.Order_Line_NumOrder_Line.Item_Num.
END. /* ITEM-BLOCK: */END. /* ORDER-BLOCK: */
Example of Unacceptable Record Reading
ORDER-BLOCK:FOR EACH Order WHERE
Order.Cust_Num = 1000NO-LOCK:
DISPLAYOrder.Cust_NumOrder.Ord_Num.
ITEM-BLOCK:FOR EACH Order_Line
OF Order WHEREOrder_Line.Order_Qty > 0NO-LOCK:
DISPLAYOrder_Line.Order_Line_NumOrder_Line.Item_Num.
END. /* ITEM-BLOCK: */END. /* ORDER-BLOCK: */
xlviProgress Coding Standards Manual Fast 4GL Systems, Inc.
R E C O R D
R E
A D I
N G
8/3/2019 Progress Programming Standards
50/74
USING may be used instead ofWHERE because USING specifiesthe key being used.
For good style the left side of the comparison in a WHERE clausewill always be the field used to retrieve the record.
Example of a Where Clause
FIND Customer WHERE Customer.Cust_Num = 10.
Instead of:
FIND Customer WHERE 10 = Customer.Cust_Num.
If the transaction level and framing support it, all relatedrecords should be found in a single FOR EACH statement.
Example of a Compound FOR EACH Statement
FOR EACH Customer NO-LOCK,EACH Order NO-LOCK WHERE
Order.Cust_Num = Customer.Cust_Num,EACH Order_Line NO-LOCK WHERE
Order_Line.Order_Num = Order.Ord_Num:END.
xlviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
51/74
When there are multiple conditions in the WHERE clause, usethe following form (note the indentation):
Example of Multiple Condition WHERE Clause
Example 1:
FOR EACH Customer WHERECustomer.Cust_Num > 10 ANDCustomer.Cust_Num < 100 ANDCustomer.State = MA
NO-LOCK:END.
Example 2:
FOR EACH Customer NO-LOCK WHERECustomer.Cust_Num > 10 ANDCustomer.Cust_Num < 100 ANDCustomer.State = MA,
EACH Order NO-LOCK WHEREOrder.Cust_Num = Customer.Cust_Num AND
Order.Order_Num > 100BREAKBY Order.Order_DateBY Customer.Name:
END.
When retrieving one-to-one relationship records in a FORstatement, the EACH should be used in case the record ismissing. If there is a possibility that a record could be missing,it should be trapped using FIND/NO-ERROR and the AVAILABLEfunction.
When a PROMPT-FOR is followed by a FIND, use NO-ERROR onthe FIND statement unless you wish to use the Progressdefault error handling (an error message followed by UNDO,RETRY of the closest UNDO block). FIND/NO-ERROR will alwaysbe followed by a test with the AVAILABLE function.
FIND/NO-WAIT will always be followed by a test with theLOCKED function.
xlviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
52/74
The order of comparisons in a WHERE clause should follow thishierarchy:
Order of Comparisons in a WHERE Clause
1. Fields of the index being used by the FIND/FOR EACH statement.The comparisons should be in the same order as the fields occur inthe index.
2. Fields from indexes not being used by the FIND/FOR EACH.
3. Non-indexed fields.
4. Variables.
5. Expressions.
Do not use a FIND statement on a non-unique index or when
all of the components of a unique index are not supplied. FINDis designed to retrieve a single record based upon uniqueindex information. Use FIND FIRST/NEXT/PREY/LAST for allother situations.
Do not use a FOR block when retrieving a single record basedupon a one-to-one relationship.
Do Not Use a Join for a one-to-one Relationship
FOR EACH Order_Line:DISPLAY Order_Line.FOR EACH Item OF Order_Line:
DISPLAY Item.END.
END.
The use of FOR EACH when retrieving the item misleads one into thinkingthat the order-line: item relationship is one-to-many rather than one-to-one.
When testing logical fields or variables in a WHERE clause,explicitly test against the implicit true or false value of the field
for R-code and performance reasons.
xlixProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
53/74
Record Locking
Use NO-LOCK whenever the state of the information is notimportant (e.g. most inquiries and reports) to reducecontention and improve performance.
When it is reasonably certain that a user will be updating anexisting record and that record will not cause lockingcontention, read the record EXCLUSIVE-LOCK. This will reducethe potential for deadly embrace as well as offer a smallperformance gain.
SHARE-LOCK should never be used. With SHARE-LOCK thepossibility always exists that deadly embraces, or deadlock,might occur.
Always explicitly state the lock status. The use of the -NLstartup option is forbidden.
PortabilitySince Progress programs can be deployed onmany different platforms, it is important to keepsome of these Portability issues in mind when
programming.
Terminals
Because the possibility exists that Progress may be run using
terminals with a varying number of available lines (25 for DOS,24 for most ASCII terminals), use the following functions tocalculate the available lines and make maximum use of theavailable screen space.
lProgress Coding Standards Manual Fast 4GL Systems, Inc.
R E C O R D
L O
C K I
N G
Chapter
6
T E R M I N A L S
8/3/2019 Progress Programming Standards
54/74
Screen Checking Functions
SCREEN-LINESFRAME-DOWNFRAME-ROWFRAME-LINE
In the Frame Phrase:
expression DOWNROW expression
The same situation exists with space taking and non-spacetaking terminals. To take maximum advantage of availablescreen space and still maintain portability, the following isrecommended:
All frames with data entry or using color attributes will be useATTR-SPACE in the Frame Phrase for that frame.
All procedures will be compiled with the NO-ATTR-SPACEoption.
liProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
55/74
Names
If DOS compatibility is needed, the following items will belimited to 8 characters in length.
DOS Limitations
File NamesProcedure NamesInclude File Names
Name suffixes are limited to 3 characters.
The period "." may not be used in the body of the name, butonly to separate the procedure or include name from thesuffix.
All procedure and include file names should be in lower case.
Workfiles
On 640K DOS machines, there is very little memory availableto allocate to local buffer space (the -l parameter). The 64Kbarrier on local buffer size on DOS machines affects portabilitywhen large numbers of workfile records might be created.Because of this, the use of workfiles is discouraged unless bothof the following conditions are met:
The number of workfile records created will remain static ornot exceed a predetermined "high water mark".
The workfile records will not be increased in size duringexecution of the procedure.
li iProgress Coding Standards Manual Fast 4GL Systems, Inc.
N A M E S
W O R K F I L E S
8/3/2019 Progress Programming Standards
56/74
Operating Systems
Use the OPSYS function to shield operating system calls.
Checking for the Operating System Example
CASE OPSYSWHEN unix THEN UNIX.WHEN msdos THEN DOS.WHEN vms THEN VMS.WHEN btos THEN BTOS.WHEN os2 THEN OS2.WHEN os400 THEN OS400.WHEN nt THEN NT.OTHERWISEMESSAGE Unknown Operating System: OPSYS.
END CASE.
Color
Use the COLOR VALUE (color-variable) in all frame phrases. Aninstallation that starts with monochrome monitors and thenmigrates to color can easily take advantage of the color if thecoding is done in this style.
Operating System Specific
OUTPUT THRU is very useful and powerful, but is not supportedon all Progress platforms.
AUTO-RETURN should never be used.
When a transaction completes, the user should be informedwith a message that the transaction has successfully finishedand been committed to the database.
Warning messages should be preceded with "WARNING:"
Error messages should be preceded with "ERROR:". Thisincludes the valmsg in the dictionary as well as the secondargument of the VALIDATE format phrase option.
All error messages should be accompanied by an audible BELL.
Help messages should be preceded with "Enter".
Because the END-ERROR key has two possible actions thatmight be taken, the ambiguous nature of the key can confuseusers.
liiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
O P E R S T I N G
S Y
S T
E M
S
C O L O R
O P E R A T I N G
S Y
S T
E M
S P
E C I
F I C
8/3/2019 Progress Programming Standards
57/74
PerformanceAlthough Performance is often not the firstpriority when programming, it is important tokeep some of these basic concepts in mind.
Coding Techniques
CAN-FIND is more efficient than FIND because CAN-FIND only
looks at the index (usually 1 I/O operation) where FINDretrieves the entire record (minimum of 2 I/Os).
For the display of constant data, the construct:
Example of Displaying Constant Data
FORMThis is a constant stringWITH FRAME fTest.
VIEW FRAME fTest.
/* This is more efficient then: */
DISPLAY This is a constant string.
li vProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
7C O D I N G
T E
C H
N I Q
U E
S
8/3/2019 Progress Programming Standards
58/74
When there are more than 1 assignments next to each other,use the ASSIGN statement.
Example of the Assign Statement
ASSIGNvVar1 = vVar2vVar3 = vVar4.
/* This is more efficient, and produces smaller R-code then** the following: */
vVar1 = vVar2.vVar3 = vVar4.
Minimize RUN statements (use include files if possible) and usea fully qualified path name with a RUN statement. Only qualifythe path from the top directory of the application to allow
flexibility in a development/production environment.
Minimize calls to the operating system.
When sharing a record between programs, use SHAREDBUFFERs instead of passing a RECID with a shared variable.Exception: when reading the record NO-LOCK in the callingprocedure (no transaction active) and re-reading the recordEXCLUSIVE-LOCK in the sub-procedure to limit the transactionto the sub-procedure.
When a variable is changed in a transaction or sub-transactionthat variable and all other variables in that procedure arewritten to the local before image (.lbi) file. To reduce theoverhead of this journaling, define variables as NO-UNDO when:
When is use NO-UNDO Variables
1. The variable represents a constant that will never change.
2. The variable is always initialized before it is used.
3. UNDO processing serves no useful purpose.
4. The variable is changed in a loop that an error may not occurin.
lvProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
59/74
Reading a record NO-LOCK eliminates the need for Progress tocheck the locking table for a slight performance gain.
Read records EXCLUSIVE-LOCK instead of the default which is aSHARE-LOCK upgraded to an EXCLUSIVE-LOCK when the recordis updated.
For multiple string comparisons, use CAN-DO, LOOKUP or INDEXversus multiple comparisons ORed together.
Examples of CAN-DO and LOOKUP
CAN-DO(PA,NJ,DE,vState) /* This is the most effiecent */
LOOKUP(vState,PA,NJ,DE) 0
vState = PA OR vState = NJ OR vState = DE /* Do Not Use */
Reduce start/stop of transactions in a tight loop (e.g. batchcreation of a large number of records).
Example of Reducing Transactions
INPUT FROM datafile.REPEAT TRANSACTION:REPEAT vCounter = 1 TO 100:CREATE Customer.IMPORT Customer.
END.END.
/* Is more efficient then: */
INPUT FROM datafile.REPEAT:CREATE Customer.IMPORT Customer.
END.
lv iProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
60/74
When loading data into a database, use the NO-ECHO option onthe INPUTFROM statement.
When loading data into the database, use IMPORT (Version 6and later) rather than SET or UPDATE.
Only use WORKFILEs for a fixed number of static recordsCreating WORKFILE records in an unrestricted way can crashthe user by running out of local buffer (-l) memory. Also re-sizing existing WORKFILE records is a potential performance
inhibitor.
Multi-DatabaseWorking in a Multiple Database environmentcan bring up some more issues to beconcerned about.
Using Multiple Databases
Do not use the Progress Auto-Connect feature. It can causeunexpected pauses in a procedure as the connection isinitiated.
For modularity, put ail CONNECT logic at the start of the user'ssession.
Use NO-ERROR on the CONNECT and test to see if the connection
was established using the CONNECTED function.
Use one CONNECT statement per database. If a multi-databaseCONNECT fails, all subsequent connections will not beestablished.
lviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
8
U S I N G
M U
L T I
P L E
D A
T A
B A
S E
S
8/3/2019 Progress Programming Standards
61/74
Understanding TransactionsTransactions, and how Progress handles them,are often difficult but yet an important conceptfor programmers to grasp.
The manner in which Progress handles transactions is one of theunique and powerful features of the 4GL. It is also an area thatwe tend to struggle with usually because we imagine that the
subject is more complex than it is in reality.
This is an important subject, however, as with a little bad planningand careless programming it is possible to adversely anddangerous affect the behavior of your application from both auser interface point of view and a performance and "physical"database point of view.
Transaction Scope OverviewA transaction scope is logical grouping of changes being carriedout to data that Progress guarantees will either be committed as
a whole or UNDOne as a whole. Reasons for undoing a transactionwill range from a user deciding to abort the current set ofchanges (pressing F4 for example), to applications errors, tohardware failure.
Each completed transaction is guaranteed to have been writtenpermanently to the database whilst any incomplete transactionswill not be written to the database of they are interrupted.
If you are unsure whether a transaction is currently active in yourprogram use the TRANSACTION function which will return true if a
transaction is currently active.
lviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
9
T R A N S A C T I O N
S C
O P
E
O V
E R
V I E
W
8/3/2019 Progress Programming Standards
62/74
Default Block ScopeProgress code is structured in blocks. These take the form ofprocedures, triggers, DO blocks (including IF/THENDO), FOR EACHand REPEAT. Of these the procedures, triggers, FOR EACH, DO ONERROR and REPEAT will start a transation if there is a find with anEXCLUSIVE-LOCK in their block.
This meanes that should a change be made to the data or arecord found with an exclusive lock within these blocks, atransaction will be scoped to the bounds of those blocks.
DO blocks have weak transaction scoping. If a change to data ismade to a DO block then the transaction is scoped to the nextouter transaction block.
Example #1
REPEAT: /* transaction starts here *//* some code ....... */
FIND FIRST Order EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Order.
/* some code ....... */END. /*transaction ends here */
Example #2
REPEAT: /* transaction DOES NOT start here *//* some code ....... */REPEAT: /* transaction starts here */
FIND FIRST Order EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Order.
END. /* transaction ends here *//* some code ....... */
END. /* repeat */
li xProgress Coding Standards Manual Fast 4GL Systems, Inc.
D E F A U L T
B L
O C
K
S C
O P
E
8/3/2019 Progress Programming Standards
63/74
Example #3
REPEAT: /* transaction starts here *//* some code */DO WHILE TRUE:
FIND FIRST Order EXCLUSIVE-LOCK NO-WAIT NO-ERROR.
/* Check locked status ....... */UPDATE Order.
END. /* DO WHILE *//* some code ....... */
END. /*transaction ends here */
Example #4
/* start of a procedure transaction starts here */FIND FIRST Customer EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Customer.
/* Some code */
REPEAT:/* some code.... */FIND NEXT Order OF Customer EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Order./* some code.... */
END.
/*end of the procedure transaction ends here */
lxProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
64/74
Controlling TransactionsIt is possible to force any block to start a transaction by using theTRANSACTION keyword (note this differs from the TRANSACTIONfunction mentioned above).
This method can be used to both increase and decrease the size
of a transaction. Take Example 4 from above:
Example #4
/* start of a procedure transaction starts here */DO TRANSACTION: /* Transaction starts here */
FIND FIRST Customer EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Customer./* Some code */
END. /* Transaction ends here */
/* some code */
REPEAT:/* some code.... */DO TRANSACTION: /* Another Transaction starts here */
FIND NEXT Order OF Customer EXCLUSIVE-LOCK NO-WAIT NO-ERROR./* Check locked status ....... */UPDATE Order./* some code.... */
END. /* Second Transaction ends here */END.
/*end of the procedure */
The transactions in this example have now been scoped in a
much more granular fashion.
lx iProgress Coding Standards Manual Fast 4GL Systems, Inc.
C O N T R O L L I N G
T R
A N
S -
A C
T I O
N S
8/3/2019 Progress Programming Standards
65/74
You may want to increase the scope of a transaction boundary:
Example #5
DO TRANSACTION: /* Transaction starts here */FOR EACH Order EXCLUSIVE-LOCK:
DELETE Order.END.
END. /* Transaction End */
If a system crash occurs here none of the Order records will bedeleted. Of course this scenario also holds locks on all therecords until the end of the transaction.
lxiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
66/74
Sub-transactionsWith Progress it is only possible to have one active transaction ata time. If a transaction block becomes part of an existingtransaction it will form a sub-transaction.
Sub-transactions can be used to UNDO parts of a transaction,
however, the changes made in a sub-transaction do not getcommitted until the end of the main transaction.
One of the most common ways of starting a sub-transaction is bycalling another procedure whilst a transaction is active.
Example #6
DO TRANSACTION ON ERROR UNDO, RETRY: /* transaction starts here */IF RETRY THEN
MESSAGE "You've undone your customer changes as well."
IF NOT CAN-FIND Customer OF WHERE Customer-Name = "Test") THENRUN newcust.p.
FIND FIRST Order EXCLUSIVE-LOCK.UPDATE Order WITH 2 COLUMN.
END.
/**** newcust.p *****/* Program to add a new customer */
/* some code */
DO TRANSACTION ON-ERROR UNDO, LEAVE: /* start a sub transaction */FIND FIRST Customer EXCLUSIVE-LOCK.UPDATE Customer WITH 2 COLUMNS.
END. /* end a sub transaction */
The program newcust.p may not be expecting to be called withinanother transaction. Any update made in newcust.p can be rolledback in the calling routine if the user presses F4.
Another side effect of this scenario is that a lock will bemaintained on the Customer record until the end of the maintransaction in the calling procedure.
lxiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
S U B - T R A N S -
A C
T I O
N S
8/3/2019 Progress Programming Standards
67/74
Record Locks and ScopeUnderstanding Record Locking and RecordScope are essential in order to produce aneffective program design.
Record LocksProgress has row-level locking. This means it locks individualrecords at a time (as opposed to pages or tables).
Two types of lock are supported, they are the SHARE-LOCK andthe EXCLUSIVE-LOCK. In addition, Progress can read records withNO-LOCK.
A SHARE-LOCK allows a record to be read by more than one userso long as that record is not being modified. A SHARE-LOCK getsupgraded to an EXCLUSIVE-LOCK if the modification on thatrecord begins.
An EXCLUSIVE-LOCK prevents any other user modifying or placinga SHARE-LOCK on a record.
NO-LOCK allows the record to be read no matter what stateanother user has it in. It cannot however be modified. NO-LOCKallows dirty reads. In other words, the data that is being readmay not have been committed to the database.
The Progress default for a record is SHARE-LOCK as this providesthe user with the most protection. However, this option is notrecommended unless absolutely required. In general, the
developer should know what is going to happen to the record andread it with a NO-LOCK or an EXCLUSIVE-LOCK.
lxivProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
10R E C O R D
L O
C K
S
8/3/2019 Progress Programming Standards
68/74
Record ScopeThis subject relates to how long information in a Progress recordbuffer remains active and by association how long Progress keepsa lock on the record.
Record locks are held for the longest of the transaction scope or
record buffer scope. It is possible for a record buffer to have awider scope that the transaction scope.
Locks are held on a record not a buffer (remember it is possibleto have multiple buffers pointing to one record).
Example #7
FIND FIRST Customer./* Some code */
DO TRANSACTION: /* transaction start */UPDATE Customer WITH 2 COLUMNS.
END. /* transaction end */
/* Some code */PAUSE.
The record buffer spans the whole of this procedure, including thePAUSE statement. The first FIND will instigate a SHARE-LOCK onthe customer record.
When the DO TRANSACTION is encountered the SHARE-LOCK gets
upgraded to an EXCLUSIVE-LOCK. At the end of the transactionthe changes to the record are committed and the lock on therecord is down graded to a SHARED-LOCK.
Example #8
FIND FIRST Customer NO-LOCK./* Some code */
DO TRANSACTION: /* transaction starts */FIND FIRST Customer EXCLUSIVE-LOCK.UPDATE Customer WITH 2 COLUMNS.
END. /*SHARE-LOCK on Customer record is active */
Note that in the above example the lock status after the end ofthe transaction is still SHARE-LOCK. In other words, the record canonly be read not modified by another user in this state.
lxvProgress Coding Standards Manual Fast 4GL Systems, Inc.
R E C O R D
S C
O P
E
8/3/2019 Progress Programming Standards
69/74
Note that finding another record in the same table will release theSHARE-LOCK.
lxviProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
70/74
The RELEASE statement can also be used to clear out a recordbuffer and release the locks on that record at the end of thetransaction.
Example #9
FIND FIRST Customer NO-LOCK./* Some code */
DO TRANSACTION: /* transaction start */FIND FIRST Customer EXCLUSIVE-LOCK.UPDATE Customer WITH 2 COLUMNS.RELEASE Customer.
END. /* transaction end, No more locks held */
/* Some code */PAUSE.
In this example the lock is released at the end of the transactionbut the Customer buffer is no longer available.
RELEASE is a bit of a cop-out indicating a failure to properlycontrol your record and transaction scopes. In addition it behavesdifferently if it is used in a sub-procedure that has been calledwithin an existing record scope. In this case the lock is notreleased but downgraded to a SHARE-LOCK at the end of theprocedure.
Finally, it is possible to narrow (or increase) the scope of yourrecord by using the DO FORtablename construct. This strongly
scopes the record to the block. No references to the buffer canbe made outside the block without a subsequent FIND.
Example #10
DO TRANSACTION: /* transaction start */FIND FAST Customer EXCLUSIVE-LOCK.UPDATE Customer WITH 2 COLUMNS.RELEASE Customer.
END. /* transaction end, No more locks held */
IF AVAILABLE Customer THEN
MESSAGE "Customer record is available"
The free reference to Customer outside the transaction boundaryeffectively increase the scope of that record (but not thetransaction).
lxviiProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
71/74
The following example ensures that the record is not availableoutside the bounds of the transaction. In fact, it should notcompile.
Example #11
DO FOR Customer TRANSACTION: /* transaction start *?FIND FIRST Customer EXCLUSIVE-LOCK.UPDATE Customer WITH 2 COLUMNS.RELEASE Customer.
END. /* transaction end, No more locks held */
IF AVAILABLE Customer THENMESSAGE "Customer record is available".
Using XREF and ListingsUsing the Progress XREF and Listings compileroptions can give invaluable insight into a
program and are often useful in debugging.
When a program has been completed, it should be compiled toproduce two extra files. These are the LISTING file and the XREF(cross-reference) file. These files contain vital information, whichwill help ensure that your programs behave as expected. Usethese files to help with unit testing and code reviews.
ListingsThe listing file expands include files and numbers the programlines by block. At the end of the listing is a summary of eachblock within the procedure, the procedure itself being the mainblock.
The record buffers and transaction that are scoped to the blockare shown, as are the frame scopes.
lxviiiProgress Coding Standards Manual Fast 4GL Systems, Inc.
Chapter
11
L I S T I N G S
8/3/2019 Progress Programming Standards
72/74
Use the COMPILEfilename.pLISTINGfilename.lstoption form thePROGRESS editor of the Compile option in the ApplicationCompiler to produce the output file.
Example Listing
1 showlist.p23 {} Line Blk4 -- ---- ---5 1 1 DO FOR Account:6 2 2 DO TRANSACTION: /* start of a transaction */7 3 2 FIND FIRST account EXCLUSIVE-LOCK8 4 2 MESSAGE TRANSACTION. /* "yes" or "no" */9 5 2 PAUSE.10 6 1 END.11 7 112 8 2 REPEAT: /* start of a transaction */13 9 2 FIND FIRST policy_header EXCLUSIVE-LOCK.14 10 2 LEAVE.15 11 1 END.16 12 117 13 1 /* shows the transaction is complete */18 14 1 MESSAGE TRANSACTION.19 15 1 PAUSE20 16 END. /* DO FOR Account */21
23 File Name Line Blk Type Tran Blk. Label24 ---------- ---- ------------ ---- -------------------25 showlist.p 0 Procedure No26 showlist.p 1 Do No27 Buffers: policypl.Account2829 showlist.p 2 Do Yes30 showlist.p 8 Repeat Yes31 Buffers:policypl.Office_Header32
Each block start has been highlighted along with the lines ofinterest at the bottom of the report.
The above listing shows that the record buffer for Account is
scoped to the outer DO FOR Account: block. That there is notransaction scoped to this block. The inner DO TRANSACTIONblock has a transaction scoped to it.
The REPEAT block has both a record buffer (Office_Header) and atransaction scoped to it.
lxixProgress Coding Standards Manual Fast 4GL Systems, Inc.
8/3/2019 Progress Programming Standards
73/74
XREF The cross reference compile option writes cross referenceinformation between procedures and PROGRESS objects,including procedures, include files, tables, fields indices, variablesframes and character strings.
Developers must use this facility to check the efficiency of theirqueries. Whenever a query is used, a SEARCH entry will be madein the XREF file. This is followed by the table name and the nameof the index used to resolve the query. If the query isunbracketed (i.e. there are no criteria given to narrow down thesearch) or PROGRESS is unable to use an index to resolve thequery then the phrase WHOLE-INDEX appears after the indexname.
In the latter instance, the index name is the primary index, whichonly gives the order in which the records are returned. The rest
of the query will be resolved by searching through the wholetable. This scenario should be avoided.
Example Xref Program
FIND FIRST Account NO-LOCK. /* unbracketed search - no conditions */
/* this next one is bracketed by a non-indexed field */FIND FIRST Office_Header.
WHERE Office_Header.Effective_Date = TODAY NO-LOCK
/* this one is bracketed by a field indexed using a 2nd index */
FIND FIRST Office_Header.WHERE Office_Header.Account_No = Account.Account_No NO-LOCK.
lxxProgress Coding Standards Manual Fast 4GL Systems, Inc.
X R E F
8/3/2019 Progress Programming Standards
74/74
This produces a number of lines, for index usage look for lineswith SEARCH in them. As these XREF lines show:
Example Xref Output
Showref.p showxref.p 1 COMPILE showxref.pShowref.p showxref.p 1 SEARCH Account main_key WHOLE-INDEXShowref.p showxref.p 3 SEARCH Office_Header main_key WHOLE-INDEXShowref.p showxref.p 6 SEARCH Office_Header account
The second line relates to the unbracketed FIND statement, this isa valid scenario.
The third line shows a bracketed search (using Effective_Date)that cannot be resolved using an index. The primary index name(main_key) indicates the order in which the records will bereturned and the WHOLE-INDEX phrases indicates that the wholetable will have to be searched to resolve this query. This shouldbe considered a bug as it will cause severe performanceproblems.
The final highlighted line shows a bracketed query that has beenresolved using an index (account). This index was inspected andlooks suitable as Account_no (the bracketing field) is also the firstcomponent in that index.
Recommended