The basics in working with CIs and CI collections

Below are some of the basics in working with CIs.

A. The basic steps in working with CIs

1) Set the get or create keys (set key values)

2) Execute get() or create()

If get() or create() returns False

do some error handling and take appropriate action such as not trying to continue processing that record. If you're going to continue processing, you'll need to call PSMessages collection's DeleteAll() method to reset the ErrorPending flag to False.

Else

Continue on to #3

3) set the properties

4) Execute save()

5) Execute cancel() - This releases this instance (or record that you were working with) so that you can set the get or create keys for the next record/CI instance. This step is not necessary if your code goes out of scope.

6) If you're accessing the CIs from PeopleCode:

(a) Use the following syntax to get a handle to the Session object.

&MySession = %Session;

Avoid using the following syntax.

&MySession = GetSession();

If( &MySession.Connect(1, "EXISTING", "", "", 0)) Then

....

(b) If using a looping construct, ensure that you don't get a handle to the Session object multiple times if using the GetSession()... syntax as it will create a new session each time, and you can end up with undesired behavior.

B. Inserting into CI collections -

1) You need to get a handle to the collection (see sample code snippet below)

&mycollection = &CI.mycollection;

2) If it is a new collection (collection in which there are no rows in the database) then a "dummy row" (that doesn't exist in the database) is made available for you to edit and set the values. You access this row as follows.

Note: The index value depends on the language being used. For zero-based languages like Java use 0, and for one-based languages like PeopleCode use 1.

&mycollectionItem = &mycollection.Item(1);

&mycollectionItem.propA = "PropA";
............

3) If the collection already has one or more items in it and you want to add additional items into it, you use InsertItem(index), where index is the numeric index for the position after which you want to insert this row for non-effective dated records, and before which you want to insert this row for effective-dated records. Make sure that you don't supply an incorrect index (for example, if you have one row in the database, do not supply an index of 2 for it or you may get an error. A safe index to supply is 1 (for one-based languages like PeopleCode and 0 for zero-based languages like Java).

&mycollectionItem = &mycollection.InsertItem(1);

&mycollectionItem.propA = "PropA";

....
C. Inserting into CI collections - More detailed example


1. If you know there are 1 or more rows in the DB (database) for a collection (let's say L1 (level 1)), then you would use InertItem(...) to insert new rows. Also, if the L1 collection has a child L2 collection and you used InsertItem(...) to insert a new L1 row, you would use Item(1) to access the Dummy row at L2. If you want to insert more than one L2 row, then you would use InsertItem(...) for subsequent rows. So, suppose you know that there is one or more rows in the DB at L1, here's a simple example of what the code may look like to insert one new L1 row and two new L2 rows

&myL1collection = &CI.myL1collection;

&myL1collectionItem = &myL1collection.InsertItem(1);

&myL1collectionItem.propA = "PropA";

...
&myL2collection = &myL1collectionItem.myL2Collection;

For &i = 1 To 3

/**NOTE I'm using very simple logic to determine whether to use Item or InsertItem. The logic in your application may be different and more complex**/

If &i = 1 Then
&myL2collectionItem = &myL2collection.Item(1);
Else
&myL2collectionItem = &myL2collection.InsertItem(1);
End-If;
&myL2collectionItem.prop1 = "prop"
&i;
...
End-For;

2. If there are no rows in the DB for the L1 collection, then
- you access the Dummy row at L1 using Item(1)

- you know that since there are 0 rows in the DB at L1, the L1 row's (that you access using Item) L2 child will not have any rows in the DB, so you'll access the Dummy row using Item(1) to insert the first row. If you want to insert more than one L2 row, then you would use InsertItem(...) for subsequent rows. Suppose you know that there are NO rows in the DB at L1. Here's a simple example of what the code may look like to insert one new L1 row and two new L2 rows

&myL1collection = &CI.myL1collection;
&myL1collectionItem = &myL1collection.Item(1);
&myL1collectionItem.propA = "PropA";
...
&myL2collection = &myL1collectionItem.myL2Collection;
For &i = 1 To 3

/**NOTE I'm using very simple logic to determine whether to use Item or InsertItem. The logic in your application may be different and more complex**/
If &i = 1 Then
&myL2collectionItem = &myL2collection.Item(1);
Else
&myL2collectionItem = &myL2collection.InsertItem(1);
End-If;
&myL2collectionItem.prop1 = "prop"
&i;
End-For;

3. If the collection already has one or more items in it and you want to add additional items into it, you use InsertItem(index), where index is the numeric index is the position after which you want to insert this row for non-effective dated records, and before which you want to insert this row for effective-dated records. Make sure you don't supply an incorrect index (for example, if you have one row in the database, do not supply an index of 2 for it or you may get an error.

&mycollectionItem = &mycollection.InsertItem(1);
&mycollectionItem.propA = "PropA";