The following CLI functions have been added or enhanced:
Purpose
| Specification: | DB2 CLI 5.2 | ISO CLI |
SQLBuildDataLink() returns a DATALINK value built from input arguments.
Syntax
SQLRETURN SQLBuildDataLink(SQLHSTMT StatementHandle,
SQLCHAR FAR *LinkType,
SQLINTEGER LinkTypeLength,
SQLCHAR FAR *DataLocation,
SQLINTEGER DataLocationLength,
SQLCHAR FAR *Comment,
SQLINTEGER CommentLength,
SQLCHAR FAR *DataLinkValue,
SQLINTEGER BufferLength,
SQLINTEGER FAR *StringLengthPtr);
Function Arguments
Table 1. SQLBuildDataLink Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHSTMT | StatementHandle | input | Used only for diagnostic reporting. |
| SQLCHAR * | LinkType | input | Always set to SQL_DATALINK_URL. |
| SQLINTEGER | LinkTypeLength | input | The length of the LinkType value. |
| SQLCHAR * | DataLocation | input | The complete URL value to be assigned. |
| SQLINTEGER | DataLocationLength | input | The length of the DataLocation value. |
| SQLCHAR * | Comment | input | The comment, if any, to be assigned. |
| SQLINTEGER | CommentLength | input | The length of the Comment value. |
| SQLCHAR * | DataLinkValue | output | The DATALINK value that is created by the function. |
| SQLINTEGER | BufferLength | input | Length of the DataLinkValue buffer. |
| SQLINTEGER | *StringLengthPtr | output | A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *DataLinkValue. If DataLinkValue is a null pointer, no length is returned. If the number of bytes available to return is greater than BufferLength minus the length of the null-termination character, then SQLSTATE 01004 is returned. In this case, subsequent use of the DATALINK value may fail. |
Usage
The function is used to build a DATALINK value. The maximum length of the string, including the null termination character, will be BufferLength bytes.
Return Codes
Diagnostics
Table 2. SQLGetDatLinkAttr SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| 01004 | Data truncated. | The data returned in *DataLinkValue was truncated to be BufferLength minus the length of the null termination character. The length of the untruncated string value is returned in *StringLengthPtr. (Function returns SQL_SUCCESS_WITH_INFO.) |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory required to support execution or completion of the function. |
| HY090 | Invalid string or buffer length. | The value specified one of the arguments (LinkTypeLength, DataLocationLength, or CommentLength) was less than 0 but not equal to SQL_NTS or BufferLength is less than 0. |
Restrictions
None.
References
Purpose
| Specification: | DB2 CLI 5.2 | ISO CLI |
SQLGetDataLinkAttr() returns the current value of an attribute of a datalink value.
Syntax
SQLRETURN SQLGetDataLinkAttr(SQLHSTMT StatementHandle,
SQLSMALLINT Attribute,
SQLCHAR FAR *DataLink,
SQLINTEGER DataLinkLength,
SQLPOINTER *ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER FAR *StringLengthPtr);
Function Arguments
Table 3. SQLGetDataLinkAttr Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHSTMT | StatementHandle | input | Used only for diagnostic reporting. |
| SQLSMALLINT | Attribute | input | Identifies the attribute of the DataLink that is to be extracted.
Possible values are:
SQL_ATTR_DATALINK_COMMENT SQL_ATTR_DATALINK_LINKTYPE SQL_ATTR_DATALINK_URLCOMPLETE (complete URL to access a file) SQL_ATTR_DATALINK_URLPATH (to access a file within a file server) SQL_ATTR_DATALINK_URLPATHONLY (file path only) SQL_ATTR_DATALINK_URLSCHEME SQL_ATTR_DATALINK_URLSERVER |
| SQLCHAR * | DataLink | input | The DATALINK value from which the attribute is to be extracted. |
| SQLINTEGER | DataLinkLength | input | The length of the DATALINK value. |
| SQLPOINTER * | ValuePtr | output | A pointer to memory in which to return the value of the attribute specified by Attribute. |
| SQLINTEGER | BufferLength | input | Length of the Attribute buffer. |
| SQLINTEGER | *StringLength | output | A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *Attribute. If Attribute is a null pointer, no length is returned. If the number of bytes available to return is greater than BufferLength minus the length of the null-termination character, then SQLSTATE HY090 is returned. |
Usage
The function is used with a DATALINK value that was retrieved from the database or built using SQLBuildDataLink. The AttrType value determines the attribute from the DATALINK value that is returned. The maximum length of the string, including the null termination character, will be BufferLength bytes.
Return Codes
Diagnostics
Table 4. SQLGetDatLinkAttr SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| 01004 | Data truncated. | The data returned in *ValuePtr was truncated to be BufferLength minus the length of the null termination character. The length of the untruncated string value is returned in *StringLengthPtr. (Function returns SQL_SUCCESS_WITH_INFO.) |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory required to support execution or completion of the function. |
| HY009 | Invalid argument value. | The value specified for the argument *DataLink was a null pointer or was not valid. |
| HY090 | Invalid string or buffer length. | The value specified for the argument BufferLength was less than 0 or the values specified for the argument DataLinkLength was less than 0 and not equal to SQL_NTS. |
| HY092 | Option type out of range. | The value specified for the argument AttrType was not valid. |
Restrictions
None.
References
A new attribute-keyword, NEWPWD, has been added to the SQLDriverConnect() function. The syntax diagram in the 'Usage' section has been updated to include the new keyword, and to fix the mistake in the Version 5 book (the separator should be a semi-colon, not a comma).
.-;------------------------------------------.
V |
>>-----+-DSN---------------------+=--attribute--+--------------><
+-UID---------------------+
+-PWD---------------------+
+-NEWPWD------------------+
'-DB2 CLI-defined-keyword-'
This new entry is defined as follows:
The application can either specify the new string to use, for example, NEWPWD=anewpass;; or specify NEWPWD=; and rely on a dialog box generated by the DB2 CLI driver to prompt for the new password (set the DriverCompletion argument to anything other than SQL_DRIVER_NOPROMPT).
The attribute-keyword NEWPWD has been added. It has the same description as "SQLDriverConnect() and NEWPWD Support".
The following change must be made to the description of the values for SQL_GETDATA_EXTENSIONS in SQLGetInfo(). The version 5.0 CLI Guide and Reference incorrectly states that SQL_GD_BLOCK is supported; this is not the case.
The Description and Notes section for SQL_GETDATA_EXTENSIONS should read as follows:
ODBC also defines the following extensions which are not returned by DB2 CLI:
The description of the StringLength argument has been updated as follows:
The length of the large object (LOB, CLOB, etc...) referenced by the Locator argument. This value is in bytes, even for DBCLOB data.
The following connection attributes have been added to SQLSetConnectAttr():
In Chapter 5 "Functions", in the section SQLSetConnectAttr(),
Table 147 "When Connection Attributes can be Set" has been updated to include
the following new rows:
Table 5. When Connection Attributes can be Set
| Attribute | Before connection | After connection | After statements allocated |
|---|---|---|---|
| SQL_ATTR_ENLIST_IN_DTC | No | Yes | Yes |
| SQL_ATTR_INFO_USERID | No | Yes | Yes |
| SQL_ATTR_INFO_WRKSTNNAME | No | Yes | Yes |
| SQL_ATTR_INFO_APPLNAME | No | Yes | Yes |
| SQL_ATTR_INFO_ACCTSTR | No | Yes | Yes |
Also, in the section "Attribute *ValuePtr Contents" for SQLSetConnectAttr(), the following new information has been added:
An SQLPOINTER which can be either:
Change the state of the connection from non-distributed transaction state to distributed transaction state. The connection will be enlisted with the Distributed Transaction Coordinator (DTC).
Change the state of the connection from distributed transaction state to a non-distributed transaction state.
Each time this attribute is used with a non-null transaction pointer, the previous transaction is assumed to be ended and a new transaction is initiated. The application must call the ITransaction member function Endtransaction before calling this API with a non-null pointer. Otherwise the previous transaction will be aborted. The application can enlist mutiple connections with the same transaction pointer.
| Note: | This connection attribute is specified by MTS automatically for each transaction and is not coded by the user application. |
A null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.
Usage notes:
DB2 for OS/390 servers support up to a length of 16 characters.
| Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.
Usage notes:
DB2 for OS/390 servers support up to a length of 18 characters.
| Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.
Usage notes:
DB2 for OS/390 servers support up to a length of 32 characters.
| Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.
Usage notes:
DB2 for OS/390 servers support up to a length of 200 characters.
| Note: | This is an IBM defined extension. |
The original Version 5 documentation for the the SQLSetStmtAttr() function concerning the SQL_ATTR_CURSOR_TYPE statement contained one mistake. If SQL_ATTR_CURSOR_TYPE is set to either SQL_CURSOR_KEYSET_DRIVEN or SQL_CURSOR_DYNAMIC (neither supported by DB2 CLI) then the value used will be SQL_CURSOR_STATIC, not SQL_CURSOR_FORWARD_ONLY as originally documented.
The complete documentation is as follows:
A 32-bit integer value that specifies the cursor type. The supported values are:
The default value is SQL_CURSOR_FORWARD_ONLY.
This option cannot be specified for an open cursor.
For more detailed information, the application should call SQLGetInfo() with an InfoType of SQL_<cursor type>_ATTRIBUTES1 and SQL_<cursor type>_ATTRIBUTES2 (SQL_STATIC_CURSOR_ATTRIBUTES2, for instance).
| Note: | The following values have also been defined by ODBC, but are not supported by
DB2 CLI:
If either of these values is used, DB2 CLI sets the statement attribute to SQL_CURSOR_STATIC and returns SQLSTATE 01S02 (Option value changed). In this case the application should call SQLGetStmtAttr() to query the actual value. |