SAP NetWeaver AS ABAP Release 740, ©Copyright 2014 SAP AG. All rights reserved.
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
Syntax
... [WIDTH = len]
[ALIGN = LEFT|RIGHT|CENTER|(val)]
[PAD = c]
[CASE = RAW|UPPER|LOWER|(val)]
[SIGN = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(val)]
[EXPONENT = exp]
[DECIMALS = dec]
[ZERO = YES|NO|(val)]
[XSD = YES|NO|(val)]
[STYLE = SIMPLE|SIGN_AS_POSTFIX|SCALE_PRESERVING
|SCIENTIFIC|SCIENTIFIC_WITH_LEADING_ZERO
|SCALE_PRESERVING_SCIENTIFIC|ENGINEERING
|(val)]
[CURRENCY = cur]
[NUMBER = RAW|USER|ENVIRONMENT|(val)]
[ALPHA = IN|OUT|RAW|(val)]
[DATE = RAW|ISO|USER|ENVIRONMENT|(val)]
[TIME = RAW|ISO|USER|ENVIRONMENT|(val)]
[TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(val)]
[TIMEZONE = tz]
[COUNTRY = cty] ... .
Extras:
1. ... WIDTH = len ...
2. ... ALIGN = LEFT|RIGHT|CENTER|(val) ...
3. ... PAD = c ...
4. ... CASE = RAW|UPPER|LOWER|(val) ...
5. ... SIGN = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(val) ...
6. ... EXPONENT = exp ...
7. ... DECIMALS = dec ...
8. ... ZERO = YES|NO|(val) ...
9. ... XSD = YES|NO|(val) ...
10. ... STYLE = ...|(val) ...
11. ... CURRENCY = cur ...
12. ... NUMBER = RAW|USER|ENVIRONMENT|(val) ...
13. ... ALPHA = IN|OUT|RAW|(val) ...
14. ... DATE = RAW|ISO|USER|ENVIRONMENT|(val) ...
15. ... TIME = RAW|ISO|USER|ENVIRONMENT|(val) ...
16. ... TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(val) ...
17. ... TIMEZONE = tz ...
18. ... COUNTRY = cty ...
Effect
These formatting options override the predefined formats of embedded expressions in string templates. The formatting options are specified as optional keyword parameters to which an actual parameter is assigned.
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.
... 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 numerical 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
See Character String Templates, Length
... ALIGN = LEFT|RIGHT|CENTER|(val) ...
Effect
This formatting option defines the alignment of the string represented by the embedded expression. It only takes effect if WIDTH is used to define a length that is greater than the minimum required length.
The alignment can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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
See Character String Templates, Alignments, and Padding
... PAD = c ...
Effect
This formatting option defines the character used to pad any excess places in the result. It only takes effect 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
See Character String Templates, Alignments, and Padding
... CASE = RAW|UPPER|LOWER|(val) ...
Effect
This formatting option defines the case of the string represented by the embedded expression. It can be specified for all data types of the embedded expression.
The case (upper/lower) can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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 has no effect
on padding 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.
Example
See String Templates, Upper/Lower Case
... SIGN = LEFT|LEFTPLUS|LEFTSPACE|RIGHT|RIGHTPLUS|RIGHTSPACE|(val) ...
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 format of the +/- sign can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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
... EXPONENT = exp ...
Effect
This formatting option defines the exponent as the value of exp when formatting floating point numbers, where exp is a numerical 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 option TIMEZONE.
The option EXPONENT only affects the data type f or if the option STYLE is specified with the value scientific. The string is then formatted in exactly the same way as with the formatting option EXPONENT of the statement WRITE TO, with the following exception:
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.
... DECIMALS = dec ...
Effect
This formatting option defines the number of decimal places as the value of dec, where dec is a numerical expression position. The option DECIMALS can be specified only if the embedded expression has a numeric data type. It cannot be specified in combination with the option TIMEZONE.
The string is then formatted in exactly the same way as with the formatting option DECIMALS of the statement WRITE TO.
Note
The DECIMALS formatting option does not override the
predefined format specifying that thousands separators are not inserted.
... ZERO = YES|NO|(val) ...
Effect
This formatting option defines the format of the numeric 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 option TIMEZONE.
The format of the value zero can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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.
... XSD = YES|NO|(val) ...
Effect
This formatting option formats the value of the embedded expression in the axXML 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 asXML format can either be enabled statically using one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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 under Mapping of Elementary ABAP Types. If the data type references one of the domains specified under Mapping of Further XML Schema Data Types (with the exception of XSDQNAME), then the format listed 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, then 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 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
See String Templates, asXML Format.
... STYLE = ...|(val) ...
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, or TIMEZONE.
The style of a decimal floating point number can either be specified statically with a predefined parameter or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT. The following table shows the predefined parameters and the constants of the class CL_ABAP_FORMAT:
Parameter | Value of val |
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 |
The default setting is SIMPLE.
The string is then formatted in exactly the same way as with the formatting option STYLE of the statement WRITE TO. This means that the numeric value is converted to the data type decfloat34 and is handled as described here. Unlike WRITE TO, the following applies:
As in WRITE TO, the following rules apply when combining these options with other formatting options:
Example
See Decimal Floating Point Number, Formatting with STYLE
... 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 code. 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 STYLE or TIMEZONE. The option SIGN can be used to control the formatting of the sign.
The string is formatted in exactly the same way as with the formatting option CURRENCY of the statement WRITE TO with the exception of data type p. In the case of data type p, the formatting depends on how the value is specified:
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.
Note
The CURRENCY formatting option does not override the
predefined format specifying that thousands separators are not inserted.
... NUMBER = RAW|USER|ENVIRONMENT|(val) ...
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 option TIMEZONE .
The format of the decimal representation can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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 current formatting setting of the language environment 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.
Example
See character string templates, formatting settings
... ALPHA = IN|OUT|RAW|(val) ...
Effect
This formatting option adds leading zeros to numeric sequences 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 format of the numeric sequence can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | Effect |
IN | CL_ABAP_FORMAT=>L_IN | If the character string of the embedded expression only contains an uninterrupted strings of digits (apart from opening and closing blanks), the numeric sequence is right-aligned in a character string of specific length (see below), which is padded the left with the digit "0", if necessary. Otherwise, the characters of the character string of the embedded expression are left-aligned 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. |
OUT | CL_ABAP_FORMAT=>L_OUT | If the character string of the embedded expression only contains an uninterrupted strings of digits (apart from opening and closing blanks), leading zeros are removed from the numeric sequence and the remaining digits are left-aligned in a character string of specific length (see below), which is padded on the right with blanks, if necessary Otherwise, all characters of the character string of the embedded expression are left-aligned 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:
Notes
Example
See String Templates, Numeric Sequences
... DATE = RAW|ISO|USER|ENVIRONMENT|(val) ...
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 format of the date can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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 hyphens (-) 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 current formatting setting of the language environment 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.
Example
See character string templates, formatting settings
... TIME = RAW|ISO|USER|ENVIRONMENT|(val) ...
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 format of the time can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | 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 current formatting setting of the language environment 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.
Example
See character string templates, formatting settings
... TIMESTAMP = SPACE|ISO|USER|ENVIRONMENT|(val) ...
Effect
This formatting option defines the format of a time stamp. The option TIMESTAMP can be specified only if the embedded expression has the data type p with the length 8 and no decimal places (TIMESTAMP from ABAP Dictionary) or data type p with length 11 and seven decimal places (TIMESTAMPL from ABAP Dictionary). The value of the embedded expression is interpreted as a time stamp.
The format of the time stamp can either be specified statically with one of the predefined parameters or dynamically as the content of a data object val, specified in parentheses. The possible values of val are defined as constants in the class CL_ABAP_FORMAT.
Parameter | Value of val | Effect |
SPACE | CL_ABAP_FORMAT=>TS_SPACE | The content of the time stamp is converted by default to a date and time in UTC reference time and they are both represented in accordance with ISO 8601: "yyyy-mm-dd hh:mm:ss.zzzzzzz". The option TIMEZONE can be used to specify a different time zone. |
ISO | CL_ABAP_FORMAT=>TS_ISO | As SPACE, but in accordance with ISO 8601 the character "T" is placed between the date and the time and the decimal separator is always a comma (,): "yyyy-mm-ddThh:mm:ss,zzzzzzz". |
USER | CL_ABAP_FORMAT=>TS_USER | As SPACE, but the date format and the time format are taken from the user master record. |
ENVIRONMENT | CL_ABAP_FORMAT=>TS_ENVIRONMENT | As SPACE. However, the date format and time format are defined in accordance with |
according to the current formatting setting of the language environment that can be set using SET COUNTRY.
- | CL_ABAP_FORMAT=>TS_RAW | The content of the time stamp is not converted and the output is a packed number. |
The default setting is SPACE.
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.
Example
See character string templates, formatting settings
... TIMEZONE = tz ...
Effect
This formatting option converts the date and time information of a time stamp to the local date and the local time of the specified time zone. The information is formatted in accordance with how the option TIMESTAMP is specified.
The option TIME ZONE can be specified only if the embedded expression has one of the data types TIMESTAMPL or TIMESTAMP from ABAP Dictionary (as with type p with length 11 and 7 decimal places or p with length 8 and no decimal places) as a time stamp. Other data types produce a syntax error or runtime error.
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, an exception that cannot be handled is raised. If tz is initial, then the time zone is set implicitly to "UTC".
If the addition TIME ZONE is specified for source fields with the types TIMESTAMPL or TIMESTAMP from ABAP Dictionary, then the content of the source field is handled like a time stamp. If the option TIMEZONE is specified without the option TIMESTAMP, the parameter SPACE is added to the option TIMESTAMP implicitly. The option TIMEZONE cannot be specified if the value of CL_ABAP_FORMAT=>TS_RAW is specified for TIMESTAMP in val. The conversion is performed in the same way as with the statement CONVERT TIME STAMP.
If the value of tz is not in the database table TTZZ, if the source field
does not contain a valid time stamp, or if the conversion produces a local time outside the value range for local dates and times, then the content is formatted as a UTC time stamp, regardless of the value.
Example
See String Templates, Time Zones
... 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 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
Examples
See