Temboo returns Choreo result data to the Samsung ARTIK in a simple key-value format. Each name and value is followed by a newline character (\n), to increase readability, and a record-separator or field-separator hex character (\x1F to delimit names, and \x1E to delimit values). This looks like:
Name1\n\x1F Value1\n\x1E Name2\n\x1F Value2\n\x1E
The Temboo Library provides information on the set of outputs returned by each Choreo. For example, you can see that the Yahoo > Weather > GetWeatherByAddress returns a number of outputs, including one named Response and one named WOEID (Yahoo’s “Where On Earth ID” for that address).
The outputs returned by the GetWeatherByAddress Choreo
In this case, after running the Yahoo! Weather sample sketch in our Getting Started tutorial, the data received by the LaunchPad would look like:
Response\n\x1F [a whole bunch of XML here, potentially containing newlines]\n\x1E WOEID\n\x1F 12761345\n\x1E HTTP_CODE\n\x1F 200\n\x1E
The last key, HTTP_CODE, is not an explicit output of the GetWeatherByAddress Choreo, but is returned by Temboo to simplify the creation of error handlers (see below). A HTTP code of 200 means that the Choreo executed successfully; any other code indicates that an error occurred.
The same format is used whether a particular key/value pair is defined in an Output Filter or is an unfiltered output from the Choreo. For example, in the Output Filters tutorial, we defined output filters for the Response output of the GetWeatherByAddress Choreo called temperature, date and city. Running this sketch would return something like:
temperature\n\x1F 90\n\x1E date\n\x1F Mon, 24 Jun 2013 11:53 am PDT\n\x1E city\n\x1F New York\n\x1E HTTP_CODE\n\x1F 200\n\x1E
Note: Since one or more Output Filters (temperature, date and city) are defined to filter the Response output, the raw XML value of the Choreo's outputs (Response and WOEID) are not returned.
The key/value format returned by Temboo makes it easy to read and use specific results in your code. To demonstrate how this works, we'll modify the sketch from the Output Filters tutorial to read and print individual output values.
To do so, update the contents of the while(GetWeatherByAddressChoreo.available()) loop at the end of that code so that it reads like the code below. Make sure the value and name char arrays are large enough to hold the expected data and a null terminator. If the char array is not large enough, choreoResultReadStringUntil will return -1.
while(tembooClientAvailable(session->connectionData)) {
char name[64];
char value[64];
memset(name, 0, sizeof(name));
memset(value, 0, sizeof(value));
choreoResultReadStringUntil(session->connectionData, name, sizeof(name), '\x1F');
if (!strcmp(name, "date")) {
if(choreoResultReadStringUntil(session->connectionData, value, sizeof(value), '\x1E') == -1) {
printf("Error: char array is not large enough to store the string\n");
} else {
printf("The date is %s\n", value);
}
} else if (!strcmp(name, "temperature")) {
if(choreoResultReadStringUntil(session->connectionData, value, sizeof(value), '\x1E') == -1) {
printf("Error: char array is not large enough to store the string\n");
} else {
printf("The temperature is %s\n", value);
}
} else if (!strcmp(name, "city")) {
if(choreoResultReadStringUntil(session->connectionData, value, sizeof(value), '\x1E') == -1) {
printf("Error: char array is not large enough to store the string\n");
} else {
printf("The city is %s\n", value);
}
} else {
choreoResultFind(session->connectionData, "\x1E");
}
}
Save and upload your new program. You should now see the parsed individual result components printed to the serial monitor.
If an error occurs while running a Choreo (for example, if you comment out the GetWeatherByAddress input that specifies the address to look up), you’ll receive a response like:
Error\n\x1F "An error has occurred. Address is required."\n\x1E HTTP_CODE\n\x1F 500\n\x1E
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.