Managing Memory for a Varying-Length Structure

Home | Previous Page | Next Page DataBlade API Overview > Accessing SQL Data Types > Varying-Length Data Type Structures >

Managing Memory for a Varying-Length Structure

The following table summarizes the memory operations for a varying-length structure.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_new_var( ), mi_streamread_lvarchar( ), mi_string_to_lvarchar( ), mi_var_copy( )
Current memory duration	Destructor	mi_var_free( )

This section describes the DataBlade API functions that allocate and deallocate a varying-length structure.

Important:

Do not use either the DataBlade API memory-management functions (such as mi_alloc( ) and mi_free( )) or the operating-system memory-management functions (such as malloc( ) and free( )) to handle allocation of varying-length structures.

Creating a Varying-Length Structure

Table 10 lists the DataBlade API functions that create a varying-length structure. These functions are constructor functions for a varying-length structure.

Table 10. DataBlade API Allocation Functions for Varying-Length Structures
Accessor Function Name	Description
mi_new_var( )	Creates a new varying-length structure with a data portion of the specified size
mi_streamread_lvarchar( )	Reads a varying-length structure (mi_lvarchar) value from a stream and copies the value to a buffer
mi_string_to_lvarchar( )	Creates a new varying-length structure and puts the specified null-terminated string into the data portion The data does not contain a null terminator once it is copied to the data portion.
mi_var_copy( )	Allocates and creates a copy of an existing varying-length structure The copy contains its own data portion with the same varying-length data as the original varying-length structure.

The varying-length structure is not contiguous. The allocation functions in Table 10 allocate this structure in two parts:

The varying-length descriptor is a fixed-length structure that stores the metadata for the varying-length data.
The allocation functions allocate the varying-length descriptor and set the data length and the data pointer in this descriptor.
The data portion contains the actual varying-length data.
The allocation functions allocate the data portion with the length that is specified in the varying-length descriptor. They then set the data pointer in the varying-length descriptor to point to this data portion.

Important:

The varying-length data itself resides in a separate structure; it does not actually reside in the varying-length descriptor.

For example, suppose you call the mi_new_var( ) function that Figure 4 shows.

Figure 4. A Sample mi_new_var( ) Call

mi_lvarchar *new_lvarch;
...
new_lvarch = mi_new_var(200);

Figure 5 shows the varying-length structure that this mi_new_var( ) call allocates. This structure consists of both a descriptor and a data portion of 200 bytes. The mi_new_var( ) function returns a pointer to this structure, which the code in Figure 4 assigns to the new_lvarch variable.

Figure 5. Memory Allocated for a Varying-Length Structure

begin figure description - This figure is described in the surrounding text. - end figure description

Server Only

The allocation functions in Table 10 allocate the varying-length structure with the current memory duration. By default, the current memory duration is PER_ROUTINE. For PER_ROUTINE memory, the database server automatically deallocates a varying-length structure at the end of the UDR in which it was allocated. If your varying-length structure requires a longer memory duration, call the mi_switch_mem_duration( ) function before the call to one of the allocation functions in Table 10.

End of Server Only

The allocation functions in Table 10 return the newly allocated varying-length structure as a pointer to an mi_lvarchar data type. For example, the call to mi_new_var( ) in Figure 4 allocates a new mi_lvarchar structure with a data portion of 200 bytes.

To allocate other varying-length data types, cast the mi_lvarchar pointer that the allocation function returns to the appropriate varying-length data type. For example, the following call to mi_new_var( ) allocates a new mi_sendrecv varying-length structure with a data portion of 30 bytes:

mi_sendrecv *new_sndrcv;
...
new_sndrcv = (mi_sendrecv *)mi_new_var(30);

This cast is not strictly required, but many compilers recommend it and it does improve clarity of purpose.

Deallocating a Varying-Length Structure

A varying-length structure has a default memory duration of the current memory duration. To conserve resources, use the mi_var_free( ) function to explicitly deallocate the varying-length structure once your DataBlade API module no longer needs it. The mi_var_free( ) function is the destructor function for a varying-length structure. It frees both parts of a varying-length structure: the varying-length descriptor and the data portion.

Important:

Do not use the DataBlade API memory-management function mi_free( ) to deallocate a varying-length structure. The mi_free( ) function does not deallocate both parts of a varying-length structure.

Use mi_var_free( ) to deallocate varying-length structures that you have allocated with mi_new_var( ) or mi_var_copy( ). Do not use it to deallocate any varying-length structure that the DataBlade API has allocated.

The mi_var_free( ) function accepts as an argument a pointer to an mi_lvarchar value. The following call to mi_var_free( ) deallocates the mi_lvarchar varying-length structure that Figure 4 allocates:

mi_var_free(new_lvarch);

To deallocate other varying-length data types, cast the mi_lvarchar argument of mi_var_free( ) to the appropriate varying-length type, as the following code fragment shows:

mi_sendrecv *new_sndrcv;
...
new_sndrcv = (mi_sendrecv *)mi_new_var(30);
...
mi_var_free((mi_lvarchar *)new_sndrcv);

This cast is not strictly required, but many compilers recommend it and it does improve clarity of purpose.