Text input and output functions

BladeSmith generates complete C code for these functions.

The generated code

The generated code for the text input and output functions uses a default text representation: a string containing all members of the structure, delimited with spaces.

Strings are enclosed in quotation marks ('). Large objects are represented as external file names enclosed in quotation marks. The input function calls the sscanf() C library function. Use character representations for these types that sscanf() recognizes.

typedef struct
{
   mi_double_precision            x;
   mi_double_precision            y;
}
Pnt;

'x y'

insert into mytable (col1) values ('12.3 66.9');

Text input function

The text input function has two arguments: an mi_lvarchar pointer, which points to the text that is to be converted, and an unused MI_FPARAM pointer.

The text input function returns a pointer to a filled-in C structure for the Pnt data type. The contents of this structure are written to the database table. The function allocates memory for the opaque type it returns, as follows:

   /* Allocate memory room to build the UDT in. */
   Gen_RetVal = (Pnt *)mi_alloc( sizeof(Pnt));
   if(Gen_RetVal == 0)
   {
      /*
      ** Memory allocation has failed so issue
      ** the following message and quit.
      **
      **    "Memory allocation has failed in PntInput."
      */
      mi_db_error_raise(Gen_Con, MI_SQL, ERRORMESG2,
         "FUNCTION%s", "PntInput", (char *)NULL);

The database server frees the allocated memory.

   /* Get the data value for Gen_OutData->x. */
   Gen_InData = Gen_sscanf(Gen_Con, "PntInput", Gen_InData,
            mi_get_varlen(Gen_param1), 0,
            "%lf %n",
            (char *)&Gen_OutData->x);

   /* Get the data value for Gen_OutData->y. */
   Gen_InData = Gen_sscanf(Gen_Con, "PntInput", Gen_InData,
            mi_get_varlen(Gen_param1), 0,
            "%lf %n",
            (char *)&Gen_OutData->y);

This code calls the Gen_sscanf() utility function, which BladeSmith adds to each generated C source file.

   /* Return the UDT value. */
   return Gen_RetVal;

Text output function

The text output function takes a pointer to the opaque type structure and an MI_FPARAM pointer and returns a text representation of the data type in an mi_lvarchar value.

BladeSmith operates under the assumption that the text representation is a string containing character representations of all of the structure members delimited with spaces. The function encloses strings and filenames for large objects in double quotation marks.

The generated text output function computes the maximum length of the string it returns and calls mi_new_var() to allocate an mi_lvarchar argument, Gen_RetVal. The database server frees the allocated memory later.

   /* Format the value for Gen_InData->x. */
   sprintf(Gen_OutData, "%lf ", Gen_InData->x);
   Gen_OutData += strlen(Gen_OutData);

   /* Format the value for Gen_InData->y. */
   sprintf(Gen_OutData, "%lf", Gen_InData->y);
   Gen_OutData += strlen(Gen_OutData);

Between calls to sprintf(), the function resets Gen_OutData to point to the end of the string.

Customize the code

To use an input text format different from the default format, or if the C structure contains data types that BladeSmith cannot scan with Gen_sscanf(), you must modify the generated text input function code.

If you want an input text format that is different from the default, replace the generated code with your own. For example, you can choose to delimit values with commas instead of spaces. Your code might be able to call the Gen_sscanf() function, or you might need to write your own scanning function.

In the Circle DataBlade module, the text representation of the Pnt data type is changed from the default format, 'x y', to a new format: '(x, y).'

   /* Get the data value for Gen_OutData->x. */
   Gen_InData = Gen_sscanf(Gen_Con, "PntInput", Gen_InData,
            mi_get_varlen(Gen_param1), 0,
            "(%lf %n,",
            (char *)&Gen_OutData->x);

   /* Get the data value for Gen_OutData->y. */
   Gen_InData = Gen_sscanf(Gen_Con, "PntInput", Gen_InData,
            mi_get_varlen(Gen_param1), 0,
            "%lf %n)",
            (char *)&Gen_OutData->y);

If you change the text input function to support a text format different from the default, also change the text output function. The string returned by the text input function is a valid string for the text output function.

   /* Format the value for Gen_InData->x. */
   sprintf(Gen_OutData, "(%lf,", Gen_InData->x);
   Gen_OutData += strlen(Gen_OutData);

   /* Format the value for Gen_InData->y. */
   sprintf(Gen_OutData, "%lf)", Gen_InData->y);
   Gen_OutData += strlen(Gen_OutData);

Smart large object considerations

Large objects are represented as external file names enclosed in quotation marks.

Examples