PeopleCode Built-in Functions and Language Constructs: S

The PeopleCode built-In functions and language constructs beginning with the letter S are listed in alphabetical order within this topic.

Syntax

SamRefreshView(matview_name, override_complete_refresh)

Description

Use the SamRefreshView function to refresh a materialized view based on its properties, such as Refresh Status, Refresh Mode, and Refresh Method.

  • If refresh status is set to 1 and refresh mode is set to ON DEMAND, then it will be a first refresh or complete refresh based on the refresh method property of the view.

  • If refresh status is set to 2 and the override_complete_refresh parameter is set to true, the materialized view is refreshed. If the override_complete_refresh parameter is set to false, the materialized view is not refreshed.

  • In all other cases, a complete refresh is performed if the override_complete_refresh parameter is set to true. If set to false, a complete refresh is not performed on the materialized view.

Note: On the MSS platform, the SamRefreshView function refreshes the summary table or indexed view. On the DB2 platform, the function refreshes the materialized query table (MQT).

Parameters

Field or Control

Definition
matview_name

Specifies the materialized view to be refreshed.
override_complete_refresh

Default value is true, that is, a complete refresh is performed.

Set it to false if you do not want a complete refresh to be performed.

Example

This example refreshes a materialized view:

/*Refresh a materialized view named MATVIEW1*/
SamRefreshView(“MATVIEW1”);

/*Refresh a materialized view named MATVIEW1 but do not perform complete refresh*/
SamRefreshView(“MATVIEW1”, false);

Syntax

ScheduleProcess(process_type, process_name [, run_location] [, run_cntl_id] [, process_instance]   [, run_dttm] [, recurrence_name] [, server_name])

Description

Use the ScheduleProcess function to schedule a process or job, writing a row of data to the Process Request table (PSPRCSRQST).

Note: This function is no longer supported. Use the CreateProcessRequest function instead.

Related Links

CreateProcessRequest

Syntax

ScrollFlush(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 ScrollFlush function to remove all rows inside the target scroll area and frees its associated buffer.

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

Rows that are flushed are not deleted from the database. This function is often used to clear a work scroll before a call to ScrollSelect.

Parameters

Field or Control

Definition
scrollpath

A construction that specifies a scroll level in the component buffer.

Returns

None.

Example

The following example clears the level-one scroll then fills the level-one and level-two scrolls.

/* Throw away all rows */
ScrollFlush(RECORD.DBFIELD_VW);
/* Fill in new values */
&FIELDSEL = "where FIELDNAME like '" | FIELDNAME | "%'";
&ORDERBY = " order by FIELDNAME";
ScrollSelect(1, RECORD.DBFIELD_VW, RECORD.DBFIELD_VW, &FIELDSEL | &ORDERBY);
ScrollSelect(2, RECORD.DBFIELD_VW, RECORD.DBFIELD_LANG_VW, RECORD.DBFIELD_LANG_VW, &FIELDSEL | " and LANGUAGE_CD = :1" | &ORDERBY, DBFIELD_SRCH.LANGUAGE_CD);

Syntax

ScrollSelect(levelnum, [Record.level1_recname,  [Record.level2_recname,]] Record.target_recname, Record.sel_recname [, sqlstr [, bindvars]] [, turbo])

where bindvars is an arbitrary-length list of bind variables in the form:

bindvar1 [, bindvar2]. . .

Description

The ScrollSelect function, like the related ScrollSelect functions (ScrollSelectNew, RowScrollSelect, and RowScrollSelectNew) reads data from database tables or views into a scroll area on the active page.

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

See Select.

Using ScrollSelect

ScrollSelect automatically places child rows in the target scroll area under the correct parent row in the next highest scroll area. If it cannot match a child row to a parent row an error occurs.

ScrollSelect selects rows from a table or view and adds the rows to a scroll area of a page. Let’s call the record definition of the table or view that it selects from the select record; and let’s call the record definition normally referenced by the scroll area (as specified in the page definition) the default scroll record. The select record can be the same as the default scroll record, or it can be a different record definition that has compatible fields with the default scroll record. If you define a select record that differs from the default scroll record, you can restrict the number of fields that are loaded into the component buffers by including only the fields that you actually need.

ScrollSelect accepts a SQL string that can contain a WHERE clause restricting the number of rows selected into the scroll area. The SQL string can also contain an ORDER BY clause to sort the rows.

ScrollSelect functions generate a SQL SELECT statement at runtime, based on the fields in the select record and WHERE clause passed to them in the function call. This gives ScrollSelect functions a significant advantage over SQLExec: they enable you to change the structure of the select record without affecting the PeopleCode, unless the field affected is referred to in the WHERE clause string. This can make the application easier to maintain.

Often, ScrollSelect is used to select rows into a work scroll, which is sometimes hidden using HideScroll. A work scroll is a scroll in which the No Auto Select option is selected on the record definition in Application Designer so that PeopleTools does not automatically populate the scroll at page startup. You can right-click on the scroll or grid then select the scroll’s No Auto Select attribute check box in the record property dialog box.

Depending on how you intend the scroll to be used by the end user, you may also want to select No Auto Update to prevent database updates, and prevent row insertions or deletions in the scroll area by selecting No Row Insert or No Row Update.

To call ScrollSelect at page startup, place the function call in the RowInit event of a key field on the parent scroll record. For example, if you want to fill scroll level one, place the call to ScrollSelect in the RowInit event of a field on level zero.

Parameters

Field or Control

Definition
levelnum

Specifies the level of the scroll level to be filled (the target scroll area. The value can be 1, 2, or 3.
target_recname

Specifies a record identifying the target scroll, into which the selected rows are read. If target_recname is on scroll level 2, it must be proceeded by a Record. level1_recname. If it is on level 3, you must specify both Record. level1_recname and Record. level2_recname.

Record. sel_recname

Specifies the select record. The selname record must be defined in Application Designer and SQL created (using Build, Project) as a table or a view, unless sel_recname and target_recname are the same. The sel_recname record can contain fewer fields target_recname, although it must contain any key fields to maintain dependencies with other page records. This enables you to limit the amount of data read into the component buffers.
sqlstr

Contains a WHERE clause to restrict the rows selected from sel_recname and/or an ORDER BY clause to sort the rows. The WHERE clause can contain the PeopleSoft meta-SQL functions such as %Datein or %CurrentDateIn. It can also contain inline bind variables.
bindvars

A list of bind variables to be substituted in the WHERE clause. The same restrictions that exist for SQLExec exist for these variables.
turbo

Setting this parameter to True turns on turbo mode for ScrollSelect. This will improve the performance of ScrollSelect verbs by as much as 300%, but should be implemented with caution on existing applications.

See InsertRow.

Returns

The number of rows read (optional.) This counts only lines read into the specified scroll. It does not include any additional rows read into autoselect child scrolls of the scroll.

Example

This example uses WHERE clauses to reset the rows in two scroll areas:

&FIELD_CNT = ActiveRowCount(DBFIELD_VW.FIELDNAME);
For &I = 1 to &FIELD_CNT;
   If RecordChanged(DBFIELD_VW.FIELDNAME, &I, DBFIELD_LANG_VW.FIELDNAME, 1)    Then
      &FIELDNAME = FetchValue(DBFIELD_VW.FIELDNAME, &I);
      &RET = WinMessage("Descriptions for " | &FIELDNAME | " have been changed. Discard changes?", 289, "DBField Changed!");
      If &RET = 2 Then
         /* Cancel selected */
         Exit;
      End-if;
   End-if;
End-for;
/* Now throw away all rows */
ScrollFlush(Record.DBFIELD_VW);
/* Fill in new values */
&FIELDSEL = "where FIELDNAME like '" | FIELDNAME | "%'";
&ORDERBY = " order by FIELDNAME";
&QTY1 = ScrollSelect(1, Record.DBFIELD_VW, Record.DBFIELD_VW, &FIELDSEL | &ORDERBY);
&QTY2 = ScrollSelect(2, Record.DBFIELD_VW, Record.DBFIELD_LANG_VW, Record.DBFIELD_LANG_VW, &FIELDSEL | " and LANGUAGE_CD = :1" | &ORDERBY, DBFIELD_SRCH.LANGUAGE_CD);

Syntax

ScrollSelectNew(levelnum, [Record.level1_recname, [Record.level2_recname, ]] Record.target_recname, Record.sel_recname [, sqlstr [, bindvars]] [, turbo])

and where bindvars is an arbitrary-length list of bind variables in the form:

bindvar1 [, bindvar2]. . .

Description

The ScrollSelectNew function is similar to ScrollSelect, except that all rows read into the work scroll are marked new so they are automatically inserted into the database at Save time.

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

This capability can be used, for example, to insert new rows into the database by selecting data using a view of columns from other database tables.

Parameters

Field or Control

Definition
levelnum

Specifies the level of the scroll level to be filled (the target scroll area. The value can be 1, 2, or 3.
target_recname

Specifies a record identifying the target scroll, into which the selected rows are read. If target_recname is on scroll level 2, it must be proceeded by a Record. level1_recname. If it is on level 3, you must specify both Record. level1_recname and Record. level2_recname.

Record. sel_recname

Specifies the select record. The selname record must be defined in Application Designer and SQL created as a table or a view (using Build, Project), unless sel_recname and target_recname are the same. The sel_recname record can contain fewer fields target_recname, although it must contain any key fields to maintain dependencies with other records on the page. This enables you to limit the amount of data read into the component buffers.
sqlstr

Contains a WHERE clause to restrict the rows selected from sel_recname and/or an ORDER BY clause to sort the rows. The WHERE clause may contain the PeopleSoft SQL platform functions that are used for SQLExec processing, such as %Datein or %Substring.

bindvars

A list of bind variables to be substituted in the WHERE clause. The same restrictions that exist for SQLExec exist for these variables.
turbo

Setting this parameter to True turns on turbo mode for ScrollSelectNew. This will improve the performance of ScrollSelect verbs by as much as 300%, but should be implemented with caution on existing applications.

See InsertRow.

Returns

The number of rows read (optional.) This counts only lines read into the specified scroll. It does not include any additional rows read into autoselect child scrolls of the scroll.

Example

The following statement selects rows from DATA2 and reads them into scroll level one on the page. If the end user saves the page, these rows will be inserted into DATA1:

&QTY = ScrollSelectNew(1, Record.DATA1, Record.DATA2, "Where SETID = :1 and CUST_ID = :2", CUSTOMER.SETID, CUSTOMER.CUST_ID);

Syntax

Second(timevalue)

Description

Use the Second function to extract the seconds component of a Time value.

Parameters

Field or Control

Definition
timevalue

A Time value from which to extract seconds.

Returns

Returns a Number equal to the seconds part of timevalue.

Example

Assume that &TIMEOUT contains Time value of 16:48:21. The following would set &SECS to 21:

&SECS = Second(&TIMEOUT);

Syntax

SecureRandomGen([num][, bytes])

Description

Use the SecureRandomGen function to generate one or more cryptographically secure pseudo-random number generator (CSPRNG) values. For example, a CSPRNG value can be used as a salt to then generate a hashed (or “salted”) string, such as a hashed password.

Note: Because SecureRandomGen is based on the Java security SecureRandom function, it is more efficient to call it once to return an array of required salt values than it is to call it for each salt value required.

Parameters

Field or Control

Definition
num

Specifies the number of random numbers to generate. If this value is not specified, one random number is generated.
bytes

Specifies the size of each random number in bytes. If this value is less than 1 or not specified, the default is 16 bytes (128 bits).

Returns

An array of string.

Example

In this example, SecureRandomGen generates an array with one 16-byte value:

Local array of string &operpwsdsalt;

&operpwsdsalt = SecureRandomGen();

In this example, SecureRandomGen generates an array with four 16-byte values:

Local array of string &operpwsdsalt;

&operpwsdsalt = SecureRandomGen(4);

In this example, SecureRandomGen generates an array with four 32-byte values.

Local array of string &operpwsdsalt;

&operpwsdsalt = SecureRandomGen(4, 32);

Syntax

SendMail(flags, recipients, CCs, BCCs, subject, text, [, attachment_filenames][, attachment_titles] [, Mail_From] [, Mail_Sep] [, Content_Type] [, Reply_To] [, Sender])

Description

Important! The SendMail function has been deprecated. Use the MCFOutboundEmail class instead.

The SendMail function was formerly used to send an email message from a PeopleSoft application page.

Parameters

Field or Control

Definition
flags

An integer value. This parameter is ignored.
recipients

A string consisting of a delimiter-separated list of email addresses containing the names of the message’s primary recipients.

Note: The delimiter is specified by the Mail_Sep parameter.
CCs

A string consisting of a delimiter-separated list of email addresses that are sent copies of the message.

Note: The delimiter is specified by the Mail_Sep parameter.
BCCs

A string consisting of a delimiter-separated list of email addresses that are sent copies of the message. These recipients won’t appear on the message list.

Note: The delimiter is specified by the Mail_Sep parameter.
subject

A string containing the text that appears in the message’s Subject field.
text

The text of the message.
attachment_filenames

A string consisting of a semicolon-separated list of fully qualified file names, containing the complete path to the file and the file name itself.
attachment_titles

Another semicolon-separated list containing titles for each of the files provided in the attachment_filenames parameter. The titles appear near the attachment icons in place of the fully qualified file name.
Mail_From

A string used to populate the 'reply-to' field. If this parameter isn't specified, the sender address from application server configuration file is used.
Mail_Sep

Specify the delimiter to be used to separate one email address from another. The default value is a semicolon (;).
Content_Type

Specify the content type of the email as a string. The default value is plain text.

If you want to specify HTML, you should use the following:

Content-type: text/html; charset=utf8
Reply_To

Specify the email address that the receiver should use when replying to this email instead of the Mail_From value.

Sender

Specifies who the email is from, as a string. This may be different than the values specified for Mail_From or Reply_To parameters.

Returns

Returns a number:

Return Code

Description

0

No error

-1

No mail interface installed.

Syntax

SetAddMode(add_mode)

Description

Use the SetAddMode function to indicate that the component build occurs in add mode.

Important! Use this function within fluid applications only.

Parameters

Field or Control

Definition
add_mode

Specifies a Boolean value indicating whether the component build process should occur in add mode or not.

Returns

None.

Example

If (&nAction = 0) Then
   REM &nAction=0 for Add mode aka New mode;
   SetAddMode( True);
Else
   If (&nAction = 2) Then
      REM &nAction=2 for Keyword Search;
      PTS_SRCH.PTS_VIEWMODE.Value = "L";
      &bDoSesSearch = True;
      SetAddMode( False);
   Else
      REM &nAction=1 for Real time Search;
      SetAddMode( False);
   End-If;
End-If;

Syntax

SetAuthenticationResult(AuthResult [, UserId] [, ResultDocument] [, PasswordExpired] [, DaysLeftBeforeExpire])

Description

Use the SetAuthenticationResult function in signon PeopleCode to customize the authentication process. It enables the developer using signon PeopleCode to implement additional authentication mechanisms beyond the basic PeopleSoft ID and password authentication.

When PasswordExpired is True, it indicates the password is expired, the passwordexpired.html page is displayed during login when signon PeopleCode is enabled.

When DaysLeftBeforeExpire is greater than 0, and PasswordExpired is False, indicating that the password will expire in x days, the passwordwarning.html page is displayed during login when signon PeopleCode is enabled.

Note: If you set AuthResult to False, ResultDocument must be the text of an error message. This text is displayed on the signon screen.

Parameters

Field or Control

Definition
AuthResult

Specify whether the authentication is successful. This parameter takes a Boolean value. If True is used, the end user of the UserId specified on the Signon page is allowed access to the system.

When AuthResult is True, the customer is responsible for providing a logout to the end user. They will remain logged in until a logout command is issued from the user, or the session expires.
UserId

Specify the UserId of the user signing on. The default value is the UserId entered on the signon page. This parameter takes a string value. This is the value returned by %SignonUserId
ResultDocument

When ResultDocument is blank (""), this parameter value is ignored. Otherwise, specify a message to be displayed in the signonresultdoc.html file when AuthResult is True.

If AuthResult is False, the ResultDocument text value is displayed on the signon screen. If ResultDocument has a value, any values in PasswordExpired and DaysLeftBeforeExpire are ignored.
PasswordExpired

Specify if the user’s password has expired. The values are:

  • False (default) if the user's password hasn't expired.

  • True if the user's password has expired

If this value is specified as True, the user is allowed to log in, but is able to access only a limited portion of the system: just enough to change their expired password.
DaysLeftBeforeExpire

A numeric value indicating the number of days left before the password expires. If the value is greater than 0, a warning is displayed when Authorized is True and Expired is False.

Returns

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

Example

If updateUserProfile(%SignonUserId, %SignonUserPswd, &array_attribs) Then 
   SetAuthenticationResult(True, &SignonUserID, "", False); 
End-If;

The following example is within a function used for logging onto a system:

    If (AddToDateTime(&fmc_wsl_exp_date, 0, 0, 0, 0, 10, 0) >= %Datetime) Then
         /* WSL logon was within last x minutes, so accept WSL for PS logon */
         SetAuthenticationResult( True, Upper(&userID), "", False);
      Else
         /* WSL logonn was too long ago, so request a more recent WSL logon */
         SetAuthenticationResult( False, "getmorerecentcookie", "", False,7); /*displays the customized passwordwarning.html. */
      End-If;

In the following example, AuthResult is True and ResultDocument is set as text to be displayed in an HTML tag.

SetAuthenticationResult( True, &USERID, "Result Doc Text", False, 0);

As part of this example, specify the following in the configuration properties:

singonresultdoc_page=signonresultdoctext.html

In signonresultdoctext.html, add a meta field as follows: 

<%=resultDoc%>:

<html>
....
  <tr><td class="PSSRCHACTION" no wrap=true><%=resultDoc%></td></tr>
.....
</html>

Syntax

SetChannelStatus(ChannelName, Status)

Description

Use the SetChannelStatus to set the status of the specified channel. You could use this function to restart a channel that had been paused, or pause a running channel.

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

Related Links

SetStatus

Parameters

Field or Control

Definition
ChannelName

Specify the channel name.
Status

Specify the status you want to set the channel to. The values are:

  • 1 for Run

  • 2 for Pause

Returns

A Boolean value: True if the channel status was changed successfully. False otherwise.

Example

/* User has clicked on a channel to change its status */ 
 
If CHNL_STATUS = "1" Then 
   rem running, so pause; 
   &status = 2; 
Else 
   rem paused. So run; 
   &status = 1; 
End-If; 
 
If SetChannelStatus(AMM_CHNL_SECVW.CHNLNAME, &status) Then 
   CHNL_STATUS = String(&status); 
Else 
   MessageBox(0, MsgGetText(117, 1, ""), 117, 22, ""); 
End-If;

Syntax

SetComponentChanged()

Description

Use the SetComponentChanged function to set the changed flag for the component. This flag is used to determine if save processing is needed or not, when the user clicks Save, or save is triggered through DoSave PeopleCode. This flag is also used to determine if a save warning needs to be issued to the user when they leave the component. Using SetComponentChanged causes full save processing to occur the next time a save is triggered. This includes the SaveEdit, SavePreChange, Workflow, and SavePostChange events. This function can be used to replace a workaround of changing a field to a different value then back to force save processing.

Note: Using this function causes a save warning to be issued to the user when they try to leave the component, assuming the save warning feature is enabled, and the end user has not saved the component since the function was called.

Using SetComponentChanged does not cause unchanged data to be saved. The component processor only saves changed data to the database. If nothing in the component has been changed, nothing is saved to the database.

Most components do not need to use this function. The changed flag is automatically set when the user changes any value in the component, as well as when PeopleCode changes a database field buffer value. This function is for certain pages that have a requirement to have save processing execute even if the user has not changed a value.

After save processing has completed successfully, the flag is cleared.

Note: SetComponentChanged can be used only in events that occur after the Page activate event.

Parameters

None.

Returns

None.

Syntax

SetControlValue(Value, PageName, PageFieldName [, RowNumber] [, &Field])

Description

Use the SetControlValue function to set an override string on the current field so that it simulates an end user entering data.

When a page is refreshed after a PeopleCode program completes, each field value gets set from the buffer. However, if you use this function to specify an override string for a field, the value you specify is used instead of the value in the buffer. This value is inserted directly into the control on the page, as if the end user typed it in. The field buffer remains unchanged. All validations, FieldEdit and FieldChange PeopleCode run immediately.

This function can be used in the following scenario: Suppose you have a text field that has a menu pop-up associated with it. The end user can use a secondary page to select an item to be used for the value. From the menu PeopleCode, you can verify that the value is valid, but the field doesn’t turn red and the end user can leave the field. This could potential mean saving the page with bad data. You can use this function after the secondary page is dismissed. This causes the same edits to be run as if the end user had typed in the value.

This function doesn't work for radio button or check box controls.

Considerations With Field Verification

SetControlValue only sets the value of the field. If you specify an incorrect value, SetControlValue has an error at runtime.

For example, suppose you are setting a value like "1900-01-01" into a date field that is expecting the format 01/01/1900. If the end user entered 1900-01-01 they would get an error, so SetControlValue causes an error with this value also. You may want to use a value in the format the end user might enter. You can get this value by using the FormattedValue method on a field. For example:

&DATE_IN_EFFECT = SF_PRDN_AREA_IT.DATE_IN_EFFECT.FormattedValue; 
... 
SetControlValue(&DATE_IN_EFFECT, %Page, "DATE_IN_EFFECT", &OCCURSNUM);

The FormattedValue function converts the field value from the PeopleSoft representation to the representation the end user would see and enter.

Restrictions on Use With a Component Interface

This function is ignored (has no effect) when used by a PeopleCode program that’s been called by a Component Interface.

Parameters

Field or Control

Definition
Value

Specify an override value on the current field. This parameter takes a string value.
pagename

Specify the name of page where the field exists.
pagefieldname

Specify the page field name. This is not the name of the field. This is the name that is assigned to the field in Application Designer, on the page field properties.
RowNumber

Specify the row number of the field. The default value is 1 if this parameter isn't set.
&Field

Specify an already instantiated field object referencing the field you want to override.

Note: If you want to set an override string for a field on the level 1 scroll for a page, you do not need to specify either a row number or a field object. However, if you want to set the override string for a field on either the second or third level scroll for a page, you must specify both a row number and a field object for SetControlValue to work.

Returns

None.

Example

Declare Function item_seach PeopleCode FUNCLIB_ITEM.INV_ITEM_ID FieldFormula; 
 
&SEARCHREC = "PS_" | RECORD.MG_ITEM_OWN1_VW; 
item_seach("", SF_PRDN_AREA.BUSINESS_UNIT, "ITEM", &SEARCHREC, "", &INV_ITEM_ID, ""); 
SetControlValue(&INV_ITEM_ID);

The following example is used in the PeopleSoft Pure Internet Architecture:

Declare Function item_search PeopleCode FUNCLIB_ITEM.INV_ITEM_ID FieldFormula; 
 
Component string &ITEM_ID_SEARCH; 
 
&ITEMRECNAME = "PS_" | Record.MG_ITEM_PDO_VW; 
item_serach("", EN_PDO_WRK.BUSINESS_UNIT, "ITEM", &ITEMRECNAME, "", &INV_ITEM_ID, ""); 
If All(&INV_ITEM_ID) Then 
   Evaluate &ITEM_ID_SEARCH 
   When "F" 
      SetControlValue(&INV_ITEM_ID, Page.EN_PDO_COPY, "FROM_ITEMID") 
   When "T" SetControlValue(&INV_ITEM_ID, Page.EN_PDO_COPY, "TO_ITEMID") 
   End-Evaluate; 
End-If;

Syntax

SetCursorPos(Page.pagename, scrollpath, target_row, [recordname.]fieldname)

where scrollpath is:

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

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

Description

Use the SetCursorPos to place the focus in a specific field in the current component. To transfer to a page outside the current component, use Transfer.

Note: If you use SetCursorPos to change the focus to a field that is not on the current page, any PeopleCode associated with the Activate event for the page being transferred to runs.

You can use the SetCursorPos function in combination with an Error or Warning function in SaveEdit to place the focus on the field that caused the error or warning condition. You must call SetCursorPos before an Error statement, because Error in SaveEdit terminates all save processing, including the program from which it was called.

Parameters

Field or Control

Definition
Pagename

The name of the page specified in the page definition, preceded by the keyword Page. The pagename page must be in the current component. You can also pass the %page system variable in this parameter (without the Page reserved word).
scrollpath

A construction that specifies a scroll level in the component buffer.

[recordname .]fieldname

Specify a field designating the record and field in the scroll where you want to place the cursor.

target_row

The row number of the row in which you want to place the cursor.

Returns

None.

Example

The following example places the cursor in the appropriate field if a SaveEdit validation fails. Note the use of the %page system variable to get the page name. Note also that SetCursorPos is called before Error.

If None(&ITEM_FOUND) Then
   SetCursorPos(%Page, INV_ITEM_ID, CurrentRowNumber());
   Error (MsgGet(11100, 162, "Item is not valid in the order business unit.", INV_ITEM_ID, CART_ATTRIB_INV.ORDER_BU));
End-If;

The following example is similar, but uses the Page reserved word and page name:

If %Component = COMPONENT.BUS_UNIT_TBL_GL Then
   SetCursorPos(PAGE.BUS_UNIT_TBL_GL1, DEFAULT_SETID, CurrentRowNumber());
End-If;
Error MsgGet(9000, 165, "Default TableSet ID is a required field.");

Syntax

SetDBFieldAuxFlag(Field.FieldName, FlagNumber, Setting)

Description

Use the SetDBFieldAuxFlag function to set the auxiliary flag mask (AuxFlagMask) property for the specified field. This field indicates properties about the field.

Currently, only one flag comes preset from PeopleSoft: a 1 indicates a ChartField. If you want to associate a property with a field, you must coordinate with other developers to make certain that no one else is setting a property using the same flag number.

Use the GetAuxFlag Field method to read the current setting of the property.

If you use this function, the change is made to the database field, but it doesn't require a rebuild of the database. However, the change is not reflected in the component buffer. You must reload the component for the new setting to take place.

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.

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.

Parameters

Field or Control

Definition
Fieldname

Specify the name of the field that you want the AuxMaskFlag property changed. This name must be prefixed by the reserved word Field.
FlagNumber

Specify the flag value, a number between 1 and 32. A 1 is a ChartField.
Setting

Specify whether this flag should be on (True) or off (False).

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

%MDA_FieldNotFound

The specified field was not found in the database.

Example

&ret = SetDBFieldAuxFlag(Field.OrgId, 1, True);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldAuxFlag succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldAuxFlag failed"); 
End-If;

Syntax

SetDBFieldCharDefn(Field.FieldName, Length [, FormatFamily])

Description

Use the SetDBFieldCharDefn function to create a field definition of type character, with the indicated name, length, and format family.

Note: After using this function, you should use the SetDBFieldLabel function to define the label for the new field.

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.

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.

Parameters

Field or Control

Definition
Fieldname

Specify the name of the new field that you want to create. This name must be prefixed by the reserved word Field.
Length

Specify the length of the new field as a number.
FormatFamily

Specify the format family of the new field. This parameter is optional: the default value is upper case. The valid values are:

  • %FormatFamilyType_Upper (default)

  • %FormatFamilyType_Name

  • %FormatFamilyType_Phone

  • %FormatFamilyType_Zip

  • %FormatFamilyType_SSN

  • %FormatFamilyType_MixedCase

  • %FormatFamilyType_NumOnly

  • %FormatFamilyType_SIN

  • %FormatFamilyType_PhoneIntl

  • %FormatFamilyType_ZipIntl

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

%MDA_Duplicate

The field specified by FieldName already exists.

%MDA_FieldFmtLength

The specified length conflicts with the specified format family and was overwritten when the field was created.

Example

&ret = SetDBFieldCharDefn(Field.OrgId, 10,  
%FormatFamilyType_MixedCase);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldCharDefn succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldCharDefn failed"); 
End-If;

You can also use this function with de-referenced parameters, as follows:

&ret = SetDBFieldCharDefn(@("FIELD." | FS_CF_UPD_AET.FIELDNAME), 
FS_CF_UPD_AET.NEW_CF_LENGTH, %FormatFamilyType_MixedCase);

The following example adds a new character field:

&cf = "CF1"; 
&len = 10; 
&frmt = %FormatFamilyType_Upper; 
&fld = "FIELD." | &cf; 
&ret = SetDBFieldCharDefn(@(&fld), &len, &frmt); 
If (&ret = 0) Then 
   MessageBox(0, "SetDBFieldCharDefn", 0, 0, "Succeeded"); 
Else 
   MessageBox(0, "SetDBFieldCharDefn", 0, 0, "Failed"); 
End-If;

Syntax

SetDBFieldFormat(Field.FieldName, FormatFamily [, FamilyName, DisplayName])

Description

Use the SetDBFieldFormat function to change the format family for a field.

Use the StoredFormat Field property to determine the existing format family for a field.

If you only want to change the display format of a single field at runtime, and not change the database field, use the DisplayFormat Field property.

Note: This function only works with character fields.

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.

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.

Parameters

Field or Control

Definition
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
FormatFamily

Specify the new format family of the field. The valid values are:

  • %FormatFamilyType_Upper

  • %FormatFamilyType_Name

  • %FormatFamilyType_Phone

  • %FormatFamilyType_Zip

  • %FormatFamilyType_SSN

  • %FormatFamilyType_MixedCase

  • %FormatFamilyType_NumOnly

  • %FormatFamilyType_SIN

  • %FormatFamilyType_PhoneIntl

  • %FormatFamilyType_ZipIntl

  • %FomatFamilyType_Custom
FamilyName

Specify a new family name. This parameter is optional, and only valid if FormatFamily is specified as custom (%FormatFamilyType_Custom).
DisplayName

Specify a new display name. This parameter is optional, and only valid if FormatFamily is specified as custom (%FormatFamilyType_Custom).

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

Example

&ret = SetDBFieldFormat(Field.OrgId, %FormatFamilyType_Custom, "Postal_Code", "Normal");  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldFormat succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldFormat failed"); 
End-If;

Syntax

SetDBFieldFormatLength(FieldName, Length)

Description

Use the SetDBFieldFormatLength function to change the format length for a field. This length controls the maximum number of characters an end user can type into an edit box for this character field. This can be used to limit the user without having to rebuild or alter the table.

Note: This function only works with character fields.

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.

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.

Parameters

Field or Control

Definition
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
Length

Specify the new format length as a number. Valid values are between 1 and 254.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_FieldNotFound

The specified field wasn't found in the database.

%MDA_Unsupported

You tried to use this function on a non character field. This function is only supported on character fields.

Example

&ret =  SetDBFieldFormatLength(FIELD.OrgId, 10);  
If (&ret = %MDA_success) Then 
  MessageBox(0, "MetaData Fn Status", 0, 0, "SetDBFieldFormatLength succeeded"); 
Else 
  MessageBox(0, "MetaData Fn Status", 0, 0, "SetDBFieldFormatLength failed"); 
End-If;

Syntax

SetDBFieldLabel(Field.FieldName, LabelID, Long, Short, Default [, LanguageID])

Description

Use the SetDBFieldLabel function to either modify an existing label, or add a new label to a field definition.

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.

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.

Parameters

Field or Control

Definition
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
LabelID

Specify the label ID of the field label that you want to modify as a string. If the specified label ID isn't found, a new label, with the specified label ID, is created for the field.
Long

Specify the new long label for the field as a string.
Short

Specify the new short label for the field as a string.
Default

Specify whether the new label is the default label for the field. This parameter takes a Boolean value: True, set the label as the default, False, do not.

LanguageID

Specify the three character language code to use with this field. This parameter is optional. If you do not specify a language code, the language of the current user is used.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_FieldNotFound

The specified field wasn't found.

Example

&ret = SetDBFieldLabel(Field.OrgId, "ORGID", "Organization ID", "OrgId", True);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldLabel succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldLabel failed"); 
End-If;

Syntax

SetDBFieldLength(Field.FieldName, Length)

Description

Use the SetDBFieldLength function to modify an existing character field to have a new length.

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.

Use the Length Field class property to find the existing length of a field.

Note: This function only works with character fields.

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.

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.

Parameters

Field or Control

Definition
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
Length

Specify the new field length as a number between 1 and 254.

Note: If a default has been specified for this field in any record, and the size of the default is greater than the new size, you must modify the record field separately.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_Unsupported

The specified field isn't a character field. This function is only supported for character fields.

%MDA_FieldNotFound

The specified field wasn't found.

%MDA_FieldFmtLength

The specified length isn't compatible with the current format family, or there are record field defaults greater than the specified size.

Note: If a default has been specified for this field in any record, and the size of the default is greater than the new size, you must modify the record field separately.

Example

&ret = SetDBFieldLength(Field.OrgId, 10);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldLength succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldLength failed"); 
End-If;

You can also use this function with de-referenced parameters, as follows:

&ret = SetDBFieldLength(@("FIELD." | FS_CF_UPD_AET.FIELDNAME), FS_CF_UPD_AET.NEW_CF_LENGTH);

Syntax

SetDBFieldNotUsed(Field.FieldName, NotUsed)

Description

Use the SetDBFieldNotUsed function to specify whether a database field is used as a chart field or not.

SetDBFieldNotUsed does the following for a field:

  • Specifies whether the field is included in the index when indexes are built for records that contain this field. The column always remains in the table associated with the record.

  • Specifies that the field is ignored in Query.

  • Specifies that the field is ignored in nVision.

In addition, fields marked as Search Keys or List Box Items in the Application Designer that are set as not used do not display in search dialogs and list boxes.

Considerations Using this Function

This function is primarily intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not, in general, supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded. Using this function to modify records in components that have not been loaded, and then loading those components will, while not changing indices, prevent Query and nVision from using the field, and may be used to key display of the field in pages.

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.

Parameters

Field or Control

Definition
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
NotUsed

Specify whether this field is to be used as a chart field. This parameter takes a Boolean value: True, this field is not used, False, this field is used.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_FieldNotFound

The specified field wasn't found.

Example

&ret = SetDBFieldNotUsed(Field.OrgId, True);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldNotUsed succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetDBFieldNotUsed failed"); 
End-If;

Syntax

SetDefault([recordname.]fieldname)

Description

Use the SetDefault function to set a field to a null value, so that the next time default processing occurs, it is set to its default value: either a default specified in its record field definition or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

Note: This function remains for backward compatibility only. Use the SetDefault field class property instead.

Blank numbers correspond to zero on the database. Blank characters correspond to a space on the database. Blank dates and long characters correspond to NULL on the database. SetDefault gives each field data type its proper value.

See SetDefault.

Where to Use SetDefault

If a PeopleCode program or function executes the SetDefault built-in on a field that does not exist in the component buffer, the remainder of the program or function is skipped. In the case of a function, execution of the calling program continues with the next statement after the call to the function. However, if the program containing the SetDefault call is at the "top level", meaning that it was called directly from the component processor or application engine runtime, it exits.

Therefore, if you want to control the behavior of SetDefault, you should encapsulate any calls to this built-in function inside your own functions. This enables your overall programs to continue, whether or not the SetDefault succeeds.

Parameters

Field or Control

Definition
[recordname.]fieldname

Specify a field designating the fields that you want to set to its default value.

Returns

Optionally returns a Boolean value indicating whether the function executed successfully.

Example

This example resets the PROVIDER to its null value. This field is reset to its default value when default processing is next performed:

If COVERAGE_ELECT = "W" Then
   SetDefault(PROVIDER);
End-if;

Syntax

SetDefaultAll([recordname.]fieldname)

Description

Use the SetDefaultAll function to set all occurrences of the specified recordname.fieldname within a scroll to a blank value, so that the next time default processing is run these fields are set to their default value, as specified by the record definition, or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

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

Example

The following example sets the fields TO_CUR and CUR_EXCHNG_RT to their default values on every row of the scroll area where the PeopleCode is run:

SetDefaultAll(TO_CUR);
SetDefaultAll(CUR_EXCHNG_RT);

Syntax

SetDefaultNext([recordname.]fieldname)

Description

Use the SetDefaultNext function to locate the next occurrence of the recordname.fieldname with the next effective date (and effective-sequence number if specified) and set the field to a blank value, so that the next time default processing is run this field will be set to its default value, as specified by the record definition, or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

SetDefaultNext is typically used to reset values within a scroll which are calculated within default PeopleCode based on a next value.

This function is valid only for effective-dated records. If a next record does not exist, then the statement is skipped.

Syntax

SetDefaultNextRel(search_field, default_field)

Description

Use the SetDefaultNextRel function to locate the next occurrence of the search_fieldwith the next effective date (and effective-sequence number if the record contains an effective-sequence number), then set the value of the specified default_fieldcorresponding to the search_field to a blank value, so that the next time default processing is run this field will be set to its default value, as specified by the record definition, or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

This function is valid only for effective-dated records. If a next record does not exist, then the statement is skipped.

Syntax

SetDefaultPrior([recordname.]fieldname)

Description

Use the SetDefaultPrior function to locate the prior occurrence of the recordname.fieldname with the prior effective date (and effective-sequence number if specified), then set the field to a blank value, so that the next time default processing is run this field will be set to its default value, as specified by the record definition, or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

SetDefaultPrior is typically used to reset values within a scroll which are calculated within FieldDefault PeopleCode based on a next value.

This function is valid only for effective-dated records. If a prior record does not exist, then the statement is skipped.

Syntax

SetDefaultPriorRel(search_field, default_field)

Description

Use the SetDefaultPriorRel function to locate the prior occurrence of the search_field with the prior effective date (and effective sequence-number if the record contains an effective-equence number) and then sets the specified default_field to a blank value, so that the next time default processing is run this field will be set to its default value, as specified by the record definition, or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

This function is valid only for effective-dated records. If a next record does not exist, then the statement is skipped.

Syntax

SetDisplayFormat(scrollpath, target_row, [recordname.]fieldname, display_format_name)

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

Usethe SetDisplayFormat function to change the display format of Custom Defined Fields at runtime. For instance, you may want to update a custom numeric display to reveal more decimal points.

Note: This function remains for backward compatibility only. Use the DisplayFormat field property instead.

Parameters

Field or Control

Definition
scrollpath

A construction that specifies a scroll level in the component buffer.

target_row

The row number of the target row.
[recordname .]fieldname

The name of the field to change. The field can be on scroll level one, two, or three of the active page. The recordname prefix is required if the call to SetDisplayFormat is not on the record definition recordname.
display_format_name

The name of the custom display format specified in the field definition.

Returns

Returns a Boolean value indicating whether the function executed successfully. The return value is not optional.

Syntax

SetLabel(scrollpath, target_row, [recordname.]fieldname, new_label_text)

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 SetLabel function to change the label text of a page field or grid column heading.

Note: This function remains for backward compatibility only. Use the Label field property instead.

You can't use this function to set labels longer than 100 characters. If you try to set a label of more than 100 characters, the label is truncated to 100 characters.

Parameters

Field or Control

Definition
scrollpath

A construction that specifies a scroll level in the component buffer.

target_row

The row number of the target row.
[recordname .]fieldname

The name of the field with the associated label text. The field can be on scroll level one, two, or three of the active page. The recordname prefix is required if the function call is not on the record definition recordname.
new_label_text

A String value specifying the new value for the field or grid column label.

Returns

Optionally returns a Boolean value indicating whether the function completed successfully.

Example

If training_loc = "HAW" then 
     SetLabel(voucher_tbl.training_loc, "Hawaii Training Center"); 
End-if;

Syntax

SetLanguage(language_code)

Description

Use the SetLanguage function to set the end user's current language preference to the specified language_code. language_code must be a valid translate value for the field LANGUAGE_CD. SetLanguage returns True if it is successful, and it returns False if it fails or an invalid value was passed. The new language preference is temporary, remaining in effect only until the user logs off, or until another call is made to SetLanguage.

Note: SetLanguage does not work in Signon PeopleCode, or with asynchronous messages.

Considerations Using SetLanguage With %Language

The value of %Language depends on the type of application:

  • For online applications, %Language is the language code that the current component is using.

  • For non-online applications (such as in an application engine program), %Language is the language code of the user based on their language preference in their User Profile.

SetLanguage changes the default language for the current session only. The language change does not take effect until the component buffer is flushed and repopulated. For example, transferring to a new component causes the buffer to be flushed.

%Language reflects the value using SetLanguage after the function is executed.

SetLanguage changes the current user interface and data language simultaneously. If the Multi Language Entry personalization option is enabled, users can change the data language independently from the user interface language. There is no way to change the data language from PeopleCode without also changing the user interface language using SetLanguage.

Parameters

Field or Control

Definition
language_code

A valid language code, stored in the Translate table for the LANGUAGE_CD field.

Returns

Optionally returns a Boolean value indicating whether the function executed successfully. Returns False if an invalid language code is passed.

Example

The following example switches the language code and displays a message informing the end user of the change:

  If SetLanguage(LANGUAGE_CD) Then 
      WinMessage(MsgGet(102, 5, "Language preference changed to ", LANGUAGE_CD)); 
   Else 
      WinMessage(MsgGet(102, 6, "Error in setting language.  Language is currently %1", %Language)); 
  End-if;

Syntax

SetMDAJAXTrf(enabled)

Description

For custom fluid wrapper components (fluid activity guides or master/detail components), use the SetMDAJAXTrf function to set whether fluid component transfers stay within the master/detail or activity guide wrapper. Since classic components are displayed within an iframe, this setting is ignored for classic component transfers. If this function is never invoked, the default value is False; component transfers leave the wrapper.

Note: Invoke this function from the wrapper component only, and not from individual components or pages displayed within the wrapper.

Note: Alternatively, AJAX transfers can be enabled on the URL for the content reference definition that launches the fluid wrapper.

Parameters

Field or Control

Definition
enabled

Specifies a Boolean value indicating whether AJAX transfers are enabled on the master/detail or activity guide wrapper.

Returns

None.

Syntax

SetMDGuided(guided)

Description

For master/detail and activity guide components, use the SetMDGuided function to set whether the master/detail or activity guide wrapper is in guided mode (that is, Previous and Next buttons are displayed in the fluid banner). If this function is never invoked, the default value is False; non-guided mode is in effect.

Note: Invoke this function from the wrapper component only, and not from individual components or pages displayed within the wrapper.

Important! Use this function within fluid applications only.

Parameters

Field or Control

Definition
guided

Specifies a Boolean value indicating whether the master/detail or activity guide wrapper is in guided mode.

Returns

A Boolean value.

Syntax

SetMDListPopup(non_optimized)

Description

For master/detail and activity guide wrapper components, use the SetMDListPopup function to set whether the master/detail or activity guide wrapper is in non-optimized mode (that is, navigation to pages is presented in a drop-down list in the fluid banner, not in the left panel). If this function is never invoked, the default value is False; optimized mode is in effect (that is, items are presented in the left panel).

Note: Invoke this function from the wrapper component only, and not from individual components or pages displayed within the wrapper.

Important! Use this function within fluid applications only.

Parameters

Field or Control

Definition
non_optimized

Specifies a Boolean value indicating whether the master/detail or activity guide wrapper is in non-optimized mode.

Returns

A Boolean value.

Syntax

SetMDListSlideout(enabled)

Description

To prevent left panel collisions in custom fluid wrapper components (fluid activity guides or master/detail components), use the SetMDListSlideout function to set whether collision handling with the slide-out left panel is enabled for the component. If this function is never invoked, the default value is False; collision handling is not enabled.

Important! Use this function within custom fluid wrapper components only.

Note: While SetMDListSlideout is used in custom fluid wrapper components, left panel collision handling is enabled via the URL for standard fluid wrappers. For master/detail components, fluid activity guides, and fluid navigation collections, add the following query string parameter to the URL for the content reference definition that launches the fluid wrapper: &ICMDListSlideout=true

Parameters

Field or Control

Definition
enabled

Specifies a Boolean value indicating whether collision handling with the slide-out left panel is enabled on the master/detail or activity guide wrapper.

Returns

None.

Syntax

SetMessageStatus(Message.MessageName, Status)

Description

Use the SetMessageStatus function to specify whether a message is active or inactive.

Parameters

Field or Control

Definition
MessageName

Specify the name of the message definition that you want to change the status for. Prefix this name with the reserved word Message.

Status

Specify the status for the message. Valid values are:

  • %IB_Status_Active

  • %IB_Status_InActive

Returns

A Boolean value: true if the status is set correctly, false otherwise.

Syntax

SetNextPanel(panelname)

Description

Use the SetNextPanel to specify the panel name to which the user will be transferred when selecting the NextPanel (F6) function or specifying it with the PeopleCode TransferPage function.

Note: The SetNextPanel function is supported for compatibility with previous releases of PeopleTools. New applications should use the SetNextPage function instead.

Related Links

SetNextPage

Syntax

SetNextPage(pagename)

Description

Use the SetNextPage function to specify the page name to which the user is transferred when selecting the NextPage (ALT+6 and ENTER) function or specifying it with the PeopleCode TransferPage function.

SetNextPage validates that pagename is listed on current menu. This selection is cleared when the user transfers to a new page.

Parameters

Field or Control

Definition
pagename

A String equal to the name of the page as specified in the page definition.

Returns

Optionally returns a Boolean value indicating whether the function executed successfully.

Example

See AddKeyListItem.

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

The following example sets up and transfers the user to page JOB_DATA.

If SetNextPage(PAGE.JOB_DATA) Then
     TransferPage( );
End-if;

Syntax

SetPageFieldPageFieldName(Page.PageName, Record.RecordName, Field.FieldName, PageFieldName)

Description

Use the SetPageFieldPageFieldName function to add or change a page field name for a field. The page field name is set on the General tab of the page field properties. Changing a name to itself is not supported.

The first field on the page with the specified record name and field name is the field that's changed.

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.

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.

Parameters

Field or Control

Definition
PageName

Specify the page containing the field you want to change. This name must be prefixed by the reserved word Page.
RecordName

Specify the record containing the field you want to change. This name must be prefixed by the reserved word Record.
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
PageFieldName

Specify the page field name that you want associated with the page field as a string.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_PageNotFound

The specified page wasn't found.

%MDA_PageFieldNotFound

The specified field wasn't found on the specified page.

%MDA_Duplicate

A second field by the same name was found on the page. Only the first page field name was changed.

Example

The following example adds a page field name to a page field.

&ret = SetPageFieldPageFieldName(Page.ABSENCE_HIST, Record.ABSENCE_HIST, Field.EMPLID, "EMPLID")

The following example adds a page field name to a page field using dereferenced parameters.

&Pnl = "Page." | "ABSENCE_HIST"; 
&Rec = "Record." | "ABSENCE_HIST"; 
&Field = "Field." | "EMPLID"; 
&Name = "EMPLID" 
&ret = SetPageFieldPageFieldName(@(&Pnl), @(&Rec), @(&Field), &Name);

Syntax

SetPanelControlStyle(style)

Description

Use the SetPanelControlStyle function to specify a String value that updates the system with styles that control the state of the left and right panels.

Important! Use this function within fluid applications only.

Parameters

Field or Control

Definition
style

Specifies the styles for the panel controller as a String value.

Returns

A String value.

Example

method UpdatePanel
   SetPanelControlStyle(&m_oCSS.ResultStyles);
end-method;

Syntax

SetPasswordExpired(NewValue)

Description

Use the SetPasswordExpired function to set the password expired status for the current user. When the user's password expired flag is set to True, they can only access the page that allows them to change their password. The function returns the old value, that is, the value that represented the status of the flag before it was set to NewValue.

Parameters

Field or Control

Definition
NewValue

Specify a new value for the user's password expired flag. This parameter takes a Boolean value

Returns

A Boolean value: True if you've set the password expire flag to False, False if you've set the password expire flag to True.

Example

If %PasswordExpired Then 
   &NewValue = SetPasswordExpired(True); 
End-If;

Syntax

SetPostReport()

Description

Use the SetPostReport function to create a reference to a PostReport object. After you’ve created this object, you can assign values to its properties, then use the Put method to initiate the posting of the files to the Report Repository.

Parameters

None.

Returns

A reference to a PostReport object.

Syntax

SetRecFieldEditTable(Record.RecordName, Field.FieldName, EditTable [, TableEditType])

Description

Use the SetRecFieldEditTable function to set the edit table value for a record field. This overwrites the value for the edit table for the record field. Use the SetEditTable Record method to just set the edit table value at runtime.

If you specify a null value for EditTable, and no value is specified for TableEditType, the table edit flag is turned off, that is, no prompt table is set for the record field.

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.

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.

Parameters

Field or Control

Definition
RecordName

Specify the record containing the field you want to change. This name must be prefixed by the reserved word Record.
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
EditTable

Specify the name of the edit table record. This name must be prefixed by the reserved word Record. If you do not want to specify a record name, specify Record."".

TableEditType

Specify the type of edit table record to be associated with the record field. If you specify a value for EditTable (and not a null value) this parameter is required. You can specify either a constant or numeric value for this parameter. Valid values are:

Constant Value

Numeric Value

Used for which types of fields

%EditTableType_NoEdit

0

Character, Number, Date, Time, Datetime

%EditTableType_Prompt

1

Character, Number, Date, Time, Datetime

%EditTableType_YesNo

2

Character

%EditTableType_Translate

3

Character fields with length 4 or less only

%EditTableType_OneZero

4

Number fields only

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_RecordNotFound

The specified record wasn't found.

%MDA_RecFieldNotFound

The specified field wasn't found on the record.

Example

&ret = SetRecFieldEditTable(RECORD.AbsHist, Field.OrgId, RECORD.EmplId_Tbl, %EditTableType_Prompt);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetRecFieldEditTable succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetRecFieldEditTable failed"); 
End-If;

Syntax

SetRecFieldKey(Record.RecordName, Field.FieldName, Key)

Description

Use the SetRecFieldKey function to specify whether a field on a record is a key field or not.

Use the IsKey field class property to determine whether or not the field is already a key.

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

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.

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.

Parameters

Field or Control

Definition
RecordName

Specify the record containing the field you want to change. This name must be prefixed by the reserved word Record.
FieldName

Specify the name of the field that you want to modify. This name must be prefixed by the reserved word Field.
Key

Specify whether the field is a key or not. This parameter takes a Boolean value: True, the field is a key field, False, it isn't.

Returns

A constant value. The values are:

Value

Description

%MDA_Success

Function completed successfully.

%MDA_Failure

Function didn't complete successfully.

%MDA_RecordNotFound

The specified record wasn't found.

%MDA_RecFieldNotFound

The specified field wasn't found on the record.

Example

&ret = SetRecFieldKey(RECORD.AbsHist, Field.OrgId, True);  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetRecFieldKey succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "SetRecFieldKey failed"); 
End-If;

Syntax

SetReEdit(reedit_on)

Description

Use the SetReEdit to switch re-edit mode on and off. When re-edit mode is on, definitional edits (such as translate table and prompt table edits), as well as FieldEdit PeopleCode, are run on each editable field in the component when the component is saved. If an error is found, the component data is not saved. SetReEdit can be called at any time during the life of the component before the SaveEdit event fires, and would typically be called in RowInit when other page settings are being initialized. When a component is started, re-edit mode is off by default.

SetReEdit is used primarily in financial applications, where transactions are sometimes brought into the database by non-online processes. When re-edit mode is on, the values read in during these transactions can be validated by simply bringing them up in the page and saving. Any errors are then reported, as if the end user had entered all of the data online.

Parameters

Field or Control

Definition
reedit_on

A Boolean value specifying whether to switch re-edit mode on or off. True turns re-edit mode on, False turns re-edit mode off.

Example

This example is used in RowInit PeopleCode to initialize component settings. After re-edit mode is on, field-level edits are re-applied when the component is saved.

SetReEdit(True);

Syntax

SetSaveWarningFilter(enable_or_disable)

Description

Use the SetSaveWarningFilter function to suppress save warning irrespective of whether the component level flag (indicating whether the component is changed) is set or not. If you use this function, the component processor ignores the component level flag value and lets the user to navigate away from the component without issuing any save warning.

Note: After the updates are completed, ensure to call SetSaveWarningFilter(False) to resume the save warning flag.

Parameters

Field or Control

Definition
enable_or_disable

Specifies a Boolean value indicating whether to issue save warning to a user.

If True, the component processor ignores the flag and save warning is not issued; if False, component processor issues save warning.

Returns

None.

Example

In this example, the function temporarily disables save warning and then enables save warning.

method LoadGroupletSetupGrid
   /+ &p_rwCurrentRow as Row +/
   /* Disabling save warning */
   SetSaveWarningFilter( True);
   If &p_rwCurrentRow.PTGPLT_WORK.PTGPLT_DT_DROPDOWN.Value = "All" Then
      &m_rsPTGPLTSetup.Flush();
      GetLevel0().Select(Scroll.PTPPB_GROUPLET, Record.PTPPB_GROUPLET);
   Else
      &m_rsPTGPLTSetup.Flush();
      GetLevel0().Select(Scroll.PTPPB_GROUPLET, Record.PTPPB_GROUPLET, "Where PTPPB_DATATYPE_ID = :1", &p_rwCurrentRow.PTGPLT_WORK.PTGPLT_DT_DROPDOWN.Value);
   End-If;
   /* Re-enabling save warning */
   SetSaveWarningFilter( False);
end-method;

Syntax

SetSearchDefault([recordname.]fieldname)

Description

Use the SetSearchDefault function to set system defaults (default values set in record field definitions) for the specified field on search dialog boxes. It does not cause the FieldDefault event to fire.

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

The system default occurs only once, when the search dialog box first starts, immediately after SearchInit PeopleCode. If the end user subsequently blanks out a field, the field is not reset to the default value. The related function ClearSearchDefault disables default processing for the specified field. SetSearchDefault is effective only when used in SearchInit PeopleCode programs.

Parameters

Field or Control

Definition
[recordname .]fieldname

The name of the target field, a search or alternate search key that is about to appear in the search dialog box. The recordname prefix is required if the call to SetSearchDefault is not on the record definition recordname.

Example

This example, from SearchInit PeopleCode turns on edits and defaults for the SETID field in the search dialog box:

SetSearchEdit(SETID);
SetSearchDefault(SETID);

Syntax

SetSearchDialogBehavior(force_or_skip)

Description

Use the SetSearchDialogBehavior function in SearchInit PeopleCode to set the behavior of search and add dialog boxes before a page is displayed, overriding the default behavior. There are two dialog behavior settings: skip if possible (0) and force display (1).

Skip if possible means that the dialog box is skipped if all of the following are true:

  • All required keys have been provided (either by system defaults or by PeopleCode).

  • If this an Add dialog box, then no duplicate key error results from the provided keys; if this error occurs, the processing resets to the default behavior.

  • If this is a Search dialog box, then at least one row is returned based on the provided keys.

Force display means that the dialog box displays even if all required keys have been provided.

The default behavior of the search and add dialog boxes is force display.

Note: SetSearchDialogBehavior can only be used in SearchInit PeopleCode.

Special Usage in Fluid Components

In a fluid component, if you set the search page type to None, you are bypassing the fluid search pages. You must use SearchInit PeopleCode or specify a search record that does not have a search key defined.

To avoid a known issue in PeopleTools 8.57 or earlier releases, if you create a SearchInit program, you must set all high-level keys and you must prevent the display of a non-functional search page using the SetSearchDialogBehavior function. For example:

#If #ToolsRel <= "8.57" #Then
   PSUSRSELF_SRCH.OPRID = %UserId;
   SetSearchDialogBehavior(0);
#Else
   PSUSRSELF_SRCH.OPRID = %UserId;
#End-If

Parameters

Field or Control

Definition
force_or_skip

A Number equal to one of the following values:

  • 0: sets the dialog behavior to skip if possible.

  • 1: sets the dialog behavior to force display.

Returns

None.

Example

The following function call, which must occur in SearchInit PeopleCode, sets the dialog behavior to skip if possible.

SetSearchDialogBehavior(0);

Syntax

SetSearchEdit([recordname.]fieldname)

Description

Use the SetSearchEdit function to enable system edits (edits specified in the record field definition) for the specified [recordname.]fieldname, for the life of the search dialog box, or until the ClearSearchEdit function is called with that same field.

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

See SearchEdit.

Using SetSearchEdit

In the Add mode search dialog, the following edits are performed when the end user clicks the Add button. In any other mode, the following edits are performed when the end user clicks the Search button:

  • Formatting

  • Required Field

  • Yes/No Table

  • Translate Table

  • Prompt Table

SetSearchEdit does not cause the FieldEdit, FieldChange, or SaveEdit PeopleCode events to fire during the search dialog.

You might use SetSearchEdit to control access to the system. For example, you can apply this function to the SETID field of a dialog box and require the end user to enter a valid SETID.

If you use this function in the SearchInit event, the search page options are limited to the "=" and "IN" operators.

Parameters

Field or Control

Definition
fieldname

The name of the search dialog field on which to enable field edits.

Returns

Returns a Boolean value indicating whether the function executed successfully.

Example

This example turns on edits and system defaults for the SETID field in the search dialog box:

SetSearchEdit(SETID);
SetSearchDefault(SETID);

Syntax

SetTempTableInstance(instance_number)

Description

Use the SetTempTableInstance function to set the default temp table instance to the specified number for the processing of temporary tables. This default is used by all %Table meta-SQL references to temporary tables, and by all SQL operations. Generally, you use this function only when you’re trying to use any of the ScrollSelect functions, the Rowset class Select or SelectAll methods, the record class SQL methods (SelectByKey, Insert, and so on.), or any of the meta-SQL statements that use %Table (%InsertSelect, %InsertSelectWithLongs, %SelectAll, %Delete, and so on.) Generally, %Table should be used to override the default.

If you use this built-in within an Application Engine program, and the program uses a process-level instance on the request, the old instance value must be saved, then restored after you’re finished using the new instance.

If you pass a zero for instance_number, the Fill method uses the physical table instance with no table append, for example, if the temporary table record is FI_INSTR_T, the physical table used is PS_FI_INSTR_T.

Parameters

Field or Control

Definition
instance_number

Specify the instance number for the temporary tables.

Returns

Existing (or previous) instance number.

Example

To avoid interfering with other uses of temporary tables, you should only set the temporary table instance for your process, then set it back to the default. For example:

/* Set temp table instance */ 
&PrevInstNum = SetTempTableInstance(&NewInstNum); 
/* use the temporary table */ 
.  .  . 
/* Restore the temp table instance */ 
SetTempTableInstance(&PrevInstNum);

Syntax

SetThemeId(theme_ID)

Description

Use the SetThemeId function to set the theme ID for the page or component so that proper theme style sheets get loaded.

Important! Use this function within fluid applications only.

Parameters

Field or Control

Definition
theme_ID

Specifies the theme ID as a string value.

Returns

None.

Example

SetThemeId(DEFAULT_THEME_TANGERINE_ALT);

Syntax

SetTracePC(n)

Description

Use the SetTracePC function to control PeopleCode trace settings programmatically. This is useful if you want to isolate and debug a single program or part of a program.

Note: If you’re using an API with the Session class, use the Trace Setting class properties instead of this function.

You can also set options prior to starting a PeopleSoft Application Designer session using the Trace tab of PeopleSoft Configuration Manager.

Tracing PeopleCode creates and writes data to a trace file that it shares with SQL tracing; SQL trace and PeopleCode trace information are both output to the file in the order of execution. The trace file uses a file name and location specified in the Trace page of PeopleSoft Configuration Manager. If no trace file is specified in PeopleSoft Configuration Manager, the file is set by default to DBG1.TMP in your Windows TEMP directory. If you specify only a file name, and no directory is specified, the file is written to the directory you’re running PeopleSoft Application Designer from. This file is cleared each time you log on and can be opened in a text editor while you are in a PeopleSoft Application Designer session, so if you want to save it, you must print it or copy it from your text editor.

Trace timings are given in the elapsed time in seconds, but reported in microseconds and include CPU time and "cycles". The CPU time measurement, depending on platform, may not be very precise. The "cycles" is a measure of how much PeopleCode the program is executing. It counts loops around the PeopleCode interpreter. This cycle count is only updated when some tracing or debugging is going on. So, for example, turning the trace off then back on again will skip some cycles.

Note: Oracle recommends using a value of  %TracePC_Statements (2048) instead of %TracePC_Functions (1) and %TracePC_List (2).

Parameters

Field or Control

Definition
options

Either a number or a constant value that sets trace options. Calculate options by either totaling the numbers associated with any of the following options or by adding constants together:

Numeric Value

Constant Value

Description

0

%TracePC_None

Set trace off.

1

%TracePC_Functions

Provide a trace of the program as it is executed. This implies options 64, 128, and 256 described in the following rows.

2

%TracePC_List

Provide a listing of the entire program.

4

%TracePC_Assigns

Show the results of all assignments made to variables.

8

%TracePC_Fetches

Show the values fetched for all variables.

16

%TracePC_Stack

Show the contents of the internal machine stack. This option is normally used for debugging the PeopleCode language and not PeopleCode programs.

64

%TracePC_Starts

Provide a trace showing when each program starts.

128

%TracePC_ExtFuncs

Provide a trace showing the calls made to each external PeopleCode routine.

256

%TracePC_IntFuncs

Provide a trace showing the calls made to each internal PeopleCode routine.

512

%TracePC_ParamsIn

Show the values of the parameters to a function.

1024

%TracePC_ParamsOut

Show the values of the parameters as they exist at the return from a function.

2048

 %TracePC_Statements

Show each statement as it's executed (and do not show statements on branches not taken.)

32768

%TracePC_Evaluations

Start the timing tracing of the start and end of top-level program evaluations. This is similar to the Trace Start of Programs, but only traced when the call isn't directly from PeopleCode.

It traces recursive evaluations, like what happens when a ScrollSelect in a RowInit event causes another recursive RowInit to fire during the outer RowInit.

If both Trace Evaluations (32768) and Trace Start of Programs (64) are on (32768+64 = 32832) then all routine calls (functions, methods, get, set for both internal and external PeopleCode to PeopleCode calls) are traced. The resulting trace file can be processed by a program to add up the timings for each routine and separate the in-routine timings from those for called routines.

Returns

None.

Example

The following example is part of a SavePreChange PeopleCode program that sets PeopleCode trace based on page field settings:

DEBUG_CODE = 0;
If DEBUG_TRACE_ALL = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 1
End-if;
If DEBUG_LIST = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 2
End-if;
If DEBUG_SHOW_ASSIGN = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 4
End-if;
If DEBUG_SHOW_FETCH = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 8
End-if;
If DEBUG_SHOW_STACK = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 16
End-if;
If DEBUG_TRACE_START = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 64
End-if;
If DEBUG_TRACE_EXT = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 128
End-if;
If DEBUG_TRACE_INT = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 256
End-if;
If DEBUG_SHOW_PARMS = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 512
End-if;
If DEBUG_SHOW_PARMSRT = "Y" Then
   DEBUG_CODE = DEBUG_CODE + 1024
End-if;
SetTracePC(DEBUG_CODE);

The following example sets Trace PC to show a listing of all the calls made to external routines as well as calls made to internal routines:

SetTracePC(384);

The following is identical to the previous example:

SetTracePC(%TracePC_ExtFuncs + %TracePC_IntFuncs);

If you need a thorough trace, you can use a value of 3596. That combines the following:

Value

Description

2048

Show each statement as it's executed

1024

Show the values of the parameters as they return

512

Show the values of the parameters to a function

8

Show the values fetched for all variables

4

Show the results of all assignments

Syntax

SetTraceSQL(options)

Description

Use the SetTraceSQL function to programmatically control the Trace SQL utility, enabling you to control TraceSQL options during the course of program execution.

Note: If you’re using an API with the Session class, use the Trace Setting class properties instead of this function.

When you interact with PeopleTools, SQL statements transparently perform actions such as page construction. The Trace SQL utility creates and updates a file showing the SQL statements generated by PeopleTools.

You can set options prior to starting a PeopleTools session using the Trace tab of PeopleSoft Configuration Manager.

Trace SQL creates and writes data to a trace file that it shares with Trace PeopleCode; Trace SQL and Trace PeopleCode information are both output to the file in the order of execution. The trace file uses a file name and location specified in the Trace page of PeopleSoft Configuration Manager. If no trace file is specified in PeopleSoft Configuration Manager, the file is set by default to DBG1.TMP in your Temp directory. If you specify only a file name, and no directory is specified, the file is written to the directory you’re running Tools from. This file is cleared each time you log on and can be opened in a text editor while you are in a PeopleTools session, so if you want to save it, you must print it or copy it from your text editor.

Parameters

Field or Control

Definition
options

Either a Number value or a constant that sets trace options. Calculate options by either totaling the numbers associated with any of the following options, or adding constants together:

Numeric Value

Constant Value

Description

0

%TraceSQL_None

No output

1

%TraceSQL_Statements

SQL statements

2

%TraceSQL_Variables

SQL statement variables (binds)

4

%TraceSQL_Connect

SQL connect, disconnect, commit and rollback

8

%TraceSQL_Fetch

Row Fetch (indicates that it occurred and the return code - not the data fetched.)

16

%TraceSQL_MostOthers

All other API calls except Set Select Buffers

32

%TraceSQL_SSB

Set Select Buffers(identifies the attributes of the columns to be selected)

64

%TraceSQL_DBSpecific

Database API-specific calls

128

%TraceSQL_Cobol

COBOL Statement Timings

1024

%TraceSQL_DB2400Server

Manager information for DB2/400 only

4096

%TraceSQL_ManagerInfo

All manager information.

8192

%TraceSQL_AppEngineInfo

Trace Application Engine information.

Note: PeopleSoft recommends setting options to 3 to provide most essential information without performance degradation. Options 8 and 32 greatly increase the volume of the trace and will noticeably degrade performance.

Returns

None.

Example

The following example switches off Trace SQL:

SetTraceSQL(0);

The following is identical to the previous example:

SetTraceSQL(%TraceSQL_None);

The following example sets Trace SQL to typical settings that won’t degrade performance:

SetTraceSQL(3);

The following is identical to the previous example:

SetTraceSQL(%TraceSQL_Statements + %TraceSQL_Variables);

Syntax

SetTransferAttributes(enable_animation, [add_to_history], [back_label], [user_data], [qry_string_array])

Description

Use the SetTransferAttributes function to set certain transfer-related properties when executing a transfer to a different page or component. SetTransferAttributes can be invoked prior to the transfer (for example, in a FieldChange program) or after the transfer in the target component (for example, in a page Activate program).

Parameters

Field or Control

Definition
enable_animation

Specifies a Boolean value indicating whether to animate the transfer.

The default value is False.
add_to_history

Specifies a Boolean value indicating whether to track the transfer in the Back button history stack.

The default value is True.

Note: The Back button is a user interface widget that appears in the portal header of classic pages and in the fluid page banner; it is not the browser’s back button.
back_label

Specifies a custom label for the Back button as a string value.
user_data

Specify any additional transfer attributes as name/value pairs using the following format:

Name1@Value1;Name2@Value2;...;NameN@ValueN

Specify the empty string, "", when no additional attributes need to be set.

Use the returntolastpage attribute to specify which page is displayed when returning to this component via the Back button:

  • returntolastpage@0 — The Back button returns the user to the first page of the component. This is the system default behavior for components.

  • returntolastpage@1 — The Back button returns the user to the last viewed page of the component.

The returntolastpage attribute overrides any page navigation settings specified in Application Designer. For fluid components, this is set on the Fluid tab; see Setting Fluid Component Properties. For classic components, this is set on the Internet tab; see Setting Internet Properties.
qry_string_array

Specifies an array of array of string containing name/value pairs to be used as query string parameters constituting the history record.

Returns

None.

Example

The following example sets animation to true, keeps the current content in the history, sets the back button's label to "Search Results," and then invokes the Transfer built-in function to complete the transfer:

SetTransferAttributes( True, True, "Search Results");
Transfer( False, MenuName.QE_NUI, BarName.USE, ItemName.QE_NUI_ED_BOOK, Page.QE_BOOK, "U", QE_BOOK.QE_BOOK_NAME);

The following example sets and uses an array of array of string containing name/value pairs to be used as query string parameters constituting the history record and then invokes the ViewURL built-in function to complete the transfer:

import EP_FUNCTIONS:DocumentPageTitle;
import EP_NUI_FUNCTIONS:EEmasterlist;
...
Component EP_NUI_FUNCTIONS:EEmasterlist &Component_MasterList;
...
SQLExec(SQL.EP_SEL_ROLE_DESCR, &EP_GBLKEYS_WRK.EP_ROLE.Value, &RoleDescr);
&Gbl_PageTitle = GetText("APPR_MAIN1_TITLE", " ", " ", " ", &EP_GBLKEYS_WRK.EP_USER_ROLE.Value, " ", &RoleDescr, " ", " ", " ", " ");
&Cmp_PageTitle = &Gbl_PageTitle;

/*  Transfer to WorkCenter  */
Local array of array of string &qs = CreateArray(CreateArray("XFER_TAB_NUMBER", String(&Component_MasterList.GetTabNumber())));
SetTransferAttributes( False, True, "", "", &qs);

&url = GenerateComponentPortalURL(%Portal, %Node, MenuName.ROLE_EMPLOYEE, "GBL", Component.EP_APPR_MAIN, "", "");
&EndPos = Find("?", &url, 0);
If &EndPos = 0 Then
 		&url = &url | "?replaceCurrentTopWindow=y&cmd=uninav";
Else
 		&url = &url | "&replaceCurrentTopWindow=y&cmd=uninav";
End-If;

rem %Response.RedirectURL(&url);
ViewURL(&url);

In certain scenarios, you may require intermediate components to perform a contextual transfer to content such as a dashboard. In these scenarios, you must prevent tracking of the intermediate component in the Back button history stack. To do so, the following code can be used in the intermediate component:

SetTransferAttributes( False, False, "", "", null, True);
ViewURL("http://domain:port/psp/ps_7/EMPLOYEE/T55106RO/h/?tab=QE_PT_DASHBOARD&pslnkid=QE_PT_DASHBOARD_LINK");

Syntax

SetupScheduleDefnItem(ScheduleName, JobName)

Description

Use the SetupScheduleDefnItem function to create a ProcessRequest object. After you’ve created this object, you can assign values to its properties then specific methods created to either schedule or print info for a Scheduled Jobset.

Parameters

Field or Control

Definition
ScheduleName

Specify the process type as a string. Values depend on the Scheduled Jobset defined for your system.
JobsName

Specify the name of the job name as a string.

Returns

A reference to a ProcessRequest object.

Example

Local ProcessRequest &MYRQST; 
 
&MYRQST = SetupScheduleDefnItem("SampleSchedule", &MyJobName);

Syntax

SetUserOption(Level, OPTN, Value)

Description

Use the SetUserOption to set the default value for the specified option.

Parameters

Field or Control

Definition
Level

Specify the option category level as a string.
OPTN

Specify the option as a string.
Value

Specify the value of the option.

Returns

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

Syntax

ShareAttachment(URLID, DirAndFilePrefix, ShareURL, ShareMode, ShareRole, ExpirationDateTime, AccessToken, UsernameArray)

Description

Use the ShareAttachment function to share files in Oracle Content and Experience Cloud (CEC).

Parameters

Field or Control

Definition
URLID

Specifies an Oracle Content Cloud.
DirAndFilePrefix

A directory and file name prefix. This is appended to the URLID parameter to get the actual file for sharing.

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

Specifies the URL to access the file that is being shared.
ShareMode

Specifies the sharing mode assigned to a user.

The following modes of sharing are supported:

  • %ShareMode_Member - Use this sharing mode to allow access as a member to the folder, which contains the specified file. The link to access the file is updated in the ShareURL parameter.

  • %ShareMode_PublicRegisteredUsers - Use this sharing mode to allow access as a public registered user, who can access the file if the user has a cloud account. The link to access the file is updated in the ShareURL parameter.

  • %ShareMode_PublicAnyone - Use this sharing mode to allow anyone having access to the Web. The link to access the file is updated in the ShareURL parameter.

If no value is passed for this parameter, %ShareMode_PublicRegisteredUsers access is assumed.

This is an optional parameter.
ShareRole

Specifies the role assigned to a user that allows user to view a file, download a file, and modify a file.

The following roles are supported:

  • %ShareRole_Viewer - allowed to view a file online.

  • %ShareRole_Downloader - allowed to download a file.

  • %ShareRole_Contributor - allowed to modify a file.

If no value is passed for this parameter, %ShareRole_Viewer role is assumed.

This is an optional parameter.
ExpirationDateTime

This parameter is used only when the sharing mode is %ShareMode_PublicAnyone or %ShareMode_PublicRegisteredUsers.

If a valid date and time are not passed, a public link URL that never expires is created.

This is an optional parameter.
AccessToken

AccessKey is set in the public link that is generated.

This parameter is used only when the sharing mode is %ShareMode_PublicAnyone or %ShareMode_PublicRegisteredUsers.

If the GENERATEACCESSKEY property is set to Y and

  • if you don't pass a string variable, the API fails.

  • if you pass an empty string variable, the API generates a random access key and sets it in this variable.

  • if you pass a non-empty string variable, the API uses that as the access key.

This is an optional parameter.
UsernameArray

Specifies users who are added as members to the folder, which contains the specified file.

This parameter is used only when the sharing mode is %ShareMode_Member.

If no value is passed in this parameter, an empty string array is assumed.

This is an optional parameter.

Returns

An integer value (0) irrespective of whether the function is successful or not.

Note: It is reserved for future use.

Example

Local array of string &user = CreateArrayRept("XYZ", 1);
Local string &url;
ShareAttachment(URLID.PAYSLIP, "PaySlips_XYZ", &url, %ShareMode_Member, %ShareRole_Downloader, , &dt, "", &user);

Syntax

ShouldSuppressCREF(CREF_URL)

Description

Note: The ShouldSuppressCREF function has been deprecated and is retained for backward compatibility only.

Use the ShouldSuppressCREF function to return a boolean value indicating whether the URL should be displayed in the particular conditional navigation context. If the return value is True, the URL should not be shown in the current context; when the return value is False, the URL can be shown in the current context.

Parameters

Field or Control

Definition
CREF_URL

Specifies the URL for a content reference as a string value.

Returns

A Boolean value.

Syntax

Sign(n)

Description

Use the Sign function to determine the sign of a number.

Parameters

Field or Control

Definition
n

A number value of which to determine the sign.

Returns

Returns a number value equal to:

  • 1 if n is positive

  • 0 if n is 0

  • -1 if n is negative

Example

The example sets &NUMSIGN to 1:

&NUMSIGN = Sign(25);

Syntax

Sin(angle)

Description

Use the Sin function to calculate the sine of the given angle (opposite / hypotenuse).

Parameters

Field or Control

Definition
angle

A value in radians.

Returns

A real number between -1.00 and 1.00.

Example

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

&MY_RESULT = Sin(1.2);

Syntax

SinglePaymentPV(int_rate, n_per)

Description

Use the SinglePaymentPV function to calculate the future value of a single monetary unit after a specified number of periods at a specified interest rate.

Parameters

Field or Control

Definition
int_rate

A number representing the interest rate at which value is accrued per period.
n_per

A number specifying the number of periods on which to base the calculated value.

Returns

Returns a number value equal to the value of the unit after n_per periods at an interest rate of int_rate per period.

Example

The example calculates &PMT as .857338820301783265:

&PMT = SinglePaymentPV(8, 2);

Syntax

SortScroll(level, scrollpath, sort_fields)

Where scrollpath is:

[Record.level1_recname, [Record.level2_recname,] Record.target_recname

and where sort_fields is a list of field specifiers in the form:

[recordname.]field_1, order_1 [, [recordname.]field_2, order_2]. . .

Description

The SortScroll function programmatically sorts the rows in a scroll area on the active page. The rows can be sorted on one or more fields.

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

The type of sort done by this function, that is, whether it is a linguistic or binary sort, is determined by the Sort Order Option on the PeopleTools Options page.

Parameters

Field or Control

Definition
level

Integer specifying the level of the scroll to sort. It can be 1, 2, or 3.
scrollpath

A construction that specifies a scroll area in the component buffer.

sort_fields

A list of field and order specifiers which act as sort keys. The rows in the scroll area are sorted by the first field in either ascending or descending order, then by the second field in either ascending or descending order, and so on.
[recordname.]field_n

Specifies a sort key field in target_recname. The recordname prefix is required if the call to SortScroll is in a record other than target_recname.
order_n

A single-character string. "A" specifies ascending order; "D" specifies descending order.

Returns

Optionally returns a Boolean value indicating whether the function executed successfully.

Example

The first example repopulates a scroll in a page programmatically by first flushing its contents, selecting new contents using ScrollSelect, then sorting the rows in ascending order by EXPORT_OBJECT_NAME: 

Function populate_scrolls;
   ScrollFlush(Record.EXPORT_OBJECT);
   ScrollSelect(1, Record.EXPORT_OBJECT, Record.EXPORT_OBJECT, 
               "where export_type = :EXPORT_TYPE_VW.EXPORT_TYPE");
   SortScroll(1, Record.EXPORT_OBJECT, EXPORT_OBJECT.EXPORT_OBJECT_NAME, "A");
End-function;

The second example sorts the rows on scroll level one by primary and secondary key fields:

SortScroll(1,Record.EN_BOM_COMPS,EN_BOM_COMPS.SETID,"A",
   EN_BOM_CMOPS.INV_ITEM_ID,"A");

Syntax

Split(string, separator)

Description

Use the Split function to convert a string into an array of strings by looking for the string separator in the given string.

Note: Split does not split an array.

If separator is omitted, a blank is used.

If separator is a null string (""), the string is split into single characters.

If separator is the last character in the string, you will not get an empty string. For example, in the following code, &array only has a value of 2:

&test = "value1:value2:";

&array = Split(&test, ":");

Parameters

Field or Control

Definition
string

The string to be converted into an array
separator

The character used for dividing the string.

Returns

Returns a reference to the array.

Example

The following code produces in &AS the array ("This", "is", "a", "simple", "example.").

&STR = "This is a simple example.";
&AS = Split(&STR);

Syntax

SQLExec({sqlcmd | SQL.sqlname}, [bindexprs [, outputvars]])

where bindexprs is a list of expressions, one for each :n reference within sqlcmd or the text found in the SQL defintion sqlname, in the form:

inexpr_1 [, inexpr_2]. . .

and where outputvars is a list of variables, record fields, or record object references, one for each column selected by the SQL command, in the form:

out_1 [, out_2]. . .

Description

Use the SQLExec function to execute a SQL command from within a PeopleCode program by passing a SQL command string. The SQL command bypasses the Component Processor and interacts with the database server directly. If you want to delete, insert, or update a single record, use the corresponding PeopleCode record object method.

If you want to delete, insert, or update a series of records, all of the same type, use the CreateSQL or GetSQL functions, then the Execute SQL class method.

Note: SQLExec opens a new database cursor each time it executes.

Limitation of SQLExec SELECT Statement

SQLExec can only Select a single row of data. If your SQL statement (or your SQL.sqlname statement) retrieves more than one row of data, SQLExec sends only the first row to its output variables. Any subsequent rows are discarded. This means if you want to fetch only a single row, SQLExec can perform better than the other SQL functions, because only a single row is fetched. If you need to SELECT multiple rows of data, use the CreateSQL or GetSQL functions and the Fetch SQL class method. You can also use ScrollSelect or one of the Select methods on a rowset object to read rows into a (usually hidden) work scroll.

Note: The PeopleSoft record name specified in the SQL SELECT statement must be in uppercase.

Limitations of SQLExec UPDATE, DELETE, and INSERT Statements

SQLExec statements that result in a database update (specifically, UPDATE, INSERT, and DELETE) can only be issued in the following events:

  • SavePreChange

  • WorkFlow

  • SavePostChange

  • FieldChange

Remember that SQLExec UPDATEs, INSERTs, and DELETEs go directly to the database server, not to the Component Processor (although SQLExec can look at data in the buffer using bind variables included in the SQL string). If a SQLExec assumes that the database has been updated based on changes made in the component, that SQLExec can be issued only in the SavePostChange event, because before SavePostChange none of the changes made to page data has actually been written back to the database.

Setting Data Fields to Null

SQLExec does not set Component Processor data buffer fields to NULL after a row not found fetching error. However, it does set fields that aren’t part of the Component Processor data buffers to NULL. Work record fields are also reset to NULL.

Using Meta-SQL in SQLExec

Different DBMS platforms have slightly different formats for dates, times, and date/times; and PeopleSoft has its own format for these data types as well. Normally the Component Processor performs any necessary conversions when platform-specific data types are read from the database into the buffer or written from the buffer back to the database.

When a SQLExec statement is executed, these automatic conversions do not take place. Instead, you need to use meta-SQL functions inside the SQL command string to perform the conversions. The basic types of meta-SQL functions are:

  • General functions that expand at runtime to give you lists of fields, key fields, record fields, and so on. %InsertSelect or %KeyEqual are typical examples.

  • In functions that expand at runtime into platform-specific SQL within the WHERE clause of a SELECT or UPDATE statement or in an INSERT statement. %DateIn is a typical example.

  • Out functions that expand at runtime into platform-specific SQL in the main clause of SELECT statement. %DateOut is a typical example.

Following is an example of a SQL SELECT using both and "in" and "out" metastring:

select emplid, %dateout(effdt) from PS_CAR_ALLOC a where car_id = '" | &REGISTRATION_NO | "' and plan_type = '" | &PLAN_TYPE | "' and a.effdt = (select max (b.effdt) from PS_CAR_ALLOC b where a.emplid=b.emplid and b.effdt <= %currentdatein) and start_dt <= %currentdatein and (end_dt is null or end_dt >= %currentdatein)";

See Understanding Meta-SQL.

Bind Variables in SQLExec

Bind variables are references within the sqlcmd string to record fields listed in bindvars. Within the string, the bind variables are integers preceded by colons:

 :1, :2,. . .

The integers need not in numerical order. Each of these :n integers represents a field specifier in the bindvars list, so that :1 refers to the first field reference in bindvars, :2 refers to the second field reference, and so on.

For example, in the following statement:

SQLExec("Select sum(posted_total_amt) 
   from PS_LEDGER 
   where deptid between  :1 and :2", DEPTID_FROM, DEPTID_TO, &SUM);

:1 is replaced by the value contained in the record field DEPTID_FROM; :2 is replaced by the value contained in the record field DEPTID_TO.

Note the following points:

  • Bind variables can be used to refer to long character (longchar) fields. Long character fields are represented in PeopleCode as strings. You should use %TextIn() meta-SQL to ensure these fields are represented correctly on all database platforms.

  • Bind variables can be passed as parameters to meta-SQL functions, for example:

    SQLExec(". . .%datein(:1). . .", START_DT, &RESULT)

  • If a bind variable :n is a Date field that contains a null value, SQLExec replaces all occurrences of ":n" located before the first WHERE clause with "NULL" and all occurrences of "= :n" located after the first WHERE to "IS NULL".

Inline Bind Variables in SQLExec

Inline bind variables are included directly in the SQL string in the form:

:recordname.fieldname

The following example shows the same SQLExec statement with standard bind variables, then with inline bind variables:

Rem without Inline Bind Variables;
SQLExec("Select sum(posted_total_amt) 
   from PS_LEDGER 
   where deptid between  :1 and :2", deptid_from, deptid_to, &sum); 
Rem with Inline Bind Variables;
SQLExec("Select sum(posted_total_amt) 
   from PS_LEDGER 
   where deptid between  :LEDGER.DEPTID_FROM 
   and :LEDGER.DEPTID_TO",  &sum);

Inline bind variables, like all field and record references enclosed in strings, are considered by PeopleTools as a "black box". If you rename records and fields, PeopleTools does not update record and field names that are enclosed in strings as inline bind variables. For this reason, you should use standard bind variable in preference to inline bind variables wherever standard bind variables are available (as they are in SQLExec).

Prior to PeopleTools 8.0, PeopleCode replaced runtime parameter markers in SQL strings with the associated literal values. For databases that offer SQL statement caching, a match was never found in the cache so the SQL had to be re-parsed and re-assigned a query path. However, with PeopleTools 8.0, PeopleCode passes in bind variable parameter markers. For databases with SQL caching, this can offer significant performance improvements.

If you use inline bind variables, they will still be passed as literals to the database. However, if you convert them to bind variables, you may see significant performance improvements.

Output Variables in SQLExec

If you use SQLExec to Select a row of data, you must place the data into variables or record fields so that it can be processed. You list these variables or fields, separated by commas in the output part of the statement following the bindvars list. Supply one variable or field for each column in the row of data retrieved by SQLExec. They must be listed in the same order in which the columns will be selected.

The number of output variables cannot exceed 64.

Selecting Columns with Leading Spaces

When you execute a select SQL statement that returns data from a Character type column that has leading spaces, leading spaces are removed from the resulting text. If the column is a Long Character type, leading spaces are not removed.

Using Arrays for Bind Variables

You can now 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 generally used when you do not know how many values are needed until the code runs.

For example, suppose that you had some PeopleCode that dynamically (that is, at runtime) generated the following SQL statement:

&Stmt = "INSERT INTO PS_TESTREC (TESTF1, TESTF2, TESTF3, TESTF4, . . . N) VALUES (:
1, :2, %DateTimeIn(:3), %TextIn(:4), . . .N)";

Suppose you have placed the values to be inserted into an Array of Any, say &AAny:

&AAny = CreateArrayAny("a", 1, %DateTime, "abcdefg", . . .N);

You can execute the insert by:

SQLExec(&Stmt, &AAny);

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.

SQLExec Maintenance Issues

SQLExec statements are powerful, but they can be difficult to upgrade and maintain. If you use a SQL string passed in the command, it’s considered a "black box" by PeopleCode. If field names or table names change during an upgrade, table and field references within the SQL string are not updated automatically. For these reasons, you should use a SQL definition and the meta-SQL statements provided in PeopleTools 8.0, instead of typing in a SQL string.

Generally, you should use SQLExec only when you must interact directly with the database server and none of the ScrollSelect functions, or record class methods (which are somewhat easier to maintain) will serve your purpose effectively.

Be Careful How You Use It

SQLExec performs any SQL statement the current Access ID has database privileges to perform. This normally includes SELECT, INSERT, UPDATE, and DELETE statements against application data tables. However, you can set up users to use Access IDs with more privileges (typically, AccessIDs have full database administrator authority). In such cases, the user could alter the structure of tables using SQLExec, or even drop the database.

Warning! The PeopleSoft application will not stop the end user from doing anything that the Access ID has privileges to do on the database server, so be very careful what you write in a SQLExec statement.

Parameters

Field or Control

Definition
sqlcmd | SQL.sqlname

Specify either a String containing the SQL command to be executed or a reference to an existing SQL definition. This string can include bind variables, inline bind variables, and meta-SQL.
bindexprs

A list of expressions, each of which corresponds to a numeric (:n) bind variable reference in the SQL command string. It can also be a reference to a record object or an array of Any containing all the bind values. See Bind Variables in SQLEXEC for more details.
outputvars

A list of PeopleCode variables or record fields to hold the results of a SQL SELECT. There must be one variable for each column specified in the SELECT statement. It can also be a reference to a record object or an Array of Any that contains all the selected values.

Returns

Optionally returns a Boolean value indicating whether the function executed successfully.

Note: Not returning a row is not considered an error. If this is a concern, consider using the %SqlRows system variable after your call to SQLExec.

Example

The following example, illustrates a SELECT statement in a SQLExec:

SQLExec("SELECT COUNT(*) FROM PS_AE_STMT_TBL WHERE AE_PRODUCT = :1 AND AE_APPL_ID =
 :2 AND AE_ADJUST_STATUS = 'A' ", AE_APPL_TBL.AE_PRODUCT, AE_APPL_TBL.AE_APPL_ID,
 AE_ADJ_AUTO_CNT);

Note the use of bind variables, where :1 and :2 correspond to AE_APPL_TBL.AE_PRODUCT and AE_APPL_TBL.AE_APPL_ID. AE_ADJ_AUTO_CNT is an output field to hold the result returned by the SELECT.

The next example is also a straightforward SELECT statement, but one which uses the %datein meta-SQL function, which expands to appropriate platform-specific SQL for the :5 bind variable:

 SQLExec("SELECT 'X', AE_STMT_SEG FROM PS_AE_STMT_B_TBL where AE_PRODUCT = :1 AND
 AE_APPL_ID = :2 AND AE_SECTION = :3 AND DB_PLATFORM = :4 AND EFFDT = %datein(:5)
 AND AE_STEP = :6 AND AE_STMT_TYPE = :7 AND AE_SEQ_NUM = :8", AE_STMT_TBL.AE_
PRODUCT, AE_STMT_TBL.AE_APPL_ID, AE_STMT_TBL.AE_SECTION, AE_STMT_TBL.DB_PLATFORM,
 AE_STMT_TBL.EFFDT, AE_STMT_TBL.AE_STEP, AE_STMT_TBL.AE_STMT_TYPE, &SEG, &EXIST,
 &STMT_SEG);

This last example (in SavePreChange PeopleCode) passes an INSERT INTO statement in the SQL command string. Note the use of a date string this time in the %datein meta-SQL, instead of a bind variable:

SQLExec("INSERT INTO PS_AE_SECTION_TBL ( AE_PRODUCT, AE_APPL_ID, AE_SECTION, DB_
PLATFORM, EFFDT, EFF_STATUS, DESCR, AE_STMT_CHUNK_SIZE, AE_AUTO_COMMIT, AE_
SECTION_TYPE ) VALUES ( :1, :2, :3, :4, %DATEIN('1900-01-01'), 'A', ' ', 200,
 'N', 'P' )", AE_APPL_TBL.AE_PRODUCT, AE_APPL_TBL.AE_APPL_ID, AE_SECTION, DB_
PLATFORM);

In the following example, a SQLExec statement is used to select into a record object. 

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 */

Syntax

SQRT(n)

Description

Use the Sqrt function to calculate the square root of a number.

Parameters

Field or Control

Definition
n

A number of which you want to find the square root.

Returns

Returns a number equal to the positive square root of n. If n is a negative number, Sqrt displays an error.

Example

The examples return 15, 4, and 8.42615, respectively:

&NUM = Sqrt(225);
&NUM = Sqrt(16);
&NUM = Sqrt(71);

Syntax

StartWork()

Description

Use the StartWork function to mark the start of a unit of work.

Once this function is executed, no updates to the database are allowed until a unit of work is completed. A unit of work is completed by an event completing (such as a FieldChange event) in which case all the Updates are saved.

A unit of work can also be completed using the CommitWork built-in function.

If a SQL failure occurs anytime during the unit of work, after the StartWork function has been called and before the unit of work completes, all updates are rolled back, up to when the StartWork function was executed.

This function can be used for nested component interface calls, such that if the lower level component interface fails, any database changes made by the calling component interface can be rolled back.

Parameters

None.

Returns

None.

Example

&oCI = &SESSION.GetCompIntfc(CompIntfc.CUSTOMER); 
    
   If &oCI <> Null Then       
      . 
      . 
      . 
      For &i = 1 To &rsCustomer.RowCount          
         &recCust = &rsCustomer(&Transaction).GetRecord(Record.CUSTOMER); 
         StartWork();          
         If &oCI.Create() Then 
             rem ***** Set CI Properties *****; 
      . 
         . 
         . 
             If Not &oCI.Save() Then 
                 rem ***** Error Handling *****; 
                 ..... 
             End-If; 
         End-If; 
 
         rem ***** CommmitWork ensures that all transactions between     *****; 
         rem ***** StartWork and CommitWork get committed to the database *****; 
 
         CommitWork(); 
 
         &oCI.Cancel(); 
      . 
      . 
      . 
      End-For; 
   End-If

Description

Use the Step keyword in for loops. See For for more information.

Syntax

StopFetching()

Description

The StopFetching function is called during Row Select processing, during which rows of data that have been selected down from the database can be filtered as they are added to the component. This function is valid only in RowSelect PeopleCode. If StopFetching is called without DiscardRow, it adds the current row to the component, then stops adding any more rows. If StopFetching is called with DiscardRow, the system skips the current row and stops adding rows to the component.

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

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

In row select processing, the following actions occur:

  1. The Component Processor checks for more rows to add to the component.

  2. The Component Processor initiates the RowSelect event, which triggers any RowSelect PeopleCode associated with the record field or component record.

    This enables PeopleCode to filter rows using the StopFetching and DiscardRow functions. StopFetching causes the system to add the current row to the component, and then to stop adding rows to the component. DiscardRow filters out a current row, and then continues the row select process.

  3. If neither the StopFetching nor DiscardRow function is called, the Component Processor adds the rows to the page and checks for the next row.

    The process continues until there are no more rows to add to the component buffers. If both StopFetching and DiscardRow are called, the current row is not added to the page, and no more rows are added to the page.

Image: Row Select Processing Logic

The following flowchart shows this row select processing logic:

Row Select Processing Logic

Returns

None.

Syntax

StoreSQL(sqlstring, [SQL.]sqlname[, dbtype[, effdt [, ownerid [, description]]]])

Description

Use the StoreSQL function to write the given sqlstring value to a SQL definition, storing it under the name sqlname, with the database type dbtype and the effective date effdt. If sqlname is a literal name, it must be in the form SQL.sqlname or in quotes ("sqlname").

To specify a generic statement, that is, one that is overridden by any other matching statement, specify dbtype as Default and effdt as the null date (or Date(19000101).

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

Parameters

Field or Control

Definition
sqlstring

Specify the SQL string to be saved as the SQL definition. This parameter takes a string value.
sqlname

Specify the name of the SQL definition to be created. This is either in the form SQL.sqlname or a string value giving the sqlname.

dbtype

Specify the database type to be associated with the SQL definition. This parameter takes a string value. If dbtype isn’t specified or is null (""), it is set by default to the current database type (the value returned from the %DbName system variable.)

Values for dbtype are as follows. These values are not case-sensitive:

  • APPSERVER

  • DB2

  • DB2UNIX

  • MICROSOFT

  • ORACLE

Note: Database platforms are subject to change.
effdt

Specify the effective date to be associated with the SQL definition. If effdt isn’t specified, it is set by default to the current as of date, that is, the value returned from the %AsOfDate system variable.
ownerid

Specify the four character ownerId associated with this SQL statement. If not specified, no ownerId is associated.
description

Specify the description text associated with this SQL statement.

Returns

None.

Example

The following code stores the select statement as a SQL definition under the name SELECT_BY_EMPLID, for the current database type and effective as of the current as of date:

StoreSQL("%Select(:1) where EMPLID = :2", SQL.SELECT_BY_EMPLID);

Syntax

String(value)

Description

Use the String function to convert any non-string data type (except an object data type) to a string.

Normally the Component Processor automatically handles data type conversions. However, for some operations, such as comparisons, you want to specify the data type explicitly. Assume, for example, that you have two fields FIELD_I and FIELD_J containing number values 5000 and 10000. As character fields, 10000 is less than 5000 (because the first character in 10000 is less than the first character in 5000). As numbers, however, 10000 is of course greater than 5000.

Note: Due to the internal representation of numbers, sometimes String represents numbers differently. If you want to control exactly how a number is represented, use the NumberToString function.

Parameters

Field or Control

Definition
value

A value of any data type other than an object data type, to be converted to its String representation.

Returns

Returns a String value representing value.

Example

To force the comparison of the two fields as strings, you could use:

if string(FIELD_1) > string(FIELD_2). . .

You can use the String function with a field object as follows:

&DATE = GetRecord(RECORD.DERIVED_HR).GetField(FIELD.EFFDT); 
&STR = String(&DATE.Value);

Syntax

StripOffHTMLTags(HTML_text)

Description

Use the StripOffHTMLTags function to remove all HTML tags in an HTML-formatted string and return plain text. First, the function removes all tags in the form of <tag_name>. Then, the function decodes six specific HTML entities into their plain text character equivalents:

HTML Entity

Character

Unicode Character Name

&quot;

"

Quotation mark

&amp;

&

Ampersand

&lt;

<

Less than sign

&gt;

>

Greater than sign

&#039;

'

Apostrophe, single quote

&nbsp;

Non-breaking space

If the HTML string was generated by the rich text editor, any < and > characters in the original text are not stripped because the rich text editor generates these as &lt; and &gt;, respectively, which are in turn decoded back to their plain text equivalents by this function.

Warning! Do not use StripOffHTMLTags to prevent cross-site scripting (XSS). In fact, the string returned by StripOffHTMLTags should be re-encoded using the EscapeHTML function before sending to the browser because the decoding performed by the function can activate XSS injection.

Parameters

Field or Control

Definition
HTML_text

A text string with HTML tags and entities.

Returns

A string value.

Example

local string &HTML_text = "<B>This is a <i> test HTML string.";
local string &plain_text;
&plain_text = StripOffHTMLTags(&HTML_text);

The output plain text string is:

This is a  test HTML string.

Syntax

Substitute(source_text, old_text, new_text)

Description

Use the Substitute function to replace every occurrence of a substring found in a string with a new substring. To replace text that occurs in a specific location in a text string use the Replace function.

Parameters

Field or Control

Definition
source_text

A String in which you want to replace substrings.
old_text

A String equal to the substring of source_text you want to replace.

A tilde character (~) used in the old_text parameter stands for an arbitrary number of white spaces. For example, the following substitution: Substitute("2003* 0723* * * * ~", "* ~", "~") produces the result 2003~0723~~~~~, not the result 2003* 0723* * * ~.
new_text

A String with which to replace occurrences of old_text in source_text.

Returns

Returns a String resulting from replacing every occurrence of old_text found in source_text with new_text.

Example

The following example changes "Second Annual Conference" to "Third Annual Conference":

&newstr = Substitute("Second Annual Conference","Second","Third");

The next example sets &newstr to "cdcdcd":

&newstr = Substitute("ababab", "ab", "cd");

Syntax

Substring(source_str, start_pos, length)

Description

Use the Substring function to extract a substring of a specified number of characters beginning at a specified location in a source string. If the string contains Unicode non-BMP characters, each code unit of the surrogate pair is counted as a separate character, care should be taken not to split a surrogate pair using Substring.

If you know the exact length of source_str, and that it is null terminated, you can set length to 1 plus the exact length of source_str to get everything from start_pos to the end.

Parameters

Field or Control

Definition
source_str

A String from which to extract a substring.
start_pos

A number representing the character position in source_str where the substring starts, starting at 1.
length

A number specifying the number of characters in the substring.

Returns

Returns a String equal to a substring length characters long beginning at character start of source_str.

Example

This example sets &PAGE_NAME to the first eight characters of the name of the current page: 

&PAGE_NAME = Substring(%page,1,8);

Syntax

Substringb(source_str, start_pos, length)

Description

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

Syntax

SwitchUser(UserID, Password, AuthToken , ExtAuthInfo)

Note: Password is not encrypted: it is passed as a string.

Description

Use the SwitchUser function to change the user ID of the current user logged onto the PeopleSoft system.

Note: SwitchUser changes the Portal user rather than the content specific user. This means it changes the user ID in all databases to which the user is connected.

Note: If you use SwitchUser with the AuthToken parameter, the local Integration Broker node must have a Password or Certificate Authentication option. If the local Integration Broker node authentication option is None, SwitchUser always fails and returns false.

The SwitchUser function might be used as follows. Suppose there is a special user ID in the system called REGIST. REGIST only has access to the self-registration component. The self-registration component has logic that asks the user a list of questions and information based on data in the database. Are you a customer, vendor, or employee? Enter your customer name. Enter other information related to this customer account (such as information only this customer knows or information this customer just received from a workflow email). After the program verifies the information, create a User ID for this customer. After the user ID is created, the program should take the user directly into their transaction without having to logoff, by using SwitchUser.

Considerations Using SwitchUser

You must never call SwitchUser from Signon PeopleCode. SwitchUser calls Signon PeopleCode, therefore creating an infinite loop.

Do not use SwitchUser in Application Engine or in asynchronous notification PeopleCode.

Do not use SwitchUser in a Component Interface. The user is only switched for the duration of the service call. During the next call, the user reverts to the original user.

Do not try to use the PeopleCode Debugger with the SwitchUser function. Only the first user is logged into the PeopleCode Debugger. Once the switch occurs, any breakpoints, logging, and so on, are no longer executed.

Parameters

Field or Control

Definition
UserID

Specify the User ID to be started. This parameter takes a string value.
Password

Specify the Password for this User ID. This parameter takes a string value.

Note: Password is not encrypted: it is passed as a string.
AuthToken

Specify a single signon authentication token used to authenticate the user. If you are authenticating the user by Userid and password, specify a NULL value for this parameter, that is, two quotation marks with no blank space between them (""). If you specify a token, and the token is valid, SwitchUser switches to the User ID embedded in the token. All other parameters are ignored if a token is used. This parameter takes a string value.
ExtAuthInfo

Specify binary data (encoded as a base64 string) used as additional input to authenticate the user. If your application doesn't use external authentication information, specify a NULL value for this parameter, that is, two quotation marks with no blank space between them ("").

Returns

A Boolean value: True if user ID is switched successfully, False otherwise.

Example

The most common use of SwitchUser specifies only a Userid and Password. If the SwitchUser function executes successfully, you should check to see if the password for the new user id has expired. 

If Not SwitchUser("MYUSERID", "MYPASSWORD", "", "") Then 
   /* switch failed, do error processing */ 
Else 
   If %PasswordExpired Then 
      /* application specific processing for expired passwords */ 
   End-If; 
End-If;

Syntax

SyncRequestXmlDoc(&XmlDoc, Message.MessageName [, Node.NodeName])

Description

Use the SyncRequestXmlDoc function to send a synchronous message that is based on an XmlDoc object.

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

See SyncRequest.

The XmlDoc object must already be instantiated and populated. The message included in the function call should be an unstructured message, that is, one that isn't based on a hierarchical record structure.

If you want to handle an XmlDoc as a Message object, you need to define a Message object with a hierarchical structure and migrate the data in the XmlDoc object into the Message object.

Parameters

Field or Control

Definition
&XmlDoc

Specify an already instantiated and populated XmlDoc object that you want to send as a synchronous message.
MessageName

Specify an already existing nonrowset-based message, prefixed with the reserved word Message.
NodeName

Specify a node. This is for Sender Specified Routing (SSR) prefixed with the reserved word Node. The node defines the target for the published message.

Returns

A reference to an XmlDoc object that is the response.

Example

Local XmlDoc &reqdoc, &respdoc;
. . .
&respdoc = SyncRequestXmlDoc(&reqdoc, Message.MY_MESSAGE, Node.MY_NODE);