Файловые операции

Группа функций для работы с файлами.

По соображениям безопасности в языке MQL5 строго контролируется работа с файлами. Файлы, с которыми проводятся файловые операции средствами языка MQL5, не могут находиться за пределами файловой системы терминала.

Существует два каталога (с подкаталогами), в которых могут располагаться рабочие файлы:

• папка_данных_терминала\MQL5\FILES\ (выберите для просмотра в терминале пункт меню «Файл»-«Открыть каталог данных»);
• общая папка всех установленных на компьютере терминалов  – обычно расположена в каталоге C:\Documents and Settings\All Users\Application Data\MetaQuotes\Terminal\Common\Files.

Программным путем можно получить наименования этих каталогов с помощью функции TerminalInfoString(), используя перечисление ENUM_TERMINAL_INFO_STRING:

//--- Папка, в которой хранятся данные терминала
string terminal_data_path=TerminalInfoString(TERMINAL_DATA_PATH);
//--- Общая папка всех клиентских терминалов
string common_data_path=TerminalInfoString(TERMINAL_COMMONDATA_PATH);

Работа с файлами из других каталогов запрещена!

Файловые функции позволяют работать с так называемыми «именованными каналами». Для этого достаточно вызвать функцию FileOpen() с соответствующими параметрами.

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

 

FileFindFirst

Начинает перебор файлов и поддиректорий в соответствующей директории в соответствии с указанным фильтром.

long FileFindFirst(
 const string file_filter, // строка - фильтр поиска
 string& returned_filename, // имя найденного файла или поддиректории
 int common_flag=0 // определяет область поиска
 );

Параметры

file_filter — [in] Фильтр поиска. В фильтре может быть указана поддиректория (или последовательность вложенных поддиректорий) относительно директории \Files, в которой необходимо проводить перебор файлов.

returned_filename — [out] Возвращаемый параметр, куда в случае удачи помещается имя первого найденного файла или поддиректории. Возвращается только имя файла (включая расширение) без указания директорий и поддиректорий, независимо от того, указывались ли они в фильтре для поиска.

common_flag — [in] Флаг, определяющий местоположение файла. Если common_flag=FILE_COMMON, то файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае файл находится в локальной папке.

Возвращаемое значение

Возвращает хэндл объекта поиска, который необходимо использовать для дальнейшего перебора файлов и поддиректорий функцией FileFindNext(), либо INVALID_HANDLE в случае, когда нет ни одного файла и поддиректории, соответствующего фильтру (в частном случае – директория пуста). После окончания поиска хэндл необходимо закрыть при помощи функции FileFindClose().

Примечание

Из соображений безопасности в языке MQL5 строго контролируется работа с файлами. Файлы, с которыми проводятся файловые операции средствами языка MQL5, не могут находиться за пределами файловой системы терминала.

 

FileFindNext

Продолжает поиск, начатый функцией FileFindFirst().

bool FileFindNext(
 long search_handle, // handle поиска
 string& returned_filename // имя найденного файла или поддиректории
 );

Параметры

search_handle — [in] Хэндл поиска, полученный функцией FileFindFirst().

returned_filename — [out] Имя следующего найденного файла или поддиректории. Возвращается только имя файла (включая расширение) без указания директорий и поддиректорий, независимо от того, указывались ли они в фильтре для поиска.

Возвращаемое значение

В случае удачи возвращает true, иначе false.

 

FileFindClose

Закрывает хэндл поиска.

void FileFindClose(
 long search_handle // handle поиска
 );

Параметры

search_handle — [in] Хэндл поиска, полученный функцией FileFindFirst().

Возвращаемое значение

Нет возвращаемого значения.

Примечание

Функцию необходимо вызывать, чтобы освобождать системные ресурсы.

 

FileIsExist

Проверяет существование файла.

bool FileIsExist(
 const string file_name, // имя файла
 int common_flag=0 // зона поиска
 );

Параметры

file_name — [in] Имя проверяемого файла.

common_flag=0 — [in] Флаг, определяющий местоположение файла. Если common_flag=FILE_COMMON, то файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае файл находится в локальной папке.

Возвращаемое значение

Возвращает true, если указанный файл существует.

Примечание

Проверяемый файл может оказаться поддиректорией. В этом случае функция FileIsExist() возвратит false, а в переменную _LastError будет записана ошибка 5018 — «Это не файл, а директория» (смотрите пример для функции FileFindFirst).

Если common_flag=FILE_COMMON, то функция ищет указанный файл в общей папке всех клиентских терминалов \Terminal\Common\Files, в противном случае функция ищет файл в локальной папке (MQL5\Files или MQL5\Tester\Files в случае тестирования).

 

FileOpen

Функция открывает файл с указанным именем и указанными флагами.

int FileOpen(
 string file_name, // имя файла
 int open_flags, // комбинация флагов
 short delimiter='\t', // разделитель
 uint codepage=CP_ACP // кодовая страница
 );

Параметры

file_name — [in] Имя открываемого файла, может содержать подпапки. Если файл открывается для записи, то указанные подпапки будут созданы в случае их отсутствия.

open_flags — [in] комбинация флагов, определяющая режим работы с файлом. Флаги определены следующим образом:

• FILE_READ файл открывается для чтения
• FILE_WRITE файл открывается для записи
• FILE_BIN двоичный режим чтения-записи (без преобразования из строки и в строку)
• FILE_CSV файл типа csv (все записанные элементы преобразуются к строкам соответствующего типа, unicode или ansi, и разделяются разделителем)
• FILE_TXT простой текстовый файл (тот же csv, однако разделитель не принимается во внимание)
• FILE_ANSI строки типа ANSI (однобайтовые символы)
• FILE_UNICODE строки типа UNICODE (двухбайтовые символы)
• FILE_SHARE_READ совместный доступ по чтению со стороны нескольких программ
• FILE_SHARE_WRITE совместный доступ по записи со стороны нескольких программ
• FILE_COMMON расположение файла в общей папке всех клиентских терминалов \Terminal\Common\Files.

delimiter=’\t’ — [in] значение, используемое в качестве разделителя в txt или csv-файле. Если для csv-файла разделитель не указан, то по умолчанию используется символ табуляции. Если для txt-файла разделитель не указан, то никакой разделитель не используется. Если в качестве разделителя явно задано значение 0, то никакой разделитель не используется.

codepage=CP_ACP — [in] Значение кодовой страницы. Для наиболее употребимых кодовых страниц предусмотрены соответствующие константы.

Возвращаемое значение

В случае успешного открытия функция возвращает хэндл файла, который затем используется для доступа к данным файла. В случае неудачи возвращает INVALID_HANDLE.

Примечание

Файл открывается в папке клиентского терминала в подпапке MQL5\Files (или каталог_агента_тестирования\MQL5\Files в случае тестирования). Если среди флагов указан FILE_COMMON, то файл открывается в общей папке всех клиентских терминалов \Terminal\Common\Files.

Можно открывать «именованные каналы» по следующим правилам:

Имя канала — строка, которая должна иметь вид: «\\servername\pipe\pipename», где servername — имя сервера в сети, а pipename — имя канала. Если каналы используются на одном и том же компьютере, имя сервера может быть опущено, но вместо него нужно поставить точку: «\\.\pipe\pipename». Клиент, который пытается соединиться с каналом, должен знать его имя.
Необходимо вызывать FileFlush() и FileSeek() на начало файла между последовательными операциями чтения из канала и записи в канал.

В приведенных строках используется специальный символ обратная косая черта ‘\’, поэтому при написании имени в MQL5 программе ‘\’ необходимо удваивать, то есть вышеприведенный пример написать в коде как «\\\\servername\\pipe\\pipename».

 

FileClose

Закрытие файла, ранее открытого функцией FileOpen().

void FileClose(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Нет возвращаемого значения.

 

FileCopy

Копирует исходный файл из локальной или общей папки в другой файл.

bool FileCopy(
 const string src_file_name, // имя файла источника
 int common_flag, // расположение файла
 const string dst_file_name, // имя файла назначения
 int mode_flags // способ доступа и/или расположение файла
 );

Параметры

src_file_name — [in] Имя файла для копирования.

common_flag — [in] Флаг, определяющий местоположение файла. Если common_flag=FILE_COMMON, то файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае файл находится в локальной папке (например, common_flag=0).

dst_file_name — [in] Имя результатного файла.

mode_flags — [in] Флаги доступа. Параметр может содержать только 2 флага: FILE_REWRITE и/или FILE_COMMON — остальные флаги игнорируются. Если файл уже существует и при этом не был указан флаг FILE_REWRITE, то файл не будет переписан, и функция возвратит false.

Возвращаемое значение

В случае неудачи функция возвращает false.

Примечание

Если новый файл существовал, то копирование будет производиться в зависимости от наличия флага FILE_REWRITE в значении параметра mode_flags.

 

FileDelete

Удаляет указанный файл в локальной папке клиентского терминала.

bool FileDelete(
 const string file_name, // имя удаляемого файла
 int common_flag=0 // местоположение удаляемого файла
 );

Параметры

file_name — [in] Имя файла.

common_flag=0 — [in] Флаг, определяющий местоположение файла. Если common_flag=FILE_COMMON, то файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае файл находится в локальной папке.

Возвращаемое значение

В случае неудачи функция возвращает false.

Примечание

Удаляет указанный файл в локальной папке клиентского терминала (MQL5\Files или MQL5\Tester\Files в случае тестирования). Если же указан common_flag=FILE_COMMON, то функция удаляет файл из общей папки всех клиентских терминалов.

 

FileMove

Перемещает файл из локальной или общей папки в другую папку.

bool FileMove(
 const string src_file_name, // имя файла для операции перемещения
 int common_flag, // расположение файла
 const string dst_file_name, // имя файла назначения
 int mode_flags // способ доступа и/или расположение файла
 );

Параметры

src_file_name — [in] Имя файла для перемещения/переименования.

common_flag — [in] Флаг, определяющий местоположение файла. Если common_flag=FILE_COMMON, то файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае файл находится в локальной папке.(common_flag=0).

dst_file_name — [in] Имя результатного файла.

mode_flags — [in] Флаги доступа. Параметр может содержать только 2 флага: FILE_REWRITE и/или FILE_COMMON — остальные флаги игнорируются. Если файл уже существует и при этом не был указан флаг FILE_REWRITE, то файл не будет переписан, и функция возвратит false.

Возвращаемое значение

В случае неудачи функция возвращает false.

Примечание

Если новый файл существовал, то копирование будет производиться в зависимости от наличия флага FILE_REWRITE в значении параметра mode_flags.

 

FileFlush

Сброс на диск всех данных, оставшихся в файловом буфере ввода-вывода.

void FileFlush(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Нет возвращаемого значения.

Примечание

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

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

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

 

FileGetInteger

Получает целочисленное свойство файла. Существует 2 варианта функции.

1. Получение свойств по хэндлу файла.

long FileGetInteger(
 int file_handle, // хэндл файла
 ENUM_FILE_PROPERTY_INTEGER property_id // идентификатор свойства
 );

2. Получение свойств по имени файла.

long FileGetInteger(
 const string file_name, // имя файла
 ENUM_FILE_PROPERTY_INTEGER property_id, // идентификатор свойства
 bool common_folder=false // файл просматривается в локальной папке (false)
 ); // или в общей папке всех терминалов (true)

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

file_name — [in] Имя файла.

property_id — [in] Идентификатор свойства файла. Значение может быть одним из значений перечисления ENUM_FILE_PROPERTY_INTEGER. Если используется второй вариант функции, то можно получать значения только следующих свойств: FILE_EXISTS, FILE_CREATE_DATE, FILE_MODIFY_DATE, FILE_ACCESS_DATE и FILE_SIZE.

common_folder=false — [in] Указывает на местоположение файла. Если параметр равен false, то просматривается каталог данных терминала, в противном случае предполагается, что файл находится в общей папке всех клиентских терминалов \Terminal\Common\Files (FILE_COMMON).

Возвращаемое значение

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

Если при получении свойств по имени будет указан каталог, то функция в любом случае выставит ошибку 5018 (ERR_MQL_FILE_IS_DIRECTORY), при этом возвращаемое значение будет корректным.

Примечание

Функция всегда изменяет код ошибки. При успешном завершении код ошибки сбрасывается в ноль.

 

FileIsEnding

Определяет конец файла в процессе чтения.

bool FileIsEnding(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Функция возвращает true в случае, если в процессе чтения или перемещения файлового указателя достигнут конец файла.

Примечание

Для определения конца файла, функция пытается провести чтение следующей строки из файла. Если ее не существует, то функция возвращает true, в противном случае false.

 

FileIsLineEnding

Определяет конец строки в текстовом файле в процессе чтения.

bool FileIsLineEnding(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Возвращает true в случае, если в процессе чтения txt или csv-файла достигнут конец строки (символы CR-LF).

 

FileReadArray

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

uint FileReadArray(
 int file_handle, // handle файла
 void& array[], // массив для записи
 int start=0, // стартовая позиция для записи в массив
 int count=WHOLE_ARRAY // сколько читать
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

array[] — [out] Массив, куда данные будут загружены.

start=0 — [in] Стартовая позиция для чтения из массива.

count=WHOLE_ARRAY — [in] Количество элементов для чтения.

Возвращаемое значение

Количество прочитанных элементов. По умолчанию, читает весь массив (count=WHOLE_ARRAY).

Примечание

Строковый массив может читаться только из файла типа TXT. При необходимости функция пытается увеличить размер массива.

 

FileReadBool

Читает из файла типа CSV строку от текущего положения до разделителя (либо до конца текстовой строки) и преобразует прочитанную строку в значение типа bool.

bool FileReadBool(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Прочитанная строка может иметь значения «true«, «false» или символьное представление целых чисел «0» или «1». Ненулевое значение преобразуется к логическому true. Функция возвращает полученное преобразованное значение.

 

FileReadDatetime

Читает из файла типа CSV строку одного из форматов: «YYYY.MM.DD HH:MI:SS», «YYYY.MM.DD» или «HH:MI:SS» — и преобразует её в значение типа datetime.

datetime FileReadDatetime(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа datetime.

 

FileReadDouble

Читает число двойной точности с плавающей точкой (double) из бинарного файла с текущего положения файлового указателя.

double FileReadDouble(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа double.

Примечание

Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError().

 

FileReadFloat

Читает число одинарной точности с плавающей точкой (float) из текущей позиции бинарного файла.

float FileReadFloat(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа float.

Примечание

Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError().

 

FileReadInteger

Читает из бинарного файла значение типа int, short или char в зависимости от указанной длины в байтах. Чтение производится с текущего положения файлового указателя.

int FileReadInteger(
 int file_handle, // handle файла
 int size=INT_VALUE // размер целого типа в байтах
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

size=INT_VALUE — [in] Количество байт (до 4 включительно), которые нужно прочитать. Предусмотрены соответствующие константы: CHAR_VALUE=1, SHORT_VALUE=2 и INT_VALUE=4, таким образом функция может прочитать целое значение типа char, short или int.

Возвращаемое значение

Значение типа int. Результат этой функции необходимо явно приводить к целевому типу, то есть тому типу данных, который требуется прочитать. Так как возвращается значение типа int, то его можно спокойно преобразовать в любое целое значение. Файловый указатель перемещается на количество считываемых байт.

Примечание

При чтении менее 4-х байт, полученный результат всегда будет положительным. Если читается один или два байта, то знак числа можно точно определить путем явного приведения соответственно к типу char (1 байт) или типу short (2 байта). Получение знака для трехбайтового числа является нетривиальным, так как нет соответствующего базового типа.

 

FileReadLong

Читает целое число типа long (8 байт) из текущей позиции бинарного файла.

long FileReadLong(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа long.

 

FileReadNumber

Читает из файла типа CSV строку от текущего положения до разделителя (либо до конца текстовой строки) и преобразует прочитанную строку в значение типа double.

double FileReadNumber(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа double.

 

FileReadString

Читает из файла строку с текущего положения файлового указателя.

string FileReadString(
 int file_handle, // handle файла
 int length=-1 // длина строки
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

length=-1 — [in] Количество символов для чтения.

Возвращаемое значение

Прочитанная строка(string).

Примечание

При чтении из bin-файла обязательно указывать длину читаемой строки. При чтении из txt-файла длину строки указывать не надо, будет прочитана строка от текущего положения до признака перевода строки «\r\n». При чтении из csv-файла длину строки также указывать не надо, будет прочитана строка от текущего положения до ближайшего разделителя либо до признака конца текстовой строки.

Если файл открыт с флагом FILE_ANSI, то прочитанная строка преобразовывается в Unicode.

 

FileReadStruct

Cчитывает из бинарного файла содержимое в структуру, переданную в качестве параметра. Чтение производится с текущего положения файлового указателя.

uint FileReadStruct(
 int file_handle, // handle файла
 const void& struct_object, // структура, куда происходит считывание
 int size=-1 // размер структуры в байтах
 );

Параметры

file_handle — [in] Файловый описатель открытого бинарного файла.

struct_object — [out] Ссылка на объект указанной структуры. Структура не должна содержать строки, динамические массивы, виртуальные функции, а также указатели на объекты и функции.

size=-1 — [in] Количество байт, которые нужно прочитать. Если размер не указан или указано большее количество байт, чем размер структуры, то используется точный размер указанной структуры.

Возвращаемое значение

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

 

FileSeek

Перемещает положение файлового указателя на указанное количество байт относительно указанного положения.

bool FileSeek(
 int file_handle, // handle файла
 long offset, // в байтах
 ENUM_FILE_POSITION origin // позиция для отсчета
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

offset — [in] Смещение в байтах (может принимать и отрицательное значение).

origin — [in] Точка отсчета для смещения. Может принимать одно из значений перечисления ENUM_FILE_POSITION.

Возвращаемое значение

В случае удачи функция возвращает true, в случае ошибки — false. Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError().

Примечание

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

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

 

FileSize

Возвращает размер файла в байтах.

ulong FileSize(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Значение типа int.

Примечание

Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError().

 

FileTell

Возвращает текущее положение файлового указателя соответствующего открытого файла.

ulong FileTell(
 int file_handle // handle файла
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

Возвращаемое значение

Текущая позиция файлового описателя в байтах от начала файла.

Примечание

Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError().

 

FileWrite

Запись данных в файл типа CSV или TXT, разделитель между данными вставляется автоматически, если он не равен 0. После записи в файл добавляется признак конца строки «\r\n».

uint FileWrite(
 int file_handle, // handle файла
 ... // список записываемых параметров
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

… — [in] Список параметров, разделенных запятыми, для записи в файл. Количество выводимых в файл параметров не должно превышать 63.

Возвращаемое значение

Количество записанных байт.

Примечание

При выводе числовые данные преобразуются в текстовый формат (см. функцию Print()). Данные типа double выводятся с точностью до 16 десятичных цифр после точки, при этом данные могут выводиться либо в традиционном либо в научном формате – в зависимости от того, как запись будет наиболее компактна. Данные типа float выводятся с 5 десятичными цифрами после точки. Для вывода вещественных чисел с другой точностью либо в явно указанном формате необходимо использовать функцию DoubleToString().

Числа типа bool выводятся в виде строк «true» или «false«. Числа типа datetime выводятся в формате «YYYY.MM.DD HH:MI:SS».

 

FileWriteArray

Записывает в файл типа BIN массивы любых типов, кроме строковых (может быть массив структур, не содержащих строки и динамические массивы).

uint FileWriteArray(
 int file_handle, // handle файла
 const void& array[], // массив
 int start=0, // начальный индекс в массиве
 int count=WHOLE_ARRAY // количество элементов
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

array[] — [out] Массив для записи.

start=0 — [in] Начальный индекс в массиве (номер первого записываемого элемента).

count=WHOLE_ARRAY — [in] Количество записываемых элементов (WHOLE_ARRAY означает, что записываются все элементы начиная с номера start до конца массива).

Возвращаемое значение

Количество записанных элементов.

Примечание

Строковый массив может записываться только в файл типа TXT. В этом случае строки автоматически завершаются символами конца строки «\r\n». В зависимости от типа файла ANSI или UNICODE, строки преобразовываются к ansi-кодировке, или нет.

 

FileWriteDouble

Записывает в файл значение параметра типа double с текущего положения файлового указателя.

uint FileWriteDouble(
 int file_handle, // handle файла
 double value // значения для записи
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

value — [in] Значение типа double.

Возвращаемое значение

В случае удачи функция возвращает количество записанных байт (в данном случае sizeof(double)=8). Файловый указатель перемещается на это же количество байт.

 

FileWriteFloat

Записывает в bin-файл значение параметра типа float с текущего положения файлового указателя.

uint FileWriteFloat(
 int file_handle, // handle файла
 float value // записываемое значение
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

value — [in] Значение типа float.

Возвращаемое значение

В случае удачи функция возвращает количество записанных байт (в данном случае sizeof(float)=4). Файловый указатель перемещается на это же количество байт.

 

FileWriteInteger

Записывает в bin-файл значение параметра типа int с текущего положения файлового указателя.

uint FileWriteInteger(
 int file_handle, // handle файла
 int value, // записываемое значение
 int size=INT_VALUE // размер в байтах
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

value — [in] Целое значение.

size=INT_VALUE — [in] Количество байт (до 4 включительно), которые нужно записать. Предусмотрены соответствующие константы: CHAR_VALUE=1, SHORT_VALUE=2 и INT_VALUE=4, таким образом функция может записать целое значение типа char, uchar, short, ushort, int или uint

Возвращаемое значение

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

 

FileWriteLong

Записывает в bin-файл значение параметра типа long с текущего положения файлового указателя.

uint FileWriteLong(
 int file_handle, // handle файла
 long value // записываемое значение
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

value — [in] Значение типа long.

Возвращаемое значение

В случае удачи функция возвращает количество записанных байт (в данном случае sizeof(long)=8). Файловый указатель перемещается на это же количество байт.

 

FileWriteString

Записывает в файл типа BIN, CSV или TXT значение параметра типа string с текущего положения файлового указателя. При записи в файл типа CSV или TXT, если в строке присутствует символ ‘\n’ (LF) без предшествующего символа ‘\r’ (CR), то перед символом ‘\n’ дописывается отсутствующий символ ‘\r’.

uint FileWriteString(
 int file_handle, // handle файла
 const string text_string, // записываемая строка
 int length=-1 // количество символов
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

text_string — [in] Строка.

length=-1 — [in] Количество символов, которые нужно записать. Параметр необходим для записи строки в файл типа BIN. Если размер не указан, то записывается вся строка без завершающего 0. Если указан размер меньший, чем длина строки, то записывается часть строки без завершающего 0. Если указан размер больший, чем длина строки, то строка дописывается соответствующим количеством нулей. Для файлов типа CSV и TXT этот параметр игнорируется и строка записывается полностью.

Возвращаемое значение

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

Примечание

Следует иметь в виду, что при записи в файл, открытый с флагом FILE_UNICODE (либо без флага FILE_ANSI), количество записанных байт будет в 2 раза больше количества записанных символов строки. При записи в файл, открытый с флагом FILE_ANSI, количество записанных байт будет совпадать с количеством записанных символов строки.

 

FileWriteStruct

Записывает в бинарный файл содержимое структуры, переданной в качестве параметра, с текущего положения файлового указателя.

uint FileWriteStruct(
 int file_handle, // handle файла
 const void& struct_object, // ссылка на объект
 int size=-1 // размер для записи в байтах
 );

Параметры

file_handle — [in] Файловый описатель, возвращаемый функцией FileOpen().

struct_object — [in] Ссылка на объект указанной структуры. Структура не должна содержать строки, динамические массивы, виртуальные функции, а также указатели на объекты и функции.

size=-1 — [in] Количество байт, которые нужно записать. Если размер не указан или указано большее количество байт, чем размер структуры, то записывается вся структура полностью.

Возвращаемое значение

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

 

FileLoad

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

bool FileLoad(
 int file_name, // имя файла
 const void& buffer[], // массив числовых типов или простых структур
 int common_flag=0 // файловый флаг, по умолчанию файл ищется в папке <каталог_данных>\MQL5\Files\
 );

Параметры

file_name — [in] Имя файла, из которого будет производиться считывание данных.

buffer — [out] Массив числовых типов или простых структур.

common_flag=0 — [in] Файловый флаг, указывающий режим работы. Если параметр не указан, то файл ищется в подпапке MQL5\Files (или <каталог_агента_тестирования>\MQL5\Files в случае тестирования).

Возвращаемое значение

Количество прочитанных элементов или -1 в случае неудачи.

Примечание

Функция FileLoad() читает из файла количество байт, кратное размеру элемента массива. Например, пусть размер файла составляет 10 байт, а чтение производится в массив типа double (sizeof(double)=8). В этом случае будет прочитано только 8 байт, оставшиеся 2 байта с конца файла просто будут отброшены, а сама функция FileLoad() вернёт 1 (прочитан 1 элемент).

 

FileSave

Записывает в бинарный файл все элементы массива, переданного в качестве параметра. Функция позволяет быстро в одну строку записывать массивы числовых типов или простых структур.

bool FileSave(
 int file_name, // имя файла
 const void& buffer[], // массив числовых типов или простых структур
 int common_flag=0 // файловый флаг, по умолчанию файлы пишутся в папку <каталог_данных>\MQL5\Files\
 );

Параметры

file_name — [in] Имя файла, в который будет записан массив данных.

buffer — [in] Массив числовых типов или простых структур.

common_flag=0 — [in] Файловый флаг, указывающий режим работы. Если параметр не указан, то файл будет записан в подпапке MQL5\Files (или <каталог_агента_тестирования>\MQL5\Files в случае тестирования).

Возвращаемое значение

В случае неудачи функция возвращает false.

 

FolderCreate

Создает директорию в директории Files (в зависимости от значения common_flag)

bool FolderCreate(
 string folder_name, // строка с именем создаваемой папки
 int common_flag=0 // область действия
 );

Параметры

folder_name — [in] Имя директории, которую требуется создать. Содержит полный путь к папке.

common_flag=0 — [in] Флаг, определяющий местоположение директории. Если common_flag=FILE_COMMON, то директория находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае директория находится в локальной папке (MQL5\Files или MQL5\Tester\Files в случае тестирования).

Возвращаемое значение

Возвращает true в случае успеха, иначе false.

Примечание

Из соображений безопасности в языке MQL5 строго контролируется работа с файлами. Файлы, с которыми проводятся файловые операции средствами языка MQL5, не могут находиться за пределами файловой системы терминала.

 

FolderDelete

Удаляет указанную директорию. Если папка не пуста, то она не может быть удалена.

bool FolderDelete(
 string folder_name, // строка с именем удаляемой папки
 int common_flag=0 // область действия
 );

Параметры

folder_name — [in] Имя директории, которую требуется удалить. Содержит полный путь к папке.

common_flag=0 — [in] Флаг, определяющий местоположение директории. Если common_flag=FILE_COMMON, то директория находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае директория находится в локальной папке (MQL5\Files или MQL5\Tester\Files в случае тестирования).

Возвращаемое значение

Возвращает true в случае успеха, иначе false.

Примечание

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

 

FolderClean

Удаляет все файлы в указанной папке.

bool FolderClean(
 string folder_name, // строка с именем папки
 int common_flag=0 // область действия
 );

Параметры

folder_name — [in] Имя директории, в которой требуется удалить все файлы. Содержит полный путь к папке.

common_flag=0 — [in] Флаг, определяющий местоположение директории. Если common_flag=FILE_COMMON, то директория находится в общей папке всех клиентских терминалов \Terminal\Common\Files. В противном случае директория находится в локальной папке (MQL5\Files или MQL5\Tester\Files в случае тестирования).

Возвращаемое значение

Возвращает true в случае успеха, иначе false.

Примечание

Из соображений безопасности в языке MQL5 строго контролируется работа с файлами. Файлы, с которыми проводятся файловые операции средствами языка MQL5, не могут находиться за пределами «файловой песочницы».

Осторожно пользуйтесь этой функцией, так как все файлы и все вложенные поддиректории удаляются безвозвратно.