Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

Introduction

This article introduces the search helps in SAPGUI for Windows. It does not talk about search helps in Web Dynpros (though functionality is rather the same) and other technologies.

Search helps are the most common type of input helps (input helps show possible values for a field on request).
Note: because they are very common, the term search help may also refer in some documentations.
Search help is also known as value help and F4 help.
For example, a Calendar help (dates shown as a calendar) may be called a search help of type Calendar.

Search helps have replaced the matchcode technology since release 4.0. All matchcodes were migrated to search helps at this time.

User guide

Input fields with search help capability have a button displayed next to the input field when the cursor is located in the field:

The user may either click this button or press F4 key. A dialog box for value restriction may be displayed or not (in this latter case the hit list is directly displayed):

Here we see 2 tabs. The second tab shows other selection fields. This search help is called a collective search help, which contains 2 elementary search helps (tabs "Single Roles" and "Composite Roles").
The user may enter more selections or not, and he presses Enter.

The hit list is displayed, which shows possible values, and here the multi-selection is enabled:

Notes about the hit list:

  • By using the contextual menu "Insert in personal list", it is possible to build a list of favorites values for each search help.
  • The contextual menu "Personalize" allows the user to move or hide columns.
  • If the number of hits is greater than the maximum, a message is displayed. The user may increase it by changing the maximum in the dialog box for value restriction. By clicking the thin horizontal bar button above the list, the dialog box is displayed above it.

The user selects the line he wants and presses Enter, the value is returned into the input field:

F4 settings

To access F4 settings, either select menu Help | Settings in the menu bar, or use contextual menu "Personalize" from any hit list and choose tab "Settings for all F4 helps":

There are the following possible settings:

  • Display first either the personal list or all the values
  • If only one value is possible, it should be returned immediately without displaying the hit list
  • Maximum number of hits by default. It can be changed on search help dialog box for value restriction, if needed.
  • Maximum width
  • Display type : control (latest technology, as shown in screen captures in this article) or dialog (old list technology)

Creating a search help

Search helps (elementary and collective) are maintained via transaction SE11.

When you create a search help, you choose either Elementary or Collective:

Elementary search help

The Definition tab contains everything needed to define a search help:

Selection method (used to fill the hit list):

  • Database table, database view (inner join or not), help view (outer join)
  • You may also let it blank if you want to fill the hit list yourself
    Note that the text table is automatically filled when you enter a database table.

Dialog type (should we display the dialog box for value restriction):

  • Display values immediately : dialog box is not displayed
  • Dialog depends on set of values : works only with a selection method. If there are more than 100 records to display in the hit list, the dialog box is displayed
  • Dialog with value restriction : dialog box is displayed

Hot key:

  • If the search help is to be used within a collective search, this code can be used by users as a shortcut to enter in the input field, to skip the dialog box with value restriction. For example, by entering =A.S in the input field, it will select the elementary search help with "A" hot key, simulate S* in first selection criteria, and display the hit list.

Search help exit:

  • Optional function module. If entered, it must have these parameters:
    | *"  TABLES |  |
    | *"      SHLP_TAB TYPE  SHLP_DESCT | |
    | *"      RECORD_TAB STRUCTURE  SEAHLPRES | |
    | *"  CHANGING | |
    | *"     VALUE(SHLP) TYPE  SHLP_DESCR | |
    | *"     VALUE(CALLCONTROL) LIKE  DDSHF4CTRL STRUCTURE  DDSHF4CTRL | |
    
    Note: you may copy F4IF_SHLP_EXIT_EXAMPLE function module. It also contains a template with useful information.
    It is called several times, at different moments (before or after the display of the selection dialog box, before or after the display of the hit list, etc.) The input parameter CALLCONTROL-STEP must be used to know what moment it is so that to take the right actions.

Special moments (see below)

CALLCONTROL-STEP value

At which moment

Parameters (which can be changed)

 

SELONE

Called once at the beginning of the search help only if the F4 calls this elementary search help (otherwise SELONE triggers at collective search help exit)

SHLP and SHLP_TAB contain the elementary search help. Only changes to SHLP_TAB are taken into account

 

PRESEL1

Called each time an elementary search help tab gains focus (initially, and when user clicks on a tab in case of a collective search help). If the initial search help is elementary, this step is called once

SHLP contains the elementary search help definition

 

PRESEL

Called just before the dialog box is displayed. It's not called if the dialog box is not displayed

You may skip the dialog box by setting CALLCONTROL-STEP = 'DISP'

(1)

 

SELECT

Called just after dialog box criteria have been entered. It's not called if the dialog box is not displayed

 

(2)

 

DISP

Called just before the hit list is displayed

RECORD_TAB contains the hit list, you may change it (or initialize it when selection method is empty)

(3)

 

RETURN

Called just after a value has been selected from the hit list

 

Notes:

    • (1) The dialog box for value restriction is displayed between PRESEL and SELECT steps
    • (2) If the elementary search help contains a selection method, SAP reads database data between SELECT and DISP steps
    • (3) The hit list is displayed between DISP and RETURN steps
    • If the hit list has to be displayed directly, the PRESEL and SELECT steps are skipped

Parameters:

IMP

X = The input field value is passed to the search help

EXP

X = The input field has to be changed by the selected value from the hit list

LPos

Position in the hit list (0 = do not display)

SPos

Position in the dialog box (0 = do not display)

SDis

X = sets the field as Read-only in the dialog box (this field should be either defined as an importing parameter or with a default value )

Data element

Used to determine texts to display in dialog box and in hit list, and also to determine the F4 capability on it. It may be changed only if Modified is checked first, and it must belong to the same domain as the original field

Modified

X = allows to change the data element in SE11, see above

Default value

You may enter a value with quotes ('DEF') which is a default value DEF, or without quotes (DEF) which then corresponds to the memory ID DEF

Collective search help


Search help exit:

  • Same as for elementary search helps, but only these 2 steps exist:

    CALLCONTROL-STEP value

    At which moment

    Parameters (which can be changed)

    SELONE

    Called once at the beginning of the search help

    SHLP contains collective search help definition, and SHLP_TAB contains all included search helps. Only changes to SHLP_TAB are taken into account

    RETTOP

    Called just after the RETURN step of the elementary search help

     

Parameters:

  • They have the same meaning as for elementary search helps (but only IMP and EXP columns are available)
  • These parameters are used to communicate between the input field(s) and the elementary search helps, and vice versa
  • Relationships between these parameters and elementary search help parameters have to be defined in the next tab


Included search helps:

  • Enter a list of Elementary or Collective search helps.
    Note that all search helps in this hierarchy are displayed in the F4 dialog in a flat way as side-to-side tabs
  • For each included search help, you must map the fields between it and the collective search help

FAQ

Where is the search help to select files?

They don't exist, as files are not related to database. Instead, you must call:

  • For frontend files: methods CL_GUI_FRONTEND_SERVICES=>FILE_OPEN_DIALOG, or CL_GUI_FRONTEND_SERVICES=>FILE_SAVE_DIALOG
  • For application server files: function module F4_DXFILENAME_TOPRECURSION

How to select several lines at a time?

You must define a search help exit, and change CALLCONTROL-MULTISEL = 'X' before the hit list is displayed (note: MULTISEL is taken into account only when the hit list control is created)

How to keep the user from entering a value manually? (value can be entered only via F4)

Either, if the number of values is low, use a listbox field instead of a search help (and by using VRM_SET_VALUES function module, see SAP library)
Or :

  • Make the input field read-only
  • Define a "POV" event on the field, so that to execute custom code when F4 is pressed:
  • Call the search help programmatically (see below)
  • Update the input field by calling DYNP_VALUES_UPDATE function module (it's the only way to update a screen field during a POV event)

How to call a search help programmatically?

Call function module F4IF_FIELD_VALUE_REQUEST

How to display an internal table like a search help?

Call function module F4IF_INT_TABLE_VALUE_REQUEST

Links

1 Comment

  1. Its really Nice Collection,

    Thanks,

    Vijay