OASIS-CC VERSION V02.05.11(1) RELEASE NOTES TABLE OF CONTENTS 1 Compatibility Information 2 OASIS-CC Installation Procedure 3 Upgrading V02.05.10 to V02.05.11 4 Major New Features Or Code Fixes (Including Patches 10(1) and 10(2)) 4.1 RUN Directive Accepts Parameters (CRN 386, OSCAR 53) 4.2 New CHECK Directive (CRN 385) 4.3 Hexadecimal Number Displayed/Entered as 32-bit Unsigned Integer (CRN 366) 4.4 Echo of Command Message Contents (CRN 384) 4.5 WRITE Directive Output Can Be Redirected (CRN 375) 4.6 IP And ASYNC_CHAR Allow Packet Id Field Up To 64 Bits Long (CRN 377) 4.7 Modal Limit Support (OSCAR 19, CRN 418) 4.8 Database Checkpointing (OSCAR 60, CRN 413) 4.9 Global Procedure Control (CRN 363) 4.10 Procedures Halt On Red Limits (CRN 417) 4.11 Filename Length And CSTOL Statement Length (CRN 431) 4.12 Modification To IEEE Setup (CRNs 390, 438) 4.13 Maximum Command Message Length Increased (CRN 398) 4.14 Uppercase Are Allowed In Pathname (CRN 414) 4.15 Protection Changed For Some Fields In Display Definitions (CRN 432) 4.16 Polling Frequency Fixed in IP and ASYNC_CHAR (CRN 424) 4.17 New Commands Verb (CRN 436) 4.18 New Task Scheduling Algorithm (CRN 390) 4.19 Remote Displays Mostly Working Under TAE 5.3 (SOLARIS only) (CRN 449) 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) 6.13 Memory fragmentation (CRN 433, CRN 314) 7 Anomaly Or Enhancement Request Reporting 8 Documentation Set Status 9 Upgrades To The Spectrometer Application Appendix A: DATABASE TABLE UPDATES Appendix B: CSTOL LANGUAGE UPDATES Appendix C: HIGH LEVEL LANGUAGE EQUATION PROCESSOR APPLICATION DEVELOPER'S GUIDE ADDITIONS AND CHANGES Appendix D: THRUPUT MEASUREMENTS Appendix E: SOLARIS VERSION STATUS Appendix F: SYNC PATTERN, BLOCK ID, ETC... (NEW VERSION) Appendix G: WHERE TO FIND EACH PROTOCOL USER'GUIDES (NEW VERSION) Appendix H: NOTE ON SCHEDULABILITY OF ADA TASKS. OASIS-CC VERSION V02.05.11(1) RELEASE NOTES These release notes describe version V02.05.11 of OASIS-CC. A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0511. A copy of the notes from previous releases can also be found in the $ODIST/release_notes directory. This release comes in 3 flavors: a SunOs 4.1.x version using TAE+ 5.2, a Sunos 4.1.x version using TAE+ 5.3 and a SOLARIS 2.3 version using TAE+ 5.3. 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.3 X MIT X11R4 with fixes 1 to 18 MOTIF 1.1.4 TAE+ 5.2 and 5.3 Sparcstation 2 SOLARIS 2.3 X X11R5 from SUN MOTIF 1.2 from SUN TAE+ 5.3 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). 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 dump_database_v020508 dump_database_v020509 load_database_v020505 load_database_v020506 load_database_v020507 load_dataabse_v020508 load_dataabse_v020509 load_dataabse_v020510 SOLARIS Distributions --------------------- Refer to the current Unix 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. * ******************************************************************************* ******************************************************************************* * 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's development, we use the following definition: * * setenv MOTIFHOME /opt/SUNWmotif * * setenv OPENWINHOME /usr/openwin * * setenv LD_LIBRARY_PATH $MOTIFHOME/lib:$OPENWINHOME/lib * ******************************************************************************* 3 Upgrading V02.05.10 Applications to V02.05.11 ------------------------------------------------ Upgrading Under The Same Operating System ----------------------------------------- There are changes in the OASIS-CC V02.05.11 code that makes this release incompatible with applications running version V02.05.10. The changes are: (1) the parser has been upgraded; (2) the size of some database table fields has changed; (3) the specification of the c_compute_equation routine has been updated. Also this release uses a new environment variable called OASIS_CHECKPOINT. This variable should point to the directory where OASIS-CC will checkpoint individual tables (see paragraph 4.8). Sites that require the ability to maintain version V02.05.10 or earlier release applications will need new accounts for their associated V02.05.11 applications. The paragraph "Creating OASIS-CC Accounts" in the Unix OASIS-CC 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 (v0205010to11.csh) that will make a V02.05.10 compatible with V02.05.11. To upgrade to V02.05.11, perform the following: (1) Log in the application account intended for V02.05.11 development. This account should be populated with V02.05.10 (the minimum set is listed above). (2) Set up all the environment variables (including OASIS_CHECKPOINT). Make sure that ODIST points to the OASIS-CC V02.05.11 distribution and that TAE points to the TAE+ distribution. (3) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v0205010to11.csh *********************8********************************************************** * Users of V020510(osc) should execute $ODIST/bin/v020510oscto11.csh instead * ******************************************************************************** (5) Re-create your application. To update from a version prior to V02.05.10, you must first upgrade to V02.05.10. Refer to the release notes in $ODIST/release_notes. NOTE: If you populate your command database via CSTOL procedures, you need to update all insert or update statements for the following tables: streams The ID_VALUE field in the streams table needs to be updated (see Appendix F). The change in the ID_VALUE field can be accomplished by swapping each byte in the ID_VALUE. For example ID_VALUE length was should be 8 bits aa aa 16 bits aabb bbaa 24 bits aabbcc ccbbaa 32 bits aabbccdd ddccbbaa (This does not apply to v020510(osc) users). Note also that the specification of the c_compute_equation routine has been updated (see Appendix C). Moving From SunOs to Solaris ---------------------------- The distribution tape contains one command procedure (v020510sunosto10.csh) that will make a V02.05.10/SunOs application compatible with V02.05.11 under SOLARIS. To upgrade to V02.05.11, perform the following: (1) Using the v02.05.10 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.11 development. This account should be populated with V02.05.10 files (the minimum set is listed above). (3) Set up all the environment variables (including OASIS_CHECKPOINT). Make sure that ODIST points to the OASIS-CC V02.05.11 distribution and that TAE points to the TAE+ distribution. (4) Transfer all the .dump files created in step 1 to the $OASIS_DATABASE directory on the SOLARIS machine. (5) Reload all the tables using LOAD_DATABASE_V020510. (6) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v020510sunosto11.csh (7) Re-create your application. NOTE: If you populate your command database via CSTOL procedures, you need to update all insert or update statements for the following tables: streams The ID_VALUE field in the streams table needs to be updated (see Appendix F). The change in the ID_VALUE field can be accomplished by swapping each byte in the ID_VALUE. For example ID_VALUE length was should be 8 bits aa aa 16 bits aabb bbaa 24 bits aabbcc ccbbaa 32 bits aabbccdd ddccbbaa Note also that the specification of the c_compute_equation routine has been updated (see Appendix C). 4 Major New Features Or Code Fixes (Including Patches 10(1) and 10(2)) ----------------------------------------------------------------------- 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 RUN Directive Accepts Parameters (CRN 386, OSCAR 53) -------------------------------------------------------- Parameters can now be passed to the RUN directive. The new RUN syntax is fully described in Appendix B. 4.1.1 New syntax The new syntax reads as follows: Format RUN program-name [parameter_list] Arguments program_name (identifier) : The utility to start. The name must appear in the Utility_Tasks database table. parameter_list: Values to pass to the utility program started by the run directive. The list can contain character strings, local variables and/or global variables, separated by commas. All parameters in local or global variables are translated into string data. 4.1.2 Interpretation of the parameters. In the rest of this paragraph we will assume that the task_file_name of the utility_tasks table record pointed by program_name contains "le_program". 4.1.2.1 Character string. The string is passed. For example: RUN program_name "-i 2000 -l TEST" will execute the following command le_program -i 2000 -l TEST 4.1.2.2 Local variable which is a string. The string is passed. For example: declare variable $le_text = "-k 'this is a test'" RUN program_name "-i 2000 -l TEST", $le_text will execute the following command le_program -2000 -l TEST -k "this is a test" (note the substitution of ' by "). 4.1.2.3 Local variable which is a state. The string corresponding to the state is passed. For example: declare variable $le_state = ON ON OFF MAY_BE RUN program_name "-i 2000 -l TEST -g", $le_state will execute the following command le_program -i 2000 -l TEST -g ON 4.1.2.4 Local variable which is a integer or a float value. The string corresponding (i.e., conversion of) to the value is passed. For example: declare variable $le_integer_value = 1 RUN program_name "-i 2000 -l TEST -h", $le_integer_value will execute the following command le_program -i 2000 -l TEST -h 1 For example: declare variable $le_float_value =0.15e+02 RUN program_name "-i 2000 -l TEST -h", $le_float_value will execute the following command le_program -i 2000 -l TEST -h 1.5000000000000E+01 (note that units are not passed to the program) 4.1.2.5 Global variable which is a character string. Same as 4.1.2.2 4.1.2.6 Global variable which is a state. Same as 4.1.2.3 4.1.2.7 Global variable which is numeric. The string corresponding to the eu value is passed. As in 4.1.2.4, the unit is not passed. NOTES: (a) The number of effective parameters is limited to 23. Note that "-i 2000 -l TEST" counts for 4 parameters. (b) It is possible to enter something like RUN c_shell "tar cvhf /dev/rst0 ." with c_shell pointing to a utility_tasks record with a blanked task_file_name field. This will execute tar cvhf /dev/rst0 . (c) New event message identification codes have been defined: UI, UW and UE for messages generated by OASIS user communications (UCOMM) subsystem. (d) The maximum length of a parameter list is 256 characters (including the name of the program to be executed) and individual parameter cannot exceed 128 characters. (e) The maximum number of parameters is 23. There is a bug in the SunOS version where if this number is exceeded OASIS-CC "thinks" that the task is active. No other task can then be started. (CRN 446) 4.2 New CHECK Directive (CRN 385) --------------------------------- The main purposes of the CHECK directive are: (1) To allow the one time comparison of a measurement value against user-provided limit values and to output the comparison results in the event messages log. (2) To output the measurement name along with the measurement value; The full syntax of the CHECK directive is described in Appendix B. Following is an overview of the CHECK directive. CSTOL> CHECK "This is a test:", platform position vs 10.0 deg : 20.0 deg, & yaw angle vs 90.0 deg : 180.0 deg, " and another test:", & power state vs off : , "and", hvps state This statement will: (1) compare platform position against 10.0 deg and 20.0 deg (2) compare yaw angle against 90.0 deg and 180.0 deg. (3) compare power state vs the state off. (4) output in the event log. This is a test: platform position = 100.0 deg yaw angle = 120.0 deg and another test: power state = OFF and hvps state = ON When a measurement is outside the value against which it is checked, then its output is colored in RED (for example "platform position = 100.0 deg" is colored in RED). The Id of the message is HI when all measurements checked Ok and HC when at least one measurements didn't check. When at least one measurement does not check, the procedure running (if any) on the clp from which the CHECK directive has been issued is blocked. The CHECK statement can be seen at as some kind of WRITE statement. However it is more limited in its scope: WRITE STATEMENT CHECK STATEMENT Output string yes yes Output global variable value yes yes Output local variable value yes yes Output special variable value yes no** Output expression result yes no* One time limit checking no yes Output global variable name no yes Output local variable name no yes *: It is possible to define a value against which a measurement is to be checked using an arithmetic expression. **: Local variables, special variables and global variables can be part of an arithmetic expression that define a value against which a measurement is to be checked. 4.3 Hexadecimal Number Displayed/Entered as 32-bit Unsigned Integer (CRN 366) ----------------------------------------------------------------------------- When a number is entered using the X# prefix or displayed using an X format, it is now considered as a 32-bit unsigned integer. 4.4 Echo of Command Message Contents (CRN 384) ---------------------------------------------- With this release it is now possible to record individual commands hexadecimal pattern and/or command message hexadecimal pattern. The recording is done via the event message log. This is controlled by a new system-wide special variable called $$COMMAND_ECHO. This variable can take the following values: OFF (no command or command message hexadecimal patterns are echoed in the event message log). CMD (only command hexadecimal patterns are echoed in the event message log). MSG (only command message hexadecimal patterns are echoed in the event message log). BOTH (command and command message hexadecimal patterns are echoed in the event message log). Like other system wide special variables, a copy of the variable value is maintained in the latest_data table under the name $$GLOBAL $$COMMAND_ECHO. The message identification used are CDxx (for the command echo) and CMxx (for command message echo), where xx can take the values: _U if the commands where requested from the user clp _T if the commands where requested from the trigger clp 01 to 20 if the commands where requested from subclp 1 to 20 Like HV, LUxx or LTxx messages, CDxx and CMxx messages are written to a message window when and only when the message window discriminator specifies their identifications. Commands hexadecimal patterns or command messages hexadecimal patterns are output 200 bits maximum per event message. Therefore a command or a command message echo can span multiple messages. As echoes from several sources (such as the user clp and a sub clp) can be intermixed, the xx extension of the CD or CM identification can be used to reconstruct individual commands or command messages. Note that command messages of the type LOAD are never echoed. 4.5 WRITE Directive Output Can Be Redirected (CRN 375) ------------------------------------------------------- The WRITE directive functionality has been upgraded to allow the user to specify the message identification code to use with the event message generated by the directive. With this feature, a user can now direct the same message to several window with different discriminators. If the first character of the event message generated by the execution of a WRITE directive is a "@", the next 32 characters (or up to the first blank character) are considered as message identification codes. The event message is then duplicated for each of the identification codes, in addition to the regular LIxx code. The parsing of the identification code field is done as follows: - No checking is done on the validity of the identification code (user can supply any characters in an identification code. However the event messages processor "understands" only alphabetical character). - Identification codes are assumed to be 2 characters long, except for the codes starting with L, CM or CD which are assumed to be 4 characters This is to be compatible with the identification codes generated by the OASIS-CC code (CM and CD are new codes. See paragraph 4.4. Example: Let's assume the following write statement entered at the keyboard: WRITE "@CEHVCM_U This is a test" The event message "This is a test" will be emitted 4 times with the following message identification codes: - LI_U (default for write from the user clp) - CE - HV _ CM_U 4.6 IP and ASYNC_CHAR Allow Packet Id Field Up To 64 Bits Long (CRN 377) ------------------------------------------------------------------------ When using IP or ASYNC_CHAR protocol, the packet identification field can now be up to 64 bits long. A full description of how to enter the ID_VALUE field in the streams table is given in Appendix F of the release notes. 4.7 Modal Limit Support (OSCAR 19, CRN 418) ------------------------------------------- This release expands the equation toolbox introduced in release 10, to allow the user to update to (1) disable/enable limit checking at the measurement level; (2) disable/enable state checking at the measurement level; (3) modify the limit values against which a measurement is checked; and (4) modify the desirability of a state for a measurement. The new procedures are described in detail in Appendix C. ******************************************************************************** * Note that the specifications of compute_equation and c_compute_equation * * have changed * ******************************************************************************** 4.8 Database Checkpointing (OSCAR 60, CRN 413) ---------------------------------------------- This release introduces a database checkpointing capability that covers two basic requirements: (a) The need to be able to save the current state of all the database tables and to be able to restart OASIS-CC from the saved files. (b) Several users have the requirement to save in a non-intrusive way the contents of some database tables (mostly the latest_data table and the limits table), so as to collect from time to time an image of the state of the system. Some users plan to use a bridge to provide this function. Other users plan to use the report directive to dump part of some tables. However this last method is very intrusive when it is used while realtime activities are taking place: the table that is reported is locked for a long period of time and the report function requires some amount of virtual memory. This method is also limited by the query capability of the CSTOL language. With the possibility of saving the state of individual tables, the user could then read back the tables using OASIS-CC as an offline tool or using some offline utilities to create his/her own reports. This release introduces a new CSTOL directive (CHECKPOINT) that can take two forms. The first version of the CHECKPOINT directive as the follwoing syntax: CHECKPOINT all TO name This form of the directive dumps all the database tables into the directory pointed by the environment variable $NAME (note the uppercase). OASIS-CC can be restarted from the saved tables by re-defining $OASIS_DATABASE to be $NAME. Note that in this form of the directive, the streams table and the latest_data table are examined to make sure that they are in a state from which OASIS-CC can be safely restarted: - No latest_data record with route_to_bridge /= NEVER and route_to_display /= NEVER - No streams table record where stream_is_on = TRUE and stream_type = PRIMARY - No streams table record where record_is_on = TRUE and processor = BUS_SUBSYSTEM If one of the tests above fails, an error message is printed and the directive execution is terminated. The other form of the CHECKPOINT directive is: CHECKPOINT table_name where selection-expression This form of the directive dumps in the .dat format the table "table_name". The dump is done in the directory pointed by $OASIS_CHECKPOINT to a file named Fyy_mmm_dd_mm_ss.table_name. This form of the CHECKPOINT directive is far less intrusive than the report directive. For example we have conducted tests on a SparcStation LX, with 2 16 kbps streams, 2200 atoms decomposed per second and were able to checkpoint the latest_data table and the limits table with no degradation of the performance. We have revived an old offline utility called report_database that can be used to report (in the report format) the files created by the CHECKPOINT directive. This utility is marked unreleased (as it's a little crude in it's user interface), but has been tested and may be very useful. It is included in the distribution. the report_database utility expects the table files in $OASIS_DATABASE, with the regular table_name.dat filename. The reports are created in $OASIS_REPORT, under the filename table_name.report. 4.9 Global Procedure Control (CRN 363) -------------------------------------- In OASIS-CC the variables $$LOG_INPUT, $$STEP_INTERVAL and $$STEP_MODE are local to a procedure. This release of OASIS-CC introduces a three new special variables ($$CLP_LOG_INPUT, $$CLP_STP_INTERVAL and $$CLP_STEP_MODE) that are local to each clp (i.e., each clp has its own copy of these variables). They can take the same values and have the same effect than respectively $$LOG_INPUT, $$STEP_INTERVAL and $$STEP_MODE. They control, at the clp level, the execution of procedures. When a procedure starts, it inherits the values of $$CLP_LOG_INPUT, $$CLP_STP_INTERVAL and $$CLP_STEP_MODE at the time of the execution of the START statement. If the procedures defines $$LOG_INPUT, $$STEP_INTERVAL or $$STEP_MODE, then the values of $$CLP_LOG_INPUT, $$CLP_STP_INTERVAL or $$CLP_STEP_MODE at the start of the procedure are overriden by the local value. That is to say that local control supersedes global control. Note: Changing the values of the new $$CLP_LOG_INPUT, $$CLP_STP_INTERVAL and $$CLP_STEP_MODE variables will not change the execution characteristics of procedure that is active. As indicated above, they are used when the start directive is executed. At startup time the new variables are initialized as follows: $$CLP_LOG_INPUT $$CLP_STP_INTERVAL $$CLP_STEP_MODE User clp YES ::0.0 GO Equa. clp NO ::0.0 GO Cmd. clp NO ::0.0 GO Trig. clp YES ::0.0 GO Sub clp YES ::0.0 GO ******************************************************************************* * Note on the interpretation of $$CLP_LOG_INPUT = NO * * * * When $$CLP_LOG_INPUT = NO in the command clp or in the equation clp, these * * clps run totally silently. Even the statement "START procedure name" is * * not echoed in the event log. * ******************************************************************************* ******************************************************************************* * Note the spelling of $$CLP_STP_INTERVAL. * ******************************************************************************* 4.10 Procedures Halt On Red Limits (CRN 417) -------------------------------------------- This release introduces a user-selectable capability to limits/states monitoring to have a failed limit check cause suspension of all executing procedures A special variable is defined ($$LIMITS_WAIT) that is a system wide variable. This variable can take the value ON or OFF. When set to ON, if a measurement goes from "green" or "yellow" to "red" (or from a good state to a bad state), the procedures that are executing on (1) the user clp and; (2) all the sub clps are halted. Procedures executing on (1) the equation clp; (2) the trigger clp and (3) the command clp are NOT halted. Like all system wide special variables, a copy of the variable is maintained in the latest_data table (in $$GLOBAL $$LIMITS_WAIT). The initial value of $$LIMITS_WAIT is FALSE. Note that halting of a clp procedure will fail if this clp has the ASK window up when the limits or states alarm is raised. 4.11 Filename Length And CSTOL Statement Length (CRN 431) --------------------------------------------------------- Filenames (including the expansion of the environment variable) are now limited to 128 characters (vs 60 characters). CSTOL statements are limited to 800 characters (vs 400 characters). Note that if a procedure contains a statement more than 800 characters long, when the procedure is compiled and executed, the procedure processing code crashes and cannot be restarted (CRN 447). 4.12 Modification To IEEE setup (CRNs 390, 438) ------------------------------------------------ (a) Automatic device sampling when SRQ is set In autopolling mode, OASIS-CC automatically executes a sample command on a device if (a) The device has asserted the SRQ line; and (b) No decomposition of the device status byte is defined. (b) Debug_Level Users can now control the output of some event messages generated by the IEEE task (mainly in relation with OASIS-CC finding that the srq line has been asserted). 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 (c) Semantic of the route statement In this release the IEEE code provides the capability to route a secondary stream according to number of bytes that were read. Usually OASIS-CC uses the secondary stream definition in the streams table (offset and frame_length) to define what is to be routed. The new capability is used if and when the frame_length in the streams table record defining the secondary stream is set to 0. 4.13 Maximum Command Message Length Increased (CRN 398) -------------------------------------------------------- The maximun command message size has been increased to 524228 bits (from 65000 bits). 4.14 Uppercase Are Allowed In Pathname (CRN 414) ------------------------------------------------ Pathnames with uppercase characters are now interpreted correctly by OASIS-CC. In previous releases OASIS-CC was lowercasing the pathname. There are however exceptions: (a) When strings are inserted in a database record via the query language (or via the load_database utility) they are uppercased. Therefore the case sensitive information is lost. Example: The TEST_4 protocol requires that the name of the file to be processed be stored in a latest_data record named "stream_name" (external_element) filename (item_name). If the record is fully defined via an insert statement like insert latest_data external_element = stream_name, item_name = filename, & data_class=character_string, char_string="/mirza5/OasisTest/test.dat" /MIRZA5/OASISTEST/TEST.DAT is stored. The workaround is to use the let processor to store correctly the filename. (b) The task_file_name field in the utility_tasks table has the same problem as it has to be inserted using the query language (or the load_database utility). The work around is to use an environment variable in the filename. When the environment variable is expanded it is not uppercased (see release notes for release 9, paragraph 4.12) 4.15 Protection Changed For Some Fields In Display_Definitions (CRN 432) ------------------------------------------------------------------------ The protection of the following fields on the display_definitions table has been changed for PROTECTED to DB_MANAGER: EXTERNAL_ELEMENT ITEM_NAME TYPE_OF_DATA Those fields can now be updated from CSTOL. The purpose of the change is to simplify the creation of wildcard panels by allowing direct updates of the fields, rather than doing delete and insert. 4.16 Polling Frequency Fixed in IP and ASYNC_CHAR (CRN 424) ----------------------------------------------------------- In previous release of OASIS-CC, the frequency at which a receiver task (IP and ASYNC_CHAR) protocol was polling the i/o port was incorrectly computed from the value in the time_out field of the primary stream record. This forced the use of lower than necessary time_out value. This release fix the problem. (see also Appendix H). 4.17 New Commands Verb (CRN 436) -------------------------------- The following new command verbs have been added to the parser: MLOAD DO 4.18 New Task Scheduling Algorithm (CRN 390) -------------------------------------------- In previous releases, the task scheduling algorithm used in OASIS-CC was a simple preemptive scheduling algorithm. With this patch OASIS-CC uses a priority inheritance scheduling algorithm. This algorithm bounds the duration of priority inversion states when they occur. 4.19 Remote Displays Mostly Working Under TAE 5.3 (SOLARIS ONLY) (CRN 448) -------------------------------------------------------------------------- TAE 5.3 (for SOLARIS) fixes many of the remote display problems that were in OASIS-CC V020510. Still some problems remain: (1) There is a large memory leak that appears whenever all the TAE panels on a remote X11 server are closed. This problem can be avoided by always leaving a TAE panel on a remote X11 server. (2) We have been able to have OASIS-CC crash under the following conditions: Multiple remote Xservers crash or are brought down simultaneously (with OASIS-CC panel present) after another remote server refuses an OASIS-CC connection request. (3) At random times, remotely displayed graphs may fail to update. As the TAE5.3/SunOs release of OASIS-CC uses X11R4 and Motif 1.1.4, the problems that were described in release v020510 still exist. 5 Change Requests Closed With This Release -------------------------------------------- Change Requests Number (including release 10 patches 1 and 2) crn # Title Comment *363 Global Procedure Control see above 4.9 *366 Handling of MSB in 32-bit values see above 4.3 *375 Directed write statement see above 4.5 *377 Streams.ID_VALUE 64 bits see above 4.6 *384 Command message contents echo see above 4.4 *385 CHECK directive see above 4.2 *386 Parameter passing in RUN directive see above 4.1 390 SQR bit cannot be checked fast enough in sub clp see above 4.12 and 4.18 392 Crash when defining command subfield in TAE 393 BRIDGE performances improvement 396 Spurious error messages in IEEE 398 MMC needs a larger command message see above 4.13 399 Confusing error messages introduced by 10(1) *400 Access to TAE menus while CSTOL prompt is unpasted 405 New EDT driver for 1553 (and s11w) 410 Problem with alert window text when default value hazardous 411 Problem with predefined C macros (ShowPanel and HidePanel) 412 Problem with display directive while in macro *413 Checkpoint capability see above 4.8 *414 Problem with uppercase in pathname see above 4.14 416 Problem with awb macro IfFunctNoEqual *417 Procedure Halt on Red Limits see above 4.10 *418 Modal Limit Support see above 4.7 421 Unable to assign -2147483648 to integer variable 422 Line number truncated when greater than 9999 424 Polling frequency in IP and ASYNC_CHAR incorrect see above 4.16 *431 Increase filename and CSTOL statement length see above 4.11 432 Protection to fields in display_definitions changed see above 4.15 434 Exception while sending large load (IEEE SunOs only) 436 New command verbs see above 4.17 438 New route statement semantic for IEEE see above 4.12 439 Frame marker addition in ASCII_CHAR protocol 441 Unable to display more that 64 characters in dynamic text 442 Routing not 100% data loss free 445 Record filename creation order modified to accomodate crn 414 *448 Remote displays under TAE 5.3 see above 4.19 In addition 391, 401, 402, 403, 420, 423 have been closed with no action taken. * Asterisks indentify changes covered in formal test plan and procedure documents that are available upon request. The associated code modifications or steps required to verify the changes are complex enough to warrant such. The changes that are not marked underwent internal tests that are also available upon request. However these tests are not managed under formal documentation requirements. 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 characters 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 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 in the SOLARIS version. 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. 6.13 Memory fragmentation (CRN 433, CRN 314) ------------------------------------------- Compiling and decompiling large procedures cause the memory used by OASIS-CC to become fragmented (OASIS-CC does a lot dynamic allocation/deallocation. Memory becomes fragmented when the memory free list is full of small, unsable memory free area). In V020510(2), we adjusted the memory management parameters in improve (by 1%) the bridge thruput (see CRN 433). An unknown side effect of the change was that when a large procedure was decompiled, the thruput of the application was greatly reduced. In V020511, we are using the old memory management parameters, so the thruput is not affected by the decompilation of large procedures. In V020511(1), we have tried to further tune-up the memroy management parameters. However this does not mean that the memory fragmentation issue has been removed and we recommend the following to avoid or minimize the problem: (1) If you have large procedures that are used only once (to load the database tables for example) do the following: start proc1 decompile proc1 ; free memory so that it can be reused by ; proc2 start proc2 decompile proc2 ; free memory so that it can be reused by ; proc3 ---- start procn ; do not decompile the last "large" procedure to ; lock memory to avoid fragmentation rather than: start proc1 decompile proc1 start proc2 decompile proc2 ---- start procn decompile procn (2) Procedures that are used only once should be decomposed into smaller procedures. From the point of view of the memory usage, it is better to have one procedure calling many small procedures than to have one "huge" procedure to accomplish the same task. I.E., proc set_up start set_up_1 decompile set_up_1 start set_up2 decompile set_up2 ---- end proc is preferable to a single procedure. 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 ---------------------------- A new OASIS-CC document set is anticipated for release this fall. 9 Upgrades To The Spectrometer Application -------------------------------------------- Spectrometer upgrades include (1) a demonstration of floating point commands (2) a demonstration of floating point decomposition, (3) a demonstration of ASCII decomposition and (4) a demonstration of a message window tailored for print-on-change messages. The command upgrades affect all commands defined for previous spectrometer applications. New packets are added to the packet telemetry system - there are no changes to the TDM telemetry system. Command Upgrade In order to allow the demonstration of floating point commands, all commands have their length increased from 24 to 120 bits (padded with zeros). A new command is added which requires single and double precision floating point data. The new command has the following mapping: bits 1-24: all zeros bits 25-88: double precision (8 byte) sub-field bits 89-120: single precision (4 byte) sub-field When it receives the new command, the spectrometer extracts the single precision field and echoes it in the (new) TYPE_A packet. To send the new command, enter at the CSTOL prompt: pass type_a_cmd with single XXXe+XX, double XXXXXe+XXX Currently, the double precision field is echoed in the packet as well, but it is not decomposed. See TYPE_A packet (below) for more information. Packetized Telemetry Upgrades There are three new packets added to the packetized telemetry stream. The "GPS" packet demonstrates decomposition of several single precision floating point telemetry items. The "Message" packet demonstrates ASCII decomposition. Finally, "Type A" packets return the floating point command data mentioned above. Packet Header Format: The format and length of the header remains unchanged. ID and length values reflect new packets: Bytes 1 and 2: Sync pattern (hex 3131) Byte 3: Packet Id 0 for science packet 1 for engineering packet 2 for GPS packet 3 for message packet 4 for type A packet Byte 4: length of the data field of the packet 28 for science packet 12 for engineering packet 27 for GPS packet 131 for message packet 12 for type A packet GPS Packet This packet includes five single precision floating point telemetry items. The ground-track longitude and latitude of a simulated spacecraft along with the x, y, and z body angles change as they would for a spacecraft in a circular orbit around the Earth. Each single precision value is located as follows: GPS Packet Data Field Format: bits 1-24: last command received (three bytes) bits 25-56: Longitude (range 0 to 360 degrees) bits 57-88: Latitude (range 0 to 360 degrees) bits 89-120: X Angle (range -0.38 to +0.38 degrees) bits 121-152: Y Angle (range -0.75 to +0.75 degrees) bits 153-184: Z Angle (range -0.25 to +0.25 degrees) bits 185-216: spare (not used) The packet is sent once per second regardless of the commanded telemetry rate. Message Packet The data portion of the packet consists of 128 characters of string data representing the latest spectrometer-generated informational message. Messages shorter than 128 characters are padded with trailing spaces. Each time the spectrometer generates a message, the Message Packet is sent. Message Packet Data Field Format: bits 1-24: Last command received (three bytes) bits 25-1080: 128 character field (128 bytes) Type A Packet This packet echoes floating point data received in the type A command. Type A Packet Data Field Format: bits 1-24: zeros bits 25-88: Double Precision Field bits 89-120: Single Precision Field Both the Double and Single Precision Fields are in Standard IEEE Floating Point formats. Type A Packets are sent only when a Type A command is received. New Panels A new panel called 'engatt' is available - it includes the standard header and all five GPS Packet telemetry items. Additionally, the Longitude and Latitude are plotted. The new panel also includes a key-in and push-button system for sending the Type A command. The new POC window demonstrates a message window customized to display print-on-change information. (The new spectrometer application defines the SPECTROMETER MESSAGE latest_data item to be printed on change.) To display the POC window, enter at the CSTOL prompt: "display poc". Note that the old spectrometer executable is still avialable in the distribution under the name of old_spectrometer. Appendix A: DATABASE TABLE UPDATES The protection of the fields external_element, item_name and type_of_data of the display_definitions table is now DB_MANAGER (vs PROTECTED). The change in the filename type specification (128 characters vs 60 characters) affects the size the following fields in the following tables: streams record_file_name utility_tasks task_file_name procedures filename macros filename Appendix B: CSTOL LANGUAGE UPDATES 1 - The CSTOL run directive has been updated. It now can take parameters. Format RUN program-name [parameter_list] Arguments program_name (identifier) : The utility to start. The name must appear in the Utility_Tasks database table. parameter_list: Values to pass to the utility program started by the run directive. The list can contain character strings, local variables and/or global variables, separated by commas. All parameters in local or global variables are translated into string data. Notes (1) If the data type of a parameter is character string, the character string is passed to the program. Single quotes (') within a string are replaced by double quotes ("). (2) If the data type of a parameter is either EU or REAL, the ASCII image of the float value is passed to the program. The units associated with EU types are dropped. (3) If the data type of a parameter is either DN or INTEGER, the ASCII image of the integer value is passed to the program. The "DN" specifier associated with DN types is dropped. (4) If the data type of a parameter is STATE, the ASCII image of the state is passed to the program (5) If the data type of a parameter is DELTA TIME, the ASCII image of the float value of seconds is passed to the program. (6) If the data type of a parameter is CLOCK TIME, the ASCII image of the time is passed. (7) The maximum number of parameters is 23. The number of parameters is defined as the number of spaces contained in the translated parameter list, plus one. For example, if a parameter list is: "THIS 'IS a' new TEST",$real assuming $real is 15.0, the effective parameter list that is passed to the program becomes: THIS "IS a" new TEST 1.5000000000e+1 which has 5 effective parameters. The maximum length of an effective parameter list is 256 characters (including the name of the program to be started) and individual string parameter cannot exceed 128 characters. 2 - A new CSTOL directive CHECK has been added Format CHECK parameter_list Arguments parameter_list: One or more of the following elements, separated by a comma (,). - character string (text between double quotes (")) - global variable [check_list] - local variable [check_list] check_list: VS value_1 : [value_2] Notes (1) Character strings are output without change. (2) When a local or a global variable is specified, its name is output followed by its value. (3) All local variables types are supported, except delta times and clock times. All global variable types are supported - including raw values. (4) When a single value is supplied in a check_list (value_1), the value of the local or global variable is checked for equality. It not equal, the portion of the output message associated with the check is red, and an indication of the mismatch (ne - not equals) is indicated. (5) When two values appear in a check_list (value_1 and value_2), OASIS-CC checks if the value of the local or global variable is within the range of check_list values (inclusive). If not within the range, the portion of the output associated with the check is red, and indication of greater than (gt) or less than (lt) the range is provided. (6) Single Values in a check_list must be followed by a colon (:). (7) Values in a check list can be valid CSTOL numeric expressions. 3 - The CSTOL write directive has been updated. See paragraph 4.5 above 4 - A new CSTOL directive CHECKPOINT has been added CHECKPOINT CHECKPOINT creates database-format disk images for database tables records. Format CHECKPOINT ALL TO name CHECKPOINT table_name WHERE selection-expression Arguments name (): translates to an upper case environment variable ($NAME) that points to the directory to which a complete database checkpoint is written. table-name (identifier): The database table containing the records to checkpoint. selection-expression (): A relational expression with subexpressions of the form field-name=value where field-name is a field and value is a constant value the field is compared against. Multiple subexpressions are connected by the logical connective AND. Records where every field has the specified value are candidates for checkpointing. Notes 1. The first form, (CHECKPOINT ALL TO name) is intended to create a complete snapshot of the OASIS-CC database from which a future OASIS-CC session may be started. Therefore, all primary streams must be switched or retrieved off, all telemetry displays must be cleared, and all bridge files must have recording stopped prior to attempting this form. If these conditions are not met, OASIS-CC will issue an appropriate error message and abort the request. 2. The second form (CHECKPOINT table-name WHERE selection-expression) is intended to allow snapshots of particular tables to be made for book- keeping purposes (such as latest_data, or limits). OASIS-CC does not care about the status of the named table in this form, so care should be taken not to allow OASIS-CC to be started from one of the files create by this form of checkpoint. If, for example, OASIS-CC was activated with a streams table where the field stream_is_on = true, the use could never activate the stream - OASIS-CC will reply "The stream is already on" when the switch on is attempted. Files generated by this form are placed in the directory pointed to by $OASIS_CHECKPOINT, and are named fyy_mon_doy_hh_mm_ss.table_name. Appendix C: HIGH LEVEL LANGUAGE EQUATION PROCESSOR APPLICATION DEVELOPER'S GUIDE ADDITIONS AND CHANGES This release of OASIS-CC expands and modifies the equation toolbox that was introduced in release 10. 1 - MODIFICATIONS TO THE EQUATION TOOLBOX Routine name Purpose Compute_Equation (Ada) Process a list of equation c_compute_equation (C) 2 - ADDITIONS TO THE EQUATION TOOLBOX Routine name Purpose Oasis_SetHiloChk (Ada) Enable/Disable limit checking Oasis_CSetHiloChk (C) Oasis_SetStateChk (Ada) Enable/Disable state checking Oasis_CSetStateChk (C) Oasis_SetLimit (Ada) Update limit threshold values Oasis_CSetLimit (C) Oasis_SetState (Ada) Update desirability of a state Oasis_CSetState (C) 3 - MANUAL PAGES FOR THE NEW AND THE MODIFIED TOOLBOX PROCEDURES NAME Compute_Equation (Ada version) - Process a list of equations c_compute_equation (C version) SYNOPSIS Ada version: with System; procedure Compute_Equation( Lock_Id : in System.ADDRESS; Li_Lock_Id : in System.ADDRESS; St_Lock_Id : in System.ADDRESS; Equation_List : in System.ADDRESS; Equation_Result : in System.ADDRESS); C version: #include void c_compute_equation(lock_id, li_lock_id, st_lock_id, equation_list, equation_result) db_lock lock_id; db_lock li_lock_id; db_lock st_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. Li_Lock_Id is passed from OASIS-CC to Compute_Equation to speed up the accesses to the limits table. This parameter SHOULD NOT be modified by Compute_Equation. St_Lock_Id is passed from OASIS-CC to Compute_Equation to speed up the accesses to the state_conversions 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_SetHiloChk (Ada version) - Enable/Disable limits checking Oasis_CSetHiloChk (C version) SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; procedure Oasis_SetHiloChk( Lock_Id : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; Hilo_Chk_State : in BOOLEAN); C version: #include void Oasis_SetHiloChk(lock_id, hashed_v, hilo_chk_state); db_lock lock_id; oasis_int hashed_v; int hilo_chk_state; DESCRIPTION This routine enables or disables limit checking for the measurement whose key is hashed_v (see compute_hashkey). Limit checking is enabled if hilo_Chk_State is set to TRUE (Ada version) or to HILO_TRUE (C version). Limit checking is disabled if hilo_Chk_State is set to FALSE (Ada version) or to HILO_FALSE (C version). The lock_id parameter is used to speed up access to the latest_data table. It corresponds to the lock_id parameter of the compute_equation procedure. NAME Oasis_SetStateChk (Ada version) - Enable/disabls state checking Oasis_CSetStateChk (C version) SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; with Latest_Dat_Type; procedure Oasis_SetStateChk( Lock_Id : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; State_Chk_State : in Latest_Data_Type.STATE_CHECK_CLASSES); C version: #include void Oasis_CSetStateChk(lock_id, hashed_v, state_chk_state); db_lock lock_id; oasis_int hashed_v; int state_chk_state; DESCRIPTION This routine updates the field state_check_class of the latest_data record for the measurement whose key is hashed_v (see compute_hashkey) with the state_chk_value. Legal values are DESIRABILITY, OFF, CHANGE and BOTH for the Ada version or STATE_DESIRABILITY, STATE_OFF, STATE_CHANGE and STATE_BOTH for the C version. The lock_id parameter is used to speed up access to the latest_data table. It corresponds to the lock_id parameter of the compute_equation procedure. NAME Oasis_SetLimit (Ada version) - Set limit threshold Oasis_CsetLimit (C version) SYNOPSIS Ada version: with Equation_User_Tools; with Numbers; procedure Oasis_SetLimit( Lock_Id : in System.ADDRESS; Li_Lock_Id : in System.ADDRESS; Hashed_V : in Numbers.INTEGER; Red_High : in Numbers.FLOAT; Red_Low : in Numbers.FLOAT; Yellow_High : in Numbers.FLOAT; Yellow_Low : in Numbers.FLOAT); C version: #include void Oasis_CSetLimit(lock_id, li_lock_id, hashed_v, red_high, red_low, yellow_high, yellow_low); db_lock lock_id; db_lock li_lock_id; oasis_int hashed_v; oasis_long_float red_high; oasis_long_float red_low; oasis_long_float yellow_high; oasis_long_float yellow_low; DESCRIPTION This routine updates the limits table record whose key is hashed_v (see compute_hashkey). It also updates the latest_data table record whose key is hashed_v, so that the next time the measurement defined by hashed_v is updated, it is checked against the new limit values even if the measurement value has not changed. Note that this side effect do not exists if the limits table is updated via the CSTOL query language. The lock_id parameter is used to speed up access to the latest_data table. It corresponds to the lock_id parameter of the compute_equation procedure. The li_lock_id parameter is used to speed up access to the limits table. It corresponds to the li_lock_id parameter of the compute_equation procedure. NAME Oasis_SetDesirability (Ada version) - Set the desirability of a state Oasis_CSetDesirability (C version) SYNOPSIS Ada version: with Equation_User_Tools; with Oasis_Types; with Data_Handling_Interface; procedure Oasis_SetDesirability( Lock_Id : in System.Status; St_Lock_Id : in System.Status; External_Element: in Oasis_Types.NAME_TYPE; Item_Name : in Oasis_Types.NAME_TYPE; State : in Data_Handling_Interface.STATE_STRING; Desirability : in Data_Handling_Interface.NEW_DATA_STATE_STATUSES); C version: #include void Oasis_CSetDesirability(lock_id, st_lock_id, external_element, item_name, state, desirability); db_lock lock_id; db_lock li_lock_id; char *external_element; char *item_name; char *state; int desirability; DESCRIPTION This procedure updates the desirability of the state state of the measurement defined by external_element and item_name. Legal values for desirability are GOOD and BAD (Ada version) and STATE_GOOD and STATE_BAD (C version). The procedure also updates the latest_data table record for the measurement defined by external_element and item_name so that the next time the measurement is updated, it is checked against the state desirability even if the measurement value has not changed. Note that this side effect do not exists if the state_conversions table is updated via the CSTOL query language. The lock_id parameter is used to speed up access to the latest_data table. It corresponds to the lock_id parameter of the compute_equation procedure. The st_lock_id parameter is used to speed up access to the state_conversions table. It corresponds to the St_lock_id parameter of the compute_equation procedure. In a C program, state can be defined as char state[OASIS_STATE_SIZE] In a C program, external_element and item_name can be defined as char external_element[OASIS_NAME_SIZE] char item_name [OASIS_NAME_SIZE] Appendix D: 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.11. 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 48,46,52 16/s 16kbps 2048 1984 on 54,54,44 24/s 24kbps 0 n/a n/a << 1 24/s 24kbps 3072 0 n/a 24,24,74 24/s 24kbps 3072 240 on 32,33,68 24/s 24kbps 3072 480 on tbd,35,62 24/s 24kbps 3072 1200 on 48,48,51 32/s 32kbps 0 n/a n/a << 1 32/s 32kbps 4096 0 n/a 33,34,65 32/s 32kbps 4096 320 on 44,42,55 32/s 32kbps 4096 640 on 47,48,47 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.11. 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,18,80 16/s 16kbps 2048 1984 off 43,45,54 16/s 16kbps 2048 1984 on 53,51,47 24/s 24kbps 0 n/a n/a << 1 24/s 24kbps 3072 0 n/a 29,29,71 24/s 24kbps 3072 240 on 33,30,70 24/s 24kbps 3072 480 on 38,37,62 24/s 24kbps 3072 1200 on 48,49,51 32/s 32kbps 0 n/a n/a << 1 32/s 32kbps 4096 0 n/a 40/38/59 32/s 32kbps 4096 320 on 43/44/54 32/s 32kbps 4096 640 on 50/50/48 For all measurement, the primary stream was set up with a frame_length of 4096 and a time_out of 0.05. Appendix E: 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.3. We are also running X11R5 and Motif 1.2, both from SUN. 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). (See also Appendix H). requested rate measured rate measured rate SunOs 4.1 (1) SOLARIS 2.3 (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.11 status Both V02.05.11 versions of OASIS-CC provide the same capabilities except for what is listed below. 2 - 1 S11W support This support is not currently avialable. 2 - 2 1553 EOS am low rate science protocol, remote terminal support The problem reported in the V02.05.09 and V02.05.10 release notes has been fixed by a new release of the EDT driver (release 1.21 (?), April 1994) 2 - 3 RS232 support The problem reported in the V02.05.09 and V02.05.10 release notes has been fixed by SOLARIS 2.3 Appendix F: SYNC PATTERN, BLOCK ID, ETC... (NEW VERSION) Bit patterns are used to specify the following fields in the four 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 1 - SPECIFYING A BIT PATTERN FIELD VALUE ---------------------------------------- In general, these fields are expressed using a hexadecimal representation. 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. Examples: Let's assume that a stream has a 8-bit ID_VALUE on a byte boundary whose pattern reads 11110111, then F7 is entered in the database. Let's assume that a stream has a 7-bit ID_VALUE starting on a byte boundary whose pattern reads 1111011, then F6 (i.e, 11110110) should be entered in the database. 2 - EXCEPTIONS TO THE RULE -------------------------- 2 - 1 BLOCK_ID_VALUE -------------------- For the field BLOCK_ID_VALUE there is one additional rule (which may be removed in a future release). - The BLOCK_ID_VALUE field has to be entered as if the trailing part of a 32 bit wide field. For example, the BLOCK_ID_VALUE 1 is expressed as "00000001" instead of "1", F1 as "000000F1" instead of "F1" and B8F1 as "0000B8F1" instead of "B8F1". 2 - 2 SYNC_PATTERN ------------------ 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 protocols do not. For example for the SYNC_PATTERN field, "FAF320" is expressed as "5FCF04" if the protocol is IP or ASYNC_CHAR. 3 - ADDITIONAL NOTES -------------------- The documentation for release 10 or earlier is incorrect concerning the field ID_VALUE. In release 10 or earlier the field has to be entered as if the trailing part of a 32 bit wide field, with the BYTES SWAPPED. For example, an ID_VALUE of 3FAB is entered as "AB3F000000" or "AB3F", which is swapped from "00003FAB". RELEASES 10(osc) AND 11 FIX THIS INCONSISTENCY: the same field is now expressed as "3FAB", following the common rule. Note also that whereas the database can hold up to 64 bits of ID_VALUE information, in release 10 or earlier only the first 32 bits are taken into account. The documentation for release 10 or earlier is incomplete concerning the field BLOCK_ID_VALUE. It forgets to mention that the field has to be entered as if the trailing part of a 32-bits wide field. However, the examples given in the release notes release 09 or 10 for this field are correct. Note also that whereas the database can hold up to 64 bits of BLOCK_ID_VALUE information, currently only the first 32 bits are taken into account. 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 Appendix H: NOTE ON SCHEDULATIBILITY OF ADA TASKS In OASIS-CC, data acquisition tasks are scheduled at regular interval to check either for the presence of data (like in the IP protocol) or for a request from the data originator (like in the IEEE-488 protocol using the SRQ capability). The scheduling interval is specified by the user, sometimes in the streams table (field time_out) or directly in the cstol directive (like in the sample directive). Therefore it is of great interest to know (1) what is the smallest possible schedule interval; and (2) what is the resolution of the time_out value entered by the user. We have conducted two basic tests outside of OASIS-CC, concentrating on the impact of the Ada language and its runtime executive on these parameters. The results give us lower bounds for OASIS-CC application. The first test consists in looking at the result of the Ada delay statement in an Ada program that does not use tasking. This test in irrelevant for OASIS-CC, as OASIS-CC uses tasking. But it gives us a baseline by which we can judge the efficiency of the runtime executive when tasking is involved. The second test consists in program with two Ada tasks. The lowest priority task loops forever. The highest priority task is scheduled at regular interval. TESTS RESULTS ------------- Test #1 .Non tasking test. Requested schedule Measured schedule Measured schedule interval interval interval in milliseconds SunOs 4.1.3, SunAda 1.1 Solaris 2.3, SunAda 2.0 00.5 20.0 1.0 01.0 20.0 1.0 01.5 20.0 2.0 02.0 20.0 2.0 05.0 20.0 5.0 10.0 20.0 20.0 30.0 30.0 40.0 Test #2 .Tasking test. Requested schedule Measured schedule Measured schedule interval interval interval in milliseconds SunOs 4.1.3, SunAda 1.1 Solaris 2.3, SunAda 2.0 00.5 20.0 30.0 01.0 20.0 30.0 01.5 20.0 30.0 02.0 20.0 30.0 05.0 20.0 30.0 10.0 20.0 30.0 15.0 20.0 30.0 20.0 30.0 40.0 25.0 30.0 40.0 30.0 40.0 50.0 35.0 40.0 50.0 40.0 50.0 60.0 45.0 50.0 60.0 50.0 60.0 70.0 55.0 60.0 70.0 CONCLUSION ---------- Under SunOs 4.1, the smallest usable time_out value is 20.0 milliseconds. Under Solaris 2.3 it is 30.0 milliseconds. Note that these results confirm the remark made in Appendix E of the release notes about the thruput problem we are facing with the simulator used to measure the OASIS-CC performances. What are the consequences on OASIS-CC applications? IP and ASYNC_CHAR protocols. The highest theoretical telemetry rate that OASIS-CC can ingest is computed by the formula: highest theoretical rate = (primary frame_length) * 50 (sunos) highest theoretical rate = (primary frame_length) * 33 (solaris) Note that because we constrain in the TDM processing code the primary frame_length to be equal to the TDM frame size, OASIS-CC is currently limited to at most 50 TDM frames/second (sunos) or 33 TDM frames/second (solaris) (see for reference paragraph 6.2 of the release notes or crn 259). The software may be upgraded in a future release to increase the performance of the TDM acquisition code. Also note that there is a coding "feature" in the IP and the ASYNC_CHAR code that makes the real rate lower than the theoretical rate. This is fixed in release 11. IEEE-488 protocol OASIS-CC is limited to at most 50 service requests/second (sunos) or 33 service requests/second (solaris).