GLOBALMEM statement

Purpose

Allocate or release a block of global memory

Syntax

GLOBALMEM ALLOC  count TO vHndl
GLOBALMEM FREE   mHndl TO vHndl
GLOBALMEM LOCK   mHndl TO vPtr
GLOBALMEM SIZE   mHndl TO vSize
GLOBALMEM UNLOCK mHndl TO vLocked

Remarks

GLOBALMEM allocates a block of global system memory of the requested size.  This is always allocated as "moveable" memory, so it can be used with any facilities of Windows.  It is the programmer's responsibility  to release the allocated memory block when it's no longer needed.

There are five general forms of the GLOBALMEM statement:

GLOBALMEM ALLOC

A moveable memory block of the size specified in bytes by count is allocated.  A unique handle is assigned to this memory object (for later identification). This handle is assigned to the LONG or DWORD variable specified by vHndl.  If the requested allocation fails for any reason, the value zero (0) is assigned to vHndl instead.

GLOBALMEM FREE

A memory block is de-allocated and released for re-use.  The mHndl parameter is a variable or expression which evaluates to the handle returned by GLOBALMEM ALLOC when the memory block was created.  If the de-allocation operation was successful, the result variable vHndl is set to zero (0) to indicate that the original handle is no longer valid.  If the operation fails for any reason, the value of the mHndl parameter is assigned to vHndl.  It may be convenient to use the same variable for both the parameter and the result, as it will then be automatically cleared to zero when the memory block is released.

GLOBALMEM LOCK

The moveable memory block referenced by mHndl is locked at a specific memory location.  A pointer to this location is assigned to the variable specified by vPtr.  You may only read or write the memory block while it is locked, and you use the current pointer to its location.

GLOBALMEM SIZE

The size of the memory block referenced by mHndl is retrieved and assigned to the LONG or DWORD variable specified by vSize.  The mHndl parameter is the handle originally returned by GLOBALMEM ALLOC.

GLOBALMEM UNLOCK

The moveable memory block referenced by mHndl is unlocked, and the previous memory pointer is invalidated.  If the memory block remains locked (perhaps because it had been locked more than once), the value TRUE (non-zero) is assigned to the result variable vLocked.  If the memory block is now unlocked, or the parameter mHndl was invalid, the value FALSE (0) is assigned to vLocked instead.

See also

MEMORY