You can use this legacy pattern to retrieve only the database objects that match a value on the current ViewModel object, then expose the returned collection in a grid; use it when maintaining an existing ViewModel that calls selfVM.ExecutePS.

Note: selfVM.ExecutePS is replaced for new development by <Class>.PSEval, which is available in the context of every class. Keep this page as a reference for existing solutions. For the operator definition and current guidance, see Documentation:OCLOperators ExecutePS.

When to use this pattern

Use a persistent-search expression when the candidate set is large and you need a small matching subset. For example, if the database contains one million Thing objects, and you need the objects whose Attribute1 value matches the selected Thing, do not load every Thing into the ViewModel and filter it there.

ExecutePS evaluates its configured expression through the persistence service. The expression is translated for database execution and the result collection is returned to the ViewModel. This makes the pattern appropriate for checks such as finding other objects with the same value, or preparing a filtered collection for a grid.

Use ordinary ViewModel fetching when the relevant objects are already available or when you need to optimize how related data is fetched. See Documentation:Efficient ViewModel fetch. Use PSExpression_Refresh when you need database-computed scalar values such as a count, sum, minimum, or maximum rather than a collection of objects.

Example goal

Assume a model class named Thing with an attribute named Attribute1. The ViewModel starts with one Thing as its root object.

When the user runs the action, the ViewModel must:

1. Copy the root Thing.Attribute1 value to vValueToMatch.
2. Evaluate a persistence-search expression that finds Thing objects with that value.
3. Store the returned collection in vMyList.
4. Use vMyList as the root for a grid.

For example, if the root Thing has Attribute1 = 'Blue', the result list contains the Thing objects found in the database whose Attribute1 is also 'Blue'.

ViewModel structure

Create or verify the following ViewModel elements. The names below follow the legacy example and make the roles clear.

Element	Purpose	Example
Root Thing	Supplies the value to match.	The currently displayed Thing has Attribute1 = 'Blue'.
vValueToMatch	ViewModel variable that holds the root value while the search is evaluated.	'Blue'
OutOfLoopToAvoidStdFetch	ViewModel area containing the persistence-search column. Keep this column out of the UI so the expression is not evaluated as normal ViewModel fetching.	Contains col1.
OutOfLoopToAvoidStdFetch.col1	The column whose expression returns the matching Thing objects through the persistence service.	Returns the Thing objects whose Attribute1 equals vValueToMatch.
vMyList	ViewModel list variable that receives the collection returned by ExecutePS.	The matching Thing objects.
Grid rooted at vMyList	Displays the result to the user.	A grid with columns for Attribute1 and other relevant Thing data.

Configure the persistence-search column

1. Add the non-UI ViewModel area named OutOfLoopToAvoidStdFetch.
2. Add the column col1 beneath it.
3. Define col1 so that it returns the collection of Thing objects with an Attribute1 value equal to vValueToMatch.
4. Do not bind this column to a visible control. Its purpose is to hold the expression that ExecutePS evaluates.

The expression must return objects of the type that the result list expects. In this example, it returns Thing objects, so vMyList must be a list that can hold Thing objects.

Add the action

Add an EAL action to the ViewModel. The action first captures the value from the current root object, then calls ExecutePS for the ViewModel column that contains the persistence-search expression, and finally stores the returned collection in vMyList.

The legacy operator takes the ViewModel class and ViewModel column that identify the expression to execute. In this example, those identify OutOfLoopToAvoidStdFetch.col1.

The action sequence is:

1. Assign vValueToMatch from the root Thing.Attribute1.
2. Call selfVM.ExecutePS for OutOfLoopToAvoidStdFetch.col1.
3. Assign or collect the returned Thing objects into vMyList.

A conceptual action flow is:

vValueToMatch := <current Thing>.Attribute1;
vMyList := selfVM.ExecutePS(<ViewModel class>, <OutOfLoopToAvoidStdFetch.col1>)

Replace the placeholders with the names in your ViewModel. The important part is the ordering: set vValueToMatch before evaluating the persistence-search column, because that column uses the variable as its match value.

Display the result

Use vMyList as the root of a grid in the UI. When the action completes, the grid shows the returned Thing objects.

For the 'Blue' example, the grid should contain only Thing objects returned by the database search for Attribute1 = 'Blue'. It should not require all Thing objects to be loaded first.

Limit result size

ExecutePS checks for a MaxFetch tagged value on the root-level column and limits the returned values accordingly. Set an appropriate limit for any result that can grow large.

A uniqueness check is a common case: you usually need only enough matches to determine whether another object has the same value. Do not configure an unbounded result list when the matching value can occur on many objects.

Important considerations

• This is a legacy selfVM.ExecutePS pattern. For new work, use <Class>.PSEval instead.
• Keep the persistence-search expression in its dedicated, non-UI column. The column exists to be evaluated by ExecutePS, not to drive normal ViewModel fetching.
• Ensure that the expression result type and vMyList element type match. This example expects a collection of Thing objects.
• The returned list is a subset selected by the database expression. It is not a replacement for configuring ordinary related-object fetching where that is what the UI needs.
• Use PSExpression_Refresh for database-calculated fields such as totals and counts. It discovers columns named with the PSExpression_ prefix and refreshes their scalar results.

See also

• Documentation:OCLOperators ExecutePS
• Documentation:SelfVM
• Documentation:PSExpression , or how to do things in the DB from MDriven
• Documentation:Efficient ViewModel fetch
• Documentation:EAL