System API Connect Functions

This section provides detailed information about each available System API function. Use this information together with the sample programs provided to develop your own applications. The System API functions are grouped as follows:

Not every function and structure in the ihapi.h is documented or available for use in user written pro- grams. Please limit your programs to the documented functions or contact the Technical Support team at GE Intelligent Platforms for additional clarifications.

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

This function establishes the connection with the Historian server.
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

Returns StatusMessage
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the server name or IP address provided cannot be located.
ihSTATUS_LIC_TOO_MANY_USERS If this connection would exceed your licensed number of connections.
ihSTATUS_NOT_VALID_USER If the user is not allowed to connect. This can happen whether you provided a username or connected as the process owner. Consult the Historian documentation for security behavior.
ihSTATUS_FAILEDFor any other type of error.

ihServerDisconnect

Use this function to disconnect from the Historian server.

Prototype
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

Returns StatusMessage
ihSTATUS_OK On success.

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

Returns StatusMessage
ihSTATUS_OK On success.
ihSTATUS_FAILED On failure.

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

Returns StatusMessage
TRUE

if you are currently successfully connected.

FALSE

if you were never connected or if the connection is currently down and being re-established.

ihServerGetTimeout

This function is used to return the messaging timeout value of the server connection identified by ihServer.
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

Returns StatusMessage
ihSTATUS_OK On success
ihSTATUS_FAILED On failure

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

Returns StatusMessage
ihSTATUS_OK On success and the desired information can be read from the output parameters.
ihSTATUS_FAILED On failure.

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

Returns StatusMessage
ihSTATUS_OK On success and the desired information can be read from the output parameter.
ihSTATUS_API_TIMEOUTIf the call could not be completed.
ihSTATUS_NOT_CONNECTED When not currently connected to the Data Archiver.
ihSTATUS_FAILEDWhen the other three return options otherwise do not apply.

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

Returns StatusMessage
ihSTATUS_OK On success and the desired information can be read from the output parameter.
ihSTATUS_FAILED On failure

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