Progress Programming Standards

8/3/2019 Progress Programming Standards

1/74

FAST 4GL SYSTEMS, INC.

Corporate Technical Documentation

Progress

Coding

Version

1


2/74

StandardsManual

2


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

([email protected])

Thanks to all that contributed their knowledge to the creationof this document. I would especially like to thank Donald Christie ([email protected])

from Catalyst IT Limited (http://www.cat-it.co.nz)
http://www.fast4gl.com/mailto:[email protected]:[email protected]://www.cat-it.co.nz/http://www.fast4gl.com/mailto:[email protected]:[email protected]://www.cat-it.co.nz/


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.


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.


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.


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/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


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.


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


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.


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.


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.


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.


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.


16/74

.p Procedure

.i Include File

.w Window

xiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.


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

.


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


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


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.


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.


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


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


24/74

3. Other Definitions

4. Forms

5. Procedure Body

6. Exit Point

xxiProgress Coding Standards Manual Fast 4GL Systems, Inc.


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


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.


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.


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


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


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.


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.


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


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.


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


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}.


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! */&param = value

}

xxxiiiProgress Coding Standards Manual Fast 4GL Systems, Inc.

Never hardcode

OS

specificpath

names

into any

program

or

include.


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.


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.


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.


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


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.


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


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.


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


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


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


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


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


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


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.


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.


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.


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


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.


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


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


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


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.


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.


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


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


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


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.


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


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.


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


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


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


69/74

Note that finding another record in the same table will release theSHARE-LOCK.

lxviProgress Coding Standards Manual Fast 4GL Systems, Inc.


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.


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.


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.


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


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.


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


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.

Documents

Progress Programming Standards