Release 8.1.6
Part Number A76975-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Call Interface Programmer's Guide Release 8.1.6 Part Number A76975-01 |
|
The chapter contains the following sections:
This chapter first describes the OCI external procedure functions. These functions enable users of external procedures to raise errors, allocate some memory, and get OCI context information. For more information about using these functions, seeOracle8i Data Cartridge Developer's Guide the Oracle8i Application Developer's Guide - Fundamentals.
Then the cartridge services functions are described. For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
For each function, the following information is listed:
A brief description of the action performed by the function.
A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.
A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described below:
More detailed information about the function (if available). This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.
A list of possible return values for the function.
A list of related function calls. For cartridge services, see all the other functions in the group being documented.
Success and error return codes are defined for certain external procedure interface functions. If a particular interface function returns OCIEXTPROC_SUCCESS or OCIEXTPROC_ERROR, then applications must use these macros to check for return values.
The C callable interface to PL/SQL external procedures requires the with_context parameter to be passed. The type of this structure is OCIExtProcContext, which is opaque to the user.
The user can declare the with_context parameter in the application as
OCIExtProcContext *with_context;
The OCI external procedure functions for C:
Allocate N bytes of memory for the duration of the External Procedure.
dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext *with_context, size_t amount )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
The number of bytes to allocate.
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
An untyped (opaque) Pointer to the allocated memory.
text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)
OCIErrorGet(), OCIMemoryAlloc().
Raise an Exception to PL/SQL.
size_t OCIExtProcRaiseExcp ( OCIExtProcContext *with_context, int errnum )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
Oracle Error number to signal to PL/SQL. errnum must be a positive number and in the range 1 to 32767.
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.
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.
Raise an exception with a message.
size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context, int errnum, char *errmsg, size_t msglen )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
Oracle Error number to signal to PL/SQL. The value of errnum must be a positive number and in the range 1 to 32767
The error message associated with the errnum.
The length of the error message. Pass zero if errmsg is a null terminated string.
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.
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.
Gets the OCI environment, service context, and error handles.
sword OCIExtProcGetEnv ( OCIExtProcContext *with_context, OCIEnv envh, OCISvcCtx svch, OCIError errh )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
The OCI Environment handle.
The OCI Service handle.
The OCI Error handle.
The primary purpose of this function is to allow OCI callbacks to use the database in the same transaction. The OCI handles obtained by this function should be used in OCI callbacks to the database. If these handles are obtained through standard OCI calls, then these handles use a new connection to the database and cannot be used for callbacks in the same transaction. In one external procedure you can use either callbacks or a new connection, but not both.
This function returns OCI_SUCCESS if the call was successful; otherwise, it returns OCI_ERROR.
OCIEnvCreate(), OCIAttrGet(), OCIHandleAlloc()
| Function/Page | Purpose |
|---|---|
|
Starts a user duration. |
|
|
Terminates a user duration. |
|
|
Allocates memory of a given size from a given duration. |
|
|
Resizes a memory chunk. |
|
|
Frees a memory chunk. |
For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
Start a user duration
sword OCIDurationBegin ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIDuration parent, OCIDuration *duration );
The OCI environment handle.
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().
The OCI service context handle. This should be passed as NULL for cartridge services.
The duration number of the parent duration. One of these:
An identifier unique to the newly created user duration.
This function starts an user duration. A user can have multiple active user durations simultaneously. The user durations do not have to be nested. The duration parameter is used to return a number which uniquely identifies the duration created by this call.
Note that the environment and service context parameters cannot both be NULL.
Terminates a user duration
sword OCIDurationEnd ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIDuration duration, CONST OCISvcCtx *svc );
The OCI environment handle.
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().
A user duration previously created by OCIDurationBegin().
OCI service context (this should be passed as NULL for cartridge services, otherwise non-NULL)
This function terminates an user duration.
Note that the environment and service context parameters cannot both be NULL.
This call allocates memory of a given size from a given duration.
sword OCIMemoryAlloc( dvoid *hndl, OCIError *err, dvoid **mem, OCIDuration dur, ub4 size, ub4 flags);
The OCI environment handle.
The error handle.
Memory allocated.
One of the following (a previously created user duration):
OCI_DURATION_CALLOUT
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
OCI_DURATION_PROCESS
Size of memory to be allocated.
Set OCI_MEMORY_CLEARED bit to get memory that has been cleared.
To allocate memory for duration of callout of agent, i.e., external procedure duration, use OCIExtProcAllocCallMemory() or OCIMemoryAlloc() with dur as OCI_DURATION_CALLOUT.
Error code.
This call resizes a memory chunk to a new size.
sword OCIMemoryResize( dvoid *hndl, OCIError *err, dvoid **mem, ub4 newsize, ub4 flags);
The OCI environment or user session handle.
The error handle.
Pointer to memory allocated previously using OCIMemoryAlloc().
Size of memory requested.
Set OCI_MEMORY_CLEARED bit to get memory that has been cleared
Memory must have been allocated before this function can be called to resize.
Error code.
This call frees a memory chunk.
sword OCIMemoryFree( dvoid *hndl, OCIError *err, dvoid *mem);
The OCI environment or user session handle.
The error handle.
Pointer to memory allocated previously using OCIMemoryAlloc().
Error code.
For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
This call is used to save a value (or address) for a particular duration.
sword OCIContextSetValue( dvoid *hndl, OCIError *err, OCIDuration duration, ub1 *key, ub1 keylen, dvoid *ctx_value);
The OCI environment or user session handle.
The error handle.
One of the following (a previously created user duration):
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
Unique key value.
Length of the key. Maximum is 64 bits.
Pointer that will be saved in the context.
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.
This call is used to return the value that is stored in the context associated with the given key (by calling OCIContextSetValue()).
sword OCIContextGetValue( dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen, dvoid **ctx_value);
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
Pointer to the value stored in the context (NULL if no value was stored).
For ctx_value: a pointer to a preallocated pointer for the stored context to be returned is required.
This call is used to remove the value that is stored in the context associated with the given key (by calling OCIContextSetValue()).
sword OCIContextClearValue( dvoid *hndl, OCIError *err, ub1 *key, ub1 keylen);
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
An error is returned when a non-existent key is passed.
This call will return a unique, 4-byte value each time it is called.
sword OCIContextGenerateKey( dvoid *hndl, OCIError *err, ub4 *key);
The OCI environment or user session handle.
The error handle.
Unique key value.
Length of the key. Maximum is 64 bits.
This value is going to be unique on a per session basis.
For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
This function initializes the parameter manager.
sword OCIExtractInit( dvoid *hndl,OCIError *err)
The OCI environment or user session handle.
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()
This function 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.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
This function releases all dynamically allocated storage.
sword OCIExtractTerm( dvoid *hndl, OCIError *err);
The OCI environment or user session handle.
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().
This function 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
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
The memory currently used for parameter storage, key definition storage, and parameter value lists is freed and the structure is re-initialized.
sword OCIExtractReset( dvoid *hndl, OCIError *err);
The OCI environment or user session handle.
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().
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Informs the parameter manager of the number of keys that will be registered.
sword OCIExtractSetNumKeys( dvoid *hndl, CIError *err, uword numkeys);
The OCI environment or user session handle.
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().
The number of keys that will be registered with OCIExtractSetKey().
This routine must be called prior to the first call of OCIExtractSetKey().
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Registers information about a key with the parameter manager.
sword OCIExtractSetKey( dvoid *hndl, OCIError *err, CONST text *name, ub1 type, ub4 flag, CONST dvoid *defval, CONST sb4 *intrange, CONST text *CONST *strlist);
The OCI environment or user session handle.
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().
The name of the key.
The type of the key:
OCI_EXTRACT_TYPE_INTEGER,
OCI_EXTRACT_TYPE_OCINUM,
OCI_EXTRACT_TYPE_STRING,
OCI_EXTRACT_TYPE_BOOLEAN.
Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values or 0 otherwise.
Set to the default value for the key. It 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.
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.
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.
This routine must be called after calling OCIExtractNumKeys() and before calling OCIExtractFromFile() or OCIExtractFromString().
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
The keys and their values in the given file are processed.
sword OCIExtractFromFile( dvoid *hndl, OCIError *err, ub4 flag, text *filename);
The OCI environment or user session handle.
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().
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE,
OCI_EXTRACT_UNIQUE_ABBREVS,
OCI_EXTRACT_APPEND_VALUES.
A null-terminated filename string.
OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called to define all of the keys before calling this routine.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
The keys and their values in the given string are processed.
sword OCIExtractFromStr( dvoid *hndl, OCIError *err, ub4 flag, text *input);
The OCI environment or user session handle.
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().
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE,
OCI_EXTRACT_UNIQUE_ABBREVS,
or OCI_EXTRACT_APPEND_VALUES.
A null-terminated input string.
OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called to define all of the keys before calling this routine.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Gets the integer value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToInt( dvoid *hndl, OCIError *err, text *keyname, uword valno, sb4 *retval);
The OCI environment or user session handle.
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).
Which value to get for this key.
The actual integer value.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_NO_DATA,
OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Gets the boolean value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToBool( dvoid *hndl, OCIError *err, text *keyname, uword valno, ub1 *retval);
The OCI environment or user session handle.
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().
Key name.
Which value to get for this key.
The actual boolean value.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_NO_DATA,
OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Gets the string value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToStr( dvoid *hndl, OCIError *err, text *keyname, uword valno, text *retval, uword buflen);
The OCI environment or user session handle.
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().
Key name.
Which value to get for this key.
The actual null-terminated string value.
The length of the buffer for retval.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_NO_DATA,
OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Gets the OCINumber value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToOCINum( dvoid *hndl, OCIError *err, text *keyname, uword valno, OCINumber *retval);
The OCI environment or user session handle.
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().
Key name.
Which value to get for this key.
The actual OCINumber value.
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.
Generates a list of parameters from the parameter structures that are stored in memory. Must be called before OCIExtractValues() is called.
sword OCIExtractToList( dvoid *hndl, OCIError *err, uword *numkeys);
The OCI environment or user session handle.
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().
The number of distinct keys stored in memory.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Generates a list of values for the parameter denoted by index in the parameter list.
sword OCIExtractFromList( dvoid *hndl, OCIError *err, uword index, text **name, ub1 *type, uword *numvals, dvoid ***values);
The OCI environment or user session handle.
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().
Which parameter to retrieve from the parameter list.
The name of the key for the current parameter.
Type of the current parameter:
(OCI_EXTRACT_TYPE_STRING,
OCI_EXTRACT_TYPE_INTEGER,
OCI_EXTRACT_TYPE_OCINUM,
OCI_EXTRACT_TYPE_BOOLEAN).
Number of values for this parameter.
The values for this parameter.
OCIExtractToList() must be called prior to calling this routine to generate the parameter list from the parameter structures that are stored in memory.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
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().
Initializes the OCIFile package. It must be called before any other OCIFile routine is called.
sword OCIFileInit( dvoid *hndl, OCIError *err);
The OCI environment or user session handle.
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().
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Terminates the OCIFile package. It must be called after the OCIFile package is no longer being used.
sword OCIFileTerm( dvoid *hndl, OCIError *err);
The OCI environment or user session handle.
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().
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Opens a file.
sword OCIFileOpen( dvoid *hndl, OCIError *err, OCIFileObject **filep, OraText *filename, OraText *path, ub4 mode, ub4 create, ub4 type);
The OCI environment or user session handle.
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().
The file identifier.
The file name as a null-terminated string.
The path of the file as a null-terminated string.
The mode in which to open the file. Valid modes are
OCI_FILE_READ_ONLY,
OCI_FILE_WRITE_ONLY,
OCI_FILE_READ_WRITE.
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
File type. Valid values are
OCI_FILE_TEXT,
OCI_FILE_BIN,
OCI_FILE_STDIN,
OCI_FILE_STDOUT,
OCI_FILE_STDERR.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Closes a previously opened file.
sword OCIFileClose( dvoid *hndl, OCIError *err, OCIFileObject *filep);
The OCI environment or user session handle.
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().
A pointer to a file identifier to be closed.
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.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Reads from a file into a buffer.
sword OCIFileRead( dvoid *hndl, OCIError *err, OCIFileObject *filep, dvoid *bufp, ub4 bufl, ub4 *bytesread);
The OCI environment or user session handle.
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().
A file identifier that uniquely references the file.
The pointer to a buffer into which the data will be read. The length of the allocated memory is assumed to be bufl.
The length of the buffer in bytes.
The number of bytes read.
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.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Writes buflen bytes into the file.
sword OCIFileWrite( dvoid *hndl, OCIError *err, OCIFileObject *filep, dvoid *bufp, ub4 buflen, ub4 *byteswritten);
The OCI environment or user session handle.
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().
A file identifier that uniquely references the file.
The pointer to a buffer from into which the data will be written. The length of the allocated memory is assumed to be buflen.
The length of the buffer in bytes.
The number of bytes written.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Changes the current position in a file.
sword OCIFileSeek( dvoid *hndl, OCIError *err, OCIFileObject *filep, uword origin, ubig_ora offset, sb1 dir);
The OCI environment or user session handle.
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().
A file identifier that uniquely references the file.
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).
The number of bytes from the origin you want to start reading from.
The direction to go from the origin.
NOTE: The direction can be either OCIFILE_FORWARD or OCIFILE_BACKWARD.
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.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Tests to see if the file exists.
sword OCIFileExists( dvoid *hndl, OCIError *err, OraText *filename, OraText *path, ub1 *flag);
The OCI environment or user session handle.
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().
The file name as a null-terminated string.
The path of the file as a null-terminated string.
Set to TRUE if the file exists or FALSE if it does not.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Gets the length of a file.
sword OCIFileGetLength( dvoid *hndl, OCIError *err, OraText *filename, OraText *path, ubig_ora *lenp);
The OCI environment or user session handle.
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().
The file name as a null-terminated string.
The path of the file as a null-terminated string.
Set to the length of the file in bytes.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Writes buffered data to a file.
sword OCIFileFlush( dvoid *h OCIError *err, OCIFileObject *filep);
The OCI environment or user session handle.
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().
A file identifier that uniquely references the file.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
| Function/Page | Purpose |
|---|---|
|
Initializes the OCIFormat package. |
|
|
Terminates the OCIFormat package. |
|
|
Writes a text string into the supplied text buffer. |
For more information about using these functions, see Oracle8i Data Cartridge Developer's Guide.
Initializes the OCIFormat package.
sword OCIFormatInit( dvoid *hndl, OCIError *err)
The OCI environment or user session handle.
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().
This routine must be called before calling any other OCIFormat routine and it must only be called once.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Terminates the OCIFormat package.
sword OCIFormatTerm( dvoid *hndl, OCIError *err)
The OCI environment or user session handle.
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().
This function must be called after the OCIFormat package is no longer being used and it must only be called once.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Writes a text string into the supplied text buffer using the argument list submitted to it and in accordance with the format string given.
sword OCIFormatString( dvoid *hndl, OCIError *err, text *buffer, sbig_ora bufferLength, sbig_ora *returnLength, CONST text *formatString,...);
The OCI environment or user session handle.
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().
The buffer that contains the string.
The length of the buffer in bytes.
The number of bytes written to the buffer (excluding the terminating null).
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.
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
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.
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
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.
'+' and ' ' flags are used in the same format specification then the ' ' flag is ignored.
'-' and '0' flags are used in the same format specification then the '-' flag is ignored.
<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.
.<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.
(<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().
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.
/* 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". */
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|