| **Navigation:**  [[introduction.htm|Language Reference]] > 4 - Entity Declarations > File Structures >====== FILE (declare a data file structure) ====== | [[file structures.htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[index declare static file access index .htm|{{btn_next_n.gif|Next page}}]] | | || | //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** | | {{blk2blue.jpg|blk2blue.jpg}} | //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). {{notebox.jpg|NoteBox.jpg}} **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:** | [[buffer set record paging .htm|BUFFER]] | [[build build keys and indexes .htm|BUILD]] | [[close close a data structure .htm|CLOSE]] | [[copy copy a file .htm|COPY]] | [[create allow data file creation .htm|CREATE]] | [[empty empty a data file .htm|EMPTY]] | [[flush flush buffers .htm|FLUSH]] | [[lock exclusive file access .htm|LOCK]] | | [[name return file name .htm|NAME]] | [[open open a data structure .htm|OPEN]] | [[pack remove deleted records .htm|PACK]] | [[records return number of rows in data set .htm|RECORDS]] | [[remove erase a file .htm|REMOVE]] | [[rename change file directory name .htm|RENAME]] | [[send send message to file driver .htm|SEND]] | [[share open data file for shared access .htm|SHARE]] | | [[status return file status .htm|STATUS]] | [[stream enable operating system buffering .htm|STREAM]] | [[unlock unlock a locked data file .htm|UNLOCK]] | [[add add an entry .htm|ADD]] | [[append add a new file record .htm|APPEND]] | [[bof return beginning of file .htm|BOF]] | [[bytes return size in bytes .htm|BYTES]] | [[delete delete a record .htm|DELETE]] | | [[duplicate check for duplicate key entries .htm|DUPLICATE]] | [[eof return end of file .htm|EOF]] | [[get read a record or entry .htm|GET]] | [[hold exclusive record access .htm|HOLD]] | [[next read next record in sequence .htm|NEXT]] | [[nomemo read file record without reading memo .htm|NOMEMO]] | [[pointer return last queue entry position .htm|POINTER]] | [[position return record sequence position .htm|POSITION]] | | [[previous read previous view record in sequence .htm|PREVIOUS]] | [[put re write record .htm|PUT]] | [[release release a held record .htm|RELEASE]] | [[reget re get record .htm|REGET]] | [[reset reset record sequence position .htm|RESET]] | [[set initiate sequential file processing .htm|SET]] | [[skip bypass records in sequence .htm|SKIP]] | [[watch automatic concurrency check .htm|WATCH]] | **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:** [[key declare dynamic file access index .htm|KEY]] [[index declare static file access index .htm|INDEX]] [[memo declare a text field .htm|MEMO]] [[blob declare a variable length field .htm|BLOB]] __RECORD__ [[external set defined externally .htm|EXTERNAL]] [[thread set thread specific memory allocation .htm|THREAD]]