OCIFormatString()

Purpose

Writes a text string into the supplied text buffer using the argument list submitted to it and in accordance with the format string given.

Syntax

sword OCIFormatString( dvoid        *hndl, 
                       OCIError     *err, 
                       text         *buffer, 
                       sbig_ora     bufferLength, 
                       sbig_ora     *returnLength, 
                       CONST text   *formatString,... );

Parameters

hndl (IN)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle; if there is an error, it is recorded in err and this function returns OCI_ERROR; diagnostic information can be obtained by calling OCIErrorGet().

buffer (OUT)

The buffer that contains the string.

bufferLength (IN)

The length of the buffer in bytes.

returnLength (OUT)

The number of bytes written to the buffer (excluding the terminating null).

formatString (IN)

The format string which can be any combination of literal text and format specifications. A format specification is delimited by the '%' character and is followed by any number (including none) of optional format modifiers and terminated by a mandatory format code. If the format string ends with '%', i.e. with no format modifiers or format specifier following it, then no action is taken. The format modifiers and format codes available are described in the tables that follow.

...(IN)

Variable number of arguments of the form <OCIFormat type wrapper>(<variable>) where <variable> must be a variable containing the value to be used. No constant values or expressions are allowed as arguments to the OCIFormat type wrappers; The OCIFormat type wrappers that are available are listed below. The argument list must be terminated with OCIFormatEnd.

OCIFormatUb1(ub1 variable);

OCIFormatUb2(ub2 variable);

OCIFormatUb4(ub4 variable);

OCIFormatUword(uword variable);

OCIFormatUbig_ora(ubig_ora variable);

OCIFormatSb1(sb1 variable);

OCIFormatSb2(sb2 variable);

OCIFormatSb4(sb4 variable);

OCIFormatSword(sword variable);

OCIFormatSbig_ora(sbig_ora variable);

OCIFormatEb1(eb1 variable);

OCIFormatEb2(eb2 variable);

OCIFormatEb4(eb4 variable);

OCIFormatEword(eword variable);

OCIFormatChar (text variable);

OCIFormatText(CONST text *variable);

OCIFormatDouble(double variable);

OCIFormatDvoid(CONST dvoid *variable);

OCIFormatEnd

Comments

The first call to this routine must be preceded by a call to the OCIFormatInit routine that initializes the OCIFormat package for use. When this routine is no longer needed terminate the OCIFormat package by a call to the OCIFormatTerm routine.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.