Chapter 8 Defining Functions for Database Operations

This chapter explains how to write functions that perform database operations, such as exporting the directory, importing LDIF files, archiving, and restoring database archives.

In general, these functions must comply with the prototype specified in "Working with Parameter Blocks" on page  30 (in other words, the functions should pass a single Slapi_PBlock argument).

You can define plug-in functions to do the following:

• Importing an LDIF File into the Database
• Exporting the Database to an LDIF File
• Saving the Database as an Archive
• Restoring the Database from an Archive
• Reporting the Size of the Database
• Testing the Database
• Generating Indexes for the Database

The front-end makes the following information available in the form of parameters in a parameter block.

Parameter ID	Data Type	Description
SLAPI_LDIF2DB_FILE	char *	LDIF file that needs to be imported into the database.
SLAPI_LDIF2DB_REPLACE_DSE_FN	void *	Function that replaces a DSE (DSA-specific entry) in the front-end. DSA is another term for the Directory Server.
SLAPI_LDIF2DB_WRITE_DSE_FILE	void *	Function that writes a DSE (DSA-specific entry) in the front-end to a file. DSA is another term for the Directory Server.
SLAPI_LDIF2DB_NOATTRINDEXES	int	(Netscape Directory Server 4.0 release only) If 1, the database should not be indexed when the database is created. If 0, the import function should automatically generate database indexes.
SLAPI_LDIF2DB_INCLUDE	char **	(Netscape Directory Server 4.0 release only) An array of the suffixes or DNs identifying the entries in the LDIF file to be included in the database.
SLAPI_LDIF2DB_EXCLUDE	char **	(Netscape Directory Server 4.0 release only) An array of the suffixes or DNs identifying the entries in the LDIF file to be excluded from the database.

The LDIF import function should parse the LDIF entries in the file specified by the SLAPI_LDIF2DB_FILE parameter and should create corresponding entries in the database.

The array of DNs and suffixes in the SLAPI_LDIF2DB_INCLUDE parameter and the SLAPI_LDIF2DB_EXCLUDE parameter identify entries in the LDIF file that should be included or excluded when creating the database. (This feature is available in the Netscape Directory Server 4.0 release and not in previous releases.)

For example, if the SLAPI_LDIF2DB_INCLUDE parameter includes the suffix "o=Airius.com", the import function should include entries in the LDIF file that have DNs ending with "o=Airius.com". On the other hand, if the SLAPI_LDIF2DB_EXCLUDE parameter includes the suffix "o=AceIndustry.com", the import function should exclude entries in the LDIF file that have DNs ending with "o=AceIndustry.com".

The LDIF import function should also check the value of the SLAPI_LDIF2DB_NOATTRINDEXES parameter. If the value of this parameter is 0, the function should automatically generate indexes when creating the database. If the value is 1, the function should not automatically generate the indexes. (This feature is available in the Netscape Directory Server 4.0 release and not in previous releases.)

In some instances, the LDIF file may contain a DSE. A DSE is a DSA-specific entry (DSA is the X.500 term for Directory Server). In the Netscape Directory Server, DSEs are stored in LDIF format in the DSE file:

<server_root>/<server_id>/config/dse.ldif

(For example, /usr/netscape/suitespot/slapd-myhost/config/dse.ldif).

When the Directory Server starts up, it reads the DSEs from this file and loads them into the front-end.

Because the imported LDIF file may contain DSEs, you should check for DSEs in your import function. If a DSE is specified in the LDIF file, you should call the DSE replacement function (specified by SLAPI_LDIF2DB_REPLACE_DSE_FN in the parameter block) to replace the existing DSEs in the front-end.

At the end of your database import function, you also need to call the DSE file write function (specified by SLAPI_LDIF2DB_WRITE_DSE_FILE in the parameter block). Calling this function will write the DSEs out to the DSE file.

The front-end makes the following information available in the form of parameters in a parameter block.

Parameter ID	Data Type	Description
SLAPI_DB2LDIF_PRINTKEY	int	Specifies whether or not the database keys should be printed out as well. If 1, you should include the database key for each entry. If 0, you do not need to include the database key for each entry.
SLAPI_DB2LDIF_PRINT_DSE_TREE_FN	void *	Function for printing the front-end DSEs in LDIF format.

The LDIF export function should generate LDIF entries corresponding to entries in the database and should store the LDIF entries in the file.

The SLAPI_DB2LDIF_PRINT_DSE_TREE_FN parameter specifies the function that prints out the DSEs in the front end. A DSE is a DSA-specific entry (DSA is the X.500 name for the Directory Server). In your database export function, you should call the DSE print function if you want the DSE entries to appear in the LDIF file.

The SLAPI_DB2LDIF_PRINTKEY parameter specifies whether or not the database keys should be printed with each entry. If this parameter is 1, you should print out the database keys for each entry. If this parameter is 0, you do not need to print out the keys.

The front-end makes the following information available in the form of parameters in a parameter block.

Parameter ID	Data Type	Description
SLAPI_SEQ_VAL	char *	Specifies the directory in which you want to store the archive.

The database archive function should create an archive of the database in the directory specified by the SLAPI_SEQ_VAL parameter.

The front-end makes the following information available in the form of parameters in a parameter block.

Parameter ID	Data Type	Description
SLAPI_SEQ_VAL	char *	Specifies the directory containing the archive that you want to restore.

The database restore function should replace the database with the archive in the directory specified by the SLAPI_SEQ_VAL parameter.

You can write your own test function for your database and register the function as the database test function. For example, you might write a function that printed status messages to standard output.

When the Directory Server receives a request to generate indexes for the database (for example, from the Administrator Server or from the db2index command-line utility), the front-end calls the back-end database function for indexing the database. The SLAPI_PLUGIN_DB_DB2INDEX_FN parameter in the parameter block specifies this function.

The front-end makes the following information available in the form of parameters in a parameter block.

Parameter ID	Data Type	Description
SLAPI_DB2INDEX_ATTRS	char **	Specifies a NULL-terminated array of the attribute types that you want indexed.

The database index function should create indexes of the database for the attributes specified by the SLAPI_DB2INDEX_ATTRS parameter.