PeopleCode Built-in Functions and Language Constructs: F
The PeopleCode built-In functions and language constructs beginning with the letter F are listed in alphabetical order within this topic.
Syntax
Fact(x)
Description
Use the Fact function to return the factorial of a positive integer x. The factorial of a number x is equal to 1*2*3*...*x. If x is not an integer, it is truncated to an integer.
Returns
Returns a Number equal to the factorial of x.
Example
The example sets &X to 1, 1, 2, then 24. Fact(2) is equal to 1*2; Fact(4) is equal to 1*2*3*4:
&X = Fact(0);
&X = Fact(1);
&X = Fact(2);
&X = Fact(4);
Syntax
FetchSQL([SQL.]sqlname[, dbtype[, effdt]] )
Description
Use the FetchSQL function to return the SQL definition with the given sqlname as SQL.sqlname or a string value, matching the dbtype and effdt. If sqlname is a literal name, it must be in quotes.
Parameters
Field or Control |
Definition |
---|---|
sqlname |
Specify the name of a SQL definition. This is either in the form SQL.sqlname or a string value giving the sqlname. |
dbtype |
Specify the database type associated with the SQL definition. This parameter takes a string value. If dbtype isn’t specified or is null (""), it is set by default to the current database type (the value returned from the %DbType system variable.) Values for dbtype are as follows. These values are not case-sensitive:
Note: Database platforms are subject to change. |
effdt |
Specify the effective date associated with the SQL definition. If effdt isn’t specified, it is set by default to the current as of date, that is, the value returned from the %AsOfDate system variable. |
Returns
The SQL statement associated with sqlname as a string.
Example
The following code gets the text associated with the ABCD_XY SQL Definition for the current DBType and as of date:
&SQLSTR = FetchSQL(SQL.ABC_XY);
The following code gets the text associated with the ABCD_XY SQL Definition for the current DBType and November 3, 1998:
&SQLSTR = FetchSQL(SQL.ABCD_XY, "", Date(19981103));
Syntax
FetchValue(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]] RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL.scrollname, where scrollname is the same as the scroll level’s primary record name.
Description
Use the FetchValue function to return the value of a buffer field in a specific row of a scroll level.
Note: This function remains for backward compatibility only. Use the Value field class property instead.
This function is generally used to retrieve the values of buffer fields outside the current context; if a buffer field is in the current context, you can reference it directly using a [recordname.]fieldname expression.
Parameters
Field or Control |
Definition |
---|---|
scrollpath |
A construction that specifies a scroll level in the component buffer. |
target_row |
An integer specifying the row on the target scroll level where the referenced buffer field is located. |
[recordname.]fieldname |
The name of the field where the value to fetch is located. The field can be on scroll level one, two, or three of the active page. The recordname prefix is required if the call to FetchValue is not on the record definition recordname. |
Returns
Returns the field value as an Any data type.
Example
The following example retrieves the value from field DEPEND_ID in record DEPEND on row &ROW_CNT from scroll level one:
&VAL = FetchValue(SCROLL.DEPEND, &ROW_CNT, DEPEND.DEPEND_ID);
Syntax
The syntax of the FieldChanged function varies depending on whether you want to use a scroll path reference or a contextual reference to specify the field.
If you want to use a scroll path reference, the syntax is:
FieldChanged(scrollpath, target_row, [recordname.]fieldname)
where scrollpath is:
[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]] RECORD.target_recname
To prevent ambiguous references, you can also use SCROLL.scrollname, where scrollname is the same as the scroll level’s primary record name.
If you want to use a contextual reference, the syntax is:
FieldChanged([recordname.]fieldname)
In this construction the scroll level and row number are determined based on the current context.
Description
The FieldChanged function returns True if the referenced buffer field has been modified since being retrieved from the database either by a user or by a PeopleCode program.
Note: This function remains for backward compatibility only. Use the IsChanged field class property instead.
This is useful during SavePreChange or SavePostChange processing for checking whether to make related updates based on a change to a field.
Parameters
Field or Control |
Definition |
---|---|
scrollpath |
A construction that specifies a scroll level in the component buffer. |
[recordname.]fieldname |
The name of the field where the value to check is located. The field can be on scroll level one, two, or three of the active page. The recordname prefix is required if the call to FieldChanged is not on the record definition recordname. |
target_row |
The row number of the target row. If this parameter is omitted, the function assumes the row on which the PeopleCode program is executing. |
Related Functions
Save PeopleCode programs (SaveEdit, SavePreChange, SavePostChange) normally process each row of data in the component. The following four functions enable you to control more precisely when the Component Processor should perform save PeopleCode:
FieldChanged
RecordChanged
RecordDeleted
RecordNew
These functions enable you to restrict save program processing to specific rows.
Example
The following example checks three fields and sets a flag if any of them has changed:
/* Set the net change flag to 'Yes' if the scheduled date, scheduled */
/* time or quantity requested is changed */
If FieldChanged(QTY_REQUESTED) Or
FieldChanged(SCHED_DATE) Or
FieldChanged(SCHED_TIME) Then
NET_CHANGE_FLG = "Y";
End-If;
Syntax
FileExists(filename [, pathtype])
Description
Use the FileExists function to determine whether a particular file or directory is present on your PeopleSoft system, so, in the case of a file, you can decide which mode to use when you open the file for writing or whether the file is available to be read, and, in the case of a directory, you can decide whether the directory already exists or needs to be created.
Note: If you want to open a file for reading, you should use the "E" mode with the GetFile function or the File class Open method, which prevents another process from deleting or renaming the file between the time you tested for the file and when you open it.
Important! The FileExists function can be used to confirm the existence of a directory on a Windows share—for example, \\my_server\temp\mydir. However, if the root of a Windows share (for example, \\my_server\temp) is passed to FileExists, the return value will always be False.
Parameters
Field or Control |
Definition |
---|---|
filespec |
Specify the name, and optionally, the path, of the file or directory you want to test. |
pathtype |
If you have prepended a path to the file name, use this parameter to specify whether the path is an absolute or relative path. The valid values for this parameter are:
If you don’t specify pathtype the default is %FilePath_Relative. If you specify a relative path, that path is appended to the path constructed from a system-chosen environment variable. A complete discussion of relative paths and environment variables is provided in documentation on the File class. See Working With Relative Paths. If the path is an absolute path, whatever path you specify is used verbatim. You must specify a drive letter and the complete path. You can’t use any wildcards when specifying a path. The Component Processor automatically converts platform-specific separator characters to the appropriate form for where your PeopleCode program is executing. On a Windows system, UNIX "/" separators are converted to "\", and on a UNIX system, Windows "\" separators are converted to "/". Note: The syntax of the file path does not depend on the file system of the platform where the file is actually stored; it depends only on the platform where your PeopleCode is executing. |
Returns
A Boolean value: True if the file or directory exists, False if it doesn’t.
Example
The following example opens a file for appending if it exists in the system:
If FileExists("c:\work\item.txt", %FilePath_Absolute) Then
&MYFILE = GetFile("c:\work\item.txt", "A");
/* Process the file */
&MYFILE.Close();
End-If;
Syntax
Find(string, within_string [, number])
Description
Use the Find function to locate one string of text within another string of text and returns the character position of the string as an integer. Find is case-sensitive and does not allow wildcards.
If you need to do either case-sensitive search or pattern matching, just to find if a string matches a pattern, use the DBPatternMatch function.
If you need to find
a quotation mark, you need to escape it with a single "
. For example
&find = Find("""", PSOPRDEFN_SRCH.OPRID);
Parameters
Field or Control |
Definition |
---|---|
string |
The text you are searching for. A tilde character (~) used in the string parameter stands for an arbitrary number of white spaces. |
within_string |
The text string you are searching within. |
number |
The position of within_string at which you want to start your search. If you omit number, Find starts at the first character of within_string. |
Returns
Returns a Number value indicating the starting position of string in within_string.
Find returns with 0 if string does not appear in within_string, if number is less than or equal to zero, or if number is greater than the length of within_string.
Example
In the following example, the first statement returns 1; the second statement returns 6.
&POS = Find("P", "PeopleSoft")
&POS = Find("e", "PeopleSoft", 4)
Syntax
Findb(string, within_string [, number])
Description
Note: This function has been deprecated and is no longer supported.
Syntax
FindCodeSetValues(CodesetName, &NameValuePairs, SourceNodeName, TargetNodeName)
Description
Use the FindCodeSetValues function to find a list of code set name-value pairs. Code sets are primarily used with data value translations as part of a transformation.
Parameters
Field or Control |
Definition |
---|---|
CodeSetName |
Specify the name of the code set you want to find, as a string. |
&NameValuePairs |
Specify a 2 dimensional array containing the name value pairs in the specified code set that you want to use. |
SourceNodeName |
Specify the name of the source (initial) node used in the data transformation. |
TargetNodeName |
Specify the name of the target (result) node used in the data transformation. |
Returns
A two-dimensional array of any.
Example
This example checks the specified CodeSet values, with the name value pairs of "locale/en_us" and "uom/box". It takes the returned array and adds XML nodes to the document. The XML nodes names are the unique names of the CodeSet value, and the XML node value is the corresponding return value.
/* Get the data from the AE Runtime */
Local TransformData &incomingData = %TransformData;
/* Set a temp object to contain the incoming document */
Local XmlDoc &tempDoc = &incomingData.XmlDoc;
/* Declare the node */
Local XmlNode &tempNode;
/* Create an array to hold the name value pairs */
Local array of array of string &inNameValuePairsAry;
/* Clear out the doc and put in a root node */
If (&tempDoc.ParseXmlString("<?xml version=""1.0""?><xml/>")) Then
/* Load the array with some values */
&inNameValuePairsAry = CreateArray(CreateArray("locale", "en_us"),
CreateArray("uom", "box"));
/* Find the codeset values */
&outAry = FindCodeSetValues("PS_SAP_PO_01", &inNameValuePairsAry,
"SAP_SRC", "PSFT_TGT");
/* Local XmlNode &tempNode; */
/* Make sure something was returned */
If &outAry.Len > 0 Then
/* Loop through the quantities and make sure they are all above 5 */
For &i = 1 To &outAry.Len
/* Add the current system date to the working storage*/
&tempNode = &tempDoc.DocumentElement.AddElement(&outAry [&i][1]);
&tempNode.NodeValue = &outAry [&i][2];
End-For;
End-If;
End-If;
Syntax
FindFiles(filespec_pattern [, pathtype])
Description
Use the FindFiles function to return a list of the external file names that match the file name pattern you provide, in the location you specify.
Parameters
Field or Control |
Definition |
---|---|
filespec_pattern |
Specify the path and file name pattern for the files you want to find. The path can be any string expression that represents a single relative or absolute directory location. The file name pattern, but not the path, can include two wildcards: * (Asterisk): matches zero or more characters at its position. ? (Question mark): matches exactly one character at its position. |
pathtype |
If you have prepended a path to the file name, use this parameter to specify whether the path is an absolute or relative path. The valid values for this parameter are:
If you don’t specify pathtype the default is %FilePath_Relative. If you specify a relative path, that path is appended to the path constructed from a system-chosen environment variable. A complete discussion of relative paths and environment variables is provided in documentation on the File class. See Working With Relative Paths. If the path is an absolute path, whatever path you specify is used verbatim. You must specify a drive letter and the complete path. You can’t use any wildcards when specifying a path. The Component Processor automatically converts platform-specific separator characters to the appropriate form for where your PeopleCode program is executing. On a Windows system, UNIX "/" separators are converted to "\", and on a UNIX system, Windows "\" separators are converted to "/". Note: The syntax of the file path does not depend on the file system of the platform where the file is actually stored; it depends only on the platform where your PeopleCode is executing. |
Returns
A string array whose elements are file names qualified with the same relative or absolute path you specified in the input parameter to the function.
Example
The following example finds all files in the system’s TEMP location whose names end with ".txt", then opens and processes each one in turn:
Local array of string &FNAMES;
Local file &MYFILE;
&FNAMES = FindFiles("\*.txt");
while &FNAMES.Len > 0
&MYFILE = GetFile(&FNAMES.Shift(), "R"); /* Open each file */
/* Process the file contents */
&MYFILE.Close();
end-while;
Syntax
FlushBulkInserts()
Description
Use the FlushBulkInserts function to move the bulk inserted rows from the bulk insert buffers of the PeopleSoft process to the physical tables on the database. This flushes all open SQL objects that have pending bulk inserts, but performs no COMMITs. If the flush fails, the PeopleCode program terminates.
When executing a SQL insert using a SQL object with the BulkMode property set to True, the rows being inserted cannot be selected by this database connection until the bulk insert is flushed. For another connection to the database to be able to select those rows, both a flush and a COMMIT are required. To have your process see the bulk inserted rows without committing and without closing the SQL object or its cursor (that is, maintaining reuse for the SQL object), use FlushBulkInserts.
An example of using this function would be in preparation for a database commit where you do not want to close the SQL insert statement, but need to ensure that all the rows you have inserted up to this point are in fact in the database and not in the buffer.
Another example would be when another SQL statement in the same PeopleSoft process needs to select rows that have been inserted using bulk insert and you do not want to close the SQL insert statement. The SELECT cannot read rows in the bulk insert buffer, so you need to flush them to the table from which the SELECT is reading.
Parameters
None.
Returns
None. If the flush fails, the PeopleCode program terminates.
Example
&CM_DEPLETION_REC = CreateRecord(Record.CM_DEPFIFO_VW);
&CM_DEPLETE_REC = CreateRecord(Record.CM_DEPLETE);
&DEPLETE_FIFO_SEL = GetSQL(SQL.CM_DEPLETE_FIFO_SEL);
&ONHAND_FIFO_SEL = GetSQL(SQL.CM_ONHAND_FIFO_SEL);
DEPLETE_INS = GetSQL(SQL.CM_DEPLETE_INS);
&DEPLETE_INS.BulkMode = True;
&DEPLETE_FIFO_SEL.Execute(&CM_DEPLETION_REC, CM_COSTING_AET.BUSINESS_UNIT,
CM_COSTING_AET.CM_BOOK);
While &DEPLETE_FIFO_SEL.Fetch(&CM_DEPLETION_REC);
/* Call functions that populate &CM_DEPLETE_REC.values */
. . .
&DEPLETE_INS.Execute(&CM_DEPLETE_REC);
. . .
If &CM_DEPLETION_REC.CM_COST_PROC_GROUP.Value = "BINTOBIN" Then
/* Bin to Bin transfers are both a deplete and receipt, call functions to
create the receipt */
. . .
/* Flush Bulk Insert to be able to see the current on hand quantities in
CM_ONHAND_VW */
FlushBulkInserts();
End-if;
End-While;
. . .
Syntax
For count = expression1 To expression2 [Step i] statement_list End-For
Description
Use the For loop to cause the statements of the statement_list to be repeated until count is equal to expression2. Step specifies the value by which count will be incremented each iteration of the loop. If you do not include Step, count is incremented by 1 (or -1 if the start value is greater than the end value.) Any statement types are allowed in the loop, including other loops.
A Break statement inside the loop causes execution to continue with whatever follows the loop. If the Break occurs in a nested loop, the Break does not apply to the outside loop.
Example
The following example loops through all of the rows for the FIELDNAME scroll area:
&FIELD_CNT = ActiveRowCount(DBFIELD_VW.FIELDNAME);
For &I = 1 To &FIELD_CNT;
WinMessage(MsgGetText(21000, 1, "Present Row Number is: %1", &I));
End-For;
Syntax
FormatDateTime(datetime, {timezone | "Local" | "Base"}, displayTZ)
Description
Use the FormatDateTime function to take a datetime value and convert it to text. If a specific time zone abbreviation, or a field reference, is passed in timezone, FormatDateTime adjusts the DateTime to the user’s local time zone instead of the specified time zone. The system’s base time zone is specified on the PSOPTIONS table. The value datetime is assumed to be in base time.
See PeopleTools Options.
If Local is specified for time zone, FormatDateTime adjusts the DateTime to the user’s local time zone instead of a specific time zone.
If True is specified for displayTZ, FormatDateTime appends the time zone abbreviation to the returned string.
Parameters
Field or Control |
Definition |
---|---|
datetime |
Specify the DateTime value to be formatted. |
timezone | Local | Base |
Specify a value for converting datetime. The values are:
|
displayTZ |
Specify whether the time zone abbreviation should be appended to the returned string. This parameter takes a Boolean: True if the abbreviation should be appended, False, otherwise. |
Returns
A formatted string value.
Example
The following example populates the &DISPDATE variable with a string containing the DateTime value in the ORDER_DATE field adjusted to the user’s local time zone, and with the time zone abbreviation.
&DISPDATE=FormatDateTime(ORDER_DATE, "Local", True);
The following example populates the &DISPDATE variable with a string containing the DateTime value in the SHIP_DATE field adjusted to the time zone stored in the SHIP_TZ field, and does not include the time zone abbreviation in the output.
&DISPDATE=FormatDateTime(SHIP_DATE, SHIP_TZ, False);
Syntax
Forward(from physical queue ID, from agent ID, task number, task type, to logical queue ID[, to agent ID])
Description
Use the Forward function to transfer a task from one agent to another agent or from one agent's logical queue to another logical queue. This enables agents to reroute tasks that are not appropriate for their skill level or functional expertise.
Keep the following in mind when using Forward:
The queue server subtracts the task's cost from the transferring agent's workload.
The system cannot forward tasks to logical queues that do not have active physical queues on the same MultiChannel Framework cluster as the physical queue to which the task currently belongs. That is, you can't forward tasks across MultiChannel Framework clusters.
A queue server does not allow a task to be transferred if the agent who owns that task is not logged on to that queue server. PeopleSoft recommends that you only use Forward for application pages that the MultiChannel Framework console launches when agents accept or activate assigned tasks.
Forward only applies to email and generic task types.
Parameters
Field or Control |
Definition |
---|---|
from physical queue ID |
The physical queue is the internal representation of the logical queue that the agent signs onto and to which the task currently belongs. This is a string value, such as “sales3” or “marketing2.” You retrieve the current
physical queue from the query string in the URL of the page launched
by the MultiChannel Framework console. Use the GetParameter request
class method with the value |
from agent ID |
Specifies the current agent, as in the agent that “accepted” the task. This is a string value. You retrieve the current
physical queue from the query string in the URL of the page launched
by the MultiChannel Framework console. Use the GetParameter request
class method with the value |
task number |
Identifies the task to be forwarded. The EnQueue function returns this value. This is a string value. You retrieve the current
physical queue from the query string in the URL of the page launched
by the MultiChannel Framework console. Use the GetParameter request
class method with the value |
task type |
Identifies the task type. This value is provided by the queue. This is a string value. Valid values are:
You retrieve the current
physical queue from the query string in the URL of the page launched
by the MultiChannel Framework console. Use the GetParameter request
class method with the value |
to logical queue ID |
Specifies the logical queue to which the system forwards the task. This is a string value. The queue ID is case sensitive and must match the case used when you created the queue using the Queues page. |
to agent ID |
This is an optional parameter. It is a string value specifying a particular agent ID to receive the forwarded task. If this value is specified, the system holds the task until the specified agent is available on the new queue to take this task. This means that the specified agent must be able to log in to one of the physical queues belonging to the destination logical queue. The system determines which physical queue the specified agent has access to and assigns the task to that queue for that agent. If the agent ID is not specified, the physical queue is chosen at random from the active physical queues. 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. |
Returns
Returns 0 on success.
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
Forward("SALES5", "TSAWYER", "email_2145", "email", "MARKETING", "GSALMON");
The following example shows how to retrieve parameters from the application page using the GetParameter request class method.
PSMCFFUNCLIB.MCF_QUEUE.Value = %Request.GetParameter("ps_qid");
PSMCFFUNCLIB.MCF_TASKTYPE.Value = %Request.GetParameter("ps_tasktype");
PSMCFFUNCLIB.MCF_TASKNUM.Value = %Request.GetParameter("ps_tasknum");
PSMCFFUNCLIB.MCF_AGENTID.Value = %Request.GetParameter("ps_agentid");
&nret = Forward(PSMCFFUNCLIB.MCF_QUEUE, PSMCFFUNCLIB.MCF_AGENTID,
PSMCFFUNCLIB.MCF_TASKNUM, PSMCFFUNCLIB.MCF_TASKTYPE, &ToQueue);
If &nret = 0 Then
MessageBox(0, "", 0, 0, "Successfully forwarded.");
End-If
Syntax
Function name[(paramlist)] [Returns data_type] [statements] End-Function
Where paramlist is:
¶m1 [As data_type] [, ¶m2 [As data_type]]...
Where data_type is any valid data type, including Number, String, Date, Rowset, SQL, Record, and so on.
Where statements is a list of PeopleCode statements.
Description
PeopleCode functions can be defined in any PeopleCode program. Function definitions must be placed at the top of the program, along with any variable and external function declarations.
Functions can be called from the program in which they are defined, in which case they don’t need to be declared, and they can be called from another program, in which case they need to be declared at the top of the program where they are called.
Any variables declared within a function are valid for the scope of the function.
By convention, external PeopleCode functions are stored in records whose names begin in FUNCLIB_, and they are always placed in the FieldFormula event (which is convenient because this event should no longer be used for anything else).
Note: Functions can be stored in the FieldFormula event only for record fields, not for component record fields.
A function definition consists of:
The keyword Function followed by the name of the function and an optional list of parameters. The name of the function can be up to 100 characters in length.
An optional Returns clause specifying the data type of the value returned by the function.
The statements to be executed when the function is called.
The End-function keyword.
The parameter list, which must be enclosed in parentheses, is a comma-separated list of variable names, each prefixed with the & character. Each parameter is optionally followed by the keyword As and the name for one of the conventional PeopleCode data types (Number, String, Date, and so on) or any of the object data types (such as Rowset, SQL, and so on.) If you specify data types for parameters, then function calls are checked to ensure that values passed to the function are of the appropriate type. If data types are not specified, then the parameters, like other temporary variables in PeopleCode, take on the type of the value that is passed to them.
Note: If a parameter is listed in the function definition, then it is required when the function is called.
PeopleCode parameters are always passed by reference. This means that if you pass the function a variable from the calling routine and change the value of the variable within the function, the value of the variable is changed when the flow of execution returns to the calling routine.
If the function is to return a result to the caller, the optional Returns part must be included to specify the data type of the returned value. You have seven choices of value types: Number, String, Date, Time, DateTime, Boolean, or Any.
PeopleCode internal subroutines are part of the enclosing program and can access the same set of variables as the other statement-lists of the program, in addition to local variables created by the parameters and local variable declarations within the function.
Returning a Value
You can optionally return a value from a PeopleCode function. To do so, you must include a Returns statement in the function definition, as described in the preceding section. For example, the following function returns a Number value:
Function calc_something(&parm1 as number, &parm2 as number) Returns number
In the code section of your function, use the Return statement to return the value to the calling routine. When the Return statement executes, the function ends and the flow of execution goes back to the calling routine.
Example
This example returns a Boolean value based on the return value of a SQLExec:
Function run_status_upd(&PROCESS_INSTANCE, &RUN_STATUS) Returns boolean;
&UPDATEOK = SQLExec("update PS_PRCS_RQST set run_status = :1 where process_instance = :2", &RUN_STATUS, &PROCESS_INSTANCE);
If &UPDATEOK Then
Return True;
Else
Return False;
End-If;
End-Function;