.INCLUDE

Include external source code

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
 
.INCLUDE filename

or

.INCLUDE "filename" [LIBRARY ["lib_name"]]

or

.INCLUDE "structure" REPOSITORY ["rpsfile_log"][, type_spec][, qualifier]

or

.INCLUDE "enumeration" REPOSITORY ,[enum_access] ENUM

Arguments

filename

The name of a source file to be included. The default filename extension is .dbl. (a)

LIBRARY

(optional) Tells the compiler to search for filename in the specified location and include the file in the program.

lib_name

(optional) A logical defined as a search list that specifies the library location. If lib_name has an extension, it is stripped. (a)

structure

A structure or alias structure from the S/DE Repository. (a)

REPOSITORY

Tells the compiler to get the structure or enumeration from the S/DE Repository.

rpsfile_log

(optional) A logical defined with the names of the repository files. (a)

type_spec

(optional) The type of data structure to create. See Including from a repository for a complete list.

qualifier

(optional) One or more of the following qualifiers:

NOPRECISION

Indicates that all implied-decimal fields for this structure will be included without their fractional precision. (For example, a d8.2 field will be included as d8.)

NOFIELDS

Indicates that no fields will be included. Instead, one unnamed alpha field will be included and its size will be the size of the entire record.

PREFIX = “prefix”

Specifies that the fields in this structure will have a prefix appended to the beginning of each field’s name.

END

For COMMON, LITERAL, RECORD, and STRUCTURE only, specifies that the corresponding END keyword (ENDCOMMON, ENDLITERAL, etc.) will be generated at the end of the included fields.

DIMENSION = “[n,n,…]”

For GROUP only, passes dimension information where n is either dimension elements or *.

enumeration

The name of the enumeration from the S/DE Repository. (a)

enum_access

(optional) For class members only, one of the following access modifiers:

PUBLIC

Access is not restricted.

PROTECTED

Access is limited to the containing class or types derived from the containing class.

PRIVATE

Access is limited to the containing type. (default)

ENUM

Indicates that an enumeration data structure should be created.

Discussion

The .INCLUDE compilation control directive instructs the compiler to include source code from another source file, library, or repository. Synergy DBL supports up to 20 nested .INCLUDE source levels.

If filename is not in quotation marks, the name begins with the first non-white space character after .INCLUDE and ends with the last non–white space character before the end of the line, ignoring comments. This filename is automatically uppercased for processing. For example, the compiler searches for LOG:FILE.INC if you enter

.include LOG:file.inc

If you don’t want the compiler to convert filenames to uppercase letters (and you don’t want to add quotation marks around the filenames), use the DBLCASE logical to specify the case of your filename specifications. In our example, the compiler searches for LOG:file.inc if you set

dblcase=u:l
Note

Any white space characters between text elements is ignored. For example,

.include name

is treated the same as 

.include na me

If filename is in quotation marks, you must either specify a valid DICTIONARY, REPOSITORY, or LIBRARY specification or not have any text other than white space and comments after the .INCLUDE directive.

If you .INCLUDE a source file (as opposed to a repository structure or enumeration), the source lines from the included file are compiled until the end-of-file character is reached. Once the end-of-file character is reached, compilation continues with the line that follows the .INCLUDE statement.

If you don’t specify the LIBRARY qualifier, filename begins with the first non-white space character after .INCLUDE and ends with the first non–white space character before the end of the line, excluding comments.

If you specify the LIBRARY qualifier, filename must be an alpha expression. If lib_name is omitted, the compiler searches for filename in the directories specified by the DBLLIBRARY logical, as if you typed the following:

.include "DBLLIBRARY:filename"

You can’t .INCLUDE a prototype. Use the IMPORT statement instead.

Including from a repository

When you include a structure or an enumeration from a repository, the compiler produces a temporary file with the specified repository contents. This temporary file is included into the source file when the source file is compiled, and then it is deleted. (If the compiler generates a listing, the temporary include file is generated to the listing file.)

You can include enumerations globally or within a class or namepace. Enumeration .INCLUDEs always terminate automatically.

For structures, you can include fields in an argument group, class record, routine record, common record, or global data section. You can specify any of the appropriate modifiers as qualifiers based on the location of the .INCLUDE. For example, if the .INCLUDE is being performed on an argument group, any of the argument modifiers can be specified as qualifiers.

The rpsfile_log argument is the name of a logical that has been set to the repository main and text filenames from which to include the specified repository structure. If you don’t specify rpsfile_log, the default logical is DBLDICTIONARY. If DBLDICTIONARY is not defined, the compiler looks for RPSMFIL and RPSTFIL to determine the locations of the repository files. We recommend that you use RPSMFIL and RPSTFIL instead of DBLDICTIONARY, because those environment variables are also used by S/DE Repository.

Note

To avoid an error, we recommend that you uppercase the logical that defines a repository location in your .INCLUDE statements.

When you include a structure from a repository, only fields that do not have the “Excluded by Language” flag set are included by name. Fields that have the “Excluded by Language” flag set are included as unnamed fields of the appropriate size. (Overlay fields flagged as “Excluded by Language” are not included.) See Basic field information for more information.

Type_spec can be one of the following types of data structures:

COMMON[ = name][,x]

EXTERNAL COMMON[ = name][,x]

GLOBAL COMMON[ = name][,x]

LITERAL[ = name][,x]

EXTERNAL LITERAL[ = name][,x]

GLOBAL LITERAL[ = name][,x]

LOCAL LITERAL[ = name][,x]

RECORD[ = name][,x]

STATIC RECORD[ = name][,x]

[access] [STATIC] RECORD[ = name]

LOCAL RECORD[ = name][,x]

STACK RECORD[ = name][,x]

NORECORD

STRUCTURE[ = name][,x]

[access] STRUCTURE[ = name]

GROUP[ = name][,x]

[access] [STATIC] GROUP[ = name]

[OPTIONAL | REQUIRED] [direction] GROUP[ = name]

where

name

(optional) The name of the data structure to create. (This may be the same name as the repository structure or a different name.) Omitting the name creates an unnamed data structure. (a)

x

(optional) The overlay indicator. This is not compatible with the access modifier.

access

(optional) For class members only, one of the following access modifiers:

PUBLIC

Access is not restricted.

PROTECTED

Access is limited to the containing class or types derived from the containing class.

PRIVATE

Access is limited to the containing type. (default)

OPTIONAL

(optional) Argument is optional. (OPTIONAL can be abbreviated OPT.)

REQUIRED

(optional) Argument is required. (REQUIRED can be abbreviated REQ.)

direction

One of the following directional modifiers:

IN = Read only

INOUT = Read and write

OUT = Write only

If you don’t specify type_spec, RECORD is the default data structure type. If NORECORD is specified, only fields are created; there is no RECORD statement.

If your repository structure includes a group that has a “Member prefix” defined, this prefix is only appended to the beginning of the group’s member fields if the “Use by compiler” flag is set. See Basic field information for more information.

If you specify the PREFIX qualifier, the prefix added by the compiler is in addition to any prefixes specified for group members (fields) if the “Use by compiler” flag is set in Repository.

Note

Unlike traditional Synergy, where a repository field name is limited to 30 characters, the addition of prefixes will not cause repository field names to be truncated in .NET.

The PREFIX and NOPRECISION qualifiers can be specified at the same time, in any order. NOFIELDS, on the other hand, cannot be specified in conjunction with any other qualifier except END.

Group .INCLUDEs always terminate automatically. Record and structure .INCLUDEs in a class terminate automatically; you do not need to specify the corresponding END qualifier. (Note, however, that depending on what the next component is, there are rare instances, such as with the xfMethod attribute, when the compiler cannot terminate the structure properly, and you must specify ENDSTRUCTURE.) For global structure .INCLUDEs, the ENDSTRUCTURE qualifier is recommended but not required; if it is not present, the compiler generates an “ENDSTRUCTURE on global structure expected” warning (NOSPECL).

If your repository structure includes overlay fields, the compiler specifies them differently depending on whether the record is named or unnamed in your code. If the record is named, the compiler specifies the overlay field with dot notation using the record name, group names (if there are any), and field name. For example, if you have this structure in your repository:

employee
  id           ,a4
  startdate    ,d8
  day          ,d2 @startdate
  month        ,d2 @startdate+2
  year         ,d4 @startdate+4 
  salary       ,d10

and you .INCLUDE the structure like this in your code: 

.include "employee" repository, record="emp_rec"

you will see this in the code listing:

RECORD emp_rec 
    id          ,a4      ; (1,4)
    startdate   ,d8      ; (5,12)
    day         ,d2 @emp_rec.startdate   ; (5,6)
    month       ,d2 @emp_rec.startdate+2 ; (7,8)
    year        ,d4 @emp_rec.startdate+4 ; (9,12)
    salary      ,d10     ; (13,22)

If the record is unnamed (i.e., the NORECORD qualifier is used), the compiler specifies the overlay fields with an offset relative to the overlay field (not the overlaid field). Hence, the offset will be a negative number. For example, if you .INCLUDE the above structure like this in your code:

.include "employee" repository, norecord

you will see this in the code listing:

    id          ,a4     ; 
    startdate   ,d8     ; 
    day         ,d2 @-8     ; 
    month       ,d2 @-6     ; 
    year        ,d4 @-4     ; 
    salary      ,d10     ;
Tip

Because the compiler uses a named reference when the record is named, an “Ambiguous symbol” error could occur if there is another symbol with the same name in your code. You can use the NORECORD qualifier to eliminate this possibility for error. If you still want to be able to refer to the record by name, you can do this: 

record emp_rec
.include "employee" repository, norecord
Tip

We recommend that you declare any data that will be used in more than one routine in an include file or in the S/DE Repository, thereby ensuring that all routines have exactly the same record definitions. Also, if you need to change the record layout of a data file, the .INCLUDE directive enables you to make the changes in one place (the include file or repository), instead of having to modify each routine that contains the record layout.

Source file examples

A. In the following example, the compiler searches for file.dbl. 
.include "file"
B. In the following example, the compiler searches for file.inc in the directories specified by the LIB logical. 
.include "LIB:file.inc"
C. Assuming that DBLCASE is not defined, the following example searches for FILE.DBL in the directories specified by the LIB logical. 
.include LIB:file
D. In the following example, the compiler searches for file.dbl in the directories specified by the DBLLIBRARY logical. 
.include "file.dbl" LIBRARY
E. In the example below, the compiler searches for file.dbl in the directories specified by the MYLIBS logical. 
.include "file.dbl" LIBRARY "MYLIBS"
F. In the following example, the compiler generates an “Alpha expression expected” error (ALPHAXP) because file is not an alpha expression and the LIBRARY qualifier is specified. 
.include file LIBRARY

Repository examples

Below are examples that specify the REPOSITORY option. In these examples, the ORDER structure has the following fields:

ord_id          ,d6
cust_id         ,d6
A. In this example, because we don’t specify rpsfile_log, the compiler uses the DBLDICTIONARY logical to get the repository filenames. If DBLDICTIONARY is not defined, the compiler uses the RPSMFIL and RPSTFIL logicals. 
.include "order" REPOSITORY

The compiler reads the ORDER element from the repository and creates a temporary include file with the following contents. 

record
     ord_id       ,d6
     cust_id      ,d6

Because we didn’t specify a data structure type, the default, RECORD, is used.

B. In this example, the compiler again reads from the repository files specified by the default logical, DBLDICTIONARY and generates a record named “prev_order”. 
.include "order" REPOSITORY, RECORD = "prev_order"

The compiler produces a temporary file with the following contents:

record prev_order
  ord_id          ,d6
  cust_id         ,d6
C. In this example, the compiler uses the repository files specified by the DDNAME logical to generate an unnamed global common. 
.include "order" REPOSITORY "DDNAME", GLOBAL COMMON

The compiler produces a temporary include file with the following contents:

global common
  ord_id          ,d6
  cust_id         ,d6
D. In this example, the compiler reads from the repository files specified by the default logical, DBLDICTIONARY to generate a literal named “order”. 
.include "order" REPOSITORY, LITERAL = "order" ,x

The compiler produces a temporary file with the following contents:

literal order ,X
  ord_id          ,d6
  cust_id         ,d6
E. In this example, the compiler again reads from the repository files specified by the default logical, DBLDICTIONARY. 
.include "order" REPOSITORY, NORECORD

No data structure type is generated. The compiler generates a temporary file with the following contents:

ord_id          ,d6
cust_id         ,d6
F. In this example, the compiler again reads from the repository files specified by the default logical, DBLDICTIONARY and generates a group named “order _info”. 
.include "order" REPOSITORY, GROUP = "order_info"

The compiler produces a temporary file with the following contents:

group order_info
  ord_id          ,d6
  cust_id         ,d6
endgroup
G. In this example, the compiler again reads from the repository files specified by the default logical, DBLDICTIONARY, creating a structure with each field prefixed by “new_”. 
.include "order" REPOSITORY, STRUCTURE="order", PREFIX="new_"

The compiler produces a temporary file with the following contents: 

structure order 
  new_ord_id     ,d6
  new_cust_id    ,d6
H. The example below defines a dimensioned group. 
.INCLUDE "rps_struct" REPOSITORY, GROUP = "mygrp_array", DIMENSION= "[100]"

The compiler produces a temporary file with the following contents: 

group mygrp_array, [100]a 
    ord_id       ,d6 
    cust_id      ,d6 
endgroup
I. The example below includes the colors enumeration from the repository. 
.include "colors" REPOSITORY, ENUM

The compiler produces a temporary file, which might look like this: 

enum colors
    red         ,3
    blue        ,5
    green       ,7
endenum