PeopleTools 8.51 PeopleBook: PeopleCode Developer's Guide

Understanding Objects and Classes in PeopleCode

This chapter discusses:

Classes and objects
Creating and using objects.
Assigning objects.
Passing objects.

Classes and Objects

PeopleSoft delivers classes of objects that you can manipulate with PeopleCode. In addition, you can extend the existing classes or create your own. The delivered classes may or may not have a graphic user interface equivalent; some are representations of data structures that occur only at runtime. With PeopleCode, you can manipulate data in the data buffer easily and consistently. These classes enable you to write code that’s more readable, more easily maintained, and more useful.

This section discusses:

Classes.
Objects.
Object instantiation.

Classes

A class is the formal definition of an object and acts as a template from which an instance of an object is created at runtime. The class defines the properties of the object and the methods used to control the object’s behavior.

PeopleSoft delivers predefined classes, such as Array, File, Field, SQL, and so on. You can create your own classes using the Application class. You can also extend the functionality of the existing classes using the Application class.

Objects

An object represents a unique instance of a data structure defined by the template provided by its class. Each object has its own values for the variables belonging to its class and responds to methods defined by that class. This is the same for classes provided by PeopleSoft and for classes you create yourself.

After an object has been created (instantiated) from a class, you can change its properties. A property is an attribute of an object. Properties define:

Object characteristics, such as name or value.
The state of an object, such as deleted or changed.

Some properties are read-only and cannot be set, such as Name or Author. Other properties can be set, such as Value or Label.

Objects are different from other data structures. They include code (in the form of methods), not just static data. A method is a procedure or routine, associated with one or more classes, that acts on an object.

An analogy to illustrate the difference between an object and its class is the difference between a car and the blue Citroen with license plate number TS5800B. A class is a general category, while the object is a specific instance of that class. Each car comes with standard characteristics, such as four wheels, an engine, or brakes, that define the class and are the template from which the individual car is created. You can change the properties of an individual car by personalizing it with bumper stickers or racing stripes, which is like changing the Name or Visible property of an object. The model and date that the car is created are similar to read-only properties because you cannot alter them. A tune-up acts on the individual car and changes its behavior, much as a method acts on an object.

Object Instantiation

A class is the blueprint for something, like a bicycle, a car, or a data structure. An object is the actual thing that is built using that class (or blueprint.) From the blueprint for a bicycle, you can build a specific mountain bike with 23 gears and tight suspension. From the blueprint of a data structure class, you build a specific instance of that class. Instantiation is the term for building that copy, or an instance, of a class.

Creating and Using Objects

This section discusses how to:

Instantiate objects.
Change object properties.
Invoke methods.
Copy objects.

Instantiating Objects

Generally you instantiate objects (create them from their classes) using built-in functions or methods of other objects. Some objects are instantiated from data already existing in the data buffer. Think about this kind of object instantiation as taking a chunk of data from the buffer, encapsulating it in code (methods and properties), manipulating it, then freeing the references. Some objects can be instantiated from a previously created definition, such as a page or file layout definition, instead of from data.

The following example creates a field object:

Local field &MyField

&MyField = GetField();

Get functions, which include functions such as GetField, GetRecord, and so on, generally provide access to data that already exists, whether in the data buffers or from an existing definition.

Create functions, which include functions such as CreateObject, CreateArray, CreateRecord, generally create defined objects that do not yet exist in the data buffer. Create functions create only a buffer structure. They do not populate it with data. For example, the following function returns a record object for a record that already exists in the component buffer:

&REC = GetRecord();

The following example creates a standalone record. However, there is no data in &REC2. The specified record definition must be created previously, but the record does not have to exist in either the component or data buffer:

&REC2 = CreateRecord(EMP_CHKLST_ITM);

Objects with no built-in functions can only be instantiated from a session object (such as tree classes, component interfaces, and so on). For most of these classes, when you use a Get function, all you get is an identifier for the object. To fully instantiate the object, you must use an Open method.

Changing Properties

To set or get characteristics of an object, or to determine the state of an object, you must access its properties through dot notation syntax. Follow the reference to the object with a period, followed by the property, and assign it a value. The format is generally as follows:

Object.Property = Value

The following example hides the field &MYFIELD:

&MYFIELD.Visible = False

You can return information about an object by returning the value of one of its properties. In the following example, &X is a variable that is assigned the value found in the field &MYFIELD:

&X = &MYFIELD.Value

In the following example, a property is used as the test for a condition:

If &ROWSET.ActiveRowCount <> &I Then

Invoking Methods

You also use dot notation to execute methods. Follow the reference to the object with a period, then with the method name and any parameters the method takes. The format is generally:

Object.method();

You can string methods and property values together into one statement. The following example strings together the GetField method with the Name property:

If &REC_BASE.GetField(&R).Name = &REC_RELLANG.GetField(&J).Name Then

Some methods return a Boolean value: True if the method executes successfully; False if it does not. The following method compares all like-named fields of the current record object with the specified record. This method returns as True if all like-named fields have the same value:

If &MYRECORD.CompareFields(&OTHERRECORD) Then

Other methods return a reference to an object. The GetCurrEffRow method returns a row object:

&MYROW = &MYROWSET.GetCurrEffRow();

Some methods do not return anything. Each method's documentation indicates what it returns.

Many objects have default methods. Instead of entering the name of the method explicitly, you can use that method's parameters. Objects with default methods are composite objects; that is, they contain additional objects within them. The default method is generally the method used to get the lower-level object.

A good example of a composite object is a record object. Record definitions are composed of field definitions. The default method for a record object is GetField.

The following lines of code are equivalent:

&FIELD = &RECORD.GetField(FIELD.EMPLID);
&FIELD = &RECORD.EMPLID;

Note. If the field you’re accessing has the same name as a record property (such as NAME) you cannot use the shortcut method for accessing the field. You must use the GetField method.

Another example of default methods concerns rowsets and rows. Rowsets are made up of rows, so the default method for a rowset is GetRow. The two specified lines of code are equivalent: They both get the fifth row of the rowset:

&ROWSET = GetRowSet();

/*the next two lines of code are equivalent */

&ROW = &ROWSET.GetRow(5);
&ROW = &ROWSET(5);

The following example illustrates the long way of enabling the Name field on a second-level scroll area (the code is executing on the first-level scroll area):

GetRowset(SCROLL.EMPLOYEE_CHECKLIST).GetRow(1).
GetRecord(EMPL_CHKLST_ITM).GetField(FIELD.NAME).Enabled = True;

Using default methods enables you to shorten the previous code to the following:

GetRowset(SCROLL.EMPLOYEE_CHECKLIST)(1).EMPL_CHKLST_ITM.NAME.
Enabled = True;

Expressions of the form class.name.property or class.name.method(..) are converted to a corresponding object. For example, the code &temp = RECORD.JOB.IsChanged; is evaluated as if it were &temp = GetRecord(RECORD.JOB).IsChanged;.

Furthermore, the code JOB.EMPLID.Visible = False; is evaluated as if it were GetField(JOB.EMPLID).Visible = False;.

Copying Objects

Many of the classes delivered with PeopleTools have some sort of copy method, such as the rowset class CopyTo, the tree class Copy, and so on. Unless specifically identified (such as the message class CopyRowsetDelta) all copy methods use the current data of the object. This may be different than the original data values if the object was retrieved from the database and the values in it have been changed either by an end-user or a PeopleCode program.

Assigning Objects

When you assign one object to another, you do not create a copy of the object, but only make a copy of the reference.

In the following example, &A1 and &A2 refer to the same object. The assignment of &A1 to &A2 does not allocate any database memory or copy any part of the original object. It makes &A2 refer to the same object to which &A1 refers.

Local Array of Number &A1, &A2;

&A1 = CreateArray(2, 4, 6, 8, 10);
&A2 = &A1;

The following diagram shows how both references point to the same object:

Representation of two arrays

If the next statement is &A2[5] = 12;, then &A1[5] also equals 12, as shown in the following diagram:

Representation of two arrays with same content

The following example is not considered an object assignment:

Local number &NUM;
Local Array of Number &A1;

&A1 = CreateArray(2, 4, 6, 8, 10);
&NUM = &A1[3];

&NUM is of data type Number, which is not an object type. If you later change the value of &NUM in the program, you will nott change the element in the array.

Passing Objects

All PeopleCode objects can be passed as function parameters. You can pass complex data structures between PeopleCode functions (as opposed to passing long lists of fields). If a function is passed an object, the function works on the actual object, not on a copy of the object.

In the following simple example, a reference to the Visible property is passed, not the value of Visible. This enables the MyPeopleCodeFunction either to get or set the value of the Visible property:

MyPeopleCodeFunction(&MyField.Visible);

In the following example, the function Process_Rowset loops through every row and record in the rowset passed to it and executes an Update statement on each record in the rowset. This function can be called from any PeopleCode program and can process any rowset that is passed to it.

Local Rowset &RS;
Local Record &REC;

Function Process_RowSet(&ROWSET as Rowset);

   For &I = 1 To &ROWSET.Rowcount
      For &J = 1 To &ROWSET.Recordcount
         &REC = &ROWSET.GetRow(&I).GetRecord(&J);
         &REC.Update();
      End-For;
   End-For;  
End-Function;

&RS = GetLevel0();

Process_RowSet(&RS);

The following function takes a rowset and a record passed in from another program. GetRecord does not take a variable for the record; however, you can use the @ symbol to dereference the record name.

Function Get_My_Row(&PASSED_ROWSET, &PASSED_RECORD)

   For &ROWSET_ROW = 1 To &PASSED_ROWSET.RowCount
      &UNDERLYINGREC = "RECORD." | &PASSED_ROWSET.DBRecordName;
      &ROW_RECORD = &PASSED_ROWSET.GetRow(&ROWSET_ROW).GetRecord(@&UNDERLYINGREC);
    
      /* Do other processing */
     
   End-For;

End-Function;