Character host variables in C and C++ applications that use SQL

There are three valid forms for character host variables.

These forms are:

Single-character form
NUL-terminated character form
VARCHAR structured form

In addition, an SQL VARCHAR declare can be used to define a varchar host variable.

All character types are treated as unsigned.

Single-character form


>>-+--------+--+----------+--+----------+--char----------------->
   +-auto---+  +-const----+  +-unsigned-+         
   +-extern-+  '-volatile-'  '-signed---'         
   '-static-'                                     

   .-,-----------------------------------------------.        
   V                                                 |        
>----variable-name--+---------+--+-----------------+-+-- ; ----><
                    '-[--1--]-'  '- = --expression-'

NUL-terminated character form


>>-+--------+--+----------+--+----------+--char----------------->
   +-auto---+  +-const----+  +-unsigned-+         
   +-extern-+  '-volatile-'  '-signed---'         
   '-static-'                                     

   .-,------------------------------------------------.        
   V                                                  |        
>----variable-name--[--length--]--+-----------------+-+-- ; ---><
                                  '- = --expression-'

Notes:

The length must be an integer constant that is greater than 1 and not greater than 32 741.
If the *CNULRQD option is specified on the CRTSQLCI or CRTSQLCPPI command, the input host variables must contain the NUL-terminator. Output host variables are padded with blanks, and the last character is the NUL-terminator. If the output host variable is too small to contain both the data and the NUL-terminator, the following actions are taken:
- The data is truncated
- The last character is the NUL-terminator
- SQLWARN1 is set to 'W'
If the *NOCNULRQD option is specified on the CRTSQLCI or CRTSQLCPPI command, the input variables do not need to contain the NUL-terminator.
The following applies to output host variables.
- If the host variable is large enough to contain the data and the NUL-terminator, then the following actions are taken:
  - The data is returned, but the data is not padded with blanks
  - The NUL-terminator immediately follows the data
- If the host variable is large enough to contain the data but not the NUL-terminator, then the following actions are taken:
  - The data is returned
  - A NUL-terminator is not returned
  - SQLWARN1 is set to 'N'
- If the host variable is not large enough to contain the data, the following actions are taken:
  - The data is truncated
  - A NUL-terminator is not returned
  - SQLWARN1 is set to 'W'

VARCHAR structured form


>>-+--------+--+----------+------------------------------------->
   +-auto---+  +-const----+   
   +-extern-+  '-volatile-'   
   '-static-'                 

>--+---------+--struct--+-----+-- { ---------------------------->
   '-_Packed-'          '-tag-'        

                      .-int-.               
>--+--------+--short--+-----+--var-1-- ; ----------------------->
   '-signed-'                               

>--+----------+--char--var-2--[--length--]-- ; -- } ------------>
   +-unsigned-+                                        
   '-signed---'                                        

   .-,------------------------------------------------------.        
   V                                                        |        
>----variable-name--+-------------------------------------+-+-- ; -><
                    '- = --{--expression ,--expression--}-'

Notes:

length must be an integer constant that is greater than 0 and not greater than 32 740.
var-1 and var-2 must be simple variable references and cannot be used individually as integer and character host variables.
The struct tag can be used to define other data areas, but these cannot be used as host variables.
The VARCHAR structured form should be used for bit data that may contain the NULL character. The VARCHAR structured form will not be ended using the nul-terminator.
_Packed must not be used in C++. Instead, specify #pragma pack(1) prior to the declaration and #pragma pack() after the declaration.
Note: You can use #pragma pack (reset) instead of #pragma pack() because they are the same.
```
#pragma pack(1)
 struct VARCHAR {
      short len;
      char s[10];
      } vstring;
#pragma pack()
```

Example:

EXEC SQL BEGIN DECLARE SECTION;
 
   /* valid declaration of host variable vstring */
 
   struct VARCHAR {
      short len;
      char s[10];
      } vstring;
 
   /* invalid declaration of host variable wstring */
 
   struct VARCHAR wstring;

SQL VARCHAR form


            .-,-------------------------------------------------.        
            V                                                   |        
>>-VARCHAR----variable-name--[--length--]--+------------------+-+-- ; -><
                                           '- = --"init-data"-'

Notes:

VARCHAR can be in mixed case.
Length must be an integer constant that is greater than 0 and not greater than 32 740.
The SQL VARCHAR form should be used for bit data that may contain the NULL character. The SQL VARCHAR form will not be ended using the nul-terminator.

Example

The following declaration:

VARCHAR vstring[528]="mydata";

Results in the generation of the following structure:

_Packed struct { short len;
                 char data[528];}
 vstring={6, "mydata"};

The following declaration:

VARCHAR vstring1[111],
        vstring2[222]="mydata",
        vstring3[333]="more data";

Results in the generation of the following structures:

_Packed struct { short len;
                 char data[111];}
vstring1;

_Packed struct { short len;
                 char data[222];}
vstring2={6,"mydata"};

_Packed struct { short len;
                 char data[333};}
vstring3={9,"more data"};