Функция
Секция описания функции.
Синтаксис:
Функция <Имя_функции>([[Знач] <Парам1>[=<ДефЗнач>], ...
, [Знач] <ПарамN> [=<ДефЗнач>]])[Экспорт]
//Объявления локальных переменных;
// Операторы;
...
Возврат <ВозвращаемоеЗначение>;
// Операторы;
...
КонецФункции
Англоязычный Синтаксис:
Function <Имя_функции> ([[Val] <Парам1>[=<ДефЗнач>], ...
, [Val] <ПapaмN> [=<ДефЗнач>]])[Export]
//Объявления локальных переменных;
// Операторы;
...
Return <ВозвращаемоеЗначение>;
// Операторы;
...
EndFunction
Параметры:
|
<Имя_функции> |
Назначает имя функции. |
|
Знач |
Необязательное ключевое слово, которое указывает на то, что следующий за ним параметр передается по значению, т. е. изменение значения формального параметра при выполнении функции никак не повлияет на значение фактического параметра, переданного при вызове функции. Если это ключевое слово не указано, то параметр функции передается по ссылке, то есть изменение внутри функции значения формального параметра приведет к изменению значения соответствующего фактического параметра. |
|
<Парам1>, ..., <ПарамN> |
Необязательный список формальных параметров, разделяемых запятыми. Значения формальных параметров должны соответсвовать значениям передаваемых при вызове функции фактических параметров. В этом списке определяются имена каждого из параметров так, как они используются в тексте функции. Список формальных параметров может быть пуст. См. также: «Передача параметров». |
|
=<ДефЗнач> |
Необязательная установка значения параметра по умолчанию. Параметры с установленными значениями по умолчанию можно располагать в любом месте списка формальных параметров. Если параметр при вызове процедуры опущен, то он принимает либо установленное по умолчанию значение (если оно есть) либо принимает «пустое» значение (значение неопределенного типа). Если параметру не задано значение по умолчанию и он является последним в списке передаваемых параметров, то при вызове процедуры его нельзя опускать. Если параметру задано значение по умолчанию и он является последним в списке, то при вызове процедуры его можно опускать в списке передаваемых фактических параметров и не ставить запятую перед опущенным параметром. Если параметру не задано значения по умолчанию, то при вызове процедуры его можно опускать в списке передаваемых фактических параметров, но разделительную запятую надо ставить. |
|
Экспорт |
Необязательное ключевое слово, которое указывает на то, что данная функция является доступной из других программных модулей. Данное ключевое слово имеет смысл использовать только в глобальном программном модуле. |
|
//Объявления локальных переменных |
Объявляются локальные переменные, на которые можно ссылаться только в рамках этой функции (см. оператор Перем). |
|
//Операторы |
Исполняемые операторы функции. |
|
Возврат |
Ключевое слово, которое завершает выполнение функции и возвращает ВозвращаемоеЗначение в выражение, в котором используется функция. Использование данного ключевого слова в функции обязательно. |
|
<ВозвращаемоеЗначение> |
Выражение, значение которого содержит результат обращения к функции. |
|
КонецФункции |
Обязательное ключевое слово, обозначающее конец исходного текста функции. |
Вычисляет функцию и включает ее результат в запрос.
Синтаксис:
Функция <ИмяФункции> = <ТипФункции> (<Параметр>|<УточненныйПараметр>)
[Когда (<Условие>)];
Англоязычный синоним:
Function <ИмяФункции>= <ТипФункции> (<Параметр>|<УточненныйПараметр>)
[When (<Условие>)];
Параметры:
|
<ИмяФункции> |
Имя, которое присваивается функции. По этому имени можно в дальнейшем обращаться к значению вычисленной функции из вызывающего программного модуля как к атрибуту запроса. Данную внутреннюю переменную заранее объявлять не нужно. Она фактически неявно объявляется в операторе Функция. |
|
<TипФyнкции> |
Ключевое слово одной из встроенных функций языка. Может быть одним из приведенных ниже. |
|
<Параметр> |
Имя объявленной ранее внутренней переменной, значение которой используется как параметр встроенной функции <ТипФункции>. В функциях: Сумма, Среднее, Максимум, Минимум в качестве данного параметра возможно использование арифметического выражения в терминах встроенного языка 1С:Предприятие. |
|
<УточненныйПараметр> |
Конкретизация объявленной ранее внутренней переменной, значение которой используется как аргумент встроенной функции < ТипФункции>. |
|
Когда |
Необязательное добавочное ключевое слово, использование которого в команде означает, что вычисление функции следует производить только при условии, когда заданное логическое выражение <Условие> истинно. |
|
<Условие> |
Логическое выражение встроенного языка 1С:Предприятие. В логическом выражении могут участвовать как внутренние, так и внешние переменные запроса (см. описание метода Условие). Используется только после ключевого слова Когда. |
Описание:
Оператор Функция вычисляет функцию <ТипФункции> и присваивает ее значение внутренней переменной <ИмяФункции>.
Типы применяемых функций предопределены и могут быть следующими:
|
Тип Функции |
Англояз. Синоним |
Выполняемое действие |
|
Сумма |
Sum |
Вычисляет сумму выбранных по запросу значений параметра.1 |
|
Среднее |
Avg |
Вычисляет среднее из выбранных по запросу значений параметра. |
|
Минимум |
Min |
Вычисляет минимум из выбранных по запросу значений параметра. |
|
Максимум |
Мах |
Вычисляет максимум из выбранных по запросу значений параметра. |
|
Счётчик |
Count |
Подсчитывает количество записей, вошедших в выборку. |
|
НачОст |
BegRest |
Вычисляет начальный остаток для выбранных по запросу значений параметра.2 |
|
КонОст |
EndRest |
Вычисляет конечный остаток для выбранных по запросу значений параметра.2 |
|
Приход |
Debit |
Вычисляет приход для выбранных но запросу значений параметра.2 |
|
Расход |
Credit |
Вычисляет расход для выбранных по запросу значений параметра.2 |
|
СНД |
IDB |
Вычисляет сальдо начальное дебетовое для выбранных по запросу значений параметра.3 |
|
СКД |
FDB |
Вычисляет сальдо конечное дебетовое для выбранных по запросу значений параметра.3 |
|
СНК |
ICD |
Вычисляет сальдо начальное кредитовое для выбранных по запросу значений параметра.3 |
|
СКК |
FCD |
Вычисляет сальдо конечное кредитовое для выбранных по запросу значений параметра.3 |
|
ДО |
TD |
Вычисляет дебетовые обороты для выбранных по запросу значений параметра. |
|
КО |
TC |
Вычисляет кредитовые обороты для выбранных по запросу значений параметра.3 |
|
КорДО |
CorTD |
Вычисляет дебетовые обороты между корреспондирующим счетам или субконто для выбранных по запросу значений параметра.3, 4 |
|
КорКО |
CorTC |
Вычисляет кредитовые обороты между корреспондирующим счетам или субконто для выбранных по запросу значений параметра.3, 4 |
Ключевое слово Функция начинает секцию исходного текста функции, выполнение которой можно инициировать из любой точки программного модуля, просто указав Имя_функции со списком параметров (если параметры не передаются, то круглые скобки, тем не менее, обязательны). Если в глобальном программном модуле в теле описания функции использовано ключевое слово Экспорт, то это означает, что данная функция является доступной из всех других программных модулей конфигурации. Ключевое слово Экспорт имеет смысл использовать только в глобальном программном модуле.
Выполнение функции заканчивается обязательным оператором Возврат. Функции отличаются от процедур только тем, что возвращают Воз вращаемое Значение. Конец программной секции функции определяется по оператору КонецФункции.
Вызов любой функции в тексте программного модуля можно записывать как вызов процедуры, т. е. в языке допускается не принимать от функции возвращаемое значение.
Переменные, объявленные в теле функции в разделе Объявления_локальных_переменных, являются локальными переменными данной функции, поэтому доступны только в этой функции (за исключением случая передачи их как параметров при вызове других процедур, функций или методов).
Замечание: ключевые слова Функция, КонецФункции являются не операторами, а операторными скобками, поэтому не должны заканчиваться точкой с запятой (это может приводить к ошибкам выполнения модуля).
См. также: «Передача параметров»
Пример:
Перем Глоб;
// Описание функции
Функция МояФункция(Парам1, Парам2, ПарамЗ) Экспорт
Лок = Глоб + Парам1 + Парам2 + ПарамЗ;
Возврат Лок;
КонецФункции
Глоб = 123;
Рез = МояФункция(5, 6, 7); // Вызов функции
1Замечание: Для ресурсов оборотных регистров допускается вызывать только тип функции "Сумма".
2Замечание: Типы функций НачОст, КонОст, Приход, Расход можно использовать только с параметрами, указывающими на ресурсы регистров остатков. Для ресурсов регистров остатков другие типы функций вызывать нельзя.
3Замечание: Функции СНД, СНК, СКД, СКК, ДО, КО, КорДО, КорКО можно использовать только с реквизитами проводки: Сумма, Количество или ВалСумма.
4Замечание: Функции КорДО и КорКО накапливают значения только тогда когда в запросе есть обращение к реквизитам проводок Счет, КорСчет Субконто или КорСубконто.
Замечание: В программном модуле, где используется запрос, <ИмяФункции> будет являться атрибутом запроса. При помощи данного атрибута можно обращаться к значению вычисленной в запросе функции.
Замечание: В функциях: Сумма, Среднее, Максимум, Минимум в качестве аргумента возможно использование арифметического выражения в терминах встроенного языка.
Пример:
...
|КолВо = Документ.ВидДокумента.Количество;
|Цена = Документ.ВидДокумента.Цена;
|Функция Сум = Сумма(КолВо * Цена);
|Функция Макс = Максимум(Окр(КолВо) * Окр(Цена));
|Функция Средн = Среднее(ФункцияОпределеннаяВМодуле(КолВо, Цена));
...
Пример:
// Создание объекта типа Запрос
Запрос = СоздатьОбъект("Запрос");
ТекстЗапроса =
"//{{ЗАПРОС(Функции)
|Период с ДатаНач по ДатаКон;
|Оклад = Справочник.Сотрудники.Оклад;
|Подр = Справочник.Сотрудники.Подразделение;
|Ктг = Справочник.Сотрудники.Категория;
|Группировка Подр без групп;
|Группировка Ктг без групп;
|Функция Всего = Сумма(Оклад);
|Условие((Ктг.Выбран() = 1) И (Подр.Выбран() = 1));
|"//}}ЗАПРОС
;
Если Запрос.Выполнить(ТекстЗапроса) = 0 Тогда
Возврат;
КонецЕсли;
// ...
Итог = Запрос.Всего;
// ...
Оператор Функция предназначен для вычисления и накопления некоторых численных значений в процессе формирования выборки по запросу.
Кроме того, при формировании временного набора данных запрос специально формирует итоговые записи, в которые заносит накопленные значения вычисленных функций для каждой вложенной Группировки (подробнее об этом см. главу данной книги «Структура запросов и методика их использования»).
Операторы функций в запросе можно опускать, тогда запрос просто не будет ничего вычислять, а просто во временный набор данных заносятся записи со значениями Группировок. Однако это справедливо только для работы запросов по справочникам и по документам. При работе запроса по регистрам следует помнить, что в этом случае обязательно наличие Функций, причем только в том случае, когда их вычисленные значения отличны от нуля (хотя бы одной из заданных Функций), найденные объекты включаются во временный набор данных, формируемый запросом. Если при работе запроса по регистрам в тексте запроса операторы функций опущены, то программа не выдаст никакого сообщения об ошибке, добросовестно пройдет по всем Группировкам, не вычислит никаких значений Функций и, значит, ничего не запишет во временном файле.
При создании в тексте запроса внутренней переменной, которую вы предполагаете использовать в качестве параметра оператора Функция, надо учитывать, что тип этой внутренней переменной должен быть «число», т. к. функции в языке запросов обрабатывают только численные значения.
В тексте запроса, при описании оператора Функция можно использовать необязательное ключевое слово Когда, использование которого в операторе означает, что вычисление функции следует производить только при условии, что значение логического выражения, заданного в параметре ключевого слова является ИСТИНА. Синтаксис применяемого логического выражения полностью аналогичен синтаксису разрешенному к применению в операторах Условие.
Следует понимать, что не все функции внутри конкретной группировки запроса могут иметь четко интерпретируемый смысл. Например, для группировки по документу движения регистра следующие функции
|Функция ПрихКол = Приход(Количество);
|Функция РасхКол = Расход(Количество);
имеют четкий смысл — приращения, сделанные документом при движении регистра. С другой стороны, в той же группировке следующие функции:
|Функция НачКол = НачОст(Количество);
|Функция КонКол = КонОст(Количество);
явно не имеют смысла (в запросах по регистрам, обычно задают период запроса при помощи оператора ПериодC. Функция НачКол в данном примере должна по смыслу показывать остаток ресурса "Количество" на начальную дату запроса. Внутри группировки по документу вопрос: «Какой начальный остаток ресурса на дату 10.01.97?» по документу, проведенному, например, 13.01.97, не имеет смысла). Поэтому в таких ситуациях функция будет иметь нулевое значение.
Пример:
Запрос = СоздатьОбъект("Запрос");
Текст3апроса=
'//{{ЗАПРОС(Функции)
|Период с ДатаОтчета;
|Товар = Регистр.КвотыТоваров.Товар;
|Отдел = Регистр.КвотыТоваров.Отдел;
|Сотрудник = Регистр.КвотыТоваров.Сотрудник;
|Партнер = Регистр.КвотыТоваров.Партнер;
|Док = Регистр.КвотыТоваров.ТекущийДокумент;
|Количество = Регистр.КвотыТоваров.КвотаТовара;
|Группировка Товар;
|Группировка Отдел;
|Группировка Сотрудник;
|Группировка Партнер;
|Группировка Док;
|Функция НачКол = НачОст(Количество);
|Функция ПрихКол = Приход(Количество);
|Функция РасхКол = Расход(Количество);
|Функция КонКол = КонОст(Количество);
|// Следующие Функции вычисляем только при определенных
|// условиях, чтобы получить отфильтрованные итоги
|Функция ПрихКолТов = Приход(Количество) Когда (Док.ФлагТовара = 1);
|Функция РасхКолТов = Расход(Количество) Когда (Док.ФлагТовара = 1);
|Функция ПрихКолОтд = Приход(Количество) Когда (Док.ФлагОтдела = 1);
|Функция РасхКолОтд = Расход(Количество) Когда (Док.ФлагОтдела = 1);
|Функция ПрихКолСотр = Приход(Количество) Когда (Док.ФлагСотрудника = 1);
|Функция РасхКолСотр = Расход(Количество) Когда (Док.ФлагСотрудника = 1);
|"//}}ЗАПРОС
;
// Если ошибка в запросе, то выход из процедуры
Если Запрос.Выполнить(ТекстЗапроса) = 0 Тогда
Возврат;
КонецЕсли;
