OASIS-CC VERSION V02.05.10 RELEASE NOTES TABLE OF CONTENTS 1 Compatibility Information 2 OASIS-CC Installation Procedure 3 Upgrading V02.05.08 or V02.05.09 Applications to V02.05.10 4 New Features Or Code Fixes 4.1 High Level Language Equation Processing (CRN 321, OSCAR 58) 4.2 Negative Discriminator for Event Message Windows (CRN 353, OSCAR 56) 4.3 Sync Pattern Don't Have to Be Bit Reversed (CRN 362) 4.4 Improved Event Message Contents and Error Message (CRN 367, OSCAR 63/64) 4.5 Acquisition and Processing of Variable Length Ascii Telemetry (CRN 368, OSCAR 55) 4.6 XXXX_PROC fields in commands and element_characteristics table (CRN 374) 5 Change Requests Closed With This Release 6 Main Known Problems And Limitations 6.1 Filename Length Limitation 6.2 Limited thruput while using a generic communication protocol with a TDM frame (CRN 259) 6.3 Badly formatted internet address hangs OASIS-CC (CRN 258) 6.4 Clearing a panel with a selection list presentation type with a scrolling bar can cause OASIS-CC to crash (CRN 252) 6.5 When an IP server stream is switched on, OASIS-CC keyboard or procedure input processing can become locked (CRN 294) 6.6 Double precision floating point printout may be incorrect (CRN 320) 6.7 Highlighted item on a selection list is unchoosable (CRN 265) 6.8 S11W implementation not available in the SOLARIS version 6.9 CEV may fail if CEV_TIMEOUT is greater than 86400.0 seconds (CRN 358) 6.10 Initialization problem with keyed binary bridge (CRN 359) 6.11 Apparent memory leak in graph presentation type (CRN 337) 6.12 Displayed Data Incorrect (CRN 349) 7 Anomaly Or Enhancement Request Reporting 8 Documentation Set Status 9 Upgrades To The Spectrometer Application Appendix A: DATABASE TABLE UPDATES Appendix B: HIGH LEVEL LANGUAGE EQUATION PROCESSOR APPLICATION DEVELOPER'S GUIDE Appendix C: THRUPUT MEASUREMENTS Appendix D: SOLARIS VERSION STATUS Appendix E: SYNC PATTERN, BLOCK ID, ETC... Appendix F: ASCII_CHAR PROTOCOLS USER'S GUIDE Appendix G: WHERE TO FIND EACH PROTOCOL USER'GUIDES OASIS-CC VERSION V02.05.10 RELEASE NOTES These release notes describe version V02.05.10 of OASIS-CC. A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0510. A copy of the notes from previous releases can also be found in the $ODIST/release_notes directory. Users should consult version V02.05.09 release notes as this version was not widely distributed. The major feature of V02.05.10 is that the user can code equations in either C or Ada. This release comes in 2 flavors: a SunOs 4.1.x version and a SOLARIS 2.2 version. The SOLARIS 2.2 uses TAE+ 5.2 for SOLARIS which is only available to the EOS am program. Note that Appendix D gives a brief overview of the SOLARIS version status. 1 Compatibility Information ----------------------------- This release of OASIS-CC has been tested or run under the following conditions: Sparcstation IPC, LX and 2 SunOS 4.1.1 and 4.1.3 X MIT X11R4 with fixes 1 to 18 MOTIF 1.1.4 TAE+ 5.2 Sparcstation 2 SOLARIS 2.2 X X11R5 from BlueStone MOTIF 1.2 from BlueStone TAE+ 5.2 for SOLARIS Note that for the SunOs distribution: (1) The Ada distributions require SunAda 1.1; (2) All the distributions require the MOTIF developer's kit; (3) OASIS-CC cannot be linked with shareable libraries. For example, OASIS-CC needs the libXm.a motif library. It cannot be linked with the libXm.so motif library; Note that for the SOLARIS distribution: (1) The Ada distributions require SunAda 2.0; (2) The C distribution requires a C compiler (OASIS-CC was tested using the Sun C SparCompiler. The make_oasis_app.sh utility requires the Sun C SparCompiler. It needs to be updated for use with other compilers such as the GNU C compiler); (3) OASIS-CC was tested with X and MOTIF from BlueStone; 2 OASIS-CC Installation Procedure ---------------------------------- SunOs Distributions ------------------- Refer to the Unix OASIS-CC V02.05.10 Installation Guide for instructions on how to install the OASIS-CC software from the tar tape. Sites that require the ability to maintain applications running under previous releases must install V02.05.10 in a new directory. Note that the SunOs distribution is quite large because $ODIST/bin contains all of the dump_database and the load_database executables since V02.05.04. This is done to allow users running an old release to convert to this release. If these are not needed, the following files can be deleted from $ODIST/bin: dump_database_v020504 dump_database_v020504a dump_database_v020505 dump_database_v020506 dump_database_v020507 load_database_v020505 load_database_v020506 load_database_v020507 SOLARIS Distributions --------------------- Refer to the Unix OASIS-CC V02.05.10 Installation Guide for instructions on how to install the OASIS-CC software from the tar tape. ******************************************************************************* * We recommend that you run OASIS-CC in the SOLARIS RT (realtime) scheduling * * class rather than the SOLARIS TS (time-sharing) scheduling class. Also, as * * OASIS-CC uses shared libraries, we recommend that you set the environment * * variable LD_BIND_NOW to a non-NULL value (ref: SunOs 5.2 System Services, * * page 188). * ******************************************************************************* ******************************************************************************* * Note that the SOLARIS distribution expects /usr/ccs/bin to be placed before * * /usr/ucb in $path. This is because OASIS-CC needs to be linked with the * * SOLARIS linker, not with the SunOs 4.1 compatibility linker * ******************************************************************************* 3 Upgrading V02.05.08 or V02.05.09 Applications to V02.05.10 ------------------------------------------------------------- ******************************************************************************* * NOTE FOR USERS UPGRADING FROM V02.05.09: * * * * THE V02.05.09 RELEASE ACCIDENTALY INTRODUCED A PROBLEM THAT SHOULD BE * * CORRECTED BEFORE CONVERTING TO ANOTHER RELEASE. THE TABLE AFFECTED IS THE * * ASCII_COMMAND_MAPS TABLE (SEE CRN 387). * * * * IF YOUR APPLICATION BEGINS WITH THE STARTER DATABASE AND THEN LOADS THE * * DATABASE TABLES USING INSERT STATEMENTS, THE PROBLEM IS MINOR AS ONLY THE ONE * ASCII_COMMAND_MAPS TABLE RECORD THAT COMES WITH THE STARTER DATABASE IS * * AFFECTED. THE V02.05.10 CONVERSION SCRIPTS WILL BRING THE CORRECT STARTER * * DATABASE RECORD. * * * * IF YOUR APPLICATION HAS COMMITTED THE ASCII_COMMAND_MAPS TABLE, ALL THE * * ASCII_COMMAND_MAPS RECORDS MAY BE AFFECTED AND THE TABLE NEEDS TO BE REBUILD. * NOTE THAT THE V02.05.10 CONVERSION SCRIPTS WILL DELETE THE CURRENT * * ASCII_COMMAND_MAPS TABLE AND REPLACE IT WITH THE TABLE CONTAINED IN THE * * STARTER DATABASE. * * * ******************************************************************************* Upgrading Under The Same Operating System ----------------------------------------- There are changes in the OASIS-CC V02.05.10 code that makes this release incompatible with applications running version V02.05.09. The changes are: (1) New protocol names have been added; (2) New units have been added; and (3) The size of some fields has changed. Also this release uses a new environment variable called OASIS_USER_CODE. This variable should point to the directory where OASIS-CC will find the archive library that contains the user-developed equation code (see Appendix B). Sites that require the ability to maintain version V02.05.09 or earlier release applications will need new accounts for their associated V02.05.10 applications. The paragraph "Creating OASIS-CC Accounts" in the Unix OASIS-CC V02.05.10 Installation Guide provides details on the requirements for application accounts. The OASIS-CC Application Environment Reference Manual describes how to create the appropriate application environment. The minimum set of files that users need to transfer from existing applications to the areas for developing applications with the new release are: OASIS Database files OASIS Procedure files OASIS Macro files TAE+ resource and graphics files The distribution tape contains 2 command procedures (v020508to10 and v020509to10) ) that will make a V02.05.08 or a V02.05.09 application compatible with V02.05.10. To upgrade to V02.05.10, perform the following: (1) Log in the application account intended for V02.05.09 development. This account should be populated with V02.05.08 or V02.05.09 files (the minimum set is listed above). (2) Set up all the environment variables (including OASIS_USER_CODE). Make sure that ODIST points to the OASIS-CC V02.05.10 distribution and that TAE points to the TAE+ 5.2 distribution. (3) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v020508to10.csh or $ODIST/bin/v020509to10.csh (5) Re-create your application. To update from a version prior to V02.05.08, you must first upgrade to V02.05.08. Refer to the release notes in $ODIST/release_notes. NOTE: If you populate your command database via CSTOL procedures and you are upgrading from V02.05.08 you need to update all insert or update statements for the following tables: command_values In the insert statement for the command_values table, the values for the field max_value, min_value, default_value needs to be changed from integer to float (for example min_value = 32 needs to be changed to min_value = 32.0). Moving From SunOs to Solaris ---------------------------- The distribution tape contains two command procedures (v020508sunosto10.csh and v020509sunosto10) that will make a V02.05.08/SunOs or V02.05.09/SunOs application compatible with V02.05.10 under SOLARIS. To upgrade to V02.05.10, perform the following: (1) Using the v02.05.08 or the v02.05.09 dump_database utility, dump all your tables (you have to do that on a SunOS machine). (2) Log in the application account intended for V02.05.10 development. This account should be populated with V02.05.08 or V02.05.09 files (the minimum set is listed above). (3) Set up all the environment variables (including OASIS_USER_CODE). Make sure that ODIST points to the OASIS-CC V02.05.10 distribution and that TAE points to the TAE+ 5.2 distribution. (4) Transfer all the .dump files created in step 1 to the $OASIS_DATABASE directory on the SOLARIS machine. (5) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v020508sunosto10.csh or $ODIST/bin/v020509sunosto10.csh (6) Re-create your application. NOTE: If you populate your command database via CSTOL procedures and you are upgrading from V02.05.08, you need to update all insert or update statements for the following tables: command_values In the insert statement for the command_values table, the values for the field max_value, min_value, default_value needs to be changed from integer to float (for example min_value = 32 needs to be changed to min_value = 32.0). 4 New Features Or Code Fixes ------------------------------ The following new features and major code fixes are included in this release. New features and code fixes have associated Change Request Numbers (CRNs) that provide a means of tracking changes to the OASIS-CC code. CRNs are generated by LASP and the general OASIS-CC user community. The pertinent CRNs are shown for each enhancement or correction included in this new version of OASIS-CC. 4.1 High Level Language Equation Processing (CRN 321, OSCAR 58) --------------------------------------------------------------- Previously, OASIS-CC equation processing was accomplished by running CSTOL procedures (written by the application developers) in the equation clp. This mechanim and its implementation has several weaknesses: - Under "heavy" equation load there is no way to ensure that all equations are run and that they operate on the correct data. - The CSTOL language does not provide the processing capability that can be found in high level languages like C or Ada. This release of OASIS-CC implements a mechanism by which equations can be coded by the application developers in Ada or C. The implementation ensures that all equations coded in Ada or C are run on time. The implementation is compatible with previous OASIS-CC releases: only equations for which no statement is defined (in the statement field of the equations table record that defines the equation) are passed to the C or the Ada code. If the statement field is not empty, the equation is passed to the equation clp. Applications using the C distribution can code their equations in C and applications using one of the Ada distributions can code their equations in either C or Ada. It is therefore preferable to develop the equations code in C as it can be used with any of the OASIS-CC distribution formats. Appendix B provides an equation developer's guide. 4.2 Negative Discriminator for Event Message Windows (CRN 353, OSCAR 56) ------------------------------------------------------------------------ This is an update to the functionality delivered in v02.05.07 (see crn 256 and OSCAR 10). In v02.05.07 the user could specify (in the discriminator field of the display_descriptions table record describing a message window) the identification code of the messages he/she WANTS to see. With this release the user can specify the identification code of the messages he/she DOES NOT WANT to see. The user can specify a negative discriminator in the form of discriminator preceded by a "-" sign. A positive discriminator is a discriminator not preceded by any sign or preceded by a "+" sign. 4.3 Sync Pattern Don't Have to Be Bit Reversed (CRN 362) -------------------------------------------------------- As indicated in Appnendix J of the V02.05.09 release notes, the way the sync pattern is to be expressed in the streams table is not consistant with the way other bit patterns are expressed in other tables. This release introduces 2 new protocols called IP_1 and ASYNC_CHAR_1. These protocols are identical to the IP and the ASYNC_CHAR protocols with the exception that they expect the sync pattern to be expressed the same way as other bit pattern fields (see Appendix E). 4.4 Improved Event Message and Error Message Contents (CRN 367, OSCAR 63/64) ---------------------------------------------------------------------------- Line numbers are now printed after the name of the procedure in the event message log. When the CSTOL statement in the procedure is several lines long, the number corresponds to the first line. Following is an example of what has been added to the message log contents. What used to be 94/ 20-09:49:32 LP_U (CRN_321_A) let dn_value test_input = 0 dn now appears as 94/ 20-09:49:32 LP_U (CRN_321_A:120) let dn_value test_input = 0 dn where 120 is the line number of the instruction "let dn_value test_input = 0 dn" When an error is generated by the execution of a procedure, the error window now contains, in addition of the error text, the procedure name and the line number. 4.5 Acquisition and Processing of Variable Length Ascii Tlm (CRN 368, OSCAR 55) -------------------------------------------------------------------------------- This release provides two new protocols called ASCII_CHAR_IP and ASCII_CHAR_RS232. The purpose of these two protocols is to allows OASIS to handle return streams (over a network running IP or over an RS232 communication line) with the following characteristics: - The stream is made of ASCII messages. - The length of each message is variable. - All messages are terminated by the same user-defined ASCII character. There are many situations where this new functionality can be very useful. For example communicating CSTOL statements to an OASIS-CC application is made easier with these new protocols. So is reading data from some laboratory instrumentation. The protocols implementation provides a limited set of functions: - Data can be recored and replayed (via the retrieve function). - Each message can be routed to one or more sub clps or to one or more forward streams. - Each message can be stored in a global variable of the class (field data_class in latest_data table) CHARACTER_STRING. The messages are not actually decomposed by OASIS-CC. This is because the implementation does not make any assumption on the contents of the messages. If the messages need to be decomposed, this can be accomplished using an equation. Appendix F provides a user's guide for both protocols. 4.6 XXXX_PROC fields in commands and element_characteristics table (CRN 374) ---------------------------------------------------------------------------- The type for the PRECHECK_PROC and the POSTCHECK_PROC fields in the commands table and for the ACCEPTANCE_PROC field in the element_characteristics table has been changed to CL_STATEMENT from NAME_TYPE. Those fields can now be up to 80 characters long 5 Change Requests Closed With This Release -------------------------------------------- Change Requests Number: 321, 353, 361, 362, 364, 367, 368, 369, 370, 373, 374, 376, 379 and 381. 6 Main Known Problems And Limitations --------------------------------------- 6.1 Filename Length Limitation ------------------------------ In OASIS-CC filenames can be up to 60 characters long. In the SOLARIS and the SunOS versions, the length of the pathname (not the length of the environment variable that translates into the pathname) is included in the filename length. Therefore, the 60 characters limit can be easily reached. A way around this limitation is to softlink the directories to directories with shorter names and define the environment variables relative to the new directories. 6.2 Limited thruput while using a generic communication protocol with a TDM --------------------------------------------------------------------------- frame (CRN 259) ------------------ The current implementation of the generic communication protocol provides the user with some flexibility in controlling the load put on the host machine by the data acquisition if the data comes as packets. Ideally, it would be nice to choose the time_out and frame_length parameters (in the streams table record describing the primary stream) such as frame_length/time_out >> bit rate. If the stream is packetized the only requirement on the frame_length is that it has to be greater than the largest of the packets. The larger the frame_length, the greater the time_out value can be and therefore the lower the load on the machine. Currently in the case of a TDM frame, the frame_length has to be equal to the length of the frame, which limits the possible values for the time_out parameter. 6.3 Badly formatted internet address hangs OASIS-CC (CRN 258) ------------------------------------------------------------ Putting a badly formatted internet address (such as "/128.32.33.34" instead of "128.32.33.34") in the data_line field of the links table for streams that use the IP protocol causes OASIS-CC to hang. 6.4 Clearing a panel with a selection list presentation type with a ------------------------------------------------------------------- scrolling bar can cause OASIS-CC to crash (CRN 252) ------------------------------------------------------ When clearing a panel with a selection list presentation type with a scrolling bar, seven error messages ("Warning: Cannot find callback list in XtRemoveAllCallbacks") are output in the startup window. Our analysis of the problem is that it may cause OASIS-CC to crash. A workaround is to hide the panel rather than clear it. NOTE THAT THIS IS FIXED IN THE SOLARIS VERSION. 6.5 When an IP server stream is switched on, OASIS-CC keyboard or ----------------------------------------------------------------- procedure input processing can become locked (CRN 294) ---------------------------------------------------------- When a server stream is started using the IP protocol, the task handling the stream first waits for a client process to connect. It is only after a connection has been established with a client process that task is able to execute processing directives, such as route or record. 6.6 Double precision floating point printout may be incorrect (CRN 320) ----------------------------------------------------------------------- When a local variable whose value is lower than 1.0e-99 is written or displayed the output is incorrect. For example 1.0e-100 appears as 1.0e-90, 1.0e-101 appears as 1.0e-91. This problem has been traced to a compiler problem and can be reproduced outside the OASIS-CC code. While the printed value is incorrect, the internal representation of the value seems to be correct. THIS PROBLEM OCCURS ONLY IN THE SUNOS VERSION. 6.7 Highlighted item on a selection list is unchoosable (CRN 265) ----------------------------------------------------------------- When a selection list panel comes up with an highlighted item, the item cannot be directly selected. NOTE THAT THIS IS FIXED IN THE SOLARIS VERSION. 6.8 S11W implementation not available in the SOLARIS version ------------------------------------------------------------ Because of driver problems the S11W code is not functional with the SOLARIS version. This should be fixed when the new EDT driver is available (TBD). 6.9 CEV may fail if CEV_TIMEOUT is greater than 86400.0 seconds (CRN 358) ------------------------------------------------------------------------ When CEV_TIMEOUT is set to a value greater than 86400.0 seconds, a command may immediatly fail CEV, as if the CEV_TIMEOUT was set to 0.0. This is due to a SunAda compiler problem. 6.10 Initialization problem with keyed binary bridge (CRN 359) -------------------------------------------------------------- The problem occurs under the following conditions: (a) The bridge is a binary keyed bridge; (b) The "w" values in the TB[w] format don't follow the format rules (i.e "w" defaults to 32 for eu_data and to 96 for time_data, "w" is rounded to the nearest 8 bits and "w" is limited to 128 * 8 for character strings; and (c) non-key items are not recieved before the triggering key item is recieved. Then OASIS-CC may report an error in the "write_line" routine and it is possible that some of the first records are not correctly formatted. This problem can be avoided by using "w" values that follow the rules listed above. 6.11 Apparent memory leak in graph presentation type (CRN 337) -------------------------------------------------------------- The graph presentation type gives the appearence of a memory leak. This is because it was designed to update very rapidly without concerns for memory deallocation except at certain times. This may need to be reconsidered in the future. For now, it is necessary to know when memory is cleaned up in order to avoid the problem of memory continuing to be allocated. If you have a continuously updating graph, it will only have memory cleaned up when: 1) The panel is deleted. (not hidden). 2) A non-visible point is plotted and the graph is set to "jump" to the new point ("dojump" resource is TRUE). 3) The graph item is redrawn due to some change in its appearance. This may be anything including a title change, font change, color change, or anything which would require the items to be rearranged in the graph. 4) The graph area is redrawn by a user scrolling with scrollbars. Notice that continuously updating graphs which take long period of time before a non-visible point is plotted (the end of the graph is reached) will continuously allocate memory without ever deallocating it. 6.12 Displayed Data Incorrect (CRN 349) ---------------------------------------- If the same measurement is displayed more than one time on the same TAE panel, but under a different unit (such as v and mv), the displayed values are incorrect. 7 Anomaly Or Enhancement Request Reporting -------------------------------------------- The mechanism previously used with the VMS version since 1988 to report OASIS-CC anomalies or to suggest enhancements to the OASIS-CC functionality has been extended to the SunOS version. The report generated using this mechanism can be sent to the OASIS project office by electronic mail (the preferred way) or by regular mail. Each report is assigned a Change Request Number (CRN) and is acknowledged to the originator. The CRN can be used to track progress on the report. To report an anomaly enter: $ODIST/bin/report.csh 8 Documentation Set Status ---------------------------- Documentation Changes for V020510 Many documentation updates were delivered with the previous version, V020509. Most of the changes reflected enhanced OASIS-CC capabilities and some of the changes were corrections or clarifications to previous documents. The updates were delivered as 'add ons' to the V020508 Document Set, meaning that they were intended to replace portions of the V020508 documents (the quick Reference Guide is the only one delivered as an entire reprint). The OASIS-CC v020510 distribution has document upgrades as well, which are also delivered as 'add ons' to the V020508 Document set. This means that the v020510 document upgrades are a combination of those delivered with v020509 and v020510. ******************************************************************************* When users replace their existing document pages (whether they are strictly v020508 or already include the mods from v020509) with the modifications delivered with this release, their documents will be up-to-date. ******************************************************************************* The following list details the mods made for the v020509 and v020510 releases. OASIS-CC System Manager's Guide (these updates replace sections from either the 'V02.05.08 and subsequent versions of June, 1993', or the 'V02.05.09 and subsequent versions of December 1993) New Title Pages Date/Version Feb 94/v020510 New Contents Chapter 4 v020509 mods: Entire reprint. Updated for new analog conversions and Unexpected Event Detection. v020510 mods: Pages 9-end. High level language equations (C and Ada) added. Chapter 5 v020509 mods: Entire reprint. Updated for Command Execution Verification, and raw ASCII commands. v020510 mods: Page 17,18 - Typo on Table 5.4 Chapter 6 v020509 mods: Page 2. Removed Reference to IEEE_488 User's Guide. Page 3 - Paragraph 3. Removed implication that command streams are recorded. Pages 1 and 4 are included for complete double-sided page. v020510 mods: Page 7,8. typo in Table 6.2 Chapter 7 v020509 mods: Page 3,8. Modified wording that precluded string data in bridges. Pages 4 and 7 included for complete double-sided pages. v020510 mods: None Chapter 8 v020509 mods: Page 8. New code - HU - added to table 8.1. Page 7 included for complete double-sided page. v020510 mods: Pages 7 to 10. Described new negative discriminator, and clarified 4 digit construct of the CLP - related codes. Chapter 9 v020509 mods: Pages 9-12. Added description of Remote Display. v020510 mods: None. Chapter 10 v020509 mods: Entire reprint. Added section describing OASIS-CC recorded telemetry file formats for previous and new version of OASIS-CC. V020510 mods: None. Chapter 12 v020509 mods: Entire reprint. Removed discussion of task types - all task types are external v020510 mods: None. Appendix A v020509 mods: Entire reprint. Spectrometer application is updated to demo CEV, UED and raw commands (binary and ASCII). A bug in the Spectro_saver procedure was fixed wherein ASCII command tables were not committed. v020510 mods: None Appendix G v020509 mods: None v020510 mods: New Chapter discussing the High Level Language Equations Toolkit OASIS-CC CSTOL Reference Manual (these updates replace sections in either the 'V02.05.08 and subsequent versions of June, 1993', or the 'V02.05.09 and subsequent versions of December 1993) New Title Pages Dates/Version Feb 94/v020509 (no new CSTOL functionality in v020510) New Contents (Note - remove contents pages vii,viii from v020508 or v020509 contents- Table 1 is removed for v020510) Chapter 2 v020509 mods: Entire reprint. Changed Real number description to reflect that they are now double precision, added previously missing "H" radix, added new special variables and reorganized their description based on the ownership of the variables. v020510 mods: Pages 7-end. Removed Table 1. EU units are presented in the DB Guide. Chapter 4 v020509 mods: Pages 3,4. Updated SEND reference to include ASCII. Included POLL and STOP POLLING to Communications directives. v020510 mods: None Chapter 5 v020509 mods: Page 10-14. Added to and clarified the available WAIT statements. Page 9 included for complete double-sided copies. v020510 mods: Page 3,4 11,12 - typos. Chapter 7 v020509 mods: Page 6-10. Embellished the discussion of the available forms of the WAIT statement, as well as the new special variables that can affect the execution of CSTOL procedures. Page 5 included for complete double-sided pages. v020510 mods: None Chapter 9 v020509 mods: Entire reprint. Added new verbs to the available verb list, present raw ASCII command along with the raw binary. Added reference to new Appendix C for adding command verbs to the list. v020510 mods: None Chapter 10 v020509 mods: Entire reprint. Changes were made to the following directives to clarify previous descriptions: INSERT, REPORT,UPDATE,DELETE,REPORT,RECORD,POLL,STOP POLLING. Changes were made to the following directives to include new features available with V02.05.09: CLEAR,DISPLAY,RUN,SEND, SHOW,WAIT,WAIT FOR,FLUSH. v020510 mods: Page 41,42. Misprinted additional PROC directive. Page 65,66 typo. Appendix A v020509 mods: Pages 3,4. Clarify which directives can be passed from the User-CLP to Sub-CLPs. v020510 mods: Page 3,4. Typo. Appendix B v020509 mods: Page 2. Removed indication that EU * EU is legal. Page 1 provided for complete double-sided page. v020510 mods: None Appendix C v020509 mods: New Chapter. Describes how to add or delete command verbs from the CSTOL parser file. v020510 mods: Page 1,2 - Typo. OASIS-CC Database Guide (these updates replace sections in either the 'V02.05.08 and subsequent versions of June, 1993', or the 'V02.05.09 and subsequent versions of December 1993) New Title Pages Dates/Version Feb 94/v020510 (new contents not needed) Table Name Updated for Chapter 2 ANALOG_CONVERSIONS v020509 Chapter 3 ASCII_COMMAND_MAPS (*) v020509 Chapter 4 ASCII_COMMAND_VALUES v020509 Chapter 6 COMMANDS v020509,v020510 Chapter 7 COMMAND_MAPS (*) v020510 Chapter 10 COMMAND_VALUES v020509 Chapter 11 COMMAND_VALUE_CONVERSIONS v020509 Chapter 13 DISPLAY_DEFINITIONS (*) v020509 Chapter 14 DISPLAY_DESCRIPTIONS (*) v020509 Chapter 17 ELEMENT_CHARACTERISTICS v020510 Chapter 17 EQUATIONS v020510 Chapter 19 LATEST_DATA v020509 Chapter 20 LIMITS (*) v020509 Chapter 21 LINKS v020509 Chapter 30 UTILITY_TASKS v020509 Appendix A Data type formats have changed v020509,v020510 over the course of several releases. (*) Indicates that a clarification was made or a typo corrected. All others contain new info relevant to V020509, or V020510. OASIS-CC Quick Reference Guide (this replaces either the 'V02.05.08 and subsequent versions of June, 1993' or the 'V02.05.08 and subsequent versions of Decmber, 1993') v020509 mods: Entire reprint. This document is updated with pagination on a chapter basis. Changes were made to Chapter 7 to reflect that devices on BUS streams act as their command channels elements, and therefore IEEE devices should have a flat hierarchy in element_hierarchies. Procs should be decompiled when not needed was added to Appendix A - Performance Considerations. v020510 mods: Chapter 6. Mention of high level language equation is included OASIS-CC Application Developer's Reference Manual (this replaces the 'V02.05.08 and subsequent versions of June, 1993') v020509 mods: None. v020510 mods: Entire reprint. This document is updated with the information required to manage User - developed C or Ada Equations code. OASIS-CC Installation Guide New version for v020510 9 Upgrades To The Spectrometer Application -------------------------------------------- No upgrades made for v020510. Appendix A: DATABASE TABLE UPDATES This Appendix describes the changes to the streams and unit_conversions tables. STREAMS TABLE *********************** The following protocols have been added: IP_1, ASYNC_CHAR_1, ASCII_CHAR_IP and ASCII_CHAR_RS232. UNIT_CONVERSIONS TABLE ************** The following units have been added: us (for microsecond), rps (for radians per second), dps (for degress per second) and mps (for meters per second). COMMANDS TABLE **************** The type for the PRECHECK_PROC and the POSTCHECK_PROC fields has been changed to CL_STATEMENT from NAME_TYPE. Those fields can now be up to 80 characters long ELEMENT_CHARACTERISTICS TABLE ********** The type of the ACCEPTANCE_PROC field has been changed to CL_STATEMENT from NAME_TYPE. Those fields can now be up to 80 characters long Appendix B: HIGH LEVEL LANGUAGE EQUATION PROCESSOR APPLICATION DEVELOPER'S GUIDE 1 - BACKGOUND 1 - 1 CURRENT IMPLEMENTATION WEAKNESSES Previously, OASIS-CC equation processing was accomplished by running CSTOL procedures (written by the application developers) in the equation clp. This mechanim and its implementation has several weaknesses: - Under "heavy" equation load there is no way to ensure that all equations are run and that they operate on the correct data. - The CSTOL language does not provide the processing capability that can be found in high level languages like C or Ada. This release of OASIS-CC implements a mechanism by which equations can be coded by the application developers in Ada or C. The implementation insure that all equations written in Ada or C are run on time. The implementation is compatible with previous OASIS-CC release: only equations for which no statement is defined (in the statement field of the equations table record that defines the equation) are passed to the C or the Ada code. If the statement field is not empty, the equation is passed to the equation clp. Applications using the C distribution can code their equations in C and applications using one of the Ada distributions can code their equations in either C or Ada. It is therefore preferable to develop the equations code in C as it can be used with any of the OASIS-CC distribution formats. 1 - 2 DEFINITION OF THE USER PROVIDED CODE In the new implementation, after every frame, if OASIS-CC has determined that equations need to be run by the user provided C or Ada code (this is the case if the statement field of the equations table record is emtpy), it calls a routine named "compute_equation". In the OASIS-CC distribution the routine compute_equation is stubbed, i.e. the routine does nothing. However this stub can be replaced by the application developer by his/her equation code. The specifications for the compute_equation routine are: C code: #include void c_compute_equation(lock_id, equation_list, equation_result) db_lock lock_id; input_list equation_list; result_list equation_result; Ada code: with System; procedure Compute_Equation( Lock_Id : in System.ADDRESS; Equation_List : in System.ADDRESS; Equation_Result : in System.ADDRESS); Lock_Id is a parameter internal to OASIS that should not be changed by the user code. Equation_List is a list containing the name of the equations to be run. This list can be scanned by the user code via the Oasis_GetNewEquation routine (see below). Equation_Result is a list containing the global variable to be updated as a result of the equation processing. This list is updated by the user code via the Oasis_Setxxxx routines (see below). The following is a "pdl" description of a typical compute_equation code. It processes two equations named equation_1 and equation_2. The code is mainly a loop. At the top of the loop the code gets the next equation name on the equation list. If the name of the equation is equation_1 a procedure called (in this example) equation_1 is executed. If the name of the equation is equation_2 a procedure called (in this example) equation_2 is executed. The next equation name is then retrieved from the equation list. The loop is exited when all the equations on the equation list have been examined. loop get the next equation name from the equation list exit the loop if no more equation if the equation name = equation_1 then execute procedure equation_1 else if the equation name = equation_2 then execute procedure equation_2 else this equation is not processed by the user code report the problem end if end loop The application developer codes his/her compute_equation routine and the routines that execute each equations (such as the procedures equation_1 and equation_2 above). C Development ------------- When linking an application implementing the equations code in C, OASIS-CC expects the C code (i.e. the code for c_compute_equation and the procedures that c_compute_equation may call) to be in an archive library placed in $OASIS_USER_CODE/libOasisUser.a. The OASIS-CC distribution provide an archive library which contains a stubbed c_compute_equation routine. This archive library is installed in the $OASIS_USER_CODE directory when the starter database is installed or when an existing application is updated to v02.05.10. The script $ODIST/bin/equation_Imakefile.csh can be used to create a makefile to maintain the library libOasisUser. If you don't want to use the makefile, you need to use the command below to compile your C code and then you need to archive the .o file using the unix archive command (ar(1)). cc -I$ODIST/include -D_NO_PROTO -target sun4 -c (SunOs version) cc -I$ODIST/include -Xs -DOSMajorVersion=5 -D_NO_PROTO -DSYSV -c (SOLARIS ver.) Ada development --------------- When linking an application implementing the equation code in Ada, the equation code (i.e. the code for the compute_equation and the procedures that compute_equation may call) should be compiled directly in the user ada library. Every time a new equation is added it may be necessary (depending how the Ada code is structured) to re-create the oasisld.sh link file by running the make_oasisld.sh script. 1 - 3 EQUATION TOOLBOX The OASIS-CC distribution provides a toolbox which contains routines the user can call from his/her Ada or C equations code. These functions and procedures will be reviewed in detail later. This paragraph only describes the basic functionality that they provide. The toolbox may be expanded in the future to provide additional functionalities. Routine name Purpose Oasis_GetNewEquation (Ada) Get the name of the next equation to be executed Oasis_CGetNewEquation (C) Oasis_GetDnValue (Ada) Get the value contained in DN_LOW of a known Oasis_CGetDnValue (C) global variable Oasis_SetDnValue (Ada) Set the DN_LOW of a known global variable Oasis_CSetDnValue (C) Oasis_GetEuValue (Ada) Get the value contained in EU value of a known Oasis_CGetEuValue (C) global variable Oasis_SetEuValue (Ada) Set the EU value of a known global variable Oasis_CSetEuValue (C) Oasis_GetState (Ada) Get the value contained in the EU_STATE of a Oasis_CGetState (C) known global variable Oasis_SetState (Ada) Set the EU_STATE of a known global variable Oasis_CSetState (C) Oasis_GetString (Ada) Get the value contained in the CHAR_STRING of a Oasis_CGetString (C) known global variable Oasis_SetString (Ada) Set the CHAR_STRING of a known global variable Oasis_CSetString (C) Report_Event (Ada) Write a message in the event log Oasis_CReportEvent (C) Compute_Hashkey Utility program to precalculate the haskeys used to access the latest_data table. equation_Imakefile.csh Utility script that creates a makefile that can be used to maintain the libOasisUser.a libray All routines in future extensions of the toolbox will also be prefixed by "Oasis_". Application developer should not name their routines starting with "Oasis_". Following this rule will avoid naming conflicts with future extensions of the toolbox. 1 - 4 MANUAL PAGES FOR THE EQUATION TOOLBOX PROCEDURES NAME Compute_Equation (Ada version) - Process a list of equation c_compute_equation (C version) SYNOPSIS Ada version: with System; procedure Compute_Equation( Lock_Id : in System.ADDRESS; Equation_List : in System.ADDRESS; Equation_Result : in System.ADDRESS); C version: #include void c_compute_equation(lock_id, equation_list, equation_result) db_lock lock_id; input_list equation_list; result_list equation_result; DESCRIPTION The Compute_Equation procedure is called by OASIS-CC code after a frame of data has been processed and it has detected that equations need to be executed. On entry, Equation_List is the list of all the equations to be executed. On exit, Equation_Result should contain the list of all the global data that need to be updated in the latest_data table (along with their new values). Lock_Id is passed from OASIS-CC to Compute_Equation to speed up the accesses to the latest_data table. This parameter SHOULD NOT be modified by Compute_Equation. In the OASIS-CC distribution Compute_Equation is a null procedure. The application developer can substitute the stub with his/her equation processing code. If the application developer codes in Ada, Compute_Equation and the routines it calls must be compiled in the Ada user library. If the application developer codes in C, c_compute_equation and the routines it calls must be archived in $OASIS_USER_CODE/libOasisUser.a. NAME Oasis_GetNewEquation (Ada version) - Get the name of the next equation Oasis_CGetNewEquation (C version) - to be executed SYNOPSIS Ada version: with Equation_User_Tools; with Oasis_Types; procedure Oasis_GetNewEquation( State : in out INTEGER; Equation_List : in System.ADDRESS; Name : out Oasis_Types.NAME_TYPE); C version: #include void Oasis_CGetNewEquation(state, equation_list, equation_name) int *state; input_list *equation_list; char *equation_name; DESCRIPTION Each time this routine is called, it steps through the list of equation names contained in equation_list and returns the name of the next equation in the variable equation_name. The variable state is an in/out parameter. The first time the routine is called it should be set to 0. The routine returns a value of -1 in the state variable when all the equations in equation_list have been examined. In a C program, equation_name can be defined as char equation_name[OASIS_EQUATION_SIZE] NAME Oasis_GetDnValue (Ada version) - Get the value contained in DN_LOW of Oasis_CGetDnValue (C version) - a known global variable SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; procedure Oasis_GetDnValue(Lock_Id : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; Value : out Numbers.INTEGER; Value_Ok : out BOOLEAN); C version: #include int Oasis_CGetDnValue(lock_id, hashed_v, value); db_lock lock_id; oasis_int hashed_v; oasis_int *value; DESCRIPTION This routine returns in the variable value the value contained in the DN_LOW field of the latest_data table record whose key is hashed_v (see compute_haskey). The lock_id parameter is used to speed access to the latest_data table (see compute_equation). In the Ada version the value_ok boolean is set to TRUE if the value exists (field DN_EXITS is TRUE) and if the data_quality field is set to GOOD. Otherwise value_ok is set to FALSE. In the C version, the function returns respectively 1 or 0. NAME Oasis_SetDnValue (Ada version) - Set the DN_LOW of a known global Oasis_CSetDnValue (C version) - variable SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; procedure Oasis_SetDnValue(Value : in Numbers.INTEGER; Hashed_V : in Numbers.INTEGER; Equation_Result : in System.ADDRESS); C version: #include int Oasis_CSetDnValue(value, hashed_v, equation_result); oasis_int value; oasis_int hashed_v; result_list equation_result; DESCRIPTION This routine passes back to OASIS-CC (in the value variable ) the value to be put in the DN_LOW field of the latest_data record whose key is hashed_v (see compute_hashkey). The value is passed back via a list of results called equation_result (see compute_equation). NAME Oasis_GetEuValue (Ada version) - Get the value contained in EU value Oasis_CGetEuValue (C version) - of a known global variable SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; with Measurement_Definition; procedure Oasis_GetEuValue( Lock_ID : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; EU_Value : out Numbers.FLOAT; EU_Unit : out Measurement_Definition.EU_Unit_Categories; Value_OK : out BOOLEAN); C version: #include int Oasis_CGetEuValue(lock_id, hashed_v, eu_value, eu_unit); db_lock lock_id; oasis_int hashed_v; oasis_float *eu_value; char *eu_unit DESCRIPTION This routine returns in eu_value variable the value contained in the EU field of the latest_data table record whose key is hashed_v (see compute_haskey). The eu_unit parameter returns the value contained in the EU_UNITS field. The lock_id parameter is used to speed access to the latest_data table (see compute_equation). In the Ada version the value_ok boolean is set to TRUE if the data_quality field is set to GOOD. Otherwise value_ok is set to false. In the C version, the function returns respectively 1 or 0. In a C program, eu_unit can be defined as char eu_unit[OASIS_UNIT_SIZE] NAME Oasis_SetEuValue (Ada version) - Set the EU value of a known global Oasis_CSetEuValue (C version) - variable SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; with Measurement_Definition; procedure Oasis_SetEuValue( EU_Value : in Numbers.FLOAT; EU_Unit : in Measurement_Definition.EU_Unit_Categories; Hashed_V : in Numbers.INTEGER; Equation_Result : in System.ADDRESS); C version: #include void Oasis_CSetEuValue(eu_value, eu_unit, hashed_v, equation_result) oasis_long_float eu_value; char *eu_unit; oasis_int hashed_v; result_list equation_result; DESCRIPTION This routine passes back to OASIS-CC (in the eu_value and eu_unit variables) the value to put in the EU and EU_UNITS fields of the latest_data record whose key is hashed_v (see compute_hashkey). The value is passed back via a list of results called equation_result (see compute_equation). In a C program eu_unit can be defined as char eu_unit[OASIS_UNIT_SIZE] NAME Oasis_GetState (Ada version) - Get the value contained in the Oasis_CGetState (C version) - EU_STATE of a known global variable SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; with Oasis_Types; procedure Oasis_GetState( Lock_ID : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; State : out Oasis_Types.NAME_TYPE; Value_OK : out BOOLEAN); C version: #include int Oasis_CGetState(lock_id, hashed_v, state); db_lock lock_id; oasis_int hashed_v; char *state; DESCRIPTION This routine returns in state variable the value contained in the EU_STATE field of the latest_data table record whose key is hashed_v (see compute_haskey). The lock_id parameter is used to speed access to the latest_data table (see compute_equation). In the Ada version the value_ok boolean is set to TRUE if the data_quality field is set to GOOD. Otherwise value_ok is set to false. In the C version, the function returns respectively 1 or 0. In a C program state can be defined as char state[OASIS_STATE_SIZE] NAME Oasis_SetState (Ada version) - Set the EU_STATE of a known global Oasis_CSetState (C version) - variable SYNOPSIS Ada version: with Equation_User_Tools; with Oasis_Types; procedure Oasis_SetState( State : in Oasis_Types.NAME_TYPE; Hashed_V : in Numbers.INTEGER; Equation_Result : in System.ADDRESS); C version: #include void Oasis_CSetState(state, hashed_v, equation_result); char *state; oasis_int hashed_v; result_list equation_result; DESCRIPTION This routine passes back to OASIS-CC (in the variable state) the value to put in the EU_STATE field of the latest_data record whose key is hashed_v (see compute_hashkey). The value is passed back via a list of results called equation_result (see compute_equation). In a C program, state can be defined as char state[OASIS_STATE_SIZE] Note that only the 16 first characters of state will be passed to OASIS-CC. NAME Oasis_GetString (Ada version) - Get the value contained in the Oasis_CGetString (C version ) - CHAR_STRING of a known global variable SYNOPSIS Ada version: with Equation_User_Tools; with Data_Handling_Interface; with Numbers; procedure Oasis_GetString( Lock_ID : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; Char_String : out Data_Handling_Interface.CHARACTER_STRING; Value_OK : out BOOLEAN); C version: #include int Oasis_CGetString(lock_id, hashed_v, char_string); db_lock lock_id; oasis_int hashed_v; char *char_string; DESCRIPTION This routine returns in the variable char_string, the value contained in the CHAR_STRING field of the latest_data table record whose key is hashed_v (see compute_haskey). The lock_id parameter is used to speed access to the latest_data table (see compute_equation). In the Ada version the value_ok boolean is set to TRUE if the data_quality field is set to GOOD. Otherwise value_ok is set to false. In the C version, the function returns respectively 1 or 0. In a C program, char_string can be defined as char char_string[OASIS_STRING_SIZE] NAME Oasis_SetString (Ada version) - Set the CHAR_STRING of a known global Oasis_CSetString (C version) - variable SYNOPSIS Ada version: with Equation_User_Tools; with Data_Handling_Interface; procedure Oasis_SetString( Char_String : in Data_Handling_Interface.CHARACTER_STRING; Hashed_V : in Numbers.INTEGER; Equation_Result : in System.ADDRESS); C version: #include void Oasis_CSetString(char_string, hashed_v, equation_result); char *char_string; int hashed_v; result_list equation_result; DESCRIPTION This routine passes back to OASIS-CC (in the char_string variable) the value to put in the CHAR_STRING field of the latest_data record whose key is hashed_v (see compute_hashkey). The value is passed back via a list of results called equation_result (see compute_equation). In a C program, char_string can be defined as char char_string[OASIS_STRING_SIZE] Note that only the first 128 characters will be passed back to OASIS-CC NAME report_event (Ada version) - write a message in the event log Oasis_CReportEvent (C version) SYNOPSIS Ada version: with Report_Event; procedure Report_Event(Id: in STRING; Msg: in STRING); C version: #include void Oasis_CReportEvent(id, msg) char *id, *msg DESCRIPTION Report_Event writes in the event message log the text contained in Msg. The message is identified by the four first characters of Id. In the C version, id and msg can be defined as char id[OASIS_STRING_SIZE] The Ada version can make used of the general_io package which instantiates text_io for most of the types used in OASIS-CC: -- Copyright 1986, 1992 by the Regents -- of the University of Colorado with NUMBERS; with TEXT_IO; with MEASUREMENT_DEFINITION; package GENERAL_IO is package INTIO is new TEXT_IO.INTEGER_IO(NUM => NUMBERS.INTEGER); package STANDARD_INTIO is new TEXT_IO.INTEGER_IO(NUM => INTEGER); package FLOATIO is new TEXT_IO.FLOAT_IO(NUM => NUMBERS.FLOAT); package STANDARD_FLOATIO is new TEXT_IO.FLOAT_IO(NUM => FLOAT); package LGFLOATIO is new TEXT_IO.FLOAT_IO(NUM => NUMBERS.LONG_FLOAT); package DURATION_IO is new TEXT_IO.FIXED_IO(NUM => DURATION); package BOOLEAN_IO is new TEXT_IO.ENUMERATION_IO (ENUM => BOOLEAN); end GENERAL_IO; NAME compute_haskey SYNOPSIS $ODIST/bin/compute_hashkey DESCRIPTION Most of the toolbox routines listed in 1.3 access the latest_data table. In OASIS-CC accesses to this table are done using a key computed from the external_element and the item_name of the global variable that is referenced. The derived key, often refered to as hashkey, is a 32 bits integer value. Using the hashkey rather than the external_element and the item_name speeds up considerably the accesses to the latest_data table. However computing the hashkey value takes quite a long time. That is why it is preferable to pre-compute the hashkeys that will be used in the equations. The OASIS-CC distribution provides a utility (compute_hashkey) that given an external_element and an item_name returns the hashkey value to be used by the tool box routines. Example: mirza% compute_hashkey Enter external_element:platform Enter item_name :position The hashkey for PLATFORM POSITION is 1556724465 NAME equation_Imakefile.csh SYNOPSIS $ODIST/bin/equation_Imakefile.csh DESCRIPTION This C shell script creates the makefile that will check the dependencies of all the .c files in the current directory, compile the .c and archive the resulting .o files in a library called libOasisUser.a. The makefile can then be used to maintain the library up-to-date. EXAMPLE Let assume that the user has just type the code for c_compute_equation.c and for three equation routines (call test_equation_1.c, test_equation_2.c and test_equation_3.c). The user can execute equation_Imakefile.csh to create a makefile and define the dependencies between his/her C routines: mirza% equation_Imakefile.csh Making depends... makedepend -s "# DO NOT DELETE" -- -DXTFUNCPROTO -- makedepend -s "# EXTRA DEPENDENCIES" -- -I/mirza5/distrib/oasis/sunos_v020509/ c_distrib/include -D_NO_PROTO -- c_compute_equation.c test_equation_1.c test _equation_2.c test_equation_3.c Finished making depends. mirza% He/she can then run "make" every time a modification is made to one of the routines or to one of the include files they reference. In the example below all 4 routines needed to be recompiled: mirza% make Creating library OasisUser... Building library OasisUser... cc -I/mirza5/distrib/oasis/sunos_v020509/c_distrib/include -D_NO_PROTO -t arget sun4 -c c_compute_equation.c cc -I/mirza5/distrib/oasis/sunos_v020509/c_distrib/include -D_NO_PROTO -t arget sun4 -c test_equation_1.c cc -I/mirza5/distrib/oasis/sunos_v020509/c_distrib/include -D_NO_PROTO -t arget sun4 -c test_equation_2.c cc -I/mirza5/distrib/oasis/sunos_v020509/c_distrib/include -D_NO_PROTO -t arget sun4 -c test_equation_3.c rm -f libOasisUser.a ar cq libOasisUser.a c_compute_equation.o test_equation_1.o test_equation_2.o te st_equation_3.o ar: filename c_compute_equation.o truncated to c_compute_equat ar: filename test_equation_1.o truncated to test_equation_1 ar: filename test_equation_2.o truncated to test_equation_2 ar: filename test_equation_3.o truncated to test_equation_3 ranlib libOasisUser.a Finished building library OasisUser. Finished creating library OasisUser. mirza% Note that equation_Imakefile.csh needs to be re-run every time a new routine is added. 2 - EXAMPLES 2 -1 EXAMPLE OF C CODE file compute_equation.c: #include #include void c_compute_equation(lock_id, equation_list, equation_result) db_lock lock_id; input_list equation_list; result_list equation_result; { char *equation_name[OASIS_EQUATION_SIZE]; int state; /* list of the equation procedure*/ state = 0; for (;;) { Oasis_CGetNewEquation(&state, equation_list, equation_name); if (state == -1) break; if (strcmp(equation_name, "TEST_EQUATION_1 ") == 0) { test_equation_1(lock_id, equation_result); } else if (strcmp(equation_name, "TEST_EQUATION_2 ") == 0) { test_equation_2(lock_id, equation_result); } else if (strcmp(equation_name, "TEST_EQUATION_3 ") == 0) { test_equation_3(lock_id, equation_result); } } } file test_equation_1.c: #include void test_equation_1(lock_id, equation_result) db_lock lock_id; result_list equation_result; { /* variables used by this equation */ oasis_int byte128; if (Oasis_CGetDnValue(lock_id, 580021342, &byte128)) { if (byte128 == 125) { Oasis_CSetState("ON", 50871138, equation_result); } else { Oasis_CSetState("OFF", 50871138, equation_result); } } } file test_equation_2.c: #include void test_equation_2(lock_id, equation_result) db_lock lock_id; result_list equation_result; { /* variables used by this equation */ oasis_float byte127; char eu_unit[OASIS_UNIT_SIZE]; if (Oasis_CGetEuValue(lock_id,-1763233093, &byte127, &eu_unit[0])) { Oasis_CSetEuValue(byte127,"v", -700799282, equation_result); if (byte127 == 1.0) { Oasis_CSetString("Rien ne va plus", -279361942, equation_result); } else { Oasis_CSetString("Tout va tres bien Madame la Marquise", -279361942, equation_result); } } } file test_equation_3.c: #include void test_equation_3(lock_id, equation_result) db_lock lock_id; result_list equation_result; { /* variables used by this equation */ oasis_int byte126; if (Oasis_CGetDnValue(lock_id, 192913142, &byte126)) { Oasis_CSetEuValue( ((double) byte126) * 100.0, "mv", -209718957, equation_result); } } 2 - 2 EXAMPLE OF ADA CODE file compute_equation.a: with Equation_User_Tools, Application_Equations, -- user developed package Oasis_Types; use Equation_User_Tools, Application_Equations; procedure Compute_Equation( Lock_Id : in System.ADDRESS; Equation_List : in System.ADDRESS; Equation_Result : in System.ADDRESS) is State : INTEGER := 0; Equation_Name : Oasis_Types.NAME_TYPE; begin -- of Compute_Equation loop Oasis_GetNewEquation(State, Equation_List, Equation_Name); exit when State = -1; if Equation_Name = "TEST_1 " then Test_1(Lock_Id, Equation_Result); elsif Equation_Name = "TEST_2 " then Test_2(Lock_Id, Equation_Result); elsif Equation_Name = "TEST_3 " then Test_3(Lock_Id, Equation_Result); elsif Equation_Name = "TEST_4 " then Test_4(Lock_Id, Equation_Result); elsif Equation_Name = "TEST_6 " then Test_6(Lock_Id, Equation_Result); end if; end loop; end Compute_Equation; file application_equations_.a: with System; package Application_Equations is procedure Test_1 (Lock_Id : in System.Address; Equation_Result : in System.Address); procedure Test_2 (Lock_Id : in System.Address; Equation_Result : in System.Address); procedure Test_3 (Lock_Id : in System.Address; Equation_Result : in System.Address); procedure Test_4 (Lock_Id : in System.Address; Equation_Result : in System.Address); procedure Test_6 (Lock_Id : in System.Address; Equation_Result : in System.Address); end Application_Equations; file application_equations.a: with Numbers, Oasis_Types, Equation_User_Tools, Measurement_Definition, Data_Handling_Interface, Report_Event; use Numbers, Measurement_Definition, Oasis_Types, Data_Handling_Interface, Equation_User_Tools; package body Application_Equations is -- NOTE: It would be more manageable to declare all procedures -- as separate procedure Test_1 (Lock_Id : in System.Address; Equation_Result : in System.Address) is Mf_Id_P1 : Numbers.INTEGER; Mf_Id : Numbers.INTEGER; Status : BOOLEAN; begin -- of Test_1 Oasis_GetDnValue(Lock_Id, 742351285, Mf_Id, Status); Mf_Id_P1 := Mf_Id + 1; Oasis_SetDnValue(Mf_Id_P1, -1849135553, Equation_Result); if Mf_Id = 0 then Report_Event("LI_U"," Major Frame just rolled over..."); end if; end Test_1; procedure Test_2 (Lock_Id : in System.Address; Equation_Result : in System.Address) is Payload_temperature : Numbers.FLOAT; Unit : Eu_Unit_Categories; F_Temp : Numbers.FLOAT; Status : BOOLEAN; begin -- of Test_2 Oasis_GetEuValue(Lock_Id, -1995859241, Payload_Temperature, Unit, Status); F_Temp := ((Payload_Temperature + 40.0) * 9.0/5.0) - 40.0; Oasis_SetEuValue(F_Temp, F, -34821337, Equation_result); end Test_2; procedure Test_3 (Lock_Id : in System.Address; Equation_Result : in System.Address) is Status : BOOLEAN; Hv_State : Oasis_Types.NAME_TYPE; begin -- of Test_3 Oasis_GetState(Lock_Id, 773904655, Hv_State, Status); Oasis_SetState(Hv_State, 1955922392, Equation_Result); Report_Event("LI_U", "HIGH VOLTAGE protection changed"); end Test_3; procedure Test_4 (Lock_Id : in System.Address; Equation_Result : in System.Address) is Status : BOOLEAN; Char_Str : Data_Handling_Interface.CHARACTER_STRING; begin -- of Test_4 Oasis_GetString(Lock_Id, 1077286016, Char_Str, Status); Oasis_SetString(Char_Str, 1530505261, Equation_Result); Report_Event("LI_U", Char_Str); end Test_4; procedure Test_6 (Lock_Id : in System.Address; Equation_Result : in System.Address) is Tp3 : Numbers.INTEGER; Tp4 : Numbers.INTEGER; Status : BOOLEAN; begin -- of Test_6 Oasis_GetDnValue(Lock_Id, -1392248074, Tp3, Status); Tp4 := Tp3 + 1; Oasis_SetDnValue(Tp4, -826077402, Equation_Result); Report_Event("LI_U", "From HLEQ: Test pt3 = " & Integer'Image(Tp3) & " Test pt4 = " & Integer'Image(Tp4)); end Test_6; end Application_Equations; Appendix C: THRUPUT MEASUREMENTS THRUPUT MEASUREMENTS OASIS-CC thruput was measured under the following conditions: Computer : Sparcstation 2, 32 Mbyte of main memory OS : SOLARIS 2.2 OASIS-CC : - Release of v02.05.10. Compiled with run-time checks ON - Application set up to decompose 128 measurements per packet. Measurements are converted to engineering unit using the analog conversion table and are limit checked. - Protocol used is Ip - OASIS-CC verifies the sync pattern of each packet Simulator: - Packet size set to 128 bytes - Running on a remote workstation In the measured % of cpu, three numbers are given. The first one is computed using the ps command. The second and the third one are the %cpu for user and idle as reported by the vmstat command. measured measured # measurements # measurements Limits measured packet bit decomposed changing status % of cpu rate rate per second per second 16/s 16kbps 0 n/a n/a << 1 16/s 16kbps 2048 0 n/a 16,16,84 16/s 16kbps 2048 1984 off 40,40,60 16/s 16kbps 2048 1984 on 54,52,44 24/s 24kbps 0 n/a n/a << 1 24/s 24kbps 3072 0 n/a 24,24,76 24/s 24kbps 3072 240 on 28,28,70 24/s 24kbps 3072 480 on 34,34,65 24/s 24kbps 3072 1200 on 47,48,51 32/s 32kbps 0 n/a n/a << 1 32/s 32kbps 4096 0 n/a 32,32,68 32/s 32kbps 4096 320 on 37,37,57 32/s 32kbps 4096 640 on 45,45,54 For all measurement, the primary stream was set up with a frame_length of 4096 and a time_out of 0.05. Computer : Sparcstation 2, 32 Mbyte of main memory OS : SunOs 4.1.3 OASIS-CC : - Release of v02.05.10. Compiled with run-time checks ON - Application set up to decompose 128 measurements per packet. Measurements are converted to engineering unit using the analog conversion table and are limit checked. - Protocol used is Ip - OASIS-CC verifies the sync pattern of each packet Simulator: - Packet size set to 128 bytes - Running on a remote workstation In the measured % of cpu, three numbers are given. The first one is computed using the ps command. The second and the third one are the %cpu for user and idle as reported by the vmstat command. measured measured # measurements # measurements Limits measured packet bit decomposed changing status % of cpu rate rate per second per second 16/s 16kbps 0 n/a n/a << 1 16/s 16kbps 2048 0 n/a 18,17,84 16/s 16kbps 2048 1984 off 44,43,57 16/s 16kbps 2048 1984 on 54,53,44 24/s 24kbps 0 n/a n/a << 1 24/s 24kbps 3072 0 n/a 29,27,71 24/s 24kbps 3072 240 on 29,29,71 24/s 24kbps 3072 480 on 37,36,61 24/s 24kbps 3072 1200 on 48,47,52 32/s 32kbps 0 n/a n/a << 1 32/s 32kbps 4096 0 n/a 37,36,64 32/s 32kbps 4096 320 on 42,41,59 32/s 32kbps 4096 640 on 50,48,52 For all measurement, the primary stream was set up with a frame_length of 4096 and a time_out of 0.05. Appendix D: SOLARIS VERSION STATUS V02.05.09 was the first release of OASIS-CC compatible with the SOLARIS 2.2 operating system. The intent of this note is to give the users some information about the current state of OASIS-CC under this new operating system. 1 - Some SOLARIS notes The version of SOLARIS we are currently running at LASP is 2.2 with the following patches: Patch-ID# 100982-02 Patch-ID# 100992-03 Patch-ID# 100999-51 Patch-ID# 101014-05 Patch-ID# 101018-05 Patch-ID# 101022-05 Patch-ID# 101025-08 Patch-ID# 101031-02 Patch-ID# 101090-01 Patch-ID# 101096-02 Patch-ID# 101109-03 Patch-ID# 101301-01 Patch-ID# 101348-01 Patch-ID# 100983-02 Patch-ID# 101036-03 Patch-ID# 101095-01 We are also running X11R5 and Motif 1.2, both from BlueStone. The Ada compiler we are using is a new version of the SunAda compiler (release 2.0). The only system optimization we have done was to update the kernel maxusers parameter to 64. The first impression is not too good. The system takes a long time to get back to the prompt after an incorrect password has been typed. Doing xinit also takes a long time. To test OASIS-CC thruput we are using a data simulator that can be commanded to output data at a known rate. This program is written in Ada. Because of overhead in its Ada code the data simulator outputs data at a lower rate than requested. The difference between the SunOs 4.1 and the SOLARIS versions is striking (see table 1). Is this due to SOLARIS or to SunAda 2.0? requested rate measured rate measured rate SunOs 4.1 (1) SOLARIS 2.2 (2) 19 kbps 16.6 kbps 14.4 kbps 29 kbps 24.4 kbps 19.0 kbps (1) as measured on a SparcStation 2 and a Sparc IPC (2) as measured on a SparcStation 2 Table 1: measured data rate vs requested rate using the simulator program On the other hand, the RT (realtime) scheduling class which is available with SOLARIS is a huge improvement over SunOs 4.1 and should be always used when running OASIS-CC. 2 - OASIS V02.05.10 status Both V02.05.10 versions of OASIS-CC provide the same capabilities except for what is listed below. Their performance is about the same. 2 - 1 S11W support This support is not currently available with the SOLARIS version. We can make the system crash with small test programs. The culprit may be the asynchronous io code (i.e., aiord() and aiwait() in aiolib) or the EDT driver (EDT is re-writing the S11W driver for SOLARIS). 2 - 2 1553 EOS am low rate science protocol, remote terminal support Transfering data block shorter than 8192 bits works fine. Transfering data blocks larger than 8192 bits does not work: the system gets stuck and has to be rebooted the hard way (i.e., using the power switch as even L1 A does not work). The culprit seems to the select() code, which is used (in a polling mode) to sense if the bus controller has read the remote terminal subaddresses before reloading them. 2 - 3 RS232 support There is big difference of thruput between the SunOs 4.1 version and the SOLARIS 2.2 version when acquiring data using an RS232 connection. In both versions the amount of cpu used by OASIS-CC is about the same. But the system itself (as reported by vmstat) uses a lot more of cpu under SOLARIS than under SunOs 4.1. The difference is so big that it is not currently possible to recommend the use of the RS232 support with the SOLARIS version of OASIS-CC. We also noted that running OASIS-CC under the RT scheduling class did not solve the "sync loss" problem, contrary to what we were expecting. In fact "sync loss" messages seem more common in the SOLARIS version. The RS232 code is different in the two OASIS-CC versions. The SunOs version used the BSD compatibility module (ttcompat()) to set up the transmission port. The SOLARIS version used termios(), as we were unable to have ttcompat() work correctly. However this should be merely a cosmetic change. Table 2 gives the performances measured with the RS232 support code at only 8kbps (as we were unable to run at 16kbps using the SOLARIS version). measured OASIS-CC cpu usage vmstat inferred from ps user sys idle SunOs 4.1.3 8% 9% 2% 89% SOLARIS 2.2 10% 10% 25% 65% Table 2: % of cpu, with RS232 input at 8kps, 1024 measurements extracted per second. Appendix E: SYNC PATTERN, BLOCK ID, ETC... The way users have to express bit pattern in the OASIS-CC database is not obvious. In fact it may appear very strange. Bit patterns are specified in the following database tables: Table name Field name COMMANDS FIXED_PATTERN CEV_MASK COMMAND_MESSAGES HEADER_PATTERN TRAILER_PATTERN DECOMPOSITION BLOCK_ID_VALUE STREAMS ID_VALUE SYNC_PATTERN These fields are expressed in hexadecimal. The first hexadecimal character represents the most significant four bits of the first byte of the pattern, the second hexadecimal represents the least significant four bits of the first byte of the pattern, and so on. As far as the SYNC_PATTERN field is concerned, the IP and ASYNC_CHAR protocols also expect that in each byte the bits to be also reversed. The IP_1 and ASYNC_CHAR_1 protocol do not. For example for the CEV_MASK field (a 32-bit wide mask) 1 is expressed as "00000001", 8 as "00000008" , F1 as "000000f1". For example for the SYNC_PATTERN field, "FAF320" is expressed as "5FCF04" if the protocol is IP or ASYNC_CHAR. Appendix F: ASCII_CHAR PROTOCOLS USER'S GUIDE This appendix provides a short user's guide for the ASCII_CHAR_IP and ASCII_CHAR_RS232 protocols. These protocols handle the transfer of data to OASIS-CC using stream sockets (ASCII_CHAR_IP) or RS232 communication lines. They should be used if: - The data is made of ASCII messages. - The length of each message is variable. - All messages are terminated by the same user-defined ASCII character. There are many situations where this new functionality can be very useful. For example communicating CSTOL statements to an OASIS-CC application is made easier with these two protocols. So is reading data from some laboratory instrumentation. The protocols implementation provides a limited set of functions: - Data can be recored and replayed (via the retrieve function). - Each message can be routed to one or more sub clps or to one or more forward streams. - Each message can be stored in a global variable of the class (field data_class in latest_data table) CHARACTER_STRING. The messages are not actually decomposed by OASIS-CC. This is because the implementation does not make any assumption on the contents of the messages. If the messages need to be decomposed, this can be accomplihed using an equation. 1 - Database Set Up The following paragraphs give an overview of the set up required by the ASCII_CHAR_IP and the ASCII_CHAR_RS232 protocols. 1 - 1 Streams Table 1 - 1 - 1 Primary Stream The primary stream provides the mechanism by which the acquisition of data can be started or stopped. This is controlled by the user via the CSTOL switch on/off or retrieve on/off directives. A return primary stream can be recorded via the record on/off CSTOL directives. STREAM_NAME => name of the stream PROCESSOR => EXTCOMM_SUBSYSTEM LINK_NAME => pointer to a links table record DIRECTION => RETURN_STREAM PROTOCOL => ASCII_CHAR_IP or ASCII_CHAR_RS232 STREAM_TYPE => PRIMARY TIME_OUT => delay between two reads FRAME_LENGTH => maximum size of a message in bits SYNC_PATTERN => The hex equivalent of the character that indicates the end of a message. For example carriage return is represented as 0D All other fields are don't care. In particular the sync_pattern_length is assumed to be 8 bits. 1 - 1 - 2 Secondary stream One secondary stream record is needed per primary stream. The purpose of the secondary stream is to allow the routing of the messages to sub clps or to forward streams and to control the transfer of the messages to a user defined global variable in the latest data table. The routing is controlled by the route/stop routing CSTOL directives. The transfer to the latest_data table is controlled by the switch on/off CSTOL directives. STREAM_NAME => name of the secondary stream PARENT => name of the primary stream STREAM_TYPE => SECONDARY All other fields are don't care 1 - 2 Links table LINK_NAME => as defined in the primary stream record DATA_LINE => port name (i.e./dev/ttyx) for the ASCII_CHAR_RS232 protocol or internet address of the server process sending the data to OASIS-CC when OASIS-CC is a client process (ASCII_CHAR_IP protocol) All other fields are don't care. 1 - 3 Decomposition table As indicated above neither the ASCII_CHAR_RS232 protocol, nor the ASCII_CHAR_IP protocol can decompose incoming messages. However one record is needed in the decomposition table to pass to OASIS-CC the name of the global variable that will receive the messages. ILK => ATOM OFFSET => not used, 0 is Ok SIZE => not used, 0 is Ok EXTERNAL_ELEMENT => external_element name of the global variable that will receive the messages ITEM_NAME => item name of the global variable that will receive the messages. OCCURENCE => not used, 0 is Ok NAME => Name of the secondary stream All other fields are don't care. Note that the global variable pointed to by EXTERNAL_ELEMENT, ITEM_NAME needs to be of the class CHARACTER_STRING. 1 - 4 Latest_Data table Not unlike the IP and the ASYNC_CHAR protocols, the ASCII_CHAR_IP and the ASCII_CHAR_RS232 protocols get some set up information from the latest_data table. 1 - 4 - 1 ASCII_CHAR_IP: Determination of the server/client relation EXTERNAL_ELEMENT => name of the primary stream ITEM_NAME => MODE DATA_CLASS => NUMERIC DN_LOW => 0 (or if this record is not present): OASIS is a client process 1 : OASIS is a server process 1 - 4 - 2 ASCII_CHAR_IP: Socket address definition EXTERNAL_ELEMENT => name of the primary stream ITEM_NAME => SOCKET_ADDRESS DATA_CLASS => NUMERIC DN_LOW => Socket address used in the communciation 1 - 4 - 3 ASCII_CHAR_RS232: RS232 line speed definition EXTERNAL_ELEMENT => name of the primary stream ITEM_NAME => LINE_SPEED DATA_CLASS => NUMERIC DN_LOW => line speed Legal line speed values are (in bps): 75, 110, 150, 134 (for 134.5), 300, 600, 1200,2400, 1800, 2400, 4800, 9600, 19200, 38400. 1 - 4 - 4 ASCII_CHAR_RS232 and ASCII_CHAR_IP: Debug level definition EXTERNAL_ELEMENT => name of the primary stream ITEM_NAME => DEBUG_LEVEL DATA_CLASS => NUMERIC DN_LOW => 0 (or if this record is not present): No debug messages are printed => > 0 some debug messages are printed 1 -4 - 5 ASCII_CHAR_RS232 and ASCII_CHAR_IP: Determination of the transfer of the message termination character EXTERNAL_ELEMENT => name of the primary stream ITEM_NAME => SUPPRESS_DELIMIT DATA_CLASS => NUMERIC DN_LOW => 0, 1, 2 or 3 This global variable controls what OASIS-CC does with the message termination character when routing a message or transfering a message to the latest_data table. NO means that the termination character is removed from the message. YES means it is left in the message. DN_LOW value 0 1 2 3 ROUTE NO NO YES YES TRANSFER NO YES NO YES Appendix G: WHERE TO FIND EACH PROTOCOLS USER'S GUIDE Protocol Name Document name ASYNC_CHAR OASIS-CC Generic Communications User's Guide IP OASIS-CC Generic Communications User's Guide ASYNC_CHAR_1 same set up as ASYNC_CHAR except for the sync pattern (see Appendix E above) IP_1 same set up as IP except for the sync pattern (see Appendix E above) IEEE Release notes for V02.05.09, Appendix E FIFTEEN_53_LR_RT Release notes for V02.05.09, Appendix C FIFTEEN_53_LRS Release notes for V02.05.05, Appendix B (see also the V02.05.08 patche 1 release notes) TEST_4 Release notes for V02.05.08, Appendix E S11W_1 Release notes for V02.05.08, Appendix F ASCII_CHAR_IP Release notes for V02.05.10, Appendix F ASCII_CHAR_RS232 Release notes for V02.05.10, Appendix F