The ILE C compiler allows you to process files with records that may contain fields that are considered to be null. You must specify nullcap=Y on the _Ropen() function. If a null-capable field is set to null, any data that is written into that field is not valid.
If a file is opened with nullcap=Y, the database provides input and output null maps and, if the file is keyed, a key null map. The input and output null maps consist of one byte for each field in the current record format of the file. These null field maps are used to communicate between the database and your program to indicate which specific fields should be considered null.
The _RFILE structure defined in the <recio.h> file contains pointers to the input, output and key null field maps, and the lengths of these maps (null_map_len and null_key_map_len).
When you write to a database file, you specify which fields are null with a character '1'. If a field is not null you specify the character '0'. This is specified in the null field map pointed to by the out_null_map pointer. If the file does not contain any null-capable fields, but has been opened with nullcap=Y, your program must set each field in the null field map to the character '0'. This must be done prior to writing any data to the file.
When you read from a database file, the corresponding byte in the null field map is indicated with a character '1' if the field is considered null. This is specified in the null field map pointed to by the in_null_map pointer.
The null key field map consists of one byte for each field in the key for the current record format. If you are reading a database file by key which has null fields, you must first indicate in the null key map pointed to by null_key_map which fields contain null. Specify character '1' for any field to be considered null, and character '0' for the other fields.
When the _Rupdate() function is called to update a file which has been opened to allow null field processing, the system input buffer is used. As a result, the database requires that an input null field map be provided through the in_null_map pointer. Prior to calling _Rupdate(), the user must clear and then set the input null field map (using the in_null_map pointer) according to the data which will be used to update the record.
You can use the #pragma mapinc directive to generate typedefs that correspond to the null field maps. You can cast the null field map pointers in the _RFILE structures to these types to manipulate these maps. Null field macros have also been provided in the <recio.h> file to assist users in clearing and setting the null field maps in their programs.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.