AFILE

ANSI

The AFILE instruction defines an Associative Access Method (AAM) file. AAM is a method of retrieving data records using one or more free form key specifications. It uses one of the following formats:

Where:

label

Optional. A Program Execution Label.

%

Optional. Denotes the item as being GLOBAL.

*

Optional. Denotes the item as being COMMON.

arraysize

Optional. An Integer decimal constant, CONST variable or equated value indicating the number of array items.

parm

Optional. One of the valid parameters listed below.

^

Optional. Denotes the item as being a POINTER.

target

Optional. A previously declared AFILE variable that initializes the array.

%%

Optional. Denotes the item as GLOBAL but does not initialize it in any way.

Flags Affected: NONE

Note the following:

1. An AFILE label must have been defined with a File Definition instruction before being referenced in a file I/O instruction.

2. AFILE definitions reference two physical files on the system. These files perform particular functions within the AAM implementation as follows:
    

File	Use
TXT	The data file containing all of the text records for this AFILE.
AAM	The associative index to the records in the TXT file. It also monitors deleted record space for re-use when appropriate and contains the TXT file name (including the drive &/or path).

 

3. {parm} is optional. The supported parameters are:

BUFFER={nnnn | nvar | exp}

This parameter establishes a maximum record length (not including the EOR character(s)) of {nnnn} bytes, the value of the previously defined numeric variable {nvar}, or the value of a numeric expression {exp}. In addition (unless the COMPRESSED option is given), the records in the file are of fixed length and are not space compressed. Any short records written to the file are padded with blanks to the record length. The maximum allowed value is 65533.

COMP or COMPRESSED

This parameter allows space compressed and of variable length records within the file. The VARIABLE parameter is assumed in this case. Space compression is performed using the operating system standards.

DYNAMIC

This parameter provides compatibility with other compilers and is simply ignored.

FIX={nnnn | nvar | exp} or FIXED={nnnn | nvar | exp}

See 'BUFFER={nnnn}' above.

FORMAT={MSDOS | UNX | BINARY}

This parameter sets the end of record indicator within the file. The MSDOS type terminates records with a carriage return followed by a line feed for an end of record mark. The UNX type terminates records with a single line feed. The BINARY type does no checking on the file for the end of record type.

NAME={value}

This parameter specifies the actual disk name of the file. The parameter is only valid if used in conjunction with a FILELIST variable. {value} may be a literal or character string variable.

NOPATH

This parameter prevents the storage of the data file's path in the index header. This is the same as creating the index file with the Z option.

SEARCHCNT={nn}

This parameter is now obsolete. It remains for compatibility only.

UNCOMP or UNCOMPRESSED

This parameter does not permit space compressed records unless the VARIABLE parameter is also present.

VARIABLE={nnnn | nvar | exp}

This parameter allows variable length records written to the text file with a maximum length (actual data elements) of {nnn} bytes, the value of the previously defined numeric variable {nvar}, or the value of a numeric expression {exp}. The maximum allowed value is 65533.

VIEW={viewname}

This parameter specifies a default view used for the file variable. The {viewname} can be a literal or a character string variable that specifies a database and view name.

WEOF

This parameter forces all write operations to the End Of File. Deleted record space is not used. This option is assumed if the COMPRESSED or VARIABLE parameters are given. The WEOF parameter may result in faster I/O.

4. Additional parameters supported when using Datapoint Corporation's RMS Remote Access Server (RMSRAS) are as follows:

AIMBUFFS={nn}

This parameter specifies the number of index buffers.

FORMAT={BINARY | BIT8 | RMS | RMSUNCOMP}

This parameter allows definition of the file type as specified.

INCREMENT={nn}

This parameter defines the file increment value.

LENGTH={nn}

This parameter specifies the record length.

STATIC={nn}

This parameter defines the number of buffers allocated to the file. It is provided for compatibility only and is ignored by the runtime.

 

5. Where necessary (and/or desired), these parameters may be combined, such as:

BUFFER and WEOF

COMPRESSED and SEARCHCNT

VARIABLE and COMPRESSED

 

6. If an AFILE contains compressed records, the value specified for the buffer must be at least two (2) times as large as the longest record(s) in the file. At compile time, if the file is specified as being compressed, the buffer is automatically doubled. However, if the file is specified as fixed and at file OPEN time, it is compressed, the buffer may actually be too small. If the buffer is too small, an I/O error occurs.

7. If the operand field begins with an asterisk (*), the file is a Common Data Item. An attempt is made to maintain the OPEN status (with existing file pointers intact) of a corresponding file declaration in the program that initiated the chain. However, if the UDA of the chained to program is not in alignment (same File Definition types, sizes, and locations) with those in the program that initiated the CHAIN, a CHAIN error occurs.

8. It is not recommended that AFILEs be used on diskette based systems.

9. Most parameters specified on the AFILE definition are overridden at execution by the actual characteristics of the file. The exception to this rule is the actual (maximum if variable length or space compressed records) record length specified with BUFFER, FIXED, or VARIABLE parameters.

10. Care should be used if performing UPDATEs against variable length or space compressed records. It is possible to physically damage the text file. UPDATEs are not recommended with space compressed data files.

11. When an ISAM or AAM file is created with variable length or space compressed records, all secondary ISIs and AAMs should be created with the same characteristics.

12. The ^ denotes a Pointer Variable.

13. If the % form is used, the data item is placed in the Global Data Area. The variable would be available to other programs that also declared it with the percent form. Global Data Items are available with PLBCMP only.

14. If the %% form is used, the data label is placed in the Global Data Area but no initialization takes place if it has not already been defined in the Global Data Area. Global Data Items are available with PLBCMP only.

15. Array definition and referencing is handled in the same manner as DIM variables.

16. An AFILE array variable may be declared within a FILELIST/FILELISTEND declaration.

See Also: Example Code, File Definitions, Disk I/O Instructions