edmiRemoteExecuteQueryEx

Invokes the EDMexpressVM with an EDMquery (also denoted Query Functions) and a list of corresponding input parameters for a data model within a remote _EDMdatabase^_ .
Query functions are defined in EDMquerySchemas. EDMquerySchemas must be compiled to extend the dictionary model of a data model with one or more Query functions. The function edmiRemoteDefineSchema may be used to compile an EDMquerySchema in a remote EDMdatabase^.
The memory needed for the returned result of an EDMquery will be implicitely allocated by this function. The result will be returned in an tSdaiQueryResult data structure. See the header file sdai.h for a description of this data structure. Use the function edmiFreeQueryResult to release the locally allocated memory when it is no longer needed.
The interactive EDMdebugger^ within the EDMsupervisor^ may be used to test and debug any Express or Express-X schemata, including Query functions, executed by the EDMexpressVM^.
The "expressions logging" feature of EDM offers powerful tracing capabilities for testing and debugging Query functions. Use edmiDefineExpressionsLog to configure this feature.
The input parameters to the Query function may otionally be supplied as an XML formatted file or string.
The resulting output from the Query function will be returned in the <executionResult> argument and may be returned in one of the following formats:
1) An ordinary SdaiQueryResult data structure. This is the format that is returned from the edmiRemoteExecuteQuery function.
2) A native EDMI format. Similar to an ordinary SdaiQueryResult data structure, but all columns will be ASCII string formatted.
3) An XML formatted string.
4) An XML formatted file.
Related functions: edmiRemoteExecuteQuery
Header:
#include "sdai.h"
Prototype:
EdmiError edmiRemoteExecuteQueryEx(SdaiServerContext   serverContextId,
                                    SdaiSourceOrTarget  source,
                                    SdaiString          remoteQuerySchemaName,
                                    SdaiString          remoteQueryName,
                                    SdaiSourceOrTarget  target,
                                    SdaiInteger         nFileMappings,
                                    SdaiFileMapping     fileMappings[],
                                    SdaiInteger         numberOfParameters,
                                    SdaiSelect          parameters[],
                                    SdaiOptions         options,
                                    SdaiString          columnNames,
                                    SdaiString          orderBy,
                                    SdaiLogDescription  logDescription,
                                    SdaiExecutionResult executionResult,
                                    SdaiSelect          extensionsArgs,
                                    SdaiInvocationId    *edmiInvocationId);

Arguments:

serverContextId	Context identification, from edmiDefineServerContext
source	An SdaiSourceOrTarget structure specifying the names of the repository and the model The name of the repository in the remote _EDMdatabase^_ that contains the model for which the Query function is to be run. The name of the model on which to run the query.
remoteQuerySchemaName	The name of the EDMquerySchema in which the Query function to be run is defined. Query Schema names are case insensitive.
remoteQueryName	The name of the Query function to be run. Query Schema names are case insensitive.
target	An SdaiSourceOrTarget structure used for receiving the query result. Applicable elements within this structure are; queryResult. Used by default and when the option RESULT_AS_TABLE is specified. resultString. Used when the [RESULT_IN_FILE] option is specified. fileName. Used when the [RESULT_IN_STRING] option is specified.
nFileMappings	Currently not used.
fileMappings	Currently not used.
numberOfParameters	The number of parameters in the <parameters> argument.
parameters	Buffer of pointers to locally allocated tSdaiSelect structures. Each tSdaiSelect structure defines the type and value of an input parameter to the Query function.
options	See description of available options below. Options may be joined by using the bitwise OR operator.
columnNames	Specification of the title and contents of each column of the returned query result table. The following examples illustrate the syntax. a) "NAME SEX AGE" : The attributes name, sex and age will be returned in column 1, 2 and 3 of the returned query table. The title of the columns will be NAME, SEX and AGE respectively. b) "NAME,WIFE.MOTHER.DOG.NAME->DOG" The first column will contain the mans name. The second column will contain the mans mother in laws dogs name. The title of the columns will be NAME and DOG respectively. c) "DOG.NAME->DOG;xpfGetMemberCount(DOG. PUPPIES)->PUPPIES" The first column will contain the dogs name. The second column will contain its number of puppies . The title of the columns will be DOG and PUPPIES respectively. Whitespace, comma end semicolon are all used as field delimiters.
orderBy	Name of the query result column to use for sorting. The column may be specified with its constructor or by the column title. If the <columnNames> argument is: "DOG.NAME->DOG" The order by argument may be either "DOG" or "DOG.NAME". This argument is only aplicable when one of the options [HTML_FORMAT] or [ASCII_FORMAT] is used. Use the options [ASCENDING] and [DESCENDING] to specify the sorting direction.
logDescription	An SdaiLogDescription structure containing the specifications for the logging of the Query function.
executionResult	An SdaiExecutionResult structure containing the error and warning status returned from the EDMexpressVM^ after running the Query function.
extensionsArgs	Currently not used.
edmiInvocationId	Currently not used.

Options: Descriptions:

ALL_ATTRIBUTES	When the argument <attributes> is NULL or an empty string, all attributes of the instances will be included in the query result. However, if the <attributes> argument is used to add one or more aditional constructed columns or to rename a column in the query result, the return of all the instance attributes will be hindered due to an <attributes> argument that is no longer NULL or an empty string. Use this option to force the including of all instance attributes even when the <attributes> argument is not NULL or an empty string. This option is only applicable on aggregates of instances.
INCLUDE_CONFIGURATION	Includes the XML Configuration in the generated ISO10303-28 compliant XML formatted query result. This option has no effect unless combined with the option [XML_FORMAT].
INCLUDE_SCHEMA	Includes the underlying meta data in the generated ISO10303-28 compliant XML formatted query result. This option has no effect unless combined with the option [XML_FORMAT].
PARAMETERS_IN_XML_STRING	The first and only parameter transferred to the Query function will be interpreted as an XML formatted list of parameters.
RESULT_IN_STRING	The resulting table will be returned in a string allocated in heap-memory of the calling application. Use edmiFree to release allocated memory. Use the option [RESULT_IN_FILE] to write the table to a file.
OPEN_MODEL_FOR_WRITE_ACCESS	The model will be opened for write access. This enables manipulation of the model population from query functions.
EXTRACT_SHALLOW	Use this option to force a shallow XML formatted query result. ISO10303-28 compliant XML Query results are deep by default. No other query result format supported by this function is deep. Hence, this option has no effect unless combined with the option [XML_FORMAT].
PARAMETERS_IN_XML_FILE	The first and only parameter transferred to the Query function will be interpreted as the name of an XML formatted file on the local file system containing the all the Query functions parameters.
ASCENDING	Arrange the query result in ascending order. This option is only applicable when the <orderBy> argument is used.
DESCENDING	Arrange the query result in descending order. This option is only applicable when the <orderBy> argument is used.
RESULT_AS_ID	The query result will be returned as an aggregateID when sdaiAGGR is the declared data type of the return value from the Query function. The aggregateID will be returned in the element data.value.aggrValof the returned tSdaiQueryResult data structure. [RESULT_AS_ID] and [RESULT_AS_ID_CONTENTS] are mutually exclusive. [RESULT_AS_ID] is the default value.
RESULT_AS_ID_CONTENTS	The query result will be returned as a table when sdaiAGGR is the declared data type of the return value from the Query function. The table will consist of a single column with one row for each element in the returned aggregate. [RESULT_AS_ID] and [RESULT_AS_ID_CONTENTS] are mutually exclusive. [RESULT_AS_ID] is the default value.
RESULT_IN_FILE	The resulting table will be written to a file on the local file system of the calling application. The name of the file must be specified in the <resultFileName> argument. [RESULT_AS_TABLE] must be activated when [RESULT_IN_FILE] is used with [HTML_FORMAT] or [ASCII_FORMAT].
EDM_IDENTIFIERS	The instanceIds that uniquely identify the instances in the remote EDMdatabase^ will be used as xmlIds for identification of the instances within the ISO10303-28 compliant XML formatted query result.
RESULT_AS_TABLE	The query result will be returned as a table. This option is only applicable for Query functions that return an aggregate of either instances or view instances. The number of elements in the aggregate will be the number of rows in the table and the number of attributes in the actual instance type or view type will be the number of columns in the table.
HTML_FORMAT	The query result table will be presented in HTML format in a locally allocated string or in a file on the local file system. See the options [RESULT_IN_FILE] and [RESULT_IN_STRING].
ASCII_FORMAT	The query result table will be presented in plain ASCII format in a locally allocated string or in a file on the local file system. See the options [RESULT_IN_FILE] and [RESULT_IN_STRING].
OLD_XML_FORMAT	The result of the query will be returned in a simple well formed XML formatted file on the local file system.
XML_FORMAT	The result of the query will be returned in an ISO10303-28 compliant XML formatted string or in a file on the local file system.
ZIPPED_FILE	The file given by the argument <resultFileName> will be compressed with gzip. This option has no effect unless combined with the option [RESULT_IN_FILE].
IGNORE_EMPTY_COLUMNS	Columns for attributes that do not have defined values for any of the returned instances will be left out of the query result table.

Returns:
A completion code of datatype EdmiError is the returned function value. The completion code has the following values:
Completion code = 0 : Operation successfully performed.
Completion code != 0: Error in operation. Completion code is an _EDMinterface^_ error code. Use edmiGetErrorText to get the error text corresponding to the error code.
Example:
/*
– --------------------------------------
– File: c:/data/furniture.exp
– --------------------------------------
SCHEMA Furniture;
TYPE tScrewType = ENUMERATION OF (PHILIPS, ALLEN, FLAT); END_TYPE;
ENTITY Screw;
Id : STRING;
Typ : tScrewType;
Len : REAL;
Dia : REAL;
END_ENTITY;
ENTITY Dining_Table;
Name : STRING;
Legs : INTEGER;
Len : REAL;
Width : REAL;
Height : REAL;
Screws : BAG OF Screw;
END_ENTITY;
END_SCHEMA;

– ---------------------------------------
– File: c:/data/furniture_query.qex
– ---------------------------------------
QUERY_SCHEMA Furniture_Query FOR Furniture;
GLOBAL
DECLARE src INSTANCE OF Furniture;
END_GLOBAL;

VIEW_ENTITY View_Table;
Name : STRING;
Area : REAL;
END_VIEW_ENTITY;

QUERY_FUNCTION Dining_Table_Area (Area : REAL) : SET OF View_Table;
LOCAL
result : SET of View_Table;
currView : View_Table;
table_area : REAL;
END_LOCAL;
FROM(sdt:src::Dining_Table)
WHEN TRUE;
BEGIN
table_area := sdt.Len*sdt.Width;
IF(table_area > Area ) THEN
NEW currView;
currView.Name := sdt.Name;
currView.Area := table_area;
result ++ currView;
END_IF;
END;
RETURN(result);
END_QUERY_FUNCTION;
END_QUERY_SCHEMA;
*/

int i, j;
EdmiError rstat, error;
SdaiInteger nErr, nWrn;
SdaiServerContext myContext;

/* Define Remote Server Context */
rstat = edmiDefineServerContext("MyRemoteServerContext",
"Johnny", "Supervisor", "cf37ftr",
"TCP", "9090", "MyServerHost",
NULL, NULL, NULL, NULL, NULL, &myContext);

/* Compile the Express Schema */
rstat = edmiRemoteDefineSchema(myContext, EXPRESS_SCHEMA_TYPE,
"c:/data/furniture.exp", "c:/temp/furniture.dia",
"Furniture", 0, &nWrn, &nErr, NULL);

/* Compile the Query Schema */
rstat = edmiRemoteDefineSchema(myContext, QUERY_SCHEMA_TYPE,
"c:/data/furniture_query.qex", "c:/temp/furniture_query.dia",
"Furniture_Query", 0, &nWrn, &nErr, NULL);

/* Import the product catalogue from a p21 file
into the model Products in the DataRepository */
rstat = edmiRemoteReadStepFile(myContext, "DataRepository",
"Products", NULL, NULL, "c:/data/furniture.stp",
"c:/temp/furniture.stp.dia", "Furniture", NULL,
0, &nWrn, &nErr, &error, NULL);

if (!rstat) {
SdaiString _usrOutFile = "c:/temp/validation.out";
SdaiString _sysOutFile = "c:/temp/validation.dia";
SdaiString _repName = "DataRepository";
SdaiString _srcModName = "Products";
SdaiString _tarModName = "Products_new";
tSdaiSourceOrTarget _source, _target;
tSdaiExecutionResult _exeRes;
tSdaiLogDescription _logDescr;
tSdaiSelect _sel[1];
SdaiSelect _param[1] = {&_sel[0]};
_logDescr.loggingOptions = FULL_LOG | LOG_TO_FILE;
_logDescr.sourceLinesToLog = NULL;
_logDescr.declarationsToLog = NULL;
_logDescr.systemOutputFile = _sysOutFile;
_logDescr.userOutputFile = _usrOutFile;
_logDescr.maxLogFileSize = 104857600;
_param[0]->nTypes = 0;
_param[0]->type = sdaiREAL;
_param[0]->typeList = NULL;
_param[0]->value.realVal = 0.0;
_source.repositoryName = _repName;
_source.modelName = _srcModName;
_source.options = REMOTE_MODEL;

/* Get all dining tables with an area
greater than 2.0 square meters */
rstat = edmiRemoteExecuteQueryEx(myContext, &_source,
"Furniture_Query", "Dining_Table_Area", &_target, 0,
NULL, 1, _param, RESULT_AS_TABLE | RESULT_AS_ID_CONTENTS,
"Name Area", "Name", &_logDescr, &_exeRes, NULL, NULL);

/* Print all matching dining tables */
printf("\nThe following dining tables was found");
for (i=0; i<_target.queryResult->rows; i++) {
for (j=0; j<_target.queryResult->columns; j++) {
printf("\n%s - %f m2",
((SdaiString*) _target.queryResult->columnDescr[0]->pvalue)[i],
((SdaiReal *) _target.queryResult->columnDescr[1]->pvalue)[i]);
}
}
edmiFreeQueryResult(_target.queryResult);
}
. . .