xpxSelectInstancesBNEx

SYNTAX:

xpxSelectInstancesBNEx (modelId : GENERIC; modelVersion : INTEGER; entityName, 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 xpxSelectInstancesBNEx function search in the specified remote edmModel for instances of a specified type that match a given condition. Optionally subtypes of the specified type may be included in the search.
The condition may be any legal symbolic Express-X logical expression. An undefined or empty string condition will match all instances of the specified types.
All the instance Ids of the candidates are collected in a single temporary instance aggregate. This aggregate will be searched for matching instances. The index of the first aggregate element to check, and the maximum number of matching instances to return, are specified as input arguments to the function. The actual number of matching instances returned and the index of the last returned matching instance in the instance aggregate will be returned from the function. This makes it possible to query through huge amounts of instances by means of a loop where each iteration handles a small subset of the total instance aggregate.
The <condition> argument will be compiled by the EDMexpressXCompiler^. The specified query will be executed by the EDMexpressVM^.
The <attributes> argument may contain a "dot expression" including Express built-in functions and EDMexpressX^ xpf bult-in functions.
Attributes argument SYNTAX example:
"Name sizeof(sdai_model.underlying_schema.entities)"
This example is from an edmiRemoteSelectInstances operation on the EDM_MODEL objects in the SystemRepository.ExpressDataManager model. There will be 2 columns

The Name attribute of the EDM_MODEL
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. By using the "->" characters, a new column name can be specified.
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 are all used as delimiters between the attribute "names" in the attributes argument, hence none of these characters can be used in the attribute name/attribute expression.
The total number of hits will be returned in the <actualHits> argument.

The arguments for the function are:

Argument::	Description:
modelId	A numeric modelID that uniquely identifies the data model of interest in the EDMdatabase^ .
modelVersion	The numeric version ID that specifies the version of the model to select instances from. If unset, the version will be the latest version.
entityName	Specifies the name of the entity that defines the actual instance type to query. Entity names are case insensitive.
condition	The condition that the instances in the instance aggregate shall match. An undefined or empty string condition will match all the instances of the specified type. A valid condition is any Express-X logical expression that refers to any number of attributes defined for the instance type specified by the argument <entityName>. The expression may also refer to attributes of referenced application instances. Example conditions: ?xpxTRUE? Equivalent to equivalent or empty string. ?(NAME LIKE ?JOHN?) AND (AGE > 30)? Maches Johnny and Johnatan if they are older than 30 years. ?WIFE.MOTHER.DOG.NAME = ?Fido?? Matches all men with a mother in law that owns a dog named Fido*.
options	Specifies the options to be used in the invocation of the xpxSelectInstancesBNEx function. The <condition> value can be specified as a bitwise OR between the actual options to enable. See the description of available options below.
attributes	Specification of the title 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 with 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	All the instances of entities are kept in entity extents. All the entity extents of the entities that are to be queried (subtypes may also be queried) are joined into a single aggregate of instances. The position in this aggregate to start reading from is specified by this parameter. This way, huge populations may be incrementally queried by setting this argument equal to one more than the value of <indexOfLastFound> that resultet from the previous iterative call to this function.
maxHits	The greatest allowed number of hits in the query result. When this number of matching instances is found, the search for additional matches will stop.
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].
indexOfLastFound	The index of the ?last returned matching element?. This argument enables the caller to search for instances in an incremental way by specifying this returned ?index value plus one? as the input to the next xpxSelectAggrInstancesEx function and so on.
actualHits	The number of matching instances found. If this value is equal to the <maxHits> argument, it is a possibility that there may be more matching instances among the queried entity types.
queryResultIndex	A numeric index that identifies the generated query result within internal datastructures in EDM. Use the <queryResultIndex> as input to the function xpfGetQueryResultDataCell to access the actual data within the query result.
resultString	Variable that will receive the returned XML, HTML or ASCII formatted query result when the option [xpxRESULT_IN_STRING] is used with one of the options [xpxHTML_FORMAT], [xpxASCII_FORMAT] or [xpxXML_FORMAT].

Option:	Description:
xpxSUBTYPES	Search for matching instances of the entity specified by the <entityName> argument and all instances of any of its subtypes.
xpxALL_ATTRIBUTES	When the argument <attributes> is undefined 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 undefined or an empty string. Use this option to force the including of all instance attributes even when the <attributes> argument is not undefined or an empty string.
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 allocated in heap-memory of the calling application. Use the option [xpxRESULT_IN_FILE] to write the table to a file.
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 query result will be returned from the remote EDMdatabase^. Use this option when the number of matching instances is the only information needed or for testing the query SYNTAX before actually performing it.
xpxASCENDING	Arrange the query result instances in ascending order. This option is only applicable when the <orderBy> argument is used.
xpxDESCENDING	Arrange the query result instances 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.
xpxINCLUDE_INSTANCE_IDS	Prepend all attribute columns in the query result with an instanceId column
xpxINCLUDE_FILTER	Only the subtypes of the entity given by the <entityName> argument that are listed in the <include_exclude_filter> argument will be queried for matching instances. Only applicable when combined with the [xpxSUBTYPES] option.
xpxEXCLUDE_FILTER	All subtypes of the entity given by the <entityName> argument except those listed in the <include_exclude_filter> argument will be queried for matching instances. Only applicable when combined with the [xpxSUBTYPES] option.
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 the remote EDMdatabase^ will be used as xmlIds for identification of the instances within the ISO10303-28 compliant XML formatted query result.
xpxFILTER_AS_ENTITY_NAMES	The <include_exclude_filter> argument will be interpreted as an aggregate of strings. Each string must give the name of a subtype of the entity given by the argument <entityName>. This option is only applicable when combined with the [xpxSUBTYPES] option.
xpxFILTER_AS_ENTITY_IDS	The <include_exclude_filter> argument will be interpreted as an aggregate of entityIds. Each entityId must identify a subtype of the entity given by the argument <entityName>. This option is only applicable when combined with the [xpxSUBTYPES] option.
xpxHTML_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 [xpxRESULT_IN_FILE] and [xpxRESULT_IN_STRING].
xpxASCII_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 [xpxRESULT_IN_FILE] and [xpxRESULT_IN_STRING].
xpxOLD_XML_FORMAT	The result of the query will be returned in 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.