Symisc PH7 Engine
An Embeddable PHP5 Engine

PH7 C/C++ API Reference - List Of Constants.

This is a list of compile-time directives and numeric constants used by PH7 and represented by #defines in the ph7.h header file. These constants are things such as numeric return parameters from various interfaces.

Result codes

Many PH7 functions return an integer result code from the set shown here in order to indicates success or failure. New error codes may be added in future versions of PH7.

#define PH7_OK
/* Successful result */
#define PH7_NOMEM
/* Out of memory */
#define PH7_ABORT
/* Foreign Function request an operation abort/Another thread have released this instance */
#define PH7_IO_ERR
/* IO error */
#define PH7_LOOKED
/* Forbidden Operation */
#define PH7_CORRUPT
/* Corrupt pointer */
#define PH7_COMPILE_ERR
/* Compilation error */
#define PH7_VM_ERR
/* Virtual machine error */


The PH7_COMPILE_ERR and PH7_VM_ERR error codes are only returned by a call to one of the compile interfaces such as ph7_compile(), ph7_compile_v2() or ph7_compile_file(). The first error code (PH7_COMPILE_ERR) is returned if there is a compile-time error while compiling the PHP script. In that case the caller must fix it's erroneous PHP code and call the compile interface again. Note that the compile time error log can be extracted via a call to ph7_config() with a configuration verb set to PH7_CONFIG_ERR_LOG or PH7_CONFIG_ERR_OUTPUT.


The second error code (PH7_VM_ERR) is returned if there is a problem related to the initialization of the PH7 virtual machine (ph7_vm) after successful compilation. This problem is generally due to a memory failure but remember, running out of memory is a very unlikely scenario on modern hardware even on modern embedded systems.

The PH7_IO_ERR is returned by a call to ph7_compile_file() only if there is an IO error (such as a nonexistent file or permission error) while opening the target file in read-only mode.


PH7_NOMEM is returned only if PH7 is running out of memory. Again, this is an unlikely scenario on modern hardware.


PH7_ABORT can be returned from the body of an installed foreign function to stop program execution and thus to mimic the die() PHP construct. This error code can also be returned from one of the public interfaces if and only if the library is compiled with threading support and the given ph7 or vm pointer have been released by another thread.

Compile-Time options for The PH7 Library

For most purposes, PH7 can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to omit PH7 features (resulting in a smaller compiled library size) or to change the default values of some parameters.

Every effort has been made to ensure that the various combinations of compilation options work harmoniously and produce a working library.

PH7_ENABLE_THREADS

This option controls whether or not code is included in PH7 to enable it to operate safely in a multithreaded environment. The default is not. All mutexing code is omitted and it is unsafe to use PH7 in a multithreaded program. When compiled with the PH7_ENABLE_THREADS directive enabled, PH7 can be used in a multithreaded program and it's safe to share the same virtual machine and engine instance between two or more threads.

The value of PH7_ENABLE_THREADS can be determined at run-time using the ph7_lib_is_threadsafe() interface.

When PH7 has been compiled with PH7_ENABLE_THREAD then the threading mode can be altered at run-time using the ph7_lib_config() interface together with one of these verbs:

Also note, platforms others than Windows and UNIX systems must install their own mutex subsystem via ph7_lib_config() with a configuration verb set to PH7_LIB_CONFIG_USER_MUTEX. Otherwise the library is not threadsafe.

Note that you must link PH7 with the POSIX threads library under UNIX-like systems (i.e: -lpthread).

Options To Omit/Enable Features

The following options can be used to reduce the size of the compiled library by omitting optional features. This is probably only useful in embedded systems where space is especially tight, as even with all features included the PH7 library is relatively small. Don't forget to tell your compiler to optimize for binary size! (the -Os option if using GCC). Telling your compiler to optimize for size usually has a much larger impact on library footprint than employing any of these compile-time options.

PH7_DISABLE_BUILTIN_FUNC

PH7 come with more than 460 built-in functions suitable for most purposes ranging from string/XML/INI processing to ZIP extracting, Base64 encoding/decoding and so on. If this directive is enabled, all built-in functions are omitted from the build. Note that special functions such as is_int(), is_string(), func_get_arg(), define(), etc... are not omitted from the build and are not affected by this directive.

PH7_ENABLE_MATH_FUNC

If this directive is enabled, built-in math functions such as sqrt(), abs(), log(), ceil(), etc. are included in the build. Note that you may need to link PH7 with the math library in same Linux/BSD flavor (i.e: -lm).

PH7_DISABLE_DISK_IO

If this directive is enabled, built-in Virtual File System functions such as chdir(), mkdir(), chroot(), unlink(), sleep(), etc. are omitted from the build.

PH7_DISABLE_HASH_IO

If this directive is enabled, built-in hash functions such as md5(), sha1(), md5_file(), crc32(), etc. are omitted from the build.

PH7_OMIT_FLOATING_POINT

This option is used to omit floating-point arithmetic from the PH7 library if compiling for a processor that lacks floating point support.

When  specified, the library will substitute 64-bit integer for floating-point which mean that 25.e-3 and 25 are equals and are of type integer.




Symisc Systems
Copyright © Symisc Systems