From eca636bec5875f630522861e168fac8fb952025a Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Mon, 14 Jun 1999 07:36:12 +0000 Subject: [PATCH] Minor updates for release. --- doc/src/sgml/datatype.sgml | 2 +- doc/src/sgml/docguide.sgml | 6 +- doc/src/sgml/func.sgml | 1362 ++++++++++++++++++------------------ doc/src/sgml/lobj.sgml | 285 ++++---- doc/src/sgml/release.sgml | 14 +- 5 files changed, 851 insertions(+), 818 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 16a0074010..8425bb4fa6 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ - Data Types + Data Types diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 1341f1818b..bf6b2d76f3 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -4,6 +4,10 @@ Documentation Guide Thomas Lockhart $Log: docguide.sgml,v $ +Revision 1.15 1999/05/27 15:49:07 thomas +Markup fixes. +Update for v6.5 release. + Revision 1.14 1999/01/07 03:01:27 thomas Fix column formatting for a table. No content changes. @@ -171,7 +175,7 @@ Include working list of all documentation sources, with current status James Clark's jade and Norm Walsh's - Modular DocBook Stylesheets. + Modular DocBook Stylesheets. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0c27254c22..492859f56b 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,17 +1,18 @@ - - Functions + + Functions - - - Describes the built-in functions available in Postgres. - - + + + Describes the built-in functions available + in Postgres. + + - + Many data types have functions available for conversion to other related types. In addition, there are some type-specific functions. Some functions are also available through operators and may be documented as operators only. - + SQL Functions @@ -24,37 +25,37 @@ - - SQL Functions - - - - Function - Returns - Description - Example - - - - - COALESCE(list) - non-NULL - return first non-NULL value in list - COALESCE(c1, c2 + 5, 0) - - - IFNULL(input, class="parameter">non-NULL substitute) - non-NULL - return second argument if first is NULL - IFNULL(c1, 'N/A') - - - CASE(WHEN expr THEN expr [...] ELSE expr ) - expr - return expression for first true clause - CASE(WHEN c1 = 1 THEN 'match' ELSE 'no match') - +
+ SQL Functions + + + + Function + Returns + Description + Example + + + + + COALESCE(list) + non-NULL + return first non-NULL value in list + COALESCE(r"le>, c2 + 5, 0) + + + IFNULL(input,non-NULL substitute) + non-NULL + return second argument if first is NULL + IFNULL(c1, 'N/A') + + + CASE WHEN expr THEN expr [...] ELSE expr END + expr + return expression for first true clause + CASE WHEN c1 = 1 THEN 'match' ELSE 'no match' END +
@@ -64,237 +65,237 @@ Mathematical Functions - - - Mathematical Functions - - - - Function - Returns - Description - Example - - - - - dexp(float8) - float8 - raise e to the specified exponent - dexp(2.0) - - - dpow(float8,float8) - float8 - raise a number to the specified exponent - dpow(2.0, 16.0) - - - float(int) - float8 - convert integer to floating point - float(2) - - - float4(int) - float4 - convert integer to floating point - float4(2) - - - integer(float) - int - convert floating point to integer - integer(2.0) - - - -
- + + + Mathematical Functions + + + + Function + Returns + Description + Example + + + + + dexp(float8) + float8 + raise e to the specified exponent + dexp(2.0) + + + dpow(float8,float8) + float8 + raise a number to the specified exponent + dpow(2.0, 16.0) + + + float(int) + float8 + convert integer to floating point + float(2) + + + float4(int) + float4 + convert integer to floating point + float4(2) + + + integer(float) + int + convert floating point to integer + integer(2.0) + + + +
+ String Functions - + SQL92 defines string functions with specific syntax. Some of these - are implemented using other Postgres functions. + are implemented using other Postgres functions. The supported string types for SQL92 are char, varchar, and text. - + - - - <Acronym>SQL92</Acronym> String Functions - - - - Function - Returns - Description - Example - - - - - char_length(string) - int4 - length of string - char_length('jose') - - - character_length(string) - int4 - length of string - char_length('jose') - - - lower(string) - string - convert string to lower case - lower('TOM') - - - octet_length(string) - int4 - storage length of string - octet_length('jose') - - - position(string in string) - int4 - location of specified substring - position('o' in 'Tom') - - - substring(string [from int] [for int]) - string - extract specified substring - substring('Tom' from 2 for 2) - - - trim([leading|trailing|both] [string] from string) - string - trim characters from string - trim(both 'x' from 'xTomx') - - - upper(text) - text - convert text to upper case - upper('tom') - - - -
- + + + <acronym>SQL92</acronym> String Functions + + + + Function + Returns + Description + Example + + + + + char_length(string) + int4 + length of string + char_length('jose') + + + character_length(string) + int4 + length of string + char_length('jose') + + + lower(string) + string + convert string to lower case + lower('TOM') + + + octet_length(string) + int4 + storage length of string + octet_length('jose') + + + position(string in string) + int4 + location of specified substring + position('o' in 'Tom') + + + substring(string [from int] [for int]) + string + extract specified substring + substring('Tom' from 2 for 2) + + + trim([leading|trailing|both] [string] from string) + string + trim characters from string + trim(both 'x' from 'xTomx') + + + upper(text) + text + convert text to upper case + upper('tom') + + + +
+ - + Many additional string functions are available for text, varchar(), and char() types. Some are used internally to implement the SQL92 string functions listed above. - + - - - String Functions - - - - Function - Returns - Description - Example - - - - - char(text) - char - convert text to char type - char('text string') - - - char(varchar) - char - convert varchar to char type - char(varchar 'varchar string') - - - initcap(text) - text - first letter of each word to upper case - initcap('thomas') - - - lpad(text,int,text) - text - left pad string to specified length - lpad('hi',4,'??') - - - ltrim(text,text) - text - left trim characters from text - ltrim('xxxxtrim','x') - - - textpos(text,text) - text - locate specified substring - position('high','ig') - - - rpad(text,int,text) - text - right pad string to specified length - rpad('hi',4,'x') - - - rtrim(text,text) - text - right trim characters from text - rtrim('trimxxxx','x') - - - substr(text,int[,int]) - text - extract specified substring - substr('hi there',3,5) - - - text(char) - text - convert char to text type - text('char string') - - - text(varchar) - text - convert varchar to text type - text(varchar 'varchar string') - - - translate(text,from,to) - text - convert character in string - translate('12345', '1', 'a') - - - varchar(char) - varchar - convert char to varchar type - varchar('char string') - - - varchar(text) - varchar - convert text to varchar type - varchar('text string') - - - -
- + + + String Functions + + + + Function + Returns + Description + Example + + + + + char(text) + char + convert text to char type + char('text string') + + + char(varchar) + char + convert varchar to char type + char(varchar 'varchar string') + + + initcap(text) + text + first letter of each word to upper case + initcap('thomas') + + + lpad(text,int,text) + text + left pad string to specified length + lpad('hi',4,'??') + + + ltrim(text,text) + text + left trim characters from text + ltrim('xxxxtrim','x') + + + textpos(text,text) + text + locate specified substring + position('high','ig') + + + rpad(text,int,text) + text + right pad string to specified length + rpad('hi',4,'x') + + + rtrim(text,text) + text + right trim characters from text + rtrim('trimxxxx','x') + + + substr(text,int[,int]) + text + extract specified substring + substr('hi there',3,5) + + + text(char) + text + convert char to text type + text('char string') + + + text(varchar) + text + convert varchar to text type + text(varchar 'varchar string') + + + translate(text,from,to) + text + convert character in string + translate('12345', '1', 'a') + + + varchar(char) + varchar + convert char to varchar type + varchar('char string') + + + varchar(text) + varchar + convert text to varchar type + varchar('text string') + + + +
+ Most functions explicitly defined for text will work for char() and varchar() arguments. @@ -309,113 +310,114 @@ for manipulating various date/time types. - - - Date/Time Functions - - - - Function - Returns - Description - Example - - - - - abstime(datetime) - abstime - convert to abstime - abstime('now'::datetime) - - - age(datetime,datetime) - timespan - span preserving months and years - age('now','1957-06-13'::datetime) - - - datetime(abstime) - datetime - convert to datetime - datetime('now'::abstime) - - - datetime(date) - datetime - convert to datetime - datetime('today'::date) - - - datetime(date,time) - datetime - convert to datetime - datetime('1998-02-24'::datetime, '23:07'::time); - - - date_part(text,datetime) - float8 - specified portion of date field - date_part('dow','now'::datetime) - - - date_part(text,timespan) - float8 - specified portion of time field - date_part('hour','4 hrs 3 mins'::timespan) - - - date_trunc(text,datetime) - datetime - truncate date at specified units - date_trunc('month','now'::abstime) - - - isfinite(abstime) - bool - TRUE if this is a finite time - isfinite('now'::abstime) - - - isfinite(datetime) - bool - TRUE if this is a finite time - isfinite('now'::datetime) - - - isfinite(timespan) - bool - TRUE if this is a finite time - isfinite('4 hrs'::timespan) - - - reltime(timespan) - reltime - convert to reltime - reltime('4 hrs'::timespan) - - - timespan(reltime) - timespan - convert to timespan - timespan('4 hours'::reltime) - - - -
- + + + Date/Time Functions + + + + Function + Returns + Description + Example + + + + + abstime(datetime) + abstime + convert to abstime + abstime('now'::datetime) + + + age(datetime,datetime) + timespan + preserve months and years + age('now','1957-06-13'::datetime) + + + datetime(abstime) + datetime + convert to datetime + datetime('now'::abstime) + + + datetime(date) + datetime + convert to datetime + datetime('today'::date) + + + datetime(date,time) + datetime + convert to datetime + datetime('1998-02-24'::datetime, '23:07'::time); + + + date_part(text,datetime) + float8 + portion of date + date_part('dow','now'::datetime) + + + date_part(text,timespan) + float8 + portion of time + date_part('hour','4 hrs 3 mins'::timespan) + + + date_trunc(text,datetime) + datetime + truncate date + date_trunc('month','now'::abstime) + + + isfinite(abstime) + bool + a finite time? + isfinite('now'::abstime) + + + isfinite(datetime) + bool + a finite time? + isfinite('now'::datetime) + + + isfinite(timespan) + bool + a finite time? + isfinite('4 hrs'::timespan) + + + reltime(timespan) + reltime + convert to reltime + reltime('4 hrs'::timespan) + + + timespan(reltime) + timespan + convert to timespan + timespan('4 hours'::reltime) + + + +
+ - + For the - date_part and date_trunc + date_part and date_trunc functions, arguments can be `year', `month', `day', `hour', `minute', and `second', as well as the more specialized quantities `decade', `century', `millenium', `millisecond', and `microsecond'. - date_part allows `dow' - to return day of week and `epoch' to return seconds since 1970 (for datetime) - or 'epoch' to return total elapsed seconds (for timespan). - + date_part allows `dow' + to return day of week and `epoch' to return seconds since 1970 + (for datetime) + or 'epoch' to return total elapsed seconds (for timespan). + @@ -426,335 +428,335 @@ circle have a large set of native support functions. - - - Geometric Functions - - - - Function - Returns - Description - Example - - - - - area(box) - float8 - area of box - area('((0,0),(1,1))'::box) - - - area(circle) - float8 - area of circle - area('((0,0),2.0)'::circle) - - - box(box,box) - box - boxes to intersection box - box('((0,0),(1,1))','((0.5,0.5),(2,2))') - - - center(box) - point - center of object - center('((0,0),(1,2))'::box) - - - center(circle) - point - center of object - center('((0,0),2.0)'::circle) - - - diameter(circle) - float8 - diameter of circle - diameter('((0,0),2.0)'::circle) - - - height(box) - float8 - vertical size of box - height('((0,0),(1,1))'::box) - - - isclosed(path) - bool - TRUE if this is a closed path - isclosed('((0,0),(1,1),(2,0))'::path) - - - isopen(path) - bool - TRUE if this is an open path - isopen('[(0,0),(1,1),(2,0)]'::path) - - - length(lseg) - float8 - length of line segment - length('((-1,0),(1,0))'::lseg) - - - length(path) - float8 - length of path - length('((0,0),(1,1),(2,0))'::path) - - - pclose(path) - path - convert path to closed variant - popen('[(0,0),(1,1),(2,0)]'::path) - - - point(lseg,lseg) - point - convert to point (intersection) - point('((-1,0),(1,0))'::lseg,'((-2,-2),(2,2))'::lseg) - - - points(path) - int4 - number of points in path - points('[(0,0),(1,1),(2,0)]'::path) - - - popen(path) - path - convert path to open variant - popen('((0,0),(1,1),(2,0))'::path) - - - radius(circle) - float8 - radius of circle - radius('((0,0),2.0)'::circle) - - - width(box) - float8 - horizontal size of box - width('((0,0),(1,1))'::box) - - - -
- + + + Geometric Functions + + + + Function + Returns + Description + Example + + + + + area(box) + float8 + area of box + area('((0,0),(1,1))'::box) + + + area(circle) + float8 + area of circle + area('((0,0),2.0)'::circle) + + + box(box,box) + box + boxes to intersection box + box('((0,0),(1,1))','((0.5,0.5),(2,2))') + + + center(box) + point + center of object + center('((0,0),(1,2))'::box) + + + center(circle) + point + center of object + center('((0,0),2.0)'::circle) + + + diameter(circle) + float8 + diameter of circle + diameter('((0,0),2.0)'::circle) + + + height(box) + float8 + vertical size of box + height('((0,0),(1,1))'::box) + + + isclosed(path) + bool + a closed path? + isclosed('((0,0),(1,1),(2,0))'::path) + + + isopen(path) + bool + an open path? + isopen('[(0,0),(1,1),(2,0)]'::path) + + + length(lseg) + float8 + length of line segment + length('((-1,0),(1,0))'::lseg) + + + length(path) + float8 + length of path + length('((0,0),(1,1),(2,0))'::path) + + + pclose(path) + path + convert path to closed + popen('[(0,0),(1,1),(2,0)]'::path) + + + point(lseg,lseg) + point + intersection + point('((-1,0),(1,0))'::lseg,'((-2,-2),(2,2))'::lseg) + + + points(path) + int4 + number of points + points('[(0,0),(1,1),(2,0)]'::path) + + + popen(path) + path + convert path to open + popen('((0,0),(1,1),(2,0))'::path) + + + radius(circle) + float8 + radius of circle + radius('((0,0),2.0)'::circle) + + + width(box) + float8 + horizontal size + width('((0,0),(1,1))'::box) + + + +
+ - - - Geometric Type Conversion Functions - - - - Function - Returns - Description - Example - - - - - box(circle) - box - convert circle to box - box('((0,0),2.0)'::circle) - - - box(point,point) - box - convert points to box - box('(0,0)'::point,'(1,1)'::point) - - - box(polygon) - box - convert polygon to box - box('((0,0),(1,1),(2,0))'::polygon) - - - circle(box) - circle - convert to circle - circle('((0,0),(1,1))'::box) - - - circle(point,float8) - circle - convert to circle - circle('(0,0)'::point,2.0) - - - lseg(box) - lseg - convert diagonal to lseg - lseg('((-1,0),(1,0))'::box) - - - lseg(point,point) - lseg - convert to lseg - lseg('(-1,0)'::point,'(1,0)'::point) - - - path(polygon) - point - convert to path - path('((0,0),(1,1),(2,0))'::polygon) - - - point(circle) - point - convert to point (center) - point('((0,0),2.0)'::circle) - - - point(lseg,lseg) - point - convert to point (intersection) - point('((-1,0),(1,0))'::lseg,'((-2,-2),(2,2))'::lseg) - - - point(polygon) - point - center of polygon - point('((0,0),(1,1),(2,0))'::polygon) - - - polygon(box) - polygon - convert to polygon with 12 points - polygon('((0,0),(1,1))'::box) - - - polygon(circle) - polygon - convert to polygon with 12 points - polygon('((0,0),2.0)'::circle) - - - polygon(npts,circle) - polygon - convert to polygon with npts points - polygon(12,'((0,0),2.0)'::circle) - - - polygon(path) - polygon - convert to polygon - polygon('((0,0),(1,1),(2,0))'::path) - - - -
- + + + Geometric Type Conversion Functions + + + + Function + Returns + Description + Example + + + + + box(circle) + box + convert circle to box + box('((0,0),2.0)'::circle) + + + box(point,point) + box + convert points to box + box('(0,0)'::point,'(1,1)'::point) + + + box(polygon) + box + convert polygon to box + box('((0,0),(1,1),(2,0))'::polygon) + + + circle(box) + circle + convert to circle + circle('((0,0),(1,1))'::box) + + + circle(point,float8) + circle + convert to circle + circle('(0,0)'::point,2.0) + + + lseg(box) + lseg + convert diagonal to lseg + lseg('((-1,0),(1,0))'::box) + + + lseg(point,point) + lseg + convert to lseg + lseg('(-1,0)'::point,'(1,0)'::point) + + + path(polygon) + point + convert to path + path('((0,0),(1,1),(2,0))'::polygon) + + + point(circle) + point + convert to point (center) + point('((0,0),2.0)'::circle) + + + point(lseg,lseg) + point + convert to point (intersection) + point('((-1,0),(1,0))'::lseg, '((-2,-2),(2,2))'::lseg) + + + point(polygon) + point + center of polygon + point('((0,0),(1,1),(2,0))'::polygon) + + + polygon(box) + polygon + convert to polygon with 12 points + polygon('((0,0),(1,1))'::box) + + + polygon(circle) + polygon + convert to 12-point polygon + polygon('((0,0),2.0)'::circle) + + + polygon(npts,circle) + polygon + convert to npts polygon + polygon(12,'((0,0),2.0)'::circle) + + + polygon(path) + polygon + convert to polygon + polygon('((0,0),(1,1),(2,0))'::path) + + + +
+ - - - Geometric Upgrade Functions - - - - Function - Returns - Description - Example - - - - - isoldpath(path) - path - test path for pre-v6.1 form - isoldpath('(1,3,0,0,1,1,2,0)'::path) - - - revertpoly(polygon) - polygon - convert pre-v6.1 polygon - revertpoly('((0,0),(1,1),(2,0))'::polygon) - - - upgradepath(path) - path - convert pre-v6.1 path - upgradepath('(1,3,0,0,1,1,2,0)'::path) - - - upgradepoly(polygon) - polygon - convert pre-v6.1 polygon - upgradepoly('(0,1,2,0,1,0)'::polygon) - - - -
- + + + Geometric Upgrade Functions + + + + Function + Returns + Description + Example + + + + + isoldpath(path) + path + test path for pre-v6.1 form + isoldpath('(1,3,0,0,1,1,2,0)'::path) + + + revertpoly(polygon) + polygon + convert pre-v6.1 polygon + revertpoly('((0,0),(1,1),(2,0))'::polygon) + + + upgradepath(path) + path + convert pre-v6.1 path + upgradepath('(1,3,0,0,1,1,2,0)'::path) + + + upgradepoly(polygon) + polygon + convert pre-v6.1 polygon + upgradepoly('(0,1,2,0,1,0)'::polygon) + + + +
+ IP V4 Functions - - - <ProductName>Postgres</ProductName>IP V4 Functions - - - - Function - Returns - Description - Example - - - - - broadcast(cidr) - text - construct broadcast address as text - broadcast('192.168.1.5/24') ==> '192.168.1.255' - - - broadcast(inet) - text - construct broadcast address as text - broadcast('192.168.1.5/24') ==> '192.168.1.255' - - - host(inet) - text - extract host address as text - host('192.168.1.5/24') ==> '192.168.1.5' - - - masklen(cidr) - int4 - calculate netmask length - masklen('192.168.1.5/24') ==> 24 - - - masklen(inet) - int4 - calculate netmask length - masklen('192.168.1.5/24') ==> 24 - - - netmask(inet) - text - construct netmask as text - netmask('192.168.1.5/24') ==> '255.255.255.0' - - - -
- + + + <productname>Postgres</productname>IP V4 Functions + + + + Function + Returns + Description + Example + + + + + broadcast(cidr) + text + construct broadcast address as text + broadcast('192.168.1.5/24') + + + broadcast(inet) + text + construct broadcast address as text + broadcast('192.168.1.5/24') + + + host(inet) + text + extract host address as text + host('192.168.1.5/24') + + + masklen(cidr) + int4 + calculate netmask length + masklen('192.168.1.5/24') + + + masklen(inet) + int4 + calculate netmask length + masklen('192.168.1.5/24') + + + netmask(inet) + text + construct netmask as text + netmask('192.168.1.5/24') + + + +
+ - + diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index c6c63d66be..10bdc90eca 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,68 +1,74 @@ - -Large Objects - - - In Postgres, data values are stored in tuples and - individual tuples cannot span data pages. Since the size of - a data page is 8192 bytes, the upper limit on the size - of a data value is relatively low. To support the storage - of larger atomic values, Postgres provides a large - object interface. This interface provides file - oriented access to user data that has been declared to - be a large type. - This section describes the implementation and the - programmatic and query language interfaces to Postgres - large object data. - - - -Historical Note - - - Originally, Postgres 4.2 supported three standard + + Large Objects + + + In Postgres, + data values are stored in tuples and + individual tuples cannot span data pages. Since the size of + a data page is 8192 bytes, the upper limit on the size + of a data value is relatively low. To support the storage + of larger atomic values, + Postgres provides a large + object interface. This interface provides file + oriented access to user data that has been declared to + be a large type. + This section describes the implementation and the + programmatic and query language interfaces to + Postgres + large object data. + + + +Historical Note + + + Originally, Postgres 4.2 supported three standard implementations of large objects: as files external - to Postgres, as UNIX files managed by Postgres, and as data - stored within the Postgres database. It causes + to Postgres, as + ym>Uym> files managed by Postgres, and as data + stored within the Postgres database. It causes considerable confusion among users. As a result, we only - support large objects as data stored within the Postgres - database in PostgreSQL. Even though it is slower to + support large objects as data stored within the Postgres + database in PostgreSQL. Even though it is slower to access, it provides stricter data integrity. For historical reasons, this storage scheme is referred to as Inversion large objects. (We will use Inversion and large objects interchangeably to mean the same thing in this section.) - - + + - -Inversion Large Objects + +Inversion Large Objects - + The Inversion large object implementation breaks large objects up into "chunks" and stores the chunks in tuples in the database. A B-tree index guarantees fast searches for the correct chunk number when doing random access reads and writes. - - + + - -Large Object Interfaces + +Large Object Interfaces - - The facilities Postgres provides to access large + + The facilities Postgres provides to access large objects, both in the backend as part of user-defined functions or the front end as part of an application using the interface, are described below. (For users - familiar with Postgres 4.2, PostgreSQL has a new set of + familiar with Postgres 4.2, + PostgreSQL has a new set of functions providing a more coherent interface. The interface is the same for dynamically-loaded C functions as well as for XXX LOST TEXT? WHAT SHOULD GO HERE??. - The Postgres large object interface is modeled after - the UNIX file system interface, with analogues of - open(2), read(2), write(2), - lseek(2), etc. User + The Postgres large object interface is modeled after + the UNIX file system interface, with analogues of + open(2), read(2), +write(2), + lseek(2), etc. User functions call these routines to retrieve only the data of interest from a large object. For example, if a large object type called mugshot existed that stored @@ -72,81 +78,82 @@ the beard that appeared there, if any. The entire large object value need not be buffered, or even examined, by the beard function. - Large objects may be accessed from dynamically-loaded C + Large objects may be accessed from dynamically-loaded C functions or database client programs that link the - library. Postgres provides a set of routines that + library. Postgres provides a set of routines that support opening, reading, writing, closing, and seeking on large objects. - + - -Creating a Large Object + +Creating a Large Object - + The routine - + Oid lo_creat(PGconn *conn, int mode) - + creates a new large object. The mode is a bitmask describing several different attributes of the new object. The symbolic constants listed here are defined in - + PGROOT/src/backend/libpq/libpq-fs.h - + The access type (read, write, or both) is controlled by - OR ing together the bits INV_READ and INV_WRITE. If + OR ing together the bits INV_READ and +INV_WRITE. If the large object should be archived -- that is, if historical versions of it should be moved periodically to - a special archive relation -- then the INV_ARCHIVE bit + a special archive relation -- then the INV_ARCHIVE bit should be set. The low-order sixteen bits of mask are the storage manager number on which the large object should reside. For sites other than Berkeley, these bits should always be zero. The commands below create an (Inversion) large object: - + inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE); - - - + + + - -Importing a Large Object + +Importing a Large Object - -To import a UNIX file as + +To import a UNIX file as a large object, call - + Oid lo_import(PGconn *conn, text *filename) - - The filename argument specifies the UNIX pathname of + + The filename argument specifies the UNIX pathname of the file to be imported as a large object. - - + + - -Exporting a Large Object + +Exporting a Large Object - + To export a large object - into UNIX file, call - + into UNIX file, call + int lo_export(PGconn *conn, Oid lobjId, text *filename) - + The lobjId argument specifies the Oid of the large object to export and the filename argument specifies - the UNIX pathname of the file. - - + the UNIX pathname of the file. + + - -Opening an Existing Large Object + +Opening an Existing Large Object - + To open an existing large object, call - + int lo_open(PGconn *conn, Oid lobjId, int mode, ...) - + The lobjId argument specifies the Oid of the large object to open. The mode bits control whether the object is opened for reading INV_READ), writing or @@ -154,64 +161,65 @@ int lo_open(PGconn *conn, Oid lobjId, int mode, ...) A large object cannot be opened before it is created. lo_open returns a large object descriptor for later use in lo_read, lo_write, lo_lseek, lo_tell, and lo_close. - - + + - -Writing Data to a Large Object + +Writing Data to a Large Object - + The routine - + int lo_write(PGconn *conn, int fd, char *buf, int len) - + writes len bytes from buf to large object fd. The fd argument must have been returned by a previous lo_open. The number of bytes actually written is returned. In the event of an error, the return value is negative. - - + + - -Seeking on a Large Object + +Seeking on a Large Object - + To change the current read or write location on a large object, call - + int lo_lseek(PGconn *conn, int fd, int offset, int whence) - + This routine moves the current location pointer for the large object described by fd to the new location specified by offset. The valid values for .i whence are SEEK_SET SEEK_CUR and SEEK_END. - - + + - -Closing a Large Object Descriptor + +Closing a Large Object Descriptor - + A large object may be closed by calling - + int lo_close(PGconn *conn, int fd) - + where fd is a large object descriptor returned by - lo_open. On success, lo_close returns zero. On error, + lo_open. On success, lo_close returns zero. On error, the return value is negative. - + - + - -Built in registered functions + +Built in registered functions - - There are two built-in registered functions, lo_import - and lo_export which are convenient for use in SQL + + There are two built-in registered functions, lo_import + and lo_export which are convenient for use + in SQL queries. Here is an example of their use - + CREATE TABLE image ( name text, raster oid @@ -222,33 +230,33 @@ INSERT INTO image (name, raster) SELECT lo_export(image.raster, "/tmp/motd") from image WHERE name = 'beautiful image'; - - - + + + - -Accessing Large Objects from LIBPQ + +Accessing Large Objects from LIBPQ - + Below is a sample program which shows how the large object interface in LIBPQ can be used. Parts of the program are commented out but are left in the source for the readers benefit. This program can be found in - + ../src/test/examples - + Frontend applications which use the large object interface in LIBPQ should include the header file libpq/libpq-fs.h and link with the libpq library. - - + + - -Sample Program + +Sample Program - - + + /*-------------------------------------------------------------- * * testlo.c-- @@ -479,8 +487,25 @@ SELECT lo_export(image.raster, "/tmp/motd") from image PQfinish(conn); exit(0); } - - - - - + + + + + + + diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index 1d3f2c661e..c6ccb00402 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -23,7 +23,7 @@ - Here is a brief summary of some of the more noticable changes: + Here is a brief summary of the more notable changes: @@ -188,16 +188,16 @@ Because readers in 6.5 don't lock data, regardless of transaction isolation level, data read by one transaction can be overwritten by - another. In the other words, if a row is returned by + another. In other words, if a row is returned by SELECT it doesn't mean that this row really exists at the time it is returned (i.e. sometime after the statement or - transaction began) nor that the row is protected from deletion or - update by concurrent transactions before the current transaction does + transaction began) nor that the row is protected from being deleted or + updated by concurrent transactions before the current transaction does a commit or rollback. - To ensure the actual existance of a row and protect it against + To ensure the actual existence of a row and protect it against concurrent updates one must use SELECT FOR UPDATE or an appropriate LOCK TABLE statement. This should be taken into account when porting applications from previous releases of @@ -205,7 +205,8 @@ - Keep above in mind if you are using contrib/refint.* triggers for + Keep the above in mind if you are using + contrib/refint.* triggers for referential integrity. Additional technics are required now. One way is to use LOCK parent_table IN SHARE ROW EXCLUSIVE MODE command if a transaction is going to update/delete a primary key and @@ -2634,6 +2635,7 @@ Initial release. Time System 02:00 Dual Pentium Pro 180, 224MB, UW-SCSI, Linux 2.0.36, gcc 2.7.2.3 -O2 -m486 + 04:38 Sparc Ultra 1 143MHz, 64MB, Solaris 2.6 -- 2.39.5