Declaration of large object type host variables in C and C++ embedded SQL applications

Large object (LOB) type host variables that you declare in your embedded C or C++ application are treated as if they were declared in a C or C++ program. You can use host variables to exchange data between the embedded application and the database manager.

The syntax for declaring large object (LOB) host variables in C or C++ is:

Read syntax diagramSkip visual syntax diagramautoexternstaticregisterconstvolatileSQL TYPE IS?XML ASBLOBCLOBDBCLOB(length1 ),*&constvolatilevariable-nameLOB data
LOB data
Read syntax diagramSkip visual syntax diagram={init-len,"init-data"}=SQL_BLOB_INIT("init-data")=SQL_CLOB_INIT("init-data")=SQL_DBCLOB_INIT("init-data")
Read syntax diagramSkip visual syntax diagram;
Notes:
  • 1 length can be any valid constant expression, in which the constant K, M, or G can be used. The value of length after evaluation for BLOB and CLOB must be 1 <= length <= 2 147 483 647. The value of length after evaluation for DBCLOB must be 1 <= length <= 1 073 741 823.
LOB host variable considerations:
  1. The SQL TYPE IS clause is needed to distinguish the three LOB-types from each other so that type checking and function resolution can be carried out for LOB-type host variables that are passed to functions.
  2. SQL TYPE IS, BLOB, CLOB, DBCLOB, K, M, G can be in mixed case.
  3. The maximum length allowed for the initialization string "init-data" is 32 702 bytes, including string delimiters (the same as the existing limit on C and C++ strings within the precompiler).
  4. The initialization length, init-len, must be a numeric constant (for example, it cannot include K, M, or G).
  5. A length for the LOB must be specified; that is, the following declaration is not permitted: 
         SQL TYPE IS BLOB my_blob;
  6. If the LOB is not initialized within the declaration, no initialization will be done within the precompiler-generated code.
  7. If a DBCLOB is initialized, it is the user's responsibility to prefix the string with an 'L' (indicating a wide-character string).
    Note: Wide-character literals, for example, L"Hello", should only be used in a precompiled program if the WCHARTYPE CONVERT precompile option is selected.
  8. The precompiler generates a structure tag which can be used to cast to the host variable's type.

BLOB example:

Declaration: 
   static Sql Type is Blob(2M) my_blob=SQL_BLOB_INIT("mydata");
Results in the generation of the following structure: 
   static struct my_blob_t { 
         sqluint32        length; 
         char             data[2097152]; 
    } my_blob=SQL_BLOB_INIT("mydata");

CLOB example:

Declaration: 
    volatile sql type is clob(125m) *var1, var2 = {10, "data5data5"};
Results in the generation of the following structure: 
    volatile struct var1_t { 
         sqluint32        length; 
         char             data[131072000]; 
    } * var1, var2 = {10, "data5data5"};

DBCLOB example:

Declaration: 
   SQL TYPE IS DBCLOB(30000) my_dbclob1;
Precompiled with the WCHARTYPE NOCONVERT option, results in the generation of the following structure: 
   struct my_dbclob1_t { 
        sqluint32        length; 
        sqldbchar        data[30000]; 
   } my_dbclob1;
Declaration: 
   SQL TYPE IS DBCLOB(30000) my_dbclob2 = SQL_DBCLOB_INIT(L"mydbdata");
Precompiled with the WCHARTYPE CONVERT option, results in the generation of the following structure: 
   struct my_dbclob2_t { 
        sqluint32        length; 
        wchar_t          data[30000]; 
   } my_dbclob2 = SQL_DBCLOB_INIT(L"mydbdata");