FileCallBackInterface and DriverOps

Top  Previous  Next

 

The FileCallBackInterface methods are called before and after each file operation. For every FileCallBackInterface registered with a FILE or VIEW the FileCallBackInterface.FunctionCalled method is called before the operation (opcode) is performed. If any of these methods return FALSE, or Parameters.StopOperation is set to TRUE, then the operation is not executed. After the operation has been called, or would have been called if FileCallBackInterface.FunctionCalled did not return FALSE, FileCallBackInterface.FunctionDone is called for every registered interface (See CALLBACK).

 

If either FileCallBackInterface.FunctionCalled or FileCallBackInterface.FunctionDone returns FALSE:

 

1. ERRORCODE() will be set to TRIGGERERROR (100)

2. FILEERRORCODE() will be set to the FileErrCode parameter of the first method that returned FALSE

3. FILEERROR() will be set to the FileErrMsg parameter of the first method that returned FALSE.

 

A CSTRING(81) is passed in FileErrCode and a CSTRING(256) is passed in FileErrMsg.

 

Both of the FileCallBackInterface methods receive an opCode and Parameters. Parameters are set up to offer different values depending on the particular opCode passed to the method.

 

The EQUATES.CLW file found in LIBSRC defines valid opCodes using the following format:

 

DriverOp:Action

 

 

Action

Invoking Statement

Valid Parameters

SEND

SEND(file, str)

Params.Text = str

COPY

COPY(file, str)

Params.Text = str

RENAME

RENAME(file,str)

Params.Text = str

SETNULLS

SETNULLS(file,str)

Params.Text = str

 

SETProperty

file{property,index} = value

Params.Text = value

Params.Property =property

Params.Index = index

 

SETBlobProperty

blob{property} = value

Params.Index =

blob number in file definition (1 based)

Params.Text = value

Params.Property = property

 

SETKeyProperty

key{property,index} = value

Params.Text = value Params.Property = property Params.Key1 = key Params.Index = index

 

DOProperty

file{property, index}

 

 

GetProperty

x = file{property,index}

 

 

DOBlobProperty

blob{property}

Params.Index =blob number in file definition (1 based) Params.Property = property

 

 

 

GetBlobProperty

x = blob{property}

Params.Index = blob number in file definition (1 based) Params.Property = property

 

 

 

DOKeyProperty

Key{property, index}

Params.Property = property Params.Key1 = key Params.Index = index

 

 

 

GetKeyProperty

x = key{property}

Params.Property = property Params.Key1 = key Params.Index = index

 

 

 

BUILDdyn

BUILD(INDEX, field_list)

Params.FieldList = field_list Params.Key1 = INDEX

 

 

 

BUILDdynfilter

BUILD(INDEX, field_list, filter)

Params.FieldList = field_list Params.Text = filter Params.Key1 = INDEX

 

 

 

REGETfile

REGET(file,buffer)

Params.Position = buffer

 

 

 

RESETfile

RESET(file,buffer)

Params.Position = buffer

 

 

 

REGETkey

REGET(key,buffer)

Params.Position = buffer Params.Key1 = key

 

 

 

RESETkey

RESET(key,buffer)

Params.Position = buffer Params.Key1 = key

 

 

 

ADDfilelen

ADD(file,length)

Params.Len = length

 

 

 

APPENDlen

APPEND(file,length)

Params.Len = length

 

 

 

BUFFER

BUFFER(file,pagesize, behind, ahead, timeout)

Params.Buffer = pagesize Params.Behind = behind Params.Ahead = ahead Params.TimeOut = timeout

 

 

 

BUILDkey

BUILD(key)

Params.Key1 = key

 

 

 

DUPLICATEkey

DUPLICATE(key)

Params.Key1 = key

 

 

 

GETfilekey

GET(file,key)

Params.Key1 = key

 

 

 

POINTERkey

x = POINTER(key)

Params.Key1 = key

 

 

 

POSITIONkey

x = POSITION(key)

Params.Key1 = key

 

 

 

RECORDSkey

x = RECORDS(key)

Params.Key1 = key

 

 

 

SETfilekey

SET(file,key)

Params.Key1 = key

 

 

 

SETkey

SET(key)

Params.Key1 = key

 

 

 

OPEN

OPEN(file, mode)

Params.OpenMode = mode

 

 

 

SHARE

SHARE(file, mode)

Params.OpenMode = mode

 

 

 

GETfileptrlen

GET(file, pointer, length)

Params.Pointer = pointer Params.Len = length

 

 

 

PUTfileptrlen

PUT(file, pointer, length)

Params.Pointer = pointer Params.Len = length

 

 

 

GETfileptr

GET(file, pointer)

Params.Pointer = pointer

 

 

 

PUTfileptr

PUT(file, pointer)

Params.Pointer = pointer

 

 

 

SETfileptr

SET(file, pointer)

Params.Pointer = pointer

 

 

 

GETkeyptr

GET(key, pointer)

Params.Key1 = key Params.Pointer = pointer

 

 

 

SETkeyptr

SET(key, pointer)

Params.Key1 = key Params.Pointer = pointer

 

 

 

HOLDfilesec

HOLD(file, seconds)

Params.Seconds = seconds

 

 

 

LOCKfilesec

LOCK(file, seconds)

Params.Seconds = seconds

 

 

 

SETkeykeyptr

SET(key1, key2, pointer)

Params.Key1 = key1 Params.Key1 = key2 Params.Pointer = pointer

 

 

 

SETkeykey

SET(key1, key2)

Params.Key1 = key1 Params.Key1 = key2

 

 

 

SKIP

SKIP(file, records)

Params.Records = records

 

 

 

NULL

x = NULL(field)

Params.Field = ADDRESS(field) Params.Len = SIZE(field)

SETNULL

SETNULL(field)

Params.Field = ADDRESS(field) Params.Len = SIZE(field)

SETNONNULL

SETNONULL(field)

Params.Field = ADDRESS(field) Params.Len = SIZE(field)

 

 

 

CLEARfile

CLEAR(file, n)

Params.Index = n

 

 

 

DESTROY

called on termination of application or thread

Params.Index = THREAD()

 

 

 

GETblobdata

x = blob[s : e]

Params.Index =blob number in file definition (1 based) Params.Start = s Params.Stop = e

 

 

 

SETblobdata

blob[s : e] = x

Params.Index = blob number in file definition (1 based) Params.Start = s Params.Stop = e

 

 

 

BLOBSIZE

x = SIZE(blob)

Params.Index =blob number in file definition (1 based)

 

 

 

SETviewfields

SET(view, fields = 0)

Params.Fields = fields

 

 

 

RESETviewf

RESET(view, file)

Params.File = file

 

 

 

RESTORESTATE

RESTORESTATE(file, state, restorebuffer)

Params.State = state Params.RestoreBuffer = restorebuffer

 

 

 

FREESTATE

FREESTATE(file, state)

Params.State = state

 

 

 

VIEWSTART

internal operation

Params.TransactionOpCode = operation starting or stopping

 

 

 

VIEWEND

internal operation

Params.TransactionOpCode = operation starting or stopping

 

VIEWSTART and VIEWEND are called by the ISAM View Engine when it executes NEXT, PREV, POSITIONfile, REGETfile, RESETfile, GETfileptr, RECORDSfile,and SKIP.

 

STARTTRAN

internal operation

Params.TransactionOpCode = operation starting or stopping

 

 

 

ENDTRAN

internal operation

Params.TransactionOpCode = operation starting or stopping

 

The runtime library will call the file driver once when starting a transaction statement (LOGOUT, COMMIT, or ROLLBACK) with an opCode of DriverOps:STARTTRAN and once when ending the transaction statement with an opCode of DriverOps:ENDTRAN. If a callback has been registered with the first file in the logout file list, then it will be called with opCode set to DriverOps:STARTTRAN at the start of the transaction command and DriverOps:ENDTRAN at the end of the transaction command. In this case Parameters.TransactionOpCode will be set to either DriverOps:LOGOUT, DriverOps:COMMIT or DriverOps:ROLLBACK.