PeopleCode Built-in Functions and Language Constructs: E

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

Description

Use the Else keyword to create an else clause in an if block. See If for more information.

Syntax

EnableMenuItem(BARNAME.menubar_name, ITEMNAME.menuitem_name)

Description

Use the EnableMenuItem function to enable (make available for selection) the specified menu item. To apply this function to a pop-up menu, use the PrePopup Event of the field with which the pop-up menu is associated.

If you’re using this function with a pop-up menu associated with a page (not a field), the earliest event you can use is the PrePopup event for the first "real" field on the page (that is, the first field listed in the Order view of the page in Application Designer.)

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.

Parameters

Field or Control	Definition
`menubar_name`	Name of the menu bar that owns the menu item, or, in the case of pop-up menus, the name of the pop-up menu that owns the menu item.
`menuitem_name`	Name of the menu item.

Returns

None.

Example

EnableMenuItem(BARNAME.MYPOPUP1, ITEMNAME.DO_JOB_TRANSFER);

Syntax

EncodeSearchCode(search_string)

Description

Use this function in special circumstances to encode a search string so that it is not “tokenized” by the search provider.

Note: Tokenization is the process that the search provider uses to split both indexed words as well as search terms containing special characters into multiple alphanumeric tokens. The index is generated using these tokens; therefore, at search time, the search provider also splits a similar search term into tokens to search the index. For special circumstances, PeopleSoft search definitions also allow that specific attributes can be encoded so that they are not tokenized during index generation. Similarly, to perform a search on attributes that have been marked for encoding on the Advanced Properties page, use this function to return an encoded search string to match the encoding done when the attribute was indexed..

This function converts all non-alphanumeric characters and the letters z and Z to hexadecimal values. A string that has been converted is terminated with Z. A string that does not include any special characters that require conversion remains unchanged as the return value. The following examples show the string input to and output from the EncodeSearchCode function.

Input: abcz123456
Output: abc7A123456Z — The z was converted to hexadecimal 7A and the string was terminated with Z.
Input: abc123456
Output: abc123456 — The search string was not encoded and therefore the string was not terminated with Z.

Parameters

Field or Control	Definition
`search_string`	Specifies the search string that is to be encoded.

Returns

A String value.

Example

import PT_SEARCH:*;

Local PT_SEARCH:SearchFilter &flt;
Local PT_SEARCH:SearchField &fld;

&flt.Field = &fld;
&srchString = &fld.Value;
&flt.Value = EncodeSearchCode(&srchString);

Syntax

EncodeURL(URLString)

Description

Use the EncodeURL function to apply URL encoding rules, including escape characters, to the string specified by URLString. The method used to encode the URLString is the standard defined by W3C. This function returns a string that contains the encoded URL. All characters outside the Unicode Basic Latin block (U+0020 — U+007F) are encoded, with the exception of the characters in the table below which are not encoded as they may represent valid components of URL or protocol syntax. If you need to encode such characters, use the EncodeURLForQueryString function.

The following table lists the characters in the Unicode Basic Latin block that are not encoded by the URLEncode function.

Character (Glyph)	Description (Unicode Character Name)
!	Exclamation mark
#	Number sign
$	Dollar sign
&	Ampersand
(	Left parenthesis
)	Right parenthesis
*	Asterisk
+	Plus sign
,	Coma
-	Hyphen, minus
.	Full stop, period
/	Solidus, slash
:	Colon
;	Semi-colon
=	Equals sign
?	Question mark
_	Underscore

Parameters

Field or Control	Definition
`URLString`	Specify the string you want encoded. This parameter takes a string value.

Returns

An encoded string.

Example

The example below returns the following encoded URL:

http://corp.office.com/human%20resources/benefits/401kchange_home.htm?FirstName=Gunter&LastName=D%c3%9crst

&MYSTRING = EncodeURL("http://corp.office.com/hr/benefits/401k/401k_home.htm");

Syntax

EncodeURLForQueryString(URLString)

Description

Use the EncodeURLForQueryString function to encode URLString for use in a query string parameter in an URL. All characters outside the Unicode Basic Latin block (U+0020 — U+007F) are encoded, with the exception of the characters in the table below which are not encoded as they are typically valid in a query string.

If the link is constructed in a page, and the value is a link field, you should not call EncodeURL to encode the entire URL, as the PeopleSoft Pure Internet Architecture does this for you. You still need to unencode the parameter value when you retrieve it, however.

Always encode each field value being added directly to query strings using EncodeURLForQueryString.

The following table lists characters in the Unicode Basic Latin block that are not encoded by the URLEncodeForQueryString function.

Character (Glyph)	Description (Unicode Character Name)
(	Left parenthesis
)	Right parenthesis
*	Asterisk
-	Hyphen, minus
.	Full stop, period
_	Underscore, low line

Parameters

Field or Control	Definition
`URLString`	Specify the string you want encoded. This parameter takes a string value.

Returns

An encoded URL string.

Example

In an Internet Script, to construct an anchor with a URL in a query string parameter, do the following:

&url = "http://host/psp/ps/EMPLOYEE/HRMS/s/EMPL_INFO.FieldFormula.IScript_EMPL_INFO?emplid=1111&mkt=usa"
 
&href = %Request.RequestURI | "?" | %Request.QueryString | "&myurl=" | EncodeURLForQueryString(&url); 
 
%Response.WriteLine("<a href= " | EncodeURL(&href) | ">My Link</a>");

The following uses a generic method to find, then encode, the URL, for the external link:

&StartPos = Find("?", &URL, 1); 
&CPColl = &Portal.ContentProviders; 
&strHREF = EncodeURLForQueryString(Substring(&URL, &StartPos + 1, Len(&URL), &StartPos)); 
&LINK = &Portal.GetQualifiedURL("PortalServlet", "PortalOriginalURL=" | &CPColl.ItembyName(&CP_NAME).URI | "?" | &strHREF);

Syntax

Encrypt(KeyString, ClearTextString)

Description

Use the Encrypt function to encrypt a string. This function is generally used with merchant passwords.

The value you use for KeyString must be the same for Decrypt and Encrypt.

Size Considerations for Encrypt

The Encrypt function uses 56-bit DES (Data Encryption Standard). The size of the output string is increased to the nearest multiple of 8 bytes. The string is encrypted (which doesn't modify the size), then encoded, which increases the resulting size to the next multiple of 3. Then, the system multiplies the result by 4/3 to get the final encrypted size.

For example, a 16-character, Unicode field is 32 bytes long, which is already an even multiple of 8. After it is encrypted, it is encoded, which increases the size of the string to 33 bytes (the next multiple of 3). Then, the system multiplies this by 4/3 to get the final encrypted string size of 44 bytes.

Parameters

Field or Control	Definition
`KeyString`	Specify the key used for encrypting the string. You can specify a Null value for this parameter, that is, two quotation marks with no blank space between them ("").
`ClearTextString`	Specify the string you want encrypted.

Returns

An encrypted string.

Example

The following encrypts a field if it contains a value. It also removes any blanks either preceding or trailing the value.

If All(PSCNFMRCHTOKEN.WRKTOKEN) Then 
   CMPAUTHTOKEN = Encrypt("", RTrim(LTrim(PSCNFMRCHTOKEN.WRKTOKEN))); 
End-If;

Syntax

EncryptNodePswd(Password)

Description

Use the EncryptNodePswd function to encrypt an Integration Broker node password.

Note: This function is generally used with Integration Broker node password encryption. This function should not be used casually, as once you encrypt your node password, there is no decrypt PeopleCode method.

Parameters

Field or Control	Definition
`Password`	Specify the Integration Broker node password that you want encrypted, as a string.

Returns

An encrypted password as a string.

Example

In the following example, the password is stored in the database in an encrypted form instead of as plain text:

PSMSGNODEDEFN.IBPASSWORD = EncryptNodePswd(RTrim(LTrim(PSNODE_WRK.WRKPASSWORD)));

Description

Use End-Evaluate to terminate an Evaluate construct. See Evaluate for more information.

Description

Use End-For to terminate a for loop. See For for more information.

Description

Use End-Function to terminate a function definition. See Function for more information.

Description

Use End-If to terminate an if block. See If for more information.

Syntax

EndMessage(message, messagebox_title)

Description

Note: The EndMessage function is obsolete and is supported only for backward compatibility. The MessageBox function, which can now be used to display informational messages in any PeopleCode event, should be used instead.

Use the EndMessage function to display a message at the end of a transaction, at the time of the database COMMIT. This function can be used only in SavePostChange PeopleCode.

When an EndMessage function executes, PeopleTools:

Verifies that the function is in SavePostChange; if it is not, an error occurs and the function terminates.
Displays the message.
Terminates the SavePostChange PeopleCode program.

Because it terminates the SavePostChange program, EndMessage is always be the last statement executed in the program on the specific field and row where the EndMessage is called. For this reason, you must write the SavePostChange program so that all necessary processing takes place before the EndMessage statement. PeopleCode programs on other fields and rows execute as usual.

Parameters

Field or Control	Definition
`message`	A string that must be enclosed in quotes containing the message text you want displayed.
`messagebox`_`title`	A string that must be enclosed in quotes containing the title of the message. It appears in the message box title bar.

Returns

None.

Example

The following example is from SavePostChange event PeopleCode. It checks to see whether a condition is true, and if so, it displays a message and terminates the SavePostChange program. If the condition is false, then processing continues in the Else clause:

If BUSINESS_UNIT = BUS_UNIT_WRK.DEFAULT_SETID Then
         EndMessage(MsgGet(20000, 12, "Message not found in Message Catalog")," ");
      Else
/* any other SavePostChange processing in Else clause */

Syntax

EndModal(returnvalue)

Description

Use the EndModal function to close a currently open modal or modeless secondary window. It is required only for secondary windows that do not have OK and Cancel buttons. If the secondary window has OK and Cancel buttons, then the function for exiting the window is built in and no additional PeopleCode is required.

Important! Do not use multiple EndModal or EndModalComponent invocations to close multiple, open modal secondary windows simultaneously. Each modal window must be closed individually with a single EndModal call followed by an event that triggers a trip to the application server. Otherwise, multiple, simultaneous EndModal or EndModalComponent invocations will close all open modal secondary windows.

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.

Parameters

Field or Control	Definition
`returnvalue`	A number value that determines whether the secondary page data is copied back to the parent page. A positive value runs SaveEdit PeopleCode and copies the data (this is the same as clicking the OK button). A value of zero skips SaveEdit and discards buffer changes made in the secondary page (this is the same as clicking the Cancel button). This value becomes the return value of the DoModal function that started the secondary page, and it can be tested after the secondary page is closed.

Field or Control

Definition

returnvalue

A number value that determines whether the secondary page data is copied back to the parent page. A positive value runs SaveEdit PeopleCode and copies the data (this is the same as clicking the OK button). A value of zero skips SaveEdit and discards buffer changes made in the secondary page (this is the same as clicking the Cancel button). This value becomes the return value of the DoModal function that started the secondary page, and it can be tested after the secondary page is closed.

Returns

None.

Example

The following statement acts as an OK button:

EndModal(1);

The following statement acts as a Cancel button:

EndModal(0);

Syntax

EndModalComponent(ReturnValue)

Description

Use the EndModalComponent function to close a currently open secondary component. You could use this for creating your own links to exit a secondary component.

Important! Do not use multiple EndModalComponent or EndModal invocations to close multiple, open modal secondary windows simultaneously. Each modal window must be closed individually with a single EndModalComponent call followed by an event that triggers a trip to the application server. Otherwise, multiple, simultaneous EndModalComponent or EndModal invocations will close all open modal secondary windows.

Restrictions on Use With a Component Interface

This function can’t be used by a PeopleCode program that’s been called by a Component Interface, and is ignored.

Parameters

Field or Control	Definition
`ReturnValue`	A Number value that determines whether the secondary component data is saved and copied back to the parent page. A positive value saves the data in the component to the database, including all save processing and PeopleCode (this is the same as pressing the OK button). It also copies the data in the shared work record, if any, back to the primary component. A value of zero skips save processing discards buffer changes made in the secondary component (this is the same as pressing the Cancel button).

Field or Control

Definition

ReturnValue

A Number value that determines whether the secondary component data is saved and copied back to the parent page. A positive value saves the data in the component to the database, including all save processing and PeopleCode (this is the same as pressing the OK button). It also copies the data in the shared work record, if any, back to the primary component. A value of zero skips save processing discards buffer changes made in the secondary component (this is the same as pressing the Cancel button).

Returns

A Boolean value: True if a non-zero value was used, False if zero was used.

Example

EndModalComponent(0);  /* cancels the component without saving */

EndModalComponent(1); /* saves and closes the component */

Description

Use End-While to terminate a while loop. See While for more information.

Syntax

EnQueue(logical_queue, task_type, Relative_URL, Language_Code [, subject][, agent_ID][, overflow_timeout][, escalation_timeout][, cost][, priority][, skill_level])

Description

Use the EnQueue function to assign a task to one of the active, physical queues belonging to the specified logical queue. The physical queue to which the system assigns the task is chosen randomly to balance load across the queues.

Note: PeopleSoft recommends that you always follow the EnQueue function with the NotifyQ function.

See NotifyQ.

Parameters

Field or Control	Definition
`logical_queue`	Specifies the logical queue in which the task should be queued. It is a string value. The logical queue ID is a case-sensitive value. The case used in the EnQueue function must exactly match the case used when creating the logical queue ID with the MultiChannel Framework administration pages.
`task_type`	Specifies the type of task to be inserted. It is a string value. The valid values are: email generic Note: This parameter does not apply to voice or chat. Chat tasks are enqueued using the InitChat function. Voice queueing is managed by PeopleSoft CTI.
`Relative_URL`	The system uses this relative URL to generate the URL of the appropriate application page for the MultiChannel Framework console to launch when an agent accepts this task. The application page should contain the logic to enable the agent to resolve the task and either forward the task using the Forward function or dequeue the task using the DeQueue function.
`Language_Code`	This is the language code associated with the task to be enqueued. It is a string value that must exist in the PeopleSoft language table. The queue server only assigns this task to an agent whose list of languages contains this value. For example if an email to be enqueued is written in English, the language code would be “ENG”, and this email would only be assigned to agents whose language list contains English.
`subject`	This is an optional parameter. It is a string value describing the purpose of the request. This value appears on the agent's console when the system assigns the task.
`agent_ID`	Specifies the assigned agent. This is an optional, string parameter. If specified, the system holds the task until the specified agent is available to take this task. If this parameter is left blank, the queue server assigns it to the first available agent. Note: For better performance, PeopleSoft recommends not specifying the target agent as this has a processing overhead for the queue servers and does not allow the system to balance workload across all available agents.
`overflow_timeout`	This is an optional parameter. It is an integer value expressing the overflow timeout in minutes. The overflow timeout is the time period within which a queue server has to find an agent who accepts the task (clicks on the flashing icon on the MultiChannel console). If the task is not accepted within this time, the task is removed from the queue and placed in the MultiChannel overflow table. If you do not specify a value, the system uses the default value specified for that task type in the Task Configuration page.
`escalation_timeout`	This is an optional parameter. It is an integer value expressing the escalation timeout in minutes. The escalation timeout is the time period within which a task must be completed by the agent and closed with DeQueue. If the task is not closed within this time, the task is removed from the queue and from the agent's accepted task list, which means the task becomes unassigned. Then the task is placed in the MultiChannel Framework escalation table. If no value is specified, the system uses the default specified for that task type in the Task Configuration pages.
`cost`	This is an optional parameter. It is an integer value measuring the workload each task places on an agent. The cost of a task is an estimate of the tasks's expected complexity and of the time required to resolve the task. The minimum value is 0, and there is no maximum value. The cost of a task is added to an agent's workload after accepting a task on the MultiChannel Framework console. A task can't be assigned to an agent if the difference between the current workload and the maximum workload defined for that agent on the Agent configuration page is less than the cost of this task. If you do not specify a value, the system uses the default value specified for that task in the Task Configuration pages. Note: If the required skill level or cost submitted exceeds the highest skill level or maximum workload of any of the agents on that queue, the task cannot be assigned.
`priority`	This is an optional parameter. It is an integer value expressing the priority level of the request. The minimum value is 0 and there is no maximum value. A higher value means a higher priority. Tasks are ordered on a physical queue based on their assigned priority. That is, the system assigns a task of a higher priority before it assigns a task of a lower priority. If no value is specified, the system uses the default value specified for that task type in the Task Configuration page. When tasks have the same priority, the system orders the tasks according to the time they were created. For example, suppose the following tasks exist: Priority 2 created at 11:15 AM and Priority 2 created at 11:16 AM. In this case, the system assigns the task created at 11:15 AM before the task created at 11:16 AM.
`skill_level`	This is an optional parameter. It is an integer value expressing the minimum skill level required of the agent to whom the system routes the request. You set an agent's skill level in the Agent configuration page. The queue server assigns this task type to an available agent on that queue whose lowest skill level is greater than or equal to the skill level required by the task. If no value is specified, the system uses the default value specified for that task type in the Task Configuration page. Note: If the required skill level or cost submitted exceeds the highest skill level or maximum workload of any of the agents on that queue, the task cannot be assigned.

Returns

If the insert was successful, the function returns a task number in the form of a string.

If unsuccessful, it returns a message number. The message set ID for MultiChannel Framework is 162.

For example, 1302 is returned when an invalid task type or no value is provided.

Example

&PortalValue = Portal.EMPLOYEE;
   &NodeValue = Node.QE_LOCAL; /*If running in Application Engine, this code 
assumes CONTENT URI has been set in node defn admin page*/
   
   &MyCompURL = GenerateComponentContentRelURL(&PortalValue, &NodeValue, 
MenuName.PT_MCF, "GBL", Component.MCFEM_DEMOERMS_CMP, Page.MCFEM_ERMSMN, "");
   &MyCompURL = &MyCompURL | "&ps_emailid=" | &emailid; /*Query string 
dependent on component. Our demo comonent just needs email id*/
   
rem The URL to be passed will look something like;
rem "/psc/ps/EMPLOYEE/QE_LOCAL/c/PT_MCF.MCF_DEMOERMS_CMP.GBL?Page=MCFEM_ERMSMN";

&strtasknum = EnQueue(&queueID, "email", &MyCompURL, &langcode, 
&subject, "QEDMO", 15, 60, &cost, &priority, &minskill);

Syntax

Error str

Description

Use the Error function in FieldEdit or SaveEdit PeopleCode to stop processing and display an error message. It is distinct from Warning, which displays a warning message, but does not stop processing. Error is also used in RowDelete and RowSelect PeopleCode events.

Warning! The behavior of the Error function in the RowSelect event is very different from its normal behavior.

See the Error in RowSelect section for more details.

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

Note: If you pass a string to the 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.

See WinMessage.

When Error executes in a PeopleCode program, the program terminates immediately and no statements after the Error are executed. In other respects behavior of Error differs, depending on which PeopleCode event the function occurs in.

Errors in FieldEdit and SaveEdit

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

In FieldEdit, Error stops processing, displays a message, and highlights the relevant field.
In SaveEdit, Error stops all save processing and displays a message, but does not highlight any field. You can move the cursor to a specific field using the SetCursorPos function, but be sure to call SetCursorPos before calling Error, otherwise Error stops processing before SetCursorPos is called. Note that an Error on any field in SaveEdit stops all save processing, and no page data is saved to the database.

Errors in RowDelete

When the user attempts to delete a row of data, the system first prompts for confirmation. If the user confirms, the RowDelete event fires. An Error in the RowDelete event displays a message and prevents the row from being deleted.

Error in RowSelect

The behavior of Error in RowSelect is totally anomalous, and is supported only for backward compatibility. It is used to filter rows that are being added to a page scroll after the rows have been selected and brought into the component buffer. No message is displayed. Error causes the Component Processor to add the current row (the one where the PeopleCode is executing) to the page scroll, then stops adding any additional rows to the page scroll.

The behavior of Error in the RowSelect event enables you to filter out rows that are above or below some limiting value. In practice this technique is rarely used, because it is more efficient to filter out rows of data before they are brought into the component buffer. This can be accomplished with search views or effective date processing.

Errors in Other Events

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

FieldDefault
FieldFormula
RowInit
FieldChange
Prepopup
RowInsert
SavePreChange
SavePostChange

Parameters

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

Returns

None.

Example

The following example, from SaveEdit PeopleCode, displays an error message, stops all save processing, and places the cursor in the QTY_ADJUSTED field. Note that SetCursorPos must be called before Error.

If PAGES2_INV_WRK.PHYS_CYC_INV_FLG = "Y" Then
   SetCursorPos(%Page, PHYSICAL_INV.INV_LOT_ID, CurrentRowNumber(1), QTY_ADJUSTED, CurrentRowNumber());
   Error MsgGet(11100, 180, "Message not found.");
End-If;

Syntax

EscapeHTML(text_string)

Description

Use the EscapeHTML function to replace the characters in text_string that would otherwise be interpreted as HTML markup.

For example, this function can be used with strings that are displayed in an HTML area or strings that are re-purposed to form a portion of URL parameters. The characters that are replaced are ones that would cause the browser to interpret them as HTML tags or other markup if they aren't encoded. Therefore, pre-formatted HTML should not be passed to this function unless the output desired is a rendering of the HTML code itself as opposed to its interpretation. This function is intended to make the text "browser safe."

Either HTML character entities (for example, <) or numeric character representations (for example, ') are output by the EscapeHTML function, depending on the character passed.

In addition to escaping characters that could be misinterpreted as HTML tags or other elements, EscapeHTML escapes the percentage sign (%) as this could interfere with PeopleCode-specific meta-HTML processing. Since all HTML in a PeopleSoft system is generated in Unicode, it is not necessary to escape other Unicode characters—their value may be passed directly to the browser instead of as a character entity or in numeric character representation.

The following table lists the Unicode characters that are escaped by the EscapeHTML function:

Unicode Character Name	Glyph	Escape Sequence
Quotation mark	"	"
Ampersand	&	&
Less than sign	<	<
Apostrophe, single quote	'	'
Percentage sign	%	%
New line	Not applicable	<BR>

Parameters

Field or Control	Definition
`text_string`	Specify a text string that contains characters that must be replaced with HTML escape sequences.

Returns

A string value.

Syntax

EscapeJavascriptString(String)

Description

Use the EscapeJavascriptString function to replace the characters in String that have special meaning in a JavaScript string as escape sequences.

For example, a single quotation mark` ( ' ) is replaced by \', a new line character is replaced by \n, and so on.

This function is for use with text that becomes part of a JavaScript program.

The characters that are replaced are ones that cause the browser to misinterpret the JavaScript if they aren't encoded. This function is intended to make the text “browser safe.” The table below shows the strings that are replaced by this function, and their replacement character sequence.

Character Name	Glyph	Description
Apostrophe, single quote	'	\'
Quotation mark	"	\"
New line	Not applicable	\n
Carriage return	Not applicable	Deleted
Double backslash	\\	\\\\

Parameters

Field or Control	Definition
`String`	Specify a string that contains character that need to be replaced with JavaScript escape sequences.

Returns

A string containing the original text plus JavaScript escape sequences.

Syntax

EscapeWML(String)

Description

Use the EscapeWML function to escape special characters that are significant to WML. This includes <, >, $ (escaped as $$), &, ' and ".

This function is for use with strings that display on an WML browser.

Parameters

Field or Control	Definition
`String`	Specify a string that contains characters that need to be replaced with WML escape sequences.

Returns

A string containing the original plus text plus WML escape sequences.

Syntax

Evaluate left_term
   When [relop_1] right_term_1
      [statement_list]
   .
   .
   .
   [When [relop_n] right_term_n
      [statement_list]]
   [When-Other
      [statement_list]]
End-Evaluate

Description

Use the Evaluate statement to check multiple conditions. It takes an expression, left_term, and compares it to compatible expressions (right_term) using the relational operators (relop) in a sequence of When clauses. If relop is omitted, then = is assumed. If the result of the comparison is True, it executes the statements in the When clause, then moves on to evaluate the comparison in the following When clause. It executes the statements in all of the When clauses for which the comparison evaluates to True. If and only if none of the When comparisons evaluates to True, it executes the statement in the When-other clause (if one is provided).

To end the Evaluate after the execution of a When clause, you can add a Break statement at the end of the clause.

Considerations Using When Clause

Generally, you use the When clause without a semicolon at the end of the statement. However, in certain circumstances, this can cause an error. For example, the following PeopleCode produces an error because the PeopleCode compiler cannot separate the end of the When clause with the beginning of the next statement:

When = COMPONENT.GARBAGE

   (create BO_SEARCH:Runtime:BusinessContact_Contact(&fBusObjDescr, Null, &fDerivedBOID, &fDerivedBORole, &fBusObjDescr1, Null, &fContactBOID, &fContactRoleID, &fCustBOID, &fCustRoleID, "")).SearchItemSelected();

End-Evaluate;

If you place a semicolon after the When clause, the two expressions are read separately by the compiler:

 When = COMPONENT.GARBAGE;

Example

The following is an example of a When statement taken evaluates ACTION and performs various statements based on its value:

&PRIOR_STATUS = PriorEffdt(HIRE.EMPL_STATUS);
Evaluate HIRE.ACTION
When = "HIR"
   If %Mode = "A" Then
      Warning MsgGet(1000, 13, "You are hiring an employee and Action is not set to Hire.");
   End-If;
   Break;
When = "REH"
   If All(&PRIOR_STATUS) And
         Not (&PRIOR_STATUS = "T" Or
            &PRIOR_STATUS = "R") Then
      Error MsgGet(1000, 14, "Hire or Rehire action is valid only if employee status is Terminated or Retired.");
   End-If;
   Break;
When-Other
   /* default code */
End-Evaluate;

Syntax

Exact(string1, string2)

Description

Use the Exact function to compare two text strings and returns True if they are the same, False otherwise. Exact is case-sensitive because it uses the internal character codes.

Returns

Returns a Boolean value: True if the two strings match in a case-sensitive comparison.

Example

The examples set &MATCH to True, then False:

&MATCH = Exact("PeopleSoft", "PeopleSoft");
&MATCH = Exact("PeopleSoft", "Peoplesoft");

Syntax

Exec(command_str [, parameter])

where parameter has one of the following formats:

Boolean constant

Exec_Constant + Path_Constant

Description

Exec is a cross-platform function that executes an external program on either UNIX or Windows.

This function has two parameter conventions in order to maintain upward compatibility with existing programs.

Note: All PeopleCode is executed on the application server. So if you're calling an interactive application, you receive an error. There shouldn't be any application interaction on the application server console.

The function can make either a synchronous or asynchronous call. Synchronous execution acts as a "modal" function, suspending the PeopleSoft application until the called executable completes. This is appropriate if you want to force the user (or the PeopleCode program) to wait for the function to complete its work before continuing processing. Asynchronous processing, which is the default, launches the executable and immediately returns control to the calling PeopleSoft application.

If Exec is unable to execute the external program, the PeopleCode program terminates with a fatal error. You may want to try to catch these exceptions by enclosing such statements in a try-catch statement (from the Exception Class).

Command Formatting

The function automatically converts the first token on command_str platform-specific separator characters to the appropriate form for where your PeopleCode program is executing, regardless of the path_constant. On a Windows system, a UNIX "/" separator is converted to "\", and on a UNIX system, a Windows "\" separator is converted to "/".

This is only done for the first token on command_str assuming it to be some sort of file specification. This allows you to put file or program names in canonical form (such as, UNIX style) as the first token on the exec command.

Using an Absolute Path

If you do not specify anything for the second parameter, or if you specify a Boolean value, the path to PS_HOME is prefixed to the command_str.

If you specify constant values for the second parameter, PS_HOME may or may not be prefixed, depending on the values you select.

You can use the GetEnv function to determine the value of PS_HOME.

Creating a File in UNIX

If you try to create a file on a UNIX machine using the Exec function the file might not be created due to permission issues. If you encounter this problem, create a script file that includes the file creation commands and run the script using the Exec function. The script file must have correct privileges.

If you pass an absolute path in the Exec argument you must use the %FilePath_Absolute flag

Restrictions on Use in PeopleCode Events

When Exec is used to execute a program synchronously (that is, if its synch_exec parameter is set to True) it behaves as a think-time function, which means that it can’t be used in any of the following PeopleCode events:

SavePreChange.
SavePostChange.
Workflow.
RowSelect.
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.

Parameters

Field or Control	Definition
`command_str`	The `command_str` parameter consists of a series of tokens that together make up the name of the executable to run and the parameters to be passed to it. Tokens are separated by unquoted space characters. Single or double quote characters can be used for quoting. Both types of quotes are treated equivalently, but the starting and ending quotes for a quoted portion of a token must match. A quoted string may not contain quotes of the same type but a single quoted string can contain double quote characters and vice versa. A single token may consist of multiple adjacent quoted characters (There must be no spaces between the quoted fragments). Unterminated quoted fragments will result in an error. Note: PeopleCode strings will require two double quote characters within a string to embed a double quote character.
`Boolean` \| `Constants`	If you specify a Boolean value, it indicates whether to execute the external program synchronously or asynchronously. Values are: True - Synchronous False - Asynchronous (default) If you do not specify a value, the program executes asynchronously. If you use this style, PS_HOME is always prefixed to `command_str.` If you specify constant values, you're specifying a numeric value composed of an `exec_constant` and a `path_constant`. The `exec_constant` specifies whether to execute the external program synchronously or not. The `path_constant` specifies how the path name is to be treated. The value specified is made up of the addition of these predefined constants. Values are:

Field or Control

Definition

command_str

The command_str parameter consists of a series of tokens that together make up the name of the executable to run and the parameters to be passed to it. Tokens are separated by unquoted space characters. Single or double quote characters can be used for quoting. Both types of quotes are treated equivalently, but the starting and ending quotes for a quoted portion of a token must match. A quoted string may not contain quotes of the same type but a single quoted string can contain double quote characters and vice versa. A single token may consist of multiple adjacent quoted characters (There must be no spaces between the quoted fragments). Unterminated quoted fragments will result in an error.

Note: PeopleCode strings will require two double quote characters within a string to embed a double quote character.

Boolean | Constants

If you specify a Boolean value, it indicates whether to execute the external program synchronously or asynchronously. Values are:

True - Synchronous
False - Asynchronous (default)

If you do not specify a value, the program executes asynchronously.

If you use this style, PS_HOME is always prefixed to command_str.

If you specify constant values, you're specifying a numeric value composed of an exec_constant and a path_constant. The exec_constant specifies whether to execute the external program synchronously or not. The path_constant specifies how the path name is to be treated. The value specified is made up of the addition of these predefined constants.

Values are:

Exec Constant	Description
%Exec_Asynchronous	Program executes asynchronously (the default)
%Exec_Synchronous	Program executes synchronously.

Path Constant	Description
%FilePath_Relative	PS_HOME is prefixed to `command_str`.
%FilePath_Absolute	Nothing is prefixed to `command_str`.

Returns

What is returned depends on what you specified for the second parameter.

If you specified a Boolean, a Number value equal to the process ID of the called process is returned.

If you specify constant values, the returned value contains the value of the exit code of the program executed using this function, unless you have executed the program asynchronously.

Example

&ExitCode = Exec("sh -c " | &scriptFile, %Exec_Synchronous + %FilePath_Absolute);

The following example demonstrates executing a program where the path to the executable contains spaces and a single parameter containing space characters is passed. Suppose the location of the executable is C:\Program Files\App\program.exe and the value of the first parameter is 1 2 3.

Exec("'c:\Program Files\App\program.exe' '1 2 3'", %FilePath_Absolute)

Exec("""c:\Program Files\App\program.exe"" ""1 2 3""", %FilePath_Absolute)

This is an example of executing a program with a parameter that contains space and single quote characters. The second parameter is enclosed in double quotes so that the single quote and space characters are passed correctly. Suppose your executable is program.exe. The first parameter is -p and the second parameter is customer's update.

Exec("program.exe -p ""customer’s update""")

This is an example of executing a program with a parameter that contains space, single quote, and double quote characters. The second parameter consists of several adjacent quoted fragments. The first fragment is enclosed in double quotes so that the single quote and space characters are passed correctly and the second fragment is enclosed in single quotes so that the double quote and space characters are passed correctly. Note that there are no spaces between the quoted fragments. Suppose your executable is program.exe. The first parameter is -p and the second parameter is John’s comment: “Hello There”.

Exec("program.exe -p ""John's comment: ""'""Hello There""'")

Syntax

ExecuteRolePeopleCode(RoleName)

Description

Use the ExecuteRolePeopleCode function to execute the PeopleCode Rule for the Role RoleName. This function returns an array of string containing dynamic members (UserIds).

Typically, this function is used by an Application Engine process that runs periodically and executes the role rules for different roles. It could then write the results of the rules (a list of users) into the security tables, effectively placing users in certain roles based on the rule.

Parameters

Field or Control	Definition
`RoleName`	Specify the name of an existing role.

Returns

An array of string containing the appropriate UserIds.

Example

The following saves valid users to a temporary table:

Local array of string &pcode_array_users; 
 
SQLExec("delete from ps_dynrole_tmp where ROLENAME=:1", &ROLENAME); 
   If &pcode_rule_status = "Y" Then 
      SQLExec("select RECNAME, FIELDNAME, PC_EVENT_TYPE, PC_FUNCTION_NAME from
      PSROLEDEFN where ROLENAME= :1", &ROLENAME, &rec, &fld, &pce, &pcf); 
      If (&rec <> "" And 
            &fld <> "" And 
            &pce <> "" And 
            &pcf <> "") Then 
         &pcode_array_users = ExecuteRolePeopleCode(&ROLENAME); 
         &pcode_results = True; 
      Else 
         &pcode_results = False; 
      End-If; 
      &comb_array_users = &pcode_array_users; 
   End-If;

Syntax

ExecuteRoleQuery(RoleName, BindVars)

where BindVars is an arbitrary-length list of bind variables that are stings in the form:

bindvar1 [, bindvar2]. . .

Description

Use the ExecuteRoleQuery function to execute the Query rule for the role rolename, passing in BindVars as the bind variables. This function returns an array object containing the appropriate user members (UserIds).

Parameters

Field or Control	Definition
`RoleName`	Specify the name of an existing role.
`BindVars`	A list of bind variables to be substituted in the query. These bind variables must be strings. You can't use numbers, dates, and so on.

Returns

An array object containing the appropriate UserIds.

Syntax

ExecuteRoleWorkflowQuery(RoleName, BindVars)

where BindVars is an arbitrary-length list of bind variables in the form:

bindvar1 [, bindvar2]. . .

Description

Use the ExecuteRoleWorkflowQuery function to execute the Workflow Query rule for the role rolename, passing in BindVars as the bind variables. This function returns an array object containing the appropriate user members (UserIds).

Parameters

Field or Control	Definition
`RoleName`	Specify the name of an existing role.
`BindVars`	A list of bind variables to be substituted in the query.

Returns

An array object containing the appropriate UserIds.

Syntax

ExecuteSearchSavePC()

Description

Use the ExecuteSearchSavePC function to execute any SearchSave PeopleCode on the search page.

Important! Use this function within fluid applications only.

Parameters

None.

Returns

None.

Syntax

Exit[(1)]

Description

Use the Exit statement to immediately terminate a PeopleCode program. If the Exit statement is executed within a PeopleCode function, the main program terminates.

Note: Exit(1) does not rollback iScript transactions. To rollback in an iScript, you can use the SqlExec built-in function with the parameter of ROLLBACK (SQLEXEC("ROLLBACK")) or the MessageBox built-in function with a message error severity of error. You can also use the built-in function Error, but only if you are not sending HTML or XML in the error text itself.

Parameters

Field or Control	Definition
1	Use this parameter to rollback database changes. Generally, this parameter is used in PeopleCode programs that affect messages. When used with a message, all database changes are rolled back, errors for the subscription contract are written to the subscription contract error table, and the status of the message is marked to Error. All errors that have occurred for this message are viewable in the message monitor: even those errors detected by the ExecuteEdits method.

Field or Control

Definition

Use this parameter to rollback database changes.

Generally, this parameter is used in PeopleCode programs that affect messages. When used with a message, all database changes are rolled back, errors for the subscription contract are written to the subscription contract error table, and the status of the message is marked to Error. All errors that have occurred for this message are viewable in the message monitor: even those errors detected by the ExecuteEdits method.

Note: This function takes only numeric values. It fails if you use a Boolean value, True or False.

Returns

None.

Example

The following example terminates the main program from a For loop:

For &I = 1 To ActiveRowCount(RECORD.SP_BUIN_NONVW)
   &ITEM_SELECTED = FetchValue(ITEM_SELECTED, &I);
   If &ITEM_SELECTED = "Y" Then
      &FOUND = "Y";
      Exit;
   End-If;
End-For;

Syntax

Exp(n)

Description

Exp returns the constant e raised to the power of n where n is a number. The constant e equals 2.71828182845904, the base of natural logarithms. The number n is the exponent applied to the base e.

Exp is the inverse of the Ln function, which is the natural logarithm of x.

Returns

Returns a Number value equal to the constant e raised to the power of n.

Example

The examples set &NUM to 2.71828182845904, then 7.389056099(e2):

&NUM = Exp(1);
&NUM = Exp(2);

Syntax

ExpandBindVar(str)

Description

Inline bind variables can be included in any PeopleCode string. An inline bind variable is a field reference (in the form recordname.fieldname), preceded by a colon. The inline bind variable references the value in the field.

Use the ExpandBindVar function to expand any inline bind variables that it finds in str into strings (converting the data type of non-character fields) and returns the resulting string. This works with inline bind variables representing fields containing any data type except Object. It also expands bind variables specified using additional parameters.

See SQLExec.

Parameters

Field or Control	Definition
`str`	A string containing one or more inline bind variables.

Returns

Returns a String value equal to the input string with all bind variables expanded.

Example

A bind variable is included in the string &TESTSTR, which is then expanded into a new string containing the current value of BUS_EXPENSE_PER.EMPLID in place of the bind variable. If this program runs on the row for EMPLID 8001, the message displayed reads "This is a test using EmplID 8001".

&TESTSTR = "This is a test using EmplID :bus_expense_per.emplid";
&RESULT = ExpandBindVar(&TESTSTR);
WinMessage(&RESULT);

Syntax

ExpandEnvVar(string)

Description

Use the ExpandEnvVar function to convert any environment variables that it finds within string into String values and returns the entire resulting string.

Parameters

Field or Control	Definition
`string`	A string containing an environment variable.

Returns

Returns a string equal to string with any enclosed environment variables expanded to their values.

Example

Assume that the environment variable %NETDRIVE% is equal to "N:". The following PeopleCode sets &newstring equal to "The network drive is equal to N:":

&newstring = ExpandEnvVar("The network drive is equal to %netdrive%.");

Syntax

ExpandSqlBinds(string)

Description

Prior to PeopleTools 8.0, the PeopleCode replaced runtime parameter markers in SQL strings with the associated literal values. For databases that offer SQL statement caching, a match was never found in the cache so the SQL had to be re-parsed and re-assigned a query path.

To process skipped parameter markers, each parameter marker is assigned a unique number. This doesn’t change the values associated with the parameter markers.

However, some SQL statements can’t contain parameter markers because of database compatibility.

To process these exceptions, use the ExpandSqlBinds function. This function does the bind variable reference expansion, and can be used within a SQLExec statement or on its own.

You should use ExpandSQLBinds only for those parts of the string that you want to put literal values into. The following code shows how to use ExpandSQLBinds with %Table:

SQLExec(ExpandSqlBinds("Insert....  Select A.Field, :1, :2 from ", "01", "02") |
 "%table(:1)", Record.MASTER_ITEM_TBL);

Parameters

Field or Control	Definition
`string`	Specify the string you want to do the bind variable reference expansion on.

Returns

A string.

Example

The following example shows both the original string and what it expands to.

&NUM = 1; 
&STRING = "My String"; 
&STR2 = ExpandSqlBinds("This :2 is an expanded string(:1)", &STRING, &NUM);

The previous code produces the following value for &STR2:

This 1 is an expanded string(My String)

If you’re having problems with an old SQL statement binds, you can use ExpandSqlBinds with it. For example, if your SQLExec is this:

SQLExec("String with concatenated bindrefs ‘M’:2, ‘M’:1", &VAR1, &VAR2),
 &FETCHRESULT1, &FETCHRESULT2);

you can make it work by expanding it as follows:

SQLExec(ExpandSqlBinds("String with concatenated bindrefs ‘M’:2, ‘M’:1", &VAR1,
 &VAR2), &FETCHRESULT1, &FETCHRESULT2);