db_locate_servers_ex Function

Provides programmatic access to the information displayed by the dblocate utility, listing all the SAP Sybase IQ database servers on the local network that are listening on TCP/IP, and provides a mask parameter used to select addresses passed to the callback function.

Syntax

unsigned int db_locate_servers_ex(
SQLCA * sqlca,
SQL_CALLBACK_PARM callback_address,
void * callback_user_data, 
unsigned int bitmask);

Parameters

sqlca – A pointer to a SQLCA structure.
callback_address – The address of a callback function.
callback_user_data – The address of a user-defined area in which to store data.
bitmask – A mask composed of any of DB_LOOKUP_FLAG_NUMERIC, DB_LOOKUP_FLAG_ADDRESS_INCLUDES_PORT, or DB_LOOKUP_FLAG_DATABASES.

Returns

1 if successful; 0 otherwise.

Remarks

The callback function must have the following prototype:

int (*)( SQLCA * sqlca,
a_server_address * server_addr,
void * callback_user_data );

The callback function is called for each server found. If the callback function returns 0, db_locate_servers_ex stops iterating through servers.

The sqlca and callback_user_data passed to the callback function are those passed into db_locate_servers. The second parameter is a pointer to an a_server_address structure. a_server_address is defined in sqlca.h, with the following definition:

typedef struct a_server_address {
    a_sql_uint32   port_type;
    a_sql_uint32   port_num;
    char           *name;
    char           *address;
    char           *dbname;
} a_server_address;

port_type – Is always PORT_TYPE_TCP at this time (defined to be 6 in sqlca.h).
port_num – Is the TCP port number on which this server is listening.
name – Points to a buffer containing the server name.
address – Points to a buffer containing the IP address of the server.
dbname – Points to a buffer containing the database name.

Three bitmask flags are supported:

DB_LOOKUP_FLAG_NUMERIC
DB_LOOKUP_FLAG_ADDRESS_INCLUDES_PORT
DB_LOOKUP_FLAG_DATABASES

These flags are defined in sqlca.h and can be ORed together.

DB_LOOKUP_FLAG_NUMERIC ensures that addresses passed to the callback function are IP addresses, instead of host names.

DB_LOOKUP_FLAG_ADDRESS_INCLUDES_PORT specifies that the address includes the TCP/IP port number in the a_server_address structure passed to the callback function.

DB_LOOKUP_FLAG_DATABASES specifies that the callback function is called once for each database found, or once for each database server found if the database server doesn't support sending database information (version 9.0.2 and earlier database servers).