Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## { } Include file reference

> Causes Progress to retrieve the statements in a file and compile them as part of the main procedure if it encounters the file’s name inside braces ({}) when compiling the procedure. You can name arguments you want substituted in the file before compilation.

> #### Syntax

>     { include-file
>       [ argument | { &argument-name = "argument-value" } ] ... }

> Enter the braces ({}) as shown; they do not represent syntax notation in this description.

> ``include-file``

> The name of an external operating system file that contains statements you want included during the compilation of a procedure. This filename follows normal operating system naming conventions and is case sensitive on UNIX. If the file you name has an unqualified path name, Progress searches directories based on the `PROPATH` environment variable.

> ``argument``

> A value used by `include-file`. When Progress compiles the main procedure (the procedure containing the braces), it copies the contents of `include-file` into that procedure, substituting any `arguments`. The first argument replaces {1} in the included file, the second argument replaces {2}, etc. So, you can use included procedures with arguments even when you precompile a procedure.

> ``&argument-name = "argument-value"``

> The `argument-name` is the name of the argument you want to pass to the include file. You can use variable names, field names, and reserved words as argument names.

> The `argument-value` is the value of the argument you pass to the include file. Enclose the `argument-value` in quotation marks.

> Examples

> The main procedure uses externally defined and maintained files for the layout and display of a customer report. You can use these same include files in many procedures.

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

> r-fcust.i
>     FORM customer.cust-num customer.name LABEL "customer Name"
>       customer.phone FORMAT "999-999-9999".

> r-dcust.i
>     DISPLAY customer.cust-num customer.name customer.phone.

> The following example references an include file that can take up to five arguments, and the main routine passes four arguments:

> r-incl2.p
>     DEFINE VARIABLE var1 as INTEGER INITIAL 9.
>     DEFINE VARIABLE var2 as DECIMAL INITIAL 6.43.
>     DEFINE VARIABLE var3 as LOGICAL INITIAL TRUE.
>         /* any statements */
>     {r-show.i point-A var1 var2 var3}
>         /* any statements */

> When the main procedure is compiled, the line referencing the show include file is replaced by the following line:

> r-show.i
>     MESSAGE "At" "{1}" "{2}" {2} "{3}" {3} "{4}" {4} "{5}" {5}.

> This example shows how you can use include files to extend the Progress language. The main procedure uses a new statement, `r-show.i`, to display the values of fields or variables at various points in a procedure. The include file in this example can handle up to five passed arguments. The main procedure only passes four (point-A, var1, var2, and var3). The output for this example is as follows:

>     MESSAGE At point-A var1 9 var2 6.43 var3 yes

> The `r-custin.p` procedure displays a frame for each customer that you can update with customer information. The procedure includes `r-cstord.i` and passes the named argument `&frame-options`, and the value of the argument (CENTERED ROW 3 NO-LABEL) to the include file. When the include file references the `&frame-options` argument, it uses the value of the argument, and therefore displays the OVERLAY frame`cust-ord` as a centered frame at row 3 without a label, as shown:

> r-custin.p
>     FOR EACH customer:
>       {r-cstord.i &frame-options = "CENTERED ROW 3 NO-LABEL"}.
>       UPDATE customer.cust-num name address address2 city state postal-code
>         phone credit-limit WITH FRAME cust-ord.
>     END.

> r-cstord.i
>     FORM   "Cust #" AT 1  customer.cust-num AT 10 SKIP(1)
>       customer.name AT 10
>       customer.address AT 10
>       customer.address2 AT 10
>       customer.city AT 10  customer.city customer.state
>       customer.postal-code SKIP(1)
>       "Phone " AT 1 customer.phone FORMAT "999/999-9999" AT 10
>       "Max Crd" AT 1 customer.credit-limit AT 10
>       WITH FRAME cust-ord OVERLAY {&frame-options}.

> Include files are particularly useful for using form layouts in multiple procedures, especially if you do not include the keyword FORM or the closing period (.) of the FORM statement.

> r-cust.f
>     customer.cust-num
>     customer.name SKIP(2)
>     customer.state

> The `r-incl3.p` procedure includes the `r-cust.f` file as the definition of a FORM statement, as shown:

> r-incl3.p
>     FORM {r-cust.f}.

> The `r-incl4.p` procedure uses the include file as a layout for a DISPLAY statement, as shown:

> r-incl4.p
>     FOR EACH customer:
>       DISPLAY {r-cust.f} WITH 3 DOWN.
>     END.

> #### Notes

> - When you use braces to include one procedure in another, Progress does not include the second procedure until it compiles the first one. This technique has the same effect as using the Editor to copy statements into the main procedure. At times, separate include files are easier to maintain.

> - You can nest include files. (They can contain references to other include files.) The number of nested include files is limited by the number of file descriptors available on the system.

> - If you have many nested include files and you are running on a Sequent machine, use Maximum Files (`-Mv`) startup parameter to control the number of files you can open simultaneously.

> - When you have a base procedure and want to make several copies of it, changing it slightly each time, use include files with parameters. For example, at times you might only want to change the name of some files or fields used by the procedure.

> - If you define a preprocessor name and later pass a compile-time argument with the same name, but a different value, to a procedure or include file, the value of the initial preprocessor name remains unchanged. Thus, a compile-time argument is scoped to the file to which it is passed.

> - Instead of maintaining duplicate source files, create a single include file with the variable portions (such as the names of files and fields) replaced by {1}, {2}, etc. Then each procedure you write can use that include file, passing file and field names as arguments.

> - You can use the name of an include file as an argument to another include file. For example, a reference to {{1}} in an include file causes Progress to include the statements from the file with the name that passed as the first argument.

> - Progress disregards an empty pair of braces ({}).

> - If you use double quotes (“ ”) around arguments in an argument list, Progress removes them. However, if you use single quotes (’ ’), Progress passes them. To pass one set of double quotes, you must use four sets of double quotes.

> - When Progress reads an include file into the source, it appends a space character to the end of an include file. For example, the following include file `r-string.i` contains data that is used by `r-incstr.p`:

> r-string.i
>     abcde

> r-incstr.p
>     DISPLAY LENGTH("{r-string.i}").

> Although `r-string.i` contains five letters, when you run `r-incstr.p`, it returns the value 6 because Progress appends a space character to the end of `r-string.i`.

> - The maximum length of the arguments you can pass to an include file is determined by the Input Characters (-inp) startup parameter.

> #### See also

> { } Argument reference, { } Preprocessor name reference, COMPILE statement, DEFINE PARAMETER statement, RUN statement

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