picm_opencache

This function creates or opens the point cache and digital cache files.

C format

int32 picm_opencache(

struct SCacheConfig * pConfig,

int32 * pnPtCacheState,

int32 * pnDgCacheState );

Returns

>0

System error

0

Success

<0

PIstatus error

-20004

Bad pointer

-20003

Memory allocation error

-20015

Cache file already open

-20017

Host server not reachable for creation of cache file

Arguments

pConfig (passed)

Cache configuration object.

pnPtCacheState (returned)

Returned cache state (enum eCACHESTATES).

pnDgCacheState (returned)

Returned cache state (enum eCACHESTATES).

Usage Notes

If the function succeeds, the cache files will have been opened or created and ready for use. The current server node will be set to the host server passed in the SCacheConfig object. If the function fails, the current server node will be set to the host server that was set prior to the call to this function.

The following structure and enumerations defined in ptcache.h are used with this function.

typedef enum eSYNCHTYPE

{

SYNCH_NONE,

SYNCH_USE_PIPT_UPDATES,

SYNCH_USE_PICM_UPDATES,

SYNCH_CACHE_ONLY

} SYNCHTYPE;

SYNCH_NONE - No cache synchronization will be performed. A call to picm_synchronizecache will return NO_MORE_POINTS (0). No updates are made available for pipt_updates or picm_serverupdates. However, the user can still receive current changes if a call to pipt_signupforupdates is made while connected to the PI Server. In this case, any point change made on the PI Server can be retrieved with a call to pipt_updates. The retrival of the update will result in the cache being updated to reflect the change made on the PI Server. Changes made prior to the call to pipt_signupforupdates will not be available.

SYNCH_USE_PIPT_UPDATES - Cache synchronization performed with updates available via pipt_updates. This is the recommended option. This option will require the cache to be synchrnized on startup if the returned cache state is CACHE_COMPLETE or CACHE_INCOMPLETE, as well as after a communicaitons failure with the PI Server.

SYNCH_USE_PICM_UPDATES - Cache synchronization performed with updates available via picm_serverupdates. This option requires the entire cache be synchronized periodically to obtain updates; which could be time consuming. If the application will be calling pipt_signupforupdates and pipt_updates, then use the SYNCH_USE_PIPT_UPDATES option.

SYNCH_CACHE_ONLY - Cache synchronization performed. No updates are made available for pipt_updates or picm_serverupdates. However, the user can still receive current changes if a call to pipt_signupforupdates is made while connected to the PI Server. In this case, changes made on the PI Server after the call to picm_sychronizecache can be retrieved with a call to pipt_updates. The retrival of the update will result in the cache being updated to reflect the change made on the PI Server. Changes made prior to the call to pipt_signupforupdates and after a call to picm_synchronizecache will not be available.

-----------------------------------------------------------------------------

typedef enum eCACHEINITOPTIONS

{

CACHE_OPEN,

CACHE_OPEN_CREATE,

CACHE_RENAME_CREATE,

CACHE_DELETE_CREATE,

CACHE_RENAME_INCOMPLETE,

CACHE_DELETE_INCOMPLETE

} CACHEINITOPTION;

CACHE_OPEN - Open existing cache files only. Return error if cache files do not exist or are invalid.

CACHE_OPEN_CREATE - Open existing cache files. Rename and create new cache files if cache files do not exist or are invalid.

CACHE_RENAME_CREATE - Rename existing cache files if they exist. Create new cache files.

CACHE_DELETE_CREATE - Delete existing cache files if they exist. Create new cache files.

CACHE_RENAME_INCOMPLETE - Rename and create new cache files if cache files are incomplete or invalid. Create new cache files if cache files do not exist.

CACHE_DELETE_INCOMPLETE - Delete and create new cache files if cache files are incomplete or invalid. Create new cache files if cache files do not exist.

-----------------------------------------------------------------------------

typedef enum eCACHESTATES

{

CACHE_NEW, /* New cache file was created. Required connection to PI Server. */

CACHE_COMPLETE, /* Cache file found valid and marked complete. */

CACHE_INCOMPLETE, /* Cache file found valid, but not marked as complete. */

CACHE_ERROR /* Cache error. No cache available. */

} CACHESTATE;

CACHE_NEW - New cache file was created. Existing cache file, if one exists, was renamed or deleted depending on the cache initialization option CACHEINITOPTION.

CACHE_COMPLETE - Cache file found valid and marked complete.

CACHE_INCOMPLETE - Cache file found valid, but not marked as complete.

CACHE_ERROR - Cache error. No cache available.

-----------------------------------------------------------------------------

struct SCacheConfig

{

char m_szFilepath[1024];

char m_szExecutableName[1024];

char m_szHostnameAndPort[1024];

char m_szId[1024];

char m_szProcessName[1024];

char* m_aPointSources[100];

SYNCHTYPE m_eSynchType;

CACHEINITOPTION m_eInitOption;

pibool m_bNoDigitalStateStrings;

};

m_szFilepath – The absolute path to cache file directory. The file path is case sensitive for UNIX and Linux platforms. The directory specified must already exist on the target machine.

Examples:

m_szFilepath=c:\\PIPC\\Interfaces\\CacheFiles

m_szFilepath=c:/PIPC/Interfaces/CacheFiles

m_szFilepath=c:/PIPC/Interfaces/CacheFiles/

m_szFilepath=c:\\PIPC\\Interfaces\\CacheFiles\\

Examples with space in path name:

m_szFilepath=c:\\Program Files\\PIPC\\MyFiles

m_szFilepath=c:/Program Files/PIPC/MyFiles

m_szFilepath=c:/Program Files/PIPC/MyFiles/

m_szFilepath=c:\\Program Files\\PIPC\\MyFiles\\

m_szExecutableName – The application executable name without the ".exe" suffix.

Examples:

m_szExecutableName=Foo

m_szHostnameAndPort=MyApplicationName

m_szHostnameAndPort – The Hostname:Port of the PI server. The Port is optional.

Examples:

m_szHostnameAndPort=MyHost:5450

m_szHostnameAndPort=MyHost

m_szId - Numerical Id.

Examples:

m_szId=1

m_szId=12

m_szProcessName – The process name. This process name is optional.

Examples:

m_szProcessName=MyProcess

m_szProcessName=FooTest

m_aPointSources – Array of point sources to be used by the application. User must manage the allocation/deallocation of character strings and then assign the character string pointer to an array index. The array size is set to 100 elements and is not initialized. Therefore, the user must set each non-used element to NULL if the element does not contain a pointsource. Point sources are optional. However, the use of one or more point sources is recommened for synchronizing groups of points used by the application to those configured on the PI server.

Example:

// cache configuration structure

SCacheConfig cacheConfig;

// zero entire SCacheConfig structure before initial use.

memset(&cacheConfig, NULL, sizeof(struct SCacheConfig));

// add pointsource

cacheConfig.m_aPointSources[0] = new char[nLen+1];

strncpy_s(cacheConfig.m_aPointSources[0], nLen+1, buf, nLen);

cacheConfig.m_aPointSources[n] = new char[nLen+1];

strncpy_s(cacheConfig.m_aPointSources[n], nLen+1, buf, nLen);

m_eSynchType – The synchronization type.

Examples:

m_eSynchType=SYNCH_USE_PIPT_UPDATES

m_eSynchType=SYNCH_USE_PICM_UPDATES

m_eInitOption – The initialization type.

Examples:

m_eInitOption=CACHE_OPEN_CREATE

m_eInitOption=CACHE_RENAME_CREATE

m_bNoDigitalStateStrings - Sets the caching digital state string value option to either true or false. This informs the cache manager as to whether or not the digital state string values are required for operation. If "false", digital state string values are required and each digital state set associated with tags brought in by the interface during run-time will be cached in the digital state set cache file. If "true", digital state string values are not required and the digital state sets associated with tags brought in by the interface will not have their digital state strings stored in the digital state set cache file.

m_bNoDigitalStateStrings=FALSE

m_bNoDigitalStateStrings=TRUE

Enabling Operational Intelligence