====== How to add a new target type ======

RTS2 targets used for scheduling are represented by subclass of Target class.
If you would like to introduce a new target type, you must:

  - introduce its type identifier among types listed in //types// table. This table contains character identifiing type and short type description.
  - add its description to src/utils/rts2target.h file. Find defines starting with TYPE_, and add your own type, together with characted which represents it. This define is of course not required, but it is highly recommended.
  - create table which will hold target extended parameters. This table must include reference to tar_id from targets as primary key.
  - create its class as subclass of Target class in src/utils directory. You might choose to create a new file with this subclass, or add its definition to existing file. It is recommended to start a new file. You must add this file to src/utilsdb/Makefile.am - please look at this file for rts2targetgrb string to see where it must be added.
  - in subclass load method, you can add any additional select statements which will load from database additional fields. For an example, look to rts2targetgrb.ec for ::load method implementation. You can of course use any ECPG statements. Please consult ECPG documentation for details.
  - add this target type to //Target *createTarget (int _tar_id, struct ln_lnlat_posn *_obs)// in //src/utilsdb/target.ec//.

There is an example. Lets suppose we would like to add target for observing
earth low orbit satelites. This target will have seven extra parameters - six
for description of the orbit, seventh for date of orbit update. We start with
adding type to types table, using pgsql console:

<code sql>
stars=# insert into types values ('b', 'Earth orbit satelites');
INSERT 0 1
stars=#
</code>

Then add type define to //sr/utils/rts2target.h//:

<code c++>
// master plan target
#define TYPE_PLAN               'p'

// target type for
#define TYPE_ORBIT              'b'
</code>

Now add table //orbits// for additional parameters:

<code sql>
stars=# insert into types values ('b', 'Earth orbit satelites');
INSERT 0 1
stars=#
</code>

Then add type define to //sr/utils/rts2target.h//:

<code c++>
// master plan target
#define TYPE_PLAN               'p'

// target type for
#define TYPE_ORBIT              'b'
</code>

Now add table //orbits// for additional parameters:

<code sql>
stars=# create table orbits (tar_id integer references targets (tar_id), p1 float8 not null, p2 float8 not null, p3 float8 not null, p4 float8 not null, p5 float8 not null, p6 float8 not null, p7 timestamp not null);
</code>

Now we will create in //src/utilsdb// files rts2targetorbit.h and
rts2targetorbit.cpp and add them to Makefile.am in this directory:

<code makefile>

inst_HEADERS = sqlerror.h rts2devicedb.h target.h rts2appdb.h rts2sqlcolumn.h rts2obs.h rts2obsset.h \
        .....
                        rts2imgsetstat.h rts2targetell.h rts2user.h rts2userset.h account.h accountset.h rts2targetorbit.h

EXTRA_DIST = sqlerror.ec rts2devicedb.ec target.ec sub_targets.ec rts2appdb.ec airmasscale.ec rts2sqlcolumn.ec rts2obs.ec \
        .....
                        rts2user.ec rts2userset.ec account.ec accountset.ec rts2targetorbit.ec

CLEANFILES = sqlerror.cpp rts2devicedb.cpp target.cpp sub_targets.cpp rts2appdb.cpp airmasscale.cpp rts2sqlcolumn.cpp rts2obs.cpp \
        .....
                        rts2user.cpp rts2userset.cpp account.cpp accountset.cpp rts2targetorbit.cpp

nodist_librts2blockdb_a_SOURCES = sqlerror.cpp rts2devicedb.cpp target.cpp sub_targets.cpp rts2appdb.cpp rts2sqlcolumn.cpp rts2obs.cpp \
        .....
                        rts2imgsetstat.cpp rts2targetell.cpp rts2user.cpp rts2userset.cpp account.cpp accountset.cpp rts2targetorbit.cpp

</code>

After you are done, you can fill rts2targetorbit.h and rts2targetorbit.cpp file.There is rts2targetorbit.h:

<code c++>
#include "target.h"

class Rts2TargetOrbit {
        private:
                double p1;
                double p2;
                double p3;
                double p4;
                double p5;
                double p6;
                time_t p7;
        public:
                Rts2TargetOrbit (int _tar_id, struct ln_lnlat_posn *_obs);
                Rts2TargetOrbit ();

                virtual int getRST (struct ln_rts_time *rst, double jd, double horizon);
                virtual int load ();
};
</code>

and there is rts2targetorbit.cpp:

<code c++>
#include "rts2targetorbit.h"

Rts2TargetOrbit (int _tar_id, struct ln_lnlat_posn *_obs)
:Target (_tar_id, _obs)
{
        p1 = p2 = p3 = p4 = p5 = p6 = nan ("f");
        p7 = 0;
}

int
Rts2TargetOrbit::getRST (struct ln_rts_time *rst, double jd, double horizon)
{

}

int
Rts2TargetOrbit::load ()
{
        EXEC SQL BEGIN DECLARE SECTION;
        double d_p1;
        double d_p2;
        double d_p3;
        double d_p4;
        double d_p5;
        double d_p6;
        int d_p7;
        int d_tar_id = getTargetID ();
        EXEC SQL END DECLARE SECTION;

        EXEC SQL SELECT
                p1,
                p2,
                p3,
                p4,
                p5,
                p6,
                EXTRACT (EPOCH FROM p7)
        INTO
                :d_p1,
                :d_p2,
                :d_p3,
                :d_p4,
                :d_p5,
                :d_p6,
                :d_p7
        FROM
                orbits
        WHERE
                tar_id = :d_tar_id;

        if (sqlca.sqlcode)
        {
                logMsgDb ("TargetOrbit::load", MESSAGE_ERROR);
                return -1;
        }
        p1 = d_p1;
        p2 = d_p2;
        p3 = d_p3;
        p4 = d_p4;
        p5 = d_p5;
        p6 = d_p6;
        p7 = d_p7;

        return Target::load ();
}
</code>

And finally add new target type to createTarget method:

<code c++>
Target *createTarget (int _tar_id, struct ln_lnlat_posn *_obs)
{
        EXEC SQL BEGIN DECLARE SECTION;
        int db_tar_id = _tar_id;
        char db_type_id;
        EXEC SQL END DECLARE SECTION;
.....
                case TYPE_PLANET:
                        retTarget = new TargetPlanet (_tar_id, _obs);
                        break;
                case TYPE_ORBIT:
                        retTarget = new Rts2TargetOrbit (_tar_id, _obs);
                default:
                        retTarget = new ConstTarget (_tar_id, _obs);
                        break;
.....
}
</code>