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. See the ct_con_props section in the Open Client Client-Library/C Reference Manual. |
BLK_CUSTOM_CLAUSE |
A custom, application-specific SQL clause to add after the existing with clause of the insert bulk command. |
A character string containing the custom clause. |
IN copies only |
Supported only by server versions that support the custom SQL clause. Currently used only by internal products. |
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 Enterprise 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 Enterprise will randomly choose a partition number. |
IN copies only |
To process a select into existing table statement that inserts rows into a proxy table, Adaptive Server uses the Bulk-Library to generate a bulk-copy operation. However, full logging is not available for regular bulk-copy operations. BLK_CUSTOM_CLAUSE enables Adaptive Server to distinguish between ordinary bulk-copy operations and bulk-copy operations that have resulted from an insert into statement affecting a proxy table. Bulk-copy operations that result from such an insert into statement can then be appended with the custom clause specified by BLK_CUSTOM_CLAUSE. Adaptive Server can detect this clause and perform full logging.
A select into operation is allowed only if the Adaptive Server select into/bulkcopy/pllsort database option is set to on.
For full logging of a select into operation, the Adaptive Server full logging for select into database option must be set to on.
BLK_CUSTOM_CLAUSE is set with blk_props:
blk_props(blkdesc, CS_SET, BLK_CUSTOM_CLAUSE,
(CS_VOID *)"from select_into", CS_NULLTERM, NULL);
Adaptive Server generates a bulk-copy operation with the specified custom clause appended:
insert bulk mydb.mytable with nodescribe from select_into
where mydb and mytable are the affected database and table.
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.
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 Enterprise.
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 Enterprise 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 Enterprise.
Application users copying into the sensitivity column must have the bcpin_labels_role role activated on Secure Adaptive Server Enterprise. blk_init fails if the bcpin_labels_role is not activated for the connection’s user.
See your Secure Adaptive Server Enterprise 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_155 or BLK_VERSION_155.
