PMDF Programmer's Reference Manual
Previous Next Contents Index

PMDFdatabaseGetEntry

Lookup an entry in a database.

PASCAL

status = PMDF_database_get_entry

(database, access, entry, entry_len, value, value_len, bits)

argument information
Argument Data type Access Mechanism
database signed longword read value
access signed longword read value
entry descriptor read/write reference
entry_len unsigned word read/write reference
value descriptor write reference
value_len unsigned word write reference
bits unsigned longword write reference

C

status = PMDFdatabaseGetEntry

(database, access, entry, entry_len, value, value_len, bits)

argument information 


int PMDFdatabaseGetEntry(int                database, 
                         int                access, 
                         char              *entry, 
                         int               *entry_len, 
                         char              *value, 
                         int               *value_len, 
                         unsigned long int *bits)

Arguments

database

Database to search.

access

Type of search to perform.

entry

Entry to search for in the database. Length of this should be KEY_LENGTH for a short database or LONG_KEY_LENGTH for a long database. On output the actual entry read from the database will be returned in entry.

entry_len

On input, the length in bytes of the entry. On output, the length in bytes of the returned entry.

value

Value of the entry retrieved from the database. Length must be at least LONG_DATA_LENGTH bytes for PMDF_database_get_entry or LONG_DATA_LENGTH+1 bytes for PMDFdatabaseGetEntry.)

value_len

Length in bytes of the returned entry value. Callers using PMDFdatabaseGetEntry must, on input, supply the maximum length in bytes of value.

bits

Optional integer longword containing personal alias control bits associated with the returned value.

Description

PMDFdatabaseGetEntry can be called to find an entry in a database and return the value associated with the entry. If the database is not already opened, it will be opened. When no more database accesses are to be performed, it should be closed with PMDFdatabaseClose. The first time a given entry is to be located, access should have the value PMDF_DATABASE_GET_FIRST or PMDF_DATABASE_GET_FIRST_ROOT. If a matching entry is found, then the return status code will be PMDF__OK. If no match is found or the database could not be opened (e.g., does not exist), then PMDF__EOF will be returned. To search for any additional matching entries, make repeated calls specifying either PMDF_DATABASE_GET_NEXT or PMDF_DATABASE_GET_NEXT_ROOT for access. After no more matching entries can be found, a status code of PMDF__EOF will be returned. The access argument specifies the nature of the database search to perform. The possible values for access are shown in the table below. In that table, the second column gives the symbolic names for the different access types. These symbolic names are defined in the API include files described in Section 1.11. Whenever possible, programmers should use the symbolic names rather than the actual values.
Symbolic name Value Description
PMDF_DATABASE_GET_FIRST 1 Starting from the beginning of the database, find the first database entry which matches (case blind) entry.
PMDF_DATABASE_GET_NEXT 2 Continuing from the last located entry, find the next database entry which matches (case blind) entry.
PMDF_DATABASE_GET_FIRST_ROOT 3 Starting from the beginning of the database, find the first database entry whose first entry_len characters match (case blind) entry.
PMDF_DATABASE_GET_NEXT_ROOT 4 Continuing from the last located entry, find the next database entry whose first entry_len characters match (case blind) entry.
PMDF_DATABASE_GET_FIRST_ALL 5 Return the first entry from the database.
PMDF_DATABASE_GET_NEXT_ALL 6 Return the next entry from the database.
The bits argument is optional and only used in conjunction with personal alias databases. When an alias value is returned, any control bits associated with that alias will be returned in the bit mask bits. Consult the description of PMDFdatabaseAddEntry for details on this bit mask. To retrieve all entries from a database use PMDF_DATABASE_GET_FIRST_ALL and PMDF_DATABASE_GET_NEXT_ALL. See the description of PMDFdatabaseAddEntry for a list of the legal values for database.

Note
For each PMDF database, a single per-process read context is maintained by PMDF. As such, any sequence of chained PMDFdatabaseGetEntry calls must not be interrupted by other threads accessing the same database with PMDFdatabase calls. Any interruption will disrupt the read state. A chained sequence is one that starts with a PMDF_DATABASE_GET_FIRST or PMDF_DATABASE_GET_FIRST_ROOT access followed by either a PMDF_DATABASE_GET_NEXT or PMDF_DATABASE_GET_NEXT_ROOT access to find subsequent, related entries. to find subsequent, related entries.

Return Values

PMDF__OK Normal, successful completion.
PMDF__BAD Bad parameter value: illegal value specified for database or access. No database search performed; no value returned
PMDF__EOF No matching entry found; no value returned.
PMDF__FATERRLIB Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. No value returned.
PMDF__INSVIRMEM Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. No value returned.
PMDF__INVSTRDES Invalid string descriptor for entry or value: one or both descriptors has an invalid value in its DSC$B_CLASS field. No value returned.
PMDF__STRTRU Supplied string value is too short; output truncated to fit into string.
PMDF__STRTRUERR Supplied string entry is too long. No value returned.

Previous Next Contents Index