PeopleCode Built-in Functions and Language Constructs: V
The PeopleCode built-In functions and language constructs beginning with the letter V are listed in alphabetical order within this topic.
Syntax
Value(string)Description
Use the Value function to convert a string representing a number to the number.
To convert a number using the user's local format for the number, use the ValueUser function.
Parameters
Parameter |
Description |
|---|---|
string |
A String value representing a number. |
Returns
Returns the Number value represented by string.
Example
The example sets &VAL1 to 5.25 and &VAL2 to 12500:
&VAL1 = Value("5.25");
&VAL2 = Value("12,500");Syntax
ValueUser(str)Description
Use the ValueUser function to convert a string representing a number to the number, using the locale-specific format for the current user to interpret the number. For example, if the locale or user level personalization settings specify to use a comma as the decimal separator, the number will be interpreted based on that setting, instead of the default for the database.
To convert a number without using the user's format for the number, use the Value function.
Parameters
Parameter |
Description |
|---|---|
str |
Specify the string value representing a number that you want converted to a number. |
Returns
Returns the number value represented by str.
Example
The example sets &VAL1 to 5.25 and &VAL2 to 12500:
&VAL1 = ValueUser("5.25");
&VAL2 = ValueUser("12,500");Syntax
VerifyHash(cleartext_string, salt_string, hashed_string)Description
Use the VerifyHash function to verify that the combination of an input clear text string plus salt string generates a hashed value that is the same as a hashed string generated by the HashWithSalt function.
The VerifyHash function is general purpose, in that it can be used for any clear text string that has been hashed with the HashWithSalt function. Use the VerifyOprPassword function instead when the input clear text is a user’s password that has been stored in the database as a hashed value.
Parameters
Parameter |
Description |
|---|---|
cleartext_string |
Specifies the string to be verified as a string value. |
salt_string |
Specifies the salt value as a string value. Important! The salt value must be exactly the same as the randomly generated salt value used to hash the original string. |
hashed_string |
Specifies the hashed value to be compared to the output of the hash algorithm. |
Returns
A Boolean value: True if the input string plus salt value generate the hashed text, False otherwise.
Example
Local array of string &salt;
&salt = SecureRandomGen();
&hashedtext = HashWithSalt(&cleartext, &salt [1]);
MY_REC.MY_HTEXT = &hashedtext;
MY_REC.MY_SALT = &salt [1];
/*** other processing ***/
If Not VerifyHash(&cleartext, MY_REC.MY_SALT, MY_REC.MY_HTEXT) Then
rem they don't match, throw error;
Error MsgGet(10001, 1, "Message not found");
End-If;Syntax
VerifyOprPassword(O_or_U, user_ID, cleartext_pwd)Description
Use the VerifyOprPassword function to verify that an input clear text string matches the password hashed by either HashWithSalt or Hash and stored in the PSOPRDEFN table.
Parameters
Parameter |
Description |
|---|---|
O_or_U |
Indicates which PSOPRDEFN field to use when matching the user ID:
|
user_ID |
Specifies the user ID as a string value. |
cleartext_pwd |
Specifies the input password as a clear text string. |
Returns
A Boolean value: True if the input password matches the hashed password stored in the database, False otherwise.
Example
If Not VerifyOprPassword("O", %UserId, "user_password") Then
rem they don't match, throw error;
Error MsgGet(48, 18, "Message not found");
End-If;Syntax
ViewAttachment(URLSource, DirAndSysFileName, UserFileName [, NewWindow[, PreserveCase]])Description
Use the ViewAttachment function to download a file from its source storage location and open it locally on the end-user machine.
By using the UserFileName parameter, the copy of the file to be viewed may be given a different name than the file at the storage location.
Additional information that is important to the use of ViewAttachment can be found in the PeopleTools: PeopleCode Developer's Guide:
PeopleTools supports multiple types of storage locations.
Certain characters are illegal in file names; other characters in file names are converted during file transfer.
Non-ASCII file names are supported by the PeopleCode file attachment functions.
The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.
Because ViewAttachment is interactive, it is known as a “think-time” function, and is restricted from use in certain PeopleCode events.
See Restrictions on Invoking Functions in Certain PeopleCode Events.
You can use a file extension list to identify file types to accept or reject when using this function.
See Using Administration Utilities.
Security Considerations
PeopleTools includes an X-Content-Type-Options: nosniff response header with content retrieved using the ViewAttachment built-in function.
Viewing a file involves requesting that it be opened. The result of the open action depends upon the extension of the file name and the application associated with that extension. Keep in mind that the act of opening a file with certain extensions (for example, .exe or .bat) results in the file being executed when it is opened. If you do not want specific file type to be handled this way, you must prevent the end user from viewing the requested file.
When the end user views attachments using the ViewAttachment function, some browsers treat documents as HTML regardless of file extension, and thus execute embedded JavaScript. You may want to write a PeopleCode program to allow only specific file extensions to be viewed.
Alternatively, you can use a file extension list to restrict the file types that can be uploaded to or downloaded from your PeopleSoft system.
See Restricting the File Types That Can Be Uploaded or Downloaded.
Problems Downloading Files
The combination of the attachmentExtraWindow web profile property and some of Internet Explorer’s settings can silently interfere with downloading and opening of files with the ViewAttachment function. For more information, see the documentation on the attachmentExtraWindow web profile property.
See Configuring Custom Properties.
In addition, if you need to use the SetLanguage built-in function to change languages, invoke SetLanguage prior to invoking ViewAttachment or DetachAttachment. You must place the call to SetLanguage in a different PeopleCode program and event from the PeopleCode program and event that invokes ViewAttachment or DetachAttachment.
Parameters
Parameter |
Description |
|---|---|
URLSource |
A reference to a URL. This can be either a URL identifier in the form URL.URL_ID, or a string. This, along with the DirAndSysFileName parameter, indicates the file's source location. Note: When the URLSource parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value. |
DirAndSysFileName |
The relative path and file name of the file on the file server. This is appended to URLSource to make up the full URL where the file is transferred from. This parameter takes a string value Note: Because the DirAndSysFileName parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter. |
UserFileName |
The name associated with the copy of the file to be viewed (may be different than the name of the file at the storage location). |
NewWindow |
Specify if the browser should try to use a new window to display the attachment. This parameter takes a Boolean value. The default is True. |
PreserveCase |
Specify a Boolean value to indicate whether when searching for the file specified by the DirAndSysFileName parameter, its file name extension is preserved or not; True, preserve the case of the file name extension, False, convert the file name extension to all lowercase letters. The default value is False. Warning! If you use the PreserveCase parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors. |
Returns
You can check for either an integer or a constant value:
|
Numeric Value |
Constant Value |
Description |
|---|---|---|
|
0 |
%Attachment_Success |
File was transferred successfully. Important! If file type restrictions are changed so that access to a previously uploaded file is now blocked, a call to ViewAttachment will return %Attachment_Success, even though the file and its contents are not displayed. |
|
1 |
%Attachment_Failed |
File transfer failed due to unspecified error. The following are some possible situations where %Attachment_Failed could be returned:
|
|
2 |
%Attachment_Cancelled |
File transfer didn't complete because the operation was canceled by the end user. |
|
3 |
%Attachment_FileTransferFailed |
File transfer failed due to unspecified error during FTP attempt. The following are some possible situations where %Attachment_FileTransferFailed could be returned:
|
|
7 |
%Attachment_DestSystNotFound |
Cannot locate destination system for FTP. The following are some possible situations where %Attachment_DestSystNotFound could be returned:
|
|
8 |
%Attachment_DestSysFailedLogin |
Unable to login to destination system for FTP. The following are some possible situations where %Attachment_DestSysFailedLogin could be returned:
|
|
9 |
%Attachment_FileNotFound |
Cannot locate file. The following are some possible situations where %Attachment_FileNotFound could be returned:
|
Example
&retcode = ViewAttachment(URL.MYFTP, ATTACHSYSFILENAME, ATTACHUSERFILE);
An example of the ViewAttachment function is provided in the demonstration application delivered in the FILE_ATTACH_WRK derived/work record. This demonstration application is shown on the PeopleTools Test Utilities page.
Syntax
ViewContentURL(URL)Description
Use the ViewContentURL function to open a new browser window and navigate to the location specified by the URL parameter.
Important! Use the ViewContentURL function in classic applications only. See Transfer and Modal Functions for more information on which functions are available for which purposes.
The content specified by the URL is not wrapped by the portal template. Therefore, you can use this function when you want to display third-party content. If you want to wrap the content in the portal template, use the ViewURL function.
This is a deferred execution command: the browser is launched after any executing PeopleCode has run to completion. This function automatically launches a new browser window.
Considerations for Opening Local Files
Note: Due to restrictions inherent in certain browsers, you cannot use ViewContentURL to open a file on a local file system. See the PeopleTools Browser Compatibility Guide (Oracle Support Document 704492.1) on My Oracle Support for more information.
For browsers that do support opening a file on a local file system, you must use a URL style path (file://path_name) instead of a UNC style path (\\path_name). For example:
ViewContentURL("file://PT-NFS01/PSUSERWS/temp/TVN/81X-PATCHES.TXT");Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
Returns
None.
Example
If &MyPage Then
ViewURL(URL.MYPAGE);
Else
ViewContentURL("http://www.oracle.com");
End-If;Syntax
ViewContentURLClassic(URL [, new_window]) Description
Use the ViewContentURLClassic function to navigate to the classic content specified by the URL parameter. Use the ViewContentURLClassic function as an alternative to the Transfer function or the ViewContentURL function. The result of this function depends on the source from which it was invoked:
When invoked from within a fluid activity guide or master/detail component with AJAX transfers enabled, the classic content replaces the target content area within the fluid activity guide or master/detail wrapper.
When invoked from within a fluid activity guide or master/detail component with AJAX transfers disabled:
If the source component is a classic component, the classic content replaces the target content area within the fluid activity guide or master/detail wrapper. This is the same as when AJAX transfers are enabled.
If the source component is a fluid component, the classic content completely replaces the current window. This is similar to how the ViewURLTop function operates.
When invoked from outside a fluid activity guide or master/detail component the classic content completely replaces the current window. (This is similar to how the ViewURLTop function operates.)
This is a deferred execution command: the browser is launched after any executing PeopleCode has run to completion.
Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
new_window |
Note: This parameter is ignored and has no effect. |
Returns
None.
Example
Local string &strURL = GenerateComponentContentURL(%Portal, %Node, MenuName.PROCESSMONITOR, "GBL", Component.PROCESSMONITOR, Page.PMN_PRCSLIST, "U");
ViewContentURLClassic(&strURL);
Syntax
ViewContentURLFluid(URL [, new_window]) Description
Use the ViewContentURLFluid function to navigate to the fluid content specified by the URL parameter. Use the ViewContentURLFluid function as an alternative to the Transfer function or the ViewContentURL function. The result of this function depends on the source from which it was invoked:
When invoked from within a fluid activity guide or master/detail component with AJAX transfers enabled, the fluid content replaces the target content area within the fluid activity guide or master/detail wrapper.
When invoked from within a fluid activity guide or master/detail component with AJAX transfers disabled, the fluid content completely replaces the entire browser window. This is similar to how the ViewURLTop function operates.
When invoked from outside a fluid activity guide or master/detail component, the fluid content completely replaces the entire browser window. This is similar to how the ViewURLTop function operates.
This is a deferred execution command: the browser is launched after any executing PeopleCode has run to completion.
Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
new_window |
Note: This parameter is ignored and has no effect. |
Returns
None.
Example
Local string &sURL = GenerateComponentContentURL(%Portal, %Node, MenuName.HRSC_HIDDEN_FL, "GBL", Component.HR_PSEL_FLU, Page.HR_PSEL_FLU, %Action_UpdateDisplay);
ViewContentURLFluid(&sURL);Syntax
ViewContentURLModeless(URL, [modal_options])Description
Use the ViewContentURLModeless function to open a modeless modal window displaying the PeopleSoft component content (either classic or fluid) specified by the URL parameter. The user must dismiss the modeless window before continuing work in the page from which the modeless window was called.
Important! Use this function within fluid applications only.
Modeless Windows
In addition to modal secondary windows, you can create modeless secondary windows. A modeless window is different from a modal window launched by any of the DoModal* functions in that its state is separate from that of the parent, launching component. When a modeless window is launched from a classic component using the TransferModeless function, the modeless window does not mask the parent window, which allows the user to update the modeless and parent window from the same browser session at the same time.
Note: While the title bar of a modeless window includes an X (or cancel) button, it cannot include any custom buttons.
Important! Only one active child modeless window can be open at one time. Therefore, after opening a modeless child window from the parent, you cannot open a second modeless child window from that modeless window. However, you can open a modal window from that modeless window.
Parameters
Parameter |
Description |
|---|---|
URL_str | URL.URL_ID |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
modal_options |
Specifies custom modal options as a String value. See Modal Options for more information. |
Returns
None.
Example
Local string &sUrl;
Local string &sMenuTitle;
Local string &sOptions;
&sUrl = GenerateComponentContentURL(%Portal, %Node, MenuName.ROLE_CUSTOMER, %Market, Component.BI_CONTACT_INFO_SS, Page.BI_CR_CARD_LIST_SS, "U");
&sMenuTitle = EscapeHTML(MsgGetText(11124, 524, "Message Not Found: New Window"));
&sOptions = "sTitle@" | &sMenuTitle | ";width@640;height@400;";
ViewContentURLModeless(&sUrl, &sOptions);
Syntax
ViewURL(URL [, new_window]) Description
Use the ViewURL function to navigate to the location specified by the URL parameter.
This is a deferred execution command: the browser is launched after any executing PeopleCode has run to completion. You can also specify whether the new page launches a new browser, or replaces the current page in the browser.
Note: This function does not issue any kind of warning to the user about losing data. Your application should verify that all data is saved before launching a new page.
The content specified by the URL is automatically wrapped by the portal template. If you do not want to wrap the content in the portal template, use the ViewContentURL function.
Important! While the ViewURL function can be used to launch a fluid component from a classic component, if the classic component will be included in a fluid activity guide or master/detail component, do not use ViewURL or RedirectURL. Use the ViewURLTop function instead.
Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
new_window |
Specify whether the new page is opened in the current browser, or launched in a new browser window. This parameter takes a Boolean value: True to launch a new browser, False to replace the existing page. The default value is False. |
Returns
None.
Example
If &MyPage Then
ViewURL(URL.MYPAGE);
Else
ViewContentURL("http://www.example.com");
End-If;Syntax
ViewURLModeless(URL, [modal_options])Description
Use the ViewURLModeless function to open a modeless modal window displaying the non-component content (for example, an iScript or external content) specified by the URL parameter. The user must dismiss the modeless window before continuing work in the page from which the modeless window was called.
To be displayed within the iframe of the modeless window, the external content and the PeopleSoft application must either reside within the same domain or they must both set the document.domain property to the same value. For more information on how the domain and same-origin is determined, see Same-origin policy.
Important! Use this function within fluid applications only.
Modeless Windows
In addition to modal secondary windows, you can create modeless secondary windows. A modeless window is different from a modal window launched by any of the DoModal* functions in that its state is separate from that of the parent, launching component. When a modeless window is launched from a classic component using the TransferModeless function, the modeless window does not mask the parent window, which allows the user to update the modeless and parent window from the same browser session at the same time.
Note: While the title bar of a modeless window includes an X (or cancel) button, it cannot include any custom buttons.
Important! Only one active child modeless window can be open at one time. Therefore, after opening a modeless child window from the parent, you cannot open a second modeless child window from that modeless window. However, you can open a modal window from that modeless window.
Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
modal_options |
Specifies custom modal options as a String value. See Modal Options for more information. |
Returns
None.
Examples
The following example displays iScript content in a modal window:
Local string &sUrl;
Local string &sMenuTitle;
Local string &sOptions;
&sUrl = GenerateScriptContentURL(%Portal, %Node, Record.WEBLIB_PTNUI, Field.FUNCLIB, "FieldFormula", "IScript_GroupletDiag");
&sMenuTitle = EscapeHTML(MsgGetText(11124, 525, "Message Not Found: iScript"));
&sOptions = "sTitle@" | &sMenuTitle | ";width@600;height@400;");
ViewURLModeless(&sUrl, &sOptions);
The following example displays external content in a modal window:
Local string &sMenuTitle;
Local string &sOptions;
&sMenuTitle = EscapeHTML(MsgGetText(11124, 526, "Message Not Found: Oracle.com"));
&sOptions = "sTitle@" | &sMenuTitle | ";width@600;height@400;");
ViewURLModeless("http://www.oracle.com", &sOptions);
Syntax
ViewURLTop(URL [, new_window]) Description
Use the ViewURLTop function to exit the current context and navigate to the location specified by the URL parameter by always replacing the current window. Use the ViewURLTop function as an alternative to the either the ViewURL or the Transfer function to ensure that when the source component is being displayed within a fluid wrapper (that is, the source classic component is being displayed within a fluid activity guide, a master/detail component, an interactive grouplet, or a modeless window) that the entire current window is replaced with the new content.
Unlike ViewURL, ViewURLTop ignores the new_window parameter. ViewURLTop always exits the current context and completely replaces the current window.
This is a deferred execution command: the new content is displayed after any executing PeopleCode has run to completion.
Note: This function does not issue any kind of warning to the user about losing data. Your application should verify that all data is saved before launching a new page.
Parameters
Parameter |
Description |
|---|---|
URL |
Specify the location to navigate to. You can specify the URL either as a string value or as a URL saved in the URL table using the following format: URL.URL_ID |
new_window |
Note: This parameter is ignored and has no effect. |
Returns
None.
Example
&contentURL = GenerateComponentContentURL(%Portal, %Node, MenuName.QE_FLUID_CR, %Market, Component.QE_CBACK_C1, Page.QE_CBACK_C1, "");
ViewURLTop(&contentURL);