TransferExactTop function

Syntax

TransferExactTop(new_window, MenuName.MENU_NAME, BarName.BAR_NAME, ItemName.MENU_ITEM_NAME, Page.COMPONENT_ITEM_NAME, action [, keylist][, AutoSearch]))

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

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

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

&RecordObject1 [, &RecordObject2].  .  .

Description

Use the TransferExactTop function to exit the current context and transfer the user to another page using an exact match of all keys in the optional key list and by always replacing the current window. Use the TransferExactTop function as an alternative to the TransferExact function to ensure that when the source component is being displayed within a fluid wrapper (that is, the source component is being displayed within a fluid activity guide, a master/detail component, an interactive grouplet, or a modeless window) that the entire current window is replaced with the new content.

Unlike TransferExact, TransferExactTop ignores the new_window parameter. TransferExactTop always exits the current context and completely replaces the current window.

You can use TransferExactTop from a secondary page only if you’re transferring to a separate instance of a component. You cannot use TransferExactTop from a secondary page if you’re not transferring to a separate instance of a component.

If you provide a valid search key for the new page in the optional keylist, the new page opens directly, using the values provided from keylist as search key values. A valid key means that enough information is provided to uniquely identify a row: not all of the key values need to be provided. If no key is provided, or if the key is invalid, or if not enough information is provided to identify a unique row, the search page could be displayed (depending on the component), enabling the user to search for a row.

If MENU_NAME+BAR_NAME+MENU_ITEM_NAME+COMPONENT_ITEM_NAME is an invalid combination, an error message displays explaining that there were invalid transfer parameters.

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

The component item name is specified in the component definition, in the Item Name column on the row corresponding to the specific page, as shown here. In this example, the PERSONAL_DATA page name appears twice: once with an item name of PERSONAL_DATA_1, and once with the item name of PERSONAL_DATA_2.

Determining the component item name

Parameters

Parameter Description

new_window

Note: This parameter is ignored and has no effect.

MENU_NAME

The name of the menu where the page is located prefixed with the reserved word MenuName.

BAR_NAME

The name of the menu bar where the page is located prefixed with the reserved word BarName.

MENU_ITEM_NAME

The name of the menu item where the page is located prefixed with the reserved word ItemName.

COMPONENT_ITEM_NAME

The component item name of the page to be displayed on top of the component when it displays. The component item name is specified in the component definition. This parameter must be prefixed with the keyword Page.

action

Uses a single-character code as in %Action. Valid actions are "A" (add), "U" (update), "L" (update/display all), "C" (correction), and "E" (data entry).

[keylist]

An optional list of field specifications used to select a unique row at level zero in the page you are transferring to, by matching keys in the page you are transferring from. It can also be an already instantiated record object.

If a record object is specified, any field of that record object that is also a field of the search record for the destination component is added to keylist. The keys in the fieldlist must uniquely identify a row in the "to" page search record. If a unique row is not identified, or if Force Search Processing is selected for the component, the search dialog box appears.

If the keylist parameter is not supplied then the destination component's search key must be found as part of the source components level 0 record buffer.

AutoSearch

Specify whether an automatic search on the target search page is executed after the transfer. This means the search results are already shown without the end user having to click the Search button. This parameter takes a Boolean value: True, do an automatic search. The default value is False (that is, the user has to click the Search button).

Returns

None.

Example

Using the following PeopleCode program:

&MYREC = CreateRecord(RECORD.QEOPC_9A2FIELDS); 
&MYREC.QE_TITLE.Value = "KEY";

TransferTop(False, MenuName.QE_PEOPLECODE_PAGES, BarName.USE, ItemName.QEPC9PROPSTESTS, Page.QEOPC_9A2FIELDS, "U", &MYREC);

The following SQL is produced:

SELECT DISTINCT TOP 301 QE_TITLE, QEPC_ALTSRCH FROM PS_QEOPC_9A2FIELDS
WHERE QE_TITLE LIKE 'KEY%' ORDER BY QE_TITLE

If you change the TransferTop to TransferExactTop:

&MYREC = CreateRecord(RECORD.QEOPC_9A2FIELDS); 
&MYREC.QE_TITLE.Value = "KEY";

TransferExactTop(False, MenuName.QE_PEOPLECODE_PAGES, BarName.USE, ItemName.QEPC9PROPSTESTS, Page.QEOPC_9A2FIELDS, "U", &MYREC);

The following SQL is produced:

SELECT DISTINCT TOP 301 QE_TITLE, QEPC_ALTSRCH FROM PS_QEOPC_9A2FIELDS
WHERE QE_TITLE=:1 ORDER BY QE_TITLE

Differences Between TransferTop and TransferExactTop

When you do a transfer, the first thing the system checks is whether all the key field values for the target component are provided.

If all the keys aren't provided, the search page is displayed. In this scenario, TransferExactTop and TransferTop are the same.

If all the keys are provided, a Select is done against the search record for that component using those keys.

  • If you use the TransferTop function, a LIKE operator is used in the Where clause of that Select for each key.

  • If you use the TransferExactTop function, the equals operator is used in the Where clause for each key. Using equals allows the database to take full advantage of key indexes for maximum performance.

See Transfer function.

Restrictions on Using TransferExactTop

  • TransferExactTop cannot be used with an Internet script or an Application Engine program.

  • TransferExactTop is ignored (has no effect) when used by a PeopleCode program that’s been called by a component interface.

  • You can't use TransferExactTop in a SearchInit PeopleCode program.

Related Topics