Navigation: Advanced Topics >====== FileCallBackInterface and DriverOps ====== | |
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 = valueParams.Property =propertyParams.Index = index |
SETBlobProperty | blob{property} = value | Params.Index =blob number in file definition (1 based)Params.Text = valueParams.Property = property |
SETKeyProperty | key{property,index} = value | Params.Text = valueParams.Property = propertyParams.Key1 = keyParams.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.