OCILobWrite()

Purpose

Writes a buffer into a LOB

Syntax

sword OCILobWrite ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amtp,
                    ub4             offset,
                    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/OUT)

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 the LOB. This locator must be a locator that was obtained from the server specified by svchp.

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.

This should always be a non-null pointer. If you want to specify write-until-end-of-file, then you must declare a variable, set it equal to zero, and pass its address for this parameter.

If the amount is 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 that 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.

offset (IN)

On input, it is the absolute offset from the beginning of the LOB value. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs it is the number of bytes. The first position is 1.

If you use streaming (by polling or a callback), then, specify the offset in the first call and in subsequent polling calls the offset parameter is ignored. When using a callback there is no offset parameter.

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 using the polling method, 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. This value will differ from the amtp value for CLOBs and NCLOBs if the amtp parameter is specified in terms of characters, while the buflen parameter is specified in terms of bytes.

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 callback 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. This is the same as the bufp passed as an input to the OCILobWrite() routine.

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 data in the buffer. If this value is 0 then csid is set to the client's NLS_LANG or NLS_CHAR value, depending on the value of csfrm.

csfrm (IN)

The character set form of the buffer data. The csfrm parameter must be consistent with the type of the LOB.

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

Writes a buffer into an internal LOB as specified. If LOB data already exists it is overwritten with the data stored in the buffer. 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.

When using the polling mode for OCILobWrite(), the first call needs to specify values for offset and amtp, but on subsequent polling calls to OCILobWrite(), the user need not specify these values.

If the value of the piece parameter is OCI_FIRST_PIECE, data may need to 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 OCILobWrite() returns the OCI_NEED_DATA error code. The application must call OCILobWrite() 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, regardless of whether the polling or callback method is used.

If the amount of data passed to Oracle (through either input mechanism) is less than the amount specified by the amtp parameter, an ORA-22993 error is returned.

This function is valid for internal LOBs only. FILEs are not allowed, since they are read-only. 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 and the output amount is in characters for CLOBs and NCLOBs. 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.

To write data in UTF16 format, set the csid parameter to OCI_UTF16ID. If the csid parameter is set, it overrides the NLS_LANG environment variable.

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(), OCILobWriteAppend()