Progress
Language Reference
COMPILE Statement
Compiles a procedure. After a procedure is compiled, the RUN statement does not recompile it, so the procedure runs quickly. A compilation can last for a session, or it can be saved permanently for use in later sessions (as an r-code file, which has a .r extension).
SYNTAX
COMPILE { procedure | VALUE ( expression ) }
Specifies the name of the procedure you want to compile.
On UNIX, you can use a procedure name (the last component of the full pathname, if you use the full pathname) up to 12 characters long. On Windows, if you use the SAVE option, the procedure name must have a .p extension, .w extension, or no extension. On UNIX, procedure names are case sensitive, so you must enter them exactly as they are stored.
ATTR-SPACE [ = logical-expression ]
No effect-supported for backward compatibility only.
XCODE expression
Decrypts the source code in procedure, and any encrypted include files, using the decryption key expression. Only use XCODE to decrypt files not encrypted with the default key. Include files that are not encrypted are included and compiled in the standard manner.
Decryption is incremental during compilation. Having the decryption key does not allow you to examine a decrypted version of the source code.
NOTE: You cannot use the XCODE and LISTING or DEBUG-LIST options together. Also, you cannot use the XCODE and XREF options together. That is, you cannot create a cross-reference listing from code that is encrypted.STREAM-IO [ = logical-expression ]
Specifies that all output from the compiled procedures is formatted for output to a file or printer. This means that all font specifications are ignored and all frames are treated as if they had the USE-TEXT option given. This produces a platform-independent output appropriate for printing.
If you specify a logical-expression, its value determines whether the STREAM-IO option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.
SAVE [ = logical-expression ] [ INTO { directory | VALUE ( expression) } ]
Produces a file that contains the r-code for the procedure you are compiling. This r-code file is saved across Progress sessions. If you do not use the SAVE phrase, the COMPILE statement produces r-code for the source procedure, but the r-code is not saved across Progress sessions. This r-code is a session compile version of the procedure.
If you specify a logical-expression, its value determines whether the SAVE option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.
The COMPILE SAVE statement produces an r-code file with the name procedure-name.r, where procedure-name is the name of your source file without the extension. If you supply a filename of test, COMPILE SAVE produces an r-code file with the name test.r. If you supply a filename of
test.p
, COMPILE SAVE produces an r-code file with the nametest.r
. However, if you specify a filename oftest.bp
, COMPILE SAVE still produces an r-code file with the nametest.r
. Progress ignores the file extension of your procedure files and always creates r-code files that use the same filename with a .r extension. Make sure that you use distinct filenames for each of your procedure files.By default, the r-code file is stored in the same directory as the source procedure. If you use the SAVE INTO phrase, the r-code file produced by a compilation can be saved in a different directory. See the EXAMPLES and NOTES sections for more information.
On UNIX and Windows, a newly created r-code file replaces any existing r-code file of the same name.
LISTING { listfile | VALUE ( expression ) }
Produces a compilation listing that includes:
- The name of the file containing the procedure you compile
- The date and time at the start of the compilation
- The number of each line in the procedure
- 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 Progress ignores the LISTING option.
APPEND [ = logical-expression ]
Appends the current listing to the contents of the listing file. If you do not use the APPEND option, Progress creates a new listing file, replacing any file of the same name.
If you specify a logical-expression, its value determines whether the APPEND option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs.
PAGE-SIZE integer-expression
Identifies the number of lines to a page in the listing file. The default page size is 55 and integer-expression must be between 10 and 127, inclusive.
PAGE-WIDTH integer-expression
Identifies the number of page columns in the listing file. The default page width is 80, and integer-expression must be between 80 and 255, inclusive. Add at least 12 spaces to the page width when you type the procedure. This allows you to list information that precedes each line of code, ensuring that the procedure appears in the listing output exactly as you typed it.
XREF { xreffile | VALUE ( expression ) } [ APPEND [ = logical-expression ] ]
Writes cross-reference information between procedures and Progress objects to the file xreffile or VALUE ( expression ). If expression returns the unknown value (?), then Progress ignores the XREF option.
NOTE: You cannot use the XREF and XCODE options together. That is, you cannot create a cross-reference listing from code that is encrypted.Cross-referenced objects include procedure and include files, user-defined functions, tables, fields, variables, frames, and character strings. XREF generates one unformatted, blank-separated line in xreffile for each object reference. Each line has the following format.
The procedure-name is the name of the procedure you compile with the COMPILE XREF statement. The file-name is the name of the file with the referenced code. The line-number is the line number of the statement in file-name that contains the object reference. The reference-type is the type of reference in the code (such as ACCESS or UPDATE), and the object-identifier is the Progress object being referenced.
NOTE: If file-name is an include-file, procedure-name is the file that includes the include-file.The possible reference types and object identifiers appear in Table 14.
If you specify the APPEND option, the cross-reference information is appended to an existing file. The first line of cross-reference information for a procedure contains the object identifier for the COMPILE reference type. This allows you to easily find where the information for each compilation begins. If you specify a logical-expression, its value determines whether the APPEND option is activated. If the logical-expression is evaluated to the unknown value (?), a run-time error occurs
STRING-XREF { sxreffile | VALUE ( expression ) }
[ APPEND [ = logical-expression ] ]Writes cross-reference string information between procedures and Progress objects to the file sxreffile or VALUE ( expression ). If expression evaluates to the unknown
value (?), Progress ignores the STRING-XREF option.
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.
The line-number is the same as line-number in the standard XREF file. The object-name is the name of the object with which the string is associated. The max-length and string-justification come from the string attribute (either explicit or implicit) and reflect the attributes applied to the string as it is entered into the text segment.
The statement-type describes the type of statement in which the string appears. Only one statement type appears in a given string’s output line. The following values are possible:
NOTE: Any statement type that is not included in the preceding list will appear as OTHER.
The detail-info is one or more detail tags that specify more specifically where the string appears in the statement. The following values are possible:
NOTE: The NON-ALPHA tag indicates that a string consists entirely of blanks or digits.
The FORMAT tag is followed by one of the following tags: CHAR, NUMERIC (includes decimal and integer), DATE, or BOOL. These tags indicate the type of format. When a string can appear in only one place in a statement, no detail tag appears.Table 15 shows the valid combinations of statement types and detail tags.
LANGUAGES ( { language-list | VALUE ( expression ) } )
Identifies which language segments to include in the compiled r-code. The language-list is a colon-separated list of language names used to generate each text segment. If you specify VALUE ( expression ), the expression must evaluate to a comma-separated list of language names. If expression evaluates to the unknown value (?), then Progress ignores the LANGUAGES option.
Translated character strings for each specified language are read from the translation database and are stored in segments within the r-code.
If you use an expression to specify language-list, you must use the VALUE option.
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.
Provided there is no language named BABEL in the translation database, the strings in this text segment would be either French, Spanish, Italian, or German, depending on which strings have translations in which languages.
TEXT-SEG-GROW = growth-factor
Specifies the factor by which Progress increases the length of strings. When you develop an application that is going to be translated, it is important to allow for the growth of the text in your widgets. If you use the TEXT-SEG-GROW option, Progress increases the size of the text strings when it compiles your application.
Progress uses the following formula to determine the length of strings.
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, Progress applies the formula as follows and defines the New-length as 35.
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 Progress ignores the DEBUG-LIST option. The debugfile consists of a line-numbered listing of the procedure with the text of all preprocessor include files, names, and parameters inserted.
PREPROCESS { preprocessfile | VALUE ( expression ) }
Preprocesses the procedure and writes the preprocessed source code to the file preprocessfile or VALUE ( expression ). If expression evaluates to the unknown value (?), Progress ignores the PREPROCESS option. The preprocessfile is a text file that contains a final version of your source code after all include files have been inserted and all text substitutions have been performed.
NO-ERROR
Specifies that any errors that occur as a result of the compilation are suppressed. After the COMPILE statement completes, you can check the ERROR and WARNING attributes of the COMPILER system handle to determine whether an error has occurred or any warning messages were produced. You then can check the ERROR-STATUS handle for the specific messages.
V6FRAME [ = logical-expression ] [USE-REVVIDEO | USE-UNDERLINE]
The V6FRAME option is designed specifically to compile and run Progress Version 6 applications with Progress Version 7 or later for Windows. This option uses the V6FontNumber setting in the [Startup] section of the current environment (which might be the Registry or an initialization file) to calculate the height and width of a character unit and then set the layout grid used to compile frames for display in Progress Version 7 or later.
At run time, the FONT attribute for a frame compiled with the V6FRAME option is set to the font number specified with the V6FontNumber setting. The default setting for the V6FontNumber setting is 3.
By default, V6FRAME displays a border around a fill-in field. This means that your code requires more space on the screen than in Progress Version 6. You can override this behavior with one of the following options.
- 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 a Progress session, see the Progress Client Deployment Guide.
MIN-SIZE [ = logical-expression ]
Minimizes the size of the generated r-code file by eliminating the Debugger Segment (which is used by the Progress Debugger) and the signature descriptor data (which is used by the Open Client Proxy Generator).
If you specify a logical-expression, its value determines whether the MIN-SIZE option is activated (TRUE) or not (FALSE). If the logical-expression evaluates to the unknown value (?), a run-time error occurs. The default value is FALSE.
GENERATE-MD5 [ = logical-expression ]
When Progress compiles a procedure with the GENERATE-MD5 option, it generates a special MD5 value based on the code content, and stores it in the r-code file. This r-code MD5 value is similar to a CRC value, except the MD5 value is 128 bits in size and the CRC value is only 16 bits. The MD5 value is virtually guaranteed to be different if the file content has changed. As with CRC, content changes include any schema changes. That is, if only the schema changes, the MD5 value also changes.
If you specify a logical-expression, its value determines whether the GENERATE-MD5 option is activated (TRUE) or not (FALSE). The default value is TRUE.
This option is supported for WebClient only (that is, only WebClient uses the resulting MD5 value). Progress recommends compiling your WebClient application procedures with this option. Using this option lets WebClient determine if an r-code file has changed since the previous version of the application.
EXAMPLESIn this procedure, Progress creates an r-code version of the
ord-ent
procedure, naming itord-ent.r
. (The sample procedures supplied with Progress do not include theord-ent
procedure.)
In this procedure, Progress compiles the demo1 procedure, reserving spaces in frame layouts for special field attributes and producing an r-code file,
demo1.r
, that can be used across Progress sessions. Progress saves the r-code file in the current directory.
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.
The following example shows the effect of include files on compilation listings.
Suppose you use the following COMPILE statement to compile the
r-incl.p
procedure.
This COMPILE statement produces four files:
r-incl.r
,r-incl.lis
,r-incl.xrf
, andr-incl.dbg
.The following procedures contain the contents of the
r-incl.lis
,r-incl.xrf
, andr-incl.dbg
files.
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.
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
.
Each line in the
xref
file specifies the procedure, line number, access type, and access information. The first line in thexref
file contains the COMPILE access type directive and the name of the procedure exactly as it appears in the COMPILE statement. See Table 14 for a list of the values that follow a particular access type (for example, table and index after SEARCH).This is the debug listing
r-incl.dbg
.
NOTES
- If you want all record retrieval statements in a procedure to default to NO-LOCK, you must compile the procedure in a Progress session started with the No Lock (-NL) startup parameter. For more information on record locking, see the Progress Programming Handbook . For more information on the No Lock (-NL) startup parameter, see the Progress 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.- On UNIX, you define the
PROPATH
variable in a startup script or in your.profile
file. In Windows, you can define yourPROPATH
in the Registry or in an initialization file. You can also define thePROPATH
interactively at the operating system level.In addition to any directories you define for
PROPATH
, Progress searches the directory containing the Progress system software. If you do not define a value forPROPATH
, Progress searches your working directory by default.- To locate the source file that you name in the COMPILE SAVE statement, Progress searches the first directory in
PROPATH
. If the source file is there, Progress 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, Progress does not produce an r-code file and leaves existing r-code files unchanged.If Progress 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):
In the example, Progress saves the source file
/pro1/source/test/proc1.p
as/pro1/obj/test/proc1.r
.If the source file is a full pathname, Progress stores
procedure name.r
in the SAVE INTO directory; it drops its original directory path.
In the example, Progress saves the source file as
/usr/rcode/proc1.r
.If the SAVE INTO pathname is null, Progress saves the r-code file in the same directory as the source file.
- The ATTR-SPACE/NO-ATTR-SPACE designation in a Frame phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase. The ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a COMPILE statement.
- To locate a file with the COMPILE statement (without the SAVE phrase), Progress 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 Progress Compiler.
- It must have the same cyclic redundancy check (CRC) value as any database tables it references, or the same time stamp if you are running with the Timestamp (-tstamp) parameter. When creating an r-code file, Progress includes, as part of the r-code file, either the CRC or the time stamp 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, Progress continues with the compilation and produces the files specified and a session compile. If Progress 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, Progress searches the same directory in
PROPATH
for a source file. If the source file is there, Progress compiles it into the session compile file. If it is not there, Progress continues on to the next directory inPROPATH
, searching for an r-code file, then for a source file.- 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 sports 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.
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 Cust-Num index keys (respectively) to be searched.
- SpeedScript — These options are invalid: V6FRAME, USE-REVVIDEO, and USE-UNDERLINE.
SEE ALSO
COMPILER System Handle, RUN Statement, No Lock (-NL) Startup Parameter (in Progress Startup Command and Parameter Reference )
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |