COMPILE statement

Compiles a procedure file or a class definition file. A compilation can last for a session, or you can save it permanently for use in later sessions (as an r-code file, which has a .r extension).

When you compile a class definition file, ABL compiles the class definition file identified in the COMPILE statement and all class files in its inherited class hierarchy, by default. You can direct ABL to compile only those class definition files in the class hierarchy that are not found in the cache, and cache any classes or interfaces it compiles during the session, by setting the MULTI-COMPILE attribute to TRUE.

Note: When you change the definition of a class, Progress Software Corporation recommends that you recompile all classes that inherit the modified class. This recommendation does not apply to method logic changes within a class.

After you compile a procedure file, you use the RUN statement to create an instance of the procedure, and you use a handle to access the procedure and its context. After you compile a class definition file, you use the NEW function (classes) to create an instance of the class, and you use an object reference to access the class-based object, as well as its data members, properties, and methods.

For more information about compiling procedure files, see OpenEdge Getting Started: ABL Essentials. For more information about compiling class definition files, see OpenEdge Development: Object-oriented Programming.

Syntax

COMPILE { procedure-pathname | VALUE ( expression ) }
     | { class-pathname | VALUE ( expression ) }
  [     OPTIONS options-list 
     |  OPTIONS-FILE { options-file | VALUE ( 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 ] ]
  ]
  [ XREF-XML { directory | filename | VALUE ( 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 ) } ]
  [ V6FRAME [ = logical-expression ]
     [ USE-REVVIDEO | USE-UNDERLINE ] ]
  [ MIN-SIZE [ = logical-expression ] ]
  [ GENERATE-MD5 [ = logical-expression ] ]
  [ ATTR-SPACE [ = logical-expression ] ]
  [ NO-ERROR ]
procedure-pathname | VALUE ( expression )
Specifies the name and location of a procedure file you want to compile, where procedure-pathname is the literal procedure pathname and expression is a character expression that evaluates to the procedure pathname. This pathname can be a full (absolute) pathname or it can be a pathname (or procedure filename only) relative to PROPATH. The specified procedure filename must include the extension (.p or .w) whether you specify it alone or as part of a path. On UNIX, filenames are case sensitive, so you must enter them exactly as they are stored. In Windows, the pathname cannot contain characters outside of the non-Unicode code page. See OpenEdge Development: Internationalizing Applications for more information about Unicode and code pages.
class-pathname | VALUE ( expression )
Specifies the name and location of a class definition file you want to compile. This can be a literal full (absolute) pathname or a literal pathname relative to PROPATH. If it is a relative pathname, the class or interface type name defined in the file must match the pattern of this relative pathname. If the type name is not defined with a package, the relative pathname must specify only the class filename. In all cases, the class filename must include the .cls extension. On UNIX, the class-pathname and corresponding class or interface type name are case sensitive, so you must enter them exactly as they are stored. In Windows, the he class-pathname and corresponding class or interface type name cannot contain characters outside of the non-Unicode code page. See OpenEdge Development: Internationalizing Applications for more information about Unicode and code pages. For more information on packages and class or interface type names, see the Type-name syntax reference entry.
OPTIONS options-list | OPTIONS-FILE { options-file | VALUE ( expression )}
Enforces one or more rules during compilation. In the case of OPTIONS, the rules are specified by a character expression that evaluates to a comma-separated list of options. In the case of OPTIONS-FILE, the rules are specified in the same way, but supplied in a designated file.
The possible options are described in the following table.
Option Description
require-full-names All table and field names must appear as they are in the schema. The compiler’s ability to implicitly resolve abbreviated names in tables is disabled.
require-field-qualifiers All buffer references (including database tables, temp-tables, and buffers) must be fully qualified. The compiler's ability to implicitly resolve the buffer to which a field reference refers is disabled.
require-full-keywords All language keywords must be fully spelled out.

For example, the following COMPILE statement enforces full table and field names and fully qualified references.

COMPILE myproc.p OPTIONS "require-full-names, require-field-qualifiers".
The code below shows access of a field with a fully qualified reference, followed by unqualified and abbreviated examples of the same statement. Only the first statement will compile without error if the code is compiled using the statement above.
/* Accessing the field "tcfield" in the table "tbhelper" */ 

tbhelper.tcfield = "doUpdate". 

/* The folllowing will not compile with "require-field-qualifiers"
in effect. */ 

tcfield = "doUpdate". 

/* The following will not compile with "require-full-names"
in effect. */  

tbh.tcf = "doUpdate".

If options-list or the contents of the options-file resolve to the empty string ("") or white space only, then no options will be applied. If options-list or the contents of the options-file resolve to the Unknown value (?), then the compiler ignores the OPTIONS or OPTIONS-FILE phrase. If an option listed is not valid, the compile statement will fail with an error. When compiling a class hierarchy, the options set in the COMPILE statement are applied to all files compiled for the hierarchy.

You can also set these options using the OPTIONS attribute of the COMPILER system handle, which can be initialized with the Compiler Options (-compileroptionsfile) startup parameter. (See OpenEdge Deployment: Startup Command and Parameter Reference for more information.) Options set using the OPTIONS or OPTIONS-FILE in the COMPILE statement override any options set in the OPTIONS attribute of the COMPILER system handle (unless options-list or the contents of the options-file resolve to the Unknown value (?), as described above).

Note: OPTION-FILE supports the use of the hashtag (#) to include comments in the options file. See the Compiler Options (-compileroptionsfile) startup parameter in OpenEdge Deployment: Startup Command and Parameter Reference for an example.
SAVE [ = logical-expression ][ INTO { directory | VALUE (expression) }]
Produces a file that contains the r-code for the procedure or class you are compiling.

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.

When you compile a class definition file with the SAVE option, ABL produces an r-code file for the class definition file and all class files in its inherited class hierarchy. For example, if you compile a class definition file that has two classes in its inherited class hierarchy, ABL compiles three files and produces three r-code files.

These r-code files are saved across ABL sessions. If you do not use the SAVE phrase, the COMPILE statement produces r-code for the source procedure or class, but the r-code is not saved across ABL sessions. This r-code is a session-compile version of the procedure or class.

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 r-code files with the name procedure-pathname.r or class-pathname.r, where procedure-pathname is the pathname of a procedure source file without the filename extension, and class-pathname is the pathname of a class source file without the filename extension. ABL ignores the filename extension of a procedure or class definition file and always creates r-code files that use the same filename with a .r extension. For example, if you supply a filename of test, test.p, or test.cls, COMPILE SAVE produces an r-code file with the name test.r. If you specify a filename of test.bp, COMPILE SAVE still produces an r-code file with the name test.r.

Caution:
Where both procedure and class definition files compile to a .r file, be sure to use distinct filenames. If you have a procedure file and a class definition file with the same name, and you compile them both with COMPILE SAVE, the first .r file will be overwritten by the second .r file.

By default, the r-code file is stored in the same directory as the source file. The r-code files for inherited (super) class definition files are also stored in the same directory as their respective source files.

If you use the SAVE INTO phrase, r-code files produced by a compilation can be saved in a different directory. See the Examples section and the Notes section of this reference entry for more information.

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:
  • The name of the file containing the procedure or class you compile
  • The date and time at the start of the compilation
  • The number of each line in the procedure or class file
  • The block number where each statement belongs
  • The complete text of all include files (except encrypted include files) and the names of any subprocedures and user-defined functions

The listfile or VALUE ( expression ) identifies the name of the file in which you want to store the Compiler listing. If expression evaluates to the Unknown value (?), then ABL ignores the LISTING option. In Windows, the filename cannot contain characters outside of the non-Unicode code page.

APPEND [ = logical-expression]
Appends the current listing to the contents of the listing file. If you do not use the APPEND option, ABL 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 file. This allows you to list information that precedes each line of code, ensuring that the file appears in the listing output exactly as you typed it.
XCODE expression
Decrypts the source code in procedure-pathname or class-pathname, and any encrypted include files, using the decryption key expression. The decryption key is also used with any class or interface in the hierarchy or any OOABL reference in a procedure or class that is not in the class hierarchy.

When the COMPILE statement detects that a source file is encrypted, it performs the following checks:

  • If the XCODE option is provided, then COMPILE uses the key specified by expression. If the key does not match the source file key, then the compilation fails with an error message. Use this option only when the encryption key is not the built-in (default) key or the encryption key for the session.
  • If XCODE is not present, the COMPILE statement looks for a session-level encryption key in the XCODE-SESSION-KEY attribute of the SECURITY-POLICY handle. If COMPILE finds a session key and it does not match the source file key, then the compilation fails with an error message.
  • If XCODE is not present and there is no session key, the COMPILE statement uses the default key. If the default key does not match the source file key, then the compilation fails with an error message. If a session key is in effect and you want a COMPILE statement to use the default key, then you must unset the XCODE-SESSION-KEY attribute by setting it to the Unknown value (?) before executing the COMPILE statement.
  • The XCODE utility does not perform code page conversions and does not use the -cpinternal parameter when encrypting files. Therefore, the source code and key will use the default code page of the operating system where you run the XCODE utility. If a different code page is in effect where XCODE-SESSION-KEY is set, then code page conversions may prevent the attribute key from matching the XCODE utility key and the compile fails. To prevent this case, use only US-ASCII characters, which are found in all code pages below code point 128.

Include files that are not encrypted are included and compiled in the standard manner.

Having the decryption key does not allow you to examine a decrypted version of the source code.

Note: You cannot use XCODE with the XREF, XREF-XML, STRING-XREF, or LISTING options together. Also, if the DEBUG-LIST option is used with an encrypted source file, the resulting debug file will only contain a notice that the source file is encrypted.
XREF {xreffile| VALUE ( expression ) } [ APPEND [ = logical-expression ] ]
Returns reference information on ABL elements, cross-references between procedures and ABL objects, and cross-references between class or interface definition files and ABL objects. See Table 1 for more information on the type of reference information returned.

Information can be written to the file xreffile or VALUE ( expression ). If expression returns the Unknown value (?), then ABL ignores the XREF option.

In addition, you can use the APPEND option to add information to an existing file. When you use APPEND, the first line for a procedure contains information for the COMPILE 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 logical-expression is evaluated to the Unknown value (?), a run-time error occurs.

XREF generates one unformatted, white space-separated line in xreffile for each referenced element. Each line has the following format:

source-namefile-nameline-numberxref-typexref-information

The source-name is the name of the procedure or class file you compile with the COMPILE XREF statement. The file-name is the name of the file containing the referenced element. For example, file-name could be an include file. Otherwise, file-name is the same as source-name. The line-number is the line number of the statement in file-name that contains the referenced element. The xref-type is the type of reference in the code and xref-information contains details about the reference.

The possible values for xref-type and xref-information appear in the following table.

XREF types and XREF information
XREF type XREF information

ACCESS

{[ DATA-MEMBER ][database. ]tablefield
[ WORKFILE | TEMPTABLE ]}|
{ SHARED variable }|
{ PUBLIC-DATA-MEMBER 
class-name:data-member-name }|
{ INHERITED-DATA-MEMBER 
class-name:data-member-name }|
{ PUBLIC-PROPERTY 
class-name:property-name}|
{ INHERITED-PROPERTY 
class-name:property-name} |
{sequence-name SEQUENCE }

ANNOTATION

string

BLOCK-LEVEL

ON ERROR UNDO, THROW1 [ (-undothrow)2 ]

CAST

[ FROM source-class-name ] 
TO target-class-name

CLASS

class-name,[ INHERITS inherited-class-name 
[ (inherited-class-name ...) ] ], 
[ IMPLEMENTS interface-name 
[ interface-name] ... ], 
[ USE-WIDGET-POOL ], [ FINAL ], [ ABSTRACT ],
[ SERIALIZABLE ]

COMPILE

procedure|class-file

CONSTRUCTOR

{{ PUBLIC, | PROTECTED, }
|{ , STATIC }},,,constructor-name,
void, [parameter1[ , parameter2 ]...]

CPINTERNAL

code-page-name-that-ABL-uses-in-memory

CPSTREAM

code-page-name-that-ABL-uses-for-stream-I/O

CREATE

{[ DATA-MEMBER | INHERITED-DATA-MEMBER ]
class-name:table-name}|
[database. ]table [ WORKFILE |
TEMPTABLE ]}

DATA-MEMBER

{ PUBLIC | PROTECTED }, [ STATIC ],
[ TEMPTABLE | BUFFER | QUERY | 
DATASET | DATASOURCE ],
data-member

DATASET

dataset-name, { PROTECTED },
[ REFERENCE-ONLY ],
[ NAMESPACE-URI namespace],
[ NAMESPACE-PREFIX prefix ],
buffer-name1[[ buffer-name2]...], [DATALINKS]

DELETE

{[ DATA-MEMBER | INHERITED-DATA-MEMBER ]
class-name:table}|
[ database. ]table[ WORKFILE | TEMPTABLE ]

DELETE-INSTANCE

class-name

DESTRUCTOR

PUBLIC,,,,destructor-name,void,

DLL-ENTRY

procedure-name,,
[parameter1 [ , parameter2 ]...]

EXTERN

function-name,return-type,
[parameter1 [ , parameter2 ]...]

EVENT

{ PUBLIC | PROTECTED }, [ STATIC ],
[ OVERRIDE ],,[ ABSTRACT ], event-name,
[delegate-type-name ], return-type,
[parameter1 [ , parameter2 ]...]

FOR EACH: JOIN BY SQLDB

Not applicable (Data Servers only)

FUNCTION

function-name,return-type,
[parameter1 [ , parameter2 ]...]

GLOBAL-VARIABLE

global-variable

INCLUDE

include-file-name

INTERFACE

interface-type-name,
[ INHERITS interface-type-name
   [ (interface-type-name...)]],,,

INVOKE

class-name:method-name
[ , invocation-parameter1
[ , invocation-parameter2 ]...]

METHOD

{ PUBLIC | PROTECTED }, [ STATIC ],
[ OVERRIDE ], [ FINAL ], [ ABSTRACT ],
method-name, return-type,
[parameter1 [ , parameter2 ]...]

NEW

class-name [ , invocation-parameter1
[ , invocation-parameter2]...]

NEW-SHR-DATASET

dataset-name, { PROTECTED },
[ REFERENCE-ONLY ],
[ NAMESPACE-URI namespace],
[ NAMESPACE-PREFIX prefix ],
buffer-name1[[ buffer-name2 ]...],
[ DATALINKS ]

NEW-SHR-FRAME

new-shared-frame

NEW-SHR-TEMPTABLE

temptable-name

NEW-SHR-VARIABLE

new-shared-variable

NEW-SHR-WORKFILE

new-shared-workfile
[ LIKE [database. ]table ]

PROCEDURE3

procedure-name,,
[parameter1 [ , parameter2 ]...]

PRIVATE-FUNCTION

function-name, return-type,
[parameter1[ , parameter2 ]...]

PRIVATE-PROCEDURE

3
procedure-name,,
[parameter1 [ , parameter2]...]

PROPERTY

{ PUBLIC | PROTECTED }, [ STATIC ],
[ OVERRIDE ],,[ ABSTRACT ], property-name

PUBLISH4

[class-name: ]event-name| (exp)

REFERENCE

{[ database. ]table [ field ]
[ WORKFILE ]}|{ SHARED variable |
{[ DATA-MEMBER | INHERITED-DATA-MEMBER ]
class-name:table[field ]}

ROUTINE-LEVEL

ON ERROR UNDO, THROW1 [ (-undothrow)2 ]

RUN3

procedure-name |value(exp)
[ PERSISTENT | REMOTE | SINGLE-RUN | SINGLETON |
SUPER | STORED-PROC ]

SEARCH5

{[ database. ]table|
{[ DATA-MEMBER | INHERITED-DATA-MEMBER ]
class-name:table }}{ WORKFILE |
{{index| RECID }[ TEMPTABLE ]
[ WHOLE-INDEX | TABLE-SCAN ]}}

SHR-DATASET

dataset-name, { PROTECTED },
[ REFERENCE-ONLY ],
[ NAMESPACE-URI namespace],
[ NAMESPACE-PREFIX prefix ],
buffer-name1[[ buffer-name2 ]...],
[ DATALINKS ]

SHR-FRAME

shared-frame

SHR-TEMPTABLE

temptable-name

SHR-WORKFILE

shared-workfile[ LIKE [ database. ]table]

SORT-ACCESS

{[ database. ] tablefield
[ WORKFILE | TEMPTABLE ]}

SORT-BY-EXP

{ FOR EACH | OPEN QUERY }table BY expression

STRING

char-string max-length justification
translatable [ FORMAT ]

SUBSCRIBE6

[class-name: ]event-name | (exp)
[ , [class-name: ]handler-name 
[ , parameter1 [ , parameter2]...]]

UNSUBSCRIBE6

[class-name: ]event-name | (exp) | ALL
[ , [class-name: ]handler-name 
[ , parameter1 [ , parameter2]...]]

UPDATE

{[ DATA-MEMBER ][ database. ] table field
[ WORKFILE | TEMPTABLE ]}|
{ SHARED variable }|
{ PUBLIC-DATA-MEMBER
class-name:data-member-name }|
{ INHERITED-DATA-MEMBER
class-name:data-member-name }|
{ PUBLIC-PROPERTY
class-name:property-name}|
{ INHERITED-PROPERTY
class-name:property-name}|
{sequence-name SEQUENCE }

This is the syntax for data-member-name:

variable-name|{[ dataset-name]table[ field ]}

This is the syntax for invocation-parameter:

{ INPUT | INPUT-OUTPUT | OUTPUT }
{ [data-type[ EXTENT [constant]]|
   TABLE temp-table-name|
   TABLE-HANDLE |
   DATASET dataset-name|
   DATASET-HANDLE |
   TABLE-REFERENCE |
   DATASET-REFERENCE|
   RUNTYPE }

The invocation parameters will be listed for every constructor or method invocation that has arguments. If a method or constructor is overloaded, invocation parameters can be used to determine which version of the method or constructor is being invoked. If the compiler has not resolved the method call (that is, it has deferred resolution to run time), one or more of the invocation parameters may be identified as TABLE REFERENCE, DATASET REFERENCE, or RUNTYPE. This label indicates that the argument being passed matches the type of the corresponding parameter in more than one of the candidate overloads.

In the case of TABLE REFERENCE or DATASET REFERENCE, the parameter may be a static temp table or dataset or a handle to a temp table or dataset.

RUNTYPE means that the compiler cannot determine the type because the argument is, for example, BUFFER-FIELD(1):BUFFER-HANDLE.

EXTENT without a constant integer value following it may simply mean that the parameter is defined as indeterminate, or it may mean that the call has not been resolved and the candidate overloads have arrays of different extents at that position in the parameter list.

The following notes describe more usage information for Table 1:

  • PUBLIC-DATA-MEMBER indicates that a line of code in a client of a class references a class public data member through an object reference. For example: localvar = MyInstance:PubMember. Properties are treated similarly.
  • In contrast to PUBLIC-DATA-MEMBER, INHERITED-DATA-MEMBER indicates that a line of code references a data member inherited by the class in which the reference appears. DATA-MEMBER in an UPDATE or ACCESS entry indicates that a line of code references a temp-table or related object that has been defined in the class in which the reference appears. Properties are treated similarly.
  • There will be quotes around the name of a class or interface if its package name includes a space.
  • In the CLASS entry, INHERITS inherited-class-name indicates the immediate super class of the class, if any exists. If the super class inherits from one or more classes, the names of these classes will appear following the name of the immediate super class of the compiled class. Each inherited class name will be separated from the preceding one by a space.
  • XREF output includes "STRING" reference type entries. In addition to the strings that are already logged (variable names, function and procedure names, and so on), the XREF output will now include "STRING" reference type entries for class names, inherited class names, implemented interface names, method names, property names, and data member names.
  • If a class has a super class but does not explicitly execute the SUPER statement in its constructor, the ABL compiler adds an implicit SUPER invocation to the r-code. When this happens, there will be an INVOKE entry generated for the implicit SUPER invocation. This entry indicates that the name of the method being invoked is super-class-type-name:class-name (the constructor name). Instead of a line number, the entry will use the label IMPLICIT.
  • As is the case with PROCEDUREs and FUNCTIONs, the entry for a method, constructor, or destructor will be made during compilation of the element's END statement. Therefore, a METHOD entry will appear after the entries for items encountered within the method, and the line number given will be the line number of its END statement.
  • Note that field for REFERENCE is optional. It will not appear if the corresponding line of code is either VALIDATE temp-table or RELEASE temp-table.
  • If a class has as a data member an ABL handle and code uses that handle to call a built-in ABL method or to set or get a built-in attribute, the XREF output will include just an ACCESS entry and the entry will identify only the name of the handle data member, not the method or attribute involved. (This is similar to how XREF handles SHARED variables that are handles.)
  • The XREF entry for CAST will include the source type if it is possible to determine the source type at compile time. If not, it will include only the target type.
  • Temp-tables must be shared to be included in XREF output. Locally defined temp-tables are not considered cross-referenced objects and are therefore not included in XREF output.
Note: You cannot use the XREF and XCODE options together. That is, you cannot create a cross-reference listing from code that is encrypted.
XREF-XML { directory |filename | VALUE ( expression ) }
Writes reference information to a formatted XML file. The standard XREF option writes the information to an unformatted text file. The XREF-XML option provides structured output that is formatted with white space for easier parsing by humans. More importantly, this option exposes the reference information in a format that developers can exploit with custom-built tools or visualize in a ProDataset or a .NET dataset.

Table 1 and the accompanying documentation in the XREF option section describes the XREF type and XREF information returned by either the XREF or the XREF-XML options. When you use XREF-XML, the XREF type is assigned to the Reference-type attribute. However, XREF information can be assigned to a number of XML elements including the Object-identifier attribute.

For compiling a single procedure or class, you can provide a filename for the XML output file. However, this output file is overwritten each time the compiler needs to compile a linked class or procedure.

For compiling several procedures and classes in a single compile statement, supply a directory for the XREF-XML option. The XREF-XML option uses this directory and a standard naming convention to capture the cross-reference information from multiple procedures and classes in separate files. Contrast this with the APPEND mode used by the XREF option.

When a directory is supplied, the compiler takes the root name of the procedure or class being compiled and creates a cross-reference file with this name and a .xref.xml file extension (sourcefilename.xref.xml). It stores it in the directory path specified, creating any necessary subdirectories that do not exist. If the main directory specified does not exist, then an error is raised.

If the filename supplied to the compiler begins with a relative path, then the directory name supplied to the XREF-XML option will include that relative path. For example, suppose your Unix PROPATH is /projectA/source and you run this COMPILE statement:

COMPILE test/procedureA.p XREF-XML /projectA/xref

The COMPILE statement will look for the source file /projectA/source/test/procedureA.p and place the XREF-XML output in /projectA/xref/test/procedureA.xref.xml (if the source file successfully compiles).

If the source file uses a full path, then the XREF-XML option stores the output in the directory provided, ignoring the path of the source file.

You may want to check for possible filename collisions before using this option. For example, if you have myCode.p and myCode.cls, both will use the myCode.xref.xml output file, destroying some of your cross-reference information.

When you use the VALUE option to provide a filename or directory path, if VALUE returns the empty string or the Unknown value (?), then the compiler ignores the XREF-XML option.

If class definition source files in a class hierarchy are in different directories, matching subdirectories will be created for them under the provided XREF-XML directory.

The XML Schema used with XREF-XML output files is stored in the following location: $DLC/properties/schemas/xrefdxxxx.xsd. The XXXX portion of the file name indicates the version number of the file.

You can see an example on the difference between XREF and XREF-XML output in the Examples section at the end of the COMPILE statement reference.

Note: You cannot use the XREF-XML option with the XREF option or with the XCODE option at the same time.
STRING-XREF {sxreffile | VALUE ( expression ) } [ APPEND [logical-expression ] ]
Writes cross-reference string information between procedures and ABL objects, or between class definition files and ABL objects, to the file sxreffile or VALUE ( expression ). If expression evaluates to the Unknown value (?), ABL ignores the STRING-XREF option.
String Xref Version x.ysource-filecode-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 values in the following table 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 values in the following table 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.

The following table shows the valid combinations of statement types and detail tags.

Valid statement type and detail tag combination
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
STREAM-IO [ = logical-expression ]
Specifies that all output from the compiled procedure or class 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.
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 ABL 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. For example:

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. For example:

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 ABL 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, ABL increases the size of the text strings when it compiles your application.

ABL uses the following formula to determine the length of strings:

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

Where:

  • New-length is the new string length.
  • Actual-length is the actual string length.
  • growth-factor is the value specified with the TEXT-SEG-GROW option.
  • table-value is the appropriate percentage from the following table:
    String length Expansion percentage
    1-10 characters 200%
    11-20 characters 100%
    21-30 characters 80%
    31-50 characters 60%
    51-70 characters 40%
    More than 70 characters 30%

For example, if you have a text string that is 25 characters and you specify a growth-factor of 50, ABL applies the formula as follows and defines the New-length as 35:

New-length = 25 * ( 1 + (80/100 * (50/100)) )
Note: TEXT-SEG-GROW is supported only when you also use the LANGUAGES option.
DEBUG-LIST {debugfile| VALUE ( expression ) }
Writes the debug listing to the file debugfile or VALUE ( expression ). If expression evaluates to the Unknown value (?), then ABL 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. In Windows, the filename cannot contain characters outside of the non-Unicode code page.
PREPROCESS {preprocessfile| VALUE ( expression ) }
Preprocesses the procedure or class definition file and writes the preprocessed source code to the file preprocessfile or VALUE ( expression ). If expression evaluates to the Unknown value (?), ABL 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. In Windows, the filename cannot contain characters outside of the non-Unicode code page.
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 in 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:

  • USE-REVVIDEO displays no border around a fill-in field. When a fill-in is enabled for input, the color of the fill-in changes to the color specified with the INPUT setting in the [Colors] section in the current environment (which might be the registry or an initialization file). The IBEAM cursor signals that a fill-in field has input focus.
  • USE-UNDERLINE displays no border around a fill-in widget. When a fill-in is enabled for input, the underline attribute of the font (V6FontNumber) for the fill-in is turned on. The color of a fill-in enabled for input does not change. The IBEAM cursor signals that a fill-in field has input focus.

The V6FRAME option also limits the vertical size of a frame title to one character unit based upon the layout grid. The text of the frame title is in the font specified with the V6FontNumber setting in the [Startup] section of the current environment (which might be the registry or an initialization file).

The V6FRAME option governs the appearance of screen output only. Use the STREAM-IO option to compile procedures that output to files and printers. If you specify the V6FRAME and STREAM-IO options in the same COMPILE statement, the STREAM-IO option overrides the V6FRAME option.

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

For more information on the environment for an ABL session, see OpenEdge Deployment: Managing ABL Applications.

MIN-SIZE [ = logical-expression ]
Minimizes the size of the generated r-code file by eliminating the Debugger Segment (which is used by the OpenEdge 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 ABL compiles a procedure or class definition file 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.

You can read the MD5-VALUE attribute on the RCODE-INFO system handle to determine the MD5 value for a procedure or class.

This option is supported for WebClient only (that is, only WebClient uses the resulting MD5 value). Progress Software Corporation 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.

ATTR-SPACE [ = logical-expression ]
Has no effect; supported only for backward compatibility.
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.

Examples

In this procedure, ABL compiles the ord-ent procedure, produces an r-code file, ord-ent.r, that can be used across ABL sessions, and saves the r-code file in the current directory:

r-cmple.p

COMPILE ord-ent SAVE.
Note: The sample procedures supplied with ABL do not include the ord-ent procedure.

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 ord-ent SAVE INTO /usr/sources.

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

r-incl.p

FOR EACH Customer NO-LOCK:
  {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 NO-LOCK:
      4   1   {r-fcust.i}
 1    1   1 /* r-fcust.i */
 1    2   1 
 1    3   1 FORM Customer.CustNum 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.CustNum 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: sports2000.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 sports2000.Customer CustNum
r-incl.p r-incl.p 4 INCLUDE r-fcust.i
r-incl.p r-fcust.i 3 ACCESS sports2000.Customer CustNum 
r-incl.p r-fcust.i 3 ACCESS sports2000.Customer Name 
r-incl.p r-fcust.i 3 ACCESS sports2000.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 sports2000.Customer CustNum 
r-incl.p r-dcust.i 3 ACCESS sports2000.Customer Name 
r-incl.p r-dcust.i 3 ACCESS sports2000.Customer Phone 
r-incl.p r-incl.p 6 STRING "CustNum" 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 "CustNum" 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 1 for a list of the values that follow a particular access type (for example, table and index after SEARCH).

If you modified r-comlis.p to use the XREF-XML option instead of XREF, your cross reference file would be named r-comlis.xref.xml. The structured formatting of XML would use many more lines to display the same information on one line of standard XREF output. Here is a small snippet of that file:

...
<Reference Reference-type="INCLUDE" Object-identifier=""c:\openedge\wrk\r-fcust.i""> 
  <Source-guid>9+5Nn2plMK7bEdVPTNq+Gw</Source-guid> 
  <File-num>1</File-num> 
  <Ref-seq>6</Ref-seq> 
  <Line-num>4</Line-num> 
  <Object-context /> 
  <Access-mode /> 
  <Data-member-ref /> 
  <Temp-ref /> 
  <Detail /> 
  <Is-static>false</Is-static>
  <Is-abstract>false</Is-abstract>
</Reference>
<Reference Reference-type="INCLUDE" Object-identifier=""c:\openedge\wrk\r-dcust.i""> 
  <Source-guid>9+5Nn2plMK7bEdVPTNq+Gw</Source-guid> 
  <File-num>1</File-num> 
  <Ref-seq>13</Ref-seq> 
  <Line-num>5</Line-num> 
  <Object-context /> 
  <Access-mode /> 
  <Data-member-ref /> 
  <Temp-ref /> 
  <Detail /> 
  <Is-static>false</Is-static>
  <Is-abstract>false</Is-abstract>
</Reference> 
<Reference Reference-type="STRING" Object-identifier="Cust Num"> 
  <Source-guid>9+5Nn2plMK7bEdVPTNq+Gw</Source-guid> 
  <File-num>1</File-num> 
  <Ref-seq>17</Ref-seq> 
  <Line-num>6</Line-num> 
  <Object-context /> 
  <Access-mode /> 
  <Data-member-ref /> 
  <Temp-ref /> 
  <Detail /> 
  <Is-static>false</Is-static>
  <Is-abstract>false</Is-abstract>
  <String-ref> 
    <Source-guid>9+5Nn2plMK7bEdVPTNq+Gw</Source-guid> 
    <Ref-seq>17</Ref-seq> 
    <Max-length>8</Max-length> 
    <Justification>LEFT</Justification> 
    <Translatable>true</Translatable> 
  </String-ref> 
</Reference>
...

This is the debug listing r-incl.dbg:

r-incl.dbg

 1   /* r-incl.p */
 2
 3   FOR EACH Customer NO-LOCK:
 4
 5   /* r-fcust.i */
 6 
 7   FORM Customer.CustNum Customer.Name LABEL "Customer
 8         Name" Customer.Phone FORMAT "999-999-9999". 
 9                 
10
11   /* r-dcust.i */
12
13  DISPLAY Customer.CustNum Customer.Name Customer.Phone
14
15   END.

For a class that implements an interface hierarchy or an interface that inherits an interface hierarchy, the whole of the hierarchy appears in the XREF and XREF-XML as a complete list. The following example illustrates the comparison of XREF output both with and without interface inheritance.

XREF output without interface inheritance

INTERFACE interface-name,,,,

XREF output with interface inheritance

INTERFACE interface-name,INHERITS acme.inventory.IWarehouse
(acme.inventory.IStoreRoom acme.inventory.IShelf),,,,

Because interfaces support multiple inheritance, the order of the interface hierarchy cannot be determined.

The following example is for the XREF-XML output both with and without interface inheritance.

XREF-XML output without interface inheritance

<Reference Reference-type="INTERFACE" Object-identifier="interface-name">
  <Source-guid>7mu7M0PmmZ0R3/Mtc60gbA</Source-guid>
  <File-num>1</File-num>
  <Ref-seq>4</Ref-seq>
  <Line-num>4</Line-num>
  <Object-context/>
  <Access-mode/>
  <Data-member-ref/>
  <Temp-ref/>
  <Detail/>
  <Is-static>false</Is-static>
  <Is-abstract>false</Is-abstract>
  <Interface-ref>
    <Source-guid>7mu7M0PmmZ0R3/Mtc60gbA</Source-guid>
    <Ref-seq>4</Ref-seq>
    <Inherited-list/>
  </Interface-ref>
</Reference>

XREF-XML output with interface inheritance

<Reference Reference-type="INTERFACE" Object-identifier="interface-name">
  <Source-guid>7mu7M0PmmZ0R3/Mtc60gbA</Source-guid>
  <File-num>1</File-num>
  <Ref-seq>4</Ref-seq>
  <Line-num>4</Line-num>
  <Object-context/>
  <Access-mode/>
  <Data-member-ref/>
  <Temp-ref/>
  <Detail/>
  <Is-static>false</Is-static>
  <Is-abstract>false</Is-abstract>
  <Interface-ref>
    <Source-guid>7mu7M0PmmZ0R3/Mtc60gbA</Source-guid>
    <Ref-seq>4</Ref-seq>
    <Inherited-list/>acme.inventory.IWarehouse(acme.inventory.IStoreRoom 
    acme.inventory.IShelf)]</Inherited-list>
  </Interface-ref>
</Reference>

Notes

See also

COMPILER system handle, NEW function (classes), RUN statement, Compile Warning List (-cwl), Keyword Forget List (-k), and No Lock (-NL) startup parameters (in OpenEdge Deployment: Startup Command and Parameter Reference)