| AMIBROKER TIPS | weekly newsletter | issue 1/2000 |
Welcome to a new AmiBroker Tips newsletter! My intention is to provide you
with a periodical source of information about using AmiBroker. For the start
it will be a rather small bag of tips and tricks. I would like to include the
information about managing your data, writing AFL formulas and all other things
that you will find useful. So please don't hesitate to write about the things
you would like to get explained. I also encourage you to write some articles
for this newsletter if you want to share with your solutions with the others.
By the way: do you have an idea on some cool name for this newsletter? Mail your suggestions to newsletter@amibroker.com
For the start I have prepared a rather advanced article about using automation with AmiBroker. Less experienced (in programming) users may just use pre-written scripts included with the article.
Just in case you haven't noticed: on November 1st, 2000 AmiBroker/Win32 has been released. It is available for download from http://www.amibroker.com/download.html. Please upgrade to the latest version - because it brings several new features including brand new system test reporting, new studies like Fibonacci retracement and timezones, faster database engine, and more. All tips that I will describe in this newsletter will work best with the new version (old versions may miss some features).
III. Tip of the week: Accessing stock data using AmiBroker's automation interface
3.1 Introduction
In this article I want to show the ways to enhance the functionality of AmiBroker by using scripts. Scripting is rather advanced topic since it requires a little bit of programming work. Those of you who don't want to touch programming may just use supplied scripts. I hope that you will find them useful. Advanced users may modify those scripts for their own needs.
3.2 What is automation?
Automation (also known as OLE Automation) makes it possible for one application to manipulate objects implemented in another application, or to "expose" objects so they can be manipulated. AmiBroker acts as an automation server. An Automation server is an application that exposes programmable objects to other applications, which are called Automation clients. Exposing programmable objects enables clients to automate certain procedures by directly accessing the objects and functionality the server makes available. You can access automation server's objects from a number of programming languages including C/C++, Visual Basic, VBScript and JScript. Especially two latter languages (VBScript and JScript) are interesting from your point of view because: a) they are scripting (interpreted) languages - no compilation is required; b) they are available for free as a part of Windows Scripting Host (WSH).
3.3 What is Windows Scripting Host?
The Windows Scripting Host (WSH) is a language-independent scripting host for 32-bit Windows platforms. Microsoft provides both Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft® JScript™ scripting engines with WSH. Other software companies will provide ActiveX™ scripting engines for languages such as Perl, TCL, REXX, Python, and others. Windows Scripting Host is integrated into Windows® 98, Windows 2000. It is also available as a free component for Windows 95 and NT4.0 (you can download it from http://msdn.microsoft.com/scripting/windowshost/default.htm ). Windows Scripting Host can be run from either the Windows-based host (Wscript.exe), or the command-shell-based host (Cscript.exe). VBScript and JScript files are simple text files, so you can use even Notepad to edit them. VBScript files have default .vbs extension while JScript files have .js extension. The Windows Explorer is set up by default in such a manner that double clicking on .js or .vbs script file causes executing it.
3.3 How AmiBroker supports automation/scripting?
AmiBroker exposes a number of automation objects (described in Automation Object Model Reference section of AmiBroker's User guide). These objects can be accessed from a number of languages including WSH's VBScript and JScript. In this article we will use JScript (a Microsoft dialect of Java Script). AmiBroker objects are organized in a hierarchy show in the picture below (not all objects shown):
As you can see all objects are accessible from the parent Application object. So all your scripts must first create AmiBroker Application object and then access the objects located deeper in the hierarchy. In the picture above you can see that some of the objects have yellow color - these object represent collections. A collection is an object that contains zero or more objects of the same class. So Stocks collection contains zero or more objects of the Stock class. Collections are used mainly to interate thru objects and manage adding/removing of the objects belonging to a collection. As you can guess you will work the most often with a Stocks and Quotations collection and a Stock and Quotation objects. These (and other) objects expose properties that are data members of the object. The value of the property can be retrieved or set (if the property is not read-only). For example Quotation object has Date, Open, Close, High, Low, Volume, OpenInt properties that holds this quotation data. A complete list of properties of AmiBroker objects' properties can be found in Automation Object Model Reference section of AmiBroker's User guide. Object could have also methods. A method is aprocedure that is exposed by an object and performs a specific action (for example Application object has a method called RefreshAll() which refreshes all views and lists of AmiBroker).
3.4 Accessing AmiBroker's object
NOTE: Now we will write some JScript code - if you want to experiment a little
please lauch any plain text editor (it could be even Notepad) to write the code
- you work should be saved to the file with .JS extension in order to enable
it to run by WSH.
In order to gain an access to any AmiBroker object you have to create AmiBroker Application object. This can be done by following JScript code:
var oAB = WScript.CreateObject("Broker.Application");
Note that WScript is a built-in object of Windows Scripting Host. The same effect can be obtained by the following:
var oAB = new ActiveXObject("Broker.Application");
Note that we don't use WScript object now. In both cases oAB object is an actual AmiBroker Application object. We can now access its methods and/or properties. For example we can close AmiBroker programmatically by calling Quit() method:
oAB.Quit();
You now give it a try: enter above lines in the text editor, save the file under the name Quit.js , launch AmiBroker by hand, and double click on the Quit.js file in the Windows Explorer. You will see that AmiBroker has closed.
Application object gives you an access to other object such as Stocks collection. For example the full name of the first stock in the list could be by:
oAB.Stocks.Item( 0 ).FullName;
or
oAB.Stocks( 0 ).FullName;
The latter method works because Item( ) is the default property of Stocks collection. Stocks collection elements could be also referenced by name for example:
oAB.Stocks( "^DJI" ).FullName;
Now it's the time for something more complicated but also more useful.
3.5 Example 1: Exporting stock information to the text file
In this example we will write the script that exports stock information (full name, address, industry, market and group assignments) to a comma separeted values text file.
Let's begin with creating AmiBroker Application object and FileSystem object. The latter object will be used to create and write text to a disk file.
var oAB = new ActiveXObject("Broker.Application");
var fso = new ActiveXObject("Scripting.FileSystemObject");
file = fso.OpenTextFile( "Info.txt", 2, true );
In the third line we create a text file called "info.txt" with write access (2). The second parameter (true) tells file system that we are creating a new file.
Then we will retrieve the number of stocks in the Stocks collection:
var oStocks = oAB.Stocks;
var Qty = oStocks.Count;
Now we can iterate through stocks retrieving needed information and writing them to the file:
for( i = 0; i < Qty; i++ )
{
oStock = oStocks( i );
file.Write( oStock.Ticker + "," );
file.Write(oStock.FullName + "," );
file.Write( oStock.Address + "," );
file.Write( oStock.IndustryID + "," );
file.Write( oStock.MarketID + "," );
file.WriteLine( oStock.GroupID );
}
file.Close();
WScript.Echo("Export finished" );
As you can see we use Write() and WriteLine() methods of file object to write the text to a disk file. WriteLine() is different from Write() in that it simply adds a new line character at the end of text written. As an excercise you can add other properties to the list such as oStock.BookValue, oStock.Issue and so on. Also financial data (quaterly income, earnings) could be accessed in that way. Note that you need to supply quarter number (0-3) for accessing these properties. For example oStock.FinanceEAT( 0 ) accesses first (zero based index) quarter earnings after taxes.
A ready to use script can be found here.
3.6 Example 2: Exporting quotation data
In this example we will write the script that exports all quotations of currently selected stock to the CSV file.
As before we will start with creating AmiBroker Application object and FileSystem object.
var oAB = new ActiveXObject("Broker.Application");
var fso = new ActiveXObject("Scripting.FileSystemObject");
Then we will determine ticker of currently selected stock and we will create a file called <TICKER>.CSV . Then we will retrieve the number of quotations of that stock.
Ticker = oAB.ActiveDocument.Name;
file = fso.OpenTextFile( Ticker + ".csv", 2, true );
var oStocks = oAB.Stocks;
oStock = oStocks( Ticker );
var Qty = oStock.Quotations.Count;
Now we will iterate through quotes and write them to the CSV file:
for( i = 0; i < Qty; i++ )
{
oQuote = oStock.Quotations( i );
var oDate = new Date( oQuote.Date );
file.WriteLine( oStock.Ticker + "," +
oDate.getFullYear() + "-" + oDate.getMonth()+1 + "-" + oDate.getDate() + "," +
oQuote.Close + "," +
oQuote.Open + "," +
oQuote.High + "," +
oQuote.Low + "," +
oQuote.Volume );
}
file.Close();
Yes... it's that simple! When you try this script you will find that price values are listed with too many decimal digits, therefore additional formatting may be needed to make this script nicer. Also we may want to include AmiBroker's style $FORMAT command that specify the data layout in the file so it could be easily imported back to AmiBroker.
These and other improvements are included in the ready to use version of the script. A special FormatFloat() function is used to cut the number to 2 decimal places.
3.7 Conclusion
AmiBroker's automation interface allows the user to extend AmiBroker's functionality by writing the scripts that implement features that could not be found in AmiBroker itself. Automation interface is the one of AmiBroker's features that decide on its flexibility and extensibility not often found in competitors' products.