Varying Length String Type
As mentioned in the section describing character strings, all C character strings are null-terminated. Ingres data of type char or varchar can contain random binary data including the zero-valued byte (the null byte or \0 in C terms). If a program uses a C char variable to retrieve or set binary data that includes nulls, the runtime system is not able to differentiate between embedded nulls and the null terminator.
In order to set and retrieve binary data that can include nulls, a new C storage class, varchar, has been provided for varying length string variables. varchar identifies the following variable declaration as a structure that describes a varying length string, namely, a 2-byte integer representing the count, and a fixed length character array. Like other storage classes, described in a previous section, the keyword varchar must appear before the variable declaration:
varchar struct {
short current_length;
char data_buffer[MAX_LENGTH];
} varchar_structure;
Note:
• The word varchar is reserved and can be in uppercase or lowercase.
• The varchar keyword is not generated to the output C file.
• The varchar storage class can only refer to a variable declaration, not to a type declaration. For example, the following declaration is legal because it declares the variable vch:
varchar struct {
short buf_size;
char buf[100];
} vch;
But the varchar declaration of the structure tag vch (without a variable) is not legal and generates an error:
varchar struct vch {
short buf_size;
char buf[100];
};
• You can replace the structure definition of a varchar variable declaration by a structure tag or typedef reference.
Example: Legal typedef and varchar declarations
typedef struct vch_ {
short vch_count;
char vch_data[VCH_MAX];
} VCH;
varchar VCH vch_1; /* Typedef referenced */
varchar struct vch_ vch_2; /* Structure tag */
/* referenced */
• You can use the varchar storage class for any type of variable declaration, including external and static variables, and to qualify nested structure members.
Example: Legal declarations
static varchar struct _txt {
short tx_len;
char tx_data[TX_MAX];
} txt_var, *txt_ptr, txt_arr[10];
struct {
char ename[20];
int eage;
varchar struct _txt ecomments;
} emp;
typedef short buf_size;
typedef char buf[512];
varchar struct {
buf_size len;
buf data;
} vchar;
• Caution! The nvarchar struct is a Unicode version of the varchar struct. Using a pack pragma for nvarchar structures on platforms where sizeof(wchar_t) == 4 causes data corruption. Do not use a pack pragma in this case. Use the following syntax to ensure proper compiler padding:
nvarchar struct {
short len;
wchar_t text[MAX_LENGTH];
} rmy_nvarchar ;
The following is an example for ESQL/C, using the demodb database included with Ingres:
exec sql begin declare section;
nvarchar struct {
short len;
wchar_t text[31];
} res_nvarchar \;
exec sql end declare section;
...
exec sql select up_first into :res_nvarchar
from user_profile
where up_email = 'ac.fan@cool-hvac.net';
(res_nvarchar).text[(res_nvarchar).len] = L'\0';
/* Requires Locale to be set up to display Unicode, for example,
UTF-8 encoding. */
printf("nvarchar col = <%S>\n", res_nvarchar.text);
...