Distributed Tuning Interface Reference : PvConnectServer()
 
PvConnectServer()
Attempts to connect to the target server that has the PSQL database engine installed. If connection is established successfully, a connection handle is returned for subsequent references.
Header File: connect.h (See also Header Files)
Function First Available In Library: w3dbav75.dll (Windows), libpsqldti.so (Linux), libpsqldti.dylib (macOS) (See also Link Libraries)
Syntax
BTI_SINT PvConnectServer(
   BTI_CHAR_PTR       serverName,
   BTI_CHAR_PTR       userName,
   BTI_CHAR_PTR       password,
   BTI_LONG_PTR       phConnection);
Arguments
 
In
serverName
Server name or IP address to which you want to connect.
See also Drive-based Formats in Getting Started with PSQL.
In
userName
User name with which you will connect to serverName. See the Remarks section for information on omitting this parameter.
In
password
User password. See the Remarks section for information on omitting this parameter.
In/Out
phConnection
Address of a long integer that receives the connection handle if connection is successful.
Return Values
 
P_OK
The operation was successful.
P_E_NULL_PTR
Call with NULL pointer.
P_E_FAIL
Failed to connect to the named server.
P_E_SERVER_NOT_FOUND
The specified server was not found
P_E_ENGINE_NOT_LOADED
The specified engine is not running.
P_E_REQUESTER_NOT_LOADED
The client requester is not loaded.
P_E_SERVER_TABLE_FULL
The internal server name table is full.
P_E_CLIENT_CONNECTIONS_LIMIT_REACHED
The operation could not connect because the limit on client connections has been reached. Check the configuration of the server.
P_E_PERMISSION_ERROR
The operation encountered a permissions error.
P_E_NO_MEMORY
The operation encountered a memory error.
P_E_NO_AVAILABLE_TRANSPORT
No remote connection could be established.
P_E_CONNECTION_LOST
The remote connection to the server was lost.
Remarks
You must know the name of the server to which you want to connect. You can have open connections to multiple servers.
An application running locally where the database engine is running can omit the user name and password and still be able call any of the DTI functions and view or modify all configuration settings.
However, if the DTI application is running locally through a Terminal Services session or running remotely, provide the user name and password of a user with administrative level privileges on the server machine. This ensures that the application has full access for the DTI functions. Without administrator level privileges, an application returns an access error for most of the DTI functions. Only a subset of the functions work. For example, many of the functions that can modify configuration settings when full access is permitted are restricted to read-only access.
Note You must call PvStart() to initialize DTI before attempting to connect to a server using this function.
Example
BTI_CHAR_PTR uName = "jsmith";
BTI_CHAR_PTR pword = “123”;
BTI_CHAR_PTR svrName = “myserver”;
BTI_LONG_PTR phConn = 0xFFFFFFFF;
BTI_SINT status = 0;
 
status = PvConnectServer(svrName,
uName,
pword,
&phConn);
See Also
PvStart()
PvGetServerName()
PvDisconnect()
PvStop()