nginstack

Class: Connection

@nginstack/engine/lib/connection/Connection~ Connection

new Connection(host [, dbName])

Classe que permite estabelecer uma comunicação com um Engine servidor.

Opcionalmente, este construtor permite que seja informado o nome de uma base de dados como segundo parâmetro. Essa opção é mantida apenas para fins de compatibilidade e, quando informada, permite que sejam utilizados métodos descontinuados associados à base de dados.

Importante: alguns métodos descontinuados desta classe permitem acesso ao cache local. Esses métodos estão disponíveis apenas na instância publicada por meio do módulo module:@nginstack/engine/context/connection e da variável global connection.

Parameters:
Name Type Argument Description
host string | Database

Endereço IP ou nome do computador remoto. Também poderá ser informada uma instância de Database. Essa opção é útil para interagir com APIs que ainda utilizam a classe Connection para acessar a base de dados.
dbName string <optional>

Nome da base de dados que será conectada. Caso não seja informado, os método relacionados à base de dados não estarão disponíveis. Este parâmetro é mantido apenas para fins de compatibilidade. Para acessar informações relacionadas à base de dados, utilize a classe Database.

Members

dbName :string

Nome do Banco de Dados configurado na Conexão.

Type:
  • string
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
if (connection.dbName === "DB_NAME") {
 throw new Error("Usuário possui permissão para consultar os Dados na Produção")
}

dbServerHost :string

IP ou Nome do Host para o servidor de banco de dados da Conexão.

Type:
  • string
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
if (! connection.isOnline ) {
 throw new Error("Não foi possível Conectar ao Host \"" + connection.dbServerHost +
     ":" + connection.dbServerPort )
}

dbServerPort :string

Porta do Host para o Servidor de Banco de Dados da Conexão.

Type:
  • string
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
if (!connection.isOnline) {
 throw new Error("Não foi possível Conectar ao Host \"" + connection.dbServerHost +
     ":" + connection.dbServerPort )
}

dbType :string

Tipo de Banco de Dados configurado na Conexão.

Type:
  • string
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
if (connection.dbType === 'ORACLE') {
 do();
}

enabled :boolean

Informa se a comunicação com o banco de dados está habilitada.

Type:
  • boolean

isOnline :boolean

Informa se a conexão está ativa (online) com o Engine destino desta conexão. O estado de online é atualizado apenas quando há uma tentativa de conexão, portanto mesmo em uma conexão ativa não há garantia que a próxima requisição será bem sucedida.

Importante: a conexão com o Engine servidor pode estar ativa, mas o banco de dados pode estar indisponível. Essa propriedade se refere apenas à conectividade do Engine.

Type:
  • boolean

protocol :string

Protocolo utilizado na comunicação com o Engine servidor. Valores possíveis: 'http:' e 'https:'.

Type:
  • string

readTimeout :number

Informa o timeout de leitura da conexão, em milissegundos. Informe o valor zero para utilizar o timeout padrão.

Type:
  • number
Example
var connection = require('@nginstack/engine/context/connection');
connection.readTimeout = 15000
try {
 var ds = connection.getDataSet( 'Select * From iVFS Where iKey = 1234')
} finally {
 connection.readTimeout = 0
}

referrer :string

Informação enviada ao servidor para que o mesmo possa identificar nas estatísticas qual processo originou a requisição. Ela é automaticamente preenchida pelo sistema e normalmente não deve ser utilizada pelo desenvolvedor.

Type:
  • string
Deprecated:
Example
const Connection = require('@nginstack/engine/lib/connection/Connection');

const conn = new Connection(host, dbName);
conn.referrer = 'Processo de sincronismo de dados';

remainingHighKeys :number

Type:
  • number
Deprecated:
  • Yes

remainingKeys :number

Informa o número de chaves ainda restantes no cache local.

Type:
  • number

remoteInstanceId :string

Id que identifica de forma única o Engine remoto conectado.

Ao acessar esta propriedade, será realizada uma requisição para o Engine servidor para obter o seu id.

Type:
  • string
See:

serverDate :Date

Data e hora local do servidor do banco de dados.

O valor será obtido do cache local caso a conexão seja com banco de dados principal. Em conexões para outras bases de dados, o valor será obtido por meio de uma requisição ao servidor remoto.

Type:
  • Date
Deprecated:
Example
const connection = require('@nginstack/engine/context/connection');
const toFormattedString = require('@nginstack/engine/lib/string/toFormattedString')
const dt = connection.serverDate;
Logger.getLogger('MyClass').info("Registro Gravado no Servidor em " +
  toFormattedString(dt, 'dd/mm/yyyy') + " às " + toFormattedString(dt, 'hh:mm:ss'));

serverVersion :string

Versão do Engine acessado por esta conexão.

Importante: o valor desta propriedade é obtido por meio de uma requisição ao servidor para obter a versão do executável Engine. Para obter a versão do Engine corrente, utilize engine.version.

Type:
  • string
Example
const connection = require('@nginstack/engine/context/connection.js');
log.info('Server version: ' + connection.serverVersion);

trackingId :string

Esta é uma propriedade que, se definida, será utilizada pelo applyUpdates e pelo executeDDL para preencher o campo iTag da iLog. Com isso, é possível agrupar os registros na iLog por tag, facilitando o desfazimento.

Recomenda-se que a string utilizada nesta propriedade seja um identificador único. Para isto, utilize a função createGUID(removeFormatChars).

Type:
  • string
Deprecated:

userKey :number

Chave do usuário logado na conexão. Retorna -1 caso não exista usuário logado.

Type:
  • number
Deprecated:
See:

userName :number

Nome do usuário logado na sessão.

Type:
  • number
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
throw new Error('O usuário ' + connection.userName + ' não possui permissão para
   Abrir Requisições.');

workloadType :string

Indica para o banco de dados qual é o tipo de carga da aplicação que está requisitando os dados. Valores possíveis:

  • 'olap' (Online analytical processing): indicado para relatórios ou processos de consulta. Normalmente, interagem com uma massa de dados média ou elevada. Prioridade de atendimento média.
  • 'oltp' (Online transaction processing): indicado para processos que realizam a leitura ou gravação de poucos registros. Prioridade de atendimento alta.
  • 'dw' (Data Warehouse): indicado para processos que consolidam grandes massas de dados para pesquisas posteriores. Prioridade de atendimento baixa.

O valor padrão desta propriedade é "olap" e os processos que necessitem alterar a conexão padrão (variável global connection) devem ter o cuidado de retornar o valor anterior após o uso, evitando assim afetar outros códigos que utilizem a a mesma instância global.

No banco de dados Oracle, este parâmetro é utilizado para definir o tamanho do buffer para a leitura de registros em bloco, sendo alocada mais memória para as cargas do tipo "olap" e "dw". Seu valor também estará disponível no campo "ACTION" da view "v$session", possibilitando ao DBA otimizar e priorizar o atendimento de acordo com o tipo informado.

Type:
  • string
Deprecated:

writeTimeout :number

Informa o timeout de escrita da conexão em milissegundos. Informe o valor zero para utilizar o timeout padrão.

Type:
  • number
Example
var connection = require('@nginstack/engine/context/connection');
connection.writeTimeout = 1000;
try {
 connection.executeScript(1234, 'parameter', 'teste');
} finally {
 connection.writeTimeout = 0;
}

Methods

<static> fromConfig(key)

Retorna uma instância de Connection associado ao engine informado.

Observação: a chave informada deve deve ser de um registro da base de dados corrente.

Parameters:
Name Type Description
key DBKey | number

Chave do cadastro do Engine. Essa chave deve ser de um registro da classe "/Dados/Sistema/Servidores".
Returns:

Instância de Connection para o Engine informado.

Type
Connection

addKeyRange(keyRangeStream, password)

Adiciona um novo Key Range na base de dados.

Parameters:
Name Type Description
keyRangeStream string

Key Range fornecido pela desenvolvedora do Engine.
password string

Novo password que será associado ao Key Range. Guarde esta senha com segurança, pois somente através dele será possível utilizar e criar licenças do Key Range.
Deprecated:
See:

addLicense(licenseStream, administratorPassword)

Adiciona uma nova licença na base de dados.

Parameters:
Name Type Description
licenseStream string

Licença em uma sequência de caracteres fornecida por um fornecedor reconhecido pela desenvolvedora do Engine.
administratorPassword string

Senha do usuário administrator. Caso seja o primeiro licenciamento do sistema, a senha do usuário administrator será alterada para o valor informado.
Deprecated:
See:

applyUpdates(ArrayOfDataSets, insertIntoLogTable)

Efetiva as alterações dos datasets nas suas respectivas tabelas.

Parameters:
Name Type Argument Description
ArrayOfDataSets DataSet | Array.<DataSet>

DatasSet ou array de datasets que devem ser atualizados.
insertIntoLogTable boolean <nullable>

Indica se as alterações devem ser incluídas na tabela de log.
Deprecated:
See:
  • DataSet#applyUpdates
Returns:

Versão dos registros alterados. Retornará 0 caso nenhum registro tenha sido alterado.

Type
number
Example
var connection = require('@nginstack/engine/context/connection');
connection.applyUpdates(ds);
connection.applyUpdates([ds1, ds2]);

authenticateUser(userName, password, useLocalCache)

Autentica o nome de usuário e senha no banco de dados e retorna a chave dele.

Parameters:
Name Type Argument Description
userName string
password string
useLocalCache boolean <nullable>

Indica se deve usar o cache local para realizar a autenticação da senha. Se for informado true, a autenticação será realizada rapidamente, pois não haverá necessidade de consultar o servidor. Caso contrário, pode haver demora ao se obter os dados do servidor. No entanto, esta última opção permite realizar autenticações sem que o cache local esteja montado.
Deprecated:
Returns:

Retorna -1 caso a autenticação seja inválida.

Type
number

changeLicensePassword(key, password, newPassword)

Altera o password de uma licença.

Parameters:
Name Type Description
key number

Licença que terá o password alterado.
password string

Password atual.
newPassword string

Password novo.
Deprecated:

classHierarchicalProperty(classNameOrKey, propertyName)

Pega uma propriedade de uma classe de forma hierárquica.

Parameters:
Name Type Description
classNameOrKey number | string

Nome ou chave da classe de onde se quer a propriedade.
propertyName string

Nome da propriedade.
Deprecated:
See:
Returns:

Objeto com as definições da classe.

Type
Object
Example
var connection = require('@nginstack/engine/context/connection');
// Neste caso, se a classe "Orçamento" não possuir valor para a propriedade "MAX_VALUE",
// busca na classe mãe, e assim sucessivamente.
var property = connection.classHierarchicalProperty("Orçamento", "MAX_VALUE");

cloneLocalCache(tableName)

Clona uma tabela do cache local. Caso seja usado o método "applyUpdates" em num DataSet proveniente do cache local, todas as alterações serão refletidas na tabela a ele associada.

Parameters:
Name Type Description
tableName string

Nome da tabela do cache local a ser clonada.
Deprecated:
See:
Returns:
Type
DataSet
Example
var connection = require('@nginstack/engine/context/connection');
var recurso = connection.cloneLocalCache('RECURSO')

cloneLocalCacheByClass(classKey [, userKeyPermissionViewFilter] [, securityExtraFilter])

Clona uma classe do cache local. Caso seja usado o método "applyUpdates" em um dataset proveniente do cache local, todas as alterações serão refletidas na tabela a ele associada. Bastando para isso que ela possua os campos CHAVE, CLASSE e VERSÃO.

Parameters:
Name Type Argument Description
classKey number

Nome da classe do sistema a ser clonada.
userKeyPermissionViewFilter number <optional>
securityExtraFilter Array <optional>
Deprecated:
See:
Returns:
Type
DataSet

cloneVfsByClass(classKey, userKeyPermissionViewFilter, securityExtraFilter)

Parameters:
Name Type Description
classKey Object
userKeyPermissionViewFilter Object
securityExtraFilter Object
Deprecated:
See:
Returns:
Type
DataSet

copyStructureLocalCache(tableName)

Copia a estrutura de uma tabela do cache local. Todas as definições de campos, índices, etc. Caso seja usado o método "applyUpdates" em num dataset proveniente do cache local, todas as alterações serão refletidas na tabela a ele associada. Bastando para isso que ela possua os campos CHAVE, CLASSE e VERSÃO.

Parameters:
Name Type Description
tableName string
Deprecated:
See:

createKey( [keysQuantity] [, getHighKeys])

  1. Ao se usar o parâmetro "keysQuantity", o servidor não retorna o número de chaves solicitadas, mas sim reserva. Após a solicitação, deve-se fazer o incremento de chaves "manualmente", como no exemplo que vimos.
  2. Recomenda-se solicitar apenas uma chave, ou seja, parâmetro nKeys = 1 (ou simplesmente omitido). Assim, em vez de ir ao servidor buscar a chave, ela será solicitada ao cache de chaves.
Parameters:
Name Type Argument Description
keysQuantity number <optional>

Número de chaves que o servidor deve reservar.
getHighKeys number <optional>

Indica se deve usar chaves altas.
Deprecated:
See:
Returns:
Type
number

createKeyRange(keyRangeName, quantity [, keyList] [, requiredLicenses] [, key] [, base] [, userName] [, password])

Cria um nova faixa de chaves negativas.

Parameters:
Name Type Argument Description
keyRangeName string

Nome do produto que será criado com esta faixa de chaves.
quantity number

Quantidade de chaves a serem reservadas no Key Range que será criado.
keyList string <optional>

Lista de chaves que fazem parte do Key Range, mas não são representadas pela faixa.
requiredLicenses string <optional>

Licenças requeridas pelo Key Range que será criado.
key number <optional>

A chave somente deve ser informada se estiver realizando a edição de informações de um key range existente.
base number <optional>

A base somente deve ser informada se estiver realizando a edição de informações de um key range existente.
userName string <optional>
password string <optional>
Deprecated:
See:

createLicense(keyRangeKey, licenserKey, licenseType, quantity, expiration, licenseeName, licenseeId, userName, password)

Cria uma licença de uso. Somente o proprietário de uma licença poderá criar e distribuir licenças de uso.

Parameters:
Name Type Description
keyRangeKey number

Chave da licença que será licenciada para um cliente.
licenserKey number

Chave gerada pelo proprietário da licença para controlar a distribuição de licenças para seus clientes.
licenseType string

Tipo da licença que será criada. Os valores possíveis são: "C" (por conexão) ou "P" (por processador).
quantity number

Quantidade de licenças concedidas à empresa licenciada.
expiration Date

Data de expiração da licença.
licenseeName string

Nome da empresa que será licenciada.
licenseeId string

Identificação oficial da empresa licenciada no País ( Ex: CNPJ ).
userName string
password string

Password do proprietário da licença.
Deprecated:
See:

discardEndpointInfoCache()

Descarta o cache de informações das capacidades conhecidas do Engine remoto acessado por meio desta conexão.

Este é um método avançado que em situações normais de uso não deve ser utilizado. Ele deve ser empregado apenas quando for conhecido que um Engine remoto tenha sido atualizado e quando as capacidades da nova versão desse Engine são requeridas imediatamente.

executeScript(scriptReference [, parametersNames] [, parametersValues])

Executa um script no servidor.

Parameters:
Name Type Argument Description
scriptReference number | string

Chave do script da VFS que deve ser executado ou caminho do script da UFS.
parametersNames Object <optional>

Array contendo o nome do parâmetro e o seu valor ([parameterName, parameterValue]) que pode ser repetido várias vezes.
parametersValues * <optional>
<repeatable>
Deprecated:
Example
var connection = require('@nginstack/engine/context/connection');
connection.executeScript( 585858, 'codigoEntidade', codEntidade, 'data', new Date() )
// ou
connection.executeScript( 585858, ['codigoEntidade', 'data' ], [ codEntidade, new Date() ])
// ou
connection.executeScript('ufs:/engine_modules/package/scripts/script.js')

executeSql(sqlExpression)

Executa uma expressão SQL no banco de dados associado ao Connection. Utilize o método Connection.getDataSet() caso a expressão SQL retorne dados.

Parameters:
Name Type Description
sqlExpression string | Array.<string>

Expressão ou array de expressões SQL que deverão ser executadas.
Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
connection.executeSql('ANALYZE iGroupUser')

get(className, codeOrKey, fieldName)

Obtém o valor de um campo do registro que possui a chave ou o código informado dentro da classe informada.

Parameters:
Name Type Description
className string

Nome da classe de onde se deve pegar o campo.
codeOrKey string

Código ou chave do registro do qual se quer pegar o campo.
fieldName string

Nome do campo que se deseja pegar.
Deprecated:
  • Utilize module:@nginstack/engine/lib/dbcache/DBCache~DBCache#getFieldValue.
Returns:

Valor do campo com o tipo de acordo com o que foi definido no banco de dados.

Type
Object

getChangeableLicenses(userKey)

Obtém as chaves das licenças que o usuário pode editar.

Parameters:
Name Type Description
userKey number

Chave do Usuário
Deprecated:
Returns:

Chaves de Licenças que o Usuário pode alterar.

Type
Array.<number>

getChildren(classKey [, userKey] [, permissionFieldName])

Traz as chaves das classes filhas da classe informada, bem como a própria classe. Podendo fazer um filtro por usuário.

Parameters:
Name Type Argument Description
classKey number | string

Chave ou nome da tabela do cache local a ser clonada.
userKey number <optional>

Chave do usuário para que seja feito o filtro de visão.
permissionFieldName string <optional>

Nome do campo onde estão as permissões dos usuários.
Deprecated:
See:
Returns:

String com lista de chaves separadas por ponto-e-vírgula.

Type
string
Example
var connection = require('@nginstack/engine/context/connection');
var classes = connection.getChildren(123456, session.userKey)

getClassDefinitionSource(classKey, vfs, classes, ignoredClassKeys)

Obtém o código fonte da definição de uma classe de dados.

Parameters:
Name Type Argument Description
classKey DBKey | number

Chave da classe do Vfs que deve ser instanciada.
vfs DataSet <nullable>
classes DataSet <nullable>
ignoredClassKeys Array.<number>

Array de chaves de x-class que devem ser ignorados.
Deprecated:
Returns:
Type
string

getDatabaseNames()

Nomes das bases de dados servidas pelo Engine remoto.

O Engine remoto pode ser um servidor de aplicação ou de borda das bases de dados. Se estiver no modo de servidor de borda, os métodos de consulta e gravação na base de dados não estarão disponíveis. Utilize o método module:@nginstack/engine/lib/database/Database~Database#isEdgeServer para determinar se o Engine remoto é um servidor de borda da base de dados.

Importante: por motivos de compatibilidade, este método retorna uma lista separada por ";" em vez de um array de nomes.

See:
Returns:

Lista separada por ";" com os nomes das bases de dados servidas pelo Engine remoto. Os nomes retornados são padronizados em letras maiúsculas a fim de simplificar a comparação de nomes.

Type
string

getDataSet(sqlOrArrayOfSql [, options])

Obtém um ou vários DataSets a partir do resultado de uma ou várias expressão SQL a serem executadas no banco de dados associado ao Connection. Será retornado um DataSet caso seja informada uma string ou um array de DataSets caso seja informado um array de strings. Utilize o método Connection.executeSql() caso a expressão SQL não retorne dados. Apenas expressões que possam retornar dados podem ser executadas neste método.

Parameters:
Name Type Argument Description
sqlOrArrayOfSql string | Array.<string>

Expressão ou array de expressões SQL que deverão ser executadas.
options Object <optional>

Opções da consulta.

Properties
Name Type Argument Description
queryCacheLifeTime number <optional>

Determina o tempo máximo (em segundos) que o DataSet retornado é mantido em cache, e retornado em consultas idênticas
Deprecated:
See:
Returns:
Type
DataSet | Array.<DataSet>
Example
var connection = require('@nginstack/engine/context/connection');
var ar = connection.getDataSet([
  'Select iKey, iVersion, iName From iGroupUser Where iStatus = -1898143908',
  'Select * from iLog Where iKey in (Select iKey From iGroupUser Where iStatus = -1898143908)'
]);

// DataSet iGroupUser
var pedido = ar[0];
// DataSet iLog
var evento = ar[1];

getExecutionPlan(sqlExpression)

Obtém o plano de execução do banco de dados para a expressão SQL informada. O plano de execução é uma informação gerada pelo banco de dados que permite ao desenvolvedor compreender como o query será executado e determinar se a expressão SQL criada possui um bom desempenho. Cada banco de dados possui um modelo de plano de execução e a documentação do mesmo deve ser lida para compreender as informações retornadas. Normalmente, este método não é conveniente para o desenvolvedor, pois a informação retornada no DataSet é extensa e a utilização de DataSets em logs não é simples. É recomendada a utilização dos métodos da classe QueryAnalyzer para obter a informação do plano de execução em um formato mais simples.

Parameters:
Name Type Description
sqlExpression string

Expressão SQL da qual deve ser obtido o plano de execução.
Deprecated:
Returns:
Type
DataSet

getHierarchicalClass(startClass, endClass [, level] [, opt_separator] [, opt_bringClassesKeys])

Devolve a hierarquia de classes.

Parameters:
Name Type Argument Description
startClass number

Chave da classe de onde deve iniciar a montagem da hierarquia.
endClass number

Chave da classe onde deve finalizar a montagem da hierarquia.
level number <optional>

Quantidade de classes que irá pegar a partir da inicial.
opt_separator string <optional>

String que irá separar as classes. O Valor padrão é "/"
opt_bringClassesKeys boolean <optional>

Determina se trará as chaves das classes.
Deprecated:
Returns:

Hierarquia de classes separadas por "/"

Type
string
Example
var connection = require('@nginstack/engine/context/connection');
var hierarchicalClasses = connection.getHierarchicalClass(2225, 22251, 2, ">", false);

getIssuableLicenses(userKey)

Obtém as chaves das licenças que o usuário pode licenciar.

Parameters:
Name Type Description
userKey number
Deprecated:
See:
Returns:
Type
Array.<number>

getKeyOfClass(className)

Parameters:
Name Type Description
className string
Deprecated:
  • Este método tem um comportamento indeterminado quando há mais de uma classe com o mesmo nome. Prefira pesquisar pelo nome na tabela de Classes e tratar corretamente as possíveis múltiplas ocorrências.
See:
Returns:
Type
number
Example
var connection = require('@nginstack/engine/context/connection');
var classe = connection.getKeyOfClass("Pessoa");

getLicenseFromNegativeRecord(key)

Obtém a chave da licença que gerou a chave informada.

Parameters:
Name Type Description
key number

Chave negativa que deverá ter a licença determinada.
Deprecated:
See:
Returns:
Type
number

getPermission(classKeyOrVfsKey, permissionFieldName, userKey, getMode, extraFilter)

Método utilizado para obter as permissões de um usuário em uma determinada classe ou Script da Virtual File System.

Parameters:
Name Type Argument Description
classKeyOrVfsKey number

Chave ou nome da classe da qual deseja-se saber se o usuário tem permissão.
permissionFieldName string

Nome do campo da tabela iPermission que define a permissão a ser obtida.
userKey number <nullable>

Chave do usuário do qual se deseja descobrir a permissão. Se não for informado, será considerado o usuário logado (session.userKey).
getMode string <nullable>

Determina como a permissão deve ser obtida. Os valores possíveis são:
"withoutInheritance": Obtém a permissão para a classe informada sem levar em conta as permissões definidas nas classes mães. Este parâmetro não é adequado para utilização com campos do tipo "string" que podem ser multivalorados, recomendamos o uso do parâmetro "distinct".
"first": Obtém a primeira permissão definida para a classe ou uma de suas mães, levando em conta a ordem da classe informada. A ordem considerada no sentido da classe atual até a classe root.
Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"max": Obtém o maior valor informado para a classe ou para uma de suas mães. Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"min": Obtém o menor valor informado para a classe ou para uma de suas mães. Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"distinct": Obtém todos os valores distintos informados para a classe ou para uma de suas mães. Se a permissão informada para uma classe possuir os separadores ";" ou ",", a mesma será dividida e cada elemento será considerado um valor distinto. Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.

Se getMode não for informado, ele será considerado como 'withoutInheritance'.
extraFilter string <nullable>

Filtro extra que traz a possibilidade de filtrar a permissão por um outro campo da tabela de permissões(iPermission). Exemplo: Este exemplo checa se o usuário "37860639 - Teste" tem acesso a classe "43614400 - Contatos" e se o campo "estabeleci" no cadastro de permissões tem o valor "3002932 - Demonstração"

connection.getPermission( 43614400, "iView", 37860639, "withoutInheritance", [['Estabeleci', 3002932]])
Deprecated:
See:
Returns:
Type
*
Example
var connection = require('@nginstack/engine/context/connection');
// Testa se o usuário corrente tem acesso à classe Entidades
if ( connection.getPermission( -2007900000, 'iView' ) ){
}
// Obtém a lista de campos alteráveis para um determinado usuário. Retornará null se ele
// possui acesso a todos os campos:
var changeableFieldNames = connection.getPermission( -1896048403,
'iChangeableFieldNames', userKey, 'distinct');

getReferences(key, tableName, maxReturnCount, ignoredTables)

Pega todas as referências de uma chave. O DataSet retornado possui os seguintes campos: iKey - Chave do registro que referencia key.
iClass - Classe do registro que referencia key. Este campo é útil para filtrar as ocorrência que podem ser exibidas para um determinado usuário. iTableName - Nome da tabela de qual faz parte o registro que referencia key.
iFieldName - Nome do campo que referencia key.
iFieldLabel - Nome de exibição do campo que referencia key.

Parameters:
Name Type Argument Description
key number

Chave do registro do qual se deseja obter as referências.
tableName string

Nome da tabela da qual faz parte o registro informado pelo parâmetro key.
maxReturnCount number <nullable>

Número máximo de referências que devem ser retornadas. É importante que este valor não seja alto, pois getReferences() pode retornar uma quantidade muito elevada de registros.
ignoredTables Array.<string> <nullable>
Deprecated:
Returns:
Type
DataSet

getTimezoneOffset()

Obtém a diferença em minutos do fuso horário do servidor acessado por esta conexão e o UTC.

Returns:
Type
number

getUserGroups(userKey)

Obtém os grupos de um usuário ou grupo de usuário levanto em conta a recursividade dos grupos. Um grupo pode fazer parte de outro.

Parameters:
Name Type Description
userKey number

Chave do usuário, papel ou grupo de usuário.
Deprecated:
Returns:

Chaves dos grupos e papéis dos quais o usuário, papel ou grupo faz parte.

Type
Array.<number>
Example
// Get groups of user
 var groups = connection.getUserGroups(session.userKey);
 response.writeln('User ' + session.userName + ' has permission of groups ' + groups.join(', ') +
   '.');

getVfsContent(vfsScriptKey)

Obtém o conteúdo de um arquivo armazenado na Virtual File System. Utilize este método em vez de acessar diretamente a tabela iVfs do cache local, pois o conteúdo poderá não estar disponível caso a classe da Virtual File System esteja configurada para não realizar cache de conteúdo.

Parameters:
Name Type Description
vfsScriptKey number

Chave do Script na Virtual File System.
Deprecated:
Returns:

Conteúdo do Script

Type
string

insertLog(logType, opt_content, opt_key, opt_classKey)

Insere um registro de Log na tabela iLog. Os campos iUser, iDate, iHour e iReferrer serão preenchidos automaticamente pelo sistema.

Parameters:
Name Type Argument Description
logType number

Chave do tipo de log que está sendo registrado. Deve ser um registro da classe "/data/system/Auxiliary Tables/Log Type". Será gravado no campo iType.
opt_content string <nullable>

Conteúdo que será gravado no campo iContent.
opt_key number <nullable>

Chave do registro ao qual o log faz referência. Será gravado no campo iKey.
opt_classKey number <nullable>

Chave da classe do registro ao qual o log faz referência. Será gravado no campo iClass.
Deprecated:

instanceClassDefinition(classKeyOrSource [, iVfsOrParentKey] [, iClass])

Obtém a definição de uma classe.

Parameters:
Name Type Argument Description
classKeyOrSource number | string
iVfsOrParentKey DataSet | number <optional>
iClass DataSet <optional>
Deprecated:
Returns:
Type
ModelDef

isCachedData(classKey, tableName)

Verifica se a tabela faz parte do cache local.

Parameters:
Name Type Description
classKey number

Classe que define a tabela. Este parâmetro não é mais utilizado, sendo mantido apenas por compatibilidade de API.
tableName string

Nome da tabela
Deprecated:
Returns:

True se a tabela fizer parte do cache local

Type
boolean

isChildOf(key, parent)

Verifica se a chave informada é filha ou igual a classe especificada. São verificadas as seguintes situações:

  • Se uma classe "key" é filha de "parent";
  • Se a classe do registro "key" é filho de "parent";
  • Se um registro iVfs "key" é filho de "parent".
Parameters:
Name Type Description
key number

Chave da classe ou do registro a qual deseja verificar a hierarquia.
parent number

Chave da classe a qual se deseja verificar se é mãe da chave passado no parâmetro "key".
Deprecated:
Returns:
Type
boolean
Example
var connection = require('@nginstack/engine/context/connection');
// Se a classe "Pessoas" é filha da classe "Entidades"
if ( connection.isChildOf( -2007890000, -2007900000 ) ){
   ...
}

// Se o cliente "Consumidor Final" é filho da classe "Clientes"
if ( connection.isChildOf( -1899931617, -2007889000 ) ) {
   ...
}

// Se o usuário "administrator" é filho da classe "Users"
if ( connection.isChildOf( -1898186559, -1898187809 ) ) {
   ...
}

isUserInGroup(userKey, groupKey)

Verifica se um usuário faz parte de um grupo.

Parameters:
Name Type Description
userKey number

Chave do usuário.
groupKey number

Chave do grupo.
Deprecated:
Returns:
Type
boolean
Example
// Is current user an administrator
 if ( connection.isUserInGroup( session.userKey, -1898186568) ){ // Administrators
 }

login(userName, password)

Realiza o login na conexão, permitindo que o usuário tenha acesso às informações do banco de dados. O método Session.login() realiza automaticamente o login da conexão default (connection), portanto, este método somente deve ser utilizado em conexões criadas manualmente.

Parameters:
Name Type Description
userName string
password string
Deprecated:
See:
Returns:
Type
boolean
Example
var Connection = require('@nginstack/engine/lib/connection/Connection');
var connection = new Connection('192.168.0.1:83', 'DB_NAME' )
var valid = connection.login( 'userName', 'password' )
if (!valid) {
 throw new Error('Usuário e/ou Senha Inválidos na base DB_NAME.')
}

logout()

Realiza o logout da conexão, impedindo que a mesma possa acessar informações do banco de dados. O método Session.logout() realiza automaticamente o logout da conexão default (connection), portanto, este método somente deve ser utilizado em conexões criadas manualmente.

Deprecated:
See:
Example
var connection = require('@nginstack/engine/context/connection');
if ( this.confirm('Deseja Realmente Finalizar a Conexão ?') ) {
 connection.logout()
}

newTask(task, userName, password)

Cria uma nova tarefa no Scheduler do servidor da conexão.

Parameters:
Name Type Argument Description
task Task

Instância de Task que contém todas as definições da tarefa a ser executada.
userName string <nullable>

Nome do usuário que está criando a tarefa. Caso não seja informado, será considerado o usuário logado na sessão corrente.
password string <nullable>

Senha do usuário que está criando a tarefa.
Example
// Cria a tarefa que deve executar o script de chave 999888 hoje, às 23:00h.
 var task = new Task();
 task.date = new Date();
 task.hour = task.date.setHours( 23, 0, 0, 0);
 task.scriptKey = 999888;
 connection.newTask(task);

refreshLocalCache( [waitDataRefreshing])

Este método pode comparado a pressionar CTRL + E no IDE O cache local é atualizado a cada 30 segundos por padrão, mas pode ser configurado via manage do Engine. Atualiza o cache local.

Parameters:
Name Type Argument Description
waitDataRefreshing boolean <optional>

Indica se deve aguardar a atualização do cache local ser concluída.
Deprecated:
  • Utilize module:@nginstack/engine/lib/dbcache/DBCache~DBCache#refresh.

scheduledSendEmail(email [, maxSize])

Agenda o envio do email no servidor.

Importante: este método deve ser evitado, pois eventuais falhas no envio são ignoradas e registradas apenas no log do servidor. O seu uso intenso ou o envio de emails de tamanho elevado também podem prejudicar o funcionamento do "Agendador de scripts" para outras atividades do sistema.

Parameters:
Name Type Argument Description
email Email

Instância de Email que contém as definições do email a ser enviado.
maxSize number <optional>

Limite em bytes do tamanho requerido para armazenar a mensagem no agendador de scripts. Caso não seja informado, será considerado 25MB.
Example
const email = new Email();
email.addRecipient('Nome do destinatário', 'nome@servidor.com.br');
email.subject = 'Assunto';
email.htmlContent = '<html><body><b>Teste de Email</b><br><br></body></html>';
connection.scheduledSendEmail(email);

sendEmail(email)

Envia um email através da conexão corrente.

Parameters:
Name Type Description
email Email

Objeto que contém as definições do email a ser enviado.
Deprecated:
  • Utilize o método `Database.prototype.sendEmail`

setChangeableLicenses(userKey, licenseKeys, passwords)

Informa quais licenças podem ser alteradas pelo usuário.

Parameters:
Name Type Description
userKey number

Chave do usuário que será associado ao Partner Key Range.
licenseKeys Array.<number>

Array com as chaves das licenças que podem ser alteradas pelo usuário.
passwords Array.<string>

Array com os passwords da licenças informadas no parâmetro licenseKeys.
Deprecated:
See:

setIssuableLicenses(userKey, licenseKeys, passwords)

Licenças podem ser licenciadas pelo usuário.

Parameters:
Name Type Description
userKey number

Chave do usuário que será associado ao Partner Key Range.
licenseKeys Array

Array com as chaves das licenças que podem ser licenciadas pelo usuário.
passwords Array

Array com os passwords da licenças informadas no parâmetro licenseKeys.
Deprecated:
See:

setPassword(userKey, password)

Altera a senha do usuário.

Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário que terá a senha alterada.
password string

Nova Senha.
Deprecated:

skipSatSunHoliday(dt, uf, localidade)

Verifica se a data passada é um dia útil e, se não for, retorna o próximo dia útil.

Parameters:
Name Type Argument Description
dt Date

Data a ser verificada.
uf number <nullable>

Chave da UF quando deseja-se considerar feriados estaduais.
localidade number <nullable>

Chave da cidade quando deseja-se considerar feriados municipais.
Returns:
Type
Date

userCanChangeNegativeRecord(key [, opt_userKey])

Determina se o usuário tem permissão de alterar um registro de chave negativa.

Parameters:
Name Type Argument Description
key number

Chave do registro.
opt_userKey number <optional>

Chave do usuário. Caso não seja informado, será considerado o usuário corrente.
Deprecated:
Returns:
Type
boolean