Oninit® SQLMorph — C to UDR: type mapping
How c2udr maps C types to SQL types, what it refuses, and how a map file adds the types of a particular library.
c2udr is a work in progress. These pages show real output of the current version, run against an Informix 15.0 test engine; they are examples, not a released product.
Built-in mapping
| C | SQL | Notes |
|---|---|---|
char, short | SMALLINT | |
int, unsigned short | INTEGER | |
long, long long, unsigned int, unsigned long, size_t, time_t | BIGINT | Passed by pointer. Unsigned 64-bit values above 263 cannot be represented. |
float, double | REAL, FLOAT | Passed by pointer. |
char *, const char * | LVARCHAR | A returned null pointer is SQL NULL. |
struct dtime, dtime_t | DATETIME YEAR TO FRACTION(5) | |
dec_t | DECIMAL | |
char *buf, size_t len | result LVARCHAR | An output buffer; 512 bytes unless set otherwise. |
non-const T *out on a void function | result of type T | One per function. |
void function without output | CREATE PROCEDURE |
What is refused
A function that cannot be wrapped is left out of the library, and the report names it with the reason. The reasons are:
- variable arguments, or a function-pointer parameter;
void *, or three or more levels of pointer;- more than one output parameter, a struct output with several members, or an output parameter together with a return value;
- a struct or other type that has no mapping — add one in a map file;
- a function declared in the headers but not defined in the library's sources.
The map file
One section per library type, and optionally one per function:
[type Idate_t]
sql = DATE # SQL type
wtype = mi_date # C type of the wrapper argument and result
byref = no # yes when the engine passes it through a pointer
in = {l} = (Idate_t){a}; # fill the local {l} from the wrapper argument {a}
out = {r} = (mi_date){l}; # fill the result {r} from the local {l}
[func idatetostr]
arg.idate = Idate_t # the header declares the argument as long
| Key | Meaning |
|---|---|
sql, wtype, byref | The SQL type, the C type the wrapper receives, and whether the engine passes it through a pointer. |
in, out | C statements converting the wrapper's type to the library's type and back. For a type passed by pointer, {r} in out points at storage c2udr has already allocated. |
init | Statements run before the call when the type is an output parameter. |
skip, name, bufsize, variant, ret, arg.NAME | Per function: leave it out, give it another SQL name, size its output buffer, register it as VARIANT, treat the return value as another C type, or give one parameter another C type. |
role.NAME | Set to in for a non-const pointer parameter that the function only reads. Without it a non-const pointer is an output. |
buf.NAME | A char * output buffer of the given size when the function has no size parameter for it (buf.result = 128). |
null_if | For a function with an output parameter and a status return value: the result is SQL NULL when this condition on {rv} holds ({rv} < 0). ret = void drops the return value instead. |
free.NAME | For a T ** output: the library function that releases the object it handed back, called after the result was converted. |
Structs
The C struct comes from the header, so the map only says which SQL value each member is. A struct parameter becomes one SQL argument per member, and c2udr fills the struct from them inside the wrapper:
[struct timeval] # or [type my_t] for a typedef name fields = tv_sec:BIGINT, tv_usec:INTEGER # member:SQLTYPE [func gdttomydt] role.date = in # takes gdt_t * but only reads it
The SQL types are SMALLINT, INTEGER, BIGINT, DATE, REAL and FLOAT. This works for a struct passed by value, for a const T *, and for a non-const pointer marked role.NAME = in. A SQL NULL in any member gives a NULL result without calling the function, members not listed are zero, and a member name that the header does not declare is an error.
A T ** parameter is an output: the library allocates the object, c2udr converts it with the type's out statement and, with free.NAME, releases it. A null pointer is SQL NULL.
A struct output can be one SQL value. Add result.sql, result.wtype, result.byref and result.out to the struct section; struct timeval comes out as microseconds in a BIGINT in the date library. A struct that the library fills with several members that should become separate SQL values would need a ROW result and is not supported yet.
When the SQL side is a single value built by C code, such as a DATETIME made from gdt_t or an INTERVAL passed as the engine's own struct, describe it with [type] and the in and out statements. A [prelude] section with code = ... adds C helper functions to the generated file for those statements to call.
See a real date library for a map file in use.