PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Add an entry to a database.

VMS FORMAT

status = PMDF_database_add_entry

(database, entry, value, create_db, replace, setbits, bits)

C FORMAT

status = PMDFdatabaseAddEntry

(database, entry, entry_len, value, value_len, create_db, replace, setbits, bits)

int PMDFdatabaseAddEntry (database, entry, entry_len, 
                          value, value_len, create_db, 
                          replace, setbits, bits) 
         int               database; 
         char             *entry; 
         int               entry_len; 
         char             *value; 
         int               value_len; 
         int               create_db; 
         int               replace; 
         int               setbits; 
         unsigned long int bits; 

ARGUMENTS

database

Database to add the entry to.

entry

Entry to add to the database (e.g., alias name). Length of this string should not exceed KEY_LENGTH for a short database or LONG_KEY_LENGTH for a long database.

entry_len

Length in bytes of the entry.

value

Value to associate with the database entry (e.g., alias translation value). Length of this string should not exceed DATA_LENGTH for a short database or LONG_DATA_LENGTH for a long database.

value_len

Length in bytes of the entry's value.

create_db

When true, create the database if it does not already exist.

replace

When true, replace the entry if one already exists in the database.

setbits

When true, set control bits associated with a personal alias database entry.

bits

Integer longword containing personal alias control bits.

DESCRIPTION

PMDF_database_add_entry adds an entry to a database. If the database is not already opened, it will be opened. When no more database accesses are to be performed, the database should be closed with PMDF_database_close. The specified entry and its associated value will be added to the database. If the database does not exist, then it will be created if create_db is true; otherwise, a PMDF__CANOPNDAT error will be returned and no database created. When a database is created, it will be created as a long database, if possible, and as a short database if not. If the specified entry already exists in the database, then it will be replaced if replace is true; otherwise, a PMDF__CANTUPDAT error will be returned and no entry added. The length of the entry and its value may not exceed, respectively, the key and data lengths used by the database. PMDF databases come in two sizes: short and long. A short database uses a key length of KEY_LENGTH and a data length of DATA_LENGTH. A long database uses a key length of LONG_KEY_LENGTH and a data length of LONG_DATA_LENGTH. The values of these constants are given in Table 1-2 . The database to use is specified with the database argument. The possible values for that argument are shown in Table 1-4 . In that table, the second column gives the symbolic names for the different databases, as defined in the API include files described in Section 1.11 . Whenever possible, programmers should use the symbolic names rather than the actual values.

Table 1-4 Database symbolic names and values

Database	Symbolic name	Value
Alias	PMDF_DATABASE_ALIAS	1
Domain	PMDF_DATABASE_DOMAIN	3
PMDF-MR FROM_MR	PMDF_DATABASE_FROM_MR	4
PMDF-X400 FROM_X400	PMDF_DATABASE_FROM_X400	5
General	PMDF_DATABASE_GENERAL	6
Personal alias	PMDF_DATABASE_PERSONAL_ALIAS	7
Address reversal	PMDF_DATABASE_REVERSE	8
PMDF-MR TO_MR	PMDF_DATABASE_TO_MR	9
PMDF-X400 TO_X400	PMDF_DATABASE_TO_X400	11
User profile	PMDF_DATABASE_USER_PROFILE	12
Popstore forward	PMDF_DATABASE_POPSTORE_FORWARD	13
Pipe	PMDF_DATABASE_PIPE	15
Forward	PMDF_DATABASE_FORWARD	16

The setbits and bits arguments are for use only with personal alias databases. When setbits is true, the control bits specified in the bit mask bits will be set for the alias. In this case, the length of value may not exceed DATA_LENGTH - 4 or LONG_DATA_LENGTH - 4. The bits in the bit mask bits control aspects of the alias and are shown in the table below:

Bit	Usage
PMDF_ALIAS_ADDRESS_BIT	Alias translation value is an address or mailing list
PMDF_ALIAS_FAX_BIT	Alias translation value is a FAX address
PMDF_ALIAS_PUBLIC_BIT	When set, alias is public; when clear, alias is private
PMDF_ALIAS_EXPAND_BIT	When set, alias is expanded in message headers; when clear, alias is not expanded
PMDF_ALIAS_RECEIPT_BIT	When set, receipts are allowed to pass through; when clear, receipts are blocked

PMDF_ALIAS_ADDRESS_BIT should always be set; otherwise, it will not be possible to manipulate the resulting alias from within the PMDF DB utility. PMDF_ALIAS_FAX_BIT should be set if the alias is to be manipulated from within PMDF DB's FAX mode. The API include files described in Section 1.11 provide values for the PMDF_ALIAS_ symbolic names.