With this session parameter, you can specify an edit mask for an input and/or output field that is used in one of the statements listed in the following table under Applicable statements.
| Possible settings | See EM Parameter Syntax. | |
|---|---|---|
| Default setting | none | |
| Applicable statements | FORMAT |
Parameter may be specified dynamically with the FORMAT
statement.
|
|
|
Parameter may be specified at statement level and/or at element level. | |
MOVE EDITED |
Parameter may be specified at element level. | |
| Applicable command | none | |
Notes:
EMU.
EM can also be used with U format fields. For
information on Unicode format, see Unicode and Code Page Support in the Natural Programming
Language, Session
Parameters, EMU,
ICU, LCU, TCU
versus EM, IC, LC,
TC.
The following topics are covered below:
For input fields, values must be entered exactly matching the edit mask. If you would
like to display the edit mask for an input field, the field should be defined as
modifiable (AD=M).
For a database field, a default edit mask may have been defined in the DDM. If you
specify with the EM parameter an edit mask for a database field,
this edit mask specified will be used instead of any default edit mask which may be
defined for the field in the DDM.
If you specify EM=OFF for a field, no edit mask will be used for the field,
not even one that may be defined in the DDM.
At statement level of a DISPLAY, FORMAT, INPUT or WRITE statement, no detail field edit mask may be specified,
except EM=OFF.
An edit mask overrides any settings for the session parameters AL, NL and SG.
The characters 9, H, X and Z
represent significant print positions in numeric (9,Z), hexadecimal
(H), and alphanumeric (X) edit masks. For the difference
between 9 and Z, see Edit Masks for Numeric
Fields, below.
DISPLAY AA(EM=OFF) AB(EM=XX.XX) WRITE SALARY (EM=ZZZ,ZZ9)
You may replace a sequence of the same significant characters with a numeric notation,
such as x(8) for xxxxxxxx. The following examples demonstrate
the abbreviated notation which may be used for the significant characters of numeric
(Z,9), hexadecimal (H), alphanumeric (X) and date
(N,L) edit masks:
EM=9(4)-9(5) is equivalent to: EM=9999-99999 EM=H(10) is equivalent to: EM=HHHHHHHHHH EM=X(6)..X(3) is equivalent to: EM=XXXXXX..XXX EM=YYYY-L(8)-DD-N(8) is equivalent to: EM=YYYY-LLLLLLLL-DD-NNNNNNNN
Blanks behind the equal sign (=) of the EM parameter are not
allowed (for example: EM=<blank>XXX).
Blanks within an edit mask are represented by the character on your keyboard that in
hexadecimal code corresponds to H'20' (ASCII) or H'5F' (EBCDIC),
that is, the character ^ (or ¬).
If no edit mask is specified for a field, a default edit mask is assigned to the field depending on the field format:
| Field Format | Default Edit Mask |
|---|---|
| A | X |
| B | H |
| N, P, I | Z9 |
| F | scientific representation |
| D | depends on default date format (as set with the profile parameter DTFORM)
|
| T | HH:II:SS |
| L | blank / X |
An edit mask specified for a field of format N, P, I, or F must contain at least one
9 or Z.
If more 9s or Zs exist than the number of positions contained
in the field value, the number of print positions in the edit mask will be adjusted to the
number of digits defined for the field value.
If fewer 9s or Zs exist, the high-order digits before the
decimal separator and/or low-order digits after the decimal separator will be
truncated.
The following topics are covered below:
| Character | Function |
|---|---|
9 |
Position to be displayed (one digit of the field value). |
. (period)
|
The first period inserted is used as a decimal separator. Subsequent
periods are treated as literal characters.
Note: |
Z |
Zero suppression for leading zeros. This is the default for numeric fields.
The letter Z may be repeatedly specified to represent floating zero
suppression. Z must not be specified to the right of the decimal
separator character. A zero value may be displayed as blanks using all
Zs in the edit mask (see also session parameter ZP).
|
The 9s or Zs can be preceded by one or more other
characters.
If the first character before the 9s or Zs is +,
-, S or N, a sign may be displayed:
| Character | Function |
|---|---|
+ |
A floating sign is to be displayed preceding (leading sign character) or following (trailing sign character) the number. The sign may be generated as a plus or minus depending on the value of the field. |
- |
A floating minus is to be displayed preceding (leading sign character) or following (trailing sign character) the number if the value of the field is negative. |
S |
A sign is to be displayed to the left of the column. A plus sign is displayed for a positive value and a minus sign is displayed for a negative value. |
N |
A minus sign is to be displayed to the left of the column if the value of the field is negative. |
Any number of literal leading characters can appear before the first displayable
position (as indicated by Z or 9). These must follow any sign
character. If there is no sign character and the first literal leading character is
+, -, S or N, it must be enclosed
in apostrophes. If a literal leading character is H, X,
Z or 9, it must be enclosed in apostrophes.
The first literal leading character specified will appear in the output only if the value contains leading zeros and the edit mask is defined with Z (leading zero suppression). This character will then be used as a filler character displayed instead of a blank for leading zeros. Subsequent literal leading characters will be displayed as they are input.
Literal insertion and trailing characters can also be used. The symbol (^)
can be used to represent a leading, inserted, or trailing blank. By enclosing
significant characters (9, H, Z, X)
in apostrophes, it is possible to use any characters as leading, insertion, or trailing
characters. Insignificant edit mask characters need not be enclosed in apostrophes.
Within the same edit mask notation, it is possible to have groups of leading, insertion,
and/or trailing character strings, some of which are bounded by apostrophes and some of
which are not.
A trailing sign character can be specified for numeric edit masks by using the
+ or - character as the last character in the edit mask. A
+ will produce a trailing + or - sign depending
on the value of the field. A - will produce a trailing space or
- sign depending on the value of the field. If a leading and trailing
sign are specified in the edit mask, both will be produced.
The table below lists the results obtained from the original values shown at the top of each column as they are output without editing mask. All values used as column headings represent format N fields. The lines below the top column represent the formats obtained using the different editing masks:
| Value | 0000.03 (N4.2) |
-0054 (N4) |
+0087 (N4) |
0962 (N4) |
1830 (N4) |
|---|---|---|---|---|---|
| Edit Mask | |||||
EM=9.9 |
0.0 |
4. |
7. |
2. |
0. |
EM=99 |
00 |
54 |
87 |
62 |
30 |
EM=S99 |
+00 |
-54 |
+87 |
+62 |
+30 |
EM=+Z9 |
+0 |
-54 |
+87 |
+62 |
+30 |
EM=-9.99 |
0.03 |
-4. |
7. |
2. |
0. |
EM=N9 |
0 |
-4 |
7 |
2 |
0 |
EM=*9.99 |
0.03 |
4. |
7. |
2. |
0. |
EM=Z99 |
00 |
54 |
87 |
962 |
830 |
EM=*EURZZ9.9 |
EUR**0.0 |
EUR*54. |
EUR*87. |
EUR962. |
EUR830. |
EM=999+ |
000+ |
054- |
087+ |
962+ |
830+ |
EM=999- |
000 |
054- |
087 |
962 |
830 |
IC=$ EM=ZZZ.99 |
$.03 |
$54. |
$87. |
$962. |
$830. |
EM=H(6) |
|||||
| - ASCII: | 303030303033 |
30303574 |
30303837 |
30393632 |
31383330 |
| - EBCDIC: | F0F0F0F0F0F3 |
F0F0F5D4 |
F0F0F8F7 |
F0F9F6F2 |
F1F8F3F0 |
By combining edit masks with the parameters IC and
TC, negative numbers can be displayed in varying formats using
a DISPLAY statement.
An alphanumeric edit mask which is only to be used with A format fields must contain at
least one X which represents a character to be displayed. An H
as the first character designates a hexadecimal edit mask. A blank is represented by a (^) symbol.
All other characters except closing parentheses are permissible including leading,
trailing, and insertion characters. It is also possible to specify leading, insertion, or
trailing characters enclosed within apostrophes. If the character X, a
closing parenthesis, or a quotation mark is specified as an insertion character, it must
be enclosed within apostrophes.
If leading characters are used before the first displayable position X of an
alphanumeric edit mask, the first of these leading characters will not be displayed, but
is used as filler character and replaces all leading blanks in the alphanumeric output
field.
DEFINE DATA LOCAL 1 #X (A4) INIT <' 34'> END-DEFINE WRITE #X (EM=*A:X:) 6X #X (EM=*A:XX:) 6X #X (EM=*A:XXX:) 6X #X (EM=*A:XXXX:) 6X #X (EM=1234XXXX5678) END
A:*: A:**: A:**3: A:**34: 23411345678
Trailing characters which immediately follow the last permissible print position will be displayed.
If the number of positions specified with the mask is smaller than the field length, the overhanging field content is not displayed.
If the number of positions specified with the mask is higher than the field length, the mask is truncated on the first overhanging position.
DEFINE DATA LOCAL 1 #TEXT (A4) INIT <'BLUE'> END-DEFINE WRITE #TEXT (EM=X-X-X) /* 'B-L-U', 3 bytes of field only. WRITE #TEXT (EM=X-X-X-X-X) /* 'B-L-U-E-', with truncated mask. END
The following program lists the alphanumeric edit masks for a field that is defined
with format/length A4 and contains the value BLUE.
** Example 'EMMASK1': Edit mask
************************************************************************
DEFINE DATA LOCAL
1 #TEXT (A4)
END-DEFINE
*
ASSIGN #TEXT = 'BLUE'
WRITE NOTITLE 'MASK 1:' 5X #TEXT (EM=X.X.X.X)
/ 'MASK 2:' 5X #TEXT (EM=X^X^X^X)
/ 'MASK 3:' 5X #TEXT (EM=X--X--X)
/ 'MASK 4:' 5X #TEXT (EM=X-X-X-X-X-X)
/ 'MASK 5:' 5X #TEXT (EM=X' 'X' 'X' 'X)
/ 'MASK 6:' 5X #TEXT (EM=XX....XXX)
/ 'MASK 7:' 5X #TEXT (EM=1234XXXX)
END
Output of Program EMMASK1:
MASK 1: B.L.U.E MASK 2: B L U E MASK 3: B--L--U MASK 4: B-L-U-E- MASK 5: B L U E MASK 6: BL....UE MASK 7: 234BLUE
Edit masks for binary fields may be set using X or H notation.
For binary fields, the X notation is supported as if H had been
specified instead of X.
If the character H is specified as the first character in an edit mask, the
content of an alphanumeric or numeric field will be displayed in hexadecimal format. Each
H represents two print positions that will occur for each byte in the
source field. Characters other than H serve as insertion or trailing
characters in the mask. The number of positions to be displayed will be adjusted to the
length of the edit mask if the mask is shorter than the field. The length of the edit mask
will be adjusted to the length of the field if the field length is shorter than the edit
mask.
Insertion or trailing characters may be optionally specified bounded by apostrophes.
All fields displayed with a hexadecimal edit mask are treated as alphanumeric. Therefore, if the edit mask is shorter than the field to be edited, numeric or alphanumeric positions will be displayed from left to right disregarding any decimal separator positions.
If a hexadecimal edit mask is used as an input edit mask, every 0-9,
a-f,
A-F, blank and hex zero are accepted as a hex digit.
Note:
Blank and hex zero are regarded as 0 and a lower-case letter
(a-f) is regarded as an upper-case letter.
The tables below list the hexadecimal edit masks with results obtained from the
original fields and values shown above each column. All numeric values
(-10, +10, 01) to which edit masks have been
applied originated in fields defined with N2 format. The alphanumeric value
AB originated from a field defined with format/length A2.
| Value => | AB |
-10 |
+10 |
01 |
EM=HH |
4142 |
3170 |
3130 |
3031 |
EM=H^H |
41 42 |
31 70 |
31 30 |
30 31 |
EM=HH^H |
4142 |
3170 |
3130 |
3031 |
EM=H-H |
41-42 |
31-70 |
31-30 |
30-31 |
EM=H |
41 |
31 |
31 |
30 |
| Value => | AB |
-10 |
+10 |
01 |
EM=HH |
C1C2 |
F1D0 |
F1F0 |
F0F1 |
EM=H:H |
C1 C2 |
F1 D0 |
F1 F0 |
F0 F1 |
EM=HH:H |
C1C2 |
F1D0 |
F1F0 |
F0F1 |
EM=H-H |
C1-C2 |
F1-D0 |
F1-F0 |
F0-F1 |
EM=H |
C1 |
F1 |
F1 |
F0 |
** Example 'EMMASK2': Edit mask
************************************************************************
DEFINE DATA LOCAL
1 #TEXT1 (A2)
1 #TEXT2 (N2)
END-DEFINE
*
ASSIGN #TEXT1 = 'AB'
ASSIGN #TEXT2 = 10
*
WRITE NOTITLE
'MASK (EM=HH) :' 18T #TEXT1 (EM=HH) 30T #TEXT2 (EM=HH)
/ 'MASK (EM=H^H) :' 18T #TEXT1 (EM=H^H) 30T #TEXT2 (EM=H^H)
/ 'MASK (EM=HH^H):' 18T #TEXT1 (EM=HH^H) 30T #TEXT2 (EM=HH^H)
/ 'MASK (EM=H-H) :' 18T #TEXT1 (EM=H-H) 30T #TEXT2 (EM=H-H)
/ 'MASK (EM=H) :' 18T #TEXT1 (EM=H) 30T #TEXT2 (EM=H)
END
Output of Program EMMASK2 (ASCII):
MASK (EM=HH) : 4142 3130 MASK (EM=H^H) : 41 42 31 30 MASK (EM=HH^H): 4142 3130 MASK (EM=H-H) : 41-42 31-30 MASK (EM=H) : 41 31
Output of Program EMMASK2 (EBCDIC):
MASK (EM=HH) : C1C2 F1F0 MASK (EM=H^H) : C1 C2 F1 F0 MASK (EM=HH^H): C1C2 F1F0 MASK (EM=H-H) : C1-C2 F1-F0 MASK (EM=H) : C1 F1
In edit masks for fields which are defined with format D (date) or T (time), the characters described in the following sections can be specified.
| Character | Usage |
|---|---|
DD |
Day. |
ZD |
Day, with zero suppression. |
MM |
Month. |
ZM |
Month, with zero suppression. |
YYYY |
Year, 4 digits (see the section Hints for Input Edit Mask). |
YY |
Year, 2 digits (see the section Hints for Input Edit Mask). |
Y |
Year, 1 digit. Must not be used for input fields. |
WW |
Number of week (see the sections Hints for Input Edit Mask and Hints for Week Display in Output Edit Mask). |
ZW |
Number of week, with zero suppression (see the sections Hints for Input Edit Mask and Hints for Week Display in Output Edit Mask). |
JJJ |
Julian day. |
ZZJ |
Julian day with zero suppression. |
NN... or N(n) |
Name of day (language-dependent). The maximum length is determined by the
number of Ns or by n. If the name is
longer than the maximum length, it will be truncated; if it is shorter, the
actual length of the name will be used.
|
O |
Number of week day. The profile parameter DTFORM determines whether Monday or
Sunday is considered the first day of the week. With DTFORM=U:
(Sunday = 1, Monday = 2, etc.). With
DTFORM=other: (Monday = 1, Tuesday =
2, etc.).
|
LL... or L(n) |
Name of month (language-dependent). The maximum length is determined by the number of L characters or by n. If the name is longer than the maximum length, it will be truncated; if it is shorter, the actual length of the name will be used. |
R |
Year in Roman numerals (maximum 13 digits). Must not be used for input fields. |
For Input and Output edit masks, you may not use the following:
| text | characters | ||||
|---|---|---|---|---|---|
| month | with | month name | MM or ZM |
with | LL or
L(n) |
| day name | with | week day number | NN or
N(n) |
with | O |
For Input edit masks, you may not use the following:
| text | characters | ||||
|---|---|---|---|---|---|
| 1-digit year | nor | a year in Roman numerals | Y |
nor | R |
| Day | without | month or month name | DD or ZD |
without | MM or ZM or LL or
L(n) |
| Week | without | year | WW or ZW |
without | YYYY or YY |
| Month | without | year | MM or ZM |
without | YYYY or YY |
| Julian day | without | year | JJJ or ZZJ |
without | YYYY or YY |
| Day name | without | week | NN or
N(n) |
without | WW or ZW |
| Week day number | without | week | O |
without | WW or ZW |
| Julian day | with | month | JJJ or ZZJ |
with | MM or ZM |
| Julian day | with | week | JJJ or ZZJ |
with | WW or ZW |
| Month | with | week | MM or ZM |
with | WW or ZW |
The range of valid year values (YYYY) is 1582 - 2699.
If only year (YY or YYYY) but no month or day is specified
within an input edit mask, the values for month and day will both be set to
01. If only year (YY or YYYY) and month
(MM) but no day is specified within an input edit mask, the value for day
will be set to 01.
If a 2-digits year (YY) is used, the century used to fill up the year
representation is the current century by default. However, this does not apply when a
Sliding or Fixed Window is set. For more details, refer to profile parameter YSLW in the Parameter
Reference documentation.
If a week number (WW or ZW) but no number of week day
(O) or name of day (NN...) is specified, the first day of
the week is assumed.
When DTFORM=U (USA format) is set, the week starts on Sunday; whereas for
all other DTFORM settings the first weekday is Monday. Whether a
week is week 52/53 of the old year or week 01 of the new year depends on which year
contains more days of the week. In other words, if Thursday (Wednesday for
DTFORM=U) of that week is in the previous year, the week belongs to the
previous year; if it is in the next year, the week belongs to the next year.
If the number of week (WW or ZW) and a year representation
(YYYY or YY or Y) is in the same edit mask, the
display for year always corresponds to the week number, regardless of the year in the
underlying date field.
DEFINE DATA LOCAL 1 D (D) END-DEFINE MOVE EDITED '31-12-2003' TO D(EM=DD-MM-YYYY) DISPLAY D(EM=DD-MM-YYYY_N(10)) D(EM=DD-MM-YYYY/WW) END
Although the underlying date is the 31 Dec. 2003, when the week number WW
is contained in the edit mask, it displays as:
D D -------------------- ------------- 31-12-2003_Wednesday 31-12-2004/01
| Character | Usage |
|---|---|
T |
Tenths of a second. |
SS |
Seconds. |
ZS |
Seconds, with zero suppression. |
II |
Minutes. |
ZI |
Minutes, with zero suppression. |
HH |
Hours. |
ZH |
Hours, with zero suppression. |
AP |
AM/PM element. |
** Example 'EMDATI': Edit mask for date and time variables ************************************************************************ * WRITE NOTITLE 'DATE INTERNAL :' *DATX (DF=L) / ' :' *DATX (EM=N(9)' 'ZW.'WEEK 'YYYY) / ' :' *DATX (EM=ZZJ'.DAY 'YYYY) / ' ROMAN :' *DATX (EM=R) / ' AMERICAN :' *DATX (EM=MM/DD/YYYY) 12X 'OR ' *DAT4U / ' JULIAN :' *DATX (EM=YYYYJJJ) 15X 'OR ' *DAT4J / ' GREGORIAN:' *DATX (EM=ZD.''L(10)''YYYY) 5X 'OR ' *DATG /// * 'TIME INTERNAL :' *TIMX 14X 'OR ' *TIME / ' :' *TIMX (EM=HH.II.SS.T) / ' :' *TIMX (EM=HH.II.SS' 'AP) / ' :' *TIMX (EM=HH) END
Output of Program EMDATI:
DATE INTERNAL : 2005-01-12
: Wednesday 2.WEEK 2005
: 12.DAY 2005
ROMAN : MMV
AMERICAN : 01/12/2005 OR 01/12/2005
JULIAN : 2005012 OR 2005012
GREGORIAN: 12.January2005 OR 12January 2005
TIME INTERNAL : 16:04:14 OR 16:04:14.8
: 16.04.14.8
: 04.04.14 PM
: 16
For fields of format L (logical fields), edit masks can be defined as follows:
(EM=[false-string/]true-string)
|
The false-string must not be longer than 31 characters.
** Example 'EMLOGV': Edit mask for logical variables
************************************************************************
DEFINE DATA LOCAL
1 #SWITCH (L) INIT <true>
1 #INDEX (I1)
END-DEFINE
*
FOR #INDEX 1 5
WRITE NOTITLE #SWITCH (EM=FALSE/TRUE) 5X 'INDEX =' #INDEX
WRITE NOTITLE #SWITCH (EM=OFF/ON) 7X 'INDEX =' #INDEX
IF #SWITCH
MOVE FALSE TO #SWITCH
ELSE
MOVE TRUE TO #SWITCH
END-IF
/*
SKIP 1
END-FOR
END
Output of Program EMLOGV:
TRUE INDEX = 1
ON INDEX = 1
FALSE INDEX = 2
OFF INDEX = 2
TRUE INDEX = 3
ON INDEX = 3
FALSE INDEX = 4
OFF INDEX = 4
TRUE INDEX = 5
ON INDEX = 5