Support for variable-length database segments

Because IMS is a hierarchical database, IMS translates SQL statements into DL/I calls that can be interpreted by the IMS Database Manager. When using the IMS Database Manager, applications must manage the length of individual variable-length segment instances with the LL field for the segment. Applications that use the IMS Universal DL/I driver or SQL support for COBOL are responsible for managing the LL field.

For application programs that use the IMS Universal database resource adapter or the IMS Universal JDBC driver driver treat IMS databases as standard JDBC data sources. The IMS Universal Database resource adapter and IMS Universal JDBC driver internally manage the LL field on behalf of the application, so that the application program does not need to manage the segment length or the size of the I/O area. For read operations, the IMS Universal Database resource adapter and IMS Universal JDBC driver handle the offsets and lengths of all the segments and fields returned. By default, the SQL result set contains the LL field information. For update or insert operations, each instance of a variable-length segment is automatically expanded to contain the largest field (determined by the field length and offset) in the segment instance.

For SQL support for COBOL, COBOL applications are responsible for managing the LL field.

In a variable-length segment, some fields might be nullable. In IMS, a nullable field is a field that has a starting offset or combined offset and length larger than the minimum length of the segment. You can determine if a nullable field exists for a particular segment instance by comparing the LL value for the instance to the combined offset and length for the nullable field. If the LL value is less than the combined offset and length of the field, the field is null. For example, if a segment definition includes a field that starts at offset 50 and is length 5, it is nullable if the minimum length of the segment is less than 55. It is null for a particular segment instance if the LL value for that instance is less than 55.

You can also use the null indicator variable for COBOL or java.sql.ResultSet.wasNull method for IMS Universal Database resource adapter and IMS Universal JDBC driver to determine whether a nullable field exists in an instance of a variable-length segment without examining the LL data.

Using the LL field with the IMS Universal Database resource adapter and IMS Universal JDBC driver

By default, the LL field for a variable length segment is returned as a visible column for SQL queries, and the IMS Universal database resource adapter or IMS Universal JDBC driver manages the LL field on behalf of your application program. If you use this option, you can make LL field data inaccessible to any query type (including SELECT *) by setting the connection property to false.

Alternatively, you can use your application program to set and control the LL field. To do so, set the llField property to true through the standard properties list of either of the following interfaces:

java.sql.DriverManager.getConnection(String url, Properties properties)

com.ibm.ims.jdbc.IMSDataSource.setProperties(Properties properties)

When the llField=true property is set, the LL field is exposed as a normal column in the standard SQL result set for all operations. You can read, insert, or update the LL field data directly. Deleting the LL field data also deletes the rest of the associated database record. To set a field to the null state, set the length of the segment (the value of the LL field column) to be smaller than the offset of the field within the segment.

The LL field is 2 bytes long and must be handled as BINARY, SHORT, or USHORT data.

Using the LL field with COBOL

The LL field is treated as a normal column in the standard SQL result set for all operations. You can read, insert, or update the LL field data directly. Deleting the LL field data also deletes the rest of the associated database record. To set a field to the null state, set the length of the segment (the value of the LL field column) to be smaller than the offset of the field within the segment.

The LL field is 2 bytes long and must be handled as BINARY, SHORT, or USHORT data.

Checking for null field instances with the IMS Universal DL/I driver

Applications that use the IMS Universal DL/I driver always receive the LL field data for a variable-length segment. You can determine if a field is null in a segment instance in one of two ways: either compare the LL field data to the offset of the field, or use the com.ibm.ims.dli.Path.wasNull() method.

The com.ibm.ims.dli.Path.wasNull() method returns a boolean value for the null state of the last field that was read. The returned value is true if the field is null. You must attempt to read a field before calling the wasNull() method to determine whether the field is null.

Checking for null field instances in COBOL

Applications that use the SQL for COBOL always receive the LL field data for a variable-length segment. You can determine if a field is null in a segment instance in one of two ways: either compare the LL field data to the offset of the field, or use the null indicator variable.