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
|
Field or Control |
Definition |
|---|---|
| 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
|
Field or Control |
Definition |
|---|---|
| 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.
Image: Example of a Message Catalog entry with message text and explanation text
The Message Catalog might contain an entry such as this:
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");
Image: Example of a WinMessage dialog with explanation text appended
The WinMessage dialog displays the explanation text appended to the intended message:
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
|
Field or Control |
Definition |
|---|---|
| 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 pushbutton: OK. |
|
1 |
%MsgStyle_OKCancel |
The message box contains two pushbuttons: OK and Cancel. |
|
|
2 |
%MsgStyle_AbortRetryIgnore |
The message box contains three pushbuttons: Abort, Retry, and Ignore. |
|
|
3 |
%MsgStyle_YesNoCancel |
The message box contains three pushbuttons: 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
Image: Message with Yes/No buttons
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:
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
Parameters
|
Field or Control |
Definition |
|---|---|
| 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. |
|
Field or Control |
Definition |
|---|---|
| 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
|
Field or Control |
Definition |
|---|---|
| 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);