FastTrack API

The FastTrack API IS  the interface to the FastTrack database and FNU files.

• Introduction
• Requirements
• Function Listing
  • Initialization and Cleanup Functions
    • FTopen
    • FTclose
    • FTrebuildSymbols
  • Issue Access Functions
    • FTgetIssue
  • Auxiliary Functions
    • FTisFTIssue
    • FTgetIssueName
    • FTgetName
    • FTgetNumDays
    • FTgetMaxDaysBySym
    • FTgetStartDateBySym
  • Utility Functions
    • FTgetFTDir
    • FTgetJulian
    • FTgetMaxDays
    • FTgetMaxNumDays
    • FTgetMarketDay
    • FTgetNumSyms
    • FTgetSymSize
    • FTgetNameSize
    • FTgetPathSize
    • FTgetDLLVersion
  • Symbol Iterator Functions
    • FTgetIssueIter
    • FTissueNext
    • FTcloseIssueIter
  • Convenience Functions (For C and C++ users)
    • FTjulian2time_t
    • FTjulian2tm
• Terms and Definitions
• Standard Error Codes

Introduction

Why use FastTrack.dll?

Of course, we may enhance the features of the DLL and the databases from time to time. To use any such new features, you would, of course, have to revise your programs . . . BUT THE GOAL is to maintain a standard set of features forever so that your programs will always work with new symbols and databases in a totally transparent manner.

Standard Disclaimer:

Requirements

Function Listing

Format

Function Name

• VB Declaration:
  This is the Visual Basic declaration of the function
• Parameters:
  The function parameters go here. The format is:
  name - direction - description
  where direction is in, out, or in/out, depending on whether the parameter is passed to the function (in), is returned from the function (out), or both (in/out).

  Note on strings:

  When a string is to be returned from a function, it must be big enough to hold the returned value. In Visual Basic, this can be done either by dimensioning it large enough, or by filling it with enough characters.

  Examples:

  • Dim sym As String * 5
  • Dim namesize As Long
    Dim name As String
    namesize = FTgetNameSize
    name = String$ (namesize, " ")

  We recommend that the latter method be used, because then the string sizes can be dynamically sized (using functions such as FTgetNameSize)

  Some notes on arrays:

  • When a array is to be passed to or from a function, it must be dimensioned so that the specified lower and upper bounds are valid. For example, the prices array is specified to be dimensioned from 0 to maxnumdays; therefore, the lower bound must be at most 0, and the upper bound must be at least maxnumdays.
  • Also, when an array is passed to or from a function, pass the first element. For example, to pass the prices array prices, use prices (0) for the parameter.

  Example:

  maxnumdays& = FTgetMaxNumDays ()
  sym = "FMAGX" ' sym is defined above
  Dim prices (maxnumdays&) as Single
  If FTgetIssue (sym, prices (0)) <> 0 Then
      ' some kind of error has occurred
      ' see standard error codes to see what went wrong
      End If

• Return value:
  Only functions have this section. Generally, functions return a standard return value. Most of the "get" functions, however, return a positive integer on success, representing the value requested, or a standard error code on failure. And some functions merely return boolean values.
• Purpose:
  The purpose of the function goes here.
• Notes:
  Some functions may have a notes section. Things that do not fit in any of the other sections go here.

Initialization and Cleanup Functions

FTopen

• VB Declaration:
  Declare Function FTopen Lib "FastTrack" () As Long
• Parameters:
  None
• Return value:
  standard return value
• Purpose:
  Initialize the DLL
• Notes:
  • The FastTrack DLL automatically initializes itself. FTopen returns the result of that initialization. If FTopen returns an error value, then most of the other functions will also return that error value until the error condition is cleared up.
  • If FT_BADSYMBOLS is returned, the symbols file needs to be rebuilt. This can be done by calling FTrebuildSymbols.
  • Some functions can be called even if the DLL is in an error condition. These functions are: FTgetFTDir, FTgetSymSize, FTgetNameSize, FTgetPathSize, FTgetDLLVersion, FTjulian2time_t, and FTjulian2tm.

FTclose

• VB Declaration:
  Declare Sub FTclose Lib "FastTrack" ()
• Parameters:
  None
• Purpose:
  Unload the DLL
• Notes: The FastTrack DLL automatically unloads itself. FTclose can be used if it doesn't unload quickly enough. Note that if you decide to use this function to force unloading, every FTopen must be followed by an FTclose.

FTrebuildSymbols

• VB Declaration:
  Declare Function FTrebuildSymbols Lib "FastTrack" () As Long
• Parameters:
  None
• Return value:
  standard return value
• Purpose:
  Rebuild the symbols file, and then reset the DLL.
• Notes: Calling this many times may cause a memory leak.

Issue Access Functions

FTgetIssue

• VB Declaration:
  Declare Function FTgetIssue Lib "FastTrack" (ByVal sym As String, prices As Single) As Long
• Parameters:
  sym - in - the issue symbol
  prices - out - the prices array (see Some notes on arrays)
• Return value:
  standard return value
• Purpose:
  Get the prices for sym
• Notes: The prices array must be dimensioned properly (from 0 to maxnumdays), or Bad Things will happen (that is, a crash, or worse).

Auxiliary Functions

FTisFTIssue

• VB Declaration:
  Declare Function FTisFTIssue Lib "FastTrack" (ByVal sym As String) As Boolean
• Parameters:
  sym - in - the issue symbol
• Return value:
  true - sym is recognized as a FastTrack or user issue
  false - sym is not recognized as a FastTrack or user issue
• Purpose:
  Return true if the symbol is either in one of the databases or is an FNU file

FTgetIssueName

• VB Declaration:
  Declare Function FTgetIssueName Lib "FastTrack" (ByVal sym As String, ByVal name As String) As Long
• Parameters:
  sym - in - the issue symbol
  name - out - the issue name (see Note on strings - FTgetNameSize returns the minimum size)
• Return value:
  standard return value
• Purpose:
  Get the name of sym

FTgetName

• VB Declaration:
  Declare Function FTgetName Lib "FastTrack" (ByVal sym As String, ByVal name As String, ByVal GetShortName As Integer) As Long
• Parameters:
  sym - in - the issue symbol
  name - out - the issue name (see Note on strings - FTgetNameSize returns the minimum size)
  GetShortName - in - return short name or long (1 for short, 0 for long)
• Return value:
  standard return value
• Purpose:
  Get the name of sym

FTgetNumDays

• VB Declaration:
  Declare Function FTgetNumDays Lib "FastTrack" (ByVal sym As String) As Long
• Parameters:
  sym - in - the issue symbol
• Return value:
  n > 0 - n is the market day of the last day of data for sym
  n < 0 - n is a standard error code
• Purpose:
  Return the market day of the last day of data for sym

FTgetMaxDaysBySym

• VB Declaration:
  Declare Function FTgetMaxDaysBySym Lib "FastTrack" (ByVal sym As String) As Long
• Parameters:
  sym - in - the issue symbol
• Return value:
  n > 0 - n is the maximum number of days that sym's database can have
  n < 0 - n is a standard error code
• Purpose:
  Return the maximum number of days that sym's database can have
• Notes: Do not use this function to dimension the prices array for FTgetIssue. Use FTgetMaxNumDays or Bad Things will happen (that is, a crash, or worse).

FTgetStartDateBySym

• VB Declaration:
  Declare Function FTgetStartDateBySym Lib "FastTrack" (ByVal sym As String) As Long
• Parameters:
  sym - in - the issue symbol
• Return value:
  n > 0 - n is the market day of the start date for sym
  n < 0 - n is a standard error code
• Purpose:
  Return the market day of the start date for sym

Utility Functions

FTgetFTDir

• VB Declaration:
  Declare Function FTgetFTDir Lib "FastTrack" (ByVal dir As String) As Long
• Parameters:
  name - out - the directory that FastTrack is installed in (see Note on strings - FTgetPathSize returns the minimum size)
• Return value:
  standard return value
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Get the FastTrack installation directory

FTgetJulian

• VB Declaration:
  Declare Function FTgetJulian Lib "FastTrack" (ByVal i As Long) As Long
• Parameters:
  i - in
• Return value:
  n > 0 - n is the julian date associated with the index i in the julian date array
  n < 0 - n is a standard error code
• Purpose:
  Return julian date associated with the index i in the julian date array
  

FTgetMaxDays

• VB Declaration:
  Declare Function FTgetMaxDays Lib "FastTrack" () As Long
• Return value:
  n > 0 - n is the maximum number of days of data that any database can have
  n < 0 - n is a standard error code
• Purpose:
  Return the maximum number of days of data that any database can have

FTgetMaxNumDays

• VB Declaration:
  Declare Function FTgetMaxNumDays Lib "FastTrack" () As Long
• Parameters: None
• Return value:
  n > 0 - n is the market day of the last day of data of the most current database
  n < 0 - n is a standard error code
• Purpose:
  Return the market day of the last day of data of the most current database

FTgetMarketDay

• VB Declaration:
  Declare Function FTgetMarketDay Lib "FastTrack" (ByVal day As Long) As Long
• Parameters:
  day - in
• Return value:
  n > 0 - n is the market day associated with day is the julian date array
  n < 0 - n is a standard error code
• Purpose:
  Return the market day for day

FTgetNumSyms

• VB Declaration:
  Declare Function FTgetNumSyms Lib "FastTrack" () As Long
• Return value:
  n > 0 - n is the number of symbols recognized by the DLL
  n < 0 - n is a standard error code
• Purpose:
  Return the number of symbols that are recognized as FastTrack issues, that is, the number in at least one of the database files, plus those that are FNUs.

FTgetSymSize

• VB Declaration:
  Declare Function FTgetSymSize Lib "FastTrack" () As Long
• Return value:
  n > 0 - n is the number of characters needed to hold an issue symbol
  n < 0 - n is a standard error code
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Return the number of characters needed to hold an issue symbol

FTgetNameSize

• VB Declaration:
  Declare Function FTgetNameSize Lib "FastTrack" () As Long
• Return value:
  n > 0 - n is the number of characters needed to hold an issue name
  n < 0 - n is a standard error code
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Return the number of characters needed to hold an issue name

FTgetPathSize

• VB Declaration:
  Declare Function FTgetPathSize Lib "FastTrack" () As Long
• Return value:
  n > 0 - n is the number of characters needed to hold a directory path
  n < 0 - n is a standard error code
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Return the number of characters needed to hold a directory path

FTgetDLLVersion

• VB Declaration:
  Declare Function FTgetDLLVersion Lib "FastTrack" (version As Long, major As Long, minor As Long) As Long
• Parameters:
  version - out - the most significant part of the version
  major - out - the major part of the version
  minor - out - the minor part of the version
• Return value:
  n > 0 - n is the encoded version number of the FastTrack DLL, combining version, major, minor and a patch level in one number.
  n < 0 - n is a standard error code
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Return the FastTrack DLL version number
• Notes:
  It is guaranteed that, if there are two versions of the FastTrack DLL, FTgetDLLVersion will return a larger number for the later version.

Symbol Iterator Functions

Basically, use these functions like this (Visual Basic code):
Dim iter As Long
Dim sym as String * 5
iter = FTgetIssueIter
While (FTissueNext (iter, sym))
     ' use sym here
     Wend
FTcloseIssueIter (iter)

Note that you can have more than one iterator open at a time.

FTgetIssueIter

• VB Declaration:
  Declare Function FTgetIssueIter Lib "FastTrack" () As Long
• Parameters:
  None
• Return value:
  an iterator handle
• Purpose:
  Initialize and return an iterator handle

FTissueNext

• VB Declaration:
  Declare Function FTissueNext Lib "FastTrack" (ByVal iterno As Long, ByVal sym As String) As Boolean
• Parameters:
  iterno - in - an iterator handle
  sym - out - the issue symbol (see Note on strings - FTgetSymSize returns the minimum size)
• Return value:
  true - Operation succeeded
  false - Operation failed, or no more issues
• Purpose:
  Return the next issue symbol from the iterator iterno

FTcloseIssueIter

• VB Declaration:
  Declare Sub FTcloseIssueIter Lib "FastTrack" (ByVal iterno As Long)
• Parameters:
  iterno - in - an iterator handle
• Purpose:
  Free the resources pointed to by iterno
• Notes:
  Always close any open iterators.

Convenience Functions (For C and C++ users)

FTjulian2time_t

• C Declaration:
  long __stdcall FTjulian2time_t (long jul, time_t *t);
• C++ Declaration:
  long __stdcall FTjulian2time_t (long jul, time_t &t);
• Parameters:
  jul - in - a julian date
  t - out - the corresponding date
• Return value:
  standard return value
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Convert a julian date to a struct time_t

FTjulian2tm

• C Declaration:
  long __stdcall FTjulian2tm (long jul, struct tm *t);
• C++ Declaration:
  long __stdcall FTjulian2tm (long jul, tm &t);
• Parameters:
  jul - in - a julian date
  t - out - the corresponding date
• Return value:
  standard return value
  Because this function can be used even if the DLL is in an error state, the return value reflects the state of this function only, and not the DLL as a whole.
• Purpose:
  Convert a julian date to a tm value

Terms and Definitions

iterator handle

A long integer value representing a issue iterator, which can be used to iterate through the issue in the FastTrack database files and FNUs.

julian date

A long integer value representing a date. This format is readily understood in Visual Basic. (For other languages, it is the number of days since December 30, 1899.)

julian date array

An array -- from 0 to maxnumdays -- of julian dates, one for each day there is data for in the database files plus 1 (every market day has one, and only one entry. Zero is not used.) FTgetJulian indexes into this array, and FTgetMarketDay does the reverse -- it returns the index corresponding to the market day passed to it (if the market was not open on that day, it returns an appropriate substitute).

market day

A long integer value representing the index (of a prices array) to the corresponding julian date in the database files and FNUs -- if a corresponding date does not exist, it is the index of the next smallest date. Note that the market day is between 1 and maxnumdays. (See also julian date array.)

maxdays

A long integer value representing the maximum number of days of a particular issue.

maxnumdays

A long integer value representing the the market day of the last day of data of the most current database.

prices array

An array of single-precision values, from 0 to maxnumdays, representing the dividend-adjusted prices of a issue. Note that even though the array has a lower bound of 0, there are valid prices only from 1 up. FTgetJulian can be used to convert the index of the prices array into its corresponding julian date.

symbol

The (up to) 5 character string uniquely representing an issue, usually a ticker symbol.

standard return value

Either 0 for success, or a standard error code for failure.