Automatic Editing Criteria
This article describes the following information:
This article describes the following information
The following terms are used in this article:
- Aninternal picturedescribes the format in which data for a field is stored in the user buffer.
- Anexternal picturedescribes the format in which data for a field is displayed on the screen.
- Anedit tableoptionally defines a set of valid or invalid values or ranges of values for a field.
- Acode tableoptionally defines values for encoding and decoding data.
External pictures can be defined by using the online or batch compiler as well as IDD. Internal pictures, edit tables, and code tables are defined externally to the mapping facility.
Types of Editing
The three automatic editing operations that are depicted in the following illustration and discussed in the following sections, can be performed:
- Display characteristics
- Data conversion
- Input verification
Automatic Editing Operations
The following diagram illustrates how automatic editing works.
Display characteristics are determined by the external picture.
For example, a date field can have an internal picture of 9(6) and an external picture of 99/99/99. If the internal picture for a DATE data field is 9(6) as many as six numeric digits can be stored for the field. The external picture of 99/99/99 specifies how a stored value is displayed on the terminal screen. Using this example, a date stored internally 101297 displays externally as 10/12/97.
Data that is entered on a map is converted and validated against a code table. For example, each value for the STATE data field is stored as a two-digit value, as specified by its internal picture 99. A code table then translates each two-digit value to a complete state name.
For example, the operator views ALABAMA when the stored value is 01. The value 50 is stored in program variable storage when the operator enters the word WYOMING.
Data that is entered on a map is compared to values in an edit table. Correct values for the sample DEPT data field are listed in an edit table. Operator input is validated against values in the edit table. (An edit table can contain either correct or incorrect values for a field.) For example, the term SALES is determined to be incorrect based on the edit table for the field; the dialog or program redisplays the error and asks the operator to correct the value.
Internal pictures define the data storage format for elements and the map fields that are associated with the elements. Internal pictures cannot be created or altered by the mapping facility.
Specifying Internal Pictures
An internal picture can be specified for a record element when the record element is defined by using either the IDD Data Dictionary Definition Language (DDDL) or the IDMS schema compiler. Internal pictures cannot be defined or altered by using the online or batch compiler.
How the Input is Converted
Before edited input is moved into program variable storage, if editing is on, the input is converted into its internal format based on the internal picture that is defined for the record element that is associated with the input field. The internal picture for a map field is the internal picture of the related record element.
An internal picture can contain a maximum of 32 characters. The characters that are used to construct alphanumeric, alphabetic, and numeric internal pictures are listed in the following table:
A single alphanumeric character.
Follows an X to represent n consecutive repetitions of alphanumeric characters.
Nmust be an integer in the range 1 through 9999.
A single alphabetic character (A through Z).
Follows an A to represent
nconsecutive repetitions of alphabetic characters.
Nmust be an integer in the range 1 through 9999.
A single numeric character (0 through 9).
Follows a 9 to represent
nconsecutive repetitions of numeric characters.
Preceding an implied decimal point position,
nmust be an integer in the range 1 through 9999.
Following an implied decimal point position,
nmust be an integer in the range 1 through 255.
Represents a decimal point position in fixed decimal numeric data. An internal picture can contain only one decimal. If a fixed decimal picture does not contain a V, the decimal position for the picture is after the rightmost 9.
Indicates that signed data is maintained as either positive or negative. When used, S must be the first character in an internal picture.
. (decimal point)
Represents the decimal point in floating-point data with DISPLAY usage only. An internal picture can contain only one decimal point.
Indicates the start of the floating-point exponent. When used, an E must be preceded by at least one 9 and followed by at least one 9.
How are the Elements Stored at Runtime?
A USAGE clause in the record element definition determines the method of storing values for an element at runtime. The USAGE clause for an element that is associated with a map field can specify one of the following storage methods:
Will Store Data This Way
Values are stored one character to a byte according to EBCDIC conventions. DISPLAY must be specified for alphanumeric and alphabetic internal pictures. DISPLAY can also be specified for numeric internal pictures.
Numeric values are stored in binary format.
Numeric values are stored in internal floating-point (short precision) format.
Numeric values are stored in internal floating-point (long precision) format.
Numeric values are stored in packed decimal format.
- COMP, COMP-1, -2, and -3 usages apply only to numeric data. Internal pictures cannot be specified for elements with COMP-1 or COMP-2 usage.
- For more information about record element definitions and the USAGE clause, see the "IDD DDDL Reference" section.
Automatic editing uses the external picture for a field on mapout and mapin as follows:
On mapout, the external picture describes how data for the field is displayed on a terminal screen. The following example illustrates the interaction of output data and an external picture:
Program variable storage value
On mapin, automatic editing uses the external picture as follows:
- The external picture is checked to determine if the characters in the field are valid. An external picture can be NUMERIC, ALPHABETIC, or ALPHANUMERIC; data in the field must conform to the external picture specifications to be valid.
- The external picture is used to eliminate insertion characters from data.
The following example illustrates the interaction of input data and an external picture:
The external picture and input data are processed from left to right. If automatic editing is not enabled for both the map and field, the external picture is not used on mapin.
Hide Sensitive Data in External Pictures through Masking
IDMSmap field masking capability, you can use a masking character in map field external pictures to hide sensitive data without having to code it manually.
To hide sensitive data in a map display, you can mask alphabetic, alphanumeric, and numeric display fields by substituting the letter M for either an A, X, or 9 in an external picture. In the run-time map display, an asterisk appears in external picture locations where an M is used.
Masked fields that are all blanks do not receive masking characters, but remain blank.
To use masking in map fields, you must be using
IDMS19.0 with APAR SO12206 installed.
The following example illustrates how map field masking affects the external picture and field display.
Resulting Field Display
To protect record element data from being corrupted, fields with external pictures that contain a masking character
are automatically protectedin a run time map display. This automatic protection prevents them from being modified and mapped in, which corrupts record element data.
Implicit External Pictures
What is an Implicit External Picture?
If the developer does not use the online or batch compiler to explicitly specify an external picture for the field, an implicit external picture is constructed for a field. The
implicit external pictureis derived from the internal picture and/or from the usage mode that is defined for the related record element.
If Automatic Editing is not Enabled
The status of automatic editing for the field determines the external picture that is constructed for the field:
If automatic editing is not enabled for the field, the online compiler constructs the external picture for a field:
- Thedata typeis alphanumeric
- Thelengthis determined by the length (in characters/bytes) that is specified by the internal picture and/or by the usage mode of the associated record element
For example, the following table illustrates how an external picture is constructed for a field for which automatic editing is not enabled:
Internal pictures cannot be specified for COMP-1 or COMP-2 elements. The previous external pictures for COMP-1 and COMP-2 elements are the default external pictures for these elements when automatic editing is disabled for a field. To avoid an error (such as PROG-470, PROG-402, or PROG-403), automatic editing should be enabled for all fields with usage other than DISPLAY.
If Automatic Editing is Enabled
If automatic editing is enabled for the field, the online compiler assigns an external picture to the field:
- If an external picture is defined for the associated element, that external picture is assigned to the field
- If an external picture is not defined for the element, the mapping facility constructs an external picture for the field:
- The data typeis the same as the data type of the internal picture, when applicable. Fields that are associated with COMP-1 and COMP-2 elements are assigned predetermined numeric external pictures.
- The lengthis determined by the length (in characters/bytes) that is specified by the internal picture, when applicable.
- The compositionis derived from the internal picture according to the translation equivalents listed in the following table.
The following table illustrates how an external picture is constructed for a field when automatic editing is enabled:
COMP (Half word)
COMP (Full word)
COMP (Double word)
Internal pictures cannot be specified for COMP-1 or COMP-2 elements. The previous external pictures for COMP, COMP-1, -2 and -3 elements are the default external pictures for these elements when automatic editing is enabled for a field.
Internal to External Translation
Internal Picture Character
External Picture Character
. (Decimal point)
. (Decimal point)
. (Decimal point)
Explicit External Pictures
To explicitly specify an external picture for a field, the developer uses the online or batch compiler. If an explicit external picture is specified for the field, an implicit external picture is not built.
When to Specify an External Picture
An external picture can be explicitly specified for a map field either during a map-definition session or in the IDD record element definition.
During Map Definition
An external picture is explicitly specified at map definition in any of the following ways:
- TheEdit pictureprompt on the Field Definition screen
- The EXTERNAL PICTURE clause of the batch compiler MFLD statement.
An external picture specification that is made for a map field overrides any other external picture specification that has been made for the field.
An external picture can be explicitly defined by using IDD. Specifying INTERNAL for the map field's external picture causes the online compiler to use the external picture that is associated with the record element definition. External pictures for record elements are defined in the IDD DDDL RECORD ELEMENT or COBOL substatement.
For more information about these substatements, see the "IDD DDDL Reference" section.
How External Pictures are Constructed
If INTERNAL is specified for the map field's external picture but the record element is not associated with an external picture, the online compiler constructs an external picture as described in the following table:
A single alphanumeric character.
A single blank character; B can appear anywhere in the picture.
Hides sensitive data in external pictures. Use the letter M in place of an X in an external picture. In the run-time map display, an asterisk appears in external picture locations where an M is used.
Characters other than A, B, M or parentheses can be used as insertion characters.
A single numeric character (0 through 9).
An insertion character when it is preceded by a 9, a decimal point, or a zero-suppression character. Otherwise, a Z is a zero-suppression character.
Multiple dollar signs at the beginning of an external picture represent a floating dollar sign. The dollar sign is an insertion character when preceded by a 9, a decimal point, or a zero-suppression character.
Multiple asterisks at the beginning of an external picture provide check protection. The asterisk is an insertion character when preceded by a 9, a decimal point, or a zero-suppression character.
In the first position of an external picture, indicates signed data, and appears as either a minus sign or a plus sign depending on the sign of the data. Multiple plus signs at the beginning of an external picture represent a floating sign. The plus sign is an insertion character when preceded by a 9, a decimal point, or a zero-suppression character.
- (Minus sign)
In the first position of an external picture, indicates signed data. The sign position appears as a blank if the data is positive and as a minus sign if the data is negative.
Multiple minus signs at the beginning of an external picture represent a floating sign. The minus sign is an insertion character when it is preceded by a 9, a decimal point, or a zero-suppression character.
. (Decimal point)
Used as a decimal point. Data is aligned with the decimal point in an external picture and is truncated or padded when necessary. The decimal point terminates zero suppression when zero-suppression characters precede the decimal point. Zero-suppression characters become insertion characters if placed after a decimal point. The first period in a series of period characters is the decimal point in a picture. If no decimal point exists in the data, a decimal point is assumed after the rightmost numeric character. The comma (,) is used as a decimal point if DECIMAL POINT IS COMMA is specified.
A single blank character; B can appear anywhere in the picture.
Hides sensitive data in external pictures. Use the letter M in place of a 9 in an external picture. In the run-time map display, an asterisk appears in external picture locations where an M is used.
Follows a 9, A, Z, $, *, +, -, or B to represent
nconsecutive repetitions of the character.
Nmust be an integer in the range 1 through 9999. When used following an implied decimal point position, as represented by a V,
nmust be in the range 1 through 255.
Indicates the decimal point position in fixed decimal data.
Indicates a floating-point data field. The mantissa can be positive or negative. The exponent must be two numeric digits that are preceded by a plus sign. If more than two digits are entered, the online compiler truncates the picture; if fewer than two digits are entered, the picture is extended. The online compiler supplies a default external picture if automatic editing is enabled for the field. The default external picture for internal short float type data fields is +9.9(7)E+99. The default external picture for internal long float type data fields is +9.9(16)E+99.
Characters other than 9, Z, $, *, +, -, B, V, M, or parentheses can be used as insertion characters.
An alphanumeric external picture must be specified for a field associated with a group element, regardless of the data type of the subordinate elements in the group.
Alphanumeric, alphabetic, and numeric external pictures must begin with specific characters:
- Alphanumeric picturesmust begin with either an X, B, or M.
- Alphabetic picturesmust begin with either an A, B, or M.
- Numeric picturesmust begin with one of the following characters:
Allowing Insertion Characters
Including insertion characters in external pictures provides the terminal operator with flexibility in supplying data. The terminal operator need only type necessary data characters; the operator can include insertion characters in data, but omitting these characters does not constitute an error.
For example, given a telephone number with an external picture of XXXBXXX-XXXXB#BXXX, the terminal operator could enter any of the following values:
- 617 555-1212 # 341
The following considerations apply to the use of insertion characters in external pictures:
- Insertion characters can be included in external pictures to assist terminal operators in reading or interpreting output data. Insertion characters do not become part of the stored data.
- Insertion characters that are embedded in zero-suppression characters are not displayed until a significant digit appears in the data.
- The dollar sign ($) is the only insertion character that can occupy the first position in an external picture.
The following considerations apply to data supplied in fields with numeric external pictures:
- Leading and/or trailing blanks are automatically deleted from data that is entered in numeric fields. Thus, the terminal operator can start entering numeric data in any field position.
- A decimal point is assumed to exist after the rightmost digit of a terminal operator's input if the following conditions are in effect:
- A decimal point is defined in the external picture for the field
- No decimal point is supplied by the operator.The sample external picture 99.99 affects the display of numeric data in the examples in the following table:
Value input by operator
If data that is typed by the terminal operator exceeds the length permitted by the external picture, excess characters are deleted from the data as described in the following table:
Type of Field
The rightmost characters are deleted from the data.
If excess characters are supplied to the right of thedecimal, the rightmost (low-order) characters are deleted from the data.
If excess characters are supplied to the left of the decimal, the leftmost (high-order) characters are deleted from the data.
Data from which low-order characters are deleted is moved to program variable storage as usual. Numeric data from which high-order characters are deleted is not moved to program variable storage; an input error occurs for the field
The following sample external pictures demonstrate how excess characters are deleted from data:
Data stored as
ADSdialog or application program can determine whether excess data has been deleted from data in a field by inquiring if the field has been truncated.
Edit and Code Tables
Existing edit and code tables can be optionally associated with map fields. Automatic editing uses the edit and code tables for a field on mapout and mapin as follows:
- On mapout, the code table (if any) is used to convert stored data to its decoded form for display at the terminal.
- On mapin, the edit and code tables for a field are used as described:
- Theedit table(if any) is used to validate operator input. An edit table can contain either valid or invalid values:
- If the edit table contains valid values, data input in the map field is valid only if it is listed in the table
- If the edit table contains invalid values, data input in the map field is valid only if it is not listed in the table
- Thecode table(if any) is used to convert data that is typed in a field to its encoded form for storage. In this way, the code table also validates data unless NOT FOUND is used to pass incorrect data through.
A given map field can have a maximum of one edit table and one code table enabled for it. Edit and code tables cannot be specified for a field that is associated with a group element unless all its elements are defined with usage DISPLAY.
The arrangement of values in a table, the searching algorithm for a table, and the relationship between a table and a map load module that uses the table are determined by the IDD DDDL statement that defines the table.
The definition of tables is discussed in the section “Generating Edit and Code Tables".
Values in Edit and Code Tables
Edit and code tables contain the values that are used by automatic editing. Values in a table can be either numeric or alphanumeric depending on the data type specified when the table was created.
Edit Table Values
Edit table valuesmust be compatible with the data type and length of data to be evaluated at runtime. The configuration of input data at runtime depends on the specific automatic editing processes that are performed on the data.
Automatic editing performs the following processes prior to edit table operations:
- Numeric input data is reversedif REVERSE NUMERIC is enabled for the field.
- Data is altered according to external picture specificationsfor example:
- Leading and trailing blanks are stripped from numeric data
- The decimal point in numeric data is aligned with the decimal point in the external picture
- Insertion characters are stripped from data
- Characters that exceed the length that is specified by the external picture are deleted from the data
Insertion characters are not included in edit table values. For example, the following sample edit table lists values for a ROOM NUMBER field with an external picture of X-X(3) and an internal picture of X(4):
Edit Table Values
Code Table Values
Code table valuesspecify encoded and decoded values:
- Encoded valuesspecify data that can be stored in program variable storage. The data type and length of encoded values must be compatible with the internal format for the field with which the code table is associated. The internal format for a field is determined by the internal picture that is defined for the associated record element.For example, the following sample encoded values are valid in terms of their corresponding internal pictures:
- Decoded valuesspecify data that can be displayed on a terminal screen. The data type and length of decoded values must be valid in terms of the external picture for the field with which the code table is associated. Insertion characters are not included as decoded values in code tables.For example, the following sample decoded values are valid in terms of their corresponding external pictures:
On mapin, the edit table (if any) is invoked before the code table (if any) for a field.
DDDL Compiler Options
DDDL compiler conventions apply when specifying values for edit and code tables:
- Delimit words or clausesby using one of the following delimiter characters:
- Quotation mark
- Embed one or more delimiter charactersby enclosing the value that contains delimiter characters in a pair of site-standard quote characters. The single quote (') is the default. For example, the value OFFICE SERVICES in the following sample code table contains an embedded blank character:01 SHIPPING02 PERSONNEL03 ACCOUNTING04 MARKETING05 'OFFICE SERVICES'Single quotes around the value OFFICE SERVICES indicate that the space character between the two words in the value is part of the value rather than a delimiter between two values.
- Embed the site-standard quote characterin a value by coding the quote character twice. For example, the value USER'S SITE in the following sample code table includes the default quote character ('):50 DENVER60 'BOSTON RGNL OFFICE'70 'CHICAGO RGNL OFFICE'85 'USER''S SITE
For more information about DDDL compiler conventions and specifying values for tables, see the IDD DDDL Reference section.
The following special values can be included in code tables to facilitate use of the tables at runtime:
- TheNOT FOUNDkeyword can be included in a code table to define a catchall for a decoded or encoded value:
NOT FOUND must not be enclosed in quotation marks when used as a keyword. For example, the following sample code table for a DEPARTMENT field includes NOT FOUND as an encoded and a decoded value:01 SHIPPING02 PERSONNEL03 ACCOUNTING04 MARKETING05 'OFFICE SERVICES'00 NOT FOUNDNOT FOUND MISSINGThe value 00 is stored for the field when an operator supplies a value that is not included as a decoded value in this sample table. The word MISSING is displayed when a value other than 01, 02, 03, 04, 05, or 00 is stored for the field.
- As anencoded value, NOT FOUND ensures that an unanticipated stored value does not cause an abend on mapout. The decoded value that corresponds to NOT FOUND is displayed for unanticipated input.
- As adecoded value, NOT FOUND ensures that unanticipated input does not cause an input error when evaluated by the code table. The encoded value that corresponds to NOT FOUND is stored for unanticipated data.
- Thenull value, (''), two consecutive quotation marks, should be included as a decoded value in a code table in the following cases:
The following sample code table for a DEPARTMENT field included the null value as a decoded value:00 '' 01 SHIPPING 02 PERSONNEL 03 ACCOUNTING 04 MARKETING 05 'OFFICE SERVICES'The decoded value 00 is stored for this example when the operator presses ERASE EOF at the beginning of the associated alphanumeric map field and submits a null value for the field.
- Thenumeric data fieldis to be filled with zeros when automatic editing is enabled and the operator presses the ERASE EOF key, as specified by either of the following options:
- TheZero when nulloption on the Map Read/Write Options screen
- The ZEROED WHEN NULL option of the batch compiler MFLD statement
- Thealphanumeric data fieldis defined without a pad character.
Built-in Edit or Code Tables
If a record element includes an edit and/or code table in its definition, the table is referred to as a
built-inedit or code table. The built-in edit or code table is available to any map data field that uses the record. The built-in table for a field is used for the field if both of the following conditions are met:
- Automatic editing is enabled for the field (and map).
- The map developer does not use the mapping facility to specify an edit/code table.
Suppressing Built-in Tables
To suppress use of a built-in table without using another table, the developer must disable automatic editing for the field.
The map developer overrides the use of a built-in table (if any) by specifying a stand-alone table for the field. Stand-alone tables are created in the data dictionary by the DDDL TABLE statement.
Specifying a Stand-alone Table
The developer uses the online or batch compiler to specify a stand-alone table:
The Edit table name and Code table name prompts on the Additional Edit Criteria screen can be used to specify the name of a table to be used for the field. For example, the
state1table is specified as an unlinked edit table of valid values in the following sample screen.
Additional Edit Criteria Page 3 of 7 Map name: EYHTST1 Version: 1 Element name EMP-STATE-0415 Subscript In record EMPLOYEE Version 100 Edit table name . . .STATE1Version 1 Link with map (/) _ Edit type . . . . .11.Valid values 2.Invalid values Code table name . . . ________ Version ____ Link with map (/) _ Error message (specify ID or text) ID. . . . . . . . . Prefix __ Number ______ Text. . . . . . . . ________________________________________ ________________________________________ DC365801 Map options processed successfully F1=Help F3=Exit F4=Prev F5=Next F6=Preview F7=Bkwd F8=Fwd
Suppressing a Stand-alone Table
To suppress use of a specified stand-alone table without specifying another table, the map developer can eliminate the name of the table from the Additional Edit Criteria screen by performing either of the following actions:
- Pressing the ERASE EOF key to erase the table name
- Typing blanks over the table name
Specifying a Stand-alone Table using the Batch Compiler
The EDIT TABLE and CODE TABLE clauses of the batch compiler MFLD statement
ADD MFLD DEPT-ID DFLD ID-0410 EDIT TABLE IS DEPTEDIT NOLINK USAGE IS VALIDATE.
Type of table
Because each table is part of the element for which it is defined
Because they are separate from the record elements with which they are associated
Linked and Unlinked
When the map developer specifies a stand-alone table for use during automatic editing, the table must be designated either linked or unlinked as described:
If the table is
The table is included in the map load module with which it is associated.
The table is loaded at runtime by the map load module with which it is associated.
Enabling a table as an unlinked table eliminates the need to regenerate maps that use the table, should the table definition change. A stand-alone table is specified as linked or unlinked on the same screen or in the same batch MFLD statement that names the table for a field.
For more information about the definition of built-in and stand-alone table, see the "Generating Edit and Code Tables section.