Ansicht
Dokumentation

/VIRSA/TEXT_FOR_VALUE - DD: Define Text of a Value for an ABAP Dictionary Field

/VIRSA/TEXT_FOR_VALUE - DD: Define Text of a Value for an ABAP Dictionary Field

RFUMSV00 - Advance Return for Tax on Sales/Purchases   Fill RESBD Structure from EBP Component Structure  
This documentation is copyright by SAP AG.
SAP E-Book

Functionality

This module can be used to define the corresponding text for a value for a field defined in the ABAP Dictionary. The value for which the text should be defined must be passed in IMPORT parameter VALUE.The text belonging to this value can be returned in EXPORT parameter TEXT.

IMPORT parameter VALUE_IS_EXTERNAL can be used to define if the contents of VALUE should be interpreted in external or internal representation. In the first case, the actual parameter assigned to VALUE must have type C. In the second case, the parameter must have the same type as the field to be processed. If the parameter is of a different type, the result of the module is undefined.

The field to be handled must always be specified by referring to a field of the ABAP Dictionary. There are several mechanisms for defining this reference:

You can describe the field to be handled by specifying a reference to the ABAP Dictionary. In this case IMPORT parameter TABNAME must have a non-initial value. If IMPORT parameter FIELDNAME is not initial either, the ABAP Dictionary field thus described is used as reference. On the other hand, if FIELDNAME is initial, the data element specified by TABNAME is used as reference.
If the object thus referenced is not defined in the ABAP Dictionary, the exception NO_DDIC_FIELD is triggered.

On the other hand, if IMPORT parameter TABNAME is initial, the description of the field to be handled is taken directly from the program calling the function module. If the IMPORT parameter FIELDNAME is also initial, the definition of the actual parameter assigned to IMPORT parameter VALUE is assumed as reference. If this actual parameter was not created with reference to the ABAP Dictionary, the exception NO_DDIC_FIELD is triggered.

If parameter TABNAME is initial but parameter FIELDNAME is not, the name of the program calling the function module must be stored in IMPORT parameter CALLING_PROGRAM. The reference field must be defined in this program as a global field with a reference to the ABAP Dictionary. If the contents of IMPORT parameter STRUCNAME are not initial, there must be a field string with the name given by STRUCNAME having a field with the name given by FIELDNAME. This component is then used as reference field. On the other hand, if STRUCNAME is initial, there must be a field with the name given by FIELDNAME that is used as reference field. If there is no such specified reference field or if it does not have a reference to the ABAP Dictionary, the exception NO_DDIC_FIELD is triggered.

The text belonging to the given field contents is always defined in the logon language of the current user. The following mechanisms are used (in this order) to determine the text:

  1. The field in question is defined in the ABAP Dictionary with a reference to a domain having fixed values. The fixed value text belonging to the fixed value specified in VALUE is then defined.
  2. A foreign key is defined in the ABAP Dictionary for the field in question. In this case a text is only defined if the check table of the field has a text table. The text is taken from the dataset of the text table corresponding to the specified value.
  3. The field in question is the key field of a table having a text table and the check field of the corresponding text foreign key is checked against the field in question. The text is taken from the dataset of the text table corresponding to the specified value.

In cases 2 and 3, the contents of other foreign key fields might also be required to precisely specify the value whose text should be defined. There are several ways to give this module the contents of such a foreign key field:

  1. A line for the foreign key field can be passed in the CHANGING parameter ADDITIONAL_FIELDS. The foreign key field must be specified with the components TABNAME and FIELDNAME. A reference to a data object containing the value of the corresponding field must be passed in component VALUE. You must set the component to EXTERNAL if the value is defined in external representation. The component FOUND must also have the value 'X' to document that the foreign key field is really available.
  2. If the name of the calling program is passed in the IMPORT parameter CALLING_PROGRAM, the system tries to identify the foreign key fields that have no entry in ADDITIONAL_FIELDS as global variables in the calling program. This is the case if the names are the same. If IMPORT parameter STRUCNAME is not initial, the name it assigned is used instead of the name of the table to be checked. The contents of these variables are interpreted as internal representation of the contents of the foreign key fields.

If the system sees that mechanism 2 or 3 was used to determine the text, the CHANGING parameter ADDITIONAL_FIELDS contains the list of additional fields required after the call. Component FOUND shows whether it was possible to find a value at all for the field. Component VALUE contains a reference to a data object containing the value that was used for the field in internal representation (or initial value if no contents could be defined). If no contents can be defined for at least one required field using the above mechanism, EXPORT parameter TEXT is initial.

Example

A structured data object smacourse_wa of type SMACOURSE is defined in a program. You want to find the corresponding text for the contents of the data object. Use the following program segment here:

PROGRAM ZZTEST.
DATA smacourse_wa TYPE SMACOURSE. " Must be defined globally
DATA: repid TYPE SY-REPID, " These variables can also
text TYPE STRING. " be defined locally

smacourse_wa-CARRID = 'LH'. " Example
smacourse_wa-MEALNUMBER = '00000002'. " Example

repid = SY-REPID.
CALL FUNCTION 'DDUT_TEXT_FOR_VALUE'
EXPORTING
CALLING_PROGRAM = repid
STRUCNAME = 'SMACOURSE_WA'
VALUE = smacourse_wa-MEALNUMBER
IMPORTING
TEXT = text.
IF text IS INITIAL.
WRITE / 'No text could be found for the given main course.'.
ELSE.
WRITE: / 'The main course is:', text.
ENDIF.

If the CHANGING parameter ADDITIONAL_FIELDS were to be parametrized with an empty table when the function module is called, it would contain an empty row after the call for which: TABNAME = 'SMACOURSE'. FIELDNAME = 'CARRID'. VALUE is a reference to a data object with the contents 'LH'. FOUND = 'X', EXTERNAL = ' '.

The example program used the second mechanism described for determining the text. The ABAP Dictionary field in question is SMACOURSE-MEALNUMBER. Since the domain belonging to the field does not have a fixed value, the first mechanism cannot be used. The specified field, however, uses check table SMEAL. It in turn has the text table SMEALT, from which the text is taken.

Notes

  1. It is not possible to directly copy SY-REPID to the IMPORT parameter CALLING_PROGRAM since it is only evaluated after the function module has been started.
  2. If IMPORT parameter VALUE_IS_EXTERNAL is set and if the value specified in VALUE cannot be converted to the given type, exception ILLEGAL_VALUE is triggered with a message that specifies the error.
  3. If the calling program is so generic that it does not recognize the additional foreign key fields, the function module can be called to get the list of additionally required fields in ADDITIONAL_FIELDS. With additional program logic, you can fill the data object to which the VALUE component refers in this list and set the FOUND flag. You can then call the module again to actually define the text.
  4. If you define the text from the text table (cases 2 and 3), there can be more than one suitable entry for the given value in the text table if one of the foreign keys is generic. In this case a suitable entry in the text table is chosen at random for defining the text. If there are more suitable records in the text table, the EXPORT parameter is set to NOT_UNIQUE.
  5. If the text is defined from the text table (cases 2 and 3), the contents of TEXT are taken from the first non-key field of the text table that has Dictionary type CHAR or STRING. The contents of all the non-key fields of the text table are returned in EXPORT parameter TEXT_FIELDS.
  6. If EXPORT parameter VALUE_INTERNAL is defined, the internal representation of the value in question is copied to VALUE_INTERNAL with the MOVE statement. If a (detectable) runtime error occurs at that time, the exception ILLEGAL_VALUE is triggered.
  7. If a data object is identified as a required foreign key field according to the above rules, but its contents cannot be copied to a field having the type of the corresponding ABAP Dictionary without an error, the exception ILLEGAL_VALUE is triggered.
  8. If you want to define all the fixed values for a field including their texts, you should use the function module DDIF_FIELDINFO_GET.

Further information





Parameters

FIELDNAME1
LANGU
VALUETEXT

Exceptions

ILLEGAL_VALUE
NO_AUTHORIZATION_FIELD
NO_DDIC_FIELD
NO_VALUES_FOUND

Function Group

SA/SAPLZVIR

TXBHW - Original Tax Base Amount in Local Currency   CL_GUI_FRONTEND_SERVICES - Frontend Services  
This documentation is copyright by SAP AG.

Length: 10212 Date: 20240328 Time: 161812     sap01-206 ( 234 ms )