User Library
advertisement
Measuresoft Development Ltd. User Library Manual Version: 4.7.6.13 prepared for measuresoft by Cathal Cleary September 10, 1996 © measuresoft development This manual is the copyright of Measuresoft, and may not be modified, copied, or distributed in any form whatsoever without the prior permission of Measuresoft measuresoft development limited partnership court dundalk ireland tel +353 42 32399 fax +353 42 27187 1 Interfacing to User Librarys 1. INSTALLING USER LIBRARY 5 2. INTRODUCTION 5 2.1 Interfacing using ‘C++’ 5 2.2 Interfacing using‘Visual Basic’. 6 2.3 Interfacing using‘C#’ 6 3. USER TASKS 7 3.1 Description 7 3.2 User Tasks File 7 ‘C++’ DATA STRUCTURES 4. 8 Digital Status Structure, D_STATUS Analog Status Structure, A_STATUS Analog Value, float Configuration Data Structure, CHAN_CONFIG Channel Configuration Structure, CHAN Analog Channel Configuration Structure, AN_CONFIG Digital Channel Configuration Structure, DIG_CONFIG 5. 8 8 8 9 9 9 10 'C++' INTERFACE ROUTINES 11 5.1 Introduction 11 5.2 Using The Interface Routines 11 Clear Signal Table Entry _orc_clear_sig 12 12 Wait For Data Update _orc_wait_update 13 13 Read Digital Channel Status _orc_read_stat _rem_read_stat 14 14 14 Read Analog Channel Values _orc_read_an _rem_read_an 15 15 15 Start Reporting Channel Range _orc_start_reports 16 16 Finish Reporting Channel Range _orc_finish_reports 17 17 Write Digital Channel Status _orc_write_dig _rem_write_dig 18 18 18 Write Analog Channel Values _orc_write_an _rem_write_an 19 19 19 Read Channel Configuration _orc_read_config _rem_read_config 20 20 20 Measuresoft development Ltd. 1 Version: 5.0.0.0 Write Channel Configuration _orc_write_config 2 21 21 Enable Logger _orc_enable_logger _rem_enable_logger 22 22 22 Disable Logger _orc_disable_logger _rem_disable_logger 23 23 23 Control Logger _orc_control_logger _rem_control_logger 24 24 24 Write Logger Text _orc_write_logtext _rem_write_logtext 25 25 25 ‘VISUAL BASIC’ DATA STRUCTURES 6. 26 Digital Status Structure, VB_D_STATUS Analog Status Structure, VB_A_STATUS Analog Value, Single Configuration Data Structure, VB_CHAN_CONFIG Channel Configuration Structure, VB_CHAN Analog Channel Configuration Structure, VB_AN_CONFIG Digital Channel Configuration Structure, VB_DIG_CONFIG 26 26 26 27 27 27 28 ‘VISUAL BASIC’ INTERFACE ROUTINES 29 7. 7.1 Introduction 29 7.2 Using The Interface Routines 29 Clear Signal Table Entry orc_clear_sig 30 30 Wait For Data Update orc_wait_update 31 31 Read Digital Channel Status orc_read_stat rem_read_stat 32 32 32 Read Analog Channel Values orc_read_an rem_read_an 33 33 33 Start Reporting Channel Range orc_start_reports 34 34 Finish Reporting Channel Range orc_finish_reports 35 35 Write Digital Channel Status orc_write_dig rem_write_dig 36 36 36 Write Analog Channel Values orc_write_an rem_write_an 37 37 37 Read Channel Configuration orc_read_config 38 38 Measuresoft development Ltd. 2 Version: 5.0.0.0 Write Channel Configuration orc_write_config 3 39 39 Enable Logger orc_enable_logger rem_enable_logger 40 40 40 Disable Logger orc_disable_logger 41 41 Control Logger orc_control_logger rem_control_logger 42 42 42 Write Logger Text orc_write_logtext 43 43 Convert Array of Bytes to VB String type BytesToString 44 44 Convert a VB String to an Array of Bytes StringToBytes 45 45 ‘C#’ DATA STRUCTURES 8. 46 Digital Status Structure, CS_D_STATUS Analog Status Structure, CS_A_STATUS Analog Value, float Configuration Data Structure, CS_CHAN_CONFIG Channel Configuration Structure, CS_CHAN Analog Channel Configuration Structure, CS_AN_CONFIG Digital Channel Configuration Structure, CS_DIG_CONFIG 9. 46 46 46 47 47 47 48 'C#' INTERFACE ROUTINES 49 9.1 Introduction 49 9.2 Using The Interface Routines 49 Clear Signal Table Entry orc_clear_sig 50 50 Wait For Data Update orc_wait_update 51 51 Read Digital Channel Status orc_read_stat rem_read_stat 52 52 52 Read Analog Channel Values orc_read_an rem_read_an 53 53 53 Start Reporting Channel Range orc_start_reports 54 54 Finish Reporting Channel Range orc_finish_reports 55 55 Write Digital Channel Status orc_write_dig rem_write_dig 56 56 56 Write Analog Channel Values orc_write_an rem_write_an 57 57 57 Measuresoft development Ltd. 3 Version: 5.0.0.0 Read Channel Configuration orc_read_config 4 58 58 Write Channel Configuration orc_write_config 59 59 Enable Logger orc_enable_logger rem_enable_logger 60 60 60 Disable Logger orc_disable_logger 61 61 Control Logger orc_control_logger rem_control_logger 62 62 62 Write Logger Text orc_write_logtext 63 63 10. LOG FILE FORMAT 64 10.1 Log File Layout 64 10.2 Log File Scan Layout 65 10.3 Log File Structures File Header Structure, LOG_FILE_HEAD Block Information Structure, LOG_BLOCK Channel Range Structure, CHAN_RANGE Configuration Block Header, LOG_CONB_HEAD Configuration Block Footer, LOG_CONB_FOOT Scan Header, LOG_SCAN_HEAD Data Block Header, LOG_DATA_HEAD Scan Footer, LOG_SCAN_FOOT Measuresoft development Ltd. 4 66 66 66 66 66 66 66 66 66 Version: 5.0.0.0 5 User Library 1. Installing User Library To install User Library we recommend that you first close down all applications. Run the User Library setup executable file. This will launch the User Library setup application. Click on the next button to continue. Follow the installation instructions on the setup windows to complete the installation. 2. Introduction This document is intended to provide sufficient information about the structure and working of the User Library to enable a programmer to write his own code. The user can interface ‘C++’ using the static library, or through ‘Visual Basic’ and C# using a dynamically linked library. Note: Any application developed using these libraries may not function under Windows Terminal Server if they are invoked through the desktop. 2.1 Interfacing using ‘C++’ It is assumed that the programmer is already familiar with the C++ programming language and the Win32 API. This document provides the following information: Defining user tasks Definition of globally available real-time data in structures. Definition of the routines to access globally available real-time data in structures. Definition of the log file format and structure. Measuresoft development Ltd. 5 Version: 5.0.0.0 6 Sample applications using the ‘C++’ interface are provided in the UserTask and Console directory which are installed when the User Library is installed. For additional information, see the ReadMe.txt file included in each directory. 2.2 Interfacing using‘Visual Basic’. Again, the user should have a working knowledge of the Visual Basic programming language. This document provides: Definition of Visual Basic Data Structures. Definition of DLL functions available to access data structures. A sample application which uses the ‘Visual Basic’ interface is provided in the VB directory which is installed when the User Library is installed. For additional information, see the ReadMe.txt file included the VB directory. 2.3 Interfacing using‘C#’ Again, the user should have a working knowledge of C#. This doccument provides: Definition of C# Data Structures Definition of DLL functions available to access channel data structures. A sample application which uses the ‘C#’ interface is provided in the CS_NET directory which is installed when the User Library is installed. Measuresoft development Ltd. 6 Version: 5.0.0.0 7 3. User Tasks 3.1 Description User tasks generally fall into two categories 1. User acquisition task - where the user wishes to interface to an external device that is not supported. 2. User processing task - where the user wishes to perform calculations on channels. Two processors are available to provide user analog and user digital channels. Configuration of these channels is described in the main documentation manual. The values of these channels can be calculated and set in user tasks. The channels can then be monitored and logged. User tasks are specified in a special file and are invoked when the system is enabled. This ensures that the user tasks are synchronised. These tasks remain active while the system is enabled. While a user task is active, the tasks can interrogate and update channels, and control loggers and devices. When the system is disabled all user tasks are killed off along with the device and processor background tasks. When writing a user task, it is important to synchronise your user task to the data coming into the system. The data structures provide a means of synchronisation using internal signal tables. Routines are provided for a user task to wait for new data to be written into a data structure. 3.2 User Tasks File The user tasks file is an ASCII text file that describes the user tasks to run when the system is enabled. This file can be edited using a standard text editor (e.g. notepad). The user tasks file is stored in the following file: <Product Name>\CURRENT_CONFIG\USRTASKS.TXT E.g. D:\APPS\Product Name\CURRENT_CONFIG\USRTASKS.TXT A sample users tasks file is shown below. * * Product Name - sample user tasks file * prog parm1 c_program parm1 parm2 parm3 Entries in the file are specified as follows program [parameters] where: [ ] brackets indicate an optional field. Program is any program executable from the command line. This program’s executable must be located either in the <Product Name>\BIN directory, or in the system path. Parameters are passed to the program. Measuresoft development Ltd. 7 Version: 5.0.0.0 8 4. ‘C++’ Data Structures All channels’ results and configurations are globally available to user tasks through the data structures. Results and configuration data structures are stored for each channels prefix. Refer to the standard documentation for a list of channel prefixes on a standard system. The results data structures can store either analog or digital results or only digital results. Note, in the following structure descriptions: All Data Structures are declared in the file orc_common.h. This file should be included in any programs which wish to use these structures. The fields are not necessarily in the order in which they appear in the physical data structure. For details on the physical layout of the data structures, refer to the header file orc_common.h. Packing and Filler fields have been omitted from the descriptions. Where a field is of type bit, then they are bits packed into a uint, however the fields can be accessed by simply using the field name. Where the type of a field is described as say, char * ORC_PREFIX_SIZE, then this means the field is an array of char and of size ORC_PREFIX_SIZE. ORC_PREFIX_SIZE is a macro which defines the size of a standard channel prefix. This macro and others used by the systems structures and applications are included in orc_common.h. Programs written to use the systems Data Structures must be compiled in a 32 bit programming environment (such as Visual Studio), so that the basic types and structure sizes will match up. Digital Status Structure, D_STATUS All Digital Channels store a Digital Status Structure, as described below. Field Description an_dig Set 0 for digital channels error Set 1 if channel is in error status digital state of channel ev_tog Set 0 for low event, 1 for high event event Set 1 if channel in event al_tog Set 0 for low alarm, 1 for high alarm alarm Set 1 if channel in alarm unack Set 1 for unacknowledged alarm Type bit bit bit bit bit bit bit bit Analog Status Structure, A_STATUS All Analog Channels store an Analog Status Structure, as described below. Field Description Type an_dig bit Set 1 for analog channels error bit Set 1 if channel is in error ev_tog bit Set 0 for low event, 1 for high event event bit Set 1 if channel in event al_tog bit Set 0 for low alarm, 1 for high alarm alarm bit Set 1 if channel in alarm unack bit Set 1 for unacknowledged alarm sig bit Set 1 if significant change has occurred Analog Value, float All Analog Channels store an Analog Value, as described below. 4 byte, IEEE Floating Point Value. Measuresoft development Ltd. 8 Version: 5.0.0.0 9 Configuration Data Structure, CHAN_CONFIG All Channels have the following Configuration Data Structure. Field Description tag Channel Tag desc Channel Description type 0 = Analog Input 1 = Digital Input 2 = Analog Output 3 = Digital Output chan Channel Configuration Structure Type char * ORC_TAG_SIZE char * ORC_DESC_SIZE char CHAN Channel Configuration Structure, CHAN Field Description An Analog Channel Configuration Structure dig Digital Channel Configuration Structure Type AN_CONFIG DIG_CONFIG Analog Channel Configuration Structure, AN_CONFIG Field Description enabled Channel Is Active ev_on Event Checking To Do al_hi_on High Alarm Checking To Do hs_hi_on High Alarm Hysteresis Checking To Do common_hi High Alarm Drives Common Alarm Output al_lo_on Low Alarm Checking To Do hs_lo_on Low Alarm Hysteresis Checking To Do common_lo Low Alarm Drives Common Alarm Output sig_on Significant Change Checking To Do ref_on Channel Is Referenced scale_on Scaling To Do al_on Not Used common Not Used hist_on Not Used units Units Description scale Channel Scaling offset Channel Offset ev_high High Event Threshold ev_low Low Event Threshold al_high High Alarm Threshold hs_high High Hysteresis Threshold al_low Low Alarm Threshold hs_low Low Hysteresis Threshold sig_change Significant Change Value al_hi_priority High Alarm Priority al_lo_priority Low Alarm Priority al_hi_message High Alarm Message al_lo_message Low Alarm Message hw Hardware Specific Configuration Structure Type bit bit bit bit bit bit bit bit bit bit bit bit bit bit char * ORC_UNITS_SIZE float float float float float float float float float char char char * ORC_MSG_SIZE char * ORC_MSG_SIZE < Hardware Dependant > Measuresoft development Ltd. 9 Version: 5.0.0.0 10 Digital Channel Configuration Structure, DIG_CONFIG Field Description enabled Channel Is Active ev_on Event Checking To Do al _on Alarm Checking To Do common Alarm Drives Common Alarm Output al_stat Alarm State ev_stat Event State on_desc On State Description off_desc Off State Description al_priority Alarm Priority al_message Alarm Message hw Hardware Specific Configuration Structure Measuresoft development Ltd. 10 Type bit bit bit bit bit bit char * ORC_DIG_DESC_SIZE char * ORC_DIG_DESC_SIZE char char * ORC_MSG_SIZE < Hardware Dependant > Version: 5.0.0.0 11 5. 'C++' Interface Routines 5.1 Introduction A library of routines are available that allow access to channels and their configurations from any program written in 'C++'. These programs can be linked into channels as user tasks making them an integral part of the environment. These routines enable a user task to read channel values and channel configurations of any channel within the system, and also to write channel values and configurations to any 'user' channel. Mechanisms are provided for synchronising the reading of data, to when this data is updated. This ensures that user tasks are provided with new data as soon as possible after it has been processed. This also makes user tasks more efficient, typically shorter and hence quicker to develop. When updating user values, alarm, event and significant change checking are automatically performed, and any change in status is reported in exactly the same way as any other channel. This means that user channels can be used to trigger event mode loggers, or to drive derived digital channels. The channel configuration of user channels can be altered dynamically. This allows the user task to alter any of the status checking discussed above, or simply to modify channel tag, description or units etc. 5.2 Using The Interface Routines The routines are located in a library called orc_user.lib. This library is supplied on the user library ‘C++’ Interface installation disk, and will be copied onto your hard disk during the installation. The library will be put into the Lib subdirectory of the directory to which the C++ Interface was installed. E.g. If you installed the C++ Interface to: C:\Product Name\Sources then the library will be in: C:\Product Name\Sources\Lib To use any of the C++ interface routines, the library must be linked in your project or makefile. In addition it is necessary to include the header files orc_signal.h, orc_common.h and orc_user.h in any source files which use either the functions or data structures. These files are also distributed with the ‘C++’ Interface, and are put into the Defs subdirectory of the directory to which the C++ Interface was installed. E.g. C:\Product Name\Sources\Defs The above library and header file directories must be included in the appropriate search path within your program’s project or makefile. The user library ‘C++’ Interface functions are described in detail in the following Section. The orc functions work on the local server whereas the rem functions can be used on remote servers. Note: Programs written to use the systems Data Structures must be compiled in a 32 bit programming environment (such as Visual Studio), so that the basic types and structure sizes will match up. Measuresoft development Ltd. 11 Version: 5.0.0.0 12 Clear Signal Table Entry _orc_clear_sig Syntax int _orc_clear_sig(ChanPrefix, EntryNum) char *ChanPrefix; int EntryNum; Description This function clears a signal table entry in preparation for performing Wait For Data Update. Parameters ChanPrefix is the one or two letter prefix of the channel range on which the clear signal will be performed. EntryNum is a number between 1 & 6 which defines the table location on which the program will wait. There are six locations available for each channel range. Notes User tasks are free to use any of the 6 locations indicated by EntryNum except that only one user task should use any particular location at any time. This function should be performed once near the beginning of the user program. Its main use is to clear up the signal table entry that may have been left set by an earlier program. Example There are two user tasks that both need to wait for data update on the DS channel range, the first task should use location 1, and the second should use location 2. If the two tasks wait for data update on different channel ranges, e.g. the first waits for DS type channels, and the second for AI type channels, then each task is free to use any of the six available entries for that channel range. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 12 Version: 5.0.0.0 13 Wait For Data Update _orc_wait_update Syntax int _orc_wait_update(ChanPrefix, EntryNum) char *ChanPrefix; int EntryNum; Description This function waits for data update on a particular channel range. Parameters ChanPrefix is the one or two letter prefix of the channel range on which the wait will be performed. EntryNum is a number between 1 & 6, which defines the table location on which the program will wait. See Clear Signal Table Entry for a discussion of which entry number to use. Notes This function is the most efficient way to synchronize user tasks to real time data. This call will put the user task to sleep, so releasing more CPU time to real time data acquisition. As soon as the update on the channel range is completed, the user task will be re-activated. Example If a user task needs to process channel DS1 every time that DS1 is updated, then the following call could be used: _orc_wait_update("DS",1); This example uses signal table entry one. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 13 Version: 5.0.0.0 14 Read Digital Channel Status _orc_read_stat Syntax int _orc_read_stat(ChanPrefix, First, Last, lpStatus) char *ChanPrefix; int First; int Last; D_STATUS * lpStatus; (or A_STATUS * lpStatus;) _rem_read_stat Syntax int _rem_read_stat(Server,ChanPrefix, First, Last, lpStatus) char *Server, *ChanPrefix; int First; int Last; D_STATUS * lpStatus; (or A_STATUS * lpStatus;) Description This function reads channel status bytes for any range of channels. Parameters Server is the sever name or ip address of the system on which the channel range is to be read. ChanPrefix is the one or two letter prefix of the channel range to be read. First is an integer number indicating the first channel number to read. Last is an integer number indicating the last channel number to be read. lpStatus is a pointer to an area into which the channel status structures are copied. There is one status structure for each channel, Notes Each bit in the status structure is used to indicate the current status of the channel. The status structure is different for a digital type channel and an analog type channel. The type declarations A_STATUS and D_STATUS define the meaning of each field. These declarations are included in the file 'orc_common.h'. Example A_STATUS status[10]; _orc_read_stat("DS",1,10,status); This call will read the status bytes for channels DS1 to DS10 into the array status. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 14 Version: 5.0.0.0 15 Read Analog Channel Values _orc_read_an Syntax int _orc_read_an(ChanPrefix, First, Last, lpValues) char *ChanPrefix; int First; int Last; float *lpValues; _rem_read_an Syntax int _rem_read_an(Server, ChanPrefix, First, Last, lpValues) char *Server, *ChanPrefix; int First; int Last; float *lpValues; Description This function reads channel values for any range of analog type. Parameters Server is the sever name or ip address of the system on which the channel range is to be read. ChanPrefix is the one or two letter prefix of the channel range to be read. First is an integer number indicating the first channel number to read. Last is an integer number indicating the last channel number to be read. lpValues is a float pointer to an area into which the channel values are copied. There is one float value for each analog channel. Notes If this call requests values from a digital type channel range then this function will return an error. If this call requests values for digital channels contained in an analog type channel range (e.g. Datascan channel range contains both analog and digital channels) then digital values are returned as 0.0 or 1.0. Example float values[10]; _orc_read_an("DS",1,10,values); This call will read the channel values for channels DS1 to DS10 into the array values. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 15 Version: 5.0.0.0 16 Start Reporting Channel Range _orc_start_reports Syntax int _orc_start_reports(ChanPrefix) char ChanPrefix; Description This function sets multiple channel update mode. Parameters ChanPrefix is the one or two letter prefix of the channel range. Notes This function is used in conjunction with Finish Reporting Channel Range to update groups of user channels. The use of this function is necessary when several groups of channels within the same range are updated through several calls of _orc_write_dig() or _orc_write_an(). If all required channels can be updated from a single call then this function does not need to be used. The start and finish reports functions must only be used with a single channel range at any one time. For example if a user task needs to update P and Q channels, then if P channels are updated first, the _orc_start_reports() call for Q channels must not occur until the _orc_finish_reports() call for P channels has been performed. The use is best described by the examples below. Examples Task needs to update channels P1 to P6 All channels can be updated from a single call to _orc_write_an(), therefore _orc_start_reports() and _orc_finish_reports() not required. Task needs to update channels P1 to P6 and P20 to P22. Task needs two calls to _orc_write_an() to update its channels, therefore _orc_start_reports() should be called before update and _orc_finish_reports() after the update : _orc_start_reports("P"); update P1 - P6 (_orc_write_an) update P20 - P22 _orc_finish_reports("P"); Task needs to update channels P1 to P6 , P20 to P22, Q1 to Q8 and Q32 to Q33 : _orc_start_reports("P"); update P1 - P6 (_orc_write_an) update P20 - P22 _orc_finish_reports("P"); _orc_start_reports("Q"); update Q1 - Q6 (_orc_write_dig) update Q32 - Q33 _orc_finish_reports("Q"); Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 16 Version: 5.0.0.0 17 Finish Reporting Channel Range _orc_finish_reports Syntax int _orc_finish_reports(ChanPrefix) char ChanPrefix; Description This function finishes multiple update mode, and signals that the update has occurred. Parameters ChanPrefix is the one or two letter prefix of the channel range. Notes This function should be called after all the channel updates have occurred for an individual channel range if _orc_start_reports() was called before the updates occurred. See the Start Reporting Channel Range function description for more detail. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 17 Version: 5.0.0.0 18 Write Digital Channel Status _orc_write_dig Syntax #include <orc_common.h> int _orc_write_dig(ChanPrefix, First, Last, lpStatus) char ChanPrefix; int First; int Last; D_STATUS *lpStatus; _rem_write_dig Syntax #include <orc_common.h> int _rem_write_dig(Server, ChanPrefix, First, Last, lpStatus) char *Server,*ChanPrefix; int First; int Last; D_STATUS *lpStatus; Description This function writes digital values for any digital output channel or for any user digital channel. Parameters Server is the sever name or ip address of the system on which the channel range is to be written. ChanPrefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpStatus is a pointer to an area from which the new channel status is determined. There is one status structure for each channel. Notes The D_STATUS definition is included in the file 'orc_common.h'. The value to pass for each digital (using the D_STATUS definition) is: status->status = 0 clear digital channel to low state status->status = 1 set digital channel to high state. If the specified channel is a user digital channel then this function will perform alarm and event checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 18 Version: 5.0.0.0 19 Write Analog Channel Values _orc_write_an Syntax int _orc_write_an(ChanPrefix, First, Last, lpValues) char ChanPrefix; int First; int Last; float *lpValues; _rem_write_an Syntax int _rem_write_an(Server, ChanPrefix, First, Last, lpValues) char *Server,*ChanPrefix; int First; int Last; float *lpValues; Description This function writes analog values for any analog output channel or for any analog user channel. Parameters Server is the sever name or ip address of the system on which the channel range is to be written. ChanPrefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpValues is a pointer to an area from which the new channel values are determined. There is one float value for each channel. Notes If the specified channel is a user analog channel then this function will perform alarm, event and significant change checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 19 Version: 5.0.0.0 20 Read Channel Configuration _orc_read_config Syntax #include <orc_common.h> int _orc_read_config(ChanPrefix, First, Last, lpConfig) char *ChanPrefix; int First; int Last; CHAN_CONFIG *lpConfig; _rem_read_config Syntax #include <orc_common.h> int _rem_read_config(Server, ChanPrefix, First, Last, lpConfig) char *Server,*ChanPrefix; int First; int Last; CHAN_CONFIG *lpConfig; Description This function reads the channel configuration for any channel in the. Parameters Server is the sever name or ip address of the system on which the channel range is to be read. ChanPrefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpConfig is a pointer to an area into which the channel configurations are copied. The type CHAN_CONFIG is declared in 'orc_common.h'. There is one entry of type CHAN_CONFIG for each channel. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 20 Version: 5.0.0.0 21 Write Channel Configuration _orc_write_config Syntax #include <orc_common.h> int _orc_write_config(ChanPrefix, First, Last, lpConfig) char ChanPrefix; int First; int Last; CHAN_CONFIG *lpConfig; Description This function updates the channel configuration for any user channel. Parameters ChanPrefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpConfig is a pointer to an area from which the new channel configurations are copied. The type CHAN_CONFIG is declared in 'orc_common.h'. There is one entry of type CHAN_CONFIG for each channel. Notes User tasks may only modify the configurations for user type channels, any attempt to change any other channel type will results in an error being returned. This function allows user tasks to dynamically modify the alarm and event checking on user channels, or simply to change a channel description or units. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 21 Version: 5.0.0.0 22 Enable Logger _orc_enable_logger Syntax int _orc_enable_logger(LoggerName) char *LoggerName; _rem_enable_logger Syntax int _rem_enable_logger(Server,LoggerName) char *Server, *LoggerName; Description This function starts the named logger. Parameters Server is the sever name or ip address of the system on which the logger is to be enabled. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 22 Version: 5.0.0.0 23 Disable Logger _orc_disable_logger Syntax int _orc_disable_logger(LoggerName) char *LoggerName; _rem_disable_logger Syntax int _rem_disable_logger(Server,LoggerName) char *Server,*LoggerName; Description This function stops the named logger. Parameters Server is the sever name or ip address of the system on which the logger is to be disabled. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already disabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 23 Version: 5.0.0.0 24 Control Logger _orc_control_logger Syntax int _orc_control_logger(LoggerName,Command) char *LoggerName; char Command _rem_control_logger Syntax int _rem_control_logger(Server, LoggerName,Command) char *Server, *LoggerName; char Command Description This function controls the named logger with a specific command. Parameters Server is the sever name or ip address of the system on which the logger is to be controlled. LoggerName is the name of the logger. Command is the name command ‘F’ – force log and ‘S’ – cycle logger. Notes This should only be called on a logger that is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 24 Version: 5.0.0.0 25 Write Logger Text _orc_write_logtext Syntax int _orc_write_logtext(LoggerName, LoggerText) char *LoggerName; char *LoggerText; _rem_write_logtext Syntax int _rem_write_logtext(Server, LoggerName, LoggerText) char *Server,*LoggerName; char *LoggerText; Description This function writes a text log to the most recent log text file for the current time. Parameters Server is the sever name or ip address of the system on which the log text is to be written. LoggerName is the name of the logger. LoggerText is the text to log. Notes This should only be called on a logger that is already enabled and which has just recorded a log. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 25 Version: 5.0.0.0 26 6. ‘Visual Basic’ Data Structures Visual Basic data structures differ slightly from their ‘C++’ counterparts. They are defined in a file called orc_user.bas which is a visual basic module. This module should be added to any Visual Basic project using the orc_user.dll library. Because the DLL is written in ‘C++’, any strings that are passed to and from the DLL must be a Visual Basic array of Bytes, as opposed to a String Type. This is because Visual Basic strings have a prefix which contains the size of the string. Two Visual Basic public functions are included in the orc_user.bas module which allow the user to convert strings to and from an “array of bytes” format needed to pass to the DLL. The functions are described later. Digital Status Structure, VB_D_STATUS All Digital Channels store a Digital Status Structure, as described below. Field Description an_dig Set 0 for digital channels Error Set 1 if channel is in error Status digital state of channel ev_tog Set 0 for low event, 1 for high event Event Set 1 if channel in event al_tog Set 0 for low alarm, 1 for high alarm Alarm Set 1 if channel in alarm Unack Set 1 for unacknowledged alarm Type long long long long long long long long Analog Status Structure, VB_A_STATUS All Analog Channels store an Analog Status Structure, as described below. Field Description Type an_dig long Set 1 for analog channels Error long Set 1 if channel is in error ev_tog long Set 0 for low event, 1 for high event Event long Set 1 if channel in event al_tog long Set 0 for low alarm, 1 for high alarm Alarm long Set 1 if channel in alarm Unack long Set 1 for unacknowledged alarm Sig long Set 1 if significant change has occurred Analog Value, Single All Analog Channels store an Analog Value, as described below. 4 byte, IEEE Single Precision Floating Point Value. Measuresoft development Ltd. 26 Version: 5.0.0.0 27 Configuration Data Structure, VB_CHAN_CONFIG All Channels have the following Configuration Data Structure. Field Description Tag Channel Tag Desc Channel Description Type 0 = Analog Input 1 = Digital Input 2 = Analog Output 3 = Digital Output Chan Channel Configuration Structure Type byte * VB_ORC_TAG_SIZE + 3 byte * VB_ORC_DESC_SIZE + 3 long CHAN Channel Configuration Structure, VB_CHAN Field Description An Analog Channel Configuration Structure Dig Digital Channel Configuration Structure Type VB_AN_CONFIG VB_DIG_CONFIG Analog Channel Configuration Structure, VB_AN_CONFIG Field Description Enabled Channel Is Active ev_on Event Checking To Do al_hi_on High Alarm Checking To Do hs_hi_on High Alarm Hysteresis Checking To Do common_hi High Alarm Drives Common Alarm Output al_lo_on Low Alarm Checking To Do hs_lo_on Low Alarm Hysteresis Checking To Do common_lo Low Alarm Drives Common Alarm Output sig_on Significant Change Checking To Do ref_on Channel Is Referenced scale_on Scaling To Do al_on Not Used Common Not Used hist_on Not Used Units Units Description Scale Channel Scaling Offset Channel Offset ev_high High Event Threshold ev_low Low Event Threshold al_high High Alarm Threshold hs_high High Hysteresis Threshold al_low Low Alarm Threshold hs_low Low Hysteresis Threshold sig_change Significant Change Value al_hi_priority High Alarm Priority al_lo_priority Low Alarm Priority al_hi_message High Alarm Message al_lo_message Low Alarm Message Type long long long long long long long long long long long long long long byte * VB_ORC_UNITS_SIZE + 3 single single single single single single single single single long long byte * VB_ORC_MSG_SIZE + 3 byte * VB_ORC_MSG_SIZE + 3 Measuresoft development Ltd. 27 Version: 5.0.0.0 28 Digital Channel Configuration Structure, VB_DIG_CONFIG Field Description Enabled Channel Is Active ev_on Event Checking To Do al_on Alarm Checking To Do Common Alarm Drives Common Alarm Output al_stat Alarm State ev_stat Event State on_desc On State Description off_desc Off State Description al_priority Alarm Priority al_message Alarm Message Measuresoft development Ltd. 28 Type long long long long long long byte * VB_ORC_DIG_DESC_SIZE + 3 byte * VB_ORC_DIG_DESC_SIZE + 3 long byte * VB_ORC_MSG_SIZE + 3 Version: 5.0.0.0 29 7. ‘Visual Basic’ Interface Routines 7.1 Introduction Just as the C++ programmer can access system data in real time through the library of ‘C++’ routines, so too can the Visual Basic programmer through a ‘C++’ DLL accessible through Visual Basic. All tasks that can be performed using the ‘C++’ library can also be performed using the orc_user.dll provided. A Visual Basic Sample program is also provided which demonstrates most of the following interface routines. 7.2 Using The Interface Routines A Visual Basic module called orc_user.bas should be inserted into your visual basic project before the routines are accessible. The routines are located in a library called orc_user.dll. This library is supplied on the User Library installation disk, and will be copied onto your hard disk during the installation. The library will be put into the VB and subdirectories of the directory to which the User Library was installed and the WINDOWS\SYSTEM32 directory. E.g. If you installed the User Library Interface to: C:\Product Name\ then the libraries will be in: C:\Product Name\VB for Visual Basic 6.0 C:\Product Name\VB_NET for Visual Basic .NET The ‘Visual Basic’ Interface functions are described in detail in the following Section. The orc functions work on the local server whereas the rem functions can be used on remote servers. Note: Programs written to use the systems Data Structures must be compiled in a 32 bit programming environment (such as Microsoft Visual Studio), so that the basic types and structure sizes will match up. Measuresoft development Ltd. 29 Version: 5.0.0.0 30 Clear Signal Table Entry orc_clear_sig Syntax orc_clear_sig(ByVal prefix As String, ByVal entry As Long) As Long Description This function clears a signal table entry in preparation for performing Wait For Data Update. Parameters prefix is the one or two letter prefix of the channel range on which the clear signal will be performed. entry is a number between 1 & 6 which defines the table location on which the program will wait. There are six locations available for each channel range. Notes User tasks are free to use any of the 6 locations indicated by entry except that only one user task should use any particular location at any time. This function should be performed once near the beginning of the user program. Its main use is to clear up the signal table entry that may have been left set by an earlier program. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 30 Version: 5.0.0.0 31 Wait For Data Update orc_wait_update Syntax orc_wait_update(ByVal prefix As String, ByVal entry As Long) As Long Description This function waits for data update on a particular channel range. Parameters prefix is the one or two letter prefix of the channel range on which the wait will be performed. entry is a number between 1 & 6, which defines the table location on which the program will wait. See Clear Signal Table Entry for a discussion of which entry number to use. Notes This function is the most efficient way to synchronize user tasks to real time data. This call will put the user task to sleep, so releasing more CPU time to real time data acquisition. As soon as the update on the channel range is completed, the user task will be re-activated. Example If a user task needs to process channel DS1 every time that DS1 is updated, then the following call could be used: retval = orc_wait_update("DS",1) This example uses signal table entry one. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 31 Version: 5.0.0.0 32 Read Digital Channel Status orc_read_stat rem_read_stat Syntax orc_read_stat(ByVal Prefix As Long, ByVal First As Long, ByVal Last As Long, vb_dig As VB_D_STATUS [or As VB_A_STATUS]) As Long rem_read_stat(ByVal Server As Long, ByVal Prefix As Long, ByVal First As Long, ByVal Last As Long, vb_dig As VB_D_STATUS [or As VB_A_STATUS]) As Long Description This function reads channel status bytes for any range of channels. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be read. First is a integer number indicating the first channel number to read. Last is a integer number indicating the last channel number to be read. lpStatus is a pointer to an area into which the channel status structures are copied. There is one status structure for each channel, Notes Each value in the status structure is used to indicate the current status of the channel. The status structure is different for a digital type channel and an analog type channel. The type declarations VB_A_STATUS and VB_D_STATUS define the meaning of each field. These declarations are included in the file orc_user.bas. Example Dim status(10) As A_STATUS retval = orc_read_stat("DS",1,10,status(1)) This call will read the status bytes for channels DS1 to DS10 into the array status. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 32 Version: 5.0.0.0 33 Read Analog Channel Values orc_read_an rem_read_an Syntax orc_read_an(ByVal prefix As String, ByVal First As Long, ByVal Last As Long, lpValues As Single) As Long rem_read_an(ByVal prefix As String, ByVal prefix As String, ByVal First As Long, ByVal Last As Long, lpValues As Single) As Long Description This function reads channel values for any range of analog type channels. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be read. First is an integer number indicating the first channel number to read. Last is an integer number indicating the last channel number to be read. lpValues is a pointer to an area into which the channel values are copied. There is one ‘single’ value for each analog channel. Notes If this call requests values from a digital type channel range then this function will return an error. If this call requests values for digital channels contained in an analog type channel range (e.g. Datascan channel range contains both analog and digital channels) then digital values are returned as 0.0 or 1.0. Example Dim vals(10) As Single orc_read_an("DS",1,10,vals(1)); This call will read the channel values for channels DS1 to DS10 into the array values. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 33 Version: 5.0.0.0 34 Start Reporting Channel Range orc_start_reports Syntax orc_start_reports(ByVal Prefix As String) As Long Description This function sets multiple channel update mode. Parameters Prefix is the one or two letter prefix of the channel range. Notes This function is used in conjunction with Finish Reporting Channel Range to update groups of user channels. The use of this function is necessary when several groups of channels within the same range are updated through several calls of orc_write_dig() or orc_write_an(). If all required channels can be updated from a single call then this function does not need to be used. The start and finish reports functions must only be used with a single channel range at any one time. For example if a user task needs to update P and Q channels, then if P channels are updated first, the orc_start_reports() call for Q channels must not occur until the orc_finish_reports() call for P channels has been performed. The use is best described by the examples below. Examples Task needs to update channels P1 to P6 All channels can be updated from a single call to orc_write_an(), therefore orc_start_reports() and orc_finish_reports() not required. Task needs to update channels P1 to P6 and P20 to P22. Task needs two calls to orc_write_an() to update its channels, therefore orc_start_reports() should be called before update and orc_finish_reports() after the update : retval = orc_start_reports("P"); update P1 - P6 (orc_write_an) update P20 - P22 retval = orc_finish_reports("P"); Task needs to update channels P1 to P6 , P20 to P22, Q1 to Q8 and Q32 to Q33 : retval = orc_start_reports("P"); update P1 - P6 (orc_write_an) update P20 - P22 retval = orc_finish_reports("P"); retval = orc_start_reports("Q"); update Q1 - Q6 (orc_write_dig) update Q32 - Q33 retval = orc_finish_reports("Q"); Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 34 Version: 5.0.0.0 35 Finish Reporting Channel Range orc_finish_reports Syntax orc_finish_reports(ByVal Prefix As String) As Long Description This function finishes multiple update mode, and signals that the update has occurred. Parameters Prefix is the one or two letter prefix of the channel range. Notes This function should be called after all the channel updates have occurred for an individual channel range if orc_start_reports() was called before the updates occurred. See the Start Reporting Channel Range function description for more detail. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 35 Version: 5.0.0.0 36 Write Digital Channel Status orc_write_dig rem_write_dig Syntax orc_write_dig(ByVal Prefix As String, ByVal First As Long, ByVal Last As Long, vb_stat As VB_D_STATUS) As Long rem_write_dig(ByVal Server As String, ByVal Prefix As String, ByVal First As Long, ByVal Last As Long, vb_stat As VB_D_STATUS) As Long Description This function writes digital values for any digital output channel or for any user digital channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_stat is a pointer to an area from which the new channel status is determined. There is one status structure for each channel. Notes The value to pass for each digital (using the VB_D_STATUS definition) is: vb_stat.status = 0 clear digital channel to low state vb_stat.status = 1 set digital channel to high state. If the specified channel is a user digital channel then this function will perform alarm and event checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 36 Version: 5.0.0.0 37 Write Analog Channel Values orc_write_an rem_write_an Syntax orc_write_an(ByVal Prefix lpValues As Single) rem_write_an(ByVal Server ByVal Last As Long, As String, ByVal First As Long, ByVal Last As Long, As Long As String, ByVal Prefix As String, ByVal First As Long, lpValues As Single) As Long Description This function writes analog values for any analog output channel or for any analog user channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpValues is a pointer to an area from which the new channel values are determined. There is one ‘single’ value for each channel. Notes If the specified channel is a user analog channel then this function will perform alarm, event and significant change checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 37 Version: 5.0.0.0 38 Read Channel Configuration orc_read_config Syntax orc_read_config(ByVal Prefix As String, ByVal First As Long, ByVal Last As Long, vb_bconf As VB_CHAN_CONFIG) Description This function reads the channel configuration for any channel. Parameters Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_bconf is a pointer to an area into which the channel configurations are copied. The type CHAN_CONFIG is declared in orc_user.bas. There is one entry of type CHAN_CONFIG for each channel. Notes Before being able to display any of the data types declared as arrays of bytes, the user must call the function BytesToString described below. This function is declared in ‘orc_user.bas’. The data is declared in this way to keep structure alignment consistent with ‘C++’ structures which use arrays of characters for string types. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 38 Version: 5.0.0.0 39 Write Channel Configuration orc_write_config Syntax orc_write_config(ByVal Prefix As String, ByVal First As Long, ByVal Last As Long, vb_bconf As VB_CHAN_CONFIG) Description This function updates the channel configuration for any user channel. Parameters Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_bconf is a pointer to an area from which the new channel configurations are copied. The type CHAN_CONFIG is declared in orc_user.bas. There is one entry of type CHAN_CONFIG for each channel. Notes User tasks may only modify the configurations for user type channels, any attempt to change any other channel type will results in an error being returned. This function allows user tasks to dynamically modify the alarm and event checking on user channels, or simply to change a channel description or units. Too set the data types declared as arrays of bytes, use the function StringToBytes described below to convert Visual Basic string types to an array of bytes. This function is declared in orc_user.bas. The data is declared in this way to keep structure alignment consistent with ‘C++’ structures which use arrays of characters for string types. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 39 Version: 5.0.0.0 40 Enable Logger orc_enable_logger rem_enable_logger Syntax orc_enable_logger(ByVal LoggerName As String) rem_enable_logger(ByVal Server As String) Description This function starts the named logger. Parameters Server is the name of the server. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 40 Version: 5.0.0.0 41 Disable Logger orc_disable_logger rem_disable_logger Syntax orc_disable_logger(ByVal LoggerName As String) rem_disable_logger(ByVal Server As String, ByVal LoggerName As String) Description This function stops the named logger. Parameters Server is the name of the server. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already disabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 41 Version: 5.0.0.0 42 Control Logger orc_control_logger rem_control_logger Syntax orc_control_logger(ByVal LoggerName As String, ByVal Command As Byte) rem_control_logger(ByVal Server As String, ByVal LoggerName As String, ByVal Command As Byte) Description This function controls the named logger with a specific command. Parameters Server is the name of the server. LoggerName is the name of the logger. Command is the name command ‘F’ – force log and ‘S’ – cycle logger. Notes This should only be called on a logger that is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 42 Version: 5.0.0.0 43 Write Logger Text orc_write_logtext Syntax _orc_enable_logger(ByVal LoggerName As String, ByVal LoggerText As String) Description This function writes a text log to the most recent log text file for the current time. Parameters LoggerName is the name of the logger. LoggerText is the text to log. Notes This should only be called on a logger that is already enabled and which has just recorded a log. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 43 Version: 5.0.0.0 44 Convert Array of Bytes to VB String type BytesToString Syntax BytesToString(Bytes() as Byte, ByVal NumBytes As Long) Description Function converts an array of bytes such as those used in the VB_CHAN_CONFIG structure to a visual basic string type. Parameters Bytes() Pointer to an array of bytes to be converted. NumBytes Size of the array of bytes. Return Value Visual Basic String containing the characters from the array of bytes. --------------------------------------------------------------------- Measuresoft development Ltd. 44 Version: 5.0.0.0 45 Convert a VB String to an Array of Bytes StringToBytes Syntax StringToBytes(strn As String, Bytes() As Byte, NumBytes As Long) Description Function converts a visual basic string type to an array of bytes such as those used in the VB_CHAN_CONFIG structure. This function must be called to fill any Byte arrays in the data structures. Parameters strn Contains the string to convert Bytes() Pointer to an array of bytes to place the string into. Notes The array of bytes must be at least long enough to hold the full extent of the string to be converted. If the string is longer, then the first NumBytes characters are used. After the call, the array of bytes contains the string’s characters, one per byte. Return Value None. --------------------------------------------------------------------- Measuresoft development Ltd. 45 Version: 5.0.0.0 46 8. ‘C#’ Data Structures All channels’ results and configurations are globally available to user tasks through the user library data structures. Results and configuration data structures are stored for each channels prefix. Refer to the standard documentation for a list of channel prefixes on a standard system. The results data structures can store either analog or digital results or only digital results. Note, in the following structure descriptions: All user library Data Structures are declared in the file orc_user.cs. This file should be included in any programs which wish to use these structures. The fields are not necessarily in the order in which they appear in the physical data structure. For details on the physical layout of the data structures, refer to the header file orc_user.cs Packing and Filler fields have been omitted from the descriptions. Programs written to use the Data Structures must be compiled using a 32 bit compilor environment (such as Visual Studio), so that the basic types and structure sizes will match up. Digital Status Structure, CS_D_STATUS All Digital Channels store a Digital Status Structure, as described below. Field Description an_dig Set 0 for digital channels error_status Set 1 if channel is in error status digital state of channel ev_tog Set 0 for low event, 1 for high event event Set 1 if channel in event al_tog Set 0 for low alarm, 1 for high alarm alarm Set 1 if channel in alarm unack Set 1 for unacknowledged alarm Type int Int Int Int Int Int Int Int Analog Status Structure, CS_A_STATUS All Analog Channels store an Analog Status Structure, as described below. Field Description Type an_dig Int Set 1 for analog channels error_status Int Set 1 if channel is in error ev_tog Int Set 0 for low event, 1 for high event event Int Set 1 if channel in event al_tog Int Set 0 for low alarm, 1 for high alarm alarm Int Set 1 if channel in alarm unack Int Set 1 for unacknowledged alarm sig Int Set 1 if significant change has occurred Analog Value, float All Analog Channels store an Analog Value, as described below. 4 byte, IEEE Floating Point Value. Measuresoft development Ltd. 46 Version: 5.0.0.0 47 Configuration Data Structure, CS_CHAN_CONFIG All Channels have the following Configuration Data Structure. Field Description tag Channel Tag desc Channel Description type 0 = Analog Input 1 = Digital Input 2 = Analog Output 3 = Digital Output chan Channel Configuration Structure Type string ORC_TAG_SIZE + 4 string ORC_DESC_SIZE + 4 int CS_CHAN Channel Configuration Structure, CS_CHAN Field Description an Analog Channel Configuration Structure dig Digital Channel Configuration Structure Type CS_AN_CONFIG CS_DIG_CONFIG Analog Channel Configuration Structure, CS_AN_CONFIG Field Description enabled Channel Is Active ev_on Event Checking To Do al_hi_on High Alarm Checking To Do hs_hi_on High Alarm Hysteresis Checking To Do common_hi High Alarm Drives Common Alarm Output al_lo_on Low Alarm Checking To Do hs_lo_on Low Alarm Hysteresis Checking To Do common_lo Low Alarm Drives Common Alarm Output sig_on Significant Change Checking To Do ref_on Channel Is Referenced scale_on Scaling To Do units Units Description scale Channel Scaling offset Channel Offset ev_high High Event Threshold ev_low Low Event Threshold al_high High Alarm Threshold hs_high High Hysteresis Threshold al_low Low Alarm Threshold hs_low Low Hysteresis Threshold sig_change Significant Change Value al_hi_priority High Alarm Priority al_lo_priority Low Alarm Priority al_hi_message High Alarm Message al_lo_message Low Alarm Message Type int int int int int int int int int int int string ORC_UNITS_SIZE + 4 float float float float float float float float float int int string ORC_MSG_SIZE + 4 string ORC_MSG_SIZE + 4 Measuresoft development Ltd. 47 Version: 5.0.0.0 48 Digital Channel Configuration Structure, CS_DIG_CONFIG Field Description enabled Channel Is Active ev_on Event Checking To Do al _on Alarm Checking To Do common Alarm Drives Common Alarm Output al_stat Alarm State ev_stat Event State on_desc On State Description off_desc Off State Description al_priority Alarm Priority al_message Alarm Message Measuresoft development Ltd. 48 Type int int int int int int string ORC_DIG_DESC_SIZE + 4 string ORC_DIG_DESC_SIZE + 4 int string ORC_MSG_SIZE + 4 Version: 5.0.0.0 49 9. 'C#' Interface Routines 9.1 Introduction A library of routines are available that allow access to channels and their configurations from any program written in 'C#'. These programs can be linked into channels as user tasks making them an integral part of the environment. These routines enable a user task to read channel values and channel configurations of any channel, and also to write channel values and configurations to any 'user' channel. Mechanisms are provided for synchronising the reading of data to when this data is updated. This ensures that user tasks are provided with new data as soon as possible after it has been processed. This also makes user tasks more efficient, typically shorter and hence quicker to develop. When updating user values, alarm, event and significant change checking are automatically performed, and any change in status is reported in exactly the same way as any other channel. This means that user channels can be used to trigger event mode loggers, or to drive derived digital channels. The channel configuration of user channels can be altered dynamically. This allows the user task to alter any of the status checking discussed above, or simply to modify channel tag, description or units etc. 9.2 Using The Interface Routines The routines are located in a library called orc_user.dll. This library is supplied on the User Library installation disk, and will be copied onto your hard disk during the installation. The library will be put into the CS_NET and subdirectories of the directory to which the User Library was installed. E.g. If you installed the User Library Interface to: C:\Product Name\ then the libraries will be in: C:\Product Name\CS_NET The ‘C#’ Interface functions are described in detail in the following Section. The orc functions work on the local server whereas the rem functions can be used on remote servers. Note: Programs written to use the user libraryData Structures must be compiled using a 32 bit compilor environment (such as the one provided in Microsoft Visual Studio), so that the basic types and structure sizes will match up. Measuresoft development Ltd. 49 Version: 5.0.0.0 50 Clear Signal Table Entry orc_clear_sig Syntax int n = orc_user.orc_clear_sig(string prefix, int entry) Description This function clears a signal table entry in preparation for performing Wait For Data Update. Parameters prefix is the one or two letter prefix of the channel range on which the clear signal will be performed. entry is a number between 1 & 6 which defines the table location on which the program will wait. There are six locations available for each channel range. Notes User tasks are free to use any of the 6 locations indicated by entry except that only one user task should use any particular location at any time. This function should be performed once near the beginning of the user program. Its main use is to clear up the signal table entry that may have been left set by an earlier program. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 50 Version: 5.0.0.0 51 Wait For Data Update orc_wait_update Syntax int n = orc_user.orc_wait_update(string prefix, int entry) Description This function waits for data update on a particular channel range. Parameters prefix is the one or two letter prefix of the channel range on which the wait will be performed. entry is a number between 1 & 6, which defines the table location on which the program will wait. See Clear Signal Table Entry for a discussion of which entry number to use. Notes This function is the most efficient way to synchronize user tasks to real time data. This call will put the user task to sleep, so releasing more CPU time to real time data acquisition. As soon as the update on the channel range is completed, the user task will be re-activated. Example If a user task needs to process channel DS1 every time that DS1 is updated, then the following call could be used: int retval = orc_user.orc_wait_update("DS",1); This example uses signal table entry one. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 51 Version: 5.0.0.0 52 Read Digital Channel Status orc_read_stat rem_read_stat Syntax int n = orc_user.orc_read_stat(string Prefix, int First, int Last, CS_D_STATUS[] vb_dig) int n = orc_user.rem_read_stat(string Server, string Prefix, int First, int Last, CS_D_STATUS[]) Description This function reads channel status bytes for any range of channels. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be read. First is a integer number indicating the first channel number to read. Last is a integer number indicating the last channel number to be read. lpStatus is a pointer to an area into which the channel status structures are copied. There is one status structure for each channel, Notes Each value in the status structure is used to indicate the current status of the channel. The status structure is different for a digital type channel and an analog type channel. The type declarations CS_A_STATUS and CS_D_STATUS define the meaning of each field. Example private orc_user.CS_D_STATUS[] vb_status = new orc_user.CS_D_STATUS[10]; int retval = orc_user.orc_read_stat("DS",1,10,status); This call will read the status bytes for channels DS1 to DS10 into the array status. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 52 Version: 5.0.0.0 53 Read Analog Channel Values orc_read_an rem_read_an Syntax int n = orc_user.orc_read_an(string Prefix, int First, int Last, float [] lpValues) int n = orc_user.rem_read_an(string Server, string Prefix, int First, int Last, float [] lpValues) Description This function reads channel values for any range of analog type channels. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be read. First is an integer number indicating the first channel number to read. Last is an integer number indicating the last channel number to be read. lpValues is a pointer to an area into which the channel values are copied. There is one ‘single’ value for each analog channel. Notes If this call requests values from a digital type channel range then this function will return an error. If this call requests values for digital channels contained in an analog type channel range (e.g. Datascan channel range contains both analog and digital channels) then digital values are returned as 0.0 or 1.0. Example private orc_user.CS_D_STATUS[] status = new orc_user.CS_D_STATUS[10]; int retval = orc_user.orc_read_an("DS",1,10,status); This call will read the channel values for channels DS1 to DS10 into the array values. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 53 Version: 5.0.0.0 54 Start Reporting Channel Range orc_start_reports Syntax int n = orc_user.orc_start_reports(string Prefix) Description This function sets multiple channel update mode. Parameters Prefix is the one or two letter prefix of the channel range. Notes This function is used in conjunction with Finish Reporting Channel Range to update groups of user channels. The use of this function is necessary when several groups of channels within the same range are updated through several calls of orc_write_dig() or orc_write_an(). If all required channels can be updated from a single call then this function does not need to be used. The start and finish reports functions must only be used with a single channel range at any one time. For example if a user task needs to update P and Q channels, then if P channels are updated first, the orc_start_reports() call for Q channels must not occur until the orc_finish_reports() call for P channels has been performed. The use is best described by the examples below. Examples Task needs to update channels P1 to P6 All channels can be updated from a single call to orc_write_an(), therefore orc_start_reports() and orc_finish_reports() not required. Task needs to update channels P1 to P6 and P20 to P22. Task needs two calls to orc_write_an() to update its channels, therefore orc_start_reports() should be called before update and orc_finish_reports() after the update : int retval = orc_user.orc_start_reports("P"); update P1 - P6 orc_write_an update P20 - P22 int retval = orc_user.orc_finish_reports("P"); Task needs to update channels P1 to P6 , P20 to P22, Q1 to Q8 and Q32 to Q33 : int retval = orc_user.orc_start_reports("P"); update P1 - P6 orc_write_an update P20 - P22 int retval = orc_user.orc_finish_reports("P"); int retval = orc_user.orc_start_reports("Q"); update Q1 - Q6 orc_write_dig update Q32 - Q33 int retval = orc_user.orc_finish_reports("Q"); Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 54 Version: 5.0.0.0 55 Finish Reporting Channel Range orc_finish_reports Syntax int n = orc_user.orc_finish_reports(String Prefix) Description This function finishes multiple update mode, and signals that the update has occurred. Parameters Prefix is the one or two letter prefix of the channel range. Notes This function should be called after all the channel updates have occurred for an individual channel range if orc_start_reports() was called before the updates occurred. See the Start Reporting Channel Range function description for more detail. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 55 Version: 5.0.0.0 56 Write Digital Channel Status orc_write_dig rem_write_dig Syntax int n = orc_user.orc_write_dig(String Prefix, int First, int Last, CS_D_STATUS[] vb_stat) int n = orc_user.rem_write_dig(String Server, String Prefix, int First, int Last, CS_D_STATUS[] vb_stat) Description This function writes digital values for any digital output channel or for any user digital channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_stat is a pointer to an area from which the new channel status is determined. There is one status structure for each channel. Notes The value to pass for each digital (using the VB_D_STATUS definition) is: vb_stat.status = 0 clear digital channel to low state vb_stat.status = 1 set digital channel to high state. If the specified channel is a user digital channel then this function will perform alarm and event checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 56 Version: 5.0.0.0 57 Write Analog Channel Values orc_write_an rem_write_an Syntax int n = orc_user.orc_write_an(string Prefix, int First, int Last, float [] lpValues) int n = orc_user.rem_write_an(string Server, string Prefix, int First, int Last, float [] lpValues) Description This function writes analog values for any analog output channel or for any analog user channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. lpValues is a pointer to an area from which the new channel values are determined. There is one ‘single’ value for each channel. Notes If the specified channel is a user analog channel then this function will perform alarm, event and significant change checking and will report any changes. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 57 Version: 5.0.0.0 58 Read Channel Configuration orc_read_config Syntax int n = orc_user.orc_read_config(string Prefix, int First, int Last, CS_CHAN_CONFIG[] vb_bconf) int n = orc_user.rem_read_config(string server, string Prefix, int First int Last, CS_CHAN_CONFIG[]vb_bconf) Description This function reads the channel configuration for any channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_bconf is a pointer to an area into which the channel configurations are copied. There is one entry of type CHAN_CONFIG for each channel. Notes Before being able to display any of the data types declared as arrays of bytes, the user must call the function BytesToString described below. The data is declared in this way to keep structure alignment consistent with ‘C++’ structures which use arrays of characters for string types. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 58 Version: 5.0.0.0 59 Write Channel Configuration orc_write_config rem_write_config Syntax int n = orc_user.orc_write_config(string Prefix, int First, int Last, CS_CHAN_CONFIG[] vb_bconf) int n = ocr_user.rem_write_config(string server, string Prefix, int First, int Last, CS_CHAN_CONFIG[] vb_bconf) Description This function updates the channel configuration for any user channel. Parameters Server is the name of the server. Prefix is the one or two letter prefix of the channel range to be written. First is an integer number indicating the first channel number to write. Last is an integer number indicating the last channel number to write. vb_bconf is a pointer to an area from which the new channel configurations are copied. There is one entry of type CHAN_CONFIG for each channel. Notes User tasks may only modify the configurations for user type channels, any attempt to change any other channel type will results in an error being returned. This function allows user tasks to dynamically modify the alarm and event checking on user channels, or simply to change a channel description or units. To set the data types declared as arrays of bytes, use the function StringToBytes described below to convert C# string types to an array of bytes. This function is declared in orc_user.cs. The data is declared in this way to keep structure alignment consistent with ‘C++’ structures which use arrays of characters for string types. Return Value Non Negative Integer -1 : : Success. Error. --------------------------------------------------------------------- Measuresoft development Ltd. 59 Version: 5.0.0.0 60 Enable Logger orc_enable_logger rem_enable_logger Syntax int n = orc_user.orc_enable_logger(string LoggerName) int n = orc_user.rem_enable_logger(string Server, string LoggerName) Description This function starts the named logger. Parameters Server is the name of the server. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 60 Version: 5.0.0.0 61 Disable Logger orc_disable_logger rem_disable_logger Syntax int n = orc_user.orc_disable_logger(string LoggerName) int n = orc_user.rem_disable_logger(string Server, string LoggerName) Description This function stops the named logger. Parameters Server is the name of the server. LoggerName is the name of the logger. Notes This can be called repeatedly even if the logger is already disabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 61 Version: 5.0.0.0 62 Control Logger orc_control_logger rem_control_logger Syntax int n = orc_user.orc_control_logger(string LoggerName, char cmd) int n = orc_user.rem_control_logger(string LoggerName, char Cmd) Description This function controls the named logger with a specific command. Parameters Server is the name of the server. LoggerName is the name of the logger. Command is the name command ‘F’ – force log and ‘S’ – cycle logger. Notes This should only be called on a logger that is already enabled. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 62 Version: 5.0.0.0 63 Write Logger Text orc_write_logtext Syntax int n = orc_user.orc_enable_logger(string LoggerName, string LoggerText) Description This function writes a text log to the most recent log text file for the current time. Parameters LoggerName is the name of the logger. LoggerText is the text to log. Notes This should only be called on a logger that is already enabled and which has just recorded a log. Return Value Non Negative Integer : Success. -1 : Error. --------------------------------------------------------------------- Measuresoft development Ltd. 63 Version: 5.0.0.0 64 10. Log File Format The file formats for the data log files and alarm log files are described below in ‘C++’ data structure format. All data log files have the following structure. Channels in the log file are grouped into blocks. These correspond to the individual groups of channels specified in the Configure Logger Channels screen (see the standard documentation). Note, in the following structure descriptions: All Log File Structures are declared in the file log_common.h. This file should be included in any programs which wish to use these structures. Many of the structures used in the log file are the standard Data Structures, which were described in the previous Section. For this reason the file orc_common.h should be included before log_common.h in any programs which use these structures. The fields are not necessarily in the order in which they appear in the physical data structure. For details on the physical layout of the data structures, refer to the header file log_common.h. Throughout the Log File, Synchronisation values are used to ensure the validity of Log File Data. These sync values are different for different structures and should be checked by any applications which directly read data from log files. The sync values are given by macros which are defined in log_common.h, and are mentioned in the description of the particular structure below, (e.g. FILE_HEAD_SYNC is the sync value in the LOG_FILE_HEAD structure). 10.1 Log File Layout Each Log File begins with a file header. This header contains various information about the log file including how many blocks it contains, how many channels are in each block, and what type of channels are in each block. The log file next contains N Configuration blocks, where N is the number of blocks that were logged. The size of each configuration block is dependant on the number of channels in that block. Finally the log file will contain a number of scans. The number of scans and the size of each scan depends on a number of factors but can be obtained from the log file header. Note, in the following structure descriptions: N is taken to be the number of blocks logged in the log file. This can be obtained from the log file header. <Num Channels> is the number of channels that were logged in the particular block to which it is referring. This can be obtained from the description for that particular block within the log file header. Region Name File Header Config Block 1 Description File Information First Configuration Block Header. First Configuration Block. First Configuration Block Footer. Config Block 2 Second Configuration Block Header. Second Configuration Block. Second Configuration Block Footer. ...... ...... Config Block N N-th Configuration Block Header. N-th Configuration Block. N-th Configuration Block Footer. File Header 16 to 64 blocks in log file RFC77 changes Extention extended file header added here Scan1 First Scan. Scan2 Second Scan. Scan3 Third Scan. ...... ...... Measuresoft development Ltd. 64 Type LOG_FILE_HEAD LOG_CONB_HEAD CHAN_CONFIG * <Num Channels> LOG_CONB_FOOT LOG_CONB_HEAD CHAN_CONFIG * <Num Channels> LOG_CONB_FOOT ...... LOG_CONB_HEAD CHAN_CONFIG * <Num Channels> LOG_CONB_FOOT LOG_FILE_HEAD_EXTRA ...... Version: 5.0.0.0 65 10.2 Log File Scan Layout Each Scan in the log file is laid out as follows. First there is a scan header which contains information about a particular scan. Next there are N Data Areas, where N is the number of blocks logged. Finally there is a scan footer. Each Data Area consists of a Data Block Header, and a Data Block. The Data Block is dependant on the type of the channels in the block. If the channels are analog, then there will be <Num Channels> A_STATUS structures followed by <Num Channels> floating point values, where <Num Channels> is the number of channels being logged in this block. If the channels are digital, then there will be <Num Channels> D_STATUS structures in the Data Block and no values. Region Name Scan Header Data Area 1 Description Scan Header First Data Block Header First Data Block Analog / Digital Data Area 2 Second Data Block Header Second Data Block Analog / Digital ...... Data Area N ....... N-th Data Block Header N-th Data Block Analog / Digital Scan Footer Scan Footer Measuresoft development Ltd. 65 Type LOG_SCAN_HEAD LOG_DATA_HEAD A_STATUS * <Num Channels> float * <Num Channels> A_STATUS * <Num Channels> LOG_DATA_HEAD A_STATUS * <Num Channels> float * <Num Channels> A_STATUS * <Num Channels> ...... LOG_DATA_HEAD A_STATUS * <Num Channels> float * <Num Channels> A_STATUS * <Num Channels> LOG_SCAN_FOOT Version: 5.0.0.0 66 10.3 Log File Structures File Header Structure, LOG_FILE_HEAD Field Description file_size Channel Tag Sync Sync Byte (FILE_HEAD_SYNC) no_blocks Number of Data Blocks no_scans Number Of Scans In File start_time Log Start Time stop_time Log Stop Time scan_offset Offset To First Scan scan_size Size Of Each Scan Block Block Information Structure Block Information Structure, LOG_BLOCK Field Description Range Channel Range Structure format 4 For Digital Channel Block, sizeof(float) + sizeof(D_STATUS) (i.e. 8) For Analog Channel Block scan_offset Offset To Data Block Within Each Scan print_name Name Of The Channel Source Type uint ushort ushort uint time_et time_et uint uint LOG_BLOCK * 16 Type CHAN_RANGE ushort ushort char * 25 Channel Range Structure, CHAN_RANGE Field Description Prefix Channel Prefix From First Channel Number In Range To Last Channel Number In Range Type char * ORC_PREFIX_SIZE ushort ushort Configuration Block Header, LOG_CONB_HEAD Field Description Sync Sync Byte (CONB_HEAD_SYNC) Type char Configuration Block Footer, LOG_CONB_FOOT Field Description Sync Sync Byte (CONB_FOOT_SYNC) Type char Scan Header, LOG_SCAN_HEAD Field Description Sync Sync Byte (SCAN_HEAD_SYNC) scan_time Scan Time us_time Not Used Type char time_et ushort Data Block Header, LOG_DATA_HEAD Field Description Sync Sync Byte (DATA_HEAD_SYNC) Type char Scan Footer, LOG_SCAN_FOOT Field Description Sync Sync Byte (SCAN_FOOT_SYNC) Type char Measuresoft development Ltd. 66 Version: 5.0.0.0
