> For the complete documentation index, see [llms.txt](https://unisim-soft.gitbook.io/unisim-soft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unisim-soft.gitbook.io/unisim-soft/razrabotka/obekty-oracle/parametry-i-makrosy-sql-zaprosov.md).
# Параметры и макросы SQL-запросов
Что такое SQL-запросы и анонимные PL/SQL-блоки?
* Под **SQL-запросами** (здесь) понимаются текстовые выражения, начинающиеся со слова 'SELECT' и использующиеся для получения данных в табличной форме.
* Под **анонимными PL/SQL-блоками** (здесь) понимаются текстовые выражения, начинающиеся со слов 'DECLARE', 'BEGIN' или 'CALL' и использующиеся для выполнения действий над данными на стороне сервера. Теоретически сюда же относятся все остальные виды выражений, не относящихся к **SQL-запросам**.
Что такое параметры и макросы SQL-запросов и анонимных PL/SQL-блоков?
* Под **параметрами** (здесь) понимаются отдельные слова, начинающиеся с двоеточия. Параметры могут быть входными и выходными. Перед выполнением выражения **сервер** заменяет эти слова значениями, которые передаются в скрытом виде вместе с текстом выражения. После выполнения выражения **сервер** заполняет значения выходных параметров для передачи их на сторону клиента. Длина параметра (не включая двоеточия) не должна превышать 30 символов.
* Под **макросами** (здесь) понимаются отдельные слова, начинающиеся с амперсанда. Перед отправкой выражения на сервер **клиент** заменяет эти слова определенными значениями. Таким образом, на сервер выражение попадает с уже подставленными вместо макросов значениями. Длина макроса (не включая амперсанда) не должна превышать 30 символов.
В каких случаях программа автоматически обрабатывает параметры и макросы SQL-запросов и анонимных PL/SQL-блоков?
* При выполнении действий (Actions) документов или форм: для каждого свойства SQLx
* При открытии настраиваемых выпадающих справочников: для свойств SQL и PrepareSQL
* При открытии выпадающих справочников UNIVERS внутри документа: для свойства SQL\_UNIV документа (обычно для инициализации нужных сисконтекстов)
* При построении печатных форм документов и форм: для свойств SQLHeader, SQLMaster и SQLDetail
* При построении некоторых отчетов: для свойств SQLHeader, SQLMaster и SQLDetail
Какие типы параметров различает программа?
* Перед выполнением выражения программа заполняет значения только входных параметров (выходные параметры игнорируются).
* Информация о типе параметра и способе получения его значения содержится в имени параметра.
* Для преодоления ограничения на длину имени параметра допускается замена короткого имени, используемого в выражении, на полное. Для этого на отдельной строке выражения (обычно внутри многострочного блока комментариев /\* ... \*/) нужно написать <короткое имя параметра>=<полное имя параметра> - без угловых скобок, разумеется [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#COMMENTS).
* Параметры с именем RESULT игнорируются.
* Параметры с именем, начинающимся с символа "", обрабатываются отдельно [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#BACKSLASH).
* Параметры с именем NRDOC получают значение номера текущего документа.
* Параметры с именем DATADOC, DOCDATA или DATAMANUAL получают значение даты текущего документа.
* Параметры с именем NRSET или NRCM получают значение NRSET текущего документа.
* Параметры с именем DATEBEGIN или DATEFINAL получают соответствующие даты периода построения отчета, а при отсутствии окна отчетов - периода просмотра документов.
* Параметры с именем, начинающимся на "INI\_", получают значение параметра текущего узла настроек [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#INI).
* Параметры с именем, начинающимся на "INDOC\_", получают значение из текущего документа (метод получения значения определяется типом и содержанием документа) [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#INDOC).
* Параметры с именем, начинающимся на "INFORM\_", получают значение из текущей формы (метод получения значения определяется типом и содержанием формы) [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#INFORM).
* Параметры с именем, начинающимся на "EDIT\_", получают значение из указанного поля ввода на указанном окне [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#EDIT).
* Параметры с именем, начинающимся на "FIELD\_", получают значение из указанного поля указанной таблицы указанного модуля [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#FIELD).
* Параметры с именем, начинающимся на "OUTBDE", помечаются как выходные параметры символьного (строкового) типа с размером буфера 32000 символов. После выполнения действия значение параметра используется для создания таблицы BDE и экспорта в нее соответствующих данных с сервера [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#OUTBDE).
* Параметры с именем, начинающимся на "OUTOLE", помечаются как выходные параметры символьного (строкового) типа с размером буфера 32000 символов. Параметр должен содержать в себе запрос, позволяющий сделать выгрузку OLE объектов из него, а также имя процедуры, для последовательного подтверждения выгрузки. После выполнения действия предлагается выбрать директорию для сохранения данных с сервера, после выбора которой, начинается процесс копирования, который, в случае чего, можно отменить (см. ниже).
* Неидентифицированные входные параметры пользователю предлагается заполнить в отдельном окне, появляющемся на экране перед выполнением выражения. Способ ввода значений этих параметров и подписи к ним можно указать на отдельных строках выражения [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#OTHER).
Какие типы макросов различает программа?
* Макросы с именем, начинающимся на BDE# или BDEQ#, заменяются именем глобальной временной таблицы, которая создается для каждого макроса перед выполнением выражения. В эту таблицу загружается содержимое таблицы BDE [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#BDE).
* Макросы с именем, начинающимся на TXT# или TXTQ#, заменяются именем глобальной временной таблицы, которая создается для каждого макроса перед выполнением выражения. В эту таблицу загружается содержимое текстового файла [(см. ниже)](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#TXT).
Примечание
Варианты макросов BDEQ# и TXTQ# отличаются только тем, что имя таблицы при вставке в текст выражения будет обрамлено кавычками (используется в **анонимных PL/SQL блоках** - в отличие от **SQL-запросов**, где имя таблицы должно указываться без кавычек).
Как обрабатываются параметры, начинающиеся с символа ""?
* Эти параметры позволяют получить значение любого свойства любой секции настроек программы - достаточно знать название секции и свойства, и в некоторых случаях явно указать используемый раздел настроек.
* Общий синтаксис параметра выглядит как **"**
**"** или **""**, где - раздел настроек (одно из значений DOCS, REPS, FORMS или SYS),- имя секции, а - имя требуемого свойства.
* В случае отсутствия явного указания раздела берется текущий (по смыслу) раздел.
Как обрабатываются параметры, начинающиеся с "INI_"?
* Эти параметры позволяют получить значение любого свойства текущей секции настроек программы - достаточно знать название свойства.
* Имя параметра строится как **INI\_**, где - имя требуемого свойства.
Пример:
```sql
SELECT * FROM VMS_UNIVERS WHERE TIP='F' AND GR1=:INI_CONTAFX
```
Как обрабатываются параметры, начинающиеся с "INDOC_"?
* Эти параметры позволяют получить значение, возвращаемое текущим документом.
* Имя параметра строится как **INDOC\_**, где - информация для обработки текущим документом.
Пример:
Так, [стандартный документ 201](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/docs.html#201) позволяет получить доступ к значениям полей master и detail таблиц
```sql
SELECT * FROM VMS_UNIVERS WHERE TIP='O' AND GR1='I' AND CODI=:INDOC_M_DTDEP
```
Как обрабатываются параметры, начинающиеся с "EDIT_"?
* Эти параметры позволяют получить значение из любого поля ввода, расположенного в любом окне программы.
* Имя параметра строится как **EDIT\_\_**, где - имя окна, а - имя поля ввода.
* Получить имя параметра для некоторых полей можно в окне их свойств на вкладке "Other field properties" в поле "Parameter name".
Пример (доступ к значению поля "Аналит. счет" на панели "Универсального отчета"):
```sql
SELECT * FROM VMS_UNIVERS WHERE TIP='M' AND CODI=:SC
/*
SC=edit_fmRG1b_sl12Sc
*/
```
Как обрабатываются параметры, начинающиеся с "FIELD_"?
* Эти параметры позволяют получить значение из любого поля любого набора данных (датасета), расположенного в любом окне программы.
* Имя параметра строится как **FIELD\_\_**, где - имя окна, а - имя компонента поля, или как **FIELD\_**, где - имя окна, - имя компонента датасета, а - имя поля.
* Получить имя параметра можно при редактировании дизайна в окне свойств столбца на вкладке "Other field properties" в поле "Parameter name".
Как отдельно указать полное имя параметра?
* Полное имя параметра требуется указывать на отдельной строке в следующих случаях:
* Когда имя параметра превышает 30 символов
* Когда имя параметра содержит недопустимые символы (например, "")
Пример:
```sql
SELECT * FROM VMS_UNIVERS WHERE TIP='F' AND GR1=:CONT
/*
CONT=\SYS\AFX\pkg_afx_Acc5342
*/
```
Как указать подписи, методы ввода и начальные значения к неидентифицированным параметрам?
* Все описанные в этом разделе дополнительные свойства параметра задаются на отдельных строках выражения внутри блока комментариев - подобно тому, как задаются [полные имена параметров](file:///D:/UNA/UNA.md-130409-4.1.5.052/un4setup/sql_params.html#COMMENTS).
* Текст подписи к параметру, не указанный явно, выглядит как имя параметра.
* Текст подписи к параметру задается свойством вида **.text.**, где - имя параметра в тексте выражения.
* Текст подписи к параметру на одном из трех языков E, M, R задается свойством вида **.text..**, где - код языка (E, M или R), а - имя параметра в тексте выражения.
* Метод ввода значения параметра задается свойством вида **.type.**, где - имя параметра в тексте выражения.
Допустимые значения свойства .type.:
* NUMBER — разрешается вводить только числовые значения
* DATE — разрешается вводить только даты
* LIST,U,, — предлагается выбор из справочника UNIVERS с фильтром и (параметры фильтра необязательны).
* LIST,S,, — предлагается выбор из справочника SYSS с фильтром и (параметры фильтра необязательны).
Начальное значение параметра задается свойством вида **.def.**, где - имя параметра в тексте выражения.
Начальное значение параметра может быть либо константой (числом или строкой), либо именем другого параметра (перед именем параметра должно стоять двоеточие).
Пример задания подписей, методов ввода и начальных значений для нескольких параметров:
```plsql
begin
:DefDate:=:DATADOC;
raise_application_error(-20000,'Param values:
SimpleString: '''||:SimpleString||'''
AnyNumber: '''||:AnyNumber||'''
AnyDate: '''||:AnyDate||'''
Univers: '''||:Univers||'''
SysS: '''||:SysS||'''
');
end;
/*
Captions:
.text.SimpleString=Простая строка
.text.AnyNumber=Любое число
.text.AnyDate=Любая дата
.text.Univers=Унив. справ.
.text.SysS=Сист. справ.
English captions:
.text.E.SimpleString=Simple string
.text.E.AnyNumber=Any number
.text.E.AnyDate=Any date
.text.E.Univers=Universal list
.text.E.SysS=System list
Types:
.type.AnyNumber=Number
.type.AnyDate=Date
.type.Univers=List,U,O,E
.type.SysS=List,S,F,2
Default values:
.def.SimpleString=Example
.def.AnyNumber=100
.def.AnyDate=:DefDate
*/
```
Как импортировать данные из таблицы BDE?
* В тексте выражения нужно ссылаться на таблицу так, как будто она уже импортирована в Oracle, используя вместо имени таблицы макрос специального вида.
* Имя макроса строится как **BDE##**
, где - имя алиаса BDE, а- имя таблицы BDE (без расширения).
**#**, где все - как и раньше, а - расширение файла таблицы BDE.
Пример:
```plsql
BEGIN
EXECUTE IMMEDIATE 'DELETE FROM '||&BDEQ#1mPriv#Bank#dbf||' WHERE VALUTA=:VAL'
USING 'LEI';
INSERT INTO TMS_TEST(VALUTA,CURS)SELECT VALUTA,CURS FROM &BDE#1mPriv#Bank#dbf;
END;
```
Здесь демонстрируются оба вида префикса **BDE#** и **BDEQ#**. Несмотря на то, что имена макросов формально разные, в обоих будет использована одна и та же таблица Oracle.
* При обращении к таблице BDE посредством EXECUTE IMMEDIATE ее имя в тексте выражения должно быть обрамлено кавычками. Для этого префикс имени макроса **BDE#** нужно заменить на **BDEQ#**.
* При необходимости задать другое расширение файла имя макроса может принимать вид **BDE##**
* Подразумевается стандартное расширение файлов БД Paradox ".DB".