Obtain the data pointer

The mi_get_vardata() and mi_get_vardata_align() functions obtain the actual data pointer from the varying-length descriptor. Through this data pointer, you can directly access the varying-length data.

The following code fragment uses the mi_get_vardata() function to obtain the data pointer from the varying-length structure in Figure 2:

mi_lvarchar *new_lvarch;
char *var_ptr;
...
/* Get the data pointer of the varying-length structure */
var_ptr = mi_get_vardata(new_lvarch);

The following figure shows the format of the varying-length structure that new_lvarch references after the preceding call to mi_get_vardata() successfully completes.

Figure 1. Getting the data pointer from a varying-length structure

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

You can then access the data through the var_ptr data pointer, as the following code fragment shows:

mi_lvarchar *new_lvarch;
mi_integer var_len, i;
mi_char one_char;
mi_char *var_ptr;

var_ptr = mi_get_vardata(new_lvarch);
var_len = mi_get_varlen(new_lvarch);
for ( i=0; i<var_len; i++ )
   {
   one_char = var_ptr[i];
   /* process the character as needed */
   ...
   }

Server only:

The database server passes text data to a UDR as an mi_lvarchar structure. Figure 1 shows the implementation of a user-defined function named initial_cap(), which ensures that the first letter of a character string is uppercase and that subsequent letters are lowercase.

The initial_cap() function uses mi_get_vardata() to obtain each character from the data portion of the varying-length structure. This data portion contains the character value that the function receives as an argument. The function checks each letter to ensure that it has the correct case. If the case is incorrect, initial_cap() uses the data pointer to update the appropriate letter. The function then returns a new mi_lvarchar structure that holds the result.

The varying-length structure aligns data on four-byte boundaries. If this alignment is not appropriate for your varying-length data, use the mi_get_vardata_align() function to obtain the data aligned on a byte boundary that you specify. You can determine the alignment of a data type from its type descriptor with the mi_type_align() function.

Tip: When you obtain aligned data from a varying-length structure that is associated with an extended data type, specify an alignment value to mi_get_vardata_align() that is appropriate for the extended data type.

The mi_get_vardata_align() function obtains the number of bytes that the data-length field specifies.