How to Use Batch Command

Read First

Start Using

Please read Start Using ForexConnect in C++ project first to understand how to use ForexConnect API in your C++ project.

Login

To execute any command you must be logged in. See How to login in ForexConnect API SDK for details.

Using Batch Command

Scope

A batch command is used to send several commands of the same type in one request. You should use a batch command in the following cases:

• When you need to send many requests of the same type because all requests in the batch are sent in one step, which reduces the total time of requests execution.
• When you need to execute commands in a certain order because all requests in the batch related to one account will be executed by the server in the same order as they are placed in the batch.

Restrictions

Use of a batch command has the following restrictions:

• Requests in one batch must have the same operation type ("create", "change" or "delete"). For example, requests to create an entry order and to create an open order can be included in the same batch. But requests to change an order and to delete an order cannot be included in the same batch.
• A batch request does not provide any transaction support mechanism, it only sends several commands in one "step". An error of execution of one command does not abort execution of the other commands. You do not have any native method to know the result of execution of the whole batch request, because responses about success or failure of execution for each "sub-command" are received separately.

How to Use

The IO2GSession object is used to send requests, so it must be available from your code for creating a batch command request.

To create a batch command, do the following steps:

1. Make sure that IO2GResponseListener is implemented and this class is subscribed to notifications from the IO2GSession object. You need this listener to receive notifications of the result of your command execution, because request sending is asynchronous. See the article How to Start Using ForexConnect API (C++ Win32/Win64) for details about the IO2GResponseListener implementation and event driven architecture.

2. Create a request factory:

    IO2GRequestFactory* factory = mSession->getRequestFactory();

3. Create and fill a value map that represents the type of the batch command:

    IO2GValueMap* mainValueMap = factory->createValueMap();
    mainValueMap->setString(O2GRequestParamsEnum::Command, O2G2::Commands::CreateOrder);

Note that only the Command parameter is required.

The O2G2::Commands namespace contains special 'constants' for command names.

4. Create and fill a value map for a sub-command of the batch request:

    IO2GValueMap* childValueMap1 = factory->createValueMap();
    childValueMap1->setString(O2GRequestParamsEnum::Command, O2G2::Commands::CreateOrder);
    childValueMap1->setString(O2GRequestParamsEnum::OrderType, "OM");
    childValueMap1->setString(O2GRequestParamsEnum::OfferID, "1");
    сhildValueMap1->setString(O2GRequestParamsEnum::AccountID, mAccount);
    childValueMap1->setString(O2GRequestParamsEnum::BuySell, "B");
    childValueMap1->setInt(O2GRequestParamsEnum::Amount, 100000);

5. Add the value map of this sub-command to the value map of the batch command:

    mainValueMap->appendChild(childValueMap1);

So, a batch command has a value map that contains child value maps to describe a particular command in the batch.

6. Add other sub-commands by repeating steps 3-4. For your convenience, you can use the clone() method to copy the previously filled IO2GValueMap instance and change only the values that differ.

7. Create an IO2GRequest object for the batch command:

    IO2GRequest* orderRequest = factory->createOrderRequest(mainValueMap);

8. Send an asynchronous request:

    mSession->sendRequest(orderRequest);

9. Release all available API objects that you do not need anymore:

    orderRequest->release();
    mainValueMap->release();
    childValueMap1->release();
    //release the other available child value maps
    factory->release();

10. Check the results of execution of the sub-commands using the IO2GResponseListener::onRequestComplete event handler. You can identify each of your sub-commands by their RequestID that can be obtained from the IO2GRequest object after the batch request is created:

      //..
      O2G2Ptr<IO2GRequest> request = factory->createOrderRequest(mainValueMap);
      for (int i = 0; i < request->getChildrenCount(); i++)
      {
          O2G2Ptr<IO2GRequest> childRequest = request->getChildRequest(i);
          mRequestIds.add(childRequest->getRequestID());
      }

So you can keep these sub-command IDs and check them in the onRequestComplete event handler.

11. If the command affects some table, you can handle the IO2GResponseListener::onTablesUpdates event handler of your listener to receive notifications of the appropriate table changes. You can identify each table row that was created or changed by a particular sub-command from the batch request using a special parameter CustomID of the value map for this particular sub-command. This CustomID parameter can be checked in the onTablesUpdates event handler when you receive data of a changed object in the table. See the How to Get Trading Table Data article for details about receiving table data.

Sample

Look at the example of the CreateOrder batch command: '"`UNIQ--toggledisplay-00000010-QINU`"'