13.29. DATABASE

About
Functions order

13.29.1. About DATABASE

13.29.2. DATABASE functions order

AFIELDS() Заполняет массив информацией о структуре файла базы данных.
ALIAS() Возвращает алиас заданной рабочей области.
BOF() Определяет достижение начала файла.
BROWSE() Просматривает записи в заданном окне.
DBAPPEND() Добавляет новую запись.
DBCLEARFILTER() Снимает условие фильтрации базы данных, установленное командой SET FILTER.
DBCLEARINDEX() Закрывает все индексные файлы в текущей рабочей области..
DBCLEARRELATION() Уничтожает активные связи.
DBCLOSEALL() Закрывает все открытые рабочие области.
DBCLOSEAREA() Закрывает текущую рабочую область
DBCOMMIT() Записывает данные из буферов на диск
DBCOMMITALL() Записывает данные из буферов на диск для всех рабочих областей.
DBCREATE() Создает файл базы данных на основе информации о структуре базы данных,
DBCREATEINDEX() Создает индексный файл
DBDELETE() Помечает запись для удаления.
DBEDIT() Просматривает информацию записей в табличной форме.
DBEVAL() Выполняет блок кода для каждой записи, входящей в группу и отвечающей
DBF() Возвращает имя текущего алиаса.
DBFILTER() Возвращает текущее выражение фильтра в виде строки символов.
DBGOBOTTOM() Перемещает указатель на последнюю логическую запись.
DBGOTO() Перемещает указатель на запись с заданным номером.
DBGOTOP() Перемещает указатель на первую логическую запись.
DBRECALL() Восстанавливает запись, помеченную для удаления.
DBREINDEX() Воссоздает все активные индексы в текущей рабочей области.
DBRELATION() Возвращает скомпонованное выражение заданного отношения.
DBRSELECT() Возвращает номер рабочей области для заданного отношения.
DBSEEK() Перемещает указатель на запись, имеющую заданное ключевое значение.
DBSELECTAREA() Изменяет текущую рабочую область.
DBSETDRIVER() Возвращает имя используемого по умолчанию драйвера баз данных и
DBSETFILTER() Устанавливает фильтр.
DBSETINDEX() Открывает существующий индексный файл.
DBSETORDER() Устанавливает управляющий индекс.
DBSETRELATION() Устанавливает связь между двумя рабочими областями
DBSKIP() Перемещает указатель относительно текущей записи.
DBSTRUCT() Создает массив, содержащий информацию о структуре базы данных.
DBUNLOCK() Снимает все блокировки в текущей рабочей области.
DBUNLOCKALL() Снимает все блокировки для всех рабочих областей.
DBUSEAREA() Открывает файл базы данных в рабочей области.
DEFPATH() Возвращает правильный путь, установленный по SET DEFAULT.
DELETED() Возвращает признак, определяющий, подлежит запись удалению или нет.
DESCEND() Создает значение ключа для сортировки по убыванию.
DOSERROR() Возвращает номер последней ошибки DOS.
EOF() Определяет момент перехода за последнюю логическую запись файла базы данных.
FCOUNT() Возвращает число полей записи текущего (.dbf) файла.
FERROR() Проверяет наличие ошибок обработки двоичных файлов.
FIELDBLOCK() Создает блок кода для данного поля базы данных.
FIELDGET() Возвращает значение поля, используя порядковый номер поля в структуре
FIELDNAME() Возвращает имя поля из текущего (.dbf) файла.
FIELDPOS() Возвращает номер поля в рабочей области.
FIELDPUT() Записывает значение в поле, используя его номер в структуре.
FIELDWBLOCK() Возвращает блок кода для поля в данной рабочей области.
FILE() Определяет, существует ли файл в текущей xClipper директории или по
__FLEDIT() Отбирает из массива структуры DBStruct() элементы, указанные в списке.
FLOCK() Ограничивает доступ к открытому и совместно используемому файлу базы
FOUND() Определяет, успешна ли предшествующая операция поиска.
HEADER() Возвращает величину заголовка текущего файла базы данных.
INDEXEXT() Возвращает расширение имени индексного файла, принятое по умолчанию
INDEXKEY() Возвращает ключевое выражение для заданного индекса.
INDEXORD() Возвращает порядковый номер управляющего индекса.
LASTREC() Определяет число записей в текущей базе данных.
LUPDATE() Возвращает дату последнего изменения файла базы данных.
MEMOEDIT() Выводит на экран или редактирует символьные строки или memo-поля.
MEMOREAD() Возвращает содержимое дискового файла как строку символов.
MEMOWRIT() Записывает символьную строку или memo-поле в дисковый файл.
NETERR() Индицирует сбой выполнения команд при работе в сети.
ORDBAGEXT() Return the default order bag RDD extension
ORDBAGNAME() Return the order bag name of a specific order
ORDLISTADD() Add orders to the order list
RECCOUNT() Определяет количество записей в текущем файле (.dbf)
RECNO() Возвращает номер текущей записи рабочей области.
RECSIZE() Определяет длину записи файла базы данных (.dbf).
RLOCK() Блокирует текущую запись в активной рабочей области.
SELECT() Определяет номер рабочей области заданного алиаса.
USED() Определяет, есть ли в наличии открытый файл базы данных.
WEIGHTASC() Возвращает весовую характеристику символа.
WEIGHTTABLE() Возвращает весовую таблицу символов.

13.29.2.1. Function AFIELDS()

  AFIELDS([<массив имен полей>], [<массив типов полей>],
 [<массив размеров полей>], [<массив размеров дробной части>])
 --> количество полей
 
 

13.29.2.1.3. Description

AFIELDS() - функция, которая заполняет группу массивов информацией о структуре активного в данный момент файла базы данных; элементы массивов с одним номером содержат при этом информацию об одном поле. AFIELDS() во многом схожа с функцией ADIR(), заполняя группу созданных массивов информацией. Чтобы воспользоваться функцией AFIELDS(), нужно сначала создать массивы одинаковой длины, в которые будет занесена информация о структуре файла базы данных, при этом количество элементов в них должно соответствовать количеству полей в записи файла базы данных (т.е.FCOUNT()). После того, как эти массивы созданы, можно использовать AFIELDS() для заполнения их данными о полях файла базы данных.

По умолчанию AFIELDS() обрабатывает активную рабочую область, однако при помощи AFIELDS() можно обрабатывать и пассивную рабочую область. Для этого необходимо использовать уточненное алиасом выражение (см. пример ниже).

AFIELDS() - функция, используемая для связи с предыдущей версией xClipper. Она может быть заменена функцией DBSTRUCT(), которая не требует создания группы массивов перед ее использованием и возвращает многомерный массив, содержащий данные о структуре файла текущей базы данных.

13.29.2.2. Function ALIAS()

 ALIAS([<номер рабочей области>]) --> алиас

13.29.2.3. Function BOF()

 BOF() --> признак начала файла

13.29.2.3.3. Description

BOF() - функция работы с базами данных, которая используется для проверки условия достижения границ файла при перемещении указателя записи в обратном направлении при помощи команды SKIP. Простой пример использования - это просмотр по убыванию значения ключа записей при индексации по возрастанию. Более наглядным примером может служить программа работы с экранными страницами, которая выдает на экран страницы изображения в прямом или обратном порядке в зависимости от нажатой пользователем клавиши. Когда пользователь начинает просматривать страницы в обратном порядке, можно использовать функцию BOF() для проверки условия достижения указателя записи начала файла перед использованием команды SKIP для передвижения указателя записи и перерисовки экрана.

После того, как функцией BOF() будет установлено значение "истина" (.T.), оно остается до тех пор, пока не будет сделана очередная попытка передвижения указателя записи.

По умолчанию функция BOF() выполняется для текущей активной рабочей области. Однако ее можно применить и для пассивной рабочей области, используя ее в выражении, уточненном алиасом ( см. пример ниже ).

Команда SKIP является единственной командой, которая может установить значение BOF() "истина" (.T.).

13.29.2.10. Function DBCLOSEAREA()

 DBCLOSEAREA() --> NIL

13.29.2.13. Function DBCREATE()

 DBCREATE(<имя базы данных>, <структура>) --> NIL

13.29.2.13.3. Description

DBCREATE() - функция работы с базой данных, которая создает файл базы данных на основе информации массива, содержащего описание структуры его записи. Массив может быть создан программным путем при использовании функции DBSTRUCT().

DBCREATE() аналогична команде CREATE FROM, которая создает новый файл базы данных по данным дополнительного файла о структуре записи. Дополнительный файл с информацией о структуре записи можно сформировать при помощи либо CREATE, либо COPY STRUCTURE EXTENDED.

Перед использованием функции DBCREATE() требуется создать массив <структура> и заполнить его информацией, описывающей атрибуты полей в соответствии с таблицей 5-7. При создании подмассива описания поля необходимо руководствоваться следующими правилами:

Все атрибуты поля должны быть определены в соответствии с типом данных. Атрибут, задающий количество знаков после десятичной точки, должен быть определен даже для нецифровых полей. Если поле не имеет атрибута, определяющего количество знаков после десятичной точки, необходимо задавать его значение 0.

Тип атрибута необходимо задавать, используя как минимум первую букву типа данных. Более полно тип атрибута может быть назван для облегчения чтения программы. Например, для указания строки символов можно использовать и "C", и "Character".

В xClipper символьные поля могут иметь длину до 64 килобайт. В отличие от команды CREATE FROM, функция DBCREATE() не использует атрибут, задающий количество знаков после десятичной точки для определения величины целой части поля.

Для того, чтобы сделать ссылки на различные элементы подмассива описаний поля более удобочитаемыми, используется файл описаний с именем dbstruct.ch, который содержит описания имен позиций в массиве для каждого элемента, определяющего атрибут поля. Этот файл находится в директории \include.

13.29.2.14. Function DBCREATEINDEX()

 DBCREATEINDEX( <имя индексного файла>,<ключевое выражение>
 ,[<блок кода>],[<признак индексации>] ) --> NIL

13.29.2.16. Function DBEDIT()

 DBEDIT([<верхняя строка>],[<левая колонка>],
 [<нижняя строка>],[<правая колонка>],
 [<массив колонок>],
 [<функция пользователя>],
 [<массив SAY-шаблонов>] | [<SAY-шаблон>],
 [<массив заголовков колонок>] | [<заголовок колонок>],
 [<массив гор. разделителей>] | [<гор. разделитель>],
 [<массив верт. разделителей>] | [<верт. разделитель>],
 [<массив под. разделителей>] | [<под. разделитель>],
 [<массив строк подписей>] | [<строка подписей>] ) --> NIL

13.29.2.16.1. Arguments

<верхняя строка>, <левая колонка>, <нижняя строка>, <правая колонка>
  определяют координаты верхнего левого и нижнего правого углов окна
  работы функции DBEDIT(). Значения номеров строк могут изменяться в
  пределах от 0 до MAXROW(). Если эти параметры опущены, то по
  умолчанию принимается, что координаты окна - 0, 0, MAXROW() и
  MAXCOL().
  
<массив колонок> - массив, содержащий символьные выражения,
  представляющие собой имена полей базы данных или, другими словами,
  выражения, используемые как значения колонок для каждой выводимой
  строки. Если этот аргумент не определен, DBEDIT() выводит информацию
  всех полей базы данных текущей рабочей области, размещая ее по
  колонкам.
  
<функция пользователя> - имя функции пользователя, которой передается
  управление при нажатии неопределенной клавиши или если клавиша не
  нажата. Имя функции определяется в виде символьного выражения без
  круглых скобок и аргументов. Отметим, что поведение функции DBEDIT()
  зависит от того, определена функция пользователя или нет. Более
  подробно этот вопрос рассматривается ниже.
  
<массив SAY-шаблонов> - это параллельный массив, содержащий
  предложения PICTURE для форматирования каждой колонки. Если
  определить <массив SAY-шаблонов> не в виде массива, а в виде строки
  (<SAY-шаблон>), информация всех колонок будет выводиться в одном и
  том же формате. Более подробная информация о предложении PICTURE
  находится в описании функции TRANSFORM() и команды @...SAY.
  
<массив заголовков колонок> - параллельный массив, содержащий
  символьные выражения, которые определяют заголовки каждой колонки.
  Для выдачи заголовков для отдельных колонок необходимо включить точку
  с запятой в выражение заголовка там, где требуется разорвать
  последовательность. Если параметр не задан, заголовки колонок
  выбираются из массива <массив колонок> или заполняются именами полей
  текущей рабочей области, если массив <массив колонок> также не задан.
  
<массив гор. разделителей> - параллельный массив, состоящий из
  символьных выражений, который определяет символы, используемые для
  рисования горизонтальных линий, отделяющих заголовки колонок от
  области выдачи информации полей. Если <гор. разделитель> задать не в
  виде массива, для отделения всех колонок будет использован один и тот
  же разделитель. Если аргумент не задан, по умолчанию принимается
  разделителем двойная линия.
  
<массив верт. разделителей> - это параллельный массив, содержащий
  символьные выражения, символы, используемые для рисования
  вертикальных линий, разделяющих колонки. Если задать <верт.
  разделитель> не в виде массива, будет использован один и тот же
  разделитель для всех колонок. Если аргумент не задан, по умолчанию
  принимается вертикальная линия.
  
<массив под. разделителей> - параллельный массив, содержащий
  символьные выражения, которые определяют символы, используемые для
  рисования разделителей между завершающими колонки подписями и
  информацией полей. Если параметр задается не в виде массива, для всех
  колонок используется один и тот же разделитель. Если аргумент не
  задан, по умолчанию принимается отсутствие разделителя (пробел).
  
<массив строк подписей> - параллельный массив, содержащий символьные
  выражения, завершающие подписи для каждой колонки. Если аргумент
  задать не в виде массива, в качестве завершающей подписи для всех
  колонок будет использоваться одно и то же значение.

13.29.2.16.3. Description

DBEDIT() - это функция взаимодействия программы с пользователем, которая выдает информацию записей из одной или более рабочих областей в табличной форме. Окно для выдачи информации функцией DBEDIT() делится на ячейки, формирующие колонки и строки. Колонки соответствуют полям баз данных, строки соответствуют записям.

Каждая колонка определена элементом массива <массив колонок>. Ширина каждой колонки определяется значением соответствующего элемента <массив колонок> или заданным значением предложения PICTURE в массиве <массив SAY-шаблонов>.

DBEDIT() поддерживает все клавиши управления курсором, включая <PgDn>, <PgUp>, <Home>, <End>, четыре клавиши со стрелками и все комбинации клавиши <Ctrl>, при помощи которых осуществляется управление курсором. Список клавиш управления курсором, если не задана функция пользователя, представлен в таблице 5-8. Если задан аргумент, определяющий имя функции пользователя (<функция пользователя>), все клавиши, представленные в таблице 5-8 активны также в сочетании с клавишами <Esc> и <Enter>. Когда DBEDIT() вызывает функцию пользователя, ей автоматически передается два аргумента:

Текущий режим, передаваемый как арифметическое выражение.

Индекс текущей колонки в <массив колонок>, передаваемый как арифметическое значение.

Первый параметр определяет текущее состояние DBEDIT() в зависимости от последней нажатой клавиши. Перечень возможных состояний приведен в таблице 5-9.

Второй параметр указывает на позицию описания в массиве <массив колонок>. Если массив <массив колонок> не определен, параметр указывает на позицию поля в структуре текущей базы данных. Получить имя поля можно при помощи функции FIELDNAME().

Активные клавиши DBEDIT().
 ---------------------------------------------------------------------
 Ключ                       Действие
 ---------------------------------------------------------------------
 <Стрелка вверх>            Вверх на одну строку
 <Стрелка вниз>             Вниз на одну строку
 <Стрелка влево>            Влево на колонку
 <Стрелка вправо>           Вправо на колонку
 <Ctrl>-<Стрелка влево>     Влево в пределах колонки
 <Ctrl>-<Стрелка вправо>    Вправо в пределах колонки
 <Home>                     Крайняя левая колонка текущего экрана
 <End>                      Крайняя правая колонка текущего экрана
 <Ctrl>-<Home>              Крайняя левая колонка
 <Ctrl>-<End>               Крайняя правая колонка
 <PgUp>                     Предыдущий экран
 <PgDn>                     Следующий экран
 <Ctrl>-<PgUp>              Первая строка текущей колонки
 <Ctrl>-<PgDn>              Последняя строка колонки
 <Enter>                    Завершить DBEDIT()
 <Esc>                      Завершить DBEDIT()
 ---------------------------------------------------------------------
 

Режимы DBEDIT().
 ---------------------------------------------------------------------
 Статус  Dbedit.ch      Описание
 ---------------------------------------------------------------------
 0       DE_IDLE        Режим ожидания, все коды клавиш обработаны
 и буфер пуст
 1       DE_HITTOP      Попытка перевода курсора выше начала файла
 2       DE_HITBOTTOM   Попытка перевода курсора ниже конца файла
 3       DE_EMPTY       Нет записей в рабочей области
 4       DE_EXCEPT      Ключ прерывания
 ---------------------------------------------------------------------
 

Значения, возвращаемые функцией пользователя.
 ---------------------------------------------------------------------
 Значение   Dbedit.ch      Описание
 ---------------------------------------------------------------------
 0          DE_ABORT       Прервать DBEDIT()
 1          DE_CONT        Продолжить DBEDIT()
 2          DE_REFRESH     Обновить экран, обработать нажатые клавиши,
 затем перейти в режим ожидания
 ---------------------------------------------------------------------
 

После вызова функции пользователя DBEDIT() ожидает от нее возврата значения, которое укажет, как действовать дальше. В таблице 5-10 сведены все возможные значения, возвращаемые функцией пользователя, и соответствующие им действия. Функция пользователя вызывается в следующих случаях:

Возникло прерывание по нажатию клавиши. Это происходит, когда DBEDIT() получает из буфера клавиатуры нераспознаваемую последовательность кодов. Эта последовательность остается в буфере клавиатуры до тех пор, пока не считана функцией пользователя или пока DBEDIT() не продолжит свою работу.

DBEDIT() перешла в режим ожидания (Idle), т.е. когда все коды буфера клавиатуры обработаны. Это происходит, когда буфер клавиатуры пуст или после обновления изображения на экране. В этом случае происходит один вызов функции пользователя и затем DBEDIT() ожидает нажатия клавиши.

Обнаружены начало или конец файла. Это тот же режим, что и режим ожидания. Все выполнимые клавиши обрабатываются и производится один вызов функции пользователя с передачей ей текущего статуса.

Когда DBEDIT() выполняется первый раз, обрабатываются все ключи буфера клавиатуры, и DBEDIT() выходит в режим ожидания с вызовом функции пользователя. Если буфер клавиатуры при вызове DBEDIT() пуст, она сразу же выходит в режим ожидания.

При разработке функции пользователя необходимо предусмотреть анализ всех режимов работы DBEDIT() с организацией соответствующих реакций на них.

Функция DBEDIT() полностью реентерабельна, т.е. можно организовывать ее вложенный вызов. Благодаря этому возможен многооконный просмотр информации.

Функция DBEDIT() оставлена для совместимости с предыдущими версиями xClipper и потому ее использование в программах не рекомендуется. Для этих целей она должна быть заменена классом объектов TBrowse. Более подробную информацию вы найдете в главе "Стандартные классы".

13.29.2.17. Function DBEVAL()

 DBEVAL(<блок кода>,[<FOR-лог.условие>],[<WHILE-лог. условие>],
 [<к-во записей>],[<номер записи>],[<переключатель>]) --> NIL

13.29.2.17.1. Arguments

<блок кода> - это блок кода, выполняемый для каждой обрабатываемой
  записи.
  
<FOR-лог.условие> - это необязательное условие, определенное как блок
  кода, который выполняется для каждой записи в группе. Он выполняет те
  же функции, что и предложение FOR в командах обработки записей.
  
<WHILE-лог. условие> - это необязательное условие, определенное как
  блок кода, который выполняется для каждой записи, начиная с текущей
  и до тех пор, пока условие не примет значение "ложь" (.F.). Он
  выполняет те же функции, что и предложение WHILE в командах обработки
  записей.
  
<к-во записей> - это необязательный аргумент, определяющий
  количество записей, вовлекаемых в обработку, начиная с текущей.
  Он работает аналогично предложению NEXT.
  
<номер записи> - это необязательный аргумент, определяющий номер
  обрабатываемой записи. Если этот параметр определен, блок кода
  выполняется для этой заданной записи. Он работает аналогично
  предложению RECORD.
  
<переключатель> - это необязательный логический аргумент,
  определяющий, начинается ли группа записей, обрабатываемых
  DBEVAL(), с текущей записи и завершается в конце файла, или
  на обработку передается весь файл. Этот аргумент аналогичен
  предложению REST и ALL в командах обработки записей. Если его
  значение "истина" (.T.), то величина группы аналогична REST,
  в противном случае - ALL ( все записи). Если аргумент не задан,
  по умолчанию принимаются все записи файла.
  
  

13.29.2.17.3. Description

DBEVAL() - это функция работы с базами данных, выполняющая блок кода для каждой записи, которая входит в определенную группу и (или) удовлетворяет заданному условию в текущей рабочей области. При каждой итерации DBEVAL() выполняет заданный блок. Все записи, входящие в группу или соответствующие условию, обрабатываются до тех пор, пока не будет достигнут конец файла. По умолчанию DBEVAL() работает с активной (текущей) рабочей областью. Однако можно заставить DBEVAL() работать с пассивной рабочей областью. Это достигается заданием выражения, уточненного алиасом. DBEVAL() работает аналогично функции AEVAL(), которая обрабатывает каждый элемент массива. Так же, как AEVAL(), DBEVAL() может быть использована в качестве примитива для построения команд пользователя, обрабатывающих файлы баз данных. Многие стандартные команды xClipper, обрабатывающие файлы баз данных, созданы с помощью DBEVAL().

Обратитесь к разделу "Блоки кода" в главе "Основные концепции" за более полной информацией по синтаксису и теории создания блоков кода. Обратитесь также к разделу "Система баз данных" в главе "Основные концепции" за более полной информацией о группировке записей и задании условий их выбора. Просмотрите стандартный файл описаний std.ch, находящийся в директории \include, куда включены примеры описаний стандартных команд обработки файлов баз данных xClipper, которые используют функцию DBEVAL().

13.29.2.17.4. Example

  Этот пример использует DBEVAL() как инструмент в функции
 пользователя COUNT(), предназначенной для подсчета количества
 записей в рабочей области в заданной группе. Условия выбора группы
 передаются функции COUNT() в виде массива. Для того, чтобы этот
 пример был еще более интересным, в нем используется команда
 пользователя, которая создает массив, задающий группу записей, тем
 самым позволяя сформировать условие выбора группы более простым
 способом. В пример также включены описания явных констант, которые
 определяют атрибуты объекта группы:
 
 // Описание команды
 //
 #command CREATE SCOPE <aScope> [FOR<for>] [WHILE<while>];
 [NEXT<next>] [RECORD<rec>] [<rest:REST>] [ALL];
 =>;
 aScope := { <{for}>, <{while}>, <next>, <rec>, <.rest.> }
 //
 // Описание констант
 //
 #define FOR_COND    1
 #define WHILE_COND  2
 #define NEXT_SCOPE  3
 #define REC_SCOPE   4
 #define REST_SCOPE  5
 //
 // Создание группы записей и расчет количества записей в ней
 //
 LOCAL mySet, myCount
 USE Customer NEW
 CREATE SCOPE mySet FOR Customer = "Smith" WHILE Zip > "90000"
 myCount = Count( mySet )
 RETURN
 
 FUNCTION Count( aScope )
 LOCAL Count := 0
 DBEVAL( { || nCount++,;
 aScope[ FOR_COND ],;
 aScope[ WHILE_COND ],;
 aScope[ NEXT_SCOPE ],;
 aScope[ REC_SCOPE ],;
 aScope[ REST_SCOPE ];
 } )
 RETURN nCount
 
 

13.29.2.19. Function DBFILTER()

 DBFILTER() --> значение фильтра

13.29.2.25. Function DBRELATION()

 DBRELATION(<номер отношения>) --> выражение связи

13.29.2.26. Function DBRSELECT()

 DBRSELECT(<номер отношения>) --> номер рабочей области

13.29.2.27. Function DBSEEK()

 DBSEEK(<выражение поиска>,
 [<признак относительного поиска>]) --> признак завершения

13.29.2.27.3. Description

DBSEEK() - перемещает указатель на первую логическую запись, ключевое значение которой равно <выражение поиска>. Если такая запись найдена, то она становится текущей записью, и DBSEEK() возвращает "истина" (.T.). В противном случае DBSEEK() возвращает "ложь" (.F.), а указатель перемещается следующим образом: при нормальном (не относительном) поиске указатель установится на записи с номером LASTREC() + 1, и функция EOF() возвратит "истина" (.T.). При относительном поиске указатель установится на первой записи, ключевое значение которой больше, чем заданное ключевое значение. Если такой записи не существует, указатель установится на записи с номером LASTREC()+1, и функция EOF() возвратит значение "истина" (.T.)

Функция DBSEEK() может применяться рабочей области, где есть активные индексы.

DBSEEK() выполняет те же функции, что и стандартная команда SEEK. Более подробную информацию смотрите в команде SEEK.

13.29.2.29. Function DBSETDRIVER()

 DBSETDRIVER([<драйвер>]) --> текущий драйвер

13.29.2.30. Function DBSETFILTER()

 DBSETFILTER(<условие - блок кода>,[<текст условия>]) --> NIL

13.29.2.30.3. Description

DBSETFILTER() устанавливает логическое условие фильтра для текущей рабочей области. Когда фильтр установлен, записи, не удовлетворяющие условию фильтра, логически не видны. То есть, операции, обрабатывающие логические записи, такие записи не рассматривают.

Выражение фильтра, задаваемое при вызове функции DBSETFILTER(), должно при вычислении для записей, удовлетворяющих условиям фильтра, давать результат "истина" (.T.) и "ложь" (.F.) в противном случае.

Выражение фильтра может быть представлено или как один блок кода <условие - блок кода>, или как блок кода и эквивалентный <текст условия>, выражающие одинаковые условия. Если второй аргумент отсутствует, то функция DBFILTER() будет возвращать пустую строку.

DBSETFILTER() выполняет те же функции, что и стандартная команда SET FILTER. Более подробную информацию смотрите в команде SET FILTER.

13.29.2.31. Function DBSETINDEX()

 DBSETINDEX( <имя индексного файла> ) --> NIL

13.29.2.32. Function DBSETORDER()

 DBSETORDER( <номер индексного файла> ) --> NIL

13.29.2.33. Function DBSETRELATION()

 DBSETRELATION( <номер области> | <алиас>,
 <выражение - блок кода>,
 [<текстовое выражение>] )   -->  NIL

13.29.2.33.3. Description

DBSETRELATION() - связывает рабочую область, определенную при помощи <номер области> или <алиас> (дочернюю рабочую область) с текущей рабочей областью (родительская рабочая область). Все активные отношения связи остаются активными.

Установленная связь между двумя рабочими областями заставляет дочернюю рабочую область работать синхронно с родительской рабочей областью. Это достигается автоматическим перемещением указателя записей в дочерней рабочей области всякий раз, когда указатель в родительской рабочей области перемещается на новую запись. Если дочерняя рабочая область имеет активный индекс, то перемещение указателя в родительской рабочей области заставляет автоматически работать команду SEEK в дочерней рабочей области. При этом ключ поиска является результатом вычисления заданного <выражение - блок кода>. Если дочерняя рабочая область не имеет активного индекса, то перемещение указателя в родительской рабочей области заставляет автоматически работать команду GOTO в дочерней рабочей области. При этом номер записи для GOTO является результатом вычисления <выражение - блок кода>.

Выражение отношения может быть задано или как одно <выражение - блок кода>, или как два аргумента: <выражение - блок кода> и эквивалентный ему <текст выражения>. Если текстовый вариант не задан, то функция DBRELATION() будет возвращать пустую строку.

DBSETRELATION() выполняет те же функции, что и стандартная команда SET RELATION с предложением ADDITIVE. Более подробную информацию смотрите в команде SET RELATION.

13.29.2.34. Function DBSKIP()

 DBSKIP(<кол-во записей>) --> NIL

13.29.2.35. Function DBSTRUCT()

 DBSTRUCT() -> массив, содержащий структуру

13.29.2.37. Function DBUNLOCKALL()

 DBUNLOCKALL() --> NIL

13.29.2.38. Function DBUSEAREA()

 DBUSEAREA( [<признак новой области>], [<драйвер>], <имя>,
 [<алиас>], [<совместный доступ>],
 [<только чтение>] )  --> NIL

13.29.2.38.1. Arguments

<признак новой области> - необязательное логическое значение.
  Значение "истина" (.T.) определяет, что текущей рабочей областью
  перед открытием базы данных становится неиспользуемая рабочая область
  с наименьшим номером. Если <признак новой области> - "ложь" (.F.) или
  опущен, используется текущая рабочая область. Если в этой рабочей
  области уже есть открытый файл базы данных, то он закрывается.
  
<драйвер> - необязательная символьная величина. Если присутствует,
  то она определяет имя драйвера баз данных, который будет
  использоваться в рабочей области. Если <драйвер> опущен, то по
  умолчанию используется текущий драйвер (см. замечание ниже).
  
<имя> - определяет имя открываемой базы данных (.dbf).
  
<алиас> - необязательная символьная величина. Если присутствует,
  то она определяет алиас, связанный с рабочей областью. Алиас должен
  быть допустимым в xClipper идентификатором. Если <алиас> опущен, то
  значение алиаса такое же, как <имя>.
  
<совместный доступ> - необязательная логическая величина. Если
  аргумент присутствует, то он определяет, открывается ли база данных в
  режиме доступности для других процессов в сети. Значение "истина"
  (.T.) определяет, что другие процессы могут иметь доступ, а значение
  "ложь" (.F.) определяет, что текущий процесс должен иметь монопольный
  доступ. Если <совместный доступ> опущен, то текущая глобальная
  установка _SET_EXLUSIVE определяет, разрешен ли совместный доступ к
  файлам баз данных.
  
<только чтение> - необязательная логическая величина, которая
  определяет, запрещены ли изменения данных в рабочей области.
  Значение "истина" (.T.) определяет запрет изменений, а "ложь"
  (.F.) - разрешение. Если аргумент <только чтение> опущен, то
  предполагается значение "ложь" (.F.).

13.29.2.39. Function DELETED()

 DELETED() --> признак удаления

13.29.2.40. Function DESCEND()

 DESCEND(<выражение>) --> дополнение выражения

13.29.2.41. Function EOF()

 EOF() --> признак конца файла

13.29.2.41.3. Description

EOF() - это функция работы с базами данных, которая используется для проверки, не достиг ли указатель записи конца файла при его движении вперед по файлу базы данных. Все команды, передвигающие указатель записи, могут изменять значение EOF().

Наиболее типичным случаем использования EOF() является ее включение в качестве аргумента условия <лог. условие> конструкции DO WHILE при последовательной обработке записей файла базы данных. В этом случае <лог. условие> должно включать проверку на .NOT.EOF(), заставляя цикл завершаться в том случае, когда EOF() возвращает значение "истина" (.T.).

Функции EOF() и FOUND() могут быть взаимозаменяемыми при проверке успешности выполнения команд SEEK, FIND или LOCATE. Однако в этом случае более предпочтительной является функция FOUND().

Когда функция EOF() возвращает значение "истина" (.T.), указатель записи устанавливается на значение LASTREC() + 1 независимо от того, было ли активно предложение SET FILTER или командой SET DELETED установлен режим ON. При дальнейших попытках передвижения указателя записи вперед значение EOF() будет оставаться неизменным и ошибки времени выполнения не будет. Значение "истина" (.T.), установленное функцией EOF(), не изменится до следующей попытки передвижения указателя записи.

По умолчанию функция EOF() работает с файлом базы данных в текущей (активной) рабочей области. Однако она может быть использована с файлом базы данных пассивной рабочей области. В этом случае EOF() должна быть частью выражения, уточненного алиасом (смотри пример ниже).

13.29.2.42. Function FCOUNT()

 FCOUNT() --> число полей

13.29.2.43. Function FIELDGET()

 FIELDGET(<номер поля>)  --> значение поля

13.29.2.44. Function FIELDNAME()

 FIELDNAME(<номер позиции>) --> имя поля

13.29.2.44.3. Description

FIELDNAME() является функцией обработки баз данных. Она возвращает имя поля, порядковый номер которого в структуре записи соответствует позиции, заданной в качестве его индекса.

Обычно она используется в прикладных программах, когда неизвестны имена полей. Если требуется получить имена сразу нескольких полей, удобнее использовать функцию AFIELDS(), так как она создает массив с именами полей, или команду COPY STRUCTURE EXTENDED, создающую базу данных с информацией о полях.

Если необходима дополнительная информация о структуре файла базы данных для совместной обработки, можно использовать функции TYPE() и LEN(). Для получения количества цифр после десятичной запятой в числовых полях, можно использовать следующее выражение:

LEN(SUBSTR(STR(<имя поля>), RAT(".", STR(<имя поля>)) + 1))

По умолчанию функция FIELDNAME() обрабатывает файл в текущей (активной) рабочей области. Однако для обработки файла в пассивной рабочей области необходимо ее включить в уточненное алиасом выражение, как показано в примере ниже.

13.29.2.45. Function FIELDPOS()

 FIELDPOS(<имя поля>)  --> номер поля

13.29.2.46. Function FIELDPUT()

 FIELDPUT(<номер поля>,<выражение>)  --> присвоенное значение

13.29.2.47. Function FLOCK()

 FLOCK() --> признак завершения

13.29.2.47.3. Description

FLOCK() является функцией обработки баз данных, которая используется в сетевой среде для захвата открытого и совместно используемого файла базы данных, чтобы не давать другим пользователям возможности изменить файл до тех пор, пока не будет снят запрет. Однако записи в захваченном файле остаются доступными другим пользователям только для чтения.

По своим действиям FLOCK() похожа на команду USE...EXCLUSIVE и функцию RLOCK(). USE...EXCLUSIVE открывает файл базы данных так, чтобы никакой другой пользователь не мог открыть тот же самый файл в то же самое время, и является наиболее грубым механизмом захвата базы данных в xClipper. Функция RLOCK() - в этом смысле более гибкая, так как распространяет запрет на изменение только одной совместно используемой записи. FLOCK() находится посередине.

Как правило, FLOCK() используется совместно с операциями, обрабатывающими все записи файла базы данных. Обычно это команды, которые имеют дело с группой записей или выбирают их по условию, такие, например, как DELETE или REPLACE ALL. Ниже приводится список таких команд:

Команды, которые требуют FLOCK().
 ---------------------------------------------------------------------
 Команда                         Режим
 ---------------------------------------------------------------------
 APPEND FROM                     FLOCK() или USE...EXCLUSIVE
 DELETE (несколько записей)      FLOCK() или USE...EXCLUSIVE
 RECALL (несколько записей)      FLOCK() или USE...EXCLUSIVE
 REPLACE (несколько записей)     FLOCK() или USE...EXCLUSIVE
 UPDATE ON                       FLOCK() или USE...EXCLUSIVE
 ---------------------------------------------------------------------
 

При каждом вызове функция FLOCK() предпринимает попытку заблокировать файл базы данных и возвращает логическое значение результата этой попытки.

Захват файла не может быть осуществлен, если в это же время другой пользователь захватил весь файл или какую-либо запись этого файла базы данных, или при открытии файла была применена команда EXCLUSIVE USE. Если функция FLOCK() завершилась успешно, блокировка файла сохраняется до тех пор, пока вы не выполните команды UNLOCK, CLOSE, DATABASE или функцию RLOCK().

По умолчанию FLOCK() действует в текущей (активной) рабочей области, но может действовать и в пассивной рабочей области путем включения ее в выражение, уточненное алиасом, как показано в примере, приведенном ниже.

13.29.2.48. Function FOUND()

 FOUND() --> признак завершения операции поиска

13.29.2.48.3. Description

FOUND() является функцией обработки баз данных, позволяющей определить, является ли операция поиска (выполняемая командами FIND, LOCATE, CONTINUE, SEEK, SET RELATION) успешной. По выполнении какой-либо из этих команд, FOUND() устанавливает значение "истина"(.Т.), если поиск был успешным; в противном случае она возвращает значение "ложь"(.F.).

Если командами поиска являются LOCATE или CONTINUE, их завершение считается успешным, если они встретят следующую запись, совпадающую с условием поиска в заданной группе. Если командами поиска являются FIND, SEEK или SET RELATION, их завершение считается успешным, когда будет найден первый ключ в управляющем индексе, совпадающий с заданным аргументом поиска. Если команда SET SOFTSEEK устанавливает режим ON, указатель записи перемещается на запись, значение ключа которой больше, чем аргумент поиска или равно ему. Если значение ключа равно аргументу поиска, FOUND() принимает значение "истина"(.Т.); в противном случае, она принимает значение "ложь"(.F.).

Значение функции FOUND() сохраняется до тех пор, пока не выполнится другая команда по перемещению указателя записи. Если эта команда не является командой поиска, функция FOUND() автоматически принимает значение "ложь"(.F.).

Для каждой рабочей области можно получить значение функции FOUND(). Это означает, что если какая-либо рабочая область связана отношением с дочерней рабочей областью при помощи команды SET RELATION, запрос FOUND() для дочерней рабочей области возвратит значение "истина"(.Т.) в том случае, если поиск был успешным.

По умолчанию функция FOUND() анализирует активную рабочую область. Однако для анализа необходимо включить ее в уточненное алиасом выражение (см. пример ниже).

13.29.2.49. Function HEADER()

 HEADER() --> количество байтов

13.29.2.51. Function INDEXKEY()

 INDEXKEY(<номер индекса>) --> выражение ключа

13.29.2.51.3. Description

INDEXKEY() - это функция обработки баз данных, определяющая ключевое выражение заданного индекса в текущей рабочей области и возвращающая его как символьную строку. Для расчета ключевого выражения задайте INDEXKEY() как макровыражение:

INDEXKEY(<номер индекса>).

INDEXKEY() имеет ряд приложений, но на ум сразу же приходят два специфических примера. Используя INDEXKEY(), вы можете выполнить команду TOTAL по ключевому выражению управляющего индекса, не задавая ключевого выражения в исходном тексте. Другой пример вы найдете, рассматривая функцию пользователя DBEDIT(). Здесь вы можете определить, обновлять экран или нет после того, как пользователь отредактирует запись. Обычно необходимо обновить экран только если изменилось ключевое выражение управляющего индекса для текущей записи. Оба эти примера иллюстрируются ниже.

По умолчанию INDEXKEY() действует в выбранной (активной) в текущий момент рабочей области. Можно сделать так, чтобы эта функция действовала в пассивной рабочей области, используя ее как элемент выражения, уточненного алиасом( смотри пример ниже ).

13.29.2.51.4. Example

 Этот пример демонстрирует, как получить доступ к ключевым
 выражениям индексов, открытых в текущей рабочей области:
 
 #define ORD_NATURAL    0
 #define ORD_NAME       1
 #define ORD_SERIAL     2
 //
 USE Customer INDEX Name, Serial NEW
 SET ORDER TO ORD_SERIAL
 ? INDEXKEY(ORD_NAME)            // Результат: Name index exp
 ? INDEXKEY(ORD_SERIAL)          // Результат: Serial index exp
 ? INDEXKEY(ORD_NATURAL)         // Результат: Serial index exp
 
 Этот пример показывает, как получить доступ к ключевому выражению
 управляющего индекса в пассивной рабочей области:
 
 USE Customer INDEX Name, Serial NEW
 USE Sales INDEX Salesman NEW
 INDEXKEY(0), Customer-> (INDEXKEY(0))
 
 Этот пример иллюстрирует использование INDEXKEY() в качестве части
 ключевого выражения в команде TOTAL. Заметим, что INDEXKEY() задана
 с использованием макровыражения, чтобы вызвать вычисление этого
 выражения:
 
 USE Sales INDEX Salesman NEW
 TOTAL ON &amp;(INDEXKEY(0)) FIELDS SaleAmount TO SalesSummary
 
 Этот пример демонстрирует, как можно использовать функцию
 INDEXKEY() для определения, должен ли обновляться экран в процессе
 выполнения функции DBEDIT() после того, как пользователь
 отредактировал текущее значение поля.  Обычно необходимо обновлять
 экран, если пользователь заменяет поле, которое является частью
 управляющего индексного ключа. FieldEdit() - это функция
 пользователя, которая может быть вызвана из функции пользователя
 DBEDIT(), чтобы отредактировать текущее поле, если пользователь
 нажал редактирующую клавишу :
 
 #include "Dbedit.ch"
 #define ORD_NATURAL 0
 //
 FUNCTION FieldEdit()
 LOCAL indexVal
 // Сохранить текущее значение выражения ключа
 // и его значение
 indexVal = &amp;(INDEXKEY(ORD_NATURAL))
 .
 . <команды ввода значения в текущее поле>
 .
 // Обновить экран, если изменено значение ключа
 IF indexVal != &amp;(INDEXKEY(ORD_NATURAL))
 nRequest = DE_REFRESH
 ELSE
 nRequest = DE_CONT
 ENDIF
 RETURN nRequest

13.29.2.52. Function INDEXORD()

 INDEXORD() --> порядковый номер

13.29.2.53. Function LASTREC()

 LASTREC() | RECCOUNT()* --> число записей

13.29.2.54. Function LUPDATE()

 LUPDATE() --> дата модификации

13.29.2.57. Function ORDLISTADD()

 ORDLISTADD(<cOrderBagName> [, <cOrderName>]) --> NIL

13.29.2.58. Function RECCOUNT()

 RECCOUNT() | LASTREC() --> количество записей

13.29.2.59. Function RECNO()

 RECNO() --> номер текущей записи

13.29.2.59.3. Description

RECNO() - это функция обработки баз данных, которая возвращает текущий номер записи в рабочей области. В файловой схеме базы данных xClipper каждый файл базы данных упорядочен по физическим номерам записей. В каждой рабочей области указатель записи выделяет текущую запись в открытом файле базы данных. Этот номер записи и возвращает функция RECNO(). Организация нумерации записей позволяет осуществлять прямой доступ к каждой записи без последовательного просмотра всего файла базы данных.

RECNO() обычно используется в программах, которые обрабатывают записи, выбирая их по номерам. Примером может служить команда SET RELATION... TO RECNO(), связывающая файлы баз данных по их номерам записей. Команду GO RECNO() также можно использовать для восстановления текущей записи с диска.

По умолчанию RECNO() обрабатывает текущую (активную) рабочую область. Для обработки пассивной рабочей области ее необходимо использовать как элемент выражения, уточненного алиасом (как показано в примере ниже).

13.29.2.60. Function RECSIZE()

 RECSIZE() --> количество байтов

13.29.2.61. Function RLOCK()

 RLOCK() --> признак завершения

13.29.2.61.3. Description

RLOCK() - это функция работы в сети, применяемая для блокирования текущей записи и запрещающая другим пользователям обновлять запись до тех пор, пока она блокирована. RLOCK() осуществляет раздельную блокировку, предоставляя другим пользователям право только считывать данные блокированной записи и оставляя право изменять ее только за текущим пользователем. Запись остается блокированной до тех пор, пока не будет блокирована другая запись, выполнится команда UNLOCK, закроется текущий файл базы данных или будет выполнена функция FLOCK() для текущего файла базы данных.

При каждом вызове RLOCK() производится одна попытка блокировать текущую запись и результат возвращается в виде логического значения. Попытка блокировки считается неудачной, если в этот момент уже была выполнена блокировка файла или этой записи другим пользователем, или файл был открыт в режиме монопольного пользования (EXCLUSIVE USE).

По умолчанию RLOCK() обрабатывает текущую (активную) рабочую область. Функция может обрабатывать и пассивную рабочую область, если ее использовать как элемент выражения, уточненного алиасом (смотрите пример ниже). Эта возможность особенно полезна, поскольку RLOCK() автоматически не блокирует записи, логически связанные с записью активной рабочей области.

Как правило, RLOCK() используется для работы с текущей записью. При этом наиболее часто используемые команды:

@...GET

DELETE (единственная запись)

RECALL (единственная запись)

REPLACE (единственная запись)

За более подробной информацией обращайтесь к главе "Программирование в сети" книги "Программирование и утилиты".

13.29.2.62. Function SELECT()

 SELECT([<алиас>]) --> номер рабочей области

13.29.2.63. Function USED()

 USED() --> признак наличия открытой базы данных