The first six fields are the beginning and ending times. The sequence is as follows:

1. beginning year,
2. beginning day,
3. beginning millisecond,
4. ending year,
5. ending day,
6. ending millisecond

Finally, the last parameter enables an X status window to appear. Send a sTrue to enable this window, or sFalse to disable it.

The value returned is a pointer to a opaque structure. You may not do anything with this pointer except send it to one of the five following routines. This structure must be freed with pro_FreePromote after being called. .

This routine requires the pointer returned by pro_InitPromote as input and will simply promote all off-line data that you requested in the pro_InitPromote. It returns sTrue for success and sFalse for failure.

This routine requires the void pointer returned by pro_InitPromote as input and will simply demote (delete!) all on-line data that you requested in the pro_InitPromote. It returns sTrue for success and sFalse for failure.

For this routine to work, pro_PromoteAll had to be called previously. You may not call pro_DemoteAll without calling pro_PromoteAll first.

There are multiple ways to set the time depending on your needs and the data that you have available to you. The SetBTime is for the beginning time and the SetETime is for the ending time.

This first way requires the year, the day, and the millisecond of the day for data access.

    void SetBTime (SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_LONG = 0);
    void SetETime (SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_INT, SDDAS_LONG = 0);

Note: You need call only one set of routines (or you may mix/match them although this is not recommended).

There are two ways of specifying a source(s) using AddSource. Either send in the data key, or send in the string names (i.e. "UARS", "UARS-1", "PEM", "HEPS", "HPSA"). Also, this routine is "adding" sources to a list so you may add as many sources to this list as you like by calling this routine multiple times with different data keys or string names.

BuildDBList is the routine needed to build a list of items to promote. You must call this routine after setting the time and the sources. The first parameter is one of the following flags or a combination of the following created by OR'ing their values together:

• _I_FILE_ - the VIDF file
• _HD_FILE_ - the HEADER and DATA files
• _P_FILE_ - the PIDF file

The second parameter is one of the following flags and refers to what "state" of data to build a list :

• ONLINE - for online data
• OFFLINE - for offline data
• EITHER - for data that is either online or offline

The third parameter is optional and specifies the maximum number of entries to promote. The default is 1000 which is a pretty sizable number. Anything more than that and you might find a better way to get the data; however, this parameter can be changed.

Return Values:

• > 0 - need to promote this many elements
• == 0 - no need to promote anything
• < 0 - error

PromoteList will promote the list generated by BuildDBList; thus, it must be called after all the previous routines have been called. It will promote all the off-line data that was generated by the BuildDBList call. PromoteList will return a sTrue on success and an sFalse on failure.

After the data has been promoted and you have finished using it, you may demote (delete!) all the data which has been promoted. PromoteList will return a sTrue on success and a sFalse on failure.

The parameter on the DemoteAllData signifies whether the data that is to be demoted is to be deleted regardless of whether or not the data was promoted. The default is sFalse which means the data will only be deleted if it was previously promoted. Sending an sTrue means delete the data regardless. This can be dangerous so be careful!

The following routines are all completely optional and need to be called only if necessary.

SetXStatus can turn on or off the X promotion status window. The default is OFF. Send SetXStatus either ON or OFF as input.

SetAutoPromoteMeta will make the promote automatically promote some meta data if it does not exist. The default is to promote the meta data. Send SetAutoPromoteMeta either sTrue to promote the meta data or sFalse to not promote it.

#include 
#include "libbase_idfs.h"
#include "libPromote.h"

int main (int argc, char *argv[])
{

    SDDAS_ULONG data_key1, data_key2;
    void *promo_struct;

    CfgInit ();              /* Initialize the database */

/* Determine our data keys */

    get_data_key ("UARS", "UARS-1", "PEM", "HEPS", "HPSA", &data_key1);
    get_data_key ("UARS", "UARS-1", "PEM", "VMAG", "VMMA", &data_key2);

/* Initialize our promotion structure */

    promo_struct = pro_InitPromote (1993, 191, 28800,
                                    1993, 191, 50400,
                                    sFalse);

/* Add our sources */

    pro_AddSource (promo_struct, data_key1);
    pro_AddSource (promo_struct, data_key2);

/* Promote the data if necessary */

    if (pro_NeedToPromote (promo_struct) == sTrue) {
        pro_PromoteAll (promo_struct);

/* do something with data in here */

        pro_DemoteAll (promo_struct);
    }

/* Free our promotion structure */

    pro_FreePromote (promo_struct);

/* Free the database info */

    CfgTerm ();
    exit (0);
}

#include "Promote.h"

int main ()
{
    Promote *P;

    CfgInit ();                 // Initialize CFG files
    P = new Promote ();
    P->SetXStatus (ON);         // default is off

    P->AddSource ("UARS", "UARS-1", "PEM", "HEPS", "HPSA");
    P->SetBTime (1993, 191, 8, 0, 0);
    P->SetETime (1993, 191, 14, 0, 0);

    if (P->BuildDBList (_I_FILE_ | _HD_FILE_ | _P_FILE_, OFFLINE) > 0) {
        P->PromoteList ();

// do something with data

        P->DemoteAllData ();
        delete P;
    }
    CfgTerm ();
    exit (0);
}