Advantage Client Engine
Retrieves a particular property of a link object from the data dictionary.
UNSIGNED32 AdsDDGetLinkProperty( ADSHANDLE hAdminConn,
UNSIGNED8 *pucLinkName,
UNSIGNED16 usPropertyID,
VOID *pvProperty,
UNSIGNED16 *pusPropertyLen );
hAdminConn (I) |
Handle of a database connection. |
pucLinkName (I) |
Name of the link object in the database. |
usPropertyID (I) |
Index of the property to retrieve. See Remarks for allowed values. |
pvProperty (O) |
Pointer to the buffer where the property is to be copied into. |
pusPropertyLen (I/O) |
On input, specifies the size of the buffer pointed to by pvProperty. On output, returns the length of the property copied into the buffer. |
AE_INVALID_PROPERTY_ID |
The value supplied in usPropertyID is not a valid link property. |
AE_INSUFFICIENT_BUFFER |
The size of the property to be copied into pvProperty is larger than the buffer size specified by pusPropertyLen. The required buffer length is returned in pusPropertyLen when this error occurs. |
AE_PROPERTY_NOT_SET |
The requested property is not set in the data dictionary. No data is returned in pvProperty and pusPropertylen. |
AdsDDGetLinkProperty retrieves a property of a global (permanent) link object from the data dictionary. The following are the valid values of usPropertyID and the expected return value in pvProperty and pusPropertyLen.
usPropertyID |
Description |
ADS_DD_LINK_PATH |
The function returns the full path of the linked data dictionary file as a NULL terminated string in pvProperty. The length returned in pusPropertyLen is the length of the path’s string including the NULL terminator. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information. |
ADS_DD_LINK_OPTIONS |
The function returns the options of the link when it is activated. This property is a 4-byte integer representing the bit field with the options OR’ed together. pusPropertyLen must be 4 on input when calling this function with this property ID. See AdsDDCreateLink for more information on link options. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information. |
ADS_DD_LINK_USERNAME |
The function returns the user name that will be used to authenticate to the linked data dictionary when the link is activated. This property is returned as a NULL terminated string. The pusPropertyLen returns the length of the string including the NULL terminator. This property may not be set if the link option specifies that the current user’s authentication information is to be used for authentication into the linked data dictionary. It also may not be set if an anonymous user is to be used to authenticate into the linked data dictionary. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information. |
After making a connection to the "MASTER" database, retrieve the information about the link to the "ARCHIVE" database.
UNSIGNED8 aucLinkUserName[ADS_MAX_USER_NAME+1]
UNSIGNED8 aucLinkPath[ADS_MAX_PATH+1];
UNSIGNED16 usBuffLen;
UNSIGNED32 ulLinkOptions;
UNSIGNED32 ulRetVal;
ADSHANDLE hAdminConn;
ulRetVal = AdsConnect60( "\\\\MyServer\\MyShare\\Data\\Master.ADD",
"ADSSYS", "SysPass", ADS_DEFAULT, &hAdminConn );
if ( ulRetVal != AE_SUCCESS )
return ulRetVal;
// Get the link options
usBuffLen = sizeof( ulLinkOptions );
ulRetVal = AdsDDGetLinkProperty( hAdminConn, "ARCHIVE", ADS_DD_LINK_OPTIONS,
&ulLinkOptions, &usBuffLen );
if ( ulRetVal != AE_SUCCESS )
return ulRetVal;
// Get the link user name
usBuffLen = sizeof( aucLinkUserName );
ulRetVal = AdsDDGetLinkProperty( hAdminConn, "ARCHIVE", ADS_DD_LINK_USERNAME,
aucLinkUserName, &usBuffLen );
if ( ulRetVal = AE_PROPERTY_NOT_SET )
aucLinkUserName[0] = 0;
else if ( ulRetVal != AE_SUCCESS )
return ulRetVal;
// Get the link path
usBuffLen = sizeof(aucLinkPath);
ulRetVal = AdsDDGetLinkProperty( hAdminConn, "ARCHIVE", ADS_DD_LINK_PATH,
aucLinkPath, &usBuffLen );
if ( ulRetVal != AE_SUCCESS )
return ulRetVal;
// disconnect
ulRetVal = AdsDisconnect( hAdminConn );
if ( ulRetVal != AE_SUCCESS )
return ulRetVal;