Runtime Character Type Conversion
Automatic conversion occurs between Ingres character string values and C character string variables. The string-valued Ingres objects that can interact with character string variables are:
• Ingres names, such as form and column names
• Database columns of type character
• Database columns of type varchar
• Form fields of type character
• Database columns of type long varchar
Several considerations apply when dealing with character string conversions, both to and from Ingres.
References in this section to character string variables do not refer to single byte integers declared with the char type, but to the character string pointer:
char *character_string_pointer;
or to the character string buffer:
char character_string_buffer[length];
Character string pointers are always assumed to be pointing at legal string values. Any pointer that has not been initialized to point at a string value causes a runtime error, resulting in program failure or the overwriting of space in memory.
The conversion of C character string variables used to represent Ingres names is simple: trailing blanks are truncated from the variables, because the blanks make no sense in that context. For example, the string literals empform and empform refer to the same form.
The conversion of other Ingres objects is a bit more complicated. First, the storage of character data in Ingres differs according to whether the medium of storage is a database column of type character, a database column of type varchar, or a character form field. Ingres pads columns of type character with blanks to their declared length. Conversely, it does not add blanks to the data in columns of type varchar or long varchar, or in form fields.
Second, the C convention is to null terminate character strings, and the Ingres runtime system assumes that all strings are null-terminated. For example, the character string abc is stored as the string literal abc followed by the C null character, \0, requiring four bytes.
Fixed length character string variables cannot contain embedded nulls, because the runtime system cannot differentiate between embedded nulls and the trailing null terminator. For a complete description of variables that contain embedded nulls and the C varchar storage class, see
Varying Length String Type in this chapter.
When retrieving character data from an Ingres database column or form field into a C character string variable, be sure to always supply enough room in the variable to accommodate the maximum size of the particular object, plus one byte for the C null character. (Consider the maximum size to be the length of the database column or the form field.) If the character string buffer is too small to contain the complete string value together with the null character, the runtime system may overwrite other space in memory.
If the length of a character string variable is known to the preprocessor, as in the declaration:
char character_string_buffer[fixed_length];
then the runtime system copies at most the specified number of characters including the trailing null character. In cases where the fixed length of the variable (less one for the null) is smaller than the data to be copied, the data is truncated. The specified length must be at least 2, because one character and the terminating null are retrieved. If the length is exactly 1, the data is overwritten by the terminating null.
Furthermore, take note of the following conventions:
• Data stored in a database column of type character is padded with blanks to the length of the column. The variable receiving such data will contain those blanks, followed by the null character. If the receiving variable was declared with a fixed length known to the preprocessor, such as:
char myvar[25]
and the data retrieved is longer than the buffer, the variable will receive only as many characters as will fit (including the terminating null). If the data received is shorter than the variable, the behavior is determined by the setting of the -blank_pad preprocessor flag. By default, the terminating null is placed at the end of the retrieved data, without padding out any space remaining in the variable. But if a module is preprocessed with the ‑blank_pad flag then receiving variables are blank padded to their full defined length (less one space reserved for the terminating null). The ‑blank_pad behavior is specified by the ANSI SQL92 standard.
• Data stored in a database column of type varchar is not padded with blanks. The character string variable receives only the actual characters in the column, plus the terminating null character.
• Data stored in a character form field contains no trailing blanks. The character string variable receives only the actual characters in the field, plus the terminating null character.
When inserting character data into an Ingres database column or form field from a C variable, the following conventions are in effect:
• When data is inserted from a C variable into a database column of type character and the column is longer than the variable, the column is padded with blanks. If the column is shorter than the variable, the data is truncated to the length of the column.
• When data is inserted from a C variable into a database column of type varchar or long varchar and the column is longer than the variable, no padding of the column takes place. However, all characters in the variable, including trailing blanks, are inserted. Therefore, you may want to truncate any trailing blanks in character string variables before storing them in varchar columns. If the column is shorter than the variable, the data is truncated to the length of the column.
• When data is inserted from a C variable into a character form field and the field is longer than the variable, no padding of the field takes place. In addition, all trailing blanks in the data are truncated before the data is inserted into the field. If the field is shorter than the data (even after all trailing blanks have been truncated), the data is truncated to the length of the field.
• When comparing data in character or varchar database columns with data in a character variable, all trailing blanks are ignored. Initial and embedded blanks are significant.
For a more complete discussion of the significance of blanks in string comparisons, see the SQL Reference Guide.
Important! As just described, the conversion of character string data between Ingres objects and C variables often involves the trimming or padding of trailing blanks, with resultant change to the data. If trailing blanks have significance in your application, give careful consideration to the effect of any data conversion. Take care not to use the standard strcmp function to test for a change in character data, since blanks are significant.
The Ingres date data type is represented as 25-byte character string. Your program should allow 26 characters to accommodate the C null.