These APIs can be used for standard memory management operations:

_SDK_AllocHandle(); Allocate relocatable memory in a platform-independent manner

_SDK_AllocHandleClear(); Allocate relocatable memory in a platform-independent manner and clear it

_SDK_AllocPtr(); Allocate non-relocatable memory

_SDK_AllocPtrClear(); Allocate non-relocatable memory and clear it

_xFreeHandle(); Free previously allocated relocatable memory

_xFreePtr(); Deallocate a block of non-relocatable memory

CloneHandle(); Clone a memory handle

ClonePtr(); Clone a Pointer

env_CompactMem(); Compact Memory

LockHandle(); Lock a memory handle

Ptr2Handle(); Pointer -to- Handle Conversion

Ptr2XHandle(); Pointer -to- XHandle Conversion

ReAllocHandle(); Reallocate Handle

ReAllocHandleClear(); Reallocate Handle Clear

SetvarHdlSize(); Set Variable Handle Size

SizeOfHandle(); Get Size of Handle

SizeOfPtr(); Get Size of Pointer

UnlockHandle(); Unlock memory handle

This function allocates re-locatable memory in a platform-independent manner.

Syntax:

MEMHDL PUBLIC
_SDK_AllocHandle (
     MEMSIZE size,
     char FAR * pFileName,
     int lineNo
);

Input:

size: Size in bytes to allocate

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if an error occurs.

Return:

MEMHDL: Pointer to allocated space if successful.

Also See:

_SDK_AllocHandleClear(), _xFreeHandle(), CloneHandle(), LockHandle(), ReAllocHandle(), SizeOfHandle(), UnlockHandle()

This function allocates re-locatable memory in a platform-independent manner. The allocated memory is guaranteed to be zeroed.

Syntax:

MEMHDL PUBLIC
_SDK_AllocHandleClear (
     MEMSIZE size,
     char FAR * pFileName,
     int lineNo
);

Input:

size: Size in bytes to allocate

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if an error occurs.

Return:

MEMHDL: Pointer to allocated space if successful.

Also See:

_SDK_AllocHandle(), _xFreeHandle(),CloneHandle(), LockHandle(), ReAllocHandleClear(), SizeOfHandle(), UnlockHandle()

This function allocates a block of non-re-locatable memory.

Syntax:

MEMPTR PUBLIC
_SDK_AllocPtr (
     MEMSIZE size,
     char FAR * fileName,
     int lineNo
);

Input:

size: Size in bytes to allocate

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if an error occurs.

Return:

MEMPTR: Pointer to requested number of allocated bytes.

Also See:

_SDK_AllocPtrClear(), _xFreePtr(), ClonePtr(), LockHandle(), SizeOfPtr()

This function allocates a block of zeroed non-re-locatable memory.

Syntax:

MEMPTR PUBLIC
_SDK_AllocPtrClear (
     MEMSIZE size,
     char FAR * fileName,
     int lineNo
);

Input:

size: Size in bytes to allocate

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if error an occurs.

Return:

MEMPTR: Pointer to requested number of allocated bytes.

Notes:

The actual physical size of the ptr (the value returned by SizeOfPtr) will be at least the size bytes long. It could be longer.

Also See:

_SDK_AllocPtr(), _xFreePtr, ClonePtr(), LockHandle(), SizeOfPtr()

This function frees previously allocated re-locatable memory (i.e., memory allocated by _SDK_AllocHandle() or _SDK_AllocHandleClear()).

Syntax:

void PUBLIC
_xFreeHandle (
     MEMHDL handle,
     char FAR * pFileName,
     int lineNo
);

Input:

handle: Pointer to previously allocated space (i.e., returned by _SDK_AllocHandle() or _SDK_AllocHandleClear())

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if an error occurs.

Return:

None

Also See:

_SDK_AllocHandle(), _SDK_AllocHandleClear()

This function de-allocates a block of non-re-locatable memory previously allocated by _SDK_AllocPtr() or _SDK_AllocPtrClear().

Syntax:

void
_xFreePtr (
     MEMPTR dPtr,
     char FAR * pFileName,
     int lineNo
);

Input:

dPtr: Pointer to previously allocated memory returned by _SDK_AllocPtr() or _SDK_AllocPtrClear()

pFileName: For debugging, identifies the calling module if an error occurs.

lineNo: For debugging, identifies the line number in the calling module if an error occurs.

Return:

None

Also See:

_SDK_AllocPtr(), _SDK_AllocPtrClear()

This function duplicates a re-locatable memory block that was previously allocated by _SDK_AllocHandle() or _SDK_AllocHandleClear().

Syntax:

BOOLEAN16 PUBLIC
CloneHandle (
     MEMHDL FAR * HandAdr
);

Input:

HandAdr: Handle to previously allocated re-locatable memory

Return:

BOOLEAN16: TRUE/FALSE

TRUE=

Handle successfully cloned

FALSE=

Failure

Example:

AnodeInfoPtr pNode;
pNode = (AnodeInfoPtr)
     LockHandle((MEMHDL)hNode);
/* clone the text handle */
*hText = (MEMHDL) (*pNode).info.text.hText;
assert( CloneHandle(hText) );
UnlockHandle((MEMHDL)hNode);

Notes:

_SDK_AllocHandle() or _SDK_AllocHandleClear() must be used to allocate the re-locatable memory and obtain the MEMHDL before this function is called.

Also See:

_SDK_AllocHandle(), _SDK_AllocHandleClear(), _xFreeHandle(), LockHandle(), ReAllocHandle(), SizeOfHandle(), UnlockHandle()

This function duplicates a non-relocatable memory block previously allocated by _SDK_AllocPtr() or _SDK_AllocPtrClear().

Syntax:

BOOLEAN16 PUBLIC
ClonePtr (
     MEMPTR FAR * ppData
);

Input:

ppData; Pointer to a previously allocated non-relocatable memory block

Return:

BOOLEAN16: TRUE/FALSE

TRUE=

success

FALSE=

failure

Also See:

_SDK_AllocPtr(), _SDK_AllocPtrClear(), _xFreePtr(), ClonePtr(), LockHandle(), SizeOfPtr()

This function rearranges allocated memory to make sure that size_wanted is available for future allocations.

Syntax:

MEMSIZE PUBLIC
env_CompactMem (
     MEMSIZE size_wanted
);

Input:

MEMSIZE: Desired size of memory

Return:

MEMSIZE: Compacted memory size

This function locks and de-references a previous re-locatable memory allocation.

Syntax:

MEMPTR PUBLIC
LockHandle (
     MEMHDL handle
);

Input:

MEMHDL: Pointer to a memory handle previously allocated by _SDK_AllocHandle() or _SDK_AllocHandleClear()

Return:

MEMPTR: Pointer to the locked handle

Example:

pAnode = (AnodeInfoPtr)::
     LockHandle(pSelItem->data.hAnode);
     nAnodeType = pAnode->nNodeType;
     ::UnlockHandle(pSelItem->data.hAnode);

Also See:

UnlockHandle()

This function creates a handle to a section of re-locatable memory and copies the contents of another section of memory into it.

Syntax:

BOOLEAN16 PUBLIC
Ptr2Handle (
     MEMPTR sPtr,
     MEMHDL FAR * HandAdr,
     MEMSIZE sLength
);

Input:

sPtr: Pointer to an existing section of re-locatable memory

HandAdr: Memory handle

sLength: Length to copy

Return:

BOOLEAN16: TRUE/FALSE

TRUE=

successful

FALSE=

failure

Also See:

Ptr2XHandle()

This function copies a block of memory to an existing handle. The handle is resized to sLength bytes

Syntax:

BOOLEAN16 PUBLIC
Ptr2XHandle (
     MEMPTR sPtr,
     MEMHDL FAR * HandAdr,
     MEMSIZE sLength
);

Input:

sPtr: Pointer to the block of memory to copy

HandAdr: Pointer to an existing memory handle

sLength: Size handle should be resized to

Return:

BOOLEAN16: TRUE/FALSE

TRUE=

successful

FALSE=

failure

Also See:

Ptr2Handle()

This function resizes a previous re-locatable memory allocation.

Syntax:

MEMHDL PUBLIC
ReAllocHandle (
     MEMHDL FAR *handle,
     MEMSIZE size
);

Input:

handle: Handle to previously allocated re-locatable memory

size: New size (in bytes)

Return:

MEMHDL: Handle to resized memory

Example:

/*
** here when we need more space
** remember current position as
** an offset since the ReAllocHandle
** call can change the handle
*/
ulOffset = pRamFile->pCurrent -
     pRamFile->pBuffer;
UnlockHandle(h = pRamFile->hBuffer);
/* attempt to increase the buffer size */
newBytes = (count / REALLOC_RAMFILE + 1)
      * REALLOC_RAMFILE;
ReAllocHandle(&h,pRamFile->bufSize + newBytes);
if (!h)return EOF;

Also See:

_SDK_AllocHandle(), ReAllocHandleClear()

This function resizes a previous re-locatable memory allocation. If handle is increased in size, the new memory is zeroed.

Syntax:

MEMHDL PUBLIC
ReAllocHandleClear (
     MEMHDL FAR *handle,
     MEMSIZE size
);

Input:

handle: Handle to previously allocated re-locatable memory

size: New Size (in bytes)

Return:

MEMHDL: Handle to resized memory

Also See:

_SDK_AllocHandle(), ReAllocHandle()

This function changes the handle size of a variable array type.

Syntax:

INT16 PUBLIC
SetvarHdlSize (
     MEMHDL *hHandle,
     MEMPTR *pPtr,
     INT16 ItemSize,
     INT16 NumItems
);

Input:

hHandle: Pointer to a memory handle to be adjusted.

pPtr: Pointer to a pointer to a variable array

ItemSize: Size of each item in the variable array.

NumItem: Number of item in the variable array.

Return:

INT16: Error code (potential memory allocation failure)

Example:

nStrings = TEXTOBJ.nTCTexts;
for (i = 0; i < nStrings; i++)
{
     SetvarHdlSize (&TCTEXT[i].vaStyle,
          &TCTEXT[i].pStyle,
           0, 0);
}

This function returns the allocated size in bytes of handle.

Syntax:

MEMSIZE PUBLIC
SizeOfHandle (
     MEMHDL handle
);

Input:

handle: Pointer to a previously allocated memory handle.

Return:

MEMSIZE: Allocated size (in bytes) of handle

Example:

/* Get current size of array */
lVarArrayByteSize = SizeOfHandle
      (hVarArray) - COUNT_BYTESIZE;
/* Dynamically get # of array elements */
nNumArrayElements =
     lVarArrayByteSize/lArrayElementSize;

Also See:

SizeOfPtr()

This function returns the actual number of allocated bytes for a locked block of memory. This number will be greater than or equal to the number of requested bytes.

Syntax:

MEMSIZE PUBLIC
SizeOfPtr (
     MEMPTR p
);

Input:

MEMPTR: Memory pointer

Return:

MEMSIZE: Actual number of allocated bytes

Example:

/* Get current size of array */
lArrayByteSize = SizeOfPtr (pArray);
/* Get # of array elements */
nNumArrayElements =
     lArrayByteSize/lArrayElementSize;

Also See:

SizeOfHandle()

This function unlocks re-locatable memory that was previously locked by LockHandle().

Syntax:

void PUBLIC
UnlockHandle (
     MEMHDL handle
);

Input:

handle: Pointer to previously allocated space (i.e., returned by _SDK_AllocHandle() or _SDK_AllocHandleClear())

Return:

None

Example:

pAnode = (AnodeInfoPtr)::
     LockHandle(pSelItem->data.hAnode);
     nAnodeType = pAnode->nNodeType;
     ::UnlockHandle(pSelItem->data.hAnode);

Also See:

_SDK_AllocHandle(), _SDK_AllocHandleClear(), LockHandle()