contents.gifindex.gifprev1.gifnext1.gif

Collection_Create

Purpose

Creates a new collection from another collection. Returns the specified collection.

Arguments

Collection_Create(

<loc>
// Collection Location, e.g. an MDB.
, <schema>
// Collection name, e.g table name within MDB.
, <sel expr>
// A quoted string. See Notes.
, <attribute_list>
// Quoted, bracketed list of attributes. See Notes.
)

Notes

The null first argument implies the use of the current location (MDB).

<table name> parameter has been modified so that either a “Table_Name” “Table_Name:Index_Name” can be used. “Index_Name” is optional. If it is not given (as has been true to this point), then “PrimaryKey” is assumed. In addition, this function can be passed fewer keys in the <row select> parameter than are contained in the index being used. If fewer keys are provided, then a Find_First where the provided keys are equal is performed. For example, the first two keys of a three key index could be used. For Collection_Create (and Driver), the resulting collection will be populated based on all records which match the supplied keys (as was previously the case).

This function can limit its search one of several ways, keeping in mind that “Lookup” routines find a single record (the first match), while “Collection” routines find all which match the request:

1. A simple value . . . which implies a single key search.

2. A list of values, such as “[v1] [v2] [v3]” which implies a multi-key search even though the index may have more keys.

3. An SQL where clause using SELF! [ ] references.

4. A list of values (as in option 2) followed by “ AND “ then an SQL where clause. For example: “[v1] [v2] AND SELF![MyFld] = ‘v3’”

Example

Collection_Create(
''

, 'FB_LN'

, 'SELF![CAT]="FREIGHT"'

, '[LINE_ITEM_NUM][CMDTY_CLASS][CHRG_DESC]

[Quantity:CLng(ConvertNulls(SELF![QTY_LABL],0))]

[RATE_AMT][RATE_PER_UNT_CNT][RATE_UNT_LABL][CHRG_AMT]'

)

The null first argument here implies the use of the current .MDB. The table name in this MDB is "FB_LN".

The third argument selects the elements in the source collection ("SELF") for which the attribute "CAT" has the value "FREIGHT". SELF! refers to the collection we are creating from.

The fourth argument is a bracketed list of attributes for the new collection. Eight attributes are specified in this example. The fourth item in the attribute list is:

[Quantity:CLng(ConvertNulls(SELF![QTY_LABL],0))]

This item means that in the new collection, the attribute Quantity is given the value of the expression CLng(ConvertNulls(SELF![QTY_LABL],0)).