Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Processing Internal Data →  Character String and Byte String Processing →  Expressions and Functions for String Processing →  string_exp - String Expressions →  string_exp - String Templates →  String Templates - embedded_expressions 

Embedded Expressions - format_options

Other versions: 7.31 | 7.40 | 7.54

Syntax


 ... [WIDTH     = len] 
 
  [ALIGN     = LEFT|RIGHT|CENTER|(dobj)|expr] 

    [PAD       = c] 

    [CASE      = RAW|UPPER|LOWER|(dobj)|expr] 

    [SIGN      = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(dobj)|expr] 

    [EXPONENT  = exp] 
    [DECIMALS  = dec] 

    [ZERO      = YES|NO|(dobj)|expr] 

    [XSD       = YES|NO|(dobj)|expr] 

    [STYLE     =  SIMPLE|SIGN_AS_POSTFIX|SCALE_PRESERVING 

                 |SCIENTIFIC|SCIENTIFIC_WITH_LEADING_ZERO 

                 |SCALE_PRESERVING_SCIENTIFIC|ENGINEERING 

                 |(dobj)|expr] 

    [CURRENCY  = cur] 
  
 [NUMBER    = RAW|USER|ENVIRONMENT|(dobj)|expr] 

    [ALPHA     = IN|OUT|RAW|(dobj)|expr] 

    [DATE      = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr] 

    [TIME      = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr] 

    [TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(dobj)|expr] 

    [TIMEZONE  = tz] 
    [COUNTRY   = cty] ...

Extras

1. ... WIDTH = len ...

2. ... ALIGN = LEFT|RIGHT|CENTER|(dobj)|expr ...

3. ... PAD = c  ...

4. ... CASE = RAW|UPPER|LOWER|(dobj)|expr ...

5. ... SIGN = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(dobj)|expr ...

6. ... EXPONENT = exp ...

7. ... DECIMALS = dec ...

8. ... ZERO = YES|NO|(dobj)|expr ...

9. ... XSD = YES|NO|(dobj)|expr ...

10. ... STYLE = ...|(dobj)|expr ...

11. ... CURRENCY  = cur ...

12. ... NUMBER = RAW|USER|ENVIRONMENT|(dobj)|expr ...
13. ... ALPHA = IN|OUT|RAW|(dobj)|expr ...

14. ... DATE = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr ...

15. ... TIME = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr ...

16. ... TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(dobj)|expr ...

17. ... TIMEZONE = tz ...

18. ... COUNTRY = cty ...

Effect

These formatting options override the predefined formats of embedded expressions in string templates. The formatting options are declared as optional keyword parameters to which an actual parameter is assigned.

Actual parameters with fixed values can be specified as follows:

  • Statically as a key word
  • Dynamically as
  • the content of a data object (dobj) specified in parentheses
The possible values of dobj or expr are defined as constants in the class CL_ABAP_FORMAT.

The possible formatting options depend on the data type of the embedded expression. The formatting options NUMBER, DATE, TIME, TIMESTAMP, and COUNTRY are mutually exclusive.

If a formal parameter or a field symbol with a generic data type is specified as an embedded expression, only those formatting options can be specified that are permitted for all possible specific data types.


Note

If specified, (dobj) and expr represent a summary functional operand position. Unlike the regular functional operand positions, however, the data object dobj must be placed in parentheses to distinguish it clearly from a parameter specified as a key word.

Addition 1

... WIDTH = len ...

Effect

This formatting option defines the length of the string displayed by the embedded expression as the value of len, where len is a numeric expression position.

The option WIDTH can be specified for all data types of the embedded expression. If the value of len is less than the minimum required length, it is ignored. This means that the predefined length cannot be reduced, only increased. By default, a string is extended on the right and padded with blanks. This default setting can be overridden using the formatting options ALIGN and PAD.


Example

The length of the result of the following string template is 20. It consists of four digits, a decimal separator, and 15 trailing blanks.

DATA(text) = |{ CONV decfloat34( 1234 / 10 ) WIDTH = 20 }|.

Executable Example

String Templates, Length

Addition 2

... ALIGN = LEFT|RIGHT|CENTER|(dobj)|expr ...

Effect

This formatting option defines the alignment of the string represented by the embedded expression. It is applied only if WIDTH is used to define a length that is greater than the minimum required length.

The values for the alignment are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
LEFT CL_ABAP_FORMAT=>A_LEFT Left-aligned
RIGHT CL_ABAP_FORMAT=>A_RIGHT Right-aligned
CENTER CL_ABAP_FORMAT=>A_CENTER Centered

The default setting is LEFT. Depending on the alignment, excess characters in the result are padded with blanks (default) on the right, left, or alternately left and right. This default setting can be overridden using the formatting option PAD.


Example

The following string template creates the character string shown below it.

DATA(text) = 
  |{ 1 WIDTH = 5 ALIGN = RIGHT 
  }{ 2 WIDTH = 5 ALIGN = RIGHT 
  }{ 3 WIDTH = 5 ALIGN = RIGHT }<-|.
    1    2    3<-

Executable Example

String Templates, Alignments and Padding

Addition 3

... PAD = c  ...

Effect

This formatting option defines the character used to pad excess spaces in the result. It is applied only if WIDTH is used to define a length that is greater than the minimum required length.

A data object of data type c or string can be defined for c, the first character of which is used as padding. If the PAD option is not specified or if c is specified as an empty string, blanks are used as padding.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ 'X' ALIGN = RIGHT WIDTH = 10 PAD = '_' }|.
_________X

Example

See Character String Templates, Alignments and Padding

Addition 4

... CASE = RAW|UPPER|LOWER|(dobj)|expr ...

Effect

This formatting option defines the case of the string represented by the embedded expression. You can declare it for all data types of the embedded expression.

The values for the case are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
RAW CL_ABAP_FORMAT=>C_RAW Unchanged
UPPER CL_ABAP_FORMAT=>C_UPPER Uppercase
LOWER CL_ABAP_FORMAT=>C_LOWER Lowercase

The default setting is RAW.


Note

The formatting option CASE affects the letters in a string. It is ignored by characters specified using PAD. In numeric data types, the "e" or "E" of an exponent is affected; in byte-like data types, the letters in a hexadecimal representation are affected. In time stamp type, a "T" is affected between date and time. If the formatting option XSD is also specified, CASE affects the asXML format thus generated.


Example

The following string template creates the character string shown below it.

DATA(text) = 
  |{ cl_abap_conv_codepage=>create_out( )->convert( 
       'Hello World!' ) CASE = LOWER }| .
48656c6c6f20576f726c6421

Executable Example

String Templates, Case

Addition 5

... SIGN = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(dobj)|expr ...

Effect

This formatting option defines the format of the +/- sign when the string represented by the embedded expression contains a numeric value. It can be specified only if the embedded expression has a numeric data type.

The values for the format of the sign are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
LEFT CL_ABAP_FORMAT=>S_LEFT "-" left without space, no "+"
LEFTPLUS CL_ABAP_FORMAT=>S_LEFTPLUS "-" and "+" left without space
LEFTSPACE CL_ABAP_FORMAT=>S_LEFTSPACE "-" left without space, blank left for "+"
RIGHT CL_ABAP_FORMAT=>S_RIGHT "-" right without space, no "+"
RIGHTPLUS CL_ABAP_FORMAT=>S_RIGHTPLUS "-" and "+" right without space
RIGHTSPACE CL_ABAP_FORMAT=>S_RIGHTSPACE "-" left without space, blank right for "+"

The default setting is LEFT.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ 1 SIGN = LEFTPLUS }| .
+1

Executable Example

String Templates, Sign

Addition 6

... EXPONENT = exp ...

Effect

This formatting option defines the exponent as the value of exp when formatting floating point numbers, where exp is a numeric expression position. The option EXPONENT can be specified only if the embedded expression has a numeric data type. It cannot be specified in combination with the options TIMESTAMP or TIMEZONE.

The option EXPONENT only affects the data type f or if the option STYLE is specified with the value scientific.

exp expects a data object of the type i that contains the required exponent.

  • In data type f, the mantissa is adjusted to this exponent by moving the decimal point and padding with zeroes. If exp contains 0, no exponent is created. If the value of exp is greater than the exponent of the source field plus 16, only zeroes are allocated to the mantissa. If the value of exp is less than the exponent of the source field, and there is not enough space for the places required before the decimal point, the addition is ignored. If the value in exp is positive and has more than three characters, only the first three places of the exponent are used.
  • If the formatting option STYLE is also specified, source fields of all numeric types (b, s), i, int8, p, f, decfloat16, and decfloat34 are converted before the formatting to decfloat34. For STYLE, only the scientific notation O_SCIENTIFIC can be declared together with EXPONENT. The addition EXPONENT defines the exponent here.

If exp is specified as the value of the constant CL_ABAP_FORMAT=>EXP_PRESERVE, the exponent is used that matches the internal representation of the floating point value.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ CONV f( 2 / 3 ) }, { CONV f( 2 / 3 ) EXPONENT = -1 }|.
0.66666666666666663, 6.6666666666666663E-01

Addition 7

... DECIMALS = dec ...

Effect

This formatting option defines the number of decimal places when formatting numeric values or time stamps as the value of dec, where dec is a numeric expression position. The option DECIMALS can be specified only if the embedded expression has a numeric data type or the time stamp type utclong. It cannot be specified in combination with the option CURRENCY.

dec expects a data object of type i that contains the number of decimal places required. For the individual data types, the following applies:

  • Numeric Data Types
If the content of dec is less than 0, it is handled like 0. The content of data objects of data types (b, s), i, int8, or p is multiplied by 10 to the power of dec beforehand.
  • For data objects of types (b, s), i, and int8, a decimal separator and as many zeroes as specified in dec are appended. The content of dec must not exceed 14. If it does, a non-handleable exception is raised. If the content of dec is 0, the output remains unaffected.
  • For data objects of type p, independently of the number of decimal places determined in the data type, as many decimal places are used as are specified in dec. The content of dec must not exceed 14. If it does, a non-handleable exception is raised. If the source field has more decimal places, they are rounded to the decimal places in dec. If the source field has fewer decimal places, zeroes are appended accordingly.
  • For data objects of types decfloat16 and decfloat34, the content of dec decides the number of decimal places in mathematical notation and the number of places in the mantissa in scientific notation.
  • For data objects of type f, the content of dec determines the number of decimal places in the scientific notation. If the content of dec is greater than 16, it is handled like 16. If the content of dec is greater than the number of decimal places of the source field, zeroes are appended accordingly. If the content of dec is less than the number of decimal places of the source field, they are rounded to the decimal places in dec.
  • Time stamp
The content of dec must be between 0 and 7.
  • For time stamp fields of the time stamp type utclong as many decimal places as specified in dec are used. Excess decimal places are truncated. If dec has the value 0, the decimal separator is removed. If dec has an invalid value, a handleable exception of class CX_SY_CONVERSION_NO_DATE_TIME is raised.
  • If one of the additions TIMEZONE or TIMESTAMP is specified for suitable numbers of the type p, their content is intepreted as a time stamp. For data type p of length 8 without decimal places (TIMESTAMP from ABAP Dictionary), as many zeroes as specified in dec are appended. For data type p of length 11 with 7 decimal places (TIMESTAMPL from ABAP Dictionary), as many decimal places as specified in dec are used. Excess decimal places are cut off. If dec has the value 0, the decimal separator is removed.


Note

The DECIMALS formatting option does not override the predefined format for numeric types, specifying that thousands separators are not inserted.


Example

The following string template creates the character string shown below it. If the conversion operator is not specified, the calculation type of the embedded expression is i.

DATA(text) = |{                  - 2 / 3   DECIMALS = 3 }, { 
                CONV decfloat34( - 2 / 3 ) DECIMALS = 3 }, { 
                CONV          f( - 2 / 3 ) DECIMALS = 3 }|.
-1.000, -0.667, -0.667

Addition 8

... ZERO = YES|NO|(dobj)|expr ...

Effect

This formatting option defines the format of the numerical value zero. The option ZERO can be specified only if the embedded expression has a numeric data type. It cannot be specified in combination with the options TIMESTAMP or TIMEZONE.

The values for the format of the zero value are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
YES CL_ABAP_FORMAT=>Z_YES The value zero is represented as a numeric value in accordance with the current formatting.
NO CL_ABAP_FORMAT=>Z_NO The value zero is represented as an empty string.

The default setting is YES.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ 0 ZERO = NO }, { 0 ZERO = YES }|.
, 0

Addition 9

... XSD = YES|NO|(dobj)|expr ...

Effect

This formatting option formats the value of the embedded expression in the asXML format that is associated with its data type. The option XSD can be specified for all elementary data types. It cannot be specified together with other formatting options; with the exception of WIDTH, ALIGN, PAD, CASE, and ZERO.

The option XSD affects all data types listed under Mapping of Elementary ABAP Types, as specified there.

The values for the asXML format are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
YES CL_ABAP_FORMAT=>X_YES The data type of the embedded expression determines how it is formatted in accordance with the asXML format specified underMapping of Elementary ABAP Types. If the data type references one of the domains specified underMapping of Further XML Schema Data Types (with the exception of XSDQNAME), the format specified there is used.XML fragments cannot be mapped using the domain XSDANY.
NO CL_ABAP_FORMAT=>X_NO Unchanged

If the data type of the embedded expression has the type x or xstring, a formatting option CASE specified at the same time is ignored (unless it refers to the domain XSDUUID_RAW).


Note

The formatting of an embedded expression with XSD generally produces the same result as applying the predefined identity transformation ID. Unlike a CALL TRANSFORMATION call, exceptions that can be raised by mappings, but not wrapped, should be handled directly.


Example

The following string template creates the character string shown below it. XSDBOOLEAN is a data element that references the special domainXSDBOOLEAN for the mapping of truth values.

DATA: 
  flag1 TYPE xsdboolean VALUE abap_true, 
  flag2 TYPE xsdboolean VALUE abap_false. 

DATA(text) = |{ flag1 XSD = YES }, { flag2 XSD = YES }|.
true, false

Executable Example

String Templates, asXML Format

Addition 10

... STYLE = ...|(dobj)|expr ...

Effect

This formatting option defines the style of decimal floating point numbers. The option STYLE can be specified only if the embedded expression has a numeric data type. It cannot be specified in combination with the options CURRENCY, SIGN, TIMESTAMP, or TIMEZONE.

The values for the format of a decimal floating point number are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr
SIMPLE CL_ABAP_FORMAT=>O_SIMPLE
SIGN_AS_POSTFIX CL_ABAP_FORMAT=>O_SIGN_AS_POSTFIX
SCALE_PRESERVING CL_ABAP_FORMAT=>O_SCALE_PRESERVING
SCIENTIFIC CL_ABAP_FORMAT=>O_SCIENTIFIC
SCIENTIFIC_WITH_LEADING_ZERO CL_ABAP_FORMAT=>O_SCIENTIFIC_WITH_LEADING_ZERO
SCALE_PRESERVING_SCIENTIFIC CL_ABAP_FORMAT=>O_SCALE_PRESERVING_SCIENTIFIC
ENGINEERING CL_ABAP_FORMAT=>O_ENGINEERING

This means that the numeric value of the string is converted to the data type decfloat34 and is handled as follows:

  • The default settings SIMPLE creates the predefined format of embedded expressions.
  • SIGN_AS_POSTFIX creates a commercial notation. The sign is appended on the right (a minus sign for negative values, a blank for positive values). Trailing zeroes in decimal places are cut off.
  • SCALE_PRESERVING preserves the scale. Here, trailing zeroes in the decimal places are not cut off. The same format is created as in conversions of a source field of type decfloat34 to the type string.
  • SCIENTIFIC creates a scientific notation. No sign is added for positive numbers. The result always has at least a two digit exponent with a sign. If the addition EXPONENT is not specified, only one integer digit (whose value is not zero) is represented in the mantissa, unless the source field has the value 0. Any trailing zeroes after the decimal point of the mantissa are cut off. The formatting option DECIMALS can be used to specify the number of decimal places and EXPONENT can be used to specify the exponent.
  • SCIENTIFIC_WITH_LEADING_ZERO creates a scientific notation with leading zero. Like SCIENTIFIC with the following differences:
  • Only one integer digit with the value 0 is represented.
  • The formatting option EXPONENT cannot be specified.
  • SCALE_PRESERVING_SCIENTIFIC creates a scientific notation while preserving the scale. Like SCIENTIFIC with the following differences:
  • The exponent always has three digits for decfloat16 and four digits for decfloat34.
  • Any trailing zeroes after the decimal point of the mantissa are not cut off.
  • The formatting option EXPONENT cannot be specified.
  • ENGINEERING creates a technical format. Like SCIENTIFIC with the following differences:
  • The value of the exponent is always an integer multiple of 3.
  • The value range of the integer digits is between 1 and 999 (except if the source field has the value 0).
  • The formatting option EXPONENT cannot be specified.

The general rules for embedded expressions apply to thousands separators and decimal separators. When combining other formatting options, the following applies:

  • The formatting option EXPONENT can only be specified in combination with the output style SCIENTIFIC.
  • The formatting option DECIMALS cannot be specified for output styles that preserve scaling. For the output formats SIMPLE and SIGN_AS_POSTFIX, DECIMALS defines the number of decimal places. In some cases, commercial rounding may take place or trailing zeroes may be appended. For the scientific output formats, DECIMALS determines the number of decimal places in the mantissa. In some cases commercial rounding may take place.


Notes

  • To a great extent, the formats match the output styles specified when a domain is created with one of the types DF16_DEC, DF16_RAW, DF16_SCL (obsolete), DF34_DEC, DF34_RAW, or DF34_SCL (obsolete) in ABAP Dictionary.
  • When a decimal floating point number defined in ABAP Dictionary is formatted, the formatting option STYLE overrides the output style defined in ABAP Dictionary.
  • It is best to use the formatting option STYLE for the formatting of all numeric output. This addition then replaces all other additions whose output format can be specified using stl.
  • To specify the scaling of a decimal floating point number before the use of the format O_SCALE_PRESERVING_SCIENTIFIC, the built-in function rescale can be called by specifying the parameter dec.
  • The methods CONVERT_CURR_TO_DECFLOAT and CONVERT_DECFLOAT_TO_CURR of the system class CL_ABAP_DECFLOAT are helpful when representing currency amounts saved as decimal floating point numbers. These methods convert currency amounts to decimal floating point numbers, as specified by a currency key, and back again.
  • The format O_SCALE_PRESERVING_SCIENTIFIC is intended to help create output that is aligned vertically with reference to the decimal separator and exponent without the addition DECIMALS being used. To make this possible, the built-in function rescale can be called before output by specifying the parameter prec.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ CONV decfloat34( '123456' ) STYLE = ENGINEERING }|.
123.456E+03

Executable Example

Decimal Floating Point Number, Formatting with STYLE

Addition 11

... CURRENCY  = cur ...

Effect

This formatting option defines the number of decimal places when formatting numeric values, dependent on a currency when specified incur using a currency ID. The option CURRENCY can be specified only if the embedded expression has one of the numeric data types i, p, or f. It cannot be specified for the numeric data types decfloat16 and decfloat34, and not in combination with the options DECIMALS, STYLE, TIMESTAMP, or TIMEZONE. The option SIGN can be used to control the formatting of the sign.

With respect to its decimal places. the string is formatted as follows for the individual numeric data types:

  • For data objects of the types (b, s), i and int8, a decimal separator is inserted into the result at the place determined by cur.
  • In the case of data type p, the formatting depends on how the value is specified:
  • If specified as a data object or as a functional method, the decimal places specified in the definition of the data type are ignored in full. Regardless of the actual value and without rounding, a decimal separator is inserted between the digits in the places determined by cur.
  • For data objects of type f, the formatting option CURRENCY has the same effect as DECIMALS, where the number of decimal places is determined by cur.

cur in the numeric data types i, p, and f expects a currency ID from the column WAERS of the database table TCURC. Two decimal places are used for every currency ID specified, unless it is contained in the CURRKEY column of the database table TCURX. In this case, the number of decimal places is determined from the CURRDEC column of the corresponding row in table TCURX.


Notes

  • The CURRENCY formatting option does not override the predefined format specifying that thousands separators are not inserted.
  • The formatting option CURRENCY is useful with currencies from the tables TCURX or TCURX for formatting data objects of types (b, s), i, int8, or p without decimal places, whose contents are currency amounts in the smallest unit of the currency.
  • For decimal floating point numbers, the methods CONVERT_CURR_TO_DECFLOAT and CONVERT_DECFLOAT_TO_CURR of the system class CL_ABAP_DECFLOAT are provided. These methods convert currency amounts to decimal floating point numbers, as specified by a currency key, and back again.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ 12345678 CURRENCY = 'EUR' }|.
123456.78

Addition 12

... NUMBER = RAW|USER|ENVIRONMENT|(dobj)|expr ...

Effect

This formatting option defines the format of the decimal representation (decimal and thousand separators). The option NUMBER can only be specified if the embedded expression has a numeric data type. As well as the exclusions mentioned above, it cannot be used in combination with the options TIMESTAMP or TIMEZONE .

The values for the format of the decimal representation are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
RAW CL_ABAP_FORMAT=>N_RAW The decimal separator is the period (.) and no thousand separators are inserted.
USER CL_ABAP_FORMAT=>N_USER The decimal and thousand separators are taken from the user master record.
ENVIRONMENT CL_ABAP_FORMAT=>N_ENVIRONMENT The decimal and thousand separators are determined according to the currentformatting setting of thelanguageenvironment that can be set using SET COUNTRY.

The default setting is RAW.


Note

If the formatting setting of the language environment has not been set to a country-specific format by means of SET COUNTRY, the use of ENVIRONMENT has the same effect as the use of USER.

Executable Example

String Templates, Formatting Settings


Example

The following string template creates the character string shown below it.

SET COUNTRY 'US'. 
DATA(text) = |{ 1000000 NUMBER = ENVIRONMENT }|.
1,000,000

Addition 13

... ALPHA = IN|OUT|RAW|(dobj)|expr ...

Effect

This formatting option adds leading zeroes to strings of digits or removes them. The option ALPHA can be specified only if the embedded expression has the data type string, c, or n. It cannot be specified together with other formatting options; apart from WIDTH and CASE.

The values for the format of the string of digits are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
IN CL_ABAP_FORMAT=>L_IN If the character string of the embedded expression only contains an uninterrupted string of digits(apart from leading and trailing blanks), the string of digits is right-justified in a character stringof specified length (see below), which is padded on the left with the digit "0", if necessary. Otherwise,the characters of the character string of the embedded expression are left-justified in the characterstring and padded with blanks on the right, if necessary. If the length is not sufficient, the string is cut off on the right in both cases.
OUT CL_ABAP_FORMAT=>L_OUT If the character string of the embedded expression only contains an uninterrupted string of digits(apart from leading and trailing blanks), leading zeroes are removed from the string of digits and theremaining digits are left-justified in a character string of a specified length (see below), which ispadded on the right with blanks, if necessary Otherwise, all characters of the character string of theembedded expression are left-justified in the character string and padded with blanks on the right, if necessary. If the length is not sufficient, the string is cut off on the right in both cases.
RAW CL_ABAP_FORMAT=>L_RAW No formatting

The length of the resulting character string is determined as follows:

  • If the formatting option WIDTH is not specified and the embedded expression, as the only content of a character string template, is assigned to a fixed-length target field of type c, n, d, or t, the length of this field determines the available length. Otherwise, the length of the original field, including trailing blanks, is used.
  • If the formatting option WIDTH is specified, the specified length is only used if it is greater than the length of the uninterrupted string of digits without leading zeroes, or the character string without trailing blanks. Otherwise, the length of the uninterrupted string of digits without leading zeroes or the character string without trailing blanks is used.


Notes

  • The formatting option ALPHA has the same function as the conversion routine CONVERSION_EXIT_ALPHA_INPUT or CONVERSION_EXIT_ALPHA_OUTPUT.
  • The parameter IN can be used to transform strings of digits without leading zeroes to the format of numeric text with leading zeroes. The parameter OUT can be used to convert numeric text with leading zeroes to strings of digits without leading zeroes.


Example

The following string template creates the character string shown below it.

DATA(text) = |{ '1234' ALPHA = IN WIDTH = 10 }|.
0000001234

Executable Example

String Templates, Strings of Digits

Addition 14

... DATE = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr ..

Effect

This formatting option defines the format of a date. The option DATE can be specified only if the embedded expression has the data type d.

The values for the format of the date are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
RAW CL_ABAP_FORMAT=>D_RAW The content of the date field is used without being formatted.
ISO CL_ABAP_FORMAT=>D_ISO The date if formatted in accordance with ISO 8601, using dashes (-) as separators: "yyyy-mm-dd".
USER CL_ABAP_FORMAT=>D_USER The date is formatted in accordance with the information in the user master data.
ENVIRONMENT CL_ABAP_FORMAT=>D_ENVIRONMENT The formatting of the date is determined according to the currentformatting setting of thelanguageenvironment that can be set using SET COUNTRY.

The default setting is RAW.


Note

If the formatting setting of the language environment has not been set to a country-specific format by means of SET COUNTRY, the use of ENVIRONMENT has the same effect as the use of USER.

Executable Example

String Templates, Formatting Settings


Example

The following string template creates the character string shown below it (depending on the current date).

DATA(text) = |{ sy-datlo DATE = ISO }|.
2016-09-09

Addition 15

... TIME = RAW|ISO|USER|ENVIRONMENT|(dobj)|expr ...

Effect

This formatting option defines the format of a time. The option TIME can be specified only if the embedded expression has the data type t.

The values for the format of the time are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
RAW CL_ABAP_FORMAT=>T_RAW The content of the time field is used without being formatted.
ISO CL_ABAP_FORMAT=>T_ISO The time is formatted in accordance with ISO 8601, in 24-hour format using colons (:) as separators: "hh:mm:ss".
USER CL_ABAP_FORMAT=>T_USER The time is formatted in accordance with the information in the user master data.
ENVIRONMENT CL_ABAP_FORMAT=>T_ENVIRONMENT The formatting of the time is determined according to the currentformatting setting of thelanguageenvironment that can be set using SET COUNTRY.

The default setting is RAW.


Note

A 24-hour format and four 12-month formats can be configured in the user master data or using the statement SET COUNTRY. To use 12-hour format, USER or ENVIRONMENT must be specified or the formatting option COUNTRY used.


Note

If the formatting setting of the language environment has not been set to a country-specific format by means of SET COUNTRY, the use of ENVIRONMENT has the same effect as the use of USER.

Executable Example

String Templates, Formatting Settings


Example

The following string template creates the character string shown below it (depending on the current time) if a country with a 12-hour format is found in the database table T005X.

SELECT SINGLE land 
       FROM t005x 
       WHERE timefm = 1 
       INTO @DATA(land). 
IF sy-subrc <> 0. 
  RETURN. 
ENDIF. 

SET COUNTRY land. 
DATA(text) = |{ sy-timlo TIME = ENVIRONMENT }|.
10:55:58 AM

Addition 16

... TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(dobj)|expr ...

Effect

This formatting option defines the format of a time stamp. The option TIMESTAMP can be specified only if the embedded expression is of one of the following data types, otherwise a syntax or runtime error occurs:

  • Time Stamp Type utclong.
  • Numeric data type p with length 8 without decimal places (TIMESTAMP from ABAP Dictionary) or p with length 11 and seven decimal places (TIMESTAMPL from ABAP Dictionary). The value of the embedded expression is interpreted as a time stamp in a packed number.

The values for the format of the time stamp are fixed. The following table shows the key words and the associated values from the class CL_ABAP_FORMAT that can be specified as dobj or expr:

Keyword Value of dobj or expr Effect
SPACE CL_ABAP_FORMAT=>TS_SPACE The time stamp is represented according to the SQL standard ISO 9075, where there is a space between date and time, and a period(.) is used as a decimal separator: "yyyy-mm-dd hh:mm:ss.fffffff".
ISO CL_ABAP_FORMAT=>TS_ISO The time stamp is represented according to ISO 8601 for date formats and time specifications, where the character"T" is between date and time and a comma (,) is used as the decimal separator: "yyyy-mm-ddThh:mm:ss,fffffff”
USER CL_ABAP_FORMAT=>TS_USER As SPACE, but the date format and the time format, and the decimal separator are taken from theuser master record.
ENVIRONMENT CL_ABAP_FORMAT=>TS_ENVIRONMENT As SPACE. However here the date format and time format, and the decimal separator are defined in accordance with according to the currentformatting setting of thelanguageenvironment that can be set using SET COUNTRY.
- CL_ABAP_FORMAT=>TS_RAW The time stamp is formatted as an uninterrupted sequence of numbers without separators, except for a decimal point (.) before fractions of seconds.

The default setting is SPACE.

Initial values and invalid values are handled as follows:

  • An initial expression of the type utclong is represented as a character string filled with spaces, whose length is that of the result for a valid time stamp. This length depends on the formatting options specified. Invalid values raise a handleable exception from the class CX_SY_CONVERSION_NO_DATE_TIME.
  • A packed number, that does not represent a valid time stamp is formatted as a time stamp anyway and the absolute value is respected for negative numbers. If the formats USER and ENVIRONMENT are used, an asterisk "*" is inserted before the date and the last position of the time is cut off.


Notes

  • In addition to TIMESTAMP, the formatting option DECIMALS can influence the number of decimal places. Other options that change the date and time format or the decimal separator cannot be specified.
  • If the formatting setting of the language environment has not been set to a country-specific format by means of SET COUNTRY, the use of ENVIRONMENT has the same effect as the use of USER.
  • The option TIMEZONE can be used to specify a time zone to convert the date and time portions of the time stamp to the corresponding local values.
  • Whereas the time stamp format ISO is already predefined for the data type utclong, and works even without a formatting option, the numeric format is predefined for time stamps in packed numbers. A time stamp represented as a packed number is identified and formatted as a time stamp only by using the formatting options TIMESTAMP or TIMEZONE.


Example

The program DEMO_STRING_TEMPLATE_TIMESTAMP shows the use of the time stamp formats. Executing the program shows its effect. The following source text section is an excerpt from the program.

DATA(out) = cl_demo_output=>new( ). 

DATA(ts)   = utclong_current( ). 
DATA(tspl) = cl_abap_tstmp=>utclong2tstmp( ts ). 
DATA(tsp)  = cl_abap_tstmp=>utclong2tstmp_short( ts ). 

out->write( 
  |Standard:\n{ 
     ts                    }\n{ 
     tspl TIMEZONE = 'UTC' }\n{ 
     tsp  TIMEZONE = 'UTC' } | ). 

out->write( 
  |ISO:\n{ 
     ts   TIMESTAMP = ISO }\n{ 
     tspl TIMESTAMP = ISO }\n{ 
     tsp  TIMESTAMP = ISO } | ).

Executable Example

String Templates, Formatting Settings

Addition 17

... TIMEZONE = tz ...

Effect

This formatting option uses the rules for time zones to convert the date and time information of a time stamp into the local date and local time of the time zone specified in tz, and formats the result as a time stamp. The option TIMEZONE can be specified only if the embedded expression is of one of the following data types, otherwise a syntax or runtime error occurs:

  • Time Stamp Type utclong.
  • Numeric data type p with length 8 without decimal places (TIMESTAMP from ABAP Dictionary) or p with length 11 and seven decimal places (TIMESTAMPL from ABAP Dictionary). The value of the embedded expression is interpreted as a time stamp in a packed number.

If the option TIMESTAMP is not specified, an expression of the type utclong is formatted according to its predefined format. A time stamp in a packed number is formatted in the same way as with the specification TIMESTAMP = SPACE. If the option TIMESTAMP is specified, it takes effect.

tz expects a character-like data object containing a time zone from the database table TTZZ. If the rule set for the specified time zone is incomplete, a non-handleable exception is raised. If tz is initial, no time shift is calculated. The conversion takes place as described in the statements CONVERT UTCLONG and CONVERT TIME STAMP. The special rules for the first and last second apply to the time stamp type utclong.

Initial values are handled as follows:

  • A character string filled with spaces, whose length is that of the result for a valid time stamp, is generated for the time stamp type utclong.
  • For time stamps in packed numbers, the initial value 0 is an invalid value and is formatted as such.

Error handling is as follows:

  • The source field does not contain a valid time stamp:
  • For the time stamp type utclong, a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.
  • Time stamps in packed numbers are still formatted as a time stamp and the absolute value is respected for negative numbers. The time zone specified has no effect.
  • The value of tz is not contained in the database table TTZZ, or the conversion would result in a local time outside the value range for local date and time:
  • For the time stamp type utclong, a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.
  • For time stamps in packed numbers, the time zone "UTC" is used implicitly.


Notes

  • The decimal places of time stamps can also be defined with the formatting option DECIMALS.
  • Unlike TIMESTAMP, the addition TIMEZONE can also be combined with the formatting option COUNTRY to affect the date and time format.
  • An initial time zone tz matches UTC only if the tables of the rules for time zones are filled correctly for the time zone UTC.


Example

The program DEMO_STRING_TEMPLATE_TIMEZONE shows the use of the option TIMEZONE without using the option TIMESTAMP but in connection with the option COUNTRY. Executing the program shows its effect.

DATA(out) = cl_demo_output=>new( ). 

DATA(ts)   = utclong_current( ). 
DATA(tspl) = cl_abap_tstmp=>utclong2tstmp( ts ). 
DATA(tsp)  = cl_abap_tstmp=>utclong2tstmp_short( ts ). 

out->write( 
  |Predefined:\n{ 
     ts   }\n{ 
     tspl }\n{ 
     tsp  } | ). 

out->write( 
  |UTC:\n{ 
     ts   TIMEZONE = 'UTC' }\n{ 
     tspl TIMEZONE = 'UTC' }\n{ 
     tsp  TIMEZONE = 'UTC' } | ). 

out->write( 
  |CET, DE:\n{ 
     ts   TIMEZONE = 'CET' COUNTRY = 'DE ' }\n{ 
     tspl TIMEZONE = 'CET' COUNTRY = 'DE ' }\n{ 
     tsp  TIMEZONE = 'CET' COUNTRY = 'DE ' } | ). 

out->write( 
  |EST, US:\n{ 
     ts   TIMEZONE = 'EST' COUNTRY = 'US ' }\n{ 
     tspl TIMEZONE = 'EST' COUNTRY = 'US ' }\n{ 
     tsp  TIMEZONE = 'EST' COUNTRY = 'US ' } | ). 

out->display( ).

Executable Example

String Templates, Time Zones

Addition 18

... COUNTRY = cty ...

Effect

The formatting option COUNTRY defines a temporary formatting setting for the currently embedded expression. It can be specified as an alternative to all formatting options for which the parameter ENVIRONMENT can be specified (that is, instead of NUMBER, DATE, TIME, and TIMESTAMP). The embedded expression is formatted as a number, date, or time, or time stamp, depending on its data type.

cty expects a data object of the type LAND1 from ABAP Dictionary. It must either contain a value from the LAND column of the database table T005X or it must be initial. If not, an exception of the class CX_SY_STRG_FORMAT is raised.

If cty contains a value from the data base table T005X, the country-specific format defined there is used. If cty is initial, the formatting specified in the user master record is used.


Notes

  • Unlike using the statement SET COUNTRY and the parameter ENVIRONMENT, there are no side-effects when using the formatting option COUNTRY. The country specified applies only to the currently embedded expression and not on any subsequent statements from the current internal session.
  • In numbers, the COUNTRY formatting option overrides the predefined setting with respect to thousand separators.


Example

The following string template creates the character string shown below it (depending on the content of the database table T005X).

DATA(text) = |{ 1000000 COUNTRY = 'DE ' }|.
1,000,000

Executable Examples