| GEOS SDK TechDocs | | VMClose() ... | VMPreserveBlocksHandle() ...

---

VMGetMapBlock()

VMBlockHandle 	VMGetMapBlock(
        VMFIleHandle		file);

This routine returns the VM block handle of the file's map block.

Include: vm.h

VMGrabExclusive()

VMStartExclusiveReturnValue VMGrabExclusive(
        VMFileHandle		file,
        word		timeout,
        VMOperation		operation,
        VMOperation *		currentOperation);

This routine gets exclusive access to a VM file for this thread.

Include: vm.h

VMInfo()

Boolean	VMInfo(
        VMFileHandle		file,
        VMBlockHandle		block,
        VMInfoStruct *		info

This routine writes the memory handle, block size, and user ID number of the block. It returns non-zero if the handle is invalid or free.

Include: vm.h

VMLock()

void *	VMLock(
        VMFileHandle		file,
        VMBlockHandle		block,
        MemHandle*		mh);

This routine locks a VM block into the global heap. It returns the block's base address.

Include: vm.h

VMMemBlockToVMBlock()

VMBlockHandle 	VMMemBlockToVMBlock(
        MemHandle		mh,
        VMFileHandle*		file);

This routine gets the VM block and file handles for a specified memory block. It returns the VM block handle and copies the VM file handle into *file .

The memory handle passed must be the handle of a block which is attached to a VM file. If it is not, the results are undefined.

Include: vm.h

VMModifyUserID()

void	VMModifyUserID(
        VMFileHandle		file,
        VMBlockHandle		block,
        word		userID);

This routine changes a VM block's user ID number.

Include: vm.h

VMOpen()

VMFileHandle 	VMOpen(
        char *		name,				/* Name of file to open/create */
        VMAccessFlags		flags,
        VMOpenType		mode,
        word		compression);				/* Compaction threshold percentage 
						 * passed as an integer */

This routine opens or creates a VM file. It returns the handle of the opened file. If it is unable to open the file, it returns a null VMFileHandle and sets a VMStatus error code which may be retrieved with ThreadGetError() . VMOpen() looks for the file in the thread's working directory (unless a temporary file is being created, as described below). The routine takes four arguments:

name

A pointer to a string containing the name of the file to open. The file will be opened in the thread's current working directory. If a temporary file is being opened, this buffer should contain the full path of the directory in which to create the file, followed by fourteen null bytes (counting the string-ending null). VMOpen() will write the name of the temporary file in those trailing nulls.

flags

This specifies what kind of access to the file you need. The flags are described in the C Structures Reference.

mode

This specifies how the file should be opened. The types are described in the C Structures Reference.

compression

The compaction threshold percentage, passed as an integer. For example, to set a compaction threshold of 50%, pass the integer 50. When the percentage of used space in the file drops below the compaction threshold, the VM manager will automatically compact the file. To use the system default threshold, pass a threshold of zero. The compaction threshold is set only when the file is created; this argument is ignored if an existing file is opened.

You must also specify how the file should be opened. To do this, you pass a member of the VMOpenType enumerated type.

If for any reason VMOpen() is unable to open the requested file, it will returns a null file handle. It will also set the error value for ThreadGetError() . The possible error conditions are:

VM_FILE_EXISTS

VMOpen() was passed VMO_CREATE_ONLY, but the file already exists.

VM_FILE_NOT_FOUND

VMOpen() was passed VMO_OPEN, but the file does not exist.

VM_SHARING_DENIED

The file was opened by another geode, and access was denied.

VM_OPEN_INVALID_VM_FILE

VMOpen() was instructed to open an invalid VM file (or a non-VM file).

VM_CANNOT_CREATE

VMOpen() cannot create the file (but it does not already exist).

VM_TRUNCATE_FAILED

VMOpen() was passed VMO_CREATE_TRUNCATE; the file exists, but could not be truncated.

VM_WRITE_PROTECTED

VMOpen() was passed VMAF_FORCE_READ_WRITE, but the file was write-protected.

VM_CANNOT_OPEN_SHARED_MULTIPLE

VMOpen() attempted to open a file marked GFHF_SHARED_MULTIPLE while passing the VMAF_DISALLOW_SHARED_MULTIPLE flag.

VM_FILE_FORMAT_MISMATCH

VMOpen() attempted to create a VM file using a name that already belongs to a DOS file.

Include: vm.h

Tips and Tricks: If you use the document control objects, they will take care of opening files as necessary; you will not need to call VMOpen() .

See Also: FileOpen().