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:

  • APPSRV

  • DB2ODBC

  • DB2UNIX

  • MICROSFT

  • ORACLE

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:

  • %FilePath_Relative (default)

  • %FilePath_Absolute

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:

  • %FilePath_Relative (default)

  • %FilePath_Absolute

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:

  • timezone - a time zone abbreviation or a field reference to be used for converting datetime.

  • Local - use the local time zone for converting datetime.

  • Base - use the base time zone for converting datetime.

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 ps_qid

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 ps_agentid.

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 ps_tasknum.

task type

Identifies the task type. This value is provided by the queue. This is a string value. Valid values are:

  • email

  • generic

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 ps_tasktype.

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:

&param1 [As data_type] [, &param2 [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;