Working with Methods

This section provides and overview of session functions and methods, standard methods and collection methods.

The session functions and methods connect to a session on an Application server. This connection must be made before you can use the component interface methods.

Component Interface Session Functions

This table describes the component interface session function createSession:

Name

Description, Programming Syntax

createSession

(In PeopleCode, &session = %session)

Returns a session object.

  • Java: ISession API.createSession()

  • C++: HPSAPI_SESSION PSApiCreateSession()

Component Interface Session Methods

This table describes the component interface session methods:

Name

Description, Programming Syntax

Connect

(not used in PeopleCode)

Connects to the application server.

Use these interfaces to call with other programming languages.

  • Java: boolean connect(long apiVersion, string server, string username, string password, byte[ ] ExternalAuth)

  • C++: Bool session_Connect(HPSAPI hSession, PSI32 ApiVersion, LPTSTR server, LPSTR username, LPTSTR password, PSAPIVAPBLOB ExternalAuth)

getCompIntfc

Returns a reference to a component interface. getCompIntfc also checks to determine whether the given user that is connecting has the appropriate security to access the component interface.

Use these interfaces to call with other programming languages.

  • Java: I<CI_Name> getCompIntfc(string ciName)

  • C++: HPSAPI_<CI_Name> Session_GetCompIntfc(HPSAPI_SESSION hsession, LPTSTR ciName)

A method is a definition that performs a specific function on a component interface at runtime. Each standard method is added by default when the component interface is created and is available in PeopleCode and other programming languages. Like properties, methods are saved as part of a component interface definition. Two main types of methods are available: standard methods and user-defined methods.

Standard Methods

Description, Programming Syntax

Cancel

Backs out of the current component interface, canceling any changes made since the last save. This is equivalent to clicking the Return to Search button online. Returns True on success, and False on failure.

Use these interfaces to call with other programming languages.

  • Java: boolean cancel()

  • C++: BOOL <CI_NAME>_Cancel(HPSAPI_<CI_NAME> hObj)

Create

Creates a new instance of a component interface. This is equivalent to creating a new record in Add mode online. Returns True on success, and False on failure.

Use these interfaces to call with other programming languages.

  • Java: boolean create()

  • C++: BOOL <CI_NAME>_Create(HPSAPI_<CI_NAME> hObj)

Find

Performs a partial key search for a particular instance of a component interface, using the search keys at level 0. Returns a collection of component interface instances which match the search criteria. If no component interface instances match the search criteria, the count on the collection is zero.

Use these interfaces to call with other programming languages.

  • Java: <CI_NAME>Collection find()

  • C++: HPSAPI_<CI_NAME>COLLECTION <CI_NAME>_Find(HPSAPI_<CI_NAME> hObj)

Get

Retrieves a particular instance of a component interface. This is equivalent to opening a record in Update/Display or Correction mode when online with a PeopleSoft application. Returns True on success, and False on failure.

Use these interfaces to call with other programming languages.

  • Java: boolean get()

  • C++: BOOL <CI_NAME>_Save(HPSAPI_<CI_NAME> hObj)

Save

Saves an instance of a component interface. This is equivalent to clicking the Save button in the online system. Returns True on success, and False on failure. You should cancel after a save.

Use these interfaces to call with other programming languages.

  • Java: boolean save()

  • C++: BOOL <CI_NAME>_Save(HPSAPI_<CI_NAME> hObj)

GetPropertyByName

Returns the value of a property that is specified by name. This function typically is used only in applications that cannot get the names of the component interface properties until runtime.

Use these interfaces to call with other programming languages.

  • Java: Object getPropertyByName(String str)

  • C++: HPSAPI_OBJECT <CiCollectionItem>_GetPropertyByName(HPSAPI_<CI_COLLECTION_ITEM> hColItem, LPTSTR Name)

SetPropertyByName

Sets the value of a property that is specified by name. This function typically is used only in applications that cannot set the names of the component interface properties until runtime.

Use these interfaces to call with other programming languages.

  • Java: long setPropertyByName(String str, Object o)

  • C++: PSI32 <CiCollectionItem>_SetPropertyByName(HPSAPI_<CI_ COLLECTION_ITEM> hColItem, LPTSTR name, HPSAPI_OBJECT Value)

GetPropertyInfoByName

(In PeopleCode, CompIntfPropInfoCollection)

Returns specific information, such as length, about the definition of a property that is specified by name. This function typically is used only in applications that cannot get the names of component interface properties until runtime or by applications that need to provide a dynamic list of values that would normally be found in prompt tables.

Use these interfaces to call with other programming languages.

  • Java: IcompIntfcPropertyInfo getPropertyInfoByName(String name)

  • C++: HPSAPI_COMPINTFCPROPERTYINFO<CiPropOrItem>_GetPropertyInfoByName(HPSAPI_<CIPROPORITEM> hPropOrItem, LPTSTR name)

    where CiPropOrItem is the name of either a property or an item in a collection.

By default, each component interface is created with four standard methods—Cancel, Find, Get, and Save. Additionally, the Create standard method is generated if Create keys have been added to the component interface.

Example for GetPropertyInfoByName

The GetPropertyInfoByName method returns an object containing the property information. Here is a Java example that calls GetPropertyInfoByName:

IcompIntfcPropertyInfo oCompIntfcPropertyInfo
oCompIntfcPropertyInfo = oCI.getPropertyInfoByName(tempName);
System.out.println(oCompIntfcPropertyInfo.getName());
if (!oCompIntfcPropertyInfo.getIsCollection()) {
  System.out.println("\t Format = " + oCompIntfcPropertyInfo.getFormat());
    System.out.println("\t Type = " + oCompIntfcPropertyInfo.getType());
}
System.out.println("\t Is Required = " + oCompIntfcPropertyInfo.
   getRequired());
System.out.println("\t Is Collection? = " + oCompIntfcPropertyInfo.
   getIsCollection ());
System.out.println("\t Is Read Only? = " + oCompIntfcPropertyInfo.
   getIsReadOnly());
System.out.println("\t Is Get Key? = " + oCompIntfcPropertyInfo.getKey());
System.out.println("\t Label Long = " + oCompIntfcPropertyInfo.
   getLabelLong());
System.out.println("\t Label Short = " + oCompIntfcPropertyInfo.
   getLabelShort());
System.out.println("\t Length = " + oCompIntfcPropertyInfo.getLength());
System.out.println("\t Name = " + oCompIntfcPropertyInfo.getName());
System.out.println("\t Is Xlat? = " + oCompIntfcPropertyInfo.getXlat());
System.out.println("\t Is Yesno? = " + oCompIntfcPropertyInfo.
   getYesno());

Note: When creating a new component interface, you must save the component interface before the standard methods are created. PeopleSoft Application Designer adds the standard methods upon the first save of a new component interface.

The first item in a component interface collection is always indexed as item 1 from PeopleCode, which is consistent with other PeopleCode processing. From Java and C++ programs, this item is indexed as item 0.

Component Interface Collection Properties

This table describes the component interface collection properties:

Data Collection Method

Action, Usage

Count

Returns the number of items in a collection.

Use these interfaces to call with other programming languages.

  • Java: long getCount()

  • C++: PSI32 <CiCollectionName>_GetCount (HPSAPI_<CI_COLLECTION_NAME> hCol)

ItemByName

(not used in PeopleCode)

Returns the property in the collection. It takes Name as a parameter.

Use these interfaces to call with other programming languages.

  • Java: ICompIntfcPropertyInfo itemByName(String Name)

  • C++: CompIntfcPropertyInfoCollection_ItemByName (HPSAPI_COMPINTFCPROPERTYINFOCOLLECTION, LPTSTR Name)

InsertItem(Index)

Inserts a new item. This is equivalent to clicking the Add button to insert a new row when online. It takes Index as a parameter and follows the same conventions for performing business rules (PeopleCode) as the online system.

Use these interfaces to call with other programming languages.

  • Java: <CiCollectionName> insertItem( long Index)

  • C++: HPSAPI_<CI_COLLECTION_ITEM> <CiCollectionName>_InsertItem(HPSAPI_<CI_COLLECTION_NAME> hCol, PSI32 Index)

DeleteItem(Index)

Deletes the item that is designated by Index. This is equivalent to clicking the Delete button to delete the selected row when online.

Use these interfaces to call with other programming languages.

  • Java: boolean deleteItem(long Index)

  • C++: BOOL <CiCollectionName>_DeleteItem(HPSAPI_<CI_COLLECTION_NAME> hCol, PSI32 Index)

Item(Index)

Takes an item number as a parameter and returns a definition of the type that is stored in the specified row in the collection. For example, if the collection is a data collection, the return value is a DataRow. If the collection value is a PropertyInfoCollection, then the return value is a PropertyInfo definition, and so on.

Use these interfaces to call with other programming languages.

  • Java: <CiCollectionName> item(long Index)

  • C++: HPSAPI_<CI_COLLECTION_ITEM> <CiCollectionName>_Item(HPSAPI_<CI_ COLLECTION_NAME> hCol, PSI32 Index) (HPSAPI_COMPINTFCPROPERTYINFOCOLLECTION, PSI32)

ItemByKeys(keys)

Identifies and finds a specific item, based on keys. The keys vary according to the design of the collection.

Use these interfaces to call with other programming languages.

  • Java: <CiCollectionName> itemByKeys(String Key1, String Key2, …)

  • C++: HPSAPI_<CI_COLLECTION_ITEM> <CiCollectionName>_ItemByKeys (HPSAPI_<CI_COLLECTION_NAME > hCol, LPTSTR Key1, LPTSTR Key2, …)

CurrentItem

Returns the current effective DataRow in the collection. The behavior is consistent with effective date rules that are used online. This method works with effective-dated records only.

Use these interfaces to call with other programming languages.

  • Java: <CiCollectionName>currentItem()

  • C++: HPSAPI_<CI_COLLECTION_ITEM> <CiCollectionName>_ CurrentItem(HPSAPI_<CI_COLLECTION_NAME> hCol)

CurrentItemNum

(CurrentItemNumber)

Returns the item number of the current effective DataRow in the collection. The behavior is consistent with effective date rules that are used online. This method works with effective-dated records only.

Use these interfaces to call with other programming languages.

  • Java: long currentItemNum()

  • C++: PSI32 <CiCollectionName>_ _CurrentItemNum(HPSAPI_<CI_COLLECTION_NAME> hCol)

GetEffectiveItem(DateString, SeqNum)

Returns the DataRow that would be effective for the specified date and sequence number. This is a more general case of the GetCurrentItem function, which returns the definition that is effective at this moment. This method works with effective-dated records only.

Use these interfaces to call with other programming languages.

  • Java: <CiCollectionName> getEffectiveItem(String Date, long SeqNum)

  • C++: HPSAPI_<CI_COLLECTION_ITEM> <CiCollectionName>_ GetEffectiveItem(HPSAPI_<CI_COLLECTION_NAME> hCol, LPTSTR Date, PSI32 SeqNum)

GetEffectiveItemNum(DateString, SeqNum)

Returns the item number of the DataRow in the collection that would be effective for the specified date and sequence number. This is a more general case of the GetCurrentItemNum function, which returns the number of the definition that is effective at this moment. This method works with effective-dated records only.

Use these interfaces to call with other programming languages.

  • Java: long getEffectiveItemNum(string Date, long SeqNum)

  • C++: <CiCollectionName>_GetEffectiveItemNum( HPSAPI_<CI_COLLECTION_NAME> hCol, LPTSTR Date,PSI32 SeqNum)

You can control whether standard methods are accessible at runtime.

Use the Properties – Standard Methods tab to enable or disable standard methods.

 Properties-Standard Methods tab

To enable or disable standard methods:

  1. Select File > Definition Properties from the PeopleSoft Application Designer menu.

    The Definition Properties dialog box appears.

  2. Select the Standard Methods tab.

    You can enable or disable any of the standard methods selecting the corresponding check box. Doing so determines whether the method is available at runtime when the component interface is accessed. The Create option is available only if the component interface has Create keys.

This section discusses how to create user-define methods.

This example shows the work area in PeopleSoft Application Designer for creating user-defined methods.

 PeopleSoft Application Designer

To create a user-defined method:

  1. Right-click anywhere in the component interface view.

  2. Select View PeopleCode from the menu.

    The PeopleCode editor appears. If you are using a new component interface, no PeopleCode will appear in the editor because no user-defined methods have been created.

  3. Write the required PeopleCode functions.

    PeopleCode functions that you write are stored in a single PeopleCode program that is attached to the component interface and associated with the Methods event.

    Note: New user-defined methods do not appear in the list of methods until you save the component interface. Double-click the icon of any existing user-defined method to return to this PeopleCode program.

  4. Set permissions for the methods that you created.

    You must set permissions for every user-defined method. If you set permission to Full Access, at runtime that function is exposed to external systems as a method on the component interface object.

Note: User-defined method names must not be named GetPropertyName. The C header for Component Interfaces creates functions with that name so you can access each property. If you create your own GetPropertyName functions, you receive errors at runtime. User-defined methods can take only simple types of arguments (such as number, character, and so on) because user-defined methods can be called from Java or C/C++ as well as from PeopleCode. PeopleCode can use more complex types (like rowset, array, record, and so on), but these types of arguments are unknown to Java and C/C++.

If you want a user-defined component interface to be exportable, meaning used by code that instantiates the component interface, the method PeopleCode definition must include a Doc statement. It is in the form of:

Doc <documentation for method>

where <documentation for method> describes what the method does

For example, the following method returns true if foo is positive; otherwise, it returns false. 

Function MyFooBar(&foo as number) returns boolean
Doc "GET"
if (&foo > 0) then
return True;
else
return False;
end-if;
end-function;

If a component interface method is to be exposed in a web service, the Doc statement should describe the standard method after which it will be called and show an indication of each type of input parameter it requires. In the following example, the SetPassword method on the USER_PROFILE component interface has been exposed to a web service. The Doc statement in this case has a string following the Doc keyword and consists of comma-separated values: the method name Get, a string containing the new password, and another string for the confirmation password.

Function SetPassword(&password As string, &passwordConfirm As string) Returns boolean
   Doc "GET, NewPasswd, ConfirmPasswd"