UDA数据值

结构定义

在诸如 mco_uda_put() 和 mco_uda_get() 这样的 UDA 数据访问调用中，需要一个类型为 mco_uda_value_t 的结构体。其在 mcouda.h 中的结构定义如下：

    typedef struct tag_mco_uda_value_t_ {
        mco_dict_type_t type;
        union {
            unsigned char           u1;   		/* MCO_DD_UINT1 */
            unsigned short          u2;   		/* MCO_DD_UINT2 */
            unsigned int            u4;   		/* MCO_DD_UINT4, MCO_DD_DATE, MCO_DD_TIME */
            uint8                   u8;   		/* MCO_DD_UINT8, MCO_DD_AUTOID, MCO_DD_AUTOOID, MCO_DD_DATETIME */
            char                    i1;   		/* MCO_DD_INT1 */
            short                   i2;   		/* MCO_DD_INT2 */
            int                     i4;   		/* MCO_DD_INT4 */
            mco_int8                i8;   		/* MCO_DD_INT8 */
            #ifdef MCO_TARGET_FLOAT_SUPPORTED
                float               f;    		/* MCO_DD_FLOAT */
                double              d;    		/* MCO_DD_DOUBLE */
            #endif
            mco_uda_object_handle_t o;    		/* MCO_DD_STRUCT */
            struct {
                unsigned int        size; 		/* 缓冲区的大小（以字节为单位） */
                unsigned int        len;  		/* 字符串的字符长度 */
                union {
                    char          * c;    		
                    /* char字符串: MCO_DD_STRING, MCO_DD_CHAR, MCO_DD_BINARY, MCO_DD_VARBINARY */
                    nchar_t       * n;    		
                    /* nchar字符串: MCO_DD_NCHAR_STRING, MCO_DD_NCHAR_CHAR */
                    #ifdef MCO_CFG_WCHAR_SUPPORT
                        wchar_t   * w;    		
                        /* wchar字符串：MCO_DD_WCHAR_STRING， MCO_DD_WIDE_CHAR */
                    #endif
                    void          * v;    		
                    /* 通用指针：MCO_DD_BLOB、MCO_DD_REF、MCO_DD_OID */
                } p;                      		/* 指向缓冲区的指针 */
            } p;
        } v;
    } mco_uda_value_t, * mco_uda_value_p;

UDA 值有两个元素，即类型type和值 v。类型可选值如下：

• MCO_DD_UINT1：1 字节整数（非负数）
• MCO_DD_UINT2：2 字节整数（非负数）
• MCO_DD_UINT4：4 字节整数（非负数）
• MCO_DD_UINT8：8 字节整数（非负数）
• MCO_DD_INT1 ：1 字节整数
• MCO_DD_INT2 ：2 字节整数
• MCO_DD_INT4 ：4 字节整数
• MCO_DD_INT8 ：8 字节整数
• MCO_DD_FLOAT：单精度浮点数
• MCO_DD_DOUBLE ：双精度浮点数
• MCO_DD_DATE ：4 字节整数（非负数）
• MCO_DD_TIME ：4 字节整数（非负数）
• MCO_DD_DATETIME ：8 字节整数（非负数）
• MCO_DD_CHAR ：1 字节字符
• MCO_DD_NCHAR_CHAR ：2 字节的Unicode字符
• MCO_DD_WIDE_CHAR：2 字节的Unicode字符
• MCO_DD_NCHAR_STRING ：2 字节的Unicode字符串
• MCO_DD_WCHAR_STRING ：2 字节的Unicode字符串
• MCO_DD_REF：指向对象的 OID 或自动 ID 的 4 字节引用
• MCO_DD_AUTOID ：4 字节的自动标识符
• MCO_DD_AUTOOID：未定义（仅供内部使用）
• MCO_DD_STRUCT ：构造
• MCO_DD_BLOB ：二进制大对象
• MCO_DD_OID：用户自定义的对象 ID
• MCO_DD_BOOL ：1 字节的布尔值
• MCO_DD_SEQUENCE_UINT1 ：1 字节整数序列（非负数）
• MCO_DD_SEQUENCE_UINT2 ：2 字节整数序列（非负数）
• MCO_DD_SEQUENCE_UINT4 ：4 字节整数序列（非负数）
• MCO_DD_SEQUENCE_UINT8 ：8 字节整数序列（非负数）
• MCO_DD_SEQUENCE_INT1：1 字节整数序列
• MCO_DD_SEQUENCE_INT2：2 字节整数序列
• MCO_DD_SEQUENCE_INT4：4 字节整数序列
• MCO_DD_SEQUENCE_INT8：8 字节整数序列
• MCO_DD_SEQUENCE_FLOAT ：浮点数序列
• MCO_DD_SEQUENCE_DOUBLE：双精度序列
• MCO_DD_SEQUENCE_CHAR：字符序列

设置数据库字段的 UDA 值元素

若要准备一个 mco_uda_value_t 结构体 val，以便使用 mco_uda_put() 函数设置数据库对象的字段值，则必须根据字段的类型设置 val 的相应元素。以下各节将演示如何为不同类型的字段准备 val。

简单标量类型

对于简单的标量类型，例如整型、浮点型、双精度型、日期型、时间型、日期时间型、布尔型和自动标识符型，请设置 val.v 中相应的元素。例如：

    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_1 = 1;
    unsigned short field_2 = 2;
    unsigned short field_3 = 3;
 
    /* 设置简单的值 */
    val.type = MCO_DD_UINT4; 	/* 设置字段的类型 */
    val.v.u4   = 999;      		/* 设置合适的联合字段 */
    mco_uda_put(&rec, field_1, 0, &val);
     
     
    val.type = MCO_DD_FLOAT; 	/* 设置字段的类型 */
    val.v.f   = 999.999;      	/* 设置合适的联合字段 */
    mco_uda_put(&rec, field_3, 0, &val);
     
    val.type = MCO_DD_AUTOID; 	/* 设置字段的类型 */
    val.v.u8   = 3;      		/* 设置合适的联合字段 */
    mco_uda_put(&rec, field_3, 0, &val);

字符串类型

对于字符串、字节数组和二进制大对象（blob），应用程序需要提供一个缓冲区，将其分配给相应的缓冲区元素，并按照以下示例设置 size 和 len 元素。 对于类型 MCO_DD_CHAR 或 MCO_DD_STRING，请设置元素 val.v.p.p.c 和 val.v.p.len：

    /* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_no = 2;
    unsigned short inner_field_no = 3;
    unsigned short vlength = 3;
    InnerStruct inner; 			/* 模式中定义的结构体 */
    char buf[1024];
    char msg[256];
     
    /* 放入一个字符向量 */
    mco_uda_field_alloc(&rec, field_no, vLength); /* 分配向量 */
    val.type = MCO_DD_CHAR;  /* 设置字段的类型 */
    val.v.p.p.c = buf;       /* 将指针指向缓冲区 */
    val.v.p.len = 20;        /* 设置字符串长度 */
    for (j = 0; j < vLength; ++j) 
    {
        sprintf(buf, "vch-%d:%d", 1, j); /* 将值放入缓冲区 */
        mco_uda_put(&rec, field_no, j, &val); /* 给对象赋值 */
    }
     
    /* 放入一个字符串向量  */
    mco_uda_field_alloc(&inner, inner_field_no, vLength); /* 分配向量 */
    val.type = MCO_DD_STRING;
    val.v.p.p.c = msg;
    val.v.p.len = 20;
    for (j = 0; j < vLength; ++j) {
        sprintf(msg, "vstr-%d:%d", 2, j);
        mco_uda_put(&rec, inner_field_no, j, &val);
    }

对于类型 MCO_DD_NCHAR_CHAR 或 MCO_DD_NCHAR_STRING，请设置元素 v.p.p.n 和 val.v.p.len：

    /* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_no = 2;
    unsigned short inner_field_no = 3;
    unsigned short vlength = 3;
    InnerStruct inner; 				/* 模式中定义的结构体 */
    char buf[1024];
    char msg[256];
     
    /* 放入一个 Unicode 字符向量 */
    mco_uda_field_alloc(&rec, field_no, vLength); 			/* 分配向量 */
    val.type = MCO_DD_NCHAR;  		/* 设置字段的类型 */
    val.v.p.p.n = buf;       		/* 将指针设置为字符 */
    val.v.p.len = 20;        		/* 设置字符串长度 */
    for (j = 0; j < vLength; ++j) 
    {
        sprintf(buf, "vch-%d:%d", 1, j); /* Put value to buffer */
        mco_uda_put(&rec, inner_field_no, j, &val); /* Put value to object */
    }
     
    /* 放入一个字符串向量  */
    mco_uda_field_alloc(&inner, inner_field_no, vLength); 	/* 分配向量 */
    val.type = MCO_DD_NCHAR_STRING;
    val.v.p.p.n = msg;
    val.v.p.len = 20;
    for (j = 0; j < vLength; ++j) {
        sprintf(msg, "vstr-%d:%d", 2, j);
        mco_uda_put(&rec, inner_field_no, j, &val);
    }

BLOB、OID 和 REF 类型

对于类型 MCO_DD_BLOB、MCO_DD_OID 或 MCO_DD_REF，请设置元素 val->v.p.p.v 和 val.v.p.len：

    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_1 = 1;
    unsigned short field_2 = 2;
    unsigned short vlength = 3;
    char buf[1024];
    char msg[256];
     
    /* 放入一个BLOB值 */
    val.type = MCO_DD_BLOB; 	/* 设置字段的类型 */
    val.v.p.p.v = buf;      	/* 设置指向blob数据的指针 */
    val.v.p.len = 128;      	/* 设置blob的长度 */
    mco_uda_put(&rec, field_3, 0, &val);

结构类型

对于基于结构的字段（必须在数据库模式中定义），首先将 val.type 设置为 MCO_DD_STRUCT，然后用结构元素值填充元素 val.v.o：

    /* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short struct_no = 1;
    unsigned short inner_field_no = 3;
    unsigned short vlength = 3;
    InnerStruct inner; 			/* 模式中定义的结构体 */
     
    /* 放入一个结构体值 */
    val.type = MCO_DD_STRUCT; 	/* 设置结构体类型 */
    mco_uda_put(&rec, struct_no, 0, &val); /* 初始化结构体句柄 */
     
    /* 将inner分配给结构体handle并设置元素 val.v */
    inner = val.v.o;
    val.type = MCO_DD_UINT4;
    val.v.u4   = 999;
    mco_uda_put(&inner, field_no, 0, &val);

将数据库字段值检索到 UDA 值元素中

要准备一个 mco_uda_value_t 结构的 val ，以便使用 mco_uda_get() 检索数据库对象的字段值，必须根据字段的类型设置 val 的适当元素。以下部分演示了如何为不同类型的字段准备 val 。

简单标量类型

对于简单标量类型，例如整数、浮点数、双精度数、日期、时间、日期时间、布尔值和自动标识，将 val.type 设置为适当的类型，然后调用 mco_uda_get() 将数据库字段值检索到 val 的适当元素中。例如：

    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_1 = 1;
    unsigned short field_2 = 2;
    unsigned short field_3 = 3;
 
    /* 获取简单值 */
    val.type = MCO_DD_UINT4; 	/* 设置字段的类型 */
    rc = mco_uda_get(&rec, field1, 0, &value);
    printf("\n\tGet Record.u4                  : %d", val.v.u4);
     
    val.type = MCO_DD_FLOAT; 	/* 设置字段的类型 */
    rc = mco_uda_get(&rec, field2, 0, &value);
    printf("\n\tGet Record.u4                  : %d", val.v.f);
     
    val.type = MCO_DD_AUTOID; 	/* 设置字段的类型 */
    rc = mco_uda_get(&rec, field2, 0, &value);
    printf("\n\tGet Record.u4                  : %d", val.v.u8);

字符串类型

对于字符串、字节数组和blob，应用程序需要提供一个缓冲区，将其分配给适当的缓冲区元素，并设置size和len元素，如下面的示例所示。对于MCO_DD_CHAR或MCO_DD_STRING类型，设置元素value .v.p.p.c和value .v.p.len：

    /* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_no = 2;
    unsigned short inner_field_no = 3;
    unsigned short vlength = 3;
    InnerStruct inner; 		/* 模式中定义的结构体 */
    char buf[1024];
    char msg[256];
     
    /* 获取一个字符向量 */
    mco_uda_field_alloc(&rec, field_no, vLength); 	/* 分配向量 */
    val.type = MCO_DD_CHAR;  	/* 设置字段的类型 */
    val.v.p.p.c = buf;      	/* 将指针指向 buf */
    val.v.p.size = sizeof(buf); /* 设置缓冲区大小 */
    for (j = 0; j < vLength; ++j) 
    {
        mco_uda_get(&rec, inner_field_no, j, &value); 
        printf("\n\tGet Record.vch[%d]              : '%s', length %d", j, buf, val.v.p.len);
    }
     
    /* 取出一个字符串向量  */
    mco_uda_field_alloc(&inner, inner_field_no, vLength); /* 分配向量 */
    val.type = MCO_DD_NSTRING;
    val.v.p.size = sizeof(buf);
    for (j = 0; j < vLength; ++j) 
    {
        mco_uda_get(&inner, inner_field_no, j, &val);
        printf("\n\tGet Record.inner.inner_vstr[%d] : '%s', length %d", j, buf, val.v.p.len);
    }

用于接收字符串字段值的缓冲区也可以动态分配。要确定要检索的字符串的确切大小，可以将 val->v.p.p.c 元素设置为 0，这样 mco_uda_get() 就会仅返回指定数据库字段中字符串的大小。然后可以分配 val.p.p.c 并通过第二次 mco_uda_get() 调用检索字符串值。例如：

    mco_uda_value_t val;
     
    val.type = MCO_DD_STRING;
    val.v.p.p.c = 0; 	/* 算出我们需要分配的实际大小 */
    mco_uda_get(&obj, my_field_no, 0, &val);
    val.v.p.p.c = malloc(val.v.p.size);
    mco_uda_get(&obj, field_no, 0, &val); /* 获取值 */
    printf("\n\tGet Record.vch[%d] : '%s', length %d", j, val.v.p.p.c, val.v.p.len);
    free(val.v.p.p.c); /* 清理内存 */

对于类型 MCO_DD_NCHAR_CHAR 或 MCO_DD_NCHAR_STRING，请设置元素 v.p.p.n 和 val.v.p.size：

	/* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_no = 2;
    unsigned short inner_field_no = 3;
    unsigned short inner_vstr_field_no = 4;
    unsigned short vlength = 3;
    InnerStruct inner; 		/* 模式中定义的结构体 */
    char buf[1024];
    char msg[256];
     
    /* 获取一个 Unicode 字符向量 */
    mco_uda_field_alloc(&rec, field_no, vLength); 	 /* 分配向量 */
    val.type = MCO_DD_NCHAR;  	/* 设置字段的类型 */
    val.v.p.p.n = buf;      	/* 将指针指向 buf */
    val.v.p.size = sizeof(buf); /* 设置缓冲区大小 */
    for (j = 0; j < vLength; ++j) 
    {
        mco_uda_get(&rec, inner_field_no, j, &value); 
        printf("\n\tGet Record.vch[%d]              : '%s', length %d", j, buf, value.v.p.len);
    }
     
    /* 获取一个字符串向量  */
    mco_uda_field_alloc(&inner, inner_vstr_field_no, vLength); /* 分配向量 */
    val.type = MCO_DD_NCHAR_STRING;
    val.v.p.p.n = buf;  		/* 将指针指向 buf */
    val.v.p.size = sizeof(buf); /* 设置缓冲区大小 */
    for (j = 0; j < vLength; ++j) {
        mco_uda_get(&inner, inner_field_no, j, &value);
        printf("\n\tGet Record.inner.inner_vstr[%d] : '%s', length %d", j, buf, val.v.p.len);
    }

BLOB， OID和REF类型

对于MCO_DD_BLOB， MCO_DD_OID或MCO_DD_REF类型设置元素值 val->v.p.p.v和val.v.p.size：

    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short field_1 = 1;
    char buf[1024];
     
    /* 输入BLOB值 */
    val.type = MCO_DD_BLOB; /* 设置字段的类型 */
    val.v.p.p.v = buf;      /* 设置指向blob数据的指针 */
    val.v.p.size = sizeof(buf); /* 设置缓冲区大小 */
    mco_uda_get(&rec, field_1, 0, &val);
    printf("\n\tGet Record.b value             : length %d", val.v.p.len);

结构类型

对于基于结构的字段（必须在数据库模式中定义），首先将value .type设置为MCO_DD_STRUCT，然后调用mco_uda_get()将结构字段检索到元素value .v.o中。然后为每个结构元素的值再次调用mco_uda_get()：

	/* 模式结构定义 */
     
    struct InnerStruct
    {
        vector<string> inner_vstr;
        uint4 inner_data;
    };
     
    /*  应用程序代码片段 */
     
    mco_uda_object_handle_t rec;
    mco_uda_value_t val;
    unsigned short struct_no = 1;
    unsigned short field_no = 2;
    unsigned short inner_field_no = 3;
    unsigned short inner_data_field_no = 5;
    InnerStruct inner; /* 模式中定义的结构体 */
     
    /* Get STRUCT value and get simple value from the inner struct */
    val.type = MCO_DD_STRUCT; /* 设置结构体类型 */
    mco_uda_get(&rec, inner_field_no, 0, &val); /* 初始化内部结构体句柄 */
    inner = val.v.o; /* 获取内部结构体句柄 */
    val.type = MCO_DD_UINT4;
    mco_uda_get(&inner, inner_data_field_no, 0, &val);
    printf("\n\tGet Record.inner.inner_data    : %d", val.v.u4);