SAP Function F4IF_INT_TABLE_VALUE_REQUEST - F4 help also returning the value to be displayed in internal table

Parameter Reference Type Length Default Optional Text
CALLBACK_FORM SYST-XFORM C 30 SPACE X Form for callback before F4 start (-> long docu)
CALLBACK_METHOD REF TO IF_F4CALLBACK_VALUE_REQ 0 X Interface for Callback Routines
CALLBACK_PROGRAM SYST-REPID C 40 SPACE X Program for callback before F4 start
DDIC_STRUCTURE TABNAME C 30 SPACE X Structure of VALUE_TAB (VALUE_ORG = 'S')
DISPLAY DDBOOL_D C 1 SPACE X Override readiness for input
DYNPNR SYST-DYNNR C 4 SPACE X Screen number
DYNPPROG SYST-REPID C 40 SPACE X Current program
DYNPROFIELD HELP_INFO-DYNPROFLD C 132 SPACE X Name of screen field for value return
MARK_TAB DDSHMARKS h 4 X Defaults for Selected Lines when Multiple Selection is Switched On
MULTIPLE_CHOICE DDBOOL_D C 1 SPACE X Switch on multiple selection
PVALKEY DDSHPVKEY C 61 SPACE X Key for personal help
RETFIELD DFIES-FIELDNAME C 30 Name of return field in FIELD_TAB
STEPL SYST-STEPL I 4 0 X Steploop line of screen field
VALUE HELP_INFO-FLDVALUE C 255 SPACE X Field contents for F4 call
VALUE_ORG DDBOOL_D C 1 'C' X Value return: C: cell by cell, S: structured
WINDOW_TITLE C C 0 X Title for the hit list

Parameter Reference Type Length Text
USER_RESET C C 0 Single-Character Flag

Parameter Reference Length Optional Text
DYNPFLD_MAPPING DSELC 396 X Assignment of the screen fields to the internal table
FIELD_TAB DFIES 675 X Fields of the hit list
RETURN_TAB DDSHRETVAL 328 X Return the selected value
VALUE_TAB 0 Table of values: entries cell by cell

Exception Text
NO_VALUES_FOUND No values found
PARAMETER_ERROR Incorrect parameter

Functionality
This module implements the standard help at POV while passing thevalues to be displayed in a table. The entire dialogue behaves as for astandard F4 help. This module also supports input help control.
Note: Before you use this module at POV (Process on Value-Request),reconsider whether a search help could not carry out the same task. Youcan implement self-defined value selection in a search help exit. Thishas the advantage that you can attach the search help to a data elementor a field of a structure. The F4 help is then automatically availablefor all users of the data element or structure.
The values to be displayed are passed in table VALUE_TAB. There aredifferent ways to organize the data in VALUE_TAB. These are mainlydefined with the parameter VALUE_ORG.
VALUE_ORG = 'S' (Structure)
This option should be used for new developments (despite otherdefault values).
VALUE_TAB is an internal table with a (flat) structure. Every line inVALUE_TAB then corresponds to one line in the list to be displayed.
How the definition of the data struture is passed to the module isdescribed below.
The data in VALUE_TAB is available in internal representation.
VALUE_ORG = 'C' (Column)
Each line of VALUE_TAB contains the contents of a single field. Thecontents of VALUE_TAB are copied to the hit list line by line. Thedescription of the columns is passed in FIELD_TAB. When all fields ofFIELD_TAB have been edited, the next line is processed.
In this case the values in VALUE_TAB must be passed in externalrepresentation. This means that for types whose external and internalrepresentation differ, the values should be passed to VALUE_TAB withthe ABAP command WRITE and not with MOVE (These are for example all thenumeric types, date, fields with conversion exit, etc.). Use theextension LEFT-JUSTIFIED for numbers.
Caution: Do not copy any constants directly to VALUE_TAB. For example,if a date is defined as constant "01.01.1998", it can no loner beinterpreted for other user-specific settings.

Definition of the data structure of VALUE_TAB.
Depending on how the internal table VALUE_TAB was defined, there aredifferent ways to pass this structure to the module.
In the end, the data structure is always stored internally in tableFIELD_TAB. In addition to passing the value directly in the call, thereare different ways for the module to fill the table automatically or toenhance the data automatically.
RESET N1
The structure of internal table VALUE_TAB is defined in the ABAPDictionary. For example the table is defined as follows:
DATA: VALUE_TAB LIKE OCCURS 0 [WITH HEADER LINE].
In this case it is sufficient to pass the name of the referencestructure to parameter DDIC_STRUCTURE. Table FIELD_TAB should not bepassed in this case because it is automatically filled with theinformation from the ABAP Dictionary in the function module.
Table FIELD_TAB only has to be defined instead of parameterDDIC_STRUCTURE if for example some of the fields of the structureshould not be displayed or if the order of the columns or header textsshould be changed.
If only fields TABNAME and FIELDNAME are filled in FIELD_TAB, themodule gets the remaining information from the ABAP Dictionary. As aresult you can easily choose individual fields and their order.
If you want to change text, you should fill FIELD_TAB initially usingthe module DDIF_FIELDINFO_GET. You canthen change for example the text in FIELD_TAB.
Table VALUE_TAB can for example be defined as follows:
DATA: BEGIN OF VALUE_TAB OCCURS 0,
FIELD1 LIKE ,
FIELD2 TYPE ,
"etc.
END OF VALUE_TAB.
If all the fields have an explicit reference to a DDIC field (mit LIKE)or to a data element (with TYPE), the module itself can determine thestructure of VALUE_TAB. In this case do not pass either DDIC_STRUCTUREor FIELD_TAB.
If you want to pass the field description with FIELD_TAB (for examplebecause you do not want to display all the fields), you normally shouldnot only fill TABNAME and FIELDNAME. The module then gets all theinformation from the ABAP Dictionary. This also includes the relativeposition of a field to the beginning of the Dictionary structure.However, this usually will not agree with the relative position of thefield in VALUE_TAB.
In this case it is better to fill table FIELD_TAB using moduleDDIF_FIELDINFO_GET. The relative position of the fields in VALUE_TABshould then be corrected in FIELD_TAB-OFFSET. You can use for examplethe ABAP command DESCRIBE DISTANCE here.
The table has only one field that holds the values column by column.'C' is passed as VALUE_ORG. The definition of VALUE_TAB could be forexample:
DATA: VALUE_TAB(100) TYPE C OCCURS 0 [WITH HEADER LINE].
The definition of the columns should be passed in FIELD_TAB. Again youcan limit yourself to TABNAME and FIELDNAME if the remaininginformation (type, length, headers) should be obtained from the ABAPDictionary.
The relative position of the fields to the beginning of the structure(FIELD_TAB-OFFSET) are of no importance for this type of data transfer.
Even if you want to pass the entire information in FIELD_TAB yourself,you nevertheless should first fill FIELD_TAB with DDIF_FIELDINFO_GETfrom the ABAP Dictionary. You can then change individual fields, suchas header text, before calling the module.
If you define parameter DDIC_STRUCTURE, FIELD_TAB is internally giventhe field description of the DDIC structure passed. This is normallymeaningless for column-by-column data transfer.
The field names in FIELD_TAB must be unique. If you need fields withthe same name from different structures, you should get the informationwith the function module DDIF_FIELDINFO_GET yourself and then changethe field name.

Return the selection in the screen
If the screen information DYNPPROG, DYNPNR, DYNPROFIELD and possiblySTEPL are also defined, the selected value is automatically returned inthe screen field.
If possible, you should always give this information because the amodalcontrol version of the F4 help can only be supported with thisinformation. A user who switches on the F4 help control does not see adifference between the standard F4 help and a help implemented withthis function module in this case.
If the user activates the ActiveX help, it is started amodally underthe following conditions:
1. The screen information DYNPPROG, DYNPNR and DYNPROFIELD must bedefined.
2. When the function module is called, the RETURN_TAB may not bedefined. (In an amodal call, the function module returns before theuser has selected a value).
Normally values are only returned in input fields. This behavior can bechanged with parameter DISPLAY (see parameter documentation).
With Release 4.6C the module can automatically recognize an inputfield.

Notes

  • DYNPPROG and DYNNR cannot be passed as SY-REPID and SY-DYNNR because
    • they are only analyzed after the function module has been called.Instead, first copy the SY fields to local variables and then pass themto the function module.
    • The value for STEPL is not within a step loop 0. Within a step loop,
      • the current line can be defined at time POV with the function moduleDYNP_GET_STEPL.
      • If you do not want to return the selected value automatically, you
        • should not define parameters DYNPPROG, DYNNR etc. A value is notreturned automatically if MULTIPLE_SELECTION is selected either, butthis could change in the future!
        • Calls that do not permit a value to be returned automatically can only
          • be implemented modally. The input help control nevertheless can be usedfor the display, but no other entries can be made in the screen as longas the popup window is displayed. The value is returned in tableRETURN_TAB. If the user terminates the F4 help, RETURN_TAB is returnedempty (termination does not result in an exception).

          Further information
          Also read the documentation for the parameters, especially for VALUEand CALLBACK_FORM.

          Description
          Parameter is returned with 'X' if the user has pressed "Deselect" onthe hit list with possible multiple selection, or the selected valueshave all been deselected individually.
          INCLUDE DDDOC_F4IF_CALLBACK_FORM OBJECT DOKU ID TX.

          Description
          With this parameter, you can pass a method that is called in a callbackcase alternatively to CALLBACK_FORM. For more information, refer to theparameter CALLBACK_FORM.
          This method must exist in the program CALLBACK_PROGRAM, analogous toCALLBACK_FORM.

          Default

          Description
          See the docu about parameter CALLBACK_FORM

          Description
          If the table passed as VALUE_TAB has a structure that was defined inthe ABAP Dictionary, the name of the structure can be specified here.
          In this case parameter FIELD_TAB is ignored.

          Description
          This parameter defines whether the F4 help should behave like an inputfield or like a pure display field.
          The F4 help for a field that is not an input field does not permit youto select values from the hit list.

          Value range
          SPACE: You can see if it is an input field from the screen field. Ifthe screen information is missing, the default value is input field.
          Caution: You can only reliablly determine whether input to a fieldis possible if the module is called at timepoint "ON VALUE REQUEST". Atother times (PBO/PAI) you are recommended to explicitly set parameter.
          'X': F4 help is called in display mode. It is not possible to selectvalues from the hit list.
          'F' (Force Input): The module also displays the selected value if thescreen field is not an input field.

          Default
          .

          Description
          Multiple selection is activated if this parameter has the value 'X'.
          You can also select multiple lines in the hit list.
          At the moment you cannot automatically reset the selected values inscreen fields if multiple selection is set. As a result, amodal dialogsare not provided.

          Description
          The values for the personal help are stored under this key. There isfirst a check whether the user stored personal help values under thiskey. If a personal value was stored, it is displayed instead of thevalue passed in VALUE_TAB.
          Leave the parameter empty if a personal help should not be displayed.
          If the help is only valid for a certain screen, you should define thekey from the program and screen number.
          If the F4 help is valid for more than one screen, you can also assignother keys. At the moment there is no mechanism that guarantees thatthe key is unique.

          Description
          The columns of the hit list normally correspond to the fields ofinternal table VALUE_TAB, but only one of these columns contains thevalue to be returned to the screen field when a line is selected.
          The field name for this column must be specified in RETFIELD. If thefield names in the table FIELD_TAB are transported, RETFIELD mustcorrespond to an entry in FIELD_TAB_FIELDNAME.

          Example
          Table VALUE_TAB consists of fields KEY and TEXT. When a line isselected from the hit list, the contents of column KEY should be copiedto the screen field or to table RETURN_TAB. Field name 'KEY' must thenbe passed as RETFIELD.

          Description
          Contents of the field when F4 is called. The contents are only copiedif they contain a wildcard. This corresponds to the behavior forstandard F4.
          If the parameter is assigned the default value SPACE, and the screeninformation (DYNPPROG, DYNPNR, STEPL) is available, the module itselfgets the current contents.
          With this internal table you can easily define that you want to returnother columns of the hit list in addition to field RETFIELD to thescreen.
          The table creates the link from the table fields to the screen fields.
          The components of DYNPFLD_MAPPING are as follows:
          FLDNAME: Field name from FIELD_TAB or from the structure given inDDIC_STRUCTURE (only field name without table name)
          FLDINH: Temporarily empty
          DYFLDNAME: Complete name of the screen field (possibly with table name)
          Note that the field names for the columns of VALUE_TAB are assignedinternally if neither DDIC_STRUCTURE nor FIELD_TAB are defined. Thefields are internally named F0001, F0002 etc. in this case.

          Description
          The selected value is returned in table RETURN_TAB if it is not copiedto screen fields in the module itself.
          Caution: Despite being called with RETURN_TAB, up to Release 4.6B thehelp is started amodally as soon as the screen information DYNPPROG,DYNPNR and DYNPROFIELD is passed and the user has activated the ActiveXhelp. In this case you cannot be sure that the RETURN_TAB contains theselected lines of the hit list. In an amodal call, the function moduleterminates before the user has made his choice.
          In most cases table RETURN_TAB has exactly one line containing thecontents of the return column from the selected line of the hit list infield FIELDVAL.
          If RETURN_TAB does not contain any lines, the user has terminated theselection.
          If there are multiple return columns or if multiple selection wasallowed, the table can contain more than one line.
          If there is more than one return column, FIELDNAME specifies the columnto which the value in FIELDVAL belongs. FIELDNAME corresponds to fieldFIELDNAME in table FIELD_TAB.
          With multiple selection (more than one line of the hit list isselected), field RECORDPOS is used to number the lines, i.e. if threelines were selected, all the columns of the first selected line arenumbered with RECORDPOS = 1, all the columns of the second line arenumbered wiith RECORDPOS = 2, etc.
          Field RETFIELD specifies the screen field belonging to the column if itis known. If there is only one return column, RETFIELD contains thefield name passed in DYNPROFIELD.
          Field SHLPNAME is not relevant for this module.