Creating and Using 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.

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

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;

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;.

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.