OASIS-CC VERSION V03.00 RELEASE NOTES prototype 8.0 - 10/1/97 1 Compatibility And Requirements Information 2 Installing OASIS-CC -------------------------------------------------!UPDATED 3 Overview 4 Subsystem Changes Description 4.1 Database 4.1.1 Concept 4.1.2 Table Layout Changes 4.1.3 Management of instance-unique information 4.2 CSTOL 4.2.1 Syntax Extension 4.2.2 Additional Statements ---------------------------------------!UPDATED 4.3 Telemetry Acquisition and Processing 4.4 Command Processing 4.4.1 Using pre-check and post-check procedures 4.4.2 User access to command and command message buffer (crn 557) 4.5 Display Processing 4.5.1 Displaying from CSTOL 4.5.2 Displaying via a "next" panel 4.5.3 Displaying a panel using a TAE Macro 4.5.4 Access to an item in a instance of panel from a TAE Macro 4.5.5 Modifying a TAE panel via user-provided code (crn 623) 4.6 Bridge Processing 5 Other Changes 5.1 User Defined Alert Window 5.2 CAUTION State 5.3 Out-Of-Limit Counters 5.4 Access to the smoothed value in "C" equation code (crn 579) 5.5 Check directive message upgrade (crn 541) 5.6 Additional unit mnemonics (crn 581) 5.7 Faster command generation (crn 596) 5.8 Improving command thruput (crn 605) 5.9 Utility task window naming (crn 607) 5.10 Failing CHECK statement does not stop procedure (crn 618) 5.11 EU_UNITS /= DN allowed when NEW_DN (crn 619) 5.12 Stale data (crn 625) 5.13 List of the current red alarm (crn 628 & crn 642) 5.14 Improved retrieve thrutput (crn 617) 5.15 Event message filtering using instance (crn 641) 5.16 Passing instance name to trigger procedure (crn 643) 5.17 Faster "switch on" when restore is used (crn 649) --------------!NEW 6 Fast Transfer Mechanism ---------------------------------------------!UPDATED 7 List of changes since last release ----------------------------------!NEW 8 Known problems 8.1 Oasis command subsystem locks up (crn 588) 8.2 Global variable not xfered when ROUTE_TO_BRIDGE = ON_CHANGE (crn 603) 8.3 Leak while doing remove/merge (crn 632) 8.4 Segmentation fault with user-defined ALERT window (crn 637) 8.5 Core dump when Wpt_ViewUpdate of graph item (crn 640) Appendix A : CSTOL SYNTAX CHANGES Appendix B : ADDITIONAL CSTOL STATEMENTS Appendix C : BUILDING AN APPLICATION-DEFINED ALERT WINDOW Appendix D : STREAMS SETUP EXAMPLE Appendix E : COMMAND TABLES SETUP EXAMPLE Appendix F : HIGH LEVEL LANGUAGE ACCESS TO COMMAND AND COMMAND MESSAGE BUFFER Appendix G : OASIS TOOLBOX DESCRIPTION Appendix H : oasis_data_server.h ------------------------------------!CORRECTED Appendix I : UPDATED Macro_Defs.C FILE Appendix J : NEW DATABASE TABLE LAYOUT (outside of instances) Appendix K : HIGH LEVEL LANGUAGE ACCESS TO TAE DISPLAY Appendix L : ADDITION TO THE EQUATION TOOLBOX (STALE DATA & SMOOTHED DATA) OASIS-CC VERSION V03.00 RELEASE NOTES prototype 8.0 - 9/1/97 1 Compatibility And Requirements Information -------------------------------------------- This release of V0300 has been tested under the following environment: Sparc UltraSparc Solaris 2.5.1 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) 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) It requires TAE+ 5.3c. It is not compatible with TAE+ 5.3l; 2 Installing OASIS-CC --------------------- Release V0300 distribution is installed the same way releases v0205xx are installed. ******************************************************************************* * 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 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: This version of the prototype for version 03 is NOT compatible with the previous version. The format of the files generated by the save_decomposition_tree utility has changed (see paragraph TBD, crn 649). To be able to use the "restore tree" capability all the decomposition tree must be re-saved. --** (NEW) **-- 3 Overview ---------- The core functionality of V0300 is basically the same as V020514(3) with few exceptions. But V0300 is optimized toward the command and control of multiple instances of the same hardware (for example, a constellation of spacecraft). Its purpose is to (1) Minimize the development and maintenance cost of the database tables. (2) Minimize the impact of the size of the database tables on memory usage. (3) Allow any instances of the hardware under control to be commanded from any workstation on a command and control LAN. The next paragraphs describe how these goals have been met. Throughout the text the term 'instance' is used to identify a copy of generic hardware. For example, assume a constellation of identical spacecraft: each spacecraft is an instance of a generic spacecraft and is identified by a instance name (for example s1 for the first instance, s2 for the second one...). The term 'instance' has a secondary meaning when discussing of displays: it is also used to identify a copy of a generic display. Notes (1) IEE-488 is not currently supported. (2) The distribution tape does not have a spectrometer application. The starter database is part of the distribution. 4 Subsystem Changes Description -------------------------------- 4.1 Database ------------ 4.1.1 Concept ------------- As far as instances are concerned, a record of a database table falls into one of three categories: (1) it is shared by all the instances of the generic object; (2) it is shared by some, but not all, instances of the generic object and (3) it is instance-unique. The choice of under which category the contents a table falls is mainly driven by type of information carried by the table. However, it is also partially driven by performance considerations. Let's take the LIMITS table for example. Theoretically, some records could be shared by all the instances (i.e., the limits on a measurement are the same for all the instances), but the system needs also to make provision for differences between instances. Accesses to a table like LIMITS are time-constrained, and it would be very costly to search, first, the table for an instance-specific record and, then, if it does not exist, for the generic record. Therefore OASIS-CC expects a table like LIMITS to contain only instance-unique information. On the other hand, accessing the command tables is less time-constrained and there OASIS-CC looks, first, for the instance-unique information and then, if it does not exist, for the generic information. The database tables that have been modified to carry instance information have been classified as follows: Table Name Classification ANALOG_CONVERSION instance-unique ASCII_COMMAND_MAPS mixed ASCII_COMMAND_VALUES instance-unique BRIDGE_DEFINITIONS mixed COMMANDS mixed COMMAND_MAPS mixed COMMAND_MESSAGES mixed COMMAND_STATE_CONVERSIONS mixed COMMAND_VALUES instance-unique COMMAND_VALUE_CONVERSIONS mixed DISPLAY_DEFINITIONS mixed ELEMENT_CHARACTERISTICS mixed LATEST_DATA instance-unique LIMITS instance-unique STATE_CONVERSIONS instance-unique 4.1.2 Table Layout Changes -------------------------- A field named INSTANCE of type NAME_TYPE has been added to following tables: Table Name Is Key? Where added ANALOG_CONVERSIONS yes first field ASCII_COMMAND_MAPS yes first field ASCII_COMMAND_VALUES yes first field BRIDGE yes after NAME COMMANDS yes first field COMMAND_MAPS yes first field COMMAND_MESSAGES yes first field COMMAND_STATE_CONVERSIONS yes first field COMMAND_VALUES yes first field COMMAND_VALUE_CONVERSIONS yes first field DISPLAY_DEFINITIONS no after INDEX ELEMENT_CHARACTERISTICS yes first field LATEST_DATA yes first field LIMITS yes first field STATE_CONVERSIONS yes first field 4.1.3 Management of instance-unique information ----------------------------------------------- The query language has been extended to allow instance-unique information to be saved from and restored into a running copy of the database tables. This mechanism divides the database tables into a generic set of records and some instance-specific set of records. The generic set is stored in $OASIS_DATABASE and each specific set (one per instance) is stored in $instance_OASIS_DATABASE (for example for an instance name s1 the specific set of records is stored in $S1_OASIS_DATABASE). When OASIS is started, it loads the generic set of records. Using the MERGE statement (see below), an application can control which instance-specific set of records should be added to the generic set of record. Using the REMOVE statement (see below), an application can save and remove the current image of an instance-specific set of records. 4.2 CSTOL --------- 4.2.1 Syntax Extension ---------------------- The syntax of many CSTOL statements has been extended to support the prefixing of objects by the instance name using a "dotted" notation. For example, these are valid statements: let s1.batt temp = 20.0 c let $s.batt temp = 20.0 c ; $s is a local variable of the type ; state or string display s1.pagea This dotted notation is valid with the following objects: global variable (e.g., s3.batt voltage) display name (e.g., s5.pageb) external element name in a command (e.g., turn on s1.hvps) bridge name (e.g., s1.my_bridge) The instance part of the dotted notation (the part at the left of the ".") can be a character string or a local variable of the type state or character string. Due to TAE constraints, the usable part of the name of the instance is limited to 15 characters. OASIS itself uses 16 characters to store the instance name in the database tables. The syntax of the following statements is changed: CLEAR DISPLAY LOAD MESSAGE RECORD (for bridge only) SNAP STOP RECORDING (for bridge only) SWITCH (for bridge only) SWITCH RECORDING (for bridge only) command request statement reference to global variables in a logical or arithmetic expression or in a paremeter list Details of the syntax changes are provided in Appendix A 4.2.2 Additional Statements --------------------------- Two new CSTOL statements have been added to support the management of instances (e.g., spacecraft) unique information (see paragraph 4 - 1 above). (a) Saving and deleting instance unique information from a workstation running copy of the database 1) REMOVE instance_name FROM table_name 2) REMOVE instance_name FROM ALL This statement saves to disk and then deletes from a specific table (1 above) or from all the tables that have a instance field (2 above) all the records in which instance = instance_name. The files are stored in a directory pointed by the variable $INSTANCE_NAME_OASIS_DATABASE, where INSTANCE_NAME is the instance name in uppercase. The file names are in the form: table_name.dat. For example, remove s1 from analog_conversions saves all the records from ANALOG_CONVERSIONS where instance = s1 in a file named analog_conversions.dat in $S1_OASIS_DATABASE before deleting them. remove s2 from latest_data saves all the records from LATEST_DATA where instance = s2 in a file name latest_data.dat in $S2_OASIS_DATABASE before deleting them. Note that what is saved is the current image of LATEST_DATA, i.e., it's the current state of the instance s2. (b) Merging instance unique information into a memory copy of the database in a workstation MERGE instance_name INTO table_name MERGE instance_name INTO ALL This statement reads back the contents of the files created a REMOVE statement and merges it into the running copy of the database table. for example merge s10 into latest_data reads and merges all the contents of the file $S1_OASIS_DATA/latest_data.dat into the memory copy of the database. Both REMOVE and MERGE are described in detail in Appendix B. Note: (1) Currently the code does not prevent a REMOVE statement from being executed while some data from the instance that is removed are displayed, bridged or "fast_xfered". However, since crn 625a, when a MERGE is done on latest_data the flags route_to_display and route_to_bridge are resetted to NEVER. The flag "route_to_data_server" is left unchanged. --** (UPDATED) **-- (2) When an instance is merged its LATEST_DATA records are marked as stale (see paragraph 5.12). (3) If a REMOVE statement results in an empty file, the file is not created. This is to avoid the situation where two REMOVE statements are executed with the same combination of instance and table without a MERGE in between (this results in an empty file being created). (crn 632) --** (NEW) **-- 4.3 Telemetry Acquisition and Processing ---------------------------------------- The protocols IP, IP_1, ASYNC_CHAR and ASYNC_CHAR_1 support the notion of instance. It is assumed that each instance shares the same stream hierarchy and the same decomposition algorithm. Therefore, only one suite of stream records and of decomposition records is needed. When a receiver for the above protocols is "switched on" (or "retrieved on"), it builds only one decomposition tree and uses an instance identification in the telemetry stream to generate the atom names when they are extracted from the telemetry stream. The information about where to find the instance identification in a telemetry stream and its size is passed to the acquisition code via two records in the latest_data table with instance = " " external_element = stream_name item_name = INS_ID_OFFSET (position of the id field) INS_ID_SIZE (size of the id field) data_class = NUMERIC dn_low = the value for the position of the id field or for the size of the id field. These values are expressed in bytes or bits depending on the value in the record " ", stream_name,IS_PACKETIZED: - if 0, the stream is a TDM stream, and the values are expressed in bits. - if 1, the stream is packetized, and the values are expressed in bytes. - if 2, the stream is packetized, and the values are expressed in bits. - if 3, the stream is a TDM stream, and the values are expressed in bytes. The list of instances to be processed by a stream and their corresponding id values are also passed to the acquisition code via the latest_data table. A first record groups all the instances to be processed by a stream under a group_name instance = " " external_element = stream_name item_name = INSTANCE_GROUP data_class = CHARACTER_STRING char_string = instance group name Then, a set of records defines the instances and their id values that belongs to a group instance = $instance_name external_element = INSTANCE_GROUP item_name = INSTANCE_ID data_class = NUMERIC dn_low = id value for the instance instance_name (note the "$" in front of the instance_name in the instance field. This is to avoid the accidental removal of this type of record via the REMOVE statement. When the stream is switched on, this information needs to be present). Appendix D gives an example of a streams table set up. Notes: (1) Currently, the ROUTE statement does not differentiate between secondary streams from different instances. Therefore, in the case of the example in Appendix D the statement route sec to stream_name will route the secondary stream sec from all the instances to the forward stream stream_name. 4.4 Command Processing ---------------------- The processing of commands in this version of OASIS-CC is not very much different from version 02. The major difference is that the command definitions can be shared among several instances of the generic object being controlled. See Appendix E for a example of command tables set up. 4.4.1 Using pre-check and post-check procedures ----------------------------------------------- When a command defines a precheck procedure or a postchek procedure the application developper can force OASIS to pass the instance name in the procedure call. This is indicated to OASIS by having the characters &&& at the end of the parameter list. For example assume the following generic command external_element platform command_name move prechec_proc start xyz par1,par2,&&& When the statement move s1.platform is executed the following prechec statement is be executed: start xyz par1,par2,"S1" (note the uppercase) 4.4.2 User access to command and command message buffer ------------------------------------------------------- User-provided code is called 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 F (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 G (OASIS TOOLBOX DESCRIPTION). 4.5 Display Processing ---------------------- 4.5.1 Displaying from CSTOL --------------------------- OASIS-CC allows for the definition of generic panels where the name of the instance is supplied at display time. For example, assume that a panel (called testa) has been defined with one item (named "bytea1" in the workbench), and assume the following record in display_definitions: insert display_definitions tae_base = bytea1, index = 0, & external_element = perf, item_name = byte1, & instance = " ", & type_of_data = eu_data, units = v, & value_format = "f8.3" The statement display s1.testa displays the panel testa associating "bytea1" with the global variable "s1.perf byte1" if such a global variable exists. If it does not exist, OASIS-CC tries to associate bytea1 with the global variable "perf byte1". The statement display s2.testa displays the same panel but associates "bytea1" with the global variable "s2.perf byte1". This second panel is displayed even if the first panel is already displayed. The statement clear s2.testa clears the panel brought up via the "display s2.testa" statement. 4.5.2 Displaying via a "next" panel From the point of view of TAE, an 'instance' can have 3 potential values (without quotes): "" (or null) indicates NO instance. This is the default usage for a panel where instance information is ignored. "instance" [reserved word] indicates "same instance as initiating panel"... this is used in connection with bringing up "next" panel, and also in specifying a panel.item parameter [old syntax] .. where new syntax allows instance.panel.item the word "instance" is reserved here and it's use explained below. "" is used to identify a unique instance of this panel. The Actions Panel which comes up for any TAE Presention type which would generate an event during runtime contains by default one line: -- Wpt_NewPanel goes here This line continues to be supported for backward compatibility in this new version. However, to make it possible to create (or show) a "next" panel specifying its "instance" information, the user may add this instance information as a parameter to the Wpt_NewPanel as follows: -- Wpt_NewPanel(name of the nextinstance) Specifying the 'no instance' case would be as above )default "goes here" case) with no parenthesis or: -- Wpt_NewPanel() Specifying the "same" instance as the panel where the event generated: -- Wpt_NewPanel(instance) For example, assume a panel "disp" which has three push buttons that define a "next" panel. The first push button is used to display s1.testa. The "next" panel is testa and in the action panel the Wpt line should read (note that the instance is uppercased) -- Wpt_NewPanel(S1) The second push button is used to display s2.test. The "next" panel is testa and in the Actions panel the Wpt line should read (note that the instance is uppercased) -- Wpt_NewPanel(S2) The third button is used to display a panel called testc. The "next" panel is testc and in the Actions panel the Wpt line should read -- Wpt_New_Panel() or -- Wpt_New_Panel goes there Assume now that the testa panel has a push button that is used to display the same instance of a panel called testb. In this case, the "next" panel is testb and in the Actions panel the Wpt line should read -- Wpt_New_Panel(instance) Pushing the button from s1.testa will display s1.testb. Pushing the button from s2.testa will displaye s2.testb 4.5.3 Displaying a panel using a TAE Macro ------------------------------------------ As indicated above, 'instance' is a reserved word defined at the panel level and whose value is the instance of the panel. For example in s1.testa 'instance' has the value is "s1". Assume that the panel testa has a push button with the following action Cstol "display" + .instance + ".testb" pushing the button from s1.testa will execute the statement "display s1.testb". 4.5.4 Access to an item in a instance of panel from a TAE Macro --------------------------------------------------------------- The former syntax for Macro Parameters in the Action Code Generator allows for specifying the value of an item on an existing panel as: panel.item The meaning for this statement in the new version which supports multiple instances of the same panel has a slight change to it. In order to support multiple instances, we now allow for specifying this with the syntax: instanceName.panel.item where instanceName may be either (without quotes): "instance" using this reserved word means (as in the Wpt_NewPanel() parameter) that the specified item is to be found in the named panel which was created for the instance with the same name as the one that generated the event nothing (as in "panel.item" rather than "xxx.panel.item") has 2 possible meanings (please note that this is different than the Wpt_NewPanel() where nothing always means "" (blank)) 1) If the "panel" is something other than the panel specifying the event, then this form means use the blank case. 2) If the "panel" is the same as the panel specifying the event, then this form means do as in "instance.panel.item" above (i.e., same instance as the one that generated the event) "anythingElse" using anything else means that a specific instance is to be used in finding the item in the named panel. Note: (1) Because TAE controls where on the screen a panel is displayed, when multiple instances of the same panel are displayed they are displayed on top of each other. (2) As indicated above 'instance' is a TAE reserved word. That can be used to automatically display on a panel its instance name. To do that define a TAE item whose workbench item name is 'instance' and whose data type is dynamic text. Displaying the panel will automatically display its instance name in place of the TAE item called 'instance'. 4.5.5 Modifying a TAE panel via user-provided code (crn 623) ------------------------------------------------------------ Every time a TAE panel is displayed OASIS-CC calls a user-provided "C" function (Oasis_CModDisplay). This function can be used to modify the apparence of a TAE panel depending on, for example, which instance of the panel is displayed. The distribution comes with a stubbed routine in $ODIST/common_distrib/objects/oasis_display_stub.c. The stubbed routine object code is in the default libOasisUser.a library that is delivered with the distribution. The function prototype of Oasis_CModDisplay()is in $ODIST/include/wptmodinc.h. It is described in detail in Appendix K. An example of usage is given below. In this example the label "b1" of a panel name "testa" is set to "PWR" if the instance is "S1" and to "CDS_PWR" if the instance is "S2". The code is called everytime a is displayed. /* code for oasis display modification */ #include "taeconf.inp" #include "wptinc.inp" #include "symtab.inc" #include "parblk.inc" #include "wptmodinc.h" void Oasis_CModDisplay(display , view, target, panel, panel_name, instance) Display *display; char *panel_name; char *instance; Id view; Id panel; Id target; { if (strcmp(panel_name,"testa")==0) { if (strcmp(instance,"S1")==0) { Vm_SetOneString(view,"b1",1,"PWR",P_UPDATE); Wpt_ViewUpdate(panel,"b1",view,"b1"); } else if (strcmp(instance,"S2")==0) { Vm_SetOneString(view,"b1",1,"CDS_PWR",P_UPDATE); Wpt_ViewUpdate(panel,"b1",view,"b1"); } } } 4.6 Bridge Processing --------------------- Generic bridges can be defined. The association of a generic bridge with a specific instance is done via the switch or record statements. For example assume that the following streams and bridge_definitions contents: streams table Stream_Name test_bridge Processor bridge_subsystem bridge_definitions Name test_bridge test_bridge test_bridge Instance test " " " " External_Element chamber power batt Item_Name temp temp temp Position_In_Output 1 2 3 The statement switch on s1.test_bridge generates a copy of the bridge "test_bridge" with the following measurements 1 test.chamber temp 2 s1.power temp (or power temp if s1.power temp is not defined in latest_data) 3 s1.batt temp (or batt temp is s1.batt temp is not defined in latest_data) The statement record on s1.test_bridge copies the same measurements to a file named fyy_mmm_dd_mm_ss.test_bridge.s1_data and the header file and the ident file are named fyy_mmm_dd_mm_ss.test_bridge.s1_header fyy_mmm_dd_mm_ss.test_bridge.s1_ident When OASIS encounters statements like switch on s1.test_bridge record on s1.test_bridge it inserts a copy of the "test_bridge" record in the streams table. The copy is done with a different name computed by "hashing" the generic stream name ("test_bridge") and the instance name ("s1"). For example switch on s1.test_bridge results in a new streams record named P1732781776 and switch on s2.test_bridge results in a new streams record named M252738351 These records may not necessarly deleted when the bridges are switched off. 5 Other Changes --------------- 5.1 User Defined Alert Window ----------------------------- Applications can now design their own alert window. The rules that a user must follow in developing his/her alert window are described in Appendix C (BUILDING AN APPLICATION-DEFINED ALERT WINDOW). Those rules are necessary to ensure 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. 5.2 CAUTION State ----------------- The desirability of a state can now be either GOOD, BAD, and CAUTION. This last additional desirability value acts like a yellow limits. 5.3 Out-Of-Limit Counters ------------------------- OASIS-CC provides 3 counters of out-of-limit items per instance/subsystem grouping. One counter ($$YELLOW_LIMIT) is for the yellow alarm, another one ($$RED_LIMIT) is for red alarm. The third counter ($$OUT_OF_LIMITS) contains the summation of the two previous counters. As in version 02 the association of a measurement to a counter is done via the contents of the field SUBSYSTEM_NAME in the latest_data record. In addition the counters are grouped by instance. For example assume the following measurement: Instance s1 External_Element e1 Item_Name i1 Subsystem_Name ss When this measurement goes from green to red the following counters are incremented: Instance s1 External_Element ss Item_Name $$OUT_OF_LIMITS and $$RED_LIMIT 5.4 Access to the smoothed value in "C" equation code (crn 579) --------------------------------------------------------------- User can access a smoothed value from a "C" equation routine. Description of the routine (Oasis_CGetSmoothedValue) that has been added to the equation toolbox follows: NAME Oasis_CGetSmoothValue - Get the value contained in - the EU_SMOOTHED field value - of a known global variable SYNOPSIS #include int Oasis_CGetEuValue(lock_id, hashed_v, smooth_value, eu_unit); db_lock lock_id; oasis_int hashed_v; oasis_float *smooth_value; char *eu_unit DESCRIPTION This routine returns in the smooth_value variable the value contained in the EU_SMOOTHED field of the latest_data table record whose key is hashed_v (see compute_haskey). The eu_unit parameter returns the value contained in the EU_UNITS field. The lock_id parameter is used to speed access to the latest_data table (see compute_equation). The function returns 1 (success) or 0 (failure, when SMOOTHING_ENABLED is FALSE). eu_unit can be defined as char eu_unit[OASIS_UNIT_SIZE] 5.5 Check directive message upgrade (crn 541) --------------------------------------------- When a Check directive is issued from a procedure the HI and HC messages generated now contain the procedure name and the line number within the procedure. This change means that the Check message ids (HC and HI) are now four characters long. The last two characters identify the issuing clp (like the LI or LU messages). 5.6 Additional unit mnemonics (crn 581) --------------------------------------- The following unit mnemonics have been added: Mnemonic Intended use GS Gauss IPS Inch-Pound-Second ILB Inch-Pounds AHR Ampere-Hours MSD Millisec/Day MD2 Millisec/Day^2 5.7 Faster command generation (crn 596) --------------------------------------- The generation of non-discrete commands can be very slow when the COMMAND_VALUES table is large (i.e., when the number of subfields defined in the application is large). To change that the COMMAND_VALUES table has been reorganized and now the command generation time is basically independent of the size of the COMMAND_VALUES table. In the new COMMAND_VALUES table for a specific command, the command subfields are ordered starting at 0 and incrementing by 1 for each subfield. This allows OASIS-CC to access directly each subfield record rather than do a full search of the COMMAND_VALUES table. See Appendix J details the new COMMAND_VALUES table layout. As an example assume an application with two commands: move s1.platform with position 10.0 deg, direction plus set s1.slit with position large, direction plus OLD COMMAND_VALUES TABLE POSSIBLE NEW COMMAND_VALUES TABLE s1 s1 first record platform platform move move position 0 .. position .. .. s1 s1 second record platform platform move move direction 1 .. direction .. .. s1 s1 third record slit slit set set position 1 .. position .. .. s1 s1 fourth record slit slit set set direction 0 .. direction 5.8 Improving command thruput (crn 605) --------------------------------------- When the COMMAND_STATE_CONVERSIONS table is large commanding is slowed down. The reason is that every time a non-discrete command is built for every subfield the COMMAND_STATE_CONVERSIONS table is searched to see if there is a state equivalent to the subfield value. This is used in the event message log file and in the command_window output where for each subfield the state translation is displayed (when it exists) rather than the subfield value. To improve commanding thruput this feature has been removed: the event message log file and the command_window output now show only the value of a subfield, not its state translation. 5.9 Utility task window naming (crn 607) ---------------------------------------- The contents of the TASK_NAME field in the UTILITY_TASKS record is now used as label to the XTERM window opened when the RUN directive is executed. 5.10 Failing CHECK statement does not stop procedure (crn 618) -------------------------------------------------------------- Contrary to the way the CHECK statement works in version 02 of OASIS-CC in this release when a CHECK statement fails the procedure from which it is issued is not stopped. The special variable $$ERROR is updated after the execution of a CHECK directive. The values returned in $$ERROR are NO_ERROR or CHECK_ERROR. 5.11 EU_UNITS /= DN allowed when NEW_DN (crn 619) ------------------------------------------------- In previous releases if a measurement was decomposed with the DATA_TYPE (in the decomposition table) set to NEW_DN a unit of DN was assumed. Then if the measurement was to be converted to an engineering unit an analog_conversions record was expected. With this release if a measurement is decomposed with the DATA_TYPE set to NEW_DN and a EU_UNITS set to a value different of DN (or ANY): - The measurement is extracted; - Its value is converted to float; - and then measurement is treated like a measurement decomposed with with the DATA_TYPE set to NEW_EU. This means that for this type of measurement: - No analog_conversions records are needed; - The DN_EXISTS flag in latest_data is not set (as the measurement is treated like a NEW_EU measurement); Note that if no analog_conversions records are defined for a measurement which units is not DN, then if the user tries to set the measurement DN value using the LET statement or one of the OASIS_CSetDn routines an error is returned by OASIS-CC and the measurement unit is resetted by OASIS-CC to DN. 5.12 Stale data (crn 625) ------------------------- The notion of stale data is now supported by OASIS-CC. In the LATEST_DATA table the field QUALITY_CODE can now take the following value: NO_DATA, BAD, GOOD and STALE. When a stale measurement is displayed a "$" sign is output at the right of the measurement if SHOW_QUALITY_CODE is set to TRUE in the DISPLAY_DEFINITIONS record for this measurement. It's the user responsibility to determine if a measurement is stale. The user is provided with two C-callable routines to update the QUALITY_CODE field in specific records of the LATEST_DATA table. These routines can only be used from the user equation code. They are Oasis_CSetDataQuality() and Oasis_CSetInstanceDataQuality(). The first routine is used to update QUALITY_CODE for a known measurement. The second routine is used to update QUALITY_CODE for all the measurements associated with a known instance. These two routines are detailed in Appendix L (ADDITION TO THE EQUATION TOOLBOX). Note that when instance-specific LATEST_DATA records are merged into the running copy of the LATEST_DATA table, the records that are merged are marked as STALE. 5.13 List of the current red alarm (crn 628 and crn 642) -------------------------------------------------------- OASIS-CC now maintains internally an ordered list of the measurements that are low and high red-limited. This list printed with an HR code each time it is modified. Messages with the code 'HR" are not logged into the event messages file and they are displayed to an event messages window only if the window has a discriminator of "HR". The order used in dumping the list is controlled by the special variable $$LIMITS_LST_ORD. This variable can take the value of FIFO (the most recent alarm is printed first) or FILO (the least recent alarm is printed first). Default value is FIFO. The number of red alarm to be dumped is controlled by the special variable $$LIMITS_LST_CNT. Default value is 15. The global variables instance = " ", external_element = "$$GLOBAL" and item_name = "$$LIMITS_LST_ORD" or item_name = "$$LIMITS_LST_CNT" are copies of the new special variables. In addition the SHOW directive can be used to dump the current contents of the red alarm list, either globally or by instance. The syntax is SHOW RED [instance].LIST. For example SHOW RED LIST will print all of the red message list. SHOW RED S1.LIST will limit the print to the instance S1. Note on $$LIMITS_LST_CNT: - It applies to all the red messages when the list is automatically refreshed or when a "show red list" statement is executed. - It applies only to the instance specific red messages when a "show red instance.list" is executed. 5.14 Improved retrieve thrutput (crn 617) ----------------------------------------- In previous releases when the "every" field in a retrieve statement was set to 00:00:00.000 (as in "retrieve xyz from www every 00:00:00.00") the time between 2 packets was defaulted to 00:00:00.1 (to avoid the processor being taken over by the retrieve task). In this release if a "every" field in a retrieve statement is set to 00:00:00:000 then no delay is applied between two packets. 5.15 Event message filtering using instance (crn 641) ----------------------------------------------------- The DISPLAY_DESCRIPTIONS table layout has been modified. A new field called INSTANCE has been added. This field is taken into account only when the PAGE_KIND field is set to FOR_MESSAGE. When for a message window the INSTANCE field is blank, no by-instance-filtering is done when messages are send to this message window. When for a message window the INSTANCE field is not blank, filtering is done by comparing the instance the message refers to to the instance defined in the INSTANCE field. Only one instance can be defined per message window. Currently only messages that refer to measurement checking or (to some extend) to commanding can be filtered. Automatic CEV messages are not currently filtered. 5.16 Passing instance name to trigger procedure (crn 643) --------------------------------------------------------- When a measurement triggers a procedure, the instance of the measurement is passed to the trigger procedure when the following rules are followed: 1 - The instance is last in the procedure variable list; 2 - In the CSTOL statement specified in the TRIGGERS table the instance value is represented by &&& (three ampersands). When this happens, OASIS-CC substitutes the &&& with the instance name (between double quotes). For example assume that in the TRIGGERS table the following statement is found in the record for the measurement s1.perf byte20: start my_trigger 5,10,&&& When the trigger is executed, the following statement is started: start my_trigger 5,10,"s1" Note that the same mechanism is used to pass the instance name to command a pre- or a post-check procedure (see paragraph 4.4.1) 5.17 Faster "switch on" when restore is used (crn 649) --** (NEW) **-- ------------------------------------------------------ The format of the files generated by the save_decomposition_tree utility has been modified. With this change the "switch on" of a stream while restoring its decomposition tree is much faster than in previous versions (however the saving of the decomposition tree takes longer). And above all the decomposition tree takes less memory. For an application with 70 instances the memory gain is around 50M bytes. A limitation has been introduced by this update. An application is now limited at 100 instances. 6 Fast Transfer Mechanism ------------------------- 6.1 Concept ----------- The purpose of the Data Server implementation in OASIS-CC is two folds: (1) Provide a data transfer mechanism that is more efficient that the Bridge subsystem. (2) Provide a mechanism by which OASIS can distribute data on-demand from client processes. In this implementation OASIS-CC acts as a server process that accepts connection and data request from client processes. The client processes request data in the form of data set that are pre-defined in OASIS-CC via the BRIDGE_DEFINITIONS table. 6.2 Interface Specification --------------------------- The interface is specified in $ODIST/include/oasis_data_server.h (see appendix H for a listing of this file). 6.2.1 Client to Data Server --------------------------- After a client process has connected to the OASIS-CC Data Server it can send three types of message to OASIS-CC: ADD_GROUP, REMOVE_GROUP and DISCONNECT. ADD_GROUP is used to request the transmission of specific data set (see paragraph 6.4 on how data sets are defined in OASIS-CC). A client process can request more than one data set at a time. REMOVE_GROUP is used the request the removal of a specific data set from the data transmitted by OASIS-CC to the client process DISCONNECT is used by the client process to warn OASIS-CC that it is disconnecting (If the client disconnect without telling OASIS-CC it's still Ok, as OASIS-CC catches the corresponding signal. However it is cleaner to have the client tell OASIS-CC). The messages from a client to OASIS-CC have the same format: an 32-bit opcode (1 means ADD_GROUP, 2 REMOVE_GROUP and 3 DISCONNECT), a 32-bit version field (that should be set to 0) and 2 16-character fields (the name of the group to be added or removed and its instance. In the DISCONNECT message these fields are ignored). 6.2.2 Data Server to Client -------------------------- The data transmitted by OASIS-CC to a client process consists in a stream of 2 32-bit field. The first field is a tag field that identifies the measurement that is transmitted. It is the hashkey value derived from the measurement instance, external_element and item names and used in OASIS-CC as a key to the measurement LATEST_DATA table record. The utility COMPUTE_HASHKEY can be used to compute a measurement tag from its instance, external_element and item names. The second field is either the measurement DN or EU value. It is the responsibility of the client process to keep track of the type (and unit if an EU value is sent) of each one of the measurements it has requested. From time to time OASIS-CC sends to the client processes data in which the tag is set to zero. These are end-of-frame (or end-of-packet) markers. Data between two end-of-frame (or end-of-packet) markers was collected from the same frame (or packet). 6.3 Starting and Terminating the Data Server -------------------------------------------- The Data Server is controlled using the switch statement. It is started by the statement SWITCH ON DATA_SERVER It is terminated by the statement SWITCH OFF DATA_SERVER When "switched on" the Data Server accepts connection and request messages from up to 100 client processes. When "switched off" it disconnects from all the connected client processes and hibernates until "switched on" again. --** (UPDATED) **-- Note 1: The Data Server stream does not need to be defined in the STREAMS table. Its name (DATA_SERVER) implies the stream. Therefore the name DATA_SERVER should not be used to define a stream. Note 2: In this release the socket number to which the client processes connect is hardcoded to 5010. Note 3: The limit to number of client processes is set to 100. However the maximum we have tested is 20 client processes. --** (NEW) **-- 6.4 Defining a Data Set ----------------------- Data grouping is done using the BRIDGE_DEFINITIONS table. Assume that a client sends an ADD_GROUP request to OASIS for the instance "S1" of a group named "XFER". OASIS searches the BRIGDE_DEFINITIONS table for all the records that have NAME = XFER (The search rule used in the bridge subsystem - see paragraph 4.6 - is also used here). These records define the dataset to transfered to the client. The DATA_TYPE field for each records define the type of data that will be transfered. Currently only DN_DATA or EU_DATA are supported. The UNITS field IS NOT taken into account. If EU_DATA is requested what is send the EU value of the measurement in the unit defined in the LATEST_DATA table record of the measurement. 6.5 Current Limitations and Future Extensions --------------------------------------------- - A client cannot request at the same time the DN and the EU value of a measurement. - The Data Server socket is hardcoded at 5010. - Currently the visibility into the status of the Data Server is very limited. A "show data_server status" statement should be implemented. - There is an hardcoded limit (100) as to how many client processes can be connected at the same time with the Data Server. --** (UPDATED) **-- - Currently the code does not protect a user from checkpointing LATEST_DATA or removing records from LATEST_DATA while the field ROUTE_TO_DATA_SERVER is not set to NEVER. 7 List of changes since last release --** (NEW) **-- ------------------------------------ crn # Title Comment 625a Change in "merge" processing for route_to_xxx flags 632a Change in "remove" processing if resulting file empty 647a Problem with Oasis_CSetInstanceQuality() 649 Faster "switch on" when restore is used see 5.17 651a Faster "switch off" or "record off" for bridges 653 Change in fast_xfer queue treatement when data server is off. Increase of the maximum number of client 8 Known problems ---------------- The following problems are specific to the version 03 of OASIS-CC. 8.1 Oasis command subsystem locks up (crn 588) ---------------------------------------------- The command subsystem locks up under the following conditions: - A command with subfield is requested. - One of the subfield value is expressed via a local variable. - This local variable is not defined. For example: CSTOL > SET S1.TELEMETRY TO $RATE The command subsystem will lock up if $RATE is not defined. 8.2 Global variable not xfered when ROUTE_TO_BRIDGE = ON_CHANGE (crn 603) ------------------------------------------------------------------------- Assume the following conditions: - A global variable with QUALITY_CODE = NO_DATA and ROUTE_TO_BRIDE = ON_CHANGE. - A value of 0 is received for this global variable. The global variable value is not transfered to the bridge subsystem. 8.3 Leak while doing remove/merge (crn 632) ------------------------------------------- The repeated execution of the following statements creates a leak: REMOVE S1 FROM ALL MERGE S1 INTO ALL 8.4 Segmentation fault with user-defined ALERT window (crn 637) --------------------------------------------------------------- OASIS-CC crashes when a user-defined ALERT window is displayed. This only occurs when the OASIS-CC code is compiled with SunAda 3.0 (this version of OASIS-CC is compiled with SunAda 3.0). 8.5 Core dump when Wpt_ViewUpdate of graph item (crn 640) --------------------------------------------------------- OASIS-CC crashes with a core dump when Wpt_ViewUpdate is called on a graph item. Appendix A : CSTOL SYNTAX CHANGES -------------------------------------------------------------------- CLEAR The syntax of the statement CLEAR page_name [FROM terminal_nickname] is changed to CLEAR [instance_name.]page_name [FROM terminal_nickname] where page_name identifies the window to remove instance_name identifies which instance of the window to remove Example: declare variable $s = s1 s1,s2,s3 let $s = s2 ......... clear $s.page_1 from merope -------------------------------------------------------------------- DISPLAY The syntax of the statement DISPLAY page_name [TO terminal_nickname] is changed to DISPLAY [instance_name.]page_name [TO terminal_nickname] where page_name identifies the window to display instance_name identifies which instance of the window to display Example: display s10.page_1 to pollux -------------------------------------------------------------------- LOAD The syntax of the statement LOAD external_element_name AT location FROM filename is changed to LOAD [instance.]external_element_name AT location FROM filename where external_element_name identifies the external element where the load is directed instance identifies to which instance of the external element the load is directed Example load s1.cds at 0 from cds_load_file -------------------------------------------------------------------- MESSAGE The syntax of the statement MESSAGE external_element is changed to MESSAGE [instance.]external_element where external_element_name identifies the external element where the message is directed instance identifies to which instance of the external element the message is directed Example: Message s10.cds -------------------------------------------------------------------- RECORD The syntax of the statement RECORD ON | OFF data_stream is changed to RECORD ON | OFF [instance_name.]data_stream where data_stream identifies the bridge stream to activate or deactivate instance_name identifies which instance of the bridge to activate or deactivate Notes: This syntax applies only to a bridge stream Example: record on s1.test_bridge -------------------------------------------------------------------- SHOW A new pair of attribute-item combination has been added RED LIST -------------------------------------------------------------------- SHOW The syntax SHOW attribute item is changed to SHOW attribute [instance].item This new syntax is only taken into account when attribute = RED and item = LIST. -------------------------------------------------------------------- SNAP The syntax of the statements SNAP pagename [RESOURCE] is changed to SNAP [instance.]pagename [RESOURCE] where page_name identifies the window to be snapped instance_name identifies which instance of the window to snap Example: snap p1.testa -------------------------------------------------------------------- STOP RECORDING The syntax of the statement STOP RECORDING data_stream has been changed to STOP RECORDING [instance.]data_stream where data_stream identifies the bridge stream to deactivate instance_name identifies which instance of the bridge to deactivate Notes: This syntax applies only to a bridge stream Example: stop recording of s1.test_bridge -------------------------------------------------------------------- SWITCH The syntax of the statement SWITCH ON | OFF data_stream is changed to SWITCH ON | OFF [instance_name.]data_stream where data_stream identifies the bridge stream to activate or deactivate instance_name identifies which instance of the bridge to activate or deactivate Notes: This syntax applies only to a bridge stream Example: switch on s1.test_bridge -------------------------------------------------------------------- SWITCH RECORDING The syntax of the statement SWITCH RECORDING OF data_stream is changed to SWITCH RECORDING OF [instance_name.]data_stream data_stream identifies the bridge stream the statement applies to instance_name identifies which instance of the bridge the statement applies to Notes: This syntax applies only to a bridge stream Example: switch recording of s1.test_bridge -------------------------------------------------------------------- COMMAND REQUEST SYNTAX The external element component in a command statement supports the dotted notation. Its syntax is now [instance.]external_element For example: turn on s1.telemetry open s10.valve -------------------------------------------------------------------- REFERENCE TO GLOBAL VARIABLE A global variable name in a logical or arithmetic expression, in a parameter list or in the left side of assignement operator of a LET statement can be expressed using a dotted notation. The syntax is now [instance.]external_element item_name For example: wait raw s1.grating position = 10 dn Appendix B : ADDITIONAL CSTOL STATEMENTS REMOVE REMOVE creates a database-format disk images of selected database table records and deletes those records. Format REMOVE instance_name FROM table_name REMOVE instance_name FROM ALL Arguments instance_name (identifier): name of the instances whose records have to be saved and removed. table_name (identifier): database table from which the records are to be saved and removed. Notes 1. In the second form, all the tables that have an instance field are processed 2. The disk images of the tables are stored in a directory pointed by the variable $instance_name_OASIS_DATABASE (where instance_name is in uppercase). For example: remove s1 from latest_data creates a file called $S1_OASIS_DATABASE/latest_data.dat 3. The first form is equivalent to checkpoint table_name where instance = instance_name delete table_name where instance = instance_name with the following difference: the file created is named $instance_name_OASIS_DATABASE/table_name.dat rather than $OASIS_CHECKPOINT/fyy_mon_doy_hh_mm_ss.table_name -------------------------------------------------------------------- MERGE MERGE loads the contents of files created by a REMOVE statement into the running copy of the database. Syntax MERGE instance_name INTO table_name MERGE instance_name INTO ALL Arguments instance_name (identifier) : name of the instance whose database records have to be merged table_name (identifier) : database table into which the records have to be merged Notes 1. In the second form, all the tables that have an instance field are processed 2. Duplicated records are skipped. 3. MERGE does not check the contents of the files it merges. It assumes that the files located in $instance_name_OASIS_DATABASE have been created by a REMOVE instance statement. Appendix C: 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 D : STREAMS SETUP EXAMPLE This example assumes that a stream receiving data from three identical spacecraft named s1, s2 and s3. Only one socket is used. The following cstol statements load the streams and the latest_data table. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;SECTION 1) External Communications for the TDM data ; ; this section inserts the records required to decompose the ; TDM data. Two streams are involved - a primary stream ; (TDM_RETURN), and a secondary substreams ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;define the primary return stream of TDM data and the node address ; of the receiving (tlm) cpu insert streams stream_name=TLM,processor=extcomm_subsystem,& link_name=tdm_rtn_link,direction=return_stream,protocol=ip,& stream_type=primary,frame_length=4096,sync_pattern_length=16,& sync_pattern="8C8C",time_out="0.05" insert links link_name=TDM_RTN_LINK,data_line="128.138.137.20" ; mirza ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; the next LATEST_DATA records are used by the external_communication ; subsystem as specified in the Generic Communications Guide ; ; stream type: packetized, expressed in byte ; insert latest_data instance = " ", & external_element=TLM,item_name=IS_PACKETIZED,& data_class=numeric,dn_low=1 ; ; instance id definition ; insert latest_data instance = " ", & external_element=TLM,item_name=INS_ID_SIZE,& data_class=numeric,dn_low=1 ; 1 byte insert latest_data instance = " ", & external_element=TLM,item_name=INS_ID_OFFSET,& data_class=numeric,dn_low=5 ; byte #5 ; ; debug level ; insert latest_data instance = " ", & external_element=TLM,item_name=DEBUG_LEVEL,& data_class=numeric,dn_low=0 ; ; socket address ; insert latest_data instance = " ", & external_element=TLM,item_name=SOCKET_ADDRESS,& data_class=numeric,dn_low=5010 ; ; packet id definition ; insert latest_data instance = " ", & external_element=TLM,item_name=ID_OFFSET,& data_class=numeric,dn_low=3 insert latest_data instance = " ",& external_element=TLM,item_name=ID_SIZE,& data_class=numeric,dn_low=1 ; ; packet length information ; insert latest_data instance = " ", & external_element=TLM,item_name=LENGTH_OFFSET,& data_class=numeric,dn_low=4 insert latest_data instance = " ", & external_element=TLM,item_name=LENGTH_SIZE,& data_class=numeric,dn_low=1 insert latest_data instance = " ", & external_element=TLM,item_name=LENGTH_UNIT,& data_class=numeric,dn_low=1 insert latest_data instance = " ", & external_element=TLM,item_name=LENGTH_CORRECTIO,& data_class=numeric,dn_low=4 ; ; client/server mode : client ; insert latest_data instance = " ", & external_element=TLM,item_name=MODE,& data_class=numeric,dn_low=0 ; ; definition of the association between the TLM stream and the instances of ; the generic spacecraft it expects to receive data from ; insert latest_data instance = " ", & external_element=TLM,item_name=INSTANCE_GROUP,& data_class=CHARACTER_STRING; let tlm instance_group ="TEST" ; ; spacecraft s1 ; insert latest_data instance = "$s1", & external_element=test,item_name=INSTANCE_ID,& data_class=numeric,dn_low=1 ; ; spacecraft s2 ; insert latest_data instance = "$s2", & external_element=test,item_name=INSTANCE_ID,& data_class=numeric,dn_low=2 ; ; spacecraft s3 ; insert latest_data instance = "$s3", & external_element=test,item_name=INSTANCE_ID,& data_class=numeric,dn_low=3 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; ; define a secondary stream. It will be used to control the decomposition ; of the data. insert streams stream_name=SEC,processor=extcomm_subsystem,& stream_type=secondary, parent=TLM, frame_length=1024,& direction=return_stream,stream_is_on=false, secondary_offset=1,& id_value=0 Appendix E : COMMAND TABLES SETUP EXAMPLE Following is an example of discrete and digital commands for two indentical spacecraft (s1 and s2). The commands share the same forward stream. The commands contains a spacecraft id, therefore the commands table records are duplicated. They share the same command message format. Another solution could have been to put the spacecraft id in the command message. The command messages records would have been duplicated and the commands records would have been shared. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;SECTION 4) Command ; ; This section builds all the records necessary to send commands ; to the software simulator ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; create the command stream: insert streams stream_name=command,processor=extcomm_subsystem,& link_name=command_link,direction=forward_stream,protocol=ip,& frame_length=128,stream_type=primary ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;insert the LATEST_DATA and LINKS records specified in the Generic ;Communications Guide: insert latest_data instance = " ", external_element=command,item_name=mode,& data_class=numeric,dn_low=0 insert latest_data instance = " ", external_element=command,& item_name=socket_address, data_class=numeric,dn_low=5011 insert links link_name=command_link,data_line="128.138.137.20" ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;define an internal reference for all commands going to the software ;simulator to the command stream they will travel through. s1 and s2 ;commands are being send on the forward stream (command) insert element_characteristics instance = " ", & name=simulator, & stream_name=command ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; define the command envelope for all simulator commands. It is shared ; by s1 and s2. insert command_messages instance = " ", & external_element=simulator,& message_type=realtime, & max_length=128 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; define the commandable elements under the auspices of the simulator: insert element_hierarchies name=testbed, & oldest_ancestor=testbed,& parent="oasis$system" insert element_hierarchies name=simulator, & oldest_ancestor=simulator,& parent=testbed insert element_hierarchies name=telemetry, & parent=simulator, & oldest_ancestor=simulator ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; define the command to turn on the telemetry: ; the cstol directive will be "turn on instance.telemetry" insert commands instance = "s1", & external_element=telemetry, & name=turn_on,& cmd_type=immediate, & is_legal_in_realtime_msg=true,& legal_source=clp, & safety_level=safe, & is_discrete=true,& length=32,& fixed_pattern="00010100" insert commands instance = "s2", & external_element=telemetry, & name=turn_on,& cmd_type=immediate, & is_legal_in_realtime_msg=true,& legal_source=clp, & safety_level=safe, & is_discrete=true,& length=32,& fixed_pattern="00010200" ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; define the command to turn off the simulator: ; the cstol directive will be "disable telemetry" insert commands instance = " ", & external_element=telemetry, & name=disable,& cmd_type=immediate, & is_legal_in_realtime_msg=true,& legal_source=clp, & safety_level=safe, & is_discrete=true,& length=32, & fixed_pattern="0003000" ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; define the serial command to change the TLM rate: ; the cstol directive will be "set instance.telemetry rate to _" insert commands instance ="s1", & external_element=telemetry, name=set_rate,& cmd_type=immediate, & is_legal_in_realtime_msg=true,& legal_source=clp, & safety_level=safe, & is_discrete=false,& length=32, & fixed_pattern="03000001" insert commands instance ="s2", & external_element=telemetry, name=set_rate,& cmd_type=immediate, & is_legal_in_realtime_msg=true,& legal_source=clp, & safety_level=safe, & is_discrete=false,& length=32, & fixed_pattern="03000002" ; ; note that the command maps for the set_rate command is shared ; by s1 and s2 ; insert command_maps instance = " ", & external_element=telemetry, & command_name=set_rate, & subfield_name=to, & command_type=immediate, & segment=1,is_last=true, & source_first_bit=1, & destination_first_bit=9, & source_last_bit=8, & destination_last_bit=16 insert command_values instance = "s1", & order = 0, & external_element=telemetry, & command_name=set_rate, & subfield_name=to, & length=8, & max_value=64.0, & min_value=1.0, & default_value=1.0, & default_safety_level=safe insert command_values instance = "s2", & order = 0, & external_element=telemetry, & command_name=set_rate, & subfield_name=to, & length=8, & max_value=32.0, & min_value=1.0, & default_value=1.0, & default_safety_level=safe Appendix F: 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 *instance; /* name of the instance */ 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 *instance; /* name of the instance */ 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 G: 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, instance); oasis_int value; char *e_name; char *i_name; char *instance; DESCRIPTION This routine sets the DN_LOW field of latest_data record whose external element name is "e_name", item name is "i_name" and instance name is "instance" 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, instance); oasis_int *value; char *e_name; char *i_name; char *instance; DESCRIPTION This routine gets the DN_LOW field of latest_data record whose external element is "e_name", item name is "i_name" and instance name is "instance" 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 H: oasis_data_server.h /* Copyright 1986, 1992 by the Regents of the University of Colorado */ /* History : */ /* Original: developed by aj per crn 586 2/96 */ /* multiple instance version aj 5/96 (see crn 551) */ /* Purpose : */ /* Define constants and structures for data distribution by OASIS */ #ifndef __OASIS_DATA_SERVER_H__ #define __OASIS_DATA_SERVER_H__ /* client request definition */ #define OASIS_ADD_GROUP 1 #define OASIS_REMOVE_GROUP 2 #define OASIS_DISCONNECT 3 #define OASIS_VERSION_0 0 typedef struct client_request { int version; /* version number */ int request_type; /* client request */ char group_name[16]; /* requested data set name - 16 character */ char instance[16]; /* instance requested */ } typedef struct server_data { /* for version 0 */ int hashkey; /* data tag */ int data; /* data value int or float */ } #endif /* __OASIS_DATA_SERVER_H__ */ Appendix I : UPDATED Macro_Defs.C FILE This note summarizes the additions done to the workbench macro file to take advantage of the multiple instance capability. The following macros have been added: EraseInsPanel instance, panel NewInsPanel instance, panel ShowInsItem instance, panel, item HideInsItem instance, panel, item HideInsPanel instance, panel ShowInsPanel instance, panel DimInsItem instance, panel, item UnDimInsItem instance, panel, item SetInstStatic instance, panel, item, to These macros have the same effect as the macros: ErasePanel panel NewPanel panel ShowItem panel, item HideItem panel, item HidePanel panel ShowPanel panel DimItem panel, item UnDimItem panel, item SetStatic panel, item, to except that they apply to a specific instance of a panel rather a "null" instance of a panel. In addition the Wpt_PanelOnXdisplay function has been modified. The instance of the panel to lookup is passed as the last parameter. Example of use: -- Wpt_NewPanel goes here testa_info ->Id = Wpt_PanelOnXDisplay(testa_info,theDisplay,"S1"); if (testa_info->Id) { EraseInsPanel "S1",testa } else { NewInsPanel "S1",testa } -- Wpt_NewPanel goes here wildcard_info->Id = Wpt_PanelOnXDisplay(wildcard_info,theDisplay,0); if (wildcard_info->Id) { ErasePanel wildcard } else { NewPanel wildcard } Note that instance is passed in UPPERCASE. Appendix J : NEW DATABASE TABLE LAYOUT (outside of instances) COMMAND_VALUES Two changes have been introduced (see paragraph 5.7): (1) The SUBFIELD_NAME field is no more a key field; and (2) a new key field called ORDER has been added. For a specific command, ORDER is expected: (1) to be different for each of the command subfield; (2) to start at the value 0; and (3) to increment monotonoulsy for each of the command subfield. Note that ordering of a command subfields via the ORDER field is only a mechanism set up to speed up the command generation when the COMMAND_VALUES table is large. It does not imply anything on the subfields of a command. The top of the COMMAND_VALUES table layout now looks like: INSTANCE unchanged. EXTERNAL_ELEMENT unchanged. COMMAND_NAME unchanged. ORDER order of definition of the subfields of a command starting at 0 KEY Protection class : PROTECTED Data type : INTEGER Default value : 0 SUBFIELD_NAME The subfield name. NON KEY Protection class : PROTECTED Data type : NAME_TYPE Default value : LATEST_DATA To support the "fast transfer" mechanism the LATEST_DATA table layout has been modified (see paragraph 6). A new field called ROUTE_TO_DATA_SERVER has been added after the ROUTE_TO_BRIDGE field ROUTE_TO_DATA_SERVER This internal OASIS-CC system flag indicates if a value is forwarded to the data server subsystem. NON KEY Protection class : PROTECTED Data type : ROUTING_TYPE Default value : NEVER LATEST_DATA The QUALITY_CODE field now takes the values: NO_DATA, GOOD, BAD and STALE. DISPLAY_DESCRIPTIONS A field named INSTANCE has been added between the field DISCRIMINATOR and the field TAE_PANEL_NAME. INSTANCE The contents of this field is used to filter event messages NON KEY Protection class : DB_MANAGER Data type : NAME_TYPE Default value : Appendix K : HIGH LEVEL LANGUAGE ACCESS TO TAE DISPLAY 1 DEFINITION OF THE USER PROVIDED CODE The display subsystem code now calls one routine that is to be provided by the application developer. This routine (Oasis_CModDisplay()) is executed every time a TAE panel is displayed. The distribution comes with a stubbed routine in $ODIST/common_distrib/objects/oasis_display_stub.c. This routine can be used to modify the apparence of a display depending on which instance of the panel is displayed. 2 DEVELOPMENT OF THE USER PROVIDED CODE When linking an application, OASIS-CC expects the user code to be placed in the $OASIS_USER_CODE/libOasisUser.a archive library. This is the same archive library in which OASIS-CC expects the user equation code or the user command code. As for the equation code and/or the command code the script $ODIST/bin/equation_Imakefile.csh can be user to create a makefile to maintain the user code. OASIS-CC is distributed with an archive library that contains stubbed routines. The source code for the stubbed routines can be found in $ODIST/common_distrib/objects. 3 ROUTINE DESCRIPTION Routine name Purpose Oasis_CModDisplay Allow the user access and modify a TAE panel description when the panel is displayed 4 MANUAL PAGES FOR THE ROUTINES NAME Oasis_CModDisplay SYNOPSIS #include "taeconf.inp" #include "wptinc.inp" #include "symtab.inc" #include "parblk.inc" #include "wptmodinc.h" void Oasis_CModDisplay(display , view, target, panel, panel_name, instance) Display *display; char *panel_name; char *instance; Id view; Id panel; Id target; DESCRIPTION This function is called whenever a TAE panel is displayed. 'panel_name' and 'instance' are the panel name and the instance used in the display statement. 'view', 'panel' and 'target' are respectively the view Id, the panel Id and the target Id. 'display' is a pointer to the X display. Refer to the TAE+ Programmer's Manual. Appendix L : ADDITION TO THE EQUATION TOOLBOX (STALE DATA & SMOOTHED DATA) This appendix contains the manual pages for three new routines that have been added to the equation toolbox. The routines are: Name Purpose Oasis_CGetSmoothValue Access the smooth value of a global variable Oasis_CSetDataQuality Set the QUALITY_CODE field of a global variable Oasis_CSetInstanceDataQuality Set the QUALITY_CODE field of all the global variables with a knewn instance. NAME Oasis_CGetSmoothValue - Get the value contained in - the EU_SMOOTHED field value - of a known global variable SYNOPSIS #include int Oasis_CGetEuValue(lock_id, hashed_v, smooth_value, eu_unit); db_lock lock_id; oasis_int hashed_v; oasis_float *smooth_value; char *eu_unit DESCRIPTION This routine returns in the smooth_value variable the value contained in the EU_SMOOTHED field of the latest_data table record whose key is hashed_v (see compute_haskey). The eu_unit parameter returns the value contained in the EU_UNITS field. The lock_id parameter is used to speed access to the latest_data table (see compute_equation). The function returns 1 (success) or 0 (failure, when SMOOTHING_ENABLED is FALSE). eu_unit can be defined as char eu_unit[OASIS_UNIT_SIZE] NAME Oasis_CSetDataQuality - Set the QUALITY_CODE field of - a global variable SYNOPSIS #include void Oasis_CSetDataQuality(lock_id, quality, hashed_v, equation_result); db_lock lock_id; int quality; oasis_int hashed_v; result_list equation_result; DESCRIPTION This routine sets the QUALITY_CODE field of the global variable whose key is hashed_v to the value contained in quality. The legal values for the quality parameter are defined in oasis_equations.h as QUALITY_GOOD, QUALITY_BAD and QUALITY_STALE. NAME Oasis_CSetInstanceDataQuality - Set the QUALITY_CODE field of - all global variable of with known - instance SYNOPSIS #include void Oasis_CSetInstanceDataQuality(lock_id, quality, instance, equation_result); db_lock lock_id; int quality; char *instance; result_list equation_result; DESCRIPTION This routine sets the QUALITY_CODE field of all the global variable whose INSTANCE field is equal to instance to the value contained in quality. The legal values for the quality paraemeter are defined in oasis_equations.h as QUALITY_GOOD, QUALITY_BAD and QUALITY_STALE.