| 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 25. 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.
Refer to the Administration Guide: Planning for more information on Data Links.
Return Codes
Diagnostics
Table 26. SQLBuildDataLink() 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.
/* ... */
void getattr( SQLHSTMT hStmt,
SQLSMALLINT AttrType,
SQLCHAR* DataLink,
SQLCHAR* Attribute,
SQLINTEGER BufferLength)
{
SQLINTEGER StringLength ;
SQLRETURN rc ;
rc = SQLGetDataLinkAttr(
hStmt,
AttrType,
DataLink,
strlen( (char *)DataLink),
Attribute,
BufferLength,
&StringLength
) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hStmt, rc ) ;
printf("Attribute #%d) >%s>\n", AttrType, Attribute) ;
return ;
}
/* ... */
SQLCHAR szCreate[] = "CREATE TABLE DL_SAMPL "
"( "
"DL1 DATALINK "
"LINKTYPE URL "
"FILE LINK CONTROL "
"INTEGRITY ALL "
"READ PERMISSION DB "
"WRITE PERMISSION BLOCKED "
"RECOVERY NO "
"ON UNLINK RESTORE "
")";
SQLCHAR szInsert[] = "INSERT INTO DL_SAMPL VALUES (?)" ;
SQLCHAR szFileLink[] =
"http://fearless.torolab.ibm.com/nfsdlink/rpomeroy/test_1.jpg" ;
SQLCHAR szComment[] = "My First Datalink" ;
SQLCHAR szSelect[] = "SELECT * FROM DL_SAMPL" ;
SQLCHAR szDrop[] = "DROP TABLE DL_SAMPL" ;
SQLCHAR szDLCol[254] ;
SQLCHAR szBuffer[254] ;
SQLSMALLINT cCol ;
SQLCHAR szColName[33] ;
SQLSMALLINT fSqlType ;
SQLUINTEGER cbColDef ;
SQLSMALLINT ibScale ;
SQLSMALLINT fNullable ;
SQLINTEGER siLength = SQL_NTS ;
/* ... */
/* Build Datalink */
rc = SQLBuildDataLink( hstmt,
(SQLCHAR *)"URL",
strlen("URL"),
szFileLink,
strlen((char *)szFileLink),
szComment,
strlen((char *)szComment),
szDLCol,
sizeof(szDLCol),
&siLength
);
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;
/* Set input parameter. */
rc = SQLBindParameter(
hstmt,
1,
SQL_PARAM_INPUT,
SQL_C_DATALINK,
SQL_DATALINK,
sizeof(szDLCol),
0,
(SQLPOINTER)szDLCol,
sizeof(szDLCol),
NULL
) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;
/* ... */
} /* end main */
References