.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2009
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, no Front-Cover Texts,
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "Database" 3m17n "15 Oct 2009" "" "Version 1.5.5" "" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Database \- The m17n database and API for it.  

.PP
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBMDatabase\fP \fBMDatabase\fP"
.br
.RI "\fIType of database. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBMDatabase\fP * \fBmdatabase_find\fP (\fBMSymbol\fP tag0, \fBMSymbol\fP tag1, \fBMSymbol\fP tag2, \fBMSymbol\fP tag3)"
.br
.RI "\fILook for a data in the database. \fP"
.ti -1c
.RI "\fBMPlist\fP * \fBmdatabase_list\fP (\fBMSymbol\fP tag0, \fBMSymbol\fP tag1, \fBMSymbol\fP tag2, \fBMSymbol\fP tag3)"
.br
.RI "\fIReturn a data list of the m17n database. \fP"
.ti -1c
.RI "\fBMDatabase\fP * \fBmdatabase_define\fP (\fBMSymbol\fP tag0, \fBMSymbol\fP tag1, \fBMSymbol\fP tag2, \fBMSymbol\fP tag3, void *(*loader)(\fBMSymbol\fP *, void *), void *extra_info)"
.br
.RI "\fIDefine a data of the m17n database. \fP"
.ti -1c
.RI "void * \fBmdatabase_load\fP (\fBMDatabase\fP *mdb)"
.br
.RI "\fILoad a data from the database. \fP"
.ti -1c
.RI "\fBMSymbol\fP * \fBmdatabase_tag\fP (\fBMDatabase\fP *mdb)"
.br
.RI "\fIGet tags of a data. \fP"
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "char * \fBmdatabase_dir\fP"
.br
.RI "\fIDirectory for application specific data. \fP"
.in -1c
.SH "Detailed Description"
.PP 
The m17n database and API for it. 
.PP
The m17n library acquires various kinds of information from data in the \fI m17n database\fP on demand. Application programs can also add/load their original data to/from the m17n database by setting the variable \fBmdatabase_dir\fP to an application\-specific directory and storing data in it. Users can overwrite those data by storing preferable data in the directory specified by the environment variable 'M17NDIR', or if it is not set, in the directory '~/.m17n.d'.
.PP
The m17n database contains multiple heterogeneous data, and each data is identified by four tags; TAG0, TAG1, TAG2, TAG3. Each tag must be a symbol.
.PP
TAG0 specifies the type of data stored in the database as below.
.PP
.PD 0
.IP "\(bu" 2
If TAG0 is \fBMchar_table\fP, the data is of the \fIchartable\fP \fItype\fP and provides information about each character. In this case, TAG1 specifies the type of the information and must be \fBMsymbol\fP, \fBMinteger\fP, \fBMstring\fP, \fBMtext\fP, or \fBMplist\fP. TAG2 and TAG3 can be any symbols.
.PP
.PD 0
.IP "\(bu" 2
If TAG0 is \fBMcharset\fP, the data is of the \fIcharset\fP \fItype\fP and provides a decode/encode mapping table for a charset. In this case, TAG1 must be a symbol representing a charset. TAG2 and TAG3 can be any symbols.
.PP
.PD 0
.IP "\(bu" 2
If TAG0 is neither \fBMchar_table\fP nor \fBMcharset\fP, the data is of the \fIplist\fP \fItype\fP. See the documentation of the \fBmdatabase_load()\fP function for the details. In this case, TAG1, TAG2, and TAG3 can be any symbols.
.PP
The notation <TAG0, TAG1, TAG2, TAG3> means a data with those tags.
.PP
Application programs first calls the \fBmdatabase_find()\fP function to get a pointer to an object of the type \fBMDatabase\fP. That object holds information about the specified data. When it is successfully returned, the \fBmdatabase_load()\fP function loads the data. The implementation of the structure \fBMDatabase\fP is concealed from application programs. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBMDatabase\fP \fBMDatabase\fP"
.PP
Type of database. 
.PP
The type \fBMDatabase\fP is for a database object. Its internal structure is concealed from an application program. 
.SH "Variable Documentation"
.PP 
.SS "char* \fBmdatabase_dir\fP"
.PP
Directory for application specific data. 
.PP
If an application program wants to provide a data specific to the program or a data overriding what supplied by the m17n database, it must set this variable to a name of directory that contains the data files before it calls the macro \fBM17N_INIT()\fP. The directory may contain a file 'mdb.dir' which contains a list of data definitions in the format described in \fBmdbDir(5)\fP.
.PP
The default value is NULL. 
.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2009 National Institute of Advanced Industrial Science and Technology (AIST)
.br
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License 
<http://www.gnu.org/licenses/fdl.html>.
