www.pepperstone.

com Excel RTD

3. Sending trading commands from Excel

The RTD app can also be used to send simple trading commands from VBA code in
Excel. You can also programmatically read the same data which is available via the
RTD function.

The following features can in fact be used from any programming language which
supports COM, not just from VBA in Excel.

3.1 Reading data in VBA code

You can read data programmatically using the FXBlueLabs.ExcelReader object. For
example:

Set reader = CreateObject("FXBlueLabs.ExcelReader")

reader.Connect ("156734")
MsgBox reader.Read("balance")

In other words: you create an instance of the FXBlueLabs.ExcelReader object; you

use the Connect() function to link it to a specific account number; and then you can
use the Read() function to get data about the account.

The property names for the Read() function are the same as the property names for
use with Excel’s RTD function.

3.1.1 Checking if a reader is successfully connected

You can successfully create the ExcelReader object and call the Connect() function
even if no RTD app is currently running for that account.

In order to check whether data is actually available you can use Read() to make sure
that properties such as balance are not blank, or you can read the LastUpdateTime
property and check that the time is later than 1/1/2000.

3.1.2 Data consistency across multiple reads

If you are querying multiple pieces of data, particularly multiple pieces of ticket data,
then you need to be careful about updates and data consistency. For example,
consider the following code which loops through the ticket list:

Page 19 of 26
www.pepperstone.com Excel RTD

For i = 1 To reader.Read("tickets")
strSymbol = reader.Read("t" & i & "s")
vVolume = reader.Read("t" & i & "v")
Next

It is possible for the following to happen:

• At outset there are 2 open tickets

• Between the two uses of Read(), i.e. between the execution of lines 2 and 3,
one of the tickets is closed.
• Therefore, what used to be ticket 2 becomes ticket 1.
• As a result, at the end of the first loop, strSymbol will hold the symbol of the
ticket which is now closed, and vVolume will hold the volume of the ticket
which is still open.

To ensure consistency while reading multiple pieces of data, use

Reader.ReaderLock(). This will suspend any changes to the data until you then use
Reader.ReaderUnlock(). For example:

Reader.ReaderLock()
For i = 1 To reader.Read("tickets")
strSymbol = reader.Read("t" & i & "s")
vVolume = reader.Read("t" & i & "v")
Next
Reader.ReaderUnlock()

Don’t forget to call ReaderUnlock() after using ReaderLock()…

3.2 Sending trading commands from Excel

As a security measure, commands are turned off by default. You must turn on the
"Accept commands" setting in the RTD app in order to send commands successfully.
If this option is turned off then all commands will return "ERR:Commands not
allowed".

You can send simple commands from Excel using the FXBlueLabs.ExcelCommand
object. For example:

Set cmd = CreateObject("FXBlueLabs.ExcelCommand")

Page 20 of 26
www.pepperstone.com Excel RTD

strResult = cmd.SendCommand("156734", "BUY", "s=EURUSD|v=10000", 5)

The SendCommand() function has four parameters:

• The account number (e.g. 156734)

• The command, e.g. BUY
• Parameters for the command, e.g. symbol and volume to buy
• The number of seconds to wait for a response

SendCommand() is synchronous. It returns either when the RTD app completes the
command, or when the timeout period expires. (Timeout does not mean that the
request such as a market order has been withdrawn/cancelled. It only means that
the broker/platform has not responded within the acceptable time.)

The return value from SendCommand() is a string, beginning either with ERR: to
indicate that an error occurred, or with OKAY:. The only exception to this is the TEST
command, which returns the text HELLO.

3.2.1 Differences between trading platforms

There are some minor differences in the trading features which are currently
supported on different platforms:

• "Magic numbers" are only valid for MT4 and MT5, and these parameters will
be ignored on other platforms.
• Order comments are only available on some platforms.
• Stop-losses and take-profits are not currently supported on tradable

3.2.2 Commands and parameters

The parameters for a command are sent as a pipe-delimited string, consisting of a

number of settings in the format name=value. The parameters can be listed in any
order, and some parameters are optional.

cmd.SendCommand("156734", "BUY", "s=EURUSD|v=10000", 5)

Trading volumes are always specified as cash amounts, not as lot sizes. The format
of symbol names depends on whether the "Use standardised symbol names" option
is turned on in the RTD app.

Page 21 of 26
www.pepperstone.com Excel RTD

3.2.2.1 TEST command

Simply returns the text HELLO if successful.

3.2.2.2 BUY and SELL commands

Submits buy or sell market orders. If successful, it returns the ID of the new ticket in
the form OKAY:ticket-number

Parameter Optional? Meaning

S Compulsory Symbol name for the buy order
V Compulsory Trading volume
sl Optional Stop-loss price for the new position
tp Optional Take-profit price for the new
position
comment Optional Comment for the new position
magic Optional Magic number for the new position

3.2.2.3 BUYLIMIT, SELLLIMIT, BUYSTOP, and SELLSTOP commands

Submits a new pending order. If successful, it returns the ID of the new ticket in the
form OKAY:ticket-number

Parameter Optional? Meaning

S Compulsory Symbol name for the buy order
V Compulsory Trading volume
price Compulsory Entry price for the pending
stop/limit order
sl Optional Stop-loss price for the new position
tp Optional Take-profit price for the new
position
comment Optional Comment for the new position
magic Optional Magic number for the new position

3.2.2.4 CLOSE command

Closes an open position or deletes a pending order. Returns OKAY:okay if

successful.

Page 22 of 26
www.pepperstone.com Excel RTD

Parameter Optional? Meaning

t Compulsory ID of the position to be closed, or
the pending order to be deleted.

3.2.2.5 PARTIALCLOSE command

Does a partial-close of an open position. Returns OKAY:okay if successful. Volumes

larger than the position size are simply treated as a full close (not as a close plus a
reverse for the remaining amount). Cannot be used on pending orders.

Parameter Optional? Meaning

t Compulsory ID of the position to be partially
closed.
v Compulsory Volume to be closed, e.g. 20000

3.2.2.6 REVERSE command

Reverses an open position, e.g. closing an open sell and replacing it with a buy.
Returns OKAY:okay if successful.

Parameter Optional? Meaning

t Compulsory ID of the position to be reversed
v Optional Volume for the new reversed
position. If omitted, the volume of
the existing position is used (i.e.
symmetrical reverse)
sl Optional Stop-loss price for the new position
tp Optional Take-profit price for the new
position
comment Optional Comment for the new position
magic Optional Magic number for the new position

3.2.2.7 CLOSESYMBOL command

Closes all open positions and pending orders for a specific symbol. Returns
OKAY:okay if successful.

Parameter Optional? Meaning

s Compulsory Symbol name to close

Page 23 of 26
www.pepperstone.com Excel RTD

3.2.2.8 CLOSEALL command

Closes all open positions and pending orders for all symbols. Returns OKAY:okay if
successful. Please note that closing everything can require a substantial timeout.

Parameter Optional? Meaning

(none)

For example:

cmd.SendCommand("156734", "CLOSEALL", "", 20) ' 20-second timeout

3.2.2.9 ORDERSL command

Changes the stop-loss on an open trade or pending order. Returns OKAY:okay if

successful.

Parameter Optional? Meaning

t Compulsory ID of the trade or pending order to
be modified
sl Compulsory New stop-loss price, or 0 to
remove any existing stop-loss

3.2.2.10 ORDERTP command

Changes the take-profit on an open trade or pending order. Returns OKAY:okay if

successful.

Parameter Optional? Meaning

t Compulsory ID of the trade or pending order to
be modified
tp Compulsory New take-profit price, or 0 to
remove any existing take-profit

3.2.2.11 ORDERMODIFY command

Changes both the stop-loss and take-profit on an open trade or pending order. For
pending orders, you can also alter the entry price.

Parameter Optional? Meaning

Page 24 of 26
www.pepperstone.com Excel RTD

t Compulsory ID of the trade or pending order to

be modified
p Compulsory for For pending orders, the new entry
pending orders price for the order. Ignored and not
required on open trades.
sl Compulsory New stop-loss price, or 0 to
remove any existing stop-loss
tp Compulsory New take-profit price, or 0 to
remove any existing take-profit

3.2.3 Standard error messages

Property Meaning
ERR:Need account Account value for SendCommand() is blank
ERR:Need command Command value for SendCommand() is blank
ERR:No listening app Cannot find an running instance of the RTD app
for the specified account
ERR:No response within No response from the broker/platform within the
timeout specified number of seconds
ERR:Commands not The "Allow commands" option is not turned on
allowed in the RTD app
ERR:Unrecognised The command value for SendCommand() is not
command understood by the RTD app
ERR:Missing parameters The command was missing one or more
compulsory parameters

3.3 Asynchronous commands

It is also possible to send commands asynchronously rather than blocking execution
of the VBA code until the command completes or times out. This works as follows:

• You use SendCommandAsync() instead of SendCommand().

• You periodically check the result of the asynchronous action using
CheckAsyncResult().
• When finished (or when you have decided to give up) you free up the
command memory using FreeAsyncCommand()

For example:

Set cmd = CreateObject("FXBlueLabs.ExcelCommand")

Page 25 of 26