OASIS-CC VERSION V02.05.07 RELEASE NOTES 3/15/93 These release notes describe version V02.05.07 of OASIS-CC. A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0507. A copy of the notes from previous releases can also be found in the $ODIST/release_notes directory. This release only applies to the SunOS version of OASIS-CC. OASIS-CC V02.05.07 implements a new event messages logging code, global variables that not local to a CLP, an updated red/yellow limit warning capability and the capability to close and open record file without data loss. 1 Compatibility Information This release of OASIS-CC has been tested under the following conditions: Sparcstation IPC 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 Note that: (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; and (5) This release of OASIS-CC is not compatible with SOLARIS 2.0 (aka SunOS 5.0), X11R5 or TAE+ 5.1. 2 OASIS-CC Installation Procedure Refer to the Unix OASIS-CC V02.05.07 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 release must install V02.05.07 in a new directory. 3 Upgrading V02.05.06 Applications to V02.05.07 There are changes in the OASIS-CC V02.05.07 code that makes this release incompatible with applications running version V02.05.06. The changes are: (1) The limits table format has been modified (See Appendix A for a description of the new layout of the table and its use); (2) The Event_Messages table is no longer referenced and should be deleted from the applications; (3) The parser has been modified (see Appendix B for a description of extension to the cstol switch statement); (4) The desirability field in the state_conversions table should not be set to null_state_status (the value null_state_status is used by the system). Sites that require the ability to maintain version V02.05.06 or earlier release applications will need new accounts for their associated V02.05.07 applications. The paragraph "Creating OASIS-CC Accounts" in the Unix OASIS-CC V02.05.07 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 a command procedure (v020506to07) that will make a v02.05.06 application compatible with V02.05.07. To upgrade to V02.05.07, perform the following. (1) Log in the application account intended for V02.05.07 development. This account should be populated with V02.05.06 files (the minimum set is listed above). (2) Set up all the environment variables. Make sure that ODIST points to the OASIS-CC V02.05.07 distribution and that TAE points to the TAE+ 5.2 distribution. (3) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v020506to07.csh (5) Re-create your application. To update from a version prior to V02.05.06, you must first upgrade to V02.05.06. Refer to the release notes in $ODIST/release_notes. 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 New Events Logging Code (CRN 256/OSCAR 10) 4.1.1 Scope of the new re-design The events logging subsystem has been re-designed. It now provides the following capabilities: - Standard message format, in the form of a time field followed by an identification field, followed by a message field. - The message field can expand to more than one line. - The messages are logged to file in a printable format. This makes the dump_events utility obsolete. - The name of the file in which the messages are logged is now in the form of Fyy_mmm_hh_mm_ss.event_message. Note that seconds are now part of the filename (this new feature applies to all of the recorded files generated by OASIS-CC). - Individual messages can be routed to specific message windows according the contents of their identification field. - When clp issued message comes from a procedure execution, the procedure name is supplied in the message. 4.1.2 Messages identification codes The following identification codes are used: code origin meaning BI Bridge Information BW Bridge Warning BE Bridge Error CI Command Information CW Command Warning CE Command Error DI Display Information DW Display Warning DE Display Error HI Data_Handling Information HW Data_Handling Warning HE Data_Handling Error HL Data_Handling Limit check HS Data_Handling State check HD Data_Handling Delta check HT Data_Handling Trend check HV Data_Handling Print_On_Change XI Communication Information XW Communication Warning XE Communication Error LI Clp Information LW Clp Warning LE Clp Error LQ Clp Query LT Clp Cstol statement originating from TAE or keyboard LP Clp Cstol statement originating from procedure The Clp originating the message is indicated by a third and a fourth character: Id Origin _U User Clp _C Command Clp _E Equation Clp _T Trigger Clp x (x=01 to 20) Sub Clp # For example, LP01 identifies a statement originating from a procedure running on the sub clp 1. 4.1.3 Routing messages to message window Messages can be routed to a specific message window by matching their identification with the contents of the discriminator field of the display_descriptions table record describing the window. The rules are - If the discriminator field is empty, then all the messages (except the LT, LP and HV messages) are routed to the window. - Otherwise the message identification is matched with the contents of the window discriminator. If a positive match is found, the message is output to the window. - BW, CW, DW, HW, XW and LW discriminators are also matched respectively to BE, CE, DE, HE and LE identifications. For example, if the discriminator field of a message window contains HSHLHD, then messages with an identification of HS or HL or HD will be output to the window. If the discriminator field contains LI01HD, then messages with an identification of LI1 or HD will be output to the window. 4.2 New RED/YELLOW Warning Capability (CRN 255/OSCAR 14) This new implementation allows the user to be warned every time a measurement is out of limits (either yellow or red) and varies by at least a given value. This is controlled by two new fields in the limits table (MSG_DELTA_RED and MSG_DELTA_YELLOW. See Appendix A). ***************************************************************** * Note that this feature increases the processing load when a * * measurement out of limits, even if the measurement value has * * not changed. In this case the processing load is about the * * same as the processing load for a measurement whose value has * * changed. * ***************************************************************** 4.3 $$LIMITS_MODE, $$STATES_MODE and $$GBL_COMMAND_MODE Global Variable (CRN 254/OSCAR 15) Three new special variables have been added: $$LIMITS_MODE, $$STATES_MODE and $$GBL_COMMAND_MODE. Whereas regular special variables, such as $$COMMAND_MODE, are local to a CLP, these three new special variables are shared by all OASIS-CC subsystems. They also update predefined latest_data table entries (and thus can be displayed on a panel). Note that the predefined latest_data entries are automatically inserted by OASIS-CC when OASIS-CC is started or after a reset on the table. Be careful not to delete via a CSTOL delete statement the pre-defined record, so as not to produce error messages every time a new value is assigned to one of the new special variables. $$LIMITS_MODE This variable can take the values OFF, BOTH, HILO or DELTA. When OFF, no HILO checking or DELTA checking is performed. When HILO, only HILO checking is performed (as controlled for each measurement by the its HILO_ENABLED field in the latest_data table). When DELTA, only DELTA checking is performed (as controlled for each measurement by the DELTA_ENABLED field). When BOTH, both HILO and DELTA checking are performed (as controlled for each measurement by the HILO_ENABLED and DELTA_ENABLED fields). The latest_data entry $$GLOBAL $$LIMITS_MODE is associated with the $$LIMITS_MODE special variable. $$STATES_MODE This variable can take the value OFF, BOTH, DESIRABILITY or CHANGE. When OFF, no state checking is performed. When DESIRABILITY, only DESIRABILITY checking is performed (as controlled for each measurement by the its STATE_CHECK_CLASS field in the latest_data table). When CHANGE, only CHANGE checking is performed (as controlled for each measurement by the STATE_CHECK_CLASS field). When BOTH, both DESIRABILITY and CHANGE checking are performed (as controlled for each measurement by the STATE_CHECK_CLASS field). The latest_data entry $$GLOBAL $$STATES_MODE is associated with the $$STATES_MODE special variable. $$GBL_COMMAND_MODE This variable can take the value ISSUE or NOISSUE. When ISSUE, the issuing of commands is controlled, in each CLP, by the $$COMMAND_MODE special variable (each CLP has its own copy of this variable). When NOISSUE, no command can be issued by OASIS. The latest_data entry $$GLOBAL $$COMMAND_MODE is associated with the $$GBL_COMMAND_MODE special variable. 4.4 User Not Warned When State Desirability Goes From BAD To GOOD (CRN 266) Whereas in previous releases a message was printed only when the desirability of a measurement changed from GOOD to BAD, a message is now printed when the desirability changes. Note that with this release a desirability of NULL_STATE_STATUS should never be defined by the user in the state_conversions table. This value is used by the system only. Note that the default value for the desirability field in the state_conversions table has been changed from NULL_STATE_STATUS to GOOD. 4.5 No Loss Of Data Or Messages When Closing and Reopening A Record File (CRN 271/OSCAR 41) A new CSTOL statement has been added to control the closure and the immediate re-opening of data and messages record files. This new feature allows record files to closed and re-opened without loss of data or messages. Appendix B describes the new CSTOL statement. Note that this new capability does not currently apply to bridge files. 4.6 Scrolling Command_Window (CRN 269/OSCAR 12) The command_window is no longer cleared when a new command message is created. The user can now scroll through the window to verify the contents of previously defined command messages. 4.7 Stack Space Increased For Receiver/Transmitter Tasks (CRN 274) 4.8 Old Ip and Async_character code (no CRN) The old Ip and Async_Char code (respectively accessible since v02.05.05 via the test_1 and test_2 protocols) has been stubbed. 5 Change Requests Closed With This Release Change Requests Number: 241, 254, 255, 256, 260, 264, 266, 267, 269, 271 and 274 6 Main Known Problems And Limitations 6.1 Filename Length Limitation In OASIS-CC filenames can be up to 60 characters long. In the SunOS version, 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 name 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 packet. 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 that the larger of the packets. The larger the frame_length value, the greater the time_out value can be, 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 stream that uses 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. 6.5 OASIS-CC Terminates With X Error (CRN 235) This problem has been noted while doing very long formal tests of OASIS-CC V02.05.05, with data being displayed at high rate. After several hours of testing OASIS-CC terminates with a X error. 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 New Documentation Set The following documents are included in this release: (a) OASIS-CC Installation Guide V020507 - Unix Version (b) OASIS-CC System Managers Guide This document is rewritten to reflect the current functionality of OASIS-CC. Previously, the System Manager's guide used a hypothetical camera application to demonstrate the tailoring of the OASIS database. The new document presents the Spectrometer application - an OASIS-CC application delivered with each distribution that controls a data generator program that is also delivered (see Section 9). Chapter 7 of the System Managers Guide (The Bridge Subsystem) is the only chapter not rewritten. It is still valid, however it does not address the Spectrometer application. When the bridge implementation is revisited in the near future, this chapter will be updated. (c) OASIS-CC CSTOL Reference Guide (d) OASIS-CC Database Guide (e) Spectrometer Data Generator Reference Manual This document desribes the telemetry and command formats and the operations of the spectrometer data generator program. (f) OASIS-CC Application Environment Reference Manual - Unix version (new) This document decribes the steps required to: 1- define an OASIS-CC application environment 2- Populate an environment with the Starter database 3- Compile and link TAE+ interfaces with OASIS-CC 4- Install the Spectrometer application for demonstrations and reference. This information was previously supplied in the Application Developers User's Guide, which is now obsolete. (g) Generic Communications User's Guide (To be supplied in a near future) (h) The OASIS-CC Application Developers Quick Reference Manual (To be supplied in the near future) 9 The Starter and Spectrometer Applications As in previous releases, OASIS-CC comes with a Starter application that can be used as a starting point for any application. It contains the minimum database information and an initial interface to allow OASIS-CC to be linked and run immediately. A slight modification is made to the starter application and the tools used to install it: A new subdirectory called 'icons' is created. It's intended to house the TAE+ graphics files used by DDOs. The environment variable OASIS_ICONS points to this subdirectory, and should be used in the graphics filename specified in the workbench. The subdirectory is created, and the environment variable defined, however their use are optional. OASIS-CC is now delivered with a ready-to-run application tailored to support a data generator program that is also provided. The data generator simulates the workings of a spectrometer. The OASIS-CC System Managers Guide is rewritten to reference the Spectrometer application database tables. The application is intended as a demonstration tool, as well as a reference for application developers. The data generator program is executed by typing: $ODIST/bin/spectrometer The steps required to install the OASIS-CC Spectrometer application are listed in Chapter 5 of the Application Environment Reference Manual. A tour through the application is presented in Chapter 3 of the OASIS-CC System Manager's Guide. Appendix A This Appendix describes the layout changes of the limits table. Three new fields (called ENTRY_VALUE, MSG_DELTA_RED and MSG_DELTA_YELLOW) have been added after YELLOW_LOW field. The rest of the table is unchanged. ENTRY_VALUE This field is updated by the system. It is used to store the value of the measurement when a read or a yellow message is issued. NON KEY Protection class: SYSTEM Data type: FLOAT Default value: 0.0 MGS_DELTA_RED If the measurement is either red high or red low, and has varied by at least MSG_DELTA_RED since the last red warning message was issued, a new red warning message is issued. NON KEY Protection class: DB_MANAGER Data type: FLOAT Default value: FLOAT'last (about 3.4028e+38) MGS_DELTA_RED If the measurement is either yellow high or yellow low , and has varied by at least MSG_DELTA_YELLOW since the last yellow warning message was issued, a new yellow warning message is issued. NON KEY Protection class: DB_MANAGER Data type: FLOAT Default value: FLOAT'last (about 3.4028e+38) Appendix B The CSTOL switch statement has been updated to take the attribute RECORDING. The new updated syntax is: Format SWITCH RECORDING OF data_stream_name | messages | all Arguments data_stream_name: Name of the stream to which the statement is to be applied Notes (1) SWITCH RECORDING OF data_stream_name forces the closing and the re-opening without data loss of the record file of the indicated stream. (2) SWITCH RECORDING MESSAGES forces the closing and the re-opening without message loss of the event message log file. (3) SWITCH RECORDING OF ALL forces the closing and the re-opening without message or data loss of all opened record files. (4) SWITCH RECORDING does not apply to BRIDGE recorded stream. This is a limitation in the current release, which will be removed in a near future. Appendix C THRUPUT MEASUREMENTS OASIS-CC thruput was measured under the following conditions: Computer : Sparctation 2, 32 Mbyte of main memory SunOs : 4.1.3 OASIS-CC : - Alpha release of v02.05.07. 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 verifies the sync pattern of each packet Simulator: - Packet size set to 128 bytes - Running on a remote workstation 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/s 16kbps 2048 1984 off 42 % 16/s 16kbps 2048 1984 on 50 % 24/s 24kbps 0 n/a n/a << 1 % 24/s 24kbps 3072 0 n/a 25 % 24/s 24kbps 3072 240 on 30 % 24/s 24kbps 3072 480 on 33 % 24/s 24kbps 3072 1200 on 48 % 32/s 32kbps 0 n/a n/a << 1 % 32/s 32kbps 4096 0 n/a 32 % 32/s 32kbps 4096 320 on 40 % 32/s 32kbps 4096 640 on 45 % For all measurement, the primary stream was set up with a frame_length of 4096 and a time_out of 0.05.