Plug in process

After defining a relational representation of data structures using the PiCO QL DSL, users should provide this description (say pico_ql_dsl.sql to the Ruby parser-generator by executing:

          cd PiCO QL/src
          ruby pico_ql_generator.rb pico_ql_dsl.sql [cpp] [c] [kernel] [mem_mgt] [no_mem_mgt] [debug]

cpp and mem_mgt are the default configuration. cpp means generate code for C++ build and mem_mgt means provide appropriate memory containers for storing method return variables in case they contain temporaries. c means generate code for C build while kernel means generate code for Linux kernel module build. The option debug prints debug information.

Users can register data structures with PiCO QL by calling:

          void register_data(void *data_structure, const char *ds_name)         # C++ 
          void pico_ql_register_data(void *data_structure, const char *ds_name) # C

Each data structure will be represented as one or more virtual table. void *data_structure is a pointer to a described C/C++ data structure and const char *ds_name is a name for the data structure that has to agree with the C NAME used in the DSL description (WITH REGISTERED C NAME ds_name).

The library is initiated with a call to:

          int init(char **db_pragmas, int argc, int port, pthread_t *t);         # C++ 
          int pico_ql_init(char **db_pragmas, int argc, int port, pthread_t *t); # C   

Application source code files containing the above two calls should include the pico_ql_search.h header file. Figure 6 presents the plug-in process.

Compile options

The flags PICO_QL_DEBUG, PICO_QL_TEST, PICO_QL_SINGLE_THREADED, PICO_QL_HANDLE_TEXT_ARRAY and PICO_QL_HANDLE_POLYMORPHISM configure the source code.

• PICO_QL_DEBUG corresponds to debug switches all over the C/C++ source code.
• PICO_QL_TEST option switches to test mode. Instead of starting the SWILL web interface, PICO QL executes the test queries it finds in pico_ql_test.c. Accordingly, it writes the results in a file called pico_ql_test_current.txt and calls a small, simple script (pico_ql_diff_test.sh) which compares the latter with pico_ql_test_success.txt.
• PICO_QL_SINGLE_THREADED starts the library in the same thread as the application. The default is a multi thread configuration where the library starts in a separate thread from the application's. If PICO_QL_SINGLE_THREADED is not defined users need to take care of the termination of PICO QL's thread with pthread_join() and provide synchronised access to the data structures accessed by both the application and PICO QL. Please see the Linux kernel module's pico_ql_dsl.sql on PiCO QL's support for synchronised access to data structures.
• PICO_QL_HANDLE_TEXT_ARRAY forces the use of a dynamic vector<string*> to hold char array return values of methods. This is useful in case of virtual methods that write to the same or neighboring memory locations their return value and the columns that represent them coexist in a SELECT clause. Since SQLite collects each column's value and presents them when the whole row is complete, the return values of the virtual methods are messed up when SQLite uses the pointer to the character array provided to it.
• PICO_QL_HANDLE_POLYMORPHISM drives dynamic type checks to ensure the safe querying of polymorphic data structures.