приложения могут производить итерации по всем ключам в базе данных. Ключи не возвращаются в каком-то определенном порядке [180] , а базу данных не нужно модифицировать во время итераций, производимых приложением.
int dpiterinit(DEPOT * depot);
char * dpiternext(DEPOT * depot, int * keySize);
180
Вернее, они возвращаются в том порядке, в котором производятся ссылки на элементы из хеш-области. Хотя это и есть порядок, он является совершенно бесполезным.
В результате вызова функции
dpiterinit qdbm
вернет первый ключ в базе данных во время следующего вызова функции
dpiternext
.
Функция
dpiternext
возвращает указатель либо на первый ключ в базе данных (если только что была вызвана функция
dpiterinit
), либо ключ в базе данных, который следует за ключом, возвращенным в последний раз. Если же в базе данных больше не окажется ключей, будет возвращено
NULL
. Если
keySize
не равен
NULL
, то целочисленное значение, на которое указывает этот параметр, будет задано в качестве размера возвращаемого ключа.
Функция
dpiternext
буфера возвращает указатель на размещение, выполненное функцией
malloc
; после того как приложение завершит работу с ключом, указатель необходимо освободить функцией
free
. Буфер также завершается
NULL
, поэтому при необходимости его можно трактовать как строку.
25.4. Модификация базы данных
Предусмотрены две операции, которые модифицируют базу данных
qdbm
: добавление записей и удаление записей. Обновление записей производится с помощью той же функции, что и добавления записей.
25.4.1. Добавление записей
Новые и обновленные записи заносятся в базу данных с использованием функции
dpput
.
int dpput(DEPOT * dfepot, const char * key, int keySize, const char * data,
int dataSize, int dmode);
key
представляет собой значение индекса, который впоследствии может использоваться для получения информации, на которую указывает
data
. Параметры
keySize
и
dataSize
могут иметь значение
– 1
, при котором функция
dpput
будет использовать функцию
strlen
для получения размера данного поля. Проверка параметра
dmode
производится только в том случае, если параметр
key
в базе данных уже связан с элементом данных. Параметр
dmode
может иметь одно из перечисленных ниже значений.
DP_DCAT
Новые данные добавляются в конец данных, которые уже находятся в базе данных.
DP_DKEEP
База данных не модифицируется; функция
dpput
возвращает сбой, а параметру
dpecode
присваивается значение
DP_EKEEP
.
DP_DOVER
Вместо существующего значения записывается новое.
Функция
dpput
возвращает нулевое значение в случае возникновения ошибки (или если ключ уже существует, и было определено значение
DP_DKEEP
), и ненулевое значение, если данные для ключа были успешно обновлены.
25.4.2. Удаление записей
Удаление записей из базы данных осуществляется путем вызова функции
dpout
и передачи ей ключа, данные которого необходимо удалить.
int dpout(DEPOT * depot, const char * key, int keySize);
Заданный ключ и связанные с ним данные удаляются из базы, после чего возвращается ненулевое значение. Если для заданного ключа данные не существовали, возвращается нулевое значение. Как и для всех остальных функций, принимающих ключ, если параметр
keySize
равен
– 1
, то функция
dpout
использует
strlen
для определения длины ключа.
25.5. Пример
Для закрепления материала этой главы ниже приводится пример приложения, в котором задействовано большинство функциональных возможностей
qdbm
. Подразумевается, что в результате выполнения этого приложения будет создана простая база данных телефонных номеров, хотя ее можно использовать и для хранения любых простых пар "имя-значение". Приложение хранит базу данных в домашнем каталоге пользователя как
.phonedb
.
Флаг
– а
добавляет запись в базу данных. Если будет указан флаг
– f
, то любой существующий элемент будет заменен новыми данными. Следующий параметр представляет собой значение ключа, которое необходимо использовать, а последний параметр — собственно данные (номер телефона).
Флаг
– q
запрашивает в базе данных определенный ключ, который должен быть представлен другим указанным параметром. Записи удаляются из базы данных с помощью флага
– d
, который принимает значение ключа для удаления в другом параметре.
Если задать флаг
– l
, то будут перечислены все пары "ключ-значение", имеющиеся в базе данных.
