Cartridge Services -- Memory Services

Table 13-5 OCI Parameter Manager Interface Functions Quick Reference  

Function/Page	Purpose
OCIDurationBegin()	Starts a user duration.
OCIDurationEnd()	Terminates a user duration.
OCIMemoryAlloc()	Allocates memory of a given size from a given duration.
OCIMemoryResize()	Resizes a memory chunk.
OCIMemoryFree()	Frees a memory chunk.

OCIDurationBegin()

Purpose

Start a user duration

Syntax

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

Parameters

env (IN/OUT)

The OCI environment handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in <Emphasis>err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling <Emphasis>OCIErrorGet().

svc (IN)

The OCI service context handle. This should be passed as NULL for cartridge services.

parent (IN)

The duration number of the parent duration. One of these:

• A user duration that was previously created.

• OCI_DURATION_STATEMENT

• OCI_DURATION_SESSION

duration (OUT)

An identifier unique to the newly created user duration.

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

Comments

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.

Related Functions

OCIDurationEnd()

OCIDurationEnd()

Purpose

Terminates a user duration

Syntax

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

Parameters

env (IN/OUT)

The OCI environment handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in <Emphasis>err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling <Emphasis>OCIErrorGet().

duration (IN)

A user duration previously created by OCIDurationBegin().

svc (IN)

OCI service context (this should be passed as NULL for cartridge services, otherwise non-NULL).

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

Comments

This function terminates an user duration.

Note that the environment and service context parameters cannot both be NULL.

Related Functions

OCIDurationBegin()

OCIMemoryAlloc()

Purpose

This call allocates memory of a given size from a given duration.

Syntax

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

Parameters

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_CALLOUT

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.

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

Comments

To allocate memory for duration of callout of agent, i.e., external procedure duration, use OCIExtProcAllocCallMemory() or OCIMemoryAlloc() with dur as OCI_DURATION_CALLOUT.

Returns

Error code.

OCIMemoryResize()

Purpose

This call resizes a memory chunk to a new size.

Syntax

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

Parameters

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

mem (IN/OUT)

Pointer to memory allocated previously using OCIMemoryAlloc().

newsize (IN)

Size of memory requested.

flags (IN)

Set OCI_MEMORY_CLEARED bit to get memory that has been cleared.

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

Comments

Memory must have been allocated before this function can be called to resize.

Returns

Error code.

OCIMemoryFree()

Purpose

This call frees a memory chunk.

Syntax

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

Parameters

hndl (IN)

The OCI environment or user session handle.

err (IN)

The error handle.

mem (IN/OUT)

Pointer to memory allocated previously using OCIMemoryAlloc().

Returns

Error code.

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