OCILobWriteAppend()

Purpose

Writes data starting at the end of a LOB.

Syntax

sword OCILobWriteAppend ( OCISvcCtx *svchp,
                          OCIError *errhp,
                          OCILobLocator *locp,
                          ub4 *amtp,
                          dvoid *bufp, 
                          ub4 buflen, 
                          ub1 piece, 
                          dvoid *ctxp, 
                          OCICallbackLobWrite   (cbfp)
                                         (/*_
                                           dvoid    *ctxp,
                                           dvoid    *bufp,
                                           ub4      *lenp,
                                           ub1      *piecep */) 
                          ub2 csid, 
                          ub1 csfrm);

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

locp (IN/OUT)

An internal LOB locator that uniquely references a LOB.

amtp (IN/OUT)

The value in amtp is the amount in either bytes or characters, as shown in this table:

LOB/FILE	Input with fixed-width client-side character set	Input with varying-width client-side character set	Output
BLOBs and BFILEs	bytes	bytes	bytes
CLOBs and NCLOBs	characters	bytes (1)	characters

(1) The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp, which is specified by buflen. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen. The output amount refers to the number of characters written into the server-side CLOB/NCLOB.

If the amount specified on input, and the data is written in pieces, *amtp will contain the total length of the pieces written at the end of the call (last piece written) and is undefined in between. (Note it is different from the piecewise read case). An error is returned if that amount is not sent to the server. If amtp is zero, then streaming mode is assumed, and data is written until the user specifies OCI_LAST_PIECE.

If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOBs/NCLOBs.

bufp (IN)

The pointer to a buffer from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen. Even if the data is being written in pieces, bufp must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp must not be used to provide data or an error will result.

buflen (IN)

The length, in bytes, of the data in the buffer. Note that this parameter assumes an 8-bit byte. If your platform uses a longer byte, the value of buflen must be adjusted accordingly.

piece (IN)

Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a single piece. The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.

ctxp (IN)

The context for the call back function. Can be null.

cbfp (IN)

A callback that may be registered to be called for each piece in a piecewise write. If this is null, the standard polling method will be used. The callback function must return OCI_CONTINUE for the write to continue. If any other error code is returned, the LOB write is aborted. The callback takes the following parameters:

ctxp (IN)

The context for the callback function. Can be null.

bufp (IN/OUT)

A buffer pointer for the piece.

lenp (IN/OUT)

The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp (OUT).

piecep (OUT)

Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.

csid (IN)

The character set ID of the buffer data.

csfrm (IN)

The character set form of the buffer data.

csfrm has two possible nonzero values:

• SQLCS_IMPLICIT - database character set ID
• SQLCS_NCHAR - NCHAR character set ID

The default value is SQLCS_IMPLICIT.

Comments

The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method. If the value of the piece parameter is OCI_FIRST_PIECE, data must be provided through callbacks or polling. If a callback function is defined in the cbfp parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp. If no callback function is defined, then OCILobWriteAppend() returns the OCI_NEED_DATA error code.

The application must call OCILobWriteAppend() again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations. A piece value of OCI_LAST_PIECE terminates the piecewise write.

OCILobWriteAppend() is not supported if LOB buffering is enabled.

If the LOB is a BLOB, the csid and csfrm parameters are ignored.

If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOBs/NCLOBs.

It is not mandatory that you wrap this LOB operation inside the Open/Close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.

If you do not wrap your LOB operations inside the Open/Close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open/close statements.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite()

Advanced Queuing and Publish-Subscribe Functions

This section describes the Advanced Queuing and publish-subscribe functions.

Table 16-3 Advanced Queuing and Publish-Subscribe Functions  

Function	Purpose
OCIAQDeq()	Advanced Queuing dequeue
OCIAQEnq()	Advanced Queuing enqueue
OCIAQListen()	Listens on one or more queues on behalf of a list of agents
OCISubscriptionEnable()	Enables notifications on a subscription
OCISubscriptionPost()	Posts to a subscription to receive notifications
OCISubscriptionRegister()	Registers a subscription
OCISubscriptionUnRegister()	Unregisters a subscription