OASIS-CC VERSION V02.05.14(1) RELEASE NOTES TABLE OF CONTENTS 1 Compatibility And Requirements Information 2 OASIS-CC Installation Procedure 2.1 SunOs Version 2.2 Solaris Version 2.3 HP_UX version 3 Upgrading V02.05.13 or V02.05.14(0) Applications to V02.05.14(1) 4 Major New Features Or Code fixes 4.1 User defined alert window (crn 554) 4.2 User access to command and command message buffer (crn 557) 4.3 Frame counter updated (crn 564) 4.4 Alternate time source for message stamping (crn 561) 4.5 Cev and buffered command (crn 559) 4.6 Changes from release 13 patch #1 included 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 When an IP server stream is switched on, OASIS-CC keyboard or procedure input processing can become locked (crn 294) 6.5 Double precision floating point printout may be incorrect (crn 320) 6.6 S11W implementation not available in the SOLARIS version 6.7 CEV may fail if CEV_TIMEOUT is greater than 86400.0 seconds (crn 358) 6.8 Initialization problem with keyed binary bridge (crn 359) 6.9 Apparent memory leak in graph presentation type (crn 337) 6.10 Ask window problem (crn 486) 6.11 Running awb remotely with the SOLARIS version (crn 378) 6.12 OASIS-CC not compiling procedures (crn 409, tbd) 6.13 OASIS-CC loops forever (Sunos version only. crn 497) 6.14 Size limitation for command log and command window (crn 508) 6.15 Incorrect time reported in message log (crn 512) 6.16 X code leaks (SunOs/ TAE 5.3a with Bluestone) (crn tbd) 6.17 res2rfg TAE utility may crash on *_.res resource files (crn 525) 6.18 Leak when displaying panel with DDOs (crn 529) 6.19 Use caution when using remote displays 6.20 OASIS-CC never told when crash occur on a remote X server (crn 529) 6.21 Remote Display issues in HP_UX version (crn 529) 6.22 Exiting a loop with repeat count via a "GOTO" statement (crn 516) 6.23 Duplicate subfield reference in command request not reported (crn 528) 6.24 Reference to non-existing local variable kills language processor (crn 538) 6.25 Sending a non "switch off" statement to an Ip server stream (crn 555) 7 Anomaly Or Enhancement Request Reporting 8 Documentation Set Status 9 Upgrades To The Spectrometer Application Appendix A: BUILDING AN APPLICATION-DEFINED ALERT WINDOW Appendix B: HIGH LEVEL LANGUAGE ACCESS TO COMMAND AND COMMAND MESSAGE BUFFER Appendix C: OASIS TOOLBOX DESCRIPTION Appendix D: THRUPUT MEASUREMENTS AND LOAD SIMULATION Appendix E: ADDITION TO THE EQUATION TOOLBOX Appendix F: RELEASE NOTES FOR 12(4) AND 13(1) OASIS-CC VERSION V02.05.14(1) RELEASE NOTES 03/07/96 These release notes describe version V02.05.14(1) (SparcStation and HP 9000/700 series) of OASIS-CC. It also includes the notes from version V02.05.14(0).A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0514_1. A copy of the notes from previous releases can also be found in the $ODIST/release_notes directory. 1 Compatibility And Requirements Information --------------------------------------------- This release of OASIS-CC has been tested on SparcStation 2, 10, and 20. This release of OASIS-CC has also been tested on a HP 715/100 running HP_UX 9.05 and on a HP 712/80 running HP_UX 10.x. There are 3 different versions: A SunOS 4.1.3 version which requires: X X11R5 (from Bluestone) MOTIF 1.2 (from Bluestone) TAE+ 5.3a (available from Century Computing for a non-NASA project, from GSFC for a NASA project) A SOLARIS 2.3 or 2.4 version which requires: X X11R5 from SUN MOTIF 1.2 from SUN (Motif Developer's Kit) TAE+ 5.3c for SOLARIS (available from Century Computing for a non-NASA project, from GSFC for a NASA project) A HP_UX 9.x and 10.x version which requires: X X11R5 MOTIF 1.2 TAE+ 5.3b for HP (available from Century Computing for a non-NASA project, from GSFC for a NASA project) Notes concerning the SunOs version: (1) It requires the MOTIF developer's kit; (2) 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; Notes concerning the SOLARIS version: (1) It requires a C compiler (OASIS-CC was tested using the Sun C SparCompiler. The make_oasis_app.sh utility requires the Sun C SparCompiler. This utility needs to be updated for use with other compilers such as the GNU C compiler); (2) Release 14 for SOLARIS requires TAE+ 5.3c. It is not compatible with TAE+ 5.3l; Notes concerning the HP_UX distribution: (1) It requires a C compiler (OASIS-CC was tested using the HP_UX C compiler (cc). The make_oasis_app.sh utility requires the HP_UX C compiler. This utility needs to be updated for use with other compilers such as the GNU C compiler); How much memory you need depends on the application. Our experience is that 32 Mbytes is a minimum. Disk space requirements are about 45 Mbytes for all three distributions. Notes on license requirements ----------------------------- TAE+ A TAE+ license is not required for every workstation that the executable image of OASIS-CC runs on. TAE+ needs only to be licensed for the workstation(s) used to develop TAE+ interfaces and to create the executable image. In other words, a TAE+ license is required for each workstation that is used to run the workbench and link the executable image. OASIS-CC A separate license is required for each workstation used to run OASIS-CC. 2 OASIS-CC Installation Procedure ---------------------------------- 2.1 SunOs Version ----------------- Refer to the Unix OASIS-CC V02.05.12 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.14 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.10. This is done to allow users running an old release to convert to this release. If these utilities are not needed, the following files can be deleted from $ODIST/bin: dump_database_v020510 dump_database_v020511 load_database_v020511 report_database_v020511 2.2 SOLARIS Version ------------------- Refer to the Unix OASIS-CC V02.05.12 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.14 in a new directory. ******************************************************************************* * We recommend that you run OASIS-CC in the SOLARIS RT (realtime) scheduling * * class rather than the SOLARIS TS (time-sharing) scheduling class. * ******************************************************************************* ******************************************************************************* * 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 * ******************************************************************************* * ***************************************************************************** * The SOLARIS version of OASIS-CC now expects that the environment variable * * LD_LIBARY_PATH to be defined with the path to the X and the Motif libraries.* * For example on LASP uses the following definition: * * setenv MOTIFHOME /opt/SUNWmotif * * setenv OPENWINHOME /usr/openwin * * setenv LD_LIBRARY_PATH $MOTIFHOME/lib:$OPENWINHOME/lib * ******************************************************************************* * ***************************************************************************** * The SOLARIS version of OASIS-CC expects the X11 include files to be in * * /usr/include/X11. If this is not the case, create a symbolic link from the * * directory containing the X11 include files * * (usually /usr/openwin/include/X11) to /usr/include/X11. * * ***************************************************************************** Note that the Solaris distribution is quite large because $ODIST/bin contains all of the dump_database and the load_database executables since V02.05.11. This is done to allow users running an old release to convert to this release. If these utilities are not needed, the following files can be deleted from $ODIST/bin: dump_database_v020510 dump_database_v020511 load_database_v020511 report_database_v020511 2.3 HP_UX version ----------------- The installation procedure for the HP 9000/700 version is the same as for the SPARC version with the additional steps listed below. Refer to the Unix OASIS-CC V02.05.13 Installation Guide for instructions on how to install the OASIS-CC software from the tar tape. Additional steps to be done for the HP_UX version: After installing the release distribution you need to: (1) Define ODIST (2) execute the make_ldas.sh script This will create 2 files (lda1 and lda2) that are needed to link OASIS-CC on your machine. ******************************************************************************* * We recommend that you run OASIS-CC with a realtime priority rather than * * with a time share priority. (see rtprio(1) in the man pages) * ******************************************************************************* * ***************************************************************************** * The HP_UX version of OASIS-CC expects the environment variable * * LPATH to be defined with the path to the X and the Motif libraries. * * For example on our development system we use the following definition: * * setenv LPATH /usr/lib/Motif1.2:/usr/lib/X11R5:/usr/lib:/lib * ******************************************************************************* * ***************************************************************************** * The HP_UX version of OASIS-CC expects the X11 include files to be in * * /usr/include/X11R5. If this is not the case, create a symbolic link from * * the directory containing the X11 include files to /usr/include/X11R5. * * ***************************************************************************** * ***************************************************************************** * The HP_UX version of OASIS-CC expects the Motif include files to be in * * /usr/include/Motif1.2. If this is not the case, create a symbolic link from * * the directory containing the Motif include files to /usr/include/Motif1.2 * * ***************************************************************************** 3 Upgrading V02.05.13 Applications to V02.05.14 ----------------------------------------------- Applications running under OASIS-CC v020513 are compatible with v020514, except that V020514 expects some additional C routines in $OASIS_USER_CODE/libOasisUser.a (see paragraph 4.2 below). The distribution contains a stubbed library in $ODIST/common_distrib/objects. The stubbed routines source code is provided in $ODIST/common_distrib/objects (files c_compute_equation_stub.c and oasis_cmd_stub.c). 4 Major 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 User Defined Alert Window (crn 554) --------------------------------------- Applications can now design their own alert window. The rules that a user has to follow in developing his/her alert window are described in Appendix A (BUILDING AN APPLICATION-DEFINED ALERT WINDOW). Those rules are necessary to insure that the OASIS-CC code interfaces correctly with a user-defined alert window. If no user-defined alert window is found in $RESOURCE_FILES, OASIS-CC defaults to its own hard-coded alert window. 4.2 User Access to Command and Command Message Buffer (crn 557) --------------------------------------------------------------- The code in this release calls user-provided code when (1) a command has been generated, before the command bit pattern is moved to the command message buffer; (2) a command message buffer has been closed, before the command message is passed to the command pre and post check code and then to the communication subsystem. The specification of these routines is given in Appendix B (HIGH LEVEL LANGUAGE ACCESS TO COMMAND AND COMMAND MESSAGE BUFFER). In addition this release provides a set of tools that can be used in the user-provided code to access the latest_data table. There tools are described in Appendix C (OASIS TOOLBOX DESCRIPTION). 4.3 Frame counter updated (crn 564) ----------------------------------- The receivers for the protocol IP, IP_1, ASYNC_CHAR and ASYNC_CHAR_1 now increment a frame counter at every packet or TDM frame. The frame counter is a global variable whose external_element is EXT_COMM and whose item_name is defined by the FRAME_COUNT_NAME field in the primary stream record. On "switch on" the code verifies that the frame counter exists in latest_data. If it exists, but is not initialized (field DN_EXISTS set to TRUE in the latest_data record), it is set to zero. 4.4 Alternate time source for message stamping (crn 561) -------------------------------------------------------- This release introduces a new special variable call $$TIME_STAMP. This variable can take three values: SYSTEM, USER, RETRIEVED. SYSTEM (the default value) indicates that the time stamping of the messages in the event log is to be done using the system clock. USER indicates that the time stamping of the messages in the event log is to be done using an alternate time stamp. Generally the alternate time stamp is updated by the user via an equation using a new C-callable function named Oasis_CSetAltTime (see Appendix E: ADDITION TO THE EQUATION TOOLBOX). RETRIEVED can be used when retrieving data previously recorded by OASIS. It forces a receiver task to update the alternate time stamp using the time of recording attached to each record in the retrieved file. The latest_data global variable $$GLOBAL $$TIME_STAMP contains a copy of the $$TIME_STAMP Notes: (1) Assume that $$TIME_STAMP is set to USER and that Oasis_CSetAltTime is used to convert a VTCW into a time stamp. Because equations are called at the end of a frame the events that have occured during the frame are stamped with the time stamp generated during the preceding frame. (2) The system does not prevent the setting of the $$TIME_STAMP to RETRIEVED when no data is retrieved or when an equation that updates the time stamp is enabled. (3) If more than one files are simultaneoulsy retrieved setting $$TIME_STAMP to RETRIEVED can lead to a very confusing time stamping of the event log. (4) The alternate time stamp is limited to 20 characters. But only the first non-blank characters on the alternate time stamp string are used. 4.5 Cev and buffered command (crn 559) -------------------------------------- When buffering a series of commands that have "do_cev=true", but "$$cev_mode = off" all commands are sent as desired, but Cev is performed on all but the last command in the buffer. This has been fixed. 4.6 Changes from release 13 patch #1 included --------------------------------------------- This release includes the code changes made to release 13 since release 14(0) was generated. The release notes for 13(1) are included in Appendix F. 5 Change Requests Closed With This Release -------------------------------------------- crn # Title Comment 554 Application defined alert window see 4.1 557 User access to command and command message buffer see 4.2 558 Crash when start of retrieve time > time of record 559 Cev and buffered command see 4.5 561 Alternate time source for message stamping see 4.4 563 Problem with Motif 1.2.4 564 Update of frame counter see 4.3 6 Main Known Problems And Limitations --------------------------------------- 6.1 Filename Length Limitation ------------------------------ In OASIS-CC filenames can be up to 128 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. In some case, the 128 character limit can be 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 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.5 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.6 S11W implementation not available in the SOLARIS version ------------------------------------------------------------ Because of driver problems the s11w code is not functional in the SOLARIS version. This protocol is not supported by the HP_UX version. 6.7 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.8 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.9 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.10 Ask window problem (crn 486) --------------------------------- This is a non fatal problem which is caused by rapid succession of ask windows. Undelayed back to back ASK windows result in the following type of error message in the window from which OASIS-CC was started: X Error of failed request: BadWindow (invalid Window parameter) Major opcode of failed request: 38 (X_QueryPointer) Major opcode of failed request: 0 Resource id in failed request: 0x200820 (e.g) Serial number of failed request:43641 6.11 Running awb remotely with the SOLARIS version (crn 378) ------------------------------------------------------------ You cannot run the awb code delivered with OASIS-CC from a remote workstation if you set the DISPLAY environmental variable using the full node name (such as setenv DISPLAY mirza.colorado.edu:0.0). You need to set DISPLAY using the internet address instead (such as setenv DISPLAY 128.138.137.20:0.). This problem concerns the SOLARIS verion only. 6.12 OASIS-CC not compiling procedures (crn 409, tbd) ----------------------------------------------------- When OASIS-CC compiles a procedure, it creates some temporary files in $OASIS_TMP. Those files are deleted (except for the files generated by the special clps) when OASIS-CC terminates via a CSTOL OFF. The files created by the special clps are not deleted. If OASIS is not terminated via a CSTOL OFF no files are deleted. This can cause problem if and when OASIS-CC (in the same environment) is run with different privileges as it may not have the permission to overwrite the files left by a previous session. 6.13 OASIS-CC loops forever (Sunos version only. crn 497) -------------------------------------------------------- This symptoms of this problem are that while "switching on" a series of streams with no wait between streams, OASIS never comes back and seems to loop forever. This anomaly has been traced to a problem with the Ada compiler used in the SunOs version (because SunOS is a "deadend" operating system, the compiler code is no more upgraded). This is fixed in the Solaris version of the compiler. The problem in the SunOs compiler is that the structure used to store file descriptors is not protected against concurrent access. The occurence of this problem can be reduced by avoiding simulataneous opening of files by OASIS. For example, assume that an application has 2 large return streams that restore their decomposition tree (instead of building them at runtime). The sequence switch on stream_1 ; This opens many files to restore the decomp tree switch on stream_2 ; This also opens many files while the previous ; statement is executed. may create the conditions of the problem. In the sequence switch om stream_1 wait 00:00:20.0 ; wait for stream_1 decomposition tree to be build switch on streams_2 the problem is avoided. 6.14 Size limitation for command log and command window (crn 508) ---------------------------------------------------------------- When a command with many subfields is used, the message generated when the command is built can be truncated (because of the limitation of the message size in the event message log). The same problem exists with the ASCII text displayed in the command window. 6.15 Incorrect time reported in message log (crn 512) ----------------------------------------------------- Due to a bug in the runtime delivered with the Ada compiler, the time reported in the event log of an OASIS-CC application started before midnight the Saturday before the last Sunday of April (!) is off by one hour after midnight (i.e, the time goes from 23:59:59 to 01:00:00). This problem affects all version of OASIS-CC. 6.16 X code leaks (SunOs/TAE+ 5.3a with Bluestone) (crn TBD) ----------------------------------------------------------- Our tests are showing that the SunOs/TAE+ 5.3a version leaks when TAE panels are displayed. We have reproduced the leaks outside of OASIS-CC. They seem to be caused in the Motif code itself. 6.17 res2rfg TAE utility may crash on *_.res resource files (crn 525) -------------------------------------------------------------------- The res2rfg utility crashes when it encounters a string larger than 132 characters. For example this can occur when using the Cstolq macro in awb. A workaround this problem is to use the '\' continuation character to end a line before it reaches a dangerous length. 6.18 Leak when displaying panel with DDOs (crn 529) --------------------------------------------------- There is a leak (which has been traced to Motif and to the Interview code used by TAE) when a panel with a DDO is displayed. This leak has been discovered in the Solaris version. It probably exists in all versions of OASIS-CC. 6.19 Use caution when using remote displays ------------------------------------------- Testing remote displays has shown that problems can occur in a heterogenious environment. For example we found problems when displaying panels with presentation types that have text input from the HP_UX version of OASIS-CC to an X11R4 server running the X MIT code or to a X11R5 server running the X Bluestone code or the X Sun code. Therefore users should carefully test their usage of remote displays before running in an operational environment. 6.20 OASIS-CC never told when crash occur on a remote X server (crn 529) ----------------------------------------------------------------------- Assume that OASIS-CC is displaying on a remote X server and that the workstation on which the remote X server runs crashes. OASIS-CC is made aware of the crash only after a period of time that may be rather long. OASIS-CC itself does not crash, but all X activities (input and output) are stopped until OASIS-CC is made aware of the crash. Same thing happens if the ethernet connection to the remote X server is severed. Note that this is a different situation from the X server being terminated on the remote workstation. 6.21 Remote Display issues in HP_UX version (crn 529) ----------------------------------------------------- Terminating an X server on which OASIS-CC is displaying can cause OASIS-CC to crash. 6.22 Exiting a loop with repeat count via a "GOTO" statement (crn 516) ------------------------------------------------------------------------ If a loop with repeat count is not exited via either the "end loop" or an "escape" statement, the loop counter is not re-initiliazed when loop is re-entered at the "loop" statement. 6.23 Duplicate subfield reference in command request not reported (crn 528) -------------------------------------------------------------------------- Assume the following statement: set telemetry with format 1, format 2 No errors or warnings are printed by Oasis to caution the user that the same subfield is referenced twice in the command request statement. Oasis uses the last value (2 in the example) for the subfield. 6.24 Reference to non-existing local variable kills language processor (crn 538) -------------------------------------------------------------------------------- If in the following statement set telemetry with format $format $format does not exist the clp that processed the command dies. 6.25 Sending a non "switch off" statement to an Ip server stream (crn 555) -------------------------------------------------------------------------- Consider the statements switch on primary_stream; ip server stream switch on secondary_stream; secondary of primary_stream route secondary_stream to another_stream The last statement may result in the following error message: "LE_U Unknown error in communication subsystem Rcvr not accessible" The problem is that a server stream interprets any "switch" statement as a "switch off" statement while it is waiting for a client connection. In the example above the "switch on secondary_stream" statement causes the stream task to terminate, whereas Oasis itself still assumes that the stream task is still running. 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 ---------------------------- none. 9 Upgrades To The Spectrometer Application -------------------------------------------- none. Appendix A: BUILDING AN APPLICATION-DEFINED ALERT WINDOW It is now possible for an application to define its own alert window. To be functional with OASIS-CC this alert window must follow the rules listed below. 1) $RESOURCE_FILES/alert.res The alert panel must be defined in a resource file called 'alert.res'. The file should be located in $RESOURCE_FILES. The panle itself must be called 'alert'. At initialization time Oasis attempts to find this file. If it finds it, then it checks the contents to find a panel named 'alert' by looking for 'alert_t.par' and 'alert_v.par'. If it does not find these, then it uses the default internally hardcoded alert panel. 2) Items necessary for alert.res to be usable. For the alert panel to be functional, and therefore accepted by the OASIS initialization checking routine, it the following conditions must be met: a) It must have an item named "line1" which is a "Color Logger" item (found under the User Contributed Presentation category). This is internally called a "scroller" presentation, so if this is not the case you will get a message saying: Error: 'line1' item exists in '' panel alert, but is not of type 'scroller', using default. Also be aware that this 'scroller' item should have the 'Auto Wrap' detail set ON, otherwise part of the alert message may be truncated. b) It must have either an item named "textin" or two items, one named "yes" and the other named "no". c) If you have an item named "textin" it must be a "Keyin" item (found under the Text Presentation category). This is internally called a "text" presentation. d) If you have either of the items "yes" or "no" they must be "clickable". This means they must be one of the following types: Presentation Type: Internal name: Dynamic Data Objects: "Composite" "compddo" "Discrete Pictures" "discrete" "Mover" "mover" "Rotator" "rotator" "Stretcher" "stretcher" Selection Objects: "Icon" "icon" "Push Button" "button" Text Objects: "Dynamic Text" "dynlabel" "Label" "static" 3) Connections ignored. Be aware that any connections defined for the Alert panel (which are defined in 'alert_m.res' are not considered at all. This means that any other items than the above ones will have no functionality. Appendix B: HIGH LEVEL LANGUAGE ACCESS TO COMMAND AND COMMAND MESSAGE BUFFER 1 DEFINITION OF THE USER PROVIDED CODE The command subsystem code now calls three routines that are to be provided by the application developer. The first routines (Oasis_CCmd) is called whenever a command has been build, prior to the command insertion in a command buffer. This routine can be used to modify the command bit pattern. The second routine (Oasis_CCmdMessage) is called whenever a command message buffer is ready to be passed to the communication susbsystem. At that point the command message buffer is composed of the message header bit pattern, the command(s) bit pattern and the message trailer bit pattern. The third routine (Oasis_CloadMessage) plays the same role as Oasis_CCmdMessage, but for microprocessor load messages. Following are three examples: cstol> turn on telemetry ; Oasis_CCmd is called after the command is built. ; Then Oasis_CCmdMessage is called after the message ; is built cstol > message uvis cstol > execute uvphoto ; Oasis_CCmd is called after the command is built cstol > execute uvgen ; Oasis_CCmd is called after the command is built cstol > send message ; Oasis_CCmdMessage is called after the message is ; built cstol > load uvis at 0 from uvis_main ; Oasis_CLoadMessage is called after ; each load message is built. 2 DEVELOPMENT OF THE USER PROVIDED CODE When linking an application, OASIS-CC expects the user code to be placed the $OASIS_USER_CODE/libOasisUser.a archive library. This is the same archive library in which OASIS-CC expects the user equation code. As for the equation code the script $ODIST/bin/equation_Imakefile.csh can be used to create a makefile to maintain the user code. OASIS-CC is distributed with an archive library that provides stubbed routines. Source code for the stubbed routines can be found in $ODIST/common_distrib/objects. The equation toolbox is described in the release notes for v02.05.10 (Appendix B) and v02.05.11 (Appendix C). 3 ROUTINES DESCRIPTION Routines name Purpose Oasis_CCmd Access to command bit pattern before the command is buffered in a command message buffer. Oasis_CCmdMessage Access to command message bit pattern before the buffer is passed to the communication subsystem for transmission. Oasis_CLoadMessage Access to load message bit pattern before the buffer is passed to the communication subsystem for transmission. 4 MANUAL PAGES FOR THE ROUTINES NAME Oasis_CCmd SYNOPSIS #include #include int Oasis_CCmd(command_descriptor_ptr) COMMAND_DESCRP_PTR command_descriptor_ptr; DESCRIPTION This routine is called after a command has been built. 'command_descriptor_ptr' is a pointer to a command_descriptor structure defined as: typedef struct command_descriptor { char *reference_element; /* top most external element in element hierarchy */ char *external_element; /* external_element */ char *command_name; /* name of the command */ short command_type; /* command type */ void *command_ptr; /* pointer to the command buffer */ int command_size; /* actual command size in bits */ /* set by oasis, updated by the user code */ int max_command_size; /* max # of bits allocated by oasis for the command */ } COMMAND_DESCRP, *COMMAND_DESCRP_PTR; Before calling Oasis_CCmd, OASIS-CC loads 'reference_element', 'external_element', 'command_type' and 'command_name' with values extracted from the commands table and the element_hierarchies table. 'command_type' can take the value CMD_IMMEDIATE or CMD_TIMED. 'command_ptr' points to a buffer containing the command bit-pattern. In this buffer 'command_size' bits have been loaded by OASIS-CC. The buffer contents can be modified by the user code that should update 'command_size' to reflect the new size of the command. The size of the buffer allocated by OASIS-CC for the command is 'max_command_size' bits. The function should return CMD_SUCCESS if successful. Note that the 'char' components of the command_descriptor structure are in uppercase. NAME Oasis_CCmdMessage Oasis_CLoadMessage SYNOPSIS #include #include int Oasis_CCmdMessage(message_descriptor_ptr) MESSAGE_DESCRP_PTR message_descriptor_ptr; int Oasis_CCmdLoad(message_descriptor_ptr) MESSAGE_DESCRP_PTR message_descriptor_ptr; DESCRIPTION Oasis_CCmdMessage is called after a command message has been built. Oasis_CLoadMessage is called after a load message has been built.'message_descriptor_ptr' is a pointer to message_descriptor structure defined as: typedef struct message_descriptor { char *external_element; /* external_element */ int max_message_size; /* max # of bits of the message allocated by oasis*/ int header_size; /* size if the header in bit */ int trailer_size; /* size of the trailer in bit */ short message_type; /* message type */ void *message_ptr; /* pointer to message buffer */ int message_size; /* actual # of bits of the message */ /* set by oasis, updated by user code */ } MESSAGE_DESCRP, *MESSAGE_DESCRP_PTR; Before calling Oasis_CCmd, OASIS-CC loads 'external_element', 'header_size' and 'trailer_size' with values extracted from the command_messages table. 'message_type' can take the value MSG_REALTIME, MGS_DELAYED, MSG_LOAD and MSG_PRORITY. 'message_ptr' points to a buffer containing the message bit-pattern: the message header followed the command(s) and terminated by the message trailer. In the buffer 'message_size' bits have been loaded by OASIS-CC. The buffer contents can be modified by the user code that should update 'message_size' to reflect the new size of the message. The size of the buffer allocated by OASIS-CC for the message is 'max_message_size' bits. The function should return CMD_SUCCESS if successful. Note that the 'char' components of the message_descriptor structure are in uppercase. Appendix C: OASIS TOOLBOX DESCRIPTION The oasis toolbox defines C callable routines that can be used in the user code. It parallels the tools provided in the equation toolbox. However the tools defined in the equation toolbox should excluvely be used to process equations, with the exception of the following routines and utility that can be used outside the processing of equations: Oasis_CReportEvent (Report_Event for the Ada version) and compute_hashkey. The equation toolbox is described in the release notes for v02.05.10 (Appendix B) and v02.05.11 (Appendix C). The toolbox currently includes four routines Routine name Purpose Set the Dn value of a measurement knowing its Oasis_CSetDnHash hash key Set the Dn value of a measurement knowing its Oasis_CSetDn external element and item name Get the Dn value of a measuremenrt knowing its Oasis_CGetDnHash hash key Set the Dn value of a measurement knowing its Oasis_CGetDn external element and item name NAME Oasis_CSetDnHash SYNOPSIS # include # include void Oasis_CSetDnHash(value, hash); oasis_int value; oasis_int hash; DESCRIPTION This routine sets the DN_LOW field of latest_data record whose key is "hash" (see compute_hashkey in the equation toolbox) to the value "value" NAME Oasis_CSetDn SYNOPSIS # include # include void Oasis_CSetDn(value, e_name, i_name); oasis_int value; char *e_name; char *i_name; DESCRIPTION This routine sets the DN_LOW field of latest_data record whose external element name is "e_name" and item name is "i_name" to the value "value" NAME Oasis_CGetDnHash SYNOPSIS # include # include int Oasis_CGetDnHash(value, hash); oasis_int *value; oasis_int hash; DESCRIPTION This routine gets the DN_LOW field of latest_data record whose key is "hash" (see compute_hashkey in the equation toolbox) and returns it in "value". The function returns 1 if the value exists and it its quality field is set to GOOD. It returns 0 otherwise. NAME Oasis_CGetDn SYNOPSIS # include # include int Oasis_CGetDn(value, e_name, i_name); oasis_int *value; char *e_name; char *i_name; DESCRIPTION This routine gets the DN_LOW field of latest_data record whose external element is "e_name" and item name is "i_name" and returns it in "value". The function returns 1 if the value exists and it its quality field is GOOD. It returns 0 otherwise. Appendix D: THRUPUT MEASUREMENTS AND LOAD SIMULATION See release notes for v02.05.13, Appendix B. Appendix E: ADDITION TO THE EQUATION TOOLBOX A new C-callable function is provided to update the alternate time stamp field in OASIS. The alternate time stamp field is a 20-character long string that is used to stamp the messages in the event log. NAME Oasis_CsetAltTime -- update the alternate time stamp field SYNOPSIS void Oasis_CSetAltTime(alternate_time) char *alternate_time DESCRIPTION This function updates the alternate time stamp field in OASIS-CC. The alternate time stamp field is a 20-character long string that can be used to stamp the messages in the event log instead of the system time. Only the first non-blank characters on the alternate time stamp string are used. Appendix F: RELEASE NOTES FOR 12(4) AND 13(1) Release notes for 12(4) and 13(1) 2/19/96 This patch implements crn 560, 562, 565 and 566. It exists for release 12/Solaris, release 13/Solaris and release 13/Sunos/Tae5.3a. It is labeled 12(4) and 13(1). 1 Application Notes ------------------- 1.1 Synchronization problems with pre and post check proc (crn 560) ------------------------------------------------------------------- When a pre or a post check procedure executes a "let cmd has_verified = " statement the value taken by "cmd has_verified" is passed to the command subsystem. It is assumed that the command subsystem is "listening" for the value. In most cases this is true. However, as OASIS-CC does not control how and when its processes are scheduled, there is now way to insure that this true 100% of the time. The patch implements some changes that improve the situation. In addition we recommend that in each pre or post check procedure a "small" wait statement be added (for example "wait 00:00:00.01") at the beginning of the procedure. This forces a rescheduling of the OASIS-CC processes. 1.2 Executing a procedures from a macro (crn 562) ------------------------------------------------ This patch strictly enforces the rule that it is ILLEGAL to start a procedure from a cstol macro. 1.3 Snap function problems (crn 566) ------------------------------------ As indicated in the notes for release 12 (paragraph 4.1), the snap function uses the "OASIS default pixel size". In previous releases this was assumed to be 8*13. It is now 7*11, which seems more adapted with the pixel size most applications use. 2 Change Requests Closed With This Patch ---------------------------------------- crn # Title Comment 560 Synchronization problems with pre and post check proc see above 1.1 562 Executing a procedure from a macro see above 1.2 565 Cmd IS_IS_USE flag left to TRUE 566 Snap function problems see above 1.3