Referência MQL5Símbolos personalizadosCustomSymbolCreate

CustomSymbolCreate

Cria um símbolo personalizado com o nome especificado no grupo definido.

bool  CustomSymbolCreate(
   const string     symbol_name,         // nome do símbolo personalizado
   const string     symbol_path="",      // nome do grupo em que será criado o símbolo
   const string     symbol_origin=NULL   // nome do símbolo com base no qual será criado o símbolo personalizado
   );

Parâmetros

symbol_name

[in] Nome do símbolo personalizado. Ele não deve conter grupos ou sub-grupos em que se encontre o símbolo.

symbol_path=""

[in] Nome do grupo em que é criado o símbolo.

symbol_origin=NULL

[in] Nome do símbolo a partir do qual serão copiadas as propriedades do símbolo personalizado gerado. Depois de criar um símbolo personalizado, você pode alterar qualquer propriedade para o valor desejado com as funções correspondentes.

Valor retornado

true, em caso de sucesso, caso contrário, false. Para obter informações sobre o erro, você deve chamar a função GetLastError().

Observação

Todos os símbolos personalizados são gerados na seção especial Custom. Se o nome de grupo não for especificado (o parâmetro symbol_path na função CustomSymbolCreate contém uma string vazia ou NULL), o símbolo personalizado será criado na raiz da seção Custom. Aqui você pode fazer uma analogia com o sistema de arquivos, onde grupos e subgrupos podem ser vistos como pastas e subpastas

O nome do símbolo e descrição do grupo são definidos apenas por caracteres latinos sem pontuação, espaços e caracteres especiais (são permitidos ".", "_", "&" e "#"). Não é recomendado usar - nos nomes dos símbolos - os caracteres <, >, :, ", /, |, ?, *.

O nome do símbolo personalizado deve ser único, independentemente do nome do grupo em que ele é criado. Se já existir um símbolo com o mesmo nome, a função CustomSymbolCreate() retornará false, enquanto a chamada subsequente de GetLastError() gerará o erro 5300 (ERR_NOT_CUSTOM_SYMBOL) ou 5304 (ERR_CUSTOM_SYMBOL_EXIST).

O nome do símbolo não deve exceder 31 caracteres, caso contrário, CustomSymbolCreate() retornará false e será gerado o ero 5302 — ERR_CUSTOM_SYMBOL_NAME_LONG.

Parâmetro symbol_path pode ser definido de duas maneiras:

apenas o nome do grupo sem o nome do símbolo personalizado, por exemplo — "CFD\\Metals". É melhor usar essa opção para evitar erros.
ou nome de <grupo> + separador de grupo "\\"+<nome de símbolo personalizado>, por exemplo — "CFD\\Metals\\Platinum". Nesse caso, o nome do grupo deve terminar com o nome exato do símbolo personalizado. Mesmo em caso de incompatibilidade, o símbolo personalizado será criado, mas não no grupo pretendido. Por exemplo, se symbol_path="CFD\\Metals\\Platinum" e symbol_name="platinum" (erro no registro), será criado o símbolo personalizado com o nome "platinum" no grupo "Custom\CFD\Metals\Platinum". Nesse caso, a função SymbolInfoGetString("platinum",SYMBOL_PATH) retornará o valor "Custom\CFD\Metals\Platinum\platinum".

Deve-se ter em mente que a propriedade SYMBOL_PATH retorna o caminho com o nome do símbolo no final. Portanto, você não pode simplesmente copiá-lo sem alterações, se quiser criar um símbolo personalizado exatamente no mesmo grupo. Nesse caso, é necessário cortar o nome do símbolo para não obter o resultado descrito acima.

Se como parâmetro symbol_origin for especificado um símbolo inexistente, o símbolo personalizado será criado vazio, como se o parâmetro symbol_origin não tivesse sido especificado. Nesse caso, será gerado o erro 4301 — ERR_MARKET_UNKNOWN_SYMBOL.

O comprimento do parâmetro symbol_path não deve exceder 127 caracteres considerando "Custom\\", separador de grupo "\\" e nome do símbolo se for indicado no final.

Exemplo:

//+------------------------------------------------------------------+
//|                                           CustomSymbolCreate.mq5 |
//|                                  Copyright 2024, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2024, MetaQuotes Ltd."
#property link      "https://www.mql5.com"
#property version   "1.00"

#define   CUSTOM_SYMBOL_NAME     Symbol()+".C"     // nome do símbolo personalizado
#define   CUSTOM_SYMBOL_PATH     "Forex"           // nome do grupo onde o símbolo será criado
#define   CUSTOM_SYMBOL_ORIGIN   Symbol()          // nome do símbolo usado como base para a criação do símbolo personalizado

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
  {
//--- se não for possível criar o símbolo personalizado, informamos no log
   if(!CustomSymbolCreate(CUSTOM_SYMBOL_NAME, CUSTOM_SYMBOL_PATH, CUSTOM_SYMBOL_ORIGIN))
     {
      Print("CustomSymbolCreate() failed. Error ", GetLastError());
      return;
     }

//--- verificamos a existência do símbolo criado e obtemos o grupo onde ele foi criado
   bool   custom= false;
   bool   exist = SymbolExist(CUSTOM_SYMBOL_NAME, custom);
   string path  = SymbolInfoString(CUSTOM_SYMBOL_NAME, SYMBOL_PATH);

//--- imprimimos no log o resultado da criação do símbolo e o nome do grupo, definido e obtido das propriedades do símbolo
   PrintFormat("Custom symbol '%s' created\n"+
               "Symbol '%s' is exist: %s\n"+
               "Symbol '%s' is custom: %s\n"+
               "Path specified in the settings: '%s'\n"+
               "Path returned from the 'SYMBOL_PATH' property: '%s'",
               CUSTOM_SYMBOL_NAME,
               CUSTOM_SYMBOL_NAME, (string)exist,
               CUSTOM_SYMBOL_NAME, (string)custom,
               CUSTOM_SYMBOL_PATH,
               path);

//--- aguardamos dois segundos e excluímos o símbolo criado com uma mensagem sobre o resultado no log
   Sleep(2000);
   ResetLastError();
   bool deleted = CustomSymbolDelete(CUSTOM_SYMBOL_NAME);
   Print(deleted ? StringFormat("Custom symbol '%s' removed", CUSTOM_SYMBOL_NAME) : StringFormat("CustomSymbolDelete() failed. Error ",GetLastError()));
   /*
   resultado:
   Custom symbol 'EURUSD.C' created
   Symbol 'EURUSD.C' is exist: true
   Symbol 'EURUSD.C' is custom: true
   Path specified in the settings: 'Forex'
   Path returned from the 'SYMBOL_PATH' property: 'Custom\Forex\EURUSD.C'
   Custom symbol 'EURUSD.C' removed
   */
  }

Veja também

SymbolName, SymbolSelect, CustomSymbolDelete

Símbolos personalizados

CustomSymbolDelete