| 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, Design and Implementation 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