The size of the log sequence number (LSN) has increased
from six-bytes to eight-bytes. A new data type, db2LSN,
has been created in support of the new LSN size.
A number of APIs with input and output structures containing LSN
fields have been updated to use the new db2LSN data type. The updated
APIs are discussed below. To ensure that the latest versions of the
APIs are used, the new DB2® version
number constant must be passed to the APIs through the version number
API input parameter.
Resulting from the LSN size increase and the creation of new versions
of the APIs, the behavior of the affected APIs is dependent on the
current client-server configuration and the level of the applications
in use. Under certain scenarios there are restrictions and conditions
to take note of regarding the extent of the APIs abilities.
Note: For the older APIs listed below, these APIs do not have new
versions and therefore their structures do not make use of the db2LSN
data type, though their behavior is still influenced by the client-server
configuration being used.
db2ReadLog API
The behavior
of the db2ReadLog API changes depending on the
client-server configuration.
Here are the possible configurations:
- Latest client and latest server: An error message SQL2032N is
returned if existing applications make use of the older version of
the db2ReadLog API. Calls to the older version
of the db2ReadLog API are not supported.
Such applications must be updated to make use of the latest version
of the db2ReadLog API. If you are using an application
developed with the latest version of the db2ReadLog API,
then there are no restrictions on the functions of the API.
Note: If
the client and server are on differing endian platforms, then all
native data type fields in the db2ReadLogInfoStruct output
structure are byte-reversed, including the LSN fields.
- Older client and latest server: As with the previous configuration,
older level db2ReadLog API calls are not supported
and the error message SQL2032N is returned. The client
must be upgraded and any existing applications updated to use the
latest version of the db2ReadLog API in order to
proceed.
- Latest client and older server: Whether the latest version of
the db2ReadLog API is invoked from within a newly
developed application, or an older version db2ReadLog API
call is made from an existing application, there are no restrictions
on the functions of the API. In both cases however, the log records
returned in the log buffer are representative of the old log records,
with the old LSN format.
Note: If the client and server are on differing
endian platforms, then all native data type fields in the db2ReadLogInfoStruct output
structure are byte-reversed, excluding the LSN fields.
db2ReadLogNoConn API
The
behavior of the db2ReadLogNoConn API changes depending
on the client-server configuration.
Here are the possible configurations:
- Latest client and latest server: An error message SQL2032N is
returned if existing applications make use of the older version of
the db2ReadLogNoConn API. Calls to the older version
of the db2ReadLogNoConn API are not supported.
Such applications must be updated to make use of the latest version
of the db2ReadLogNoConn API. If you are using an
application developed with the latest version of the db2ReadLogNoConn API,
then there are no restrictions on the functions of the API.
db2HistoryGetEntry API
The
behavior of the db2HistoryGetEntry API changes
depending on the client-server configuration.
Here are the possible
configurations:
- Latest client and latest server: An error message SQL2032N is
returned if existing applications make use of the older version of
the db2HistoryGetEntry API and if the LSNs of the
history file entries are larger than can be contained by the "oLastLSN" field
of the older level API output structure. Such applications must be
updated to make use of the latest version of the db2HistoryGetEntry API
to correct this behavior. If you are using an application developed
with the latest version of the db2HistoryGetEntry API,
then there are no restrictions on the functions of the API.
- Older client and latest server: An error message SQL2032N is
returned if an older version of the db2HistoryGetEntry API
is used, and if the LSNs of the history file entries are larger than
can be contained by the "oLastLSN" field of the older level API
output structure. An upgrade of the client and an update of the existing
applications updated are needed to correct the problem.
- Latest client and older server: If the latest version of the db2HistoryGetEntry API
is invoked from within a newly developed application, or if a call
to the earlier version of the db2HistoryGetEntry API
is made from an existing application, then there are no restrictions
on the functions of the API.
db2Prune API
The behavior
of the db2Prune API changes depending on the client-server
configuration.
Here are the possible configurations:
- Latest client and latest server: If you are using a new application
with the latest version of the db2Prune API, or
you are using and existing application that utilizes an earlier version
of the db2Prune API, then there are no restrictions
on the functions of the API.
- Older client and latest server: If you are using an existing application
and making calls to an earlier version of the db2Prune API,
then there are no restrictions on the functions of the API.
- Latest client and older server: When using the latest version
of the db2Prune API with an LSN string as input,
an error message SQL2032N is returned if the LSN
string either represents an LSN that exceeds the value 0xFFFF FFFF
FFFF, or the LSN string is less than 12 characters in length. To bypass
this error, the server must be upgraded to at least match the level
of the client. If making calls to an older version of the db2Prune API
through an existing application, there are no restrictions on the
functions of the API as introduced by the changes to the LSN.
sqlbftpq API, sqlbstpq API,
and sqlbmtsq API
The behavior of the sqlbftpq API, sqlbstpq API,
and sqlbmtsq API changes depending on the client-server
configuration.
Here
are the possible configurations:
- Latest client and latest server: For each of these APIs, if calls
are made to an earlier version of the API through an existing application,
an error message SQL2032N is returned, provided that
the LSN returned is larger in size than the "lifeLSN" field of
the older SQLB_TBSPQRY_DATA structure can contain.
There is an additional consideration for the sqlbmtsq API:
when making a call to an earlier version of this API, the "lifeLSN" field
of the SQLB_TBSPQRY_DATA structure will contain
an invalid value, even though all other fields of the structure contain
valid values. Updating the applications to use the latest versions
of the APIs can solve these problems. If using the latest versions
of these APIs, then there are no restrictions on the functions of
the APIs.
- Older client and latest server: For this configuration, exercising
the earlier version of any of the three APIs results in a behavior
that mirrors the behavior of the APIs in the configuration where both
the client and server are of the latest release, as noted above, excluding
the limitation noted for the sqlbmtsq API. To resolve
these limitations, the client must be upgraded to at least the release
level of the server, and the applications in use updated to make use
of the latest versions of the APIs.
- Latest client and older server: When making a call to an earlier
version of the sqlbmtsq API through an existing
application, the "lifeLSN" field of the SQLB_TBSPQRY_DATA structure
is returned with an invalid LSN value. All other fields of the structure
remain valid. To correct this behavior, the application in use must
be updated to incorporate the latest version of the sqlbmtsq API.
For the other APIs, there are no restrictions on the functions of
the APIs regardless of the version of the API in use.
sqlurlog API (older level API)
The
behavior of the sqlurlog API changes depending
on the client-server configuration.
Here are the possible configurations:
sqlbftsq API, sqlbstsq API,
and sqlbtsq API (older level APIs)
The
behavior of the sqlbftsq API, sqlbstsq API,
and sqlbtsq API changes depending on the client-server
configuration.
Here are the possible configurations:
- Latest client and latest server: Using any of these three APIs
in this type of client-server configuration could result in the population
of the "lifeLSN" field of the older SQLB_TBSPQRY_DATA structure
with an invalid LSN value. This is a consequence of the "lifeLSN" field
of the SQLB_TBSPQRY_DATA structure being unable
to contain large LSN values. To avoid this problem, the successors
of the sqlbftsq API, sqlbstsq API,
and sqlbtsq API must be used, where the successors
are the sqlbftpq API, sqlbstpq API,
and sqlbmtsq API respectively.
- Older client and latest server: The API behavior described in
the previous configuration applies for this configuration as well.
- Latest client and older server: There are no limitations in the
functions of the APIs when using the sqlbftsq API, sqlbstsq API,
and sqlbtsq API under this client-server configuration.
DB2 Version 9.7 for Linux, UNIX, and Windows