Database.Oracle.OCIFunctions

Documentation

data OCIStruct

• Each handle type has its own data type, to prevent stupid errors i.e. using the wrong handle at the wrong time.

Constructors

OCIStruct

type OCIHandle = Ptr OCIStruct

data OCIBuffer

Constructors

OCIBuffer

type BufferPtr = Ptr OCIBuffer

type BufferFPtr = ForeignPtr OCIBuffer

type ColumnResultBuffer = ForeignPtr OCIBuffer

type BindBuffer = (ForeignPtr CShort, ForeignPtr OCIBuffer, ForeignPtr CUShort)

data Context

Constructors

Context

type ContextPtr = Ptr Context

data EnvStruct

Constructors

EnvStruct

type EnvHandle = Ptr EnvStruct

data ErrorStruct

Constructors

ErrorStruct

type ErrorHandle = Ptr ErrorStruct

data ServerStruct

Constructors

ServerStruct

type ServerHandle = Ptr ServerStruct

data UserStruct

Constructors

UserStruct

type UserHandle = Ptr UserStruct

data ConnStruct

Constructors

ConnStruct

type ConnHandle = Ptr ConnStruct

data SessStruct

Constructors

SessStruct

type SessHandle = Ptr SessStruct

data StmtStruct

Constructors

StmtStruct

type StmtHandle = Ptr StmtStruct

data DefnStruct

Constructors

DefnStruct

type DefnHandle = Ptr DefnStruct

data ParamStruct

Constructors

ParamStruct

type ParamHandle = Ptr ParamStruct

data BindStruct

Constructors

BindStruct

type BindHandle = Ptr BindStruct

type ColumnInfo = (DefnHandle, ColumnResultBuffer, ForeignPtr CShort, ForeignPtr CUShort)

data OCIException

Low-level, OCI library errors.

Constructors

OCIException CInt String

Instances

Show OCIException

Methods

showsPrec :: Int -> OCIException -> ShowS

show :: OCIException -> String

showList :: [OCIException] -> ShowS

Exception OCIException

Methods

toException :: OCIException -> SomeException

fromException :: SomeException -> Maybe OCIException

displayException :: OCIException -> String

catchOCI :: IO a -> (OCIException -> IO a) -> IO a

throwOCI :: OCIException -> a

mkCInt :: Int -> CInt

mkCShort :: CInt -> CShort

mkCUShort :: CInt -> CUShort

cStrLen :: CStringLen -> CInt

cStr :: CStringLen -> CString

ociEnvCreate :: Ptr EnvHandle -> CInt -> Ptr a -> FunPtr a -> FunPtr a -> FunPtr a -> CInt -> Ptr (Ptr a) -> IO CInt

ociHandleAlloc :: OCIHandle -> Ptr OCIHandle -> CInt -> CInt -> Ptr a -> IO CInt

ociHandleFree :: OCIHandle -> CInt -> IO CInt

ociErrorGet :: OCIHandle -> CInt -> CString -> Ptr CInt -> CString -> CInt -> CInt -> IO CInt

ociParamGet :: OCIHandle -> CInt -> ErrorHandle -> Ptr OCIHandle -> CInt -> IO CInt

ociAttrGet :: OCIHandle -> CInt -> BufferPtr -> Ptr CInt -> CInt -> ErrorHandle -> IO CInt

ociAttrSet :: OCIHandle -> CInt -> BufferPtr -> CInt -> CInt -> ErrorHandle -> IO CInt

ociLogon :: EnvHandle -> ErrorHandle -> Ptr ConnHandle -> CString -> CInt -> CString -> CInt -> CString -> CInt -> IO CInt

ociLogoff :: ConnHandle -> ErrorHandle -> IO CInt

ociSessionBegin :: ConnHandle -> ErrorHandle -> SessHandle -> CInt -> CInt -> IO CInt

ociSessionEnd :: ConnHandle -> ErrorHandle -> SessHandle -> CInt -> IO CInt

ociServerAttach :: ServerHandle -> ErrorHandle -> CString -> CInt -> CInt -> IO CInt

ociServerDetach :: ServerHandle -> ErrorHandle -> CInt -> IO CInt

ociTerminate :: CInt -> IO CInt

ociTransStart :: ConnHandle -> ErrorHandle -> Word8 -> CInt -> IO CInt

ociTransCommit :: ConnHandle -> ErrorHandle -> CInt -> IO CInt

ociTransRollback :: ConnHandle -> ErrorHandle -> CInt -> IO CInt

ociStmtPrepare :: StmtHandle -> ErrorHandle -> CString -> CInt -> CInt -> CInt -> IO CInt

ociDefineByPos :: StmtHandle -> Ptr DefnHandle -> ErrorHandle -> CInt -> BufferPtr -> CInt -> CUShort -> Ptr CShort -> Ptr CUShort -> Ptr CUShort -> CInt -> IO CInt

ociStmtExecute :: ConnHandle -> StmtHandle -> ErrorHandle -> CInt -> CInt -> OCIHandle -> OCIHandle -> CInt -> IO CInt

ociStmtFetch :: StmtHandle -> ErrorHandle -> CInt -> CShort -> CInt -> IO CInt

ociBindByPos

Arguments

:: StmtHandle

-> Ptr BindHandle

-> ErrorHandle

-> CUInt

position

-> BufferPtr

buffer containing data

-> CInt

max size of buffer

-> CUShort

SQL data type

-> Ptr CShort

null indicator ptr

-> Ptr CUShort

input + output size, or array of sizes

-> Ptr CUShort

array of return codes

-> CUInt

max array elements

-> Ptr CUInt

number of array elements

-> CUInt

mode

-> IO CInt

ociBindDynamic :: BindHandle -> ErrorHandle -> ContextPtr -> FunPtr OCICallbackInBind -> ContextPtr -> FunPtr OCICallbackOutBind -> IO CInt

type OCICallbackInBind = ContextPtr -> BindHandle -> CInt -> CInt -> Ptr BufferPtr -> CInt -> Ptr Word8 -> Ptr CShort -> IO CInt

type OCICallbackOutBind = ContextPtr -> BindHandle -> CInt -> CInt -> Ptr BufferPtr -> Ptr CInt -> Ptr Word8 -> Ptr CShort -> Ptr (Ptr CShort) -> IO CInt

mkOCICallbackInBind :: OCICallbackInBind -> IO (FunPtr OCICallbackInBind)

mkOCICallbackOutBind :: OCICallbackOutBind -> IO (FunPtr OCICallbackOutBind)

getOCIErrorMsg2 :: OCIHandle -> CInt -> Ptr CInt -> CString -> CInt -> IO (CInt, String)

This is just an auxiliary function for getOCIErrorMsg.

getOCIErrorMsg :: OCIHandle -> CInt -> IO (CInt, String)

fromEnumOCIErrorCode :: CInt -> String

formatErrorCodeDesc :: CInt -> String -> String

formatOCIMsg :: CInt -> String -> OCIHandle -> CInt -> IO (Int, String)

Given the two parts of an OCIException (the error number and text) get the actual error message from the DBMS and construct an error message from all of these pieces.

formatMsgCommon :: OCIException -> OCIHandle -> CInt -> IO (Int, String)

We have two format functions: formatEnvMsg takes the EnvHandle, formatErrorMsg takes the ErrorHandle. They're just type-safe wrappers for formatMsgCommon.

formatErrorMsg :: OCIException -> ErrorHandle -> IO (Int, String)

formatEnvMsg :: OCIException -> EnvHandle -> IO (Int, String)

testForError :: CInt -> String -> a -> IO a

The testForError functions are the only places where OCIException is thrown, so if you want to change or embellish it, your changes will be localised here. These functions factor out common error handling code from the OCI wrapper functions that follow.

testForErrorWithPtr :: Storable a => CInt -> String -> Ptr a -> IO a

Like testForError but when the value you want to return is at the end of a pointer. Either there was an error, in which case the pointer probably isn't valid, or there is something at the end of the pointer to return. See dbLogon and getHandleAttr for example usage.

envCreate :: IO EnvHandle

handleAlloc :: CInt -> OCIHandle -> IO OCIHandle

handleFree :: CInt -> OCIHandle -> IO ()

setHandleAttr :: ErrorHandle -> OCIHandle -> CInt -> Ptr a -> CInt -> IO ()

setHandleAttrString :: ErrorHandle -> OCIHandle -> CInt -> String -> CInt -> IO ()

getHandleAttr :: Storable a => ErrorHandle -> OCIHandle -> CInt -> CInt -> IO a

getParam :: ErrorHandle -> StmtHandle -> Int -> IO ParamHandle

dbLogon :: String -> String -> String -> EnvHandle -> ErrorHandle -> IO ConnHandle

The OCI Logon function doesn't behave as you'd expect when the password is due to expire. ociLogon returns oci_SUCCESS_WITH_INFO, but the ConnHandle returned is not valid. In this case we have to change oci_SUCCESS_WITH_INFO to oci_ERROR, so that the error handling code will catch it and abort. I don't know why the handle returned isn't valid, as the logon process should be able to complete successfully in this case.

dbLogoff :: ErrorHandle -> ConnHandle -> IO ()

terminate :: IO ()

serverDetach :: ErrorHandle -> ServerHandle -> IO ()

serverAttach :: ErrorHandle -> ServerHandle -> String -> IO ()

getSession :: ErrorHandle -> ConnHandle -> IO SessHandle

Having established a connection (Service Context), now get the Session. You can have more than one session per connection, but I haven't implemented it yet.

sessionBegin :: ErrorHandle -> ConnHandle -> SessHandle -> CInt -> IO ()

sessionEnd :: ErrorHandle -> ConnHandle -> SessHandle -> IO ()

beginTrans :: ErrorHandle -> ConnHandle -> CInt -> IO ()

commitTrans :: ErrorHandle -> ConnHandle -> IO ()

rollbackTrans :: ErrorHandle -> ConnHandle -> IO ()

stmtPrepare :: ErrorHandle -> StmtHandle -> String -> IO ()

With the OCI you do queries with these steps:

stmtExecute :: ErrorHandle -> ConnHandle -> StmtHandle -> Int -> IO ()

defineByPos

Arguments

:: ErrorHandle

-> StmtHandle

-> Int

Position

-> Int

Buffer size in bytes

-> CInt

SQL Datatype (from Database.Oracle.OCIConstants)

-> IO ColumnInfo

tuple: (DefnHandle, Ptr to buffer, Ptr to null indicator, Ptr to size of value in buffer)

defineByPos allocates memory for a single column value. The allocated components are:

substituteBindPlaceHolders :: String -> String

Oracle only understands bind variable placeholders using syntax :x, where x is a number or a variable name. Most other DBMS's use ? as a placeholder, so we have this function to substitute ? with :n, where n starts at one and increases with each ?.

sbph :: String -> Int -> Bool -> String -> String

bindByPos

Arguments

:: ErrorHandle

-> StmtHandle

-> Int

Position

-> CShort

Null ind: 0 == not null, -1 == null

-> BufferPtr

payload

-> Int

payload size in bytes

-> CInt

SQL Datatype (from Database.Oracle.OCIConstants)

-> IO ()

bindOutputByPos

Arguments

:: ErrorHandle

-> StmtHandle

-> Int

Position

-> BindBuffer

triple of (null-ind, payload, input-size)

-> Int

buffer max size in bytes

-> CInt

SQL Datatype (from Database.Oracle.OCIConstants)

-> IO BindHandle

stmtFetch :: ErrorHandle -> StmtHandle -> IO CInt

Fetch a single row into the buffers. If you have specified a prefetch count > 1 then the row might already be cached by the OCI library.

maybeBufferNull :: ForeignPtr CShort -> Maybe a -> IO a -> IO (Maybe a)

Short-circuit null test: if the buffer contains a null then return Nothing. Otherwise, run the IO action to extract a value from the buffer and return Just it.

nullByte :: CChar

cShort2Int :: CShort -> Int

cUShort2Int :: CUShort -> Int

cuCharToInt :: CUChar -> Int

byteToInt :: Ptr CUChar -> Int -> IO Int

bufferToString :: ColumnInfo -> IO (Maybe String)

makeYear :: Int -> Int -> Int

Oracle's excess-something-or-other encoding for years: year = 100*(c - 100) + (y - 100), c = (year div 100) + 100, y = (year mod 100) + 100.

makeYearByte :: Int -> Word8

makeCentByte :: Int -> Word8

dumpBuffer :: Ptr Word8 -> IO ()

bufferToCaltime :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe CalendarTime)

bufferToUTCTime :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe UTCTime)

setBufferByte :: BufferPtr -> Int -> Word8 -> IO ()

calTimeToBuffer :: BufferPtr -> CalendarTime -> IO ()

utcTimeToBuffer :: BufferPtr -> UTCTime -> IO ()

bufferPeekValue :: Storable a => BufferFPtr -> IO a

bufferToA :: Storable a => ForeignPtr CShort -> BufferFPtr -> IO (Maybe a)

bufferToCInt :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe CInt)

bufferToInt :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe Int)

bufferToCDouble :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe CDouble)

bufferToDouble :: ForeignPtr CShort -> BufferFPtr -> IO (Maybe Double)

bufferToStmtHandle :: BufferFPtr -> IO StmtHandle