FD_HistoryAlloc

FIDAL - Financial Data Access Library

NAME
FD_HistoryAlloc - C Function

SYNOPSIS
#include "fidal.h"

FD_RetCode FD_HistoryAlloc( FD_UDBase *unifiedDatabase,
                                             const FD_HistoryAllocParam *param,
                                             FD_History **history );

DATA STRUCTURE
   Excerpt from fidal.h:

   typedef struct
   {
      unsigned int nbBars; /* Nb of element into the following arrays. */
      FD_Period period; /* Amount of time between each bar. */

      /* The arrays containing data. Unused array are set to NULL. */
      FD_Timestamp *timestamp;
      FD_Real      *open;
      FD_Real      *high;
      FD_Real      *low;
      FD_Real      *close;
      FD_Integer   *volume;
      FD_Integer   *openInterest;

      /* Enumerate all the data source that did contribute. */
      FD_StringTable listOfSource;
   } FD_History;

   typedef struct
   {
      const char    *sourceName;
      const char    *category;
      const char    *symbol;
      FD_Period      period;
      FD_Timestamp   start;
      FD_Timestamp   end;
      FD_Field       field;
      FD_HistoryFlag flags;
   } FD_HistoryAllocParam;

DESCRIPTION

Allocate and return the historical data for a symbol.

All the available data in the unified database is returned for this symbol. If the symbol data is found in multiple different data source, the data will be transparently merged by the unified database mechanism.

The category of the symbol can be specified. The category will typically represent the exchange to which that symbol belongs. See FD_AddDataSource for details on how setting up categories.

The data can be requested in a higher period of the precision provided by the unified database. Meaning that daily or even intra-day data can be stored in the database, but the user can simply ask for weekly, monthly, quarterly and yearly precision.

When finished with the data, it can be freed by calling FD_HistoryFree.

Safe way to initialize 'param' is to set the whole structure to zero and set only the parameter for your application. A value of zero is assume by FIDAL to mean the current default behavior. This will keep your code working even if new parameters are added in the future (see Examples).

PARAMETERS

'unifiedDatabase'
The data will be obtained from the specified unified database.

'param.sourceName'
Allows to request the data from a particular data source. Use the optional name who was provided with FD_AddDataSource. Leave to zero to let FIDAL choose a data source or perform data merging.

'param.category'
A string representing the category to which the symbol belongs. When NULL the default category "ZZ.OTHER.OTHER" is used.

'param.symbol'
A string representing the symbol. Mandatory parameter.

'param.period'
The data will be returned with price bar separated by the period specified here. If the database contains data at an "higher time precision" the data will be aggregate to be delivered at the requested time frame. Specify FD_DAILY for daily data, FD_WEEKLY for weekly data and so on...

'param.start' and 'param.end'
Limit the output to the range defined by start/end. The date specified are included in the output (if available). Only the granularity specify by period is consider from these timestamps. Example, requesting with param.period equal FD_MONTHLY means that only the Year and Month component of start/end will be used and the day and time will be ignored. FD_Timestamp can be set with FD_SetDate. See fd_common.h for the complete interface related to FD_Timestamp

If param.start is not specified (all zero), the history will start with the oldest price bar found in the database.

If param.end is not specified (all zero), the history will end with the most recent price bar found in the database.

'param.field'
Indicates which element of the price bar you wish to be allocated and returned. If all available fields are needed, just specify FD_ALL.. Leave to zero for no flags.

'param.flags'

FD_ALLOW_INCOMPLETE_PRICE_BARS
When FIDAL does data consolidation to weekly, monthly, quarterly and yearly period, the default behavior is to not return incomplete starting/ending price bars. This flag disable this filtering.

A starting price bar period is determine completed when one of the following is true:
- The end-of-day price bar for the first weekday of the target period is available.
- Some data is found for the previous price bar.

A ending price bar period is determine completed when one of the following is true:
- The end-of-day price bar for the last weekday of the target period is available.
- Some data is found for the next price bar.

Examples:
(1) Requesting historical monthly data will not return the
       ending month until at least the last week day is available OR
       a price bar in the following month is found in the database.

(2) Requesting historical weekly data will not return the starting
       week if it was an incomplete week AND no data is found for
       the previous week in the database.

(3) Requesting historical yearly data will not return the starting
       year if the first week day of the year is not available AND
       no data is found for the previous year in the database.

FD_USE_TOTAL_VOLUME
This option makes FIDAL to sum the daily volume when doing price bar consolidation e.g. when converting daily data to period equal or greater to weekly. Without this flag, the default behavior is to return the daily average volume.

FD_USE_TOTAL_OPENINTEREST
This option makes FIDAL to sum the daily open interest when doing price bar consolidation e.g. when converting daily data to period equal or greater to weekly. Without this flag, the default behavior is to return the daily average open interest.

FD_DISABLE_PRICE_VALIDATION
By default FIDAL fails a FD_HistoryAlloc call when an inconsistency is found among the high, low, close, open e.g. high<low. This option disable these price validations and the caller is left on its own to detect erroneous data (Planned for V0.1.4)

'history'
Pointers that are going to be set to the allocated FD_History upon success (only when FD_SUCCESS is returned).

RETURN VALUE

FD_SUCCESS	Operation is successful
FD_ALLOC_ERR	Cannot allocate memory, or memory corruption detected
FD_CATEGORY_NOT_FOUND	Specified category cannot be found in the unified database.
FD_SYMBOL_NOT_FOUND	Specified symbol cannot be found in the unified database.
FD_BAD_PARAM	One of the parameter has an out-of-range value
FD_LIMIT_ERR	The specified 'period' parameter is lower than the precision available from the unified database.
FD_DAFD_ERROR_VOLUME_IS_NEGATIVE FD_DAFD_ERROR_OI_IS_NEGATIVE FD_DAFD_ERROR_CLOSE_IS_NEGATIVE FD_DAFD_ERROR_OPEN_IS_NEGATIVE FD_DAFD_ERROR_HIGH_IS_NEGATIVE FD_DAFD_ERROR_LOW_IS_NEGATIVE FD_DAFD_ERROR_LOW_EXCEED_HIGH FD_DAFD_ERROR_OPEN_EXCEED_HIGH FD_DAFD_ERROR_OPEN_BELOW_LOW FD_DAFD_ERROR_CLOSE_EXCEED_HIGH FD_DAFD_ERROR_CLOSE_BELOW_LOW	All these error code are return when an inconsistency is detected in the data returned by the data source. You can disable the detection of these inconsistency with the FD_DISABLE_PRICE_VALIDATION flag.
FD_UNKNOWN_ERR	Operation failed for unknown reason

For other error code, or to match a number to an error description, check the FD_RetCode enumeration in "FIDAL/c/include/fd_common.hdefs.h"

EXAMPLE (1)

#include "fidal.h"

void getWeeklyData( const char *category,
                    const char *symbol,
                    FD_UDBase *uDBase )
{
   FD_RetCode retCode;
   FD_HistoryAllocParam param;
   FD_History *history;
   
   /* Get the data for the specified category/symbol.
    * Note the memset to zero to make sure all unspecified 
    * parameter use the default behavior.
    */
   memset( &param, 0, sizeof( FD_HistoryAllocParam ) );
   param.category = category;
   param.symbol   = symbol;   
   param.period   = FD_WEEKLY;
   param.flags    = FD_ALLOW_INCOMPLETE_PRICE_BARS | FD_USE_TOTAL_VOLUME; 
   retCode = FD_HistoryAlloc( uDBase, &param, &history );
   if( retCode == FD_SUCCESS )
   {
      /* Use the data for your application. */
      ...
      /* Free the data once done. */
      FD_HistoryFree( history );
   }

}

EXAMPLE (2)

<<TO BE COMPLETED>>