UnQLite C/C++ API Reference - Jx9 Script Compile.

Syntax

int unqlite_compile_file(

unqlite *pDb,

const char *zFile,

unqlite_vm **ppOutVm

);

Compile a Jx9 script file to a bytecode program.

Description

To execute Jx9 code, it must first be compiled into a bytecode program using one of the compile interfaces.

This routine takes as input a Jx9 file to compile and produce a bytecode program represented by an opaque pointer to the unqlite_vm structure.

This routine does not actually evaluate the Jx9 code. It merely prepares it for later execution.

On successful compilation, the compiled program is stored in the ppOutVm pointer (Third parameter) and the program is ready for execution using unqlite_vm_exec(). When something goes wrong while compiling the Jx9 script due to a compile-time error, the caller must discard the ppOutVm pointer and fix its erroneous Jx9 code. The compile-time error log can be extracted (See example below) using the unqlite_config() interface with a configuration verb set to UNQLITE_CONFIG_JX9_ERR_LOG.

Parameters

pDb

A pointer to a unQLite database handle.

zJx9

Relative or full path to the Jx9 file to compile.

Note: This routine depends on the xMmap() method of the underlying VFS. In other words, it tries to get a read-only memory view of the whole file. Windows and UNIX users don't have to worry about these details since UnQLite come with a built-in VFS that handle all the stuff. But others platforms must register their own VFS (Virtual File System). Otherwise this routine fail and UNQLITE_IOERR is returned.

ppOutVm

OUT: On successful compilation, *ppOutVm is left pointing to the compiled Jx9 program represented by an opaque pointer to the unqlite_vm structure. It's safe now to call one of the VM management interfaces such as unqlite_vm_config() and the compiled program can be executed using unqlite_vm_exec(). Otherwise *ppOutVM is left pointing to NULL.

Return value

UNQLITE_OK is returned on successful compilation of the target Jx9 script. Any other return value indicates failure such as:

UNQLITE_COMPILE_ERR is returned when compile-time errors occur. That is, the caller must fix its erroneous Jx9 code and call the compile interface again.

Note that the compile-time error log can be extracted (See example below) using the unqlite_config() interface with a configuration verb set to:

UNQLITE_CONFIG_JX9_ERR_LOG

UNQLITE_VM_ERR is returned when something goes wrong during initialization of the virtual machine (i.e. Out of memory). But remember, this is a very unlikely scenario on modern hardware even on modern embedded system.

UNQLITE_IOERR is returned when IO errors occurs (i.e. permission error, nonexistant file, etc.) or the underlying VFS does not implement the xMmap() method which is not the case when the built-in VFS is used.

Example

Compile this C file for a smart introduction to this interface.

#include <unqlite.h>

int rc;
unqlite *pDb;
unqlite_vm *pVm;

// Open our database;
rc = unqlite_open(&pDb,"test.db",UNQLITE_OPEN_CREATE);
if( rc != UNQLITE_OK ){ return; }

// Compile our Jx9 program
rc = unqlite_compile_file(pDb,"/path/to/jx9_prog.txt",&pVm);
if( rc != UNQLITE_OK ){
   /* Extract error log here */
   const char *zBuf;
   int iLen;
   unqlite_config(pDb,UNQLITE_CONFIG_JX9_ERR_LOG,&zBuf,&iLen);
   if( iLen > 0 ){
      puts(zBuf);
   }
   return;
}

//Configure our VM ...

// Execute our Jx9 program
rc = unqlite_vm_exec(pVm);
if( rc != UNQLITE_OK ){ return; }

// Release our VM
unqlite_vm_release(pVm);

//Auto-commit the transaction and close our handle
unqlite_close(pDb);