13
Reference -- Cartridge Services

This reference chapter includes the following information:

Cartridge Services -- External Procedures

OCIExtProcAllocCallMemory

Syntax

dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext  *with_context,
                                    size_t amount )

Remarks

This call allocates amount bytes of memory for the duration of the call of the external procedure.

Any memory allocated by this call is freed by PL/SQL upon return from the external procedure. The application must not use any kind of 'free' function on memory allocated by OCIExtProcAllocCallMemory(). Use this function to allocate memory for function returns.

A zero return value should be treated as an error

Returns

An untyped (opaque) Pointer to the allocated memory.

Table 13-1 OCIExtProcAllocCallMemory Keywords/Parameters

Keyword/Parameter	Meaning
`with_context (IN)`	the with_context pointer that is passed to the C External Procedure
`amount (IN)`	the number of bytes to allocate

Example

text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)

OCIExtProcRaiseExcp

Syntax

size_t OCIExtProcRaiseExcp ( OCIExtProcContext *with_context, int errnum )

Remarks

Calling this function signals an exception back to PL/SQL. After a successful return from this function, the external procedure must start its exit handling and return back to PL/SQL. Once an exception is signalled to PL/SQL, IN/OUT and OUT arguments, if any, are not processed at all.

Returns

OCIEXTPROC_SUCCESS - If the call was successful.

OCIEXTPROC_ERROR - If the call failed.

Table 13-2 OCIExtProcAllocCallMemory Keywords/Parameters

Keyword/Parameter Meaning

Keyword/Parameter	Meaning
`with_context (IN)`	the `with_context` pointer that is passed to the C external procedure
`errnum (IN)`	Oracle Error number to signal to PL/SQL `errnum` must be a positive number and in the range 1 to 32767

with_context (IN)

the with_context pointer that is passed to the C external procedure

errnum (IN)

Oracle Error number to signal to PL/SQL errnum must be a positive number and in the range 1 to 32767

OCIExtProcRaiseExcpWithMsg

Syntax

size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context,
                                    int errnum, char  *errmsg, size_t msglen )

Remarks

Raise an exception to PL/SQL. In addition, substitute the following error message string within the standard Oracle error message string. See the description of OCIExtProcRaiseExcp() for more information.

Returns

OCIEXTPROC_SUCCESS if the call was successful.

OCIEXTPROC_ERROR if the call failed.

Table 13-3 OCIExtProcAllocCallMemory Keywords/Parameters

Keyword/Parameter	Meaning
`with_context (IN)`	the with_context pointer that is passed to the C external procedure
`errnum (IN)`	Oracle Error number to signal to PL/SQL; `errnum` must be a positive number and in the range 1 to 32767
`errmsg (IN)`	the error message associated with the errnum
l`en (IN)`	the length of the error message; pass zero if `errmsg` is a null terminated string

Cartridge Services -- Memory Services

OCIDurationBegin

Syntax

sword OCIDurationBegin(OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, 
OCIDuration parent, OCIDuration *dur);

Remarks

This call starts a user duration. Note that the environment or service context parameter cannot both be NULL.

Returns

An error code.

Table 13-4 OCIDurationBegin Keywords/Parameters

Keyword/Parameter	Meaning
`env (IN)`	the OCI environment handle
`err (IN)`	the error handle
`errhps (IN)`	the OCI error handle stack
`OCISvcCtx (IN)`	the OCI Service Context (this should be passed as `NULL` for cartridge services)
`parent (IN)`	one of the following: a previously created user duration `OCI_DURATION_STATEMENT` `OCI_DURATION_SESSION`
`dur (OUT)`	newly created user duration

OCIDurationEnd

Syntax

sword OCIDurationEnd(OCIEnv *env, OCIError *err, OCIDuration dur, CONST 
                     OCISvcCtx *svc);

Remarks

This call terminates a user duration. All memory allocated for this duration is freed. Note that the environment or service context parameter cannot both be NULL.

Returns

Error code.

Table 13-5 OCIDurationEnd Keywords/Parameters

Keyword/Parameter	Meaning
`env (IN)`	the OCI environment handle
`err (IN)`	the error handle
`dur (IN)`	a previously created user duration using `OCIDurationBegin`()
`OCISvcCtx (IN)`	`OCI` Service Context (this should be passed as `NULL` for cartridge services)

OCIMemoryAlloc

Syntax

sword OCIMemoryAlloc(dvoid *hndl, OCIError *err, dvoid **mem, OCIDuration dur, 
                    ub4 size, ub4 flags);

Remarks

This call allocates memory of a given size from a given duration. To allocate memory for duration of callout of agent, i.e., external procedure duration, use OCIExtProcAllocCallMemory. If the hndl is an OCI environment, the only duration supported is OCI_DURATION_PROCESS. If the hndl is an OCI user session, the duration cannot be OCI_DURATION_PROCESS.

Returns

Error code.

Table 13-6 OCIMemoryAlloc Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment handle
`err (IN)`	the error handle
`mem (OUT)`	memory allocated
`dur (IN)`	one of the following: a previously created user duration `OCI_DURATION_STATEMENT` `OCI_DURATION_SESSION` `OCI_DURATION_PROCESS`
`size (IN)`	size of memory to be allocated
`flags (IN)`	set `OCI_MEMORY_CLEARED` bit to get memory that has been cleared

OCIMemoryResize

Syntax

sword OCIMemoryResize(dvoid *hndl, OCIError *err, dvoid **mem, ub4 newsize, ub4 
                     flags);

Remarks

This call resizes a memory chunk to a new size. Memory must have been allocated before this function can be called to resize.

Returns

Error code.

Table 13-7 OCIMemoryResize Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment or user session handle
`err (IN)`	the error handle
`mem (IN/OUT)`	pointer to memory pointer allocated previously using `OCIMemoryAlloc`()
`newsize (IN)`	size of memory requested
`flags (IN)`	set `OCI_MEMORY_CLEARED` bit to get memory that has been cleared

OCIMemoryFree

Syntax

sword OCIMemoryFree(dvoid *hndl, OCIError *err, dvoid *mem);

Remarks

This call frees a memory chunk.

Returns

Error code.

Table 13-8 OCIMemoryFree Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment or user session handle
`err (IN)`	the error handle
`mem (IN/OUT)`	pointer to a previously allocated memory

Cartridge Services -- Maintaining Context

OCIContextSetValue

Syntax

sword OCIContextSetValue(dvoid *hndl, OCIError *err, OCIDuration duration, 
                         ub1 *key, ub1 keylen, dvoid *ctx_value);

Remarks

This call can be used to save a value (or address) for a particular duration. The context value being stored must be allocated out of memory of duration greater than or equal to the duration being passed in. The key being passed in should be unique in this session. Trying to save a context value under the same key and duration again will result in overwriting the old context value with the new one. Typically, a client will allocate a structure, store its address in the context using this call, and get this address in a separate call using OCIContextGetValue(). The (key, value) association can be explicitly removed by calling OCIContextClearValue() or else it will go away at the end of the duration.

Returns

If operation succeeds, return OCI_SUCCESS.

If operation fails, return OCI_ERROR.

Table 13-9 OCIContextSetValue Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the OCI environment or user session handle
`err (IN)`	the error handle
`duration (IN)`	any user created duration `OCI_DURATION_STATEMENT` `OCI_DURATION_SESSION`
`key (IN))`	unique key value
`keylen (IN)`	length of the above key (maximum length is 64 bits)
`ctx_value (IN)`	pointer that will be saved in the context

OCIContextGetValue

Syntax

sword OCIContextGetValue(dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen, 
                         dvoid **ctx_value);

Remarks

This call is used to return the value that is stored in the context associated with the given key (by calling OCIContextSetValue()).

Requires

ctx_value -- pointer to a preallocated pointer for the stored context to be returned

Returns

If operation succeeds, return OCI_SUCCESS.

If operation fails, return OCI_ERROR.

Table 13-10 OCIContextSetValue Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment or user session handle
`err (IN)`	the error handle
`key (IN))`	key value previously registered via `OCIContextSetValue`()
`keylen (IN)`	length of the above key (maximum length is 64 bits)
`ctx_value (IN)`	pointer to the value stored in the context or `NULL` if no value was stored

OCIContextClearValue

Syntax

sword OCIContextClearValue(dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen);

Remarks

This call is used to remove the value that is stored in the context associated with the given key (by calling OCIContextSetValue()). An error is returned when a non-existent key is passed.

Returns

If operation succeeds, return OCI_SUCCESS.

If operation fails, return OCI_ERROR.

Table 13-11 OCIContextClearValue Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment or user session handle
`err (IN)`	the error handle
`key (IN))`	unique key value
`keylen (IN)`	length of the above key (maximum length is 64 bits)

OCIContextGenerateKey

Syntax

sword OCIContextGenerateKey(dvoid *hndl, OCIError *err, ub4 *key);

Remarks

This call will return a unique, 4 byte value each time it is called. This value is going to be unique on a per session basis.

Returns

If operation succeeds, return OCI_SUCCESS.

If operation fails, return OCI_ERROR.

Table 13-12 OCIContextGenerateKey Keywords/Parameters

Keyword/Parameter	Meaning
`hndl (IN)`	the `OCI` environment or user session handle
`err (IN)`	the error handle
`key (OUT))`	pointer to a unique, 4 byte value

Cartridge Services -- Parameter Manager Interface

OCIExtractInit

Syntax

sword OCIExtractInit(dvoid *hndl, OCIError *err)

Remarks

This function initializes the parameter manager. It must be called before calling any other parameter manager routine and it must only be called once. The NLS information is stored inside the parameter manager context and used in subsequent calls to OCIExtract routines.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-13 OCIExtractInit 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`()

OCIExtractTerm

Syntax

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

Remarks

This function releases all dynamically allocated storage and may perform other internal bookkeeping functions. It must be called when the parameter manager is no longer being used and it must only be called once.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-14 OCIExtractTerm 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`().

OCIExtractReset

Syntax

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

Remarks

The memory currently used for parameter storage, key definition storage, and parameter value lists is freed and the structure is reinitialized.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-15 OCIExtractReset 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`()

OCIExtractSetNumKeys

Syntax

sword OCIExtractSetNumKeys(dvoid *hndl, OCIError *err, uword numkeys);

Remarks

Informs the parameter manager of the number of keys that will be registered. This routine must be called prior to the first call of OCIExtractSetKey().

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-16 OCIExtractSetNumKeys 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`().
`numkeys (IN)`	the number of keys that will be registered with `OCIExtractSetKey`()

OCIExtractSetKey

Syntax

sword OCIExtractSetKey(dvoid *hndl, OCIError *err, CONST text *name, ub1 type, 
                      ub4 flag, CONST dvoid *defval, CONST sb4 *intrange, 
                      CONST text *CONST *strlist);

Remarks

Registers information about a key with the parameter manager. This routine must be called after calling OCIExtractNumKeys() and before calling OCIExtractFromFile() or OCIExtractFromString().

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-17 OCIExtractSetKey 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`()
`name (IN)`	the name of the key
type (IN)	the type of the key (`OCI_EXTRACT_TYPE_INTEGER, OCI_EXTRACT_TYPE_OCINUM, OCI_EXTRACT_TYPE_STRING, or OCI_EXTRACT_TYPE_BOOLEAN`)
flag (IN)	set to `OCI_EXTRACT_MULTIPLE` if the key can take multiple values or 0 otherwise
defval (IN)	set to the default value for the key; may be `NULL` if there is no default; a string default must be a (`text`) type, an integer default must be an (`sb4`) type, and a boolean default must be a (`ub1*`) type.
intrange (IN)	starting and ending values for the allowable range of integer values; may be `NULL` if the key is not an integer type or if all integer values are acceptable
strlist (IN)	list of all acceptable text strings for the key ended with 0 (or `NULL`); may be `NULL` if the key is not a string type or if all text values are acceptable

OCIExtractFromFile

Syntax

sword OCIExtractFromFile(dvoid *hndl, OCIError *err, ub4 flag, text *filename);

Remarks

The keys and their values in the given file are processed. OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called to define all of the keys before calling this routine.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-18 OCIExtractFromFile 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`()
flag (IN)	zero or has one or more of the following bits set: `OCI_EXTRACT_CASE_SENSITIVE`, `OCI_EXTRACT_UNIQUE_ABBREVS`, or `OCI_EXTRACT_APPEND_VALUES`
filename (IN)	`NULL`-terminated filename string

OCIExtractFromStr

Syntax

sword OCIExtractFromStr(dvoid *hndl, OCIError *err, ub4 flag, text *input);

Remarks

The keys and their values in the given string are processed. OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called to define all of the keys before calling this routine.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-19 OCIExtractFromStr 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`().
flag (IN)	zero or has one or more of the following bits set: `OCI_EXTRACT_CASE_SENSITIVE`, `OCI_EXTRACT_UNIQUE_ABBREVS`, or `OCI_EXTRACT_APPEND_VALUES`
input (IN)	`NULL`-terminated input string

OCIExtractToInt

Syntax

sword OCIExtractToInt(dvoid *hndl, OCIError *err, text *keyname, uword valno, 
sb4 *retval);

Remarks

Gets the integer value for the specified key. The valno'th value (starting with 0) is returned.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR. OCI_NO_DATA means that there is no valno'th value for this key.

Table 13-20 OCIExtractToInt Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
`keyname (IN)`	key name
`valno (IN)`	which value to get for this key
`retval (OUT)`	the actual integer value

OCIExtractToBool

Syntax

sword OCIExtractToBool(dvoid *hndl, OCIError *err, text *keyname, uword valno, 
                      ub1 *retval);

Remarks

Gets the boolean value for the specified key. The valno'th value (starting with 0) is returned.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR. OCI_NO_DATA means that there is no valno'th value for this key.

Table 13-21 OCIExtractToBool Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
`keyname (IN)`	key name
`valno (IN)`	which value to get for this key
`retval (OUT)`	the actual boolean value

OCIExtractToStr

Syntax

sword OCIExtractToStr(dvoid *hndl, OCIError *err, text *keyname, uword valno, 
                     text *retval, uword buflen);

Remarks

Gets the string value for the specified key. The valno'th value (starting with 0) is returned.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR. OCI_NO_DATA means that there is no valno'th value for this key.

Table 13-22 OCIExtractToStr Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
`keyname (IN)`	key name
`valno (IN)`	which value to get for this key
`retval (OUT)`	the actual `NULL`-terminated string value
`bufflen (IN)`	the length of the buffer for retval

OCIExtractToOCINum

Syntax

sword OCIExtractToOCINum(dvoid *hndl, OCIError *err, text *keyname, uword valno, 
                       OCINumber *retval);

Remarks

Gets the OCINumber value for the specified key. The valno'th value (starting with 0) is returned.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR. OCI_NO_DATA means that there is no valno'th value for this key.

Table 13-23 OCIExtractToOCINum Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
`keyname (IN)`	key name
`valno (IN)`	which value to get for this key
`retval (OUT)`	the actual `OCINumber` string value

OCIExtractToList

Syntax

sword OCIExtractToList(dvoid *hndl, OCIError *err, uword *numkeys);

Remarks

Generates a list of parameters from the parameter structures that are stored in memory. Must be called before OCIExtractValues() is called.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-24 OCIExtractToList Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
numkeys (OUT)	number of distinct keys stored in memory

OCIExtractFromList

Syntax

sword OCIExtractFromList(dvoid *hndl, OCIError *err, uword index, text **name, 
                        ub1 *type, uword *numvals, dvoid ***values);

Remarks

Generates a list of values for the parameter denoted by index in the parameter list. OCIExtractToList() must be called prior to calling this routine to generate the parameter list from the parameter structures that are stored in memory.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-25 OCIExtractFromList Keywords/Parameters

Keyword/Parameter	Meaning
`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`()
`index (IN)`	which parameter to retrieve from the parameter list
`name (OUT)`	name of the key for the current parameter
`type (OUT)`	type of the current parameter (`OCI_EXTRACT_TYPE_STRING`, `OCI_EXTRACT_TYPE_INTEGER`, `OCI_EXTRACT_TYPE_OCINUM`, or `OCI_EXTRACT_TYPE_BOOLEAN`)
`numvals (OUT)`	number of values for this parameter
`values (OUT)`	the values for this parameter

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

OCIFileInit

Syntax

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

Remarks

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

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-26 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

Syntax

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

Remarks

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

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-27 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

Syntax

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

Remarks

Opens a file.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-28 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

Syntax

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

Remarks

Closes a previously opened file. 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, or OCI_ERROR.

Table 13-29 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

Syntax

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

Remarks

Reads from a file into a buffer. 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, or OCI_ERROR.

Table 13-30 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

Syntax

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

Remarks

Writes buflen bytes into the file.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-31 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

Syntax

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

Remarks

Changes the current position in a file. 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, or OCI_ERROR.

Table 13-32 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

Syntax

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

Remarks

Tests to see if the file exists.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-33 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

Syntax

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

Remarks

Gets the length of a file.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-34 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

Syntax

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

Remarks

Write buffered data to a file.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

Table 13-35 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 -- 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-36 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-37 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-38 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

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

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". */

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

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

13 Reference -- Cartridge Services

Cartridge Services -- External Procedures

OCIExtProcAllocCallMemory

Syntax

Remarks

Returns

Table 13-1 OCIExtProcAllocCallMemory Keywords/Parameters

Example

OCIExtProcRaiseExcp

Syntax

Remarks

Returns

Table 13-2 OCIExtProcAllocCallMemory Keywords/Parameters

OCIExtProcRaiseExcpWithMsg

Syntax

Remarks

Returns

Table 13-3 OCIExtProcAllocCallMemory Keywords/Parameters

Cartridge Services -- Memory Services

OCIDurationBegin

Syntax

Remarks

Returns

Table 13-4 OCIDurationBegin Keywords/Parameters

OCIDurationEnd

Syntax

Remarks

Returns

Table 13-5 OCIDurationEnd Keywords/Parameters

OCIMemoryAlloc

Syntax

Remarks

Returns

Table 13-6 OCIMemoryAlloc Keywords/Parameters

OCIMemoryResize

Syntax

Remarks

Returns

Table 13-7 OCIMemoryResize Keywords/Parameters

OCIMemoryFree

Syntax

Remarks

Returns

Table 13-8 OCIMemoryFree Keywords/Parameters

Cartridge Services -- Maintaining Context

OCIContextSetValue

Syntax

Remarks

Returns

Table 13-9 OCIContextSetValue Keywords/Parameters

OCIContextGetValue

Syntax

Remarks

Requires

Returns

Table 13-10 OCIContextSetValue Keywords/Parameters

OCIContextClearValue

Syntax

Remarks

Returns

Table 13-11 OCIContextClearValue Keywords/Parameters

OCIContextGenerateKey

Syntax

Remarks

Returns

Table 13-12 OCIContextGenerateKey Keywords/Parameters

Cartridge Services -- Parameter Manager Interface

OCIExtractInit

Syntax

Remarks

Returns

Table 13-13 OCIExtractInit Keywords/Parameters

OCIExtractTerm

Syntax

Remarks

Returns

Table 13-14 OCIExtractTerm Keywords/Parameters

OCIExtractReset

Syntax

Remarks

13
Reference -- Cartridge Services