/**
 * call-seq:
 *     compile( db, sql ) -> [ vm, remainder ]
 *
 * Compiles the given SQL statement and returns a new virtual machine handle
 * for executing it. Returns a tuple: [ vm, remainder ], where +remainder+ is
 * any text that follows the first complete SQL statement in the +sql+
 * parameter.
 */
static VALUE
static_api_compile( VALUE module, VALUE db, VALUE sql )
{
  sqlite     *handle;
  sqlite_vm  *vm;
  char       *errmsg;
  const char *sql_tail;
  int         result;
  VALUE       tuple;

  GetDB( handle, db );
  Check_Type( sql, T_STRING );

  result = sqlite_compile( handle,
                           STR2CSTR( sql ),
                           &sql_tail,
                           &vm,
                           &errmsg );

  if( result != SQLITE_OK )
  {
    static_raise_db_error2( result, &errmsg );
    /* "raise" does not return */
  }

  tuple = rb_ary_new();
  rb_ary_push( tuple, Data_Wrap_Struct( rb_cData, NULL, static_free_vm, vm ) );
  rb_ary_push( tuple, rb_str_new2( sql_tail ) );

  return tuple;
}