Calling isc_array_put_slice2()

Go Up to Writing Data to an Array

The following steps are required to store the data into an array or array slice:

1. Declare an array ID:

   ISC_QUAD array_id; /* Declare an array ID. */
   

2. Initialize the array ID. If you are creating a new array to be inserted into a new row, or to replace an existing array, then simply initialize the array ID to NULL:

   array_id = NULL; /* Set handle to NULL before using it */
   

   If you are modifying an existing array, then follow the steps listed under “Reading Data from an Array” to read the existing array ID into array_id.

3. Call ­isc_array_put_slice2(). In your call you pass the array ID (either the array ID of an existing array, or NULL for a new array) in the array_id variable. You also pass the buffer of data to be written and a descriptor specifying the array slice to which the data belongs.

   When ­isc_array_put_slice2() is called with an array ID of an existing array, it creates a new array with the same characteristics as the specified array, and copies the existing array data to the new array. Then ­isc_array_put_slice2() writes the data from the array buffer to the new array (or slice of the array), per the bounds specified in the array descriptor, and returns in the same array_id variable the array ID of the new array.

   When ­isc_array_put_slice2() is called with a NULL array ID, it creates a new empty array with characteristics as declared for the array column whose name and table name are specified in the array descriptor passed to isc_array_put_slice2(). It then writes the data from the array buffer to the new array (or slice of the array), and returns in the array_id variable the array ID of the new array.

   Note that in both cases, a new array is created, and its array ID is returned in the array_id variable. The array is temporary until an UPDATE or INSERT statement is executed to associate the array with a particular column of a particular row.

   You can make a single call to isc_array_put_slice2() to write all the data to the array. Or, you may call isc_array_put_slice2() multiple times to store data into various slices of the array. In this case, each call to ­isc_array_put_slice2() after the first call should pass the array ID of the temporary array. When isc_array_put_slice2() is called with the array ID of a temporary array, it copies the specified data to the specified slice of the temporary array, but does not create a new array.

   The following is a sample call to isc_array_put_slice2():

   isc_array_put_slice2( status_vector, &db_handle, &trans,
   &array_id, /* array ID (NULL, or existing array's array ID) */
   &desc, /* array descriptor describing where to write data */
   hcnt, /* array buffer containing data to write to array */
   &len); /* length of array buffer */
   

   This call creates a new array, copies the data in hcnt to the new array (or slice of the array), assigns the array an array ID, and sets array_id to point to the array ID.

Important:
array_id should be the variable pointed to by the Sqldata field of the UPDATE (or INSERT) statement input parameter that specifies the array column to be updated. Thus, when the INSERT or UPDATE statement is executed, this new array’s array ID will be used to set or update the array column to refer to the new array.

Advance To:

• Associating the New Array with the Array Column