Progress
External Program
Interfaces


Initializing and Uninitializing MEMPTR Variables

After declaring a MEMPTR variable, you must initialize it before you can use it. In general, to initialize a MEMPTR variable, you use the SET-SIZE statement to allocate a region of memory and associate it with the variable.

NOTE: You can also allocate the memory region for a MEMPTR variable using a shared library routine. In this case, you must still use the SET-SIZE statement to initialize the size of the returned memory region in Progress. For more information, see Shared Library and DLL Support."

Initializing MEMPTR Variables Using the SET-SIZE Statement

This is the syntax for the SET-SIZE statement:

SYNTAX
SET-SIZE ( mptr-name ) = expression 

The value mptr-name is the name of a MEMPTR variable, and expression is an integer expression specifying the size, in bytes, of a memory region associated with mptr-name. The value of expression can also be zero (0), which frees any memory previously allocated to mptr-name. Progress uses this size to perform bounds checking that ensures you do not read or write to portions of memory outside of the specified region.

If mptr-name is uninitialized (that is, defined but not associated with any memory region) and expression is greater than zero (0), the SET-SIZE statement allocates a memory region whose size is specified by expression, and associates it with mptr-name. If mptr-name is already initialized and expression is greater than zero (0), the SET-SIZE statement has no effect.

To resize memory allocated to a MEMPTR variable, you must invoke SET-SIZE with an expression of zero (0), then invoke SET-SIZE with an expression equal to the new allocation.

Checking a MEMPTR Variable For Initialization

You might not be sure whether a particular MEMPTR variable is already initialized when you try to initialize it. You can verify that the variable is initialized and obtain the size of its memory region using the GET-SIZE function. This is the syntax for the GET-SIZE function:

SYNTAX
GET-SIZE ( mptr-name ) 

If mptr-name is initialized, the GET-SIZE function returns the size of its memory region. Otherwise, it returns zero (0).

NOTE: To return a memory size greater than zero (0), the variable must be fully initialized with the SET-SIZE statement, not just allocated by a shared library routine. For more information, see Shared Library and DLL Support."

Freeing Memory Associated With a MEMPTR Variable

The region of memory associated with a MEMPTR variable remains allocated until it is freed. Progress does not automatically free the memory for you. It is up to you to ensure that the memory is freed.

You can free the memory using SET-SIZE with an expression of zero (0). SET-SIZE then deallocates (frees) any memory region associated with mptr-name. This makes mptr-name uninitialized.

NOTE: When working with shared library routines, you must fully understand the memory management provided by these routines before using MEMPTR variables with them effectively. For more information, see Shared Library and DLL Support."


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095