PeopleCode Built-in Functions and Language Constructs: D

Syntax

Date(date_num)

Description

The Date function takes a number in the form YYYYMMDD and returns a corresponding Date value. If the date is invalid, Date displays an error message.

Warning! Make sure that you pass a four-digit year in the year parameter of this function. Two-digit values are interpreted literally: 93, for example, represents the year 93 AD.

Returns

Returns a date equal to the date specified in date_num.

Example

Set the temporary variable &HIREDate to a date field containing the date July 1, 1997:

&HIREDate = Date(19970701);

Syntax

Date3(year, month, day)

Description

The Date3 function accepts a date expressed as three integers: year, month, and day. It returns a corresponding Date value. If the date is invalid, the Date3 displays an error message.

Warning! Make sure that you pass a four-digit year in the year parameter of this function. Two-digit values will be interpreted literally: 93, for example, represents the year 93 AD.

Parameters

Field or Control	Definition
`year`	An integer for the year in the form YYYY.
`month`	An integer from 1 to 12 designating the month.
`day`	An integer from 1 to 31 designating the day of the month.

Returns

Returns a Date value equal to the date specified in the function parameters.

Example

The following PeopleCode Date3 function returns the first day of the year in which the employee was hired:

Date3(HIRE_YEAR, 1, 1);

Syntax

DatePart(datetime_value)

Description

Use the DatePart function to determine a date based on a provided DateTime value.

Returns

Returns a Date value equal to the date part of a specified DateTime value.

Example

The following statement sets &D2 to a Date value for 11/12/1997:

&D1 = DateTimeValue("11/12/1997 10:23:15 AM");
&D2 = DatePart(&D1);

Syntax

DateTime6(year, month, day, hour, minute, second)

Description

The DateTime6 function returns a DateTime value based on integer values for the year, month, day, hour, minute, and second. If the result of this function is not an actual date, there is a runtime error.

Warning! Make sure that you pass a four-digit year in the year parameter of this function. Two-digit values will be interpreted literally: 93, for example, represents the year 93 AD.

Parameters

Field or Control	Definition
`year`	A four-digit number representing the year.
`month`	A number between 1 and 12 representing the month.
`day`	A number representing the day of the month.
`hour`	A number from 0 to 23 representing the hour of the day.
`minute`	A number from 0 to 59 representing the minute of the hour.
`second`	A number from 0 to 59.999999 representing seconds.

Returns

Returns a DateTime value based on the integers provided.

Example

The following example sets &DTTM to a DateTime value equal to 10:09:20 on March 15, 1997:

&DTTM = DateTime6(1997, 3, 15, 10, 9, 20);

Syntax

DateTimeToHTTP(datetime)

Description

Use the DateTimeToHTTP function to convert any DateTime value to a date/time string in the format specified by HTTP 1.0 and 1.1 standards.

Note: Because the HTTP protocol is used to interchange information between diverse computing systems, the value returned from this function is always the ”US English” form of weekdays and months. If you want the value to use the localized form, use the DateTimeToLocalizeString function instead.

The standard HTTP date/time has the following fixed length format:

<dow><,><sp><dd><sp><mon><sp><year><sp><hh><:><mm><:><ss><sp><GMT>

where:

Value	Description
<dow>	a 3-character day of week name, one of Sun, Mon, Tue, Wed, Thu, Fri, Sat.
<,>	a literal comma character
<sp>	a literal space character
<dd>	a 2-digit day of month, such as 02 or 22.
<mon>	is a 3-character month name, one of Jan, Feb, Mar, and so on.
<year>	a 4-digit year number
<hh>	a 24-hour hour number, such as 00 or 13
<mm>	a 2-digit minute number, such as 01 or 56
<ss>	a 2-digit second number, such as 03 or 59
<GMT>	a literal 3-character GMT.

As indicated by the trailing GMT, this date/time format is always expressed in GMT (or UTC, which is declared to be the same for the purposes of HTTP).

Parameters

Field or Control	Definition
`datetime`	Specify the DateTime value you want converted to HTTP format. This DateTime is assumed to be in the base time zone of the installation.

Returns

A string containing the converted HTTP date/time.

Example

&gmtdate = DateTimeToHTTP(AddToDateTime(%DateTime, 0,0,0,0,600,0));

%Response.setHeader("Last-Modified", &gmtdate);

Syntax

DateTimeToISO(textdatetime)

Description

Use the DatetimeToISO function to convert the text value textdatetime (as a base time zone time) to a DateTime value in ISO 8601 format. This function automatically calculates whether daylight saving time is in effect for the given textdatetime.

The system’s base time zone is specified in the PSOPTIONS table.

Parameters

Field or Control	Definition
`textdatetime`	Specify a date/time represented as text in the ISO 8601 format: `YYYY`-`MM`-`DD`T`hh`:`mm`:`ss`[.`S`] (for example, 1999-01-01T19:20:30.000000) In which: `YYYY` is a four-digit year. `MM` is a two-digit month (01 through 12). `DD` is a two-digit day of the month (01 through 31). `hh` is a two digits of hour (00 through 23). `mm` is a two digits of minute (00 through 59). `ss` is two digits of second (00 through 59). `S` is milliseconds in one or up to six digits. `TZD` is a time zone designator (Z, +/-`hh`:`mm` or +/-`hhmm`).

Field or Control

Definition

textdatetime

Specify a date/time represented as text in the ISO 8601 format: YYYY-MM-DDThh:mm:ss[.S] (for example, 1999-01-01T19:20:30.000000)

In which:

YYYY is a four-digit year.
MM is a two-digit month (01 through 12).
DD is a two-digit day of the month (01 through 31).
hh is a two digits of hour (00 through 23).
mm is a two digits of minute (00 through 59).
ss is two digits of second (00 through 59).
S is milliseconds in one or up to six digits.
TZD is a time zone designator (Z, +/-hh:mm or +/-hhmm).

Returns

Returns a DateTime value in ISO 8601 format.

Example

In the following example, assuming the base time (as defined in PSOPTIONS) is PST, &DATETIME would have a DateTime value of "1999-01-01T01:00:00.000000-08:00":

&DATETIME= DateTimeToISO("1999-01-01 01:00:00.000000");

Syntax

DateTimeToLocalizedString({datetime | date}, [Pattern])

Description

Use the DateTimeToLocalizedString function to convert either datetime or date to a localized string. You can also specify a particular pattern to convert datetime or date to.

The Pattern is optional. Only specify Pattern if necessary.

If you need to change the pattern for each language, change the first message in Message Catalog set number 138. This is a format for each language.

Parameters

Field or Control	Definition
`datetime \| date`	Specify either the DateTime or Date value that you want to convert.
`Pattern`	Specify the pattern you want to the localized DateTime or Date value to be converted to.

Using the Pattern Parameter

Pattern takes a string value, and indicates how you want the DateTime or Date value converted.

The valid values for Pattern are as follows.

Note: The values for pattern are case-sensitive. For example, if you specify a lowercase m, you get minutes, while an uppercase M displays the month.

Symbol	Definition	Type	Example
G	Era designator	Text	AD
y	Year	Number	1996
M	Month in year	Text&Number	July&07
d	Day in month	Number	10
h	Hour in am/pm	Number (1-12)	12
H	Hour in day	Number (0-23)	0
m	Minute in hour	Number	30
s	Second in minute	Number	55
S	Millisecond	Number	978
E	Day in week	Text	Tuesday
a	am/pm marker	Text	PM
k	Hour in day	Number (1-24)	24
K	Hour in am/pm	Number (0-11)	0
'	Escape for text	Delimiter
''	Single quote	Literal	'

The number of pattern letters determine the format.

Type	Pattern Format
Text	If 4 or more pattern letters are used, the full form is used. If less than 4 pattern letters are used, the short or abbreviated form is used if one exists.
Number	Use the minimum number of digits. Shorter numbers are zero-padded to this amount. The year is handled specially; that is, if the count of 'y' is 2, the year is truncated to 2 digits.
Text&Number	If 3 or more pattern letters are used, text is used, otherwise, a number is used.

Type

Pattern Format

Text

If 4 or more pattern letters are used, the full form is used. If less than 4 pattern letters are used, the short or abbreviated form is used if one exists.

Number

Use the minimum number of digits. Shorter numbers are zero-padded to this amount.

The year is handled specially; that is, if the count of 'y' is 2, the year is truncated to 2 digits.

Text&Number

If 3 or more pattern letters are used, text is used, otherwise, a number is used.

Any characters in Pattern are not in the ranges of ['a'..'z'] and ['A'..'Z'] are treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' appear in the resulting string even they're not within single quotes.

A pattern containing any invalid pattern letter results in a runtime error.

Examples using a United States locale:

Pattern	Result
"yyyy.MM.dd G 'at' hh:mm:ss"	1996.07.10 AD at 15:08:56
"EEE, MMM d, ''yy"	Wed, July 10, '96
"h:mm a"	12:08 PM
"hh 'o''clock' a"	12 o'clock PM
"K:mm a"	0:00 PM
"yyyyy.MMMMM.dd GGG hh:mm aaa"	1996.July.10 AD 12:08 PM

Returns

A string.

Example

REM**************************************************************; 
Function ConvertDateToDTTM(&Date As date) Returns DateTime ; 
REM ***********************************************************; 
   &String = DateTimeToLocalizedString(&Date, "M/d/y"); 
   &String = &String | " 00:00:00.000000"; 
   &DateTime = DateTimeValue(&String); 
   Return &DateTime; 
End-Function;

Syntax

DateTimeToTimeZone(OldDateTime, SourceTimeZone, DestinationTimeZone)

Description

Use the DateTimeToTimeZone function to convert DateTime values from the DateTime specified by SourceTimeZone to the DateTime specified by DestinationTimeZone.

Considerations Using this Function

Typically, this function is used in PeopleCode, not for displaying time. If you take a DateTime value, convert it from base time to client time, then try to display this time, depending on the user settings, when the time is displayed the system might try to do a second conversion on an already converted DateTime. This function could be used as follows: suppose a user wanted to check to make sure a time was in a range of times on a certain day, in a certain timezone. If the times were between 12 AM and 12 PM in EST, these resolve to 9 PM and 9 AM PST, respectively. The start value is after the end value, which makes it difficult to make a comparison. This function could be used to do the conversion for the comparison, in temporary fields, and not displayed at all.

Parameters

Field or Control	Definition
`OldDateTime`	Specify the DateTime value to be converted.
`SourceTimeZone`	Specify the time zone that `OldDateTime` is in. Valid values are: `timezone -` a time zone abbreviation or a field reference to be used for converting `OldDateTime`. Local - use the local time zone for converting `OldDateTime`. Base - use the base time zone for converting `OldDateTime`.
`DestinationTimeZone`	Specify the time zone that you want to convert `OldDateTime` to. Valid values are: `timezone -` a time zone abbreviation or a field reference to be used for converting `OldDateTime`. Local - use the local time zone for converting `OldDateTime`. Base - use the base time zone for converting `OldDateTime`.

Field or Control

Definition

OldDateTime

Specify the DateTime value to be converted.

SourceTimeZone

Specify the time zone that OldDateTime is in. Valid values are:

timezone - a time zone abbreviation or a field reference to be used for converting OldDateTime.
Local - use the local time zone for converting OldDateTime.
Base - use the base time zone for converting OldDateTime.

DestinationTimeZone

Specify the time zone that you want to convert OldDateTime to. Valid values are:

timezone - a time zone abbreviation or a field reference to be used for converting OldDateTime.
Local - use the local time zone for converting OldDateTime.
Base - use the base time zone for converting OldDateTime.

Returns

A converted DateTime value.

Example

The following example. TESTDTTM, is a DateTime field with a value 01/01/99 10:00:00. This example converts TESTDTTM from Pacific standard time (PST) to eastern standard time (EST).

&NEWDATETIME = DateTimeToTimeZone(TESTDTTM, "PST", "EST");

&NEWDATETIME will have the value 01/01/99 13:00:00 because EST is three hours ahead of PST on 01/01/99, so three hours are added to the DateTime value.

Syntax

DateTimeToUserFormat(textdatetime, {timezone | "Local" | "Base"})

Description

Use the DateTimeToUserFormat function to convert the string value textdatetime in PeopleSoft internal date/time format to a date/time value in the user's personalized date/time format for a specified time zone.

The format for the return value is determined in the following order of precedence:

User personalizations if they exist.
If there are no user personalizations, then any format specified by the browser language setting in PSLOCALEDEFN.
If there are no user personalizations and there is no browser session to determine the browser language settings (for example, when running an Application Engine program directly in Application Designer), the system’s regional language setting is used to determine the format.

For example, if the user's date and time format personalization settings are DDMMYY and 24-hour clock, the following function invocation returns a DateTime string equal to 27/09/2011 08:00:00.

&DTM = DateTimeToUserFormat("2011-09-27 08:00:00.000000", "Base");

Parameters

Field or Control	Definition
`textdatetime`	Specifies a String value representing a date/time value in the PeopleSoft internal format: `YYYY`-`MM`-`DD` `hh`:`mm`:`ss`.`SSSSSS` (for example, 1999-01-01 19:20:30.000000) In which: `YYYY` is a four-digit year. `MM` is a two-digit month (01 through 12). `DD` is a two-digit day of the month (01 through 31). `hh` is two digits of hour (00 through 23). `mm` is two digits of minute (00 through 59). `ss` is two digits of second (00 through 59). `S` is milliseconds in one or up to six digits.
`timezone` \| "Local" \| "Base"	Specifies a String value to indicating the time zone to convert to. The values are: `timezone` – A time zone abbreviation or a field reference. "Local" – Use the local time zone. "Base" – Use the base time zone.

Field or Control

Definition

textdatetime

Specifies a String value representing a date/time value in the PeopleSoft internal format: YYYY-MM-DD hh:mm:ss.SSSSSS (for example, 1999-01-01 19:20:30.000000)

In which:

YYYY is a four-digit year.
MM is a two-digit month (01 through 12).
DD is a two-digit day of the month (01 through 31).
hh is two digits of hour (00 through 23).
mm is two digits of minute (00 through 59).
ss is two digits of second (00 through 59).
S is milliseconds in one or up to six digits.

timezone | "Local" | "Base"

Specifies a String value to indicating the time zone to convert to. The values are:

timezone – A time zone abbreviation or a field reference.
"Local" – Use the local time zone.
"Base" – Use the base time zone.

Returns

Returns a DateTime value in user format for the specified time zone.

Example

In the following example, assuming the base time (as defined in PSOPTIONS) is PST, &DT would have a value of "1999-01-13 22:00:00":

&DT= DateTimeToUserFormat("1999-01-13 19:00:00.000000","EST");

Syntax

DateTimeValue(textdatetime)

Description

Use the DateTimeValue function to derive a DateTime value from a string representing a date and time.

Using this Function in Fields Without a Default Century Setting

This function may derive the wrong century setting if passed a two-character year and DateTimeValue is executing in a PeopleCode event not associated with a field that has a default century setting.

For example, assume that TEST_DATE is a date field with a default century setting of 10. TEST_FIELD is a field with no default century setting. If the following PeopleCode program is executing in TEST_FIELD, the date will be calculated incorrectly:

TEST_DATE = DateTimeValue("10/13/11 15:34:25");

Although TEST_DATE has a century setting, it isn’t used because the PeopleCode fired in TEST_FIELD. Instead, DateTimeValue uses the 50/50 rule and calculates the year to be 2011 (instead of 1911).

Parameters

Field or Control	Definition
`textdatetime`	Specify a date/time value represented as text in one of three formats: `MM`/`DD`/`YY`[`YY`] `hh`:`mm`:`ss.ssssss` [{AM\|PM}] `MM`.`DD`.`YY`[`YY`] `hh`:`mm`:`ss.ssssss` [{AM\|PM}] `YYYY`-`MM`-`DD`T`hh`:`mm`:`ss`[.`S`]`TZD` (that is, ISO 8601 format—for example, 1999-01-01T19:20:30.000000+0800) In which: `YY`[`YY`] is a two- or four-digit year. `YYYY` is a four-digit year. `MM` is a two-digit month (01 through 12). `DD` is a two-digit day of the month (01 through 31). `hh` is a two digits of hour (00 through 23). `mm` is a two digits of minute (00 through 59). `ss` is two digits of second (00 through 59). `ssssss` is six digits of milliseconds. `S` is milliseconds in one or up to six digits. `TZD` is a time zone designator (Z, +/-`hh`:`mm` or +/-`hhmm`).

Field or Control

Definition

textdatetime

Specify a date/time value represented as text in one of three formats:

MM/DD/YY[YY] hh:mm:ss.ssssss [{AM|PM}]
MM.DD.YY[YY] hh:mm:ss.ssssss [{AM|PM}]
YYYY-MM-DDThh:mm:ss[.S]TZD (that is, ISO 8601 format—for example, 1999-01-01T19:20:30.000000+0800)

In which:

YY[YY] is a two- or four-digit year.
YYYY is a four-digit year.
MM is a two-digit month (01 through 12).
DD is a two-digit day of the month (01 through 31).
hh is a two digits of hour (00 through 23).
mm is a two digits of minute (00 through 59).
ss is two digits of second (00 through 59).
ssssss is six digits of milliseconds.
S is milliseconds in one or up to six digits.
TZD is a time zone designator (Z, +/-hh:mm or +/-hhmm).

Returns

Returns a DateTime value.

Example

Both of the following examples set &Date_TIME to a DateTime value equal to October 13, 1997 10:34:25 PM.:

&Date_TIME = DateTimeValue("10/13/97 10:34:25 PM");
&Date_TIME = DateTimeValue("10/13/97 22:34:25");

Assuming the base time (as defined in PSOPTIONS) is PST, the following three examples set &Date_TIME to a DateTime value equal to 2009-12-31-22.30.40.120000 UTC:

&Date_Time = DateTimeValue("2010-01-01 06:30:40.12Z");
&Date_Time = DateTimeValue("2010-01-01 00:30:40.12-0600");
&Date_Time = DateTimeValue("2010-01-01 10:30:40.12+04:00");

Syntax

DateValue(date_str)

Description

Use the DateValue function to convert a date string and returns the result as a Date type. date_str must be a string in the active date format user's current personalization date format.

If the user's Date Format personalization setting is set to DDMMYY (or it is defaulted to this from their browser locale or the system-wide personalization defaults) then the following code returns a Date value equal to September 10, 1997.

&DTM = DateValue("10/09/97");

If the user's Date Format personalization setting is set to MMDDYY (or it is defaulted to this from their browser locale or the system-wide personalization defaults) then the same function call returns a value equal to October 9, 1997.

Using this Function in Fields Without a Default Century Setting

This function may derive the wrong century setting if passed a 2-character year and DateValue is executing in a PeopleCode event not associated with a field that has a default century setting.

For example, assume that TEST_DATE is a date field with a default century setting of 10. TEST_FIELD is a field with no default century setting. If the following PeopleCode program is executing in TEST_FIELD, the date will be calculated incorrectly:

TEST_DATE = DateValue("10/13/11");

Though TEST_DATE has a century setting, it isn’t used because the PeopleCode fired in TEST_FIELD. Instead, DateValue uses the 50/50 rule and calculates the year to be 2011 (instead of 1911).

Returns

Returns a Date value.

Syntax

Day(dt_val)

Description

Use the Day function to determine an integer representing the day of the month based on a Date or DateTime value.

Returns

Returns a Number value equal to the day of the month for dt_val. The return value is an integer from 1 to 31.

Example

If HIRE_DATE is November, 1, 1997, the following Day function returns the integer 1:

&FIRST_DAY = Day(HIRE_DATE);

Syntax

Days(dt_val)

Description

Use the Days function to returns the Julian date for the dt_val specified. This function accepts a Date, DateTime, or Time value parameter.

Returns

Returns a Number value equal to the Julian date for dt_val.

Example

To find the number of days between two dates, use the Days function on both dates, and subtract one from the other:

&NUM_DAYS = Abs(Days(HIRE_Date) - Days(RELEASE_Date));

Syntax

Days360(date_val1, date_val2)

Description

Use the Days360 function to return the number of days between the Date values date_val1 and date_val2 using a 360-day year (twelve 30-day months). Use this function to help compute payments if your accounting system is based on twelve 30-day months.

If date_val2 occurs before date_val1, Days360 returns a negative number.

Example

The following example sets &NUMDAYS to the number of days between TERM_START_DT and PMT_DT based on a 360-day calendar:

&NUMDAYS = Days360(TERM_START_DT, PMT_DT);

Syntax

Days365(date_val1, date_val2)

Description

Use the Days365 function to return the number of days between the Date values date_val1 and date_val2 using a 365-day year. Use this function to help compute payments if your accounting system is based on a 365-day year.

If date_val2 occurs before date_val1, Days365 returns a negative number.

Returns

Returns a Number value equal to the number of days between the two dates in a 365-day calendar.

Example

The following example sets &NUMDAYS to the number of days between and TERM_START_DT and PMT_DT, based on a 365-day calendar:

&NUMDAYS = Days360(TERM_START_DT, PMT_DT);

Syntax

DBCSTrim(source_str)

Description

Note: This function has been deprecated.

Use the DBCSTrim function to remove a trailing DBCS lead byte at the end of the string.

Syntax

DBPatternMatch(Value, Pattern, CaseSensitive)

Description

Use the DBPatternMatch function to match the string in Value to the given pattern.

You can use wildcard characters % and _ when searching. % means find all characters, while _ means find a single character. For example, if you wanted to find if the string in Value started with the letter M, you'd use "M%" for Pattern. If you wanted to find either DATE or DATA, use "DAT_" for Pattern.

These characters can be escaped (that is, ignored) using a \. For example, if you want to search for a value that contains the character %, use \% in Pattern.

If Pattern is an empty string, this function retrieves the value just based on the specified case-sensitivity (that is, specifying "" for Pattern is the same as specifying "%").

Parameters

Field or Control	Definition
`Value`	Specify the string to be searched.
`Pattern`	Specify the pattern to be used when searching.
`CaseSensitive`	Specify whether the search is case-sensitive. This parameter takes a Boolean value: True, the search is case-sensitive, False, it is not.

Returns

Returns a Boolean value. True if the string matches the pattern, False otherwise.

Syntax

DeChunkText(table_name, seq_field, data_field, &array_of_keys, &array_of_key_datatypes, &array_of_key_values)

Description

Use the DeChunkText function to read the chunks created by the ChunkText function from a database table and assemble them back into a long text string.

Parameters

Field or Control	Definition
`table_name`	Specify the name of the database table as a string. This table stores the chunks created by ChunkText.
`seq_field`	Specify the name of the field that stores the sequence number for each chunk as a string.
`data_field`	Specify the name of the field that stores the data chunks as a string.
`&array_of_keys`	Specify key field names as an array of string.
`&array_of_key_datatypes`	Specify the types for the key fields as an array of string. See below.
`&array_of_key_values`	Specify the key field values as an array of string.

The values for &array_of_key_datatypes can be as follows:

Value	Description
STR	String value
CHAR	Single character
LONGTEXT	Long text value
DATE	Date value
TIME	Time value
DATETIME	Date/time value
INT	Integer value
SHORT	Short integer value
LONG	Long integer value
DOUBLE	Double-sized integer value

Returns

A string.

Example

Local array of string &key_names;
Local array of string &keyfdatatypes;
Local array of string &key_vals;
Local string &text;

&tablename = "PSPCMTXT";
&seq_fld = "SEQNUM";
&data_fld = "PEOPLECODE";

&key_names = CreateArray("OBJECTID1", "OBJECTVALUE1", "OBJECTID2", "OBJECTVALUE2", "OBJECTID3", "OBJECTVALUE3");
&keyfdatatypes = CreateArray("INT", "STR", "INT", "STR", "INT", "STR");
&key_vals = CreateArray("1", "PSTRANSFRM_WRK", "2", "IB_TRANSFORM_PB", "12", "FieldChange");

&text = DeChunkText(&tablename, &seq_fld, &data_fld, &key_names, &keyfdatatypes, &key_vals);

Syntax

PeopleCode Function Syntax

Declare Function function_name PeopleCode record_name.field_name event_type

External Library Function Syntax

Declare Function function_name Library lib_name
    [Alias module_name]
    [paramlist]
    [Returns ext_return_type [As pc_type]]

In which paramlist is:

([ext_param1 [, ext_param2] . . .)

And in which ext_param1, ext_param2, and so on is:

ext_datatype [{Ref|Value}] [As pc_return_type]

Description

PeopleCode can call PeopleCode functions defined in any field on any record definition. You can create special record definitions whose sole purpose is to serve as function libraries. By convention, PeopleCode functions are stored in FieldFormula PeopleCode, in record definitions with names beginning in FUNCLIB_.

PeopleCode can also call external programs that reside in dynamic link libraries. You must declare either of these types of functions at the top of the calling program using the Declare Function statement.

To support processes running on an application server, you can declare and call functions compiled in dynamic link libraries on windows (*.DLL files) and shared libraries on UNIX (lib*.so files.) The PeopleCode declaration and function call syntax is the same regardless of platform, but UNIX libraries must be compiled with an interface function.

See Calling DLL Functions on the Application Server.

PeopleCode Functions

You can call a PeopleCode function defined on any record definition, provided you declare it at the top of the calling program. The declaration identifies the function name, as well as the record, field, and event type where the function definition resides. The function parameters and return type are not declared; they are determined from the function definition.

Note: You can define functions only in record field PeopleCode. You can’t define functions in component PeopleCode, component record Field PeopleCode, and so on.

External Library Functions

Function declarations define routines in an external (C-callable) library. The function declaration provides the name of the library, an optional alias module_name, a list of parameters to pass to the function, an optional Returns clause specifying the type of any value returned by the external function, and the PeopleCode data type into which to convert the returned value. The library must be a DLL accessible by Windows or a shared library accessible by UNIX.

After you have declared an external library function, you can call it the same way as an external PeopleCode function. Like PeopleCode functions, you must pass the number of parameters the library function expects. Calls to external functions suspend processing: this means that you should exercise caution to avoid “think-time” errors when calling the function in 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.

See Think-Time Functions.

Parameters

The following are the parameters for the PeopleCode function syntax:

Field or Control	Definition
`function_name`	Name of the function.
PeopleCode	Reserved word that identifies the function as a PeopleCode function.
`recordname.fieldname`	Specifies the record and field where the function is located.
`event_type`	Component Processor event with which the function is associated.

Note: event_type can be used to specify record field events only. You can’t specify a component record field event, a component record event, and so on.

The following are the parameters for the external library function syntax:

Field or Control	Definition
`function_name`	Name of the function.
Library	Reserved word that identifies the function as an external library function.
`lib_name`	A string representing the name of the external library. The external routine must be located in a DLL named `lib_name` accessible by Windows, or an equivalent shared library in a UNIX system.
Alias `module_name`	Optionally specifies the name of the function’s entry point within the shared library. This is needed only if the C function name differs from `function_name` in the PeopleCode external function declaration. The external module is invoked using the __stdcall calling convention on Windows.
`paramlist`	List of parameters expected by the function, each in the form: `ext_datatype` [{Ref \| Value}] [As `pc_type`]
`ext_datatype`	The data type of the parameter expected by the function. To specify the type you can use any of the following: BOOLEAN INTEGER LONG UINTEGER ULONG STRING STRING FLOAT DOUBLE
Ref \| Value	Optionally use one of these two reserved words to specify whether the parameter is passed by reference or by value. If Ref is specified, it is passed by pushing a reference (pointer) on the stack. If Value is specified the value is pushed on the stack (for integers, and so on.) If neither is specified, Ref is assumed.
As `pc_type`	Specifies PeopleCode data type of the value passed to the function. You can choose between PeopleCode data types String, Number, Integer, Float, Date, Boolean, and Any.
Returns `ext_return_type`	Specifies the data type of any value returned by the function. The Returns clause is omitted if the function is void (returns no value.) To specify the return type you can use any of the following: BOOLEAN INTEGER LONG UINTEGER ULONG FLOAT DOUBLE The types String and LString are not allowed for the result type of a function.
As `pc_return_type`	Specifies the PeopleCode data type of the variable or field into which to read the returned value. You can choose between PeopleCode data types String, Number, Integer, Float, Date, Boolean, and Any. If the As clause is omitted, PeopleTools selects an appropriate type based on the type of value returned by the external function (for example, all integer and floating point types are converted to Number).

Example

Assume you have defined a PeopleCode function called VerifyZip. The function definition is located in the record definition FUNCLIB_MYUTILS, in the record field ZIP_EDITS, attached to the FieldFormula event. You would declare the function using the following statement:

Declare Function verifyzip PeopleCode FUNCLIB_MYUTILS.ZIP_EDITS FieldFormula;

Now assume you want to declare a function called PCTest in PSUSER.DLL. It takes an integer and returns an integer. You would write this declare statement:

Declare Function pctest Library "psuser.dll"
      (integer Value As number) Returns integer As number;

Syntax

Decrypt(KeyString, EncryptedString)

Description

Use the Decrypt function to decrypt a string previously encrypted with the Encrypt function. This function is generally used with merchant passwords. For this function to decrypt a string successfully, you must use the same KeyString value used to encrypt the string.

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 ("").
`EncryptedString`	Specify the string you want decrypted.

Returns

A clear text string.

Example

Encrypt and Decrypt support only strings.

&AUTHPARMS.WRKTOKEN.Value = Decrypt("", RTrim(LTrim(&MERCHANTID_REC.CMPAUTHNTCTNTOKEN.Value)));

Syntax

Degrees(angle)

Description

Use the Degrees function to convert the given angle from radian measurement to degree measurement.

Parameters

Field or Control	Definition
`angle`	The size of an angle in radians.

Returns

The size of the given angle in degrees.

Example

The following example returns the equivalent size in degrees of an angle measuring 1.2 radians:

&DEGREE_SIZE = Degrees(1.2);

Syntax

DeleteAttachment(URLSource, DirAndSysFileName[, PreserveCase])

Description

Use the DeleteAttachment function to delete a file from the specified storage location.

DeleteAttachment does not generate any type of “Are you sure?” message. If you want the end user to verify the deletion before it is performed, you must write your own checking code in your application.

Additional information that is important to the use of DeleteAttachment can be found in the PeopleTools: PeopleCode Developer's Guide:

PeopleTools supports multiple types of storage locations.
See Understanding File Attachment Storage Locations.
Certain characters are illegal in file names; other characters in file names are converted during file transfer.
See File Name Considerations.
Non-ASCII file names are supported by the PeopleCode file attachment functions.
See Attachments with non-ASCII File Names.

You can use a file extension list to identify file types to accept or reject when using this function.

See Using Administration Utilities.

Parameters

Field or Control	Definition
`URLSource`	A reference to a URL. This can be either a URL identifier in the form URL.`URL_ID`, or a string. This, along with the `DirAndSysFileName` parameter, indicates the file's location. Note: When the `URLSource` parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value. See Understanding URL Strings Versus URL Objects.
`DirAndSysFileName`	The relative path and system file name of the file on the file server. This is appended to `URLSource` to make up the full URL where the file is deleted from. This parameter takes a string value. Note: Because the `DirAndSysFileName` parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter.
`PreserveCase`	Specify a Boolean value to indicate whether when searching for the file specified by the `DirAndSysFileName` parameter, its file name extension is preserved or not; `True`, preserve the case of the file name extension, `False`, convert the file name extension to all lower case letters. The default value is `False`. Warning! If you use the `PreserveCase` parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors.

Field or Control

Definition

URLSource

A reference to a URL. This can be either a URL identifier in the form URL.URL_ID, or a string. This, along with the DirAndSysFileName parameter, indicates the file's location.

Note: When the URLSource parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value.

See Understanding URL Strings Versus URL Objects.

DirAndSysFileName

The relative path and system file name of the file on the file server. This is appended to URLSource to make up the full URL where the file is deleted from. This parameter takes a string value.

Note: Because the DirAndSysFileName parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter.

PreserveCase

Specify a Boolean value to indicate whether when searching for the file specified by the DirAndSysFileName parameter, its file name extension is preserved or not; True, preserve the case of the file name extension, False, convert the file name extension to all lower case letters.

The default value is False.

Warning! If you use the PreserveCase parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors.

Returns

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

Numeric Value	Constant Value	Description
0	%Attachment_Success	File was deleted successfully.
1	%Attachment_Failed	File deletion failed due to an unspecified error. The following are some possible situations where %Attachment_Failed could be returned: Failed to initialize the process due to some internal error. Failed due to unexpected/bad reply from server. Failed to allocate memory due to some internal error. Failed due to timeout. Failed due to non-availability of space on FTP server. Failed to close SSL connection. Failed due to an unspecified error on the HTTP repository. If the HTTP repository resides on a PeopleSoft web server, then you can configure tracing on the web server to report additional error details. See Enabling Tracing on the Web Server or Application Server.
3	%Attachment_FileTransferFailed	File deletion failed due to unspecified error during FTP attempt. The following are some possible situations where %Attachment_FileTransferFailed could be returned: No response from server.
7	%Attachment_DestSystNotFound	Cannot locate destination system for FTP. The following are some possible situations where %Attachment_DestSystNotFound could be returned: Improper URL format. Failed to connect to the server specified.
8	%Attachment_DestSysFailedLogin	Unable to login to destination system for FTP. The following are some possible situations where %Attachment_DestSysFailedLogin could be returned: Unsupported protocol specified. Access denied to server. Failed to connect using SSL Failed to verify the certificates. Failed due to problem in certificates used. Could not authenticate the peer certificate. Failed to login with specified SSL level. Remote server denied logon. Problem reading SSL certificate.
9	%Attachment_FileNotFound	Cannot locate file. This error code applies to the following storage locations: database records only. The following are some possible situations where %Attachment_FileNotFound could be returned: Remote file not found. Failed to read remote file.
10	%Attachment_DeleteFailed	Cannot delete file. This error code applies to the following storage locations: FTP sites and HTTP repositories. The following are some possible situations where %Attachment_DeleteFailed could be returned: Remote file not found. Failed to read remote file.

Example

&retcode = DeleteAttachment(URL.BKFTP, ATTACHSYSFILENAME);

An example of the DeleteAttachment function is provided in the demonstration application delivered in the FILE_ATTACH_WRK derived/work record. This demonstration application is shown on the PeopleTools Test Utilities page.

See Using the PeopleTools Test Utilities Page.

Syntax

DeleteEmailAddress(Type)

Description

Use the DeleteEmailAddress function to delete the email address associated with the specified type for the current user. You can only have one email address of a specific type for a user.

Note: You can only delete the Primary Email Address if it's the only address. If the email address you want to delete is marked as the primary email address, and it is not the only email address, you must mark another email address as primary before you can delete the email address you want to delete. Use the MarkPrimaryEmailAddress function to set the primary email address.

Parameters

Field or Control	Definition
`Type`	Specify the type that you want to change the email address to. This parameter takes a string value. The valid values are:

Value	Description
BB	Blackberry email address
BUS	Business email address
HOME	Home email address
OTH	Other email address
WORK	Work email address

Returns

None.

Syntax

DeleteImage(scrollpath, target_row, [recordname.]fieldname)

where scrollpath is:

[SCROLL.level1_recname, level1_row, [SCROLL.level2_recname, level2_row,]] SCROLL.target_recname

Description

Use the DeleteImage function to remove an image associated with a record field.

Note: To update an image field using this function, be sure that PSIMAGEVER field is also on the same record as the image field being updated.

Parameters

Field or Control	Definition
`scrollpath`	A construction that specifies a scroll area in the component buffer.
`target_row`	The row number of the target row.
[`recordname` .]`fieldname`	The name of the field asThe `recordname` prefix is not required if the program that calls DeleteImage is on the `recordname` record definition.

Returns

Returns a Boolean value: True if image was successfully deleted, False otherwise.

Example

&Rslt = DeleteImage(EMPL_PHOTO.EMPLOYEE_PHOTO);

Syntax

DeleteRecord(level_zero_recfield)

Description

Use the DeleteRecord function to remove a high-level row of data and all dependent rows in other tables from the database.

Note: This function remains for backward compatibility only. Use the Delete record class method instead.

DeleteRecord deletes the component’s level-zero row from the database, deletes any dependent rows in other tables from the database, and exits the component.

This function, like DeleteRow, initially marks the record or row as needing to be deleted. At save time the row is actually deleted from the database and cleared from the buffer.

This function works only if the PeopleCode is on a level-zero field. It cannot be used from SavePostChange or WorkFlow PeopleCode.

Parameters

Field or Control	Definition
`level_zero_recfield`	A `recordname`.`fieldname` reference identifying any field on the level-zero area of the page.

Returns

Optionally returns a Boolean value indicating whether the deletion was completed successfully.

Example

The following example, which is in SavePreChange PeopleCode on a level-zero field, deletes the high-level row and all dependent rows in other tables if the current page is EMPLOYEE_ID_DELETE.

if %Page = PAGE.EMPLOYEE_ID_DELETE then
     &success = DeleteRecord(EMPLID);
end-if;

Syntax

DeleteRow(scrollpath, target_row)

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 DeleteRow function to delete rows programmatically.

Note: This function remains for backward compatibility only. Use the DeleteRow rowset class method instead.

See DeleteRow.

A call to this function causes the RowDelete event sequence to fire, as if an user had manually deleted a row.

DeleteRow cannot be executed from the same scroll level where the deletion will take place, or from a lower scroll level. Place the PeopleCode in a higher scroll level record.

When DeleteRow is used in a loop, you have to process rows from high to low to achieve the correct results, that is, you must delete from the bottom up rather than from the top down. This is necessary because the rows are renumbered after they are deleted (if you delete row one, row two becomes row one).

Parameters

Field or Control	Definition
`scrollpath`	A construction that specifies a scroll level in the component buffer.
`target_row`	The row number of the row to delete.

Returns

Boolean (optional). DeleteRow returns a Boolean value indicating whether the deletion was completed successfully.

Example

In the following example DeleteRow is used in a For loop. The example checks values in each row, then conditionally deletes the row. Note the syntax of the For loop, including the use of the -1 in the Step clause to loop from the highest to lowest values. This ensures that the renumbering of the rows will not affect the loop.

For &L1 = &X1 To 1 Step - 1
    &SECTION = FetchValue(AE_STMT_TBL.AE_SECTION, &L1);
    &STEP = FetchValue(AE_STMT_TBL.AE_STEP, &L1);
    If None(&SECTION, &STEP) Then
       DeleteRow(RECORD.AE_STMT_TBL, &L1);
    End-If;
 End-For;

Syntax

DeleteSQL([SQL.]sqlname[, dbtype[, effdt]])

Description

Use the DeleteSQL function to programmatically delete a SQL definition. The SQL definition must have already been created and saved, either using the CreateSQL and StoreSQL functions, or by using Application Designer.

When you create a SQL definition, you must create a base statement before you can create other types of statements, that is, one that has a dbtype as GENERIC and effdt as the null date (or Date(19000101)). If you specify a base (generic) statement to be deleted, all statements as well as the generic statement are deleted.

If you specify a non-generic statement that ends up matching the generic statement, DeleteSQL does not delete anything, and returns False.

You must commit all database changes prior to using this function. This is to avoid locking critical Tools tables and hence freezing all other users. You receive a runtime error message if you try to use this function when there are pending database updates, and your PeopleCode program terminates. You need to commit any database updates prior to using this function. The CommitWork PeopleCode function has been enhanced to allow this.

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 set by default to the current database type (the value returned from the %DbName system variable.) Valid 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.

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 set by default to the current database type (the value returned from the %DbName system variable.)

Valid 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

A Boolean value: True if the delete was successful, False if the specified SQL statement wasn’t found, and terminates with an error message if there was another problem (that is, date in incorrect format, and so on.)

Example

The following code deletes the ABCD_XY SQL definition for the current DBType and as of date:

&RSLT = DeleteSQL(SQL.ABC_XY);

If NOT(&RSLT) Then 
   /* SQL not found − do error processing */ 
End-if;

The following code deletes the ABCD_XY SQL Definition for the current DBType and November 3, 1998:

&RSLT = DeleteSQL(SQL.ABCD_XY, "",Date(19981103));

Syntax

DeleteSystemPauseTimes(StartDay, StartTime, EndDay, EndTime)

Description

Use the DeleteSystemPauseTimes function to delete pause times that occur on your system by adding a row to the system pause times table.

A pause time is an interval of time during which the node becomes inactive. When the pause time begins, the node is shut down until the pause time is scheduled to end.

Parameters

Field or Control	Definition
`StartDay`	Specify a number from 0-6. The values are:

Value	Description
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

Field or Control	Definition
`StartTime`	Specify a time, in seconds, since midnight.
`EndDay`	Specify a number from 0-6. The values are:

Value	Description
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

Field or Control	Definition
`EndTime`	Specify a time, in seconds, since midnight.

Returns

A Boolean value: True if the system pause time specified was deleted, False otherwise.

Example

Component Boolean &spt_changed; 
 
/* deleting a system pause time interval; */ 
 
If Not DeleteSystemPauseTimes(PSSPTIMES.STARTINGDAY, PSSPTIMES.STARTINGSECOND, PSSPTIMES.ENDINGDAY, PSSPTIMES.ENDINGSECOND) Then 
   Error MsgGetText(117, 15, ""); 
Else 
   &spt_changed = True; 
 
/* to force a save; */ 
 
   PSSPTIMES.MSGSPTNAME = " "; 
 
   DoSave(); 
End-If;

Syntax

DeQueue(physical queue ID, task type, task number, agent ID)

Description

Once a task that has been placed in a queue by the EnQueue function and has been completed by the agent, use the DeQueue function to notify the queue server. The queue server removes the task from the queue and subtracts the cost of that task from the agent's workload.

Note: The queue server does not allow a task to be dequeued if the agent who owns that task is not logged on to that particular queue server. PeopleSoft recommends that you only use the DeQueue function in application pages that the MultiChannel Framework Console launches when agents accept or activate assigned tasks.

Parameters

Field or Control	Definition
`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, using the GetParameter request class method with the value `ps_qid`.
`task type`	Specifies the type of task that an agent completed. It is a string value. The valid values are: email generic Note: This parameter is valid only for persistent tasks (email and generic). It is not valid for chat or voice tasks. You can retrieve the value from the query string in the URL of the application page launched by the MultiChannel Framework console. Use the GetParameter request class method with the value `ps_tasktype`.
`task number`	Uniquely identifies a particular task. This is the task number returned by the Enqueue function when the system first inserted the task into a queue. This is a string value. You can retrieve the value from the query string in the URL of the application page launched by the MultiChannel Framework console. Use the GetParameter request class method with the value `ps_tasknum`.
`agent ID`	Identifies the agent who processed the task. This is a string value. You can retrieve the value from the query string in the URL of the application page launched by the MultiChannel Framework console. Use the GetParameter request class method with the value `ps_agentid`.

Returns

Returns 0 for success. Otherwise, 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

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 = DeQueue(PSMCFFUNCLIB.MCF_QUEUE, PSMCFFUNCLIB.MCF_TASKTYPE, PSMCFFUNCLIB.MCF_TASKNUM, PSMCFFUNCLIB.MCF_AGENTID);

If &nret = 0 Then
      MessageBox(0, "", 0, 0, "Successfully dequeued.");
      End-If

Syntax

DetachAttachment(URLSource, DirAndSysFileName, UserFileName [,PreserveCase])

Description

Use the DetachAttachment function to download a file from its source storage location and save it locally on the end-user machine. The file is sent to the browser with appropriate HTTP headers to cause the browser to display a save dialog box to the user.

The end user can specify any file name to save the file.

Additional information that is important to the use of DetachAttachment can be found in the PeopleTools: PeopleCode Developer's Guide:

PeopleTools supports multiple types of storage locations.
See Understanding File Attachment Storage Locations.
The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.
See Considerations When Attaching Text Files.
Because DetachAttachment is interactive, it is known as a “think-time” function, and is restricted from use in certain PeopleCode events.
See Restrictions on Invoking Functions in Certain PeopleCode Events.
You can restrict the file types that can be uploaded to or downloaded from your PeopleSoft system.

See Restricting the File Types That Can Be Uploaded or Downloaded.

Problems Downloading Files

If you need to use the SetLanguage built-in function to change languages, invoke SetLanguage prior to invoking ViewAttachment or DetachAttachment. You must place the call to SetLanguage in a different PeopleCode program and event from the PeopleCode program and event that invokes ViewAttachment or DetachAttachment.

Parameters

Field or Control	Definition
`URLSource`	A reference to a URL. This can be either a URL identifier the form URL.`URL_ID`, or a string. Note: When the `URLSource` parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value. See Understanding URL Strings Versus URL Objects.
`DirAndSysFileName`	The relative path and file name of the file on the file server. This is appended to `URLSource` to make up the full URL where the file is transferred from. This parameter takes a string value. Note: Because the `DirAndSysFileName` parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter.
`UserFileName`	The default file name provided by the Detach dialog.
`PreserveCase`	Specify a Boolean value to indicate whether when searching for the file specified by the `DirAndSysFileName` parameter, its file name extension is preserved or not; `True`, preserve the case of the file name extension, `False`, convert the file name extension to all lowercase letters. The default value is False. Warning! If you use the `PreserveCase` parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors.

Returns

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

Numeric Value	Constant Value	Description
0	%Attachment_Success	File was transferred successfully. Important! If file type restrictions are changed so that access to a previously uploaded file is now blocked, a call to DetachAttachment will return %Attachment_Success, even though the file and its contents are not downloaded.
1	%Attachment_Failed	File transfer failed due to unspecified error. The following are some possible situations where %Attachment_Failed could be returned: Failed to initialize the process due to some internal error. Failed due to unexpected/bad reply from server. Failed to allocate memory due to some internal error. Failed due to timeout. Failed due to no-availability of space on FTP server. Failed to close SSL connection. Failed due to an unspecified error on the HTTP repository. If the HTTP repository resides on a PeopleSoft web server, then you can configure tracing on the web server to report additional error details. See Enabling Tracing on the Web Server or Application Server.
2	%Attachment_Cancelled	File transfer didn't complete because the operation was canceled by the end user.
3	%Attachment_FileTransferFailed	File transfer failed due to unspecified error during FTP attempt. The following are some possible situations where %Attachment_FileTransferFailed could be returned: Failed due to mismatch in file sizes. Failed to write to local file. Failed to store the file on remote server. Failed to read local file to be uploaded. No response from server. Failed to overwrite the file on remote server.
7	%Attachment_DestSystNotFound	Cannot locate destination system for FTP. The following are some possible situations where %Attachment_DestSystNotFound could be returned: Improper URL format. Failed to connect to the server specified.
8	%Attachment_DestSysFailedLogin	Unable to login to destination system for FTP. The following are some possible situations where %Attachment_DestSysFailedLogin could be returned: Unsupported protocol specified. Access denied to server. Failed to connect using SSL Failed to verify the certificates. Failed due to problem in certificates used. Could not authenticate the peer certificate. Failed to login with specified SSL level. Remote server denied logon. Problem reading SSL certificate.
9	%Attachment_FileNotFound	Cannot locate file. The following are some possible situations where %Attachment_FileNotFound could be returned: Remote file not found. Failed to read remote file.

Example

&retcode = DetachAttachment(URL.MYFTP, ATTACHSYSFILENAME, ATTACHUSERFILE);

An example of the DetachAttachment function is provided in the demonstration application delivered in the FILE_ATTACH_WRK derived/work record. This demonstration application is shown on the PeopleTools Test Utilities page.

See Using the PeopleTools Test Utilities Page.

Syntax

DisableMenuItem(BARNAME.menubar_name, ITEMNAME.menuitem_name)

Description

Use the DisableMenuItem function to disable (make unavailable) 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

DisableMenuItem(BARNAME.MYPOPUP1, ITEMNAME.DO_JOB_TRANSFER);

Syntax

DiscardRow()

Description

Use the DiscardRow function to prevent a row from being added to a page scroll during Row Select processing. This function is valid only in RowSelect PeopleCode. When DiscardRow is called during RowSelect processing, the current row is skipped (not added to the scroll). Processing then continues on the next row, unless the StopFetching function has also been called, in which case no more rows are added to the page.

If you try to discard a row and it's the only row in the scroll, the row is not discarded. You will still have one blank row in your scroll.

DiscardRow has the same functionality as the Warning function in the RowSelect event. The anomalous behavior of Warning is supported for compatibility with previous releases of PeopleTools.

Note: RowSelect processing is used infrequently, because it is more efficient to filter out rows of data using a search view or an effective-dated record before the rows are selected into the component buffer from the database server.

In row select processing, the following actions occur:

The Component Processor checks for more rows to add to the component.
The Component Processor initiates the RowSelect event, which triggers any RowSelect PeopleCode associated with the record field or component record.
This enables PeopleCode to filter rows using the StopFetching and DiscardRow functions. StopFetching causes the system to add the current row to the component, and then to stop adding rows to the component. DiscardRow filters out a current row, and then continues the row select process.
If neither the StopFetching nor DiscardRow function is called, the Component Processor adds the rows to the page and checks for the next row.
The process continues until there are no more rows to add to the component buffers. If both StopFetching and DiscardRow are called, the current row is not added to the page, and no more rows are added to the page.

Parameters

None.

Returns

None.

Syntax

DoCancel( )

Description

Use the DoCancel function to cancel the current page.

In the page, the DoCancel function terminates the current component and returns the user to the search dialog box.
In the menu, the DoCancel function terminates the current component and returns the user to the current menu with no component active.

DoCancel terminates any PeopleCode programs executing prior to a save action. It does not stop processing of PeopleCode in SaveEdit, SavePreChange, and SavePostChange events.

Parameters

None.

Returns

None.

Syntax

DoesTableExist(DB_tbl_name)

Description

Use the DoesTableExist function to return a boolean value indicating whether the database table exists.

Parameters

Field or Control	Definition
`DB_tbl_name`	Specifies the name of the database table as a string value.

Returns

A boolean value.

Example

Local boolean &IsExist = DoesTableExist("PSTIMEZONEMAP");

Syntax

DoModal(Page.page_name, title, xpos, ypos, [level, scroll_path, target_row])

In which 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, in which scrollname is the same as the scroll level’s primary record name.

Description

Use the DoModal function to display a secondary page in a modal, secondary window with a child relationship to the parent window. This means that the user must dismiss the secondary window before continuing work in the page from which the secondary window was called. DoModal can display a single page modally. To display an entire component modally, use DoModalComponent.

Important! The DoModal and DoModalComponent functions support fluid-to-fluid, or classic-to-classic parent/child relationships only. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Alternatively, you can specify a secondary page in a command push button definition without using PeopleCode. This may be preferable for performance reasons.

Any variable declared as a component variable will still be defined after calling the DoModal function. If you call DoModal without specifying a level number or any record parameters, the function uses the current context as the parent. See Using Secondary Pages.

Restrictions on Use in PeopleCode Events

Control does not return to the line after DoModal until after the user has dismissed the secondary page. This interruption of processing makes DoModal a “think-time” function, which means that it shouldn’t be used in any of the following PeopleCode events:

SavePreChange.
SavePostChange.
Workflow.
RowSelect.
Any PeopleCode event that executes as a result of a ScrollSelect, ScrollSelectNew, RowScrollSelect, or RowScrollSelectNew function call.
Any PeopleCode event that executes as a result of a Rowset classs Select method or SelectNew method.
You should not use DoModal or any other think-time function in FieldChange when the field is associated with an edit box, long edit box, or drop-down list box. Use FieldEdit instead.
However, DoModal can be used in FieldChange when the field is associated with a push button, radio button, checkbox, or hyperlink.

In addition, you can't use DoModal in the SearchInit event.

See Think-Time Functions.

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.

Considerations for the DoModal Function and Catching Exceptions

Using the DoModal function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
`page_name`	The name of the secondary page.
`title`	The text that displays in the caption of the secondary page.
`xpos`	The pixel coordinates of the top left corner of the secondary page, offset from the top left corner of the parent page (the default of -1, -1 means centered).
`ypos`	The pixel coordinates of the top right corner of the secondary page, offset from the top right corner of the parent page (the default of -1, -1 means centered).
`level`	Specifies the level of the scroll level on the parent page that contains the row corresponding to level 0 on the secondary page.
`scroll_path`	A construction that specifies a scroll level in the component buffer.
`target_row`	The row number of the row in the parent page corresponding to the level 0 row in the secondary page.

Returns

Returns a number that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModal function in a PeopleCode program. In either case, the return value of DoModal is one of the following:

1 if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
0 if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

DoModal(Page.EDUCATION_DTL, MsgGetText(1000, 167, "Education Details - %1", EDUCATN.DEGREE), - 1, - 1, 1, Record.EDUCATN, CurrentRowNumber());

Syntax

DoModalComponent(MenuName.MENU_NAME, BarName.BAR_NAME, ItemName.MENU_ITEM_NAME, Page.COMPONENT_ITEM_NAME, action, Record.SHARED_RECORD_NAME [, keylist])

In which keylist is a list of field references in the form:

[recordname.]field1 [, [recordname.]field2]. . .

Or in which keylist is a list of field references in the form:

&RecordObject1 [, &RecordObject2]. . .

Description

Use the DoModalComponent function to display a secondary component in a modal, secondary window with a child relationship to the parent window. This means that the user must dismiss the secondary window before continuing work in the page from which the secondary window was called. The secondary component launches modally from within an originating component. After the secondary component is displayed, the user can’t proceed with changes to the originating component until either accepting or canceling the secondary component.

Important! The DoModal and DoModalComponent functions support fluid-to-fluid, or classic-to-classic parent/child relationships only. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Secondary components can be displayed in any of the following action modes: Add, Update/Display, Update/Display All, Correction. A secondary component can be launched from any component, including another secondary component. You can also use DoModalComponent from a secondary page.

The originating component and the secondary component share data, including search keys, using a Shared Work Record or the values in the keylist parameter. If valid search keys are provided in the shared work record and populated with valid values before launching the secondary component, the search is conducted using the provided search key values. If the keylist parameter isn't used and no search keys are provided, or if search key fields contain invalid values, the user accesses the secondary component using a search dialog box.

Note: The user may see a different title for a search page if they enter the search page using this function versus from the regular navigation.

In the COMPONENT_ITEM_NAME parameter, make sure to pass the component item name for the page, not the page name.

Shared Work Records

The originating component and the secondary component share fields in a Derived/Work record called a shared work record. Shared fields from this record must be placed at level zero of both the originating component and the secondary component.

You can use the shared fields to:

Pass values that are assigned to the search keys in the secondary component search record. If these fields are missing or not valid, the search dialog box appears, enabling the user to enter search keys.
Optionally pass other values from the originating component to the secondary component.
Pass values back from the secondary component to the originating component for processing.

To do this, you have to write PeopleCode that:

Assigns values to fields in the shared work record in the originating page at some point before the modal transfer takes place.
Accesses and changes the values, if necessary, in the secondary component.
Accesses the values from the shared work record from the originating component after the secondary component is dismissed.

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.

Restrictions on Use With SearchInit Event

You can't use this function in a SearchInit PeopleCode program.

Considerations for the DoModalComponent Function and Catching Exceptions

Using the DoModalComponent function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
MenuName.`MENU_NAME`	Name of the menu through which the secondary component is accessed.
BarName.`BAR_NAME`	Name of the menu bar through which the secondary component is accessed.
ItemName.`MENU_ITEM_NAME`	Name of the menu item through which the secondary component is accessed.
Page.`COMPONENT_ITEM_NAME`	The component item name of the page to be displayed on top of the secondary component when it displays. The component item name is specified in the component definition.
`action`	String representing the action mode in which to start up the component. You can use either a character value (passed in as a string) or a constant. See below.
	If only one action mode is allowed for the component, that action mode is used. If more than one action mode is allowed, the user can select which mode to come up in.
Record.`SHARED_RECORD_NAME`	The record name of the shared work record. This record must include: Fields that are search keys in the secondary component search record; if search key fields are not provided, or if they are invalid, the user accesses the secondary component using the search dialog box. Other fields to pass to the secondary component. Fields to get back from the secondary component after it has finished processing.
`keylist`	An optional list of field specifications used to select a unique row at level zero in the page you are transferring to, by matching keys in the page you are transferring from. It can also be an already instantiated record object. If a record object is specified, any field of that record object that is also a field of the search record for the destination component is added to `keylist`. The keys in `keylist` must uniquely identify a row in the "to" page search record. If a unique row is not identified, the search dialog box appears. If the `keylist` parameter is not supplied then the destination components' search key must be found as part of the source component's level 0 record buffer.

The values for the action parameter can be as follows:

Numeric Value	Constant Value	Description
A	%Action_Add	Add
U	%Action_UpdateDisplay	Update/Display
L	%Action_UpdateDisplayAll	Update/Display All
C	%Action_Correction	Correction
E	%Action_DataEntry	Data Entry
P	%Action_Prompt	Prompt

Returns

Returns a Boolean that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModalComponent function in a PeopleCode program. In either case, the return value of DoModalComponent is one of the following:

True if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
False if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

The following example shows how to structure a DoModalComponent function call:

DoModalComponent(MenuName.MAINTAIN_ITEMS_FOR_INVENTORY, BarName.USE_A, ItemName.ITEM_DEFINITION, Component.ESTABLISH_AN_ITEM, "C", Record.NEW7_WRK);

Supporting PeopleCode is required if you must assign values to fields in the shared work record or access those values, either from the originating component, or from the secondary component.

Syntax

DoModalComponentPopup(modal_options, Cancel_button_ID, title, MenuName.menuname, BarName.BARNAME, ItemName.MENUITEM_NAME, Page.COMPONENT_ITEM_NAME, action, Record.SHARED_RECORD_NAME [, keylist])

In which keylist is a list of field references in the form:

[RECORD_NAME.]field1 [, [recordname.]field2]. . .

Or in which keylist is a list of field references in the form:

&RecordObject1 [, &RecordObject2]. . .

Description

Use DoModalComponentPopup as the recommended function to display a secondary fluid component in a modal, secondary window with a child relationship to the parent window. This function includes a modal_options parameter, which allows you to specify characteristics of the modal window such as height and width.

Important! Use the DoModalComponentPopup and DoModalPopup functions in fluid applications only. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Using DoModalComponentPopup means that the user must dismiss the secondary window before continuing work in the page from which the secondary window was called. The secondary component launches modally from within an originating component. After the secondary component is displayed, the user can’t proceed with changes to the originating component until either accepting or canceling the secondary component.

Secondary components can be displayed in any of the following action modes: Add, Update/Display, Update/Display All, Correction. A secondary component can be launched from any component, including another secondary component. You can also use DoModalComponentPopup from a secondary page.

The originating component and the secondary component share data, including search keys, using a shared work record or the values in the fieldlist parameter. If valid search keys are provided in the shared work record and populated with valid values before launching the secondary component, the search is conducted using the provided search key values. If the fieldlist parameter isn't used and no search keys are provided, or if search key fields contain invalid values, the user accesses the secondary component using a search dialog box.

Note: The user may see a different title for a search page if they enter the search page using this function versus from the regular navigation.

In the COMPONENT_ITEM_NAME parameter, make sure to pass the component item name for the page, not the page name.

Shared Work Records

The originating component and the secondary component share fields in a derived/work record called a shared work record. Shared fields from this record must be placed at level zero of both the originating component and the secondary component.

You can use the shared fields to:

Pass values that are assigned to the search keys in the secondary component search record. If these fields are missing or not valid, the search dialog box appears, enabling the user to enter search keys.
Optionally pass other values from the originating component to the secondary component.
Pass values back from the secondary component to the originating component for processing.

To do this, you have to write PeopleCode that:

Assigns values to fields in the shared work record in the originating page at some point before the modal transfer takes place.
Accesses and changes the values, if necessary, in the secondary component.
Accesses the values from the shared work record from the originating component after the secondary component is dismissed.

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.

Restrictions on Use With SearchInit Event

You can't use this function in a SearchInit PeopleCode program.

Considerations for the DoModalComponentPopup Function and Catching Exceptions

Using the DoModalComponentPopup function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
`modal_options`	Specifies custom modal options as a String value. See Modal Options for more information.
`Cancel_button_ID`	Specifies the field ID of the cancel button as a string value.
`title`	Specifies a string value to be displayed in the caption of the secondary page.
MenuName.`MENUNAME`	Name of the menu through which the secondary component is accessed.
BarName.`BARNAME`	Name of the menu bar through which the secondary component is accessed.
ItemName.`MENUITEM_NAME`	Name of the menu item through which the secondary component is accessed.
Page.`COMPONENT_ITEM_NAME`	The component item name of the page to be displayed on top of the secondary component when it displays.The component item name is specified in the component definition.
`action`	String representing the action mode in which to start up the component. You can use either a character value (passed in as a string) or a constant. See below.
	If only one action mode is allowed for the component, that action mode is used. If more than one action mode is allowed, the user can select which mode to come up in.
Record.`SHARED_RECORD_NAME`	The record name of the shared work record (preceded by the reserved word Record). This record must include: Fields that are search keys in the secondary component search record; if search key fields are not provided, or if they are invalid, the user accesses the secondary component using the search dialog box. Other fields to pass to the secondary component. Fields to get back from the secondary component after it has finished processing.
`keylist`	An optional list of field specifications used to select a unique row at level zero in the page you are transferring to, by matching keys in the page you are transferring from. It can also be an already instantiated record object. If a record object is specified, any field of that record object that is also a field of the search record for the destination component is added to `keylist`. The keys in `fieldlist` must uniquely identify a row in the "to" page search record. If a unique row is not identified, the search dialog box appears. If the `keylist` parameter is not supplied then the destination components' search key must be found as part of the source component's level 0 record buffer.

The values for the action parameter can be as follows:

Numeric Value	Constant Value	Description
A	%Action_Add	Add
U	%Action_UpdateDisplay	Update/Display
L	%Action_UpdateDisplayAll	Update/Display All
C	%Action_Correction	Correction
E	%Action_DataEntry	Data Entry
P	%Action_Prompt	Prompt

Returns

Returns a Boolean that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModalComponent function in a PeopleCode program. In either case, the return value of DoModalComponentPopup is one of the following:

True if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
False if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

The following example shows how to structure a DoModalComponentPopup function call:

Local string &sPopupOptions = "bFullScreen@1;";
Local string &sCancelButtonId = "";
Local string &sTemp = &srchPivotGrid.Prompt.PageName;
&srchPivotGrid.Prompt.PageName = Page.PTPG_GRIDVIEWERNUI;

Local boolean &ret = DoModalComponentPopup(&sPopupOptions, &sCancelButtonId, &srchPivotGrid.m_model.getModelTitle(), MenuName.PTPG_WIZ_MENU, BarName.PTPG_MENU, ItemName.PTPG_NUI_VWGRID, Page.PTPG_GRIDVIEWERNUI, "U", Record.PTPG_NUI_WRK);
&srchPivotGrid.Prompt.PageName = &sTemp;

Supporting PeopleCode is required if you must assign values to fields in the shared work record or access those values, either from the originating component, or from the secondary component.

Syntax

DoModalPanelGroup(MENUNAME.menuname, BARNAME.barname, ITEMNAME.menuitem_name, PANEL.panel_group_item_name, action, RECORD.shared_record_name)

Description

Use the DoModalPanelGroup function to launch a secondary component.

Note: The DoModalPanelGroup function is supported for compatibility with previous releases of PeopleTools. Future applications should use DoModalComponent instead.

Syntax

DoModalPopup(modal_options, Cancel_button_ID, display_only, cached, Page.PAGE_NAME, title, xpos, ypos[, level, scrollpath, target_row])

In which 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, in which scrollname is the same as the scroll level’s primary record name.

Description

Use DoModalPopup as the recommended function to display a secondary fluid page in a modal, secondary window with a child relationship to the parent window. This function includes a modal_options parameter, which allows you to specify characteristics of the modal window such as height and width.

Important! Use the DoModalComponentPopup and DoModalPopup functions in fluid applications only. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Using DoModalPopup means that the user must dismiss the secondary window before continuing work in the page from which the secondary page was called. In addition, DoModalPopup can display the secondary page in a display-only mode.

Note: Alternatively, you can specify a secondary page in a command push button definition without using PeopleCode. This may be preferable for performance reasons, especially with PeopleSoft Pure Internet Architecture.

DoModalPopup can display a single page modally. To display an entire component modally, use DoModalComponentPopup. Any variable declared as a component variable will still be defined after calling the DoModalPopup function. If you call DoModalPopup without specifying a level number or any record parameters, the function uses the current context as the parent. See Using Secondary Pages.

Restrictions on Use in PeopleCode Events

Control does not return to the line after DoModalPopup until after the user has dismissed the secondary page. This interruption of processing makes DoModalPopup a “think-time” function, which means that it shouldn’t be used in any of the following PeopleCode events:

SavePreChange.
SavePostChange.
Workflow.
RowSelect.
Any PeopleCode event that executes as a result of a ScrollSelect, ScrollSelectNew, RowScrollSelect, or RowScrollSelectNew function call.
Any PeopleCode event that executes as a result of a Rowset classs Select method or SelectNew method.
You should not use DoModalPopup or any other think-time function in FieldChange when the field is associated with an edit box, long edit box, or drop-down list box. Use FieldEdit instead.
However, DoModalPopup can be used in FieldChange when the field is associated with a push button, radio button, checkbox, or hyperlink.

In addition, you can't use DoModalPopup in the SearchInit event.

See Think-Time Functions.

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.

Considerations for the DoModalPopup Function and Catching Exceptions

Using the DoModalPopup function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
`modal_options`	Specifies custom modal options as a String value. See Modal Options for more information.
`Cancel_button_ID`	Specifies the ID of the cancel button as a string value.
`display_only`	Specifies a Boolean value indicating whether the modal secondary page is display-only.
`cached`	Specifies a Boolean value indicating whether to cache the <div> group container for the modal secondary page within the parent page. Note: The value of `display_only` must be True for this parameter to take effect.
Page.`PAGE_NAME`	The name of the secondary page.
`title`	The text that displays in the caption of the secondary page.
`xpos`	The pixel coordinates of the top left corner of the secondary page, offset from the top left corner of the parent page (the default of -1, -1 means centered).
`ypos`	The pixel coordinates of the top right corner of the secondary page, offset from the top right corner of the parent page (the default of -1, -1 means centered).
`level`	Specifies the level of the scroll level on the parent page that contains the row corresponding to level 0 on the secondary page.
`scrollpath`	A construction that specifies a scroll level in the component buffer.
`target_row`	The row number of the row in the parent page corresponding to the level 0 row in the secondary page.

Returns

Returns a number that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModal function in a PeopleCode program. In either case, the return value of DoModal is one of the following:

1 if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
0 if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

Local string &sPopupOptions = "bAutoClose@1;";
&sPopupOptions = &sPopupOptions | "bCenter@1;";
&sPopupOptions = &sPopupOptions | "bHeader@1;";
&sPopupOptions = &sPopupOptions | "bClose@1;";
&sPopupOptions = &sPopupOptions | "width@350;";
&sPopupOptions = &sPopupOptions | "height@400;";

&newHPName = "";
If DoModalPopup(&sPopupOptions, "", False, False, Page.PTNUI_ADDLP_SEC, MsgGetExplainText(95, 10017, "MNF-Add Homepage"), - 1, - 1) = 1 Then
End-If;

Syntax

DoModalX(showInModal, cancelButtonName, Page.pagename, title, xpos, ypos[, level, scrollpath, target_row])

In which 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, in which scrollname is the same as the scroll level’s primary record name.

Description

Use the DoModalX function to display a secondary page modally when you do not want it to display in a modal, secondary window. Instead, the page to be displayed completely replaces the primary window when the showInModal parameter is set to False. Similar to DoModal, the user must complete work on the secondary page before continuing work in the page from which the secondary page was called.

Important! Use the DoModalX and DoModalXComponent functions in classic applications only, either in a standalone classic application or when classic components are included in fluid activity guide and master/detail wrappers. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Important! When the showInModal parameter is set to False, using DoModalX will completely replace the primary window, even if DoModalX is called from a modal window. In addition, this will also close any open modal windows. Therefore, Oracle recommends that DoModalX with the showInModal parameter set to False not be used after calling DoModal or DoModalComponent, or after calling DoModalX or DoModalXComponent when the showInModal parameter is set to True.

DoModalX can display a single page modally. To display an entire component modally, use DoModalXComponent. Any variable declared as a component variable will still be defined after calling the DoModalX function. If you call DoModalX without specifying a level number or any record parameters, the function uses the current context as the parent.

See Using Secondary Pages.

Restrictions on Use in PeopleCode Events

Control does not return to the line after DoModalX until after the user has dismissed the secondary page. This interruption of processing makes DoModalX a “think-time” function, which means that it shouldn’t be used in any of the following PeopleCode events:

SavePreChange.
SavePostChange.
Workflow.
RowSelect.
Any PeopleCode event that executes as a result of a ScrollSelect, ScrollSelectNew, RowScrollSelect, or RowScrollSelectNew function call.
Any PeopleCode event that executes as a result of a Rowset classs Select method or SelectNew method.
You should not use DoModalX or any other think-time function in FieldChange when the field is associated with an edit box, long edit box, or drop-down list box. Use FieldEdit instead.
However, DoModalX can be used in FieldChange when the field is associated with a push button, radio button, checkbox, or hyperlink.

In addition, you can't use DoModalX in the SearchInit event.

See Think-Time Functions.

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.

Considerations for the DoModalX Function and Catching Exceptions

Using the DoModalX function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
`showInModal`	Specify a Boolean value to indicate whether to display the secondary page in a modal, secondary window: `True` display the page in a secondary, modal window similar to the function of DoModal `False` do not display the page in a secondary window; instead, completely replace the primary window.
`cancelButtonName`	Currently, this parameter is not used and should be specified as an empty string: “”.
`pagename`	The name of the secondary page.
`title`	The text that displays in the caption of the secondary page.
`xpos`	The pixel coordinates of the top left corner of the secondary page, offset from the top left corner of the parent page (the default of -1, -1 means centered).
`ypos`	The pixel coordinates of the top right corner of the secondary page, offset from the top right corner of the parent page (the default of -1, -1 means centered).
`level`	Specifies the level of the scroll level on the parent page that contains the row corresponding to level 0 on the secondary page.
`scrollpath`	A construction that specifies a scroll level in the component buffer.
`target_row`	The row number of the row in the parent page corresponding to the level 0 row in the secondary page.

Returns

Returns a number that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModal function in a PeopleCode program. In either case, the return value of DoModalX is one of the following:

1 if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
0 if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

DoModalX( False, "", Page.EDUCATION_DTL, MsgGetText(1000, 167, "Education Details - %1", EDUCATN.DEGREE), - 1, - 1, 1, Record.EDUCATN, CurrentRowNumber());

Syntax

DoModalXComponent(showInModal, cancelButtonName,  MenuName.MENU_NAME,  BarName.BAR_NAME,  ItemName.MENU_ITEM_NAME,  Page.COMPONENT_ITEM_NAME,  action, Record.SHARED_RECORD_NAME [, keylist])

In which keylist is a list of field references in the form:

[recordname.]field1 [, [recordname.]field2].
. .

Or in which keylist is a list of field references in the form:

&RecordObject1 [, &RecordObject2]. . .

Description

Use the DoModalXComponent function to display a secondary component modally when you do not want it to display in a modal, secondary window. Instead, the component to be displayed completely replaces the primary window when the showInModal parameter is set to False. Similar to DoModalComponent, the user must complete work on the secondary component before continuing work in the page from which the secondary component was called.

Important! Use the DoModalX and DoModalXComponent functions in classic applications only, either in a standalone classic application or when classic components are included in fluid activity guide and master/detail wrappers. See Transfer and Modal Functions for more information on which functions are available for which purposes.

Important! When the showInModal parameter is set to False, using DoModalXComponent will completely replace the primary window, even if DoModalXComponent is called from a modal window. In addition, this will also close any open modal windows. Therefore, Oracle recommends that DoModalXComponent with the showInModal parameter set to False not be used after calling DoModal or DoModalComponent, or after calling DoModalX or DoModalXComponent when the showInModal parameter is set to True.

Secondary components can be displayed in any of the following action modes: Add, Update/Display, Update/Display All, Correction. A secondary component can be launched from any component, including another secondary component. You can also use DoModalXComponent from a secondary page.

The originating component and the secondary component share data, including search keys, using a Shared Work Record or the values in the fieldlist parameter. If valid search keys are provided in the shared work record and populated with valid values before launching the secondary component, the search is conducted using the provided search key values. If the fieldlist parameter isn't used and no search keys are provided, or if search key fields contain invalid values, the user accesses the secondary component using a search dialog box.

Note: The user may see a different title for a search page if they enter the search page using this function versus from the regular navigation.

In the component_item_name parameter, make sure to pass the component item name for the page, not the page name.

Shared Work Records

The originating component and the secondary component share fields in a Derived/Work record called a shared work record. Shared fields from this record must be placed at level zero of both the originating component and the secondary component.

You can use the shared fields to:

Pass values that are assigned to the search keys in the secondary component search record. If these fields are missing or not valid, the search dialog box appears, enabling the user to enter search keys.
Optionally pass other values from the originating component to the secondary component.
Pass values back from the secondary component to the originating component for processing.

To do this, you have to write PeopleCode that:

Assigns values to fields in the shared work record in the originating page at some point before the modal transfer takes place.
Accesses and changes the values, if necessary, in the secondary component.
Accesses the values from the shared work record from the originating component after the secondary component is dismissed.

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.

Restrictions on Use With SearchInit Event

You can't use this function in a SearchInit PeopleCode program.

Considerations for the DoModalXComponent Function and Catching Exceptions

Using the DoModalXComponent function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component:

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Parameters

Field or Control	Definition
`showInModal`	Specify a Boolean value to indicate whether to display the secondary component in a modal, secondary window: `True` display the page in a secondary, modal window similar to the function of DoModal `False` do not display the page in a secondary window; instead, completely replace the primary window.
`cancelButtonName`	Currently, this parameter is not used and should be specified as an empty string: “”.
`MENU_NAME`	Name of the menu through which the secondary component is accessed.
`BAR_NAME`	Name of the menu bar through which the secondary component is accessed.
`MENU_ITEM_NAME`	Name of the menu item through which the secondary component is accessed.
`COMPONENT_ITEM_NAME`	The component item name of the page to be displayed on top of the secondary component when it displays. The component item name is specified in the component definition.
`action`	String representing the action mode in which to start up the component. You can use either a character value (passed in as a string) or a constant. See below.
	If only one action mode is allowed for the component, that action mode is used. If more than one action mode is allowed, the user can select which mode to come up in.
`SHARED_RECORD_NAME`	The record name of the shared work record (preceded by the reserved word Record). This record must include: Fields that are search keys in the secondary component search record; if search key fields are not provided, or if they are invalid, the user accesses the secondary component using the search dialog box. Other fields to pass to the secondary component. Fields to get back from the secondary component after it has finished processing.
`keylist`	An optional list of field specifications used to select a unique row at level zero in the page you are transferring to, by matching keys in the page you are transferring from. It can also be an already instantiated record object. If a record object is specified, any field of that record object that is also a field of the search record for the destination component is added to `keylist`. The keys in `fieldlist` must uniquely identify a row in the "to" page search record. If a unique row is not identified, the search dialog box appears. If the `keylist` parameter is not supplied then the destination components' search key must be found as part of the source component's level 0 record buffer.

The values for action can be as follows:

Numeric Value	Constant Value	Description
A	%Action_Add	Add
U	%Action_UpdateDisplay	Update/Display
L	%Action_UpdateDisplayAll	Update/Display All
C	%Action_Correction	Correction
E	%Action_DataEntry	Data Entry
P	%Action_Prompt	Prompt

Returns

Returns a Boolean that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModalComponent function in a PeopleCode program. In either case, the return value of DoModalXComponent is one of the following:

True if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.
False if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.

Example

The following example shows how to structure a DoModalXComponent function call:

DoModalXComponent( False, "", MenuName.MAINTAIN_ITEMS_FOR_INVENTORY, BarName.USE_A, ItemName.ITEM_DEFINITION, Component.ESTABLISH_AN_ITEM, "C", Record.NEW7_WRK);

Supporting PeopleCode is required if you must assign values to fields in the shared work record or access those values, either from the originating component, or from the secondary component.

Syntax

DoSave()

Description

Use the DoSave function to save the current page. DoSave defers processing to the end of the current PeopleCode program event, as distinct from DoSaveNow, which causes save processing (including SaveEdit, SavePreChange, SavePostChange, and Workflow PeopleCode) to be executed immediately.

DoSave can be used in the following PeopleCode events only: FieldEdit, FieldChange, or ItemSelected (for menu items in popup menus only).

Parameters

None.

Returns

None.

Example

The following example sets up a key list with AddKeyListItem, saves the current page, and then transfers the user to a page named PAGE_2.

ClearKeyListItem( );
AddKeyListItem(OPRID, OPRID);
AddKeyListItem(REQUEST_ID, REQUEST_ID);
SetNextPage("PAGE_2");
DoSave( );
TransferPage( );

Syntax

DoSaveNow()

Description

The DoSaveNow function is designed primarily for use with remote calls. It enables a PeopleCode program to save page data to the database before running a remote process (most frequently a COBOL process) that will access the database directly. It is generally necessary to call DoSaveNow before calling the RemoteCall function.

DoSaveNow causes the current page to be saved immediately. Save processing (including SaveEdit, SavePreChange, SavePostChange, and Workflow PeopleCode) is executed before continuing execution of the program where DoSaveNow is called. DoSaveNow differs from the DoSave function in that DoSave defers saving the component until after any running PeopleCode is completed.

DoSaveNow can only be called from a FieldEdit or FieldChange event.

If you call DoSaveNow and there are no changes to save, save processing is skipped entirely. You can call SetComponentChanged right before you call DoSaveNow. The SetComponentChanged function makes the Component Processor think there are changes and so will force full save processing.

See RemoteCall, DoSave.

Errors in DoSaveNow Save Processing

DoSaveNow initiates save processing. It handles errors that occur during save processing as follows:

If save processing encounters a SaveEdit error, it displays the appropriate message box. DoSaveNow immediately exits from the originating FieldChange or FieldEdit program. The user can correct the error and continue.
If save processing encounters a fatal error, it displays the appropriate fatal error. DoSaveNow handles the error by immediately exiting from the originating FieldChange or FieldEdit program. The user must then cancel the page.
If save processing completes with no errors, PeopleCode execution continues on the line after the DoSaveNow call in FieldChange or FieldEdit.

Restrictions on Use of DoSaveNow

The following restrictions apply:

DoSaveNow can be executed only from a FieldEdit or FieldChange event.
DoSaveNow is only allowed prior to the first CallAppEngine function in a FieldChange event, but not afterward.
Deferred operations should not be called before the DoSaveNow. Deferred operations include the DoSave, TransferPage, SetCursorPos, and EndModal functions.
Components that use DoSaveNow must not use the DoCancel, Transfer, TransferPage, or WinEscape functions in PeopleCode attached to save action events (SaveEdit, SavePreChange, and SavePostChange), because these functions terminate the component, which would cause the program from which DoSaveNow was called to terminate prematurely.

Note: You should be aware that DoSaveNow may result in unpredictable behavior if PeopleCode in save events deletes rows or inserts rows into scrolls. PeopleCode that runs after DoSaveNow must be designed around the possibility that rows were deleted or inserted (which causes row number assignments to change). Modifying data on a deleted row may cause it to become “undeleted.”

Parameters

None.

Returns

None.

Example

The following example calls DoSaveNow to save the component prior to running a remote process in the remote_depletion declared function:

Declare Function remote_depletion PeopleCode FUNCLIB_ININTFC.RUN_DEPLETION FieldFormula;

/*
Express Issue Page - run Depletion job through RemoteCall()
*/
If %Component = COMPONENT.EXPRESS_ISSUE_INV Then
   DoSaveNow();
   &BUSINESS_UNIT = FetchValue(SHIP_HDR_INV.BUSINESS_UNIT, 1);
   &SHIP_OPTION = "S";
   &SHIP_ID = FetchValue(SHIP_HDR_INV.SHIP_ID, 1);
   remote_depletion(&BUSINESS_UNIT, &SHIP_OPTION, &SHIP_ID, &PROGRAM_STATUS);
End-If

Syntax

DownloadToExcel(&Rowset, File_Name, Output_Format, [Header_Required])

Description

Use the DownloadToExcel function to generate a spreadsheet file with data as specified by the rowset object, and download it locally to the end-user’s machine. You can specify the following file formats for the spreadsheet file - XLSX, HTML, or CSV.

Parameters

Field or Control	Definition
`Rowset`	Specify an already instantiated and populated rowset object containing the result.
`File_Name`	Specify a name for the spreadsheet file, which is generated and downloaded to the user’s machine.
`Output_Format`	Specify the format of the output. You can specify either a numeric value or a constant value.
`Header_Required`	Specify whether the spreadsheet header should be displayed or not. This parameter takes a Boolean value. This parameter is optional.

The values for Output_Format values can be as follows:

Numeric Value	Constant Value	File Format
1	%ExcelFormat_Xlsx	XLSX
2	%ExcelFormat_Html	HTML
3	%ExcelFormat_Csv	CSV

Returns

Returns 0 if the function is successful; returns 1 if the function is unsuccessful.

Example

Local Rowset &rs;
&rs = CreateRowset(Record.QE_ABSENCE_HIST);
/*Populate Rowset*/
&NUM_READ = &rs.Fill();
&File_Name = "output-" | %Datetime | ".csv";
/*Download the result into spreadsheet file and push it to the web browser*/
&result = DownloadToExcel(&rs, &File_Name, %ExcelFormat_Csv);