Field Class

This chapter provides an overview of Field class and discusses the following topics:

• Shortcut considerations

• Data Type for a field object

• Scope of a field object

• Field class built-in function

• Field class methods

• Field class properties

Understanding the Field Class

A field object, instantiated from the field class, is a single instance of data within a record object, and is based on a field definition.

Accessing or changing the value of a field using the Value property is a common action.

SetDefault is a frequently used method. Name, Enabled, and Type are several commonly used field properties. If you are working with message objects, EditError is also a commonly used field property.

The field class is one of the data buffer access classes.

See Also

Accessing the Data Buffer

Considerations Using User Interface Properties

All of the field properties related to the user interface, such as the Label property, only return the value previously set in PeopleCode (false, or blank if nothing was set). They do not return the values set for the field in Application Designer.

Shortcut Considerations

An expression of the form

FIELD.fieldname.property

or

FIELD.fieldname.method(. . .)

is converted to an object expression by using GetField(FIELD.fieldname). For example, the next two lines of code are identical:

FIELD.CHECKLIST_DT.Enabled = False;
                
GetField(FIELD.CHECKLIST_DT).Enabled = False;

An expression of the form

recname.fieldname.property

or

recname.fieldname.method(.  .  .)

is converted to an object expression by using GetField(recname.fieldname). For example, the next two lines of code are identical:

EMPL_CHECKLINST.CHECKLIST_DT.Enabled = False;
                
GetField(EMPL_CHECKLIST.CHECKLIST_DT).Enabled = False;

Data Type for a Field Object

Field objects are declared as type Field. For example,

Local Field &MyField;

Scope of a Field Object

A field can only be instantiated from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in an application class, Application Engine PeopleCode, record field PeopleCode, and so on.

Field Class Built-in Functions

GetField

GetPageField

Field Class Methods

In this section, we discuss the Field class methods in alphabetical order.

AddDropDownItem

Syntax

AddDropDownItem(CodeString, DescriptionString)

Description

The AddDropDownItem method adds an item to the dropdown list in the control for the field. The first time this method is called, it overrides the prompt table or translate table used to populate the list. Those items no longer appear in the list. Only the items added using this method display.

Subsequent calls to this method adds additional items to the dropdown list. The items added with the first call to the method also display.

If there is an existing value and the dropdown list is changed with these functions, the selection shows as (Invalid value) unless the new list contains an entry with the same code as the existing value.

Considerations Using AddDropDownItem

If the data for the dropdown is language sensitive, the values for the dropdown should come from the message catalog or from a database field that has a related language record, and should not be hard-coded.

A good place for your PeopleCode program to populate a dropdown list is in the RowInit event. This event executes before the page is shown for the first time, so it prevents unnecessary SQL.

Parameters

Returns

None.

Example

Using a hardcoded list is not appropriate for this function because translations do not work. The data must come from the Translate Table (or other record) directly so that the data is translated correctly.

Local Rowset &Xlat;

&FLD = GetRecord(Record.JOB).GetField(Field.ACTION);
&FLD.ClearDropDownList();

Evaluate %Component
When Component.JOB_DATA_CONCUR
   &Xlat = CreateRowset(Record.PSXLATITEM);
   &Xlat.Fill("WHERE FILL.FIELDNAME = 'ACTION' AND Fill.FIELDVALUE in ⇒
('ADL','HIR') and EFFDT = (select max(EFFDT) from PSXLATITEM B where B.FIELDNAME =⇒
 'ACTION' and B.FIELDVALUE in ('ADL','HIR') and EFFDT <= JOB.EFFDT)");
   
   &Xlat_cnt = &Xlat.ActiveRowCount;
   For &I = 1 To &Xlat_cnt
      &CodeIn = &Xlat.GetRow(&I).GetRecord(1).FIELDVALUE.Value;
      &DescIn = &Xlat.GetRow(&I).GetRecord(1).XLATLONGNAME.Value;
      
      &FLD.AddDropDownItem(&CodeIn, &DescIn);
   End-For;
   
   Break;
When-Other
End-Evaluate;

See Also

Field class: ClearDropDownList method.

ClearDropDownList

Syntax

ClearDropDownList()

Description

The ClearDropDownList method clears all items added to the dropdown list using the AddDropDownItem method. In addition, this method causes the prompt table or translate table values defined for the list to come back into effect again (unless they're subsequently overridden again with AddDropDownItem.)

Parameters

None.

Returns

None.

Example

&FLD = GetRecord(Record.ABSENCE_HIST).GetField(Field.ABSENCE_TYPE);
&FLD.AddDropDownItem("CNF", "Conference");
&FLD.AddDropDownItem("VAC", "Vacation");
&FLD.AddDropDownItem("SCK", "Sick");
. . . .
&FLD.ClearDropDownList();

See Also

Field class: AddDropDownItem method.

DecryptPETKey

Syntax

DecryptPETKey()

Description

Use this method to apply PeopleSoft Encryption Technology (PET) to decrypt an PET-encrypted key.

Returns

None.

Example

If %Component = Component.CRYPT_KEYSET Then
   &rec = GetRecord(Record.PSCRYPTKEYSET);
   DERIVED_CRYPT.CRYPT_KEY = &rec.CRYPT_KEY.DecryptPETKey();
End-If;

See Also

EncryptPETKey

Securing Data with PeopleSoft Encryption Technology

EncryptPETKey

Syntax

EncryptPETKey()

Description

Use this method to apply PeopleSoft Encryption Technology (PET) to PET-encrypt a key.

Returns

None.

Example

If %Component = Component.CRYPT_KEYSET Then;
   &crypt_key = GetField(Field.CRYPT_KEY);
   PSCRYPTKEYSET.CRYPT_KEY = &crypt_key.EncryptPETKey();
End-If;

See Also

DecryptPETKey

Securing Data with PeopleSoft Encryption Technology

GetAuxFlag

Syntax

GetAuxFlag(FlagNumber)

Description

Use the GetAuxFlag method to determine whether the Auxiliary Flag Mask specified by FlagNumber has been set for a field.

Currently, only one flag comes preset from PeopleSoft: a 1 indicates a ChartField.

Parameters

Returns

A Boolean value: True, the flag is set, False if the flag hasn't been set.

Example

&field = GetField(Field.RC_TEST_PB);
&ret = &field.GetAuxFlag(1);
If (&ret = True) Then
   MessageBox(0, "Metadata Fn Status", 0, 0, "Aux Flag 1 is SET - ChartField");
Else
   MessageBox(0, "Metadata Fn Status", 0, 0, "Aux Flag 1 is NOT SET - Not a Chart⇒
Field");
End-If;

See Also

SetDBFieldAuxFlag.

GetLongLabel

Syntax

GetLongLabel(LabelID)

Description

The GetLongLabel method returns the long name for a field given a label ID. If the given label ID isn’t found, a null string is returned. LabelID takes a string value.

Note. If a button is defined as an HTML button or hyperlink, and if it has an associated record field, the label associated with it is only the text of the button. The mouse-over text can only be changed by the lable if the button is defined as a button with an Image label.

Returns

A text string containing the long name of the field for the specified label ID.

Example

The following code sets the label for a field to one of two different texts, based on the page.

Local Field &FIELD;

&FIELD = GetField(RECORD.MYFIELD);
   If %Page = PAGE.PAGE1 Then
      &FIELD.Label = &FIELD.GetLongLabel("LABEL1");
   Else If %Page = PAGE.PAGE2 Then
      &FIELD.Label = &FIELD.GetLongLabel("LABEL2");
End-If;

If the Label ID is the same as the name of the field, you could use the following:

&LABELID = &FIELD.Name;
&FIELD.Label = &FIELD.GetLongLabel(&LABELID);

See Also

Field class: GetShortLabel method, Label property, SetLabel .

GetRelated

Syntax

GetRelated(recname.fieldname)  

Description

The GetRelated method returns a field object for a related field recname.fieldname that has the field executing the method as its control field.

This method is similar to the GetRelField built-in function, however, the built-in works only in the current context, while this method can be applied to a field from any position in the buffer structure.

Using GetRelated With a Control Field

PeopleCode events on the Control Field can be triggered by the Related Edit field. When this happens, there can be different behavior than with other types of fields:

• If the events are called from FieldEdit of the Control Field, and that FieldEdit is triggered by a change in the Related Edit field, the functions return the previous value.

• If the events are called from FieldChange of the Control Field, and that FieldChange is triggered by a change in the Related Edit field, the functions return the value entered into the Related Edit. This may be a partial value, that will subsequently be expanded to a complete value when the processing is complete.

Parameters

Returns

The field object for the field with the specified name that is related to the field executing the method.

Example

In the following example, the field object is instantiated, then the related display field object. The Value property for the related display is changed, it is disabled, and another variable is assigned its value.

Local Field &FIELD, &REL_FIELD;

&FIELD = GetField(OPC_9A2FIELDS.COMPANY);   
/* control field object  */
&REL_FIELD = &FIELD.GetRelated(COMPANY_TBL.DESCR);    
/* related display object */
&REL_FIELD.Value = "Change";
&REL_FIELD.Enabled = False;
&TMP = &REL_FIELD.Name;
&REL_FIELD.Value = &TMP;

If you were not going to use the &FIELD variable later, the first two lines of code in the previous example could be combined:

&REL_FIELD = GetField(OPC_9A2FIELDS.COMPANY).GetRelated(COMPANY_TBL.DESCR);

Suppose you had two control fields, EMPLID and MANAGER_ID, and both use the NAME field on the PERSONAL_DATA table as their related display. If you need to access both related display fields, you could do the following:

&NAME_EMPLID = GetField(PERSONAL_DATA.EMPLID).GetRelated(PERSONAL_DATA.NAME);
                
&NAME_MANAGER = GetField(PERSONAL_DATA.MANAGER_ID).GetRelated(PERSONAL_DATA.NAME);

See Also

GetField.

GetShortLabel

Syntax

GetShortLabel(LabelID)

Description

The GetShortLabel method returns the short name for a field given a label ID. If the given label ID isn’t found, a null string is returned. LabelID takes a string value.

Note. If a button is defined as an HTML button or hyperlink, and if it has an associated record field, the label associated with it is only the text of the button. The mouse-over text can only be changed by the lable if the button is defined as a button with an Image label.

Returns

A text string containing the short name of the field for the specified label ID.

Example

The following code sets the label for a field to one of two different texts, based on the page.

Local Field &FIELD;

&FIELD = GetField(RECORD.MYFIELD);
   If %Page = PAGE.PAGE1 Then
      &FIELD.Label = &FIELD.GetShortLabel("LABEL1");
   Else If %Page = PAGE.PAGE2 Then
      &FIELD.Label = &FIELD.GetShortLabel("LABEL2");
End-If;

If the Label ID is the same as the name of the field, you could use the following:

&LABELID = &FIELD.Name;
&FIELD.Label = &FIELD.GetShortLabel(&LABELID);

See Also

Field class: GetLongLabel method, Label property, SetLabel .

SearchClear

Syntax

SearchClear()

Description

The SearchClear method clears the field values if the field is a search key.

Considerations Using SearchClear and SetDefault

The SetDefault method causes a field to be set to its default value (if there is one) immediately after SearchInit PeopleCode finishes. SetDefault overrides SearchClear. If you call SearchClear for a record, then use SetDefault for a field, the field is set to its default value and the search key values for the rest of the record are cleared.

Parameters

None.

Returns

None.

Example

Local Field &FIELD;

&FIELD = GetField(PERSONAL_DATA.EMPLID);
&FIELD.SearchClear();

See Also

SetDefault, SearchClear.

SetCursorPos

Syntax

SetCursorPos(PAGE.pagename | %Page)

Description

The SetCursorPos method enables you to set the focus to the page field corresponding to the field object (on the specified page). The current page may be specified as %Page.

Restrictions on Use with a Component Interface

This function is ignored (has no effect) when used by a PeopleCode program that’s been called by a Component Interface.

Parameters

Returns

None.

Example

The following pseudo-code enables you to set the focus to a related field:

GetField(ControlRec.ControlField).GetRelated(RelatedRec.RelatedField).SetCursorPos⇒
(PAGE.pagename);

See Also

SetDefault, SetCursorPos.

SetDefault

Syntax

SetDefault() 

Description

SetDefault sets the value of the field to a null value, or to a default, depending on the type of field.

• If this method is used against data from the component buffers, the next time default processing occurs, it is set to its default value: either a default specified in its record field definition or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

• If this method is used with a field that isn't part of the data buffer (for example, a field in a record object instantiated with CreateRecord) the field is automatically set to its default value if one is set for the field, not for the record field. Any FieldDefault PeopleCode will not be run on these types of fields. If you want to set the default values for all the fields in a record, use the SetDefault record class method.

Blank numbers correspond to zero on the database. Blank characters correspond to a space on the database. Blank dates and long characters correspond to NULL on the database. SetDefault gives each field data type its proper value.

Parameters

None.

Returns

None.

Example

&CHARACTER.SetDefault();

See Also

SetDefault, Default Processing.

Field Class Properties

In this section, we discuss the Field class properties. The properties are discussed in alphabetical order.

DataAreaCollapsed

Description

This property specifies whether the default initial view of the data area of a group box is collapsed or expanded.

Note. You must set the Collapsible Data Area on the properties for the group box in Application Designer for this property to have any effect.

This property changes to reflect the current state of the data area, according to whether the user has collapsed or expanded it. Changing the value collapses or expands the data area, but it does not prevent the user from collapsing (or expanding) it themselves.

Note. Because the user can change the value of this property, whatever value is set in PeopleCode isn’t guaranteed to be still set the next time it is checked, because the user may have collapsed or expanded the data area in the meantime.

This property overwrites the value of the Default Initial View to Expanded field set in Application Designer. For example, if Default Initial View to Expanded is selected in Application Designer, then the value for the DataAreaCollapsed property is set to True, the control initially displays collapsed.

This property takes a Boolean value: True, initially display the data area collapsed, False, initially display the data area expanded.

This property is read-write.

Note. If you want to collapse an entire level-based control, such as a scroll area or a grid, use the DataAreaCollapsed Rowset method.

See Also

Rowset class: DataAreaCollapsed property.

DecimalPosition

Description

Use this property to specify the number of digits after the decimal point to be displayed for a field defined as number or signed number.

This property overwrites the Decimal Positions value defined for a field in Application Designer.

Setting the DecimalPosition property to a smaller number than the record field's decimal position causes the displayed data to be truncated. For example, suppose a numeric field in the database has a value 0.005. Setting DecimalPosition to 2 displays 0.00 on page.

This property takes an integer value. The default value is -1, which indicates that the property is not set.

This property is read-write.

See Also

Specifying Number Field Attributes.

DisplayFormat

Description

Use this property to specify a custom format to use for the field.

This property is read-write.

The custom format for a field is specified in the field definition. This property enables you to switch between display formats that are defined as part of a custom format. For example, suppose your field used the PHONE-INTL custom format:

PHONE-INTL format

Both the LONG and the SHORT stored formats have two display formats: STANDARD and UNFORMATTED.

Using this property, you could select either of the display formats. For example:

If %Component = PAGE.INTERNATIONAL
   &CHAR.DisplayFormat = "STANDARD";
Else
   &CHAR.DisplayFormat = "UNFORMATTED";
End-If;

Note. You cannot change the Stored format, but you can find its value using the StoredFormat property.

Example

&CHARACTER.DisplayFormat = "STANDARD";
                
/* this assumes that &CHARACTER is a custom formatted field, 
and a display format option is STANDARD */

See Also

Field class: StoredFormat property.

DisplayOnly

Description

This property is set to true if the field property DisplayOnly in the Application Designer is set. May be set to false to change how the field displays.

Note. This property overwrites whatever value is set in Application Designer.

This property is read-write.

DisplayZero

Description

Use this property to specify if, in a numeric field, zeros or blank are displayed on a page.

This property overwrites the Display Zero value on the page field properties dialog box in Application Designer.

This property takes a Boolean value: true, display zeros, false, display blank. The default values is false.

The value of the DisplayZero property can be changed by the SmartZero property.

If SmartZero is set to true, and your application sets DisplayZero to false in a PeopleCode program, the application server changes the value of DisplayZero to true to display zeros, not blanks. When this occurs, the DisplayZeroChanged property is set to true.

This property is read-write.

See Also

DisplayZeroChanged, SmartZero.

Specifying Attributes for a New Field Definition

DisplayZeroChanged

Description

Use this property to determine if the original DisplayZero property has been changed from its original setting.

The DisplayZeroChanged property is only relevant when the SmartZero property has been set to true. When SmartZero equals true, the application server adjusts the DisplayZero property to display a blank or zero based on the user's input. You can then check the DisplayZeroChanged property to find out if the application server has changed the DisplayZero property.

This property takes a Boolean value: true, the application server has changed the field's DisplayZero property, false otherwise.

For example, suppose you have a PeopleCode program in the RowInit event that sets the DisplayZero property for a field to True, and also sets the SmartZero property to True. When a user deletes the numeric zero in that field on the page, and the page is submitted to the application server, the application server sets the field's DisplayZero property to False so that the new page displays a blank, not a numeric zero. The DisplayZeroChanged property is set to true in this example.

This property is read-only.

See Also

DisplayZero, SmartZero.

EditError

Description

This property is True if an error for this field has been found after executing the ExecuteEdits method with either a message object or a record object. This property can be used with the MessageSetNumber and MessageNumber properties to find the error message set number and error message number.

The EditError property returns True if a Null value was encountered for this field.

This property is read-write. After you have fixed the errors, you must set this property to False before running ExecuteEdits again.

Example

The following is an example showing how EditError, along with the ExecuteEdits method could be used:

&REC.ExecuteEdits();
If &REC.IsEditError Then
   For &I = 1 to &REC.FieldCount
      If &REC.GetField(&I).EditError Then
         LOG_ERROR();  /* application specific pgm */
      End-If;
   End-For;
End-If;

See Also

ExecuteEdits, ExecuteEdits, MessageNumber, MessageSetNumber.

Enabled

Description

This property is True if this field is enabled. May be set False to disable any control that displays this field.

This property is read-write.

Example

&CHARACTER.Enabled = True;
                
&CHARACTER.Enabled = False;

FieldLength

Description

This property returns the length of the field as a number.

This property is read-only.

Example

&MyRec = CreateRecord(Record.BKREC1);
&MyField = &MyRec.GetField(Field.BKNAME);
&length = &MyField.FieldLength;
MessageBox(0, "Field Length", 0, 0, "The field BKREC1.BKNAME is length " |⇒
 &length);

FormatLength

Description

This property returns the length of the format for the field as a number.

This property is read-only.

Example

&field = GetField(Field.BKTEST);
&formatlength = &field.FormatLength;
&length = &field.FieldLength;
&mymsg = "Field.BKTEST length is " | &length | " and format length is " |⇒
 &formatlength;
MessageBox(0, "MetaData Fn Status", 0, 0, &mymsg);

FormattedValue

Description

This property returns the value of a field as a string, formatted exactly as it would be displayed on an edit field on a page. This is useful when you're using a prompt field for the label of another field.

Because a record field can be bound to more than one page field, FormattedValue takes the first associated page field, looking first on the current page, then through all the pages in the component. This property returns a null string ("") if used with an Image or ContentReference field. It also returns a null string if no associated page field is found.

This property is read-write.

Example

This property could be used to set up a hyperlink labeled by data generated on a page. To do this, do the following:

1. Define a work field.

2. Associate the work field with the hyperlink page field.

3. Define a hidden page field with the formatting that you want.

4. Associate the hidden page field with the data field.

5. Write PeopleCode (probably for RowInit) to set the label on the work field to be the FormattedValue of the data field.

For example, suppose you wanted a hyperlink labeled by the QE_POSITION_ID field on the QE_PLYR_POSITN record. This field is a prompt table field, edited by table QE_POSITION.

You want to display the DESCRSHORT field from the prompt table, instead of the QE_POSITION_ID code value. Create a work field, POS_LINK on the WORK_REC record, and create a hyperlink page field associated with the DESCRSHORT field. For the label, create an invisible drop-down list page field, associated with QE_PLYR_POSITN.QE_POSITION_ID. Set its Prompt Table Field to DESCRSHORT. Then put a PeopleCode program on the component RowInit for either the QE_PLYR_POSITN record or the WORK_REC.

WORKREC.POS_LINK.Label = QE_PLYR_POSITN.QE_POSITION_ID.FormattedValue;

HoverText

Description

Use this property to override the hover text for any push buttons or hyperlinks associated with the field. The maximum length of hover text is 100 characters. If the hover text is identical to the push button or hyperlink label, the hover text will not be shown.

Important! Even if the hover text has been set in Application Designer, this property returns a blank string if you use the property before you’ve explicitly set it in PeopleCode. This property overrides the existing value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

This property is read-write.

Example

QE_ABSENCE_HIST.QE_ABSENCE_TYPE.HoverText = MsgGetText(95, 5037, "Personalize⇒
 Layout");

See Also

Field class: Label property.

IsAltKey

Description

This property is True if this field references a field definition that is defined as an Alternate Search key in the associated record definition.

This property is read-only.

IsAuditFieldAdd

Description

This property is True if this field references a field definition that is defined as an audit field in the associated record definition, and the field is audited whenever new data is added.

This property is read-only.

IsAuditFieldChg

Description

This property is True if this field references a field definition that is defined as an audit field in the associated record definition, and the field is audited whenever data is changed.

This property is read-only.

IsAuditFieldDel

Description

This property is True if this field references a field definition that is defined as an audit field in the associated record definition, and the field is audited whenever data is deleted.

This property is read-only.

IsAutoUpdate

Description

This property is True if this field references a field definition that is defined as an Auto-Update field in the associated record definition.

This property is read-only.

IsChanged

Description

This property returns True if the value for the field has been changed.

Note. Use this property with the primary database record only. It will not return valid results if used with a work record.

This property is read-only.

Example

If &CHARACTER.IsChanged Then
                
     Warning ("The character field has been changed");
                
End-If;

IsDateRangeEdit

Description

This property is True if this field references a field definition that is defined as requiring a Reasonable Date in the associated record definition.

This property is read-only.

IsDescKey

Description

This property is True if this field references a field definition that is defined as a descending key in the associated record definition.

This property is read-only.

IsDuplKey

Description

This property is True if this field references a field definition that is defined as a duplicate key in the associated record definition.

This property is read-only.

IsEditTable

Description

This property is True if this field references a field definition that has a table edit type of a Prompt Table with Edit.

This property is read-only.

IsEditXlat

Description

This property is True if this field references a field definition that has a table edit type of a Translate Table Edit.

This property is read-only.

IsFromSearchField

Description

This property is True if this field references a field definition that is defined as a From Search Field in the associated record definition.

This property is read-only.

IsInBuf

Description

This property returns True if the data of the field is present in the data buffers. For example, all of the fields of a derived record are not present in the data buffer.

This property is read-only.

Example

The following example iterates over all the fields in a record. The code verifies that the data for the field is accessible before it tries to assign the value to a variable.

For &I = 1 to &REC.FieldCount
   &FIELD = &REC.GetField(&I);
   If &FIELD.IsInBuf Then
      &VALUE = &FIELD.Value;
      /* do other processing */
   End-If;
End-For;

See Also

Record Fields and the Component Buffer.

IsKey

Description

This property is True if this field references a field definition that is defined as a primary key of the associated record definition.

This property is read-only.

Example

If &CHARACTER.IsKey Then
                
     Warning ("The field " | &Character.Name | " is a key");
                
End-If;

IsListItem

Description

This property is True if this field references a field definition that is defined as a List Box item of the associated record definition.

This property is read-only.

IsNotUsed

Description

This property is True if this field has been set as NotUsed with the SetDBFieldNotUsed function.

This property is read-only.

Example

&field = GetField(Field.RC_TEST_PB);
&ret = &field.IsNotUsed;
If (&ret = True) Then
   MessageBox(0, "MetaData Fn Status", 0, 0, "Field is NOTUSED");
Else
   MessageBox(0, "MetaData Fn Status", 0, 0, "Field is used.");
End-If;

IsRequired

Description

This property is True if this field references a field definition that is defined as Required in the associated record definition.

This property is read-only.

IsRichTextEnabled

Description

This property is True if this field is a long edit box with the rich text editor enabled.

This property is read-only.

IsSearchItem

Description

This property is True if this field references a field definition that is defined as a Search key in the associated record definition.

This property is read-only.

IsSystem

Description

This property is True if this field references a field definition that is defined as System Maintained field in the associated record definition.

This property is read-only.

IsThroughSearchField

Description

This property is True if this field references a field definition that is defined as a Through Search Field in the associated record definition.

This property is read-only.

IsUseDefaultLabel

Description

This property is True if this field references a field definition that has its label defined as Use Default Label in the associated record definition.

This property is read-only.

IsYesNo

Description

This property is True if this field references a field definition that has a table edit type of a Yes/No Table Edit.

This property is read-only.

Label

Description

Use this property to override the label text for the field when it’s displayed on a page.

Important! Even if the label text has been set in Application Designer, this property returns a blank string if you use the property before you’ve explicitly set it in PeopleCode. This property overrides the existing value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

To set the label in PeopleCode, use this property or the SetLabel built-in function. To return the text of a label before you set it, use the GetShortLabel or GetLongLabel methods.

Note. You can't use this property to set labels longer than 100 characters. If you try to set a label of more than 100 characters, the label is truncated to 100 characters.

The “tool tip,” or mouse over text, that appears with a hyperlink at runtime comes from the RFT long label assigned to the record field. However, the RFT long label displays only if it is different from the assigned display value of the hyperlink and it is not null. If the link is an image button, the tool tip is derived from the label text if there is any. Otherwise, the RFT long label is used.

This property is read-write.

Example

The following code sample changes all the field labels for a record to the short label. It assumes that there is a label with the same name as the name of the field for all fields in the record.

Local Field &FLD;
Local Record &REC;

If CHECK_FIELD Then
   &REC = GetRecord();
   For &I = 1 to &REC.FieldCount
      &FLD = &REC.GetField(&I);
      &LABELID = &FLD.Name;
      ​&FLD.Label ​= &FLD.GetShortLabel(&LABELID);
   End-For;
End-If;

See Also

Field class: GetShortLabel method, GetLongLabel method.

LabelImage

Description

Use this property to override the image for a button. This property is only valid for button controls. This property can be set even when the button is disabled or display-only.

Important! Even if the image has been set in Application Designer, this property returns a blank string if you use the property before you’ve explicitly set it in PeopleCode. This property overrides the existing value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

The value for this property can be either of the following:

Image.imagename

or

"Imagename"

Oracle strongly recommends that if the PeopleCode program sets the LabelImage for an active button, it also sets the image appropriately if the button is disabled.

This property is read-write.

Example

Local Field &MyField;

&MyField = GetField(BUTTON_BOTTOM);
&MyField.LabelImage = Image.BTN_REFRESH;

LongTranslateValue

Description

This property returns a string that contains the Long translate (XLAT) value of the field if the field is based on a translate table.

If the field has a null value, a null string is returned. If the field isn’t based on a translate table, or the value isn’t in the translate table, the field’s current value is returned. Because the current value can be of any type, this property has a type of Any.

Note. If you’re accessing a field based on the Translate table, the Value property returns only the one or two letter XLAT value.

Use the ShortTranslateValue property to return the short translate value of a field.

This property is read-only.

Example

Local Any &VALUE;
Local Field &MYFIELD;

&MYFIELD = GetField();
&VALUE = &MYFIELD.LongTranslateValue;
If ALL(&VALUE) Then
   /* do processing */
End-if;

See Also

Field class: Value property, ShortTranslateValue property.

MessageNumber

Description

This property returns the error message number (as a number) if an error for this field is found after executing ExecuteEdits method. You can use this property in conjunction with the EditError property (which can be used to determine whether there are any errors) and the MessageSetNumber property (which contains the error message set number if an error is found.)

This property is read-only.

Example

For &I = 1 to &RECORD.FieldCount
   &MYFIELD = &RECORD.GetField(&I);
   If &MYFIELD.EditError Then
      &MSGNUM = &MYFIELD.MessageNumber;
      &MSGSET = &MYFIELD.MessageSetNumber;
      /* Do processing */
   End-If;
End-For;

MessageSetNumber

Description

This property returns the error message set number (as a number) if an error for this field is found after executing ExecuteEdits method. You can use this property in conjunction with the EditError property (which can be used to determine whether there are any errors) and the MessageNumber property (which contains the error message number if an error is found.)

This property is read-only.

Example

For &I = 1 to &RECORD.FieldCount
   &MYFIELD = &RECORD.GetField(&I);
   If &MYFIELD.EditError Then
      &MSGNUM = &MYFIELD.MessageNumber;
      &MSGSET = &MYFIELD.MessageSetNumber;
      /* Do processing */
   End-If;
End-For;

MouseOverMsgNum

Description

Use this property to override the message number for a message catalog mouse over popup page. Together with the MouseOverMsgSet property, this property uniquely identifies a Message Catalog entry to be used as the mouse over popup page.

The Message Text field from that Message Catalog entry becomes the title of the mouse over popup page; the Explanation field becomes the body of the mouse over popup page.

Important! For this property to have an effect, the page field definition must first be set as a message catalog mouse over popup in Application Designer. This property overrides the existing message number value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

This property is read-write.

Example

For example, the following code could be added to the page Activate event to override the message set and number defined in Application Designer for the popup page associated with the DEBUG_PEOPLECD.DEBUG_CODE field.

GetField(DEBUG_PEOPLECD.DEBUG_CODE).MouseOverMsgSet = 2;
GetField(DEBUG_PEOPLECD.DEBUG_CODE).MouseOverMsgNum = 13;

See Also

MouseOverMsgSet

Enabling Message Catalog Pop-up Pages

MouseOverMsgSet

Description

Use this property to override the message set number for a message catalog mouse over popup page. Together with the MouseOverMsgNum field property, this property uniquely identifies a Message Catalog entry to be used as the mouse over popup page.

Important! For this property to have an effect, the page field definition must first be set as a message catalog mouse over popup in Application Designer. This property overrides the existing message set value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

This property is read-write.

See Also

MouseOverMsgNum

Name

Description

This property returns the name of the field definition that the field object is based on as a string value.

This property is read-only.

Example

WinMessage("The character field's name is : " | &CHARACTER.Name);

OriginalValue

Description

This property returns the value of a field, that is, the value that from the database. If the value hasn't been changed and saved by the user, it is the original value from the database. If the value has been changed and saved by the user, it is the existing value in the database.

Note. This property does not work for derived records. Original values are the database values, and derived records do not have a corresponding database value.

This property is read-only.

Example

&Orig = &MyField.OriginalValue;
If &Orig = &Date Then
   /* do current day processing */
Else
   /* do other processing */
End-If;

ParentRecord

Description

This property returns a reference to the record object for the record containing the field.

This property is read-only.

Example

&NUMBER_OF_FIELDS = &CHARACTER.ParentRecord.Fieldcount;
                
/* note that FieldCount is a property of the Record class */ 

PromptTableName

Description

This property returns the name of the prompt table (if any) associated with this field. This property returns a string value. This property returns Null if no prompt table is associated with the field.

This property is read-only.

SearchDefault

Description

If this property is set to True, system defaults (the default values set in the record field definitions) are enabled on search dialogs for the field. Setting this property to True does not cause the FieldDefault event to fire.

The system default is done only once, when the search dialog first starts, immediately after any SearchInit PeopleCode. If the user subsequently blanks out a field, the field isn't reset to the default value. Setting SearchDefault to False disables default processing for the field executing the property.

SearchDefault is effective only when used in SearchInit PeopleCode programs.

This property is read-write.

Example

&CHARACTER.SearchDefault = True;
                
/* assuming &CHARACTER is a search key, and has a default value */

This example turns on edits and system defaults for the SETID field in the search dialog box:

&SETID = GetField(INV_ITEMS.SETID);
&SETID.SeachDefault = True;
&SETID.SearchEdit = True;

SearchEdit

Description

If this property is set to True, SearchEdit enables system edits (edits specified in the record field definition) for the field, for the life of the search dialog box. Setting SearchEdit to False disables system edits. In the Add mode search dialog box, the following edits are performed when the end-user clicks the Add button. In any other mode, the following edits are performed when the end-user clicks the Search button:

• Formatting

• Required Field

• Yes/No Table

• 1/0 Table

• Translate Table

• Prompt Table

SearchEdit does not cause the FieldEdit, FieldChange, or SaveEdit PeopleCode events to fire during the search dialog.

You might use SearchEdit to control access to the system. For example, you can apply this function to the SETID field of a dialog box and require the user to enter a valid SETID before they are able to click OK on the search dialog box.

This property is read-write.

Considerations Using SearchEdit

If you use this method in the SearchInit event, the search page options are limited to the "=" and "IN" operators.

Example

&CHARCTER.SearchEdit = True;
                
/* assuming &CHARACTER is a search key, and contains an edit table 
such as translate table defined in its field properties.  */

This example turns on edits and system defaults for the SETID field in the search dialog box:

&SETID = GetField(INV_ITEMS.SETID);
&SETID.SeachDefault = True;
&SETID.SearchEdit = True;

SetComponentChanged

Description

This property determines whether a change to a field (using PeopleCode) marks the component as changed and the data written to the database if the field is a database field.

This property takes a Boolean value: true, changes to the field mark the component as changed, false, the component is treated as if unchanged. The default value is true for database fields and false for derived fields.

The Set Component Changed checkbox for a page field in Application Designer determines if a user's action on a page marks the component as changed. For example, if Set Component Changedfor an edit box control is cleared in Application Designer, then user's editing on the edit box does not mark the component as changed and no save warning message is displayed if the user leaves the page without saving. The SetComponentChanged property for a field determines if a change on the field value using PeopleCode marks the component as changed and a save warning is issued when the user tries to exit the page without saving.

This property is only applicable after the Page Activate event has run. If you try to use this property before or during Page Activate, the user does not receive a warning if data has been changed.

This property is read-write.

See Also

Setting Use Properties

SetComponentChanged

ShortTranslateValue

Description

This property returns a string that contains the Short translate (XLAT) value of the field if the field is based on a translate table.

If the field has a null value, a null string is returned. If the field isn’t based on a translate table, or the value isn’t in the translate table, the field’s current value is returned. Because the current value can be of any type, this property has a type of Any.

Note. If you’re accessing a field based on the translate table, the Value property returns only the one or two letter XLAT value.

Use the LongTranslateValue property to return the long translate value of a field.

This property is read-only.

Example

Local Any &VALUE;
Local Field &MYFIELD;

&MYFIELD = GetField();
&VALUE = &MYFIELD.ShortTranslateValue;
If ALL(&VALUE) Then
   /* do processing */
End-if;

See Also

Field class: Value property, LongTranslateValue property.

ShowRequiredFieldCue

Description

With PeopleTools 8, an asterisk (*) is displayed on pages beside fields that are defined as Required in Application Designer. You can use this property to specify whether this asterisk, also called the required field cue, is displayed for a particular field.

For example, many fields are made required or non-required either procedurally or through PeopleCode. This means they aren’t defined as Required in Application Designer, and the end-user may be confused. For these fields, you can use this property.

Note. This property affects only fields where a required field cue is otherwise permissible. That is, regardless of the setting of the property, no cue is ever shown on a pushbutton, a display-only field, and so on.

This property is read-write.

SmartZero

Description

Use this property to specify if FieldChange PeopleCode programs are run when a user changes a zero to a blank, or a blank to a zero, for a field on a page.

This property takes a Boolean value: true, run FieldChange PeopleCode programs, false, do not. The default value is false.

When you set this property to true, in addition to treating a user change of blank-to-zero and zero-to-blank as a field change, the application server also adjusts the DisplayZero property for the runtime field object to display a blank or zero as entered by the user.

This property is read-write.

See Also

DisplayZero, DisplayZeroChanged.

SqlText

Description

This property is valid only for fields that have a dynamic view as their prompt record. If you set SqlText to a non-null value, that text is used instead of the dynamic view's normal text used for prompting.

Important! Even if the SQL text has been set in Application Designer, this property returns a blank string if you use the property before you’ve explicitly set it in PeopleCode. This property overrides the existing value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

Suppose you wanted to have a different prompt table depending on the settings of other fields in the row. Normally you could use %EDITTABLE to dynamically specify the prompt table you want. However in this case there are too many possible combinations of values, which would require too many views. Furthermore, the values are customizable by the end-user or the application, which means even if you, the developer, wanted to, you couldn't provide all the combinations of views necessary. However you can generate the desired SQL text for the view in PeopleCode based on what the user enters.

If you use a dynamic view as the prompt table, and have the dynamic view contain a SQL object that is updated from PeopleCode, you could achieve this functionality. However, a SQL object is a shared object, so if multiple users used the same page, they overwrite each other's settings and the SQL object contains the SQL for the most recent user. Similarly if a single user had multiple rows on a page, the SQL object is valid only for the most recent row. This means if the user went to another row and did a prompt, they would get the wrong values again.

The purpose of this property is to enable you to specify the generated SQL text independently for each occurrence in each transaction. It enables you to override the text of a dynamic view being used as a prompt table on a field by field basis.

It is up to the developer to verify that the text specified for this property is valid, that is, that it selects the correct number of fields for the record definition, and so on.

This property is read-write.

StoredFormat

Description

This property returns the custom character format (as a string) for the field executing the property.

If the field doesn’t have a custom format associated with it, the user receives a runtime error message.

If the field has a display format associated with it, you can change that using the DisplayFormat property.

This property is read-only.

Example

WinMessage("The character field's custom stored format is : " | &CHARACTER.Stored⇒
Format);

/* this assumes that &CHARACTER is a custom formatted */
/* field */

See Also

Field class: DisplayFormat property.

Style

Description

If a page has a style sheet associated with it, this property can be used to specify a different style class with a field. Use this property to override the existing style class for a field.

Important! Even if the style class has been set in Application Designer, this property returns a blank string if you use the property before you’ve explicitly set it in PeopleCode. This property overrides the existing value only. When a user navigates away from the component, and then back to the page again, the original value is used until it's changed again through PeopleCode.

This property takes a string value.

This property is read-write.

Example

The following example associates a test field first with a style class depending on the value of the field.

Local Field &field;

&field = GetField();

If TESTFIELD1 = 1 Then;
   &field.Style = "PSHYPERLINK";
End-If;

If TESTFIELD1 = 2 Then;
   &field.Style = "PSIMAGE";
End-If;

Field with PSHYPERLINK style

Field with PSIMAGE style

Type

Description

This property returns the type of field. The values can be one of the following strings:

• CHAR

• DATE

• DATETIME

• IMAGE (for static images)

• IMAGEREFERENCE

• LONGCHAR

• NUMBER

• SIGNEDNUMBER

• TIME

Note. Fields of type Attachment have a type of IMAGE.

This property is read-only.

Example

If &CHARACTER.Type = "NUMBER" Then 
   /* perform processing */
Else
   /* error processing */
End-If;

Value

Description

This property contains the current value of the field, converted to an appropriate PeopleCode data type.

In most contexts, the Value property can be used to assign a new value to the field. However, there are some restrictions:

• You cannot assign the Value property in any RowSelect PeopleCode program.

• You cannot assign the current record field value to the Value property in any FieldEdit PeopleCode program.

Note. If you’re accessing a field based on the translate table, Value returns only the one letter XLAT value. To get the full XLAT value, use the LongTranslateValue or ShortTranslateValue properties.

This property is read-write.

Considerations Using INSTALLATION or OPTIONS Tables

When using the INSTALLATION or OPTIONS table, you cannot use the Value property. You must use the old style format, not the field object format. For example, the following code is invalid:

If %Page = Page.GP_RUN_TYPE And
      ​INSTALLATION.TL.Value = "N" Then
   &RS2.HideAllRows();

While the following code is valid:

If %Page = Page.GP_RUN_TYPE And
      ​INSTALLATION.TL = "N" Then
   &RS2.HideAllRows();

Considerations Using Character Values

Previously, if you had an edit-box field, and if the end-user selected the value in it and deleted the value, leaving the field empty, the value of the field in PeopleCode was not an empty (zero-length) string.

Now, the value of such a field is an empty (zero-length) string.

In addition, if the user adds one or more space characters to a field, the field still returns a Null string.

The following is how to check for this:

If (fieldname.Value = "") Then

Example

&CHARACTER.Value = "Hello";

See Also

Field class: LongTranslateValue property, ShortTranslateValue property.

Visible

Description

This property is True if this field is visible in the page displaying it. Setting this property to False hides the field. Because every field is implicitly associated with a rowset, row, and record, setting the Visible property for a field on the first page of a component hides only that field. If that field is repeated on other pages in the component, the other occurrences of the field aren't hidden.

This property is read-write.

Example

The following code hides the field &ROUND_OPTION based on the value of AVG_DFLT_OPTION:

Local field &ROUND_OPTION;

&ROUND_OPTION = GetField();

If AVG_DFLT_OPTION = "Y" Then
   &ROUND_OPTION.SetDefault();
   &ROUND_OPTION.Visible = True;
Else
   &ROUND_OPTION.Visible = False;
End-If;