## Printer Device Driver

[prev][next][parent][TOC]

### GplMemoryCreateInstance

Description

This function creates an MCB and a user heap.

Format

    HMCB APIENTRY GplMemoryCreateInstance( ULONG  ulPrimarySize,

                                           ULONG  ulExtSize,

                                           ULONG  ulThreshold,

                                           ULONG  ulType );

Parameters

ulPrimarySize (ULONG) Initial Heap size in bytes.

ulExtSize (ULONG) Heap growth size fills in bytes.

ulThreshold (ULONG) Threshold for heap allocation. Requests larger than this will be converted to DosAllocMem.

ulType (ULONG) Heap type (process, shared). See the following notes for a description of process and shared heaps.

Returns

Success Valid handle to memory control block.
Failure NULL.
WinGetLastError() will return one of the following:
PMERR_MEMORY_ALLOCATION_ERROR
PMERR_INV_OR_INCOMPAT_OPTIONS

Notes

Treat creating a memory instance like creating a memory heap. The ulSize parameter should be a reasonable amount of memory for most of your processing. It is not necessary to set ulSize to a high number so that you do not run out of memory, because the memory area will automatically grow if your processing allocates more than the amount originally set by ulSize.

When the memory area is automatically grown, the ulExtSize value is used to determine how large an additional memory area should be created. A default value of 0 (zero) may be used, and the growth size will be tailored to a reasonable amount for the OS/2 version.

The GplMemoryAlloc() API will allocate memory blocks differently based on the ulThreshold value. Typically, allocations of memory of sizes less than the threshold are allocated in a fast access memory area, and sizes larger than the threshold are allocated from a different memory pool. A default value of 0 (zero) may be used and the threshold will be automatically set to perform most efficiently on the current OS/2 version.

The ulType parameter allows you to specify the type of memory that you want to allocate. This defines the scope of accessibility to the memory within your driver or program and is one of the following:

SHARED_MEMORY Used to create a global memory area (heap). For example, it is used for allocating global data like string tables in a printer driver.

PROCESS_MEMORY Used to create a per process memory area (heap). For example , it is used for allocating a per device context (DC) memory in a printer driver.