progress Programming Coding Standards - Smart It€¦ · Web viewProgress Coding Standards Manual...

FAST 4GL SYSTEMS, INC.Corporate Technical Documentation

ProgressCoding

Version

1

Standards Manual

1

CORPORATE TECHNICAL DOCUMENTATION

Progress Coding Standards Manual

Fast 4GL Systems, Inc.http://www.fast4gl.com/

220 White Horse Pike • Audubon, NJ 08106Phone +1 877 327-8445 • Fax +1 609 547-7876

By: 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.cat-it.co.nz/

mailto:[email protected]

mailto:[email protected]

http://www.fast4gl.com/

Table of Contents

iProgress Coding Standards Manual Fast 4GL Systems, Inc.

Document Overview_____________0This Manual is intended to________0

This Manual is not intended to_____0

Database Design Considerations___0Definition______________________0

Tables (or Files)_________________0

Fields (or Columns)______________0

Indexes________________________0

Referential Integrity_____________0

Naming Conventions____________0General Naming Conventions_____0

Procedures_____________________0

Variables______________________0

Widgets________________________0

Frames________________________0

Buffers________________________0

Streams________________________0

Blocks_________________________0

Workfiles and Temp Tables_______0

External References_____________0

Procedure Structure_____________0General Outline_________________0

Program Header________________0

Variables______________________0

Other Defines___________________0

Forms_________________________0

Startup Routines________________0

Procedure Style________________0Indentation_____________________0

Statements Per Line_____________0

Capitalization___________________0

Block Labels____________________0

2Progress Coding Standards Manual Fast 4GL Systems, Inc.

Punctuation____________________0

Comments_____________________0

Dictionary Formats and Labels____0

Include Files____________________0

If / Then / Else__________________0

Case Statement_________________0

Program Exits__________________0

Listing Field Names______________0

Listing Format Phrase Options____0

Listing Frame Phrase Options_____0

Keywords to Not Use_____________0

Keywords to Avoid______________0

Abbreviations___________________0

Miscellaneous___________________0

Frames________________________0

Transactions____________________0

Error Handling_________________0

Record Reading_________________0

Record Locking_________________0

Portability_____________________0Terminals______________________0

Names_________________________0

Workfiles______________________0

Operating Systems_______________0

Color__________________________0

Operating System Specific________0

Performance___________________0Coding Techniques______________0

Multi-Database_________________0Using Multiple Databases_________0

Understanding Transactions______0Transaction Scope Overview______0


Default Block Scope_____________0

Controlling Transactions_________0

Sub-transactions________________0

Record Locks and Scope_________0Record Locks___________________0

Record Scope___________________0

Using XREF and Listings________0Listings________________________0

XREF_________________________0


Document OverviewThese are the reasons why this Progress Coding Standards Manual was created.

In order to ease Progress program readability and future maintenance, it is important to identify and encourage a consistent coding style. This document does not attempt to address 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 outlined here. However, these are the standards and guidelines that come from years of experience and should not be deviated from, except under 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 weak spots that we can make the necessary changes and help others get 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 code reviews

It should be a straightforward matter to apply the standards set forth here to all new programs. The aim is to introduce an efficient style of coding that will improve readability, maintenance and performance.


Chapter

1I C O N K E Y

Valuable information

Notes and comments

Progress code Other

references

This Manual is not intended to Teach anyone how to program in Progress.

This document does not suggest any standard or style for Smartobjects and GUI programming in general. It covers the development of 4GL code and data dictionary only.

Database Design ConsiderationsProper Database Design and Naming conventions are probably the most important part of the application development 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.


Chapter

2D E F I N I T I O N

Entering all the information correctly in the data dictionary will lead to not having to override these in all procedures.

Default field formats are entered.

There should always be one unique primary index per table.

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.


Using a cross-reference tool such as Roundtable, can ease application development.

Tables (or Files) If DOS compatibility is desired, file names should be limited

to 8 characters even though Progress allows 32. This restriction is lifted 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 stores these names literally in the compiled R-code. Therefore, long names have a direct impact on R-code size. This also applies to field, variable, and workfile names.

Use include files for the dictionary deletion validation. This allows the deletion criteria to be changed even if a database may be in use by other users. Simply edit the include file and recompile the affected procedures.


T A B L E N A M I N GEven though table names should be kept as short as possible, they should also be long enough to be easily understood

Fields (or Columns) It is recommended that field names be limited to 12

characters, even though Progress allows 32.

Be aware of the limitations of using the RECID datatype. During a data dump using EXPORT, Progress converts the RECID to the unknown value (?) . Using stored RECIDs normally requires the developer to write custom dump and load procedures.

For DECIMAL fields, the number of decimals stored should match, or exceed the number of decimals displayed in the format.

The use of SIDE-LABELS will cause DECIMAL fields using the formatting ">" character to lose decimal alignment depending upon the size of the number displayed (even if the format is the same size). Therefore, the use of the "z" formatting character is recommended.

The formats for logical data types should always have the positive format on the left and the negative on the right. A format of "No/Yes" could cause severe logic problems.

For character field formats, avoid using the "!" and "9" formatting characters unless a character MUST be entered because 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 label will not be truncated when displaying WITH 1 COLUMN or WITH 2 COLUMNS. If 3 or 4 COLUMNS are used frequently, the label should not exceed 12 characters.

Column-Labels should be the same width or less than the format of the field to act as a "short label" for tight reports and screens. If screen space is limited don't stack column labels more than 2 levels deep.


F I E L D N A M I N GMake sure to always note, and change if needed, the number of decimals stored. This is separate from the display format.

Avoid using “!” and “9” formatting, since these force the user to enter a specific value. It is better to use a flexible format, and validate this.

Avoid using the unknown value (?) as an initial value except for dates. In numeric fields, calculations involving the unknown 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/GLabel: Net or GrossInitial: N

The "N" in Initial might lead the uninitiated into believing that the default is going the be "Net" when actually it will default to a logical No or "G" for "Gross".

Mandatory should generally be set to YES for fields where the unknown value might cause a problem. This is to prevent the logical 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 the dictionary 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 entry statements (UPDATE, SET and PROMPT-FOR).


Always check for the unknown value (?) as this can cause unexpected results.

When defining logical fields, list positive value first, then the negative. The field should be named after the positive condition.

Always check data dictionary validation after making any changes.

Indexes The primary index should be the index that is used most often

for traversing a file with a FOR EACH, not the index mainly used for random access. This will cause the data to be dumped in that order. When the data is subsequently reloaded into a new database, the RECIDs are assigned sequentially to the records during the load. When the primary index is built, it will be build with references to these sequential recids. All other indexes for that will be built with the recids in non-sequential order.

Character index components should be defined as Abbreviate set to 'yes' (unless the component is not the last component of the index). This will allow the use of a PROMPT-FOR / FIND USING 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 12 characters.


I N D E X N A M I N GNever create an index “just because it might be needed in the future”. Before creating any index, determine what you needs are.

Referential IntegrityReferential integrity means ensuring that all foreign keys fields can be resolved to a valid entry in an associated table.

This implies that when these foreign key fields are populated a check must be made to ensure the valid entry exists. If an entry is deleted then a check should be made for entries in any table that may use its fields as foreign keys. If such relations exist then the 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 data dictionary, database triggers (CREATE, FIND, ASSIGN, WRITE and DELETE) and the application code itself.

Use the DELETE trigger to enforce deletion integrity and audit and the WRITE trigger for audit.


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 Referential Integrity is always maintained.

Naming ConventionsFollowing basic Naming Conventions will greatly enhance code readability.

In order to ease Progress program readability and future maintenance, it is important to identify and encourage a consistent coding style. This document does not attempt to address 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 outlined here. However, these are the standards and guidelines that come from years of experience and should not be deviated from, except under special situations.

General Naming Conventions All PROGRESS reserved words must be entirely in upper

case. Other programming entities, such as variable names, will use either lower case or a mixture of upper and lower case, as described below for various specific instances. For those instances not discussed below, all lower case is the preferred option.

Field and Table names will commence with an upper case letter, and will use lower case letters for the remainder of single word names. For multiple word names, each of the words will be separated by the underscore (‘_’) character and each word will start with an upper case letter.


Chapter

3G E N E R A L

N A M I N G

C O N V E N T I O N S

Procedures If compatibility with Progress conventions is desired, the

following file name extensions should be used:

File Name Extensions

.p Procedure

.i Include File

.w Window


P R O C E D U R E SFollow the Progress standard filenames of “.p”, “.i” and “.w”.

Variables To distinguish variables from database fields, it is

recommended that a prefix or suffix be used to set the actual name off. This makes it much easier for the maintenance programmer to track variables through a chain of procedures. If the variable is defined LIKE a field, the field name should be contained 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 is recommended that database names and file/buffers names be distinct to prevent confusion over database.file and file.field.


V A R I A B L E SAlways prefix variable names with an identification of what type of variable you are defining.

Widgets A number of other widgets are available in V7&V8. The

naming conventions for these should be the same as for field and file names but with a prefix indicating what type of object is 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_Header DISPLAY Office_Header.Office_Number Office_Header.Office_Type WITH TITLE “Select a Office” 8 DOWN.

DEFINE VARIABLE cbHist_Date AS DATE FORMAT “99/99/9999” VIEW-AS COMBO-BOX LIST-ITEMS 04/07/1066, 20/01/1966/27/10/1991.


W I D G E T S

Frames As with variables, frame names should also have a prefix or

suffix to set them off. In addition the frame should be identified by type (local or shared). In multi-screen conversations, the frame may also need to be numbered.

Frame Naming

DEFINE FRAME fMain.

Buffers Buffers should also have a suffix/prefix and be identified as

shared or local. The database file name that the buffer represents 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.


F R A M E SB U F F E R SS T R E A M S

Blocks Block labels are to be on a separate line above the block

statement.

Block Labels

MAIN-LOOP:REPEAT: DISPLAY Customer.Name.END. /* MAIN-LOOP: */

Block labels should have a suffix or prefix and give some indication 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: */


B L O C K SAll large blocks should be named for easier readability.

Labeled blocks should have the block label as a comment next to the END statement for the block, include the colon in the block label for quick/easy access to the beginning and ending of 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 potential for confusion.


Always comment the “end.” statement with the block label, so finding the ending to a block of code is easier.

Workfiles and Temp Tables To distinguish workfiles from database fields, a prefix should

be used. If the workfile represents a dictionary file, the workfile name should contain the dictionary file name. This will make it easier 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 the index 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.


W O R K F I L E S

A N D T E M P

T A B L E S

External References When Progress output is directed to an ASCII file, the

following naming conventions should apply.

For portability, the file name should not exceed 8 characters with a 3 character suffix.

To prevent collisions with other users who may also be writing ASCII files to disk, one of the following conventions can be used:

Write to the user's home directory or specially designated temporary directory.

Make the name of the file unique. Usually the ETIME function with a tie breaker such as USERID is sufficient to prevent name conflicts.

Use a .d suffix for files that contain EXPORTed data.

Procedure StructureFollowing these Procedure Structure guidelines will allow for being able to track the program’s flow more easily.

General OutlineThe general outline or flow of a program should be as follows:

General Outline


E X T E R N A L

R E F E R E N C E S

Always keep in mind to code and test for all deployed platforms, and minimize operating system calls. Chapter

4G E N E R A L

P R O C E D U R E

O U T L I N E

1. Header

2. Variables

3. Other Definitions

4. Forms

5. Procedure Body

6. Exit Point


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


P R O G R A M

H E A D E R

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 be defined as no-undo. All exceptions must be commented to avoid future changes that will cause problems.

Variables should always be defined LIKE file.field-name whenever appropriate for self-documentation and ease of maintenance. One possible disadvantage is that LIKE requires that a session be connected to the appropriate database.

Variables should not have the same name as a database field or a database (Version 6) for clarity.

All NEW SHARED/SHARED variables should be stored in include files passing NEW as a parameter in the procedure where initially defined. This will make maintenance easier and also prevent problems with conflicts in DATATYPE, NO-UNDO, EXTENT, etc.


V A R I A B L E SAlmost all variables should be defined as “NO-UNDO” to reduce writes to the local before-image file and enhance performance.

Use shared variables sparingly. All shared variables should be in include files.

When defining variables, all definition options should be aligned 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 a DEFINE statement. Progress allows variable definitions in DISPLAY, UPDATE, FORM and other data handling statements, but they are difficult to locate and maintain when DEFINEd in this way.


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


O T H E R D E F I N E S

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 be listed only on the FORM statement for ease of maintenance.

All forms described in a program should be given explicit frame names. This is particularly important when FORMs are placed at the beginning of a procedure, scoping them to the procedure block.


F O R M S

Startup Routines Any include file startup routines such as screen headings and

security checks should be listed together.

Variable initialization should also done in this section. Exit Point:

All procedures should have a common exit point. This is usually 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 that RETURN can only go back to the calling procedure.

This exit point should also be used to HIDE any frames that do not need to be visible when returning to the calling procedure and initialize any shared variables that need to be.

Procedure StyleProcedure Style is unique to each programmer. However, following these suggestions will allow the programs that you write to be more easily maintained.

Indentation Recommended indentation is 3 spaces.

When the level of block nesting gets to the point where lines are being "broken" prematurely, 2 space indentation is


S T A R T U P

R O U T I N E S

Chapter

5I N D E N T A T I O N

allowed, although this can be a symptom of poor program design.

All statements contained within a block must be indented:

Indentation Example

MAIN-BLOCK:FOR EACH Customer: DISPLAY Customer. ORDER-BLOCK: FOR EACH Order WHERE Order.Cust_Num = Customer.Cust_Num NO-LOCK: DISPLAY Order. END. /* ORDER-BLOCK: */END. /* MAIN-BLOCK: */

END statements will always line up with the block statement they are ending.


Properly indented code is easier to read and maintain.

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 block

labels and text inside a comment.

Block Labels Major REPEAT and FOR EACH blocks should be preceded with a

block 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 some purpose other than grouping statements together such as defining a new frame or changing transaction scope; or when they are more than 10-12 lines long.

Any block that is subject to a NEXT, LEAVE, or UNDO statement must have a block label. The NEXT, LEAVE, or UNDO statement should explicitly reference that label.

Punctuation All Progress statements are terminated with periods except

block labels and block headers (REPEAT/FOR/DO) which are terminated with a colon.


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 SP U N C T U A T I O N

Comments All block headers (FOR EACH/REPEAT) should be preceded with

a comment describing the purpose of the block, especially if that block is a transaction block.

All END statements for blocks should be followed with a comment that "matches" the END to the block header statement. The only exceptions would be blocks that contain very 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:


C O M M E N T SProper and extensive comments will help in documenting and reading code. This will allow for easier maintenance and debugging later on.

No need to Comment the END

IF true-condition THENDO: MESSAGE “ True “.END.


Dictionary Formats and Labels Labels, formats, validation and help from the dictionary

should be used rather than overriding in the procedure.

When overriding dictionary labels, do so on the FORM or DEFINE FRAME statement if one is being used to define the frame.

For variables specify LABEL and FORMAT in the DEFINE or FORM statement rather than on data handling statements such as DISPLAY and UPDATE.

Use LABEL when defining side-labels and COLUMN-LABEL when defining column labels. Keep the width of the COLUMN-LABEL the 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 the convservation of horizontial space at the cost of one line of vertical space.


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

Include Files When overriding dictionary labels, do so on the FORM or

DEFINE FRAME statement if one is being used to define the frame.

Use system include files whenever possible.

System include files used across multiple applications are located in the "include" directory.

Application specific include files are located in that application's subdirectory (e.g. ar/).

Named parameters rather than positional parameters will be used whenever parameters need to be passed to an include file.

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/LISTING option 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:


I N C L U D E F I L E SUsing named parameters, such as “{&file}”, are easier to debug then using positional parameters, such as “{1}”.

Multiple Parameter Include Files

{ lookup.i &file-name = Customer &frame-attr = “NO-BOX 2 COLUMNS” &key = Customer.Cust_Num}

Include files should not terminate a block started outside of the include file. Conversely, an include file should not start a block 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 file call, as the compiler tends to get confused.

Do NOT Use Comments Within an Include File Reference

{ lookup.i /* This may blow up! */ &param = “value”}


Never hardcode OS specific path names into any program or include.

If / Then / Else The use of NOT should be avoided. Good style dictates testing

a positive condition whenever possible. Okay to use when testing logical functions and variables.

Mixed AND and OR conditions should be avoided, but if used the order of evaluation should be explicitly noted through the use of parentheses. Put each condition on a separate line aligning the AND/ORs vertically.

Mixed AND / OR Conditions Example

IF true-cond1 AND true-cond2 AND (true-cond3 OR true-cond4) THEN

For a group of conditions connected by AND, the most unlikely condition(s) should be tested first.

For a group of conditions connected by OR, the most likely condition(s) should be tested first.


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 statement, consider using the CASE statement.

Every branch of an IF/THEN/ELSE will use a DO block to enclose the code even if there is only one statement. The cost is a slight increase in R-code size. This will prevent errors if other statements 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 were added 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 when there 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.


Always place a DO/END block around any include file reference.

ELSE statements should appear on separate lines, aligned with the IF statements to which they apply.

For compound tests, align the ORs and ANDs.

Compound AND / OR Example

IF condition AND vBegDate > Order.Order_Date AND vEndDate < Order.Order_Date THENDO: /* Statements */END.

When testing logical fields or variables, do not use TRUE, FALSE, YES, and NO for comparisons because of reduced performance and larger R-code.

Use the Progress CASE statement (V7) when ever possible. If it is necessary to use nested IF statements, use the following constructs:

Multiple IF / THEN / ELSE Example

IF condition AND vBegDate > Order.Order_Date AND vEndDate < Order.Order_Date THENDO: /* Statements */END.ELSEIF NOT (condition) THENDO: /* Statements */END.

The use of "null" THENs and ELSEs is not allowed.

Null THEN / ELSE Example


Never use “null” THEN/ELSE statements, which can lead to confusion.

IF condition THEN . ELSE .

This code does compile and illustrates what a “null” THEN or ELSE is.


Case Statement In Version 7 Progress use the CASE statement, instead of

nested IF/THEN/ELSE statements.

Example of the CASE statement

CASE selection WHEN “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 last

statement of every program should be a RETURN and this should be the only RETURN used in a program. To "goto" a RETURN 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.


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

Listing Field Names All field names should be "qualified" and typed in as

filename.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. should be 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 if the FRAME Phrase is used, it will be aligned with the fields/variables.

Example of Fields on multiple lines

UPDATE Customer.Cust_Num Customer.Name Customer.Address Customer.Phone WITH FRAME fCustFrame.

When displaying a subset of an array, use the following notation:

Example of Using an Array

DISPLAY array[1 FOR 5].

This method is easier to read and maintain than listing out each individual array element.


L I S T I N G F I E L D

N A M E S

Listing field names vertically eases readability and makes it simple to add or delete fields later.

Listing Format Phrase Options When FORMAT Phrase options are used, they should be

aligned vertically or horizontally.

Example of Format Phrase Options

UPDATE Customer.Name HELP “Enter Customer Name” VALIDATE (Customer.Name NE “”,”Customer Name Must Be Entered”) Customer.Contact AT 20 HELP “Enter Customer Contact”.

UPDATE vStartDate AT 10 HELP “Enter Start Date” vEndDate AT 50 HELP “Enter Ending Date”

UPDATE Customer.Name HELP “Enter Customer Name” VALIDATE (Customer.Name NE “”,”Error”) Customer.Contact AT 20 HELP “Enter Customer Contact”.

Listing Frame Phrase Options Arrange frame phrase options in a manner that avoids

placement of two integers together for different options.

Example of Frame Phrase Options to Avoid

UPDATE Customer.Name Customer.Phone WITH RETAIN 1 8 DOWN ROW 2 2 COLUMNS.

Example of Frame Phrase Options Preferred

UPDATE Customer.Name Customer.Phone WITH 2 COLUMNS 8 DOWN ROW 2 RETAIN 1.


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

Keywords to Not Use STOP statement: Useful for testing only.

USE-INDEX option: Essentially hard-codes an index name into a procedure. Don't use unless knowledge of data distribution shows that Progress' automatic index selection will be incorrect. Should never be used in Version 7 Progress.

Keywords to Avoid OF: OF makes code easier to read, but hides the name of the

field(s) being used to relate the files together. Ok to use when there are no further qualifications necessary for record selection. Do not use OF and WHERE together.

ENTERED function: The ENTERED flag is easily cleared by an UNDO, RETRY and could lead to incorrect results.

RELEASE statement: Use of this statement within a TRANSACTION might indicate a lack of understanding record and/or transaction scope. RELEASE cannot release SHARE-LOCK or EXCLUSIVE-LOCKs within a transaction.

OR operator: Use in a WHERE clause can negate the efficient use of an index.


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 transaction will not release the lock on the record.

Abbreviations The abbreviation of variables, file and field names is not

allowed.

The following keywords should not be abbreviated, because the minimum allowed abbreviation is too short:

Keywords to NOT Abbreviate

ACCUMULATEAVAILABLEAVERAGEALL COLORS (BLACK, BLUE, CYAN, ETC.)BLINKDATELIGHTNO-VALIDATEPROMPT-FORRECIDSUB-AVERAGETRANSACTIONUNDERLINE

The following keywords may be abbreviated, but not as much as Progress allows:

Keywords that can be Abbreviated

KEYWORD ALLOWEDCHARACTER CHARDECIMAL DECDESCENDING DESCENDINTEGER INTLOGICAL LOG

All other Progress supported abbreviations are allowed.


A B B R E V I A -

T I O N S

Miscellaneous Hard coding of values into any program is discouraged with

the following exceptions: Parameters passed to an include file and 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 one” “line in the code. ”.

Note in the preceding example that the message string is delimited with a blank on each end. This suggestion also pertains to TITLEs.

Example of Titles

FORM Customer.Cust_Num Customer.Name WITH TITLE “ Customer Information “ CENTERED.


M I S C E L L A N -

E O U S

Algebraic style logical operators are preferred over the FORTRAN style. Either style is acceptable.

Example of Operators

Preferred Instead Ofa <> b a NE ba <= b a LE 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 is never met.

Example of an Acceptable Check

TEST-BLOCK:DO WHILE TRUE: /* statements */ IF vCounter <= 0 THEN LEAVE TEST-BLOCK.END. /* TEST-BLOCK */

Example of an Unacceptable Check

TEST-BLOCK:DO WHILE TRUE: /* statements */ IF vCounter = 0 THEN LEAVE TEST-BLOCK.END. /* TEST-BLOCK */


TRIM character field sensitive to leading blanks (i.e. sort fields).

The fields in a FORM statement should be listed vertically one per line for ease of maintenance.

Example of a Form Statement

FORM Customer.Cust_Num Customer.Name Customer.Phone WITH 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 to recover the blank line (and columns) that Progress allocates for the "invisible" graphics box at the top of the frame.

For standardized frame widths on reports, use standard WIDTHs that match the characters per inch normally used on the printer:

Frame Widths

10 CPI: 75/12512 CPI: 90/140etc.

Avoid widths that exceed 132 columns particularly because this compromises the ability for a user to send a wide report to their terminal (using the TERMINAL statement) without wrapping. In addition, it means that there is not need to


F R A M E S

support condensed/compressed print for a potentially variety of printers.

To make maximum use of paper, but still leave an adequate margin, use PAGE-SIZE 60.


Transactions Block headers that define a transaction should explicitly use

the TRANSACTION keyword for self-documentation. This will allow 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 the block which is the Progress default (UNDO, RETRY). Instead, more localized DO ON ERROR blocks along with NEXT-PROMPT should be used to keep the cursor on the field where the error occurred.

The UNDO statement should never be used without a RETRY, NEXT, LEAVE or RETURN even though Progress allows it. Always follow the UNDO with the appropriate action (NEXT, LEAVE, RETRY, RETURN) and a label if appropriate. Although Progress allows the use of RETURN, as stated earlier this is to be avoided.


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

Record Reading Always use WHERE instead of OF so that whoever is looking at

the code always knows which fields are being used to join files, unless there are no further conditions necessary for record selection. Do not use OF and WHERE together.

Example of Acceptable Record Reading

ORDER-BLOCK:FOR EACH Order WHERE Order.Cust_Num = “1000” NO-LOCK: DISPLAY Order.Cust_Num Order.Ord_Num. ITEM-BLOCK: FOR EACH Order_Line OF Order NO-LOCK: DISPLAY Order_Line.Order_Line_Num Order_Line.Item_Num. END. /* ITEM-BLOCK: */END. /* ORDER-BLOCK: */

Example of Unacceptable Record Reading

ORDER-BLOCK:FOR EACH Order WHERE Order.Cust_Num = “1000” NO-LOCK: DISPLAY Order.Cust_Num Order.Ord_Num. ITEM-BLOCK: FOR EACH Order_Line OF Order WHERE Order_Line.Order_Qty > 0 NO-LOCK: DISPLAY Order_Line.Order_Line_Num Order_Line.Item_Num. END. /* ITEM-BLOCK: */END. /* ORDER-BLOCK: */


R E C O R D

R E A D I N G

USING may be used instead of WHERE because USING specifies the key being used.

For good style the left side of the comparison in a WHERE clause will 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 related records 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.


When there are multiple conditions in the WHERE clause, use the following form (note the indentation):

Example of Multiple Condition WHERE Clause

Example 1:

FOR EACH Customer WHERE Customer.Cust_Num > 10 AND Customer.Cust_Num < 100 AND Customer.State = “MA” NO-LOCK:END.

Example 2:

FOR EACH Customer NO-LOCK WHERE Customer.Cust_Num > 10 AND Customer.Cust_Num < 100 AND Customer.State = “MA”, EACH Order NO-LOCK WHERE Order.Cust_Num = Customer.Cust_Num AND Order.Order_Num > 100 BREAK BY Order.Order_Date BY Customer.Name:END.

When retrieving one-to-one relationship records in a FOR statement, the EACH should be used in case the record is missing. If there is a possibility that a record could be missing, it should be trapped using FIND/NO-ERROR and the AVAILABLE function.

When a PROMPT-FOR is followed by a FIND, use NO-ERROR on the FIND statement unless you wish to use the Progress default error handling (an error message followed by UNDO, RETRY of the closest UNDO block). FIND/NO-ERROR will always be followed by a test with the AVAILABLE function.

FIND/NO-WAIT will always be followed by a test with the LOCKED function.


The order of comparisons in a WHERE clause should follow this hierarchy:

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 in the 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. FIND is designed to retrieve a single record based upon unique index information. Use FIND FIRST/NEXT/PREY/LAST for all other situations.

Do not use a FOR block when retrieving a single record based upon 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 thinking that 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.


Record Locking Use NO-LOCK whenever the state of the information is not

important (e.g. most inquiries and reports) to reduce contention and improve performance.

When it is reasonably certain that a user will be updating an existing record and that record will not cause locking contention, read the record EXCLUSIVE-LOCK. This will reduce the potential for deadly embrace as well as offer a small performance gain.

SHARE-LOCK should never be used. With SHARE-LOCK the possibility always exists that deadly embraces, or deadlock, might occur.

Always explicitly state the lock status. The use of the -NL startup option is forbidden.

PortabilitySince Progress programs can be deployed on many different platforms, it is important to keep some 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


R E C O R D

L O C K I N G

Chapter

6T E R M I N A L S

DOS, 24 for most ASCII terminals), use the following functions to calculate the available lines and make maximum use of the available screen space.

Screen Checking Functions

SCREEN-LINESFRAME-DOWNFRAME-ROWFRAME-LINE

In the Frame Phrase:

expression DOWNROW expression

The same situation exists with space taking and non-space taking terminals. To take maximum advantage of available screen space and still maintain portability, the following is recommended:

All frames with data entry or using color attributes will be use ATTR-SPACE in the Frame Phrase for that frame.

All procedures will be compiled with the NO-ATTR-SPACE option.


Names If DOS compatibility is needed, the following items will be

limited 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, but only to separate the procedure or include name from the suffix.

All procedure and include file names should be in lower case.

Workfiles On 640K DOS machines, there is very little memory available

to allocate to local buffer space (the -l parameter). The 64K barrier on local buffer size on DOS machines affects portability when large numbers of workfile records might be created. Because of this, the use of workfiles is discouraged unless both of the following conditions are met:

The number of workfile records created will remain static or not exceed a predetermined "high water mark".

The workfile records will not be increased in size during execution of the procedure.


N A M E SW O R K F I L E S

Operating Systems Use the OPSYS function to shield operating system calls.

Checking for the Operating System Example

CASE OPSYS WHEN “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. OTHERWISE MESSAGE “Unknown Operating System:” OPSYS.END CASE.

Color Use the COLOR VALUE (color-variable) in all frame phrases. An

installation that starts with monochrome monitors and then migrates to color can easily take advantage of the color if the coding is done in this style.

Operating System Specific OUTPUT THRU is very useful and powerful, but is not supported

on all Progress platforms.

AUTO-RETURN should never be used.

When a transaction completes, the user should be informed with a message that the transaction has successfully finished and been committed to the database.

Warning messages should be preceded with "WARNING:"

Error messages should be preceded with "ERROR:". This includes the valmsg in the dictionary as well as the second argument of the VALIDATE format phrase option.

All error messages should be accompanied by an audible BELL.


O P E R S T I N G

S Y S T E M S

C O L O RO P E R A T I N G

S Y S T E M

S P E C I F I C

Help messages should be preceded with "Enter".

Because the END-ERROR key has two possible actions that might be taken, the ambiguous nature of the key can confuse users.

PerformanceAlthough Performance is often not the first priority when programming, it is important to keep 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 FIND retrieves the entire record (minimum of 2 I/Os).

For the display of constant data, the construct:

Example of Displaying Constant Data

FORM “This is a constant string” WITH FRAME fTest.VIEW FRAME fTest.

/* This is more efficient then: */

DISPLAY “This is a constant string”.


Chapter

7C O D I N G

T E C H N I Q U E S

When there are more than 1 assignments next to each other, use the ASSIGN statement.

Example of the Assign Statement

ASSIGN vVar1 = vVar2 vVar3 = 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 use a fully qualified path name with a RUN statement. Only qualify the 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 SHARED BUFFERs instead of passing a RECID with a shared variable. Exception: when reading the record NO-LOCK in the calling procedure (no transaction active) and re-reading the record EXCLUSIVE-LOCK in the sub-procedure to limit the transaction to the sub-procedure.

When a variable is changed in a transaction or sub-transaction that variable and all other variables in that procedure are written to the local before image (.lbi) file. To reduce the overhead 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 occur in.


Reading a record NO-LOCK eliminates the need for Progress to check the locking table for a slight performance gain.

Read records EXCLUSIVE-LOCK instead of the default which is a SHARE-LOCK upgraded to an EXCLUSIVE-LOCK when the record is updated.

For multiple string comparisons, use CAN-DO, LOOKUP or INDEX versus 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. batch creation 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.


When loading data into a database, use the NO-ECHO option on the INPUT FROM statement.

When loading data into the database, use IMPORT (Version 6 and later) rather than SET or UPDATE.

Only use WORKFILEs for a fixed number of static records Creating WORKFILE records in an unrestricted way can crash the 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 environment can bring up some more issues to be concerned about.

Using Multiple Databases Do not use the Progress Auto-Connect feature. It can cause

unexpected pauses in a procedure as the connection is initiated.

For modularity, put ail CONNECT logic at the start of the user's session.

Use NO-ERROR on the CONNECT and test to see if the connection was established using the CONNECTED function.


Chapter

8U S I N G

M U L T I P L E

D A T A B A S E S

Use one CONNECT statement per database. If a multi-database CONNECT fails, all subsequent connections will not be established.

Understanding TransactionsTransactions, and how Progress handles them, are often difficult but yet an important concept for programmers to grasp.

The manner in which Progress handles transactions is one of the unique and powerful features of the 4GL. It is also an area that we 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 planning and careless programming it is possible to adversely and dangerous affect the behavior of your application from both a user interface point of view and a performance and "physical" database point of view.

Transaction Scope OverviewA transaction scope is logical grouping of changes being carried out to data that Progress guarantees will either be committed as a whole or UNDOne as a whole. Reasons for undoing a transaction will range from a user deciding to abort the current set of changes (pressing F4 for example), to applications errors, to hardware failure.


Chapter

9T R A N S A C T I O N

S C O P E

O V E R V I E W

Each completed transaction is guaranteed to have been written permanently to the database whilst any incomplete transactions will not be written to the database of they are interrupted.

If you are unsure whether a transaction is currently active in your program use the TRANSACTION function which will return true if a transaction is currently active.


Default Block ScopeProgress code is structured in blocks. These take the form of procedures, triggers, DO blocks (including IF/THEN DO), FOR EACH and REPEAT. Of these the procedures, triggers, FOR EACH, DO ON ERROR and REPEAT will start a transation if there is a find with an EXCLUSIVE-LOCK in their block.

This meanes that should a change be made to the data or a record found with an exclusive lock within these blocks, a transaction will be scoped to the bounds of those blocks.

DO blocks have weak transaction scoping. If a change to data is made to a DO block then the transaction is scoped to the next outer 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 */


D E F A U L T

B L O C K S C O P E

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


Controlling TransactionsIt is possible to force any block to start a transaction by using the TRANSACTION keyword (note this differs from the TRANSACTION function 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.


C O N T R O L L I N G

T R A N S -

A C T I O N S

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 be deleted. Of course this scenario also holds locks on all the records until the end of the transaction.


Sub-transactionsWith Progress it is only possible to have one active transaction at a time. If a transaction block becomes part of an existing transaction 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 get committed until the end of the main transaction.

One of the most common ways of starting a sub-transaction is by calling 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") THEN RUN 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 within another transaction. Any update made in newcust.p can be rolled back in the calling routine if the user presses F4.

Another side effect of this scenario is that a lock will be maintained on the Customer record until the end of the main transaction in the calling procedure.


S U B - T R A N S -

A C T I O N S

Record Locks and ScopeUnderstanding Record Locking and Record Scope are essential in order to produce an effective program design.

Record LocksProgress has row-level locking. This means it locks individual records at a time (as opposed to pages or tables).

Two types of lock are supported, they are the SHARE-LOCK and the EXCLUSIVE-LOCK. In addition, Progress can read records with NO-LOCK.

A SHARE-LOCK allows a record to be read by more than one user so long as that record is not being modified. A SHARE-LOCK gets upgraded to an EXCLUSIVE-LOCK if the modification on that record begins.

An EXCLUSIVE-LOCK prevents any other user modifying or placing a SHARE-LOCK on a record.

NO-LOCK allows the record to be read no matter what state another user has it in. It cannot however be modified. NO-LOCK allows dirty reads. In other words, the data that is being read may not have been committed to the database.

The Progress default for a record is SHARE-LOCK as this provides the user with the most protection. However, this option is not recommended unless absolutely required. In general, the developer should know what is going to happen to the record and read it with a NO-LOCK or an EXCLUSIVE-LOCK.


Chapter

10R E C O R D L O C K S

Record ScopeThis subject relates to how long information in a Progress record buffer remains active and by association how long Progress keeps a 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 a wider scope that the transaction scope.

Locks are held on a record not a buffer (remember it is possible to 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 the PAUSE statement. The first FIND will instigate a SHARE-LOCK on the customer record.

When the DO TRANSACTION is encountered the SHARE-LOCK gets upgraded to an EXCLUSIVE-LOCK. At the end of the transaction the changes to the record are committed and the lock on the record 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 */


R E C O R D S C O P E

Note that in the above example the lock status after the end of the transaction is still SHARE-LOCK. In other words, the record can only be read not modified by another user in this state.

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


The RELEASE statement can also be used to clear out a record buffer and release the locks on that record at the end of the transaction.

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 transaction but the Customer buffer is no longer available.

RELEASE is a bit of a cop-out indicating a failure to properly control your record and transaction scopes. In addition it behaves differently if it is used in a sub-procedure that has been called within an existing record scope. In this case the lock is not released but downgraded to a SHARE-LOCK at the end of the procedure.

Finally, it is possible to narrow (or increase) the scope of your record by using the DO FOR tablename construct. This strongly scopes the record to the block. No references to the buffer can be 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 boundary effectively increase the scope of that record (but not the


transaction).


The following example ensures that the record is not available outside the bounds of the transaction. In fact, it should not compile.

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 THEN MESSAGE "Customer record is available".

Using XREF and ListingsUsing the Progress XREF and Listings compiler options can give invaluable insight into a program and are often useful in debugging.

When a program has been completed, it should be compiled to produce two extra files. These are the LISTING file and the XREF (cross-reference) file. These files contain vital information, which will help ensure that your programs behave as expected. Use these files to help with unit testing and code reviews.

ListingsThe listing file expands include files and numbers the program lines by block. At the end of the listing is a summary of each block within the procedure, the procedure itself being the main block.

The record buffers and transaction that are scoped to the block are shown, as are the frame scopes.


Chapter

11L I S T I N G S

Use the COMPILE filename.p LISTING filename.lst option form the PROGRESS editor of the Compile option in the Application Compiler 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 */2123 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 of interest 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 no transaction scoped to this block. The inner DO TRANSACTION block has a transaction scoped to it.

The REPEAT block has both a record buffer (Office_Header) and a transaction scoped to it.


XREFThe cross reference compile option writes cross reference information between procedures and PROGRESS objects, including procedures, include files, tables, fields indices, variables frames and character strings.

Developers must use this facility to check the efficiency of their queries. Whenever a query is used, a SEARCH entry will be made in the XREF file. This is followed by the table name and the name of the index used to resolve the query. If the query is unbracketed (i.e. there are no criteria given to narrow down the search) or PROGRESS is unable to use an index to resolve the query then the phrase WHOLE-INDEX appears after the index name.

In the latter instance, the index name is the primary index, which only gives the order in which the records are returned. The rest of the query will be resolved by searching through the whole table. 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.


X R E F

This produces a number of lines, for index usage look for lines with 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 is a 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 be returned and the WHOLE-INDEX phrases indicates that the whole table will have to be searched to resolve this query. This should be considered a bug as it will cause severe performance problems.

The final highlighted line shows a bracketed query that has been resolved using an index (account). This index was inspected and looks suitable as Account_no (the bracketing field) is also the first component in that index.


Date post:	27-Jul-2018
Category:	Documents
Upload:	vuphuc
View:	214 times
Download:	0 times

progress Programming Coding Standards - Smart It€¦ · Web viewProgress Coding Standards Manual...

Documents