FastTrack Family DLL - Updated 06/16/14
The FastTrack Family DLL is the interface to the FastTrack families, both FastTrack and user-defined.
Introduction
This program can be called by other applications to read, delete, and rename FastTrack families. This program is used extensively within FastTrack Charting and ranking to provide access to families.
It is important to use this DLL in your applications as FastTrack may change the method of providing families without notice in future versions. However, we intend to maintain binary compatibility of the DLL so that all dependent programs will continue to function normally after any such changes.
DO NOT treat families as files in your own code. Use the methods of this DLL. In several places, the description of the calls makes reference to the family files as they existed in FT4DOS and FT4WEB in the 20th century. These references are a courtesy to developers of programs that used family files directly. Any new programs should not incorporate the concept that a family is a file . . . indeed we intended to build families into a database structure in the future.
Binary compatibility is a complex concept promoted by Microsoft, implemented in Microsoft development tools, and in a variety of independent developer tools. FastTrack will not be responsible for the failure of the FastTrack Family DLL to operate in all environments. Support is on a best effort basis. Call technical support at (866) 295-0166.
FamiRead Object
Object Name: FamiRead
File Name: FTFAMRED. DLL
Events: 1
Methods: 9
Before you can use the FamiRead object in your application, you must add the FTFAMRED. DLL file to your project's references. If you use the object in most of your VB projects, you may want to add it to VB's Autoload file.
To distribute applications you create with the FamiRead object, you must install and register it on the user's computer. Registration is taken care of automatically during a FTCOMM upgrade.
FamiRead has no visual interface. However, it is used within FastTrack to provide the family information for the Family Tree (Treeview) controls.
Dependencies and Licensing
The FastTrack Family DLL makes extensive use of routines found in the STAMIN32.DLL file. This is a wonderful, fast, powerful set of utility routines available at www.microdexterity.com. You cannot use FTFAMRED.DLL in a development environment without licensing STAMIN32.DLL . . . no VB programmer should be without STAMIN32.DLL. You must get a license for it as we will not supply them.
You can distribute FTFAMRED. DLL and STAMIN32.DLL to your users without royalty.
Environment Requirements
The FTFAMRED. DLL file must exist in the windows\system or windows\system32 folder. To define the location of the FT4WIN folder. The WIN.INI file commonly found in C:\WINDOWS must contain a section as follows,
[FT4WIN] Path=C:\FT
The folder specified by Path must contain the following folders
FTDEF Mutual fund families. One named FIDELITY is required.
USERDEF User defined families, but none are required.
Optional
FT4WIN\SFTDEF Stock families, but none are required.
Warning: If you put FTFAMRED. DLL or famioies into a folder other than the folders as defined above, then the FastTrack upgrade process that maintains and upgrades the families will not be able to replace them during the program upgrade process.
Third party program using FTFAMRED. DLL may access it as a normal, registered, ActiveX DLL. Within the VB environment, it would be listed under Project/References menu item.
The categories within FT4Web's Charting program for Stock/Mutual Fund tree on the Family Tab are arbitrary. Families may mix issues of all types. FastTrack Charting's Family Tree separate Issues into many arbitrary Categories based on the folder that contains them, the family name, and the family description. This categorization is a feature of the visual family tree, and not this DLL. Placing user-defined families in any folder other than USERDEF is NOT supported.
FamiRead Properties, Events, and Methods
All of the properties, events, and methods for the FamiRead control are listed in the following tables. Properties, events, and methods that apply only to this control, or that require special consideration when used with it, are marked with an asterisk (*). These are documented in later sections. For documentation on the remaining properties, see the Visual Basic documentation.
Common Arguments Defined
-
FamName is the family name that conforms to Win32 file naming conventions. However, this is not a file name. It cannot include a path or extensions. While in FT4WEB version 3.0 and lower the family name always had an associated .FAM file name, there is no assurance that families will continue to be structured this way. Applications which read family files directly will eventually become incompatible with FT4WEB.
-
FamDesc is a string describing the family up to 72 characters long. It many not contain a comma character, and should not contain any characters which are not ASCII printable characters.
-
FamMembers( ) is a string array of ticker symbols that is returned by some of the methods.
-
FamType may be
-
USERDEF: User defined families.
-
FTDEF: FastTrack-defined Mutual Fund Families
-
FastTrack defined Stock Families
-
Sym is a 1-5 letter ticker symbol as defined within FastTrack.
Properties
Rebuild Property
Syntax: [form!]FamiRead.Rebuild [ = {True | False} ]
When your program adds, deletes, renames any family, or a FamDesc changed, set this value to True in your program. Subsequent FastTrack Family DLL methods that require a current family list or description will invoke the ReBuildIX method when the ReBuild property is true.
DO NOT confuse this property with the similarly named method ReBuildIX.
Events
FamilyChange Event
Syntax: Private Sub FamiRead_FamilyChange ()
The control evokes this event in the calling program when an action adds or deletes a family. This event also fires, when a family is saved AND its description is changed.
For example, when this event fires within the FastTrack Charting Family Tree, the visual Family Tree is refreshed.
Methods
DeleteFamily Method
Syntax: Return& = [form!]FamiRead.DeleteFamily (Byval FamName As String)
Only user defined families can be deleted. Actually, when each family is "deleted" it is renamed to UNDO_DELETE . The prior UNDO_DELETE family is actually deleted.
The method returns
- 0 on success,
- -1 if family does not exist
- -2 if family is a FastTrack defined family that cannot be deleted. Only families in the USERDEF folder can be deleted.
This method sets the Rebuild property to True.
Exists Method
Syntax: Return = [form!]FamiRead.Exists ( Byval FamName As String )
The method returns a Boolean value.
- True If the FamName exists. However, there is no validity check at this point. The family may contain no members or be corrupt.
- False The family file is not found anywhere.
Commonly, you will use this function in an IF statement with the syntax,
IF Form1.FamiRead.Exists("FIDELITY") then . . .
GetFamInSeq Method
Syntax: Return& = [form!]FamiRead.GetFamInSeq (Byval I As Integer, FamName As String, optional FamDesc As String, optional FamType As String)
This method returns FamName, FamDesc, and FamType for every family, one at a time. You have no control over the sequence in which the families are returned. To use this method, keep incrementing I until the method returns a -1. I does not necessarily stay the same for a particular family. When you add or delete families, I will refer to a different family.
- Return& = 0 when the function is successful.
- Return& = -1 when I has exceed the number of families.
- Return& =-2 when no families exist. There is some problem building the list of families. Check paths to be sure that the conform to specifications.
- Return&=-3 General program failure. A common cause is that the I argument should start with a value of 1, not 0.
Code example
I=1
DO
NX&=FamiRead.GetFamInSeq (I%,FamName$,FamDesc$
if NX&<-1 then msgbox "error . . . "
I = I + 1
Loop until NX&=-1GetFamsWithIssue Method
Syntax: Return& = [form!]FamiRead.GetFamsWithIssue (Byval Sym As String) As String
Sym is a 1-5 letter ticker symbol of an issue.
This method removes all the families, whose members do not include Sym, from the list of families delivered by the GetFamInSeq method. You may use this method multiple times to narrow the list. To restore the full list, invoke the RebuildIX method.
- Return& = 0 when the function is successful.
- Return& = -1 when the resulting list of families is empty (none contained Sym).
- Return& = -2 when Sym is not a valid symbol (for example, an empty string).
The Method does NOT change the Rebuild property. As such, your program must eventually invoke the RebuildIX method or the list of families will continue as reduced by this method. If the ReBuild property is set to true by certain subsequent methods, then the reduced list will be lost.
IsIssue Method
Syntax: Return& = form! FamiRead.IsIssue (Byval Sym As String) As Boolean
Sym is 1-5 characters.
use this method to determine if Sym can be saved within as a member of a family. This function is somewhat broader than the FTisFTIssue function available in the fasttrack.dll.
- Return& = True when Sym is a rate of return ( like "10%"), a symbol in the FT database, or an existing FNU file name.
- Return& = False Sym is not one of the above.
NameValid Method
Syntax: Return& form! FamiRead .NameValid (Byval FamName As String, Optional FamDesc as String) As String
FamName is a valid long-filename. If the family is to be used by FT4DOS, then the name should be limited to a valid DOS name. However, no checking is done to ensure name compatibility with DOS.
FamDesc is the family description. If the optional FamDesc is included, then it is validated. The only check for validity is that the description may not contain a comma character.
- Return& = True when the FamName is a valid FT family name.
- Return& = False when the FamName is invalid. or the FamDesc contains a comma.
ReadFam Method
Syntax: Return& = [form!]FamiRead.ReadFam (Byval FamName As String, FamMembers() As String, Optional FamDesc As String, Optional NumMems As Integer)
Reads a family returning an array of variable length strings, FamMembers(), which are the symbols of the issues in the family. Strings are always trimmed (no blanks on end) and capitalized.
- Return& = 0 when the function is successful.
- Return& = -1 when the family does not exist.
- Return& = -2 if the FamName exists, has no members, or is otherwise corrupted.
The Optional arguments do not have to be used. If they are used, the values of returned. NumMems is the number of members in the family. You could also get this value by examining Ubound(FamMembers). FamMembers( ) is dimensioned from 1 to NumMems.
ReadFamHeader Method
Syntax: Return& = [form!]FamiRead.ReadFamHeader (Byval FamName As String, FamType As String, FamDesc As String, Optional FamMembers As Integer)
This method requires the FamName argument and returns other parameters.
- Return& = 0 when the function is successful.
- Return& = -1 when the family does not exist.
- FamMembers% = when this parameter is passed with nonzero value, then the family members will be read and counted in addition to the header and FamMembers will return the number of members in the family. If FamMembers is passed as 0, then no members are read and FamMembers remains zero in the return. Use this call to speed up family header reading when the number of family members is unimportant.
Rebuild Property
Syntax: [form!]FamiRead.Rebuild[ = {True | False} ]
When this property' value is true, it means that methods your program used in the dll method (like creating a new family) which has made it necessary to rebuild the list of families internal to the dll. This takes a few seconds so the rebuilding is not triggered immediately. Your application program may test the value of the Rebuild property and use the RebuildIX method to rebuild at an appropriate time. However, even if your application never invokes RebuildIX, then REBUILDIX will automatically be run whenever needed for other methods of the dll.
If your application changes family names, descriptions, deletes or creates new families, then your application program should set REBUILD to true.
ReBuildIX Method
Syntax: Return&= [form!] FamiRead.ReBuildIX
Rebuilds the internal index of families and descriptions inside FastTrack Family DLL. Your program may use ReBuildIX, but should seldom have to do so. The one instance within FastTrack Charting that uses ReBuildIX is when clicking the
button on the Family Tab
to restore the full family tree after using the 
button to prune the family tree. - Return& = 0 when the function is successful.
- Return& = -1 when the event fails. The only known cause of failure is that the Environment Requirements are not met.
The Method sets the Rebuild property to False.
RenameFamily Method
Syntax: Return& = [form!]FamiRead.RenameFamily( Byval OldFamName As String, Byval NewFamName As String)
Renames an existing family. Only families in the USERDEF folder may be renamed.
- Return& = 0 when the function is successful.
- Return& = -1 when the OldFamName does not exist.
- Return& = -1 when the OldFamName specifies a FastTrack-defined family that the user cannot rename.
- Return& = -2 when the NewFamName already exists.
The Method sets the Rebuild property to True.
WriteaFamily Method
Syntax: Return& = [form!]FamiRead.WriteaFamily(Byval FamName as String, FamMembers() as String, FamDesc as String)
All fields are required. FamMembers( ) strings are trimmed of spaces and made upper case before being saved in a family
- Return& = 0 when a family that previously did not exist has been written successful.
- Return& = 1 when the method successfully overwrites an existing family.
- Return& = 2 when the method successfully makes a family with corrupt or missing members.
- Return& = -1 when FamName specifies is invalid. use the NameCheck method before attempting to WriteaFamily
- Return& = -4 when the FamName specifies a FastTrack-defined family. You must use a different name.
The Method sets the Rebuild property to True when the FamName specifies a family that does not exist or when the FamDesc of an existing family has changed.
Programming Notes
In a module, place
Global WithEvents FTFam As FamiRead (in declarations)
Set FTFam = New FamiRead (in the first method/subprocedure/function you call)OR
In the main Usercontrol or Form of your application, place
Public WithEvents FTFam As FamiRead (in declarations)
Set FTFam = New FamiRead (in the first method you call)In any Usercontrol or Form of your application that needs family access, place
Public FTFam As FamiRead (in declarations)
Set FTFam = Parent.FamiRead (in the first method you call)The Set FTFam above cannot be executed in a class or Usercontrol Initialize procedure since the Parent will be unknown at that time.
The goal of the above, which may be accomplished with other forms of code, is to have only a single instance of the FastTrack Family DLL loaded in a project. Loading multiple occurrences is permissible, but there is substantial memory and CPU overhead in doing so and the internal family lists may not stay in synchronization. This code creates the DLL as an object in the Parent and uses that Parent's object in the Usercontrol.
The DLL doesn't execute a DoEvents statement at any time, this means that all methods complete their tasks without interruption. Your own code should not use DoEvents until all the processing in your own code as needed after the return of a DLL call is complete.
-