KCML_Map_FileArray

Purpose

Map a string array variable to a file

Definition

DEFSUB 'KCML_Map_FileArray(BYREF x$(), filename$, Flags, Offset = 0, Bytes = INT_MAX) AS Void

Parameters

x	String array variable to be mapped
filename	Name of file
Flags	Any MAPFILE_ constant
Offset	Optional. Optional offset into file where mapping is to start (default is from start of file). Only applicable to read only mapping.
Bytes	Optional. Optional number of elements to map into variable (default value is INT_MAX meaning to map the while file). Only applicable to read only mapping.

Description

The 'KCML_Map_FileArray function maps a string array variable to an external file. The exact behaviour is determined by the flags variable. This can be a combination of several values determining whether the mapping should be read-only or read+write and whether the file should exist or be be created. Common values are _MAPFILE_READONLY | _MAPFILE_OPEN Here the file must already exist. The string array must already be dimensioned to a 1-dimension string array with elements of the correct size. The number of elements may be zero as the string array is always redimensioned to contain the entire size of the file. If the file is not an exact multiple of the size of each element than an error will occur. After using this call whole of the file can be accessed through the string array. This is often an easier and faster operation than opening a file and reading its contents into a variable. _MAPFILE_READWRITE | _MAPFILE_CREATE Here the file is created based on the size of the string. Modifying the string array directly modifies the contents of the file. Any other process which has similarly mapped in the file will see the changes immediately. This is using memory mapped files to share information across processes. _MAPFILE_READWRITE | _MAPFILE_OPEN As above except that it is an error unless the file already exists. The variable is sized to the size of the file. The file can be unmapped by REDIM'ing the string variable to a size of zero. REDIMensioning a string variable that is mapped to a file to a non-zero size is not allowed.