Collections

You can create an array which includes a number of elements which all satisfy specific selection criteria, as defined by yourself. This is a useful way of collecting information on particular elements. You use the syntax:

VAR !Array COLLECT selection criteria MAX number

!Array is the name of the array that will be created to contain the elements selected.

The following general criteria can be used to define the selection:

• A class of elements or element types.

• A logical expression to be satisfied at all selected elements.

• A physical volume in which all selected elements must lie.

• A point in the hierarchy below which all selected elements must lie.

  All criteria (except for class) are optional.

It is possible to limit the number of items collected using the MAX number option. Starting for example: MAX 50, will collect only the first 50 items that matches the criteria given.

Class is essentially a list of element types (or possibly of actual elements). This list can be optionally qualified to indicate whether members should be included, or whether only ‘items’ (that is, the lowest level components in the hierarchy below a given element) should be included.

For example:

The command:

VAR !PIPECOMPS COLLECT ALL BRANCH MEMBERS

Would create the array !PIPECOMPS and set it to contain the reference numbers of every piping component in the MDB.

Logical expressions, which return TRUE or FALSE, can be used. They are most likely to be used to check the value of an attribute for collection. The WITH or WHERE options introduce the expression. For example:

VAR !LENGTHS COLLECT ALL WITH ( XLEN * YLEN 8 ZLEN GT 1000 )

would collect all elements for which the attributes XLEN, YLEN and ZLEN match the criteria in the array !LENGTHS.

A volume is defined by the WITHIN keyword. You can define the volume either in terms of two diagonally opposite points of an enclosing box, or as a volume around an element (with an optional clearance around the box which contains the element). For example:

VAR !VOLUME COLLECT ALL WITHIN W800N17000U0 TO W1400N13500U1200

collects all elements in the defined volume into the array !VOLUME.

VAR !P COLLECT ALL PIPE EXCLUSIVE WITHIN VOLUME /PUMP1 1500

collects all piping components within the volume defined by a box ‘drawn’ 1500 mm around /PUMP1 and puts them into the array !P. The EXCLUSIVE keyword indicates that only the chosen elements exclusively within the given volume are to be selected.

In Plant there are structural design data, termed MODEL, and detailed design data, termed PRODUCTION. These two sets of data represent the same model and occupy the same 3D space. For a volumetric query you only want one of the sets of data returned.

These two options allow you to choose which set of data will be returned by the volumetric query.

Example

Command Syntax

>--- VOLUMEOPTION ---+--- HULL DESIGN ---.
                     |                   |
                     |                   |
                     ‘- HULL PRODUCTION -+--- ON  ---.
                                         |           |
                                         |           |
                                         ‘--- OFF ---+--->

Hierarchy criteria can be defined by the FOR keyword. It identifies a list of elements below which all selected elements must occur. You can also include an exclusion list. For example:

VAR !BRANCH COLLECT ALL BRANCH MEMBERS FOR /PIPE1 /PIPE2

EXCLUDE BRAN 1 OF /PIPE2

You can append the results of such a collection to an existing array using the APPEND keyword. For example:

VAR !BENDS APPEND COLLECT ALL ELBOWS

Would add the references for all elbows to the array !BENDS.

You can also overwrite elements in the array by specifying the first index in the array which you want to be overwritten. The specified index, and the indexes following it, will be overwritten by the results. For example:

VAR !BENDS[99] COLLECT ALL ELBOWS

Would place the reference for the first ELBOW selected at position 99 in the array !BENDS, overwriting any existing data, and subsequent selections in the array elements that follow.

If you specify more than one criteria, the specifications must be in the above order Some more examples:

Note: This selection mechanism is a very powerful tool for searching whole databases and MDBs. However, if you're not careful the selection process could be very time consuming and tie up a lot of computer resource. Therefore, it is important that selection is performed as efficiently as possible. Plant tries to apply the above criteria so that the fastest condition is applied first and the most expensive is left to last.

Typically, the expression is the slowest condition to evaluate, so it is important to limit the selection as much as possible. For instance, take the example which appeared above:

ENHANCE ALL WITH ( XLEN * YLEN * ZLEN GT 100 0 )

Since only BOXes (and NBOXes) meet this criterion it would be sensible to limit the search by specifying an appropriate class:

ENHANCE ALL BOX WITH ( XLEN * YLEN * ZLEN GT 100 0 )

This cuts the time to execute the selection. This is because the selection system knows that BOXes only occur in DESI databases. Therefore it does not search other types of database. It also knows where boxes are in the hierarchy, and so does not search unnecessary elements.

Even greater performance savings can be gained by explicitly limiting the elements which have to be visited by the search:

ENHANCE ALL BOX WITH ( XLEN * YLEN * ZLEN GT 1000 ) FOR /*

By default, the entire MDB is searched. But by specifying a hierarchy criterion, the selection time can be cut considerably.

Limiting the volume of the search also cuts the number of elements which have to be checked. However, it should be noted that this criterion is applied by determining whether element limit boxes fall within the specified volume, using the spatial map. This is a fast approach, but is not meant to provide the same accuracy as is used in on line clashing.

VAR IPIPECOMPS COLLECT ALL BRANCH MEMBERS

will set up the array IPIPECOMPS to contain the reference numbers of every piping component in the MDB. For example:

IPIPECOMPS [1]  = '=20/302'

IPIPECOMPS [2]  = '=20/303'

IPIPECOMPS [3]  = '=20/304'

       .

       .

       .

IPIPECOMPS [354] = '=25/510'

Every flange could then be extracted as follows:

VAR !FLANGES COLLECT (ALL FLANGES) FROM IPIPECOMPS

and then enhanced (highlighted):

ENHANCE ALL FROM !FLANGES

This could alternatively be performed in one step:

ENHANCE ALL FLANGES FROM IPIPECOMPS

Collections may be joined or concatenated by preceding the COLLECT keyword by APPEND:

VAR !BENDS APPEND COLLECT ALL ELBOWS

Alternatively, the following:

VAR !LIST[99] COLLECT ALL SLCY

would place the reference of the first SLCY at position 99 in !LIST overwriting any data that already exists at that and subsequent elements of the array.

If a selection contains elements of type TUBIng, then the collection describes it as the Leave Tube of an existing database element:

VAR !TUBING COLLECT (ALL TUBI) FOR /*

Then !TUBING would contain something like the following:

The evaluate command allows an expression to be evaluation for all members of a collection.

The syntax is:

VAR !variable EVALUATE expression For selection. For example, to get the description of all equipment you can do:

var !cln collect all EQUI

var !name evaluate (description) for all from !cln

or

var !name evaluate (description) for all EQUI

The PML collection object can also be used as an alternative to the COLLECTION syntax. This object is described in the Software Customization Reference documentation.

The name of a given prefix may be collected using the 'FROM TABLE NAME PREFIX' option.

For example:

COLLECT ALL FROM TABLE NAME PREFIX '/B'

This will find all names starting with 'B'.

The syntax may be used in conjunction with the standard options. For example:

COLLECT ALL NOZZ WHERE (HEIGHT GT 100) FROM TABLE NAME PREFIX '/B'

Some reference attributes index the attribute values. For these the indexed values can be accessed directly using FROM TABLE XXXX VALUE YYYY, where XXX is the attribute name and YYYY is the attribute match.

For example:

VAR !COLL COLLECT ALL FROM TABLE SPRE VALUE /RF300/100G

This will return all elements with SPRE set to /RF300/100G.

The syntax may be used in conjunction with the standard options. For example:

VAR !COLL COLLECT ALL FLAN FROM TABLE SPRE VALUE /RF300/100G

Searching using indexes directly will be considerably faster than the standard searches.for example:

VAR !COLL COLLECT ALL WHERE (SPRE EQ /RF300/100G)

The referenced attributes that are indexed are:

To benefit from indexing you must use the 'FROM TABLE' syntax in collections. This syntax is similar the same as for system attributes.

For Text Userd Defined Attributes (UDAS):

VAR !COLL COLLECT ALL for /* FROM TABLE :MYTEXTATT VALUE 'fred'

will find all elements in current Database (DB) with :MYTEXTATT set to 'fred'

VAR !COLL COLLECT ALL for /* FROM TABLE :MYTEXTATT PREFIX 'fred'

will find all elements in current DB with :MYTEXTATT starting with 'fred'

For Integer UDAS:

VAR !COLL COLLECT ALL FROM TABLE :MYATT VALUE 100

This will find all elements with a :MYATT of 100

VAR !COLL COLLECT ALL FROM TABLE :MYATT VALUE 100 TO 110

This will find all elements where :MYATT is between 100 and 110.

For Ref Attributes:

VAR !COLL COLLECT ALL for /* FROM TABLE :MYREFATT VALUE /PIPE1

will find all elements in current DB with :MYREFATT set to /PIPE1

The new syntax may be combined with existing collection syntax. For example:

VAR !COLL COLLECT ALL for /* FROM TABLE :MYREFATT VALUE /PIPE1

Currently a collection can be restricted to a specific DB by navigating to a specific DB and setting the scope of /*. For example:

Q ALL … for /*

At 12.1 the DB name may be specified as part of the collection.

For example:

VAR !COLL COLLECT ALL BOX FOR DB CTBATEST/DESI

Or

VAR !COLL COLLECT ALL WHERE (SITE EQ /ATEST) FOR DB CTBATEST/DESI FROM TABLE SPRE VALUE /RF300/100G

Or

VAR !COLL COLLECT ALL FOR DB CTBATEST/DESI FROM TABLE NAME PREFIX '/B'