xpxSelectAggrElementsEx

SYNTAX:

xpxSelectAggrElementsEx (aggrId : AGGREGATE OF GENERIC; modelVersion : INTEGER; condition : STRING; options : INTEGER; attributes : STRING; include_exclude_filter : AGGREGATE OF GENERIC; orderBy : STRING; firstIndex, maxHits : INTEGER; xmlConfigurationName : STRING; resultFileName : STRING; VAR indexOfLastFound : INTEGER; VAR actualHits : INTEGER; VAR queryResultIndex : INTEGER; VAR resultString : STRING) status : INTEGER;

The xpxSelectAggrElementsEx function searches an aggregate for elements that match a given condition. The condition may be any symbolic Express-X logical expression. An empty string condition will match all aggregate elements.
Each matching aggregate element will be identified by its element index. All the matching elements will generate a row in the query result. The returned query result may contain a single column of element indexes, each identifying an aggregate element that match the logical expression given in the <condition> argument. If the aggregate has instance type elements, the attributes of the instance may also be returned in any number of individual columns in the query result table.
The index of the aggregate element from which to start searching for matches, and the maximum number of matching element indexes to return, are both specified as input arguments to the function. The actual number of matching indexes returned and the index of the last returned matching element will be returned from the function. This makes it possible to query through huge aggregates by means of a loop where each iteration handles a small subset of the total aggregate. See the example below.
The logical expression given in the <condition> argument will be compiled by the EDMexpressXCompiler^. The query will be executed by the EDMexpressVM^.
If the aggregate elements are instances, the <attributes> argument may be used to specify which attribute values to return in the query result table. It may contain dot expressions, Express built-in functions and EDMexpressX^ xpf bult-in functions.
Attributes argument SYNTAX example:
?Name sizeof(sdai_model.underlying_schema.entities)?
This example will return two columns for instances of EDM_MODEL type in the SystemRepository.ExpressDataManager model. The two columns are.
1) The Name attribute of the EDM_MODEL
2) The number of entities in the "underlying schema" of the model.
The column names in the resulting query table will be ?Name? and ?sizeof(sdai_model.underlying_schema.entities)? respectively. Different column names may be specified by using the "->" operator.
Example: if we want the 2nd column to be given the name "Entities", we may write the 2nd attribute like this:
?sizeof(sdai_model.underlying_schema.entities)->Entities?
Note that the characters white space, comma, and semicolon may all be used as delimiters between the attribute names in the <attributes> argument. Hence none of these characters may be used in the attribute name/attribute expression.
The total number of hits will be returned in the <numberOfHits> argument.

The arguments for the function are:

Argument:	Description:
aggrId	A numeric aggregateID that uniquely identifies the aggregate of interest in the EDMdatabase^. This may be any type of aggregate, persistant, volatile or scratch.
modelVersion	The version of the edmModel to apply this function call on. The <modelVersion> parameter is a numeric sequence number counting from one by increments of one for each new model version that is created. A zero model version number means the current version.
condition	A conditional statement, written in Express-X, that the aggregate elements shall match. References to the element it self is done by the symbol SELF. A string comparing condition may therefore be written ?SELF = SCHMIDT? or ?SELF LIKE SCHMIDT? or even ?xpxLIKE(SELF, SCHMIDT)? Expressions may also refer to the attributes of instances that are being refered to from instance elements; ?SELF.WIFE.FIRST_NAME LIKE Lucy? An unset condition, will match all aggregate elements. All symbolic Express-X logical expressions are legal <condition> values. The <condition> argument will be compiled by the EDMexpressXCompiler^
options	See the description of available options below.
attributes	Specification of the name and contents of each column of the returned query result table. The following examples illustrate the SYNTAX. ?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. ?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. ?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.
include_exclude_filter	The numeric id of an aggregate containing the names or ids of the entities that will be affected by this filter. If the option [xpxFILTER_AS_ENTITY_IDS] is used, this parameter will be interpreted as an aggregate of instance ids, each defining an entity. If the option [xpxFILTER_AS_ENTITY_NAMES] is used, this parameter will be interpreted as an aggregate containing entity names. If the option [xpxINCLUDE_FILTER] is used, no instances but those of a type contained in the aggregate will be included. If the option [xpxEXCLUDE_FILTER] is used, all instances but those of a type contained in the aggregate will be included.
orderBy	Name of the query result column to use for sorting. The column may be specified by its constructor or by the column title. If the <attributes> 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 [xpxHTML_FORMAT] or [xpxASCII_FORMAT] is used. Use the options [xpxASCENDING] and [xpxDESCENDING] to specify the sorting direction.
firstIndex	The aggregate index from which to start searching for matching elements.
maxHits	Specifies the maximum number of indexes that may be returned in the <resultString> or in the query result.
xmlConfigurationName	The name of the XML configuration to apply to the resulting XML formatted query result when the option [xpxXML_FORMAT] is used
resultFileName	The name of the file that will contain the returned XML, HTML or ASCII formatted query result. Only applicable when using the [xpxRESULT_IN_FILE] option in combination with one of the options [xpxHTML_FORMAT], [xpxASCII_FORMAT] or [xpxXML_FORMAT]. Use the [xpxZIPPED_FILE] option to compress the generated file.
indexOfLastFound	The index of the last found matching element. This return value enables incremental search for matching elements. See example below.
actualHits	The number of matching elements found.
queryResultIndex	The index that may be used to identify the queryResult that was generated by the call to this procedure.
resultString	Variable that will receive the returned XML formatted query result when the options [xpxRESULT_IN_STRING] and [xpxXML_FORMAT] are used.

Options:	Description:
xpxALL_ATTRIBUTES	When the argument <attributes> is unset 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 unset or an empty string. Use this option to force the including of all instance attributes even when the <attributes> argument is not unset or an empty string. This option is only applicable on aggregates of instances.
xpxINCLUDE_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 xpxXML_FORMAT.
xpxINCLUDE_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 [xpxXML_FORMAT].
xpxRESULT_IN_STRING	The resulting table will be returned in a string. Must be used in combination with [xpxXML_FORMAT].
xpxEXTRACT_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 [xpxXML_FORMAT].
xpxTRANSFER_NO_DATA	No actual query result will be returned. Use this option when the number of matching elements is the only information needed or for testing the query SYNTAX before actually performing it.
xpxASCENDING	Arrange the query result in ascending order. This option is only applicable when the <orderBy> argument is used.
xpxDESCENDING	Arrange the query result in descending order. This option is only applicable when the <orderBy> argument is used.
xpxONLY_INSTANCE_IDS	Return only a single column with the instanceIds of the matcing instances. This option is only applicable on aggregates of instances.
xpxINCLUDE_INSTANCE_IDS	Prepend all attribute columns in the query result with an instanceId column. This option is only applicable on aggregates of instances.
xpxINCLUDE_FILTER	Only the aggregate elements of types that are explicitely listed in the <include_exclude_filter> argument will be checked. This option is only applicable on aggregates of instances.
xpxEXCLUDE_FILTER	All the aggregate elements, but those of types that are explicitely listed in the <include_exclude_filter> argument, will be checked. This option is only applicable on aggregates of instances.
xpxRESULT_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.
xpxEDM_IDENTIFIERS	The instanceIds that uniquely identify the instances in EDMdatabase will be used as xmlIds for identification of the instances within the ISO10303-28 compliant XML formatted query result. This option is only applicable on aggregates of instances.
xpxFILTER_AS_ENTITY_NAMES	The <include_exclude_filter> argument will be interpreted as an aggregate of entity names. This option is only applicable on aggregates of instances.
xpxFILTER_AS_ENTITY_IDS	The <include_exclude_filter> argument will be interpreted as an aggregate of entityIds. This option is only applicable on aggregates of instances.
xpxHTML_FORMAT	The query result table will be written to an HTML formatted file on the local file system.
xpxASCII_FORMAT	The query result table will be written to a plain ASCII formatted file on the local file system.
xpxONLY_ELEMENT_INDEXES	The query result table will contain only one column with the index of all the matching elements.
xpxOLD_XML_FORMAT	The result of the query will be written to a simple wellformed XML formatted file on the local file system.
xpxXML_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.
xpxZIPPED_FILE	The file given by the argument <resultFileName> will be compressed with gzip. This option has no effect unless combined with the option [xpxRESULT_IN_FILE].
xpxIGNORE_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.

Example:
. . .

firstIndex = 1;
maxHits := 10;
actualHits := maxHits;

WHEN (actualHits = maxHits);
BEGIN
stat := xpxSelectAggrElementsEX (myAggrId, 0,
?SELF.WIFE.FIRST_NAME LIKE Lucy?,
xpxRESULT_IN_STRING + xpxASCENDING,
?FirstName, LastName, Address?, 0, ?LastName?,
firstIndex, maxHits, ??, ??, lastFound, actualHits,
0, resultString);

(* Process the result string here *)

firstIndex := lastMatch + 1;
END;

. . .