PeopleCode Built-in Functions and Language Constructs: W-Z

The PeopleCode built-In functions and language constructs beginning with the letters W, X, Y, and Z are listed in alphabetical order within this topic.

Syntax

Warning str

Description

You typically use the Warning function in FieldEdit or SaveEdit PeopleCode to display a message alerting the end user about a potentially incorrect data entry or change. It differs from the Error function in that it does not prevent the end user from taking an action, and it does not stop processing in the PeopleCode program where it occurs.

Warning is also used in RowDelete and RowSelect PeopleCode, where its behavior is specialized. See the following sections Warnings in RowDelete and Warnings in RowSelect.

The text of the warning message (the str parameter), should always be stored in the Message Catalog and retrieved using the MsgGet or MsgGetText function. This makes it easier to translate the text, and it also enables you to include more detailed Explain text about the warning.

Note: If you pass a string to the Warning function instead of using a Message Catalog function, the explanation text from the last call to the Message Catalog may be appended to the message. This can cause unexpected results.

See WinMessage.

Warnings in FieldEdit and SaveEdit

The primary use of Warning is in FieldEdit and SaveEdit PeopleCode:

  • In FieldEdit, Warning displays a message and highlights the relevant field.

  • In SaveEdit, Warning displays a message, but does not highlight any field. You can move the cursor to a specific field using the SetCursorPos function.

See SetCursorPos.

Warnings in RowDelete

When the end user attempts to delete a row of data, the system first prompts for confirmation. If the end user confirms, the RowDelete event fires. A Warning in the RowDelete event displays a warning message with OK and Cancel buttons. If the end user clicks OK, the row is deleted. If the end user clicks Cancel, the row is not deleted.

Warnings in RowSelect

The behavior of Warning in RowSelect is totally anomalous and maintained for backward compatibility only. Use it to filter rows being added to a page scroll after the rows have been selected and brought to the component buffer. Warning causes the Component Processor to skip the current row (so that it is not added to the page scroll), then continue processing. No message is displayed.

Note: Do not use Warning in this fashion. Use the DiscardRow function for replacement instead.

See DiscardRow.

Warnings in Other Events

Do not use the Warning function in any of the remaining events, which include:

  • FieldDefault

  • FieldFormula

  • RowInit

  • FieldChange

  • RowInsert

  • SavePreChange

  • SavePostChange

Parameters

Parameter

Description

str

A string containing the text of the warning message. This string should always be stored in the Message Catalog and retrieved using the MsgGet or MsgGetText function. This makes translation easier and also enables you to provide detailed Explain text about the warning.

Returns

None.

Example

The following example shows a warning that alerts an end user to a possible error, but allows the end user to accept the change:

If All(RETURN_DT, BEGIN_DT) And
      8 * (RETURN_DT - BEGIN_DT) < (DURATION_DAYS * 8 + DURATION_HOURS) Then
   Warning MsgGet(1000, 1, "Duration of absence exceeds standard hours for number of days absent.");
End-If;

Syntax

Weekday(dt)

Description

Use the Weekday function to calculate the day of the week based on a date value.

Parameters

Parameter

Description

dt

A Date value. Weekday determines the day of the week that dt falls on.

Returns

Returns a Number value representing the day of the week. 1 is Sunday, 7 is Saturday.

Example

If &Date_HIRED equals October 30, 1996, a Monday, then the following statement sets &DAY_HIRED to 2:

&DAY_HIRED = Weekday(&Date_HIRED);

Description

Use When clauses in an Evaluate construct. See Evaluate for more information.

Description

Use a When–Other clause in an Evaluate construct. See Evaluate for more information.

Syntax

While logical_expression
   statement_list
End-While

Description

The While loop causes the statements of the statement_list to be repeated until logical_expression is false. Statements of any kind are allowed in the loop, including other loops. A Break statement inside the loop causes execution to continue with whatever follows the end of the loop. If the Break is in a nested loop, the Break does not apply to the outside loop.

Example

The following example counts from 0 to 10:

&COUNTER = 1;
While &COUNTER <= 10
   WinMessage(MsgGet(21000, 1, "Count is %1", &COUNTER));
   &COUNTER = &COUNTER + 1;
End-While;

Syntax

WinEscape()

Description

Note: This function has been deprecated and is no longer supported.

Syntax

WinExec(command_line, window_option [, synch_exec])

Description

Note: This function has been deprecated and is no longer supported.

Syntax

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

Description

Note: The WinMessage function is supported for compatibility with previous releases of PeopleTools. New applications should use MessageBox instead.

See MessageBox.

Use the WinMessage function to display a message in a message box.

Use the WinMessage for simple informational display, where the end user reads the message, then clicks an OK button to dismiss the message box. WinMessage can also be used for branching based on end user choice, in which case the message box contains two or more buttons (such as OK and Cancel or Yes, No, and Cancel). The value returned by the function tells you which button the end user clicked, and your code can branch based on that value.

If WinMessage displays more than one button, it causes processing to stop while it waits for user response. This makes it a "user think-time" function, restricting its use in certain PeopleCode events.

The contents of the message displayed by WinMessage can be passed to the function as a string, but unless you are using the function for testing purposes you should always retrieve the message from the Message Catalog using the MsgGet or MsgGetText function. This has the advantage of making the messages much easier to localize and maintain.

Note that if you pass a string to the WinMessage function (or a Warning or Error function) instead of using a Message Catalog function, the explanation text from the last call to the Message Catalog may be appended to the message. This can cause unexpected results.

The Message Catalog functions MsgGet, MsgGetText, and MessageBox retrieve and store two text strings in memory: the message text and the explanation text. The MsgGetExplainText function retrieves and stores only the explanation text. When these strings are displayed by a WinMessage, MessageBox, Error or Warning dialog, the buffers are reinitialized.

If a Message Catalog function is called without displaying the text, for instance to populate a variable or record field, the message text and the explanation text remain in memory.

If a subsequent call passes a string to a WinMessage, Warning, or Error function before the buffers are reinitialized, the explanation text remains in memory and is appended to the message.

The following example shows one way this could occur.

The Message Catalog might contain an entry such as this:

Example of a Message Catalog entry with message text and explanation text

MsgGetText is used to assign the Message Catalog entry to a variable for further processing.


&PartDesc = MsgGetText(30000, 5, "Amana Radar Range");
/** Process order **/
WinMessage("Your Kitchen Upgrade Order has been processed");

The WinMessage dialog displays the explanation text appended to the intended message:

Example of a WinMessage dialog with explanation text appended

This example shows a simple workaround to clear the buffers using MsgGet.


&PartDesc = MsgGetText(30000, 5, "Amana Radar Range");
/** Process order **/
&Dummy = MsgGet(0,0, " ");
WinMessage("Your Kitchen Upgrade Order has been processed"); 

Restrictions on Use in PeopleCode Events

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 unnecessary restrictions, you should always pass an appropriate value in the WinMessage style parameter.

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

If the style parameter specifies more than one button, or if the style parameter is omitted, WinMessage returns a value based on user response and interrupts processing until the user has clicked one of the buttons. This makes it a "user think-time" function, subject to the same restrictions as other think-time functions which means that it cannot be used in any of the following PeopleCode events:

  • SavePreChange.

  • Workflow.

  • RowSelect.

  • SavePostChange.

  • Any PeopleCode event that fires as a result of a ScrollSelect (or one of its relatives) function calls, or a Select (or one of its relatives) Rowset class method.

See Think-Time Functions.

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.

Message Box Icons

In the PeopleSoft Pure Internet Architecture, you can’t change the icon of a message box. You can change the number and type of buttons, as well as the default button, but the message always displays with the warning icon (a triangle with an exclamation mark in it.)

Parameters

Parameter

Description

Message

Text displayed in message box. Normally you want to use the MsgGet or MsgGetText function to retrieve the message from the Message Catalog.

Title

Title of message box.

Style

Either a numerical value or a constant specifying the contents and behavior of the dialog box. This parameter is calculated by cumulatively adding either a value or a constant from each of the following categories:

Category

Value

Constant

Meaning

Buttons

0

%MsgStyle_OK

The message box contains one push button: OK.

1

%MsgStyle_OKCancel

The message box contains two push buttons: OK and Cancel.

2

%MsgStyle_AbortRetryIgnore

The message box contains three push buttons: Abort, Retry, and Ignore.

3

%MsgStyle_YesNoCancel

The message box contains three push buttons: Yes, No, and Cancel.

4

%MsgStyle_YesNo

The message box contains two push buttons: Yes and No.

5

%MsgStyle_RetryCancel

The message box contains two push buttons: Retry and Cancel.

Returns

If the style parameter is provided, WinMessage optionally returns a Number value. If the style parameter is omitted, WinMessage optionally returns a Boolean value: True if the OK button was clicked, otherwise it returns False.

The return value is zero if there is not enough memory to create the message box.

If the style parameter is provided, WinMessage returns one of the following Number values:

Value

Constant

Meaning

-1

%MsgResult_Warning

Warning was generated.

1

%MsgResult_OK

OK button was selected.

2

%MsgResult_Cancel

Cancel button was selected.

3

%MsgResult_Abort

Abort button was selected.

4

%MsgResult_Retry

Retry button was selected.

5

%MsgResult_Ignore

Ignore button was selected.

6

%MsgResult_Yes

Yes button was selected.

7

%MsgResult_No

No button was selected.

Example

The following example displays a message dialog box with Yes and No buttons. The message is taken from the Message Catalog. The message displayed looks like this:

Message with Yes/No buttons

When the end user clicks the Yes or No button, a result is passed back that the program uses to control branching.

/* Displays Yes/No buttons in message box.  */
&RESULT = WinMessage(MsgGetText(30000, 1, "Message not found."), 4, "Test Application");
if &RESULT = %MsgResult_Yes then
   /* Yes button was pressed -- do Yes button stuff */
else
   /* No button was pressed -- do No button stuff */
end-if;

Syntax

WriteToLog(AppFenceSetting, String)

Description

Use the WriteToLog function to write String to either the application server or the TraceSQL log file.

The WriteToLog function writes String to the TraceSQL log file if AppFenceSetting is less than or equal to the current application log fence (AppLogFence) setting in the application server configuration file (PSAPPSRV.CFG.)

Note: This is distinct from the PeopleTools LogFence capability which applies to PeopleTools level logging.

The WriteToLog function writes String to the TraceSQL log file in PSAPPSRV.CFG if any of the following trace options is turned on.

  • TracePPR

  • TraceSQL

  • TracePC

  • TracePIA

If any change is made to the trace options in PSAPPSRV.CFG, you must restart both the application server and web server so that the change takes effect.

The debugging options for a Web Profile also affects the WriteToLog function. If any of the following page fields are selected (checked), the WriteToLog function writes String to the TraceSQL log file.

  • Show Layout

  • Show Overlapping Fields

  • Show Stylesheet Inline HTML

  • Show JavaScript Inline HTML

  • Generate HTML for Testing

  • Create File from PIA HTML Page

If the above conditions are not true, the WriteToLog function writes String to the application server log file.

Related Links

Setting Up the PeopleCode Debugger

Parameters

Parameter

Description

AppFenceSetting

Specify the level at which logging should occur, if AppFenceSetting is less than or equal to the current application log fence. You can use either a number or a constant value. The values are:

Value

Description

%ApplicationLogFence_Error

Allow all levels of errors to be written to the log. This is the lowest setting.

%ApplicationLogFence_ Warning

Allowing only warnings or higher to be written to the log.

%ApplicationLogFence_ Level1

Allow only this level of errors or higher to be written to the log.

%ApplicationLogFence_ Level2

Allow only this level of errors or higher to be written to the log.

%ApplicationLogFence_ Level3

Allow only this level of errors to be written to the log.

Parameter

Description

String

Specify the message text to be written to the log file.

Returns

None.

Example

WriteToLog(%ApplicationLogFence_Level2, "MYAPP" | &Somestring);

Syntax

Year(dt)

Description

Use the Year function to derive the year component of a Date value.

Parameters

Parameter

Description

dt

A Date value from which to derive the year component.

Returns

Returns a Number value between 1900 and 2078 equal to the year component in dt.

Example

The example sets &GRAD_YEAR to 1976:

&GRAD_DATE = DateValue("10/04/1976");
&GRAD_YEAR = Year(&GRAD_DATE);