Call Level Interface Guide and Reference

SQLGetDataLinkAttr - Get DataLink Attribute Value

Purpose

Specification: DB2 CLI 5.2 ISO CLI

Return 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 96. 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.

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.

Refer to the Administration Guide: Planning for more information on Data Links.

Return Codes

SQL_SUCCESS
SQL_NO_DATA
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 97. SQLExtendedBind() 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.

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.

Example

See Example.

References

SQLBuildDataLink - Build DATALINK Value

[ Top of Page | Previous Page | Next Page ]