| Navigation: Language Reference > 4 - Entity Declarations > File Structures >====== FILE (declare a data file structure) ====== |    |
| label | FILE,DRIVER( ) | [,CREATE] [,RECLAIM] [,OWNER( )] [,ENCRYPT] [,NAME()] [,PRE( )] |
| [,BINDABLE] [,TYPE] [,THREAD] [,EXTERNAL] [,DLL] [,OEM] | ||
| label | [INDEX( )] | |
| label | [KEY( )] | |
| label | [MEMO( )] | |
| label | [BLOB] | |
| [label] | RECORD | |
| [label] | fields | |
| END | ||
| END |
| 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:
Examples:
Names FILE,DRIVER('Clarion') !Declare a file structure
Rec RECORD !Required record structure
Name STRING(20) !containing one or more data elements
END
END !End file and record declaration
AsciiFileName STRING(260),STATIC
AsciiFile FILE,DRIVER('ASCII','/FILEBUFFERS=8'), NAME(AsciiFileName),|
PRE(ASC),CREATE,THREAD
Record RECORD,PRE()
Line STRING(1024)
END
END
Services FILE,DRIVER('TOPSPEED'),RECLAIM,PRE(SER), BINDABLE,CREATE,THREAD
ServiceIDKey KEY(SER:ServiceID),NOCASE,OPT,PRIMARY
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)
END
END
See Also:
RECORD