[ Home |
Alpha index |
Topic index |
The OS/2 API Project
[ Syntax |
rc = DosSubSetMem( pOffset,
- PVOID pOffset (input)
- This is the address of the memory pool used for suballocation.
- ULONG ulFlags (input)
- Flags used to describe the characteristics of the memory object being suballocated.
- DOSSUB_INIT (0x00000001). This bit must be set for the memory
block to be intialized for suballocation. If it is not set the request is
to attach a process to a shared memory pool that was initialized by another
process using DosSubSetMem.
- DOSSUB_GROW (0x00000002). Setting this bit means that the size
of the current memory_pool is to be increased. This will leave
DOSSUB_INIT without meaning.
- DOSSUB_SPARSE_OBJ (0x00000004). If a suballocation function is to be used to
manage commitment of the pages in the memory pool this bit should be set. This means that
all the pages of the memory block must be uncommitted. If this bit is not set the
suballocation function will assume the pages to be committed and valid. If DosSubSetMem is
used to increase the size of a memory pool, this bit must be the same as it was when the
memory pool was originally initialized. If this is not the case an error will be returned.
- DOSSUB_SERIALIZE (0x00000008). Setting this bit will serialize the memory pool.
- The first DosSubSetMem request on a shared memory pool, it may be an init or a
serialize request, will create the memory pool and open it for requesting processes. All
following DosSubSetMem (serialize or attach) will attach the shared memory pool to the
- ULONG ulSize (input)
- The size in bytes of the memory pool. It's supposed to be a multiple of 8 bytes, if not
it will be rounded down by the system.
- APIRET rc
- The following values can be returned
DosSubSetMem is used to initialize a pool for suballocation, or used to
increase the size of an already initialized memory pool.
The requester must begin by gaining access to the memory block in which the
memory pool resides.
If you use DosSubSetMem, it should later be followed by DosSubUnsetMem to reset resources no longer
The minimum size used with DosSubSetMem is 72 bytes. This since the memory
pool contains 64 bytes of control information, and then you must add a
multiple of 8 bytes for you to have memory to use.
Do NOT use DosSetMem to set or change the
attributes of a page managed by the suballocation function. It can be
done, but the result is unpredictable.
All pages in the memory pool should have the same attributes, and at least
read/write access must have been requested for the pages when the memory
DosSubSetMem( grow) is very closely related to memory and perfomance
requirements of the requester.
If the requester needs the best possible performance for DosSubFreeMem, together with a guarantee that
those requests will not fail due to lack of swap space, the requester
should not use the sparse feature. This is because the suballocation
function dynamically commit pages and request swap space for them. In this
case the DosSubSetMem( grow) should be used to notify the suballocation
function that more committed memory is available. Since, in most cases,
this is not needed, they should instead allow the suballocation function to
manage the pages in the memory pool and should initialize it with the
sparse attribute set. In this case DosSubSetMem(grow) should have to be
/* The address of the memory pool used for suballocation. */
/* Flags describing the memory object which we */
/* suballocate. */
/* Size in bytes of the memory pool. */
/* Just to take care of the return code. */
Size = 40000;
/* The memory pool has a size of 40000 bytes. This is */
/* already a multiple of 8 bytes, so no rounding down is */
/* made by the system. */
Flags = DOSSUB_INIT | DOSSUB_SPARSE_OBJ;
/* The memory pool should be initialized and memory */
/* commitment should be taken care of by the following */
/* DosSubAllocMem calls. */
rc = DosSubSetMem( Offset, Flags, Size);
if (rc != 0)
/* We have an error we must take care of. */
Stefan Mars -
Last modified March 16/1996
Please send all errors, comments, and suggestions to:
The OS/2 API Project