Commit fa1b7f83 authored by Olivier Courtin's avatar Olivier Courtin

Split reference.xml on several sub files (upon sect1). Use entity to avoid...

Split reference.xml on several sub files (upon sect1). Use entity to avoid redundant compliant/support text (SFS, SQL/MM, Z/M dimensions, Curve support)

git-svn-id: http://svn.osgeo.org/postgis/[email protected] b70326c6-7e19-0410-871a-916f4a2858ee
parent ac4e5e18
......@@ -9,13 +9,62 @@
<!ENTITY last_proj_release_version "4.6.1">
<!ENTITY last_geos_release_version "3.0.3">
<!ENTITY sfs_compliant
"<inlinemediaobject>
<imageobject><imagedata fileref='images/check.png' /></imageobject>
</inlinemediaobject>
This method implements the <ulink
url='http://www.opengeospatial.org/standards/sfs'>OpenGIS Simple Features
Implementation Specification for SQL 1.1.</ulink>">
<!ENTITY sqlmm_compliant
"<inlinemediaobject>
<imageobject>
<imagedata fileref='images/check.png' />
</imageobject>
</inlinemediaobject> This method implements the SQL/MM specification.">
<!ENTITY curve_support
"<inlinemediaobject>
<imageobject><imagedata fileref='images/check.png' /></imageobject>
</inlinemediaobject>
This method supports Circular Strings and Curves">
<!ENTITY Z_support
"<inlinemediaobject>
<imageobject>
<imagedata fileref='images/check.png' />
</imageobject>
</inlinemediaobject>
This function supports 3d and will not drop the z-index.">
<!ENTITY M_support
"<inlinemediaobject>
<imageobject>
<imagedata fileref='images/check.png' />
</imageobject>
</inlinemediaobject>
This function supports M coordinates.">
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY installation SYSTEM "installation.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY using_postgis_dataman SYSTEM "using_postgis_dataman.xml">
<!ENTITY using_postgis_app SYSTEM "using_postgis_app.xml">
<!ENTITY performance_tips SYSTEM "performance_tips.xml">
<!ENTITY reference SYSTEM "reference.xml">
<!ENTITY reference_management SYSTEM "reference_management.xml">
<!ENTITY reference_constructor SYSTEM "reference_constructor.xml">
<!ENTITY reference_accessor SYSTEM "reference_accessor.xml">
<!ENTITY reference_editor SYSTEM "reference_editor.xml">
<!ENTITY reference_output SYSTEM "reference_output.xml">
<!ENTITY reference_operator SYSTEM "reference_operator.xml">
<!ENTITY reference_measure SYSTEM "reference_measure.xml">
<!ENTITY reference_processing SYSTEM "reference_processing.xml">
<!ENTITY reference_lrs SYSTEM "reference_lrs.xml">
<!ENTITY reference_transaction SYSTEM "reference_transaction.xml">
<!ENTITY reference_misc SYSTEM "reference_misc.xml">
<!ENTITY reference_exception SYSTEM "reference_exception.xml">
<!ENTITY postgis_aggs_mm SYSTEM "postgis_aggs_mm.xml">
<!ENTITY reporting SYSTEM "reporting.xml">
<!ENTITY release_notes SYSTEM "release_notes.xml">
......@@ -55,9 +104,39 @@
&using_postgis_dataman;
&using_postgis_app;
&performance_tips;
&reference;
<chapter>
<title>PostGIS Reference</title>
<para>The functions given below are the ones which a user of PostGIS is
likely to need. There are other functions which are required support
functions to the PostGIS objects which are not of use to a general
user.</para>
<note>
<para>PostGIS has begun a transition from the existing naming convention
to an SQL-MM-centric convention. As a result, most of the functions that
you know and love have been renamed using the standard spatial type (ST)
prefix. Previous functions are still available, though are not listed in
this document where updated functions are equivalent. These will be
deprecated in a future release.</para>
</note>
&reference_management;
&reference_constructor;
&reference_accessor;
&reference_editor;
&reference_output;
&reference_operator;
&reference_measure;
&reference_processing;
&reference_lrs;
&reference_transaction;
&reference_misc;
&reference_exception;
</chapter>
&postgis_aggs_mm;
&reporting;
&release_notes;
</book>
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Exceptional_Functions">
<title>Exceptional Functions</title>
<para>These functions are rarely used functions that should only be used if your data is corrupted in someway. They are used for troubleshooting corruption
and also fixing things that should under normal circumstances, never happen.</para>
<refentry id="PostGIS_AddBBox">
<refnamediv>
<refname>PostGIS_AddBBox</refname>
<refpurpose>Add bounding box to the geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>PostGIS_AddBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Add bounding box to the geometry. This would make bounding
box based queries faster, but will increase the size of the
geometry.</para>
<note>
<para>Bounding boxes are automatically added to geometries so in general this is not needed
unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes. Then you need to drop the old and readd.</para>
</note>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>UPDATE sometable
SET the_geom = ST_AddBBox(the_geom)
WHERE ST_HasBBox(the_geom) = false;</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_DropBBox" />, <xref linkend="PostGIS_HasBBox" /></para>
</refsection>
</refentry>
<refentry id="PostGIS_DropBBox">
<refnamediv>
<refname>PostGIS_DropBBox</refname>
<refpurpose>Drop the bounding box cache from the geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>PostGIS_DropBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Drop the bounding box cache from the geometry. This reduces
geometry size, but makes bounding-box based queries slower. It is also used to drop a corrupt bounding box. A tale-tell sign of a corrupt cached bounding box
is when your ST_Intersects and other relation queries leave out geometries that rightfully should return true.</para>
<note>
<para>Bounding boxes are automatically added to geometries and improve speed of queries so in general this is not needed
unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes.
Then you need to drop the old and readd. This kind of corruption has been observed in 8.3-8.3.6 series whereby cached bboxes were not always recalculated when a geometry changed and upgrading to a newer version without a dump reload will not
correct already corrupted boxes. So one can manually correct using below and readd the bbox or do a dump reload.</para>
</note>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>--This example drops bounding boxes where the cached box is not correct
--The force to ST_AsBinary before applying Box2D forces a recalculation of the box, and Box2D applied to the table geometry always
-- returns the cached bounding box.
UPDATE sometable
SET the_geom = PostGIS_DropBBox(the_geom)
WHERE Not (Box2D(ST_AsBinary(the_geom)) = Box2D(the_geom));
UPDATE sometable
SET the_geom = PostGIS_AddBBox(the_geom)
WHERE Not PostGIS_HasBBOX(the_geom);
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_HasBBox" />, <xref linkend="Box2D" /></para>
</refsection>
</refentry>
<refentry id="PostGIS_HasBBox">
<refnamediv>
<refname>PostGIS_HasBBox</refname>
<refpurpose>Returns TRUE if the bbox of this geometry is cached, FALSE otherwise.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>PostGIS_HasBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns TRUE if the bbox of this geometry is cached, FALSE
otherwise. Use <xref linkend="PostGIS_AddBBox" /> and <xref linkend="PostGIS_DropBBox" /> to control caching.</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT the_geom
FROM sometable WHERE PostGIS_HasBBox(the_geom) = false;</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_DropBBox" /></para>
</refsection>
</refentry>
</sect1>
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Long_Transactions_Support">
<title>Long Transactions Support</title>
<para>This module and associated pl/pgsql functions have been
implemented to provide long locking support required by <ulink
url="http://portal.opengeospatial.org/files/index.php?artifact_id=7176">Web Feature Service</ulink> specification.</para>
<note>
<para>Users must use <ulink
url="http://www.postgresql.org/docs/8.3/static/transaction-iso.html">serializable
transaction level</ulink> otherwise locking mechanism would
break.</para>
</note>
<refentry id="AddAuth">
<refnamediv>
<refname>AddAuth</refname>
<refpurpose>Add an authorization token to be used in current transaction.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>AddAuth</function></funcdef>
<paramdef><type>text </type> <parameter>auth_token</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Add an authorization token to be used in current transaction.</para>
<para>Creates/adds to a temp table called temp_lock_have_table the current transaction identifier
and authorization token key.</para>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT LockRow('towns', '353', 'priscilla');
BEGIN TRANSACTION;
SELECT AddAuth('joey');
UPDATE towns SET the_geom = ST_Translate(the_geom,2,2) WHERE gid = 353;
COMMIT;
---Error--
ERROR: UPDATE where "gid" = '353' requires authorization 'priscilla'
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="LockRow" /></para>
</refsection>
</refentry>
<refentry id="CheckAuth">
<refnamediv>
<refname>CheckAuth</refname>
<refpurpose>Creates trigger on a table to prevent/allow updates and deletes of rows based on authorization token.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>CheckAuth</function></funcdef>
<paramdef><type>text </type> <parameter>a_schema_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_key_column_name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>CheckAuth</function></funcdef>
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_key_column_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Creates trigger on a table to prevent/allow updates and deletes of rows based on authorization token. Identify rows using &lt;rowid_col&gt; column.</para>
<para>If a_schema_name is not passed in, then searches for table in current schema.</para>
<note><para>If an authorization trigger already exists on this table function errors.</para>
<para>If Transaction support is not enabled, function throws an exception.</para>
</note>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT CheckAuth('public', 'towns', 'gid');
result
------
0
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="EnableLongTransactions" /></para>
</refsection>
</refentry>
<refentry id="DisableLongTransactions">
<refnamediv>
<refname>DisableLongTransactions</refname>
<refpurpose>Disable long transaction support. This function removes the
long transaction support metadata tables, and drops all triggers
attached to lock-checked tables.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>DisableLongTransactions</function></funcdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Disable long transaction support. This function removes the
long transaction support metadata tables, and drops all triggers
attached to lock-checked tables.</para>
<para>Drops meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname>
and all triggers called <varname>checkauthtrigger</varname></para>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT DisableLongTransactions();
--result--
Long transactions support disabled
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="EnableLongTransactions" /></para>
</refsection>
</refentry>
<refentry id="EnableLongTransactions">
<refnamediv>
<refname>EnableLongTransactions</refname>
<refpurpose>Enable long transaction support. This function creates the
required metadata tables, needs to be called once before using the
other functions in this section. Calling it twice is
harmless.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>EnableLongTransactions</function></funcdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Enable long transaction support. This function creates the
required metadata tables, needs to be called once before using the
other functions in this section. Calling it twice is
harmless.</para>
<para>Creates a meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname></para>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT EnableLongTransactions();
--result--
Long transactions support enabled
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="DisableLongTransactions" /></para>
</refsection>
</refentry>
<refentry id="LockRow">
<refnamediv>
<refname>LockRow</refname>
<refpurpose>Set lock/authorization for specific row in table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>LockRow</function></funcdef>
<paramdef><type>text </type> <parameter>a_schema_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
<paramdef><type>timestamp</type> <parameter>expire_dt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>LockRow</function></funcdef>
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
<paramdef><type>timestamp</type> <parameter>expire_dt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>integer <function>LockRow</function></funcdef>
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Set lock/authorization for specific row in table
&lt;authid&gt; is a text value, &lt;expires&gt; is a timestamp
defaulting to now()+1hour. Returns 1 if lock has been assigned, 0
otherwise (already locked by other auth)</para>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT LockRow('public', 'towns', '2', 'joey');
LockRow
-------
1
--Joey has already locked the record and Priscilla is out of luck
SELECT LockRow('public', 'towns', '2', 'priscilla');
LockRow
-------
0
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="UnlockRows" /></para>
</refsection>
</refentry>
<refentry id="UnlockRows">
<refnamediv>
<refname>UnlockRows</refname>
<refpurpose>Remove all locks held by specified authorization id. Returns
the number of locks released.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>UnlockRows</function></funcdef>
<paramdef><type>text </type> <parameter>auth_token</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Remove all locks held by specified authorization id. Returns
the number of locks released.</para>
<para>Availability: 1.1.3</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT LockRow('towns', '353', 'priscilla');
SELECT LockRow('towns', '2', 'priscilla');
SELECT UnLockRows('priscilla');
UnLockRows
------------
2
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="LockRow" /></para>
</refsection>
</refentry>
</sect1>
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment