Clarion Community Help

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
| **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:**

<code>
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
</code>

**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]]