// Exported functions from the ConSys API (CSAPI) are defined in this file. // Version: 1.33.893.116 (3. juli 2014) // Version: 1.35.1178.118 (marts 2016): Added support DWORD and LONG. // Version: 1.35.1215.119 (april 2016): Changed return value of StartPacketCollect(LSHANDLE lsHandle) and SendPacket(LSHANDLE lsHandle) from bool to WORD // Version: 1.37.1305.122 (october 2016): New methods: RegisterParameterSQL(), GetRegisteredParameterIds(..),GetRegisteredParameterTypes(..), GetValueArrayExt(..) // Version: 1.37.1322.125 (dec 2016): New methods: RegisterParameterLogGroups(..), GetApiVersion(..), __int64 GetDataTimeStampInt(..), GetTime(..), SetTime(..) // Version: 1.39.1545.129 (feb 2018): New method: CloseCsAPI(): Method to be called as the last thing before the application using CsAPI is closed // Version: 1.39.1591.130 (aug 2018): New methods for get and set of 64 bit signed and unsigned integers // Version: 1.39.1670.131 (marts 2019): New methods: GetIOStringMaxStrLength,GetStringEx,GetLastMessageEx. // Version: 1.40.1685.133 (may 2019): // - CAPIClient reimplemented/updated: All arrays are now dynamic allocated to the actual size needed to save memory and all internal loops improved in performance // (running to actual size instead of MAX_PARAM (10000). ELOG 1745 // - Use of MAX_PARAM has been removed (see ELOG 1745) // - New method: long GetLocalLogPath(..) // - Checked and improved/corrected many API get/set string methods (buffer check, null termination etc.) // - Methods using IOSTRING instead of char* has been moved to 'deprecated methods'. Instead new fooEx methods using char* has been implemented: // SetAppName -> SetAppNameEx // RegisterParameterString -> RegisterParameterStringEx1 // RegisterParameterStringSimulWrite -> RegisterParameterStringSimulWriteEx // RegisterParameterStringEx -> RegisterParameterStringEx2 // RegisterParameterSQL -> RegisterParameterSQLEx // GetParameterName -> GetParameterNameEx // GetDataTimeStampAsString -> GetDataTimeStampAsStringEx // - RegisterParameters replaced by RegisterParametersEx // - GetValueArrayExt - Added support for Int64, DWord64, DWord and Long // - Limit number of allowed registrations to avoid users to make to many registrations - each registration is quite resource intensive in ConSys. // All 'LSHANDLE CRegisterXXX' methods changed, return -1 if the registration failed (due to many registrations). // New methods related to this method: // * WORD GetNumberOfRegistrations() // * WORD GetMaxNumberOfRegistrations() // * WORD SetMaxNumberOfRegistrations() // * long GetLastAPIMessage(char* str, int bufferSize) // * void SetMessagePopupFilter(WORD messageFilter) // Version 1.40.1790.134: Add missing export declarations in .def file // Version 1.45.363.135 (16/3-2022): Added Type cast to "known" types to and from Set- and GetValue // New methods // - SetDouble(...) - Set a double value, like original version of SetValue(...) // - GetDouble(...) - Get a double value, like original version of GetValue(...) // - SetAPIOperationMode() - Changes the operation mode of SetValue() and GetValue() // - GetRegisteredParameterType(LSHANDLE lsHandle,LONG paramNumber); // Change methods: // - SetValue(...) // - SetValue(...) // In operation mode 1 (not default) supports multiple ConSys data value types #pragma once // #define MatLab // For loading the library in MatLab (loadlibrary) outcomment the above (remove the //), // General notes on char* strings: // *1: Return strings from methods like 'long foo((char* str, int bufferSize);': // - The caller must supply a buffer 'str' of size bufferSize to hold the result of the call. // - Note the maximum length of the 'str' is bufferSize-1 to account for the terminating NULL character // - If the supplied buffer is large enough to hold the result string, the methods will return the length // of the result string and the string content in 'str' as a null-terminated string. // - If the buffer is to small to hold the full result, the method returns minus the length of the full string that would // have been returned if the supplied buffer was large enough - and a null-terminated string of 'bufferSize-1' // containing the first part of the result string in 'str' as a null-terminated string. // => In this case a new call to the method with a buffer of at least size '- + 1' will give the full string // - A call with bufferSize <=0 => return . // Can be used to obtain the needed buffer size, ex: // long minBufferSize = foo(NULL,-1) // A buffer of at least the returned size must be allocated to get the full untruncated string. // Remark: The string may have changed between the calls if a new value has been set in between - in most cases it is recommended to // use a larger buffer than needed - and always to check the result. // // *2: Get methods with return strings like 'void foo((char* str, int bufferSize);': // - return a null-terminated string in 'str'. // if the supplied buffer is to small the result string will be truncated to a null-terminated string of length 'bufferSize-1' // *3: Set methods like 'void foo((char* str, int bufferSize);': // The behavior of the methods depend on the value of 'bufferSize': // < 0: Negative bufferSize is invalid, the method will not do anything. // 0: The input string 'str' must be a null-terminated string. No other check of buffer length is made. // >0: The size of the buffer 'str' must be at least 'bufferSize'. If a null-charecter is found within the first 'bufferSize' chars // of 'str', 'str' is treated as a null-terminated char - otherwise the the string is set to the first 'bufferSize' chars of 'str' - // ie. bufferSize is the length of the string. #define MAX_LOGGROUPS 100 // Filter constants for message types allowed popup message boxes from the API. // Set with method 'SetMessagePopupFilter()' #define MSG_TYPE_OK_MESSAGE 0x1 // Messages of things went well, ex. registration ok. Typical NOT enabled in popup messages #define MSG_TYPE_REGISTRATION_ERROR 0x2 // Registration error messages #define MSG_TYPE_MISSING_CloseCsAPI 0x4 // Warning message if CloseCsAPI is not called // Message numbers,numbers >= 1000 is error messages, < 1000 is status/ok messages #define MSG_NO_API_ERROR 0 // No API error (all ok) #define MSG_REGISTRATION_OK 1 // Registration succeded #define MSG_ERRORS_START 1000 #define MSG_NUMBER_OF_REGISTRATIONS_LIMIT_REACHED 1000 // Registration failed because number of registration limit is reached. #define MSG_SOME_PARAMTERS_NOT_REGISTERED 1001 // Not all parameters in the registration string was found in the ConSys database - found parameters registered #define MSG_SOME_PARAMTERS_NOT_FOUND_NOT_REGISTED 1002 // Not all parameters in the registration string was found in the ConSys database - registration failed // Registration options filter constants used in some registration methods #define REG_OPT_FAIL_NOT_ALL_PARAMETERS_FOUND 0x1 // If set, the registration will fail if all parameters in the parameter list can not be found in the database #ifndef LONG typedef long LONG; // LONG is 32 bit signed #endif #ifndef ULONG typedef unsigned long ULONG; // ULONG is 32 bit unsigned #endif #ifndef WORD typedef unsigned short WORD; // WORD is 16 bit unsigned #endif #ifndef BOOL #ifdef MatLab typedef long BOOL; // BOOL is 32 bit signed #else typedef int BOOL; // BOOL is 32 bit signed #endif #endif typedef LONG LSHANDLE; // LONG is a 32 bit signed integer // ********** Deprecated constants and type definitions (constants used in depriated methods) #define MAX_PARAM_DEP 100 // Max number of parameters for deprecated RegisterParameter method #define MaxStrLength_DEP 10000 // Max length for IOSTRING based methods (deprecated methods). This length is including the terminating NULL-character. typedef char IOSTRING[MaxStrLength_DEP]; // IOSTRING is an array of char (ie. bytevalues which values are the ASCII values of the characters. // The string must be terminated by a bytevalue of 0. (terminating NULL-character) typedef LONG PARAMLIST_DREP[MAX_PARAM_DEP]; // Deprecated Max param list for depriated methods // *********** End of deprecated constants and type definitions typedef long* PARAMLIST_PTR; // Pointer to array of parameter ids typedef short LOGGROUP_LIST[MAX_LOGGROUPS]; typedef double* VALUELIST_PTR; // Value list is used to get/set data values to all registered parameters in an registration typedef __int64* TIMESTAMPLIST_PTR; typedef WORD* STATUSLIST_PTR; // Pointer to array of status bits: Bit 0: Value changed since last call to read. 1: Valid typedef LONG* PARAMETER_LIST_PTR; typedef WORD* PARAMETERTYPE_LIST_PTR; #define CONSYS_EXT_API __declspec( dllexport ) __stdcall #ifndef MatLab extern "C" { #endif LONG CONSYS_EXT_API TestFunction(); // TestFunction: A simple function to test API calls, // increment an internal counter for each call LONG CONSYS_EXT_API TestFunctionWithLog(); // TestFunctionWithLog: A simple function to test API calls, // increment an internal counter for each call // This function does a logging of the call to the CSAPI.txt logfile void CONSYS_EXT_API GetApiVersion(char* str, int bufferSize); // Return the version of the CsAPI // To hold the version string the supplied buffer size should be at least 21 // See general notes *2 void CONSYS_EXT_API SetAPIOperationMode(WORD mode); // Sets the operational mode of API methods. In pressent mode version, affects SetValue() and GetValue() methods // 0: Normal, original/default mode - only allow double values // 1: Extended SetValue, GetValue: Convert internal ConSys value data types to double long CONSYS_EXT_API GetLocalLogPath(char* str, int bufferSize); // Return the local path to the local ConSys log directory // See general notes *1 LONG CONSYS_EXT_API GetIOStringMaxStrLength(); // Return the constant 'MaxStrLength', the (maximum) length of the buffer for methods using IOSTRING // Recommended to use to allocate the correct minimum string for GetString and GetMessage void CONSYS_EXT_API GetCsComputerName(int computerId, char* str, int bufferSize); // Return the ComputerName for the ConSys computerId // The result will be a null terminated string // See general notes *2 void CONSYS_EXT_API DoNothing(LONG sleepTime /* ms */); // DoNothing: Suspends the calling thread sleepTime milliseconds void CONSYS_EXT_API SetAppNameEx(char* appName, int bufferSize); // Sets the name of the calling application // Used for debug purpose (logging). Needs only to be called once (before any RegisterParameter...) // See general notes *3 void CONSYS_EXT_API SetLogCount(WORD logCount); // Sets the remaining number of log entries // Can be called at any time to reset the count or to terminate the logging (by setting a zero) // Initial value is 50000 WORD CONSYS_EXT_API GetNumberOfRegistrations(); // Get the number of current registrations in the API WORD CONSYS_EXT_API GetMaxNumberOfRegistrations(); // Get maximum number of registrations allowed. WORD CONSYS_EXT_API SetMaxNumberOfRegistrations(WORD maxRegistrationsDesired); // Set the maximum number of allowed registrations. Can be used to increase (or decrease) the number of allowed registrations. // Can not be set lower than the current number of registrations and not higher than an internal defined maximum in the API // (Each registration is quite resource demanding in ConSys so keep the number of registrations as low as practical possible) // Return: New maximum number of registrations actually set. // Remark: In MatLab and LabVIEW in developer mode the CsAPI is not unloaded before the environment is closed. This may lead to // several registered but not used registrations - for example if LabVIEW programs are broken before a call to Deregister. // In LabVIEW when only developing one program one could include a DeRegisterAll in the beginning of the program to deregister eventual // registrations from previous broken runs. In MatLab DeRegisterAll could be called to clean up hanging registrations. void CONSYS_EXT_API SetMessagePopupFilter(WORD messageFilter); // Set filter for messages allowed to bring up a pop message dialog in case of errors // See available filters at the top of this file // Default set to MSG_TYPE_REGISTRATION_ERROR+MSG_TYPE_MISSING_CloseCsAPI // Remark: The user of the API can disable further messages of a given type at each message popup. // Calling SetMessagePopupFilter will reenable messages that has been disabled by the API user. WORD CONSYS_EXT_API GetMessagePopupFilter(); // Get filter for messages allowed to bring up a pop message dialog in case of errors long CONSYS_EXT_API GetLastAPIMessage(WORD* lastAPIMessageNumber, char* lastMessageStr, int bufferSize); // Return last API status/error message. // lastAPIMessageNumber: Message number id, numbers less than 1000 are messages, >= 1000 errors. See message constants in top of this file. // Note that the lastAPIMessageNumber in fact should have been WORD& (parameter reference and not pointer parameter), but the WORD& does for some // unknown reason not work in MatLab (2016b) 64-bit. In practice however there is not much difference. // See general notes *1 LSHANDLE CONSYS_EXT_API RegisterParameterStringEx1(char* paramStr, int bufferSize, WORD options); // Register a list of parameters (Syntaks: name.surname separated by space and/or newline - // Do not add any characters (spaces..) after the last parameter) // NOTE that the RegisterParameter functions returns immediately, i.e. they do NOT wait for the connection // to be completely established, so the valid parameters are NOT ready immediately after the registration // function returns. // The recommended strategy is to call WaitForAllParametersConnected to wait for (valid) data to appear. // The timeout need to be sufficiently long (say 1000ms) to ensure time for network and remote computer response. // The IsParameterConnected function can be used to test if data is available for a given parameter. // Special registrations: Use ':x' (just) before the parameterNames (e.g. ':1BMH11IBM.adc') // Allowed ':x' : // ':1' : Use dumpDataServer in registration. A dumpDataSever allways transmit all new values even if there // is no change in the value. This can be very usefull in connection with WaitForParamChange when // all values are needed (for averaging or ...) // ':2' : Logs both all reads and writes through the API, and all new arrivals of Values from ConSys // for the parameter. // THIS IS ONLY A DEBUG FEATURE, since the load on the computer will be fairly high (the logging // is done with open/close file on every write). The logfile name is AppName_CSAPI.txt, // where AppName is the name from the SetAppName function. If the SetAppName has not been called // the name is CSAPI.txt. There is a limitation of 50000 log entries (per application). // Note also that logging is only active if the logfilter 'Application Info' and 'Detailed Info' is set // (ConSys registry key - Set by CsShortcupSetup) // ':3' : Logs all the succeding parameters (equivalent to :2 in front of all the succeding parameters) // ':4' : Use dumpDataserver for this and all following parameters // See general notes *3 for string issues // options: option filter, see 'Registration options filter constants' in top of this file // Return: handle to the registration, -1 if the registration failed. LSHANDLE CONSYS_EXT_API RegisterParameterStringSimulWriteEx(char* paramStr, int paramBufferSize,char* simulWrtControlParamStr, int simulWrtBufferSize, WORD options); // Like RegisterParameterString - with registering of parameter name for simultaneous write control bit // Used with SetValueArray to send simultaneous write packets to IfaSupplies device // Registered parameters in paramStr can be accessed as usual. To work with SetValueArray the parameters to set with this // method must be defined as the first parameters in the list // See SetValueArray for further details. // See also general notes *3 // options: option filter, see 'Registration options filter constants' in top of this file // Return: handle to the registration, -1 if the registration failed. LSHANDLE CONSYS_EXT_API RegisterParameterStringEx2(WORD expectedReadDataRate /*ms*/, WORD expectedWriteDataRate /*ms*/,char* paramStr, int bufferSize, WORD options); // Like RegisterParameterStringEx1(char* paramStr, int bufferSize) // expectedReadDataRate [ms], expectedWriteDataRate [ms]: // Used to specify the expected data rate of parameters in reqistered in the request. // Used to optimize the connection retry schema's in case of transport errors. // See also general notes *3 // options: option filter, see 'Registration options filter constants' in top of this file // Return: handle to the registration, -1 if the registration failed. LSHANDLE CONSYS_EXT_API RegisterParametersEx(PARAMLIST_PTR parameterList, WORD parameterBufferSize); // Register a list of parameters by database id's. // Input: // parameters: pointer to 'long' array of parameter id's. // parameterBufferSize: number of parameters/longs in array. // The array is read until either a zero is incountered or 'parameterBufferSize' parameters have been read // Return: handle to the registration, -1 if the registration failed. LSHANDLE CONSYS_EXT_API RegisterParameterSQLEx(char* SQLstr, int bufferSize, WORD options); // Register parameters based on a SQL filter string for the underlying database 'ViewRequestSet'. // Use 'GetNumberOfRegisteredParameters()', GetRegisteredParameterIds(...) to get information on the registered parameters // Primary intented for registration for data logging // See also general notes *3 // options: option filter, see 'Registration options filter constants' in top of this file // Return: handle to the registration, -1 if the registration failed. LSHANDLE CONSYS_EXT_API RegisterParameterLogGroups(LOGGROUP_LIST* pLogGroups, unsigned short sleepTime); // Register a list of parameters by with parameters in the log groups in the input list. // The array is read until either a zero is incountered or MAX_LOGGROUPS parameters have been read // SleepTime in ms: The time the packet servers in the server end will sleep between allowing new data to be send // A sleepTime of 0 will send data as soon as new data is awaileble at and fir the requirements of the data server // This will lead to many small network packages // Setting the sleepTime>0 suppend the packet server 'sleepTime' after each package is send => data are collected in larger packages // It is recommended to set the sleepTime to the expected read interval or a litle less than this to reduce the overall load on ConSys. // Return: handle to the registration, -1 if the registration failed. void CONSYS_EXT_API DeRegister(LSHANDLE lsHandle); // Closes the handle to the ConSys system void CONSYS_EXT_API DeRegisterAll(); // Closes all opened registrations to ConSys. Could be called before calling application is closed to ensure all connections has been DeRegistered. void CONSYS_EXT_API CloseCsAPI(); // Method to be called when the use of CsAPI is finished and the calling application is going to be closed. // Must be called to ensure ConSys environment is closed/cleaned correctly. // Will close internal threads before the dll is unloaded. // Calls DeRegisterAll(); as part of its actions // After call to CloseCsAPI() registration and other methods will no more work correctly. // If not called before the dll is unloaded, error messages may show up in programs during close. // Remark: In MatLab and LabVIEW in developer mode the CsAPI is not unloaded before the environment is closed. Do not call CloseCsAPI in each appl. here. // To avoid warning dialogs during program closure, one can disable these dialog by not including MSG_TYPE_MISSING_CloseCsAPI // in a call of SetMessagePopupFilter, see examples in the MatLab CSAPI. LONG CONSYS_EXT_API WaitForAllParametersConnected(LSHANDLE lsHandle, ULONG timeout /* ms */); // Waits (within the timeout periode) for all parameters to be connected. I.e. when the // function returns all the specified parameters are "live". // // A return value of 1 signifies success. // If the function returns -2, a timeout occured // If the function returns -3, an invalid lsHandle is used WORD CONSYS_EXT_API IsConnectionToLocalKernelOK(LSHANDLE lsHandle); // Ask if the connection to the local ConSysKernel is OK. // Returns true (= 1) if local ConsysKernel is running (either as a service or as an // application). Returns false (= 0) is the local ConSysKernel is NOT running or if // the LSHandle is invalid (no registretion) or if the connection has not been // reestablished yet (the client will automatically try to reconnect (with longer // and longer timeintervals) if there is no connection to the local kernel). LONG CONSYS_EXT_API GetNumberOfRegisteredParameters(LSHANDLE lsHandle); // Returns the number of actually registered (valid) parameters. // If the function returns -3, an invalid lsHandle is used LONG CONSYS_EXT_API GetNumberOfRequestedParameters(LSHANDLE lsHandle); // Returns the number of requested parameters. // If the function returns -3, an invalid lsHandle is used LONG CONSYS_EXT_API GetRegisteredParameterIds(LSHANDLE lsHandle,PARAMETER_LIST_PTR parameterIdAr, WORD maxSize); // Input: parameterIdAr: reference to array of LONG to hold ConSys ParameterId's for the registered parameters. // The called must input an array of at least maxSize elements // The method returns the number of updated indices. If the result equals maxSize, there request may have registered more parameters than maxSize LONG CONSYS_EXT_API GetRegisteredParameterTypes(LSHANDLE lsHandle,PARAMETERTYPE_LIST_PTR parameterTypeAr, WORD maxSize); // Input: parameterTypeAr: reference to array of WORD to hold ConSys parameter types for the registered parameters. // The called must input a reference to an array of at least maxSize elements // Parameter types: // 0: Double // 1: Word // 2: Boolean // 3: String // 4: Time // 5-7: not supported in CsAPI (DAF block, 4k memblock, device status) // 8: Double array // 9: not supported in CsAPI (general block) // 10: DWord // 11: Long // 12: DWord64 // 13: Int64 // The method returns the number of updated parameter types. If the result equals maxSize, the request may have registered more parameters than maxSize // Use GetNumberOfRegisteredParameters to get the number of registred parameters LONG CONSYS_EXT_API GetRegisteredParameterType(LSHANDLE lsHandle, LONG paramNumber); // Get the parameter type of the parameter registered at index paramNumber // Parameter types: // 0: Double // 1: Word // 2: Boolean // 3: String // 4: Time // 5-7: not supported in CsAPI (DAF block, 4k memblock, device status) // 8: Double array // 9: General block/Byte array // 10: DWord // 11: Long // 12: DWord64 // 13: Int64 // Negative: Invalid parameterNumber or lsHandle LONG CONSYS_EXT_API GetParameterNameEx(LSHANDLE lsHandle, LONG paramNumber, char* str, int bufferSize); // Get the registered parameter name in the format . // Return: >0: Length of returned string, <0 buffer to small, string truncated, 0: No string could be returned (not availeble). // See also general notes *1 WORD CONSYS_EXT_API IsParameterValid(LSHANDLE lsHandle, LONG paramNumber); // Ask if a given parameter (paramNumber) is valid (existing) // (i.e. was the parameter found in the ConSys database) // Valid: Return 1, TRUE // Invalid: Return 0, FALSE WORD CONSYS_EXT_API IsAllParametersValid(LSHANDLE lsHandle); // Ask if all requested parameters are valid (i.e. are all the parameters found in the database) // same as (GetNumberOfRegisteredParameters(LSHANDLE lsHandle) equal to // GetNumberOfRequestedParameters(LSHANDLE lsHandle)) // Valid: Return 1, TRUE // Invalid: Return 0, FALSE WORD CONSYS_EXT_API IsParameterConnected(LSHANDLE lsHandle, LONG paramNumber); // Ask if data at a given paramNumber is connected to the ConSys system. // The connection can be broken, either because the local ConSysKernel is not running, the remote // Kernel is not running, or if the network connection between the two computers are down. // A parameter is not connected to ConSys before first data has arrived, i.e. this is the test // to perform to check whether the ConSys connection is up and running. WORD CONSYS_EXT_API IsAllParametersConnected(LSHANDLE lsHandle); // Ask if all parameters are connected to the ConSys system. // The connection can be broken, either because the local ConSysKernel is not running, the remote // Kernel is not running, or if the network connection between the two computers are down. // A parameter is not connected to ConSys before first data has arrived, i.e. this is the test // to perform to check whether the ConSys connection is up and running. WORD CONSYS_EXT_API IsDataValid(LSHANDLE lsHandle, LONG paramNumber); // Ask if data at a given paramNumber is available and valid. // Data is invalidated if the ConSys connection is broken, but the last // datavalue is still returned in the corresponding GetValue function. // FALSE is returned until the first valid data has arrived. void CONSYS_EXT_API SetDataValidForWrites(LSHANDLE lsHandle, WORD val); // Set the value of the DataValid flag for future writes (Set...) // 0: Written Data will be invalid // 1: Written Data will be valid void CONSYS_EXT_API SetParamLogging(LSHANDLE lsHandle, LONG paramNumber, WORD val); // Enables (1) or disables (0) logging to debug text file. // Enable a parameter is equivalent to a :2 in front of the parameter name during registration // A paramNumber of -1 will enable or disable logging for all parameters double CONSYS_EXT_API GetDataTimeStamp(LSHANDLE lsHandle, LONG paramNumber); // Returns the TimeStamp of the datavalue in number of seconds (incl millisec) since 1/1-1970. // The TimeStamp of a datavalue is the time of setting (i.e. change of value). long CONSYS_EXT_API GetDataTimeStampAsStringEx(LSHANDLE lsHandle, LONG paramNumber, char* str, int bufferSize); // Returns the TimeStamp of the datavalue as a formated string. // The TimeStamp of a datavalue is the time of setting (i.e. change of value). // See also general notes *1 __int64 CONSYS_EXT_API GetDataTimeStampInt(LSHANDLE lsHandle, LONG paramNumber); // Returns the TimeStamp of the datavalue in number of milliseconds since 1/1-1970. // The TimeStamp of a datavalue is the time of setting (i.e. change of value). LONG CONSYS_EXT_API WaitForChange(LSHANDLE lsHandle, ULONG timeout /* ms */); // Test if there are parameters that has not been read since last change. // The return value is the paramNumber of the first parameter which has changed. // The change-flag is cleared by a read (GetValue..) for each parameter individually. // If no parameters has changed, the function waits (very efficiently) for a change, // ie. waits with no CPU-load. For a timeout value of 0, the function will return immediately // (with -2 in case of no parameter change). // // If the function returns -1, a message has arrived (use GetLastMessage to clear message change-flag). // If the function returns -2, a timeout occured // If the function returns -3, an invalid lsHandle is used // // NOTE: The parameter list is zero justified. LONG CONSYS_EXT_API WaitForParamChange(LSHANDLE lsHandle, LONG paramNumber, ULONG timeout /* ms */); // Same as WaitForChange, but waits for at specific parameter to change. // Note however that it will not return in case a message arrives. WORD CONSYS_EXT_API StartPacketCollect(LSHANDLE lsHandle); // Sets connection for the registration lsHandle into data collect mode. All subsequent calls to SetXXX methods adds the // data values to a data packet instead of sending them directly. // Calling StartPacketCollect twice without an SendPacket in between has no effect, but will return false. // The packet is send by SendPacket. // Also return false, if lsHandle is invalid // Started correct: Return 1, TRUE // Failed to start send packet (see above): Return 0, FALSE WORD CONSYS_EXT_API SendPacket(LSHANDLE lsHandle); // Send the data packet created by StartPacketCollect followed by a series of SetXXX operations. // After the call to SendPacket, the connection for lsHandle returned to normal operation, ie. values are send directly in the SetXXX methods. // Return TRUE,1, if StartPacketCollect has been called before the call to SendPacket, ie. there is a packet to send. // Return FALSE,0 if no packet is pressent (StartPacketColloct has not been called), or lsHandle is invalid void CONSYS_EXT_API SetValue(LSHANDLE lsHandle, LONG paramNumber, double val); // The action of this method depends on the API operation mode set by SetAPIOperationMode(mode) // // In mode 0: (default/original mode) // Set a double value to a ConSysDouble parameter. Other types will log an error to the error log and not set the value // // mode>0: Conversion mode // Support multiple ConSys data types. The double 'val' is converted to the appropriate data type and send // Supported ConSys data types // double, bit, word, dword, long, dword64, int64 double CONSYS_EXT_API GetValue(LSHANDLE lsHandle, LONG paramNumber); // The result of this method depends on the API operation mode set by SetAPIOperationMode(mode) // // In mode 0: (default/original mode) // Get a double value fom a ConSysDouble parameter. Other types return -9e99 // // mode>0: Conversion mode // Support multiple ConSys data types. The received data converted from the native format to double // Supported ConSys data types // double, bit, word, dword, long, dword64, int64 // // In all modes, // "Invalid" data is returned as -9e99 void CONSYS_EXT_API SetDouble(LSHANDLE lsHandle, LONG paramNumber, double val); // Set a double value double CONSYS_EXT_API GetDouble(LSHANDLE lsHandle, LONG paramNumber); // Get a double value // "Invalid" data is returned as -9e99 void CONSYS_EXT_API SetBit(LSHANDLE lsHandle, LONG paramNumber, WORD val); // Set a bit. 0 means FALSE, and 1 means TRUE. WORD CONSYS_EXT_API GetBit(LSHANDLE lsHandle, LONG paramNumber); // Get a bit. 0 means FALSE, and 1 means TRUE. // "Invalid" data is returned as 0 (false) WORD CONSYS_EXT_API GetWord(LSHANDLE lsHandle, LONG paramNumber); // Get a word. // "Invalid" data is returned as 65535 ((WORD)-1) void CONSYS_EXT_API SetWord(LSHANDLE lsHandle, LONG paramNumber, WORD val); // Set a word unsigned long CONSYS_EXT_API GetDWord(LSHANDLE lsHandle, LONG paramNumber); // Get a dword (unsignet 32 bit) // "Invalid" data is returned as ((DWORD)-1) void CONSYS_EXT_API SetDWord(LSHANDLE lsHandle, LONG paramNumber, unsigned long val); // Set a dword (unsignet 32 bit) long CONSYS_EXT_API GetLong(LSHANDLE lsHandle, LONG paramNumber); // Get a long (signet 32 bit) // "Invalid" data is returned as -1 void CONSYS_EXT_API SetLong(LSHANDLE lsHandle, LONG paramNumber, long val); // Set a long (signet 32 bit) unsigned __int64 CONSYS_EXT_API GetDWord64(LSHANDLE lsHandle, LONG paramNumber); // Get a dword64 (unsignet 64 bit) // "Invalid" data is returned as ((DWORD64)-1) void CONSYS_EXT_API SetDWord64(LSHANDLE lsHandle, LONG paramNumber, unsigned __int64 val); // Set a dword64 (unsignet 64 bit) signed __int64 CONSYS_EXT_API GetInt64(LSHANDLE lsHandle, LONG paramNumber); // Get a int64 (signet 64 bit) // "Invalid" data is returned as ((INT64)-1) void CONSYS_EXT_API SetInt64(LSHANDLE lsHandle, LONG paramNumber, signed __int64 val); // Set a int64 (signet 64 bit) void CONSYS_EXT_API SetStringEx(LSHANDLE lsHandle, LONG paramNumber, char* str, int bufferSize); // Set a string // See also general notes *3 long CONSYS_EXT_API GetStringEx(LSHANDLE lsHandle, LONG paramNumber,char *str, int bufferSize); // Get a string. Make sure that there is enough space in *str to hold the expected return value. // "Invalid" data is returned as "No Consys Data is available" // See also general notes *1 void CONSYS_EXT_API SetTime(LSHANDLE lsHandle, LONG paramNumber, __int64 timeVal); // Set a time to ConSys // The time is a system time in s since since 1/1-1970. __int64 CONSYS_EXT_API GetTime(LSHANDLE lsHandle, LONG paramNumber); // Get a time from ConSys // The time is a system time in s since since 1/1-1970. void CONSYS_EXT_API SetValueArray(LSHANDLE lsHandle, VALUELIST_PTR valueAr, WORD size); // Set values as an array of doubles // The values from handle/index 0 to size-1 is set by the method // The method supports double, Int64, DWord64, DWord, Long, boolean and word - // Int64, DWord64, DWord, Long, boolean and word values are converted from the double value // by standard c++ conversion, Other types are ignored // The values are send in one packet to the frontend. Data are set to be unpacket in the dataserver. // If the parameter registration is made with RegisterParameterStringSimulWrite, a data value 'true' will // be set to the registered control bit parameter as the first item in the packet. At the end of the packet a data value // 'false' will be set to the control parameter. This feature was the first implmentation for the corrector supplies at ASTRID2 void CONSYS_EXT_API GetValueArray(LSHANDLE lsHandle, VALUELIST_PTR valueAr, WORD size); // Get values as an array of doubles // The values from handle/index 0 to size-1 , returned by the method // Int64, DWord64, DWord, Long, Words and boolean are converted to double values // other ConSys data types will return the value -9e99 (ConSys default invalid value) as a signal of invalid data type void CONSYS_EXT_API SetSelectedValueArray(LSHANDLE lsHandle, PARAMETER_LIST_PTR paramNumberAr, VALUELIST_PTR valueAr, WORD size); // Set values to selected paramNumbers from an array of doubles. // The selected parameters (paramNumber) must be specified in paramNumberAr. // paramNumberAr: Reference to an array of LONGs with selected paramNumbers (index in registration list). Must contain at least 'size' elements // The function set 'size' values. 'size' must be equal to or less than GetNumberOfRegisteredParameters() // valueAr: Reference to an array of doubles holding the set values. Must contain at least 'size' elements // paramNumberAr: Reference to an array of LONGs with selected paramNumbers. Must contain at least 'size' elements // The method supports double, Int64, DWord64, DWord, Long, boolean and word - // Int64, DWord64, DWord, Long, boolean and word values are converted from the double value // by standard c++ conversion, Other types are ignored // The values are send in one packet to the frontend. Data are set to be unpacket in the dataserver. // If the parameter registration is made with RegisterParameterStringSimulWrite, a data value 'true' will // be set to the registered control bit parameter as the first item in the packet. At the end of the packet a data value // 'false' will be set to the control parameter. void CONSYS_EXT_API GetSelectedValueArray(LSHANDLE lsHandle, PARAMETER_LIST_PTR paramNumberAr, VALUELIST_PTR valueAr, WORD size); // Get values from selected paramNumbers as an array of doubles. // The selected parameters (paramNumber) must be specified in paramNumberAr. // The function will return 'size' values. 'size' must be equal to or less than GetNumberOfRegisteredParameters() // valueAr: Reference to an array of doubles to hold the result. Must have room for at least 'size' elements // Int64, DWord64, DWord, Long, Words and boolean are converted to double values // other ConSys data types will return the value -9e99 (ConSys default invalid value) as a signal of invalid data type // paramNumberAr: Reference to an array of LONGs with selected paramNumbers (index in registration list). Must contain at least 'size' elements // GetValueArrayExt option constants #define VE_KEEP_POSITION 0x1 #define VE_REG_INDICES 0x2 #define VE_TYPECAST 0x4 #define VE_DISABLE_CHECKTIMESTAMP 0x8 WORD CONSYS_EXT_API GetValueArrayExt(LSHANDLE lsHandle, VALUELIST_PTR valueAr, TIMESTAMPLIST_PTR timestampAr, STATUSLIST_PTR statusAr, PARAMETER_LIST_PTR parameterIdAr, WORD maxSize, WORD options); // Get CHANGED received values as array's. // Meant for (made for) efficient history logging. // All result arrays given to the method must have room for 'maxSize' elements. // Int64, DWord64, DWord, Long, boolean and word values are converted from the double value (see also options, bit 2). // The content of the return array and the result of the call depends on the 'options' // INPUTS: // lsHandle: The handle registered for the connection // maxSize: The size of the result arrays. All result arrays must be allocated by the caller and have a size of at least 'maxSize' // options: Mask with call options: // bit 0: Place results at original location: // F (not set): (recommended): Only values that have changed since last call is returned, placed continously from index 0 in the result arrays. // parameterIdAr is updated which information of wich parameters are present at a given result index. Note the interpretation of parameterIdAr depends on 'bit 1' // T (set): changed/updated values are located at registered indeces in the result arrays. Only data for changed values are updated in // the result arrays. Existing values from prev. calls are left untouched in the result arrays for unchanged parameters (given the same // arrays are reused in the calls of GetValueArrayExt(...). However the 'datachanged' flag in statusAr are cleared for unchanged/not updated parameters // bit 1: parameterIdAr content type - only used for bit 0:F // F: parameterIdAr contains ConSys parameterId's // T: parameterIdAr contains registration indeces (recommended) // bit 2: Convert or typecast WORD/BOOLEAN // F: Data for WORD and BOOLEAN datatypes are converted to double in the result array 'valueAr' // T: Data for WORD and BOOLEAN datatypes are typecast and stored in original format in the double result array 'valueAr'. The caller is // must typecast back dependend on the registered data types when receiving the data. // bit 3: (Disable) Set Current time to current time if timestamp invalid // F: Set Set Current time to current time if timestamp invalid // T: Keep invalid timestamp (invalid timestamp is typical 0) // valueAr: Reference to an array of doubles to hold the result. // WORD and BOOLEAN values are converted to double or typecast dependend on options // other ConSys data types will return the value -9e99 (ConSys default invalid value) as a signal of invalid data type // timestampAr: Measured time stamps for the received data, Number of milliseconds after January 1, 1970 UTCthe number of seconds after January 1, 1970 UTC // statusAr: Status of received value: // bit 0: Data changed flag. TRUE if data has changed since last call of a GetValueXXX method for the parameter. // Be aware that all methods clears the data changed flag in the API - ie. using other GetDataXXX methods than 'GetValueArrayExt' also // clears the flag // bit 1: Data valid flag // parameterIdAr: Reference to a return array of LONGs with parameter numbers of the values. Only used if option bit 0 ís false. // See option bit 1 for interpretation. // // RETURN: Number of values updated in the result arrays. <= maxSize. If equals maxSize, there may be more parameters reqistered/availeble than the input buffers has room for. void CONSYS_EXT_API SetDoubleArray(LSHANDLE lsHandle, LONG paramNumber, VALUELIST_PTR valueAr, WORD size); // Send a double array to a CConSysDoubleArray data type // Note that CConSysDoubleArray data type are quite rare in Consys, so know what you are doing, when using this function // This method was developed to be used with the corrector supplies at ASTRID2 (the most efficient way) WORD CONSYS_EXT_API GetDoubleArray(LSHANDLE lsHandle, LONG paramNumber, VALUELIST_PTR valueAr, WORD maxSize); // Gets a double array from a CConSysDoubleArray data type // The return value specifies the number of element returned (number of values copied into valueAr) // The maximum number of values returned is 'maxSize' and valueAr must have room for 'maxSize' elements // Note that CConSysDoubleArray data type are quite rare in Consys, so know what you are doing, when using this function WORD CONSYS_EXT_API GetDoubleArraySize(LSHANDLE lsHandle, LONG paramNumber); // Gets the size of the (last received) double array from a CConSysDoubleArray data type // The return value specifies the number of element in the DoubleArray // Can be used to provide the correct (adequate) number of element for a subsequent call to GetDoubleArray // if no value (no doubleArray) are retrived by CSAPI (or if used on a non-doubleArray parameter) zero is returned. // Note that CConSysDoubleArray data type are quite rare in Consys, so know what you are doing, when using this function long CONSYS_EXT_API GetLastMessageEx(LSHANDLE lsHandle, char*str, int bufferSize); // Get last ConSys message. // Get a string. Make sure that there is enough space in *str to hold a reasonal message. // See general notes *1 for char* based methods. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // // Deprecated methods using IOSTRING *str, all replaced by new 'xxxEx' methods using char*. // The deprecated methods are still in the CsAPI for backwards compability with existing projects using the API. // New projects should use the new char* based xxxEx methods. // Existing projects should preferably be converted to the new API methods as well. // ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// #ifndef MatLab void CONSYS_EXT_API SetAppName(IOSTRING *appName); // Sets the name of the calling application // Used for debug purpose (logging). Needs only to be called once (before any RegisterParameter...) LSHANDLE CONSYS_EXT_API RegisterParameters(PARAMLIST_DREP parameters); // Register a list of parameters by database id's. // The array is read until either a zero is incountered or MAX_PARAM parameters have been read // Return: handle to the registration, -1 if the registration failed. // Max array size hardwired to MAX_PARAM_DREP (100) LSHANDLE CONSYS_EXT_API RegisterParameterString(IOSTRING *paramStr); // Register a list of parameters (Syntaks: name.surname separated by space and/or newline - // Do not add any characters (spaces..) after the last parameter) // NOTE that the RegisterParameter functions returns immediately, i.e. they do NOT wait for the connection // to be completely established, so the valid parameters are NOT ready immediately after the registration // function returns. // The recommended strategy is to call WaitForChange (or WaitForParamChange) to wait for (valid) data to appear. // The timeout need to be sufficiently long (say 1000ms) to ensure time for network and remote computer response. // The IsDataValid function can be used to test if data is available (and valid) for a given parameter. // Special registrations: Use ':x' (just) before the parameterNames (e.g. ':1BMH11IBM.adc') // Allowed ':x' : // ':1' : Use dumpDataServer in registration. A dumpDataSever allways transmit all new values even if there // is no change in the value. This can be very usefull in connection with WaitForParamChange when // all values are needed (for averaging or ...) // ':2' : Logs both all reads and writes through the API, and all new arrivals of Values from ConSys // for the parameter. // THIS IS ONLY A DEBUG FEATURE, since the load on the computer will be fairly high (the logging // is done with open/close file on every write). The logfile name is AppName_CSAPI.txt, // where AppName is the name from the SetAppName function. If the SetAppName has not been called // the name is CSAPI.txt. There is a limitation of 50000 log entries (per application). // Note also that logging is only active if the logfilter 'Application Info' and 'Detailed Info' is set // (ConSys registry key - Set by CsShortcupSetup) // ':3' : Logs all the succeding parameters (equivalent to :2 in front of all the succeding parameters) // ':4' : Use dumpDataserver for this and all following parameters LSHANDLE CONSYS_EXT_API RegisterParameterStringSimulWrite(IOSTRING *paramStr, IOSTRING *simulWrtControlParamStr); // Like RegisterParameterString - with registering of parameter name for simultanious write control bit // Used with SetValueArray to send simultanious write packets to IfaSupplies device // Registered parameters in paramStr can be accessed as usual. To work with SetValueArray the parameters to set with this // method must be defined as the first parameters in the list // See SetValueArray for further details. LSHANDLE CONSYS_EXT_API RegisterParameterStringEx(WORD expectedReadDataRate /*ms*/, WORD expectedWriteDataRate /*ms*/,IOSTRING *paramStr); // Like RegisterParameterString(IOSTRING *paramStr) // expectedReadDataRate [ms], expectedWriteDataRate [ms]: // Used to specify the expected data rate of parameters in reqistered in the request. // Used to optimize the connection retry schema's in case of transport errors. LSHANDLE CONSYS_EXT_API RegisterParameterSQL(IOSTRING *SQLstr); // Register parameters based on a SQL filter string for the underlying database 'ViewRequestSet'. // Use 'GetNumberOfRegisteredParameters()', GetRegisteredParameterIds(...) to get information on the registered parameters // Primary intented for registration for data logging BOOL CONSYS_EXT_API GetParameterName(LSHANDLE lsHandle, LONG paramNumber, IOSTRING *str); // Get the registered parameter name in the format . // Return: True if parameterName could be returned void CONSYS_EXT_API GetDataTimeStampAsString(LSHANDLE lsHandle, LONG paramNumber, IOSTRING *str); // Returns the TimeStamp of the datavalue as a formated string. // The TimeStamp of a datavalue is the time of setting (i.e. change of value). void CONSYS_EXT_API SetString(LSHANDLE lsHandle, LONG paramNumber, IOSTRING *str); // Set a string // Note the string is null-terminated with a maximum length of MaxStrLength (see above) void CONSYS_EXT_API GetString(LSHANDLE lsHandle, LONG paramNumber, IOSTRING *str); // Get a string void CONSYS_EXT_API GetLastMessage(LSHANDLE lsHandle, IOSTRING *str); // Get the last message. Make sure that there is enough space in *str (up to MaxStrLength) //#ifndef MatLab }; // Extern C #endif