FILE (declare a data file structure)

Top  Previous  Next

 

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:

KEY

INDEX

MEMO

BLOB

RECORD

EXTERNAL

THREAD