PeopleCode Built-in Functions and Language Constructs: V

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

Field or Control	Definition
`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

Field or Control	Definition
`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

Field or Control	Definition
`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

Field or Control	Definition
`O_or_U`	Indicates which PSOPRDEFN field to use when matching the user ID: `O` – Indicates the OPRID field. `U` – Indicates the USERIDALIAS field.
`user_ID`	Specifies the user ID as a string value.
`cleartext_pwd`	Specifies the input password as a clear text string.

Field or Control

Definition

O_or_U

Indicates which PSOPRDEFN field to use when matching the user ID:

O – Indicates the OPRID field.
U – Indicates the USERIDALIAS field.

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.
See Understanding File Attachment Storage Locations.
Certain characters are illegal in file names; other characters in file names are converted during file transfer.
See File Name Considerations.
Non-ASCII file names are supported by the PeopleCode file attachment functions.
See Attachments with non-ASCII File Names.
The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.
See Considerations When Attaching Text Files.
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.

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

Field or Control	Definition
`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. See Understanding URL Strings Versus URL Objects.
`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: Failed to initialize the process due to some internal error. Failed due to unexpected/bad reply from server. Failed to allocate memory due to some internal error. Failed due to timeout. Failed due to non-availability of space on FTP server. Failed to close SSL connection. Failed due to an unspecified error on the HTTP repository. If the HTTP repository resides on a PeopleSoft web server, then you can configure tracing on the web server to report additional error details. See Enabling Tracing on the Web Server or Application Server.
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: Failed due to mismatch in file sizes. Failed to write to local file. Failed to store the file on remote server. Failed to read local file to be uploaded No response from server. Failed to overwrite the file on remote server.
7	%Attachment_DestSystNotFound	Cannot locate destination system for FTP. The following are some possible situations where %Attachment_DestSystNotFound could be returned: Improper URL format. Failed to connect to the server specified.
8	%Attachment_DestSysFailedLogin	Unable to login to destination system for FTP. The following are some possible situations where %Attachment_DestSysFailedLogin could be returned: Unsupported protocol specified. Access denied to server. Failed to connect using SSL Failed to verify the certificates. Failed due to problem in certificates used. Could not authenticate the peer certificate. Failed to login with specified SSL level. Remote server denied logon. Problem reading SSL certificate.
9	%Attachment_FileNotFound	Cannot locate file. The following are some possible situations where %Attachment_FileNotFound could be returned: Remote file not found. Failed to read remote file.

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.

See Using 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

Field or Control	Definition
`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

Field or Control	Definition
`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

Field or Control	Definition
`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 a modeless window. 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. However, when a modeless window is launched from a fluid component using either the ViewContentURLModeless or ViewURLModeless functions, the parent window is masked and cannot be accessed until the modeless window is dismissed. In this respect and from the user’s perspective, a modeless window launched from a fluid component operates similar to a modal window; but programmatically, its state is separate from that of the parent, launching component.

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

Field or Control	Definition
`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

Field or Control	Definition
`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.PeopleSoft.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 a modeless window. 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. However, when a modeless window is launched from a fluid component using either the ViewContentURLModeless or ViewURLModeless functions, the parent window is masked and cannot be accessed until the modeless window is dismissed. In this respect and from the user’s perspective, a modeless window launched from a fluid component operates similar to a modal window; but programmatically, its state is separate from that of the parent, launching component.

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

Field or Control	Definition
`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

Field or Control	Definition
`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);