UnQLite C/C++ API Reference - VM Configure.

Configuration Verb

Expected Arguments

Description

UNQLITE_VM_CONFIG_OUTPUT

Two Arguments:

int (*xConsumer)(

  const void  *pOutput,

  unsigned int nLen,

  void *pUserData

),

void *pUserData;

This option is used to install a VM output consumer callback. That is, an user defined function responsible of consuming the VM output such as redirecting it (i.e. The VM output) to STDOUT or sending it back to the connected peer.

This option accepts two arguments. The first argument is a pointer to the user defined function responsible of consuming the VM output. The callback must accept three arguments. The first argument is a pointer to the VM generated output that the callback body can safely cast to a string (const char *). Note that if the pointer is casted to a string, keep in mind it is not null terminated. The second argument is the VM output length in bytes. The virtual machine guarantee this number is always greater than zero. The last argument is a copy of the pointer (callback private data) passed as the second argument to this option. When done, the callback must return UNQLITE_OK. But if for some reason the callback wishes to abort processing and thus to stop program execution, it must return UNQLITE_ABORT instead of UNQLITE_OK.

Note: The virtual machine will invoke this callback each time it have something to output.

Refer to the following article for an introduction and some working example of VM output consumer callbacks.

The last argument this option takes is an arbitrary user pointer forwarded verbatim by the engine to the callback as its last argument.

UNQLITE_VM_CONFIG_IMPORT_PATH

One Argument:

const char *zPath;

This option add a path to the import search directories. That is, if a local file is included from the running script using the include or import Jx9 constructs, then the given path is used as one of the search directory. This option takes a single argument which is a pointer to a NULL terminated string holding the search path.

Example:

/* Import from local/include*/

unqlite_vm_config(

pVm,

UNQLITE_VM_CONFIG_IMPORT_PATH,

"/usr/local/include"

);

UNQLITE_VM_CONFIG_ERR_REPORT

No Arguments

This option takes no arguments and if set, all run-time errors such as call to an undefined function, instantiation of an undefined class and so on are reported in the VM output.

UNQLITE_VM_CONFIG_RECURSION_DEPTH

One Argument:

int nMaxDepth

This option is used to set a recursion limit to the running script. That is, a function may not call itself (recurse) more than this limit. If this limit is reached then the virtual machine abort the call and null is returned to the caller instead of the function return value. Note that passing this limit will not stop program execution, simply a null value is returned instead.

The default limit (depending on the host environment) is adequate for most situations (Jx9 is smart enough to peek the appropriate value) and thus we recommend the users to not set a limit of their own unless they know what they are doing.

This option accept a single argument which is an integer between 0 and 1024 specifying the desired recursion limit.

UNQLITE_VM_CONFIG_OUTPUT_LENGTH

One Argument:

unsigned int *pLength

This option takes a single argument which is the address of an unsigned integer. The value of this integer will hold the total number of bytes that have been outputted by the Virtual Machine during program execution.

UNQLITE_VM_CONFIG_CREATE_VAR

Two Arguments:

const char zVarname,

unqlite_value *pValue

This option is used to register a foreign variable within the running Jx9 script. This option is useful if you want to pass information from the outside environment to the target Jx9 script such as your application name, version, copyright or some environments variables and so forth.

This option accepts two arguments. The first argument is a pointer to a null terminated string holding the name (without the dollar sign) of the foreign variable to be installed such as APP_NAME, APP_VERSION, etc. and the second argument is a pointer to a unqlite_value obtained by a prior successful call to unqlite_vm_new_scalar() or unqlite_vm_new_array().

Use the following interfaces to populate the unqlite_value with the desired value:

unqlite_value_int()

unqlite_value_int64()

unqlite_value_bool()

unqlite_value_null()

unqlite_value_double()

unqlite_value_string()

unqlite_value_string_format()

unqlite_value_resource()

After installing the foreign variable, it is recommended that your release its associated value using unqlite_vm_release_value() since Jx9 will make a private copy of the installed value.

UNQLITE_VM_CONFIG_HTTP_REQUEST

Two Arguments:

const char *zRequest,

int nByte

This option is used to pass HTTP request information to the target Jx9 script. Jx9 is shipped with a powerful HTTP request parser and a query decoder for GET, POST and PUT methods. All you have to do is read the raw HTTP request using the standard system call such read() or recv() and pass a pointer to the buffer used for reading the request to this interface and let Jx9 parse the request, decode the queries and fill the appropriate JSON objects such as $_GET, $_POST, $_REQUEST, $_SERVER, etc.

This option must be called prior to program execution so that the Jx9 engine can populate the appropriate JSON objects.

This option accept two arguments. The first argument is a pointer to the raw HTP request just read and 

the second argument is the HTTP request length (data just read) in bytes.

UNQLITE_VM_CONFIG_SERVER_ATTR

Three Arguments:

const char *zKey,

const char *zValue,

int nLen

This option is used to manually populate the $_SERVER predefined JSON object which hold sever environments entries. This option takes three arguments. The first argument is a pointer to a null terminated string holding the entry key, the second argument is a pointer to a string holding the entry value (This string may not be null terminated). The third argument is the zValue length in bytes. If the nLen argument is less than zero, then zValue is read up to the first zero terminator. If nLen is non-negative, then it is the maximum number of bytes read from zValue.

UNQLITE_VM_CONFIG_ENV_ATTR

Three Arguments:

const char *zKey,

const char *zValue,

int nLen

This option is used to manually populate the $_ENV predefined JSON object which hold environments variable. This option takes three arguments. The first argument is a pointer to a null terminated string holding the entry key, the second argument is a pointer to a string holding the entry value (This string may not be null terminated). The third argument is the zValue length in bytes. If the nLen argument is less than zero, then zValue is read up to the first zero terminator. If nLen is non-negative, then it is the maximum number of bytes read from zValue.

UNQLITE_VM_CONFIG_EXEC_VALUE

One Argument:

unqlite_value **ppValue

This option takes one argument which is the address of a pointer to a unqlite_value. This will point to the return value of the running script (usually NULL).

UNQLITE_VM_CONFIG_IO_STREAM

One Argument:

const jx9_io_stream *pStream

This option is reserved for future use.

UNQLITE_VM_CONFIG_ARGV_ENTRY

One Argument:

const char *zArgValue;

This option is used to populate the $argv predefined JSON object. The only argument this option takes is a pointer to a null terminated string holding the script argument value to insert.

Example:

unqlite_vm_config(

pVm,

UNQLITE_VM_CONFIG_ARGV_ENTRY,

"arg1"

);

unqlite_vm_config(

pVm,

UNQLITE_VM_CONFIG_ARGV_ENTRY,

"arg2"

);

Now, $argv[0] value is “arg1” and $argv[1] value is “arg2”

UNQLITE_VM_CONFIG_EXTRACT_OUTPUT

Two Arguments:

const void **ppOut, unsigned int *pLen;

If the host application did not install a VM output consumer callback (This can be done via UNQLITE_VM_CONFIG_OUTPUT), then the Virtual Machine will automatically redirect its output to an internal buffer. This option can be used to point to that buffer.

The first argument this option takes is a pointer address. This pointer will be automatically set by the VM to point to the internal output buffer which is not null terminated.

The second argument is the address of an unsigned integer. This integer will hold the length of the VM output buffer. This option must be called after successful call to unqlite_vm_exec() and before unqlite_vm_reset() or unqlite_vm_release()

Example:

/* Execute the script */

rc = jx9_vm_exec(pVm,0);

if( rc != JX9_OK ){

Fatal("VM execution error");

}

{

const void *pOut;

unsigned int nLen;

/* Extract the output */

jx9_vm_config(

  pVm,

  JX9_VM_CONFIG_EXTRACT_OUTPUT,

  &pOut,

  &nLen

);

if( nLen > 0 ){

  /* Redirect to STDOUT */

  printf("%.*s",

      (int)nLen,

      (const char *)pOut /* Not NULL terminated */

   );

  }

}

Note that for performance reason it is preferable to install a VM output consumer callback via (UNQLITE_VM_CONFIG_OUTPUT) rather than waiting for the VM to finish executing and extracting the output.

A pointer to a unQLite Virtual Machine.

An integer configuration option that determines what property of the virtual machine is to be configured.