Formatted functions

## Detailed Description

OCILIB offers some smart routines that takes a variable number of arguments in order to minimize OCILIB function calls and reduce the amount of code lines

On Windows platforms, the target programming language must support the __cdecl calling convention

Note
  OCI_Immediate() and OCI_ImmediateFmt() support all OCILIB supported types for output result, except :
  - OCI_Long
  - OCI_Statement If a query output result contains one of these unsupported types, the function returns FALSE
  In the parameter list, every output placeholder MUST be preceded by an integer parameter that indicates the type of the placeholder in order to handle correctly the given pointer.

Possible values for indicating placeholders type :

- OCI_ARG_SHORT ---—> short *
- OCI_ARG_USHORT --—> unsigned short *
- OCI_ARG_INT -----—> int *
- OCI_ARG_UINT ----—> unsigned int*
- OCI_ARG_BIGINT --—> big_int *
- OCI_ARG_BIGUINT -—> unsigned big_int *
- OCI_ARG_DOUBLE -—> double *
- OCI_ARG_FLOAT ---—> float *
- OCI_ARG_NUMBER --—> OCI_Number *
- OCI_ARG_TEXT ----—> otext *
- OCI_ARG_RAW -----—> void *
- OCI_ARG_DATETIME —> OCI_Date *
- OCI_ARG_LOB -----—> OCI_Lob *
- OCI_ARG_FILE ----—> OCI_File *
- OCI_ARG_TIMESTAMP –> OCI_Timestamp *
- OCI_ARG_INTERVAL —> OCI_Interval *
- OCI_ARG_OBJECT --—> OCI_Object *
- OCI_ARG_COLLECTION -> OCI_Coll *
- OCI_ARG_REF -----—> OCI_Ref *

Note
  For output strings and Raws, returned data is copied to the given buffer instead of returning a pointer the real data. So these buffers must be big enough to hold the column content. No size check is performed.

- For strings, only the real string is copied.
- For Raws, the number of bytes copied is the column size

Warning
  Input parameters for formatted function only support a restricted set of data types !

Supported input identifiers :

- 's' : (otext *) -------—> input string (quotes are added)
- 'm' : (otext *) -------—> meta data string (no quotes added)
- 't' : (OCI_Date *) ----—> Date
- 'p' : (OCI_Timestamp *) –> timestamp
- 'v' : (OCI_Interval *) —> Interval
- 'i' : (int) -----------—> signed 32 bits integer
- 'u' : (unsigned int) --—> unsigned 32 bits integer
- 'li' : (big_int) -------—> signed 64 bits integer
- 'lu' : (big_uint) ------—> unsigned 64 bits integer
- 'hi' : (short) ---------—> signed 16 bits integer
- 'hu' : (unsigned short) —> unsigned 16 bits integer
- 'g' : (double, float ) —> Numerics
- 'n' : (OCI_Number *) --—> Number
- 'r' : (OCI_Ref *) -----—> Reference
- 'o' : (OCI_Object *) --—> Object (not implemented yet)
- 'c' : (OCI_Coll *) ----—> collection (not implemented yet)

Example
  #include "ocilib.h"
  /* requires script demo/products.sql */
  void err_handler(OCI_Error *err)
  {
  printf("%s\n", OCI_ErrorGetString(err));
  }
  int main(void)
  {
  OCI_Connection *cn;
  OCI_Statement *st;
  OCI_Resultset *rs;
  int code;
  char name[50];
  if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
  {
  return EXIT_FAILURE;
  }
  cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
  st = OCI_StatementCreate(cn);
  /* sql format with params ----------------------------------------------- */
  code = 1;
  OCI_ExecuteStmtFmt(st, "select name from products where code = %i", code);
  rs = OCI_GetResultset(st);
  while (OCI_FetchNext(rs))
  {
  printf("article : %s\n", OCI_GetString(rs, 1));
  }
  /* sql immediate (parse, exec, one fetch) ------------------------------- */
  OCI_Immediate(cn, "select name from products where code = 2", OCI_ARG_TEXT, name);
  printf("article : %s\n", name);
  /* sql immediate (parse, exec, one fetch) with params ------------------- */
  code = 1;
  OCI_ImmediateFmt(cn, "select name from products where code = %i", code, OCI_ARG_TEXT, name);
  printf("article : %s\n", name);
  OCI_StatementFree(st);
  OCI_ConnectionFree(cn);
  OCI_Cleanup();
  return EXIT_SUCCESS;
  }

## Functions

OCI_EXPORT boolean | OCI_Immediate (OCI_Connection *con, const otext *sql,...)
| Perform 3 calls (prepare+execute+fetch) in 1 call. More...
OCI_EXPORT boolean | OCI_ImmediateFmt (OCI_Connection *con, const otext *sql,...)
| Performs 4 call (prepare+bind+execute+fetch) in 1 call. More...
OCI_EXPORT boolean | OCI_PrepareFmt (OCI_Statement *stmt, const otext *sql,...)
| Prepare a formatted SQL statement or PL/SQL block. More...
OCI_EXPORT boolean | OCI_ExecuteStmtFmt (OCI_Statement *stmt, const otext *sql,...)
| Execute a formatted SQL statement or PL/SQL block. More...
OCI_EXPORT boolean | OCI_ParseFmt (OCI_Statement *stmt, const otext *sql,...)
| Parse a formatted SQL statement or PL/SQL block. More...
OCI_EXPORT boolean | OCI_DescribeFmt (OCI_Statement *stmt, const otext *sql,...)
| Describe the select list of a formatted SQL select statement. More...

## Function Documentation

## OCI_Immediate()

OCI_EXPORT boolean OCI_Immediate | ( | OCI_Connection * | con,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Perform 3 calls (prepare+execute+fetch) in 1 call.

Parameters

  con | - Connection handle
  sql | - SQL statement
  ... | - List of program variables address to store the result of fetch operation

Note
  Every output parameter MUST be preceded by an integer parameter that indicates the type of the placeholder in order to handle correctly the given pointer.

TRUE on success otherwise FALSE

## OCI_ImmediateFmt()

OCI_EXPORT boolean OCI_ImmediateFmt | ( | OCI_Connection * | con,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Performs 4 call (prepare+bind+execute+fetch) in 1 call.

Parameters

  con | - Connection handle
  sql | - SQL statement
  ... | - List of program values to format the SQL followed by the output variables addresses for the fetch operation

TRUE on success otherwise FALSE

## OCI_PrepareFmt()

OCI_EXPORT boolean OCI_PrepareFmt | ( | OCI_Statement * | stmt,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Prepare a formatted SQL statement or PL/SQL block.

Parameters

  stmt | - Statement handle
  sql | - SQL statement
  ... | - List of program values to format the SQL

Returns
  TRUE on success otherwise FALSE

## OCI_ExecuteStmtFmt()

OCI_EXPORT boolean OCI_ExecuteStmtFmt | ( | OCI_Statement * | stmt,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Execute a formatted SQL statement or PL/SQL block.

Parameters

  stmt | - Statement handle
  sql | - SQL statement
  ... | - List of program values to format the SQL

Returns
  TRUE on success otherwise FALSE

Warning
  If a SQL warning occurs:
  - the function returns TRUE
  - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() attribute set to OCI_ERR_WARNING
  - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error object corresponding to the warning

## OCI_ParseFmt()

OCI_EXPORT boolean OCI_ParseFmt | ( | OCI_Statement * | stmt,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Parse a formatted SQL statement or PL/SQL block.

Parameters

  stmt | - Statement handle
  sql | - SQL statement
  ... | - List of program values to format the SQL

Note
  This call sends the SQL or PL/SQL command to the server for parsing only. The command is not executed. This call is only useful to check is a command is valid or not.
  This call prepares the statement (internal call to OCI_Prepare()) and ask the Oracle server to parse its SQL or PL/SQL command. OCI_Execute() can be call after OCI_ParseFmt() in order to execute the statement, which means that the server will re-parse again the command.

Warning
  Do not use OCI_ParseFmt() unless you're only interested in the parsing result because the statement will be parsed again when executed and thus leading to unnecessary server round-trips and less performance

Returns
  TRUE on success otherwise FALSE

## OCI_DescribeFmt()

OCI_EXPORT boolean OCI_DescribeFmt | ( | OCI_Statement * | stmt,
|  | const otext * | sql,
|  |  | ...
| ) |  |

`#include <ocilib.h>`

Describe the select list of a formatted SQL select statement.

Parameters

  stmt | - Statement handle
  sql | - SQL statement
  ... | - List of program values to format the SQL

Note
  This call sends the SELECT SQL order to the server for retrieving the description of the select order only. The command is not executed. This call is only useful to retrieve information on the associated resultset Call OCI_GetResultet() after OCI_Describe() to access to SELECT list information
  This call prepares the statement (internal call to OCI_Prepare()) and ask the Oracle server to describe the output SELECT list. OCI_Execute() can be call after OCI_Desbribe() in order to execute the statement, which means that the server will parse, and describe again the SQL order.

Warning
  Do not use OCI_Desbribe() unless you're only interested in the resultset information because the statement will be parsed again when executed and thus leading to unnecessary server round-trips and less performance

Returns
  TRUE on success otherwise FALSE