# PeopleCode Built-in Functions and Language Constructs

The PeopleCode built-In functions are listed in alphabetical order within this topic.

## Typographical Conventions

The following topic describes typographical conventions that apply to PeopleCode and are used throughout PeopleSoft documentation: Typographical Conventions

## Abs

`Abs(x)`

### Description

Use the Abs function to return a decimal value equal to the absolute value of a number x.

### Example

The example returns the absolute value of the difference between &NUM_1 and &NUM_2:

`&RESULT = Abs(&NUM_1 - &NUM_2);`

## AccruableDays

### Syntax

`AccruableDays(StartDate, EndDate, Accrual_Conv)`

### Description

Use the AccruableDays function to return the number of days during which interest can accrue in a given range of time according to the Accrual_Conv parameter.

### Parameters

Numeric Value

Constant Value

Description

0

%Accrual_30DPM

30/360: all months 30 days long according to NASD rules for date truncation

1

%Accrual_30DPME

30E/360: all months 30 days long according to European rules for date truncation

2

N/A

30N/360: all months but February are 30 days long according to SIA rules

3

%Accrual_Fixed360

Act/360: months have variable number of days, but years have fixed 360 days

4

%Accrual_Fixed365

Act/365: months have variable number of days, buy years have fixed 365 days

5

%Accrual_ActualDPY

Act/Act: months and years have a variable number of days

### Returns

An integer representing a number of days.

## AccrualFactor

### Syntax

`AccrualFactor(StartDate, EndDate, Accrual_Conv)`

### Description

Use the AccrualFactor function to compute a factor that's equal to the number of years of interest accrued during a date range, according to Accrual_Conv parameter.

### Parameters

Numeric Value

Constant Value

Description

0

%Accrual_30DPM

30/360: all months 30 days long according to NASD rules for date truncation

1

%Accrual_30DPME

30E/360: all months 30 days long according to European rules for date truncation

2

N/A

30N/360: all months but February are 30 days long according to SIA rules

3

%Accrual_Fixed360

Act/360: months have variable number of days, but years have fixed 360 days

4

%Accrual_Fixed365

Act/365: months have variable number of days, buy years have fixed 365 days

5

%Accrual_ActualDPY

Act/Act: months and years have a variable number of days

### Returns

A floating point number representing a number of years.

## Acos

### Syntax

`Acos(value)`

### Description

Use the Acos function to calculate the arccosine of the given value, that is, the size of the angle whose cosine is that value.

### Returns

A value in radians between 0 and pi.

### Example

The following example returns the size in radians of the angle whose cosine is 0.5:

`&MY_ANGLE = Acos(0.5);`

## ActiveRowCount

### Syntax

`ActiveRowCount(Scrollpath)`

Where scrollpath is:

`[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]] RECORD.target_recname`

To prevent ambiguous references, you can use SCROLL. scrollname, where scrollname is the same as the scroll level’s primary record name.

### Description

Use the ActiveRowCount function to return the number of active (non-deleted) rows for a specified scroll area in the active page.

Note: This function remains for backward compatibility only. Use the ActiveRowCount Rowset class property instead.

ActiveRowCount is often used to get a limiting value for a For statement. This enables you to loop through the active rows of a scroll area, performing an operation on each active row. Rows that have been marked as deleted are not affected in a For loop delimited by ActiveRowCount. If you want to loop through all the rows of a scroll area, including deleted rows, use TotalRowCount.

Use ActiveRowCount with CurrentRowNumber to determine whether the user is on the last row of a record.

### Returns

Returns a Number value equal to the total active (non-deleted) rows in the specified scroll area in the active page.

### Example

In this example ActiveRowCount is used to delimit a For loop through a level-one scroll:

```&CURRENT_L1 = CurrentRowNumber(1);
&ACTIVE_L2 = ActiveRowCount(RECORD.ASSIGNMENT, &CURRENT_L1, RECORD.ASGN_HOME_HOST);
&HOME_HOST = FetchValue(RECORD.ASSIGNMENT, &CURRENT_L1,
ASGN_HOME_HOST.HOME_HOST, 1);
If All(&HOME_HOST) Then
For &I = 1 To &ACTIVE_L2
DeleteRow(RECORD.ASSIGNMENT, &CURRENT_L1, RECORD.ASGN_HOME_HOST, 1);
End-For;
End-If;```

### Syntax

`AddAttachment(URLDestination, DirAndFilePrefix, FileType, UserFileName[, MaxSize [, PreserveCase[, UploadPageTitle[, AllowLargeChunks]]]])`

### Description

Use the AddAttachment function to upload one file from an end-user machine to a specified storage location. To upload more than one file with a single function call, use the MAddAttachment function.

Important! It is the responsibility of the calling PeopleCode program to store the returned file name for further use.

If a file exists at a particular place on a storage location and then another file with the same name is uploaded to that same place on that same storage location, the original file will be silently overwritten by the new file. If that is not the behavior you desire, it is recommended that you implement PeopleCode to guarantee the ultimate uniqueness of either the name of the file at its place on the storage location or the name of its place (the subdirectory) on the storage location.

You cannot use a relative path to specify the file that is to be uploaded; you must use a full path. If end users experience problems in uploading files, ensure that they browse to the file they wish to upload rather than attempting to manually enter the full path name of the file. This problem can manifest itself differently depending on the browser used. For example, with some browser versions, the PeopleSoft page appears to be in an infinite “Processing” state. Information is available on working with different browsers.

See My Oracle Support, “Troubleshooting Browser Limitations”

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

• PeopleTools supports multiple types of storage locations.

• Certain characters are illegal in file names; other characters in file names are converted during file transfer.

• Non-ASCII file names are supported by the PeopleCode file attachment functions.

• The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.

• Because AddAttachment is interactive, it is known as a “think-time” function, and is restricted from use in certain PeopleCode events.

• Virus scanning can be performed on all files uploaded with the AddAttachment function.

### Returns

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

Numeric Value

Constant Value

Description

0

%Attachment_Success

File was transferred successfully.

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

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.

• No response from server.

• Failed to overwrite the file on remote server.

6

%Attachment_FileExceedsMaxSize

File exceeds maximum size, if specified.

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

Unable to login to destination system for FTP.

The following are some possible situations where %Attachment_DestSysFailedLogin could be returned:

• Unsupported protocol specified.

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

9

%Attachment_FileNotFound

Cannot locate file.

The following are some possible situations where %Attachment_FileNotFound could be returned:

• Failed to read remote file.

11

%Attachment_NoFileName

File transfer failed because no file name was specified.

12

%Attachment_FileNameTooLong

File transfer failed because name of selected file name is too long. Maximum is 64 characters.

13

%Attachment_ViolationFound

File violation detected by virus scan engine.

14

%Attachment_VirusScanError

Virus scan engine error.

15

%Attachment_VirusConfigError

Virus scan engine configuration error.

16

%Attachment_VirusConnectError

Virus scan engine connection error.

21

%Attachment_Rejected

File transfer failed because the file extension is not allowed.

### Example

`&retcode = AddAttachment(URL.MYFTP, ATTACHSYSFILENAME, "", ATTACHUSERFILE, 0); `

An example of the AddAttachment 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.

### Syntax

`AddEmailAddress(Type, Address [, Primary])`

Value

Description

BB

BUS

HOME

OTH

WORK

None.

### Syntax

`AddKeyListItem(field, value)`

### Description

Use the AddKeyListItem to add a new key field and its value to the current list of keys. It enables PeopleCode to help users navigate through related pages without being prompted for key values. A common use of AddKeyListItem is to add a field to a key list and then transfer to a page which uses that field as a key.

### Returns

Returns a Boolean value indicating whether it completed successfully.

### Example

The following example creates a key list using AddKeyListItem and transfers the user to a page named VOUCHER_INQUIRY_FS.

```AddKeyListItem(VNDR_INQ_VW_FS.BUSINESS_UNIT, ASSET_ACQ_DET.BUSINESS_UNIT_AP);
TransferPage("VOUCHER_INQUIRY_FS");```

### Syntax

`AddSystemPauseTimes(StartDay, StartTime, EndDay, EndTime)`

### Description

Use the AddSystemPauseTimes function to set when pause times occur on your system by adding a row to the system pause-times tables.

This function is used in the PeopleCode for the Message Monitor. Pause times are set up in the Message Monitor.

Value

Description

0

Sunday

1

Monday

2

Tuesday

3

Wednesday

4

Thursday

5

Friday

6

Saturday

Value

Description

0

Sunday

1

Monday

2

Tuesday

3

Wednesday

4

Thursday

5

Friday

6

Saturday

### Returns

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

### Example

```Declare Function SetTime PeopleCode REFRESH_BTN FieldFormula;

Component Boolean &spt_changed;

Function GetSecond(&time) Returns number ;
Return Hour(&time) * 3600 + Minute(&time) * 60 + Second(&time);
End-Function;

/* initialize; */

STARTDAY = "0";
AMM_STARTTIME = SetTime(0);
ENDDAY = "0";
AMM_ENDTIME = SetTime(0);

If DoModal(Panel.AMM_ADD_SPTIMES, MsgGetText(117, 13, ""), - 1, - 1) = 1 Then
If AddSystemPauseTimes(Value(STARTDAY), GetSecond(AMM_STARTTIME), Value(ENDDAY), GetSecond(AMM_ENDTIME)) Then
&spt_changed = True;
DoSave();
Else
MessageBox(16, MsgGetText(117, 13, ""), 117, 14, "");
End-If;
End-If;```

### Syntax

`AddToDate(date, num_years, num_months, num_days)`

### Description

Use the AddToDate function to add the specified number of years, months, and days to the date provided.

Suppose, for example, that you want to find a date six years from now. You could not just multiply 6 times 365 and add the result to today’s date, because of leap years. And, depending on the current year, there may be one or two leap years in the next six years. AddToDate takes care of this for you.

You can subtract from dates by passing the function negative numbers.

When you are adding one month to the date provided, and the date provided is the last day of a month, and the next month is shorter, the returned result is the last day of the next month.

For example, in the following, &NewDate is 29/02/2004:

`&NewDate = AddToDate("31/01/2004", 0, 1, 0);`

When you are adding one month to the date provided, and the date provided is the last day of a month, and the next month is longer, the returned result is not the last day of the next month.

For example, in the following, &NewDate is 29/03/2004.

`&NewDate = AddToDate("29/02/2004", 0, 1, 0)`

### Returns

Returns a Date value equal to the original date plus the number of years, months, and days passed to the function.

### Example

The following example finds the date one year, three months, and 16 days after a field called BEGIN_DT:

`AddToDate(BEGIN_DT, 1, 3, 16);`

This example finds the date two months ago prior to BEGIN_DT:

`AddToDate(BEGIN_DT, 0, -2, 0);`

### Syntax

`AddToDateTime(datetime, years,  months, days, hours, minutes, seconds)`

### Description

Use the AddToDateTime function to add the specified number of years, months, days, hours, seconds, and minutes to the datetime provided. You can subtract from datetimes by passing the function negative numbers.

### Returns

A Datetime value equal to the original date plus the number of years, months, days, hours, minutes, and seconds passed to the function.

### Example

The following example postpones an interview scheduled in the INTRTime field by two days and two hours:

`INTRTIME = AddToDateTime(INTRTIME, 0, 0, 2, 2, 0, 0);`

### Syntax

`AddToTime(time, hours, minutes, seconds)`

### Description

Use the AddToTime function to add hours, minutes, and seconds to time. This function returns the result as a Time value. To subtract from time, use negative numbers for hours, minutes, and seconds. The resulting value is always adjusted such that it represents an hour less than 24 (a valid time of day.)

### Returns

A Time value equal to time increased by the number of hours, minutes, and seconds passed to the function.

### Example

Assume that a time, &BREAKTime, is 0:15:00. The following moves the time &BREAKTime back by one hour, resulting in 23:15:00:

`&BREAKTime = AddToTime(&BREAKTime, -1, 0, 0);`

## All

### Syntax

`All(fieldlist)`

Where fieldlist is an arbitrary-length list of field names in the form:

`[recordname.]fieldname1 [, [recordname.]fieldname2] ...`

### Description

Use the All function to verify if a field contains a value, or if all the fields in a list of fields contain values. If any of the fields are Null, then All returns False.

A blank character field, or a zero (0) numeric value in a required numeric field is considered a null value.

### Returns

Returns a Boolean value based on the values in fieldlist. The All function returns True if all of the specified fields have a value; it returns False if any one of the fields does not contain a value.

### Example

The All function is commonly used in SaveEdit PeopleCode to ensure that a group of related fields are all entered. For example:

```If All(RETURN_DT, BEGIN_DT) and
8 * (RETURN_DT - BEGIN_DT) (DURATION_DAYS * 8 + DURATION_HOURS)
Then
Warning MsgGet(1000, 1, "Duration of absence exceeds standard hours for number of days absent.");
End-if;```

## AllOrNone

### Syntax

`AllOrNone(fieldlist)`

Where fieldlist is an arbitrary-length list of field references in the form:

`[recordname.]fieldname1 [, [recordname.]fieldname2] ...`

### Description

The AllOrNone function takes a list of fields and returns True if either of these conditions is true:

• All of the fields have values (that is, are not Null).

• None of the fields has a value.

For example, if field1 = 5, field2 = "Mary", and field3 = null, AllOrNone returns False.

This function is useful, for example, where you have a set of page fields, and if any one of the fields contains a value, then all of the other fields are required also.

A blank character field, or a zero (0) numeric value in a required numeric field is considered a null value.

### Returns

Returns a Boolean value: True if all of the fields in fieldlist or none of the fields in fieldlist has a value, False otherwise.

### Example

You could use AllOrNone as follows:

```If Not AllOrNone(STREET1, CITY, STATE) Then
WinMessage("Address should consist of at least Street (Line 1), City, State, and Country.");
End-if;```

## AllowEmplIdChg

### Syntax

`AllowEmplIdChg(is_allowed)`

### Description

By default, the Component Processor does not allow an user to make any changes to a record if a record contains an EMPLID key field, EMPLID is a required field, and its value matches the value of the user’s EMPLID. In some situations, though, such changes are warranted. For example, you would want employees to be able to change information about themselves when entering time sheet data.

The AllowEmplIdChg function enables the user to change records whose key matches the user’s own EMPLID, or prevents the user from changing these records. The function takes a single Boolean parameter that when set to True allows the employee to update their own data. When the parameter is set to False, the employee is prevented from updating this data.

After permission is granted, it stays through the life of the component, not the page. After a user switches to another component, the default value (not being able to make changes) is reapplied.

### Returns

Optionally returns a Boolean value: True if the function executed successfully, False otherwise.

### Example

```If Substring (%Page, 1, 9) = Substring(PAGE.TimeSHEET_PNL_A, 1, 9) Then
AllowEmplIdChg(true);
End-if;```

## Amortize

### Syntax

`Amortize(intr, pb, pmt, pmtnbr, payintr, payprin, balance)`

### Description

Use the Amortize function to compute the amount of a loan payment applied towards interest (payintr), the amount of the payment applied towards principal (payprin), and the remaining balance balance, based on the principal balance (pb) at the beginning of the loan term, the amount of one payment pmt, the interest rate charged during one payment period (intr), and the payment number pmtnbr.

### Parameters

Note that payintr, payprin, and balance are “outvars”: you must pass variables in these parameters, which the Amortize function then fills with values. The remaining parameters are “invars” containing data the function needs to perform its calculation.

None.

### Example

Suppose you want to calculate the principal, interest, and remaining balance after the 24th payment on a loan of \$15,000, at an interest rate of 1% per loan payment period, and a payment amount of \$290.

```&INTRST_RT=1;
&LOAN_AMT=15000;
&PYMNT_AMNT=290;
&PYMNT_NBR=24;
Amortize(&INTRST_RT, &LOAN_AMT, &PYMNT_AMNT, &PYMNT_NBR, &PYMNT_INTRST, &PYMNT_PRIN, &BAL);
&RESULT = "Int=" | String(&PYMNT_INTRST) | " Prin=" | String(&PYMNT_PRIN) | "    Bal=" | String(&BAL);```

This example sets &RESULT equal to "Int=114 Prin=176 Bal=11223.72".

## Asin

### Syntax

`Asin(value)`

### Description

Use the Asin function to calculate the arcsine of the given value, that is, the size of the angle whose sine is that value.

### Returns

A value in radians between -pi/2 and pi/2.

### Example

The following example returns the size in radians of the angle whose sine is 0.5:

`&MY_ANGLE = Asin(0.5);`

## Atan

### Syntax

`Atan(value)`

### Description

Use the Atan function to calculate the arctangent of the given value, that is, the size of the angle whose tangent is that value.

### Returns

A value in radians between -pi/2 and pi/2.

### Example

The following example returns the size in radians of the angle whose tangent is 0.5:

`&MY_ANGLE = Atan(0.5);`

## BlackScholesCall

### Syntax

`BlackScholesCall(Asset_Price, Strike_Price, Interest_Rate, Years, Volatility)`

### Description

Use the BlackScholesCall function to return the value of a call against an equity underlying according to the Black-Scholes equations.

### Returns

A number representing the value of a call against an equity.

## BlackScholesPut

### Syntax

`BlackScholesPut(Asset_Price, Strike_Price, Interest_Rate, Years, Volatility)`

### Description

Use the BlackScholesPut function to return the value of a put against an equity underlying according to the Black-Scholes equations.

### Returns

A number representing the value of a call against an equity.

## BootstrapYTMs

### Syntax

`BootstrapYTMs(Date, MktInst, Accrual_Conv)`

### Description

Use the BootstrapYTMs function to create a zero-arbitrage implied zero-coupon curve from a yield-to-maturity curve using the integrated discount factor method, based on the Accrual_­Conv.

### Parameters

Elements

Description

1

tenor in days

2

yield in percent

3

price per 100 par

4

coupon rate (zero for spot instruments)

5

frequency of coupon payments

6

unit of measure for coupon frequency, 0 for days, 1 for months, and 2 for years

7

coefficient a of a curve interpolating the dataset

8,9,10

coefficients b, c, and d of a curve interpolating the dataset

### Returns

An array of array of number. The elements in the array have the same type as the elements in the array for the MktInst parameter.

## Break

`Break`

### Description

Use the Break statement to terminate execution of a loop or an Evaluate function. The program resumes execution immediately after the end of the statement. If the loop or Evaluate is nested in another statement, only the innermost statement is terminated.

None.

### Example

In the following example, Break is used to terminate the Evaluate statement, while staying within the outermost If statement:

```If CURRENCY_CD = PriorEffdt(CURRENCY_CD) Then
Evaluate ACTION
When = "PAY"
If ANNUAL_RT = PriorEffdt(ANNUAL_RT) Then
Warning MsgGet(1000, 27, "Pay Rate Change action is chosen and Pay Rate has not been changed.");
End-if;
Break;
When = "DEM"
If ANNUAL_RT >= PriorEffdt(ANNUAL_RT) Then
Warning MsgGet(1000, 29, "Demotion Action is chosen and Pay Rate has not been decreased.");
End-if;
Break;
When-other
End-evaluate;
WinMessage("This message appears after executing either of the BREAK statements or after all WHEN statements are false");
End-if;```

## BulkDeleteField

### Syntax

`BulkDeleteField(ProjectName, Field.FieldName [, ExclProj])`

### Description

Use the BulkDeleteField function to delete fields from records and pages, as well as the associated PeopleCode programs and modify the SQL either on the record, or, if the record is a subrecord, on the parent records.

Note: You must have the role Peoplesoft Administrator assigned to your UserId in order to use this function.

If you specify a project that contains objects such as fields which have an upgrade action of delete, those objects are ignored.

The field is removed from the page regardless of where the field exists on the page, whether on a grid or not.

If the field is in the SELECT clause of the SQL, the removal is straightforward. However, if the field is also used in a WHERE clause, or if the field is the only item in the SELECT clause, the record isn't modified and is instead inserted into a project called BLK_FieldName. The record should be examined and any additional changes made as necessary.

Deleting fields from records and pages does not remove the field definition itself and it does not remove the field from other areas, such as Projects, Crystal Reports, or message definitions.

In addition, this function does not delete the references to the field in the PeopleCode. You must manually remove the references to the deleted field. Use the Find In. . . tool to search for the field name you deleted.

Note: Because performing this operation changes records, you must subsequently rebuild the project (alter tables).

#### Using the Log File

Information about this operation is stored in a log field. The directory where the log file is placed depends on where the function is run from:

• If the function is run in two-tier, the log file is located at PS_CFG_HOME /BulkOps.txt. This is also the default location if the system cannot find the other paths.

• If the function is run from an application server, the log file is located at:

PS_CFG_HOME /APPSERV/Domain_Name/LOGS/BulkOps.txt

• If the function is run from an Application Engine program, the log file is written to the process' output log directory, that is:

PS_CFG_HOME /APPSERV/prcs/Domain_Name/log_output/Process_Name_Instance/BulkOps.txt

#### Considerations Using this Function

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on a currently loaded component. In general, changes aren't recognized until the component is reloaded.

Bulk operations are time consuming, therefore, referencing the log file to see the progress of an operation is recommended. These operations accommodate errors and continue processing, logging the overall progress of the operation.

Warning! These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.

#### Considerations Using the Exclusion Project

If you specify ExclProj, the following items that are both in ProjectName and ExclProj are not changed, that is, the field specified is not removed from these items:

• pages

• records

• associated SQL with records of type View

• any PeopleCode associated with those items.

Individual SQL or PeopleCode items are not ignored by themselves, only as associated with records or pages.

### Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

### Example

```&pjm = "MYPROJ";
&ret =  BulkDeleteField(&pjm, Field.OrgId, "EXCLPROJ");

If (&ret = %MDA_Success) Then
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkDeleteField succeeded");
Else
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkDeleteField failed");
End-If;```

## BulkInsertField

### Syntax

`BulkInsertField(ProjectName, Field.FieldName, ModelName, ClonePCode [, ExclProj])`

### Description

Use the BulkInsertField function to insert a source field into records and pages in a project if and only if the model field specified by ModelName exists on those records and pages.

If you specify a project that contains objects such as fields which have an upgrade action of delete, those objects are ignored.

Note: You must have the role Peoplesoft Administrator assigned to your UserId in order to use this function.

#### Using the Log File

Information about this operation is stored in a log field. The directory where the log file is placed depends on where the function is run from:

• If the function is run in two-tier, the log file is located at PS_HOME/BulkOps.txt. This is also the default location if the system cannot find the other paths.

• If the function is run from an application server, the log file is located here:

PS_CFG_HOME /APPSERV/Domain_Name/LOGS/BulkOps.txt

• If the function is run from an Application Engine program, the log file is written to the process' output log directory, that is:

PS_CFG_HOME /APPSERV/prcs/Domain_Name/log_output/Process_Name_Instance/BulkOps.txt

#### Considerations Inserting Fields into Records

In records, the source field is assigned the same record field properties as the model field on each record, and is inserted directly after the model field.

If the model field has a prompt table, a prompt table is created for the source field using the name of the source field with TBL appended to it.

If the record is either a SQL View or Dynamic View type, the associated SQL is modified by having the SELECT clause expanded to include the new field.

If the record is a subrecord, the parent records of type SQL View or Dynamic View that contain this subrecord are updated.

If the SQL contains the model field in the WHERE clause, or the SQL is complex, the associated record is inserted into a project called BLK_FieldName. You should examine this record and make any necessary changes.

If the model field has PeopleCode associated with it on the record or in a component, and ClonePCode has been set to True, this PeopleCode is cloned to the new field, with all references to the model field changed to refer to the new field.

Note: Because using this function changes records that are used to build application tables, you must rebuild (alter) the specified project before these changes can be used.

#### Considerations Inserting Fields into Pages

If the model field is in a grid, the system inserts the new field into the grid next to the model field and assigns it the same page field properties.

If the model field is not in a grid, the system inserts the new field onto the page to the right of the model field (in the first open space) and assigns it the same page field properties. If the system detects a questionable field position, it inserts the page into a project called BLK_FieldName. The page will work as-is, however, the GUI layout may not be optimal, so you should examine these pages by hand.

The page field name property isn't cloned if it exists on the model field. Instead, the field name of the new field is used, since the page field name should be a unique identifier for page elements.

Note: If the project you specified only contained pages and not records, you do not need to rebuild the project after using this function. The changes take affect when the component containing the page is reloaded.

#### Considerations Using this Function

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded.

Bulk operations are time consuming, therefore, referencing the log file to see the progress of an operation is recommended. These operations accommodate errors and continue processing, logging the overall progress of the operation.

Warning! These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.

#### Considerations Using the Exclusion Project

If you specify ExclProj, the following items that are both in ProjectName and ExclProj are not changed, that is, the field specified is not inserted to these items:

• pages

• records

• associated SQL with records of type View

• any PeopleCode associated with those items.

Individual SQL or PeopleCode items are not ignored by themselves, only as associated with records or pages.

### Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

### Example

```&pjm = "MYPROJ";

&ret =  BulkInsertField(&pjm, Field.OrgId, Field.DeptId, True, "EXCLPROJ");

If (&ret = %MDA_Success) Then
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkInsertField succeeded");
Else
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkInsertField failed");
End-If;```

## BulkModifyPageFieldOrder

### Syntax

`BulkModifyPageFieldOrder({ProjectName | PageList}, ColNames, RequireAll, [ColWidths])`

### Description

Use the BulkModifyPageFieldOrder function to reorder the grid columns as specified by ColNames. If ColWidths is specified, the columns are also resized. This can also be used to modify a single columns width.

Note: You must have the role Peoplesoft Administrator assigned to your UserId in order to use this function.

If you specify a project name as a parameter, and if that project contains objects such as fields which have an upgrade action of delete, those objects are ignored.

The reordering algorithm “bunches” these fields together at the first instance of any of these fields in a target page grid, and forces the remaining fields into the order specified.

This function only reorders fields inside a grid.

If the fields occur twice or more in a grid, from two or more records, such as work records, the fields are bunched together in record groupings before being sorted into the order specified. For example, the two records ABS_HIST and PERSONAL_HISTORY both contain the fields DURATION_DAYS and DURATION_HOURS. The following is an example of how the records are fields would be bunched together first:

• ABS_HIST, DURATION_DAYS

• ABS_HIST, DURATION_HOURS

• PERSONAL_HISTORY, DURATION_DAYS

• PERSONAL_HISTORY, DURATION_HOURS

Note: These changes take affect after components are reloaded.

#### Using the Log File

Information about this operation is stored in a log field. The directory where the log file is placed depends on where the function is run from:

• If the function is run in two-tier, the log file is located at PS_CFG_HOME /BulkOps.txt. This is also the default location if the system cannot find the other paths.

• If the function is run from an application server, the log file is located here:

PS_CFG_HOME /APPSERV/Domain_Name/LOGS/BulkOps.txt

• If the function is run from an Application Engine program, the log file is written to the process' output log directory, that is:

PS_CFG_HOME /APPSERV/prcs/Domain_Name/log_output/Process_Name_Instance/BulkOps.txt

#### Considerations Using this Function

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded.

Bulk operations are time consuming, therefore, referencing the log file to see the progress of an operation is recommended. These operations accommodate errors and continue processing, logging the overall progress of the operation.

Warning! These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.

### Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

### Example

```Local Array of String &ColOrder;
Local Array of Number &ColWidth;
Local String &pjm, &ret;

&pjm = "MYPROJ";
&ColWidth = CreateArray(50, 100, -1);
&ColOrder = CreateArray("DEPTID", "ORGID", "PROJECT");

&ret =  BulkModifyPageFieldOrder(&pjm, &ColOrder, True, &ColWidth);

If (&ret = %MDA_Success) Then
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkModifyPageFieldOrder succeeded");
Else
MessageBox(0, "Metadata Fn Status", 0, 0, "BulkModifyPageFieldOrder failed");
End-If;```

## BulkUpdateIndexes

### Syntax

`BulkUpdateIndexes([StringFieldArray])`

### Description

Use BulkUpdateIndexes to update indexes (PSINDEXDEFN table) for records that contain a field whose NotUsed setting has changed.

A field whose NotUsed flag has been set to True does not show up in indexes. The only way to modify a field's NotUsed setting is through an API call such as in the following example:

`SetDBFieldNotUsed(FIELD.OrgId, True); `

The indexes of records that contain this field need to be updated to reflect the new settings.

Information about this operation can be logged by turning on PeopleCode tracing of internal functions (value 256.)

#### Considerations Using this Function

Do not invoke this function from runtime pages, as it modifies all records, including the records used to support the page it is invoked from. This function should be invoked from a Application Engine program.

Note: If you do call this function from a page the operation completes successfully, but the page returns an error message. Switching to a new component clears up this error, however, any changes not saved to the database are lost.

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded.

Bulk operations are time consuming, therefore, referencing the log file to see the progress of an operation is recommended. These operations accommodate errors and continue processing, logging the overall progress of the operation.

Calling this function without any parameter rebuilds the indexes for all records, an operation that may take hours. By indicating a list of fields whose NotUsed flag has changed, only the affected records have their indexes updated, reducing the time required to run this function.

Warning! These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.

### Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

### Example

The following example uses the function without the optional array of field names:

```&ret =  BulkUpdateIndexes();
If (&ret = %MDA_Success) Then
MessageBox(0, "MetaData Fn Status", 0, 0, "BulkUpdateIndexes succeeded");
Else
MessageBox(0, "MetaData Fn Status", 0, 0, "BulkUpdateIndexes failed");
End-If;```

The following example uses the function with an array of two field names passed to it:

```&ret =  BulkUpdateIndexes(CreateArray("DEPTID","PROJECT"));
If (&ret = %MDA_success) Then
MessageBox(0, "MetaData Fn Status", 0, 0, "BulkUpdateIndexes succeeded");
Else
MessageBox(0, "MetaData Fn Status", 0, 0, "BulkUpdateIndexes failed");
End-If;```

## CallAppEngine

### Syntax

`CallAppEngine(applid[, statereclist, processinstance])`

Where statereclist is list of record objects in the form:

`&staterecord1 [, &staterecord2] .  .  .`

There can be only as many record objects in statereclist as there are state records for the Application Engine program. Additional record objects are ignored.

### Description

Use the CallAppEngine function to start the Application Engine program named applid. This is how to start your Application Engine programs synchronously from a page. (Prior to PeopleTools 8, you could do only this using the RemoteCall function.) Normally, you won’t run Application Engine programs from PeopleCode in this manner. Rather, the bulk of your Application Engine execution will be run using the Process Scheduler, and the exception would be done using CallAppEngine.

The staterecord can be the hard-coded name of a record, but generally you use a record object to pass in values to seed particular state fields. The record name must match the state record name exactly.

The processinstance allows you to specify the process instance used by the Application Engine runtime. In your PeopleCode program this parameter must be declared of type integer since that is the only way the runtime can tell whether the last parameter is to be interpreted as a process instance. For more details see the Application Engine documentation.

After you use CallAppEngine, you may want to refresh your page. The Refresh method, on a rowset object, reloads the rowset (scroll) using the current page keys. This causes the page to be redrawn. GetLevel0().Refresh() refreshes the entire page. If you want only a particular scroll to be redrawn, you can refresh just that part.

Note: If you supply a non-zero process instance, all message logging is done under the process instance. You must build your own PeopleSoft Pure Internet Architecture page to access or delete the messages, since there is no Process Monitor entry for the process instance you used.

#### PeopleCode Event Considerations

You must include the CallAppEngine PeopleCode function within events that allow database updates because generally, if you’re calling Application Engine, you’re intending to perform database updates. This includes the following PeopleCode events:

• SavePreChange (Page)

• SavePostChange (Page)

• Workflow

• FieldChange

If CallAppEngine results in a failure, all database updates is rolled back. All information the user entered into the component is lost, as if the user pressed ESC.

#### Application Engine Considerations

You can also use the CallAppEngine function in a Application Engine program, either directly (in a PeopleCode action) or indirectly (using a Component Interface). This functionality must be used carefully, and you should only do this once you have a clear understanding of the following rules and restrictions.

• Dedicated cursors are not supported inside a "nested application engine instance" (meaning an application engine program invoked using CallAppEngine from within another application engine program). If a nested application engine instance has any SQL actions with ReUse set to Yes or Bulk Insert, those settings are ignored.

• As in any other type of PeopleCode event, no commits are performed within the called application engine program. This is an important consideration. If a batch application engine program called another program using CallAppEngine, and that child program updated many rows of data, the unit-of-work might become too large, resulting in contention with other processes. A batch application engine program should invoke such child programs using a Call Section action, not CallAppEngine.

• Temp tables are not shared between a batch application engine program and child program invoked using CallAppEngine. Instead, the child program is assigned an "online" temporary table instance, which is used for all temp tables in that program. In addition, if that child program invokes another program using CallAppEngine, that grandchild shares the online temp instance with the caller. In other words, only one online temp instance is allocated to a process at any one time, no matter how many nested CallAppEngine's there might be.

• The lock on an online temp instance persists until the next commit. If the processing time of the called program is significant (greater than a few seconds), this would be unacceptable. As a general rule, application engine programs that make use of temp tables and have a significant processing time should be called from other application engine programs using a Call Section action, not CallAppEngine.

#### Save Events Considerations

To execute the Application Engine program based on an end user Save, use the CallAppEngine function within a Save event. When you use CallAppEngine, you should keep the following items in mind:

• No commits occur during the entire program run.

• During SavePreChange, any modified rows in the page have not been written to the database.

• During SavePostChange, the modified rows have been written to the database. The Page Process issues one commit at the end of the Save cycle.

#### FieldChange Considerations

If you don’t want the CallAppEngine call to depend on a Save event, you can also initiate CallAppEngine from a FieldChange event. When having a FieldChange event initiate CallAppEngine, keep the following items in mind:

• No commits occur within the program called by CallAppEngine. The called program remains a synchronous execution in the same unit of work.

• The Component Processor commits all updates done in a FieldChange at the end of the event, which frees any locks that the Application Engine program might have acquired.

• Do not include a DoSave function in the same FieldChange event. Not only is this not allowed, but it also indicates that you should be including the CallAppEngine within a Save event.

• You can use the DoSaveNow function in the same FieldChange event, but it must be called prior to the first CallAppEngine function, but not afterward.

None.

### Example

The following calls the Application Engine program named MYAPPID, and passes initialization values.

```&REC = CreateRecord(RECORD.INIT_VALUES);
&REC.FIELD1.Value = "XYZ";
/* set the initial value for INIT_VALUES.FIELD1 */
CallAppEngine("MYAPPID", &REC);```

### Syntax

`CancelPubHeaderXmlDoc(PubID, PubNode, ChannelName, VersionName)`

### Description

Use the CancelPubHeaderXmlDoc function to programmatically cancel the message header of a publication contract, much the same as you can do in the message monitor.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class Cancel method instead.

The message header, also known as the message instance, is the published message before the system performs any transformations.

The function is only available when the message has one of the following statuses:

• Error

• New

• Retry

• Timeout

• Edited

Cancel

### Returns

A Boolean value: True if the function completed successfully, False otherwise.

## CancelPubXmlDoc

### Syntax

`CancelPubXmlDoc(PubID, PubNode, ChannelName, VersionName, MessageName, SubNode[, Segment])`

### Description

Use the CancelPubXmlDoc function to programmatically cancel a message publication contract, much the same as you can do in the message monitor.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class Cancel method instead.

This is the publication contract that exists after any transformations have been preformed.

The function is only available when the message has one of the following statuses:

• Error

• New

• Retry

• Timeout

• Edited

### Returns

A Boolean value: True if the function completed successfully, False otherwise.

## CancelSubXmlDoc

### Syntax

`CancelSubXmlDoc(PubID, PubNode, ChannelName, VersionName, MessageName, SubscriptionName[, Segment])`

### Description

Use the CancelSubXmlDoc function to programmatically cancel a message subscription contract, much the same as you can do in the message monitor.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class Cancel method instead.

The function is only available when the message has one of the following statuses:

• Error

• New

• Retry

• Timeout

• Edited

### Returns

A Boolean value: True if function completed successfully, False otherwise.

### Syntax

`ChangeEmailAddress(Type, Address)`

### Description

Use the ChangeEmailAddress function to change the type of an email address that you've already added for the current user. You can only have one email address of a specific type for a user. If you try to use a type that already has an email address associated with it, you receive an error.

Value

Description

BB

BUS

HOME

OTH

WORK

None.

## Char

### Syntax

`Char(n)`

### Description

Use the Char function to convert a decimal numeric value n to the corresponding Unicode character.

### Returns

Returns a string representing the Unicode character corresponding to the number n.

### Example

This example sets three strings:

```&STRING1 = Char(80) | Char(83);
&STRING2 = Char(26085) | Char(26412);
&STRING3 = Char(55362) | Char(56697);

```

The following table shows the Unicode hexadecimal code points and the string equivalents for these calls to the Char function:

Variable

Char (Decimal)

Unicode Code Points

String

&STRING1

Char(80) | Char(83)

U+0050, U+0053

PS

&STRING2

Char(26085) | Char(26412)

U+65E5, U+672C

&STRING3*

Char(55362) | Char(56697)

U+D842 U+DD79

𠥹

* The single character in &STRING3 signifies a non-BMP, UTF-32 character (U+20979), which is represented by the UTF-16 surrogate pair (U+D842 U+DD79). Unless your system is configured to display supplementary characters and has a supporting font, &STRING3 will appear as an empty box in the String column in the preceding table.

For reference, Unicode character charts are available from The Unicode Consortium.

## CharType

### Syntax

`CharType(source_str, char_code) `

### Description

Use the CharType function to determine whether the first character in source_str is of type char_code . The char_code parameter is a numeric value representing a character type (see the following Parameters section for details). Most character types supported by this function equate to specific Unicode character blocks or are based on Unicode character properties.

Understanding Character Sets

### Parameters

The following table shows valid values for char_code. You can specify either a Character Code or a Constant:

Numeric Value

Constant

Character Set

0

%CharType_AlphaNumeric

Basic Latin — Alphanumeric (printable range of 7-bit US-ASCII), Unicode characters in the range U+0020 — U+007E

1

%CharType_ExtendedLatin1

Extended Latin-1 characters (ISO 8859-1 accents for Western European languages), Unicode characters in the range U+00BF — U+07E

2

%CharType_HankakuKatakana

Hankaku Katakana (half-width Japanese Katakana)

3

%CharType_ZenkakuKatakana

Zenkaku Katakana (full-width Japanese Katakana)

4

%CharType_Hiragana

Hiragana (Japanese)

5

%CharType_Kanji

Chinese, Japanese and Korean ideographic characters. Includes Japanese Kanji, Chinese Hanzi and Korean Hancha.

6

%CharType_DBAlphaNumeric

Full-width Latin Alphanumeric characters, primarily used for Japanese. Excludes

7

None

Korean Hangul syllables, excluding Hangul Jamo.

8,9

None

Reserved for future use.

10

%CharType_JapanesePunctuation

Full- and half-width punctuation, including space (U+0020) and Fullwidth / Ideographic Space (U+3000).

11

None

Greek

12

None

Cyrillic

13

None

Armenian

14

None

Hebrew

15

None

Arabic

16

None

Devanagari

17

None

Bengali

18

None

Gurmukhi

19

None

Gujarati

20

None

Oriya

21

None

Tamil

22

None

Telugu

23

None

24

None

Malayalam

25

None

Thai

26

None

Lao

27

None

Tibetan

28

None

Georgian

29

None

Bopomofo

### Returns

CharType returns one of the following Number values. You can check for the constant values instead of the numeric values if you prefer:

Numeric Value

Constant Value

Description

1

%CharType_Matched

Character is of type char_code.

0

%CharType_NotMatched

Character is not of type char_code.

-1

%CharType_Unknown

UNKNOWN: unable to determine whether character is of set char_code. This occurs if the character being checked is an unallocated Unicode codepoint, or was added in a version of Unicode greater than that supported by PeopleTools.

### Example

This example tests to see if a character is Hiragana:

```&ISHIRAGANA = CharType(&STRTOTEST, %CharType_Hiragana);
If &ISHIRAGANA = 1 Then
WinMessage("Character type is Hiragana");
Else
If &ISHIRAGANA = 0 Then
WinMessage("Character type is not Hiragana");
Else
WinMessage("Character type is UNKNOWN");
End-If;
End-If;```

## ChDir

### Syntax

`ChDir(path)`

### Description

Use the ChDir function to change the current directory on a drive. This is similar to the DOS ChDir command. The drive and the directory are both specified in a path string.

Note: This function has been deprecated.

## ChDrive

### Syntax

`ChDrive(str_dr)`

### Description

Use the ChDrive function to change the current disk drive to the drive specified by str_dr, which is a string consisting of a valid drive letter followed by a colon, for example "C:".

Note: This function has been deprecated.

### Syntax

`CheckMenuItem(BARNAME.menubar_name, ITEMNAME.menuitem_name)`

### Description

Use the CheckMenuItem function to change the menu state by placing a check mark beside the menu item.

Note: This function has been deprecated.

## ChunkText

### Syntax

`ChunkText(string, delimiter [, chunk_size])`

### Description

Use the ChunkText function to break a long text string into chunks that can be more readily managed by a storage system, such as a database text field. You must specify a string delimiter; the chunk size is optional.

### Returns

An array of string.

### Example

```Local array of string &chunkList;

&STRINGTOCHUNK = "NewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYorkNewYork";
&DELIM = "r";
&CHUNKSIZE = 8;

&chunkList = ChunkText(&STRINGTOCHUNK, &DELIM, &CHUNKSIZE);
```

The preceding example produces the following 16 chunks:

`[NewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYor][kNewYork]`

## Clean

### Syntax

`Clean(string)`

### Description

Use the Clean function to remove all non-printable characters, such as control codes, end of line marks, and unpaired Unicode combining marks, from a text string and return the result as a String value. It is intended for use on text imported from other applications that contains characters that may not be printable. Frequently, low-level characters appear at the beginning and end of each line of imported data, and they cannot be printed.

### Returns

Returns a String value purged of non-printable characters.

### Example

Because Char(7) (U+0007) is a non-printable character, the following Clean function returns a null string:

`&CLEANSTR = Clean(Char(7));`

## CleanAttachments

### Syntax

`CleanAttachments(([PreserveCaseHint])`

### Description

Use the CleanAttachments function to delete all unreferenced (orphaned) files from database tables serving as file storage locations.

Note: CleanAttachments operates only on database tables that have been used as file attachment storage locations, and not on FTP sites or HTTP repositories.

Warning! There is no way to roll back changes made by the CleanAttachments function. Oracle recommends that you perform a database backup before invoking this function.

It is important that you understand how the system determines that a file is unreferenced, and how it determines which tables contain file attachments.

CleanAttachments compiles two lists:

• List 1: A list of file references that is constructed by finding all the distinct values in the ATTACHSYSFILENAME column in each table with a record definition that contains the FILE_ATTACH_SBR subrecord (at any level). Any file not in this list is considered not referenced (orphaned).

• List 2: A list of actual stored files that is constructed by finding the distinct values in the ATTACHSYSFILENAME column in each table with a record definition that contains the FILE_ATTDET_SBR subrecord at the top level.

The system deletes any file that appears in the second list, but not in the first, after having determined the effect of the optional PreserveCaseHint parameter.

Note: A table is only considered to contain file references if its associated record contains the FILE_ATTACH_SBR subrecord (at any level). If an application has stored file references in tables that do not contain the FILE_ATTACH_SBR subrecord, and you invoke the CleanAttachments function, then all the files uploaded to the database through that application will be deleted because the files will not be found in list 1 and the system therefore regards them as unreferenced.

Similarly, the FILE_ATTDET_SBR subrecord must be at the top level of the table that contains the actual attachments or the table will be ignored by CleanAttachments. In this case, CleanAttachments does not find any files to delete and does nothing at all.

To schedule a regular job to clean up orphaned file attachments, you can use the CLEANATT84 Application Engine program.

In addition, the Copy File Attachments page is provided as a way to launch a CopyAttachments operation (select PeopleTools, Utilities, Administration, Copy File Attachments). The CleanAttachments function is also available from this page.

Note: When large numbers of orphaned file attachments might exist, Oracle recommends using the delivered Application Engine program, CLEANATT84, rather than the Delete Orphan Attachments button to remove the orphaned files. This avoids potential time-out issues.

See “Deleting Orphan Attachments” in Copy File Attachments.

### Parameters

For PreserveCaseHint, specify one of the following constant values:

Numeric Value

Constant Value

Description

1

%CleanAttach_PreserveCase

Indicates that the comparison is to be performed as if PreserveCase were True when all the files were uploaded to this database. Therefore, the comparison between list 1 and list 2 requires an exact match of the file name including its file extension. Any files in list 2 (actual stored files) that do not have an exact match in list 1 (names of referenced files) are deleted.

2

%CleanAttach_NoPreserveCase

Indicates that the comparison is to be performed as if PreserveCase were False when all the files were uploaded to this database. Therefore, the comparison between list 1 and list 2 will be performed only after the file extension of each file in list 1 is lowercased. Any files in list 2 (actual stored files) that do not have an exact match in list 1 (names of referenced files) after lowercasing the file extension in list 1 are deleted.

0

%CleanAttach_Default

Indicates that the comparison is to be performed as if PreserveCase were True when some of the files were uploaded to this database and False for others. Therefore, a file in list 2 (actual stored files) is retained if it would have been retained had PreserveCaseHint been specified as either %CleanAttach_PreserveCase or %CleanAttach_NoPreserveCase. Otherwise, the file is considered an orphan and is deleted.

The following table summarizes the action of CleanAttachments on five different stored files depending on the values found in the file reference table and depending on the value of the optional PreserveCaseHint parameter:

List 1: File Names in File Reference Table(s)

List 2: File Names in File Storage Table(s)

%CleanAttach_ PreserveCase

%CleanAttach_ NoPreserveCase

%CleanAttach_ Default

file1.txt

file1.txt

retain

retain

retain

file2.TXT

file2.txt

delete

retain

retain

file3.TXT

file3.TXT

retain

delete

retain

file4.TXT and file4.txt

file4.TxT

delete

delete

delete

none found

file5.txt

delete

delete

delete

### Returns

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

Note: Because CleanAttachments is designed to work with multiple files, to track errors when using CleanAttachments set your PeopleCode trace to 2112 and your SQL trace to 15 so that errors will be written to the appropriate trace files.

Numeric Value

Constant Value

Description

0

%Attachment_Success

Files were deleted successfully.

1

%Attachment_Failed

Files were not deleted successfully.

The following are some possible situations where %Attachment_Failed could be returned:

• Failed to initialize the process due to some internal error.

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

### Example

`&retcode = CleanAttachments(%CleanAttach_PreserveCase);`

## ClearKeyList

### Syntax

`ClearKeyList()`

### Description

Use the ClearKeyList function to clear the current key list. This function is useful for programmatically setting up keys before transferring to another component.

### Returns

Optionally returns a Boolean value indicating whether the function succeeded.

### Example

The following example sets up a key list and then transfers the user to a page named PAGE_2.

```ClearKeyList( );
SetNextPage("PAGE_2");
TransferPage( );```

## ClearSearchDefault

### Syntax

`ClearSearchDefault([recordname.]fieldname)`

### Description

Use the ClearSearchDefault function to disable default processing for the specified field, reversing the effects of a previous call to the SetSearchDefault function.

Note: This function remains for backward compatibility only. Use the SearchDefault Field class property instead.

If search default processing is cleared for a record field, the default value specified in the record field properties for that field will not be assigned when the field appears in a search dialog box. This function is effective only when used in SearchInit PeopleCode.

### Returns

Optionally returns a Boolean value indicating whether the function succeeded.

## ClearSearchEdit

### Syntax

`ClearSearchEdit([recordname.]fieldname)`

### Description

Use the ClearSearchEdit function to reverse the effects of a previous call to the SetSearchEdit function. If ClearSearchEdit is called for a specific field, the edits specified in the record field properties will not be applied to the field when it occurs in a search dialog.

Note: This function remains for backward compatibility only. Use the SearchEdit Field class property instead.

### Returns

Optionally returns a Boolean value indicating whether the function succeeded.

## Code

### Syntax

`Code(str)`

### Description

Use the Code function to return the numerical Unicode UTF-16 value for the first character in the string str. (Normally you would pass this function a single character.) If the string starts with a non-BMP Unicode character, the value returned will be that of the Unicode high surrogate of the character (the first value of the surrogate pair).

### Returns

Returns a Number value equal to the character code for the first character in str.

## Codeb

### Syntax

`Codeb(str)`

### Description

Note: This function has been deprecated and is no longer supported.

## CollectGarbage

### Syntax

`CollectGarbage()`

### Description

Use the CollectGarbage function to remove any unreachable application objects created by the Application Classes.

Sometimes there may be unrecoverable application objects that are can no longer be referenced from PeopleCode, but which have not been reclaimed and so are still taking up computer memory. Generally this situation arises only if you have application objects that form into loops of references.

This function is automatically invoked by the application server as part of its end-of-service processing, so generally you do not need to call it for online applications. However, in Application Engine (batch), it is possible that a long-running batch job could grow in memory usage over time as these unreferencable Application Objects accumulate. The solution to such a problem is to call CollectGarbage periodically to reclaim these objects.

None.

None.

## CommitWork

### Syntax

`CommitWork()`

### Description

Use the CommitWork function to commit pending changes (inserts, updates, and deletes) to the database.

#### Considerations for Using CommitWork

The following are the considerations for using CommitWork.

• This function is available in Application Engine PeopleCode, the FieldChange and SavePreChange events. If you use it anywhere else, you'll receive a runtime error.

• When used with an Application Engine program, this function only applies to those Application Engine programs that run in batch (not online). If the program is invoked using the CallAppEngine function, the CommitWork call is ignored. The same is true for commit settings at the section or step level.

• This function can only be used in an Application Engine program that has restart disabled. If you try to use this function in a program that doesn't have restart disabled, you'll receive a runtime error.

• Component interfaces that rely on CommitWork to save data cannot be used in the Excel to Component Interface utility.

• When CommitWork is called in the context of a component interface (such as, during a SavePreChange PeopleCode program that's associated with the component), if the caller of the component interface already has an open cursor (such as an active SQL object) the Commit does not take effect immediately, but only when the last cursor is closed.

See CallAppEngine.

#### FieldChange and SavePreChange Considerations

The following are the FieldChange and SavePreChange considerations:

• All updates done in FieldChange (including those using CallAppEngine) should be considered a single database transaction. This is a fundamental change: previously, a single transaction was represented by a page or a component.

• A consequence of this is that a message requiring a reply, or any other think-time action, causes a fatal error if located in FieldChange after a database update that has not been committed to the database using the CommitWork function. So it is possible for an application to update the database in FieldChange, then do a think-time action, by preceding the think-time action with a call to CommitWork.

• CommitWork commits the updates and closes the database transaction (that is, the unit of work). The consequence of using CommitWork is that because it closes the database transaction, any subsequent rollback calls will not rollback the committed updates.

• Just as any database updates in FieldChange required careful application design to ensure that the transaction model is appropriate, so too does the use of CommitWork.

• When using CommitWork in the Component Processor environment (as opposed to using it in an Application Engine program) CommitWork produces an error if there are any open cursors, such as any open PeopleCode SQL objects.

#### Application Engine Considerations

The CommitWork function is useful only when you are doing row-at-a-time SQL processing in a single PeopleCode program, and you must commit without exiting the program. In a typical Application Engine program, SQL commands are split between multiple Application Engine actions that fetch, insert, update, or delete application data. Therefore, you would use the section or step level commit settings to manage the commits. This is the recommended approach.

However, with some types of Application Engine programs that are PeopleCode intensive, it can be difficult to exit the PeopleCode in order to perform a commit. This is the only time when the CommitWork function should be used.

#### Restart Considerations

Disabling restart on a particular program means that the application itself is intrinsically self-restartable: it can be re-run from the start after an abend, and it performs any initialization, cleanup, and filtering of input data to ensure that everything gets processed once and only once, and that upon successful completion, the database is in the same state it would have been if no abend occurred.

Set-based applications should always use Application Engine's restart. Only row-by-row applications that have restart built into them can benefit from disabling Application Engine's restart.

Consider the following points to managing restarts in a self-restarting program:

• Locking input transactions (optional).

If the input data can change, and if it's important not to pick up new data during a restart, there should be logic to lock transactions at the start of the initial run (such as updating rows with current Process Instance). The program should first check whether any rows have the current Process Instance (that is, is the process being restarted from the top after an abend?). If no rows found, do the update.

In some cases it is acceptable for a restarted process to pick up new rows, so that locking is not necessary. It depends on your application.

Also, if you do not lock transactions, you must provide some other way to manage concurrent processing of the same program. You do not want two simultaneous runs of the same program to use the same data, so you must have some strategy for dividing up the data such that there is no overlap.

• Filtering input transactions (required).

After an input transaction is processed, the row should be updated accordingly (that is, setting a "processed" flag). The SELECT statement that drives the main processing loop should include a WHERE condition to filter out rows that have already been processed.

### Returns

A Boolean value, True if data was successfully committed, False otherwise.

### Example

The following example fetches rows and processes them one at a time, committing every 100 iterations. Because restart is disabled, you must have a marker indicating which rows have been processed, and use it in a conditional clause that filters out those rows.

```Local SQL &SQL;
Local Record &REC;
Local Number &COUNT;

&REC = CreateRecord(RECORD.TRANS_TBL);
&SQL = CreateSQL("%SelectAll(:1) WHERE PROCESSED <> 'Y'");
&COUNT = 0;

&SQL.Execute(&REC);
While &SQL.Fetch(&REC)
If (&COUNT > 99) Then
&COUNT = 0;
CommitWork();   /* commit work once per 100 iterations */
End-if;
&COUNT = &COUNT + 1;
/* do processing */
...

/* update transaction as "processed" */
&REC.PROCESSED.Value = 'Y';
&REC.Update();
End-While;```

## CompareLikeFields

### Syntax

`CompareLikeFields(from, to)`

where from and to are constructions that reference rows of data on specific source and target records in the component buffer; each have the following syntax:

`level, scrollpath, target_row`

and where scrollpath is:

`[RECORD.level1_recname, level1_row, [RECORD.level2_recname, level2_row, ]] RECORD.target_recname`

To prevent ambiguous references, you can use SCROLL. scrollname, where scrollname is the same as the scroll level’s primary record name.

### Description

Use the CompareLikeFields function to compare fields in a row on a specified source record to similarly named fields on a specified target record.

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

If all of the like-named fields have the same data value, CompareLikeFields returns True; otherwise it returns False.

### Returns

Returns a Boolean value indicating whether all of the like-named fields in the two records have the same data value.

### Example

The following example compares the like-named fields in two rows on levels 1 (&L1_ROW) and 2 (&L2_ROW) and returns True if all of the like-named fields in the two rows have the same value.

```&L1_ROW = 1;
&L2_ROW = 1;
if CompareLikeFields(1, RECORD.BUS_EXPENSE_PER, &L1_ROW, 2, RECORD.BUS_EXPENSE_PER, 1, RECORD.BUS_EXPENSE_DTL, &L2_ROW) then
WinMessage("The fields match.");
end-if;```

## CompareStrings

### Syntax

`CompareStrings(new_text, old_text [, content_type [, delimiter]])`

### Description

Use the CompareStrings function to compare the content of new_text with the content of old_text and return an XML-formatted text string detailing the differences between the two strings.

The XML string indicates the type of change for each line or text segment, based on the delimiter, as shown in the following table:

Notation

Description

None

Both lines are the same

Insert

A line is present in new_text that is not in old_text.

Delete

A line is absent in new_text that is present in old_text.

Change

A change in a line shows as an Insert in new_text and a Delete in old_text.

### Returns

Returns a String in XML format showing the differences between the two input strings.

### Example

This example shows a comparison of two text strings.

The variable &NewText contains the following string:

```Line 2.
Line 2.1.
Line 2.2.
Line 3.
Line 5.
Line 6.
Line 8.
```

The variable &OldText contains the following string:

```Line 1.
Line 2.
Line 3.
Line 4.
Line 7.
```

The following PeopleCode statement compares the two ASCII-formatted text strings, &NewText and &OldText.

`&OutputXML = CompareStrings(&NewText, &OldText, "Text");`

The string variable &OutputXML contains the following text:

```<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<CompareReport ContentType="text" Delimitter="&#xA;">
<FileContent Difference="Deleted">
<Line Num="1">
<LineContent>Line 1.</LineContent>
</Line>
</FileContent>
<FileContent Difference="None">
<Line Num="1" OldLineNum="2">
<LineContent>Line 2.</LineContent>
</Line>
</FileContent>
<FileContent Difference="Inserted">
<Line Num="2">
<LineContent>Line 2.1.</LineContent>
</Line>
<Line Num="3">
<LineContent>Line 2.2.</LineContent>
</Line>
</FileContent>
<FileContent Difference="None">
<Line Num="4" OldLineNum="3">
<LineContent>Line 3.</LineContent>
</Line>
</FileContent>
<FileContent Difference="Changed">
<OldLine Num="4">
<LineContent>Line</LineContent>
<LineContent Changed="Deleted">4.</LineContent>
</OldLine>
<Line Num="4">
<LineContent>Line</LineContent>
<LineContent Changed="Inserted">5.</LineContent>
</Line>
<OldLine Num="5">
<LineContent>Line</LineContent>
<LineContent Changed="Deleted">7.</LineContent>
</OldLine>
<Line Num="5">
<LineContent>Line</LineContent>
<LineContent Changed="Inserted">6.</LineContent>
</Line>
</FileContent>
<FileContent Difference="Inserted">
<Line Num="7">
<LineContent>Line 8.</LineContent>
</Line>
</FileContent>
</CompareReport>
```

This example shows a comparison of two HTML strings.

The variable &NewHTML contains the following string:

```<p><H1>peoplesoft<B>file<B> difference utility
<I>Peopletools<I> Release &lt;6 and &gt;5 </H1></p>
<p> &lt;BOLD&gt;Hello world<ITALIC></p>
```

The variable &OldHTML contains the following string:

```<p><H1>peoplesoft<B>file<B>difference utility
<I>Peopletools<I> Release &lt;7 and &gt;5 </H1></p>
<p> &lt;BOLD&gt;Hello world<ITALIC></p>
```

The following PeopleCode statement compares the two HTML-formatted text strings, &NewHTML and &OldHTML.

&OutputXML = CompareStrings(&NewHTML, &OldHTML, "HTML");

The string variable &OutputXML contains the following text:

```<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<CompareReport Delimitter="</p>,</H1>" ContentType ="html">
<FileContent Difference="Changed">
<OldLine Num="1">
<LineContent Changed="Deleted">peoplesoftfile difference</LineContent>
<LineContent>utility Peopletools Release</LineContent>
<LineContent Changed="Deleted ">&lt;6</LineContent>
<LineContent>and &gt;5 </LineContent>
</OldLine>
<Line Num="1">
<LineContent Changed="Inserted">peoplesoftfiledifference</LineContent>
<LineContent>utility Peopletools Release</LineContent>
<LineContent Changed="Inserted ">&lt;7</LineContent>
<LineContent>and &gt;5 </LineContent>
</Line>
</FileContent>
<FileContent Difference="None">
<Line Num="2" OldLineNum="2">
<LineContent>&amp;lt;BOLD&amp;gt;Hello world</LineContent>
</Line>
<Line Num="3" OldLineNum="3">
<LineContent></LineContent>
</Line>
</FileContent>
</CompareReport>

```

## CompareTextDiff

### Syntax

`CompareTextDiff(new_text, old_text [, content_type [, delimiter]]) `

### Description

Use the CompareTextDiff function to compare the content of new_text with the content of old_text and return an array of array of any detailing the differences between the two strings. The elements of the returned subarray are as follows:

Element

Data Type

Description

index

number

The sequential index number in the comparison array.

line

number

The line number for the line of text being compared.

subline

number

The subline is the counter of added lines that exist in the new_text.

Note: For DELETE, CHANGED and COMMON operations, 0 is always reported for the subline.

type

string

The type of difference:

• COMMON – Both lines are the same

• ADD – A line is present in new_text that is not in old_text.

• DELETE – A line is absent in new_text that is present in old_text.

• CHANGED – A change in a line shows as an Add in new_text and a Delete in old_text.

text

string

The actual text being compared.

### Returns

An array of array of any.

### Example

This example shows a comparison of two text strings. The variable &NewText contains the following string:

```Line 2.
Line 2.1.
Line 2.2.
Line 3.
Line 5.
Line 6.
Line 8.```

The variable &OldText contains the following string:

```Line 1.
Line 2.
Line 3.
Line 4.
Line 7.```

The following PeopleCode statement compares the two ASCII-formatted text strings, &NewText and &OldText:

```&Output = CompareTextDiff(&NewText, &OldText, "text");
```

The string variable &Output contains the following array:

```0, 1, 0, DELETED, Line 1.
1, 2, 0, COMMON, Line 2.
2, 2, 1, ADD, Line 2.1.
3, 2, 2, ADD, Line 2.2.
4, 3, 0, COMMON, Line 3.
5, 4, 0, CHANGED, Line 5.
6, 5, 0, CHANGED, Line 6.
7, 5, 1, ADD, Line 8.
```

## Component

### Syntax

`Component data_type &var_name`

### Description

Use the Component statement to declare PeopleCode component variables. A component variable, after being declared in any PeopleCode program, remains in scope throughout the life of the component.

The variable must be declared with the Component statement in every PeopleCode program in which it is used.

Declarations appear at the beginning of the program, intermixed with function declarations.

Note: Because a function can be called from anywhere, you cannot declare any variables within a function. You receive a design time error if you try.

The system automatically initializes temporary variables. Declared variables always have values appropriate to their declared type. Undeclared variables are initialized as null strings.

Not all PeopleCode data types can be declared as Component.

### Example

`Component string &PG_FIRST;`

## ComponentChanged

### Syntax

`ComponentChanged()`

### Description

Use the ComponentChanged function to determine whether a component has changed since the last save, whether by the user or by PeopleCode.

### Returns

Returns a Boolean value: True if the component has changed.

### Example

```If ComponentChanged() Then
/* do some stuff */
End-if;```

## ConnectorRequest

### Syntax

`ConnectorRequest(&Message)`

### Description

Use the ConnectorRequest function to send data to the connector using a message, when the connector properties are assigned in the message.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class ConnectorRequest method instead.

In general, you would build a message, add the specific connector properties, then use ConnectorRequest.

You do not need to set up any transaction or relationship when you use this function. It is a direct call to the gateway.

The response to the message is returned as a nonrowset-based message. Use the GetXmlDoc message class method to retrieve the content data. The data is wrapped in the CDATA tag.

### Returns

A nonrowset-based message object.

## ConnectorRequestURL

### Syntax

`ConnectorRequestURL(ConnectorStringURL)`

### Description

Use the ConnectorRequestURL function to go directly to the gateway for accessing information.

Note: This function has been deprecated and remains for backward compatibility only. Use the IntBroker class ConnectorRequestURL method instead.

### Returns

A string containing the URL information returned from the message.

### Example

The following is the type of URL that could be returned if you were trying to get a PSFT stock quote:

` http://finance.yahoo.com/d/quotes.txt/?symbols=PSFT&format=l1c1d1t1`

## ContainsCharType

### Syntax

`ContainsCharType(source_str, char_code) `

### Description

Use the ContainsCharType function to determine if any of the characters in source_str are of type char_code. The char_code is a numerical value representing a character type (see the following Parameters section for details). Most character types supported by this function equate to specific Unicode character blocks or are based on Unicode character properties.

### Parameters

Numeric Value

Constant

Character Set

0

%CharType_AlphaNumeric

Basic Latin — Alphanumeric (printable range of 7-bit US-ASCII), Unicode characters in the range U+0020 — U+007E

1

%CharType_ExtendedLatin1

Extended Latin-1 characters (ISO 8859-1 accents for Western European languages), Unicode characters in the range U+00BF — U+07E

2

%CharType_HankakuKatakana

Hankaku Katakana (half-width Japanese Katakana)

3

%CharType_ZenkakuKatakana

Zenkaku Katakana (full-width Japanese Katakana)

4

%CharType_Hiragana

Hiragana (Japanese)

5

%CharType_Kanji

Chinese, Japanese and Korean ideographic characters. Includes Japanese Kanji, Chinese Hanzi and Korean Hancha.

6

%CharType_DBAlphaNumeric

Full-width Latin Alphanumeric characters, primarily used for Japanese. Excludes

7

None

Korean Hangul syllables, excluding Hangul Jamo.

8,9

None

Reserved for future use.

10

%CharType_JapanesePunctuation

Full- and half-width punctuation, including space (U+0020) and Fullwidth / Ideographic Space (U+3000).

11

None

Greek

12

None

Cyrillic

13

None

Armenian

14

None

Hebrew

15

None

Arabic

16

None

Devanagari

17

None

Bengali

18

None

Gurmukhi

19

None

Gujarati

20

None

Oriya

21

None

Tamil

22

None

Telugu

23

None

24

None

Malayalam

25

None

Thai

26

None

Lao

27

None

Tibetan

28

None

Georgian

29

None

Bopomofo

### Returns

ContainsCharType returns one of the following Number values. You can check for the constant instead of the numeric value if you prefer:

Numeric Value

Constant Value

Description

1

%CharType_Matched

String contains at least one character of set char_code.

0

%CharType_NotMatched

String contains no characters of set char_code.

-1

%CharType_Unknown

UNKNOWN: unable to determine whether character is of set char_code. This occurs if the character being checked is an unallocated Unicode codepoint, or was added in a version of Unicode greater than that supported by PeopleTools.

### Example

This example tests to see if the string contains any Hiragana:

```&ANYHIRAGANA = ContainsCharType(&STRTOTEST, 4);
If &ANYHIRAGANA = 1 Then
WinMessage("There are Hiragana characters");
Else
If &ANYHIRAGANA = 0 Then
WinMessage("There are no Hiragana characters");
Else
WinMessage("UNKNOWN");
End-If;
End-If;```

## ContainsOnlyCharType

### Syntax

`ContainsOnlyCharType(source_str, char_code_list)`

Where char_code_list is a list of character set codes in the form:

`char_code_1 [, char_code_2]. . .`

### Description

Use the ContainsOnlyCharType function to determine whether every character in source_str belongs to one or more of the character types in char_code_list. See the following Parameters section for a list of valid character code values. Most character types supported by this function equate to specific Unicode character blocks or are based on Unicode character properties.

### Parameters

Numeric Value

Constant

Character Set

0

%CharType_AlphaNumeric

Alphanumeric (7-bit ASCII codes; A-Z, a-z, 1-9, punctuation)

1

%CharType_ExtendedLatin1

Extended Latin-1 characters (ISO8859-1 accents for Spanish, French, etc.)

2

%CharType_HankakuKatakana

Hankaku Katakana (single-byte Japanese Katakana)

3

%CharType_ZenkakuKatakana

Zenkaku Katakana (double-byte Japanese Katakana)

4

%CharType_Hiragana

Hiragana (Japanese)

5

%CharType_Kanji

Kanji (Japanese)

6

%CharType_DBAlphaNumeric

Double-byte Alphanumeric (Japanese)

7,8,9

Reserved for future use

10

%CharType_JapanesePunctuation

Japanese punctuation

### Returns

ContainsOnlyCharType returns one of the following Number values. You can check for the constant instead of the numeric value, if you prefer:

Numeric Value

Constant Value

Description

1

%CharType_Matched

String contains only characters belonging to the sets listed in char_code_list.

0

%CharType_NotMatched

String contains one or more characters that do not belong to sets listed in char_code_list.

-1

%CharType_Unknown

UNKNOWN: unable to determine whether character is of set char_code. This occurs if the character being checked is an unallocated Unicode codepoint, or was added in a version of Unicode greater than that supported by PeopleTools.

Note: If any character in the string is determined to be UNKNOWN, the return value is UNKNOWN.

### Example

This example tests to see is the string is only Hiragana or Punctuation:

```&ONLYHIRAGANA = ContainsOnlyCharType(&STRTOTEST, 4, 10);
If &ONLYHIRAGANA = 1 Then
WinMessage("There are only Hiragana and Punctuation characters");
Else
If &ONLYHIRAGANA = 0 Then
WinMessage("Mixed characters");
Else
WinMessage("UNKNOWN");
End-If
End-If```

## Continue

### Syntax

`Continue`

### Description

Use the Continue statement to continue execution in a loop. How the statement performs depends on the type of loop:

• In For loops, this statement continues to do the next step of the iteration

• In While loops, this statement continues to the top of the loop and the test of the condition

• In Repeat-Until loops, this statement continues to the Until check at the bottom of the loop.

None.

### Example

The following are tests of the continue statement in various types of loops:

```SetTracePC(%TracePC_List);
/* tests of continue statement */
&N = 0;
For &I = 1 To 10;

If &I > 5 Then
Continue;
End-If;
&J = &I + 1;
&K = 0;
/* now a while loop in here */
While &J <= 10;
&J = &J + 1;
If &J = 7 Then
Continue;
End-If;
For &A = 0 To 5;
&K = &K + 2;
End-For; /* no continue statement */
&Barf = 2;
Repeat
&Barf = &Barf;
If &Barf = 1 Then
Continue;
End-If;
Until &Barf = &Barf;
&K = &K + 1;
End-While;
MessageBox(0, "", 0, 0, "K=" | &K);
If &I < 2 Then
Continue;
End-If;
&N = &N + 1;
End-For;
MessageBox(0, "", 0, 0, "N=" | &N);```

## ConvertChar

### Syntax

`ConvertChar(source_str, source_str_category, output_str, target_char_code) `

### Description

Use the ConvertChar function to convert every character in source_str to type target_char_code, if possible, and place the converted string in output_str. ConvertChar supports the following conversions:

• Conversion among Japanese Hankaku (half-width) Katakana, Zenkaku (full-width) Katakana, and Hiragana .

• Conversion of Japanese Hankaku (half-width) Katakana, Zenkaku (full-width) Katakana, and Hiragana to Hepburn Romaji (Latin representation).

• Conversion of full-width alphanumeric characters to their half-width equivalents.

• Conversion of full-width punctuation characters to their half-width equivalents.

Other source_str and target_char_code combinations are either passed through without conversion, or not supported. Character types 0 and 1 (alphanumeric and extended Latin-1) are always passed through to output_str without conversion. See the Supported Conventions section later in this reference entry for details.

If ConvertChar is unable to determine whether the characters in source_str belong to the specified character set, the function returns a value of UNKNOWN (-1). If source_str can be partially converted, ConvertChar will partially convert string, echo the remaining characters to the output string as-is, and return a value of -2 (Completed with Issues).

### Parameters

Numeric Value

Constant Value

Description

0

%ConvertChar_AlphaNumeric

Half-width AlphaNumeric

1

%ConvertChar_ExtendedLatin1

Extended Latin-1 Characters (ISO8859-1 accents, Spanish, French etc.)

2

%ConvertChar_Japanese

Japanese (any)

Numeric Value

Constant Value

Description

0

%CharType_AlphaNumeric

Half-width AlphaNumeric — results in a Hepburn Romaji conversion when the input string contains Hiragana or Katakana

2

%CharType_HankakuKatakana

Hankaku Katakana (half—width Japanese Katakana)

3

%CharType_ZenkakuKatakana

Zenkaku Katakana (full-width Japanese Katakana)

4

%CharType_Hiragana

Hiragana (Japanese)

6

%CharType_DBAlphaNumeric

Full-width AlphaNumeric (Japanese)

The following target values are not supported; if the source string is of the same type as any of these values, then the string is passed through without conversion.

Numeric Value

Constant Value

Description

1

%CharType_ExtendedLatin1

Extended Latin-1 characters (ISO8859-1 accents for Spanish, French, etc.)

5

%CharType_Kanji

Chinese, Japanese and Korean ideographic characters.

10

%CharType_JapanesePunctuation

Full- and half-width punctuation, including space (U+0020) and Fullwidth / Ideographic Space (U+3000).

#### Supported Conversions

The following table shows which conversions are supported, which are passed through without conversion, and which are not supported:

Source

Target

Conversion

0 (Alphanumeric US-ASCII)

0-6 (All supported character types)

Pass through without conversion

1 (Extended Latin-1 characters)

0-6 (All supported character sets)

Pass through without conversion

2 (Hankaku Katakana)

0 (Alphanumeric — Hepburn romaji)

Conversion supported

1 (Extended Latin)

Not supported

2 (Hankaku Katakana)

Pass through without conversion

3 (Zenkaku Katakana)

Conversion supported

4 (Hiragana)

Conversion supported

5 (Kanji)

Not supported

6 (Full-width alphanumeric)

Not supported

3 (Zenkaku Katakana)

0 (Alphanumeric)

Conversion supported

1 (Extended Latin)

Not supported

2 (Hankaku Katakana)

Conversion supported

3 (Zenkaku Katakana)

Pass through without conversion

4 (Hiragana)

Conversion supported

5 (Kanji)

Not supported

6 (Full-width alphanumeric)

Not supported

4 (Hiragana)

0 (Alphanumeric- Hepburn Romaji)

Conversion supported

1 (Extended Latin)

Not supported

2 (Hankaku Katakana)

Conversion supported

3 (Zenkaku Katakana)

Conversion supported

4 (Hiragana)

Pass through without conversion

5 (Kanji)

Not supported

6 (Full-width alphanumeric)

Not supported

5 (Kanji)

0-4, 6

Not supported

5 (Kanji)

Pass through without conversion

6 (Full-width alphanumeric)

0 (Alphanumeric)

Conversion supported

1-5

Not supported

6 (Full-width alphanumeric)

Pass through without conversion

10 (Japanese punctuation)

0 (Alphanumeric)

Conversion supported

1 (Extended Latin)

Not supported

3-6, 10

Pass through without conversion

### Returns

Returns either a Number or a constant with one of the following values, depending on what you’re checking for:

Numeric Value

Constant Value

Description

1

%ConvertChar_Success

String successfully converted.

0

%ConvertChar_NotConverted

String not converted.

-1

%ConvertChar_Unknown

UNKNOWN: unable to determine whether character is of set char_code. This occurs if the character being checked is an unallocated Unicode codepoint, or was added in a version of Unicode greater than that supported by PeopleTools.

-2

%ConvertChar_Issues

Completed with issues. Conversion executed but there were one or more characters encountered that were either not recognized, or whose conversion is not supported.

Note: If any character cannot be translated, it is echoed as-is to output_str. output_str could therefore be a mixture of converted and non-converted characters.

### Example

This example attempts to convert a string to Hiragana:

```&RETVALUE = ConvertChar(&INSTR, 2, &OUTSTR, 4);
If &RETVALUE = 1 Then
WinMessage("Conversion to Hiragana successful");
Else
If &RETVALUE = 0 Then
WinMessage("Conversion to Hiragana failed");
Else
If &RETVALUE = - 1 Then
WinMessage("Input string is UNKNOWN character type.");
Else
WinMessage("Some characters could not be converted.");
End-If
End-If
End-If```

## ConvertCurrency

### Syntax

`ConvertCurrency(amt, currency_cd, exchng_to_currency, exchng_rt_type, effdt, converted_amt [, error_process [, round] [, rt_index]])`

### Description

Use the ConvertCurrency function to convert between currencies. The result of the conversion is placed in a variable passed in converted_amt.

Understanding Currency-Specific Settings

### Parameters

Note: If the currency exchange rate is changed in a PeopleSoft table, this change will not be reflected in an already open page until the user closes the page, then opens it again.

### Returns

ConvertCurrency returns a Boolean value where True means a conversion rate was found and converted_amt calculated, and False means a conversion rate was not found and a value of one (1) was used.

### Example

```rem **-----------------------------------------------**;
rem *  Convert the cost & accum_depr fields if books *;
rem * use different currencies.  *;
rem **-----------------------------------------------**;
rem;
If &FROM_CUR <> &PROFILE_CUR_CD Then
&CON_COST_FROM = &COST_COST;
&CON_ACC_DEPR_FROM = &COST_ACCUM;
ConvertCurrency(&CON_COST_FROM, &FROM_CUR, &PROFILE_CUR_CD, RT_TYPE,TRANS_DT, &CON_COST_TO, "F");
UpdateValue(COST_NON_CAP.COST, &COST_ROW_CUR, &CON_COST_TO);
Else
UpdateValue(COST_NON_CAP.COST, &COST_ROW_CUR, &COST_COST);
End-If;
UpdateValue(COST_NON_CAP.FROM_CUR, &COST_ROW_CUR, &PROFILE_CUR_CD);
UpdateValue(COST_NON_CAP.OPRID, &COST_ROW_CUR, %UserIdId);```

## ConvertDatetimeToBase

### Syntax

`ConvertDatetimeToBase(textdatetime, {timezone | "Local" | "Base"})`

### Description

Use the ConvertDatetimeToBase function to convert the text value textdatetime to a DateTime value. The ConvertDatetimeToBase function then further converts it from the specified time zone to the base time zone. This function automatically calculates whether daylight saving time is in effect for the given textdatetime and time zone.

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

### Returns

Returns a DateTime value in the base time zone.

### Example

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

`&DATETIMEVAL= ConvertDateTimeToBase("1999-01-01 10:00:00.000000", "EST");`

## ConvertRate

### Syntax

`ConvertRate(Rate, In_Frequency, Out_Frequency)`

### Description

Use the ConvertRate function to convert a rate between various compounding frequencies.

### Parameters

Value

Description

0

continuous compounding

1

daily compounding

2

monthly compounding

3

yearly compounding

Value

Description

0

continuous compounding

1

daily compounding

2

monthly compounding

3

yearly compounding

### Returns

A number representing the converted rate.

### Example

The following example converts the specified values from days to years.

```Local array of number &In, &Out;
Local number &rate, &NewRate;

&rate = 0.01891;
&In = CreateArray(0, 0);
&In[1] = 1; /* daily */
&In[2] = 1; /* compound_days */
&Out = CreateArray(0, 0);
&Out[1] = 1; /* one year */
&Out[2] = 3; /* compound_years */

&NewRate = ConvertRate(&rate, &In, &Out);```

## ConvertTimeToBase

### Syntax

`ConvertTimeToBase(texttime,{timezone | "Local" | "Base"})`

### Description

Use the ConvertTimeToBase function to convert the text value texttime to a Time value and converts it to the base time. This function automatically calculates whether daylight saving time is in effect for the given texttime.

This function is useful for users to convert constant times in specific time zones into database time. For example, there is a deadline for completing Federal Funds transfers by 3:00 PM Eastern Time. ConvertTimeToBase does this conversion, taking into account daylight saving time. The date used to calculate whether daylight saving time is in effect is the current date.

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

### Returns

Returns a time value in the base time zone.

### Example

In the following example, &TIMEVAL would have a time value of "07:00:00.000000", assuming the Base time (as defined in PSOPTIONS) was PST.

`&TEXTTIME = ConvertTimeToBase("01/01/99 10:00:00AM", "EST");`

## CopyAttachments

### Syntax

`CopyAttachments(URLSource, URLDestination [, FileRefRecords [, PreserveCase[, AllowLargeChunks]]])`

### Description

Use the CopyAttachments function to copy all files from one storage location to another. The files to be copied can be limited to those referenced in specific file reference tables.

The Copy File Attachments page is provided as a way to launch a CopyAttachments operation (select PeopleTools, Utilities, Administration, Copy File Attachments). (The CleanAttachments function is also available from this page.)

CopyAttachments looks for the field ATTACHSYSFILENAME in the table that stores the file references. Oracle recommends that you include the FILE_ATTACH_SBR subrecord, which includes the ATTACHSYSFILENAME and ATTACHUSERFILE fields, in your record definition, not just the fields themselves.

CopyAttachments generates a list of all file attachments references, and then performs two operations on each file attachment. First, CopyAttachments calls GetAttachment to retrieve the file from your source location. Then, it calls PutAttachment to copy the attachment to your destination.

Note: If the specified subdirectories do not exist this function tries to create them.

PeopleTools supports multiple types of storage locations. Additional information on using CopyAttachments with storage locations can be found in the PeopleTools 8.53: PeopleCode Developer's Guide PeopleBook.

#### Considerations on Using PreserveCase with CopyAttachments

If the files to be copied were originally uploaded with the value of the PreserveCase optional parameter unspecified or explicitly specified as False, then CopyAttachments should be similarly invoked (with the value of PreserveCase unspecified or explicitly specified as False). On the other hand, if the files to be copied were originally uploaded with the value of the PreserveCase explicitly specified as True, then CopyAttachments should be similarly invoked (with the value of PreserveCase explicitly specified as True). If the files to be copied fall into both categories, then CopyAttachment will need to be run twice , once with the value of PreserveCase unspecified or explicitly specified as False, and then again with the value of PreserveCase explicitly specified as True.

### Returns

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

Note: Since file attachment references might not always point to real files in your source location (they might point to files in other locations, for example), file not found errors from the GetAttachment operation are ignored and not included in the CopyAttachments return code.

Note: Because CopyAttachments is designed to work with multiple files, to track errors when using CopyAttachments set your PeopleCode trace to 2112 and your SQL trace to 15 so that errors will be written to the appropriate trace files.

Numeric Value

Constant Value

Description

0

%Attachment_Success

Files were copied successfully.

1

%Attachment_Failed

File copy 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 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.

3

%Attachment_FileTransferFailed

File copy failed due to an 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.

• No response from server.

• Failed to overwrite the file on remote server.

4

%Attachment_NoDiskSpaceAppServ

No disk space on the application 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

Unable to login to destination system for FTP.

The following are some possible situations where %Attachment_DestSysFailedLogin could be returned:

• Unsupported protocol specified.

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

9

%Attachment_FileNotFound

Cannot locate file.

The following are some possible situations where %Attachment_FileNotFound could be returned:

• Failed to read remote file.

### Example

`&retcode = CopyAttachments(URL.UrlID, ftp://user:passwd@ftpaddress/");`

Here is another example.

```&aRecs = CreateArray("HRATTS", "MFGATTS", "CRMATTS");

&ret = CopyAttachments("ftp://user:pass@system/HR/", "record://HRARCHIVE",
&aRecs);

If (&ret = %Attachment_Success) Then
MessageBox(0, "Copy Archive Status", 0, 0, "Copy attachment archive succeeded");
Else
MessageBox(0, "Copy Archive Status", 0, 0, "Copy attachment archive failed");
End-If;```

## CopyFields

### Syntax

`CopyFields(from, to)`

where from and to are constructions that reference rows of data on specific source and target records in the component buffer; each have the following syntax:

`level, scrollpath, target_row`

and 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 CopyFields function to copy like-named fields from a row on the specific source record to a row on the specific target record.

Note: This function remains for backward compatibility only. Use the CopyFieldsTo or CopyChangedFieldsTo record class methods instead.

### Returns

Optionally returns a Boolean value indicating whether the function succeeded.

### Example

The following example copies fields from PO_RECEIVED_INV (level 1 scroll) from row &ROW to PO_RECV_INV_VW (level 1 scroll), row &LOC_ROW:

`CopyFields(1, RECORD.PO_RECEIVED_INV, &ROW, 1, RECORD.PO_RECV_INV_VW, &LOC_ROW);`

## CopyFromJavaArray

### Syntax

`CopyFromJavaArray(JavaArray, &PeopleCodeArray [, &RestrictionArray])`

### Description

Use the CopyFromJavaArray function to copy the array specified by JavaArray into one-dimensional PeopleCode array &PeopleCodeArray.

Note: The Java array must be at least the same size as the PeopleCode array.

The optional &RestrictionArray parameter is a PeopleCode array that contains the index elements of the elements to copy. For example if &RestrictionArray contains the indexes 3, 5 and 7, only elements 3, 5 and 7 in the PeopleCode array are copied to the Java array, and they are copied to the elements 3, 5 and 7. This allows you to minimize the copying when you have arrays that don’t require a full element by element copy. If &RestrictionArray is not specified, a complete array copy is done.

The array types between the PeopleCode array and the Java array must match the standard type mapping between Java and PeopleCode types. For example, trying to copy a PeopleCode array of Any into a Java array of int will fail because the Any PeopleCode type doesn't map onto the Java int type.

None.

### Example

```Local array of any &x = CreateArrayAny();

&x.Push("First bit");
&x.Push(1);
&x.Push(%Datetime);
&x.Push(%Date);
&x.Push("Final bit");
Local array of number &selection = CreateArray(1, 3, 5);
Local JavaObject &Jarray = CreateJavaArray("java.lang.Object[]", &x.Len);
/* Full copy to a Java array */
CopyToJavaArray(&x, &Jarray);
/* Full copy from Java array to PeopleCode array */
Local array of any &y = CreateArrayAny();
&y [5] = Null; /* make sure it's the right length */
CopyFromJavaArray(&Jarray, &y);
```

## CopyRow

### Syntax

`CopyRow(destination_row, source_row)`

### Description

Use the CopyRow function to copy data from one row to another row.

Note: This function remains for backward compatibility only. Use the CopyTo row class method instead.

destination_row is the row number to which you want the source _row data values copied. The two rows, and the PeopleCode function call, must all be located on the same scroll level.

### Example

This example uses CopyRow to give an inserted row the same values as the previous row:

```/*  Get the row number of the inserted row and the previous row */
&NEW_ROW_NUM = CurrentRowNumber();
&LAST_ROW_NUM = &NEW_ROW_NUM - 1;
/*  Copy the data from the previous row into the inserted row */
CopyRow(&NEW_ROW_NUM, &LAST_ROW_NUM);```

## CopyToJavaArray

### Syntax

`CopyToJavaArray(&PeopleCodeArray, JavaArray [, &RestrictionArray])`

### Description

Use the CopyToJavaArray function to copy the one-dimensional array specified by &PeopleCodeArray into the Java array JavaArray. The Java array must be at least as large as the PeopleCode array.

The optional &RestrictionArray parameter is a PeopleCode array that contains the index elements of the elements to copy. For example if &RestrictionArray contains the indexes 3, 5 and 7, only elements 3, 5 and 7 in the PeopleCode array are copied to the Java array, and they are copied to the elements 3, 5 and 7. This allows you to minimize the copying when you have arrays that don’t require a full element by element copy. If &RestrictionArray is not specified, a complete array copy is done.

The array types between the PeopleCode array and the Java array must match the standard type mapping between Java and PeopleCode types. For example, trying to copy a PeopleCode array of Any into a Java array of int will fail because the Any PeopleCode type doesn't map onto the Java int type.

None.

### Example

The following example creates an array, then shows both copying the full array, as well as only copying elements of it.

```Local array of any &x = CreateArrayAny();

&x.Push("First bit");
&x.Push(1);
&x.Push(%Datetime);
&x.Push(%Date);
&x.Push("Final bit");

Local array of number &selection = CreateArray(1, 3, 5);

Local JavaObject &Jarray = CreateJavaArray("java.lang.Object[]", &x.Len);

/* Full copy to a Java array */
CopyToJavaArray(&x, &Jarray);

/* Only copy elements 1, 3 and 5 */
CopyToJavaArray(&x, &Jarray, &selection);
```

## Cos

### Syntax

`Cos(angle)`

### Description

Use the Cos function to calculate the cosine of the given angle (adjacent / hypotenuse).

### Returns

A real number between -1.00 and 1.00.

### Example

The following example returns the cosine of an angle measuring 1.2 radians:

`&MY_RESULT = Cos(1.2);`

## Cot

### Syntax

`Cot(angle)`

### Description

Use the Cot function to calculate the cotangent of the given angle (adjacent / opposite, that is, the reciprocal of the tangent).

### Parameters

Note: In theory, all values of angle such that mod(angle, pi) equals 0 are not valid for this function, because inputs approaching such values produce results that tend toward infinity. In practice, however, no computer system can represent such values exactly. Thus, for example, the statement Cot(Radians(180)) produces a number close to the largest value PeopleCode can represent, rather than an error.

A real number.

### Example

The following example returns the cotangent of an angle measuring 1.2 radians:

`&MY_RESULT = Cot(1.2);`

## CreateAnalyticInstance

### Syntax

`CreateAnalyticInstance(AnalyticType, ID, Descr, &RecordRef, ForceDelete)`

### Description

Use the CreateAnalyticInstance function to create an analytic instance as identified by the analytic ID. If ID is an empty string, the system automatically generates a unique ID.

This function only creates the metadata for the ID. It doesn't load the instance into an analytic server.

If this analytic instance already exists in the system, and you specify ForceDelete as false, the analytic instance is not created. If you specify ForceDelete as true, the existing analytic instance is deleted and the new one is created.

Every analytic type definition is defined with an application package that contains three methods: Create, Delete, and Copy. The values in &RecordRef are passed to the Create method.

### Returns

An AnalyticInstance object if successful, null otherwise.

### Example

```Local AnalyticInstance &pi;

/* Create a brand new analytic instance */
&pi = CreateAnalyticInstance("BusinessPlanning", "Test", "PopulateTables", &argrec, True);
```

## CreateArray

### Syntax

`CreateArray(paramlist)`

Where paramlist is an arbitrary-length list of values in the form:

`param1 [, param2] ...`

### Description

Use the CreateArray function to construct an array and returns a reference to it.

The type of the first parameter determines the type of array that is built. That is, if the first parameter is of type NUMBER, an array of number is built. If there is no first parameter an empty array of ANY is built.

The CreateArray function uses flattening and promotion as required to convert subsequent values into suitable elements of the array.

### Returns

Returns a reference to the array.

### Example

```Local Array of Array of Number &AAN;
Local Array of Number &AN;

&AAN = CreateArray(CreateArray(1, 2), CreateArray(3, 4), 5);
&AN = CreateArray(6, &AAN[1]);```

&AAN is a two dimensional array with three elements:

• A one-dimensional array with 1 and 2 as elements.

• A one-dimensional array with 3 and 4.

• A one-dimensional array with only the element 5.

The last parameter to Array was promoted to a one-dimensional array. &AN is a one-dimensional array with 3 elements: 6, 1, and 2. The last parameter to Array in the last line was flattened into its two elements.

## CreateArrayAny

### Syntax

`CreateArrayAny([paramlist])`

Where paramlist is an arbitrary-length list of values in the form:

`param1 [, param2] ...`

### Description

Use the CreateArrayAny function to construct an array whose elements are of data type ANY and returns a reference to it.

The CreateArrayAny function uses flattening and promotion as required to convert subsequent values into suitable elements of the array.

If you do not specify any parameters with CreateArrayAny, it's the same as using the CreateArray function without any parameters.

If you do not know how many values are needed in a SQL statement until runtime, you can use an array of any to supply the values.

### Returns

Returns a reference to an array of ANY.

### Example

`local Array of Any &ArrayAny = CreateArrayAny(1, 2, "hi", "there");`
`local Array of Array of Any &AAAny = CreateArray(CreateArrayAny(1, 2), CreateArrayAny("hi"), "there");`

&ArrayAny is a two dimensional array with four elements: 1, 2, "hi" and "there". All the elements have the data type Any.

&AAAny is a two-dimensional array with three elements: a one-dimensional array with 1 and 2 as elements, a one-dimensional array with "hi" as its element, and a one-dimensional array with only the element "there". The last parameter to the array was promoted to a one-dimensional array.

## CreateArrayRept

### Syntax

`CreateArrayRept(val, count)`

### Description

Use the CreateArrayRept function to create an array that contains count copies of val. If val is itself an array, the created array has one higher dimension, and each element (sub-array) is the array reference val.

The type of the first parameter (val) determines the type of array that is built. That is, if the first parameter is of type NUMBER, an array of number is built. If count is zero, CreateArrayRept creates an empty array, using the val parameter for the type.

If you are making an array that is multi-dimensional, val will be the subarray used as the elements.

To make the subarrays distinct, use the Clone method. For example:

`&A = CreateArrayRept(&AN, 4).Clone();`

### Returns

Returns a reference to the array.

### Example

The following code sets &A to a new empty array of string:

`&A = CreateArrayRept("", 0);`

The following code sets &A to a new array of ten zeroes:

`&A = CreateArrayRept(0, 10);`

The following code sets &AAS to a new array of array of strings, with two subarrays:

`&AAS = CreateArrayRept(CreateArray("one", "two"), 2);`

Note that in this case, both elements (rows) of &AAS contain the same subarray, and changing the value of an element in one of them changes it in both of them. To get distinct subarrays, use the Clone method:

`&AAS = CreateArrayRept(CreateArray("one", "two"), 2).Clone();`

The following example shows how to create a two-dimension array using CreateArrayRept and Push. In addition, it shows how to randomly assigns values to the cells in a two-dimension array.

```Local array of array of string &ValueArray;

&Dim1 = 10;
&Dim2 = 5;
&ValueArray = CreateArrayRept(CreateArrayRept("", 0), 0);
For &I = 1 To &Dim1
&ValueArray.Push(CreateArrayRept("", &Dim2));
End-For;
&ValueArray[1][1] = "V11";
&ValueArray[2][1] = "V21";

WinMessage("&ValueArray[1][1] = " | &ValueArray[1][1] | " " | "&ValueArray[2][1] = " | &ValueArray[2][1], 0);```

## CreateDirectory

### Syntax

`CreateDirectory(path, [, pathtype])`

### Description

Use the CreateDirectory function to create the directory specified by path and any non-existent directories specified in path.

On UNIX systems, the directory has the mode 755, that is, read-write-execute permission for the owner, while group and other have only read and execute permission.

`drwxr-xr-x`

None.

### Example

`CreateDirectory("D:\Resumes\New_Hires", %FilePath_Absolute);`

## CreateDocument

### Syntax

`CreateDocument(DocumentKey | Package, DocumentName, Version)`

### Description

Use this method to instantiate a new Document object.

### Returns

A Document object.

### Example

The following provides two examples of instantiating a Document object. Both result in the same object.

Example 1:

```Local Document &Doc;

/* Instatiate the Document object */
```

Example 2:

```Local Document &Doc;
Local DocumentKey &DocKey;

/* Instatiate the Document object */
&Doc = CreateDocument(&DocKey);```

## CreateDocumentKey

### Syntax

`CreateDocumentKey(Package, DocumentName, Version)`

### Description

Use this method to instantiate a new DocumentKey object.

### Returns

A DocumentKey object.

### Example

The following provides an example of instantiating a Document object from a document key:

```Local Document &Doc;
Local DocumentKey &DocKey;

/* Populating Document Object */
&Doc = CreateDocument(&DocKey);```

## CreateException

### Syntax

`CreateException(message_set, message_num, default_txt [, subslist])`

where subslist is an arbitrary-length list of substitutions of undetermined (Any) data type to be substituted in the resulting text string, in the form:

`substitution1 [, substitution2]. . .`

### Description

Use the CreateException function to create an exception object with the given properties. You can use this in your exception handling. Use this function either in conjunction with the throw statement, or on its own to get more information of a message.

### Returns

A reference to an exception object if successful, Null otherwise.

### Example

```Function t2
throw CreateException(2, 160, "'%1' doesn't support property or method '%2'", "SomeClass", "SomeMethod");
End-Function;```

## CreateJavaArray

### Syntax

`CreateJavaArray(ElementClassName[], NumberOfElements)`

### Description

Use the CreateJavaArray function to create a Java array without knowing the number or value of the elements.

When you create an array in Java, you already know the number of elements in the array. If you do not know the number of elements in the array, but you want to use a Java array, use the CreateJavaArray function in PeopleCode. This creates a Java object that is a Java array, and you can pass in the number of elements that are to be in the array.

The first index in a Java array is 0. PeopleCode arrays start at 1.

Do the following to specify this type of array in Java:

`new ElementClassName[NumberOfElements];`

A Java object

## CreateJavaObject

### Syntax

`CreateJavaObject(ClassName [ConstructorParams])`

Where ConstructorParams has the form

`argument1 [, argument2] . . . `

### Description

Use the CreateJavaObject function to create a Java object that can be manipulated in PeopleCode.

Note: If you create a class that you want to call using GetJavaClass, it can be located in a directory specified in the PS_CLASSPATH environment variable or in other specified locations. The PeopleCode API Reference provides details on where you can place custom and third-party Java classes.

Use the CreateJavaObject function to create a Java array when you know how many values it should contain. If ClassName is the name of an array class (ending with [ ]), ConstructorParams are used to initialize the array.

In Java, do the following to initialize an array:

`intArray = new int[]{1, 2, 3, 5, 8, 13};`

Do the following to initialize such a Java array from PeopleCode:

`&IntArray = CreateJavaObject("int[]", 1, 2, 3, 5, 8, 13);`

To initialize a Java array without knowing the number of parameters until runtime, use the CreateJavaArray function.

A Java object.

### Example

The following is an example of using dot notation and CreateJavaObject.

`&CHARACTER.Value = CreateJavaObject(&java_path).GetField(&java_newchar).Value;`
`&NUMBER.Value = CreateJavaObject(&java_path).GetField(&java_newnum).Value;`
`&DATE.Value = CreateJavaObject(&java_path).GetField(&java_newdate).Value;      `

## CreateMCFIMInfo

### Syntax

`CreateMCFIMInfo(UserID, Network)`

### Description

Use the CreateMCFIMInfo function to create an instance of the MCFIMInfo class. This is used to initiate the instant messaging session.

### Returns

An MCFIMInfo object if successful, a null value otherwise.

## CreateMessage

### Syntax

`CreateMessage(OPERATION.messagename [, message_type])`

### Description

Use the CreateMessage function to instantiate a message object that refers to a message definition associated with a service operation. The CreateMessage function sets the following properties for the resulting message object, based on the values set for the message definition:

• Name

• QueueName

• Active

Other properties are set when the message is published or subscribed to (TransactionID and so on,) or are dynamically generated at other times (Size, EditError, and so on.)

For rowset-based messages, CreateMessage also sets the LANGUAGE_CD field in the level 0 PSCAMA record for a message based on the USERID default language group. If the message is being published from a component, the language code is set to the USERID language code for the component. If CreateMessage is called from a PeopleSoft Application Engine program, the language code of the user who started the batch process is used.

### Parameters

Value

Description

%IntBroker_Request

A request message. This is the default.

%IntBroker_Response

A response message.

%IntBroker_Fault

A fault message.

### Returns

Returns a reference to a message object.

### Example

The following example creates a request message &MSG assocaited with the service operation PURCHASE_ORDER.

```Local message &MSG;

&MSG = CreateMessage(OPERATION.PURCHASE_ORDER);```

## CreateObject

### Syntax

`CreateObject(str_class_name, create_par,  ...)`

Where str_class_name either:

—identifies a class by class name

—identifies a class of OLE Automation object in the form:

`app_name.object_name`

### Description

Use the CreateObject function to return an instance of a class. You can use this function to access an Application Class, a PeopleCode built-in object (like a chart), or an OLE Automation object.

If the class you are creating requires values to be passed, use the create_par parameters to supply them, or use the CreateObjectArray function.

#### Considerations Using Application Classes

You can use the CreateObject function to access an Application Class. You would want to do this when you were programming at a high-level, when you might not know the name of the class you wanted to access until runtime. You must specify a fully-qualified class name. In addition, the class name is case-sensitive.

The returned object has the type of class you specified.

#### Considerations Using PeopleCode Built-in Objects

For example, to generate a PeopleSoft chart object without using a chart control (that is, without using the GetChart function) you could use:

`&MyChart = CreateObject("Chart");`

The returned object has the type of class you specified.

Note: The only way to instantiate a crypt object is using the CreateObject function.

#### Considerations Using OLE Automation Objects

CreateObject returns an instance of an OLE Automation object as a variable of type Object.

The str_class_name argument uses the syntax app_name.object_type, which consists of: app_name (the name of the application providing the object) and object_type (the class or type of the object to create), separated by a period (dot).

Any application that supports OLE Automation exposes at least one type of object. For example, a spreadsheet application may provide an application object, a worksheet object, and a toolbar object.

To create an OLE Automation object, you assign the object returned by CreateObject to a variable of type Object:

```local object &WORKSHEET;

&WORKSHEET = CreateObject("Excel.Sheet");```

After an object is created, you can reference it using the object variable. In the previous example, you access properties and methods of the new object using the ObjectGetProperty, ObjectSetProperty, and ObjectDoMethod functions.

Note: If an object has registered itself as a single-instance object, only one instance of the object can be created, even if CreateObject is executed more than once. Note also that an object assigned to a global variable is not valid across processes: that is, the scope and lifetime of the global is the same as the scope and lifetime of the instance of PeopleTools in which the object was created.

### Example

This example instantiates an Excel worksheet object, makes it visible, names it, saves it, and displays its name. Note the use of ObjectGetProperty in the example to return the Excel.Sheet.Application object.

```&WORKAPP = CreateObject("COM", "Excel.Application");
&WORKBOOKS = ObjectGetProperty(&WORKAPP, "Workbooks");
ObjectDoMethod(&WORKBOOKS, "Add", "C:\TEMP\INVOICE.XLT"); /* This associates the INVOICE template w/the workbook */
ObjectDoMethod(&WORKAPP, "Save", "C:\TEMP\TEST1.XLS");
ObjectSetProperty(&WORKAPP, "Visible", True);```

This following example illustrates the creation of an application class object. This code assumes that MyBaseClass is the superclass of both MySubclass1 and MySubclass2 classes.

```local MyBaseClass &mbobj;
local String &ClassName = "MySubclass1";
if &test then
&ClassName = "MySubclass2";
end-if;
&mbobj = CreateObject(&ClassName);```

The following example creates a chart in an iScript, using the CreateObject function to generate a reference to a chart object.

```Function IScript_GetChartURL()

Local Chart &oChart;
Local Rowset &oRowset;
Local string &sMap;
Local string &sURL;

&oChart = CreateObject("Chart");

&oRowset = CreateRowset(Record.QE_CHART_RECORD);
&oRowset.Fill("where QE_CHART_REGION= :1", "MIDWEST");
&oChart.SetData(&oRowset);

&oChart.Width = 400;
&oChart.Height = 300;

&oChart.SetDataYAxis(QE_CHART_RECORD.QE_CHART_SALES);
&oChart.SetDataXAxis(QE_CHART_RECORD.QE_CHART_PRODUCT);
&oChart.SetDataSeries(QE_CHART_RECORD.QE_CHART_REGION);

&oChart.HasLegend = True;
&oChart.LegendPosition = %ChartLegend_Right;

&sURL = %Response.GetChartURL(&oChart);
&sMap = &oChart.ImageMap;

%Response.Write("<HTML><IMG SRC=");
%Response.Write(&sURL);
%Response.Write("  USEMAP=#THEMAP></IMG><MAP NAME=THEMAP>");
%Response.Write(&sMap);
%Response.Write("</MAP></HTML>");

End-Function;```

## CreateObjectArray

### Syntax

`CreateObjectArray(Class_Name, Array_of_Args)`

### Description

Use the CreateObjectArray function to return an instance of a class.

Use this function when you must pass in parameters to create the object and you don’t know when you write the code how many parameters are required. If you can create the object without passing in additional values, or if you know how many parameters are required, use the CreateObject function instead.

The array of parameters is an array of Any. It must be a one-dimensional array, that is, you cannot pass in an array of array of Any. You cannot pass in field references, that is, you cannot pass in references of the form:

`RECORD.FIELDNAME`

If you do not want to supply any parameters, you can use an empty array, or a reference to a Null array.

### Returns

A reference to newly created object.

### Example

The following is an example of the creation of an Application Class object where the number of parameters used to create the object varies, depending on data in the database.

```local String &ClassName, &RecName;
local Record &Rec;

/* Read class name and parameter record name from the database. */
SQLExec("SELECT CLASSNAME, RECNAME FROM %TABLE(RECORD.CLASSDATA)", &ClassName, &RecName);

local Record &Rec = CreateRecord(@ ("RECORD." | &RecName));

/* Read the parameters from the database. */
local Array of Any &Params = CreateArrayAny();

SQLExec("%SelectAll(:1)", &Rec, &Params);

/* Create the object. */
local MyPackage:BaseClass &Obj = CreateObjectArray(&ClassName, &Params);```

## CreateProcessRequest

### Syntax

`CreateProcessRequest([ProcessType, ProcessName])`

### Description

Use the CreateProcessRequest function to create a ProcessRequest object. After you’ve created this object, you can assign values to its properties then use the Schedule method to submit the process request for scheduling.

If you specify PSJob for the process type, the ProcessRequest object contains all the items of the job.

### Returns

A reference to a ProcessRequest object.

### Example

```Local ProcessRequest &MYRQST;

&MYRQST = CreateProcessRequest("PSJOB", &MyJobName);```

## CreateRecord

### Syntax

`CreateRecord(RECORD.recname)`

### Description

Use the CreateRecord function to create a standalone record definition and its component set of field objects. The specified record must have been defined previously, that is, it must have a record definition. However, if you are calling this function from PeopleCode associated with a page, the record does not have to be included on the current page.

The record and field objects created by this function are accessible only within PeopleCode. They can be used with any of the record and field object methods and properties. The record and field objects are automatically deleted when there are no remaining references to them stored in any variables.

The fields created by this function are initialized to null values. Default processing is not performed. No data associated with the record definition’s SQL table is brought in: only the record definition.

You can select into a record object created this way using the SelectByKey record class method. You can also select into it using the SQLExec function.

### Returns

This function returns a record object that references a new record buffer and set of fields.

### Example

```Local Record &REC2;

&REC2 = CreateRecord(RECORD.OPC_METH);```

In the following example, a free-standing record is created (&PSBATREPREQRES). Values are assigned to the fields associated with the record. Then a second record is created (&PUBHDR), and the values from the first record are used to populate the second record.

```&PSBATREPREQRES = CreateRecord(RECORD.PSBATREPREQRES);
&PSBATREPREQRES.BATREPID.Value = &BATREPID;
&PSBATREPREQRES.PUBID.Value = &MSG.Pubid;
&PSBATREPREQRES.CHNLNAME.Value = &MSG.ChannelName;
&PSBATREPREQRES.PUBNODE.Value = &MSG.PubNodeName;
&PSBATREPREQRES.MSGNAME.Value = &MSG.Name;

&PUBHDR = CreateRecord(RECORD.PSAPMSGPUBHDR);
&PSBATREPREQRES.CopyFieldsTo(&PUBHDR);```

To create a PeopleCode record object for a record whose name is unknown when the PeopleCode is written, do the following.

Suppose a record name is in the PeopleCode variable &RECNAME. Use the @ operator to convert the string to a component name. The following code creates a corresponding record object:

```&RECNAME = "RECORD." | Upper(&RECNAME);
&REC = CreateRecord(@ &RECNAME);```

The following example uses SQLExec to select into a record object, based on the effective date.

```Local Record &DST;

&DST = CreateRecord(RECORD.DST_CODE_TBL);
&DST.SETID.Value = GetSetId(FIELD.BUSINESS_UNIT, DRAFT_BU, RECORD.DST_CODE_TYPE, "");
&DST.DST_ID.Value = DST_ID_AR;
SQLExec("%SelectByKeyEffDt(:1,:2)", &DST, %Date, &DST);
/* do further processing using record methods and properties */```

## CreateRowset

### Syntax

`CreateRowset({RECORD.recname | &Rowset} [, {FIELD.fieldname, RECORD.recname | &Rowset}] .  .  .)`

### Description

Use the CreateRowset function to create an unpopulated, standalone rowset.

A standalone rowset is a rowset that has the specified structure, but is not tied to any data (that is, to the component buffer or to a message.) In addition, a standalone rowset isn’t tied to the Component Processor. When you fill it with data, no PeopleCode runs (like RowInsert, FieldDefault, and so on.)

The first parameter determines the structure of the rowset to be created.

If you specify a record as the first parameter, it’s used as the primary level 0 record. If you don’t specify any other parameters, you create a rowset containing one row, with one unpopulated record. To populate this type of rowset with data, you should only use:

• the Fill or FillAppend rowset class methods

• a record method (SelectByKey)

• the SQLExec function

If you specify a rowset object, you are creating a new rowset based on the structure of the specified rowset object, including any child rowsets. It will not contain any data. If you want to populate this type of rowset with data, use the CopyTo method or a SQL statement.

Note: You should not use the rowset Select or SelectNew methods for populating rowsets created using CreateRowset. Use Fill or FillAppend instead.

#### Restrictions on Using CreateRowset

The following methods and properties don’t work with a rowset created using CreateRowset:

• Select

• SelectNew

• Any GUI methods (like HideAllRows)

• Any effective date methods or properties (like EffDt, EffSeq, or GetCurrEffRow)

In addition, rowsets created using CreateRowset are not automatically tied to the database. This means if you insert or delete rows, the rows will not be inserted or deleted in the database when you save the page.

### Returns

An unpopulated, standalone rowset object.

### Example

The following creates a simple rowset of just a single record per row:

`&RS = CreateRowset(RECORD.QA_MYRECORD);`

The following creates a rowset with the same structure as the specified rowset:

`&RS2 = CreateRowset(&RS);`

The following code creates a rowset structure composed of four records in an hierarchical structure, that is,

```QA_INVEST_HDR
QA_INVEST_LN
QA_INVEST_TRANS
QA_INVEST_DTL```

Note that you have to start at the bottom of the hierarchy, and add the upper levels, not the other way around.

```Local Rowset &RS, &RS2, &RS_FINAL;

&RS2 = CreateRowset(RECORD.QA_INVEST_DTL);
&RS = CreateRowset(RECORD.QA_INVEST_TRANS, &RS2);
&RS2 = CreateRowset(RECORD.QA_INVEST_LN, &RS);
&RS_FINAL = CreateRowset(RECORD.QA_INVEST_HDR, &RS2);```

The following example reads all of the QA_MYRECORD records into a rowset, and returns the number of rows read:

```&RS = CreateRowset(RECORD.QA_MYRECORD);

To make a clone of an existing rowset, that is, to make two distinct copies, you can do the following:

```&RS2 = CreateRowset(&RS);
&RS.CopyTo(&RS2);```

The following code example is used for creating multiple children in a standalone rowset:

```Local Rowset &rsBOCMRole, &rsBOCMRel, &rsBOCMUse;

&rsBOCMRole = CreateRowset(Record.BO_CM_ROLE);
&rsBOCMRel = CreateRowset(Record.BO_CM_REL);
&rsBOCMUse = CreateRowset(Record.BO_CM_USE);
&rsBOCM = CreateRowset(Record.BO_CM, &rsBOCMUse, &rsBOCMRole, &rsBOCMRel);```

## CreateRowsetCache

### Syntax

`CreateRowsetCache(&Rowset, [Rowset.]Name, Description)`

### Description

Use the CreateRowsetCache function to create a new RowsetCache object with the given name if it doesn't already exist.

### Returns

A reference to the new RowsetCache object if there is not already a RowsetCache object of the given name.

### Example

```Local RowsetCache &Cache;
Local Rowset &RS;

&RS = CreateRowset(Record.PSLANGUAGES);

&Cache = CreateRowsetCache(&RS, "AAROWSET1", "ROWSET_AAROWSET1");
```

## CreateSOAPDoc

### Syntax

`CreateSOAPDoc()`

### Description

Use the CreateSOAPDoc function to create an empty SOAPDoc object. Then use the SOAPDoc class methods and properties, as well as the XmlDoc class methods and properties to populate the SOAPDoc object.

None.

### Returns

A reference to a SOAPDoc object.

### Example

`Local SOAPDoc &MyDoc;`
`&MyDoc = CreateSOAPDoc();`

## CreateSQL

### Syntax

`CreateSQL([{sqlstring | SQL.SqlName}[, paramlist]])`

Where paramlist is an arbitrary-length list of values in the form:

`inval1 [, inval2] ...`

### Description

Use the CreateSQL function to instantiate a SQL object from the SQL class and opens it on the given sqlstring and input values. sqlstring is a PeopleCode string value giving the SQL statement.

Any errors in the SQL processing cause the PeopleCode program to be terminated with an error message.

You can use CreateSQL with no parameters to create an empty SQL object that can be used to assign properties before being populated and executed.

#### Opening and Processing sqlstring

If sqlstring is a SELECT statement, it is immediately bound with the inval input values and executed. The SQL object should subsequently be the subject of a series of Fetch method calls to retrieve the selected rows. If you want to fetch only a single row, use the SQLExec function instead. If you want to fetch a single row into a PeopleCode record object, use the record Select method.

If sqlstring is not a SELECT statement, and either there are some inval parameters, or there are no bind placeholders in the SQL statement, the statement is immediately bound and executed. This means that there is nothing further to be done with the SQL statement and the IsOpen property of the returned SQL object will be False. In this case, using the SQLExec function would generally be better. If you want to delete, insert or update a record object, use the record Delete, Insert, or Update methods.

If sqlstring is not a SELECT statement, there are no inval parameters, and there are bind placeholders in the SQL statement, the statement is neither bound nor executed. The resulting SQL object should subsequently be the subject of a series of Execute method calls to affect the desired rows.

#### Using Arrays with paramlist

You can use a parameter of type "Array of Any" in place of a list of bind values or in place of a list of fetch result variables. This is particularly useful when fetching an unknown number of results.

```&Sql1 = CreateSql("Select * from " | &TableName);
&AAny = CreateArrayAny();

While &Sql1.Fetch(&AAny)
/* Process the row in &AAny. */
...
End-While;```

Because the Array of Any promotes to absorb any remaining select columns, it must be the last parameter for the SQL object Fetch method or (for results) SQLExec. For binding, it must be the only bind parameter, as it is expected to supply all the bind values needed.

None.

### Example

This SQL object should be used in a series of Fetch method calls:

```Local SQL &SQL;

&SQL = CreateSQL("%SelectAll(:1) where EMPLID = :2", RECORD.ABSENCE_HIST, &EMPLID);```

This SQL object has been opened, bound, and is already closed again:

`&SQL = CreateSQL("Delete from %Table(:1) where EMPLID = :2", RECORD.ABSENCE_HIST, &EMPLID);`

This SQL object should be used in a series of Execute method calls:

`&SQL = CreateSQL("Delete from %Table(:1) where EMPLID = :2"); `

This SQL object is created as an empty object in order to set properties before being executed:

```&Sql = CreateSQL();
&Sql.Tracename = "SQL1";
&Sql.ReuseCursor = True;
&Sql.Open(......); /* do the deed */```

## CreateWSDLMessage

### Syntax

`CreateWSDLMessage(MessageName, ChannelName)`

### Description

Use the CreateWSDLMessage function to create an unstructured message. This function creates both the message as well as the channel.

This function has been deprecated. It is no longer supported.

## CreateXmlDoc

### Syntax

`CreateXmlDoc(XmlString, DTDValidation)`

### Description

Use the CreateXmlDoc function to create an XmlDoc object. If you specify a Null string for XmlString (""), you create an empty XmlDoc object.

#### Considerations Using CreateXmlDoc

The following coding is either ignored or removed from the XmlDoc object that is created with this function:

• encoding attributes

PeopleSoft only supports UTF-8 encoding. Any specified encoding statement is removed, as all XmlDoc objects are considered UTF-8.

• version attributes

Regardless of what version is specified in XmlString, the version attribute in the generated XmlDoc object is 1.0.

### Returns

A reference to the newly created XmlDoc object.

### Example

The following creates an empty XmlDoc object.

`Local XmlDoc &MyDoc;`
`&MyDoc = CreateXmlDoc("");`

## CropImage

### Syntax

`CropImage(src_recfield, dst_recfield, [width, height])`

### Description

Use the CropImage function to crop a source image existing in a database record field and save it to a different destination record field in the database. The source and destination fields must be defined with the same image format: BMP, GIF, or, JPG only.

The image cropping can be constrained to a specific aspect ratio by specifying the optional [width and height parameters. These parameters define the aspect ratio only, and do not constrain the cropping to a specific size. If the aspect ratio is not specified, then the user will be unconstrained when cropping the image.

An error occurs and CropImage returns False when:

• The source or destination field does not exist in the component buffer.

• The source or destination field is not of type image

• The image type of the destination field differs from that of the source field.

• The destination image field is the same as the source image field.

#### Restrictions on Use in PeopleCode Events

CropImage is a “think-time” function, which means it shouldn’t be used in any of the following PeopleCode events:

• SavePreChange

• SavePostChange

• Workflow

• RowSelect

• Any PeopleCode event that fires as a result of a ScrollSelect (or one of its relatives) function calls, or a Select (or one of its relatives) Rowset class method.

### Returns

A Boolean value: True when successful, False otherwise.

### Example

`&bRet = CropImage(QE_IMAGE.QE_IMAGE, QE_IMAGE_CROP.QE_CROP_IMAGE, 60, 90);`

## CubicSpline

### Syntax

`CubicSpline(DataPoints, Control_Option, Left_Constraint, Right_Constraint)`

### Description

Use the CubicSpline function to compute a cubic spline interpolation through a set of at least four datapoints.

### Parameters

Numeric Value

Constant Value

Description

0

%SplineOpt_SlEstEst

Generate an internal estimate of the beginning and ending slope of the cubic piecewise equations

1

%SplineOpt_SlSetEst

Use the user-specified value for the slope of the leftmost point, and generate an estimate for the rightmost point

2

%SplineOpt_SlEstSet

Use the user-specified value for the slope of the rightmost point, and generate an estimate for the leftmost point

3

%SplineOpt_SlSetSet

Use the user-specified values for the slopes of the leftmost and rightmost points

4

%SplineOpt_CvEstEst

Generate an internal estimate of the beginning and ending curvature of the cubic piecewise equations

5

%SplineOpt_CvSetEst

Use the user-specified value for the curvature of the leftmost point, and generate an estimate for the rightmost point

6

%SplineOpt_CvEstSet

Use the user-specified value for the curvature of the rightmost point, and generate an estimate for the leftmost point

7

%SplineOpt_CvSetSet

Use the user-specified values for the curvatures of the leftmost and rightmost points

8

%SplineOpt_ClEstEst

Generate an internal estimate of the beginning and ending curl of the cubic piecewise equations

9

%SplineOpt_ClSetEst

Use the user-specified value for the curl of the leftmost point, and generate an estimate for the rightmost point

10

%SplineOpt_ClEstSet

Use the user-specified value for the curl of the rightmost point, and generate an estimate for the leftmost point

11

%SplineOpt_ClSetSet

Use the user-specified values for the curls of the leftmost and rightmost points

12

%SplineOpt_Natural

Generate a “natural” spline

13

%SplineOpt_ContCurl

Generate a spline wherein the equation for the first segment is the exact same equation for the second segment, and where the equation for the penultimate segment is the same as the equation for the last segment.

### Returns

A modified array of array of numbers. The elements in the array correspond to the elements in the array used for DataPoints.

## CurrEffDt

### Syntax

`CurrEffDt([level_num])`

### Description

Use the CurrEffDt function to return the effective date of the specified scroll level as a Date value.

Note: This function remains for backward compatibility only. Use the EffDt rowset class property instead.

If no level is specified, CurrEffDt returns the effective date of the current scroll level.

### Returns

Returns a Date value equal to the current effective date of the specified scroll level.

### Example

```If INSTALLATION.POSITION_MGMT = "P" Then
If All(POSITION_NBR) Then
If (EFFDT = CurrEffDt(1) and
EFFSEQ >= CurrEffSeq(1)) or
(EFFDT > CurrEffDt(1) and
EFFDT = %Date) Then
Gray_employment( );
End-if;
End-if;
End-if;```

## CurrEffRowNum

### Syntax

`CurrEffRowNum([level_num])`

### Description

Use the CurrEffRowNum function to return the effective row number of the selected scroll level.

Note: This function remains for backward compatibility only. Use the RowNumber row class property, in combination with the GetCurrEffRow rowset method, instead.

If no level is specified, it returns the effective row number of the current level.

### Example

`&ROW = CurrEffRowNum(1);`

## CurrEffSeq

### Syntax

`CurrEffSeq([level_num])`

### Description

Use the CurrEffSeq function to determine the effective sequence of a specific scroll area.

Note: This function remains for backward compatibility only. Use the EffSeq rowset class property instead.

If no level is specified, CurrEffSeq returns the effective sequence of the current scroll level.

### Returns

Returns a Number representing the effective sequence of the specified scroll level.

### Example

```If INSTALLATION.POSITION_MGMT = "P" Then
If All(POSITION_NBR) Then
If (EFFDT = CurrEffDt(1) and
EFFSEQ >= CurrEffSeq(1)) or
(EFFDT > CurrEffDt(1) and
EFFDT = %Date) Then
Gray_employment( );
End-if;
End-if;
End-if;```

## CurrentLevelNumber

### Syntax

`CurrentLevelNumber()`

### Description

Use the CurrentLevelNumber function to return the scroll level where the function call is located.

### Returns

Returns a Number value equal to the scroll level where the function is being called. The function returns 0 if the field where the function is called is not in a scroll area.

### Example

`&LEVEL = CurrentLevelNumber();`

## CurrentRowNumber

### Syntax

`CurrentRowNumber([level])`

### Description

Use the CurrentRowNumber function to determine the row number of the row currently displayed in a specific scroll area.

Note: This function remains for backward compatibility only. Use the RowNumber row class property instead.

This function can determine the current row number on the level where the function call resides, or on a higher scroll level. It won’t work on a scroll level below the one where the PeopleCode program resides.

### Returns

Returns a Number value equal to the current row number on the specified scroll level. The current number is the row where the PeopleCode program is being processed, or, if level specifies a higher level scroll, CurrentRowNumber returns the row number of the parent or grandparent row.

### Example

CurrentRowNumber is typically used in component buffer functions to return the current row of the parent scroll of the target:

`&VAL = FetchValue(RECORD.BUS_EXPENSE_PER, CurrentRowNumber(), BUS_EXPENSE_DTL.CHARGE_DT, &COUNT);`

The following example checks if the current row number is equal to the active row count (that is, whether the active row is the last record on the scroll):

```If CurrentRowNumber() = ActiveRowCount(EMPLID) Then
det_employment_dt();
End-if;```

## Date

### 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);`

## Date3

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

### 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);`

## DatePart

### 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);```

## DateTime6

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

### 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);`

## DateTimeToHTTP

### 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).

### 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);`

## DateTimeToISO

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

### 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");`

## DateTimeToLocalizedString

### 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

#### 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

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.

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"

"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"

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;```

## DateTimeToTimeZone

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

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

## DateTimeValue

### 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).

### 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");```

## DateValue

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

## Day

### 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);`

## Days

### 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));`

## Days360

### 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);`

## Days365

### 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);`

## DBCSTrim

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

## DBPatternMatch

### 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 "%").

### Returns

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

## DeChunkText

### 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

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

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);
```

## Declare Function

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

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

### Parameters

The following are the parameters for the PeopleCode function syntax:

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:

### 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;
```

## Decrypt

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

### Returns

A clear text string.

### Example

Encrypt and Decrypt support only strings.

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

## Degrees

### Syntax

`Degrees(angle)`

### Description

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

### 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);`

## DeleteAttachment

### 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 8.53: PeopleCode Developer's Guide PeopleBook:

• PeopleTools supports multiple types of storage locations.

• Certain characters are illegal in file names; other characters in file names are converted during file transfer.

• Non-ASCII file names are supported by the PeopleCode file attachment functions.

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

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

Unable to login to destination system for FTP.

The following are some possible situations where %Attachment_DestSysFailedLogin could be returned:

• Unsupported protocol specified.

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

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:

• 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:

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

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

Value

Description

BB

BUS

HOME

OTH

WORK

None.

## DeleteImage

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

### Returns

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

### Example

`&Rslt = DeleteImage(EMPL_PHOTO.EMPLOYEE_PHOTO);`

## DeleteRecord

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

### 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;```

## DeleteRow

### 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).

### 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; ```

## DeleteSQL

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

### 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
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));`

## DeleteSystemPauseTimes

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

This function is used in the PeopleCode for the Message Monitor. Pause times are set up in the Message Monitor.

Value

Description

0

Sunday

1

Monday

2

Tuesday

3

Wednesday

4

Thursday

5

Friday

6

Saturday

Value

Description

0

Sunday

1

Monday

2

Tuesday

3

Wednesday

4

Thursday

5

Friday

6

Saturday

### 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;```

## DeQueue

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