About the Easysoft ODBC-FreeAgent Driver

The Easysoft ODBC-FreeAgent Driver provides real-time access to FreeAgent data from any application that supports ODBC.

ODBC API and scalar functions

API functions

Use this table to find out what ODBC API functions the Easysoft ODBC-FreeAgent Driver supports:

Function Status

SQLAllocConnect

Supported

SQLAllocEnv

Supported

SQLAllocHandle

Supported

SQLAllocStmt

Supported

SQLBindCol

Supported

SQLBindParameter

Supported

SQLBrowseConnect

Not supported

SQLBulkOperations

Supported

SQLCancel

Supported

SQLCloseCursor

Supported

SQLColAttribute

Supported

SQLColAttributes

Supported

SQLColumnPrivileges

Not Supported

SQLColumns

Supported

SQLConnect

Supported

SQLCopyDesc

Supported

SQLDataSources

Supported

SQLDescribeCol

Supported

SQLDescribeParam

Supported

SQLDisconnect

Supported

SQLDriverConnect

Supported

SQLDrivers

Supported

SQLEndTran

Supported

SQLError

Supported

SQLExecDirect

Supported

SQLExecute

Supported

SQLExtendedFetch

Supported

SQLFetch

Supported

SQLFetchScroll

Supported

SQLForeignKeys

Supported

SQLFreeConnect

Supported

SQLFreeEnv

Supported

SQLFreeHandle

Supported

SQLFreeStmt

Supported

SQLGetConnectAtt

Supported

SQLGetConnectOption

Supported

SQLGetCursorName

Supported

SQLGetData

Supported

SQLGetDescField

Supported

SQLGetDescRec

Supported

SQLGetDiagField

Supported

SQLGetDiagRec

Supported

SQLGetEnvAttr

Supported

SQLGetFunctions

Supported

SQLGetInfo

Supported

SQLGetStmtAttr

Supported

SQLGetStmtOption

Supported

SQLGetTypeInfo

Supported

SQLMoreResults

Supported

SQLNativeSql

Supported

SQLNumParams

Supported

SQLNumResultCols

Supported

SQLParamData

Supported

SQLParamOptions

Supported

SQLPrepare

Supported

SQLPrimaryKeys

Supported

SQLProcedureColumns

Supported

SQLProcedures

Supported

SQLPutData

Supported

SQLRowCount

Supported

SQLSetConnectAttr

Supported

SQLSetConnectOption

Supported

SQLSetCursorName

Supported

SQLSetDescField

Supported

SQLSetDescRec

Supported

SQLSetEnvAttr

Supported

SQLSetParam

Supported

SQLSetPos

Supported

SQLSetScrollOptions

Supported

SQLSetStmtOption

Supported

SQLSetStmtOption

Supported

SQLSetStmtAttr

Supported

SQLStatistics

Supported

SQLTablePrivileges

Not supported

SQLTables

Supported

SQLTransact

Supported

Scalar functions

The Easysoft ODBC-FreeAgent Driver supports a number of scalar functions:

Use either the SQL-92 or ODBC syntax with scalar functions. For example:

SELECT
  Invoice_Id,
  Customer_Name,
  EXTRACT(YEAR FROM Due_Date) as "Year"
FROM
  Invoice

SELECT
  Invoice_Id,
  Customer_Name,
  {fn EXTRACT(YEAR FROM Due_Date)} as "Year"
FROM
  Invoice

String functions

The Easysoft ODBC-FreeAgent Driver supports these string functions:

  • ASCII(string_exp)

  • BIT_LENGTH(string_exp)

  • CHAR(code)

  • CHAR_LENGTH(string_exp)

  • CHARACTER_LENGTH

  • CONCAT(string_exp1, string_exp2)

  • DIFFERENCE(string_exp1, string_exp2)

  • INSERT(string_exp1, start, length, string_exp2)

  • LCASE(string_exp)

  • LEFT(string_exp, count)

  • LENGTH(string_exp)

  • LOCATE(string_exp1, string_exp2[,start])

  • LTRIM(string_exp)

  • OCTET_LENGTH(string_exp)

  • POSITION(char_exp IN char_exp)

  • REPEAT(string_exp, count)

  • REPLACE(string_exp1, string_exp2, string_exp3)

  • RIGHT(string_exp, count)

  • RTRIM(string_exp)

  • SOUNDEX(string_exp)

  • SPACE(count)

  • SUBSTRING(string_exp, start, length)

  • TRIM

  • UCASE(string_exp)

Numeric functions

The Easysoft ODBC-FreeAgent Driver supports these numeric functions:

  • ABS(numeric_exp)

  • ACOS(float_exp)

  • ASIN(float_exp)

  • ATAN(float_exp)

  • ATAN2(float_exp1, float_exp2)

  • CEILING(numeric_exp)

  • COS(float_exp)

  • COT(float_exp)

  • DEGREES(numeric_exp)

  • EXP(float_exp)

  • FLOOR(numeric_exp)

  • LOG(float_exp)

  • LOG10(float_exp)

  • MOD(integer_exp1, integer_exp2)

  • PI()

  • POWER(numeric_exp, integer_exp)

  • RADIANS(numeric_exp)

  • RAND([integer_exp])

  • ROUND(numeric_exp, integer_exp)

  • SIGN(numeric_exp)

  • SIN(float_exp)

  • SQRT(float_exp)

  • TAN(float_exp)

  • TRUNCATE(numeric_exp, integer_exp)

Time, date, and interval functions

The Easysoft ODBC-FreeAgent Driver supports these time, date, and interval functions:

  • CURRENT_DATE()

  • CURRENT_TIME[(time-precision)]

  • CURRENT_TIMESTAMP[(timestamp-precision)]

  • CURDATE()

  • CURTIME()

  • DAYNAME(date_exp)

  • DAYOFMONTH(date_exp)

  • DAYOFWEEK(date_exp)

  • DAYOFYEAR(date_exp)

  • EXTRACT(extract-field FROM extract-sourc)

  • HOUR(time_exp)

  • MINUTE(time_exp)

  • MONTH(date_exp)

  • MONTHNAME(date_exp)

  • NOW()

  • QUARTER(date_exp)

  • SECOND(time_exp)

  • TIMESTAMPADD(interval, integer_exp, timestamp_exp)

  • TIMESTAMPDIFF(interval, timestamp_exp1, timestamp_exp2)

  • WEEK(date_exp)

  • YEAR(date_exp)

System functions

The Easysoft ODBC-FreeAgent Driver supports these system functions:

  • DATABASE()

  • IFNULL(exp, value)

  • USER()

Conversion functions

The Easysoft ODBC-FreeAgent Driver supports supports both the SQL-92 CAST function and the ODBC CONVERT function for conversion between compatible data types.

Data type mapping

The Easysoft ODBC-FreeAgent Driver maps FreeAgent data types to ODBC data types in this way:

URI

FreeAgent data type ODBC data type

Array

SQL_WLONGVARCHAR

Boolean

SQL_BIT

Date

SQL_TYPE_DATE

Decimal

SQL_DOUBLE

Integer

SQL_INTEGER

Object

SQL_WLONGVARCHAR

Parameter

SQL_TYPE_TIMESTAMP
SQL_TYPE_DATE


SQL_WVARCHAR

String

SQL_WVARCHAR
SQL_WLONGVARCHAR
SQL_TYPE_DATE
SQL_TYPE_TIMESTAMP
SQL_INTEGER
SQL_DOUBLE

Timestamp

SQL_TYPE_TIMESTAMP

URI

SQL_WVARCHAR

Finding out more about data types on Windows

If you need more information about a data types, for example, the precision and scale, use Microsoft’s ODBC Test to do this.

  1. Download the version of ODBC Test that matches your application’s architecture from:

  2. Copy both files to a folder on the machine where Easysoft ODBC-FreeAgent Driver is installed.

  3. Double-click odbcte32.exe.

  4. Select Con > Full Connect.

  5. Choose your Easysoft ODBC-FreeAgent Driver data source from the list.

  6. Choose Catalog > SQLGetTypeInfo.

  7. Either choose SQL_ALL_TYPES=0 (1.0) or a specific data type from the DataType list.

  8. Choose Results > Get Data All.

SQL support

The Easysoft ODBC-FreeAgent Driver supports these SQL statements, clauses, and operators:

  • SELECT

  • SELECT DISTINCT

  • WHERE

  • ORDER BY

  • AND

  • OR

  • NOT

  • INSERT INTO

  • NULL

  • UPDATE

  • DELETE

  • TOP

  • MIN

  • MAX

  • COUNT

  • SUM

  • AVG

  • LIKE

  • WILDCARDS

  • IN

  • BETWEEN

  • ALIASES

  • JOINS

  • UNION

  • GROUP BY

  • HAVING

  • EXISTS

  • CASE

Example queries

  • To fetch all records from a table, use the asterisk symbol (*) in your queries. For example:

    SELECT * FROM Invoices
  • To only fetch records whose values are different, use DISTINCT. For example:

    -- Which different customers do we invoice?
    SELECT DISTINCT Contact_Name AS Different_Contact_Name FROM Invoices
    -- How many different customers do we invoice?
    SELECT COUNT(DISTINCT Contact_Name) AS Different_Contact_Total FROM Invoices
  • To filter records, use WHERE. For example:

    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoice
    WHERE
      Currency = 'USD'
    
    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      Currency = 'USD'
      OR Currency = 'EUR'
    
    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      Currency = 'USD'
      AND Total_Value < 1000

    You can also supply a WHERE clause value as a parameter. For example, to do this in Python:

    cursor.execute("SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      Currency = ?", ['USD'])
  • To fetch records that don’t match the WHERE clause pattern use NOT. For example:

    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      NOT Currency = 'USD'
  • To sort the result set in either ascending or descending order, use ORDER BY. For example:

    SELECT
      Id,
      Contact_Name,
      Net_Value
    FROM
      Invoices
    ORDER BY
      Net_Value ASC
    
    SELECT
      *
    FROM
      Contacts
    ORDER BY
      (
        CASE
          WHEN Last_Name IS NULL THEN Organisation_Name
          ELSE Last_Name
        END
      );
  • To group a result set into summary rows, use GROUP BY. For example:

    SELECT
        COUNT(Id) As "Number",
        Currency
    FROM
        Invoices
    GROUP BY
        Currency
    
    SELECT
      COUNT(Id) As "Number",
      Currency
    FROM
      Invoices
    GROUP BY
      Currency
    HAVING
      COUNT(Id) > 10;
  • To do calculations based on result set vales, use the SQL aggregate functions MIN(), MAX(), COUNT(), SUM(), and AVG(). For example:

    SELECT Max(Total_Value) FROM Invoices
    SELECT Sum(Total_Value) FROM Invoices

    In addition, you can use these scalar funtions.

  • To convert between compatible data types, use CAST or CONVERT. For example:

    SELECT CAST(Total_Value AS Char(100))FROM Invoices
    SELECT {fn CONVERT(Total_Value, SQL_CHAR)} FROM Invoices
  • To fetch records that contain column values between a given range, use BETWEEN For example:

    SELECT Id, Contact_Name FROM Invoices WHERE Total_Value BETWEEN 10 AND 20
  • To combine the result set of two or more SELECT statements, use UNION. For example:

    SELECT
        Group_Description,
        Description,
        Id,
        Url,
        Nominal_Code,
        Allowable_For_Tax,
        Tax_Reporting_Name,
        Auto_Sales_Tax_Rate
    FROM
        Categories_Admin_Expenses
    UNION ALL
    SELECT
        Group_Description,
        Description,
        Id,
        Url,
        Nominal_Code,
        Allowable_For_Tax,
        Tax_Reporting_Name,
        Auto_Sales_Tax_Rate
    FROM
        Categories_Cost_Of_Sales
    UNION ALL
    SELECT
        REPLACE (Url, Url, 'General') AS Group_Description,
        Description,
        Id,
        Url,
        Nominal_Code,
        CAST(NULL AS bit) AS Allowable_For_Tax,
        Tax_Reporting_Name,
        CAST(NULL AS double) AS Auto_Sales_Tax_Rate
    FROM
        Categories_General
    UNION ALL
    SELECT
        Group_Description,
        Description,
        Id,
        Url,
        Nominal_Code,
        CAST(NULL AS bit) AS Allowable_For_Tax,
        REPLACE (Url, Url, 'N/A') AS Tax_Reporting_Name,
        Auto_Sales_Tax_Rate
    FROM
        Categories_Income
  • To combine rows from two or more tables, use JOIN. For example:

    SELECT
        a.Name,
        bt.*
    FROM
        Bank_accounts a
        LEFT JOIN Bank_Transactions bt ON bt.Bank_Account = a.URL
  • To fetch records that contain column values matching a search pattern, use LIKE. For example:

    SELECT Id FROM Invoices WHERE Contact_Name LIKE 'E%'
    SELECT Id FROM Invoices WHERE Contact_Name LIKE '_asysoft'
  • To search for columns without a value (NULL) or with a value (non NULL), use either IS NULL or IS NOT NULL. For example:

    SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Include_Estimates IS NULL
  • To specify multiple values in a WHERE clause, you can use IN as an alternative to OR. For example:

    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      Currency = 'USD'
      OR Currency = 'EUR'
      OR Currency = 'GBP'

    can be replaced with:

    SELECT
      Id,
      Contact_Name,
      Total_Value
    FROM
      Invoices
    WHERE
      Currency IN ('USD', 'EUR', 'GBP');
  • To set the maximum number of records to return, use TOP. For example:

    SELECT TOP 10 Id, Contact_Name FROM Invoices
  • To test for the existence of records in a subquery, use EXISTS. For example:

    SELECT
      Contact_Name
    FROM
      Invoices
    WHERE
      EXISTS (
        SELECT
          First_Name,
          Last_Name
        FROM
          Contacts
        WHERE
          Invoices.Contact_Id = Contacts.Id
          AND Currency = 'USD'
      )

Example inserts, updates, and deletes

  • To insert a FreeAgent record, use INSERT INTO. For example:

    INSERT INTO
        Bills (
            Contact,
            Reference,
            Dated_On,
            Due_On,
            Bill_Items
        )
    VALUES
        (
            'https://api.freeagent.com/v2/contacts/18727314',
            'YEB021',
            '2025-01-16',
            '2025-01-16',
            '[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'
        )
  • Here’s a SQL Server linked server example:

    EXEC ('INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items)
    VALUES (''https://api.freeagent.com/v2/contacts/18727314'' , ''YEB021'' , ''2025-01-16'' , ''2025-01-16'' , ''[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'')')
  • Here’s an Oracle linked table example:

    DECLARE
      num_rows integer;
    BEGIN
    num_rows:=DBMS_HS_PASSTHROUGH.EXECUTE_IMMEDIATE@FreeAgentLink
    ('INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items) VALUES (''https://api.freeagent.com/v2/contacts/18727314'', ''YEB021'', ''2025-01-16'', ''2025-01-16'', ''[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'')');
    END;
    /
  • The Easysoft ODBC-FreeAgent Driver also supports parameterized inserts. Here’s an example of doing this in PHP:

    $stmt = odbc_prepare($cnx, "INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items) VALUES (?, ?, ?, ?, ?)");
    
    $success = odbc_execute($stmt, array('https://api.freeagent.com/v2/contacts/18727314', 'YEB021', '2025-01-16', '2025-01-16', '[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'));
  • To update a FreeAgent record, use UPDATE. For example:

    UPDATE Bills
    SET
      Contact = 'Standing charges for second line.'
    WHERE
      Account_Id = '31962267'

    The Easysoft ODBC-FreeAgent Driver also supports parameterized updates. Here’s an example of doing this in Perl:

    my $sth = $dbh->prepare('UPDATE Bills SET Contact = \'Standing charges for second line.\' WHERE Id = ?')
        or die "Can't prepare statement: $DBI::errstr";
    
    $sth->execute('31962267');
  • To delete a FreeAgent record, use DELETE. For example:

    -- Delete (mark inactive) a bank account
    DELETE FROM Bills WHERE Id = '31962267'

    The Easysoft ODBC-FreeAgent Driver also supports parameterized deletes. Here’s an example of doing this in Python:

    sql = "DELETE FROM Bills WHERE Id = ?"
    cursor.execute(sql, '31962267')