About collection attributes/properties

All collections used on a form have their own attributes that can, for the most part, be defined or altered using the Collections tab for the form in the Web Designer (web client) or in Design Mode (Windows client).

These tables list and describe the attributes/properties that can be used to define collections on forms and determine their capabilities and behaviors:

Table 1. Definition attributes/properties
Attribute name Description/Comments
Collection This property specifies the source of a collection of data for a form. The value of the property must be the name of an IDO.
Base Table and Alias This read-only field displays the name of the primary table and its alias for the IDO named in the Collection field.
Collection Name This property is a string name or literal value that identifies the collection in error messages and menu options. The name should be appropriate for the end user.
Custom Load Method Use this property when you want to specify an IDO method as an alternative for loading or manipulating data in the collection. This property should be specified only if the standard default method of loading the collection is inadequate. This specification is usually required only in very advanced applications.
Method Parameters

Use this property to specify any parameters that must be passed to a custom load method. Parameters may include literal values, properties, variables, or component values.

Read Mode Use this property to specify the isolation level for transactions when loading a collection. This setting overrides the default value for the Collection Read Mode as set on the Process Defaults form. The override applies only to the collection for which it is specified.

This property permits or prevents "dirty reads."

  • A setting of UNCOMMITTED implements dirty reads, in which no shared locks are issued and no exclusive locks are honored. It is possible to read uncommitted data; values can be changed and rows can appear or disappear in the collection before the end of the transaction. The setting corresponds to the Transact-SQL statement SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED.
  • A setting of COMMITTED specifies that shared locks are held while data is being read to avoid dirty reads, but the data can be changed before the end of the transaction. The setting corresponds to the Transact-SQL statement SET TRANSACTION ISOLATION LEVEL READ COMMITTED.

Other options for collections

Collection specifications can also be modified in other ways, including the way standard operations are handled, and how data in those collections are handled.

These tables list and describe the Options attributes/properties:

Table 2. Standard Operations attributes/properties
Attribute name Description/Comments
Navigate Use this property to specify whether the user can use shortcut keys or the Actions menu to navigate to the first, next, previous, and last rows of the collection.
  • True: Navigation is enabled.
  • False: Navigation is disabled.
Refresh Use this property to specify whether the user can requery the data in the collection.
Filter Use this property to specify whether the user can set filter criteria for data being queried in the collection.
New/Copy Use this property to specify whether the user can create new rows or copy rows in the collection.
Save Use this property to specify whether the user can save changes made to data in the collection.
Delete Use this property to specify whether the user can delete data from the collection.
Notes Use this property to specify whether the user can attach notes to rows in the collection.
Graph Use this property to specify whether the user can generate an ad hoc graph of the data in the collection.
Spreadsheet Disabled Use this property to specify whether the user can export the contents of the collection to a spreadsheet, such as Microsoft Excel (or any other application capable of reading CSV-formatted spreadsheets).

This property cannot be used for subcollections.

Table 3. Advanced Options attributes/properties
Attribute name Description/Comments
Record Cap Override/Page Size Use this property to specify a maximum record cap for list sources of type IDO Collection and IDO Method, collections and subcollections, and tree definitions. This number cannot exceed the WinStudio Max Record Cap setting, if one is specified on the Process Defaults form.

If no other value is specified, this field defaults to a value of 200.

Enable Paging Use this property to enable pagination of records displayed for a primary collection or a subcollection.

When this property is set to True, you must specify the number of records to be displayed per page in the Record Cap Override/Page Size property field.

Operate As Primary Use this property to designate a collection other than the primary collection to be associated with unbound or variable-bound components that are normally associated with the form's primary collection. This would typically be set to True only for secondary collections or subcollections.

For instance, variable-bound components are re-initialized when the user inserts a new row into the primary collection. This property allows you to designate another collection, perhaps a secondary collection, to be associated with these components.

Reload After Save Use this property to determine whether the collection is to be refreshed after each save operation.
Reload After Child Save Use this property to specify whether the parent collection is to be refreshed after a child subcollection is saved.
Defer Refresh Until Visible Use this property to specify whether a collection or subcollection is to be populated before it becomes visible to the user.

Deferral is especially useful in cases where subcollections or secondary collections are displayed on notebook tabs. If this property is set to True, the collection is not queried until the user selects the tab that contains it.

Save One Row Per Transaction Use this property to specify whether to save each modified row in a separate transaction.

For more detailed information, see Save One Row Per Transaction property.

The property applies only to primary and secondary collections.

Load/Save Overrides Use this property to specify custom procedures for update, insert, delete, and post-query processing.

To specify which type of operation is to be handled by custom processing in the IDO instead of by a standard operation on the collection, click the ellipsis (•••) button, which opens the Edit Middleware Load/Update Overrides dialog box.

Update Locking Use this property to select which column-locking option is to be used during an IDO item update.

For more detailed information, see Update Locking property.

Table 4. Collection Selection attributes/properties
Attribute name Description/Comments
Permanent Filter Expression Use this property to specify a permanent filter to be applied to the collection for a form. Ad hoc filter specifications set by a filter form or Filter-In-Place are added to this filter when querying the collection.

A Permanent Filter Expression value is a SQL WHERE clause without "WHERE" (for example, username <> 'service').

Note: Use the Edit Permanent Filter dialog box to create or edit permanent filter expressions. This dialog box opens when you click the ellipsis (•••) button next to the field.

Expressions can reference the values of components, variables, or properties on other collections, by means of substitution keywords, etc. These use Boolean AND filtering with any end-user filtering or security rules for row-level filtering.

Optional Filters Use the Optional Filters property to specify optional filters to be applied when querying IDO collections.

These filters are applied to the IDO query only when there is a value supplied here. Optional filters are excluded from the query when this field value is blank.

Optional filters are stored in the data source as in this example:

FILTEROPTS(FILTEROPT(…),FILTEROPT(…))
FILTEROPT(PROP(…)OPER(…)EOD())
Note: Use the Edit Optional Filters dialog box to create or edit optional filters. This dialog box opens when you click the ellipsis (•••) button next to the field.
Distinct Use this property to remove duplicate records from returned data.

As with other properties, this attribute effects the SQL code that the IDO Runtime service generates for IDO LoadCollection actions.

Caution: 
If you remove duplicates, the data cannot be reliably updated. This option should only be used with read-only data.
Order By Use this property to specify IDO properties by which a collection is sorted.

An Order By setting is a comma-delimited list of IDO property names. The default order is ascending. You can specify the order of any of the properties by adding either desc (descending) or asc (ascending) after the property name.

Expressions can reference the values of components, variables, or properties on other collections, by means of substitution keywords, etc. These use Boolean AND filtering with any end-user filtering or security rules for row-level filtering.