| **Navigation:**  [[advanced topics 1.htm|Advanced Topics]] >====== FileCallBackInterface and DriverOps ====== | [[keycode equates list.htm|{{btn_prev_n.gif|Previous page}}]][[advanced topics 1.htm|{{btn_home_n.gif|Return to chapter overview}}]][[clarioncl exe.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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  register or unregister a filecallbackinterface.htm|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 |

{{notebox.jpg|NoteBox.jpg}}

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 |

{{notebox.jpg|NoteBox.jpg}}

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**.