PeopleCode Built-in Functions and Language Constructs: P-Q

The PeopleCode built-In functions and language constructs beginning with the letters P and Q are listed in alphabetical order within this topic.

Syntax

PanelGroupChanged()

Description

Use the PanelGroupChanged function to determine whether a component has changed since the last save, whether by the user or by PeopleCode.

Note: The PanelGroupChanged function is supported for compatibility with previous releases of PeopleTools. New applications should use the ComponentChanged function instead.

Syntax

PingNode(MsgNodeName)

Description

Use the PingNode function to ping the specified node. It returns an XmlDoc object that you must go through to find the status of the node.

Parameters

Field or Control	Definition
`MsgNodeName`	Specify the name of the message node you want to ping, as a string.

Returns

An XmlDoc object. The node in the XmlDoc object with the name of status contains information about the node you pinged.

Example

Local XmlDoc &ErrorInfo;

&ErrorInfo = PingNode("TESTNODENAME");
   &Root = &ErrorInfo.DocumentElement;
   &MsgNodeArray = &Root.GetElementsByTagName("msgnode");
   For &M = 1 To &MsgNodeArray.Len
      &MsgNode = &MsgNodeArray [&M];
      &MsgText = &MsgNode.FindNode("status").NodeValue;
      If &MsgText <> "Success (117,73)" Then
         Error ("Web Server not available for web service");
      End-If;
   End-For;

Syntax

PriorEffDt(field)

Description

Use the PriorEffDt function to return the value of the specified field from the record with the prior effective date. This function is valid only for effective-dated records.

If the record contains an effective sequence number field, the value of this field is compared along with the effective-date field when the prior effective date/effective record sequence is determined. Therefore, if there is an effective-sequence number, it's possible that the effective-date field will be the same as the current record, but the sequence number would be earlier.

If a prior record does not exist, the statement is skipped. If the PriorEffDt function is not a top-level statement, that is, if it's contained with a compound statement or a loop, the statement is skipped and execution begins with the next top-level statement.

In the following example, execution skips to the top If statement:

If ACTION <> "REH" Then  /* skip to here if PriorEffdt fails to find prior record */ 
   If    STD_HOURS <> PriorEffdt(STD_HOURS) And  
         Day(EFFDT) <> 1 Then 
      Error MsgGet(30000, 8, "Meldung nicht vorhanden - WAZ bzw. Beschäftigungsgradänderungen sind nur zum ersten eines Monats zulässig.") 
   End-If; 
End-If; 
/* if PriorEffdt fails, run to here directly */

Example

If CURRENCY_CD = PriorEffdt(CURRENCY_CD) Then
      Evaluate ACTION
      When = "PAY" 
         If ANNUAL_RT = PriorEffdt(ANNUAL_RT) Then
            Warning MsgGet(1000, 27, "Pay Rate Change action is chosen and Pay Rate has not been changed.");
         End-if;
         Break;
      When = "DEM" 
         If ANNUAL_RT >= PriorEffdt(ANNUAL_RT) Then
            Warning MsgGet(1000, 29, "Demotion Action is chosen and Pay Rate has not been decreased.");
         end-if;
      When-other
      End-evaluate;
      WinMessage("This message appears after executing either of the BREAK statements or after all WHEN statements are false");
   End-if;

Syntax

PriorRelEffDt(search_field, fetch_field)

Description

Use the PriorRelEffDt function to locate the prior occurrence of the search_field with the prior effective date (and effective-sequence number if specified), then return the value of the specified fetch_field corresponding to the search_field. The return value is an Any data type. Typically, this function is used to retrieve values for related display fields.

This function is valid only for effective-dated records.

If a prior record does not exist, then the statement is skipped. If the PriorRelEffDt function isn't a top-level statement, that is, if it's contained within a compound statement or a loop, the statement is skipped and execution restarts with the next top-level statement.

Syntax

PriorValue(fieldname)

Description

Use the PriorValue function in FieldEdit and FieldChange PeopleCode to obtain the prior value of a buffer field that the user just changed. It returns the value that was in the buffer field before the user changed it, not the value of the field the last time the component was saved.

PriorValue gives correct results only in FieldEdit and FieldChange PeopleCode, and only for the buffer field where the function is executing. If you pass another field name to the function, it returns the current value of the buffer field, not the prior value.

Parameters

Field or Control	Definition
`fieldname`	The name of the record field. For correct results, this must be the name of the field where the call to PriorValue executes.

Returns

Returns an Any value equal to the value that was in the current buffer field immediately prior to the last edit.

Example

The following example from FieldChange PeopleCode gets the prior value of a field:

&PRIOR = PriorValue(QUANTITY); 
DERIVED_TEST.TOTAL_AMT = (DERIVED_TEST.TOTAL_AMT  -  &PRIOR) + QUANTITY;

Syntax

Product(numlist)

where numlist is an arbitrary-length list of numbers in the form

n1 [, n2]. . .

Description

Use the Product function to multiply all the numbers in numlist and returns the product as a Number data type. The numbers in the list can be any number expressed as a number, variable, or expression.

Returns

Returns a Number value equal to the product of the numbers in numlist.

Example

The example sets &N2 to 96:

&N2 = Product(4,80,0.3);

Syntax

Prompt(title, heading, {fieldlist | &Record})

where fieldlist is an arbitrary-length list of fields in the form:

field1 [, label1 [, tempvar1]] [, field2 [, label2 [, tempvar2]]]...

Note that the label parameter is required before the temporary variable.

Description

Important! The Prompt function is not supported in fluid applications. A PeopleCode error will occur if the function is used in a fluid application.

Use the Prompt function to display a page prompting the user to insert values into one or more text boxes. If the user cancels the page, any entered values are discarded and the function returns False. When the prompt page is displayed, the text boxes are initially filled with default values from the fields in fieldlist. The user can change the values in the text boxes, then if the user clicks OK, the values are placed either into the buffer for the appropriate field, or into a temporary variable, if a tempvar for that field is provided in the function call.

Prompt can also take a record object. This is primarily used with the Query classes, when running a query, to prompt the end user for the prompt values of a query.

Prompt is a think-time function, and as such cannot be used during the PeopleCode attached to the following 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.

Prompt should also not be called in any PeopleCode event that fires as a result of a ScrollSelect or its relatives, or a Select Rowset class method or its relatives.

Parameters

Field or Control	Definition
`title`	Used as the title for the page.
`heading`	Displayed in the page above the fields. If a zero-length string ("") is passed, the heading line is omitted in the page.
`fieldlist` \| `&Record`	A list of one or more fields; each field in the list consists of a [`recordname`.]`fieldname` followed by an optional label and an optional temporary variable for storing the input value. The label parameter is required if you supply the temporary variable parameter. Instead of a list of fields, you can also specify an already instantiated and populated record object.
`field`	The name of the field being prompted for, the form [`recordname`.]`fieldname`.
`label`	Optional label for the prompted field. If this parameter is omitted, the field RFT Long value is used. This parameter is required before the `tempvar` parameter.
`tempvar`	Optional temporary variable to receive the user-entered value. If this parameter is omitted, the value is placed into the buffer for the field specified. Using a temp variable enables the PeopleCode program to inspect and process the entered value without affecting the buffer contents.

Returns

Optionally returns a Boolean value:

False if the user clicks the Cancel button.
True if the user clicks the OK button.

Example

The following example prompts for a single field, using calls to the MsgGetText function to retrieve values for the window title and prompt, and places the result into FISCAL_YEAR field:

Prompt(MsgGetText(5000, 182, " "), MsgGetText(5000, 184, " "), FISCAL_YEAR);

To following example places the results of the prompt into a temporary variable:

Prompt("Change Voucher", "", VOUCHER_ID, "Change Voucher ID to", &NEW_VOUCHER_ID);

The following code is in the USA push button FieldChange PeopleCode, and calls for the single field as shown in the page.

When = PAGE.PERSONAL_DATA1 
        /* Administer Global Personnel - USA Flag Btn on PERSONAL_DATA1 Page */ 
         Prompt("US Social Security Number", "", PERSONAL_DATA.SSN); 
         Break;

Syntax

Proper(string)

Description

Use the Proper function to capitalize the first letter in a text string and any other letters in a text string that follow any character other than another letter. It also converts all other letters in a text string to lowercase. Punctuation and other characters that have no case sensitivity are not changed.

Returns

Returns a String value with the first character of each word capitalized.

Example

The example sets the value of &BADKD to "K. D. Lang".

&BADKD = Proper("k.  d.  LANG")

Syntax

PublishXmlDoc(&XmlDoc, Message.MessageName [, Node.NodeName])

Description

Use the PublishXmlDoc function to send an asynchronous message that is based on an XmlDoc object.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class Publish method instead.

The XmlDoc object must already be instantiated and populated. The message included in the function call should be an unstructured message, that is, one that isn't based on a hierarchical record structure.

If you want to retrieve an XmlDoc message that was sent asynchronously, use the GetMessageXmlDoc built-in function.

If you want to handle an XmlDoc as a Message object, you need to define a Message object with a hierarchical structure and migrate the data in the XmlDoc object into the Message object.

Parameters

Field or Control	Definition
`&XmlDoc`	Specify an already instantiated and populated XmlDoc object that you want to send as an asynchronous message.
`MessageName`	Specify an already existing nonrowset-based message, prefaced with the reserved word Message.
`NodeName`	Specify a node. This is for Sender Specified Routing (SSR), prefixed with the reserved word Node. The node defines the target for the published message.

Returns

A Boolean value: True if the message was successfully published, False otherwise.

Example

Local XmlDoc &MyDoc;

. . .

PublishXmlDoc(&MyDoc, Message.MyXmlMessage, Node.MyNode);

Syntax

PutAttachment(URLDestination, DirAndSysFileName, DirAndLocalFileName[, LocalDirEnvVar[, PreserveCase[, AllowLargeChunks]]])

Description

Use the PutAttachment function to upload a file from the file system of the application server to the specified storage location. The file system of the application server includes any directories accessible from the application server including those on local disks as well as on network shares.

Note: It is the responsibility of the calling PeopleCode program to store the specified file name for further use.

If a file exists at a particular place on a storage location and then another file with the same name is uploaded to that same place on that same storage location, the original file will be silently overwritten by the new file. If that is not the behavior you desire, it is recommended that you implement PeopleCode to guarantee the ultimate uniqueness of either the name of the file at its place on the storage location or the name of its place (the subdirectory) on the storage location.

Note: If the web server load-balances via Jolt session pooling, then it may be difficult to anticipate which application server machine will be expected to have the specified file.

Note: If the specified destination subdirectories do not exist at the storage location, this function tries to create them.

Additional information that is important to the use of PutAttachment 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.

File System Considerations

If you are uncertain which type of file system the file is going to be transferred from, either a Unix or Windows system, you should simply specify a file name for the DirAndLocalFileName parameter and either explicitly set the LocalDirEnvVar parameter or accept its default value, which is “TMP” (indicating that the value of the TMP environment variable will be used).

The following code example works for Windows systems, but not Unix systems:

&retcode = PutAttachment(&FTPINFO, &TARGETFILENAME, "c:\temp\resume.doc");

The following code example works for Unix systems, but not Windows systems:

&retcode = PutAttachment(&FTPINFO, &TARGETFILENAME, "/tmp/resume.doc");

The following two examples work for both Windows and Unix systems:

&retcode = PutAttachment(&FTPINFO, &TARGETFILENAME, "resume.doc");

&retcode = PutAttachment(&FTPINFO, &TARGETFILENAME, "resume.doc", "PS_CFG_HOME");

Parameters

Field or Control	Definition
`URLDestination`	A reference to a URL. This can be either a URL identifier the form URL.`URL_ID`, or a string. This (along with the corresponding `DirAndSysFileName`) indicates a file's destination location. Note: When the `URLDestination` 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 at the storage location. This is appended to `URLDestination` to form the full URL where the file will be transferred to. 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.
`DirAndLocalFileName`	The name, relative path name, or full path name of the source file on the application server. This parameter takes a string value. If you specify only a name or a relative path name for the source file, the file will be searched for in or relative to: The directory indicated by the value of the environment variable specified by the `LocalDirEnvVar` parameter. The directory indicated by the value of the TMP environment variable if the `LocalDirEnvVar` parameter has not been specified. Important! If a reference to the uploaded file is to be stored in a file reference table, then the PeopleCode that calls PutAttachment must restrict the length of the file name portion of the value of the `DirAndLocalFileName` parameter to 64 characters. Otherwise, that file name will be too long to be stored in that file reference table as a user file name.
`LocalDirEnvVar`	This optional parameter takes a string value. If `LocalDirEnvVar` is specified, then its value will be prefixed to the value of the `DirAndLocalFileName` parameter to form the full path name of the source file on the application server’s file system. With this parameter, you can avoid the need to hard-code the full path name. If `LocalDirEnvVar` is not specified and the value of the `DirAndLocalFileName` parameter is already a full path file name, then that value will itself be used as the full path name of the source file on the application server. If `LocalDirEnvVar` is not specified and the value of the `DirAndLocalFileName` parameter is not a full path file name, then the value of the TMP environment variable will be prefixed to the value of the `DirAndLocalFileName` parameter to form the full path name of the source file on the application server. Note: Do not specify `LocalDirEnvVar` if you use an absolute path for the `DirAndLocalFileName` parameter. Note: In order to use the optional parameter `PreserveCase,` you must pass some value for `LocalDirEnvVar.` If you want to use the default behavior of `LocalDirEnvVar` and also use `PreserveCase,` you can specify "" (the empty string) for `LocalDirEnvVar.` Then the function behaves as if no value is specified. In this situation, if you wish to use the TMP environment variable, it must be explicitly specified.
`PreserveCase`	Specify a Boolean value to indicate whether the case of the extension of the file specified in `DirAndSysFileName` is preserved at the storage location: True, preserve the case, False, convert the file name extension in `DirAndSysFileName` to all lower case letters. The default value is False. For a particular file, save the value specified for this parameter so that it may be used when later calling other file-processing built-in functions on this file. 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. This is an optional parameter.
`AllowLargeChunks`	Specify a Boolean value to indicate whether to allow large chunks. If the value specified in the Maximum Attachment Chunk Size field on the PeopleTools Options page is larger than is allowed for retrieval, then the system breaks the file upload into the largest sized chunks allowed. If `AllowLargeChunks` is set to True, this behavior can be overridden so that it is possible for an end user to upload a file in chunks that are too large for the system to retrieve. If `AllowLargeChunks` is set to False, the system will use the largest size chunk that is allowed for retrieval, or the configured chunk size, whichever is smaller. The default value is False. Note: If the chunks are too big to be retrieved, then any file retrieval built-in function, such as GetAttachment, will fail. Note: The `AllowLargeChunks` parameter is only applicable when the storage location is a database record. It has no impact when the storage location is an FTP site or an HTTP repository, since attachments at those locations are never chunked. See PeopleTools Options This is an optional parameter.

Returns

You can check for either an integer or a constant value:

Numeric Value	Constant Value	Description
0	%Attachment_Success	File was transferred successfully.
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.
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.
4	%Attachment_NoDiskSpaceAppServ	No disk space on the application 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

The following uploads the file, HRarchive/NewHire/11042000resume.txt, to the FTP server from c:\NewHires\resume.txt on the application server machine.

&retcode = PutAttachment("ftp://anonymous:hobbit1@ftp.ps.com/HRarchive/", "NewHire/11042000resume.txt", "C:\NewHires\resume.txt");

Syntax

Quote(String)

Description

Use the Quote function to enclose a string in single quotation marks. This function also can be used to put quotation marks around SQL statements.

Parameters

Field or Control	Definition
`String`	Specify the string you want to enclose in single quotation marks.

Returns

The string specified by String enclosed in single quotation marks.

Example

The following code returns 'Bob':

&QuotedString = Quote("Bob");

The following code returns 'Bob''s' (two single quotes to represent the apostrophe)

&QuotedString = Quote("Bob's");

The following code returns '%'' OR USER ID LIKE ''%':

&QuotedString = Quote("%' OR USERID LIKE '%");

PeopleCode Built-in Functions and Language Constructs: P-Q

PanelGroupChanged

Syntax

Description

Related Links

PingNode

Syntax

Description

Parameters

Returns

Example

PriorEffDt

Syntax

Description

Example

PriorRelEffDt

Syntax

Description

Related Links

PriorValue

Syntax

Description

Parameters

Returns

Example

Product

Syntax

Description

Returns

Example

Prompt

Syntax

Description

Related Links

Parameters

Returns

Example

Proper

Syntax

Description

Returns

Example

PublishXmlDoc

Syntax

Description

Related Links

Parameters

Returns

Example

PutAttachment

Syntax

Description

File System Considerations

Parameters

Returns

Example

Quote

Syntax

Description

Parameters

Returns

Example