<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<chapter label="appendixa.xml" id="appendixa">
  <abstract>
    <para>This reference chapter contains information that needs to be found quickly
    and accurately without specific guide lines to the topics in question.  This
    chapter contains the SQL Grammar, listings of all system errors messages, release
    notes for the product, how to get support on the product and a list of the
    system tables and there schema definitions.</para>
  </abstract>

<title>Appendix</title>

 &yacgrammar;
 &errors;
 
<sect1 id="signalsandexitcodes"><title>Signals and Exit codes</title>
<para>This section presents the most important exit codes and signals for Virtuoso on Unix/Linux.</para>
  <sect2 id="signalsandexitcodesc"><title>Exit codes</title>
<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0">
    <title>Exit codes</title>
    <tgroup align="char" charoff="50" char="." cols="3">
    <colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
    <thead>
      <row>
        <entry>Exit Code</entry>
        <entry>Category</entry>
        <entry>Comment</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>-1</entry>
        <entry>FATAL</entry>
        <entry>Unrecoverable condition detected like disk or memory full</entry>        
      </row>
      <row>
        <entry>0</entry>
        <entry>NORMAL</entry>
        <entry>Normal exit with success</entry>        
      </row>
      <row>
        <entry>1</entry>
        <entry>WARNING</entry>
        <entry>Some kind of failure at startup/shutdown, typically shown with a reason for this error</entry>        
      </row>
      <row>
        <entry>&gt;1</entry>
        <entry>UNKNOWN</entry>
        <entry>Not used under normal operations</entry>        
      </row>
      <row>
        <entry>&gt;128</entry>
        <entry>SIGNAL</entry>
        <entry>Virtuoso was killed by a signal it could not process. (error code = signal + 128)</entry>        
      </row>      
    </tbody>
  </tgroup>
</table>  
  </sect2>
  <sect2 id="signalsandexitcodess"><title>Signals</title>
<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0">
    <title>Signals</title>
    <tgroup align="char" charoff="50" char="." cols="4">
    <colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
    <thead>
      <row>
        <entry>Signal</entry>
        <entry>Name</entry>
        <entry>Category</entry>
        <entry>Comment</entry>        
      </row>
    </thead>
    <tbody>
      <row>
        <entry>1</entry>
        <entry>SIGHUP</entry>
        <entry>NORMAL</entry>        
        <entry>Initiate quick shutdown when shell exits while running virtuoso in foreground mode</entry>           
      </row>
      <row>
        <entry>2</entry>
        <entry>SIGINT</entry>
        <entry>NORMAL</entry>        
        <entry>User pressed CTRL-C on Virtuoso running in foreground mode to initiate normal shutdown</entry>           
      </row>
      <row>
        <entry>3</entry>
        <entry>SIGQUIT</entry>
        <entry>NORMAL</entry>   
        <entry>User pressed CTRL-\ on Virtuoso running in foreground mode to initiate quick shutdown</entry>                
      </row>
      <row>
        <entry>4</entry>
        <entry>SIGILL</entry>
        <entry>FAULT</entry> 
        <entry>Illegal instruction resulting in a program crash</entry>                  
      </row>
      <row>
        <entry>7</entry>
        <entry>SIGBUS</entry>
        <entry>FAULT</entry>      
        <entry>Misaligned mem read/write resulting in a program crash</entry>             
      </row>
      <row>
        <entry>8</entry>
        <entry>SIGFPE</entry>
        <entry>FAULT</entry>   
        <entry>Divide by 0 or other arithmetical error</entry>                
      </row>
      <row>
        <entry>9</entry>
        <entry>SIGKILL</entry>
        <entry>SPECIAL</entry>   
        <entry>Terminate Virtuoso without flushing dirty pages etc. This signal should NOT be used under normal operations.</entry>                
      </row>
      <row>
        <entry>11</entry>
        <entry>SIGSEGV</entry>
        <entry>FAULT</entry>     
        <entry>Buffer/stack overrun resulting in a program crash</entry>              
      </row>
      <row>
        <entry>13</entry>
        <entry>SIGPIPE</entry>
        <entry>IGNORED</entry>   
        <entry>Other side of a pipe was killed while this side tried to write data to it</entry>                
      </row>
      <row>
        <entry>15</entry>
        <entry>SIGTERM</entry>
        <entry>NORMAL</entry>   
        <entry>Initiate quick shutdown</entry>                
      </row>                                                      
    </tbody>
  </tgroup>
</table>  
<para>Signals that are marked as <emphasis>NORMAL</emphasis> indicate that these signals can be 
sent by root or the owner of the virtuoso process to shutdown Virtuoso. The <emphasis>SIGINT</emphasis> and 
<emphasis>SIGQUIT</emphasis> signals also work when Virtuoso is running in background mode and can be used 
in shell scripts.</para>
<para>Signals that are marked as <emphasis>FAULT</emphasis> indicate an abnormal condition which should be 
checked. If enabled (e.g. with ulimit -c unlimited), the operating system can write a core dump allowing 
post-mortem debugging if the Virtuoso executable was compiled with debugging symbols.</para>
<para>Signals that are marked as <emphasis>IGNORED</emphasis> are handled inside Virtuoso.</para>
<para>The <emphasis>SIGTERM</emphasis> signal is mostly used by rc.d type shell scripts on Unix/Linux which 
are called during shutdown, but can also be used inside shell scripts.</para>
<para>The <emphasis>SIGKILL</emphasis> signal should only be used as a last resort when all other efforts 
to stop Virtuoso have failed.</para>
    <sect3 id="signalsandexitcodessquicksh"><title>Quick shutdown</title>
    <para>In quick shutdown mode, Virtuoso will only flush dirty disk buffers, close transaction log and 
    	database files and exit to the operating system. Since Virtuoso does not perform a checkpoint, the 
    	next startup will take extra time as Virtuoso first needs to perform a rollback and a checkpoint 
    	before it can resume operation. The <emphasis>SIGTERM</emphasis> signal mostly used by rc.d type 
    	scripts on Unix/Linux which are called during shutdown as such instances it is better to quickly 
    	finish operations and delay the checkpoint until the next boot.</para>
    </sect3>    
    <sect3 id="signalsandexitcodessquicknsh"><title>Normal shutdown</title>
    <para>In normal shutdown mode, Virtuoso will do first do a full checkpoint, then flush dirty disk 
    	buffers, close transaction log and database files before exiting to the operating system. Depending 
    	on the size of the transaction log this can take some time. The <emphasis>SIGINT</emphasis> signal 
    	can be used in stop scripts to cleanly shutdown the database by the dba or by root.</para>
    <para>Note that in all cases signals can only be sent by the kernel, the root user or the uid of 
    	the person who started Virtuoso. Anyone else that wants to shutdown the Virtuoso instance 
    	should use the isql program to connect to Virtuoso and run the 'shutdown' command.</para>    
    </sect3>    
  </sect2>
</sect1>
 
 &relnotes;
 &support;
 &systemtables;
 <!--&migrate27to30;-->

<sect1 id="apndxregexp"><title>Basic Syntax of Regular Expressions</title>

<para>The two special symbols: <computeroutput>'^'</computeroutput> and 
<computeroutput>'$'</computeroutput> indicate the <emphasis>start</emphasis> 
and the <emphasis>end</emphasis> of a string respectively, like so:</para>

<simplelist>
  <member><computeroutput>^The</computeroutput>: matches any string 
  that starts with The;</member>
  <member><computeroutput>of despair$</computeroutput>: matches a 
  string that ends in the substring of despair;</member>
  <member><computeroutput>^abc$</computeroutput>: a string that 
  starts and ends with abc -- that could only be abc itself!</member>
  <member><computeroutput>notice</computeroutput>: a string that 
  has the text notice in it.</member>
</simplelist>

<para>Without either of the above special character you are allowing the pattern 
to occur anywhere inside the string.</para>

<para>The symbols <computeroutput>'*'</computeroutput>, <computeroutput>'+'</computeroutput>, 
and <computeroutput>'?'</computeroutput> denote the number of times a character 
or a sequence of characters may occur.  What they mean is: zero or more, one or 
more, and zero or one.  Here are some examples:</para>

<simplelist>
  <member><computeroutput>ab*</computeroutput>: matches a string 
  that has an <emphasis>a</emphasis> followed by zero or more 
  <emphasis>b</emphasis>'s (a, ab, abbb, etc.);</member>
  <member><computeroutput>ab+</computeroutput>: same, but there is 
  at least one <emphasis>b</emphasis> (ab, abbb, etc.);</member>
  <member><computeroutput>ab?</computeroutput>: there might be a 
  <emphasis>b</emphasis> or not;</member> 
  <member><computeroutput>a?b+$</computeroutput>: a possible <emphasis>a</emphasis> 
  followed by one or more <emphasis>b</emphasis>'s ending a string.</member>
</simplelist>

<para>You can also use <emphasis>bounds</emphasis>, which come inside braces 
and indicate ranges in the number of occurrences: </para>

<simplelist>
  <member><computeroutput>ab{2}</computeroutput>: matches a string that has an 
  <emphasis>a</emphasis> followed by exactly two <emphasis>b</emphasis>'s 
  (abb);</member>
  <member><computeroutput>ab{2,}</computeroutput>: there are at least two 
  <emphasis>b</emphasis>'s (abb, abbbb, etc.);</member>
  <member><computeroutput>ab{3,5}</computeroutput>: from three to five 
  <emphasis>b</emphasis>'s (abbb, abbbb, or abbbbb).</member>
</simplelist>

<para>Note, that you must always specify the first number of a range 
(i.e, <computeroutput>{0,2}</computeroutput>, not <computeroutput>{,2}</computeroutput>).  
Also, as you may have noticed, the symbols '*', '+', and '?' have the same effect 
as using the bounds <computeroutput>{0,}</computeroutput>, 
<computeroutput>{1,}</computeroutput>, and <computeroutput>{0,1}</computeroutput>, 
respectively.</para>

<para>Now, to quantify a sequence of characters, put them inside parentheses:</para>

<simplelist>
  <member><computeroutput>a(bc)*</computeroutput>: matches a string that has 
  an <emphasis>a</emphasis> followed by zero or more copies of the sequence bc;</member>
  <member><computeroutput>a(bc){1,5}</computeroutput>: one through five copies of bc.</member>
</simplelist>

<para>There's also the '|' symbol, which works as an OR operator:</para>

<simplelist>
  <member><computeroutput>hi|hello</computeroutput>: matches a string that has 
  either hi or hello in it;</member>
  <member><computeroutput>(b|cd)ef</computeroutput>: a string that has either 
  bef or cdef;</member>
  <member><computeroutput>(a|b)*c</computeroutput>: a string that has a 
  sequence of alternating <emphasis>a</emphasis>'s and <emphasis>b</emphasis>'s 
  ending in a <emphasis>c</emphasis>;</member>
</simplelist>

<para>A period ('.') stands for any single character:</para>

<simplelist>
  <member><computeroutput>a.[0-9]</computeroutput>: matches a string that has 
  an <emphasis>a</emphasis> followed by one character and a digit;</member>
  <member><computeroutput>^.{3}$</computeroutput>: a string with exactly 3 characters.</member>
</simplelist>

<para><emphasis>Bracket expressions</emphasis> specify which characters are 
allowed in a single position of a string: </para>

<simplelist>
  <member><computeroutput>[ab]</computeroutput>: matches a string that has 
  either an <emphasis>a</emphasis> or a <emphasis>b</emphasis>
    (that's the same as <computeroutput>a|b</computeroutput>);</member>
  <member><computeroutput>[a-d]</computeroutput>: a string that has lowercase 
  letters 'a' through 'd' (that's equal to <computeroutput>a|b|c|d</computeroutput> 
  and even <computeroutput>[abcd]</computeroutput>);</member>
  <member><computeroutput>^[a-zA-Z]</computeroutput>: a string that starts with a letter;</member>
  <member><computeroutput>[0-9]%</computeroutput>: a string that has a single 
  digit before a percent sign;</member>
  <member><computeroutput>,[a-zA-Z0-9]$</computeroutput>: a string that ends in 
  a comma followed by an alphanumeric character.</member>
</simplelist>

<para>You can also list the characters that do NOT want -- just use a '^' as 
the first symbol in a bracketed expression (i.e., 
<computeroutput>%[^a-zA-Z]%</computeroutput> matches a string with a character 
that is not a letter between two percent signs).</para>

<para>Do not forget that bracket expressions are an exception to that 
rule--inside them, all special characters, including the backslash ('\'), 
lose their special powers (i.e., <computeroutput>[*\+?{}.]</computeroutput> 
matches exactly any of the characters inside the brackets).  
To include a literal ']' in the list, make it the first character 
(following a possible '^'). To include a literal '-', make it the first or last 
character, or the second endpoint of a range.</para>

</sect1>

<sect1 id="apndxclientcompilance"><title>Server &amp; client versions compatibility</title>
    <para>
	The RPC protocol has changed between 2.7 and 3.0 versions.  Thus, not all 
	clients can connect to all servers.  For best results, the version should be identical on 
	both ends of ODBC and JDBC connections.  However, the following table shows which 
	combinations should generally be successful.
    </para>
      <table>
	<tgroup cols="9">
	  <tbody>
	      <row>
		  <entry>Driver/Server</entry>
		  <entry>4.0</entry>
		  <entry>3.5</entry>
		  <entry>3.2</entry>
		  <entry>3.1</entry>
		  <entry>3.0</entry>
		  <entry>2.7</entry>
		  <entry>2.5</entry>
		  <entry>2.1</entry>
	      </row>
	      <row>
		  <entry>4.0</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
	      </row>
	      <row>
		  <entry>3.5</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
	      </row>
	      <row>
		  <entry>3.2</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
	      </row>
	      <row>
		  <entry>3.1</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
	      </row>
	      <row>
		  <entry>3.0</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
	      </row>
	      <row>
		  <entry>2.7</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
	      </row>
	      <row>
		  <entry>2.5</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
	      </row>
	      <row>
		  <entry>2.1</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>N</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
		  <entry>Y</entry>
	      </row>
	  </tbody>
	</tgroup>
      </table>
</sect1>

</chapter>