CHECK (Check) keyword for display files
CHECK (Check) keyword for display files
You use this keyword to perform a number of functions, depending on the parameter values specified.
Function : Valid parameter values
Validity checking : AB, ME, MF, M10, M10F, M11, M11F, VN, VNE
Keyboard control : ER, FE, LC, RB, RZ
Cursor control : RL, RLTB
The formats of the keyword are:
CHECK(validity-checking-code [. . .])
CHECK(keyboard-control-code [. . .])
CHECK(cursor-control-code)The following CHECK keywords are the preferred form of other DDS keywords:
- CHECK(ER) is equivalent to AUTO(RA)
- CHECK(LC) is equivalent to LOWER
- CHECK(RB) is equivalent to AUTO(RAB)
- CHECK(RZ) is equivalent to AUTO(RAZ)
The following CHECK keyword functions can also be specified using the Change Input Default (CHGINPDFT) keyword at the file, record, or field level:
CHECK keyword : CHGINPDFT equivalent
CHECK(FE) : CHGINPDFT(FE)
CHECK(LC) : CHGINPDFT(LC)
CHECK(ME) : CHGINPDFT(ME)
CHECK(MF) : CHGINPDFT(MF)
Option indicators are valid only for CHECK(ER) and CHECK(ME).
Validity checking
Use CHECK at the field level to specify that the IBM i operating system or the device is to check the validity of the data typed into an input-capable (input-only or input/output) field.
CHECK validates the data by applying one or more edit/check algorithms against the data. An error message is displayed if a specified edit/check algorithm is not satisfied.
Note: See CHKMSGID (Check Message Identifier) keyword for display files for information about defining user-specified messages.
The valid edit/check codes are:
Edit/Check code : Meaning
AB : Allow blanks
Use this code at the file level, record
level, or field level to allow all-blank input to satisfy validity
checking for an input-capable field when any associated validity check
fails. This enables the passing of data to the program when the workstation
user has positioned the cursor to the field but left it blank (for
instance, by pressing the Erase Input key, the Field Exit key, or
the spacebar). For example, FLD1 is an input-capable field with CHECK(M10
ME) in effect. If the workstation user accidentally types in the field,
the M10 algorithm must be satisfied. By specifying (CHECK(M10 ME AB)),
you enable the display station user to clear the field to satisfy
validity checking.
When specified at the file level, this keyword
applies for all input-capable fields in the file for which a validity
checking keyword is coded. Likewise, when specified at the record
level, this keyword applies for all input-capable fields in the record
for which a validity checking keyword is coded. At the field level,
always specify this keyword with another validity checking keyword
(CHECK(M10, M10F, M11, M11F, VN, VNE), CHKMSGID, COMP, RANGE, or VALUES).
CHECK(AB)
should not be specified if SFLROLVAL or SFLRCDNBR is also specified
for the field.
CHECK(AB) can be used in database files for reference
purposes.
When you consider using CHECK(AB) with other validity
checking functions, note that processing occurs in the following order:
1. Any of the following order:
1. The keyboard shift attribute specified in position 35 (such as
alphanumeric shift or numeric only) can restrict input typing to certain
characters.
2. If the keyboard shift attribute is numeric shift, the data type
(character or numeric) is set by the entry in positions 36 through
37 (decimal positions) and restricts input typing to certain characters.
3. The CHECK(FE), CHECK(MF), and CHECK(ME) keywords, if specified,
restrict input typing.
2. Either of the following order:
1. If CHECK(AB) is specified, data management passes the input data
to the program (blanks for a character field and zeros for a numeric
field). No further validity checking is done.
2. If CHECK(AB) is not specified, data management performs the following
validity checking functions before passing the data to the program:
CHECK(VN), CHECK(VNE), CHECK(M10), CHECK(M10F), CHECK(M11), CHECK(M11F),
COMP(. . .), RANGE(. . .), VALUES(. . .).
You cannot specify the CHECK(AB) keyword on a floating-point
field (F in position 35).
Option indicators are not valid for
this keyword.ME : Mandatory enter
This code specifies that at least 1 character
of data (a blank is valid) must be typed into the field. Note that
when no field currently on the display has been changed, the display
station does not enforce mandatory enter. To enforce mandatory enter,
specify DSPATR(MDT) for at least one field in each record on the display.
For all other fields in the record, CHECK(ME) is then enforced. However,
because the device cannot determine if the user has typed data to
a field with both DSPATR(MDT) and CHECK(ME), you should also specify
DSPATR(ND) so that this field is not displayed.
Option indicators
are valid for this keyword.MF : Mandatory fill
This code specifies that if any part of the
field is altered, each position in the field must have a character
entered in it. Blanks are considered valid characters.
This
code cannot be specified with keyboard control codes (RB or RZ) or
with the WRDWRAP keyword.
Option indicators are not valid for
this keyword.M10/M10F or M11/M11F (IBM® Modulus 10 or Modulus 11 Algorithm) : IBM Modulus 10 self-check algorithm
This code
specifies that data typed into the field must satisfy the IBM Modulus
10 (M10 or M10F) or Modulus 11 (M11 or M11F) self-check algorithm.
When you specify CHECK(M10) or CHECK(M11), the self-check verifies
that the field has a valid Modulus 10 or Modulus 11 number when you
press the Enter key or a function key. When you specify CHECK(M10F)
or CHECK(M11F), the self-check verifies that the field has a valid
Modulus 10 or Modulus 11 number as the user types the data into the
field. You cannot specify both the Modulus 10 and the Modulus 11 self-check
algorithms for the same field or both formats of the same algorithm
for the same field.
A self-check field is composed of two parts:
the base number and one check digit. The check digit is the farthest
right digit in the field. The base number and the check digit together
make up a field in your database (for example, an account number).
The following figure is an example of an 8-digit self-check field.
See
the [Application Display Programming book](http://public.dhe.ibm.com/systems/power/docs/systemi/v6r1/en_US/sc415715.pdf "(Opens a PDF file)") for
information about how to use CHECK(M10), CHECK(M10F), CHECK(M11),
and CHECK(M11F).
Notes:
1. The IBM i operating
system supports a maximum length of 31 digits for numeric fields.
2. You cannot specify the CHECK(M10), CHECK(M10F), CHECK(M11), and
CHECK(M11F) keywords with the COMP(EQ) keyword.
3. You cannot specify the CHECK(M10), CHECK(M10F), CHECK(M11), and
CHECK(M11F) keywords on a floating-point field (F in position 35).
4. You cannot specify the CHECK(M10F) or the CHECK(M11F) keyword
in a file containing the USRDSPMGT keyword.
5. You cannot specify the CHECK(M10F) or the CHECK(M11F) keyword
on a field containing the CHKMSGID or WRDWRAP keyword.
For each position in the base number, there is
a Modulus 10 weight factor and a Modulus 11 weight factor. Positions
are counted from the farthest right digit (not including the check
digit).
The Modulus 10 weight factor is 2 for positions 1, 3,
5, …, 31. It is 1 for positions 2, 4, 6, …, 30. The Modulus 11 weight
factors are 2, 3, 4, 5, 6, 7, 2, 3, 4, 5, 6, 7,…, 2, 3, 4, 5, 6, 7,
2 for positions 1, 2,…, 31.
To calculate the Modulus
10 self-check digit, follow these steps:
1. Multiply the units position and every alternate position of the
base number by 2.
2. Add the digits in the products to the digits in the base number
that were not multiplied.
3. Subtract the sum from the next higher number ending in zero.
The difference is the self-check digit.
For example:
```rpgle
Base number: 6 1 2 4 8
Units position and every alternate position: 6 2 8
Multiply by the weight factor, 2: x2 x2 x2
Products: 12 4 16
Digits not multiplied: 1 4
Add the digits of the products and the digits
from the base number that were not used for
multiplication: ( 1 + 2 ) + 4 + ( 1 + 6 ) + 1 + 4 = 19
Next higher number ending in 0: 20
Subtract: -19
Self-check digit: 1
```
To calculate the Modulus 11 self-check digit, follow
these steps:
1. Assign a weight factor to each digit position of the base number.
These factors are: 2, 3, 4, 5, 6, 7, 2, 3, 4, 5, 6, 7, 2, 3, . .
. starting with the units position of the number and progressing toward
the high-order digit. For example, the base number 991246351 can
be assigned the weight factors as follows:
```rpgle
Base number 9 9 1 2 4 6 3 5 1
Weight factors 4 3 2 7 6 5 4 3 2
```
2. Multiply each digit by its weight factor.
3. Add the products.
4. Divide this sum by 11.
5. Subtract the remainder from 11.
The difference is the self-check digit.
For example:
Base number
: 1 3 7 3 9
Weight factors
: x6 x5 x4 x3 x2
Multiply each digit by its weight factor
: 6 15 28 9 18
Add the products
: 6 + 15 + 28 + 9 + 18 = 76
Divide the sum by 11
: 76/11 = 6 plus a remainder of 10
Subtract the remainder from 11
: 11 - 10 = 1
Self-check digit
: 1
Note: If the remainder in step 4 is 0, the self-check
digit is 0. If the remainder is 1, the base number has no self-check
digit; you must make sure that such base numbers are not used in the
fields you define as self-check fields.
Option indicators
are not valid for CHECK(M10), CHECK(M10F), CHECK(M11), or CHECK(M11F).VN : Validate name
Use this code to specify that the data typed
into the field must be a valid simple name. The first character must
be $, #, @, or A through Z. The remaining characters must be alphanumeric
($, #, @, A through Z, 0 through 9, or underscore (\_), and must not
contain embedded blanks.
When the CHECK(VN) keyword is specified
on a field, the field must be character (keyboard shift of A, N, X,
W, or I), and must be input-capable (usage of I or B).
CHECK(VN)
cannot be specified with any of the following keywords:
| | |
| --- | --- |
| CHECK(M10) CHECK(M10F) CHECK(M11) CHECK(M11F) | CHECK(VNE) COMP RANGE VALUES |
Option indicators are not valid for this keyword.VNE : Validate name extended
Use this code to specify that the data
typed into the field must be a valid extended name.
When the
CHECK(VNE) keyword is specified on a field, the field must be character
(keyboard shift of A, N, X, W, or I), input-capable (usage of I or
B), and have a maximum length of 255 characters.
If the name
is not delimited by double quotation marks:
* The first character must be A through Z, a through z, #, $, or
@.
* The remaining characters must be A through Z, a through z, #,
$, \_, or a period.
* Lowercase letters will be converted to uppercase.
If the name is delimited by double quotation marks:
* Any character is allowed except:
Hex 00 through Hex 3F
: (device control)
Hex FF
: (device control)
Hex 40
: (blank)
Hex 5C
: (\*)
Hex 6F
: (?)
Hex 7D
: (')
Hex 7F
: (")
* Lowercase letters remain lowercase.
* The system removes quotation marks when they are not needed (if
the syntax of the name meets the requirements of an unquoted name,
and all letters are uppercase).
CHECK(VNE) cannot be specified with any of the following
keywords:
| | |
| --- | --- |
| CHECK(M10) CHECK(M10F) CHECK(M11) CHECK(M11F) | CHECK(VN) COMP RANGE VALUES |
Option indicators are not valid for this keyword.Keyboard control
When the CHECK keyword is used with a keyboard control code, it controls certain data-entry aspects. The valid keyboard control codes are:
Keyboard control code : Meaning
ER : End of record; equivalent to AUTO(RA)
Use this code so that
the workstation user does not need to press the Enter key. Whenever
the workstation user keys a character (including a blank) into the
last position of the field, the record is sent from the device just
the same as if the Enter key had been pressed. If you also specify
DSPATR(SP) for the field, the record is sent from the device as soon
as the workstation user selects the field. If you use this function,
it should be on the last field typed in by the user for this record.
Option
indicators are valid for this keyword.FE : Field exit check
This code specifies that the workstation user
cannot advance to the next input field without pressing one of the
field exit keys. The cursor remains under the low-order character
position of the field until a valid field exit key has been pressed,
even though that character has been typed in. If the user presses
any other key, an error results.
If you want to specify CHECK(FE)
for all the input-capable fields in a record format, specify CHGINPDFT(FE)
at the record level. If you want to specify CHECK(FE) for all the
input-capable fields in a file, specify CHGINPDFT(FE) at the file
level.
Field exit keys include the Field Exit, Field+, Field-,
and cursor movement keys. Which keys are valid field exit keys depends
on the keyboard style being used.
This code applies only to
input fields into which the workstation user can type.
Option
indicators are not valid for this keyword.LC : Lowercase; equivalent to LOWER
Use CHECK(LC)
for input-only or input/output fields to permit the workstation user
to type lowercase a through z. The way the workstation user types
the characters (uppercase or lowercase) is the way the characters
appear on the display and are returned to your program.
If you
want to specify CHECK(LC) for all the character input-capable fields
in a record format, specify CHGINPDFT(LC) at the record level. If
you want to specify CHECK(LC) for all the character input-capable
fields in a file, specify CHGINPDFT(LC) at the file level.
Your
program can display a field that contains both uppercase and lowercase
characters.
If you specify this keyword, lowercase a through
z remain lowercase. If you do not specify this keyword, lowercase
a through z are changed to uppercase.
The CHECK(LC) keyword
has no effect on data-entry keyboards. Data-entry keyboards do not
support lowercase characters a through z.
Option indicators
are not valid for this keyword.
[Figure 1](#rzakcmstdfcheck__exchlc) shows how to specify the CHECK(LC)
keyword.
Figure 1. Specifying the CHECK(LC) keyword
```rpgle
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00100A NAME 30 I 3 2CHECK(LC)
A
```RB : Right-aligned with blank fill; equivalent to AUTO(RAB)
This
code shifts data typed into the field to the farthest right positions
and fills the remaining positions with blanks.
For
signed numeric fields, you do not need to specify CHECK(RB). Right-aligned
with blank fill is the default. When the value of a signed numeric
field is zero, the field appears as all blanks on the display.
The IBM i program converts blanks
to zeros when returning numeric fields to your program.
Option
indicators are not valid for this keyword.RZ : Right-aligned with zero fill; equivalent to AUTO(RAZ)
This
code shifts data typed into the field to the farthest right positions
and fills the remaining positions with zeros.
For signed numeric
fields, if you do not specify CHECK(RZ), CHECK(RB) is the default.Option indicators are not valid with this keyword.
The following list shows programming considerations for CHECK(RB) and CHECK(RZ):
- You can activate right-alignment only by pressing the Field Exit, the Field+, or the Field- key. If you use the cursor movement keys to exit from a right-aligned field, the field is not right-aligned. It is left as is.
- Right-aligned fields longer than 15 character positions slow keyboard entries.
- The Dup key fills a right-aligned field from the cursor location to the end of the field with the duplication character, but the field is not right-aligned.
- You cannot specify the CHECK(RB) or CHECK(RZ) keyword on a field containing the WRDWRAP keyword.
Example 1
The following example shows how to specify the CHECK keyword for right-aligned with blank fill (RB) and for right-aligned with zero fill (RZ).
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A R RECORD1
00020A* Numeric only
00030A DATA1 7Y OI 2 2TEXT('No right-adjust')
00040A DATA2 7Y OI 3 2CHECK(RZ)
00050A* Signed numeric
00060A DATA3 7S OI 4 2TEXT('CHECK(RB) is the default')
00070A DATA4 7S OI 5 2CHECK(RZ)
00080A* Character
00090A DATA5 7 I 6 2TEXT('No right-adjust')
00100A DATA6 7 I 7 2CHECK(RB)
AWhen you specify the CHECK keyword for right-aligned with zero or blank fill, fill the following displays:
| Field name | Data typed in | Key pressed | Result on display |
|---|---|---|---|
| Numeric only | |||
| DATA1 | 1. 1 2 3 _ _ _ _ 2. 1 2 3 – _ _ _ 3. 0 _ _ _ _ _ _ 4. _ _ _ _ _ _ _ | * Field Exit * Field Exit * Field Exit * Field Exit | * 1 2 3 _ _ _ _ * 1 2 3 – _ _ _ * 0 _ _ _ _ _ _ _ See note. * _ _ _ _ _ _ See note. |
| DATA2 | 1. 1 2 3 _ _ _ _ 2. 1 2 3 – _ _ _ 3. 0 _ _ _ _ _ _ 4. _ _ _ _ _ _ _ | * Field Exit * Field Exit * Field Exit * Field Exit | * 0 0 0 0 1 2 3 * 0 0 0 1 2 3 – * 0 0 0 0 0 0 0 * 0 0 0 0 0 0 0 |
| Signed Numeric | |||
| DATA3 | 1. 1 2 3 _ _ _ _ _ 2. 1 2 3 _ _ _ _ _ 3. 0 _ _ _ _ _ _ _ 4. _ _ _ _ _ _ _ _ | * Field Exit * Field- * Field Exit * Field Exit | * _ _ _ _ 1 2 3 _ * _ _ _ _ 1 2 3 – * _ _ _ _ _ _ 0 _ See note. * _ _ _ _ _ _ _ _ See note. |
| DATA4 | 1. 1 2 3 _ _ _ _ _ 2. 1 2 3 _ _ _ _ _ 3. 0 _ _ _ _ _ _ _ 4. _ _ _ _ _ _ _ _ | * Field Exit * Field- * Field Exit * Field Exit | * 0 0 0 0 1 2 3 _ * 0 0 0 0 1 2 3 – * 0 0 0 0 0 0 0 _ * 0 0 0 0 0 0 0 _ |
| Note: The IBM i operating system converts blanks to zeros when returning numeric fields to your program. Therefore, this field is returned to your program as all zeros. | |||
| Character | |||
| DATA5 | 1. 1 2 3 _ _ _ _ 2. 1 2 3 – _ _ _ 3. 0 _ _ _ _ _ _ 4. _ _ _ _ _ _ _ 5. A B C _ _ _ _ | * Field Exit * Field Exit * Field Exit * Field Exit * Field Exit | * 1 2 3 _ _ _ _ * 1 2 3 – _ _ _ * 0_ _ _ _ _ _ * _ _ _ _ _ _ _ * A B C _ _ _ _ |
| DATA6 | 1. 1 2 3 _ _ _ _ 2. 1 2 3 –_ _ _ 3. 0 _ _ _ _ _ _ 4. _ _ _ _ _ _ _ 5. A B C _ _ _ _ | * Field Exit * Field Exit * Field Exit * Field Exit * Field Exit | * _ _ _ _ 1 2 3 * __ _ 1 2 3 – * _ _ _ _ _ _ 0 * _ _ _ _ _ _ _ * __ _ _ A B C |
Cursor control
When the CHECK keyword is used with a cursor control code, it specifies that the cursor is to move from right to left. This feature is designed for languages where information is read right to left.
The IBM i operating system does not ensure that right-to-left files are opened only for display stations capable of right-to-left cursor movement. Therefore, all workstations in the same system should be configured with the same language capability and with the same right-to-left capability.
The valid cursor control codes that can be specified for cursor control are:
Cursor control code : Meaning
RL : Right-to-left cursor movement within fields
Use the CHECK(RL)
keyword at the file, record, or field level to specify that the cursor
should move from right to left within input-capable character fields.
At the file level, specifying CHECK(RL) makes the cursor move from
right to left in all input-capable character fields in the file. At
the record level, specifying CHECK(RL) makes the cursor move from
right to left in all input-capable character fields in the record.
At the field level, specifying CHECK(RL) makes the cursor move from
right to left in only the field with which it is associated.
**Example
2:**
The following example shows how to specify the CHECK(RL)
keyword at the file level.
```rpgle
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A CHECK(RL)
00020A R DSPLY
A
```
**Example 3:**
The following example
shows how to specify the RL cursor control with edit check.
```rpgle
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
A :
A :
A R RECORD1 CHECK(RL AB)
A :
A :
A R RECORD2
A INPFLD 4 I 4 10CHECK(RL MF)
A :
A :
A
```
Note: If you want to specify the RL cursor control
code with an edit/check code, you can do so only if the edit/check
code is valid at the level you specify. In the example above, CHECK(RL
AB) is specified at the record level because AB is valid at that level.
CHECK(RL MF) is specified at the field level because MF is valid only
at that level.RLTB : Right-to-left, top-to-bottom cursor movement from field to field
Use
the CHECK(RLTB) keyword only at the file level. It specifies the direction
the cursor is to advance from input-capable field to input-capable
field. CHECK(RLTB) specifies that on exiting from a field, the cursor
advances by moving from right to left and from top to bottom of the
display until it reaches the next input-capable field. You can specify
the RLTB cursor control code with only the edit/check code AB, as
the others are not valid at the file level.
Note: Specifying CHECK(RLTB)
does not change which input-capable field the cursor is positioned
in when the display initially appears.
**Example 4:**
The
following example shows how to specify the CHECK(RLTB) keyword.
```rpgle
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A CHECK(RLTB)
00020A R PROMPT
A
```Right-to-left capability restrictions
The right-to-left capability includes the following restrictions:
- The check digit for modulus checking is the farthest right byte in the field.
- Katakana cannot be used with right-to-left support.
- CHECK(RL) and CHECK(RLTB) cannot be specified with user-defined records (having the USRDFN keyword).
- CHECK(RL) applies only to character fields.
- You cannot specify the CHECK(RB) or CHECK(RZ) keyword on a field containing the WRDWRAP keyword.
A warning message appears for the following conditions:
- A right-to-left field that also allows magnetic card reader operator identification data (DSPATR(OID) keyword)
- A right-to-left field that spans more than one line
- A right-to-left field that is also a self-check field (CHECK(M10) or CHECK(M11) keyword)
- A right-to-left field for which CHECK(RZ) or CHECK(RB) is specified
Option indicators are not valid with cursor control codes.
Example 5
The following example shows how to specify the validity-checking CHECK keywords.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00060A R RECORD1 CHECK(AB)
00070A FIELD11 10 B 1 2TEXT('CHECK(AB) not propagated to +
00080A this field')
00090A FIELD21 10 B 1 22CHECK(VN)
00100A TEXT('CHECK(AB) is propagated to +
00110A this field')
00120A FIELD31 10 B 1 42CHECK(VNE)
00130A TEXT('CHECK(AB) is propagated to +
00140A this field')
00150A*
00160A R RECORD2
00170A FIELD12 10 B 2 2CHECK(VN) CHECK(AB)
00180A FIELD22 10 B 2 22CHECK(VN AB)
00190A FIELD32 1 B 2 42CHECK(AB) VALUES('A' 'B' 'C')
00200A FIELD42 10 B 2 62CHECK(VN)
00210A FIELD52 10 B 3 2CHECK(VNE)
00220A FIELD62 10 B 3 22CHECK(VNE AB)
00230A FIELD72 10 B 4 1CHECK(ME MF)
00240A FIELD82 8 OB 4 22CHECK(M10)
00250A FIELD92 10 OB 4 42CHECK(M11)
A