Sets or retrieves bulk-descriptor structure properties.
CS_RETCODE blk_props(blkdesc, action, property,
buffer, buflen, outlen)
CS_BLKDESC *blkdesc;
CS_INT action;
CS_INT property;
CS_VOID *buffer;
CS_INT buflen;
CS_INT *outlen;
A pointer to a CS_BLKDESC structure. A bulk-descriptor structure contains information about a bulk-copy operation. blk_alloc allocates a bulk-descriptor structure.
One of the following symbolic constants:
Value of action |
blk_props |
|---|---|
CS_SET |
Sets the value of the property |
CS_GET |
Retrieves the value of the property |
CS_CLEAR |
Clears the value of the property by resetting it to its default value |
A symbolic constant that indicates the property of interest. Table 4-6 lists valid property constants and describes each property.
If a property value is being set, buffer points to the value to use in setting the property.
If a property value is being retrieved, buffer points to the space in which blk_props will place the requested information.
The C datatype of the value depends on the property. Refer to Table 4-6 for the datatype of the property of interest.
Generally, buflen is the length, in bytes, of *buffer.
If a property value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.
If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.
A pointer to an integer variable.
If a property value is being set, outlen is not used and should be passed as NULL.
If a property value is being retrieved and outlen is supplied, blk_props sets *outlen to the length, in bytes, of the requested information.
If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.
blk_props returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
Bulk-descriptor properties define aspects of a specific bulk-copy operation.
Applications that set Bulk-Library properties must do so after calling blk_alloc to allocate a bulk-descriptor structure and before calling blk_init to initiate a specific bulk-copy operation.
An application can use blk_props to set or retrieve the following properties:
Property name |
Description |
*buffer is |
Applies to |
Notes |
|---|---|---|---|---|
BLK_CONV |
Character-set conversion performed by client. |
CS_TRUE or CS_FALSE. |
IN copies only |
To disable character-set conversion on the current server connection, set CS_NOCHARSETCNV_REQD to CS_TRUE. For more information, see the ct_con_props section in the Open Client Client-Library/C Reference Manual. |
BLK_IDENTITY |
Whether values for a table’s identity column are specified explicitly for each row to be inserted. This property cannot be set to CS_TRUE if BLK_IDSTARTNUM has been set for a bulk-copy-in operation. |
CS_TRUE or CS_FALSE. The default is CS_FALSE, which indicates that identity values are either:
|
IN copies only |
|
BLK_IDSTARTNUM |
The starting value for identity columns in inserted rows. The first inserted row uses this value, and the value is incremented for each subsequent row. This property cannot be set if BLK_IDENTITY has been set to CS_TRUE for the bulk-copy-in operation. |
A CS_NUMERIC variable containing the starting identity value. There is no default. |
IN copies only |
|
BLK_NOAPI_CHK |
Whether parameter and error checking for illegal parameter values and state transitions are disabled for Bulk-Library calls. |
CS_TRUE or CS_FALSE. The default is CS_FALSE, which means error checking is performed. |
Both IN and OUT copies |
|
BLK_PARTITION |
Property to support BCP partitions for BCP_IN and BCP_OUT operations. |
A character string containing the name of the partition. |
Both IN and OUT copies |
|
BLK_SENSITIVITY_ LBL |
Whether a table’s sensitivity column is included in the bulk-copy operation. |
CS_TRUE or CS_FALSE (default). |
Both IN and OUT copies |
Secure Adaptive Server only |
BLK_SLICENUM |
For bulk-copy into a partitioned table. Specifies the partition number that copied rows are inserted to. |
A CS_INT variable containing a positive value representing the partition number. The default is CS_UNUSED, which indicates that Adaptive Server will randomly choose a partition number. |
IN copies only |
BLK_IDENTITY determines whether a table’s identity column is included in a bulk-copy-in operation.
BLK_IDENTITY does not affect bulk-copy-out operations.
If BLK_IDENTITY is CS_TRUE, the application must supply data for the identity column.
If BLK_IDENTITY is CS_FALSE, the application does not need to supply data for the identity column. In this case, the server supplies a default value for the column.
BLK_IDENTITY works by setting identity_insert on for the database table of interest. This allows values to be inserted into the identity column. When the bulk-copy operation is finished, the identity_insert option for the table is turned off.
For more information about identity_insert, see the Adaptive Server Enterprise Reference Manual.
BLK_NOAPI_CHK can be set to CS_TRUE to disable parameter and state checking of Bulk-Library calls. The default is CS_FALSE, which enables parameter checking and state checking of each Bulk-Library call. These two types of error checking are described below:
Parameter checking determines whether the application has passed valid parameters and combinations of parameters in the call.
State checking ensures that calls are made in the required sequence. For example, blk_init must be called before blk_bind.
The default error checking ensures that your application calls Bulk-Library routines in the appropriate manner. With API checking enabled, a descriptive error message is raised when the application commits a usage error, and the routine that discovers the error returns CS_FAIL.
WARNING! With API checking disabled, Bulk-Library usage errors may lead to unexpected behavior or even program crashes.
If your application has been fully tested and completely debugged, you may see improved performance with API checking disabled. Bulk-Library also calls Client-Library internally, so to get the full benefit, you should also disable API checking in Client-Library (by calling ct_config to set the CS_NOAPI_CHK context property to CS_TRUE).
BLK_NOAPI_CHK does not affect testing for errors, such as network errors or conversion overflow, that can occur in well-behaved applications.
BLK_SENSITIVITY_LBL is useful in applications that perform bulk-copy operations to or from Secure Adaptive Server.
BLK_SENSITIVITY_LBL determines whether or not data for the sensitivity column is included in a bulk-copy operation. By default, sensitivity column data is not included.
BLK_SENSITIVITY_LBL affects both bulk-copy-in and bulk-copy-out operations.
If BLK_SENSITIVITY_LBL is CS_TRUE, the application must supply data for the sensitivity column on bulk-copy-in operations and will receive data from the sensitivity column on bulk-copy-out operations.
If BLK_SENSITIVITY_LBL is CS_FALSE, the application does not need to supply data for the sensitivity column on bulk-copy- in operations and will not receive data from the sensitivity column on bulk-copy-out operations.
BLK_SENSITIVITY_LBL is applicable to Secure Adaptive Server copies only. blk_init fails if BLK_SENSITIVITY_LBL is CS_TRUE and the application attempts a bulk-copy operation against a standard Adaptive Server.
Application users copying into the sensitivity column must have the bcpin_labels_role role activated on Secure Adaptive Server. blk_init fails if the bcpin_labels_role is not activated for the connection’s user.
For more information about Secure Adaptive Server, see your Secure Adaptive Server documentation.
Only one name can be provided. A single BLKLIB operation always operates on an entire table or on a single partition. If no partition name is provided, the BLKLIB will not operate on a specific partition but on the entire table.
This property can be used for both BCP_IN and BCP_OUT operations. Either BLK_PARTITION or BLK_SLICENUM can be used; if one is set, the other is cleared.
The BLK_PARTITION property does not require you to set CS_VERSION_150 or BLK_VERSION_150.
