Call_Driver

Purpose

To directly access a database driver-specific function.

Syntax

Call_Driver {tableHandle} {sDriverName} ;
Function {iDriverFunction} ;
Callback {callbackObject} ;
Passing {sArg1} {sArg2} {iArg} ;
Result {returnValue}

Argument Explanation

{tableHandle}: Is a handle or number to the table that you wish to affect. The table must have been opened.
{sDriverName}: A string containing the name of the driver. If you pass {tableHandle}, you do not need to pass a driver name explicitly, so you pass "" -- {tableHandle} will be used to determine the driver. If you pass {sDriverName}, you do not need to pass {tableHandle}, so you can pass 0.
{iDriverFunction}: An integer whose value identifies one of {sDriverName}'s functions.
{callbackObject}: Is a handle to an object that will receive the Callback message during the sort operation. Refer to Implementing Callback Functions for more information.
{sArg1}: A string variable containing the first argument (if any) for the driver function; must be a variable, and may contain modified data when the driver call is finished.
{sArg2}: A string variable containing the second argument (if any) for the driver function; must be a variable, and may contain modified data when the driver call is finished.
{iArg}: An integer containing the third argument (if any) for the driver function.
{returnValue}: Name of a variable to contain the value returned by the driver function; must be a variable, and may contain modified data when the driver call is finished.

What It Does

Each database driver has certain specific functions. Call_Driver is used to call these from within DataFlex. The parameters to this command were set up to be as generic as possible. Most instances will not use all of them.

Example

DataFlex Driver

This section documents how to use this command for the DataFlex driver. Notice that since all parameters must be used, many null strings and zeroes appear in these examples.

Procedure IncreaseSortBufferSize
    String sNull
    Boolean bBufferSet
    Integer iSortBufferSize

    move "" to sNull
    move (1024 * 128) to iSortBufferSize
    Call_Driver 0 "DATAFLEX" Function FLEX_SET_MAX_SORT_BUFFER ;
    Callback 0 ;
    Passing sNull sNull iSortBufferSize ;
    Result bBufferSet
End_Procedure  // IncreaseSortBufferSize

This example sets the maximum amount of memory to be used during sorting to the value of integer iSortBufferSize, which might be (1024 * 128) for 128 Megabytes. FLEX_SET_MAX_SORT_BUFFER interprets its argument as Kilobytes (KB).

Function RetrieveSortBufferSize returns Integer
    String sNull
    Boolean bBufferSet
    Integer iSortBufferSize

    move "" to sNull
    Call_Driver 0 "DATAFLEX" Function FLEX_GET_MAX_SORT_BUFFER ;
    Callback 0 ;
    Passing sNull sNull iSortBufferSize ;
    Result bBufferSet
    function_return iSortBufferSize
End_Function  // RetrieveSortBufferSize

This example retrieves the maximum amount of memory to be used in sorting into an integer variable called iSortBufferSize, which is then returned by the sample function.

Procedure RepairDataFlexTable
    String sTableName sMode
    Boolean bRepairComplete

    move "Employee" to sTableName
    move "0" to sMode
    Call_Driver 0 "DATAFLEX" Function FLEX_REPAIR_FILE ;
    Callback 0 ;
    Passing sTableName sMode 0 ;
    Result bRepairComplete
End_Procedure  // RepairDataFlexTable

This example will repair the DataFlex table named in the value of string variable sTableName. The sMode argument has a value of "0", which specifies to sort the table as part of the repair process. If this argument is non-zero, the table will not be sorted, which means that only errors in the table header (.HDR) file will be fixed.

Function RepairNeeded returns String
    String sTableName sMode sRepair
    Integer iRepairNeeded

    move "Employee" to sTableName
    move "0" to sMode
    Call_Driver 0 "DATAFLEX" Function FLEX_GET_REPAIRS_NEEDED ;
    Callback 0 ;
    Passing sTableName sMode 0 ;
    Result iRepairNeeded

    if (iRepairNeeded = FLEX_HEADER_OK) ;
        move "None" to sRepair
    else if (iRepairNeeded = FLEX_BLOCK0_BAD) ;
        move "Bad Block 0" to sRepair
    else if (iRepairNeeded = FLEX_HEADER_BAD) ;
        move "Bad Header" to sRepair
    else if (iRepairNeeded = FLEX_HEADER_INTEGRITY_OFF) ;
        move "Header Integrity Turned Off" to sRepair
    else if (iRepairNeeded = FLEX_HEADER_UNREADABLE) ;
        move "Header Unreadable" to sRepair

    function_return sRepair
End_Function  // RepairNeeded

This example returns a constant representing the type of repair(s) needed to iRepairNeeded and the function returns a String representation of this to the calling method.

Procedure TurnOffIndexOptimization
    String sNull
    Boolean bOptimized

    move "" to sNull
    Call_Driver 0 "DATAFLEX" Function FLEX_SET_INDEX_OPT ;
    Callback 0 ;
    Passing sNull sNull FLEX_INDEX_OPT_OFF ;
    Result bOptimized
End_Procedure  // TurnOffIndexOptimization

This example sets index optimization to off.

Function IndexOptimizationMode returns String
    String sNull sOptMode
    Integer iRepairNeeded

    move "0" to sMode
    Call_Driver 0 "DATAFLEX" Function FLEX_GET_INDEX_OPT ;
    Callback 0 ;
    Passing sNull sNull 0 ;
    Result iOptimizeMode

    if (iOptimizeMode = FLEX_INDEX_OPT_ON) ;
        move "None" to sOptMode
    else if (iOptimizeMode = FLEX_INDEX_OPT_OFF) ;
        move "Bad Block 0" to sOptMode
    else if (iOptimizeMode = FLEX_INDEX_OPT_PERMISSIVE) ;
        move "Bad Header" to sOptMode

    function_return sOptMode
End_Function  // IndexOptimizationMode

This example retrieves the index-optimization mode to the variable iOptimizeMode and the function returns a String representation of this to the calling method.

ON is the default setting, allowing programs to use index data where all segments used are not set case-insensitive. OFF prohibits all use of index data by programs; the record buffer is always loaded after every find. PERMISSIVE allows the use of all index data, including that in case-insensitive index segments.

Function StrictTransactions returns Boolean
    String sNull
    Boolean bStrictTransactions

    move "0" to sMode
    Call_Driver 0 "DATAFLEX" Function FLEX_GET_STRICT_TRANSACTIONS ;
    Callback 0 ;
    Passing sNull sNull 0 ;
    Result bStrictTransactions

    function_return bStrictTransactions
End_Function  // StrictTransactions

This example gets the state of enforcement of the requirement for the NetWare shell (True or False) on server atomic files to the variable bStrictTransactions.

Procedure SetStrictTransactions Boolean bStrictTransactions
    String sNull
    Integer iVoid

    move "0" to sMode
    Call_Driver 0 "DATAFLEX" Function FLEX_SET_STRICT_TRANSACTIONS ;
    Callback 0 ;
    Passing sNull sNull bStrictTransactions ;
    Result iVoid
End_Procedure  // SetStrictTransactions

This example sets FLEX_SET_STRICT_TRANSACTIONS to the value of Boolean function parameter bStrictTransactions.

Notes

For specific commands and parameters to use this command with a non-DataFlex driver, refer to the database-driver documentation.
A callback function can be implemented to display the progress of long sort operations. Refer to Implementing Callback Functions for further information.