ullaResultCode_t ullaTupleNext(const ullaTupleId_t utId);
ullaResultCode_t ullaTupleFieldCount(const ullaTupleId_t utId, ullaFieldNum_t
*fieldCount);
ullaResultCode_t ullaFieldNameLength(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaStringLen_t *fieldNameLen);
ullaResultCode_t ullaFieldName(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaString_t fieldName, ullaStringLen_t *fieldNameLen);
ullaResultCode_t ullaFieldStatus(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaResultCode_t *fieldStatus);
Additional accessor functions for ullaRequestAttribute, ullaRequestCommand,
ullaRequestSample, ullaRequestNotification
ullaResultCode_t ullaFieldTimestamp(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaTime_t *timestamp, ullaTime_t *now);
Additional accessor functions for ullaRequestAttribute, ullaRequestCommand,
ullaRequestSample, ullaRequestNotification
ullaResultCode_t ullaFieldType(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaType_t *fieldType);
ullaResultCode_t ullaFieldValueLength(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaStringLen_t *fieldLen);
ullaResultCode_t ullaFieldValueToInt(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaInteger_t *fieldValue);
ullaResultCode_t ullaFieldValueToString(const ullaTupleId_t utId, const
ullaFieldNum_t fieldNum, ullaString_t fieldValue, ullaStringLen_t *fieldValueLen);
Additional accessor functions for ullaRequestReflection
ullaResultCode_t ullaFieldModifier(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaModifier_t *modifier);
ullaResultCode_t ullaFieldDescriptionLength(const ullaTupleId_t utId, const
ullaFieldNum_t fieldNum, ullaStringLen_t *descriptionLen);
ullaResultCode_t ullaFieldDescription(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaString_t description, ullaStringLen_t *descriptionLen);
ullaResultCode_t ullaFieldMin(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaInteger_t *min);
ullaResultCode_t ullaFieldMax(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaInteger_t *max);
ullaResultCode_t ullaFieldValueSetLength(const ullaTupleId_t utId, const
ullaFieldNum_t fieldNum, ullaStringLen_t *valueSetLen);
ullaResultCode_t ullaFieldValueSet(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaString_t valueSet, ullaStringLen_t *valueSetLen);
ullaResultCode_t ullaFieldUnitLength(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaStringLen_t *unitLen);
ullaResultCode_t ullaFieldUnit(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaString_t unit, ullaStringLen_t *unitLen);
ullaResultCode_t ullaFieldParameterLength(const ullaTupleId_t utId, const
ullaFieldNum_t fieldNum, ullaStringLen_t *ParameterLen);
ullaResultCode_t ullaFieldParameter(const ullaTupleId_t utId, const ullaFieldNum_t
fieldNum, ullaString_t parameter, ullaStringLen_t *parameterLen);
In order to access the data from the ULLA result, the Link User (LU), or application using ULLA, can utilize the accessor functions. The ULLA result is structured using tuples and fields. Using a tupleId the LU can iterate over the "rows" in the ullaResult. The method ullaTupleNext allows to increment the tupleId to access the next tuple in the ullaResult.
Each tuple within the same ullaResult has as the same number of fields, according to the uql_statement used. The number of fields can be retrieved using the ullaTupleFieldCount method. The order of the attribute or command names in the uqp_statement determines the order the data is stored into the ULLA result fields.
All further functions work based on a combination of utId and fieldNum in order to address a specific field in the ullaResult. Please look at the individual descriptions of these so-called "accessor-functions". All xxxLength functions are indicating the amount of bytes used for a string. This does include the trailing \0 at the end of the string.
Another specific function is the ullaFieldStatus method. It is possible to verify the status of the field data is ok. In the case of an ullaResult from a ullaRequestAttribute call the attribute data might not be available at all times. In this case the status indicates the corresponding error code (see below). In the case of an ullaResult from an ullaRequestCommand call the status indicates the success of the command execution of a specific command in the select_clause of the uql_statement.
ullaTupleNext is used to increment the ULLA Core internal tuple pointer to the next tuple of the same ullaResult. Before getting any information from the ullaTuple, this functions needs to be called to access the first tuple.
ullaTupleFieldCount returns the number of fields within all tuples of the same ullaResult.
Using ullaFieldName and ullaFieldNameLength the LU can verify that the name of the data field matches the one in the query. The position of the data value is subsequently the same as in the select clause of the query.
ullaFieldTimestamp returns the current timestamp and the timestamp the field was filled by the LLA.
ullaFieldType returns the ULLA-type of the field data according to the type-specific accessor functions (see below).
ullaFieldValueLength returns the number of bytes required to hold the data of the field.
ullaFieldValueToInt is a type-specific accessor function that works on field containing an ulla_integer_t value. It casts the value to int and copies the data to the pre-allocates location.
ullaFieldValueToString is a type-specific accessor function that works on field containing an ulla_string_t value. It casts the value to int and copies the data to the pre-allocates location.
The following accessor functions are used only for the reflection interface:
ullaFieldModifier returns the ULLA-modifier of the attribute.
ullaFieldDescription and ullaFieldDescriptionLength return the description of the attribute according to the attribute semantics.
ullaFieldMin and ullaFieldMax are valid for ulla_integer_t attributes and return the minimum and maximum value the attribute data can have.
ullaFieldValueSet and ullaFieldValueSetLength in case there is a specific list of possible values the attribute data can have, this list can be retrieved by the means of these two functions.
ullaFieldUnit and ullaFieldUnitLength describe the unit of the attribute value.
ullaFieldParameter and ullaFieldParameterLength are valid if the field describes a command. The list of attributes, which are parameters to this command are listed by these two functions.
The following parameters have to be carefully considered:
Some examples for the usage of accessor-functions on an ullaResult:
if( (res = ullaResultTuple(urId, &utId)) < 0) {
/* failed to access tuples from ullaResult */
/* verify status of the ullaResult if shared among threads */
}
while(ullaTupleNext(utId) != ULLA_NO_MORE_TUPLES_ERROR) {
if( (res = ullaFieldCount(utId, &count)) < 0) {
/* failed to get field count */
}
for(i=0; i<count; i++) {
if( (res = ullaFieldType(utId, i, &type)) < ) {
/* failed to get field type */
}
if( type == ULLA_TYPE_INTEGER ) {
if( (res = ullaFieldValueToInt(utId, i, &integer)) < 0) {
/* failed to cast field data to ulla_integer_t */
}
printf("extracted integer value %i\n", integer);
}
}
}
ullaResultFree(urId);
ulla(2) , uql(2) , ullaResult(2) , ullaTuple(2) , ullaRequestReflection(2) , ullaRequestAttribute(2) , ullaRequestCommand(2) , ullaRequestNotification(2) , ullaRequestSample(2) , ullaRequestLock(2) , ullaGetCoreDescriptor(2)