Specifying the POPSPEC Parameter

For a given property in a class that extends %PopulateOpens in a new tab, you can customize how the Populate() method generates data for that property. To do so, do the following:

Find or create a method that returns a random, but suitable value for this property.
The %PopulateUtilsOpens in a new tab class provides a large set of such methods; see the Class Reference for details.
Specify the POPSPEC parameter for this property to refer to this method. The first subsection gives the details.

The POPSPEC parameter provides additional options for list and array properties, discussed in later subsections.

For a literal, non-collection property, another technique is to identify an SQL table column that contains values to use for this property; then specify the POPSPEC parameter to refer to this property; see the last subsection.

Note:

There is also a POPSPEC parameter defined at the class level that controls data population for an entire class. This is an older mechanism (included for compatibility) that is replaced by the property-specific POPSPEC parameter. This topic does not discuss it further.

Specifying the POPSPEC Parameter for Non-Collection Properties

For a literal property that is not a collection, use one of the following variations:

POPSPEC="MethodName()" — In this case, Populate() invokes the class method MethodName*( of the %PopulateUtilsOpens in a new tab class.
POPSPEC=".MethodName()" — In this case, Populate() invokes the instance method MethodName() of the instance that is being generated.
POPSPEC="##class(ClassName).MethodName()" — In this case, Populate() invokes the class method MethodName() of the ClassName class.

For example:

Property HomeCity As %String(POPSPEC = "City()");

If you need to pass a string value as an argument to the given method, double the starting and closing quotation marks around that string. For example:

Property PName As %String(POPSPEC = "Name(""F"")");

Also, you can append a string to the value returned by the specified method. For example:

Property JrName As %String(POPSPEC = "Name()_"" jr."" ");

Notice that it is necessary to double the starting and closing quotation marks around that string. It is not possible to prepend a string, because the POPSPEC is assumed to start with a method.

Also see Specifying the POPSPEC Parameter via an SQL Table for a different approach.

Specifying the POPSPEC Parameter for List Properties

For a property that is a list of literals or objects, you can use the following variation:

POPSPEC="basicspec:MaxNo"

Where

basicspec is one of the basic variations shown in the preceding section. Leave basicspec empty if the property is a list of objects.
MaxNo is the maximum number of items in the list; the default is 10.

For example:

Property MyListProp As list Of %String(POPSPEC = ".MyInstanceMethod():15");

You can omit basicspec. For example:

Property Names As list of Name(POPSPEC=":3");

In the following examples, there are lists of several types of data. Colors is a list of strings, Kids is a list of references to persistent objects, and Addresses is a list of embedded objects:

Property Colors As list of %String(POPSPEC="ValueList("",Red,Green,Blue"")");

Property Kids As list of Person(POPSPEC=":5");

Property Addresses As list of Address(POPSPEC=":3");

To generate data for the Colors property, the Populate() method calls the ValueList() method of the PopulateUtils class. Notice that this example passes a comma-separated list as an argument to this method. For the Kids property, there is no specified method, which results in automatically generated references. For the Addresses property, the serial Address class inherits from %PopulateOpens in a new tab and data is automatically populated for instances of the class.

Specifying the POPSPEC Parameter for Array Properties

For a property that is an array of literals or objects, you can use the following variation:

POPSPEC="basicspec:MaxNo:KeySpecMethod"

Where:

basicspec is one of the basic variations shown earlier. Leave basicspec empty if the property is a array of objects.
MaxNo is the maximum number of items in the array. The default is 10.
KeySpecMethod is the specification of the method that generates values to use for the keys of the array. The default is String(), which means that InterSystems IRIS invokes the String() method of %PopulateUtilsOpens in a new tab.

The following examples show arrays of several types of data and different kinds of keys:

Property Tix As array of %Integer(POPSPEC="Integer():20:Date()");

Property Reviews As array of Review(POPSPEC=":3:Date()");

Property Actors As array of Actor(POPSPEC=":15:Name()");

The Tix property has its data generated using the Integer() method of the PopulateUtils class; its keys are generated using the Date() method of the PopulateUtils class. The Reviews property has no specified method, which results in automatically generated references, and has its keys also generated using the Date() method. The Actors property has no specified method, which results in automatically generated references, and has its keys generated using the Name() method of the PopulateUtils class.

Specifying the POPSPEC Parameter via an SQL Table

For POPSPEC, rather than specifying a method that returns a random value, you can specify an SQL table name and an SQL column name to use. If you do so, then the Populate() method constructs a dynamic query to return the distinct column values from that column of that table. For this variation of POPSPEC, use the following syntax:

POPSPEC=":MaxNo:KeySpecMethod:SampleCount:Schema_Table:ColumnName"

Where:

MaxNo and KeySpecMethod are optional and apply only to collection properties (see earlier the subsections on lists and arrays).
SampleCount is the number of distinct values to retrieve from the given column, to use as a starting point. If this is larger than the number of existing distinct values in that column, then all values are possibly used.
Schema_Table is the name of the table.
ColumnName is the name of the column.

For example:

Property P1 As %String(POPSPEC=":::100:Wasabi_Data.Outlet:Phone");

In this example, the property P1 receives a random value from a list of 100 phone numbers retrieved from the Wasabi_Data.Outlet table.

Basing One Generated Property on Another

Default Behavior