[docs] docs - heins modified icdatabase.sdf
docs@interchange.redhat.com
docs@interchange.redhat.com
Fri Jul 19 23:15:01 2002
User: heins
Date: 2002-07-20 03:14:37 GMT
Modified: . icdatabase.sdf
Log:
* Add some more search variable documentation. Will eventually be mirrored =
in
icvars.sdf -- I wonder if there is an "include" functionality in SDF?
Revision Changes Path
1.49 +185 -24 docs/icdatabase.sdf
rev 1.49, prev_rev 1.48
Index: icdatabase.sdf
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
RCS file: /anon_cvs/repository/docs/icdatabase.sdf,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- icdatabase.sdf 16 Jul 2002 12:41:44 -0000 1.48
+++ icdatabase.sdf 20 Jul 2002 03:14:37 -0000 1.49
@@ -1,10 +1,10 @@
!init OPT_LOOK=3D"akopia"; OPT_STYLE=3D"manual"
-# $Id: icdatabase.sdf,v 1.48 2002/07/16 12:41:44 jon Exp $
+# $Id: icdatabase.sdf,v 1.49 2002/07/20 03:14:37 mheins Exp $
=20
!define DOC_NAME "Interchange Databases"
!define DOC_TYPE ""
!define DOC_CODE "icdatabase"
-!define DOC_VERSION substr('$Revision: 1.48 $',11, -2)
+!define DOC_VERSION substr('$Revision: 1.49 $',11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://interchange.redhat.com/doc/icdatabase.html"
@@ -14,7 +14,12 @@
=20
Interchange can use GDBM, DB_File, SQL, LDAP, or in-memory databases. In m=
ost cases, these different database formats should operate the same when ca=
lled by Interchange's access methods.
=20
-Also, Interchange does not require an external SQL database. If you have a=
small database and do not want to integrate your own tool set, you might w=
ant to use Interchange's internal database. However, the order management f=
unctions of Interchange will be slower and not as robust without an SQL dat=
abase. SQL is strongly recommended for at least the orderline, transactions=
, and userdb tables.
+Also, Interchange does not require an external SQL database. If you have
+a small database and do not want to integrate your own tool set, you
+might want to use Interchange's internal database. However, the order
+management functions of Interchange will be slower and not as robust
+without an SQL database. SQL is strongly recommended for at least the
+orderline, transactions, and userdb tables.
=20
Keeping a database in an SQL manager makes it easier to integrate Intercha=
nge with other tools. Interchange can be used to maintain a spreadsheet con=
taining product information through modifying the file C<products.txt> as n=
eeded. References to SQL, DBI, and DBD can be ignored.
=20
@@ -405,7 +410,7 @@
.Set the LARGE attribute to 1 to avoid this problem:
=20
!block example
- Database transactions LARGE 1
+ Database transactions LARGE 1
!endblock
=20
.In this case the UI supplies only input boxes to search records in the
@@ -414,9 +419,15 @@
=20
H2: Dictionary Indexing With INDEX
=20
-Interchange will automatically build index files for a fast binary search =
of an individual field. This type of search is useful for looking up the au=
thor of a book based on the beginning of their last name, a book title base=
d on its beginning, or other similar situations.
-
-Such a search requires a dictionary ordered index with the field to be sea=
rched contained in the first field and the database key (product code) in t=
he second field. If the C<INDEX field> modifier is specified, Interchange w=
ill build the index upon database import:
+Interchange will automatically build index files for a fast binary
+search of an individual field. This type of search is useful for looking
+up the author of a book based on the beginning of their last name, a
+book title based on its beginning, or other similar situations.
+
+Such a search requires a dictionary ordered index with the field to be
+searched contained in the first field and the database key (product
+code) in the second field. If the C<INDEX field> modifier is specified,
+Interchange will build the index upon database import:
=20
!block example
Database products products.txt TAB
@@ -434,51 +445,73 @@
The Starry Night 00-343
!endblock
=20
-Options can be appended to the field name after a colon (:). The most usef=
ul will be C<f>, which does a case-insensitive sort. The C<mv_dict_fold> op=
tion must be added to the search in this case.
+Options can be appended to the field name after a colon (:). The most
+useful will be C<f>, which does a case-insensitive sort. The
+C<mv_dict_fold> option must be added to the search in this case.
=20
-Another option is C<c>, which stands for "comma index." To index on comma-=
separated sub-fields within a field, use the :c option:
+Another option is C<c>, which stands for "comma index." To index on
+comma-separated sub-fields within a field, use the :c option:
=20
!block example
Database products products.txt TAB
Database products INDEX category:c
!endblock
=20
-This can get slow for larger databases and fields. Interchange will split =
the field on a comma (stripping surrounding whitespace) and make index entr=
ies for each one. This allows multiple categories in one field while retain=
ing the fast category search mechanism. It might also be useful for a C<key=
words> field.
+This can get slow for larger databases and fields. Interchange will
+split the field on a comma (stripping surrounding whitespace) and make
+index entries for each one. This allows multiple categories in one field
+while retaining the fast category search mechanism. It might also be
+useful for a C<keywords> field.
=20
The fast binary search is described in greater detail in THE SEARCH ENGINE=
below.
=20
H2: MEMORY for Memory-Only Databases
=20
-Interchange's memory-based databases are the fastest possible way to organ=
ize
-and store frequently used data. To force a database to be built in memory =
instead of DBM, use the MEMORY modifier:
+Interchange's memory-based databases are the fastest possible way to
+organize and store frequently used data. To force a database to be built
+in memory instead of DBM, use the MEMORY modifier:
=20
!block example
Database country country.asc TAB
Database country MEMORY 1
!endblock
=20
-Obviously, large tables will use a great deal of memory, and the data will=
need to be re-imported from the ASCII source file at every catalog reconfi=
guration or Interchange restart. The big advantage of using MEMORY is that =
the database remains open at all times and does not need to be reinitialize=
d at every connect. Use it for smaller tables that will be frequently acces=
sed.
+Obviously, large tables will use a great deal of memory, and the data
+will need to be re-imported from the ASCII source file at every catalog
+reconfiguration or Interchange restart. The big advantage of using
+MEMORY is that the database remains open at all times and does not need
+to be reinitialized at every connect. Use it for smaller tables that
+will be frequently accessed.
=20
The MEMORY modifier forces IMPORT_ONCE.
=20
H2: IMPORT_ONCE
=20
-The IMPORT_ONCE modifier tells Interchange not to re-import the database f=
rom the ASCII file every time it changes. Normally, Interchange does a comp=
arison of the database file modification time with the ASCII source every t=
ime it is accessed, and if the ASCII source is newer it will re-import the =
file.
+The IMPORT_ONCE modifier tells Interchange not to re-import the database
+from the ASCII file every time it changes. Normally, Interchange does a
+comparison of the database file modification time with the ASCII source
+every time it is accessed, and if the ASCII source is newer it will
+re-import the file.
=20
-IMPORT_ONCE tells it only to import on a server restart or catalog reconfi=
guration:
+IMPORT_ONCE tells it only to import on a server restart or catalog
+reconfiguration:
=20
!block example
Database products products.txt TAB
Database products IMPORT_ONCE 1
!endblock
=20
-SQL databases don't normally need this. They will only be imported once in=
normal operation. Also see C<NoImport> for a way to guarantee that the tab=
le will never be imported.
+SQL databases don't normally need this. They will only be imported once
+in normal operation. Also see C<NoImport> for a way to guarantee that
+the table will never be imported.
=20
-IMPORT_ONCE is always in effect for MEMORY databases. A catalog reconfigur=
ation is required to force a change.
+IMPORT_ONCE is always in effect for MEMORY databases. A catalog
+reconfiguration is required to force a change.
=20
H2: Importing in a Page
=20
-To add a data record to a database as a result of an order or other operat=
ion, use Interchange's C<[import ...]> tag.
+To add a data record to a database as a result of an order or other
+operation, use Interchange's C<[import ...]> tag.
=20
LI1: [import table type*] RECORD [/import]
=20
@@ -492,7 +525,11 @@
separator=3Dc*]
!endblock
=20
-Import one or more records into a database. The C<type> is any of the vali=
d Interchange delimiter types, with the default being TAB. The table must a=
lready be a defined Interchange database table. It cannot be created on-the=
-fly. If on-the-fly functionality is need, it is time to use SQL.
+Import one or more records into a database. The C<type> is any of the
+valid Interchange delimiter types, with the default being TAB. The
+table must already be a defined Interchange database table. It cannot
+be created on-the-fly. If on-the-fly functionality is need, it is time
+to use SQL.
=20
The import type selected need not match the type the database was specifie=
d. Different delimiters may be used.
=20
@@ -778,6 +815,59 @@
=20
Invoke the command without any arguments for a usage message describing th=
e options.
=20
+H1: Other Database Capabilities
+
+Interchange has a number of other options that can affect operation
+of or operations on a defined database.
+
+H2: Search Modification
+
+Normally, Interchange can search any database and will return all records
+that match the search specification. Some attributes affect this.
+
+H3: HIDE_FIELD
+
+When set to a field name, i.e.:
+
+!block example
+ Database sometable HIDE_FIELD inactive
+!endblock
+
+Interchange will not return records that have that field (in the
+example, c<inactive>) set to a true (non-blank, non-zero) value.
+
+H3: NO_SEARCH
+
+An indication that the database should not be searchable by default. Used =
to
+determine the default search files for a product searc.
+
+!block example
+ Database sometable NO_SEARCH 1
+!endblock
+
+In the C<foundation> demo, this is used to prevent the C<options> table fr=
om
+being searched for products.
+
+H2: Indexing
+
+You can indicate that a database should be indexed on a field with the
+INDEX modifier:
+
+!block example
+ Database sometable INDEX category
+!endblock
+
+This will create an ASCII index on every import, and will also create an
+index on the field at SQL creation time. (See L<Dictionary Indexing with I=
NDEX>.)
+
+If you wish to create SQL indices at table creation time I<without> creati=
ng
+an ASCII index, use the NO_ASCII_INDEX parameter:
+
+!block example
+ Database sometable NO_ASCII_INDEX 1
+!endblock
+
+Of course you can create a SQL index manually at any time via your SQL too=
lset.
=20
H1: The Search Engine
=20
@@ -1381,7 +1471,6 @@
=20
LI1: mv_base_directory
=20
-
.Scan abbreviation: bd=3D/directory/name. In the text search, set to the d=
irectory from which to base file searches. File names without leading / cha=
racters will be based from there. In the Glimpse search, passed to Glimpse =
with the C<-H> option, and Glimpse will look for its indices there. Default=
is ProductDir.
=20
.If an absolute path directory is used, for security enable it in the user=
s session with:
@@ -1398,12 +1487,51 @@
=20
.This is a multiple parameter. If C<mv_coordinate> is in force, it should =
be set as many times as necessary to match the field/searchstring combinati=
on. If set only once, it applies to all fields. If set more than once but n=
ot as many times as the fields, it will default to off.
=20
+LI1: mv_cache_key
+
+.Not normally set by the user. It is a value that provides a pointer to th=
e search
+reference by the C<more> function.
+
LI1: mv_case
=20
.If this item is set to C<No>, the search will return items without regard=
to upper or lower case. This is the default. Set to C<Yes> if case should =
be matched. Implement with a checkbox <INPUT TYPE=3DCHECKBOX> field.
=20
.If stacked to match the C<mv_search_field> and C<mv_searchspec> variables=
, and C<mv_coordinate> is set, it will operate only for the corresponding f=
ield.
=20
+.Scan abbreviation: cs
+
+LI1: mv_column_op
+
+.In the coordinated search, the operation that will be performed to check =
the=20
+field for a search match. These operations are supported:
+
+!block example
+ !=3D Not equal to
+ !~ Not matching regular expression
+ < Less than
+ <=3D Less than or equal to
+ <> Not equal to
+ =3D Equal to
+ =3D=3D Equal to
+ =3D~ Matching regular expression
+ > Greater than
+ >=3D Greater than or equal to
+ em Exact match
+ eq Equal to
+ ge Greater than or equal to
+ gt Greater than
+ le Less than or equal to
+ lt Less than
+ ne Not equal to
+ rm Matching regular expression
+ rn Not matching regular expression
+!endblock
+
+.If stacked to match the C<mv_search_field> and C<mv_searchspec> variables=
, and C<mv_coordinate> is set, it will operate only for the corresponding f=
ield.
+
+Note that several of the operators are the same. They do either numeric or=
string
+comparisons based on the status of C<mv_numeric> (alias C<nu>) for that co=
lumn.
+
LI1: mv_coordinate
=20
.If this item is set to C<Yes>, and the number of search fields equals the=
number of search specs, the search will return only items that match field=
to spec. (The search specifications are set by stacked C<mv_searchspec> an=
d C<mv_search_field> variables.)
@@ -1416,7 +1544,8 @@
=20
.*If more than one instance of the options are set, but fewer than the num=
ber of search specifications, the default setting will be used for the trai=
ling unset options.
=20
-..If a search specification is blank, it will be removed and all case-sens=
itivity/negation/substring options will be adjusted accordingly.
+..If a search specification is blank, it will be removed and all case-sens=
itivity/negation/substring options will be adjusted accordingly. If you nee=
d a blank string to
+match on, use quotes (C<"">).
=20
LI1: mv_dict_end
=20
@@ -1474,12 +1603,19 @@
=20
LI1: mv_doit
=20
-.This must be set to C<search> to make this a search page.
+.This can be set to C<search> to make a form with a C<process> action be a
+search page by default. The C<mv_todo> variable takes precedence.
=20
LI1: mv_exact_match
=20
.Normally Interchange searches match words, as opposed to sentences. This =
behavior can be overridden with C<mv_exact_match>, which when set will plac=
e quotes around any value in C<mv_searchspec> or C<mv_dict_look>.
=20
+LI1: mv_field_file
+
+.If you want to search a file which has no field header on the first line,=
you can
+specify a file to get the field names from. It expects a single line with =
the
+field names separated by TAB characters.
+
LI1: mv_field_names
=20
.Deprecated in favor of in-list sorting. Defines the field names for the f=
ile being searched. This guarantees that they will be available, and preven=
ts a disk access if using named fields on a search file (that is not the pr=
oduct database ASCII source, where field names are already known). This mus=
t be exactly correct, or it will result in anomalous search operation. Usua=
lly passed in a hidden field or search profile as a comma-separated list.
@@ -1496,7 +1632,19 @@
=20
LI1: mv_index_delim
=20
-.Sets the delimiter for counting fields in a search index. The default is =
TAB.
+.Sets the delimiter for counting fields in a search index. The default is =
TAB. It
+should rarely be changed unless you are searching a pipe-delimited or colo=
n-delimited
+file.
+
+LI1: mv_like_field
+
+.Specifies a field in a database search which should be used for a screeni=
ng
+function based on the SQL C<like> function. Needs C<mv_like_spec>.
+
+LI1: mv_like_spec
+
+.The string that should be searched for in C<mv_like_field>. The behavior =
of
+the % character and case-sensitivity depends on your SQL implementation.
=20
LI1: mv_matchlimit
=20
@@ -1608,6 +1756,16 @@
=20
.Defaults to text if Glimpse is not defined; defaults to Glimpse if it is =
defined. This can allow use of both search types if that is desirable. For =
instance, searching for very common strings is better done by the text-base=
d search. An example might be searching for categories of items instead of =
individual items.
=20
+LI1: mv_small_data
+
+Tells the search engine that there is a small amount of data in the file a=
nd that
+it should perform the search function on every line.
+
+Normally, when Interchange can find a fixed search expression it produces a
+"screening" function which will allow records to be quickly rejected when
+they don't match. If there are less than 50 records in the file or databas=
e,
+this may be counterproductive.
+
LI1: mv_sort_field
=20
.The file field(s) the search is to be sorted on, specified in one of two =
ways. If the file(s) to be searched have a header line (the first line) tha=
t contains delimiter-separated field names, it can be specified by field na=
me. It can also be specified by column number (the code or key is specified=
with a value of 0, for both types). These can be stacked if coming from a =
form or placed in a single specification separated by commas.
@@ -2825,7 +2983,10 @@
]
!endblock
=20
-.This would be coupled with a login form that asks for order number and zi=
p code, thereupon allowing the display of the contents of a transaction dat=
abase with (presumably updated) order status information or a shipping comp=
any tracking number.
+.This would be coupled with a login form that asks for order number and
+zip code, thereupon allowing the display of the contents of a
+transaction database with (presumably updated) order status information
+or a shipping company tracking number.
=20
LI1: change_pass
=20