Reference: Cartridge Services Using C, 6 of 6

Cartridge Services -- File I/O Interface

Table 13-30 OCI File I/O Interface Functions Quick Reference

Function/Page	Purpose
OCIFileInit()	Initializes the OCIFile package.
OCIFileTerm()	Terminates the OCIFile package.
OCIFileOpen()	Opens a file.
OCIFileClose()	Closes a previously opened file.
OCIFileRead()	Reads from a file into a buffer.
OCIFileWrite()	Writes buflen bytes into the file.
OCIFileSeek()	Changes the current position in a file.
OCIFileExists()	Tests to see if the file exists.
OCIFileGetLength()	Gets the length of a file.
OCIFileFlush()	Writes buffered data to a file.

OCIFileObject

The OCIFileObject data structure holds information about the way in which a file should be opened and the way in which it will be accessed once it has been opened. When this structure is initialized by OCIFileOpen(), it becomes an identifier through which operations can be performed on that file. It is a necessary parameter to every function that operates on open files. This data structure is opaque to OCIFile clients. It is initialized by OCIFileOpen() and terminated by OCIFileClose().

OCIFileInit()

Purpose

Initializes the OCIFile package. It must be called before any other OCIFile routine is called.

Syntax

sword OCIFileInit( dvoid    *hndl, 
                   OCIError *err);

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().

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-31 OCIFileInit Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`().

OCIFileTerm()

Purpose

Terminates the OCIFile package. It must be called after the OCIFile package is no longer being used.

Syntax

sword OCIFileTerm( dvoid    *hndl, 
                   OCIError *err);

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().

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-32 OCIFileTerm Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()

OCIFileOpen()

Purpose

Opens a file.

Syntax

sword OCIFileOpen( dvoid *hndl, 
                   OCIError       *err, 
                   OCIFileObject  **filep, 
                   OraText        *filename, 
                   OraText        *path, 
                   ub4            mode, 
                   ub4            create, 
                   ub4            type);

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().

filep (IN/OUT)

The file identifier.

filename (IN)

The file name as a null-terminated string.

path (IN)

The path of the file as a null-terminated string.

mode (IN)

The mode in which to open the file. Valid modes are

OCI_FILE_READ_ONLY,

OCI_FILE_WRITE_ONLY,

OCI_FILE_READ_WRITE.

create (IN)

Indicates if the file be created if it does not exist -- valid values are:

OCI_FILE_TRUNCATE -- create a file regardless of whether or not it exists. If the file already exists overwrite the existing file.

OCI_FILE_EXCL -- fail if the file exists, else create.

OCI_FILE_CREATE -- open the file if it exists, and create it if it does not.

OCI_FILE_APPEND -- set the file pointer to the end of the file prior to writing. This flag can be OR'ed with OCI_FILE_CREATE

type (IN)

File type. Valid values are

OCI_FILE_TEXT,

OCI_FILE_BIN,

OCI_FILE_STDIN,

OCI_FILE_STDOUT,

OCI_FILE_STDERR.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-33 OCIFileOpen Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	the file identifier
`filename (IN)`	the file name as a `NULL`-terminated string
`path (IN)`	the path of the file as a `NULL`-terminated string
`mode (IN)`	the mode in which to open the file. Valid modes are `OCI_FILE_READ_ONLY`, `OCI_FILE_WRITE_ONLY`, `OCI_FILE_READ_WRITE`
`create (IN)`	indicates if the file be created if it does not exist -- valid values are: `OCI_FILE_TRUNCATE` -- create a file regardless of whether or not it exists. If the file already exists overwrite the existing file `OCI_FILE_EXCL` -- fail if the file exists, else create. `OCI_FILE_CREATE` -- open the file if it exists, and create it if it doesn't `OCI_FILE_APPEND` -- set the file pointer to the end of the file prior to writing. This flag can be OR'ed with `OCI_FILE_CREATE`
`type (IN)`	file type; valid values are `OCI_FILE_TEXT`, `OCI_FILE_BIN`, `OCI_FILE_STDIN`, `OCI_FILE_STDOUT` and `OCI_FILE_STDERR`

OCIFileClose()

Purpose

Closes a previously opened file.

Syntax

sword OCIFileClose( dvoid         *hndl, 
                    OCIError      *err, 
                    OCIFileObject *filep);

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().

filep (IN/OUT)

A pointer to a file identifier to be closed.

Comments

Once this returns, the OCIFileObject structure pointed to by filep will have been destroyed. Therefore, you should not attempt to access this structure after this returns.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-34 OCIFileClose Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	a pointer to a file identifier to be closed

OCIFileRead()

Purpose

Reads from a file into a buffer.

Syntax

sword OCIFileRead( dvoid         *hndl, 
                   OCIError      *err, 
                   OCIFileObject *filep, 
                   dvoid         *bufp, 
                   ub4           bufl, 
                   ub4           *bytesread);

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().

filep (IN/OUT)

A file identifier that uniquely references the file.

bufp(IN)

The pointer to a buffer into which the data will be read. The length of the allocated memory is assumed to be bufl.

bufl (IN)

The length of the buffer in bytes.

bytesread (OUT)

The number of bytes read.

Comments

As many bytes as possible will be read into the user buffer. The read will end either when the user buffer is full, or when it reaches end-of-file.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-35 OCIFileRead Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	a file identifier that uniquely references the file
`bufp (IN)`	the pointer to a buffer into which the data will be read. The length of the allocated memory is assumed to be `bufl`
`bufl (IN)`	the length of the buffer in bytes
`bytesread (OUT)`	the number of bytes read

OCIFileWrite()

Purpose

Writes buflen bytes into the file.

Syntax

sword OCIFileWrite( dvoid         *hndl, 
                    OCIError      *err, 
                    OCIFileObject *filep, 
                    dvoid         *bufp, 
                    ub4           buflen, 
                    ub4           *byteswritten);

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().

filep (IN/OUT)

A file identifier that uniquely references the file.

bufp(IN)

The pointer to a buffer from into which the data will be written. The length of the allocated memory is assumed to be buflen.

buflen (IN)

The length of the buffer in bytes.

bytesread (OUT)

The number of bytes written.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-36 OCIFileWrite Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	a file identifier that uniquely references the file
bufp (IN)	the pointer to a buffer into which the data will be written; the length of the allocated memory is assumed to be `buflen`
buflen (IN)	the length of the buffer in bytes
byteswritten (OUT)	`t`he number of bytes written

OCIFileSeek()

Purpose

Changes the current position in a file.

Syntax

sword OCIFileSeek( dvoid         *hndl, 
                   OCIError      *err, 
                   OCIFileObject *filep, 
                   uword         origin, 
                   ubig_ora      offset, 
                   sb1           dir);

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().

filep (IN/OUT)

A file identifier that uniquely references the file.

origin(IN)

The starting point we want to seek from. The starting point may be

OCI_FILE_SEEK_BEGINNING (beginning),

OCI_FILE_SEEK_CURRENT (current position),

OCI_FILE_SEEK_END (end of file).

offset (IN)

The number of bytes from the origin you want to start reading from.

dir (IN)

The direction to go from the origin.

NOTE: The direction can be either OCIFILE_FORWARD or OCIFILE_BACKWARD.

Comments

This will allow a seek past the end of the file. Reading from such a position will cause an end-of-file condition to be reported. Writing to such a position will not work on all file systems. This is because some systems do not allow files to grow dynamically. They require that files be preallocated with a fixed size. Note that this function performs a seek to a byte location.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-37 OCIFileSeek Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	a file identifier that uniquely references the file
origin (IN)	the starting point we want to seek from. The starting point may be `OCI_FILE_SEEK_BEGINNING` (beginning), `OCI_FILE_SEEK_CURRENT` (current position), or `OCI_FILE_SEEK_END` (end of file)
offset (IN)	the number of bytes from the origin you want to start reading from
dir (IN)	the direction we want to go from the origin. NOTE: The direction can be either `OCIFILE_FORWARD` or `OCIFILE_BACKWARD`

OCIFileExists()

Purpose

Tests to see if the file exists.

Syntax

sword OCIFileExists( dvoid    *hndl, 
                     OCIError *err, 
                     OraText  *filename, 
                     OraText  *path, 
                     ub1      *flag);

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().

filename (IN)

The file name as a null-terminated string.

path (IN)

The path of the file as a null-terminated string.

flag (OUT)

Set to TRUE if the file exists or FALSE if it does not.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-38 OCIFileExists Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`().
`filename (IN)`	the file name as a `NULL`-terminated string
path (IN)	the path of the file as a `NULL`-terminated string
flag (OUT)	set to `TRUE` if the file exists or `FALSE` if it does not

OCIFileGetLength()

Purpose

Gets the length of a file.

Syntax

sword OCIFileGetLength( dvoid    *hndl, 
                        OCIError *err, 
                        OraText  *filename, 
                        OraText  *path, 
                        ubig_ora *lenp);

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().

filename (IN)

The file name as a null-terminated string.

path (IN)

The path of the file as a null-terminated string.

lenp (OUT)

Set to the length of the file in bytes.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-39 OCIFileGetLength Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filename (IN)`	the file name as a `NULL`-terminated string
path (IN)	the path of the file as a `NULL`-terminated string
lenp (OUT)	set to the length of the file in bytes

OCIFileFlush()

Purpose

Writes buffered data to a file.

Syntax

sword OCIFileFlush( dvoid         *h
                    OCIError      *err, 
                    OCIFileObject *filep);

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().

filep (IN/OUT)

A file identifier that uniquely references the file.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-40 OCIFileFlush Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()
`filep (IN/OUT)`	a file identifier that uniquely references the file

Cartridge Services -- File I/O Interface

OCIFileObject

The OCIFileObject data structure holds information about the way in which a file should be opened and the way in which it will be accessed once it has been opened. When this structure is initialized by OCIFileOpen(), it becomes an identifier through which operations can be performed on that file. It is a necessary parameter to every function that operates on open files. This data structure is opaque to OCIFile clients. It is initialized by OCIFileOpen() and terminated by OCIFileClose().

Cartridge Services -- String Formatting Interface

OCIFormatInit

Syntax

sword OCIFormatInit(dvoid *hndl, OCIError *err)

Remarks

Initializes the OCIFormat package. This routine must be called before calling any other OCIFormat routine and it must only be called once.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-41 OCIFormatInit Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`()

OCIFormatTerm

Syntax

sword OCIFormatTerm(dvoid *hndl, OCIError *err)

Remarks

Terminates the OCIFormat package. It must be called after the OCIFormat package is no longer being used and it must only be called once.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-42 OCIFormatTerm Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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`().

OCIFormatString

Syntax

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

Remarks

Writes a text string into the supplied text buffer using the argument list submitted to it and in accordance with the format string given. 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, or OCI_ERROR.

Table 13-43 OCIFormatString Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN/OUT)`	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 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 below.
... (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`

Format Modifiers

A format modifier alters or extends the format specification, allowing more specialized output. The format modifiers may be in any order and are all optional.

Flags (in any order)

Flag Operation

'-'

left-justify the output in the field

'+'

always print a sign ('+' or '-') for numeric types

' '

if a number's sign is not printed then print a space in the sign position

'0'

pad numeric output with zeros not spaces

Flag	Operation
`'-'`	left-justify the output in the field
`'+'`	always print a sign ('+' or '-') for numeric types
`' '`	if a number's sign is not printed then print a space in the sign position
`'0'`	pad numeric output with zeros not spaces

If both the '+' and ' ' flags are used in the same format specification then the ' ' flag is ignored.
If both the '-' and '0' flags are used in the same format specification then the '-' flag is ignored.

Alternate output:

For the octal format code add a leading zero.
For the hexadecimal format code add a leading '0x'.
For floating point format codes the output will always have a radix character.

Field Width

<w> where <w> is a number specifying a minimum field width. The converted argument will be printed in a field at least this wide, and wider if necessary. If the converted argument takes up fewer display positions than the field width, it will be padded on the left (or right for left justification) to make up the field width. The padding character is normally a space, but it is a zero if the zero padding flag was specified. The special character '*' may be used in place of <w> and indicates the current argument is to be used for the field width value, the actual field or precision follows as the next sequential argument.

Precision

.<p> specifies a period followed by the number <p>, specifying the maximum number of display positions to print from a string, or digits after the radix point for a decimal number, or the minimum number of digits to print for an integer type (leading zeroes will be added to make up the difference). The special character '*' may be used in place of <p> indicating the current argument contains the precision value.

Argument Index

(<n>) where <n> is an integer index into the argument list with the first argument being 1. If no argument index is specified in a format specification the first argument is selected. The next time no argument index is specified in a format specification the second argument is selected and so on. Format specifications with and without argument indexes can be in any order and are independent of each other in operation.

For example, the format string "%u %(4)u %u %(2)u %u" selects the first, fourth, second, second, and third arguments given to OCIFormatString.

Format Codes

A format code specifies how to format an argument that is being written to a string.

Note that these codes can appear in upper case, which will cause all alphabetic characters in the output to appear in upper case except for text strings, which are not converted.

Codes Operation

'c'

single-byte character in the compiler character set

'd'

signed decimal integer

'e'

exponential (scientific) notation of the form [-]<d><r>[<d>...]e+[<d>]<d><d> where <r> is the radix character for the current language and <d> is any single digit; the default precision is given by the constant OCIFormatDP. the precision may be optionally specified as a format modifier - using a precision of 0 suppresses the radix character; the exponent is always printed in at least 2 digits, and can take up to 3 e.g. 1e+01, 1e+10, and 1e+100

'f'

fixed decimal notation of the form [-]<d>[<d>...]<r>[<d>...] where <r> is the appropriate radix character for the current language and <d> is any single digit; the precision may be optionally specified as a format modifier- using a precision of 0 suppresses the radix character. the default precision is given by the constant OCIFormatDP

'g'

variable floating-point notation; chooses 'e' or 'f', selecting 'f'' if the number will fit in the specified precision (default precision if unspecified), and choosing 'e' only if exponential format will allow more significant digits to be printed; does not print a radix character if number has no fractional part

'i'

identical to 'd'

'o'

unsigned octal integer

'p'

platform specific pointer printout

's'

prints an argument using the default format code for its type:
ociformatub<n>, ociformatuword, ociformatubig_ora, ociformateb<n>, and ociformateword.
the format code used is 'u'.
ociformatsb<n>, ociformatsword, and ociformatsbig_ora.
the format code used is 'd'.
ociformatchar
the format code used is 'c'.
ociformattext
prints text until trailing null is found.
ociformatdouble
the format code used is 'g'.
ociformatdvoid
the format code used is 'p'.
' %' - print a '%'.

'u'

unsigned decimal integer

'x'

unsigned hexadecimal integer

Codes	Operation
`'c'`	single-byte character in the compiler character set
`'d'`	signed decimal integer
`'e'`	exponential (scientific) notation of the form [`-]<d><r>[<d>...]e+[<d>]<d><d>` where `<r>` is the radix character for the current language and `<d>` is any single digit; the default precision is given by the constant `OCIFormatDP`. the precision may be optionally specified as a format modifier - using a precision of 0 suppresses the radix character; the exponent is always printed in at least 2 digits, and can take up to 3 e.g. 1e+01, 1e+10, and 1e+100
`'f'`	fixed decimal notation of the form `[-]<d>[<d>...]<r>[<d>...]` where `<r>` is the appropriate radix character for the current language and `<d>` is any single digit; the precision may be optionally specified as a format modifier- using a precision of 0 suppresses the radix character. the default precision is given by the constant `OCIFormatDP`
`'g'`	variable floating-point notation; chooses `'e'` or `'f'`, selecting `'f'`' if the number will fit in the specified precision (default precision if unspecified), and choosing `'e'` only if exponential format will allow more significant digits to be printed; does not print a radix character if number has no fractional part
`'i'`	identical to `'d'`
`'o'`	unsigned octal integer
`'p'`	platform specific pointer printout
`'s'`	prints an argument using the default format code for its type: `ociformatub<n>`, `ociformatuword`, `ociformatubig_ora`, `ociformateb<n>`, and `ociformateword`. the format code used is 'u'. `ociformatsb<n>`, `ociformatsword`, and `ociformatsbig_ora`. the format code used is 'd'. `ociformatchar` the format code used is 'c'. `ociformattext` prints text until trailing null is found. `ociformatdouble` the format code used is 'g'. `ociformatdvoid` the format code used is 'p'. `' %' - print a '%'.`
`'u'`	unsigned decimal integer
'x'	unsigned hexadecimal integer

Example

/* This example shows the power of arbitrary argument    */
/* selection in the context of internationalization.  A  */
/* date is formatted in 2 different ways for 2 different */
/* countries according to the format string yet the      */
/* argument list submitted to OCIFormatString remains    */
/* invariant.                                            */

text      buffer[255];
ub1       day, month, year;
OCIError *err;
dvoid    *hndl;

/* Set the date. */

day   = 10;
month = 3;
year  = 97;

/* Work out the date in United States' style: mm/dd/yy *:/
OCIFormatString(hndl, err,
                buffer, (sbig_ora)sizeof(buffer),
                (CONST text *)"%(2)02u/%(1)02u/%(3)02u",
                OCIFormatUb1(day),
                OCIFormatUb1(month),
                OCIFormatUb1(year),
                OCIFormatEnd);    /* Buffer is "03/10/97". */

/* Work out the date in New Zealand style: dd/mm/yy *:/
OCIFormatString(hndl, err,
                buffer, (sbig_ora)sizeof(buffer),
                (CONST text *)"%(1)02u/%(2)02u/%(3)02u",
                OCIFormatUb1(day),
                OCIFormatUb1(month),
                OCIFormatUb1(year),
                OCIFormatEnd);    /* Buffer is "10/03/97". */