ILE COBOL Programmer's Guide

Null-Capable Fields

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.

Using Null Maps and Null Key Maps in Input and Output Operations

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.

Positioning to a Null-Capable Record in a Database File

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.

Deleting a Null-Capable Record in a Database File

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.

Example of Using Null Maps and Null Key Maps

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.

(1)
Defines the database file NULLSTDT as null-capable.

(2)
Defines data item MARK. The message (Null-capable field) appears below, since the field was defined as null-capable with the ALWNULL keyword in the DDS.

(3)
The null-capable DDS file NULLSTDT is brought into the program using the COPY DDS statement and the WITH NULL-MAP phrase.

(4)
The null map PERSON-NM is defined.

(5)
The data item MARK-NF is initialized to not null with a value of B"0". A value of B"1" in a null-capable field makes it null.

(6)
The null key map CARS-NKM is defined.

(7)
The record NULLSTDT-REC is written with the NULL-MAP IS PERSON-NM phrase, showing how the null map is used during a write operation. The NULL MAP IS phrase is also used in all of the other I/O operations.

(8)
The MARK-NF OF PERSON-NM data item is checked for a null value (B"1").

(9)
The NULLCAR-REC record is written, and both the null key map and null map need to be referenced using the NULL-KEY-MAP IS and NULL-MAP IS phrases.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]