Understanding Restrictions on Method and Function Use

Think-time functions suspend processing either until the user has taken some action (such as clicking a button in a message box) or until an external process has run to completion (for example, a remote process).

Avoid think-time functions in the following PeopleCode events:

• SavePreChange.

• Workflow.

• RowSelect.

• SavePostChange.

• Any PeopleCode event that executes as a result of a ScrollSelect, ScrollSelectNew, RowScrollSelect, or RowScrollSelectNew function call.

• Any PeopleCode event that executes as a result of a Rowset class Select or SelectNew method.

Violation of this rule can result in application failure.

The following are think-time functions:

• Calls to an external DLL.

• DoCancel.

• DoModal and DoModalComponent.

• Exec (this is think-time only when synchronous).

• File attachment functions AddAttachment, DetachAttachment, MAddAttachment, and ViewAttachment.

• CropImage and InsertImage.

• Object functions, such as CreateObject, ObjectDoMethod, ObjectSetProperty, and ObjectGetProperty (these are think-time only when the object requires user action).

• Prompt.

• RemoteCall.

• RevalidatePassword.

• WinExec (think-time only when synchronous).

• WinMessage and MessageBox (depending on the style parameter).

The WinMessage and MessageBox functions sometimes behave as think-time functions, depending on the value passed in the function’s style parameter, which controls, among other things, the number of buttons displayed in the message dialog box.

Here is the syntax of both functions:

MessageBox(style, title, message_set, message_num, default_txt [, paramlist]) 

WinMessage(message [, style] [, title])

If the style parameter specifies more than one button, the function behaves as a think-time function and is subject to the same restrictions as other think-time functions (that is, it should never be used from SavePreChange through SavePostChange PeopleCode, or in RowSelect).

If the style parameter specifies a single button (that is, the OK button), then the function can be called in any PeopleCode event.

The style parameter is optional in WinMessage. If style is omitted, WinMessage displays OK and Cancel buttons, which causes the function to behave as a think-time function. To avoid this situation, always pass an appropriate value in the WinMessage style parameter.

The following table shows the values that can be passed in the style parameter. To calculate the value to pass, make one selection from each category in the table, then add the selections.

Under certain conditions, when you access a field that is not in the data buffer, a portion of your PeopleCode program is skipped. The skip occurs when:

• The reference is in the Import Manager.

• The reference is from the FieldDefault or FieldFormula events.

After the call to the invalid field, execution skips to the next top-level statement. Top-level statements are not nested inside other statements. The start of a PeopleCode program is a top-level statement. Nesting begins with the first conditional statement (such as While or If) or the first function call.

For example, if your code is executing in a function and inside an If … then … end-if statement, and it runs into the skip conditions, the next statement executed is the one after the End-if statement, still inside the function.

Errors and warnings should not be used in FieldDefault, FieldFormula, RowInit, FieldChange, RowInsert, SavePreChange, WorkFlow, and SavePostChange PeopleCode events. An error or warning in these events causes a runtime error that forces cancellation of the component.

DoSave can be used in the following PeopleCode events only: FieldEdit, FieldChange, or ItemSelected (for menu items in popup menus only).

You use the following record class methods to update the database:

• Delete

• Insert

• Save

• Update

Only use these methods in the following events (events that allow database updates):

• SavePreChange

• WorkFlow

• SavePostChange

• FieldChange

• Application Engine PeopleCode action

Use the SQL class to update the database. Use these functions and methods only in the following events (events that allow database updates):

• SavePreChange

• WorkFlow

• SavePostChange

• FieldChange

• Application Engine PeopleCode action

PeopleCode events and functions that relate exclusively to the page interface (the GUI) and online processing can’t be used by Component Interfaces. These include:

• Menu PeopleCode and pop-up menus.

  The ItemSelected and PrePopup PeopleCode events are not supported. In addition, the DisableMenuItem, EnableMenuItem, and HideMenuItem functions aren’t supported.

• Transfers between components, including modal transfers.

  The DoModal, EndModal, IsModal, Transfer, TransferPage, DoModalComponent, TransferNode, TransferPortal, and IsModalComponent functions cannot be used.

• Cursor position.

  SetControlValue cannot be used.

• WinMessage cannot be used.

• Save in the middle of a transaction.

  DoSave cannot be used.

• The page Activate event cannot be used.

When executed using a component interface, these functions do nothing and return a default value. In addition, using the Transfer function terminates the current PeopleCode program.

For the unsupported functions, you should put a condition around them, testing whether there’s an existing Component Interface.

If %ComponentName Then
   /* process is being called from a Component Interface */
   /* do CI specific processing */
Else
   /* do regular processing */
   .  .  .
End-if;

You cannot use the following functions in SearchInit PeopleCode:

• DoModal, DoModalComponent, DoModalX, and DoModalXComponent

• Transfer, TransferExact, TransferNode, TransferPage, and TransferPortal

Use the CallAppEngine function only in events that allow database updates, because, generally, if you are calling Application Engine, you intend to perform database updates. This category of events includes the following PeopleCode events:

• SavePreChange (Page)

• SavePostChange (Page)

• Workflow

• FieldChange

CallAppEngine cannot be used in a Application Engine PeopleCode action. If you need to access one Application Engine program from another Application Engine program, use the CallSection action.

The ReturnToServer function returns a value from a PeopleCode application messaging program to the publication or subscription server. You would use this in either your publication or subscription routing code, not in one of the standard Component Processor events.

The GetPage function cannot be used until after the Component Processor has loaded the page. You should not use this function in an event prior to the PostBuild event.

PeopleSoft builds a grid one row at a time. Because the grid and AnalyticGrid classes apply to a complete grid, you cannot use either the GetGrid or GetAnalyticGrid functions in an event prior to the Activate event.

If you are using PeopleSoft Integration Broker, your sending PeopleCode should go in the SavePostChange event, for either the record or the component.

If you are using PeopleSoft Integration Broker, your SyncRequest PeopleCode should go in the SavePostChange event, for either the record or the component.