PMDF Programmer's Reference Manual
Previous Next Contents Index

PMDFdatabaseAddEntry

Add an entry to a database.

PASCAL

status = PMDF_database_add_entry

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

argument information
Argument Data type Access Mechanism
database signed longword read value
entry descriptor read reference
value descriptor read reference
create_db boolean read value
replace boolean read value
setbits boolean read value
bits unsigned longword read value

C

status = PMDFdatabaseAddEntry

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

argument information 


int PMDFdatabaseAddEntry(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

PMDFdatabaseAddEntry 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 PMDFdatabaseClose. 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 can 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 can 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.

Return Values

PMDF__OK Normal, successful completion.
PMDF__BAD Bad parameter value: illegal value specified for database.
PMDF__CANOPNDAT Database could not be opened. If it does not exist, then create_db must be true in order to force the creation of the database.
PMDF__CANTUPDAT Cannot update the database. Attempt to add or replace the entry failed.
PMDF__DUPENTRY Entry already exists and replace was false. No entry added.
PMDF__ENTWONFIT Length of entry or value too long for database. No entry added.
PMDF__INVSTRDES Invalid string descriptor for entry or value: one or both descriptors has an invalid value in its DSC$B_CLASS field. No entry added.
PMDF__STRTRUERR Supplied string entry or value is too long. No entry added.

Previous Next Contents Index