Functions
This section lists the PTF functions.
Note: Regarding the use of strings in functions: Typically, variables are used within functions, however, if you are using a string directly, it must be enclosed in quotes.
Syntax
Add(number1|number2[|number3]...)
Description
Use the Add function to add a series of numbers. Decimals and negative numbers are supported.
Parameters
|
Field or Control |
Definition |
|---|---|
| number1 |
Number to be added. |
| number2 |
Number to be added. |
| number3 |
(Optional) A series of additional numbers to be added. |
Returns
Sum of the numbers in the parameters.
Example
The following table presents examples of using Add.
|
Expression |
Result |
|---|---|
|
Add(10| -12| -3| 4| 6) |
5 |
|
Add(10.43| 10.55| -6.789| -178) |
-163.809 |
Syntax
Concat(string1|string2[|string3…])
Description
Concatenates the strings in the parameters.
Parameters
|
Field or Control |
Definition |
|---|---|
| string1 |
Beginning string for concatenation |
| string2 |
A string to be concatenated to string1. |
| string3… |
(Optional) Additional strings to be concatenated. |
Returns
Returns a string resulting from concatenating the strings in the parameters.
Example
The following table presents examples of using the Concat function:
|
Expression |
Result |
|---|---|
|
Concat(''hello ''|''and ''|''welcome '|''to ''|''PTF'') |
hello and welcome to PTF |
Syntax
Date()
Description
Returns the current date, using the date format specified in the current execution option.
Returns
The current date.
Example
The following table presents an example of using the Date function, where the current date is July 4, 2011:
|
Expression |
Result |
|---|---|
|
Date() |
07/04/2011 |
Syntax
Day(date_value)
Description
Returns the day portion of the date value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| date_value |
A date value, such as the value returned by the Date() function. |
Returns
Returns the day portion of the date value provided as a parameter.
Example
The following table presents examples of using the Day function; the second example assumes that the current day of the month is 13:
|
Expression |
Result |
|---|---|
|
Day(February 13, 2012) |
13 |
|
Day(Date()) |
13 |
Syntax
Divide(number1|number2|dec=dec_places)
Description
Use the Divide function to perform division. Decimals and negative numbers are supported. Optionally specify the number of decimal places.
Parameters
|
Field or Control |
Definition |
|---|---|
| number1 |
The dividend. |
| number2 |
The quotient. |
| dec=dec_places |
(Optional) The number of decimal places. The maximum is 10. The default is zero. Note that "dec=" must be included in the parameter. |
Returns
The result of dividing number1 by number2 rounded to dec=dec_places decimals.
Example
The following table presents examples of using the Divide function:
|
Expression |
Result |
|---|---|
|
Divide(75| 13.5) |
6 |
|
Divide(-75| 13.5| dec=5) |
-5.55556 |
Syntax
GetField(string, segment, delimiter)
Description
GetField returns the substring from a specified segment of a character-delimited text string.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
A character-delimited text string. |
| segment |
An integer specifying which segment of the string will be returned, counting left to right. Specify a negative integer to count right to left. |
| delimiter |
The character that delimits each segment in the string. |
Returns
Returns the substring between the delimiters in the specified segment of the string.
Example
The following table presents examples of using GetField.
|
Expression |
Result |
|---|---|
|
GetField(''a/b/c''| 1| ''/'') |
a |
|
GetField(''a/b/c''| 2| ''/'') |
b |
|
GetField(''a/b/c''| 5| ''/'') |
blank |
|
GetField(''a/b/c''| -1| ''/'') |
c |
Syntax
Hour(time_value)
Description
Returns the hour portion of the time value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| time_value |
A time value, such as the value returned by the Time() function. |
Returns
Returns the hour portion of the time value provided as a parameter.
Example
The following table presents examples of using the Hour function; the second example assumes that the current time is between 1:00 PM and 1:59:59 PM.:
|
Expression |
Result |
|---|---|
|
Hour(13:07:25) |
13 |
|
Hour(Time()) |
13 |
Syntax
InStr(within_string|substring)
Description
Locates a substring within a string of text and returns the starting position of the substring as an integer..
Parameters
|
Field or Control |
Definition |
|---|---|
| substring |
The text you are searching for. The string parameter is not case sensitive. |
| within_string |
The text string you are searching within. |
Returns
Returns an integer indicating the starting position of substring in within_string.
InStr returns 0 if substring does not appear in within_string. It returns 1 if substring is empty.
Example
The following table presents examples of using the InStr function.
|
Expression |
Result |
|---|---|
|
instr(''ABCDEFG''|''c'') |
3 |
|
instr(''ABCDEFG''|''C'') |
3 |
|
instr(''ABCDEFG''|''CDE'') |
3 |
|
instr(''ABCDEFG''|''zz'') |
0 |
|
instr(''ABCDEFG''|) |
1 |
|
instr(''ABCDEFG''|''A'') |
1 |
Syntax
LCase(string)
Description
Converts a string to lowercase.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
The string to be converted. |
Returns
Returns a string resulting from converting string to lowercase.
Example
The following table presents an example of using the LCase function.
|
Expression |
Result |
|---|---|
|
lcase(''Hello World 1234'') |
hello world 1234 |
Syntax
Left(string|length)
Description
Extracts a substring of a specified number of characters from the left side of a string.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
A string from which to extract a substring. |
| length |
A number specifying the number of characters in the substring. |
Returns
Returns a substring length characters long from the left side of a string.
Example
The following table presents an example of using Left function.
|
Expression |
Result |
|---|---|
|
left(''Hello World''|5) |
Hello |
Syntax
Len(string)
Description
Returns the length of string as an integer.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
A text string. |
Returns
Returns an integer indicating the length of string.
Example
The following table presents an example of using Len function.
|
Expression |
Result |
|---|---|
|
len(''Hello World'') |
11 |
Syntax
MakeDate(year_value | month_value | day_value)
Description
This function returns a date value based on the year, month, and day values passed to the function as parameters.
Parameters
|
Field or Control |
Definition |
|---|---|
| year_value |
A number representing the year, such as the value returned by the Year() function. |
| month_value |
A number representing the month, such as the value returned by the Month() function. |
| day_value |
A number representing the day, such as the value returned by the Day() function. |
Returns
Returns a date value.
Example
The following table presents examples of using the MakeDate function. In these examples, the current date was February 13, 2012:
|
Expression |
Result |
|---|---|
|
MakeDate(Add(Year(Date())|1)|Add(Month(Date())|11)|Add(Day(Date())|1) |
January 14, 2014 |
|
MakeDate(Add(Year(Date())|1)|Add(Month(Date())|-1)|Add(Day(Date())|-1) |
January 12, 2013 |
Syntax
MakeTime(hour_value | minute_value | second_value | rollover_boolean)
Description
This function returns a time value based on the hour, minute, and second values passed to the function as parameters.
Parameters
|
Field or Control |
Definition |
|---|---|
| hour_value |
A number representing the hour, such as the value returned by the Hour() function. |
| minute_value |
A number representing the minute, such as the value returned by the Minute() function. |
| second_value |
A number representing the second, such as the value returned by the Second() function. |
| rollover_boolean |
(Optional) Rolls over the hour to 0 when hour_value reaches 24. True - Returns (hour_value – 24) when hour_value is greater than 24. False - Returns hour_value even when hour_value is greater than 24. The default value is True. |
Returns
Returns a time value.
Example
The following table presents examples of using the MakeTime function:
|
Expression |
Result |
|---|---|
|
MakeTime(Add(Hour(Time())|12)|Add(Minute(Time())|-30)|Second(Time())) |
7:00:00 AM |
|
MakeTime(23|Add(60|30)|0|False) |
24:30:00 |
|
MakeTime(23|Add(60|30)|0|True) |
00:30:00 |
|
MakeTime(23|Add(60|-30)|0) |
23:30:00 |
Syntax
Minute(time_value)
Description
Returns the minute portion of the time value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| time_value |
A time value, such as the value returned by the Time() function. |
Returns
Returns the minute portion of the time value provided as a parameter.
Example
The following table presents examples of using the Minute function; the second example assumes that the current time is seven minutes past the hour:
|
Expression |
Result |
|---|---|
|
Minute(13:07:25 ) |
7 |
|
Minute(Time()) |
7 |
Syntax
Month(date_value)
Description
Returns the month portion of the date value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| date_value |
A date value, such as the value returned by the Date() function. |
Returns
Returns the month portion of the date value provided as a parameter.
Example
The following table presents examples of using the Month function; the second example assumes that the current month is February:
|
Expression |
Result |
|---|---|
|
Month(February 13, 2012) |
2 |
|
Month(Date()) |
2 |
Syntax
Multiply(number1|number2[|dec=dec_places])
Description
Use the Multiply function to perform multiplication. Decimals and negative numbers are supported. Optionally specify the number of decimal places.
Parameters
|
Field or Control |
Definition |
|---|---|
| number1 |
First factor. |
| number2 |
Second factor. |
| dec=dec_places |
(Optional) The number of decimal places. The maximum is 10. The default is zero. Note that "dec=" must be included in the parameter. |
Returns
The result of multiplying number1 by number2 rounded to dec=dec_places decimals.
Example
The following table presents examples of using Multiply function.
|
Expression |
Result |
|---|---|
|
Multiply(10.3| 13.45) |
139 |
|
Multiply(10.3| -13.45|dec=3) |
-138.535 |
Syntax
Now()
Description
Returns the current datetime, using the date format specified in the current execution option.
Returns
The current datetime.
Example
The following table presents an example of using the Now function, assuming that the function was called at 12:20 PM on July 4, 2011.
|
Expression |
Result |
|---|---|
|
Now() |
07/04/2011 12:20 PM |
Syntax
Replace(source|find|replace)
Description
Use the Replace function to replace every occurrence of a substring found in a string with a new substring.
Parameters
|
Field or Control |
Definition |
|---|---|
| source |
A string in which you want to replace substrings. |
| find |
A string equal to the substring of source you want to replace. |
| replace |
A string with which to replace occurrences of find in source. |
Returns
Returns a string resulting from replacing every occurrence of find found in source with replace.
Example
The following table presents an example of using the Replace function.
|
Expression |
Result |
|---|---|
|
replace(“original text”|“i”|77) |
Or77g77nal text |
Syntax
Right(string|length)
Description
Use the Right function to extract a substring of a specified number of characters from the right side of a string.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
A string from which to extract a substring. |
| length |
A number specifying the number of characters in the substring. |
Returns
Returns a substring length characters long from the right side of a string.
Example
The following table presents an example of using the Right function.
|
Expression |
Result |
|---|---|
|
right(''Hello World''|5) |
World |
Syntax
Round(number|[|dec=dec_places])
Description
Use the Round function to round a number. Decimals and negative numbers are supported. Optionally specify the number of decimal places.
Parameters
|
Field or Control |
Definition |
|---|---|
| number1 |
First factor. |
| number2 |
Second factor. |
| dec=dec_places |
(Optional) The number of decimal places. The maximum is 10. The default is zero. Note that "dec=" must be included in the parameter. |
Returns
The result of rounding number1 to dec=dec_places decimal places.
Example
The following table presents examples of using the Round function.
|
Expression |
Result |
|---|---|
|
Round(-130.456) |
-130 |
|
Round(-130.456|dec=2) |
-130.46 |
|
Round(-130.455|dec=2) |
-130.45 |
Syntax
Second(time_value)
Description
Returns the second portion of the time value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| time_value |
A time value, such as the value returned by the Time() function. |
Returns
Returns the second portion of the time value provided as a parameter.
Example
The following table presents examples of using the Second function; the second example assumes that the current time is 25 seconds after the minute:
|
Expression |
Result |
|---|---|
|
Second(13:07:25 ) |
25 |
|
Second(Time()) |
25 |
Syntax
SubStr(source_str|start_pos[|length])
Description
Extracts a substring of a specified number of characters beginning at a specified location in a source string.
If length is not specified, SubStr returns the substring starting at the position specified in start_pos and continuing to the end of the string.
Parameters
|
Field or Control |
Definition |
|---|---|
| source_str |
A string from which to extract a substring. |
| start_pos |
A number representing the character position in source_str where the substring starts, starting at 1. |
| length |
(Optional) A number specifying the number of characters in the substring. |
Returns
Returns a string equal to a substring length characters long beginning at character start_pos of source_str.
Example
The following table presents examples of using SubStr function.
|
Expression |
Result |
|---|---|
|
substr(''12345678''|2|3) |
234 |
|
substr(''12345678''|2) |
2345678 |
Syntax
Subtract(number1|number2[|number3]...])
Description
Use the Subtract function to subtract a series of numbers. Numbers can be decimal and negative.
Parameters
|
Field or Control |
Definition |
|---|---|
| number1 |
Initial number. |
| number2 |
Number to be subtracted. |
| number3… |
(Optional) A series of additional numbers to be subtracted. |
Returns
The result of subtracting number2, number3, etc., from number1.
Example
The following table presents examples of using the Subtract function.
|
Expression |
Result |
|---|---|
|
Subtract(10|2|3) |
5 |
|
Subtract(10|-2|-3) |
15 |
Syntax
Sum(Index|Value|Section|Delimiter)
Description
Sum works with the HTMLTable indexes.
Note: In PeopleTools releases prior to 8.53 commas were supported as a delimiter for the sum function parameters. If any tests exist in the database using that format, the commas will be converted to pipes in the upgrade.
Parameters
|
Field or Control |
Definition |
|---|---|
| Index |
The HTMLTable index string, such as 2/5/4. An index string is the return value of CellGetIndex. See CellGetIndex. |
| Value |
The value that you want to add or subtract. The default action is addition. |
| Section |
The section of the index that will be modified. |
| Delimiter |
The character that delimits each section in the text value. The character must be enclosed in quotes. |
Example
The following table presents examples of using the Sum function.
|
Expression |
Result |
|---|---|
|
sum("2/5/4"|2|1|"/") |
4/5/4 2 is added to the first section of the string. |
|
sum("2/5/4"|-1|3|"/") |
2/5/3 1 is subtracted from the third section of the string. |
|
Sum(&index|-4|3|"/") |
4 is subtracted from the third section of the string in the variable &index. |
Syntax
Time()
Description
Returns the current time, using the date format specified in the current execution option.
Parameters
None
Returns
Returns a string with the current time.
Example
The following table presents examples of using the Time function with the regional options set to 24 hour format and 12 hour format, respectively:
|
Expression |
Result |
|---|---|
|
Time() |
13:07:25 |
|
Time() |
1:07:25 PM |
Syntax
Trim(string)
Description
Returns a string with all leading and trailing spaces removed.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
A text string. |
Returns
Returns a string with all leading and trailing spaces removed.
Example
The following table presents an example of using trim function.
|
Expression |
Result |
|---|---|
|
trim('' Hello World '') |
Hello World |
Syntax
UCase(string)
Description
Converts a string to uppercase.
Parameters
|
Field or Control |
Definition |
|---|---|
| string |
The string to be converted. |
Returns
Returns a string resulting from converting string to uppercase.
Example
The following table presents an example of using UCase function.
|
Expression |
Result |
|---|---|
|
ucase(''Hello World 1234") |
HELLO WORLD 1234 |
Syntax
Weekday(date_value)
Description
Returns an integer value, ranging from 1 through 7, which represents the day of the week for the date value provided as a parameter, where Sunday equals 1 and Saturday equals 7.
Parameters
|
Field or Control |
Definition |
|---|---|
| date_value |
A date value, such as the value returned by the Date() function, or “10/29/2104” |
Returns
Returns an integer value, ranging from 1 through 7, which represents the day of the week for the date value provided as a parameter, where Sunday equals 1 and Saturday equals 7.
Example
The following table presents examples of using the Weekday function; the second example assumes that Tuesday is the weekday of the current date:
|
Expression |
Result |
|---|---|
|
Weekday(October 18, 2014) |
6 |
|
Weekday(Date()) |
3 |
|
Weekday("07/29/2013") |
2 |
Syntax
Year(date_value)
Description
Returns the year portion of the date value provided as a parameter.
Parameters
|
Field or Control |
Definition |
|---|---|
| date_value |
A date value, such as the value returned by the Date() function. |
Returns
Returns the year portion of the date value provided as a parameter.
Example
The following table presents examples of using the Year function; the second example assumes that the current year is 2012:
|
Expression |
Result |
|---|---|
|
Year(February 13, 2012 ) |
2012 |
|
Year(Date()) |
2012 |