Data Collection Methods

A data collection is the collection of data, available at runtime or during test mode, associated with a particular scroll (or record.) The data collection object returns information about every row of data (item) that is returned for that record at runtime.

To access a data collection, use the name of the record (scroll) as a property on a Component Interface.

Syntax

CurrentItem()

Description

If the component associated with the Component Interface is effective-dated, CurrentItem returns a reference to the current effective-dated item (row of data). To get a specific item based on a date, use GetEffectiveItem.

If there is no current item, a Null is returned.

Example

&MYCD = &MYCI.EMPL_CHKLST_ITM;
&ITEM = &MYDC.CurrentItem();

Syntax

DeleteItem(number)

Description

The DeleteItem method deletes the item (row of data) at the position specified by number. This parameter takes a number value.

When the DeleteItem method is executed, if there are any RowDelete PeopleCode programs associated with any of the fields, they fire as well, as if the user pressed ALT+8 and ENTER or clicked the DeleteRow icon. However, the programs are executed as if turbo mode was selected. (In turbo mode default processing is performed only for the row being deleted.)

If you set the InteractiveMode property to True, any RowDelete PeopleCode runs immediately after you execute DeleteItem. If this property is set to False, any RowDelete PeopleCode runs after you execute the Save method.

The deleted item is not actually deleted from the database until after you use the Save method.

Example

Image: EMPL_CHK_BC in Component Interface Tester

Here is an example of EMPL_CHK_BC in Component Interface Tester where in , suppose your Component Interface had two scrolls: EMPL_CHECKLIST and EMPL_CHKLST_ITM. The data collection EMPL_CHECKLIST has four items (rows of data.) The data collection EMPL_CHKLST_ITM (under the third item) has five items (rows of data.) If you run this component in the Component Interface Tester, it would look as follows:

EMPL_CHK_BC in Component Interface Tester

To delete the third row in the third item, use the following:

Local ApiObject &MYSESSION;
Local ApiObject &MYCI;

&MYSESSION = %Session;
&MYCI = &MYSESSION.GetCompIntfc(COMPINTFC.EMPL_CHK_BC);
&MYLVL1 = &MYCI.EMPL_CHECKLIST;
&ITEM2 = &MYLVL1.Item(3);
&MYLVL2 = &ITEM2.EMPL_CHKLST_ITM;
&MYLVL2.DeleteItem(3);
&MYCI.Save();

Syntax

GetEffectiveItem(DateString, SeqNo)

Description

If the component associated with the Component Interface is effective-dated, GetEffectiveItem returns a reference to the closest effective-dated item (row of data) that is less than or equal to the date specified by the DateString. To get an item based on the current effective date, use CurrentItem.

Note: DateString takes only a string value. You must convert a date variable into a string before you can use it for DateString. You can use the String function to do this.

Parameters

Field or Control

Definition
DateString

Specify the year, month, and day of the effective date that you want to look for. This parameter takes a string value. You can specify the date either as YYYY-MM-DD orMM/DD/YY.
SeqNo

Specify the sequence number of the effective date that you want to look for. This parameter takes a number value.

Returns

A reference to an effective-dated item.

Example

&MYCD = &MYCI.EMPL_CHKLST_ITM;
&DSTRING = String(&MYDATE);
&ITEM = &MYDC.GetEffectiveItem(&DSTRING, 1);

Syntax

GetEffectiveItemNum(DateString, SeqNo)

Description

If the component associated with the Component Interface is effective-dated, GetEffectiveItemNum returns a reference to the number of the closest effective-dated item (row of data) that is less than or equal to the date specified by the DateString. To get an item number based on the current effective date, use CurrentItemNum.

Note: DateString takes only a string value. You must convert a date variable into a string before you can use it for DateString. You can use the String function to do this.

Considerations for Returning Rows

GetEffectiveItemNum returns a valid row number only when EFFDT is less than or equal to DateString. If the value you use for DateString pre-dates all the rows in the data collection, this method returns a zero and logs a message in the PSMessages collection.

For example, if 12/01/1990 was the earliest date in the collection, the following would return zero:

&NUM = &MYDC.GetEffectiveItemNum("01/01/1900", 1);

Parameters

Field or Control

Definition
DateString

Specify the year, month, and day of the effective date that you want to look for. This parameter takes a string value. You can specify the date either as YYYY-MM-DD orMM/DD/YYYY.
SeqNo

Specify the sequence number of the effective date that you want to look for. This parameter takes a number value.

Returns

A number. This method returns 0 if no row matching the criteria is found.

Example

&MYCD = &MYCI.EMPL_CHKLST_ITM;
&DSTRING = String(&MYDATE);
&ITEMNUM = &MYDC.GetEffectiveItemNum(&DSTRING, 1);

Syntax

InsertItem(number)

Description

The InsertItem method inserts the item (row of data) at the position specified by number. This parameter takes a number value. You can insert items below only the zero level scroll. If you need to add a new data item, use the Create method instead.

InsertItem adds the new row after the current row. If the row has an effective date (EFFDT) or an effective sequence (EFFSEQ), these values are copied into the new row.

If a collection has n items and you specify n as the value for number, InsertItem inserts a new item (row) after the last row.

The InsertItem method returns a reference to the newly created item (row of data).

When the InsertItem method is executed, if there are any RowInsert PeopleCode programs associated with any of the fields, they fire also, as if the user pressed ALT+7 and ENTER or clicked the InsertRow icon. However, the programs are executed as if turbo mode was selected. (In turbo mode default processing is performed only for the row being inserted.)

If you set the InteractiveMode property to True, any RowInsert PeopleCode runs immediately after you execute InsertItem. If this property is set to False, any RowInsert PeopleCode runs after you execute the Save method.

The inserted item is not added to the database until after you use the Save method.

Example

In the following example a new item (row of data) is added at the end of the current collection.

&MYDC = &MYCI.EMPL_CHECKLIST;
&COUNT = &MYDC.Count;
&ITEM = &MYDC.InsertItem(&COUNT);
&ITEM.CHECKLIST_CD = "00001";
&ITEM.RESPONSIBLE_ID = "6609";
&RSLT = &MYCI.Save();

Syntax

Item(number)

Description

The Item returns the item (row of data) that exists at the number position in the data collection executing the method. The parameter takes a number value.

Syntax

ItemByKeys(­key_values)

Description

The ItemByKeys method returns the item specified by the parameters. The number and type of keys are unique to each specific collection. Each key must be separated by a comma.

The collection reference must be the name of the Component Interface, followed by the record name. This method won’t work on a collection reference (that is, &CI.RECNAME.ItemByKeys, not &MYCOLLECTION.ItemByKeys).

After you’ve returned an item, use the ItemNum property to determine the number of the item.

The keys must be in the exact order as in the Component Interface. A second level data collection also contains the keys of the parent data collection.

An easy way to determine the keys and their order in PeopleCode is to open the Component Interface in Application Designer, and use the Test Component. To determine the keys in Visual Basic, use the Object Browser.

See ItemNum.

To see the signature for ItemByKeys:

  1. Open the Component Interface in Application Designer.

  2. Start the Component Interface Tester.

    Select the open Component Interface, then right-click, and select Test Component Interface from the pop-up menu.

  3. Instantiate an object.

    Add data to the Get or Create keys and click Get Existing or Create New, respectively.

  4. Expand the instantiated component until you find the collection in which you’re interested.

  5. Right-click on the collection and select ItemByKeys from the resulting pop-up menu.

  6. The dialog that follows shows you the specific parameters, types, and order in which you should call ItemByKeys.

Returns

An item (row) of data from a data collection.

Example

Local ApiObject &MYSESSION;
Local ApiObject &CI;
Local ApiObject &CI_COLLECTION;
Local ApiObject &CI_ITEM;

&MYSESSION = %Session;
&CI = &MYSESSION.GetCompIntfc(COMPINTFC.CM_EVAL);
&CI.EMPLID = "8001";
If &CI.Get() <> 1 Then
   Exit;
End-If;

&CI_COLLECTION = &CI.CM_EVALUATIONS;
&COUNT = &CI_COLLECTION.Count;

&CI_ITEM = &CI.CM_EVALUATIONS.itembykeys("01");
&CI_ITEM.DESCR50 = "TEST";
If &CI.Save() <> 1 Then
   Exit;
End-If;