Release Level	5.4
Release Date	2008 10
Revision Level	1.0

RTXPS/CourseWare

1. IMPLEMENTATION
   describes the files and directories and alternative data base used by RTXPS:
   • data files (organised in a KB directory, consisting of a KBconfig file and at least one of each for ACTIONS, RULES, DESCRIPTORS.

     The data files are found under a directory on the http server specified by a configuration file: A-TEAM-dev.path in the servers cgi-bin directory. Each course's knowledge base is stored in an individual sub-directory, identified by the course name
     [NOTE: course names must therefor be valid UNIX directory names !].

   • ORACLE data base where the corresponding information is stored; access to the data base is through the Java editor tools;

     The data base is implemented on the server 80.120.147.30, It includes three major tables, namely

     • ACTIONS
     • RULES
     • DSECRIPTORS
     corresponding to the file structure.

   To generate a hardcopy (print-out) of a given course knowledge base from the data base, a utility cgi extracts all data related to a given course and generates a simple HTML page suitable for printing.

2. Current implementation status:
   • User authentication
   • Running courses

3. RTXPS: ACTIONS, RULES, FUNCTIONS:

   RTXPS ACTIONS use embedded functions to:

   • display html/mm content in the basic page or a pop-up;
   • trigger specific fundtions such as the emergency simulation models, or the CBR server;
   • start a questionnaire;
   • terminate a course session.

4. SEQUENCING and TIMERS:

   Rtxps generates 3 buttons on every page; they will eventually be integrated in the header part:

   1. Submit - leads to the next page of the current course
   2. Stop - stops counting time and leads to the ateam root page
   3. Abort - deletes state of the current course for the current user and leads to the ateam root page
   There are 3 predefined descriptors relating to TIME:
   1. START_TIME,
   2. CURRENT_TIME,
   3. ELAPSED_TIME
   Their definition is as follows (from /acad2/RTXPS/dyn/TIMEdescriptors):

   
   DESCRIPTOR
   START_TIME
   T V
   Q start time of an emergency, arbitrary string
   ENDDESCRIPTOR
   
   DESCRIPTOR
   CURRENT_TIME
   T V
   Q start time of an emergency, arbitrary string
   ENDDESCRIPTOR
   
   DESCRIPTOR
   ELAPSED_TIME
   T V
   Q start time of an emergency, arbitrary string
   ENDDESCRIPTOR
   

   The Directory /acad2/RTXPS/dyn is used as a temporary directory for knowledge base files created on the fly. In the moment it contains two permanent files:

   • KBconfig and
   • TIMEdescriptors.
   Rtxps first creates dynamic knowledge base, then sets predifined descriptors to their current values. START_TIME and ELAPSED_TIME rely on the fact that courses start with init() function.

   These descriptors can be used for computation as well as display. Behaviour of value(ELAPSED_TIME) is equivalent to header in-text function \elapsed_time and behaviour of value(CURRENT_TIME) is equivalent to header in-text function \time.

   In addition the user can define application specific time descriptors and set their value by rtxps function set_time(descriptor_name). All time descriptors can be displayed with rtxps in-text function \value whose format is hh:mm:ss or with rtxps in-text function \valuef which displays an integer number in seconds. There are two operations defined for time descriptors:

   • addition:   add_time(result,operand1,operand2)
   • substraction:   subst_time(result,operand1,operand2)

   Header: can contain any html feature like icons; besides there are 3 rtxps specific in-text functions defined:

   1. \user   displays the current user name;
   2. \time   displays the current time;
   3. \elapsed_time   displays the elapsed time since starting the couse/session with init()

5. SIMULATION MODELS:

   The embedded simulation models use a standard, generic interface with RTXPS. The basic logic and implementation is as follows:

   1. For each model type, there is a (set of) scenario file(s) that contain a list of input variables, in the form of Descriptors (which can include references to other, more complex files and data structures such as images, background maps, DEM, time series of forcings, etc.

      Please note: currently, the definition of the input (and output) Descriptors must be included in the respective course knowledge base. In a future stage, these descriptor will be available automatically, provided the default names are used !

   2. When the model is run,
      • any Descriptor currently in the KB will overload its equivalent default value in the scenario: this is how the scenario can be changed interactively, by placing the appropriate set of \ask, \askf statements in a scenario editing page before the model is run !
      • the model is executed with the ionputs defined in the scenario file(s) and the current set of descriptors;
      • the model places its output onto the server; the output consists of one output file that again contains a list of Descriptors, as well as images referred to be some of these Descriptors: this is how the results can be incorporated in subsequent pages (or RULES !) through \value, \valuef statements, in combination with IMG tags that use the value of the appropriate Descriptors as their SRC term: <IMG SRC="\value(model_result_image)":>

   Embedded model interface components:

   Generic Model Interface

   run_MS():

   Metodo Speditivo, quick assessment model run_MS(substance_class, substance_state, total_mass, wind_direction, impact_factor) Runs Metodo Speditivo model. Returns values for descriptors: radius1, radius2, area1, area2, exposure1, and exposure2 if they have been defined run_MS() Runs Metodo Speditivo model with predefined descriptors: substance_class, substance_state, total_mass, wind_direction, and impact_factor Returns values for descriptors: radius1, radius2, area1, area2, exposure1, and exposure2 if they have been defined

6. EXTERNAL SERVER INTERFACE
   1. DocCentre Interface
      1. Functions to retrieve HTML pages from DocCentre, see above;

      User and session management:

      user authentication

      
      http://ateam.chiron.pt/pls/dcourse/check_user?slogin=DGAC01&pwd=DGAC01
       
      Checks if the user exists and if the password is correct. The result is
       
      
       <RESULT>
          <TYPE>XXX</TYPE>
       </RESULT>
      
       
      Where XXX is the top profile of the user, i.e. the one with the largest
      set of privileges.
      
       -1 user/pwd not correct
       0
       1
       2
       3
       4 student
      

   2. CBR server Interface

      cbr_display(i_accident_location, i_calorific_power, i_time, i_height,
                         o_accident_location, o_calorific_power, o_time, o_height,
                         o_case)
      

      Retrieves case_id and other characteristics of a precomputed case that was identified as the one having the smalles distance in parameter space from the case required.
      i_* are inputs, o_* outputs

      cbr_run()

      Runs cbr_display() silently,
      

      i_accident_location, i_calorific_power, i_time, i_height,
      o_accident_location, o_calorific_power, o_time, o_height,
      o_case
      
      i_* are inputs, o_* outputs
      

7. HTML Embedded functions

   \value(DESCRIPTORNAME)	displays the currrent symbolic value for the named DESCRIPTOR
   \valuef(DESCRIPTORNAME)	displays the current numeric value for the named DESCRIPTOR
   \ask(DESCRIPTORNAME)	generated a dialog box to edit/enter the value for a DESCRIPTOR
   \askf(DESCRIPTORNAME)	generated a slider to edit/enter the value for a DESCRIPTOR; under development
   \cbr_image(parameter, timestep)	loads and inserts an image defined by parameter (temperature or tracer) and time step for the current case: cbr_run or cbr_display() must bee run before this function can be used !

8. CONTENT EDITING

   Use your favourite HTML editor, submit the file to DocCentre.

   Alternatively, for implementations with a local server and limited network access, RTXPS also supports functions that can load HTML files from the local server.