FIDAL - Financial Data Access Library

  Home | Documentation | Download
 

 

NAME
  FD_AddDataSource - C Function


SYNOPSIS
  #include "fidal.h"
  FD_RetCode FD_AddDataSource( FD_UDBase     *unifiedDatabase,
                               FD_AddDataSourceParam *param );

DATA STRUCTURE
  
typedef struct
   {
     
FD_SourceId id;

      FD_SourceFlag flags;

      const char *location;
      const char *info;

      const char *username;
      const char *password;

      const char *category;
      const char *symbol;

      const char *country;
      const char *exchange;
      const char *type;

      FD_Period period;
  
} FD_AddDataSourceParam;
 

DESCRIPTION

To make accessible a source of market data, it must be added to an "unified database" (allocated with FD_UDBaseAlloc)

Many data source can be added to the same unified database. All the data source will get transparently merge.

It is possible to add one or many symbols simultaneously in one call. The data is not retrieved immediately, only the index is build at this point. The data is extracted/merged later using the FD_HistoryAlloc function.

In the case that the same symbol is provided from two different data source, the data will get merged according to a specific rule: the order in which the data source where added with FD_AddDataSource do determine which data takes precedence on the other. The first added data source is the "least important" one, and the data provided by the last one cannot be overwritten by the others.

Example 1: You have a local database and you want an online data source to provide the missing data. You will add the online data source last. 

The merging is independently performed down to each price bar.

Example 2: You have a local read-only CD with an error on a couple of price bars. You can "cover" the erroneous data by putting the correct price bars in a file on your hard disk. Build the unified database by adding first the CD data source and then add the hard disk data source. That way the hard disk data will be taken for this particular price bar, this will effectively correct the error.

The usage of this function is highly dependable of the 'param.id' parameter who is identifying the type of data source (ASCII, CSI, TC2000 etc..). 

Note: For simplicity, data source cannot be individually removed. For such rare functionality, it is simpler to simply de-allocate the corresponding unified database and re-build by re-adding the needed data sources.

PARAMETERS

'unifiedDatabase'
Pointer on the unified database to which the data source will be added.

'param.id'
Specify the data source being added. The usage of many of the other parameters are dependable on this value. Further details about the list of supported id is found in List of data source.

'param.location'
Indicates where the data source can be found. Will generally be a directory path. Cannot be longer than FD_SOURCELOCATION_MAX_LENGTH.

'param.info'
Gives additional information on the files to be added. This could be the name of a file, the extension of the valid files or a precise description of the content. See the documentation corresponding to the 'param.id' for further information. Cannot be longer than FD_SOURCEINFO_MAX_LENGTH.

'param.category'
The symbols added can be categorize. A category will usually represent the exchange where these added symbols belongs. A category can be any string the end-user wish ("US.NASDAQ", "MY STOCK", "TELCO GROUP" etc...). When choosing a string, consider the Category Guidelines, Sometimes the data source will ignore this parameter and provides its own categorization. Use NULL to use the default category "ZZ.OTHER.OTHER". Cannot be longer than FD_CATEGORY_MAX_LENGTH.

'param.country', 'param.exchange', 'param.type'
Advanced user following the Category Guideline may find it useful to specify individually the sub-component of a category. If a sub-component is not specified (left to NULL), it can be completed by the data source, or the default will be used. Default country is "ZZ", default exchange is "OTHER" and default type is "OTHER". When using these sub-components, 'param.category' must be left to NULL.

'param.username', 'param.password'
Some data source requires user authentication.

'param.flags'
It is possible to enable/disable certain functionality with flags
. An error will be immediately reported if an option is not supported for this data source :

FD_NO_FLAGS Used when no optional functionality are needed.
FD_DO_NOT_SPLIT_ADJUST

A data source is assumed to be completely split adjusted relatively to its most recent historical data. This will be the case with most of the data source. This option allows to return the data without split adjustment.

FD_DO_NOT_VALUE_ADJUSTSome data source account for the added value of dividends in their price. This option allows to prevent the dividend (or any other adjustment) to be considered.
FD_REPLACE_ZERO_PRICE_BAR

Some data source return a price bar with some price to be zero as an an indication that there was no change in price. This option allows  to replace these "zero" price with the previous close. If the zero price are in the initial bars e.g. no previous valid close are known, these zero price bar will be ignored. Without this option, a "zero" detected in a price bar will be considered  an error and a call to FD_HistoryAlloc will fail. A volume of zero is valid.


RETURN VALUE

FD_SUCCESSOperation is successful
FD_ALLOC_ERRCannot allocate memory, or memory corruption detected
FD_BAD_PARAMOne of the parameter is out of range
FD_NO_DAFD_SOURCEData source contains no data. Not an error by itself, but could be an indication of problem if some data was expected by the user.
FD_INVALID_PATH'param.location' parameter cannot be resolved (bad directory path?)
FD_INVALID_FIELDCan be returned when a bad field is specified with FD_ASCII_FILE data sources.
FD_UNKNOWN_ERROperation 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

SEE ALSO

FD_Initialize


EXAMPLE (1)

#include <stdlib.h>
#include <string.h>
#include "fidal.h"

int main( void )
{
   FD_RetCode retCode;
   FD_UDBase *unifiedDatabase;
   FD_InitializeParam    initParam;
   FD_AddDataSourceParam addParam;

   /* Initalize the library and create an unified database. */
   memset( &initParam, 0, sizeof( FD_InitializeParam ) );
   if( FD_Initialize( &initParam ) != FD_SUCCESS )
      exit( -1 );

   if( FD_UDBaseAlloc( &unifiedDatabase ) != FD_SUCCESS )
   {
      FD_Shutdown();
      exit( -2 );
   }

   /* Add Yahoo! index for all supported USA exchange. */
   memset( &addParam, 0, sizeof( FD_AddDataSourceParam ) );
   addParam.id = FD_YAHOO_WEB;
   addParam.location = "us";
   retCode = FD_AddDataSource( unifiedDatabase, &addParam );

   /* ... add here code to get data with FD_HistoryAlloc ... */

   FD_UDBaseFree( unifiedDatabase );
   FD_Shutdown();
   return 0;
}

EXAMPLE (2)

#include <stdlib.h>
#include <string.h>
#include "fidal.h"
int main( void )
{
   FD_UDBase   *unifiedDatabase;
   FD_History  *data;
   FD_RetCode  retCode;
   FD_InitializeParam    initParam;
   FD_AddDataSourceParam addParam;
   FD_HistoryAllocParam  historyParam;

   unsigned int i;

   /* Initialize the access to the library. */
   memset( &initParam, 0, sizeof( FD_InitializeParam ) );
   if( FD_Initialize( &initParam ) != FD_SUCCESS )
      exit( -1 );

   /* Create an unified database. */
   if( FD_UDBaseAlloc( &unifiedDatabase ) != FD_SUCCESS )
   {
      FD_Shutdown();
      exit( -2 );
   }
   /* Indicate where to get the data and put it in
    * the "US.NASDAQ.STOCK" category. By default
    * the name of the file determine the name of
    * the symbol. (Wildcards '*' can be used to 
    * include multiple files/symbols in one call).
    */
   memset( &addParam, 0, sizeof( FD_AddDataSourceParam ) );
   addParam.id = FD_ASCII_FILE;
   addParam.location = "c:\\my_data\\LNUX";
   addParam.info = FD_DOHLCV;
   addParam.category = "US.NASDAQ.STOCK";
   retCode = FD_AddDataSource( unifiedDatabase, &addParam );

   /* Now, display all daily close price available
    * for the LNUX symbol.
    */
   if( retCode == FD_SUCCESS )
   {
      memset( &historyParam, 0, sizeof(FD_HistoryAllocParam) );
      historyParam.category = "US.NASDAQ.STOCK";
      historyParam.symbol   = "LNUX";
      historyParam.period   = FD_DAILY;
      historyParam.field    = FD_CLOSE|FD_VOLUME;      
      retCode = FD_HistoryAlloc( unifiedDatabase, &historyParam, &data );

      if( retCode == FD_SUCCESS )
      {
         for( i=0; i < data->nbBars; i++ )
            printf( "%f %d\n", data->close[i], data->volume[i] );
         FD_HistoryFree( data );
      }
   }

   /* Clean-up and exit. */
   FD_UDBaseFree( unifiedDatabase );
   FD_Shutdown();

   return 0;
}

EXAMPLE (3)

#include "fidal.h"
#include <stdlib.h>
#include <string.h>

int main( void )
{
   FD_UDBase   *unifiedDatabase;
   FD_RetCode  retCode;
   FD_InitializeParam initParam;
   FD_AddDataSourceParam addParam;

   /* Initialize the access to the library. */
   memset( &initParam, 0, sizeof( FD_InitializeParam ) );
   if( FD_Initialize( &initParam ) != FD_SUCCESS )
      exit( -1 );

   if( FD_UDBaseAlloc( &unifiedDatabase ) != FD_SUCCESS )
   {
      FD_Shutdown();
      exit( -2 );
   }

   /* Add all ASCII files with a "dat" extension.
    * These are going to be added in the default
    * "ZZ.OTHER.OTHER" category.
    * This advanced example use fields definition for
    * handling specific file content. In that case, only
    * monthly data with only the Close value and the Volume
    * is provided by the data file.
    * The [SYM] fields indicates where the symbol name is
    * going to be extracted from. It could have been from
    * anywhere in the path!
    * See documentation for this flexible feature.
    */
    memset( &addParam, 0, sizeof( FD_AddDataSourceParam ) );
    addParam.id = FD_ASCII_FILE;
    addParam.location = "..\\download\\[SYM].dat";
    addParam.info = "[YYYY][MM][C][V]";
    addParam.category = "US.NASDAQ.STOCK";

    retCode = FD_AddDataSource( unifiedDatabase, &addParam );

    if( retCode != FD_SUCCESS )
       printf( "Cannot add data source (%d)\n", retCode );
    else
    {
       /* The following function will output on screen all category
        * and symbols that are now part of the unified database.
        */
       FD_Report( unifiedDatabase, stdout, FD_REPORT_CATEGORY | FD_REPORT_SYMBOL );
    }

   /* Free all ressources. */
   FD_UDBaseFree( unifiedDatabase );
   FD_Shutdown();

   return 0;
}


Google  SourceForge Logo
  Web FidalSoft.org
 

Copyright? 2006 TicTacTec LLC. All Rights Reserved. Last Update: 07/21/06, Unique Visitor: