Component Interface Class Methods

This section discusses the Component Interface class methods. The methods are discussed in alphabetical order.

Syntax

Cancel()

Description

The Cancel method cancels the instance of the Component Interface object executing the method, rolling back any changes that were made. This sets the Component Interface state to the same state it was in immediately after it was created by GetCompIntfc. This closes the Component Interface.

Parameters

None.

Returns

A Boolean value: True if component was successfully cancelled, False otherwise.

Syntax

CopyRowset(&Rowset [, InitialRow] [, record_list]);

Where record_list is a list of record names in the form:

[RECORD.source_recname1, RECORD.target_recname1 
[, RECORD.source_recname2, RECORD.target_recname2]].  .  .

Description

The CopyRowset method copies the specified rowset object to the Component Interface executing the method, copying like-named record fields and data collections (child rowsets) at corresponding levels. If pairs of source and destination record names are given, these are used to pair up the records and data collections before checking for like-named record fields.

CopyRowset uses the Page Field order when copying properties. This helps ensure that dependent fields are set in the required order.

Note: This method works in PeopleCode only. This method uses the names of the records in the collection, not the name you may give the collection when you create the Component Interface.

If there are blanks in source rowset or record, they are copied over to the Component Interface only if the field’s IsChanged property is set to True. Otherwise blanks are not copied.

Use this method when you are using a Component Interface to verify the data in your application message.

Note: The structure of the rowset you’re copying data from must exactly match the existing rowset structure, with the same records at level zero, 1, 2, and so on. CopyRowset is intended to be used with a notification process, that is, with message data. As all notifications work only in two-tier mode, CopyRowset works only in two-tier mode.

Parameters

Field or Control	Definition
`&Rowset`	Specify an existing, instantiated rowset object that contains data.
`InitialRow`	Specify the initial transaction row to begin with. This parameter provides a quick way to loop through a rowset that has multiple level zero rows. The default value for this parameter is 1.
`record_list`	Specify a list of source and target record names. All `source_recnames` are records being copied from, in the rowset object being copied from. All `target_recnames` are records being copied to, in the Component Interface being copied to.

Returns

None.

Example

The following example would be in your notification PeopleCode. The Exit(1) causes all changes to be rolled back, and the message is marked with the status ERROR so you can correct it.

Local message &MSG;
Local ApiObject &SESSION;
Local ApiObject &PO;
Local rowset &ROWSET;

&MSG = %IntBroker.GetMessage();
&ROWSET = &MSG.GetRowset();

&SESSION = %Session;

If &SESSION <> NULL Then
/* Session connected correctly */
/* Set key values to create component */
&PO = &SESSION.GetCompIntfc(COMPINTFC.PO);
&PO.BU = &MSG(&I).PO_HDR.BU.Value;
&PO.PO_ID = &MSG(&I).PO_HDR.PO_ID.Value;
&PO.Create();

&PO.CopyRowset(&ROWSET);
If NOT (&PO.Save()) Then
   Exit(1);
End-if;
Else
/* do error processing */
End-If;

The following example loops through all the transactions of a message rowset.

Local message &MSG;
Local ApiObject &SESSION;
Local ApiObject &CI;
Local rowset &ROWSET;

&MSG = %IntBroker.GetMessage();
&ROWSET = &MSG.GetRowset();


&SESSION = %Session;
If &SESSION <> Null Then)  
   &CI = &SESSION.GetCompIntfc(CompIntfc.VOL_ORG);
   &I = 0;
   While (&I < &ROWSET.RowCount)
      &I = &I + 1;
      &CI.VOLUNTEER_ORG = &ROWSET.GetRow(&I).VOLNTER_ORG_2.  VOLUNTEER_ORG.Value;
      If &CI.Create() Then
         If &CI.CopyRowset(&ROWSET, &I, Record.VOLNTER_ORG_TBL, Record.VOLNTER_ORG_TBL) Then
         
         /* App specific processing */

            If Not &CI.Save() Then
               Winmessage("Save Failed");
               /* Other app specific processing */
            End-If;
         End-If;
      End-If;
   &CI.Cancel();
   End-While;
End-If;

Syntax

CopyRowsetDelta(&Rowset [, InitialRow] [, record_list]);

Where record_list is a list of record names in the form:

[RECORD.source_recname1, RECORD.target_recname1 
[, RECORD.source_recname2, RECORD.target_recname2]].  .  .

Description

The CopyRowsetDelta method copies the changed rows in the specified rowset object to the Component Interface executing the method, copying like-named record fields and data collections (child rowsets) at corresponding levels. If pairs of source and destination record names are given, these are used to pair up the records and data collections before checking for like-named record fields.

Note: This method works in PeopleCode only. This method uses the names of the records in the collection, not the name you give the collection when you create the Component Interface.

If there are blanks in source rowset or record, they are copied over to the Component Interface only if the field’s IsChanged property is set to True. Otherwise blanks are notcopied.

You will generally use this method with a Component Interface to verify data from a message.

Note: CopyRowsetDelta is intended for a notification process, that is, with message data. As all notifications work only in two-tier mode, CopyRowsetDelta works only in two-tier mode.

If the rowset you’re copying from is a message rowset, the CopyRowsetDelta method uses the AUDIT_ACTN field in the PSCAMA table in the message to know whether the row is to be inserted, updated, or deleted inside the Component Interface.

If the rowset you’re copying from is not a message rowset, that rowset must have the same structure as a message, that is, it must have a PSCAMA record with an AUDIT_ACTN field on every level of the rowset.

Warning! CopyRowsetDelta uses a record's keys to locate the target row to change for all audit actions other than Add. CopyRowsetDelta actions (other than Add) therefore work only on rowsets that have keys that uniquely identify all rows in the rowset. Rowsets that do notdistinguish between rows using a key field will be updated in an unpredictable fashion.

Considerations Using CopyRowsetDelta with Effective-Dated Rowsets

If a message data row inserted using a PSCAMA Audit action of "A" belongs to an effective dated scroll containing child scrolls, the insertion of the parent row causes child rows of the previous effective-dated row to be copied over, and their effective date is updated with that of the inserted parent.

If the message also contains a child row being inserted with a PSCAMA Audit action of "A", the component interface being populated will end up having two child rows: the one inserted as part of the Effective-dated processing and the one inserted using the PSCAMA Audit action "A" in the message.

Parameters

Field or Control	Definition
`&Rowset`	Specify an existing, instantiated rowset object that contains data.
`InitialRow`	Specify the initial transaction row to begin with. This parameter provides a quick way to loop through a rowset that has multiple level zero rows. The default value for this parameter is 1.
`record_list`	Specify a list of source and target record names. All `source_recnames` are records being copied from, in the rowset object being copied from. All `target_recnames` are records being copied to, in the Component Interface being copied to.

Returns

None.

Example

The following PeopleCode would exist in your notification process. The Exit(1) causes all changes to be rolled back, and the message is marked with the status ERROR so you can correct it.

Local Message &MSG;
Local ApiObject &SESSION;
Local ApiObject &PO;
Local Rowset &ROWSET;

&MSG = %IntBroker.GetMessage();
&ROWSET = &MSG.GetRowset();

&SESSION = %Session;

If &SESSION <> Null Then
/* Session connected correctly */
/* Set key values to get component */
&PO = &SESSION.GetCompIntfc(COMPINTFC.PO);
&PO.BU = &MSG(&I).PO_HDR.BU.Value;
&PO.PO_ID = &MSG(&I).PO_HDR.PO_ID.Value;
&PO.Get();

   
&PO.CopyRowsetDelta(&ROWSET);
If NOT (&PO.Save()) Then
   Exit(1);
End-if;
Else
   /* do error processing */
End-If;

Syntax

CopySetupRowset(&Rowset [, InitialRow] [, record_list]);

Where record_list is a list of record names in the form:

RECORD.source_recname, RECORD.target_recname

Description

The CopySetupRowset method is used to copy a setup table application message to a Component Interface. A setup table has the same record at level zero and level one, while a Component Interface has only a single copy of a record. This method copies the contents of the message (at level zero) to the first level collection (level one) of the Component Interface.

The CopySetupRowset method copies like-named record fields. If a pair of source and destination record names are given, these are used to pair up the records and data collections before checking for like-named record fields.

Note: This method works in PeopleCode only. This method uses the names of the records in the collection, not the name you may give the collection when you create the Component Interface.

If there are blanks in source rowset or record, they are copied over to the Component Interface only if the field’s IsChanged property is set to True. Otherwise blanks are not copied.

Note: CopySetupRowset is for a notification process, that is, with message data. As all notifications work only in two-tier mode, CopySetupRowset works only in two-tier mode.

Parameters

Field or Control	Definition
`&Rowset`	Specify an existing, instantiated rowset object that contains data.
`InitialRow`	Specify the initial transaction row to begin with. This parameter provides a quick way to loop through a rowset that has multiple level zero rows. The default value for this parameter is 1.
`record_list`	Specify source and target record names. The `source_recname` is the record being copied from, in the rowset object being copied from. The `target_recname` is the record being copied to, in the Component Interface being copied to.

Returns

None.

Example

The following example would be in your Notification PeopleCode.

Local ApiObject &SESSION;
Local ApiObject &PSMESSAGES;

Local ApiObject &CI;

Local Message &MSG;
Local Rowset &RS;

&SESSION = %Session;
&PSMESSAGES = &SESSION.psmessages;

&MSG = %IntBroker.GetMessage();
&RS = &MSG.GetRowset();

&CI = &SESSION.getcomponent(Component.VOL);

/** Set Business Component Properties **/
&CI.gethistoryitems = True;
/*&CI.InteractiveMode = True;*/
/*&CI.stoponfirsterror = True;*/

For &TRANSACTION = 1 To &RS.RowCount
   
   &CI.VOLUNTEER_ORG = &RS(&TRANSACTION).VOLNTER_ORG_TBL.VOLUNTEER_ORG.Value;
   
   /* note: You can achieve better performance if you add code here to check  if the keys are the same L0 keys as the last time  through the loop and, if so,skip the Get/Create section. */
   
   If Not &CI.create() Then
      &PSMESSAGES.DeleteAll();
      If Not &CI.get() Then
         /** Check Error Messages **/
         For &I = 1 To &PSMESSAGES.count
            &TYPE = &PSMESSAGES.item(&I).type;
            &TEXT = &PSMESSAGES.item(&I).text;
         End-For;
         Exit(1);
         
      End-If;
   End-If;
   
   If Not &CI.CopySetupRowset(&RS, &TRANSACTION) Then
      /** Check Error Messages **/
      For &I = 1 To &PSMESSAGES.count
         &TYPE = &PSMESSAGES.item(&I).type;
         &TEXT = &PSMESSAGES.item(&I).text;
      End-For;
      Exit(1);
   End-If;
   
   If Not &CI.Save() Then
      /** Check Error Messages **/
      For &I = 1 To &PSMESSAGES.count
         &TYPE = &PSMESSAGES.item(&I).type;
         &TEXT = &PSMESSAGES.item(&I).text;
      End-For;
      Exit(1);
   End-If;
   
   &CI.Cancel();
End-For;

Syntax

CopySetupRowsetDelta(&Rowset [, InitialRow] [, record_list]);

Where record_list is a list of record names in the form:

RECORD.source_recname, RECORD.target_recname

Description

The CopySetupRowsetDelta method is used to copy a setup table with changed rows in an application message to a Component Interface. A setup table has the same record at level zero and level one, while a Component Interface has only a single copy of a record. This method copies the contents of the message (at level zero) to the first level collection (level one) of the Component Interface.

Note: This method works in PeopleCode only. CopySetupRowsetDelta copies all the like-named fields from the changed row into the message. It is not copying only the changed fields.

The CopySetupRowsetDelta method copies like-named record fields, in those rows where the IsChanged property is True. If a pair of source and destination record names are given, these are used to pair up the records and data collections before checking for like-named record fields.

Note: This method uses the names of the records in the collection, notthe name you may give the collection when you create the Component Interface.

If there are blanks in source rowset or record, they are copied over to the Component Interface only if the field’s IsChanged property is set to True. Otherwise blanks are notcopied.

Note: CopySetupRowsetDelta is for a notification process, that is, with message data. As all notifications work only in two-tier mode, CopySetupRowsetDelta works only in two-tier mode.

Warning! CopySetupRowsetDelta uses a record's keys to locate the target row to change for all audit actions other than Add. CopySetupRowsetDelta actions (other than Add) therefore work only on rowsets that have keys that uniquely identify all rows in the rowset. Rowsets that do notdistinguish between rows using a key field will be updated in an unpredictable fashion.

Parameters

Field or Control	Definition
`&Rowset`	Specify an existing, instantiated rowset object that contains data.
`InitialRow`	Specify the initial transaction row to begin with. This parameter provides a quick way to loop through a rowset that has multiple level zero rows. The default value for this parameter is 1.
`record_list`	Specify source and target record names. The `source_recname` is the record being copied from, in the rowset object being copied from. The `target_recname` is the record being copied to, in the Component Interface being copied to.

Returns

None.

Example

Local ApiObject &SESSION;
Local ApiObject &PSMESSAGES;

Local ApiObject &CI;

Local Message &MSG;
Local Rowset &RS;

&SESSION = %Session;
&PSMESSAGES = &SESSION.psmessages;

&MSG = %IntBroker.GetMessage();
&RS = &MSG.GetRowset();

&CI = &SESSION.getcomponent(Component.VOL);

/** Set Business Component Properties **/
&CI.gethistoryitems = True;
/*&CI.InteractiveMode = True;*/
/*&CI.stoponfirsterror = True;*/

For &TRANSACTION = 1 To &RS.RowCount
   
   &CI.VOLUNTEER_ORG = &RS(&TRANSACTION).VOLNTER_ORG_TBL.VOLUNTEER_ORG.Value;
   
   /* note: You can achieve much better performance if you add code here to check  if the keys are the same L0 keys as the last time through the loop and, if so, skip the Get/Create section. */
   
   If Not &CI.create() Then
      &PSMESSAGES.DeleteAll();
      If Not &CI.get() Then
         /** Check Error Messages **/
         For &I = 1 To &PSMESSAGES.count
            &TYPE = &PSMESSAGES.item(&I).type;
            &TEXT = &PSMESSAGES.item(&I).text;
         End-For;
         Exit(1);
         
      End-If;
   End-If;
   
   If Not &CI.CopySetupRowsetDelta(&RS, &TRANSACTION) Then
      /** Check Error Messages **/
      For &I = 1 To &PSMESSAGES.count
         &TYPE = &PSMESSAGES.item(&I).type;
         &TEXT = &PSMESSAGES.item(&I).text;
      End-For;
      Exit(1);
   End-If;
   
   If Not &CI.Save() Then
      /** Check Error Messages **/
      For &I = 1 To &PSMESSAGES.count
         &TYPE = &PSMESSAGES.item(&I).type;
         &TEXT = &PSMESSAGES.item(&I).text;
      End-For;
      Exit(1);
   End-If;
   
   &CI.Cancel();

Syntax

Create()

Description

The Create method associates the Component Interface object executing the method with a new, open Component Interface that matches the key values that were set prior to using the Create method. If there are CREATEKEYS values associated with the Component Interface, these are the values you must set. If there are no CREATEKEYS values, you must set the required GETKEYS values instead. All keys required for creating a new Component Interface must be set before using the Create method, otherwise you receive a runtime error. If you do not use unique key values, (that is, you try to set the keys to values that already exist in the database) you receive a runtime error.

Setting the key values prior to using the Create method is analogous to filling in the key values in the Add dialog for a component when you access it in add mode.

Parameters

None.

Returns

A Boolean value: True if component was successfully created, False otherwise.

Example

&MYCI = &MYSESSION.GetCompIntfc(COMPINTFC.ACTION_REASON);
&MYCI.ACTION = "Additional Job";
&MYCI.ACTION_REASON = "0001";
&MYCI.Create();

Syntax

Find()

Description

Note: Find can be used only at level zero within the Component Interface.

You do not have to set values for all the key values. You can use the same wildcards in your Find that you can use in the search dialog, that is, % for one or more characters in a search pattern, and _ (underscore) for exactly one character. In addition, you can use partial values. For example, the following code finds all the data items where the employee ID starts with an "8":

&MYCI.Emplid = "8";
&MYDC = &MYCI.Find();

This is analogous to using a partial key from the search dialog, opening a component.

After you have a data collection, you can use one of the data collection methods to open the Component Interface.

Parameters

None.

Returns

A collection of Component Interfaces.

Syntax

Get()

Description

The Get method associates the Component Interface object executing the method with an open Component Interface that matches the key values that were set prior to using the Get method. The key values you must set are the required GETKEYS values for the Component Interface.

Note: To retrieve all the history data for a Component Interface, you must specify the GetHistoryItems property as True before you use the Get method. If you want any PeopleCode programs associated with the fields to fire immediately after a value is changed, you must set the InteractiveMode property as True beforeyou use the Get method.

After any execution of Get, you should check if there are any errors pending on the session object. In some special circumstances (involving failure of previously cached operations failing after the Get has executed) Get returns True even though the component wasn’t retrieved.

Parameters

None.

Returns

A Boolean value: True if component was successfully retrieved, False otherwise.

Example

&MYCI.EMPLID = "8001";
&MYCI.Get();
If %Session.ErrorPending Then
   /* Get Unsuccessful, do error processing */
Else
   /* do regular processing */
End-if;

Syntax

GetPropertyByName(string)

Description

The GetPropertyByName method returns the value of the property specified by string. For a collection, it returns a reference to the collection. Generally this function is used only in applications that cannot get the names of the component interface properties until runtime.

Parameters

Field or Control	Definition
`string`	The name of the property.

Returns

String. The value of the property.

ApiObject. For a collection. The value of the property.

Example

Local ApiObject &oSession, &oCI;
Local array of string &Keys_Arr, &Temp_Arr, &Prop_Arr;
Local string &strCIName, &PropertyValue;
Local number &I, &J, &K;

Function getPropertyValue(&oDataColl As ApiObject, &PropertyName As string) Returns string
rem ***** Return property value
   Return &oDataColl.GetPropertyByName(&PropertyName);
End-Function;

Function getCollection1(&collectionName As string)
   Local ApiObject &oL1_DataColl, &oL1_DataItem;
rem ***** Return collection
   &oL1_DataColl = &oCI.GetPropertyByName(&collectionName);
   For &J = 1 To &oL1_DataColl.Count
      &oL1_DataItem = &oL1_DataColl.Item(&J);
      For &K = 1 To &Prop_Arr.Len
         &Temp_Arr = Split(&Prop_Arr [&K], "|");
         If &Temp_Arr [1] = "1" Then
            If &Temp_Arr [3] = "Property" Then
               &PropertyValue = getPropertyValue(&oL1_DataItem, 
                   &Temp_Arr [2]);
            Else
               rem ***** Code to Get Collection 2 goes here *****;
            End-If;
         End-If;
      End-For;
   End-For;
End-Function;

Syntax

Save()

Description

Saves any changes that have been made to the data of the Component Interface executing the method. You must save any new Component Interfaces you create before they are added to the database.

The standard PeopleSoft save business rules (that is, any PeopleCode programs associated with SaveEdit, SavePreChange, WorkFlow, and so on.) is executed after you execute this method. If you didn’t specify the Component Interface to run in interactive mode, FieldEdit, FieldChange, and so on, also run at this time.

If there are multiple errors, all errors are logged to the PSMessages collection, not just the first occurrence of an error. As you correct each error, you may want to delete it from the PSMessages collection.

Note: If you’re running a Component Interface from an Application Engine program, the data won’t actually be committed to the database until the Application Engine program performs a COMMIT.

Parameters

None.

Returns

A Boolean value: True if component was successfully saved, False otherwise.

Example

&MYCI.Emplid = "8001";
&MYCI.Get();
&MYCI.CHECKLIST_CD = "00001";
&MYCI.Save;

Syntax

SetPropertyByName(string, value)

Description

The SetPropertyByName method sets the value of the property specified by string. Generally this function is used only in applications that cannot set the names of the component interface properties until runtime.

Parameters

Field or Control	Definition
`string`	The name of the property.
`value`	The value to which the property is to be set.

Returns

None.

Example

Local ApiObject &oSession, &oCI;
Local array of string &Keys_Arr, &Temp_Arr, &Prop_Arr;
Local string &strCIName, &PropertyValue;
Local number &I, &J, &K;

&strCIName = "SDK_BUS_EXP";
&Keys_Arr = CreateArrayRept("", 0);
&Keys_Arr.Push("SDK_EMPLID|" | "8001");

&oSession = %Session;
&oCI = &oSession.GetCompIntfc(@("CompIntfc." | &strCIName));

For &I = 1 To &Keys_Arr.Len
   &Temp_Arr = Split(&Keys_Arr [1], "|");
   &oCI.SetPropertyByName(&Temp_Arr [1], &Temp_Arr [2]);
End-For;