Handling an Unknown Column List
For an introduction on how to handle columns in a VALUES clause of an INSERT, see page 15-25. This section describes how to use an sqlda structure to handle the INSERT...VALUES statement.
To use an sqlda structure to handle input parameters in an INSERT
1. Declare a variable to hold the address of an sqlda structure. For more information, see "Defining an sqlda Structure".
2. Prepare the INSERT statement (with the PREPARE statement) and give it a statement identifier. See "Assembling and Preparing the SQL Statement".
3. Use the DESCRIBE...INTO statement to perform two tasks:
a. Allocate an sqlda structure. The address of the allocated structure is stored in the sqlda pointer that you declare. For more information, see "Allocating Memory for the sqlda Structure".
b. Determine the number and data types of columns in the table with the DESCRIBE...INTO statement. The DESCRIBE statement fills an sqlvar_struct structure for each item of the column list. For more information, see "Initializing the sqlda Structure".
4. Examine the sqltype and sqllen fields of sqlda for each column to determine the amount of memory that you need to allocate for the data. For more information, see "Allocating Memory for Column Data".
5. Save the number of columns stored in the sqld field in a host variable.
6. Set the columns to their values with C-language statements that set the appropriate sqldata fields in the sqlvar_struct structures of sqlda. A column value must be compatible with the data type of its associated column. If you insert a null value, make sure to set the appropriate sqlind field to the address of an indicator variable that contains -1.
7. Execute the INSERT statement to insert the values into the database.
The following sections demonstrate how to execute a simple INSERT statement that inserts only one row and an INSERT statement that uses an insert cursor to insert several rows from an insert buffer.
8. Release the memory that is allocated to the sqldata fields and the sqlda structure. For more information, see "Freeing Memory Allocated to an sqlda Structure".
Executing a Simple Insert
The following steps outline how to execute a simple INSERT statement with an sqlda structure:
1. Prepare the INSERT statement (with the PREPARE statement) and give it a statement identifier.
2. Set the columns to their values with C-language statements that set the appropriate sqldata fields in the sqlvar_struct structures of sqlda.
3. Execute the INSERT statement with the EXECUTE...USING DESCRIPTOR statement.
These steps are basically the same as those that handle an unknown select list of a SELECT statement (page 17-26). The major difference is that because the statement is a not a SELECT statement, the INSERT does not require a cursor.
Executing an INSERT That Is Associated with a Cursor
You can also use an sqlda structure to handle an INSERT that is associated with an insert cursor. In this case, you do not execute the statement with the EXECUTE...USING DESCRIPTOR statement. Instead, you must declare and open an insert cursor and execute the insert cursor with the PUT...USING DESCRIPTOR statement, as follows:
1. Prepare the INSERT statement and associate it with an insert cursor with the DECLARE statement. All multirow INSERT statements must have a declared insert cursor.
2. Create the cursor for the INSERT statement with the OPEN statement.
3. Insert the first set of column values into the insert buffer with a PUT statement and its USING DESCRIPTOR clause. After this PUT statement, the column values stored in the specified sqlda structure are stored in the insert buffer. Repeat the PUT statement within a loop until there are no more rows to insert.
4. After all the rows are inserted, exit the loop and flush the insert buffer with the FLUSH statement.
5. Close the insert cursor with the CLOSE statement.
You handle the insert cursor in much the same way as you handle the cursor associated with a SELECT statement (page 17-18). For more information on how to use an insert cursor, refer to the PUT statement in the Informix Guide to SQL: Syntax.
| 
