Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Error handling

Sequencing long messages

Sequencing long messages

Message callback routines and ct_diag return Client-Library and server messages in CS_CLIENTMSG and CS_SERVERMSG structures. In the CS_CLIENTMSG structure, the message text is stored in the msgstring field. In the CS_SERVERMSG structure, the message text is stored in the text field. Both msgstring and text are CS_MAX_MSG bytes long.

If a message longer than CS_MAX_MSG, minus one bytes is generated, Client-Library's default behavior is to truncate the message. However, an application can use the CS_NO_TRUNCATE property to tell Client-Library to sequence long messages instead of truncating them.

When Client-Library is sequencing long messages, it uses as many CS_CLIENTMSG or CS_SERVERMSG structures as necessary to return the full text of a message. The message's first CS_MAX_MSG bytes are returned in one structure, its second CS_MAX_MSG bytes are returned in a second structure, and so forth.

Client-Library null-terminates only the last chunk of a message. If a message is exactly CS_MAX_MSG bytes long, the message is returned in two chunks: The first contains CS_MAX_MSG bytes of the message, and the second contains a null terminator.

If an application is using callback routines to handle messages, Client-Library calls the callback routine once for each message chunk.

If an application is using ct_diag to handle messages, it must call ct_diag once for each message chunk.

The SQLCA, SQLCODE, and SQLSTATE structures do not support sequenced messages. An application cannot use these structures to retrieve sequenced messages. Messages that are too long for these structures are truncated.

Operating system messages are reported via the osstring field of the CS_CLIENTMSG structure. Client-Library does not sequence operating system messages.

• The status field in the CS_CLIENTMSG and CS_SERVERMSG structures indicates whether the structure contains a whole message or a chunk of a message.

  The following status values are related to sequenced messages:

  Symbolic value	Meaning
  CS_FIRST_CHUNK	The message text is the first chunk of the message.
  CS_LAST_CHUNK	The message text is the last chunk of the message.

  • If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then the message text in the structure is the entire message.

  • If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then the message text in the structure is a middle chunk.

• The msgstringlen field in the CS_CLIENTMSG structure and the textlen field in the CS_SERVERMSG structure reflect the length of the current message chunk.

• All other fields in the CS_CLIENTMSG and CS_SERVERMSG are repeated with each message chunk.

If a sequenced server message has extended error data associated with it, an application can retrieve the extended error data while processing any single chunk of the sequenced message. Once the application has retrieved the extended error data, however, it is no longer available. For more information about extended error data, see "Extended error data".

If an application is using sequenced error messages, ct_diag acts on message chunks instead of messages. This has the following effects:

• A ct_diag(CS_GET, index) call returns the message chunk that has number index.

• A ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library will store.

• A ct_diag(CS_STATUS) call returns the number of currently stored chunks, not the number of currently stored messages.