Create a varying-length structure

The following table lists the DataBlade® API functions that create a varying-length structure. These functions are constructor functions for a varying-length structure.

Table 1. 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 DataBlade API allocation functions for varying-length structures 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 is in a separate structure; it is not actually in the varying-length descriptor.

For example, suppose you call the mi_new_var() function that the following code shows.

Figure 1: A sample mi_new_var() call

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

The following figure 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 A sample mi_new_var() call assigns to the new_lvarch variable.

begin figure description - This figure is described in the surrounding text. - end figure description — Figure 2: Memory allocated for a varying-length structure

Server only: The allocation functions in DataBlade API allocation functions for varying-length structures 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 DataBlade API allocation functions for varying-length structures.

The allocation functions in DataBlade API allocation functions for varying-length structures 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 A sample mi_new_var() call 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.