DosAllocMem

Syntax

rc = DosAllocMem( pBaseAddress, 
                  ulObjectSize, 
                  ulAllocationFlags );

Parameters

PPVOID pBaseAddress (output)

This is a pointer to the variable which will recieve the base address of the allocated private memory object.

ULONG ulObjectSize (input)

The size in bytes of the memory block you want to allocate. This will, by the system, be rounded up to the next page-size boundary.

ULONG ulAllocationFlags (input)

Flags used to describe allocation attributes, as well as access protection of the private memory block.

Allocation attributes

Setting PAG_COMMIT (0x00000010) makes all private memory blocks initially committed.

Setting OBJ_TILE (0x00000040) forces the memory block to be allocated in the first 512MB of virtual-address space. Mapping the memory block is done with the 16-bit selectors. The following table shows how a 32-bit memory block is mapped using 16-bit selectors.

32bit Offset	16bit alias selectors
BaseAddress+000KB	Sel
BaseAddress+064KB	Sel + HugeInc
BaseAddress+128KB	Sel + HugeInc * 2
. . .	. . .

HugeInc is the same huge increment that is used by DosAllocHuge.

Access protection

Setting PAG_EXECUTE (0x00000004) tells the system that 'execute access' to the commited pages is desired in the memory block.

Setting PAG_READ (0x00000001) tells the system that 'read access' is desired.

Setting PAG_WRITE (0x00000002) tells the system that 'write access' is desired.

Setting PAG_GUARD (0x00000008) tells the system that an access to the committed pages should cause a guard page exception to be raised.

At least one of PAG_EXECUTE,PAG_WRITE or PAG_READ must be set.

Returns

APIRET rc

The following values can be returned

0	NO_ERROR
8	ERROR_NOT_ENOUGH_MEMORY
87	ERROR_INVALID_PARAMETER
95	ERROR_INTERRUPT

Include Info

#define INCL_DOSMEMMGR
#include <os2.h>
#include <bsememf.h>

Usage Explanation

DosAllocMem is used to allocate a private memory object, within the boundaries of the virtual-address space.

Sample Code

 
#define INCL_DOSMEMMGR
#include 
#include     /* This will get the memory managment flags */

PVOID BaseAddress;      /* Pointer to the allocated memory block    */
ULONG ObjectSize;       /* The requested size of the memory block   */
ULONG AllocationFlags;  /* Flags                                    */
APIRET rc;              /* Will recieve the return code             */

   ObjectSize = 9000;   /* Asking for 9000 bytes, this will */
                        /* rounded up to 12KB.              */

   AllocationFlags = PAG_WRITE | PAG_EXECUTE;
            /* Allows read/write to the memory block, but */
            /* the block isn't committed within memory    */
            /* yet.                                       */

   rc = DosAllocMem(&BaseAddress, ObjectSize, AllocationFlags);

   if ( rc != 0)
   {
     /* We have an error we must take care of. */
   }

See Also

DosAllocSharedMem, DosFreeMem