EuroSim FAQs

 How is the real-time performance achieved with IRIX, a Unix OS? 
As Unix is not preemptable in general, what is the latency time 
for activation of a process after an interrupt?

In order to provide a real-time environment, EuroSim uses the SGI IRIX 
real-time REACT extensions. Because the implementation of POSIX threads
is in general not sufficient to meet the real-time requirements 
imposed by simulators based on EuroSim, EuroSim has a proprietary thread 
implementation that provides a more efficient response. 
(See also Scheduling model?.)

The system requirements state that a task should be activated within 0.2
msec wall-clock time from a hardware interrupt occurring, and within 
20 msec wall-clock time from an event being raised from model code.

I have a large model: is there an easy way to home in on
a particular section without having to either a) "show all" 
which can become a bit "crowded"  or b) double-click my way down the 
required branch which is tedious?

Try the ModelEditor's Edit | Find Nodes... menu option. You can keep
repeating the find by clicking the "Find" button again.

PS. When viewing the API in the Simulation Controller or Schedule Editor
You can click on it (to give it focus) and then just type the name of the
part you are interested in.

I want to schedule a procedure which has arguments, but
I can't make an entrypoint from it. 

When the ApiEditor scans your source code, only those
procedures which have no return values and no arguments will
appear in the "list" of those potentially available as
entrypoints.  The trick to make them accessible is to make a 
small wrapper that maps those arguments and the return value 
onto API variables, and allows you to create a void proc(void)
interface.

For example:

Suppose you have a sub-model A, providing a function TeleCommand:

	file A.c:
	int TeleCommand(int a, int b, float c) {
        	blah blah
	}


This function is not directly schedulable as it does not meet the
API requirements for entrypoints. But an API compliant wrapper 
(mainTeleCommand) can be provided in file A.c as follows:

	file A.c:
	int TeleCommand(int a, int b, float c) {
        	blah blah
	}

	static int a;
	static int b;
	static float c;
	static int rTC;

	void mainTeleCommand(void) {
	        rTC = TeleCommand(a, b, c);
	}

This file can then be "APIfied"  so that a, b, c, rTC and 
mainTeleCommand appear as API variables and an entrypoint 
respectively in the data dictionary.  This allows the entrypoint 
to be scheduled, and the values for the arguments to be set via 
MDL actions or from within the code still.

The same principle can also be applied to 
Calling functions from mdl?.

Is it true that I can call model tasks and functions directly
from MDL?

 Yes, the following examples show how to use the "exec" mdl 
command in the <Action to be executed:> section of a script
action definition:

   # Example 1
   # execute a schedule task directly
   exec "task:startApproach"

   # Example 2
   # execute an entrypoint directly
   exec "entry:resetOBSW"

(See also Executing entrypoints from mdl?.)

If the procedure that you wish to execute has arguments, then make
a wrapper for it as described in An entrypoint with args?. Then
the usual approach is to provide the "arguments" via the appropriate
API values, followed by a call to the entrypoint, as shown here
using the example described in An entrypoint with args?:

   # Example 3
   # set TC parameters
   :software:A.c:mainTeleCommand:a = 10
   :software:A.c:mainTeleCommand:b = 20
   :software:A.c:mainTeleCommand:c = 3.14
   # call the function (which uses these values)
   exec "entry:mainTeleCommand"
   # print TC result to log
   print "mdlTC=", :software:A.c:mainTeleCommand:rTC

 I can't close the plot windows opened by the PV-WAVE plot backend.

 This is a PV-WAVE "feature". You cannot close PV-WAVE plot windows
using the methods provided by your favourite window manager. The only way
to close these windows is by selecting the corresponding plot icon in the
Test Analyzer and selecting 'Plot | Close Plot(s)...'.

When I try to build my model I get an error message:
   'Fatal error: Can't open temporary formatfile'
   What is going wrong?

The current version (Mk3-rev1) of the language parse utilities of
EuroSim for Windows create a temp file in the root directory of
the current drive. If you do not have sufficient (write) priviliges,
then you get this error message. Future versions of the utilities
will use the TEMP environment variable.

An error is reported when using the EuroSim python interface on Debian 3.1

This is a problem in the Python module that is shipped with the Debian 3.1 release.
See also http://cvs.sourceforge.net/viewcvs.py/swig/SWIG/Lib/python/pystrbase.swg.
Revision 1.9 of pystrbase.swg contains the fix.

You can manually fix it or simply install a more recent Python package.

Can I change the frequency of the data monitors?

The monitoring frequency is fixed at 2Hz, which is adequate for
the on-line displays.  If you require a higher sampling rate, then
the data should be recorded to file (tip: recorder files can be added on
the "Script Monitors" tabpage in the Simulation Controller).

Changing the frequency of a recorder leads to loss of data?

When changing the frequency of recorder actions the recorder starts
recording data from scratch. This means that all previously recorded
data is lost. This is caused by the way EuroSim processes changes in
actions. The old action is deleted first and then added back again with
the new frequency. This means that the new action will open a new
recorder file overwriting the old one.

How can I build a simulator from the command line ?
Is there a Makefile example ?
simulator?

You can build a simulator from the command line by
calling the EuroSim build commands directly from a
makefile. The following example shows typical make production
rules for this:

# first set the name of your model:
MODEL=mymodel

all: $(MODEL).make
	$(MAKE) -f $(MODEL).make all
	

# Generate a EuroSim makefile $(MODEL).mk from model:
$(MODEL).make: $(MODEL).model
	ModelMake $< $@

clean:
	$(MAKE) -f $(MODEL).make clean
	$(RM) $(MODEL).make
	$(RM) -r 200?-* core

# purify targets
pure: $(MODEL).exe
	purify $? && mv $?.pure $?

How can I set compiler flags?

Any user specific compiler flags can be set in the compile options
section of the ModelEditor's "Tools | Set Build Options..." form.

Tip: try using '-xansi -fullwarn' flags in the ANSI-C field in
order to be SGI extended and ANSI-C compliant.  

What is the difference between condensed and non-condensed view in the Dict 
Browsers?  Is there any impact of choosing one over the other?

An API reference can take one of two forms:

a) non-condensed
   All variables and entrypoints are visible, as is the full structure of the
   model, as created by the Model Editor.  When a variable or entrypoint is
   selected, it will get the full path as its reference.  This consists of the form:
   	/one_or_more_org_nodes/file_node/entrypoint  or 
  	/one_or_more_org_nodes/file_node/entrypoint/var (for vars with proc scope)
  	/one_or_more_org_nodes/file_node/var            (for vars with file scope)

b) condensed
   Only variables and organisation nodes are visible, so the Test Conductor is
   not overwhelmed with the model, but can concentrate on the vars which the
   Model Editor has made available for him to manipulate.  The variable gets
   a condensed version of the path as its reference, which consists of the
   form:
	one_or_more_org_nodes/var


In most cases, as a TestConductor, you don't need to know the actual source files
that the API items were derived from, and can simply use the shorter (condensed)
references for monitoring, to make recordings from, to alter the values of, etc.

There are two cases however where the non condensed view is the preferred one:

1. If the Model Developer has tagged two variables in different files which have 
the same name then the reference in the condensed view is ambiguous.  By switching
to the non-condensed view you will get a unique reference for that variable.  

For example:

non-condensed		        condensed

/orgNodeA/file1.c/count         /orgNodeA/count
/orgNodeA/file2.c/count         /orgNodeA/count

2. If you wish to activate an entrypoint directly from an action, then you
need to switch to non condensed view in order to see the names of the entrypoints.
See Executing entrypoints from mdl?.

Can you configure the simulation before each run eg. add or 
remove sub-models? 

 Changes to the content of the model (ie. to its sub-models 
(= source code files)) require recompilation of the simulator.  
However if you wish to keep the same executable each time, then 
there are two ways of achieving this.  Both require that all possible 
tasks need to be defined in model development (eg. a task triggering 
a hifi approach sub-model procedure for a rendezvous and docking 
simulation, and a low fidelity version).

1. Both versions of the task are scheduled, but then you use the 
function of enabling/disabling tasks to alter the runtime 
configuration.  This can be:

a) done manually during a run (after initialisation, or during actual
   execution using the Simulation Controller's Schedule tabpage and the
   Debug menu)

b) controlled via an mdl script (an action in the mission), so that 
   the switch occurs when a particular value is reached, eg. when the 
   spacecraft distance from the target is less than a predetermined 
   value.

   # Example mdl script
   <Execution Condition:>
   :some:api:spacecraftDistanceFromTarget < 100.0

   <Action to be executed:>
   deactivate "task:<lowfi task name>"
   activate   "task:<hifi  task name>"

   Note: when a task is disabled, all the tasks which are shown in the
   schedule definition as having a dependency on this task (ie. those
   "downstream" of it) will also no longer be scheduled.

2. Two schedules are produced, one for each situation; either of these 
can be used with the executable without having to recompile.  So the 
configuration of a simulation can be altered by selecting a schedule 
which only schedules the required tasks (sets of sub-model entrypoints).
You can easily switch schedules in the Simulation controller by selecting the
schedule file on the "Input Files" tabpage and choosing "File | Select 
Schedule...".

When I try to execute a simulation, I get a "could not connect 
to simulator" error message.  What does this mean? 

 It means that the Simulation Controller has not managed to success-
fully launch the simulation, and/or to connect itself as client to that
simulation server.  There are several reasons for this, and you need
to look in the esim-daemon log to see why the connection has failed.
The log is by default in /var/adm/esimd.log (IRIX),
/var/log/esimd.log (Linux) or the Application Event Log 
(Windows: Start | Administrative Tools | Event Viewer).
If it's not there, then the output can be found by looking for an esimd
process in the ps listing for that host (or ask your system manager).

The startup of a simulator with all its parameters is logged in
/var/adm/SYSLOG (IRIX), /var/log/messages (Linux) or the Application Event
Log (Windows). Check the arguments for unexpected values (especially path-
names). If there are shared library problems you will find them here as well.

The simulator executable may also be low on locked memory. In that case you
can specify a global value using the EFO_SHAREDMEMSIZE environment variable.
You can also set a simulator specific value in the ModelEditor using the
Tools | Set Build Options menu command. The default value is 4194304 bytes.

If it looks like a privilege problem then see 
Nfs and running simulators?.  

If there's a problem with schedule registration, try going back to the Model-
Editor, and using Tools | Cleanup, followed by rebuilding with Tools | Build All.

EuroSim consumes the full colormap of my display and doesn't allow to see
proper colors in the applications launched after it. How can I change the
number of colors the EuroSim applications are using?

EuroSim makes use of the Qt library, which supports the following command
line options when running the X11 version (i.e. Linux or IRIX). You can
specify them on the command-line when starting EuroSim:

-visual TrueColor, forces the application to use a TrueColor visual
 on an 8-bit display. 
-ncols count, limits the number of colors allocated in the color cube
 on an 8-bit display, if the application is using the QApplication::ManyColor
 color specification. If count is 216 then a 6x6x6 color cube is used (i.e. 6
 levels of red, 6 of green, and 6 of blue); for other values, a cube
 approximately proportional to a 2x3x1 cube is used. 
-cmap, causes the application to install a private color map on an 8-bit display. 

Other options that may be of use:

-display display, sets the X display (default is $DISPLAY). 
-fn or -font font, defines the application font. The font should 
 be specified using an X logical font description. 
-bg or -background color, sets the default background color and an
 application palette (light and dark shades are calculated). 
-fg or -foreground color, sets the default foreground color. 
-btn or -button color, sets the default button color. 
-name name, sets the application name. 
-title title, sets the application title (caption). 
-style= style, sets the application GUI style. Possible values are motif,
 windows, and platinum.

efoList and others not found under Debian?

This is because efoList and other EuroSim command line
utilities are installed in /usr/EuroSim/bin, which is not part of the
PATH environment variable on a Debian distribution by default. This
is a Debian policy.

You can find more information on this subject in /usr/share/doc/base-files/FAQ
on a Debian system.

There is a simple work-around: start the EuroSim Project Manager with the
'esim' command. This utility is installed in /usr/bin and sets the proper
environment variables. If you then start a new shell from the Project Manager
with the Tools:Shell command, you have an environment that you can use to
run the EuroSim command line utilities.

Alternatively you can add the following two lines to the .bashrc file in
your home directory:
export EFOROOT=/usr/EuroSim
export PATH=$EFOROOT/bin:$PATH

How do I activate an entrypoint directly from mdl?

By using the following mdl command:

exec "entry:<entrypoint name>"

The entrypoint name should be just the name of the actual
procedure (ie. without path information).  So if you drag&drop
the name from the dictbrowser, you need to remove the path
information.  The full name drop is provided because it can be 
useful eg. for including within a print statement in the same
action which writes the full path to the log for information.

See also Calling functions from mdl?.

How does EuroSim support interrupt handling when using
hardware-in-the-loop?

There are several options (assuming of course that your 
platform supports external interrupts), depending on what
the interrupts are to be used for:

- sub-model code can generate output interrupts to a 
  specified SGI output connector, eg. esimEIPulse

- sub-model code can request a poll for outstanding interrupts 
  on the /dev/ei device and dequeue one if available

- you can create an external event handler in the Schedule
  Editor. When using the 'default dispatcher', the editor
  will create a corresponding input connector that can be
  picked from the 'Insert' menu or from the toolbar. Note
  that in Mk3 there no longer is a special EI input connector,
  you have to create an external event handler for it.

- you can install a user defined handler for incoming
  interrupts for a "direct" response, see 'man esimEH(3)'

- you can use input interrupts as the (external)  realtime
  clock  of  the  scheduler,  instead  of the default itimer
  mechanism

Refer to esimEH(3) and esimEI(3) manpages for a more complete
description of the possibilities and limitations.

My external simulator access isn't working correctly.  Are there
built-in debug facilities that I can use?

The following debug flags are available:

ext_client_debug_flag
ext_server_debug_flag
ext_compress_debug_flag
ext_export_debug_flag
ext_sim_debug_flag
ext_view_debug_flag

To set one or more of these on, then put the following lines
in a function to be executed during initialisation, 
eg. for ext_server_debug_flag:

  extern bool ext_server_debug_flag;
  ext_server_debug_flag=true;

Note that the client/server flags are only relevant in the
code on the appropriate "side", whilst the others will activate
debug feedback in both client and server code.

Can I fork a process in my model code?

First the insurance clauses!

1. We do not support doing system calls from model code; simply because
there would be no way to guarantee real-time behaviour of the simulator.

2. The forked process will not run (hard) real-time.

3. If (sysv; brrr) semaphores are subsequently used from within the hard 
real-time model code with the forked process, we cannot assure real-time 
behaviour and prevention of deadlocks.

Now the good news!  If you're still convinced that you need to fork a 
process, it can be done in the following way:

1. Create a task on your schedule canvas containing an 'entry_point' that 
   will do the fork. Add a 'static int beenhere' to that entry point to 
   assure that the fork is only done once.
   [Never ever exit the parent process]

2. Connect a STATE_ENTRY input connector to a non-realtime task that gets 
   the name of the newly created task. Do this on the 'initialising' state 
   canvas.

EuroSim is now installed - is there a fast way to get something 
running?

There are several examples in $EFOROOT/src.  The best ones are:

- Satellite: which is also the one used in the manual, so you have a
description and a fallback for checking on what you should be seeing;

- TmTc+ExtSimModel/SpaceStation: this is part of a simulation used to
demonstrate connection to another simulator, but can also be used as a
stand-alone EuroSim simulation.  There's no documentation though (mainly
because it's the model used for the training course, and people are given
the documentation then).  But basically, it's a simulation of a 2D array of
cells, each of which has a heater and a sensor, and an OBSW module which
monitors the sensed temperatures and turns each of the heaters on and off
according to the setpoints.

To be able to access eg. Satellite from EuroSim, try the 
following steps (it's not as bad as it looks! but the description 
is detailed so that hopefully it'll work the first time....):

set up a new (personal) project
===============================
$ mkdir  $HOME/simulations

Now, copy the model of interest to your simulations directory:
$ cp -r $EFOROOT/src/Satellite $HOME/simulations
$ chmod -R +w $HOME/simulations

Start EuroSim:
$ esim

- select File | Add Project
  The Add Project dialog box will appear.

- Fill in the name (e.g. Satellite) and click the Browse button next to the
  directory field.
  Browse to the copied Satellite directory and press OK.

- Optionally, fill in a project description in the Description field.

- Click OK.

- Choose File | Add Model... browse to the model file and click "Open".

- Add project files: Choose File | Add Files... and the project files you 
want. You can select multiple files by keeping the CTRL button pressed while
clicking on the file names. Click "Add" when done.

start playing with the project
==============================
The name of your newly created project ("SatelliteDemo") should now
appear in the top left of the Project Manager window.

Double click the model file and the Model Editor will start. 
  Enjoy!

My Action Manager task appears to cause a real-time overrun
during simulation.

By default, the Action Manager task (an internal EuroSim task
which coordinates mission execution, recording, etc) is scheduled
to execute after completion of all the user tasks (ie. the ones
defined in your schedule).  This means that the Action Manager 
task gets "blamed" for any overruns occurring within a particular
timeslot.  The real culprit is likely to be one of the earlier
user tasks which needed an excessive amount of execution time, but
which had no (user defined) limit on its allowed execution time.

What libraries are available to support hardware-in-the-loop
interfacing?

Interface libraries are available to support:

- RS232/422
- MIL1553
- TCP/IP
- external interrupts
- External Simulator Access (communicate with an external client via TCP/IP)

See esimSerial(3), esimMil1553(3), esimEI(3), extClient(3) manpages.

There is one study using CORBA to access a few parts of EuroSim but
this use is strictly in the off-line model building/version
control/traceability area. There is no link with the real-time
domain. The CORBA support is not available in off-the-shelf
EuroSim. Contact EuroSim Product Support for more information.

There has also been a study into DIS extensions, the user of which 
requires an additional VR-Link license.  Again, this support is not 
available in the off-the-shelf EuroSim, but can be discussed on
request.

How can I initialise an array variable? 

There are two ways of doing this:

1.  Use the Simulation Controller :
    In the Simulation Controller, select the initial conditions file on the 
    "Input Files" tabpage. Choose Edit | Properties and you can enter the
    initial conditions. For large arrays, this can be a bit tedious.
    
    Using this method, the initial condition file needs to
    be set to active ( Edit | Activate ). The values will then be 
    automatically applied at initialisation time.

2.  using an MDL action script : 
    this gives more freedom, by allowing individual elements of an 
    array to be set or using for-loops to initialise particular 
    rows/columns of the array, and by allowing absolute values to be
    given or allowing a functional definition.  
	
    Using this method, you must remember to execute the action; this 
    can be done by:
    a) triggering the action manually before starting the run
    b) triggering the action via a command in another action
       (activate "myInitAction")
    c) adding an appropriate condition to allow automatic execution
       (see Example 3 below)

    Examples of possible action scripts are:   

    # Example 1
    # set an individual element to an absolute value
    <Action to be executed:>
    y[1][0]=10

    # Example 2
    # set a row of an array, incrementing the value each time
    # and writing the setting to the log
    <Action to be executed:>
    initValue = 10
    i = 0 
    for (i = 0; i < 10; i = i+1) {
         a[1][i] = initValue
         print "a{1][",i,"] initialised to ", initValue
         initValue = initValue + 1
    }

    # Example 3
    # attributes for action to cause it to be automatically
    # executed when initialising state is reached, and then
    # for it to disable itself
    <Action execution options:>
    Initialising should be checked
    <Execution Condition:>
    1
    <Action to be executed:>
    y[1][0]=10
    deactivate "<this action's name>"

I want to know when my procedure has run, but I get a single message
to the log ("proc X has completed") followed by "last message repeated 
10 times".

The log messages are filtered for duplicates, to prevent the log
being overrun with duplicate error messages for example.  However, the
implemented mechanism will also filter out "duplicate" messages 
which are genuinely required, as described above. 

If the messages are required to be logged individually, the simplest
way is to add simtime to the message content to ensure that they 
"differ" and all appear at the Test Controller interface. An example
of this for use from within model source code is:

double sim_time = esimGetSimtime();
esimMessage("powerInit completed: %s", sim_time);

A similar trick in an MDL action would be to have the following
at the end of the action script:

print "myAction completed: ", time()

The SUM mentions a constraint when using mixed language code (eg.
F77 calling C or viceversa). Is this only applicable to the part of 
code that is directly visible to the Eurosim environment or it is
applicable to the whole code required by a particular model?

The constraint is a result of compiler conventions not
EuroSim tools, and therefore is applicable to all of the code within a
particular model.  For the Irix compilers on SGI platforms, this means that
Fortran variables can be referenced within C source by appending an
underscore to the C variable name.  A more detailed example/explanation of
its use is given in the SUM (section 4.6).

I'm having problems starting a simulation (messages about permission 
conflicts), but the files seem to have the correct user/group privileges
set.  Could it have something to do with the fact that the files are in
an NFS mounted directory?

Short explanation: yes, it's a strong possibility!
Longer explanation: if your directory is NFS mounted, and the NFS server
did not specify the root option to make you root on the host
which mounts this file system, and the permissions of the file to be 
read are set to be not world-readable, then the root uid is mapped to 
nobody which will result in a denied permission situation.

To confirm, try mimicking the behaviour of the daemon/simulator to
find out where exactly the permission is denied. So become superuser, 
go to the daemon's directory ('ps -ef | grep esimd' will show you where
it's being run from) and try to read the file.

I can't set breakpoints or traces and I can't enable/disable tasks!

Were you running in real-time?  Because this feature is only 
available when running non real-time.

When I try to execute a simulation, I get the message that 
my current host cannot be used as a server.  And trying to list
the available servers, I get a similar message that there appear 
to be no suitable servers.

 It sounds like the EuroSim server (daemon) running on your 
machine is no longer active and/or your licence key is invalid.

The licence key sent with your installation is derived from the
host details sent with your licence application, and will have
a limited validity period.  If EuroSim is installed on another 
machine or if the validity period has expired, then the key will 
be invalid and it will not be possible to use EuroSim.   To 
obtain a new licence key, send the outputs of your sysinfo(1) 
and hostname(1) commands to EuroSim Product Support 
(e-mail: esim-info@dutchspace.nl).

Alternatively, has the daemon process have been stopped for any 
reason (eg. maintenance activities)?  You should have a process 
called $EFOROOT/etc/esimd running on your host.  If not, then it 
just needs to be restarted.  This is described in the 
OM (section 4.2); you probably just need to check the config flag 
and start the daemon as described in steps 4 and 6 (you need 
root permissions for this btw).

When I run my simulator (server) and client on different hosts,
there is no exchange of Tm/Tc data. When I run both on the same
host, it all works as expected.

This is probably caused by bad time synchronization of the hosts.
Check with your system administrator that both hosts use a (the
same) time synchronization mechanism.

How can I read in a data file during initialisation, ie. directly
in model code rather than via an Initial Condition File?

The following has been successfully been used in a couple of 
projects:

1. In your model code, you need:
   - to define a subroutine to read the file
   - to tag this subroutine as an entrypoint using the API Editor
   - to signal when the routine is complete by raising an event (from 
     the source code) before returning (eg. use esimRaiseEvent("FileRead") 
     (see esim(3) manpage for details of esimRaiseEvent)).

2. On your scheduling graph for initialisation, you need to make:
   - a connection from an input connector for "STATE_ENTRY" to a 
     non-realtime task containing your entrypoint 
     (ie. use an arrow to join the two symbols)
   - a connection from an input connector named after your raised event 
     (eg. "FileRead") to either other initialisation tasks or (if no 
     more initialisation is necessary) to an output connector named 
     "PAUSE"

This means that as soon as initialising begins, the file will be read in as
a result of the subroutine name being called via the appropriate output
connector.  When the file read is complete, the raised event will trigger
the remainder of the initialising graph tasks (or can lead to state exit as
required).

The SimulationController says that my simulation is NOT reproducible, 
while the ModelEditor said that it was!  When I ask the SimulationController
for Versioning: Check Reproducibility, the given reason is that the
dict was supposedly generated from a temp model, which it wasn't! 

The reason for this is that the relevant model file is an 
old version. When you request that a particular version of 
mine.model is opened, this is (secretly) checked out under a temporary 
location.  But when you request one of the build operations, then 
this temporary file is needed in the normal directory for the makefile, 
etc., so a temporary modelfile (mine.tm) is created and referenced for 
all the build requests. And by definition, mine.tm has a "not_traceable" 
status which is inherited by all generated files such as the dict.  So the 
MissionTool infers that the simulation is non reproducible, whereas the
ModelEditor (which just checks the source files) knows that it is.

Solution: if you want derived files to have a "reproducible" state then 
you need to build them from a "permanent" version of that file on disk - 
ie. after retrieving the required version of the model file, do a File: 
SaveAs and then build everything.

When starting a simulator on a Samba share (network drive), I get an
error: "Not able to connect".

The simulator is started by the EuroSim daemon, which is implemented as a
'service' under Windows(NT). Because the current implementation (Mk3Rev0) of
this service is not running as a specific user, it is possible that it
cannot read the simulator executable because of insufficient privileges.
This is also true for ordinary shared drives.

Solution:
Windows-NT and Windows-2000:
You may need to contact your system administrator for this: Add
sufficient (read+write+execute) privileges to the shared drive for user
'Everyone'. If you do not want to breach security, you better create a new
directory (tree) and Samba share for your shared EuroSim project. 

Windows-XP:
Redirected drives cannot be shared between processes that are running
under different user accounts.
More information in Microsoft article #180362:
http://support.microsoft.com/default.aspx?scid=kb;en-us;180362&sd=tech

As an alternative you can open a command shell (Cygwin), stop the
service with the 'net stop esimd' command and then start the service
as an ordinary application using the '-n' (no daemon) flag, i.e.:

     $EFOROOT/etc/esimd -n

or:

     %EFOROOT%/etc/esimd -n

when using 'cmd' as command shell.

Important Note: because of unpredictable network performance, you should
always try to run your simulator on a local drive (i.e. a fixed disk) and
avoid running it on a network drive.

See also Could not connect? and Nfs and running simulators?

Can I save the simulation state vector and use it to 
restart a simulation the next day? 

 Our snapshot facility records all values of variables which
you have tagged as "API".  This can be reused in two ways:

1. As an initial condition
The snapshot can be referenced as the initial condition for a mission, 
which means that the values in the file are applied to the global 
API data after the executable has been loaded and the default values 
applied, but before any tasks scheduled for the initialising state are 
executed. 

2. For applying during a simulation
The snapshot can be applied during a (paused) simulation, in which
case the values in the file are applied to the global API data, and
then the simulation can be resumed, with the new values being used.

What sort of scheduling model does EuroSim use?

EuroSim uses a scheduling model based on threads, with a thread
being created for each of the processors (EuroSim is intended for a
multi-processor platform), and with EuroSim tasks being executed "within"
each of those threads taking the user's scheduling requirements (fixed/free
processor allocation, task-dependencies, preemptability, priority) into
account.

See also IRIX as a realtime operating system?.

How can I edit source code using my favourite editor? 

 Set the EDITOR environment variable to your favourite editor.
Eg. to set your favourite editor to vim:

For bash/sh shells:

  export EDITOR=vim

For tcsh/csh

  setenv EDITOR vim

You can add these lines to your .bashrc or .cshrc so you don't 
have to type them each time you start EuroSim.


Windows specific note
=====================

For Windows platforms you need to provide the short path notation to
the editor executable (i.e. the one without spaces). You can use the
'cygpath' utility for this purpose. Say for example your editor is
located in:

  C:\Program Files\My Editor\edit.exe

Then you can set the EDITOR environment variable from your .bashrc as
follows:

  export EDITOR=`cygpath -w -s "C:\Program Files\My Editor\edit.exe"`

Alternatively run the cygpath utility from the command line:

  cygpath -w -s "C:\Program Files\My Editor\edit.exe"

And place the result in the EDITOR environment variable using the
Windows system properties dialog. You can decide to add the EDITOR
environment variable as a system-wide variable (i.e. available to
all users) or as a user specific variable.

I used "Change version requirement..." and set the version for one 
of my sources files to 1.2, whilst the latest version is 1.3. I expected
the node label to be "File.c 1.2 (1.3)" but it's actually "File.c 1.2".

 This is correct.  The figure in the brackets indicates the 
*disk* version and not the latest version; and the selection of an 
old version has done a silent retrieve.

See SUM (section 2.7) for more information on version control.

I'm trying to integrate two sub-models:

   Model A has global_output variable called 'float VAR_A'  and 
   Model B has global_input variable called 'double VAR_B'

I wish to use Model A VAR_A output as input for Model B VAR_B. 
Is this possible or do the variables have to have the same type 
definition and the same name?

The API only specifies the interface between the sub-models and EuroSim,
and is not intended to take care actively of sub-model to sub-model
interfacing: that has to be accomplished by the normal methods which are 
supported by the programming language.

There are three possibilities to solve this problem:
1. use the Model Description and Parameter Exchange editor to 
   copy the output variable VAR_A to input variable VAR_B.
2. have sub-models A & B share a variable, which has then to be of 
   the same type
3. make a function that copies VAR_A into VAR_B and does the type
   conversion

What happens to my simulation results when I disconnect and then
reconnect to the same simulation?

When a "disconnect" is requested, the journal file is closed and no
entries are written for the period when the simulation is running
"in the background".  However, any active recording actions carry on 
collecting data regardless.

Where a "reconnect" to the simulation run is requested, the 
original directory location is re-used for the timings file (written
when the simulation run is "stopped") and an additional journal
file.  In order that the original journal file is not overwritten, 
the file created on a reconnect will get the name EsimJournal_1 
(or a similar extension if a user defined name has been provided).

I don't seem to be able to find (some of) my simulation results?!

The simulation results consist of the following files:
   - recording data index (*.tr)
   - recording data files (*.rec)
   - scheduling timings file (timings)
   - log of simulation run (EsimJournal)

By default, these will appear together in a (new) directory having
a location such as:

 	 <esimproject>/1997-02-21/17:08:49

where the date and timestamps are the time at which the simulation
was initialised.

If you have overridden the default directory location (possible via 
the SimulationController: Tools: Configuration window), then this
will be used instead as the output directory for that and any
subsequent simulation runs (or until the value is reset to 
"Unknown").

An additional "feature" occurs if the SimulationController client and 
the simulation server are on different hosts.  Under these
circumstances, if an output directory is set to eg. "/tmp", then
the rec files (made by the server) go to <server>/tmp and the 
journal file (made locally by the client) goes to <client>/tmp. 

See also Simulation results and disconnecting?.

Which variables are contained in the environment of a running
simulator?

The environment variables are the same as the environment variables
of the testcontroller, with one exception. The PWD variable is updated
to match the directory where the simulator is running. This directory
is defined in the project setup and is equal to the project directory.
The EuroSim tools add also a number of environment variables for their
own use. These are present as well.

If I want to substitute a software sub-model by a hardware module,
how do I have to change the interface?

It depends on the hardware interface, but you will need to replace
the calls from other sub-models to this software sub-model with interface
calls to the required hardware-in-the-loop component.

We provide certain interface calls as standard within EuroSim
(see Hardware interfaces?).

I understand that that some system calls could cause non 
deterministic real-time behaviour, but can't I use non-blocking
calls within EuroSim?

Our experience with system-calls, advertised non-blocking or 
not, is that they can, but not necessarily will, introduce non 
deterministic non-predictable timing delays. The moment you give 
control to the kernel, you might spend a few milliseconds (!) 
before returning to your model thread. Moreover, if somebody were 
to do something simple like a 'chdir' syscall, we'd have serious
problems.

So, the message in the SUM  is not to use them. But of course,
you can always try to have them in the hard real-time loop. It 
simply is not advised and we cannot guarantee the timings (nor 
can Silicon Graphics :).

The workaround that we give to interface hardware and that has 
also been used successfully in a couple of projects is to put 
all system calls in an asynchronous task (ie. create a task from
model entrypoints, but put it on the scheduler canvas as an 
output connector with that task name, rather than as a round 
"normal" task.  This means that when the output connector is
triggered, the task executes in the non real-time domain, and
therefore does not compromise the real-time performance.

Summarising, use of syscalls and real-time performance:

1. No, no guarantee in the real-time loop. So refrain from using 
   them, but you can always try.

2. Yes, but again no guarantee, if you're using them in asynchronous
   tasks. This is the advised workaround.

3. Yes, but with guarantee, if you're using drivers that are provided
   by EuroSim, eg. esimSerial, etc (see Hardware interfaces?).

See also scheduling_an_output_connector.faq

I seem to get a merge conflict when using typedefs with unnamed 
field.

Yes, it is not (yet) possible to have two files with structures 
with unnamed sub structures, such as the following, because both
are allocated the same internal fake type name which generates the
conflict:

	file 1: typedef struct
 	     { struct
             	{ long int Command;
             	} chaser_command
             } CHASER_InputType;
             

	file2: typedef struct
             { struct
             	{ long int target_Command;
             	} target_command;
             } TARGET_InputType;

The solution is to make sure that structs are named!

My structures contain bitfields. Can I use them with EuroSim ?

Yes, as long as you remember that the ANSI-C standard only supports
usage of 'int's as field types, and EuroSim will (currently) always show you
bitfields on container alignment bounderies, implicitly packing bitfields in
their container.

I'm having problems integrating some code which has data types of 
'long double' into EuroSim.  Is this type not supported?

 Although 'long long' (and 'signed' and 'unsigned' friends) and 'long double'
are in Irix 6.x and Linux, these are *not* an ANSI-C supported types,
and are therefore outside the reqmts for EuroSim.
The good news is that EuroSim supports 'long long' and that under IRIX 6.x
the 'long double' type might even work.

Can I use malloc and other such calls in my model code?

Yes and no!  The direct use of the malloc (and free, calloc, etc) 
calls are not possible because this could interfere with the real-time
performance.  However, there are a set of esim library 
interface calls (eg. esimMalloc), which are callable from model 
code and which provide the same function but with real-time 
performance guaranteed.  

See esim(3) manpage for a full description of these and other calls.

My pointer type has been given a PARAMETER attribute by the 
ApiEditor, which leads to errors if the source code tries to 
assign values to this variable pointer.

Unfortunately, use of pointers is not supported in EuroSim.

Can I start and stop data recording upon an event generated
by a model or a hardware interrupt?

Yes, there are various ways to start and stop data recording.  Here
are a couple of ideas:

1. From within model code, the following library call can be used.  An 
   arg of 0 would stop all recording activities.

   void changeRecState(void) {
	....
	retVal = esimSetRecordingState(1);
	....
   }

   The proc (technically the task its in) can be scheduled at a fixed 
   frequency, in which case the condition for checking when the state 
   needs to change should be included in the body of the proc.  

   Alternatively, the relevant task can be attached to an input connector
   which represents some raised event which triggers the change of 
   recording state. The event can then be raised:

   a) from the model code via esimRaiseEvent("myEvent"); see esim(3) 
      manpage
   b) from an mdl script via raise("myEvent")
   c) via a hardware interrupt (a predefined "EI" input connector)
   d) via any of the other predefined input connectors (see SUM 
      section 8.3.4.1).


2. From within an mdl script, there is no direct call for changing
   all recording states (this can be done from the TestController
   menu option Simulation: Suspend Recording).  A more flexible approach 
   is available, where one action checks the condition for (not) recording 
   and sets a flag accordingly, which all or a subset of the recording 
   actions have in their condition.  

   <ActionName:>"CheckAction"
   <Condition:>
      	freq(10)

   <Action to be executed:>
        # sets all recording on when spacecraft is close
	int   recordingCheck = 0
        float thisIsClose    = 100.0
	if  ( :some:api:spacecraftDistanceFromTarget < thisIsClose ) {
 		recordingCheck = 1
	}
        else {
		recordingCheck = 0
	}	


   <ActionName:>"RecordingAction"
   <Condition:>
      	freq(100) && CheckAction:recordingCheck

   <Action to be executed:>
 	record  "someFile.rec" :some:API:variable

I have data from a source other than EuroSim, which I wish to reference in a
stimulus action, in order to feed data values into an API variable.  Do I have 
to convert the data first?

Stimulus data files should have the same format as the recording files which
EuroSim produces.  This means that there should be an (ascii) header block 
followed by lines of (binary) data, where each line consists of a value for 
simulation_time followed by one or more data values.  The values for the 
simulation_time can be used to synchronise the data input with the simulation 
time ("compare timestamps") or can be dummy values which are ignored ("ignore 
timestamps").  This concept is explained in more detail in the SUM 
(section 9.7.3).

The first step is to ensure that you have an ascii file which has the data in 
lines of the format: <simulation_time> <varX_value> <varY_value>, where the 
values can be space or tab separated. It's important that the first value 
represents the simulation_time, so even where this value is redundant 
(eg. file is being fed in at a fixed frequency), it's still necessary to 
provide a (dummy) value.

The second step is to add a header to the datafile, which has the following 
format:

# comment line
Date recorded: (optional)
Dict: (optional) eg. ../mymodel/dict
Number of variables: n
1{var declarations of the form <name: datatype>}n


An example of a legal header is:

# my test file
Date recorded: 27 Aug 1997
Number of variables: 3
/simulation_time: double
/varX: int
/varY: int


The final step is to use the utility a2r(1) (ascii => results) to convert the 
file to binary and fill in the header with additional information such as 
record size.  If the dict is not referenced, then use the -D flag to stop the
check against the dict (see a2r(1) manpage for more details on this and other
options).

The equivalent r2a(1) converts (results => ascii) allows you to view/edit 
recording files.

I have a FrameMaker file for my model description, but after adding 
a version to it, it became unreadable by Frame. Why?

Versioning a non-ASCII file, eg. normal Frame format, is not possible.  
It is possible to put the MIF version of the file under version control.  

What happened to the EI input connector in Mk2 and later?

Because all external events can now be configured in
the 'Tools: External Event' menu of the Schedule Editor,
it was decided to not have an exception for the EI
(External Interrupt) on SGI. You can simply create
an external event handler for 'EI' with the appropriate
path (i.e. /dev/ei) and set the dispatcher type to 'default'.
The Schedule Editor then automatically adds an external
input connector with the name of the event handler to the
'Insert: External event' menu. You can then use this input
connector just as the 'EI' input connector in Mk1.

Which version of EuroSim am I running?

There are two ways of finding out the current version:

1. type in "esimversion" at the Unix command prompt
2. request Help: About EuroSim from any of the EuroSim
   window menus