EXTERNAL (set defined externally)

Top  Previous  Next

 

EXTERNAL( member )

EXTERNAL

Specifies the variable, FILE, QUEUE, GROUP, or CLASS is defined in an external library.

member

A string constant (valid only on FILE, GROUP, or QUEUE declarations) containing the filename (without extension) of the MEMBER module containing the actual FILE, GROUP or QUEUE definition (the one without an EXTERNAL attribute) respectively. If the FILE, GROUP or QUEUE is defined in a PROGRAM module or in a "universal member module" (i.e., MEMBER statement for that module has no parameter), an empty string ('') can be used as a parameter of the EXTERNAL attribute, or the parameter can be omitted.

The EXTERNAL attribute specifies the variable, FILE, QUEUE, GROUP, or CLASS on which it is placed is defined in an external library. Therefore, a variable, FILE, QUEUE, GROUP, or CLASS with the EXTERNAL attribute is declared and may be referenced in the Clarion code, but is not allocated memory--the memory for the variable, FILE, QUEUE, GROUP, or CLASS is allocated by the external library. This allows the Clarion program access to any variable, FILE, QUEUE, GROUP, or CLASS declared as public in external libraries. The EXTERNAL attribute is not valid on variables declared inside FILE, QUEUE, GROUP, or CLASS structures.

When using EXTERNAL(member) to declare a FILE shared by multiple libraries (.LIBs, or .DLLs and .EXE), only one library should define the FILE without the EXTERNAL attribute. All the other libraries (and the .EXE) should declare the FILE with the EXTERNAL attribute. This ensures that there is only one record buffer allocated for the FILE and all the libraries and the .EXE will reference the same memory when referring to data elements from that FILE.

The declarations in all libraries (or .EXEs) must be EXACTLY the same (with the appropriate addition of the EXTERNAL and DLL attributes). For example, the FILE declarations in all libraries (or .EXEs) that reference common files must contain exactly the same keys, memos, and fields declared in exactly the same order. If they are not exactly the same, data corruption could occur. Any incompatibilities between libraries cannot be detected by the compiler or linker, therefore it is the programmer's responsibility to ensure that consistency is maintained.

Do not place the OWNER, ENCRYPT, or NAME attributes on a FILE which has the EXTERNAL attribute. These attributes should only be on the FILE structure declared without the EXTERNAL, because the EXTERNAL declaration is actually a re-declaration of a FILE already declared elsewhere. Therefore, these attributes are unnecessary.

One suggested way of coding large systems using many .DLLs and/or .EXEs that share the same files would have one .DLL containing the actual FILE definition that only contains FILE and global variable definitions that are shared among all (or most) of the .DLLs and .EXEs. This makes one central library in which the actual file definitions are maintained. This one central .DLL is linked into all .EXEs that use those common files. All other .DLLs and/or .EXEs in the system would declare the common FILEs with the EXTERNAL attribute.

Example:

PROGRAM

MAP

 MODULE('LIB.LIB')

AddCount PROCEDURE                       !External library procedure

 END

END

 

TotalCount LONG,EXTERNAL                 !A variable declared in an external library

 

!A File defined in a PROGRAM module whose .LIB is linked into this program

Cust   FILE,DRIVER('TopSpeed'),PRE(Cus),EXTERNAL('')

CustKey  KEY(Cus:Name)                  

Record   RECORD

Name      STRING(20)

        END

      END

!A File defined in a MEMBER module whose .LIB is linked into this program

Contact   FILE,DRIVER('TopSpeed'),PRE(Con),EXTERNAL('LIB01')

ContactKey KEY(Con:Name)                

Record     RECORD

Name        STRING(20)

          END

         END

!**************************************

! The LIB.CLW file contains:

PROGRAM

MAP

 MODULE('LIB01')

AddCount PROCEDURE                        !Library procedure

 END

END

 

TotalCount LONG                           !The TotalCount variable definition

!The Cust File definition where the record buffer is allocated

Cust    FILE,DRIVER('TopSpeed'),PRE(Cus)

CustKey  KEY(Cus:Name)                  

Record    RECORD

Name       STRING(20)

         END

       END

 

CODE

!Executable code ...

!*************************************

! The LIB01.CLW file contains:

MEMBER('LIB')

 

!The Contact File definition where the record buffer is allocated

Contact    FILE,DRIVER('TopSpeed'),PRE(Con)

ContactKey  KEY(Con:Name)                

Record      RECORD

Name         STRING(20)

           END

          END

 

AddCount PROCEDURE

CODE

TotalCount += 1

 

See Also:

DLL

NAME

EXTERNAL - Thread Considerations