trick/doxygen/users_guide/appendix_a.dox_in

/**
@page LEVEL1 Converting From Trick 7 To Trick 10

Listed here are the main differences you'll have to handle if you have a Trick version 7 simulation
that you want to convert to Trick version 10.

@section LEVEL2 S_define File
The Trick 7 S_define file syntax for a sim object looks more or less like a C Structure containing model job specifications. The Trick 10 S_define file
syntax for a sim object looks like a C++ Class containing model job specifications within the Class constructor. There are other features of the S_define file
that may or may not look different.<br><br>
See the
@htmlonly
<a href="appendix_a_sdefine_table.html"> Table of S_define File Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 S_define File syntax.

@section LEVEL2 Input File
The Trick 7 input syntax is a C-like language created and maintained just for Trick. The Trick 10
input syntax is Python. In addition to the obvious differences due to using a new input file language,
many things have been implemented differently in Trick 10 resulting in changes to the way
Trick data is configured or referenced in the input file.<br><br>
See the
@htmlonly
<a href="appendix_a_input_table.html"> Table of Input File Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 Input File syntax.

@section LEVEL2 Memory Initialization

Trick 10 does not automatically initialize C structures to zero (while Trick 7 does). Trick 10 uses the C++ "new" command to allocate memory for both C and C++ data,
which relies on user code (C: an init function, C++: constructor) to do the initializing. 

However, you can use a feature of C++ to initialize your C structures to zero (see the S_define example below). This method is also implemented in Trick's generated io_src code
so that when you dynamically allocate a C structure using Trick's memory manager, e.g. TMM_declare_var, it will be zeroed as well.

This way Trick 10 can act like Trick 7 with regards to initializing memory.

@code
class mySimObject : public Trick::SimObject {

    public:
        STRUCT1 my_c_struct1;
        STRUCT2 my_c_struct2;

        // you can put C structs with empty parens as initializers on the constructor to zero them out:
        mySimObject() : my_c_struct1(), my_c_struct2() {

            (0.1, "scheduled")  state_update(&my_c_struct1) ;
            (0.1, "scheduled")  state_update(&my_c_struct2) ;
                                                                                    }
} 
mySimObject dyn ;@endcode

@section LEVEL2 Memory Allocation
See @subpage convert_07_to_10.

@section LEVEL2 Default Data Files

Trick 7 default data files should be converted to default_data class jobs in Trick 10. See below for more background on
the default data capabilities in Trick 7 vs. Trick 10. There is a convenience script called dd_convert 
that can automatically convert your existing Trick 7 default data files to source code so they can be used as default_data jobs.
See the dd_convert help screen for its usage:

<tt><b>UNIX Prompt></b> dd_convert -h</tt>

<b>Trick 7 default data capability:</b><br>
Using syntax that the Trick input processor can understand, the user can code assignment statements to set the initial ("default") value for variables.  These assignment statements are stored in a file with a ".d" extension. When a variable is declared in the S_define file, an optional .d file (or files) may be specified on the declaration statement so that the data is initialized with values from the .d file. 

S_define syntax:@code
<rel_path1>: <type> <instance> [(<rel_path2>/<filename>.d)] ;@endcode

S_define example:@code
sim_object {
   mymodels: MYSTRUCT var (mymodels/data/mystruct.d) ;
} examp ;@endcode

The <rel_path1> is the path (relative to TRICK_CFLAGS path) to the C or C++ header file where <type> is defined.  The <rel_path2> is the relative path to where the .d file is located. The difference between a default data assignment statement and a regular input file statement is that the <type> is specified instead of the declared variable name. Trick will process the .d file and substitute the variable name for each <type>. This way a .d file can be used for one or more variable declarations.

.d file syntax: @code
<type>.<member>[[<dim>]] [{<units>}] = <value> [, <value>#] ;@endcode

.d file example:<br>
Assume there is a mystruct.h file that looks like this:@code
typedef struct {
   int dist ; /* km my distance */
} MYSTRUCT ;@endcode
The .d file assignment statement may look like this:@code
MYSTRUCT.dist = 100 ;@endcode
Trick instantiates the .d statement to this:@code
examp.var.dist = 100 ;@endcode

All Trick instantiated .d files are stored in the Default_data directory.  Trick also generates an S_default.dat file that includes all of the .d files from the Default_data directory. The 1st statement in the input file should be to #include the S_default.dat file so that the default data assignment statements are processed first by the Trick input processor, guaranteeing that all variables that had default data specified are initialized.

Pros:
   - User can change a .d file and not have to recompile (CP -d)

Cons:
   - Slower execution at simulation startup
   - User can add other input statements (for/if/then/else/etc.) that Trick's default data processor may ignore, which can be error prone

<b>Trick 10 default data capability:</b><br>
A new default_data Trick job class was created so that source code can do the data assignments instead of .d files, mainly because of the two Cons listed above. So the Trick 7 example above can be done using C or C++ source code in Trick 10.

S_define syntax (C):@code
<type> <instance> ;
("default_data") <function>(&<simobj>.<instance>) ;@endcode

S_define example (C):@code
/* LIBRARY DEPENDENCIES: ((mymodels/src/my_ddata.c)) */
class exampSimObject : public Trick::SimObject {
public:
   MYSTRUCT var ;
   exampSimObject() {
      ("default_data") my_ddata(MYSTRUCT *ptr = &examp.var) ;
   }
};
exampSimObject examp ;@endcode

Source file syntax (C):@code
void <function>(<type> *<param>) {
   (*<type>).<member>[[<dim>]] = <value> ; 
}@endcode

Source file example (C):@code
void my_ddata(MYSTRUCT *t) {
   (*t).dist = 100 ; 
}@endcode

S_define syntax (C++):@code
<type> <instance> ;
("default_data") <instance>.<function>() ;@endcode

S_define example (C++):@code
##include "mymodels/include/mystruct.h"
class exampSimObject : public Trick::SimObject {
public:
   MYSTRUCT var ;
   exampSimObject() {
      ("default_data") var.my_ddata() ;
   }
};
exampSimObject examp ;@endcode

Source file syntax (C++):@code
void <type>::<function>() {
   <member>[[<dim>]] = <value> ; 
}@endcode

Source file example (C++):@code
void MYSTRUCT::my_ddata() {
   dist = 100 ; 
}@endcode

Of course because your default data is now done in source code, if you want to change default data values from sim to sim, you would have to run "make" to pick up your changes.

<b>Trick 10 Another way to do it:</b><br>
Don't wanna mess with default_data jobs? You can just assign default values in the sim object constructor. The Trick 10 sim object is a C++ Class, so you can write code in its constructor to assign data values. Note that if you are going to change your default data from sim to sim, you will have to re-CP every time you change values. Otherwise this is a fine method if you don't plan to change your default data values much or at all. (It's pertinent to note that class constructors execute before default_data jobs, in case you use both methods.) So the S_define example from above would look like the example below, with no default_data job needed.

S_define example:@code
##include "mymodels/include/mystruct.h"
class exampSimObject : public Trick::SimObject {
public:
   MYSTRUCT var ;
   exampSimObject() {
      var.dist = 100 ;
   }
};
exampSimObject examp ;@endcode

@section LEVEL2 Variable Server Commands
The Variable Server sends any commands it receives to the Trick input processor for parsing, so essentially you can send any valid input syntax
to the Variable Server. In addition to general input statements, there are special commands that only the Variable Server understands
in order to send back variable data to the client. <br><br>
See the
@htmlonly
<a href="appendix_a_varserver_table.html"> Table of Variable Server Command Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 Variable Server Command syntax.

@section LEVEL2 Data Product Files

TODO.


*/