Utility Functions Generated by BladeSmith

BladeSmith generates support functions that it calls from other generated code. These functions include:

• Gen_IsMMXMachine(). This function determines whether the database server is running on a computer with an Intel MMX processor. This function is only generated if you specify that you want MMX-enabled functions when you generate source code. See The Gen_IsMMXMachine() Utility Function for more information.
• Gen_LoadLOFromFile(). When an opaque type includes a large object handle, BladeSmith includes this function to retrieve the large object data from a disk file.
• Gen_nstrwords(). This function counts the number of values (each separated by a blank space) in a formatted string. This function is called from input and import functions to retrieve values from variable-length opaque types.
• Gen_sscanf(). This function is called from input and import functions to convert text data to the C structure for an opaque type. See The Gen_sscanf() Utility Function for more information.
• Gen_StoreLOToFile(). When an opaque type includes a large object handle, BladeSmith includes this function to write large object data to a disk file.
• Gen_Trace(). This function processes trace messages and errors. This function is generally invoked by the macros DBDK_TRACE_ENTER(), DBDK_TRACE_EXIT(), DBDK_TRACE_MSG(), and DBDK_TRACE_ERROR(). See Tracing and Error Handling for more information.

Most of the generated utility functions are called by code that BladeSmith generates, and you typically do not use them in your code. The Gen_sscanf() utility function, however, can be useful in your input/output functions. You can use the Gen_IsMMXMachine() function if you use Intel MMX instructions in your code.

The Gen_sscanf() Utility Function

The Gen_sscanf() utility function scans one value from an input string and stores it at a given address. Gen_sscanf() returns a pointer that points just past the value it scanned from the input string.

Gen_sscanf() takes the following arguments:

Gen_Con

The database connection handle

Gen_Caller

The name of the calling function

Gen_InData

A pointer to the text to be scanned

Gen_InDataLen

An integer containing the length of the text (mi_lvarchar strings are not null-terminated)

Gen_Width

An integer containing the maximum data length for text data

Gen_Format

A string containing a sscanf() format string for the structure member to be scanned

Gen_Result

A pointer to the member in the structure where Gen_sscanf() stores the scanned value

The generated input and import functions call Gen_sscanf() once for each structure member. Gen_sscanf() requires an input string in the current locale and uses the IBM Informix GLS routines to scan the string.

The Gen_IsMMXMachine() Utility Function

The Gen_IsMMXMachine() utility function can be used when you include Intel MMX media enhancement technology in your DataBlade module. The function tests the processor in the database server computer to determine if it has MMX technology support. If MMX technology support is found, Gen_IsMMXMachine() returns 1.

If the database server machine does not have MMX technology support, or if the FORCE_NO_MMX environment variable is set in the database server environment, Gen_IsMMXMachine() returns 0. On UNIX machines, Gen_IsMMXMachine() always returns 0.

To execute MMX instructions when possible and to execute portable C code on computers that do not have MMX technology support, call Gen_IsMMXMachine() in an IF statement.

Gen_IsMMXMachine() declares a static INT flag, MMXType. It first looks for the FORCE_NO_MMX environment variable, which must be set in the environment before the database server is started.

If FORCE_NO_MMX is found, the function sets MMXType to 0 without testing the CPU. If FORCE_NO_MMX is not found, the function tests the processor and sets the MMXType variable to 1 if MMX technology support is found or 0 if not. After the value of MMXType is set, Gen_IsMMXMachine() returns its value immediately, so that tests are performed once after the DataBlade module object file is loaded.