Руководство программиста

Основные положения

В систему «Курьерская служба 2008» встроен внутренний интерпретируемый язык программирования. Среда состоит из базовой функциональности, и дополнительно создаваемых объектов. Некоторые объекты автоматически создаются средой перед запуском интерпретатора для предоставления доступа к контексту, в котором работает скрипт. Все типы данных приводятся друг к другу автоматически, иногда при необходимости можно использовать функции приведения типов.

Как интерпретатор приводит типы:

1. При использовании значения как параметр функции интерпретатор автоматически приводит значение к типу, необходимому функции.

2. При операциях сложения, а также логических операциях, операнды приводятся к строке если хотя бы один из них имеет тип «строка». Например: 3.3+5 -> 8.3 ‘3.3’+5 -> ‘3.35’ подобную проблему можно решить принудительно преобразовав тип: float(‘3.3’)+5 -> 8.3

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

Как работают функции приведения типов:

1. При преобразовании строки к числу: функция «читает» строку до первого символа, не позволяющего создать число с плавающей точкой, при этом разделителем целой и дробной частей может быть как точка так и запятая. Если приведение производится к целочисленному типу, то после этого происходит округление. Например: float('3.6qwerty735') -> 3.6 int('3.6qwerty735') -> 4

2. При преобразовании к булевому типу ложью считается пустая строка либо число 0, все остальное - истина

3. При преобразовании булевого типа к числу истина преобразуется в 1, ложь – в 0. Такое преобразование позволяет использовать сложение и умножение в качестве логических «ИЛИ» и «И» соответственно: if((5=5)+(6=7), <a>, [b]) – условие истинно, выполнится код «a».

4. При преобразовании булевого типа к строке сначала происходит преобразование к числу: (5=5)+'qwerty' -> ‘1qwerty’

Описание синтаксиса

Команды разделяются точкой с запятой. Параметры функций разделяются запятыми. Каждая команда (даже цикл while) является функцией, возвращающей некоторое значение. Результатом выполнения составной команды (последовательности функций, разделенных точкой с запятой), является результат выполнения последней функции. Имена переменных, функций, объектов, а также их свойств и методов не чувствительны к регистру. Константы: константы бывают целочисленными, дробными и строковыми. Значения целочисленных и дробных констант указываются «как есть» (в этом случае разделитель целой и дробной частей – точка), шестнадцатеричные значения начинаются с символа «$» и, если первая цифра – буква, она упреждается цифрой 0, а строковые – в одинарных кавычках. При этом, если внутри строковой константы встречается символ одинарной кавычки он должен быть задвоен, для указания интерпретатору того, что он не является признаком конца константы. Операции сравнения: >, <, =, ! - Больше, меньше, равно, не равно соответственно. Логические операции: + (ИЛИ), * (И). Арифметические операции: +, -, *, / Операция конкатенации строк: +

Функциональность базового объекта

SET($a, a) – присваивает переменной (1-й параметр) значение второго параметра. При отсутствии переменной – создает ее. Имена переменных должны начинаться с символа «$», а следующий символ не должен быть цифрой. Возвращает новое значение переменной. Функция используется только для задания значений переменных. Не допускается использования для задания значений свойств объектов. Для этого используются соответствующие методы этих объектов.

IF(a,b,c) или IF(a,b) – Условный оператор. В первом случае возвращает b, если a истинно (не равно нулю или пустой строке), иначе – c. Во втором случае – возвращает a, если оно истинно, иначе – b.

WHILE(a, b) – Оператор цикла. Выполняет b пока a истинно: set($i, 10); set($sum, 0); while($i>0, set($sum, $sum+$i); set($i, $i-1)); $sum Результат – 55

FOR($a, b, c, d) – Оператор цикла. Выполняет d пока $a последовательно присваиваются значения от b до с включительно: set($sum, 0); for($i, 1, 10, set($sum, $sum+$i)); $sum Результат – 55

NEW(ClassName, InstanceName) – Создает экземпляр класса ClassName, назначает ему имя InstanceName. Возвращает порядковый номер созданного объекта. Доступ к свойствам и методам объектов осуществляется по имени объекта и имени свойства/метода, разделенным точкой. Именем объекта может быть и пустая строка, тогда доступ к его свойствам и методам будет осуществляться без указания имени, и, в случае совпадения имен свойств и/или методов со стандартными или свойствами/методами других объектов, использоваться будут соответствующие свойства/методы объекта, созданного ранее, а также такой объект невозможно уничтожить до окончания выполнения скрипта. Все объекты созданные во время выполнения скрипта уничтожаются автоматически после окончания его выполнения.

FREE(InstanceName) – Уничтожает объект с именем InstanceName. Возвращает 0. В случае отсутствия объекта с заданным именем вызывает ошибку.

ShowObjects – Возвращает список созданных объектов – названия классов и имена.

ERROR(message) – Вызывает ошибку с текстом message.

SHOWMESSAGE(message) – Отображает диалоговое окно с текстом message, останавливает выполнение скрипта до закрытия окна пользователем.

SimpleAskUser(Message) – Выводит диалоговое окно с текстом Message и кнопками «Да» и «Нет». Возвращает 1, если пользователь нажал кнопку «Да», иначе – 0.

TRY(a) – Выполняет a в «защищенном от ошибки» режиме. Если в процессе выполнения a возникает ошибка, возвращает текст ошибки, иначе – 0 (ложь).

REM(….) – Код в скобках игнорируется (комментарий).

EXEC(FileName, Params, Wait, WindowState) – Запускает внешнее приложение FileName с параметрами Params. Если Wait истинно – ожидает завершение процесса. Для WindowState доступны следующие числовые значения: 0 - SW_HIDE 1 - SW_SHOWNORMAL (по-умолчанию) 3 - SW_MAXIMIZE 6 - SW_MINIMIZE Функция возвращает истину если приложение запущено успешно. Иначе – Ложь. В случае успеха, при параметре Wait – истина кладет в переменную $LastResult код завершения приложения.

Строковые функции

UPCASE(s) – возвращает строку s в верхнем регистре.

LCASE(s) – возвращает строку s в нижнем регистре.

LEN(s) – возвращает количество символов в строке s.

POS(s, substr) – возвращает номер первого символа первого включения подстроки substr в строку s, возвращает 0, если включения подстроки отсутствуют.

PARAM(s, i) – возвращает i-й элемент строки s, разделенной запятыми на элементы.

LEFT(s, i) – возвращает i первых символов строки s.

MID(s, i, j) - возвращает подстроку из s начиная с i символа и длиной j символов

RIGHT(s, i) – возвращает i последних символов строки s.

CHAR(i) – возвращает символ с кодом i.

ORD(s) – возвращает код первого символа строки s.

REPLACE(s, s1, s2) – возвращает строку s, в кот. все включения подстроки s1 заменены строкой s2 (не чувствительно к регистру).

REMSPACE(s) – возвращает сроку s без начальных и конечных запятых и пробелов, а также начальных точек.

QUOTEDSTR(s) – квотирует строку s символом «\» (обратный слеш). Возвращает строку s, помещенную между символами одинарной кавычки, при этом все вхождения в строку s символов: «\», «"» и «'» экранируются квотирующим символом, а символы #0, #10 и #13 заменяются на \0, \n и \r соответственно.

FormatTextXML(s) - квотирует строку s для использования в XML. Производит замены спец. символов для корректности XML-синтаксиса.

FormatTextJSON(s) - переводит строку в формат JSON, экранирует служебные символы.

SUMSTR(f) – Возвращает сумму f, написанную прописью.

FullNameToShort(Name) – Возвращает фамилию и инициалы по полному ФИО Name.

MonthName1(m) – Возвращает имя месяца с номером m с большой буквы на русском языке в именительном падеже.

MonthName2(m) – Возвращает имя месяца с номером m с большой буквы на русском языке в родительном падеже.

STR2UTF(s) - Производит перекодировку строки s из кодировки ANSI в кодировку UTF8.

StrForXML(s) - Подготавливает строку к парсингу как xml: Если находит в строке подстроку "UTF-8" - перекодирует ее из utf-8 в win-1251, убирает начальный знак вопроса, если такой встречается.

FixedIntToStr(i, len[, char]) - Возвращает целое число i дополненное слева символами char (по-умолчанию - "0") до длины len.

HMACHash256(key, text) - создаёт хэш по алгоритму SHA256 для проверки целостности сообщения, key - секретный ключ, text - хэшируемое сообщение

MD5Hash(text) - создаёт хэш по алгоритму MD5

UTF8Encode - кодирует ansi в UTF8

UTF8Decode - декодирует UTF8 в ansi

Translit(s) - транслитерация русского текста латиницей

Функции работы с датой и временем

CurrTime – возвращает текущее время

CurrDate – возвращает текущую дату

Day(dt) – возвращает день месяца даты dt.

Month(dt) – возвращает месяц года даты dt.

Year(dt) – возвращает год даты dt.

DaysInMonth(month, year) – Возвращает количество дней в указанном месяце.

IncDay(dt) – Возвращает дату, увеличенную на 1 день.

SQLDate(dt) – Пытается конвертировать dt в дату, вернуть в формате «'YYYY-MM-DD'» (с апострофами), если не удается – возвращает «NULL».

SQLDateToDate(dt) – Переводит дату из SQL-формата в обычный.

DAYSBETWEEN(dt1, dt2) – Возвращает количество дней между датами dt1 и dt2. В случае ошибки приведения dt1 или dt2 к дате возвращает -1000.

SQLFloat(f) – Приводит число с плавающей точкой к виду, пригодному для SQL-запроса, т.е. к тексту с разделителем дробной части – точка.

TimePeriod(time1, time2) - Оформляет временной период. Возвращаемое значение зависит от наличия значения в параметрах. Возможные варианты: "time1 - time2" , "С time1" , "ДО time2".

Функции приведения типов

INT(v) – возвращает значение типа “целое”, приводя вариантное значение v к числовому типу, а затем округляя его. В том числе используется как функция округления.

FLOAT(v) – возвращает значение типа “число”, приводя вариантное значение v к числовому типу, переводя в число цепочку символов до первого нецифрового символа (либо точки или запятой).

STR(v) – возвращает значение типа “строка”, приводя вариантное значение v к строковому типу.

Date(v) – возвращает дату, либо пустую строку, если не удается конвертировать v в дату

Математические функции

ROUNDUP(f) – округляет число f до ближайшего большего по модулю целого числа.

ROUNDDN(f) – округляет число f до ближайшего меньшего по модулю целого числа.

Подсказка: для простого округления используется функция int()

Константы

Null – Возвращает пустое значение.

Да, True, Нет, False – константы, соответствующие булевым значениям.

Прочие функции

SetPhoneParams(CountryCode, TownCode) – Устанавливает глобальные настройки кода телефонных кодов страны и города соответственно. По-умолчанию код страны – 7, код города – 495.

PhonesCount(s) – Возвращает количество корректных телефонных номеров, найденных в строке s.

GetPhone(s[, n]) – Возвращает n-й корректный телефонный номер, найденный в строке s. Нумерация начинается с 1.

GetEmail(s) – Возвращает все корректные адреса email, найденный в строке s, разделенные запятыми (т.е. готовыми к передаче в функцию SendEmail).

SendEmail(Server, Port, User, Pass, AddressFrom, AddressTo, MsgText, Subject[, FileName]) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY).

SendEmail(EmailFromStr, AddressTo, MsgText, Subject[, FileName]) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY). EmailFromStr – строка, содержащая данные для отправки письма – адрес SMTP-сервера, порт, логин, пароль и email отправителя, разделенные символом переноса строки.

GenEan(ID, Code) – Формирует штрих-код EAN 13 Состоящий из идентификатора ID и кода Code, Выравнивает до 13-ти символов, первый – «2», последний – контрольная сума.

SaveToFile(FileName,s)- Создает текстовый файл по пути, указанному в FileName (если по указанному пути существует файл с указанным именем, он удаляется и создается новый) и производит запись строки s в созданный текстовый файл.

StrFromFile(FileName) - Читает файл FileName, возвращает в виде строки. При ошибке чтения вызывает ошибку.

HTTPPOST(host, PostParams, Proxy, ContentType, HTTPUser, HTTPPass, Method) - Отправляет HTTP запрос по адресу host с данными PostParams. Proxy - объект Proxy, задающий прокси-сервер (по-умолчанию - пусто - не использовать прокси). ContentType - Заголовок ContentType. По-умолчанию - "application/x-www-form-urlencoded; Charset=UTF-8". HTTPUser и HTTPPass - данные для http-авторизации на сервере. Method - метод отправки запроса, по-умолчанию - "POST". Функция возвращает ответ сервера.

Объект TExcel

Предназначен для доступа к данным документов MS Excel. Требует установленного приложения MS Excel.

Функции:

FileName – Возвращает имя текущего файла.

SetFileName(aFileName) – Задает значение свойства FileName.

Open - Открывает файл с именем, заданным свойством FileName. Если имя файла не задано - создает чистую книгу.

OpenFile(aFileName) – Выполняет функции SetFileName и Open.

LoadFromDB(DB[, Headered=true][, Col=1][, Row=1]) – Загружает таблицу из набора данных, открытого в объекте DB типа TADO. Если Headered истинно (по-умолчанию), таблица загружается вместе с заголовками. Если название поля содержит подстроку «_RecNo» - данная подстрока не попадет в заголовок, а все значения поля будут заменены на порядковый номер записи в наборе данных, начиная с «1». В одной таблице допускается не более одного поля с порядковой нумерацией. Поля, названия которых начинаются в символа "-" не выгружаются.

Post2Sheet(DB[, Headered=true][, Col=1][, Row=1]) - Почти полный аналог LoadFromDB. В отличии от LoadFromDB если есть открытый файл, выгрузка данных будет выполнена прямо в него.

SetBorders(x1, y1, x2, y2) – Устанавливает границы прямоугольника. Если координаты опущены, или 0 – устанавливает границы всей используемой области.

DoNotDestroy(b) – При уничтожении объекта TExcel (а он уничтожается, как и все остальные объекты автоматически при завершении выполнения скрипта), приложение Excel уничтожается вместе с ним. DoNotDestroy(true) отключает уничтожение приложения.

SetVisible(b) – Устанавливает видимость приложения Excel для пользователя. По-умолчанию – false (не видимо).

RecNo – Возвращает номер текущей строки. Нумерация строк начинается с 1.

SetRecNo(aRecNo) – Устанавливает значение свойства RecNo.

A..ZZ – Возвращает значение соответствующего поля текущей строки. Может вызываться с целочисленным аргументом, указывающим на сдвиг относительно текущей строки. Например: AC(-1) – вернет значение столбца AC предыдущей строки. Если номер строки окажется вне допустимых значений вернет пустую строку.

Cell(x, y) – Возвращает значение ячейки, заданной координатами.

SetCell(x, y, v) – Устанавливает значение ячейки, заданной координатами x и y, в значение v.

SetSheet(No) – Устанавливает номер текущего листа.

SetSheetName(Name) - Устанавливает название текущего листа.

Close – Закрывает текущий файл.

First – Делает первую запись листа текущей.

Next – Увеличивает значение свойства RecNo на единицу в случае, если конец файла не достигнут. Иначе – выставляет свойство EOF в истину.

EOF – Возвращает признак достижения конца файла.

RecordCount – Возвращает количество строк в листе.

SheetsCount – Возвращает количество листов в книге.

AutoFit – Устанавливает автоматическую ширину столбцов.

RowAutoFit - Устанавливает автоматическую ширину строк.

RowInsert(i) - Вставляет на выбранном листе строку ПОД строкой с номером i.

SetRowHeight(r, h) – Устанавливает высоту строки r в h пикселей.

SetColWidth (c, w) – Устанавливает ширину столбца c в w символов.

SendEmail(Server, Port, User, Pass, AddressFrom, AddressTo, MsgText, Subject) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY). Функция закрывает текущий файл, и не может использоваться для файлов, закрытие которых запрещено.

SendEmail(EmailFromStr, AddressTo, MsgText, Subject) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY). EmailFromStr – строка, содержащая данные для отправки письма – адрес SMTP-сервера, порт, логин, пароль и email отправителя, разделенные символом переноса строки. Функция закрывает текущий файл, и не может использоваться для файлов, закрытие которых запрещено.

SetRowFontColor(Row,Color) - Устанавливает цвет шрифта в строке Row. Color - целое значение (RGB)

SetRowColor(Row,Color) - Устанавливает цвет фона в строке Row. Color - целое значение (RGB)

SetColumnFontColor(Col,Color) - Устанавливает цвет шрифта в столбце Col. Color - целое значение (RGB)

SetColumnColor(Col,Color) - Устанавливает цвет фона в столбце Col. Color - целое значение (RGB)

SetCellFontColor(Row,Col,Color) - Устанавливает цвет шрифта в ячейке с координатами [Row,Col]. Color - целое значение, равное номеру цвета в палитре (ColorIndex,не RGB)

SetCellColor(Row,Col,Color) - Устанавливает цвет фона в ячейке с координатами [Row,Col]. Color - целое значение (RGB)

GetRowFontColor(Row)- Возвращает RGB значение цвета шрифта строки Row

GetRowColor(Row)- Возвращает RGB значение цвета фона строки Row

GetColumnFontColor(Col)- Возвращает RGB значение цвета шрифта столбца Col

GetColumnColor(Col)- Возвращает RGB значение цвета фона столбца Col

GetCellFontColor(Row,Col) - Возвращает номер цвета шрифта в палитре (ColorIndex) в ячейке с координатами [Row,Col]

GetCellColor(Row,Col) - Возвращает RGB значение цвета фона в ячейке с координатами [Row,Col]

WrapText(x1, y1, x2, y2, value) – Устанавливает перенос текста прямоугольника в значение value. Если координаты опущены, или 0 – устанавливает границы всей используемой области. Для Value значение по-умолчанию - true.

SetOrientation(value) - Устанавливает ориентацию страницы. True (по-умолчанию) - альбомная (ландшафтная), Ложь - портретная.

Copy(x1, y1, x2, y2) - Копирует в буфер экселя

Cut(x1, y1, x2, y2) - Вырезает в буфер экселя

Paste(x1, y1) - Вставляет из буфера экселя. Команды copy-paste неразрывны, если что нибудь сделать в промежутке между ними, например вставить значение в ячейку, то копирование сброситься. (Последовательность использования: copy - paste, cut - paste)

PasteStyle(x1, x2, y1, y2) - Вставляет только оформление из буфера экселя (Последовательность использования: Copy - PasteStyle)

SetFont(Font[, x1, y1[, x2, y2]]) - Устанавливает шрифт Font для ячеек диапазона. Можно указать координаты только одной ячейки, можно - вообще не указать, тогда будет использован "UsedRange". Пока поддерживается только имя и размер шрифта.

Пример использования:

new('TExcel', 'myxl');
myxl.OpenFile('c:\asdf.xlsx');
set($sum, 0);
while (myxl.EOF=0, 
     set($sum, $sum+int(myxl.c));
     myxl.next );
$sum

Возвращает сумму всех числовых данных столбца C файла 'c:\asdf.xlsx'

Объект TCSVFile

Предназначен для доступа к данным документов CSV.

Функции:

FileName – Возвращает имя текущего файла.

OpenFile(FileName) – Открывает файл FileName.

LoadFromDB(DB) – Загружает таблицу из набора данных, открытого в объекте DB типа TADO.

RecNo – Возвращает номер текущей строки. Нумерация строк начинается с 1.

SetRecNo(aRecNo) – Устанавливает значение свойства RecNo.

A..ZZ – Возвращает значение соответствующего поля текущей строки. Может вызываться с целочисленным аргументом, указывающим на сдвиг относительно текущей строки. Например: AC(-1) – вернет значение столбца AC предыдущей строки. Если номер строки окажется вне допустимых значений вернет пустую строку.

First – Делает первую запись листа текущей.

Next – Увеличивает значение свойства RecNo на единицу в случае, если конец файла не достигнут. Иначе – выставляет свойство EOF в истину.

EOF – Возвращает признак достижения конца файла.

RecordCount – Возвращает количество строк в листе.

SendEmail(Server, Port, User, Pass, AddressFrom, AddressTo, MsgText, Subject) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY).

SendEmail(EmailFromStr, AddressTo, MsgText, Subject) – Отправляет письмо по e-mail с указанными параметрами. В случае ошибки отправки вызывает ошибку (рекомендуется использовать совместно с TRY). EmailFromStr – строка, содержащая данные для отправки письма – адрес SMTP-сервера, порт, логин, пароль и email отправителя, разделенные символом переноса строки.

Объект TADO

Предназначен для доступа к базам данных.

Функции:

Функция	Описание
Connect(ConnectionString)	Подключает к источнику данных. ConnectionString – Строка подключения ADO.
Open(Query)	Открывает набор данных выполнив запрос Query.
FieldByNo(i)	Возвращает значение поля с номером i. Нумерация полей – с нуля.
FieldName(i)	Возвращает имя поля с номером i.
FieldCount	Возвращает количество полей.
RecordCount	Возвращает количество записей.
RecNo	Возвращает номер текущей записи. ВНИМАНИЕ! В зависимости от способа подключения к БД нумерация может начинаться как с 0 так и с 1!
EOF	Возвращает признак достижения конца набора данных. Становится истиной когда выполняется команда Next на последней записи.
Next	Переход на следующую запись набора.
First	Переход на первую запись набора.
Last	Переход на последнюю запись набора.
FieldByName(FieldName)	Возвращает значение поля по имени. Также возможно указание имени поля как свойства объекта.
Field(Table, ID, FieldName)	Возвращает значение поля FieldName записи с кодом ID таблицы Table. Набор данных, если он открыт, при этом не закрывается. Первичный ключ таблицы должен называться «code». Гарантированно работает только с MYSQL!!!
GetSQLValue(Query)	Выполняет SQL-запрос. Текст запроса должен начинаться с первого символа строки (перед запросом не должно быть пробелов, переносов строк, комментариев и т.д.). Если запрос Insert – возвращает ID вставленной записи. Если запрос – Update, Delete, Replace, Set, Start, Commit, Rollback – возвращает количество измененных записей (RowsAffected), иначе – Select – значение первого поля первой строки результа как текст.
FillText(s)	Возвращает строку s с замененными названиями полей между знаками процента на соответствующие значения текущей записи. Так же в строке возможно использование интерпретируемого кода, заключенного между тегами "<?>" и ">". При интерпретации система сначала производит замену полей с процентами на значения, потом интерпретирует код. При этом создается новый объект интерпретатора, поэтому набор переменных и объектов в этом контексте не связан с глобальным контекстом, в котором выполняется функция FillText. В данном контексте автоматически создается объект TSelfADO, подключенный к той же БД, что и контекст, вызвавший функцию, с пустым именем, а так же с именем "dataset".
Query(Query)	Синоним GetSQLValue.
Close	Закрывает набор данных.
Self	Возвращает указатель на подключение к БД для использования в других объектах.

Пример использования – см. TSelfADO

Объект TSelfADO

Наследник объекта TADO. Служит для подключения к «родной» для программы, в которой выполняется скрипт, базе данных. Обладает всеми свойствами и методами объекта TADO, кроме Connect. Иногда автоматически создается системой для обеспечения простого доступа к базе данных, а также иногда создается системой с уже открытым набором данных для передачи обрабатываемого системой набора данных в скрипт. В этом случае для скрипта недоступны функции Open и Close.

Пример использования:

rem('Копируем данные из «родной» базы данных в базу MSSQL.');
       new('TSelfADO', 'MyDB');
       new('TADO', 'MSSQL');
       MSSQL.Connect('Provider=SQLOLEDB.1;Password=myPassword;Persist Security Info=True;User ID=myUsername;Initial Catalog=myDataBase;Data Source=myServerAddress');
       MyDB.Open('select code, name, passport from kurier where code>'+Int(MSSQL.Query('select max(code) from kurier'))+' order by code');
       While(MyDB.EOF=0,
               MSSQL.Query('insert kurier (code, name, passport) VALUES ('+MyDB.Code+', '+QuotedStr(MyDB.Name)+', '+QuotedStr(MyDB.Passport)+')');
               MyDB.Next;
             )

Объект TPrinter

Предназначен для доступа к принтерам.

Функции:

BeginDoc – Начинает новый документ.

EndDoc – Закрывает документ

PageHeight – Возвращает высоту страницы в пикселях

PageWidth – Возвращает ширину страницы в пикселях

PageNumber – Возвращает номер текущей страницы документа

Orientation – Возвращает текущую ориентацию страницы (0 – портретная, 1 – ландшафтная)

Printing – Возвращает истину если документ открыт

SetOrientation(Orientation) – Устанавливает ориентацию страницы. При необходимости начинает новый документ, новую страницу.

ShowDialog – Показывает пользовательский диалог печати

NewPage – Начинает новую страницу

Canvas – Предоставляет доступ к объекту TCanvas, связанному с принтером.

PrinterNames – Возвращает список принтеров, установленных в системе, разделенный переносами строк

PrintersCount – Возвращает количество установленных в системе принтеров

SetPrinter(Printer) – Устанавливает текущий принтер. Если передана строка – ищет принтер по названию, иначе – по номеру. Нумерация начинается с 0.

PrintTable(Y, Table) – Выводит на печать таблицу Table типа TTable, начиная с координаты Y. При необходимости таблица печатается на нескольких страницах. Возвращает координату Y конца таблицы.

Объект TCanvas

Предоставляет доступ к холсту объекта для прорисовки изображения.

Функции:

DPIX – Возвращает разрешение холста по горизонтали в точках на дюйм

DPIY – Возвращает разрешение холста по вертикали в точках на дюйм

TextOut(x, y, s[, x1, y1, x2, y2]) – Выводит строку s начиная с точки с координатами x и y. Если указаны параметры x1, y1, x2, y2 – то выводимый текст ограничивается заданным прямоугольником.

TextOutEx(x1, y1, x2, y2, Alignment, Font, s, Indent) – Выводит строку s в прямоугольнике с координатами x1, y1, x2, y2. По горизонтали строка выравнивается в соответствии с Alignment (0 – прижато влево, 1 – вправо, 2 – по центру), по вертикали выравнивается по центру. Используя шрифт Font (см описание ниже). Indent – отступ по горизонтали, расстояние в пикселях между границей прямоугольника и текстом. Функция возвращает координату X фактического окончания текста (правой стороны – если строка прижата влево, и левой – в остальных случаях)

MLTextOut(x1, y1, x2, y2, Alignment, VAlignment, Font, s, Heigth, Indent) – Выводит многострочный текст s в прямоугольнике с координатами x1, y1, x2, y2 с переносом по словам. По горизонтали строки выравниваются в соответствии с Alignment, по вертикали – в соответствии с VAlignment (0 – прижато вверх, 1 – по центру, 2 – прижато вниз). Используя шрифт Font (см описание ниже). Heigth – высота строки. Если опущено или равно нулю – высота определяется автоматически в соответствии с выбранным шрифтом. Indent – отступ по горизонтали, расстояние в пикселях между границей прямоугольника и текстом. Функция возвращает координату Y фактического окончания текста (нижней границы последней строки текста. ВНИМАНИЕ! Функция использует координаты прямоугольника для позиционирования текста, однако она не ограничивает его верхней и нижней границами этого прямоугольника!

DrawPic(x1, y1, x2, y2, Pic, Style, Alignment) – Прорисовывает изображение Pic (ссылка на изображение TPicture.Self) в прямоугольник заданный координатами x1-y2. Style – стиль масштабирования. 0 – растянуть изображение до границ прямоугольника не сохраняя пропорции, 1 – вписать изображение в прямоугольник сохраняя пропорции – вероятно, останутся поля по вертикали или горизонтали, 2 – вписать сохраняя пропорции, обрезав при необходимости изображение по вертикали или горизонтали. Alignment – выравнивание по горизонтали. Работает только в случае если style=1 и при растягивании изображения получились вертикальные поля. 0 – разместить по центру, 1 – прижать влево, 2 – прижать вправо. Функция возвращает координату X правой стороны изображения кроме случая, когда Style=1 и Alignment=2 – в этом случае возвращается координата левой стороны изображения.

FillRect(x1, y1, x2, y2) – Закрашивает прямоугольник цветом BrashColor

Rect(x1, y1, x2, y2) – Закрашивает прямоугольник цветом BrashColor.

SetFont(Font) – Устанавливает шрифт по-умолчанию.

TextHeight(s) – Возвращает высоту текста s в пикселях без учета многострочности, с учетом текущего шрифта.

TextWidth(s) – Возвращает ширину текста s в пикселях без учета многострочности, с учетом текущего шрифта.

Использование шрифта (Font): У объекта TCanvas есть «глобальные» установки шрифта. Однако для некоторых функций возможно указание шрифта, отличающегося от глобального. Параметры шрифта – это текстовая строка, состоящая из 6-ти параметров, разделенных запятыми: Название, размер, жирный, курсив, подчеркнутый, цвет. Например:

'Times New Roman, 8, Y, N, N, 255'

Любой параметр можно опустить, и тогда вместо него будет использовано значение по-умолчанию: шрифт: arial, размер – 10, не жирный, не курсив, не подчеркнутый, цвет – черный. Например: ', 7' – указывает, что по-умолчанию нужно взять все параметры кроме размера шрифта. Также можно вместо всей строки указать тире ('-') или пустую строку, и шрифт будет использоваться «глобальный».

Объект TPicture

Предоставляет функции для работы с графическими изображениями форматов BMP и Jpeg, а также для формирования штрих-кодов.

Функции:

LoadFromFile(FileName) – Загружает изображение из файла FileName. Возвращает истину, если операция прошла успешно, иначе – ложь.

LoadFromDB(DB, Query) – Загружает изображение из базы данных. DB – ссылка на подключение к базе данных TADO.Self, Query – текст запроса. Запрос должен вернуть в первом поле первой строки BLOB-поле с изображением, все остальные данные возвращаемые запросом игнорируются. Возвращает истину, если операция прошла успешно, иначе – ложь.

CreateEan(Width, Height, BarCode, Textless) – Формирует штрих-код EAN13 c шириной Width и высотой Height. BarCode – текст штрих-кода. Должен быть цифровым 12 или 13 символов (13-й, контрольная сумма рассчитывается автоматически). Булево значение Textless указывает, что в штрих-коде не должно быть человеко-читаемых символов если истинно. Внимание! Ширина штрих-кода Width не является точным значением получаемого на выходе изображения. Ширина изображения рассчитывается как максимальное кратное минимально возможной ширине, но не меньше минимально возможной. Конечную ширину можно получить в соответствующем свойстве объекта.

Create128(Width, Height, BarCode, Textless) – Формирует штрих-код CODE128 c шириной Width и высотой Height. BarCode – текст штрих-кода. Булево значение Textless указывает, что в штрих-коде не должно быть человеко-читаемых символов если истинно. Внимание! Ширина штрих-кода Width не является точным значением получаемого на выходе изображения. Ширина изображения рассчитывается как максимальное кратное минимально возможной ширине, но не меньше минимально возможной. Конечную ширину можно получить в соответствующем свойстве объекта.

Width – Возвращает ширину изображения.

Height – Возвращает высоту изображения.

Rotate(Angle) – Поворачивает изображение по часовой стрелке на угол Angle. Угол указывается в градусах и может принимать любые значения.

Self – Ссылка на объект с изображением, используется в качестве параметра для функций, работающих с изображениями из данного объекта.

Объект TTable

Предоставляет функции для работы с таблицами.

Функции:

LoadFromDB(DB) – Загружает таблицу из набора данных, открытого в объекте DB типа TADO. Таблица загружается вместе с заголовками. Если название поля содержит подстроку «_RecNo» - данная подстрока не попадет в заголовок, а все значения поля будут заменены на порядковый номер записи в наборе данных, начиная с «1». В одной таблице допускается не более одного поля с порядковой нумерацией. Поля, названия которых начинаются в символа "-" не выгружаются. Заголовок – это первая строка таблицы.

Cell(С, R) – Возвращает значение ячейки таблицы с координатами (C, R). Нумерация строк и столбцов начинается с 1.

RowCount – Возвращает количество строк в таблице.

ColCount – Возвращает количество столбцов в таблице.

SetTitleFont(Font) – Задает шрифт заголовка таблицы (первой строки).

SetFont(Font) – Задает шрифт всей таблицы кроме заголовка.

SetIndent(Indent) – Задает отступ от границы ячейки до текста в процентах от ширины страницы.

SetWidth(С, Width) – Задает значение ширины столбца C в процентах от ширины страницы.

SetMinRowHeght (Heght) – Задает значение минимальной высоты строки.

SetBarCode(Col, Type) - Указывает, что данные из столбца Col должны печататься в виде штрих-кода. Тип штрих-кода - Type. Поддерживается только "1" - EAN13. Для кода EAN13 данные в столбца должны иметь вид "тип штрих-кода, номер", например "7, 123" (без кавычек, конечно). В этом случае система сформирует штрих-код: "2700000001233". Первая цифра - всегда 2, далее - указанный тип штрих-кода, нули, чтобы получилось 13 символов, номер, указанный в таблице, и один символ - контрольная сумма.

SetColFont

Self – Ссылка на объект с таблицей, используется в качестве параметра для функций, работающих с таблицами из данного объекта.

Объект TBaseUtils

Предоставляет функции, базирующиеся на БД системы «Курьерская служба 2008». По-умолчанию, при создании подключается к основной базе данных модуля, в котором выполняется скрипт, если такая определена контекстом, однако это можно изменить, см SetConnection.

Функции:

MakeAddress(s) – возвращает значение, полученное путем преобразований адреса s для приведения его к внутреннему формату программы. В процессе преобразования до нескольких раз происходит замена буквосочетаний по таблице замены (ее редактирование доступно по нажатию кнопки «Автозамена» в интерфейсе импорта БД из Excel системы (см. Руководство пользователя)), поиск улиц по базе КЛАДР с точностью до одного знака, и некоторые другие операции, нацеленные на исправление ошибок в написании адреса.

GetStationCode(s) – возвращает код станции метро, ассоциированный в системе с адресом s. В случае невозможности идентифицировать станцию метро – возвращает 0.

SetConnection(DB) – Подключает объект к базе данных DB, где DB – ссылка на объект TADO.Self. ВРЕМЕННО НЕ РАБОТАЕТ!

SetTown(Town) – Устанавливает код текущего города (используется в некоторых функциях объекта) в значение Town. По-умолчанию текущий город – 1. ВРЕМЕННО НЕ РАБОТАЕТ!

SetIndexLength(Length) – Устанавливает длину почтового индекса. По-умолчанию – 6.

LogTable(Table, Code, User) – Добавляет в журнал истории запись таблицы с кодом Table, с кодом Code. Если запись отсутствует – добавляется запись об удалении пользователем с кодом User.

GetIndex(Address) – Возвращает почтовый индекс из адреса.

TownByIndex(Index) – Возвращает код города по индексу. В случае ошибки поиска – код текущего города.

TownByName(Name) – Возвращает код города по имени. В случае ошибки поиска – код текущего города.

FillClientInfo(Excel, client, Sheet, Row, Col) – Выводит в эксель информацию о клиенте с кодом client на лист sheet начиная со строки row и столбца col.

SavePrintFormToFile(FormType, FormNumber) - Сохраняет на диске файл печатной формы и возвращает путь к нему

CreateTrans(Address[, Store]) - Формирует запись для печати кассового чека для корреспонденции с кодом Address, для выбора кассового аппарата используется код склада Store. Если Store не указано - при исполнении в среде клиентского модуля системы использует склад, указанный пользователем в окне "Настройка" - "Параметры", в остальных модулях - код текущего склада из переменной "CL" ("Текущий филиал"). Возвращает идентификатор записи чека. В случае ошибки вызывает ошибку, поэтому рекомендуется использовать с функцией Try.

Объект TBaseSupport

Предоставляет функции системы «Курьерская служба 2008». Создается только автоматически контекстом.

Функции:

UserCode - Возвращает код текущего пользователя из таблицы «Пользователи» (users).

UserName - Возвращает имя текущего пользователя из таблицы «Пользователи» (users).

UserPass - Возвращает пароль текущего пользователя.

UserBaseCode – Возвращает код текущего пользователя из таблицы «Сотрудники» (kurier).

UserEmail - Возвращает e-mail текущего пользователя.

CurrentTown – Возвращает код текущего города (из таблицы town).

CurrentCity – Возвращает код текущего региона (из таблицы city).

CurrentLocation – Возвращает код текущего филиала (из таблицы store).

Объект TINIFile

Предоставляет функции работы с ini-файлами. В некоторых контекстах создается автоматически для предоставления доступа к настроечному файлу модуля, выполняющего скрипт.

Функции:

IniParam(s) – Существует только если имя экземпляра объекта пустое. Возвращает значение параметра s ini-файла секции «common». В случае отсутствия параметра в файле возвращает пустую строку.

Param(s) – Синоним IniParam с тем отличием, что существует только если имя объекта непустое.

Объект TSMS

Предназначен для отправки SMS, а также проверки статуса их доставки.

Функции:

Connect(Provider, Host, User, Pass, SenderName, SMSPrefix) – Подключает объект к провайдеру provider, используя адрес Host, имя пользователя User и пароль Pass. Значение SMSPrefix предназначено для того, чтобы провайдер мог различить сообщения от разных филиалов, если этими филиалами используется одно подключение. Если необходимости разделять сообщения нет - значение SMSPrefix можно не указывать. Для провайдера доступны значения 'zanzara', 'sms16', 'mirsms', 'websms', 'epochta', 'SMSManager', либо можно указать числовые значения номера протокола, от 1 до 6 соответственно. Эти значения соответствуют значениям переменной SMSProtocol таблицы "Value".

SendSMS(Phone, Text, [ID]) – Отправляет SMS с текстом Text на телефон Phone. Для некоторых провайдеров необходим уникальный идентификатор сообщения ID. Возвращает ID провайдера для последующей проверки статуса доставки.

CheckSMS(ProviderID) – Проверяет состояние доставки сообщения с идентификатором ProviderID. Возвращает: 0 – доставляется, 1 – успешно доставлено, 2 – не доставлено.

ReceiveSMS(InboxID, DateFrom, DateTo, NewOnly) - Получает входящие SMS, с ящика InboxID (идентификатор выдаётся провайдером). DateFrom, DateTo - задается временной интервал в котором были приняты сообщения(формат 08.04.2013 18:00:00 'DD.MM.YYYY HH:NN:SS'). Чтобы получать только новые сообщение поле NewOnly должно быть True. Возвращает XML с сообщениями

Объект TXML

Предназачен для парсинга XML-данных.

Функции:

SetText(S) – Задает текст XML документа для парсинга, делает текущим корневой элемент.

NodeValue – Возвращает значение текущего элемента.

NodeName – Возвращает имя текущего элемента.

OpenChild(V) – Ищет дочерний элемент и делает его текущим. Если V – число – ищет по номеру, если V – текст – ищет по названию. Возвращает значение найденного элемента, или пустую строку, если элемент не найден. Нумерация элементов начинается с нуля.

ChildrenCount – Возвращает количество дочерних элементов.

ChildNodeValue(V) – Ищет дочерний элемент и возвращает его значение. Если V – число – ищет по номеру, если V – текст – ищет по названию.

OpenParent – Делает текущим родительский элемент. Возвращает значение найденного элемента.

AttribCount – Возвращает количество атрибутов текущего элемента.

AttribName(i) – Возвращает имя атрибута с номером i.

Attrib(V) – Ищет атрибут и возвращает его значение. Если V – число – ищет по номеру, если V – текст – ищет по названию.

Reset – Делает текущим корневой элемент, возвращает его значение.

Объект TJSON

Предназачен для парсинга JSON-данных.

Функции:

SetText(S) – Задает текст JSON документа для парсинга, делает текущим корневой элемент.

NodeValue – Возвращает значение текущего элемента.

NodeName – Возвращает имя текущего элемента.

OpenChild(V) – Ищет дочерний элемент и делает его текущим. Если V – число – ищет по номеру, если V – текст – ищет по названию (регистрозависимый поиск). Возвращает значение найденного элемента, или пустую строку, если элемент не найден. Нумерация элементов начинается с нуля.

ChildrenCount – Возвращает количество дочерних элементов.

ChildNodeValue(V) – Ищет дочерний элемент и возвращает его значение. Если V – число – ищет по номеру, если V – текст – ищет по названию (регистрозависимый поиск).

OpenParent – Делает текущим родительский элемент. Возвращает значение найденного элемента.

Reset – Делает текущим корневой элемент, возвращает его значение.

isArray - Возвращает true, если текущий элемент является массивом (доступ к дочерним элементам возможен только по индексу, нумерация элементов начинается с нуля)

Объект TBase

Функции общего назначения:

execsimplescript(Caption, Text) - Выполняет скрипт "Дополнительных возможностей". Возвращаемые значения, введенные пользователем устанавливает в переменные $scriptvar1..$scriptvarN. Функция возвращает истину, если пользователь нажал "OK" в диалоговом окне.

FillExcelDoc(Excel, Dataset, FormType, FormNumber) - Выполняет указанную печатную форму в объекте excel. Dataset объект с данными для скрипта в печатной форме, может быть null. Например:

new('TExcel', 'excel');
FillExcelDoc(excel.self, null, 12, 1);
excel.DoNotDestroy(true);
excel.SetVisible(true);
Покажет эксель с выполненной печатной формой

PrintSticker(Codes)

GetItemByName(Name)

GetKurierByStation(station, Mass, Cash, Date_Putn)

Функции, работающие только в импорте БД из эксель:

ReplaceAddress

GetItemByCode

GetPrice

GetNewNumber

GetNewPos

Zakaz

addresscode

Source

Применение языка формул

в различных контекстах системы «Курьерская служба 2008» и сопутствующих проектах

Курьерская служба 2008

Дополнительная информация на чеке

В карточке клиента на закладке «Касса» имеется поле для ввода текста, который будет отображаться на кассовых чеках, печатаемых для корреспонденции от данного клиента. В поле может быть введен как просто текст, так и интерпретируемый скрипт, начинающийся с признака скрипта: «<?>». В контексте выполнения скрипта система создает объекты:

TSelfDB с открытым набором данных со строчкой корреспонденции, заказа и клиента, на которую печатается чек

TBaseSupport

TBaseValue

Все объекты создаются с пустыми именами.

Так же система записывает в переменную $CashRegisterID вычисленный код фискального регистратора, на котором предполагается печать чека.

Результат работы скрипта печатается на создаваемом чеке, если скрипт не возвращает значение “-1” (число или текст) – в этом случае система чек не создает. Подразумевается, что либо скриптом было принято решение об отсутствии необходимости формирования чека, либо скрипт взял эту функцию на себя.

Прайс лист клиента

Формула возвращает сумму в валюте клиента для каждой поездки (туда или обратно) единицы корреспонденции, которая добавляется к штатному ценообразованию. Если формула установила в значение «Истина» переменную «$FormulaReplace», то значение, возвращаемое формулой заменяет штатное ценообразование. Помимо стандартных объектов, система создает объект AddressRecord, в котором, как свойства, доступны все поля текущей записи. Так же она выставляет значение переменной $Forward в 1 (истина), если необходимо произвести расчет для направления "Туда" и 0 (ложь) - если обратно. ВНИМАНИЕ! Как и во всех остальных местах, после формулы нельзя ставить ";", иначе скрипт вернет 0!

Например:

if(int(AddressRecord.Time_Put_Max)>19, 100, 0)

Прибавляет 100 рублей в случае, если максимальный срок доставки 20 часов или более

if(pos(AddressRecord.Address, 'Аренда')>0, 
          set($FormulaReplace, 1); 
          1500
, 0)

В случае наличия подстроки "Аренда" в адресе заменяет штатное ценообразование на 1500 рублей

Объект AddressRecord может предоставить доступ к связанным таблицам userfields и boxes. Чтобы получить доступ к полю VarCode из таблицы userfields необходимо записать AddressRecord.Userfields.VarCode. В присоединённой таблице может быть несколько записей чтобы получить к ним доступ предусмотрены функции _First, _EOF, _Next.

Например:

set($value1, 0); set($value2, 0);
while(AddressRecord.userfields._EOF=0,
  if(AddressRecord.userfields.varCode=1, 
    set($value1, if(AddressRecord.userFields.VarValue='Праздничная упаковка', 150, 0)), '');
  if(AddressRecord.userfields.varCode=2, 
    set($value2, AddressRecord.userFields.VarValue), '');
  AddressRecord.userFields._Next;
);
int($value1) + int($value2)

В скрипте доступна переменные: «$FormulaKoeff» - это коэффициент на который умножится конечная цена (по умолчанию равна 1); «$PriceCode» - код прайса

Зарплата курьеров

Формула возвращает сумму в основной валюте для каждой единицы корреспонденции, которая добавляется к штатному ценообразованию. Если формула установила в значение «Истина» переменную «$FormulaReplace», то значение, возвращаемое формулой заменяет штатное ценообразование.

Планировщик

В поле текста задания может быть введен как текст с командами планировщика (см ниже), так и интерпретируемый скрипт, начинающийся с признака скрипта: «<?>». В контексте выполнения скрипта система создает объекты:

TIniFile, Указывает на настроечный ini-файл планировщика.

Все объекты создаются с пустыми именами.

Прочее

ReplaceAddress(target, address) – Возвращает адрес последней доставки корреспонденции получателю target по адресу address от текущего клиента. При отсутствии такой доставки, возвращает address.

GetPrice –возвращает рассчитанное значение цены, на основе прайс-листа клиента и данных о корреспонденции.

GetKurierByStation(i) – возвращает код курьера, ассоциированного со станцией метро с кодом i.

GetNewNumber – Возвращает не занятый номер единицы корреспонденции в текущем заказе.

История изменений

Добавлено:	Функция FixedIntToStr
Добавлено:	Функция TimePeriod
Добавлено:	В интерпретатор добавлена функция приёма смс - ReceiveSMS
Добавлено:	Функция STR2UTF
Добавлено:	Функция SAVETOFILE
Добавлено:	Функция TExcel.SetSheetName
Добавлено:	В пользовательские отчеты добавлен тип "FILESTR"

Версия 308   24.11.2012

Добавлено:	В функции загрузки таблиц из TADO добавлено условие, что поля, названия которых начинаются с "-" не выгружаются. Таким образом можно скрывать служебные поля из результирующего набора.
Добавлено:	Функция TExcel.RowAutoFit
Добавлено:	Функция TExcel.RowInsert

Версия 300   01.11.2012

Добавлено:	В объекте TCSVFile добавилась возможность запрашивать значения не только текущей записи через параметр сдвига
Добавлено:	В пользовательские отчеты добавлен тип "UPDOWN"
Добавлено:	В интерпретатор добавлен объект TCSVFile

Версия 266   14.09.2012

Добавлено:

В интерпретатор добавлена поддержка массивов

Версия 265   11.09.2012

Добавлено:

Функция CreateTrans в интерпретатор