PeopleCode Built-in Functions and Language Constructs: O

The PeopleCode built-In functions and language constructs beginning with the letter O are listed in alphabetical order within this topic.

Syntax

ObjectDoMethod(obj_this, str_method_name [, paramlist])

Where paramlist is a list of parameters of arbitrary length:

param1 [, param2]. . .

Description

Use the ObjectDoMethod function to invoke the method specified by str_method_name for the object object_this, passing in any required parameters using paramlist.

You can use ObjectDoMethod with Component Interfaces, Application Classes, OLE Automation objects, and so on.

This method can be useful if you know the number of parameters you need to pass for a method. If you do not know how many parameters you may need to pass when you write your PeopleCode, use the ObjectDoMethodArray function.

Parameters

Field or Control

Definition
obj_this

Specify an already instantiated object. This variable must have been instantiated either with CreateObject, or another function or method that creates objects.
str_method_name

A string containing the name of an exposed method of obj_this.
paramlist

The parameter list to pass to the str_method_name method.

Returns

None.

Example

This simple example instantiates an Excel worksheet object, makes it visible, names it, saves it, and displays its name. 

&WORKAPP = CreateObject("Excel.Application"); 
&WORKBOOKS = ObjectGetProperty(&WORKAPP, "Workbooks"); 
ObjectDoMethod(&WORKBOOKS, "Add", "C:\TEMP\INVOICE.XLT"); /* This associates the INVOICE template w/the workbook */ 
ObjectDoMethod(&WORKAPP, "Save", "C:\TEMP\TEST1.XLS"); 
ObjectSetProperty(&WORKAPP, "Visible", True);

This simple example invokes a user-defined method associated with the current component interface object: 

ObjectDoMethod(%CompIntfcName, &inMethodName);

Syntax

ObjectDoMethodArray(Object_Name, Method_Name, Array_of_Args)

Description

Use the ObjectDoMethodArray function to invoke the method specified by method_name for the object object_name, passing in any required parameters using the array.

Use this function when you're not certain, at the time you're writing your PeopleCode program, how many parameters a method is going to require. If you know the number of parameters, use the ObjectDoMethod function instead.

The array of parameters is an array of Any. It can only be one-dimensional. You cannot pass in field references, that is, you can't pass in references of the form RECORD.FIELDNAME.

If you do not want to supply any parameters, you can use an empty array, or a reference to a Null array.

Parameters

Field or Control

Definition
Object_Name

Specify an already instantiated object on which the method is to be evaluated.
Method_Name

Specify the name of an exposed method for the object.
Array_Of_Args

Specify an Array of Any containing the parameters for the method.

Returns

Depends on the specified object and method if a result is returned or not.

Example

&MyRslt = ObjectDoMethodArray(&MyObject, "My-Method", &MyArray);

Syntax

ObjectGetProperty(obj_this, str_property_name [, index_param_list])

Description

Use the ObjectGetProperty function to return the value of a property str_property_name of the object obj_this.

Note: The object must have already been instantiated, either using CreateObject or another function or method that returns an object. Default" OLE Automation object properties are not supported. You must specify the object property that you want to retrieve explicitly.

Parameters

Field or Control

Definition
obj_this

Specify an already instantiated object. This variable must have been instantiated either with CreateObject or another function or method that creates objects.
str_property_name

A string containing the name of an exposed property of obj_this.
index_param_list

A comma-separated list for accessing an OLE automation object indexed property. (These parameters are only used with OLE/COM objects.)

Returns

Returns an Any value equal to the value of the str_property_name property of the obj_this object.

Example

This simple example instantiates an Excel worksheet object, makes it visible, names it, saves it, and displays its name. 

&WORKAPP = CreateObject("Excel.Application"); 
&WORKBOOKS = ObjectGetProperty(&WORKAPP, "Workbooks"); 
ObjectDoMethod(&WORKBOOKS, "Add", "C:\TEMP\INVOICE.XLT"); /* This associates the INVOICE template w/the workbook */ 
ObjectDoMethod(&WORKAPP, "Save", "C:\TEMP\TEST1.XLS"); 
ObjectSetProperty(&WORKAPP, "Visible", True);

Excel Worksheets had an index property called Range that has the following signature:

Property Range (Cell1 [, Cell2]) as Range

In the following example, the range is A1:

&CELL = ObjectGetProperty(&SHEET, "Range", "A1");

Syntax

ObjectSetProperty(obj_this, str_property_name, val [, index_param_list])

Description

Use the ObjectSetProperty function to set the value of a property str_property_name of the object obj_this to val.

The object must have already been instantiated, either using CreateObject or another function or method that returns an object.

Note: Default OLE Automation object properties are not supported. You must specify the object property that you want to set explicitly.

Parameters

Field or Control

Definition
obj_this

Specify an already instantiated object. This variable must have been instantiated either with CreateObject or another function or method that creates objects.
str_property_name

A string containing the name of an exposed property of obj_this.
val

str_property_name is set to this value.
index_param_list

A comma-separated list of parameters for accessing an OLE automation object indexed property. (This is only used with COM/OLE objects.)

Returns

None.

Example

This simple example instantiates an Excel worksheet object, makes it visible, names it, saves it, and displays its name. 

&WORKAPP = CreateObject("Excel.Application"); 
&WORKBOOKS = ObjectGetProperty(&WORKAPP, "Workbooks"); 
ObjectDoMethod(&WORKBOOKS, "Add", "C:\TEMP\INVOICE.XLT"); /* This associates the INVOICE template w/the workbook */ 
ObjectDoMethod(&WORKAPP, "Save", "C:\TEMP\TEST1.XLS"); 
ObjectSetProperty(&WORKAPP, "Visible", True);

Syntax

OnlyOne(fieldlist)

where fieldlist is an arbitrary-length list of fields in the form:

[recordname.]fieldname1 [, [recordname.]fieldname2] ...

Description

Use the OnlyOne function to check a list of fields and return True if one and only one of the fields has a value. If all of the fields are empty, or if more than one of the fields has a value, OnlyOne returns False. This function is used to validate that only one of a set of mutually exclusive fields has been given a value.

A blank character field, or a zero numeric value in a required numeric field is considered a Null value.

Related Functions

Field or Control

Definition
All

Checks to see if a field contains a value, or if all the fields in a list of fields contain values. If any of the fields is Null, then All returns False.
None

Checks that a field or list of fields have no value. None is the opposite of All.

AllOrNone

Checks if either all the field parameters have values, or none of them have values. Use this in cases where if an end user fills in one field, she must all fill in the other related values.
OnlyOneOrNone

Checks if no more than one field in the set has a value. Use this in cases when a set of fields is both optional and mutually exclusive; that is, if the end user puts can put a value into one field in a set of fields, or leave them all empty.

Example

You typically use OnlyOne as follows:

If OnlyOne(param_one, param_two)
   Then value_a = "y";
End-if;

Syntax

OnlyOneOrNone(fieldlist)

where fieldlist is an arbitrary-length list of fields in the form:

[recordname.]fieldname1 [, [recordname.]fieldname2] ...

Description

Use the OnlyOneOrNone function to check a list of fields and return True if either of these conditions is true:

  • Only one of the fields has a value.

  • None of the fields has a value.

This function is useful when you have a set of mutually exclusive fields in a page and the entire set of fields is optional. The end user can leave all the fields blank or enter a value in one of the fields only.

A blank character field, or a zero numeric value in a required numeric field is considered a null value.

Related Functions

Field or Control

Definition
All

Checks to see if a field contains a value, or if all the fields in a list of fields contain values. If any of the fields is Null, then All returns False.
None

Checks that a field or list of fields have no value. None is the opposite of All.

AllOrNone

Checks if either all the field parameters have values, or none of them have values. Use this in cases where if an end user fills in one field, she must fill in all the other related values.
OnlyOne

Checks if exactly one field in the set has a value. Use this when the end user must fill in only one of a set of mutually exclusive fields.

Example

You typically use OnlyOneOrNone as follows:

If OnlyOneOrNone(param_one, param_two)
   Then value_a = "y";
End-if;

Description

Use Or to combine Boolean expressions. See Boolean Operators for more information.

Syntax

OverrideCNAVDisplayMode([disable])

Description

Important! OverrideCNAVDisplayMode has been deprecated and remains for backward compatibility. Use the OverrideConditionalNav function instead.

Use the OverrideCNAVDisplayMode function to specify whether to disable conditional navigation.

Conditional navigation can be disabled for the life of a component by invoking this function as the first executable statement in a PeopleCode PreBuild event. Alternatively, conditional navigation can be temporarily disabled for just a segment of code in other PeopleCode events.

Important! When temporarily disabling conditional navigation, you must explicitly re-enable it by calling OverrideCNavDisplayMode( False). Failing to do so will leave conditional navigation disabled for the remainder of the code execution.

The following methods, properties, and functions are “conditional navigation aware,” which means that they will generate a URL or return a value that is dependent on the conditional navigation configuration as well as on the current state as set by the OverrideCNAVDisplayMode function:

  • AbsoluteContentURL property (content reference class and content reference link class).

  • AbsolutePortalURL property (content reference class and content reference link class).

  • FindCRefByName method (PortalRegistry class).

  • FindCRefByURL method (PortalRegistry class).

  • FindCRefLinkByName method (PortalRegistry class).

  • GenerateComponentContentRelURL built-in function.

  • GenerateComponentContentURL built-in function.

  • GenerateComponentPortalRelURL built-in function.

  • GenerateComponentPortalURL built-in function.

  • GenerateComponentRelativeURL built-in function.

  • GenerateHomepagePortalURL built-in function.

  • GenerateHomepageRelativeURL built-in function.

  • GetAbsoluteContentURL method (PortalRegistry class).

  • GetURL built-in function.

  • Transfer built-in function.

  • ViewURL built-in function.

Parameters

Field or Control

Definition
disable

Specifies whether to disable conditional navigation as a Boolean value.

Note: The default value is True.

Returns

(Optional) A Boolean value. True if the function executed successfully, False otherwise.

Example 1

The following example, which must appear in the component PreBuild event, disables conditional navigation for the life of the component:

OverrideCNavDisplayMode( True);

Example 2

The following example temporarily disables conditional navigation to generate a URL to a classic component. Then, conditional navigation is re-enabled for the remainder of the program’s execution.

/* Disable conditional navigation before generating the URL. */
OverrideCNavDisplayMode( True);
&URL = GenerateComponentPortalURL(%Portal, %Node, MenuName."ROLE_MANAGER", "GBL", Component."HR_PROMOTE_APPR", "", "");

/* IMPORTANT: Re-enable conditional navigation */
OverrideCNavDisplayMode( False);
&URL = &URL | "?Action=U&BUSINESS_UNIT=US100&REQ_ID=0000000067";
&URL = &URL | "&SKIPCNAV=1"; /* Add this  to skip Pre and Post Processing */

/* Invoke MCFOutboundEmail.Send to send the email including the generated URL */
...

Syntax

OverrideConditionalNav([mode])

Description

Use the OverrideConditionalNav function to specify how to disable conditional navigation.

Conditional navigation can be disabled for the life of a component by invoking this function as the first executable statement in a PeopleCode PreBuild event. Alternatively, conditional navigation can be temporarily disabled for just a segment of code in other PeopleCode events.

Important! When temporarily disabling conditional navigation, you must explicitly re-enable it by calling OverrideConditionalNav(%CNAV_RestoreAll). Failing to do so will leave conditional navigation disabled for the remainder of the PeopleCode program.

The following methods, properties, and functions are “conditional navigation aware,” which means that they will generate a URL or return a value that is dependent on the conditional navigation configuration as well as on the current state as set by the OverrideConditionalNav function:

  • AbsoluteContentURL property (content reference class and content reference link class).

  • AbsolutePortalURL property (content reference class and content reference link class).

  • FindCRefByName method (PortalRegistry class).

  • FindCRefByURL method (PortalRegistry class).

  • FindCRefLinkByName method (PortalRegistry class).

  • GenerateComponentContentRelURL built-in function.

  • GenerateComponentContentURL built-in function.

  • GenerateComponentPortalRelURL built-in function.

  • GenerateComponentPortalURL built-in function.

  • GenerateComponentRelativeURL built-in function.

  • GenerateHomepagePortalURL built-in function.

  • GenerateHomepageRelativeURL built-in function.

  • GetAbsoluteContentURL method (PortalRegistry class).

  • GetURL built-in function.

  • Transfer built-in function.

  • ViewURL built-in function.

Parameters

Field or Control

Definition
mode

Specifies how to disable conditional navigation as an Integer value.

Specify the mode as one of the following values. You can use either the numeric or constant value. Except for %CNAV_SkipAll and %CNAV_RestoreAll, any of the other constant values can be combined. For example, specifying 12 is the equivalent of specifying %CNAV_SkipDisplayMode + %CNAV_SkipToolsRel while specifying 60 is the equivalent of specifying %CNAV_SkipAll.

Numeric Value

Constant Value

Description

1

%CNAV_SkipAll

Note: The default value is %CNAV_SkipAll.

Ignores all conditional navigation attributes.

2

%CNAV_RestoreAll

Turns on conditional navigation

4

%CNAV_SkipDisplayMode

Ignores CN_DISPLAYMODE attributes only.

8

%CNAV_SkipToolsRel

Ignores CN_TOOLSREL attributes only.

16

%CNAV_SkipGeneric

Ignores user-defined conditional navigation attributes only.

32

%CNAV_SkipNavGroup

Ignores CN_NAVGROUP attributes only.

Note: The skipcnav query string parameter that can be appended to a generated URL takes the same integer values that are valid for the mode parameter of the OverrideConditionalNav function. This includes the ability to combine two values by using their sum as the integer value. See Example 4 for information on how to post-process a URL to append the skipcnav query string parameter.

Returns

(Optional) An Integer value. 1 indicates the function executed successfully, 0 indicates failure.

Example 1

The following example temporarily disables all conditional navigation to generate a URL to a classic component. Then, conditional navigation is re-enabled for the remainder of the program’s execution.

OverrideConditionalNav();
rem generate the URL to base;
&url = GenerateComponentContentURL(%Portal, %Node, @("Menuname.ROLE_EMPLOYEE"), %Market, @("Component.HR_EE_NAME"), "", "U");
OverrideConditionalNav(%CNAV_RestoreAll);
ViewURL(&url, False);

Example 2

The following example, which must appear in the component PreBuild event, disables conditional navigation for the life of the component:

OverrideConditionalNav(%CNAV_SkipAll);

Example 3

The following example temporarily disables for CN_DISPLAYMODE attributes only. If other attributes types are set—for example, CN_TOOLSREL or user-defined attributes—those attributes will still be used to generate a URL to a classic component. Then, conditional navigation is re-enabled for the remainder of the program’s execution.

/* Skip display mode CNAV only */
OverrideConditionalNav(%CNAV_SkipDisplayMode);
rem generate the URL to base ;
&url = GenerateComponentContentURL(%Portal, %Node, @("Menuname.ROLE_EMPLOYEE"), %Market, @("Component.HR_EE_NAME"), "", "U");
OverrideConditionalNav(%CNAV_RestoreAll);
ViewURL(&url, False);

Example 4

The following example temporarily disables conditional navigation to generate a URL to a classic component. Then, conditional navigation is re-enabled for the remainder of the program’s execution. However, conditional navigation could be invoked at a later date whenever the generated link is clicked. Therefore, post-processing of the generated URL appends the skipcnav query string parameter to the URL to ensure that conditional navigation is always ignored for every user who clicks the link in every situation.

/* Disable conditional navigation before generating the URL. */
OverrideConditionalNav();
&URL = GenerateComponentPortalURL(%Portal, %Node, MenuName."ROLE_MANAGER", "GBL", Component."HR_PROMOTE_APPR", "", "");

/* IMPORTANT: Re-enable conditional navigation */
OverrideConditionalNav(%CNAV_RestoreAll);

&URL = &URL | "?Action=U&BUSINESS_UNIT=US100&REQ_ID=0000000067";
/* Post-processing ensures that CN is skipped when the user clicks the link.  */
&URL = &URL | "&skipcnav=1"; 

/* Invoke MCFOutboundEmail.Send to send the email including the generated URL */
...

Note: The skipcnav query string parameter takes the same integer values that are valid for the mode parameter of the OverrideConditionalNav function. This includes the ability to combine two values by using their sum as the integer value. See the mode parameter of the OverrideConditionalNav function for more information.