Commodity Systems Incorporated

200 W. Palmetto Park Road

Boca Raton, FL 33432

TITLE: Unfair Advantage API (API2) Functional Specification

STAGE: Released

DATE: , 1998

RELEASE:

Prepared by :_________________________________________ ____________

JOSHUA REED Programmer Date

Approved by :_________________________________________ ____________

Bob Pelletier President Date

This document is the Functional Specification for the CSI Unfair Advantage API (API2). The intent of this document is as follows:

API2 is an interface between Unfair Advantage (UA) and a client software product. The interface provides a way for the client software to request commodity price data. UA responds to interface requests by checking licensing information, retrieving the data, and copying the data onto the clipboard and exposed data members.

This document assumes a general understanding of stock and commodity trading. Section 4.3.2 on computed contracts assumes a detailed understanding of each computed contract discussed. The Unfair Advantage User Manual is one such source.

For details on the Perpetual Contract®, the reader is invited to read the Futures magazine article "Contracts that don't expire aid technical analysis" by Robert Pelletier published in March 1983 issue.

Additional details on the Back Adjusted contracts are provided on the website at http://ua.csidata.com/ua/backadj.htm.

An OLE Automation object has certain properties, such as commodity symbol, data date, delivery month, opening price, and actions, such as retrieving contract, copying the price data to the clipboard, and looking up market information. All of the properties can be read and modified by the client application. When the client application wants UA to take some action, such as retrieving some data, the client applications accesses one of the interface's actions (functions). The following example should clarify.

The following working VBA code is an example of client code accessing the interface.

Line #

Line 1 declares an OLE Automation object. Lines 2 through 4 declare a number of temporary variables used in the example. Line 5 activates the OLE Automation object. This causes Unfair Advantage to be launched if it is not already running. Line 6 is unnecessary within Excel. Please see section 3.4 for additional information. Line 7 places the symbol SP into a local variable named symbol. Line 8 sets the API2 property "symbol" using the local variable. Unfortunately the intermediate variable symbol is required for this to work correctly in Excel. Line 9 identifies the symbol as not a stock symbol (1 for stocks, 0 for futures.)

Line 10 and 11 requests a Market look-up based on the given symbol. The intermediate local variable is needed for VB.Net only. Line 12 requests detailed Market Specifications about the market. Lines 13 and 14 generates a message box with several of the results of this lookup.

Line 15 requests a December 2007, Copper contract from the first (-1) to the last (-1) day. Line 16 requests that the data be copied to the clipboard. Lines 17 and 18 paste the results into a spreadsheet.

Line 19 specifies that you want UA to close when you are done with it, and line 20 closes the connection.

API2 is an extension of the COM_API OLE interface created by Josh Reed which is no longer available starting with version 2.0.0. COM_API is not documented here.

Because there are a number of things during the initialization of UA which may require user attention, the Windows message pump is allowed to start before initialization is completed. Although I have gone to great lengths to prevent CreateObject from returning until initialization is complete, it is theoretically possible for CreateObject to return a connection before UA has fully initialized. Waiting 0.1 second between the receipt of the connection and its usage insures that UA has begun its actual initialization before data requests are made. This is not important with VBA access as there is enough latency without an explicit wait. For interpreted languages such as Perl and VBScript, sleep(1) and WScript.Sleep(100) are sufficient. For compiled languages, one may wish to use WaitForInputIdle so that you wait the very least amount of time necessary.

Because it takes some time between when you release the connection to UA and when UA has actually been removed from memory, one should not immediately CreateObject again unless HoldUAOpenOnClose is 1. Testing has demonstrated that at least 2 seconds are needed to insure that your new connection request is not caught by the previous UA. If it is caught during the close, UA should return an ErrorMessage.

Starting with version 2.0 of UA, a property ErrorMessage is accessible. This is set or cleared by each function call. Look for an empty ErrorMessage to mean that there was no error. Additionally each of the functions has some kind of error return. If ErrorMessage is not empty, please pass it on to the user so that the problem may be resolved.

CSI identifies a stocks and commodity by a symbol and by a number. For example, the cotton traded at NYCE is labeled with the market symbol CT and with the number 7. The number is needed since it is a unique assignment made by CSI whereas no agreement exists between the exchanges to keep the symbols as unique. Further, symbols are sometimes changed or reused in an effort to keep consistent with the exchanges.

To this end, the properties "MarketSymbol" and "MarketNumber" can be used to identify what the current market is or to specify the current market.

MarketSymbol is a string of up to 6 characters.

MarketNumber is an integer assigned by CSI. The value is only required to fit within a four-byte integer.

IsStock is either 0 or 1 reflecting whether the currently described market is a Stock/Mutual Fund/Index rather than a future.

FindMarketNumber searches an internal database (cdbfacts.adm) for any exact match to the symbol. If a match is found, the MarketNumber property is set to the result and the return value is the MarketNumber. If no match is found, the value –1 is set instead and the return value is non-positive.

Starting with version 2.0 of UA, the IsStock property is used to determine if you are asking for a Stock symbol lookup. UA has settings to determine whether inactive stocks are to be included in this search. There are sometimes stocks with no data and this can trip-up the API programmer.

The Factsheet property in UA is used to determine if the function is supposed to include delisted stocks in the search.

To learn more about the identified market, you need to get its Profile, which consists of the following fields:

This interface action searches the commodity database for a matching MarketNumber. The MarketNumber is returned if any are found. Otherwise a non-positive is returned. Starting with version 2.0 of UA, the IsStock property is used to determine if you are asking to step through the equities.

The first and last date available for a given data set. When accessing a market profile, the data set is from the first contract, or cash if earlier, to the last contract, or cash if later. Although for most data, the data goes continuously from one date to the next, this is not necessarily the case for all markets. The Mexican Peso, for example, was illegal to trade for several years in the middle of its price history.

A symbol representing the exchange on which the commodity trades.

This property is a description of the market.

Conversion factors determine how to interpret the price information for either a market price, a strike price, or for an option premium:

CSI reserves the right to add additional conversion factors without notice. Unknown conversion factors should be treated as +0. The MinTickInPoints is often needed to make meaningful use of these results see sec. 4.1.2.9.

This is a string of 12 characters. Each of those characters is either an ‘I’ for inactive, ‘V’ for active (valid), or ‘S’ for switching (currently low volume.) During retrieval, the condition is 'V' to retrieve and not 'V' to ignore. If the active months have changed historically, it is up to the users to convert 'S's to 'V's to build representative contracts. Of course 12 Vs ('VVVVVVVVVVVV') retrieves every contract ever traded.

The minimum tick in points is used in conjunction with the conversion factor to interpret the database entries. Because floor traders are always trying to split the difference, futures have developed some odd mixed-fractional numbering systems. For example, Live Cattle #2 (LC) is quoted as 23 cents, 6 tenths of cents, and ¾ of a tenth of a cent. Mathematically, this can be represented as 23.675 or 23 27/40. Since no one likes to work with fractions, especially when placing an order, the 23.675 representation is preferred. To save costs and to avoid a slippery slope, they choose to not print the final 5 just as they would not print 2.3333333333333333333333333333333 either. CSI which got much of its early history from newspapers and books followed suit. UA will either output 2367, 23.675, or 23.67500000 depending upon the circumstances and settings.

If you would rather not deal with these things, then you might want to look at ShowDecimalPoint (sec. 4.3.1.4).

A related issue is that sometimes opening prices in CSI are not valid exchange prices. For example, if the opening range of LC were 23.625 and 23.650, then CSI might list the open as 23.64 which can easily throw off your code when it tried to figure out how many quarters that is. For that reason, UA offers the "Round to Nearest Tick" option.

Provided that you don’t mind rounding to the nearest tick, then you can convert point values (2367) to decimal values (23.675) using the conversion factor and minimum tick as follows:

These properties do not exist in UA versions 2.6.1 and higher.

The first and last date available for the options associated with the given data set. Although for most data, the data goes continuously from one date to the next, this is not necessarily the case for all markets.

There are two actions (functions) provided for enumerating the known markets. There may be data available for unknown markets, but this should not be used.

This interface action extracts the Market Profile for the first commodity (IsStock=0) or stock (IsStock=1) in the database. Returns the 1 on success, 0 at end of list, and -1 on error.

This interface action extracts the Market Profile for the next commodity(IsStock=1) or stock (IsStock=1) in the database. Returns the 1 on success, 0 at end of list, and -1 on error.

The following table of properties provides various current fundamental data for some stocks. IsStock must be 0, and MarketNumber provides the identification of the stock. Not every stock, much less every series in the Stock Database, has fundamental data so make sure to check the property HasStockFundamentalData first as it may save you time. Even if HasStockFundamentalData is 1, some field may be missing for a variety of reasons including the field being inapplicable by accounting standards, the field was not provided in the company filings, or our current source may not carry certain information which a previous source carried.

Commodity trading relies upon standardization of deliverable contracts. A ContractDeliveryCode identifies the class of deliverable contracts is identified by. For example Pork Bellies deliverable in August 1996 is designated 199608. An immediately deliverable or forward deliverable contract is labeled with a ContractDeliveryCode of 54 for compatibility with previous CSI products. In the case of Stock Options, the ContractDeliveryCode tells in which year and month the option expires.

This function takes a long integer argument for the MarketNumber, a short integer for IsStock, and a short integer for IsOption. It returns a short integer for the number of series, including cash if available, present for that stock or commodity. If IsStock is 1, then the MarketNumber is interpreted to be a stock, else 0. If IsOption is 1, then a list of options is created. If IsOption is 0, then a list of contracts is created. The order of the list is cash (if exists,) lag cash (if exists and is separate,) then most distant to oldest contract with the strike prices numerically ordered. It returns the number of contracts found.

The property NumContracts is a short integer, which reports the number of contracts in the contract list which is built by the BuildContractList function, see 4.2.1.

The function, GetNextContractDetails, can be called repeatedly following a BuildContractList function, see 4.2.1, to enumerate the contracts available for a commodity. At least the properties ContractDeliveryCode, ContractStrikePrice, ContractFirstDate, and ContractLastDate are set. The ContractFirstDate and ContractLastDate are the first and last dates of the contract respectively. The ContractDeliveryCode is a number describes a futures contract (200512 for the Decmeber 2005 contract). For data not associated with a futures delivery month, such as the cash series or an econometric series, use the delivery month 54 for cash.

These allow random access to the ContractList which is set by BuildContractList (MarketNumber), see 4.2.1. These functions simply return the same values as 4.2.4 through 4.2.6 except not requiring you to step through the list.

This function flushes the contract list and the retrieve data list. This automatically called when a download/distribution has successfully completed.

Before we look into synthetic contract generation, let us look at the simpler case of actual contract retrieval. There are two functions of interest: RetrieveContract and CopyDataToClipboard.

Important Note. If you are looking for COT data, Econometric data, LME Forward data, or any other data where does not have a futures commodity month associated with it, then either RetrieveStock or RetrieveContract is the relevant method. If the series is found under the Stocks Market Specifications, then use RetrieveStock. Otherwise, use RetrieveContract with the ContractDeliveryCode of 54 for cash.

This function takes two long integer arguments, MarketNumber and ContractDeliveryCode. The MarketNumber is discussed in section 4.1.1.2. The ContractDeliveryCode is discussed in section 4.2.4. Given this information, UA decompresses the corresponding database file and loads the data into memory.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9) , ApplyCommodityAdjustments (4.4.11), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The return value is the number of data days found.

These two long integers allow the user to limit the retrieval to a date range. Use the values -1, -1 or 0,0 if you want the full history available. Can significantly improve performance, but for forward generated Nth Nearest Future and Back-Adjusted contracts can result in different contract choices.

Once you have the data loaded into memory, the CopyDataToClipboard function writes the information to the clipboard.

The function has two control properties: IncludeHolidays and ShowDecimalPoint. If IncludeHolidays is not true, than all data records reflect actual trading. If it is true, then weekdays on which there is not a record, inclusive to the date range of the result set, are recorded with a day of week value of 8 and no price information. If OnHolidaysUsePreviousData is 1, then the previous days data is copied with the Date and DayOfWeek changed. If also the OnHolidaysUseCloseOnly is 1, then the price values are set to the previous close and the volumes are set to zero. The ShowDecimalPoint property controls whether prices are listed as integers or as strings representing the number (see 4.1.2.6 for details.)

At least two formats are provided: Text and UAStraightData. To retrieve either of the results, the Clipboard Format Id is required. For Text, Microsoft provides the value CF_TEXT (1). To determine the UAStraightData Clipboard format Id, the client software can either Register the "UAStraightData" format or call the API function GetUAStrClipFormat that takes no arguments.

Both formats provide the same information, but the future expansion is a little different. The text image placed on the clipboard is in a CSV format. The first 17 fields are described here. There may be additional fields. In the binary format, additional bytes are reserved for future expansion.

Also the first record in the binary format, has a RecordDate which records the version of the file, currently +1. The version number for this clipboard format shall not reach 10000. The record length is stored in the Day of Week field. Make sure to read this value and to seek accordingly.

Unfortunately in UA 2.8.1, the Unadjusted Close field was inserted after the Close field. Make sure to check for this version number if you need your software to be compatible with that version.

CombineDataToClipboard and CombineDataToClipboard2 extend CopyDataToClipboard by allowing different data compress: daily, weekly, monthly, quarterly, or yearly bars depending on the Periodicity argument and by allowing you to specify a field separator. CombineDataToClipboard(p) assume you want a comma (‘,’) as a separator. The Periodicity following values are valid.

In each case, the following definitions apply

The return value is the number of data days found.

This function has no useful purpose when applied to a NearestFuturesContract, discussed in 4.3.2.3.

Previous versions of UA only allowed detrending of cash data and computed contracts. The current version allows it, but it is of dubious value for short series.

This Boolean property indicates whether a second pass through the database should be done to determine a "cash" price for each retrieved data day. The "cash" price may be an actual cash price, it may be lagged cash, which would only have been known the day after, or it may simply be the nearest future contract.

Since the cash series often starts at the beginning of the database and extends all the way to the end, it often more than doubles the retrieval time this option.

These short integer properties indicates what method is used to aggregate volume and total volume, aggregate open interest and total open interest, aggregate cash, date, and day of week in weekly, monthly, quarterly, and annual series. The values for Volume, Open Interst, and Cash are listed below. A total cash doesn’t make sense, so value 4 is not allowed in the AggregateCashAs parameter.

The AggregateDateAs is 0 for the first day of the week and 1 for the last actual day of trading.

The AggregateDayOfWeekAs can be one of the following:

long CopyRetrievedDataToArray(short Period,

VARIANT *DateArray, VARIANT *DowArray, VARIANT *DydmArray,

VARIANT *OpenArray, VARIANT *HighArray, VARIANT *LowArray,

VARIANT *CloseArray, VARIANT *ClosingBidArray, VARIANT *ClosingAskArray,

VARIANT *VolumeArray, VARIANT *OIArray,

VARIANT *TotalVolumeArray, VARIANT *TotalOIArray,

VARIANT *CashArray);

CopyRetrievedDataToArray does the same things as CombineDataToClipboard, except that it writes the data to variant arrays which are passed in as arguments. (A variant array is not an array of variant objects. Please see variant documentation for your language.) Please see 4.3.1.6 Clipboard Field List concerning the meaning of the arguments.

The return value is the number of data days found.

This function does not work with VBScript; because VBScript cannot pass an array by reference.

The following VBA code may help to clarify how to handle a variant array:

Set UA = CreateObject("UA.API2")

Dim datea, dowa, dydma, opena, higha, lowa, closea

Dim closingbida, closingaska, vola, oia, tvola, toia, casha

UA.ShowDecimalPoint = 0

UA.IncludeHolidays = 0

MyErrNo = UA.RetrieveStock(1006, 20050101, -1)

MyErrNo = UA.CopyRetrievedDataToArray(1, datea, dowa, dydma,

MsgBox Format(datea(0))+Format(closea(0))

This code displays a message box with the first date and the first closing price.

long CopyDataToResource(short Period, HGLOBAL *StrFormat, HGLOBAL *TxtFormat);

This function is no longer available.

CopyRetrievedDataToArray does the same things as CombineDataToClipboard, except that it writes the data to variant arrays which are passed in as arguments. (A variant array is not an array of variant objects. Please see variant documentation for your language.) Please see 4.3.1.6 Clipboard Field List concerning the meaning of the arguments.

The return value is the number of data days found.

This function does not work with VBScript; because VBScript cannot pass an array by reference.

The IntResultArray and FltResultArray return the values, and the return code is the number of records retrieved. Use 0(zero) for ContractDeliveryCode if you want all of them. Use 0(zero) for the StrikePrice if IsOption is 0(zero) or if you want all of the strikes. Currently the IntResultArray is an 8 column table, and FltResultArray is also an 8 column table. Additional columns will be added without notice. The following table lists what is in those columns currently. The FillInCashPrice and DetrendMethod properties are ignored. The IncludeHolidays, IncludeSaturdays, AggregateVolAs, AggregateOiAs, AggregateCashAs properties are ignored.

The following VBA code may help to clarify how to handle a variant array:

Set UA = CreateObject("UA.API2")

MyErrNo = UA.RetrieveStock(5159, 20030728, 20030730)

MyErrNo = UA CopyRetrievedDataToArray2(0, IntArray, FltArray)

MsgBox Format(IntArray(0, 0))+Format(FltArray(3,0))

Computed contracts allow the multitude of changing, deliverable contracts to be synthesize into a time series with useful, if not exact, characteristics. A back-adjusted computed contract, for example, generally exists for every day on which any non-cash contract was traded from the first day of trading to the last, and the prices vary continuously.

This method retrieves an Nth Nearest Futures Contract. UA decompresses the corresponding database file and loads the data into memory.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9), ApplyCommodityAdjustments (4.4.11), UseAlternateBackAdjuster (4.4.9), RaiseNegBackAdjustSeries (4.4.10), NumDaysConfirmation (4.3.2.1.6), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. The ContractDeliveryCode is discussed in section 4.2.4. The remaining arguments are discussed in the following sections.

Refers to which future. For example, the nearest future contract is the 1^st nearest future, 1. The next contract out is the 2^nd nearest future, 2.

Identifies the logic to be used in deciding when to ignore a near contract. The following values are valid. Other values may be supported in the future.

These same values are available for the back-adjusted contract.

As example, suppose that roll on open interest is selected and, if back adjusted, close-to-close splicing is requested with two days of confirmation.

are used when the rollLogicType is a date roll. If the DayOfMonthToRoll were 3 and the MonthsPriorToRoll where 2, then a March 1998 contract would be disallowed on January, 3, 1998 if the rollLogicType is from start of month and January 29, 1998 if from end of month. DayOfMonthToRoll values may not exceed 31.

To include all contracts in determining the nearest use, 31/0 and roll from start of month. Unfair Advantage does not currently record information after the earlier of expiration or the end of the month of delivery. December 1997 Milk, for example, traded in the first few days of January 1998, but this is not recorded by Unfair Advantage. In the event that Unfair Advantage changes to allow recording of such information, many things will have to change, including the upper limit to DayOfMonthToRoll.

Selects which delivery months to consider. The ValidMonths argument must be a string of 12 characters, one character for each month. Each character determines whether contracts deliverable in that month are included. A contract is included if there is a 'V' (for valid) in that position. A value of 'I' for invalid causes exclusion..

Unless an explicit date roll is requested, this parameter selects how many consecutive volume and/or open interest roll signals are required before the algorithm rolls. For the Standard Back Adjuster which views the market backward in time from the most recent to the most distant, this argument is ignored and has an effective value of 1. For the Nth Nearest Future and the Alternate Back Adjuster, a value of at least 1 is required. Spikes in volume can cause premature rolling on volume. For this reason, a NumDaysConfirmation value of 1 to is not recommended when rolling on volume.

The effects of this depend greatly on the GenerateForward option. If the UseAlternateBackAdjuster is zero then GenerateFoward will have no effect.

If you are generating forward (non-zero), then the alternate back adjuster is applied. This back adjuster begins with the first day of data and steps forward backing roll decisions based on the data as it becomes available. If the RollAtLeastNDaysBeforeExpiration argument causes a roll to happen if necessary to avoid getting too close to expiration.

If you are not generating forward (zero), then the standard back adjuster is applied. If the RollAtLeastNDaysBeforeExpiration is greater than zero, then the rollLogicType is overridden so that rolls happen based only on expiration. (Like a roll relative to month end.)

This method retrieves a Back- or Forward- Adjusted Contract. UA decompresses the corresponding database file and loads the data into memory. For the RetrieveBackAdjustedContract function, the accumulationMethod for Proportional adjustment is used together with the GenerateForward option to determine the ProportionalAdjustment parameter.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9), ApplyCommodityAdjustments (4.4.11), UseAlternateBackAdjuster (4.4.9), RaiseNegBackAdjustSeries (4.4.10), NumDaysConfirmation (4.3.2.1.6), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. rollLogicType is discussed in section 4.3.2.1.2. rollWhen is discussed in section 4.3.2.1.3. DayOfMonthToRoll and MonthsPriorToRoll are discussed in section 4.3.2.1.4. ValidMonths is discussed in section 4.3.2.1.5. The remaining arguments are discussed in the following sections. Then GenerateForward and RollAtLeastNDaysBeforeExpiration arguments are discussed in section 4.3.2.1.6. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2. The ProportionalAdjustment parameter is described in

identify how the adjustments are to take cumulative effect. Valid values are:

If the ProportionalAdjustment parameter is non-zero, then the Backward or Forward adjustments are applied by a multiplicative ratio factor rather than an additive factor. When the standard back adjuster is applied, only Backward adjustments can be applied proportionally. This option has three advantages: prices cannot fall into negative territory in the past with this option, compounding of profits/loses is better represented, and the proportional profit/loss per trade is correct. The disadvantage is that trade profit/loss numbers are not correct.

Notice that the standard back adjuster is fundamentally backward looking while the alternate back adjuster is fundamentally forward-looking which is why the Proportional accumulation is different.

This method retrieves all of the data for the current nearest contracts lined up by day and then by delivery code. UA decompresses the corresponding database file and loads the data into memory.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9), ApplyCommodityAdjustments (4.4.11), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. DayOfMonthToRoll and MonthsPriorToRoll arguments are not used. Instead the contract are selected according to which have current day data. ValidMonths is discussed in section 4.3.2.1.5. The remaining arguments are discussed in the following sections. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

Applying the CombineDataToClipboard has no useful purpose on this series.

Identifies the maximal number of contracts to extract. You were requesting the data on March 13, 1998. Then if you ask for 1 contract, you might well get the March 1998 contract. If you asked for 2, you might well get the March 1998 and April 1998 contracts with the data ordered primarily by date.

If true, then the cash data is considered the nearest contract and is included in the count of the number of contracts to extract.

This method retrieves a Perpetual Contract. UA decompresses the corresponding database file and loads the data into memory.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9), ApplyCommodityAdjustments (4.4.11), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. DayOfMonthToRoll and MonthsPriorToRoll are discussed in section 4.3.2.1.4. ValidMonths is discussed in section 4.3.2.1.5. The remaining arguments are discussed in the following sections. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

This method retrieves a Gann Contract. UA decompresses the corresponding database file and loads the data into memory.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), FillInCashPrice(4.3.1.9) , AggregateVolAs (4.3.1.10), ApplyCommodityAdjustments (4.4.11), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. DayOfMonthToRoll and MonthsPriorToRoll are discussed in section 4.3.2.1.4. The remaining arguments are discussed in the following sections. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

is a value between 1 and 12. Individual contracts with the same delivery month are concatenated together. Notice that if a given contract did not trade for a full year, there most likely will be a gap in the Gann contract.

This method retrieves all of the data for a stock up to the last day updated unless the StartDate and/or EndDate are greater than zero. If a date greater than zero is supplied, then it is used instead of the beginning and end of the database respectively. UA decompresses the corresponding database file and loads the data into memory. The FillInCash property is ignored.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), ApplyStockSplitAdjustments (4.4.12), ApplyStockDividendAdjustments (4.4.13), PropStockAdjustments (4.4.14), PropStockVolumeAdjustments (4.4.23), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), CoverMutualFundHigh (4.4.17), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

This method retrieves all of the option premium data for a commodity or stock up to the last day updated. UA decompresses the corresponding database file and loads the data into memory.

The return value is the number of data days found.

The FillInCash (4.3.1.9) property is ignored.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), ApplyCommodityAdjustments (4.4.11), ApplyStockSplitAdjustments (4.4.12), ApplyStockDividendAdjustments (4.4.13), PropStockAdjustments (4.4.14), PropStockVolumeAdjustments (4.4.23), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. IsStock is 1 for a stock series and 0 for a commodity series as in section 4.1.1.2. The ContractDeliveryCode is discussed in section 4.2.4. The strike price is negative for puts. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

The method, RetrievePutCallRatio, retrieve the total call volume, total call open Interest, total put volume, and total put open interest. The values are then stored as

The return value is the number of data days found.

The CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), FillInCash (4.3.1.9) properties are ignored.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), ApplyCommodityAdjustments (4.4.11), ApplyStockSplitAdjustments (4.4.12), ApplyStockDividendAdjustments (4.4.13), PropStockAdjustments (4.4.14), PropStockVolumeAdjustments (4.4.23), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The MarketNumber is discussed in section 4.1.1.2. IsStock is discussed in section 4.1.1.2. The StartDate and EndDate parameters are discussed in section 4.3.1.1.2.

This method retrieves adjusted database data collated by date, contract, and strike. The IntResultArray and FltResultArray return the values, and the return code is the number of records retrieved. Use 0(zero) for ContractDeliveryCode if you want all of them. (54 and 61 also return all.) Use 0(zero) for the StrikePrice if IsOption is 0(zero) or if you want all of the strikes. Currently the IntResultArray is a 7 column table, and FltResultArray is also a 7 column table. Additional columns will be added without notice. The following table lists what is in those columns currently.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), ApplyCommodityAdjustments (4.4.11), ApplyStockSplitAdjustments (4.4.12), ApplyStockDividendAdjustments (4.4.13), PropStockAdjustments (4.4.14), PropStockVolumeAdjustments (4.4.23), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10), FillInCash (4.3.1.9) are accessed

If you are requesting a stock, but not the option on the stock, than this function returns all of the stocks in that group of 50. To find the one you want, search by ContractDeliveryCode.

RetrieveAdjAndUnadjStock combines calling RetrieveStock twice, once with default adjustment setting and a second time with adjustments turned off, and also a CopyRetrievedDataToArray

The IntResultArray and FltResultArray return the values, and the return code is the number of records retrieved. Use 0(zero) for ContractDeliveryCode if you want all of them. Use 0(zero) for the StrikePrice if IsOption is 0(zero) or if you want all of the strikes. Currently the IntResultArray is an 8 column table, and FltResultArray is also an 8 column table. Additional columns will be added without notice. The following table lists what is in those columns currently.

The return value is the number of data days found.

The IncludeSaturdays (4.3.1.9), IncludeHolidays (4.3.1.3), DetrendMethod (4.3.1.8), ApplyStockSplitAdjustments (4.4.12), ApplyStockDividendAdjustments (4.4.13), PropStockAdjustments (4.4.14), PropStockVolumeAdjustments (4.4.23), CloseOutOfRangeAdjustmentMethod (4.4.15), RoundToTick (4.4.16), UseTradeableTick(4.4.16), CoverMutualFundHigh (4.4.17), OnHolidaysUsePreviousData (4.3.1.3), OnHolidaysUseCloseOnly (4.3.1.3), AggregateVolAs (4.3.1.10), AggregateOiAs (4.3.1.10), AggregateCashAs (4.3.1.10), AggregateDateAs (4.3.1.10), AggregateDayOfWeekAs (4.3.1.10) are accessed

The following VBA code may help to clarify how to handle a variant array:

Set UA = CreateObject("UA.API2")

MyErrNo = UA. RetrieveAdjAndUnadjStock (5159, 20030728, 20030730, IntArray, FltArray)

MsgBox Format(IntArray(0, 0))+Format(FltArray(3,0))

The method, RetrieveMysteryIndex, was removed in version 2.9.2.

Exactly the same as RetrieveContract(MarketNumber, 54, StartDate, EndDate).

Both method retrieves the cash contract for the future specified, or the series if there are no futures for that market.

This function provides direct access to the Capital Gains, Dividends, and Splits for the stock/mutual fund referenced by MarketNumber. IsStock should be 1. LoadStartDate and LoadEndDate should be -1 to get all of the data available.

This information is an add-on to the standard stock and mutual fund package at the time of this writing. If you are not entitled to receive this information, then the corresponding list will be blank and corresponding count (NumDividends, NumCapitalGains, NumSplits) will be -1. Also check the ErrorMessage property for other possible problems.

The dividends are returned in the DividendList array along with their corresponding dates in the DivDateList array. Likewise, the capital gains and splits are returned with one data field per array. The following example demonstrates how to retrieve this information in VBA.

UpdateDatabase is only available in UA 2.1 or later, and UpdateDatabaseFromCompletedDownload is only available in UA 2.8.3 and higher. Both function takes no arguments and returns no value. UpdateDatabase checks for conflicting simultaneous tasks, finding none, it initiates download and updating of the database and portfolio. Provided browser access is not requested, the function returns when done. UpdateDatabaseFromCompletedDownload assumes that a download has already been completed, and proceeds to distribute it. In the event of error/s, check the ErrorMessage property.

UpdateDatabase2 is only available in UA 2.10.1 or later. It does the same thing as UpdateDatabase, but allows you to specify the WaitForTransmissionId and CollectionGroupIndex. Use 0 and -1, respectively, if you don’t know what value you want.

UA can distribute a selected group of exchanges rather than all exchanges. These Collection Groups can only be defined in the user interface, and their index is only valid until the list is modified in the user interface. To view this list, open UA, click on the menus Database -> Update Database. The list at the top contains your Collection Groups. The "All Dataseries and Markets" item has CollectionGroupIndex -1. The next item, if it exists, has CollectionGroupIndex 0. If you want to verify that nothing has changed, they are defined in the unfair.ini file in the section DistributionFilters with keys formed by "List:" followed by the CollectionGroupIndex plus 1. So for example, "List:1=ALBRTA,AEX,ADEX" refers to CollectionGroupIndex 0.

This property should not be used as it has been replaced with the function UpdateDatabase.

This property returns a 2-byte integer. None-zero after and during a download. Set to 0 after you have completed your processing to detect next download.

This function only available in UA 2.1.4 or later. This function takes the ConversionFactor (cvf) and Minimum Tick (MinTick) from the market along with a price in points. It returns the price in decimal.

For efficiency sake, it is better to implement your own.

long PriConv_PntsPerUnit[15]= {128,64,256,128,64,32,16,8,1,10,100,1000,10000,100000L,1000000L };

float TicksPerUnit = (float)(PriConv_PntsPerUnit[cvf+8]/MinTick);

long ticks = (sign?-1:1)*(long)(cPTD(cvf,(sign?-pnts:pnts))*TicksPerUnit+0.5);

*dec = (double)ticks /(TicksPerUnit);

cPTD follows the Conversion Factor definitions.

This function only available in UA 2.1.4 or later. This function takes the ConversionFactor (cvf) and a price in decimal form. It returns the price in points.

For efficiency sake, it is better to implement your own.

This property controls the window state (normal, minimized, maximzed) of UA. It does not control the window state of the Market Scanner, Multi-Market Analyzer, Trade System Performance Evaluator, or any other UA software. Set to value 0 for normal mode, to 1 for minimized mode, and 2 for maximized mode. Minimizing UA can be especially helpful when you are keeping a UA connection open for a while.

This property controls whether UA closes when you end your sessions. By default it does. Set to value 0 to close UA when you close your connection. Set to 1 to keep UA open once the OLE connection is closed.

This string property is the version number for the UA installed. For example, "2.4.4".

This is a special purpose function which allows you to import into UA a scan result list. This function only available in UA 2.4.5 or later. This function creates a set of invisible charts based on its arguments and opens the SaveToPortfolio dialog. The user can then specify which directory (possibly creating a new directory) to save them to, what export format, and such things.

StartDate is as described in 4.3.1.1.2.

List is a linefeed seperated list of comma seperated list of symbol (or for better performance csinum) and IsStock (0 for future, 1 for stock). For example if the list were the single string

QQQ,1

S,0

DELL,1

Then UA would try to insert the stock QQQ, future S, and stock DELL into the portfolio.

This property controls whether UA uses the standard or alternate back adjusters. The default is the non-portfolio chart option value in UA. It can be overridden by setting this property for the session. If the value is 1, then the Alternate Back Adjuster is used for all series. (Warning, many customers are not pleased with the results of rolling by volume.) If the value is 0, then the standard back adjuster is used when possible..

This property controls whether UA automatically adds the smallest number of thousands of points to bring the back adjuster series into the non-negative domain.

This property controls whether UA applies commodity adjustments.

This property controls whether UA applies stock split adjustments.

This property controls whether UA applies dividend and capital gains adjustments.

This property controls whether UA applies dividends and capital gains proportionally or additively. (Reinvest or disburse.) See also PropStockVolumeAdjustments.

This property controls whether UA should adjust the close, high, or low to make them consistent.

typedef enum {

LeaveAlone_CloseOutOfRangeAdjustmentMethod=0,

CompromiseHighLow_CloseOutOfRangeAdjustmentMethod=1,

CompromiseClose_CloseOutOfRangeAdjustmentMethod=2,

} CloseOutOfRangeAdjustmentMethodType;

This property controls whether UA rounds values to the nearest tick. If so, then UseTradeableTick determines whether the settlement price should be rounded as per the exchange or the same way as the other prices.

The property currently has no affect on my market, but we can make up an example, suppose an E-mini contracts where the settlement is from the full-sized contract which has a different minimal trade increment. Please consider the following example from a back-adjusted series:

If the Tradeable Tick is set, then the numbers are rounded to the nearest tradeable tick (.1), otherwise the close is rounded to .05 while the open, high, and low are round to .1.

This property controls whether UA automatically copies the close value of a mutual fund to the high value. This hides fund loading information.

This property controls whether UA aggregates the date field to be the last existing date in the period, or the last logical date in the period.

This property controls how UA fills holidays.

This property controls how UA fills holidays.

This method returns the contents of the customer’s UA portfolio when the PortfolioIndex is set to –1. The results are not defined for any other value. The format of the return is in CSV format. The first line describes the column contents. The table below describes some of column headers. Other column headings should be ignored.

This is a special purpose function allows you to remove items from your portfolio. See 4.4.8 for introduction method.

The portfolio is speicifed by the PortfolioIndex. -1 is used when you want to delete the series from all series. Other values can be obtained by using the GetPortfolioContents function in 4.4.21.

The Series list follows the same format as in 4.4.8.

Confirm should be one if you want a dialog prompting for confirmation on the deletion. Pass through a zero if you do not want this dialog.

This setting refers to whether the volume should be adjusted for dividends and capital gains.

This function retrieves the numerical profit of a full point move. IsStock should be 1 or 0 depending on whether the market is in the stock database, respectively. IsOption should be 1 or 0 depending on whether you wish a full point move of the option or of the underlying, respectively.

This function returns a number in the base currency which would reflect the profit made by a full-point move in the market for a 1 contract position.  This is an easy multiplier to convert between the difference in entry and exit prices and dollar profit/loss.  Of course, you made need to do some currency conversions to get an estimated total profit/loss on the aggregate account. 

Some people prefer to access the Contract Size and Point Value fields directly so lets see how they are related using Corn as an example. The contract size is 5000 bu and the units are cents/bu so a full-point move would be 5000 bu/cntrt * 1 cent/bu = 5000 cents = 50.00 USD/cntrt.  To get this number for the Point Value is a bit more difficult.  Many data providers list the Tick Value as 12.50 because corn trades in quarters so 1 tick = 1/4 cent has a value of 5000 bu/cntrt * 1/4 cent/bu = 5000/4/100 USD/cntrt = 12.50 USD/cntrt.  CSI computes the Point Value a bit differently.  Since Corn is quoted in 1/8 s, the Point Value is 5000 bu/cntrt * 1/8 cent/bu = 6.25 USD/cntrt.  It is usually easiest to use the Whole Point Value 50 USD/cntrt, but they are all equivalent.

This function opens a chart in UA for the specified Market (see 4.1.1.2) and StartDate (see 4.3.1.1.2). If IsStock is zero, then the cash contract is displayed. This function has since been replaced by the 4.5.4 Chart Commands.

This function adds a database and/or split file to the list of items which are believed to be corrupt and needing to be replaced.

This function exists for internal operations purposes only. It allows the download date of the UA to be modified.

This function exists for internal purposes only. The Command is a comma separated list consisting of the csinum, IsStock, IsOption, date, delivery month, strike price. It is used internally to delete user edits system-wide.

This property is an integer of whose digits are YYYYMMDD. This is the date of the last full distribution. Setting this date back will also set back the date of all collection groups.

This function performs the actions encoded in the Commands argument on the UA portfolio with results returned in the Results variable. For example,

<?xml version="1.0" encoding="ISO-8859-1"?>

<ActionList SaveDocumentEditsToEnd="False">

<Action Command="AddPortfolio" Id="132">

<Name>TestXml2</Name>

<Directory>c:\\ua\\files\\testxml2\\</Directory>

</Action>

<Action Command="AddDocument" Id="811">

<Symbol>DDR</Symbol>

<IsStock>True</IsStock>

<PortfolioName>TestXml</PortfolioName>

<FileFormat>CSI</FileFormat>

<FilePeriod>Daily</FilePeriod >

</Action>

<Action Command="AddPortfolio" Id="583">

<Name>TestOther</Name>

<Directory>c:\\ua\\files\\testother\\</Directory>

</Action>

</Action>

<Action Command="AddDocument" Id="3">

<Symbol>INTC</Symbol>

<IsStock>True</IsStock>

<Periodicity>Daily</Periodicity>

</Action>

</ActionList>

could return

<?xml version="1.0" encoding="ISO-8859-1"?>

<ResultList>

<Result Id="132">

<Success/>

</Result>

<Result Id="583">

<Success/>

</Result>

<Result Id="811">

<Error>Unrecognized Symbol</Error>

</Result>

<Result Id="3">

<Error>Too Many Charts Open</Error>

<Error>Maximum Chart Limit: 12</Error>

</Result>

</ResultList>

The root node for the Command is ActionList which can contain several Action nodes. The action nodes either command actions on Portfolios (Directories), on Documents (Files), or on Charts. The actions Document actions can either be completed in order or the Document actions can be completed as one transaction after all of the Portfolio actions. By completing all of the Document transactions at once, the actions process more quickly and can avoid certain conflicts, but multiple actions on the same document are not guaranteed to produce the same result as if performed one at a time.

The root node for the Results is ResultList which can contain several Result nodes. There should be a Result node for every Action node in the input. The Result node references the Id provided in the Action node. One should not assume that the Result nodes will be in the same order as the Action nodes.

The Command attribute for a Portfolio Action nodes include AddPortfolio, ModifyPortfolio, or DeletePortfolio. AddPortfolio creates a new Portfolio with the options provided. If the Name or Directory conflict with an existing Portfolio an exception is thrown. ModifyPortfolio will look for a matching Portfolio by Name or Directory. If none is found, it will attempt to create a new one. For this to work, the Name field must be provided. The properties provided or omitted automatically overwrite the existing Portfolio. DeletePortfolio searches by Name or Directory. If found, it deletes all of the Documents and the Portfolio.

The attribute nodes for a Portfolio node:

The Command attribute for a Document Action node include AddDocument, ModifyDocument, or DeleteDocument. A similar document is searched for by a complex set of comparisons. At least the Symbol, IsStock, ComputationMethod, FileFormat, and FilePeriod must agree. Depending upon the ComputationMethod still more may need to be specified. For example, to delete a 24000 Oct ’03 strike series for Cotton, the strike and delivery month are also needed to distinguish the series. When possible, it is usually better for the end user if Documents are separated into different Portfolios so that the whole Portfolio can be deleted and readded rather than trying to modify the documents.

The attribute nodes for all Document nodes:

The attribute nodes for Contract/Stock Document nodes:

There are no special attribute nodes for PutCallRatio documents.

The attribute nodes for IFG/NearestContracts group Document nodes:

The attribute nodes for Perpetual or OIPerpetual Document nodes:

The attribute nodes for NearestFuture and BackAdjust/BackAdjusted nodes (see sec. 4.3.2 for more information):

The attribute nodes Gann Document nodes:

The Command attribute for a Document Action node may be LaunchChart. Specify the same attributes you would for a Document (see 4.5.3) those that don’t apply such as FileFormat, FilePeriod, and PortfolioName.