Version 8.2.5
 —  Command Reference  —

Record Buffers

A record buffer defines an area in storage to which Adabas can return data or in which you supply data for processing. When a record buffer is required, a corresponding format buffer is expected as well. If a format buffer is not provided, Adabas will create a dummy format buffer (with length zero) to pair with the record buffer. For complete information about the relationships between the different types of ABD or buffer specifications, read Understanding the Different Buffer Types.

When using the ACBX direct call interface, multiple record buffers can be specified for an Adabas direct call.

Record buffers are used primarily with read, search, and update commands:

This document covers the following topics:


Specifying and Reading the SQL Null Indicator in Record Buffers

To support Adabas SQL Gateway (ACE) and other structured query languages (SQLs), fields defined with the NC/NN (not-counted/null-not-allowed) options indicate an SQL-significant null with a two-byte binary null indicator in the record buffer.

Whether a field's zero value is significant or an irrelevant null (unspecified) depends on the null indicator specified in the record buffer when the value is entered or changed, or returned in the record buffer when the value is read.

In addition to specifying or reading the value itself, either:

The null indicator is always two bytes long and has fixed-point format, regardless of the data format.

For a read (Lx) or find with read (Sx with format buffer entry) command, the null indicator value returns one of the following (hexadecimal) null indicator values, according to the actual value that the selected field contains:

Hex Value Description
FFFF A null value in the field is not significant.
0000 A null value in the field is a significant value; that is, a true zero or blank.
xxxx The field is truncated. The null indicator value contains the length (xxxx) of the entire value as stored in the database record if the length is less than 32,768.
0001 The field is significant and the value is truncated, and the length of the value does not fit into the S element because it is greater than 32, 767.

For an update (Ax) or add (Nx) command, the (hexadecimal) null indicator value in the record buffer must be set to one of the following values:

Hex Value Description
FFFF The field value is set to "undefined", an insignificant null; the field's contents in the record buffer are irrelevant when set to binary zero or blank characters.
0000 If either no value is specified in the record buffer, or binary zero or blanks are specified, the field contains a significant null value.

For an add command, if no value for the field is supplied in the record buffer for a field defined with the NC option, the field is treated as a null field. The following example shows how a null would be represented in a two-byte Adabas binary field AA defined with the NC option:

Field definition: 01,AA,2,B,NC

  For a nonzero value For a blank For null
Null Value indicator in Record Buffer 0 (binary value is significant) 0 (binary null is significant) FFFF (binary null is not significant)
Data 0005 0000 (zero) not relevant
Adabas internal representation 0205 0200 C1

For an update (A1/N1) command, the field value is always significant whenever the field is defined with the NC option; the field is treated as if a hexadecimal null indicator value of "0000" has been specified.

For a read command, if the null indicator is not specified for an NC option field, the field value is returned in the record buffer whenever there is a significant value in the record. If the Data Storage record contains a "not significant" (FFFF) indicator value for the field, response code 55 (ADARSP055) will be returned when the record is read.

Top of page

Specifying Field Lengths of LA (Long Alpha) Fields in Record Buffers

The LA option is normally used with variable-length data. If the length is not explicitly specified in the format buffer then the length of an alphanumeric field with the LA option can be specified in the record buffer or will be returned by Adabas.

The field value is preceded by a two-byte length field containing the length of the value, plus 2 (inclusive length).

Format Buffer
BA, ... .

or

BA,0, … .
Name of the fields to be read without explicit length specifications.
Record Buffer
X´0005C1C1C1´...

or

X´2712...(10,000 characters)...
Field values specified for Adabas or returned by Adabas in hexadecimal.

In the first case the value is three bytes long; in the second case the value is 10,000 bytes long.

Top of page

Specifying Field Lengths of LOB (Large Object) Fields in Record Buffers

The LB option is normally used with variable-length data. If the length is not explicitly specified in the format buffer then the length of an alphanumeric field with the LB option can be specified in the record buffer or will be returned by Adabas.

The field value is preceded by a four-byte length field containing the length of the value, plus 4 (inclusive length).

Format Buffer
L1, ... .

or

L1,0, … .
Name of the fields to be read or updated without explicit length specifications.
Record Buffer
X´00000007C1C1C1´...

or

X´000186A4...(100,000 characters)...
Field values specified for Adabas or returned by Adabas in hexadecimal.

In the first case the value is three bytes long; in the second case the value is 100,000 bytes long.

Top of page

Specifying the Daylight Savings Time Offset in Record Buffers

The daylight savings offset from standard time (in seconds) is specified in the record buffer associated with the format buffer in the following format:

H'nnnn'

The value nnnn represents the number of seconds that the stored time should be offset from standard time to calculate daylight savings time. A value of zero indicates that standard time should be used; any value other than zero indicates that daylight savings time should be adjusted for and specifies the offset for that adjustment.

Suppose the definition of field AA in the FDT is:

"1,AA,14,U,TZ,DT-E(DATETIME)"

A valid format buffer might be:

"AA,14,U,AAD,2,F."

The corresponding record buffer might be:

"20080814120000",H'3600'

In this example the daylight savings offset for field AA is 1 hour (3600 seconds) from standard time.

Read Daylight Savings Indicator (D) for more information about daylight savings indicator usage in format and search buffers.

Top of page