How to Access a File Mapped

You can access a file mapped by declaring a short (32-bit) or long (64-bit) pointer variable within a program and passing that variable to the appropriate HPFOPEN option. The HPFOPEN intrinsic returns the variable pointing to the beginning of the data area of the opened file.

After HPFOPEN returns the address of the file, you simply reference the pointer as an array. The machine architecture ensures integrity and protection of the file.

The following file types are allowed any type of access (Read, Write, Read/Write, and so forth) when opened using mapped access options:

standard disk files with fixed-length or undefined-length record formats

The following file types are allowed read-only access when opened using mapped access options:

standard disk files with variable-length record formats
KSAM files opened with copy mode option enabled

The following file types are not allowed to be opened using mapped access options:

relative I/O (RIO) files
message (MSG) files
circular (CIR) files
device files

You can use all applicable file system intrinsics mapped access, including all data transfer intrinsics; however, when mixing data transfer intrinsic calls (such as FREAD and FWRITE) with mapped access, you must take into consideration the data type (ASCII/binary) of the file, the record format, and the record size. Otherwise, data written to the file using mapped access may not make sense when read by FREAD.

When you open a file using mapped access and write data to that file, you must use the FPOINT and FCONTROL intrinsics to reset the EOF before you close the file. Otherwise, all data you write to the file after the EOF will be lost when you close the file. In the case of a newly created file, the EOF initially points to record zero.




	NOTE: When you access a file with mapped access you are bypassing file system services that set various file system pointers automatically, including the EOF and the logical record pointer. You are responsible for resetting the EOF prior to closing a file that you have accessed mapped. Also, file system posting is bypassed; so, if data recovery is needed you should use `FCONTROL` `controlcodes` 2 and/or 6 to post data and update the EOF periodically. Heavy use of the `FCONTROL` intrinsic to post data and set the EOF degrades performance due to the overhead of the extra posting.

Advantages of mapped access

Mapped access to a file can be much faster than access through normal file system intrinsics. This is especially the case when you are accessing a smaller file randomly rather than sequentially. When accessing a file mapped, there is no file system overhead associated with a specific reference to the file. The only difference between accessing a file mapped and accessing normal memory is the locality of the access and the protection strategy.




	NOTE: It is possible to show a degradation of performance if an application that accesses files sequentially is modified to access those files mapped. Normal system reads prefetch multiple records per read. Mapped file access has no method of prefetching the data, consequently, some performance penalty is paid by additional overhead on page faults.

There are two perspectives you can take on mapped file access:

A file is accessible as virtual memory. The advantages from this perspective are high performance and fast response time from the file system.
Virtual memory is accessed through the file system. The advantages from this perspective are
- Virtual memory can be easily saved permanently.
- Virtual memory can be checkpointed.
- Virtual memory can be easily shared through a common naming convention.

Short-mapped access

Item #18 short-mapped option is available in the HPFOPEN intrinsic to provide you with shared virtual memory. A short pointer is returned in an optional item parameter. You can use the pointer as a large array of any type to efficiently access the file.

A file created using the short-mapped option can be up to four megabytes in size. A process can have open at the same time up to six megabytes of files that are opened using the short-mapped option. For larger file needs, a file created using the long-mapped option is required.

An error results if you attempt to open a file using the short-mapped option that you have previously opened normally or with the long-mapped option.

You cannot access a loaded program file or a loaded library file using either mapped access option. In addition, you cannot load a file that is currently being accessed mapped.

Long-mapped access

Item #21 long-mapped option is available in the HPFOPEN intrinsic to provide you with access to large amounts of shared virtual memory. You can use the pointer as a large array of any type to efficiently access the file.

A file created using the long-mapped option can be up to two gigabytes in size. There is no practical limit of the number of long-mapped access files that a process can have open at a time.

You cannot access a loaded program file or a loaded library file using either mapped access option. In addition, you cannot load a file that is currently being accessed mapped.

Advantages of long-mapped access over short-mapped access are:

You can access much larger files than you can using the short-mapped option.
You can open files that were opened previously with any options (as long as the exclusive status of the file is not violated)

The disadvantage of long-mapped access is that it may be slower than short mapped access because of the need to load a space register to access the long-pointer space. long-mapped access can be as much as four times slower than short-mapped access, although long-mapped access still can be faster than accessing the file through the file system data transfer intrinsics.

The degradation can be minimized if you make the references to the long pointer space in a localized part of your code. This way it may be possible for the system to keep the pointer to the file's virtual space loaded into a space register rather than to repeatedly load and unload it.

How to Access a File Mapped

Technical documentation

» Table of Contents

» Index

Advantages of mapped access

Short-mapped access

Long-mapped access