Release Level	5.4
Release Date	2008 10
Revision Level	1.0

RTXPS CourseWare specific functions (ACTIONS)

General functions

init(header, footer, document_root)

Initialises a course, must be called as the first function.
Resets all real-time data related to the current course and current user. Optionally overloads default page header, page footer, and the path which is used for loading documents (from local file system).

The document root parameter is ignore for pages called from DocCentre as it only refer to local pages.

end_lecture(end_url)

Tells to the rtxps system that this is the last action of the current course and it modifies the submit button of the current page in such a way that it leads the user back to the installation main page or to the page specified by the course designer (if end_url is defined),

Display functions

html_display(html_page)

Displays an html page and any embedded imagery or multi-media material referenced.
The source of that page is a file in the local file system. The reference to the page is relative to the document root that is specified in the init() funtion, see below.

dc_display(html_page)

Displays an html page as above.
The source of that page is a document in DocCentre, the argument is the ID for the page as administered by DocCentre.

html_display(html_page, n)

Displays an html page, as above.
The source of that page is a file in the local file system, as above (html_display(). The page displayed will expire after n seconds - n being a descriptor, the second parameter of this function.

The use of the timer (as a Descriptor) includes reading it back in the next ACTION/rules, so that the time spent on a page, and whether or not it timed out, can be used for course sequence control, in particular for components that involve time-critical response under stress.

html_popup(html_page)

Displays an html page in a new browser window (pop-up).
The source of that page is a file in the local file system, referenced as above for html_display().

dc_popup(html_page)

Displays an html page in a new browser window, as above.
The source of that page is a document in Doc Centre, the argument the corresponding page ID.

set_descriptor_value(descriptor_name, value)

Sets a descriptor descriptor_name to values, where value must be a legal string for the Descriptor as defined in the course editor, depending on the TYPE of the Descriptor.

Embedded tests

run_test(test_id, score, header,footer)

Starts the embedded TEST tool. See also: Test Editor Manual
Passes control to test generator. Input parameter test_id uniquely identifies required test. Test generator sets descriptor of score (second parameter) to the number of points which were achived by the user. Optional parameters header and footer overload default document header and footer by those defined by the course designer.

Embedded models

run_MS(substance_class, substance_state, total_mass, wind_direction, impact_factor)

Runs the Metodo Speditivo model fast assessment.

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

Generic model interface

The generic model interface provide three main functions to:
1. Select and modify (partialy overload) a set of model input files
2. Execute (run) the model on the local RTXPS server
3. Read the model output into the knowledge base for further use in normal HTML pages.

set_input(template_name,input file)

Rtxps reads a template file (first parameter) currently located in /acad2/RISC/models/templates. Templates contain descriptor names, their values and units:

Spill_duration          2               min
Feed_rate               45.8            l/s
Storage_temperature     0               oC
Fire_type               pool
Confinement             no
Pool_diameter           2.5             m
Trench_length           20.0            m
Trench_width            3.0             m
Trench_orientation      0.0             deg

Rtxps creates a new file (supposedly a model input file) in /acad2/RISC/models/inputs which contains the same sequence of the descriptors as in the template file but with updated descriptor values for all descriptors which have a defined value within the current session.

read_output(filename)

Rtxps reads a file containing descriptor values (same format as in case of set_input) and updates values of descriptors which have been defined in the current session. Output files are expected in /acad2/RISC/models/outputs.

run_executable(executeable_name,input_file,output_file)

Rtxps runs specified executable (using system call) on the foreground (it waits for its termination). It passes input file name and output file name to the executable as parameters (argv[1] and argv[2]). Executable which can be run by rtxps are located in /acad2/RISC/models/bin.

External models

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

Interface to the case Based Reasoning Server
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_display()

Same as previous but with a predifined parameter list consisting of: 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

Control functions

They relate to two main concepts:
1. TIMERS that make it possible to manipulate TIME, real, absolute, simulated as part of the scenario control and the HTML display;
2. SAVEPOINTS that make the repeated use of ACTION groups possibel, i.e., to repeatdly run through a given sequence based on a test or model scenario result;

For more details on the manipulation of time in RTXPS, see: timers.

set_time(descriptor)

Sets the value of descriptor to current time; OThe timer descriptor is of type variable and represented by a string with the fomat hh:mm:ss

elapsed_time(descriptor)

Elapsed time since course was started
Elapsed_time(descriptor) sets the specified descriptor to relative time or time elapsed since the last init() was called. Value of that descriptor can be diplayed or used in time computation.

add_time(time1,time2,time3)

Function add_time(time1,time2,time3) implements operation: time1 = time2 + time3. Variables time1, time2, and time3 are of type timer (hh:mm:ss).

subst_time(time1,time2,time3)

Function subst_time(time1,time2,time3) implements operation: time1 = time2 - time3. Variables time1, time2, and time3 are of type timer (hh:mm:ss).

create_savepoint(savepoint_name)

Defines a fixed point or label in the dynamic knowledge base.
Creates a copy of descriptor values and action states which is course and user specific, or a label in the dynamic knowledge base corresponding to the state of the system at that point in time (and rule sequence). It can be restored with read_savepoint(savepoint_name), in the manner of a GOTO statement of procedural programming languages.

Implementation details:
Both descriptor and action values are saved in a database table called savepoints. The structure of that table is the same as the one of rdescriptors and raction - extended by type being D (descriptor), A (action) and svpname - name of that save point.

read_savepoint(savepoint_name)

Restores a savepoint. The forward chaining sequence will resume at the savepoint, i.e., at the state of the system at the point when the safepoint was defined. ALl subsequent ACTIONS will be discarded. This cycle can be repeated any number of times.