Natural for OpenVMS Version 6.3.12 for OpenVMS
 —  Parameter Reference  —

EM - Edit Mask

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.

DEFINE DATA
DISPLAY
INPUT
PRINT
PROCESS PAGE/PROCESS PAGE UPDATE
WRITE

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:

  1. For information on Unicode edit masks, see session parameter EMU.
  2. The parameter 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.
  3. See also Edit Masks - EM Parameter in the Programming Guide.

The following topics are covered below:


EM Parameter Syntax

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.

Top of page

Examples

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

Top of page

Blanks in Edit Masks

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 ¬).

Top of page

Default Edit Masks

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

Top of page

Edit Masks for Numeric Fields

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:

Characters for the Definition of Numeric Edit Masks

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:
At this point, the period represents the sign currently defined as decimal separator character. If another character is choosen (for example, a comma) with the session or profile parameter DC, this character is to be used instead.

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.

Sign 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.

Literal Leading Characters

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

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.

Trailing Sign Characters

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.

Examples of Numeric Edit Masks

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.

Top of page

Edit Masks for Alphanumeric Fields

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.

Example:

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

Output Produced:

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.

Example:

DEFINE DATA LOCAL 
 1 #TEXT  (A4) INIT <'BLUE'>
END-DEFINE   
WRITE #TEXT (EM=X-X-X)   
WRITE #TEXT (EM=X-X-X-X-X)
 
 
 
displays as 'B-L-U'       .. only three bytes of field displayed
displays as 'B-L-U-E-'    .. mask definition was truncated to (EM=X-X-X-X-)

Example of Alphanumeric Edit Masks

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 

Top of page

Edit Masks for Binary Fields - Format B

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.

Top of page

Hexadecimal Edit Masks

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.

Edit Mask Examples for Hexadecimal Fields:

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.

ASCII:

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

EBCDIC:

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 Program Using Hexadecimal Edit Masks:

** 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   

Top of page

Edit Masks for Date and Time Fields - Formats D and T

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.

Date - Format D, and Time - Format T

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.

Syntactical Restrictions for Date Characters

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

Hints for Input Edit Mask

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, please refer to profile parameter YSLW in the Natural 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.

Hints for Week Display (WW or ZW) in Output Edit Mask

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.

Example:

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)
          

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
          

Time - Format T - only

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.

Examples of Date and Time Edit Masks

** 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                                        

Top of page

Edit Masks for Logical Fields - Format L

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 of Edit Masks for Logical Field

** 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

Top of page