System API Connect Functions

Connect Functions

To perform a connection you need to just use the connect functions. The API will complete the connection and do further necessary reconnects when the Data Archiver is restarted. Your program does not need to manage and monitor connections as it is done by the API.

Connections are subjected to Historian security, which is based on Microsoft Windows Security.

It is expected that user written programs will connect a minimal number of times for staying connected and using that connection for all read and write calls. Connecting and disconnecting rapidly is not efficient. The connect functions are:

ihServerConnect

ihServerConnect(

ihString ServerName,// the computer name or IP address of the Machine running the Data Archiver. You can pass 
NULL or the empty string ”to attempt connection to a Data Archiver on your local machine.
ihString Username,// The windows username to use when connecting or NULL if you want to connect as the process 
owner of your program, typically the logged in user. You would specify a username if the process owner was unable to 
connect or did not have sufficient Historian Security permissions. 
ihString Password,// if you passed a Username you can pass the password or ”if there is no password or 
otherwise just pass NULL
ihString BufferFileName, // an optional bufferfilename if your program will be using store and forward to 
deliver written data     
ihServerHandle *hServer // this is an output parameter that will contain the server handle that you would use in  
later read and write calls
);

Remarks

A server is a computer running a Data Archiver. You can specify a server by including the computer name or IP address.

ihServerConnect() will initiate a connection, but you should really use ihServerIsConnected() to determine if the connect actually completed.

If you setup a connection callback function with ihServerRegisterConnectionCallback() you will be notified of connection changes. Your security permissions for reads and writes will be established at connect time and are based on the user name and password provided.

Returns

ihServerDisconnect

Use this function to disconnect from the Historian server.

ihSeverDisconnect {
ihServerHandle hServer // the handle returned by a previous call to ihServerConnect

);

Remarks

You should call ihServerDisconnect() function even if the connection attempt returned an error.

Returns

ihServerIsConnected

This function returns whether the Historian server is currently connected or not. It is an indication that if you try to read and write data the call should be successful.

Prototype

ihServerIsConnected {
ihServerHandle hServer // a server handle returned from ihServerConnect

};

Returns

ihServerSetTimeout

This function is used to configure the timeout of the server connection.

Prototype

TihServerSetTimeout {
ihServerHandle hServer, // a server handle returned from ihServerConnect
int Timeout // the timeout, in seconds, to use
};

Use this to configure the timeout to a larger or smaller value. If the System API does not receive any response, even a partial response, during the timeout value, a ihSTATUS_API_TIMEOUT will be returned from the API call.

Set the timeout any time after connecting and the timeout stays in effect until it is changed or disconnect is issued.

Returns

ihServerGetTimeout

ihServerGetTimeout {
ihServerHandle hServer, ihULong *timeout
};

Remarks

Call ihServerConnect() to make a connection, then ihServerSetTimeout() to set the timeout if you want a non default value. You can use the ihServerGetTimeout() function to determine the timeout value that is being used.

The returned timeout value is in seconds.

Returns

ihServerGetVersion

This function returns the Historian server version and connection status.

Prototype

ihServerGetVersion {
ihServerHandle hServer, // a serverhandle returned from a previous call to ihServerConnect
int *Major, // output parameter to contain the major version of the Data Archiver. 
For example 4 when the Data Archiver version is 4.5.
int *Minor, // output parameter to contain the minor version of the Data Archiver. 
For example 5 when the Data Archiver version is 4.5.
int *Build, // output parameter to contain the build number of the Data Archiver. This is typically not used. 
int *Revision // output parameter to contain the revision number of the Data Archiver. This is typically not used

};
You will not receive an immediate callback with the current connection status. You will be notified of the next change in status

Remarks

You will not receive an immediate callback with the current connection status. You will be notified of the next change in status.

Returns

ihSecurityGetMembership

This function returns your membership list. Your group memberships determine your security permissions and what calls you can make on this Proficy Historian server connection.

Prototype

ihSecurityGetMembership {
ihServerHandle hServer, // handle from previous call to ihServerConnect 
ihSecurityGrpMembership *Memberships // output parameter to contain the group membership list

};

Remarks

You can optionally use this call after a successful connect to determine whether the Data Archiver considers your membership list. You need to be completely connected, not just initiate a connection, before this call can be used. The best way is to use ihServerIsConnected() after ihServerConnect() to determine that the connection completed.

Returns

ihServerOpenRecordset

This function returns the list of Historian servers that exist in the Windows registry.

Prototype

ihServerOpenRecordset {
ihString ServerNameMask, // typically NULL to get all servers but could be a mask

ihServerRecordset *ServerRecordset // output parameter containing the recordset

};

Remarks

Use this function to get the list of servers that exist in the Registry. This is a local call and does not need the Data Archiver.

The default server is stored in the Registry and can be used to query instead of hardcoding a server name in your program or prompting the user. The default server is established during product install and can be changed anytime later

Returns

ihServerCloseRecordset

This function is used to free any memory such as server names that were allocated in the System API.

Prototype

void ihServerCloseRecordset {
ihServerRecordset *ServerRecordset // recordset returned from ihServerOpenRecordset
};

Use this function to free any memory such as server names that were allocated in the System API in the ihServerOpenRecordset() call.

Returns

void