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 the
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 the profile parameter MAXYEAR is set to
9999, the range of valid year values is 1582 - 9999.
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