User Tools

Site Tools

Navigation:  Language Reference > 4 - Entity Declarations > File Structures >====== FILE (declare a data file structure) ====== Previous pageReturn to chapter overviewNext page
label FILE,DRIVER( ) [,CREATE] [,RECLAIM] [,OWNER( )] [,ENCRYPT] [,NAME()] [,PRE( )]
label [INDEX( )]
label [KEY( )]
label [MEMO( )]
label [BLOB]
[label] RECORD
[label] fields


label A valid Clarion label for the FILE, INDEX, KEY, MEMO, BLOB, RECORD, or field (PROP:Label).
FILE Declares a data file.
DRIVER Specifies the data file type (PROP:DRIVER). The DRIVER attribute is required on all FILE structure declarations.
CREATE Allows the file to be created with the CREATE statement during program execution (PROP:CREATE).
RECLAIM Specifies reuse of deleted record space (PROP:RECLAIM).
OWNER Specifies the password for data encryption (PROP:OWNER).
ENCRYPT Encrypt the data file (PROP:ENCRYPT).
NAME Set DOS filename specification (PROP:NAME).
PRE Declare a label prefix for the structure.
BINDABLE Specify all variables in the RECORD structure may be used in dynamic expressions.
TYPE Specify the FILE is a type definition for FILEs passed as parameters. only available for Clarion#
THREAD Specify that memory for the record buffer and file structure is separately allocated for each execution thread, when the file is opened on the thread (PROP:THREAD).
EXTERNAL Specify the FILE is defined, and the memory for its record buffer is allocated, in an external library.
DLL Specify the FILE is defined in a .DLL. This is required in addition to the EXTERNAL attribute.
OEM Specify string data is converted from OEM ASCII to ANSI when read from disk and ANSI to OEM ASCII before writing to disk (PROP:OEM).
INDEX Declare a static file access index which must be built at run time.
KEY Declare a dynamically updated file access index.
MEMO Declare a variable length text field up to 64K in length.
BLOB Declare a variable length memo field which may be greater than 64K in length.
RECORD Declare a record structure for the fields. A RECORD structure is required in all FILE structure declarations.
fields Data elements in the RECORD structure.

FILE declares a data file structure which is an exact description of a data file residing on disk. The label of the FILE structure is used in file processing statements and procedures to effect operations on the disk file. The FILE structure must be terminated by a period or the END statement.

All attributes of the FILE, KEY, INDEX, MEMO, data declaration statements, and the data types which a FILE may contain, are dependent upon the support of the file driver. Anything in the FILE declaration which is not supported by the file system specified in the DRIVER attribute will cause a file driver error when the FILE is opened. Attribute and/or data type exclusions for a specific file system are listed in each file driver's documentation.

At run-time, the RECORD structure is assigned memory for a data buffer where records from the disk file may be processed by executable statements. This record buffer is always allocated static memory on the heap, even if the FILE is declared in a local data section. A RECORD structure is required in a FILE structure. Memory for a data buffer for any MEMO fields is allocated only when the FILE is opened, and de-allocated when the FILE is closed. The memory for BLOB fields is allocated as needed once the FILE is open.

A FILE with the BINDABLE attribute declares all the variables within the RECORD structure as available for use in a dynamic expression, without requiring a separate BIND statement for each (allowing BIND(file) to enable all the fields in the file). The contents of each variable's NAME attribute is the logical name used in the dynamic expression. If no NAME attribute is present, the label of the variable (including any prefix) is used. Space is allocated in the .EXE for the names of all of the variables in the structure. This creates a larger program that uses more memory than it normally would. Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

A FILE with the THREAD attribute declares a separate record buffer (and file control block) for each execution thread that OPENs the FILE. If the thread does not OPEN the file, no record buffer is allocated for the file on that thread. If a NAME attribute is defined for the file and declared as “STRING, STATIC”, it will need to explicitly declare the THREAD attribute if a different file name will be opened on each thread (or PROP:Name may be used to specify the file name).


Any FILE declared in the local scope of a PROCEDURE or ROUTINE is treated as threaded, regardless of the presence of the THREAD attribute in its declaration.

A FILE with the EXTERNAL attribute is declared and may be referenced in Clarion code, but is not allocated memory. The memory for the FILE's record buffer is allocated by the external library. This allows a Clarion program access to FILEs declared as public in external libraries.

Related Procedures:


Names FILE,DRIVER('Clarion') !Declare a file structure
Rec    RECORD                !Required record structure
Name    STRING(20)           !containing one or more data elements
     END                    !End file and record declaration

AsciiFileName  STRING(260),STATIC
AsciiFile FILE,DRIVER('ASCII','/FILEBUFFERS=8'), NAME(AsciiFileName),| 
Record     RECORD,PRE()
Line        STRING(1024)
ServTypeDescKey KEY(SER:ServiceType,SER:ServiceDesc),NOCASE,OPT
Notes           MEMO(1000)
Record           RECORD,PRE()
ServiceID         LONG
ServiceDesc       STRING(20)
ServiceType       STRING(12)
Notes             STRING(30)

See Also:








file_declare_a_data_file_structure_.htm.txt · Last modified: 2021/06/15 23:24 by carlbarnes