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 in the following sections. 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 in the following sections, 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 an existing application that uses 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.
Note: These APIs
have been deprecated and might be removed in a future release. You
can use the MON_GET_TABLESPACE and the MON_GET_CONTAINER table functions
instead which return more information.
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 previously,
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.
- 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.