Null-capable fields are fields that can hold null values. The null value is a special value that is distinct from all non-null values, indicating the absence of any information. For example, a null value is not the same as a value of zero, all blanks, or hex zeroes. It is not equal to any value, not even to other null values.
For each field in a database record, there is a one-byte value that indicates whether or not the field is null. If the field is null, it contains the value 1; if the field is not null, it contains the value 0. This string of values is called the null map, and there is one null map for each record in a null-capable database file. Each record format in a null-capable database file has its own null map.
If a file is also keyed, then it contains a null key map. A null key map is a separate string of similarly defined values: one for each field in the key. There is one null key map for each record in a keyed null-capable database file. Each record format in a keyed null-capable database file has its own null key map.
The values in a null map can be boolean or alphanumeric, depending on how you define the null map in the WORKING-STORAGE section. If you are using an externally described file, and you specify a COPY-DDS statement WITH NULL-MAP, then one or more null maps with boolean values will be set up for you. If you specify a COPY-DDS statement WITH NULL-MAP-ALPHANUM, then one or more null maps with alphanumeric values will be set up for you. A COPY-DDS statement WITH NULL-KEY-MAP will generate one or more null key maps with boolean values. If you are using a program-described file, you can define the null map as either boolean or alphanumeric in the WORKING-STORAGE section.
NULL-MAP-ALPHANUM extends the range of values that can be received into or sent from the null map to include values other than 0 or 1. Only a value of 1 in a null map field indicates that the field is null. For more information on values other than 0 or 1 that can be sent or received in the null map, refer to the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries 400 Information Center at this Web site - http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.
When a database record containing null-capable fields is accessed by an ILE COBOL program, the record's null key map, if one exists, and the record's null map are copied to or from the program's copy of the null map (null key map) by specifying a NULL-MAP (NULL-KEY-MAP) phrase on an I/O statement. For more information about using the NULL-MAP and NULL-KEY-MAP phrases on an I/O statement, refer to WebSphere Development Studio: ILE COBOL Reference.
Null-capable file I/O, positioning to a record, and deleting a record in a null-capable keyed file are discussed in the following sections:
For more information about handling error conditions for null-capable fields, refer to Handling Errors in Operations Using Null-Capable Fields. For more information about defining null-capable fields, and using null-capable fields with the COPY DDS statement, refer to WebSphere Development Studio: ILE COBOL Reference.
Input and output operations can be done on null-capable fields using the NULL-MAP IS or NULL-KEY MAP IS phrases in these I/O statements:
These phrases work with the system's data management settings of the null map and null key maps that define the record and its key. The settings specified in these phrases can be subscripted or reference modified.
If the ALWNULL attribute has been specified on the ASSIGN clause, and on a WRITE or REWRITE statement you do not specify a NULL-MAP IS phrase, then a string of B'0's are passed. All of the fields in the record are assumed to not be null. If the file is an indexed file and you have specified a NULL-MAP IS phrase, then you must also specify a NULL-KEY-MAP IS phrase. You must ensure that for key fields, the values in the null key map are the same as the corresponding values in the null map.
If the ALWNULL attribute has been specified on the ASSIGN clause, and on a READ statement you do not specify a NULL-MAP IS phrase, then the null map will contain the same values that it contained before the READ. The same happens for null-capable keys, if you have not specified the NULL-KEY-MAP IS phrase. If the file is an indexed file and you have specified a NULL-MAP IS phrase, then you must also specify a NULL-KEY-MAP IS phrase.
For more information about the I/O statements that allow you to work with null-capable fields, refer to the WebSphere Development Studio: ILE COBOL Reference.
To position to a null-capable record in a database file, use the NULL-KEY-MAP IS phrase in the START statement. The object of this phrase can be subscripted or reference modified. If one of the key fields referenced in the START statement is null-capable and the NULL-KEY-MAP IS phrase is not used, a null map with all zeroes is used instead.
For more information about using the NULL-KEY-MAP IS phrase to position to a null-capable record in a database, refer to the WebSphere Development Studio: ILE COBOL Reference.
To delete a null-capable record in a database file, use the NULL-KEY-MAP IS phrase in the DELETE statement. The object of this phrase can subscripted or reference modified. If one of the key fields referenced in the DELETE statement is null-capable and the NULL-KEY-MAP IS phrase is not used, a null map with all zeros is used, instead.
For more information about using the NULL-KEY-MAP IS phrase to delete a null-capable record in a database, refer to the WebSphere Development Studio: ILE COBOL Reference.
Figure 107. Example of Use of Null Map and Null Key Map--Student Information File DDS
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* THIS IS THE STUDENT INFORMATION FILE - NULLSTDT A A R PERSON A FNAME 20 A LNAME 30 A MARK 3P ALWNULL |
Figure 108. Example of Use of Null Map and Null Key Map--Car Information File DDS
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A* THIS IS THE CAR INFORMATION FILE - NULLCAR A A UNIQUE A R CARS A CARMODEL 25A ALWNULL A YEAR 4P A OPTIONS 2P A PRICE 7P 2 A K CARMODEL |
Figure 109. Example of Use of Null Map and Null Key Map
5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/NULLMAP ISERIES1 03/09/15 14:20:55 Page 2 S o u r c e STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 1 000100 IDENTIFICATION DIVISION. 2 000200 PROGRAM-ID. NULLMAP. 3 000300 ENVIRONMENT DIVISION. 4 000400 CONFIGURATION SECTION. 5 000500 SOURCE-COMPUTER. IBM-ISERIES 6 000600 OBJECT-COMPUTER. IBM-ISERIES 7 000700 INPUT-OUTPUT SECTION. 8 000800 FILE-CONTROL. 9 000900 SELECT NULLSTDT 10 001000 ASSIGN TO DATABASE-NULLSTDT-ALWNULL (1) 11 001100 ORGANIZATION IS SEQUENTIAL 12 001200 ACCESS IS SEQUENTIAL 13 001300 FILE STATUS IS NULLSTDT-STATUS. 14 001400 SELECT NULLCAR 15 001500 ASSIGN TO DATABASE-NULLCAR-ALWNULL 16 001600 ORGANIZATION IS INDEXED 17 001700 ACCESS IS DYNAMIC 18 001800 RECORD KEY IS EXTERNALLY-DESCRIBED-KEY 19 001900 FILE STATUS IS NULLCAR-STATUS. 20 002000 DATA DIVISION. 21 002100 FILE SECTION. 22 002200 FD NULLSTDT. 23 002300 01 NULLSTDT-REC. 002400 COPY DDS-ALL-FORMATS OF NULLSTDT. 24 +000001 05 NULLSTDT-RECORD PIC X(52). <-ALL-FMTS +000002* I-O FORMAT:PERSON FROM FILE NULLSTDT OF LIBRARY CBLGUIDE <-ALL-FMTS +000003* <-ALL-FMTS 25 +000004 05 PERSON REDEFINES NULLSTDT-RECORD. <-ALL-FMTS 26 +000005 06 FNAME PIC X(20). <-ALL-FMTS 27 +000006 06 LNAME PIC X(30). <-ALL-FMTS 28 +000007 06 MARK PIC S9(3) COMP-3. (2) <-ALL-FMTS +000008* (Null-capable field) <-ALL-FMTS 29 002500 FD NULLCAR. 30 002600 01 NULLCAR-REC. 002700 COPY DDS-ALL-FORMATS OF NULLCAR. 31 +000001 05 NULLCAR-RECORD PIC X(34). <-ALL-FMTS +000002* I-O FORMAT:CARS FROM FILE NULLCAR OF LIBRARY CBLGUIDE <-ALL-FMTS +000003* <-ALL-FMTS +000004*THE KEY DEFINITIONS FOR RECORD FORMAT CARS <-ALL-FMTS +000005* NUMBER NAME RETRIEVAL ALTSEQ <-ALL-FMTS +000006* 0001 CARMODEL ASCENDING NO <-ALL-FMTS 32 +000007 05 CARS REDEFINES NULLCAR-RECORD. <-ALL-FMTS 33 +000008 06 CARMODEL PIC X(25). <-ALL-FMTS +000009* (Null-capable field) <-ALL-FMTS 34 +000010 06 YEAR PIC S9(4) COMP-3. <-ALL-FMTS 35 +000011 06 OPTIONS PIC S9(2) COMP-3. <-ALL-FMTS 36 +000012 06 PRICE PIC S9(5)V9(2) COMP-3. <-ALL-FMTS 002800 37 002900 WORKING-STORAGE SECTION. 38 003000 01 NULLSTDT-STATUS PIC XX VALUE " ". 39 003100 01 NULLCAR-STATUS PIC XX VALUE " ". 40 003200 01 NULLSTDT-NM. 003300 COPY DDS-ALL-FORMATS OF NULLSTDT 5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/NULLMAP ISERIES1 03/09/15 14:20:55 Page 3 STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 003400 WITH NULL-MAP. (3) +000001* NULL MAP: PERSON FROM FILE NULLSTDT OF LIBRARY CBLGUIDE <-ALL-FMTS +000002* <-ALL-FMTS 41 +000003 05 PERSON-NM. (4) <-ALL-FMTS 42 +000004 06 FILLER PIC X(2) VALUE ZEROS. <-ALL-FMTS 43 +000005 06 MARK-NF PIC 1 VALUE B"0". (5) <-ALL-FMTS 44 003500 01 NULLCAR-NKM. 003600 COPY DDS-ALL-FORMATS OF NULLCAR 003700 WITH NULL-KEY-MAP 003800 WITH NULL-MAP. +000001* NULL MAP: CARS FROM FILE NULLCAR OF LIBRARY CBLGUIDE <-ALL-FMTS +000002* <-ALL-FMTS +000003* NULL KEY MAP: (6) <-ALL-FMTS 45 +000004 05 CARS-NKM. <-ALL-FMTS 46 +000005 06 CARMODEL-NF PIC 1 VALUE B"0". <-ALL-FMTS 47 +000006 05 CARS-NM. <-ALL-FMTS 48 +000007 06 CARMODEL-NF PIC 1 VALUE B"0". <-ALL-FMTS 49 +000008 06 FILLER PIC X(3) VALUE ZEROS. <-ALL-FMTS 003900 50 004000 PROCEDURE DIVISION. 004100 MAINLINE. 51 004200 OPEN OUTPUT NULLSTDT. 52 004300 MOVE "JOHN" TO FNAME OF PERSON. 53 004400 MOVE "SMITH" TO LNAME OF PERSON. 54 004500 MOVE B"1" TO MARK-NF OF PERSON-NM. (7) 55 004600 WRITE NULLSTDT-REC 004700 NULL-MAP IS PERSON-NM. 56 004800 CLOSE NULLSTDT. 004900 57 005000 OPEN INPUT NULLSTDT. 58 005100 MOVE " " TO FNAME OF PERSON. 59 005200 MOVE " " TO LNAME OF PERSON. 60 005300 MOVE B"0" TO MARK-NF OF PERSON-NM. 61 005400 READ NULLSTDT NULL-MAP IS PERSON-NM. 62 005500 IF FNAME OF PERSON = "JOHN" AND 005600 LNAME OF PERSON = "SMITH" AND 005700 MARK-NF OF PERSON-NM = B"1" AND (8) 005800 NULLSTDT-STATUS = "00" 63 005900 DISPLAY "NAME IS CORRECT" 006000 ELSE 64 006100 DISPLAY "NAME IS NOT CORRECT" 006200 END-IF. 65 006300 CLOSE NULLSTDT. 006400 66 006500 OPEN EXTEND NULLSTDT. 67 006600 MOVE "TOM" TO FNAME OF PERSON. 68 006700 MOVE "JONES" TO LNAME OF PERSON. 69 006800 MOVE B"1" TO MARK-NF OF PERSON-NM. 70 006900 WRITE NULLSTDT-REC NULL-MAP IS PERSON-NM. 71 007000 CLOSE NULLSTDT. 007100 72 007200 OPEN INPUT NULLSTDT. 73 007300 MOVE " " TO FNAME OF PERSON. 74 007400 MOVE " " TO LNAME OF PERSON. 75 007500 MOVE B"0" TO MARK-NF OF PERSON-NM. 5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/NULLMAP ISERIES1 03/09/15 14:20:55 Page 4 STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 007600 76 007700 READ NULLSTDT 007800 NULL-MAP IS PERSON-NM. 77 007900 READ NULLSTDT 008000 NULL-MAP IS PERSON-NM. 78 008100 IF FNAME OF PERSON = "TOM" AND 008200 LNAME OF PERSON = "JONES" AND 008300 MARK-NF OF PERSON-NM = B"1" AND 008400 NULLSTDT-STATUS = "00" 79 008500 DISPLAY "NAME IS CORRECT" 008600 ELSE 80 008700 DISPLAY "NAME IS NOT CORRECT" 81 008800 DISPLAY "NAME IS: " FNAME " " LNAME 008900 END-IF. 82 009000 CLOSE NULLSTDT. 009100 83 009200 OPEN EXTEND NULLSTDT. 84 009300 MOVE "PETER" TO FNAME OF PERSON. 85 009400 MOVE "STONE" TO LNAME OF PERSON. 86 009500 MOVE B"1" TO MARK-NF OF PERSON-NM. 87 009600 WRITE NULLSTDT-REC 009700 NULL-MAP IS PERSON-NM. 88 009800 CLOSE NULLSTDT. 009900 89 010000 OPEN I-O NULLSTDT. 90 010100 MOVE " " TO FNAME OF PERSON. 91 010200 MOVE " " TO LNAME OF PERSON. 92 010300 MOVE B"1" TO MARK-NF OF PERSON-NM. 93 010400 READ NULLSTDT 010500 NULL-MAP IS PERSON-NM. 94 010600 READ NULLSTDT 010700 NULL-MAP IS PERSON-NM. 95 010800 READ NULLSTDT 010900 NULL-MAP IS PERSON-NM. 96 011000 MOVE "BRICK" TO LNAME OF PERSON. 97 011100 MOVE B"0" TO MARK-NF OF PERSON-NM. 98 011200 REWRITE NULLSTDT-REC NULL-MAP IS PERSON-NM. 99 011300 CLOSE NULLSTDT. 011400 100 011500 OPEN I-O NULLSTDT. 101 011600 MOVE " " TO FNAME OF PERSON. 102 011700 MOVE " " TO LNAME OF PERSON. 103 011800 MOVE B"1" TO MARK-NF OF PERSON-NM. 104 011900 READ NULLSTDT 012000 NULL-MAP IS PERSON-NM. 105 012100 READ NULLSTDT 012200 NULL-MAP IS PERSON-NM. 106 012300 READ NULLSTDT 012400 NULL-MAP IS PERSON-NM. 107 012500 IF FNAME OF PERSON = "PETER" AND 012600 LNAME OF PERSON = "BRICK" AND 012700 MARK-NF OF PERSON-NM = B"0" AND 012800 NULLSTDT-STATUS ="00" 108 012900 DISPLAY "NAME IS CORRECT" 013000 ELSE 5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/NULLMAP ISERIES1 03/09/15 14:20:55 Page 5 STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 109 013100 DISPLAY "NAME IS NOT CORRECT" 110 013200 DISPLAY "NAME IS: " FNAME " " LNAME 013300 END-IF. 111 013400 CLOSE NULLSTDT. 013500*-------------------------------------------------------------* 013600* WRITE records to indexed NULLCAR. * 013700*-------------------------------------------------------------* 112 013800 OPEN OUTPUT NULLCAR. 113 013900 MOVE B"0" TO CARMODEL-NF OF CARS-NKM. 114 014000 MOVE B"0" TO CARMODEL-NF OF CARS-NM. 115 014100 MOVE "SUPERCAR" TO CARMODEL OF CARS. 116 014200 MOVE 1995 TO YEAR OF CARS. 117 014300 MOVE 2 TO OPTIONS OF CARS. 118 014400 MOVE 14799 TO PRICE OF CARS. 119 014500 WRITE NULLCAR-REC NULL-KEY-MAP IS CARS-NKM 014600 NULL-MAP IS CARS-NM. 120 014700 MOVE "FASTCAR" TO CARMODEL OF CARS. 121 014800 MOVE 1997 TO YEAR OF CARS. 122 014900 MOVE 5 TO OPTIONS OF CARS. 123 015000 MOVE 18799 TO PRICE OF CARS. 124 015100 WRITE NULLCAR-REC NULL-KEY-MAP IS CARS-NKM 015200 NULL-MAP IS CARS-NM. (9) 125 015300 MOVE B"1" TO CARMODEL-NF OF CARS-NKM. 126 015400 MOVE B"1" TO CARMODEL-NF OF CARS-NM. 127 015500 MOVE 1996 TO YEAR OF CARS. 128 015600 MOVE 5 TO OPTIONS OF CARS. 129 015700 MOVE 16199 TO PRICE OF CARS. 130 015800 WRITE NULLCAR-REC NULL-KEY-MAP IS CARS-NKM 015900 NULL-MAP IS CARS-NM. 131 016000 CLOSE NULLCAR. 016100 132 016200 OPEN I-O NULLCAR. 133 016300 MOVE B"0" TO CARMODEL-NF OF CARS-NKM. 134 016400 MOVE B"0" TO CARMODEL-NF OF CARS-NM. 135 016500 MOVE "SUPERCAR" TO CARMODEL OF CARS. 136 016600 MOVE 0 TO YEAR OF CARS. 137 016700 MOVE 0 TO OPTIONS OF CARS. 138 016800 MOVE 0 TO PRICE OF CARS. 139 016900 READ NULLCAR 017000 NULL-KEY-MAP IS CARS-NKM 017100 NULL-MAP IS CARS-NM. 140 017200 READ NULLCAR NEXT 017300 NULL-KEY-MAP IS CARS-NKM 017400 NULL-MAP IS CARS-NM. 141 017500 IF CARMODEL-NF OF CARS-NKM = B"1" AND 017600 YEAR OF CARS = 1996 AND 017700 OPTIONS OF CARS = 5 AND 017800 PRICE OF CARS = 16199 AND 017900 NULLCAR-STATUS = "00" 142 018000 DISPLAY "CAR IS CORRECT" 018100 ELSE 143 018200 DISPLAY "CAR IS NOT CORRECT" 144 018300 DISPLAY "CAR IS: " CARMODEL " " YEAR " " OPTIONS " " PRICE 145 018400 DISPLAY "NULLCAR-STATUS " NULLCAR-STATUS 018500 END-IF. 146 018600 CLOSE NULLCAR. 018700 147 018800 STOP RUN. * * * * * E N D O F S O U R C E * * * * * |
The sample program shown in Figure 109 is an example of how to use null key maps and null maps in database files to track valid students and car models.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.