blk_alloc

Description

Allocates a CS_BLKDESC structure.

Syntax

CS_RETCODE blk_alloc(connection, version, blk_pointer)
 
 CS_CONNECTION    *connection;
 CS_INT                      version;
 CS_BLKDESC           **blk_pointer;

Parameters

connection

A pointer to a CS_CONNECTION structure that has been allocated with ct_con_alloc and opened with ct_connect. A CS_CONNECTION structure contains information about a particular client/server connection.

The connection must not have any pending results.

version

The intended version of Bulk-Library behavior. During initialization, version’s value is checked for compatibility with Client-Library’s version level. version can take the following values:

Value	Meaning	Compatible Client-Library version level(s)
BLK_VERSION_100	Version 10.0 behavior	CS_VERSION_110, CS_VERSION_100
BLK_VERSION_110	Version 11.0 behavior	Same as BLK_VERSION_100
BLK_VERSION_120	Version 12.0 behavior	Same as BLK_VERSION_100, 110
BLK_VERSION_125	Version 12.5 behavior	Same as BLK_VERSION_100, 110, 120

BLK_VERSION_100 can only be used with Open Client/Server versions 11.x and higher, regardless of whether the context/ctlib is initialized to CS_VERSION_100 or CS_VERSION_110.

The application’s Client-Library version level is determined by the call to ct_init that initializes the connection’s parent context structure.

blk_pointer

The address of a pointer variable. blk_alloc sets *blk_pointer to the address of a newly allocated CS_BLKDESC structure.

In case of error, blk_alloc sets *blk_pointer to NULL.

Returns

blk_alloc returns:

Returns	Indicates
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

The most common reason for a blk_alloc failure is a lack of adequate memory.

Examples

Example 1

/*

 ** BulkCopyIn()

 ** Ex_tabname is globally defined.

*/

 CS_STATIC CS_RETCODE

 BulkCopyIn(connection)

 CS_CONNECTION   *connection;

      CS_BLKDESC     *blkdesc;

      CS_DATAFMT     datafmt;     /* variable descriptions */

      Blk_Data       *dptr;       /* data for transfer */

      CS_INT         datalen[5];  /* variable data length */

      CS_INT         len;

      CS_INT         numrows;

/*

      ** Ready to start the bulk copy in now that all the

      ** connections have been made and have a table name.

      ** Start by getting the bulk descriptor and

      ** initializing.

*/

      if (blk_alloc(connection, BLK_VERSION_100, &blkdesc)

            != CS_SUCCEED)

            ex_error("BulkCopyIn: blk_alloc() failed");

            return CS_FAIL;

  if (blk_init(blkdesc, CS_BLK_IN,

            Ex_tabname, strlen(Ex_tabname)) == CS_FAIL)

            ex_error("BulkCopyIn: blk_init() failed");

            return CS_FAIL;

/*

 ** Bind the variables to the columns and send the rows,

 ** and then clean up.

*/

 ...CODE DELETED.....

 return CS_SUCCEED;

Usage

A CS_BLKDESC structure, also called a bulk-descriptor structure, is the control structure for sending and receiving bulk-copy data. It is a hidden structure that contains information about a particular bulk-copy operation.
Before calling blk_alloc, an application must call the Client-Library routines ct_con_alloc and ct_connect to allocate a CS_CONNECTION structure and open the connection.
blk_alloc must be the first routine called in a bulk-copy operation.
Multiple CS_BLKDESC and CS_COMMAND structures can be allocated on a connection, but only one CS_BLKDESC or CS_COMMAND structure can be active at a time. For more information, see blk_init in this chapter.
To deallocate a CS_BLKDESC structure, an application can call blk_drop.