Progress
Language Reference


COMPILE Statement

Interfaces
OS
SpeedScript
All
All
Yes

Compiles a procedure. After a procedure is compiled, the RUN statement does not recompile it, so the procedure runs quickly. A compilation can last for a session, or it can be saved permanently for use in later sessions (as an r-code file, which has a .r extension).

SYNTAX

COMPILE { procedure | VALUE ( expression ) }
  [ ATTR-SPACE [ = logical-expression ] ]
  [ SAVE [ = logical-expression ] 
     [ INTO { directory | VALUE ( expression ) } ]
  ]
  [ LISTING { listfile | VALUE ( expression ) } 
     [     APPEND [ = logical-expression ] 
        |  PAGE-SIZE integer-expression 
        |  PAGE-WIDTH integer-expression 
     ]
  ]
  [ XCODE expression ]
  [ XREF { xreffile | VALUE ( expression ) } 
     [ APPEND [ = logical-expression ] ]
  ]
  [ STRING-XREF { sxreffile | VALUE ( expression ) } 
     [ APPEND [ = logical-expression ] ]
  ]
  [ STREAM-IO [ = logical-expression ] ]
  [ LANGUAGES ( { language-list | VALUE ( expression ) } )
     [ TEXT-SEG-GROW = growth-factor ] ]
  [ DEBUG-LIST { debugfile | VALUE ( expression ) } ]
  [ PREPROCESS { preprocessfile | VALUE ( expression ) } ]
  [ NO-ERROR ] 
  [ V6FRAME [ = logical-expression ]
     [ USE-REVVIDEO | USE-UNDERLINE ] ]
    [ MIN-SIZE [ = logical-expression ] ]
[ GENERATE-MD5 [ = logical-expression ] ] 

COMPILE { procedure | VALUE ( expression ) }

Specifies the name of the procedure you want to compile.

On UNIX, you can use a procedure name (the last component of the full pathname, if you use the full pathname) up to 12 characters long. On Windows, if you use the SAVE option, the procedure name must have a .p extension, .w extension, or no extension. On UNIX, procedure names are case sensitive, so you must enter them exactly as they are stored.

ATTR-SPACE [ = logical-expression ]

No effect-supported for backward compatibility only.

XCODE expression

Decrypts the source code in procedure, and any encrypted include files, using the decryption key expression. Only use XCODE to decrypt files not encrypted with the default key. Include files that are not encrypted are included and compiled in the standard manner.

Decryption is incremental during compilation. Having the decryption key does not allow you to examine a decrypted version of the source code.

NOTE: You cannot use the XCODE and LISTING or DEBUG-LIST options together. Also, you cannot use the XCODE and XREF options together. That is, you cannot create a cross-reference listing from code that is encrypted.

STREAM-IO [ = logical-expression ]

Specifies that all output from the compiled procedures is formatted for output to a file or printer. This means that all font specifications are ignored and all frames are treated as if they had the USE-TEXT option given. This produces a platform-independent output appropriate for printing.

If you specify a logical-expression, its value determines whether the STREAM-IO option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.

SAVE [ = logical-expression ] [ INTO { directory | VALUE ( expression) } ]

Produces a file that contains the r-code for the procedure you are compiling. This r-code file is saved across Progress sessions. If you do not use the SAVE phrase, the COMPILE statement produces r-code for the source procedure, but the r-code is not saved across Progress sessions. This r-code is a session compile version of the procedure.

If you specify a logical-expression, its value determines whether the SAVE option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.

The COMPILE SAVE statement produces an r-code file with the name procedure-name.r, where procedure-name is the name of your source file without the extension. If you supply a filename of test, COMPILE SAVE produces an r-code file with the name test.r. If you supply a filename of test.p, COMPILE SAVE produces an r-code file with the name test.r. However, if you specify a filename of test.bp, COMPILE SAVE still produces an r-code file with the name test.r. Progress ignores the file extension of your procedure files and always creates r-code files that use the same filename with a .r extension. Make sure that you use distinct filenames for each of your procedure files.

By default, the r-code file is stored in the same directory as the source procedure. If you use the SAVE INTO phrase, the r-code file produced by a compilation can be saved in a different directory. See the EXAMPLES and NOTES sections for more information.

On UNIX and Windows, a newly created r-code file replaces any existing r-code file of the same name.

LISTING { listfile | VALUE ( expression ) }

Produces a compilation listing that includes:

APPEND [ = logical-expression ]

Appends the current listing to the contents of the listing file. If you do not use the APPEND option, Progress creates a new listing file, replacing any file of the same name.

If you specify a logical-expression, its value determines whether the APPEND option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.

PAGE-SIZE integer-expression

Identifies the number of lines to a page in the listing file. The default page size is 55 and integer-expression must be between 10 and 127, inclusive.

PAGE-WIDTH integer-expression

Identifies the number of page columns in the listing file. The default page width is 80, and integer-expression must be between 80 and 255, inclusive. Add at least 12 spaces to the page width when you type the procedure. This allows you to list information that precedes each line of code, ensuring that the procedure appears in the listing output exactly as you typed it.

XREF { xreffile | VALUE ( expression ) } [ APPEND [ = logical-expression ] ]

Writes cross-reference information between procedures and Progress objects to the file xreffile or VALUE ( expression ). If expression returns the unknown value (?), then Progress ignores the XREF option.

NOTE: You cannot use the XREF and XCODE options together. That is, you cannot create a cross-reference listing from code that is encrypted.

Cross-referenced objects include procedure and include files, user-defined functions, tables, fields, variables, frames, and character strings. XREF generates one unformatted, blank-separated line in xreffile for each object reference. Each line has the following format.

procedure-name  file-name  line-number  reference-type  object-identifier 

The procedure-name is the name of the procedure you compile with the COMPILE XREF statement. The file-name is the name of the file with the referenced code. The line-number is the line number of the statement in file-name that contains the object reference. The reference-type is the type of reference in the code (such as ACCESS or UPDATE), and the object-identifier is the Progress object being referenced.

NOTE: If file-name is an include-file, procedure-name is the file that includes the include-file.

The possible reference types and object identifiers appear in Table 14.

Table 14: Reference Types and Object Identifiers
Reference Type
Object Identifier
COMPILE
procedure
STRING
char-string max-length justification translatable[FORMAT]
RUN
procedure-name | value(exp)
INCLUDE
include-file-name
CREATE
[database.]table [ WORKTABLE]
DELETE
[database.]table [WORKTABLE]
SORT-ACCESS
{[database.]table field [WORKTABLE | TEMPTABLE]}
ACCESS
{[database.]table field [WORKTABLE]} | {SHARED variable}
REFERENCE
{[database.]table field [WORKTABLE]} | {SHARED variable}
UPDATE
{[database.]table field [WORKTABLE]} | {SHARED variable}
SEARCH
[database.]table
{index | RECID | WORKTABLE | TEMPTABLE}
[WHOLE-INDEX]1
NEW-SHR-VARIABLE
new-shared-variable
GLOBAL-VARIABLE
global-variable
SHR-FRAME
shared-frame
NEW-SHR-FRAME
new-shared-frame
SHR-WORKTABLE
shared-worktable [LIKE [database.]table]
NEW-SHR-WORKTABLE
new-shared-worktable [LIKE [database.]table]
FUNCTION
function-name,return-type,[parameter1
[,parameter2]...]
EXTERN
function-name,return-type,[parameter1
[,parameter2]...]
PROCEDURE
procedure-name,,[parameter1[,parameter2]...]
DLL-ENTRY
procedure-name,,[parameter1[,parameter2]...]
PUBLISH
event-name|(exp)
SUBSCRIBE
event-name|(exp)
UNSUBSCRIBE
event-name|(exp)|ALL
CPINTERNAL
name-of-the-code-page-that-Progress-uses-
in-memory
CPSTREAM
name-of-the-code-page-that-Progress-uses-for-
stream-I/O
SORT-BY-EXP
{ FOR EACH | OPEN QUERY } table BY expression
  1. WHOLE-INDEX means that the selection criteria specified to search the table does not offer opportunities to use indexes that allow optimized key references (bracketed high and low values). Instead, Progress must search the entire table using available indexes (often only the primary index) to satisfy the query, hence a WHOLE-INDEX search. Thus, depending on the query, you might be able to optimize the search by adding indexes. See also NOTES.

If you specify the APPEND option, the cross-reference information is appended to an existing file. The first line of cross-reference information for a procedure contains the object identifier for the COMPILE reference type. This allows you to easily find where the information for each compilation begins. If you specify a logical-expression, its value determines whether the APPEND option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs

STRING-XREF { sxreffile | VALUE ( expression ) }
[ APPEND [ = logical-expression ] ]

Writes cross-reference string information between procedures and Progress objects to the file sxreffile or VALUE ( expression ). If expression evaluates to the unknown
value (?), Progress ignores the STRING-XREF option.

String Xref Version x.y  source-file  code-page 

The x.y is a major.minor version number, where a major version change implies a formatting change that will not be backward compatible with older versions of TranManII. The source-file is the name of the file from which the strings are extracted. The code-page is the code page with which the file was written.

The line for each string appears in the following format.

line-number  object-name  string  max-length  string-justification  
statement-type  detail-info 

The line-number is the same as line-number in the standard XREF file. The object-name is the name of the object with which the string is associated. The max-length and string-justification come from the string attribute (either explicit or implicit) and reflect the attributes applied to the string as it is entered into the text segment.

The statement-type describes the type of statement in which the string appears. Only one statement type appears in a given string’s output line. The following values are possible:

Statement Type Values
ASSIGN
DEF-SUB-MENU
INSERT
PUT-SCREEN
CASE
DISPLAY
MESSAGE
REPEAT
CREATE
DO
OPEN-QUERY
RUN
DEF-BROWSE
ENABLE
OTHER
SET
DEF-BUTTON
EXPORT
PAUSE
STATUS
DEF-FRAME
FOR
PROMPT-FOR
UPDATE
DEF-IMAGE
FORM
PUT
VIEW-AS
DEF-MENU
IF
   

NOTE: Any statement type that is not included in the preceding list will appear as OTHER.

The detail-info is one or more detail tags that specify more specifically where the string appears in the statement. The following values are possible:

Detail Tags
ASSIGN
FORMAT
MESSAGE
TITLE
COL-LABEL
IMAGE-FILE
NON-ALPHA
VALUE
COMBO-BOX-ITEM
INPUT
PROMSGS
WHEN
CUR-LANG
INPUT-PARAM
PROPATH
WHERE
DEFAULT
LABEL
SEL-LIST-ITEM
WHILE
EXPR
LIST-ITEM
TERMCAP
 

NOTE: The NON-ALPHA tag indicates that a string consists entirely of blanks or digits.
The FORMAT tag is followed by one of the following tags: CHAR, NUMERIC (includes decimal and integer), DATE, or BOOL. These tags indicate the type of format. When a string can appear in only one place in a statement, no detail tag appears.

Table 15 shows the valid combinations of statement types and detail tags.

Table 15: Valid Combinations of Statement Types and Detail Tags
Statement Type
Detail Tags
ASSIGN
CUR-LANG, PROMSGS, PROPATH, TERMCAP
CASE
WHEN
CREATE
N/A
DEF-BROWSE
FORMAT, COL-LABEL
DE-FBUTTON
IMAGE-FILE, LABEL
DEF-FRAME
FORMAT, COL-LABEL, LABEL
DEF-IMAGE
IMAGE-FILE
DEF-MENU
TITLE, LABEL
DEF-SUB-MENU
LABEL
DISPLAY
FORMAT, LABEL, COL-LABEL, WHEN, TITLE
DO
WHILE, WHERE, TITLE
ENABLE
LABEL, COL-LABEL, WHEN, TITLE
EXPORT
FORMAT
FOR
WHILE, WHERE, TITLE
FORM
FORMAT
IF
N/A
INSERT
TITLE
MESSAGE
TITLE, FORMAT
PAUSE
MESSAGE
PROMPT-FOR
WHEN, TITLE, FORMAT, LABEL, COL-LABEL
PUT
N/A
PUT-SCREEN
N/A
REPEAT
WHILE, TITLE, WHERE
RUN
INPUT-PARAM
SET
WHEN, ASSIGN, FORMAT, LABEL, COL-LABEL, TITLE
STATUS
DEFAULT, INPUT
UPDATE
WHEN, ASSIGN, FORMAT, LABEL, COL-LABEL, TITLE
VIEW-AS
SEL-LIST-ITEM, COMBO-BOX-ITEM

LANGUAGES ( { language-list | VALUE ( expression ) } )

Identifies which language segments to include in the compiled r-code. The language-list is a colon-separated list of language names used to generate each text segment. If you specify VALUE ( expression ), the expression must evaluate to a comma-separated list of language names. If expression evaluates to the unknown value (?), then Progress ignores the LANGUAGES option.

Translated character strings for each specified language are read from the translation database and are stored in segments within the r-code.

COMPILE myfile.p LANGUAGES(French-Canadian:French:English, 
Portuguese:Spanish,
New-York:American:English).

If you use an expression to specify language-list, you must use the VALUE option.

COMPILE myfile.p LANGUAGES (VALUE(char-var)).

/* char-var = "French-Canadian:French:English, 
Portuguese:Spanish,
New-York:American:English" */

In this example, the compiler searches the translation database for French-Canadian translations. If a French-Canadian translation is not found, the compiler searches for a French translation. If a French translation is not found, the compiler searches for an English translation. If an English translation is not found, the compiler uses the strings from the source code.

This example generates four text segments: French-Canadian, Portuguese, New-York, and the unnamed (default) text segment. The first language name in each language-list argument designates the name of the text segment and specifies the first language that the compiler looks up in the translation database. As a result, it is possible to create a text segment whose name has no relationship to the languages it is composed of. For example, the following argument creates a text segment named BABEL.

LANGUAGES(BABEL:French:Spanish:Italian:German) 

Provided there is no language named BABEL in the translation database, the strings in this text segment would be either French, Spanish, Italian, or German, depending on which strings have translations in which languages.

TEXT-SEG-GROW = growth-factor

Specifies the factor by which Progress increases the length of strings. When you develop an application that is going to be translated, it is important to allow for the growth of the text in your widgets. If you use the TEXT-SEG-GROW option, Progress increases the size of the text strings when it compiles your application.

Progress uses the following formula to determine the length of strings.

New-length = 
Actual-length * [1 + (growth-factor/100 * (table-value/100))] 

Where:

DEBUG-LIST { debugfile | VALUE ( expression ) }

Writes the debug listing to the file debugfile or VALUE ( expression ). If expression evaluates to the unknown value (?), then Progress ignores the DEBUG-LIST option. The debugfile consists of a line-numbered listing of the procedure with the text of all preprocessor include files, names, and parameters inserted.

PREPROCESS { preprocessfile | VALUE ( expression ) }

Preprocesses the procedure and writes the preprocessed source code to the file preprocessfile or VALUE ( expression ). If expression evaluates to the unknown value (?), Progress ignores the PREPROCESS option. The preprocessfile is a text file that contains a final version of your source code after all include files have been inserted and all text substitutions have been performed.

NO-ERROR

Specifies that any errors that occur as a result of the compilation are suppressed. After the COMPILE statement completes, you can check the ERROR and WARNING attributes of the COMPILER system handle to determine whether an error has occurred or any warning messages were produced. You then can check the ERROR-STATUS handle for the specific messages.

V6FRAME [ = logical-expression ] [USE-REVVIDEO | USE-UNDERLINE]

The V6FRAME option is designed specifically to compile and run Progress Version 6 applications with Progress Version 7 or later for Windows. This option uses the V6FontNumber setting in the [Startup] section of the current environment (which might be the Registry or an initialization file) to calculate the height and width of a character unit and then set the layout grid used to compile frames for display in Progress Version 7 or later.

At run time, the FONT attribute for a frame compiled with the V6FRAME option is set to the font number specified with the V6FontNumber setting. The default setting for the V6FontNumber setting is 3.

By default, V6FRAME displays a border around a fill-in field. This means that your code requires more space on the screen than in Progress Version 6. You can override this behavior with one of the following options.

MIN-SIZE [ = logical-expression ]

Minimizes the size of the generated r-code file by eliminating the Debugger Segment (which is used by the Progress Debugger) and the signature descriptor data (which is used by the Open Client Proxy Generator).

If you specify a logical-expression, its value determines whether the MIN-SIZE option is activated (TRUE) or not (FALSE). If the logical-expression evaluates to the unknown value (?), a run-time error occurs. The default value is FALSE.

GENERATE-MD5 [ = logical-expression ]

When Progress compiles a procedure with the GENERATE-MD5 option, it generates a special MD5 value based on the code content, and stores it in the r-code file. This r-code MD5 value is similar to a CRC value, except the MD5 value is 128 bits in size and the CRC value is only 16 bits. The MD5 value is virtually guaranteed to be different if the file content has changed. As with CRC, content changes include any schema changes. That is, if only the schema changes, the MD5 value also changes.

If you specify a logical-expression, its value determines whether the GENERATE-MD5 option is activated (TRUE) or not (FALSE). The default value is TRUE.

This option is supported for WebClient only (that is, only WebClient uses the resulting MD5 value). Progress recommends compiling your WebClient application procedures with this option. Using this option lets WebClient determine if an r-code file has changed since the previous version of the application.

EXAMPLES

In this procedure, Progress creates an r-code version of the ord-ent procedure, naming it ord-ent.r. (The sample procedures supplied with Progress do not include the ord-ent procedure.)

r-cmple.p
COMPILE ord-ent SAVE. 

In this procedure, Progress compiles the demo1 procedure, reserving spaces in frame layouts for special field attributes and producing an r-code file, demo1.r, that can be used across Progress sessions. Progress saves the r-code file in the current directory.

r-cmple2.p
COMPILE demo1 ATTR-SPACE SAVE. 

You can save the r-code file in a different directory by using the SAVE INTO phrase. For example, to save an r-code file in /usr/sources on a UNIX system, enter this command.

COMPILE demo1 ATTR-SPACE SAVE INTO /usr/sources. 

The following example shows the effect of include files on compilation listings.

r-incl.p
FOR EACH customer:
  {r-fcust.i}
  {r-dcust.i}
END. 

Suppose you use the following COMPILE statement to compile the r-incl.p procedure.

r-comlis.p
COMPILE r-incl.p  SAVE  LISTING r-incl.lis  
 XREF r-incl.xrf DEBUG-LIST r-incl.dbg. 

This COMPILE statement produces four files: r-incl.r, r-incl.lis, r-incl.xrf, and r-incl.dbg.

The following procedures contain the contents of the r-incl.lis, r-incl.xrf, and r-incl.dbg files.

r-incl.lis
r-incl.p                       06/01/93 13:06:30   PROGRESS(R) Page 1

{} Line Blk
-- ---- ---
      1     /* r-incl.p */
      2     
      3   1 FOR EACH customer:
      4   1   {r-fcust.i}
 1    1   1 /* r-fcust.i */
 1    2   1 
 1    3   1 FORM customer.cust-num customer.name LABEL "Customer Name"
 1    4   1      customer.phone FORMAT "999-999-9999".
      4   1  
      5   1   {r-dcust.i}
 1    1   1 /* r-dcust.i */
 1    2   1 
 1    3   1 DISPLAY customer.cust-num customer.name customer.phone.
      5   1  
      6     END.
^Lr-incl.p                     06/01/93 13:06:30   PROGRESS(R) Page 2     

     File Name       Line Blk. Type Tran            Blk. Label            
-------------------- ---- --------- ---- --------------------------------
r-incl.p                0 Procedure No                                    
r-incl.p                3 For       No                                    
    Buffers: sports.Customer
    Frames:  Unnamed

^L 

This sample output is not an exact copy of the r-incl.lis file.

There are three columns next to the procedure in the listing file.

  1. {} — The level of the include file.
  2. Line — The line number in the file.
  3. Blk — The number of the block.

The information follows each of the procedure blocks or function blocks:

This is the cross-reference file r-incl.xrf.

r-incl.xrf
r-incl.p r-incl.p 1 COMPILE r-incl.p
r-incl.p r-incl.p 3 STRING "Customer" 8 NONE UNTRANSLATABLE 
r-incl.p r-incl.p 3 SEARCH sports.Customer Cust-Num
r-incl.p r-incl.p 4 INCLUDE r-fcust.i
r-incl.p r-fcust.i 3 ACCESS sports.Customer Cust-Num 
r-incl.p r-fcust.i 3 ACCESS sports.Customer Name 
r-incl.p r-fcust.i 3 ACCESS sports.Customer Phone 
r-incl.p r-fcust.i 3 STRING ">>>>9" 5 NONE TRANSLATABLE  FORMAT 
r-incl.p r-fcust.i 3 STRING "x(20)" 5 NONE TRANSLATABLE  FORMAT 
r-incl.p r-fcust.i 3 STRING "999-999-9999" 12 NONE TRANSLATABLE  FORMAT 
r-incl.p r-incl.p 5 INCLUDE r-dcust.i
r-incl.p r-dcust.i 3 ACCESS sports.Customer Cust-Num 
r-incl.p r-dcust.i 3 ACCESS sports.Customer Name 
r-incl.p r-dcust.i 3 ACCESS sports.Customer Phone 
r-incl.p r-incl.p 6 STRING "Cust-Num" 8 LEFT TRANSLATABLE 
r-incl.p r-incl.p 6 STRING "Customer Name" 13 LEFT TRANSLATABLE 
r-incl.p r-incl.p 6 STRING "Phone" 5 LEFT TRANSLATABLE 
r-incl.p r-incl.p 6 STRING
    "-------- ---------------------- --------------" 46 LEFT TRANSLATABLE 
r-incl.p r-incl.p 6 STRING "Cust-Num" 8 LEFT TRANSLATABLE  

Each line in the xref file specifies the procedure, line number, access type, and access information. The first line in the xref file contains the COMPILE access type directive and the name of the procedure exactly as it appears in the COMPILE statement. See Table 14 for a list of the values that follow a particular access type (for example, table and index after SEARCH).

This is the debug listing r-incl.dbg.

r-incl.dbg
 1   /* r-incl.p */
 2
 3   FOR EACH customer:
 4
 5   /* r-fcust.i */
 6 
 7   FORM customer.cust-num customer.name LABEL "Customer
 8         Name" customer.phone FORMAT "999-999-9999". 
 9                 
10
11   /* r-dcust.i */
12
13  DISPLAY customer.cust-num customer.name customer.phone
14
15   END. 

NOTES

SEE ALSO

COMPILER System Handle, RUN Statement, No Lock (-NL) Startup Parameter (in Progress Startup Command and Parameter Reference )


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095