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.

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 Develop ABL Applications. For more information about compiling class definition files, see Develop Object-oriented ABL Applications.

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 ] ]
  [ DEFAULT-UNTRANSLATABLE [ = 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 Internationalize ABL 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 Internationalize ABL 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[:Error |:Warning ]	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. Optionally set severity level to Warning or Error.
require-field-qualifiers[:Error |:Warning ]	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. Optionally set severity level to Warning or Error.
require-full-keywords[:Error |:Warning ]	All language keywords must be fully spelled out. Optionally set severity level to Warning or Error.
require-return-values[:Error |:Warning ]	In user-defined functions, non-VOID methods, and property getters, all logical code paths must have RETURN value statements. For more information, see Require-return-values compiler option. Optionally set severity level to Warning or Error.

Note that the severity level specifies what happens when there is a failure:

• Error generates a message for each failure, and prevents the generation of r-code.
• Warning generates a message for each failure, but allows the generation of r-code, provided that the only failures during compilation are related to the option. (Other types of failure can prevent r-code generation.)
• If no severity level is specified, the default is Warning.

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

COMPILE myproc.p OPTIONS "require-field-qualifiers:Error,require-full-names".

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 compiles without error if the code is compiled using the statement above.

/* Accessing the field "tcfield" in the table "tbhelper" */ tbhelper.tcfield = "doUpdate". /* The following does not compile with "require-field-qualifiers:Error" in effect. */ tcfield = "doUpdate". /* The following compiles with "require-full-names" with default severity level in effect but warning messages are generated. */ 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 are 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 fails 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 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 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 SAVE or STREAM-IO options are 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.

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 is 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 object-oriented ABL reference in a procedure or class that is not in the class hierarchy.

Note: The XCODE option is not supported when FIPS mode is enabled. Compilation of encrypted source code will fail with an error. This behavior impacts the functionality of Data Administration dump or load utilities. To work around this limitation, you can:

• Use ABL code for Data Administration operations while FIPS mode is enabled.
• Perform binary dump or load using the PROUTIL utility when FIPS mode is enabled.
• Run Data Administration utilities in environments where FIPS mode is disabled.

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 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 only contains 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-name file-name line-number xref-type xref-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.

Table 1. 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 }| { PACKAGE-PROTECTED-DATA-MEMBER class-name:data-member-name }| { PACKAGE-PRIVATE-DATA-MEMBER class-name:data-member-name }| { INHERITED-DATA-MEMBER class-name:data-member-name }| { PUBLIC-PROPERTY class-name:property-name}| { PACKAGE-PROTECTED-PROPERTY class-name:property-name }| { PACKAGE-PRIVATE-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|PACKAGE-PROTECTED|PROTECTED|PACKAGE-PRIVATE} |{ , 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|PACKAGE-PROTECTED|PROTECTED|PACKAGE-PRIVATE}, [ 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|PACKAGE-PROTECTED|PROTECTED|PACKAGE-PRIVATE}, [ 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|PACKAGE-PROTECTED|PROTECTED|PACKAGE-PRIVATE}, [ 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|PACKAGE-PROTECTED|PROTECTED|PACKAGE-PRIVATE} [ STATIC ], [ OVERRIDE ], [ FINAL ] ,[ 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 }| { PACKAGE-PROTECTED-DATA-MEMBER class-name:data-member-name }| { PACKAGE-PRIVATE-DATA-MEMBER class-name:data-member-name }| { INHERITED-DATA-MEMBER class-name:data-member-name }| { PUBLIC-PROPERTY class-name:property-name}| { PACKAGE-PROTECTED-PROPERTY class-name:property-name }| { PACKAGE-PRIVATE-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 are 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, PACKAGE-PROTECTED-DATA-MEMBER, and PACKAGE-PRIVATE-DATA-MEMBER indicate 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 are 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 appear following the name of the immediate super class of the compiled class. Each inherited class name is 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 now includes "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 is 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 uses the label IMPLICIT.
• As is the case with procedures and functions, the entry for a method, constructor, or destructor is made during compilation of the element's END statement. Therefore, a METHOD entry appears after the entries for items encountered within the method, and the line number given is the line number of its END statement.
• Note that field for REFERENCE is optional. It does 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 includes just an ACCESS entry and the entry identifies 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 includes the source type if it is possible to determine the source type at compile time. If not, it includes only the target type.

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 includes 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 looks 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 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 are 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 is not 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 appears 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.

Table 2. 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.

Language-list is a comma-separated list of language definitions used to generate each text segment. Each language definition consists of a colon-separated list of languages, in order of preference, used to find the translation of each string stored in the text segment.

Expression (in VALUE(expression)) is a character expression equivalent to the language-list. 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 Manage 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.

DEFAULT-UNTRANSLATABLE [ = logical-expression ]

If the logical-expression evaluates to YES/TRUE, then literal character strings with no string attributes are considered untranslatable. This is the same behavior as if the string:U syntax is used (see " "Character-string literal for more information on string attributes).

If the option is not specified, or DEFAULT-UNTRANSLATABLE=FALSE, then literal character strings with no attributes are considered translatable.

If the logical-expression evaluates to the Unknown value (?), a run-time error occurs.

The following code example describes the behavior if the DEFAULT-UNTRANSLATABLE option is not specified or if set to NO/FALSE.

/* Behavior without DEFAULT-UNTRANSLATABLE */ VAR CHARACTER str. /* If :U not specified, we assume it's translatable. */ str = "Hello!". /* :U means untranslatable. */ str = "Hi there!":U. /* In this case, the compiler will not be able to put the strings together if either string is translatable. */ str = "Hello " + "World!".

The following code example describes the behavior if DEFAULT-UNTRANSLATABLE is set to YES/TRUE.

/* Behavior with DEFAULT-UNTRANSLATABLE=TRUE */ VAR CHARACTER str. /* Because of DEFAULT-UNTRANSLATABLE, it's marked as untranslatable. */ str = "Hello!". /* :U means untranslatable. */ str = "Hi there!":U. /* In this case, the compiler will be able to put the strings together because both are untranslatable. */ str = "Hello " + "World!".

Note: The Default Untranslatable (-defuntrans) startup parameter can be used to enable the untranslatable behavior for compiles during the session.

NO-ERROR

The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.

You can also check the ERROR and WARNING attributes of the COMPILER system handle to determine whether an error or warning occurred.

Examples

Example 1: COMPILE with SAVE option

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.

Example 2: COMPILE with SAVE INTO option

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.

Example 3: COMPILE with SAVE INTO option for class files

CLASS Classes.OE.myClass1:

COMPILE "/source/Classes/OE/myClass1.cls" SAVE INTO "/rcode".

The .r file is saved into /rcode/Classes/OE.

CLASS myClass2:

COMPILE "/source/Classes/OE/myClass2.cls" SAVE INTO "/rcode".

ABL saves the .r file into /rcode. No subdirectories are created because myClass2.cls is in the default package.

Example 4: COMPILE with SAVE, LISTING, XREF, XREF-XML, and DEBUG-LIST options

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 listing contains 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: Sports2020.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:

• Line — The line number where the block starts
• Blk. Type — The type of block (Procedure, DO, FOR EACH, REPEAT)
• Tran — Whether the block is a transaction block
• Blk. Label — The label of the block
• Buffers — The name of the record buffer scoped to the block
• Frames — The name of the frame scoped to the block

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 Sports2020.Customer CustNum
r-incl.p r-incl.p 4 INCLUDE r-fcust.i
r-incl.p r-fcust.i 3 ACCESS Sports2020.Customer CustNum 
r-incl.p r-fcust.i 3 ACCESS Sports2020.Customer Name 
r-incl.p r-fcust.i 3 ACCESS Sports2020.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 Sports2020.Customer CustNum 
r-incl.p r-dcust.i 3 ACCESS Sports2020.Customer Name 
r-incl.p r-dcust.i 3 ACCESS Sports2020.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

• When compiling class definition files, the following options apply to the class definition file identified in the COMPILE statement and all class files in its inherited class hierarchy: XCODE, STREAM-IO, LANGUAGES, V6FRAME, and MIN-SIZE.
• When compiling class definition files, the following options apply only to the class definition file identified in the COMPILE statement, and not to the class files in its inherited class hierarchy: PREPROCESS, LISTING, DEBUG-LIST, XREF, and STRING-XREF.
• If you want all record retrieval statements in a procedure to default to NO-LOCK, you must compile the procedure in an ABL session started with the No Lock (-NL) startup parameter. For more information on record locking, see Develop ABL Applications. For more information on the No Lock (-NL) startup parameter, see Startup Command and Parameter Reference.
• Two additional startup parameters are available that can affect the behavior of the COMPILE statement: Compile Warning List (-cwl) and Keyword Forget List (-k). The Compile Warning List option lets you specify a set of ABL statements that trigger compile-time warnings if they are found in the source code. The Keyword Forget List option lets you disable specified keywords, allowing you to compile code in which those keywords occur as ABL user-defined element names, such as table, field, variable, and procedure names. For more information about these startup parameters, see Startup Command and Parameter Reference.
• The value of the PROPATH environment variable defines the list of directories (path) to use when searching for a procedure.
• The ABL compiler does not search libraries for include files referenced in a procedure.
• On UNIX, you define the PROPATH variable in a startup script or in your .profile file. In Windows, you can define your PROPATH in the Registry or in an initialization file. You can also define the PROPATH interactively at the operating system level.

  In addition to any directories you define for PROPATH, ABL searches the directory containing the ABL system software. If you do not define a value for PROPATH, ABL searches your working directory by default.

• To locate the source file that you name in the COMPILE SAVE statement, ABL searches the first directory in PROPATH. If the source file is there, ABL compiles the source file and creates an r-code file. On UNIX, this new r-code file replaces any existing r-code file. If errors occur during compilation, ABL does not produce an r-code file and leaves existing r-code files unchanged.

  If ABL cannot find the source file, it continues on to the next directory in PROPATH.

• Use the SAVE INTO phrase to store a compiled r-code file in a different directory from its corresponding source file.

  If you specify a relative pathname for the source file, that pathname is appended to the SAVE INTO path. For example (using UNIX pathnames):

  PROPATH="/pro1/source". COMPILE test/proc1.p SAVE INTO /pro1/obj.

  In the example, ABL saves the source file /pro1/source/test/proc1.p as /pro1/obj/test/proc1.r.

  If the source file is a full pathname, ABL stores the r-code file in the SAVE INTO directory; it drops its original directory path. For example:

  COMPILE /pro1/obj/test/proc1.p SAVE INTO /usr/rcode.

  In the example, ABL saves the source file as /usr/rcode/proc1.r.

  When you use the SAVE INTO phrase to store compiled r-code files for one or more class definition files specified with a package, ABL creates a directory structure under the specified SAVE INTO directory that is consistent with the directory structure of the original source files relative to PROPATH (if the directory structure doesn't already exist). That is, ABL creates a subdirectory under the specified SAVE INTO directory to match the original source directory for each class definition file in the hierarchy.

  For example, if the source for two class definition files in a class hierarchy reside in two different directories, such as dir1 and dir2, ABL creates two matching subdirectories named dir1 and dir2 under the specified SAVE INTO directory and stores the r-code files in their respective subdirectories.

  If the SAVE INTO pathname is null, ABL saves r-code files in the same directory as their source files.

• To locate a file with the COMPILE statement (without the SAVE phrase), ABL searches the first directory in PROPATH for a usable r-code file. A usable r-code file must meet these criteria:
  • It must have the correct format; it must have been produced by the COMPILE SAVE statement.
  • It must have been produced by the current version of the ABL compiler.
  • It must have the same cyclic redundancy check (CRC) value as any database tables it references. When creating an r-code file, ABL includes, as part of the r-code file, the CRC of the most recent change to the database schema that affects this procedure (for example, adding or deleting a field or index definition in a table that the procedure references).
  • On UNIX, it must have read access to the r-code file.

  If there is a usable r-code file, there is no reason to perform the compilation. You receive an error and the compilation stops unless you have specified the XREF, LISTING, PREPROCESS, or DEBUG-LIST option. If you specified one of these options, ABL continues with the compilation and produces the files specified and a session compile. If ABL does create a session compile version, the version is not used when you use the RUN statement. The RUN statement always uses an existing r-code file before using a session compile version of a procedure.

  If there is no usable r-code file, ABL searches the same directory in PROPATH for a source file. If the source file is there, ABL compiles it into the session compile file. If it is not there, ABL continues on to the next directory in PROPATH, searching for an r-code file, then for a source file.

• After you compile a procedure, the RUN statement does not recompile it. If you RUN a procedure multiple times within a session, changing the procedure between runs, you must manually recompile the procedure each time. Otherwise, the procedure's last r-code, which persists for a session, is found and the procedure is not automatically recompiled.
• The size of the r-code might vary, depending on the window system on which it is compiled.
• Modifications to existing field definitions do not affect database table CRC or time-stamp values. Therefore, updating a table's existing field definitions does not invalidate r-code versions of procedures that reference the table. However, adding or deleting tables, fields, or indexes does affect database table CRC and time stamps. This invalidates r-code versions of procedures that reference the changed tables.
• When you use a reserved keyword to specify a language with the LANGUAGES option, you must use quotation marks (" ") around the language-list.
• The SORT-BY-EXP reference in the XREF is used to indicate a FOR EACH or OPEN QUERY statement which contains a BY clause which uses an expression.
• A WHOLE-INDEX search reported for a table occurs when an entire index is used to search the table. (That is, the bracket used by the query to search the table spans the entire index.) This can occur either when no selection criteria are specified to limit the range of index keys searched (that is, to bracket a subset of the index) or when there is no appropriate index available to optimize the selection criteria. For example, the following queries on Customer table of the Sports2020 database both result in WHOLE-INDEX searches. The first query uses the Name index to search the entire table, returning every record in Name order. The second query uses the primary index to search the entire table because there is no index provided for the Balance field to limit the search.

  FOR EACH Customer NO-LOCK USE-INDEX Name:   DISPLAY Customer. END. FOR EACH Customer NO-LOCK WHERE Customer.Balance < 10000   AND Customer.Balance > 5000:   DISPLAY Customer. END.

  On the other hand, the following queries do not result in WHOLE-INDEX searches because the selection criteria directly limit the range of Name and CustNum index keys (respectively) to be searched:

  FOR EACH Customer NO-LOCK   WHERE Customer.Name < "Penan Sporttiklubi"     AND Customer.Name > "Chip's Poker":   DISPLAY Customer. END. FOR EACH Customer NO-LOCK WHERE Customer.CustNum < 40:   DISPLAY Customer. END.

• For SpeedScript, the following options are invalid: V6FRAME, USE-REVVIDEO, and USE-UNDERLINE.
• When ABL compiles a procedure or class definition file, it generates a unique signature value based on the code content and the schema, and stores it in the r-code file. You can read the SIGNATURE-VALUE attribute on the RCODE-INFO handle to determine the signature value for a procedure or class. This signature value is used by WebClient to determine if an r-code file has changed since the previous version of the application.
• The COMPILE statement is not synchronized with other ABL sessions. As such, compiling individual files in a common code base when applications are using that same code base for either compilation or execution, can cause unpredictable behavior and is not advised. The best practice is to holistically compile a project in one ABL session prior to updating a running application. The Progress Application Server (PAS) for OpenEdge supports the ability to easily update an application in production.

  For more information, see Update PROPATH in a production instance with zero downtime.

See also

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