KCML_Map_File | KCML Reference Manual

KCML_Map_File

Purpose

Memory map a file onto a scalar string variable

Definition

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

Parameters

x	String 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 bytes to map into variable (default value is INT_MAX meaning to map the whole file). Only applicable to read only mapping.

Description

The 'KCML_Map_File function maps a string 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 is redimensioned to the size of the file. After using this call whole of the file can be accessed through the string. 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. If the file already exists a P59 error is thrown, otherwise the file is created atomically using the contents of the string. Modifying the string 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.