Review the C++ sample client code to learn how to link your Excel spreadsheets to Symphony.
The connector for Excel package also includes a VB client sample that connects to Symphony using the COM API; refer to the Cross-language tutorial in the Knowledge Center for more information.
%SOAM_HOME%\5.0\Integrations\ConnectorForMsExcel\samples\CPP\AsyncClient\connector_for_ms_excel_sample_vc71.sln
%SOAM_HOME%\5.0\Integrations\ConnectorForMsExcel\samples\CPP\AsyncClient\connector_for_ms_excel_sample_vc80.sln
%SOAM_HOME%\5.0\Integrations\ConnectorForMsExcel\samples\CPP\AsyncClient\AsyncClient.cpp
The service required to compute the input data along with additional application parameters are defined in the application profile:
%SOAM_HOME%\5.0\Integrations\ConnectorForMsExcel\samples\CPP\AsyncClient\connectorForExcelSampleApp.xml
The sample provides an asynchronous C++ client, Excel spreadsheet, and wrapper service for Excel. The Excel spreadsheet contains business logic implemented in the form of a macro (VBA function) that performs calculations.
When you run the sample, here is the sequence of events:
The client sends task input messages and common data to the ConnectorForMsExcel service. Each task input message contains:
The ConnectorForMsExcel service launches Excel, which opens the workbook and executes the VBA macro. The VBA macro processes the input data string that is sent with each task input message.
The macro formats the result message and passes it to the service. The service sends the message to the client, which displays it in the command prompt window. The service closes Excel upon completion of the tasks.
The spreadsheet contains the logic (VBA code) that performs the calculations on the input data. When we create the input message, we pass the name of the VBA macro and other data to the service.
In the ConnectorForExcelDemo.xls spreadsheet, we implement MyMacro() as the main function. It calls the Initialize() function, which parses the input data string to extract the values for <NumberIterations> and <Seed>.
The Sim_RunFunction() performs a cycle of calculations based on the number of iterations specified in the input data string and prints out the results in the spreadsheet.
In AsyncClient.cpp, when you initialize, you initialize the Symphony client infrastructure. You initialize once per client.
With an asynchronous client, when a task is completed by the service, there must be a means of communicating this status back to the client. The response handler or callback is implemented for this purpose. It is called by the middleware each time a service completes a task.
In this sample, the OnResponse() method is the response handler. It is a member of the MySessionCallback class that inherits from the SessionCallback class. The method accepts the TaskOutputHandle as an input argument, which is passed to the method by the middleware whenever the respective task has completed.
First, we check if there is output to retrieve. If so, get the output message from the service and print out the task ID. Extract and print the message from the task result using the populateTaskOutput() method.
Increment the counter that records the number of task results received. The critical section object ensures that another thread does not try to increment the counter while it is being accessed.
To send data to be calculated in the form of input messages, you connect to an application.
You specify an application name, a user name, and password. The application name must match that defined in the application profile.
For Symphony DE, there is no security checking and login credentials are ignored—you can specify any user name and password. Security checking is done however, when your client application submits workload to the actual grid.
The default security callback encapsulates the callback for the user name and password.
In AsyncClient.cpp, perform this step after you have connected to the application.
When creating an asynchronous session, you need to specify the session attributes by using the SessionCreationAttributes object. In this sample, we create a SessionCreationAttributes object called attributes and set five parameters in the object.
The first parameter is the session name. This is optional. The session name can be any descriptive name you want to assign to your session. It is for information purposes, such as in the command line interface.
The second parameter is the session type. The session type is optional. You can leave this parameter blank and system default values are used for your session.
The third parameter is the session flag, which we specify as SF_RECEIVE_ASYNC. You must specify it as shown. This indicates to Symphony that this is an asynchronous session.
The fourth parameter is the common data object containing the path to the Excel spreadsheet that you want to send to the service.
The fifth parameter is the callback object.
We pass the attributes object to the createSession() method, which returns a pointer to the session.
In this step, we create 10 input messages to be processed by the service. We call the fillMessageWithExcelData() method. The fillMessageWithExcelData() method fills the inMsg object with (1) spreadsheet name, (2) macro name, and (3) data input string. When a message is sent with the sendTaskInput() method, a task input handle is returned. This task input handle contains the ID for the task that was created for this input message.
After all 10 tasks (messages) have been sent to the service, the main client execution thread must wait for all tasks to be processed before uninitializing the client API. As each task is completed by the service, the m_tasksReceived variable is incremented; refer to Step 3. The myCallback.getReceived() method returns the value of m_tasksReceived. If m_tasksReceived is less than the total number of tasks sent and there are no exceptions thrown, the main thread waits two seconds before checking the value of m_tasksReceived again. This cycle continues until all the tasks results are received.
When you add an application through the DE PMC, you must use the Add Application wizard. This wizard defines a consumer location to associate with your application, deploys your service package, and registers your application. After completing the steps with the wizard, your application should be ready to use.