$ABOUTCATEG$
	CODB-QUERY
$SUMMARY$
	Library for work with CODB databases by queries.
$LANG_RU$
	      CODB  .
$DESCRIPTION$
	codb-query library provides unified access to CODB databases by
	queries instead call of	methods of classes <link linkend="classCODBDEPOSITORY">CODBDEPOSITORY</link>, 
	<link linkend="classCODBDICTIONARY">CODBDICTIONARY</link>, 
	<link linkend="classCODBLIST">CODBLIST</link> and
	<link linkend="classCODBIDLIST">CODBIDLIST</link>.
	
	Queries are written on CQL language (SQL dialect adapted for CODB). You
	can use this library in own CLIP program or use console program called codb.
	
	<command>Using In Programs.</command>
	
	For use codb-query library in programs you should build program with this
	library. Just append '-lcodb-query' to build command.
	
	Typical session of work with database contains following steps:
<pre>db := codb_connect() // Connect to databases
e := codb_get_error( db ) // Check error
if e != NIL
	?? "ERROR codb_connect(): " + e + chr(10)
	return 1
endif

// Query execution
oRes := codb_execute( db, 'show databases' )

// Process result
aResult := codb_get_result( oRes )

codb_close( db ) // Close databases</pre>
	
	Connect to databases is provided by function 
	<link linkend="functionCODBCONNECT">codb_connect()</link>. This function
	opens all available databases. Function 
	<link linkend="functionCODBCLOSE">codb_close()</link> closes all databases.
	
	Real operations with databases are provided by functions:
	<link linkend="functionCODBEXECUTE">codb_execute()</link>, 
	<link linkend="functionCODBGETMETAOBJECT">codb_get_metaobject()</link>,
	<link linkend="functionCODBGETOBJECT">codb_get_object()</link>,
	<link linkend="functionCODBPUTMETAOBJECT">codb_put_metaobject()</link>,
	<link linkend="functionCODBPUTOBJECT">codb_put_object()</link>.
	
	The difference between these functions is 
	<link linkend="functionCODBEXECUTE">codb_execute()</link> returns object, from
	which you can extract data by function 
	<link linkend="functionCODBGETRESULT">codb_get_result()</link>, but other
	functions operate only real objects. 
	
	For error check use 
	<link linkend="functionCODBGETANSWER">codb_get_answer()</link> and 
	<link linkend="functionCODBGETERROR">codb_get_error()</link>.
	
	Query result returned from 
	<link linkend="functionCODBEXECUTE">codb_execute()</link>, you can processed by
	<link linkend="functionCODBGETRESULT">codb_get_result()</link>, 
	<link linkend="functionCODBNUMCOLUMNS">codb_num_columns()</link>,
	<link linkend="functionCODBNUMROWS">codb_num_rows()</link> and 
	<link linkend="functionCODBGETCOLUMN">codb_get_column()</link>.
	
	Besides you can get result as formatted string. Just pass result object in
	<link linkend="classCODBFORMATTER">CODBFormatter()</link> method show.
	
	<command>Using codb.</command>
	
	<pre>codb [options] [database[:depository]]</pre>
	
	On start codb without any parameters it will be work in interactive mode.
	
	codb options:
	<itemizedlist>
	<listitem><command>-c 'command'</command> - Execute query and exit.</listitem>
  	<listitem><command>--hide-titles</command> - Suppress column names.</listitem>
  	<listitem><command>--delim='DELIM'</command> - Set columns delimiter.</listitem>
  	</itemizedlist>
  	
  	Complete list of options is available on run <command>codb -h</command>.
  	
  	Examples:
  	<pre>codb ETC01 -c 'show classes;'</pre>
  	Show all classes in database ETC01.
  	<pre>codb ETC01:ETC0101 -c 'select * from mng_vendor,mng_author;' --delim='|'</pre>
	Show all fields from all objects of classes mng_vendor and mng_author from
	database ETC01 and depository ETC0101 with delimiter '|'.
	
	Note: All data outputs in formatted mode so fields are accompanied
	with spaces to maximum width of element in each column.
  	
  	<command>CQL Commands.</command>
  	
  	Each CODB command should be ended by semicolon. You can write comments
	begin with '#' character and end with line end ('\n'). String are
	delimited by single quote ('). If single quote is part of string it should
	be escaped by backslash (\').
	
	You can pass several commands in -c parameter and through pipe:
  	<pre>echo 'show classes;show indexes;' | codb ETC01</pre>

	Brief CQL Commands Description.
	
	<itemizedlist>
	<listitem><command>help</command> - Help about database commands;</listitem>
	<listitem><command>create</command> - Create metaobject;</listitem>
	<listitem><command>delete</command> - Delete object or metaobject;</listitem>
	<listitem><command>describe</command> - Show class structure;</listitem>
	<listitem><command>drop</command> - Delete metaobject by its name;</listitem>
	<listitem><command>get</command> - Get object from depository;</listitem>
	<listitem><command>metaget</command> - Get metaobject;</listitem>
	<listitem><command>metaput</command> - Create or update metaobject;</listitem>
	<listitem><command>put</command> - Create or update object in depository;</listitem>
	<listitem><command>select</command> - Query object attributes;</listitem>
	<listitem><command>show</command> - Show list of metaobjects;</listitem>
	<listitem><command>use</command> - Open database.</listitem>
	</itemizedlist>
	
	There is command <command>quit</command> - quits the program in interactive
	mode. You can quit from codb to press Esc key.

	Verbose CQL Command Description.
	
	<command>help [&lt;command&gt;]</command>
	Help on command. If 'help' call without command name show all
	available commands.
	
	<command>create <metaclass> (<attr1>=<value1>[,...])</command>
	or <command>create database <db_name> <path>[<description>]</command>
	Create database or metaobject.
	Examples:
	create database EAS01 /var/lib/db 'E/AS Database';
	create attribute (name='phone',type='C',len=20);
	
	Supported metaclasses: 
	<itemizedlist>
	<listitem><command>depository</command> - depository;</listitem>
	<listitem><command>extent</command> - namespace;</listitem>
	<listitem><command>attribute</command> - attribute;</listitem>
	<listitem><command>counter</command> - counter;</listitem>
	<listitem><command>index</command> - index;</listitem>
	<listitem><command>class</command> - class;</listitem>
	<listitem><command>tcolumn</command> - view column;</listitem>
	<listitem><command>tview</command> - view;</listitem>
	<listitem><command>report</command> - report;</listitem>
	<listitem><command>plugin</command> - plugin;</listitem>
	<listitem><command>user</command> - user;</listitem>
	<listitem><command>group</command> - group of users.</listitem>
	</itemizedlist>
	
	<command>delete <id></command>
	Delete object or metaobject by its id.
	
	<command>describe <class_name></command>
	Show class structure by its name.
	
	<command>drop <metaclass> <metaobject_name></command>
	Delete metaobject by its name.
	
	Supported metaclasses: 
	<itemizedlist>
	<listitem><command>depository</command> - depository;</listitem>
	<listitem><command>extent</command> - namespace;</listitem>
	<listitem><command>attribute</command> - attribute;</listitem>
	<listitem><command>counter</command> - counter;</listitem>
	<listitem><command>index</command> - index;</listitem>
	<listitem><command>class</command> - class;</listitem>
	<listitem><command>tcolumn</command> - view column;</listitem>
	<listitem><command>tview</command> - view;</listitem>
	<listitem><command>report</command> - report;</listitem>
	<listitem><command>plugin</command> - plugin;</listitem>
	<listitem><command>user</command> - user;</listitem>
	<listitem><command>group</command> - group of users.</listitem>
	</itemizedlist>
	
	<command>get <id></command>
	Get object content from depository by its id.
	
	<command>metaget <id></command>
	Get metaobject content from dictionary by its id.
	
	<command>metaput (<attr1>=<value1>[, ...])</command>
	Create or change metaobject in dictionary. If 'id' is defined in attributes
	list, exist object will be replaced by new values.
	
	<command>put (<attr1>=<value1>[, ...])</command>
	Create or change metaobject in depository. If 'id' is defined in
	attributes list, exist object will be replaced by new values.
	
	<command>select <attributes> from <class> [where <condition>]</command>
	Get list of attribute values matched condition. 
	
	<attributes> - list of attribute names delimited by comma. Names with
	spaces put in single quotes. You can use * for all attribute names for all
	specified classes.
	
	<class> - list of class names delimited by comma. Names with
	spaces put in single quotes.
	
	<condition> - condition by CLIP rules. There are supported
	operators: '==', '!=', '>', '>=', '<=', '<' and logical operators
	'.not.', '.and.', '.or.'. Value should be put in double quotes and
	there are no spaces between operators.
	
	Example:
	<pre>select id,author_name,email from mng_author where code=="Uri";</pre>
	
	<command>show <metaclass></command>
	Show metaobject list.
	
	Supported metaclasses: 
	<itemizedlist>
	<listitem><command>databases</command> - databases;</listitem> 
	<listitem><command>depositories</command> - depositories;</listitem>
	<listitem><command>extents</command> - namespaces;</listitem>
	<listitem><command>attributes</command> - attributes;</listitem>
	<listitem><command>counters</command> - counters;</listitem>
	<listitem><command>indexes</command> - indices;</listitem>
	<listitem><command>classes</command> - classes;</listitem>
	<listitem><command>tcolumns</command> - view columns;</listitem>
	<listitem><command>tviews</command> - views;</listitem>
	<listitem><command>reports</command> - reports;</listitem>
	<listitem><command>plugins</command> - plugins;</listitem>
	<listitem><command>users</command> - users;</listitem>
	<listitem><command>groups</command> - user groups;</listitem>
	<listitem><command>statistics</command> - total statistics with number metaobjects in each metaclass.</listitem>
	</itemizedlist>
	
	<command>use <db> [<depository>]</command>
	Change current work database and depository.

$LANG_RU$
	 codb-query       
	 CODB       
	<link linkend="classCODBDEPOSITORY">CODBDEPOSITORY</link>, 
	<link linkend="classCODBDICTIONARY">CODBDICTIONARY</link>, 
	<link linkend="classCODBLIST">CODBLIST</link> 
	<link linkend="classCODBIDLIST">CODBIDLIST</link>.
	
	    CQL ( SQL,   CODB). 
	     ,   
	  codb.
	
	<command>  .</command>
	
	   codb-query      
	   .    '-lcodb-query'.
	
	      :
<pre>db := codb_connect() //    
e := codb_get_error( db ) //  
if e != NIL
	?? "ERROR codb_connect(): " + e + chr(10)
	return 1
endif

//  
oRes := codb_execute( db, 'show databases' )

//  
aResult := codb_get_result( oRes )

codb_close( db ) //   </pre>
	
	      
	<link linkend="functionCODBCONNECT">codb_connect()</link>.   
	   .      
	<link linkend="functionCODBCLOSE">codb_close()</link>.
	
	      :
	<link linkend="functionCODBEXECUTE">codb_execute()</link>, 
	<link linkend="functionCODBGETMETAOBJECT">codb_get_metaobject()</link>,
	<link linkend="functionCODBGETOBJECT">codb_get_object()</link>,
	<link linkend="functionCODBPUTMETAOBJECT">codb_put_metaobject()</link>,
	<link linkend="functionCODBPUTOBJECT">codb_put_object()</link>.
	
	    ,  
	<link linkend="functionCODBEXECUTE">codb_execute()</link>  , 
	      
	<link linkend="functionCODBGETRESULT">codb_get_result()</link>, 
	    . 
	
	     
	<link linkend="functionCODBGETANSWER">codb_get_answer()</link>  
	<link linkend="functionCODBGETERROR">codb_get_error()</link>.
	
	 ,    
	<link linkend="functionCODBEXECUTE">codb_execute()</link>,  ,
	  
	<link linkend="functionCODBGETRESULT">codb_get_result()</link>, 
	<link linkend="functionCODBNUMCOLUMNS">codb_num_columns()</link>,
	<link linkend="functionCODBNUMROWS">codb_num_rows()</link>  
	<link linkend="functionCODBGETCOLUMN">codb_get_column()</link>.
	
	 ,      .  
	     'show'   
	<link linkend="classCODBFORMATTER">CODBFormatter()</link>.
	
	<command>  codb.</command>
	
	<pre>codb [] [[:]]</pre>
	  codb  ,      .
	
	 codb:
	<itemizedlist>
	<listitem><command>-c ''</command> -    .</listitem>
  	<listitem><command>--hide-titles</command> -    .</listitem>
  	<listitem><command>--delim='DELIM'</command> -    .</listitem>
  	</itemizedlist>
  	
  	    ,  <command>codb -h</command>.
  	
  	:
  	<pre>codb ETC01 -c 'show classes;'</pre>
  	       ETC01.
  	<pre>codb ETC01:ETC0101 -c 'select * from mng_vendor,mng_author;' --delim='|'</pre>
	      mng_vendor  mng_author   
	 ETC01   ETC0101   '|'.
	
	:     ,     
	    .
  	
  	<command> CQL.</command>
  	
  	      .  
	 ,    '#'   
	( '\n').     ('). 
	         (\').	
	
	         -c,   
	:
  	<pre>echo 'show classes;show indexes;' | codb ETC01</pre>

	   CQL.
	
	<itemizedlist>
	<listitem><command>help</command> -   ;</listitem>
	<listitem><command>create</command> -     ;</listitem>
	<listitem><command>delete</command> -    ;</listitem>
	<listitem><command>describe</command> -   ;</listitem>
	<listitem><command>drop</command> -     ;</listitem>
	<listitem><command>get</command> -     ;</listitem>
	<listitem><command>metaget</command> -  ;</listitem>
	<listitem><command>metaput</command> -    ;</listitem>
	<listitem><command>put</command> -      ;</listitem>
	<listitem><command>select</command> -    ;</listitem>
	<listitem><command>show</command> -   ;</listitem>
	<listitem><command>use</command> -      .</listitem>
	</itemizedlist>
	
	     <command>quit</command> -  
	.      ,   Esc.

	   CQL:
	
	<command>help [<>]</command>
	  .    ,  
	     .
	
	<command>create <> (<1>=<1>[, ...])</command>
	 <command>create database <> <> [<>]</command>
	    .
	:
	create database EAS01 /var/lib/db '  E/AS';
	create attribute (name='phone',type='C',len=20);
	
	  : 
	<itemizedlist>
	<listitem><command>depository</command> - ;</listitem>
	<listitem><command>extent</command> -  ͣ;</listitem>
	<listitem><command>attribute</command> - ;</listitem>
	<listitem><command>counter</command> - ޣ;</listitem>
	<listitem><command>index</command> - ;</listitem>
	<listitem><command>class</command> - ;</listitem>
	<listitem><command>tcolumn</command> -  ;</listitem>
	<listitem><command>tview</command> - ;</listitem>
	<listitem><command>report</command> - ޣ;</listitem>
	<listitem><command>plugin</command> -  ;</listitem>
	<listitem><command>user</command> - ;</listitem>
	<listitem><command>group</command> -  .</listitem>
	</itemizedlist>
	
	<command>delete <id></command>
	      .
	
	<command>describe <_></command>
	     .
	
	<command>drop <> <_></command>
	    .
	
	  : 
	<itemizedlist>
	<listitem><command>depository</command> - ;</listitem>
	<listitem><command>extent</command> -  ͣ;</listitem>
	<listitem><command>attribute</command> - ;</listitem>
	<listitem><command>counter</command> - ޣ;</listitem>
	<listitem><command>index</command> - ;</listitem>
	<listitem><command>class</command> - ;</listitem>
	<listitem><command>tcolumn</command> -  ;</listitem>
	<listitem><command>tview</command> - ;</listitem>
	<listitem><command>report</command> - ޣ;</listitem>
	<listitem><command>plugin</command> -  ;</listitem>
	<listitem><command>user</command> - ;</listitem>
	<listitem><command>group</command> -  .</listitem>
	</itemizedlist>
	
	<command>get <id></command>
	       .
	
	<command>metaget <id></command>
	      .
	
	<command>metaput (<1>=<1>[, ...])</command>
	     .     
	 (id),  Σ  .
	
	<command>put (<1>=<1>[, ...])</command>
	     .     
	 (id),  Σ  .
	
	<command>select <> from <> [where <>]</command>
	   ,   . 
	
	<> -  , ̣ .    
	  .    *      
	 .
	
	<> -  ͣ , ̣ .    
	   .
	
	<> -    CLIP.   
	 '==', '!=', '>', '>=', '<=', '<'   
	'.not.', '.and.', '.or.'.       ("),
	      .
	
	:
	<pre>select id,author_name,email from mng_author where code=="Uri";</pre>
	
	<command>show <></command>
	  .
	
	  : 
	<itemizedlist>
	<listitem><command>databases</command> -  ;</listitem> 
	<listitem><command>depositories</command> - ;</listitem>
	<listitem><command>extents</command> -  ͣ;</listitem>
	<listitem><command>attributes</command> - ;</listitem>
	<listitem><command>counters</command> - ޣ;</listitem>
	<listitem><command>indexes</command> - ;</listitem>
	<listitem><command>classes</command> - ;</listitem>
	<listitem><command>tcolumns</command> -  ;</listitem>
	<listitem><command>tviews</command> - ;</listitem>
	<listitem><command>reports</command> - ޣ;</listitem>
	<listitem><command>plugins</command> -  ;</listitem>
	<listitem><command>users</command> - ;</listitem>
	<listitem><command>groups</command> -  ;</listitem>
	<listitem><command>statistics</command> -     .</listitem>
	</itemizedlist>
	
	<command>use <_> [<>]</command>
	     .
