nginstack

Class: DataSet

@nginstack/engine/lib/dataset/DataSet~ DataSet

new DataSet( [idoDB])

DataSet é uma coleção de dados convertida em linhas e colunas e organizada a partir das posições de memória dos mesmos. As linhas referenciam os registros e as colunas, os campos.

Esta classe também é publicada pelo Engine por meio da variável global DataSet.

Parameters:
Name Type Argument Description
idoDB IdoDB <optional>

Base de dados onde a tabela será criada. Se for omitido será usando cache local da base de dados default.

Members

<static> MAX_FIELDS_PER_TABLE :number

Quantidade máxima de colunas por tabela.

Type:
  • number

active :boolean

Indica se o DataSet está ativo. A propriedade é marcada para true quando for executado o método "create" e marcado pra false quando for executado o método "close".

Type:
  • boolean
See:
Example
var ds = new DataSet()
 // Neste ponto, a propriedade ds.active está false
 ds.createField( "CODIGO", "string", 25 )
 // Ao executar o método create(), a propriedade ds.active será marcada para true.
 ds.create()

 (...)

  // Ao executar o método close(), a propriedade ds.active será marcada para false.
  ds.close()

automaticApplyUpdates :boolean

Indica se as alterações no DataSet deverão ser gravadas automaticamente no banco de dados. Desta forma, será executado o método applyUpdates a cada modificação dos registros no DataSet.
IMPORTANTE: Todos os DataSet que são criados a partir do cache local possuem esta propriedade marcada automaticamente como true.

Type:
  • boolean
See:
Example
var ds = connection.cloneLocalCache("ENTIDADE")
 ds.automaticApplyUpdates = false

 (...)

 if ( mustUpdateChanges ) {
    ds.applyUpdates()
 }

automaticPost :boolean

Efetua o post automaticamente nos registros do DataSet. O post é chamado, geralmente, após a inserção de um registro no DataSet para confirmar a inclusão para o ponteiro.

Importante: esta propriedade não deve ser mais utilizada, pois a maioria dos códigos não trata a possibilidade do post automático estar desativado. Ao navegar em um dataSet com o post automático desativado as informações em edição são perdidas, comportamento indesejado na maioria dos cenários. Em versões futuras do Engine, esse recurso será desligado.

Type:
  • boolean
Deprecated:
  • Yes

bof :boolean

Indica se o cursor está no início do DataSet. BOF, do inglês, Begin of File (Início do Arquivo). Se o valor for true, significa que o cursor está no primeiro registro do DataSet.

Type:
  • boolean
See:

bookmark :string

Marcador único que identifica o registro no DataSet. O valor do bookmark é somente para leitura não podendo ser alterado. Modificar esta propriedade não modifica o valor do bookmark e sim a posição do cursor para o registro associado ao bookmark informado.

Type:
  • string
See:
Example
var bookmark = ds.bookmark // pega o bookmark do registro atual
 (...)
 ds.bookmark = bookmark // volta para a posição de origem antes das operações no dataset

classesFilter :string

Expressão de filtro de classes para o DataSet. Indica quais classes devem permanecer no DataSet. A expressão deve ser com chaves de classes, separadas por vírgula.

Type:
  • string
Deprecated:
  • Yes
Example
var ds = connection.cloneLocalCache("ENTIDADE")

 // Deixa disponíveis para navegação somente os registros das classes 25845, 585487 e
 // 895653.
 ds.classesFilter = "25845,585487,895653"

dataSetId :number

Identificador único do DataSet da sessão do browser em que o usuário está logado.

Type:
  • number

dataSetVersion :number

Versão incrementada a cada alteração realizada no DataSet, permitindo determinar se um dataSet foi modificado.

Type:
  • number
See:
Example
var recordVersions = []

 var ivfs = connection.cloneLocalCache( 'iVfs')
 var beforeDataSetVersion = ivfs.dataSetVersion

 for ( ivfs.first(); !ivfs.eof; ivfs.next() ){
    recordVersions.push( ds.recordVersion )
 }

 externalEvent( ivfs )

 if ( ivfs.dataSetVersion != beforeDataSetVersion ) {
    log.write("DataSet has been modified.")

    recordVersions.sort()

    for ( ivfs.first(); !ivfs.eof; ivfs.next() ) {
       if ( recordVersions.indexOf( ds.recordVersion ) >= 0 ) {
          log.write("The Record: " + ivfs.ikey + " has been modified" )
       }
    }
 }

eof :boolean

Indica se o cursor está no fim do DataSet. EOF, do inglês, End of File (Fim de Arquivo). Se o valor for true, significa que o cursor está no último registro do DataSet.

Type:
  • boolean
Example
ds.first()
 while ( !ds.eof ) { // Enquanto não for o Fim do Arquivo
    ...
    ds.next()
 }

fieldCount :number

Quantidade de campos no DataSet.

Type:
  • number
See:
Example
var ds = database.query("
    Select CHAVE, CLASSE, CODIGO, NOME
    From ENTIDADE
    Where CADASTRO >= '01/01/2000'")

 var quantidadeDeCamposNoDataSet = ds.fieldCount
 // Neste ponto, a variável "quantidadeDeCamposNoDataSet" terá valor 4

fieldDefs :DataSetFieldDefs

Coleção contendo as definições dos campos deste DataSet. Ela deve ser utilizada para criar novos campos ou para alterar os existentes.

Type:
  • DataSetFieldDefs
See:
Example
const ds = new DataSet();
 ds.fieldDefs.add([
    { name: 'iKey', type: 'int64' },
    { name: 'iCode', type: 'string', size: 150 }
 ]);
 ds.create();

filter :string

Expressão de filtro para o DataSet.
É obrigatória a expressão "javascript:" antes do início do código. Dentro da expressão do filter, o DataSet que recebe o filtro deverá ser referenciado por "ds" (independente do nome do filtro) e outras variáveis só poderão ser acessadas por meio de concatenação da expressão do filtro.

Type:
  • string
See:
Example
// Filtra todos os registros que possuem a string "ABC"
 // no campo CODIGO.
 ds.filter = "javascript:ds.codigo.indexOf(\"ABC\") >= 0"

filtered :boolean

Possibilita desabilitar o filtro definido. O seu valor inicial é true, indicando que qualquer filtro informado em filter será ativo por padrão.

Type:
  • boolean
See:
Example
ds.filtered = false // desabilita o filtro
 // realiza uma ação sobre o dataset não filtrado
 // ...
 ds.filtered = true // habilita o filtro definido na propriedade filter

getFieldInformed

O conceito do termo 'InformedField' trata de uma sinalização para indicar se o conteúdo de um campo do DataSet foi informado pelo usuário do sistema ou não. Geralmente esta propriedade é alterada no DataSet pela grid do Framework

Deprecated:
  • Utilize #getInformedField.

ignoredFieldNamesOnApplyUpdates :string

Lista de campos separada por ";" que não serão atualizados na base de dados, mesmo que tenham sido alterados no DataSet.

O uso desta propriedade permite a execução do applyUpdates em DataSets com campos que não existem na tabela a ser atualizada.

Type:
  • string

indexFieldNames :string

Indica quais campos o DataSet devem ser indexados. Pode-se indexar mais de um campo, desde que os mesmos sejam separados por ponto-e-vírgula ";". A ordem de indexação deve ser passada para a propriedade indexFieldNames com os campos da sequência informada. ( Ex: ds.indexFieldNames = "CAMPO1;CAMPO2" ).
No caso de indexações em DataSets clonados do cache local, a indexação das colunas fica disponível para outros DataSets clonados posteriormente e, inclusive, em outros processos ou métodos utilizados pelo usuário enquanto o aplicativo estiver sendo executado.
O índice não é apagado da memória de imediato.

Type:
  • string
See:
Example
ds.indexFieldNames = "CLASSE;CODIGO"
 if ( ds.find([ chaveDaClasse, codigoPessoa ]) ) {
    (...)
 }

insertWithHighKey

Inseria uma faixa de chaves altas. Chaves altas eram chaves da faixa 1.000.000.000 a 2.147.483.648. Este conceito não é mais utilizado. O comando tem agora a mesma função que #insertWithKey.

Deprecated:
  • #insertWithKey

insertWithKey :boolean

Indica se deve criar uma chave automaticamente na inserção de um novo registro no DataSet.

Type:
  • boolean
See:
Example
var ds = connection.copyStructureLocalCache("ENTIDADE")
 ds.insertWithKey = true

 ds.append()
 ds.codigo = "CODIGO USUÁRIO"
 ds.nome = "NOME COMPLETO DO USUÁRIO"
 (...)
 ds.post()

 // Neste ponto, o campo CHAVE do DataSet "ds" receberá um valor disponível da sequência
 // de chaves do sistema. Ex: ds.chave == 123456

integrityCheck

Indica se o DataSet irá gerar um erro caso existam referências a um registro que está sendo deletado.

See:

isEmpty :boolean

Indica se o DataSet está vazio, equivalente a verificar se a propriedade recordCount = 0.

Type:
  • boolean
See:

isProtected :boolean

Indica se o DataSet teve seus dados protegidos pelo método protect.

Type:
  • boolean
See:

localDBInfo :Object

Informa atributos do banco local associado a este DataSet. Este objeto possui as seguintes propriedades:

name
{string} Nome do arquivo que guarda o banco local.
kind
{string} Gênero do banco local. Pode ser 'temporary' ou 'persistent'.
id
{number} Identificador único atribuído a um banco local.
Type:
  • Object

logChanges :boolean

Indica se as alterações no dataset devem ser registradas no log. Gravar no Log, por padrão, indica que as alterações realizadas no DataSet podem refletir nas informações no banco de dados, de maneira automática ou manual. IMPORTANTE: Todos os DataSets que são criados a partir do cache local possuem esta propriedade marcada automaticamente como true.

Type:
  • boolean
See:
Example
if ( ds.logChanges ) {
  // Grava as alterações do DataSet no Banco de Dados.
  ds.applyUpdates()
}

modified

Indica se o DataSet foi modificado. Esta propriedade é definida como false sempre que os métodos applyUpdates ou post forem executados.

See:
Example
if ( ds.modified ) {
    throw new Error("Por favor, confirme os dados antes da gravação.")
 }

 ds.applyUpdates()

protectedFields :Array.<string>

Array com os nomes dos campos que foram protegidos pelo método protect.

Type:
  • Array.<string>
See:

rangeActive

Indica se o DataSet está com um range ativo. Esta propriedade é setada como true sempre que é chamado o setRange() e enquanto o índice do DataSet não for alterado e não for chamado o método resetRange().

See:

recNo :number

Indica em qual registro do DataSet o cursor está posicionado. Não é o identificador de um registro no DataSet. Para mais detalhes sobre o identificador de registro no DataSet, veja bookmark.

Type:
  • number
See:

recordCount :number

Indica a quantidade dos registros que o DataSet possui no momento.

Type:
  • number
See:
Example
if ( ds.recordCount > 10 ) {
    throw new Error("Você só pode inserir, no máximo, 10 itens.")
 }

recordVersion :number

Número da versão do DataSet, incrementada a cada alteração realizada no registro corrente.

Type:
  • number
See:
Example
var recordVersions = []

 var ivfs = connection.cloneLocalCache( 'iVfs')
 var beforeDataSetVersion = ivfs.dataSetVersion

 for ( ivfs.first(); !ivfs.eof; ivfs.next() ){
   recordVersions.push( ds.recordVersion )
 }

 externalEvent( ivfs )

 if ( ivfs.dataSetVersion != beforeDataSetVersion ) {
   log.write("DataSet has been modified.")

   recordVersions.sort()

   for ( ivfs.first(); !ivfs.eof; ivfs.next() ) {
     if ( recordVersions.indexOf( ds.recordVersion ) >= 0 ) {
  log.write("The Record: " + ivfs.ikey + " has been modified" )
     }
   }
 }

rowId :number

Identificação do registro no DataSet. O valor do rowId é somente para leitura.

Type:
  • number
See:

setFieldInformed

O conceito do termo 'FieldInformed' trata de uma sinalização para indicar se o conteúdo de um campo do DataSet foi informado pelo usuário do sistema ou não. Geralmente esta propriedade é alterada no DataSet pela grid do Framework.

Deprecated:
  • Utilize #setInformedField.

sqlStatement :string

Expressão SQL que gerou este DataSet, caso ele tenha sido obtido a partir de uma consulta à base de dados.

Type:
  • string
Example
const ds = database.query('SELECT * FROM iGroupUser WHERE iKey < 0');
ds.sqlStatement; // => 'SELECT * FROM iGroupUser WHERE iKey < 0'

state :number

Indica em que estado o DataSet está no momento.

Type:
  • number
See:
Example
var ds = new DataSet()
 this.checkEquals( DataSetStates.INACTIVE, ds.state)
 ds.createField( 'key', 'int64')
 ds.create()

 this.checkEquals( DataSetStates.BROWSE, ds.state)

 ds.append()
 ds.key = 10
 this.checkEquals( DataSetStates.INSERT, ds.state)
 ds.post()

 this.checkEquals( DataSetStates.BROWSE, ds.state)
 ds.key = 20
 this.checkEquals( DataSetStates.EDIT, ds.state)
 ds.post()

 this.checkEquals( DataSetStates.BROWSE, ds.state)
 ds.close()
 this.checkEquals( DataSetStates.INACTIVE, ds.state)

streamDelta :boolean

Indica se o delta do DataSet deve fazer parte do stream. Delta do dataset é todo o histórico de alterações feitas no dataset (inserção, deleção, etc). É o delta que permite a execução do método "applyUpdates" do DataSet.

Type:
  • boolean
See:
Example
var file = new File("C:\\streamedDataSet.txt")
 file.streamDelta = true
 ds.saveToStream( file )
 ...
 ds.loadFromStream( file )
 ....
 ds.applyUpdates()

streamOnlyChangedRecords :boolean

Indica que apenas os registros que foram alterados devem fazer parte do stream. É bastante útil quando se quer salvar um dataset muito grande para o stream apenas com a intenção de usar o "applyUpdates" logo em seguida. Neste caso, para que não seja necessário mandar para o stream um DataSet muito grande, envia-se apenas os campos que sofreram alterações, otimizando o processo.

Type:
  • boolean
See:
Example
var fileStream = new File('C:\\streamChangedRecords.txt')
 // Supondo que o DataSet abaixo tem 100000 registros, mas apenas 50 foram alterados e
 // a intenção do script é apenas enviar para o stream > carregar do stream > aplicar
 // o applyUpdates. Para otimizar o processo, mandamos para o stream apenas os
 // registros alterados.
 ds.streamOnlyChangedRecords = true
 ds.saveToStream( fileStream )
 ....
 ds.loadFromStream( fileStream )
 ds.applyUpdates()

tableName :string

Nome da tabela de onde o DataSet está vinculado, caso o resultado do DataSet tenha vindo de uma consulta ao banco de dados ou a um clone do cache local.

Type:
  • string
See:
  • Connection#cloneLocalCache
  • Connection#cloneLocalCacheByClass
  • Connection#getDataSet
Example
var ds = connection.cloneLocalCache("ENTIDADE")
 // Neste ponto do script, a propriedade ds.tableName estará setada com "ENTIDADE"
 ds.tableName

verifyDeleteIntegrity :boolean

Indica se deve verificar a integridade referencial dos dados antes de uma deleção.

Type:
  • boolean
See:

viewActive :boolean

Determina se há um filtro de classe ativo, definido previamente pelo método #setView.

Type:
  • boolean
See:

Methods

<static> getIntegerDataType()

Obtém o tipo de dados real que é utilizado quando um campo é criado com o tipo legado "integer".

See:
Returns:
Type
DataSetFieldType

<static> getStringOverflowMode()

Obtém o modo atual de tratamento do estouro de campos do tipo string de DataSets.

Returns:

Valores possíveis: 'error' ou 'truncate'.

Type
string

<static> setIntegerDataType(type)

Define o tipo de dados real que é utilizado quando um campo é criado com o tipo legado "integer".

Esta é uma configuração avançada e global a nível de Engine. Alterar o seu valor irá afetar o funcionamento de todas as sessões JavaScript do sistema e pode provocar a perda de dados se utilizada indevidamente.

Parameters:
Name Type Description
type DataSetFieldType

Tipo que deve utilizado. Valores possíveis: 'int32' ou 'int64'.
See:

<static> setStringOverflowMode(mode)

Define o comportamento do DataSet ao atribuir um valor com tamanho maior que a capacidade de um campo do tipo string.

Esta é uma configuração avançada e global a nível de Engine. Alterar o seu valor irá afetar o funcionamento de todas as sessões JavaScript do sistema e pode provocar a perda de dados se utilizada indevidamente.

Parameters:
Name Type Description
mode string

Valores possíveis: 'error' (padrão) ou 'truncate'.
Example
DataSet.setStringOverflowMode('truncate');

addMultivalue(fieldId, value)

Insere um elemento numa lista de elementos separados por ponto e vírgula. Se o elemento já existir, ele não é duplicado, mesmo que este tenha um caso diferente. Ao alterar a lista, não há garantia de que a ordem dos elementos seja mantida.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo no DataSet com a lista de valores
value string

Elemento a ser inserido
See:

append( [dataSet] [, updatePreexistingKey] [, insertEvenPreexistingKey])

Abre uma linha para a inserção de registros no DataSet. Podem ser copiados todos os registros dos campos coincidentes de um DataSet para outro. No caso de "cópias" entre DataSets recomenda-se a utilização dos métodos clone() ou copy(), o que vai depender da situação. A utilização do método append() sem parâmetros faz com que o cursor fique posicionado no novo item inserido.
Este método pode disparar exceção caso o dataset tenha sido protegido pelo método #protect.

Parameters:
Name Type Argument Description
dataSet DataSet | Array <optional>

DataSet de onde serão copiados os registros para o DataSet corrente.
updatePreexistingKey boolean <optional>

Valor padrão: false Se este parâmetro for true e o DataSet corrente tiver o campo CHAVE e o DataSet também tiver o campo CHAVE e os registros que tiverem o mesmo conteúdo deste campo serão apenas atualizados no DataSet corrente.
insertEvenPreexistingKey boolean <optional>

Valor padrão: true. Se este parâmetro for true e os registros do DataSet serão inseridos no DataSet corrente mesmo se existir o campo CHAVE em ambos os DataSets e tiverem o mesmo conteúdo.
See:
Example
var saldo = new DataSet()
saldo.createField("DEPOSITO", "string", 50)
saldo.createField("VALOR", "number")
saldo.create()

saldo.append()
saldo.deposito = "DEPOSITO MATERIAIS"
saldo.valor = 400
saldo.post()

// ...

var ds = new DataSet()
ds.createField( "DEPOSITO", "string", 50 )
ds.createField( "VALOR", "number" )
ds.create()

ds.append()
ds.deposito = "DEPOSITO CENTRAL"
ds.valor = 300
ds.post()

// Grava os dados do "ds" para o "saldo"
saldo.append( ds )

// Neste ponto, a quantidade de registros do DataSet "saldo" será 2.
// A quantidade de registros do "ds" será 1.

applyLog(iLog [, options])

Refaz as alterações com base na tabela iLog.

Parameters:
Name Type Argument Description
iLog DataSet

Dataset que contém as informações de log.
options ApplyUndoLogOptions <optional>

Opções de aplicação do log transacional.
See:
Example
const log = database.query("SELECT * FROM iLog WHERE iVersion = " + toSqlString(version));
ds.applyLog(log);

applyUpdates( [waitDBCacheSync] [, logChanges])

Atualiza o DataSet e retorna a versão em que os registros foram gravados. Caso o dataSet não possua alterações, o retorno será 0.

Parameters:
Name Type Argument Description
waitDBCacheSync boolean <optional>

Indica se deve aguardar a sincronização do cache local após a atualização do servidor.
logChanges boolean <optional>

Registra as alterações na tabela iLog. Caso não seja informado, será considerado true. Este parâmetro é ignorado para tabelas que participam do cache local, pois o registro de log para essas tabelas é obrigatório.

Atenção: a desativação do log transacional não permite o desfazimento das alterações realizadas e prejudica a auditoria do sistema em inspeções de segurança. Modificações sem geração de log também não são aplicadas nas bases de dados destino dos processos de replicação de dados. Essas modificações podem ser perdidas em cenários de migração de banco de dados onde uma base de dados é sincronizada a partir do log transacional.
See:
Returns:

Versão das alterações ou zero caso não existam diferenças a serem gravadas. O valor retornado também é gravado nos campos iVersion ou VERSAO dos registros.

Type
number
Example
ds.append()
// ...
ds.del()
// ...
ds.applyUpdates()

backupState()

Cria uma cópia da configuração atual do dataSet, permitindo que elas possam ser restauradas posteriormente por #restoreState.

As propriedades que serão preservadas são: automaticApplyUpdates, logChanges, indexFieldNames, range, view, classesFilter, filter e o bookmark.

Esta função é útil para garantir que um dataset preserve a sua configuração após a execução de uma função que manipule o dataset de forma não previsível. O retorno dela deve ser utilizado exclusivamente para uma posterior restauração.

Returns:

Objeto contendo o estado atual do dataSet, podendo ser utilizado posteriormente na função #restoreState.

Type
Object
Example
var state = ds.backupState();
try {
  thirdPartyFunc(ds);
} finally {
 ds.restoreState(state);
}

bool(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo boolean.

Caso o valor do campo solicitado não seja um booleano, ele será convertido em um de forma equivalente a expressão Boolean(value).

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
boolean
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(-1898186559)) {
   ds.bool('iClass.MAE') // => true
   ds.bool('iName') // true
   ds.bool('iEnd') // false
 }

cancel()

Cancela a alteração de um registro no DataSet.

See:

cancelUpdates( [opt_key])

Apaga um ou todos os registros do delta do DataSet, ou seja, se depois das alterações no DataSet for chamado o método "cancelUpdates" e, logo em seguida, o "applyUpdates". As alterações não serão efetivadas na tabela à qual o dataset está associado. Nota: As alterações feitas no DataSet não são perdidas, apenas o delta do DataSet é descartado.

Parameters:
Name Type Argument Description
opt_key number <optional>

Chave do registro que deve ter as alterações do delta descartadas. Se não for informado, todo o delta será excluído.
See:
Examples
// <b>Exemplo 1</b> - descartando todas as alterações realizadas em um campo.

// Seleciona todas as entidades que tenham o código começado por "Transportadora".
var ds = database.query(
  "Select CHAVE, CLASSE, VERSAO, CODIGO, DATA " +
  "From ENTIDADE " +
  "Where CODIGO like 'Transportadora%'")

// Arquivo para onde vai o nome alterados das transportadoras
var file = new File("C:\\Transportadoras.txt")
file.writeln("CODIGO TRANSPORTADORA")
for ( ds.first; !ds.eof; ds.next() ){
  ds.codigo = ds.codigo + ' Ltda.'
  file.writeln(ds.codigo)
}
// Descarta o delta do DataSet para que as alterações
// feitas no código das transportadoras não vá para a tabela ENTIDADE
ds.cancelUpdates()

// Altera apenas o campo DATA do DataSet para a data corrente
for ( ds.first; !ds.eof; ds.next() ){
  ds.data = new Date();
}

// Efetivo as alterações das datas na tabela do DataSet
ds.applyUpdates();

// Como resultado, temos um arquivo com o nome das transportadoras alterados.
// No banco de dados, apenas as alterações de datas foram efetivadas.
// <b>Exemplo 2</b> - Adicionando registros atualizados em um DataSet auxiliar,
 // permitindo visualizar uma prévia antes de realizar o applyUpdates, sem alterar
 // o cache local.
 var iGroupUser = connection.cloneLocalCache("iGroupUser")
 var iGroupUserChanged = connection.copyStructureLocalCache("iGroupUser")

 if ( iGroupUser.findKey( key ) ){
   iGroupUserChanged.append()
   iGroupUserChanged.copyRecord(iGroupUser)
   iGroupUserChanged.post()
   // Descarta o delta de inserção, para que as alterações no registro
   // sejam interpretadas como uma atualização
   iGroupUserChanged.cancelUpdates( key )

   iGroupUserChanged.iname = "My test"
   iGroupUserChanged.post()
 }

clone(source [, opt_options])

Toda alteração feita no clone será replicada no source DataSet.

Parameters:
Name Type Argument Description
source DataSet

Dataset do qual será feito o clone.
opt_options Object <optional>

Opções do clone. Atualmente é suportada apenas a opção "sharedDelta", utilizada para indicar que este novo clone do cursor deve compartilhar o o mesmo delta do DataSet original. Por padrão ela é falsa.
See:
Examples
var ds = new DataSet();
ds.clone(source);
var ds = new DataSet();
ds.clone(source, {sharedDelta: true});

close()

Fecha um DataSet. Permite redefinir todos os campos de um DataSet. Usando o close, todos os registros do DataSet são perdidos.

Example
ds = new DataSet()
ds.createField('CLASSE', 'int64')
ds.createField('CODIGO', 'string', 50)
ds.createField('TOTAL',  'number')
ds.create()
// ...
ds.close()
ds.createField('CAMPO1', 'int64')
ds.createField('CAMPO2', 'string', 50)
ds.createField('CAMPO3', 'number')
ds.create()

copy(source)

Copia os dados de um DataSet para outro. Ao contrário do "clone", o "copy" não vincula o DataSet de origem ao de destino.

Parameters:
Name Type Description
source DataSet

DataSet a partir do qual será feita a cópia.
See:
Example
ds = new DataSet()
// ...
ds.copy( dsSource )
// ...

copyRecord(ds [, excludedFieldNames])

Copia um registro de um outro DataSet. Somente os campos que existam nos 2 DataSets serão copiados.

Parameters:
Name Type Argument Description
ds DataSet

DataSet que será copiado.
excludedFieldNames string <optional>

Nomes dos campos que não devem ser copiados.
Example
// Percorre o DataSet copiando todos os registros, exceto o campo chave
for ( source.first; !source.eof; source.next() ) {
  target.append()
  target.copyRecord( source, "CHAVE;VERSAO")
}

copyStructure(sourceDataSet [, fieldNames])

Copia as definições de campos de um dataSet.
O Exemplo abaixo copia todos os campos do DatSet ds1 para o DataSet ds2.

Parameters:
Name Type Argument Description
sourceDataSet DataSet

DataSet de onde será copiadas as definições dos campos.
fieldNames String <optional>

Lista de nomes de campos separados por ;(ponto-e-vírgula) que serão copiados. Se for omitido, serão copiados todos os campos.
Examples
ds1 = connection.cloneLocalCache("iVFS")

var ds2 = new DataSet()
ds2.copyStructure( ds1 )
ds2.create()
// Este outro exemplo copia os campo iName e iUrl do DataSet ds1 para o DataSet ds2.
ds1 = connection.cloneLocalCache("iVFS")

var ds2 = new DataSet()
ds2.copyStructure( ds1, 'iName;iUrl' )
ds2.create()

create()

Finaliza a criação do DataSet, liberando o mesmo para uso em memória. Antes da versão 11.1.0.10 não era possível inserir campos após o DataSet ser criado, a partir desta versão é possível inserir novos campos desde que o DataSet não pertença ao cache local.

See:
Example
var ds = new DataSet()
ds.createField( "NOME", "string", 150 )
ds.createField( "BOOLEANO", "boolean" )
ds.createField( "DATA", "date" )
ds.createField( "CHAVE", "int64" )
ds.createField( "VALOR", "number" )
ds.create()

createField(fieldName, fieldType [, opt_fieldSize])

Cria um novo Campo no DataSet.

É possível inserir novos campos após um DataSet ser criado desde que este não pertença ao cache local, caso haja clones deste DataSet os mesmos devem chamar o método reload para carregar as novas definições das tabelas.

Parameters:
Name Type Argument Description
fieldName string

Nome do Campo a ser criado no DataSet. Este parâmetro é obrigatório e deve, obrigatoriamente, ser declarado sem espaços.
fieldType string

Tipo do Campo. Valores possíveis: 'int32', 'int64', 'integer', 'date', 'number', 'string', 'memo' e 'boolean'. O tipo 'integer' é mantido apenas para fins de compatibilidade e ele será automaticamente mapeado para 'int32' ou 'int64' de acordo com o tipo indicado pela função estática setIntegerDataType. O tipo "numeric" não deve ser mais utilizado devido à obrigatoriedade de se informar a quantidade de casas decimais do campo. Em seu lugar deve ser utilizado o tipo "number".
opt_fieldSize number <optional>

Tamanho do Campo. Obrigatório quando o tipo do campo for 'string' ou 'numeric'.
Deprecated:
  • Utilize fieldDefs.add()
See:
Example
var ds = new DataSet()
ds.createField('NOME', 'string', 150);
ds.createField('BOOLEANO', 'boolean');
ds.createField('DATA', 'date');
ds.createField('CHAVE', 'int64');
ds.createField('VALOR', 'number');
ds.create();

date(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será uma instância de Date ou null.

Será gerado um erro caso o valor do campo solicitado não seja uma data, exceto quando ele for null. Nesse caso, o valor retornado também será null.

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
Date | null
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(session.userKey)) {
   ds.date('iLastPasswdChg') // => Date()
   ds.date('iEnd') // null
   ds.date('iName') // Error()
 }

dbkey(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local.

O valor retornado será uma instância de DBKey quando o campo estiver preenchido ou null no caso contrário. Será gerado um erro caso o valor do campo solicitado não seja um valor numérico inteiro. Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
DBKey | null
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(-1898186559)) {
   ds.dbkey('iClass') // => DBKey(-1898187809)
   ds.dbkey('iSmtpServer') // null
   ds.dbkey('iName') // Error()
 }

del()

Deleta o registro corrente do DataSet e move para o próximo. Muito cuidado ao se usar o "del", pois não se faz necessário o uso do "next", já que ele é automático.
Este método pode disparar exceção caso o dataset tenha sido protegido pelo método #protect.

See:
Example
// Deleta apenas os registros que sejam da classe -1151515
while ( !ds.eof ) {
  if ( ds.classe == -1151515 ) {
    ds.del()
  } else {
    ds.next()
  }
}

edit()

Deixa o DataSet em modo de edição.

See:

empty()

Esvazia o DataSet, apagando todos os registros. Este método não gera delta, logo ele não apaga os registros no banco de dados, apaga apenas no cache local. Este método apaga, no cache local, todos os registros da tabela, mesmo que o DataSet só traga uma parte dos registros da tabela, ou seja, suponha que a tabela TESTE possua 100 registros e esta tabela armazena registros da classe "CLASSE TESTE" que possui 50 registros. Ao executar o código abaixo serão excluídos todos os 100 registros da tabela TESTE do cache local e os registros permaneceram no banco de dados.
Este método pode disparar exceção caso o método protect tenha sido chamado com o parâmetro canDelete igual a false.

See:
Example
var ds = connection.cloneLocalCacheByClass( -123456789 / * Classe * / )
ds.empty()

fieldIsNull(fieldNameOrPositionIndex)

Indica se o campo está vazio.

Parameters:
Name Type Description
fieldNameOrPositionIndex Object

Nome ou índice do campo.
Returns:

Retorna true se o campo estiver sido informado.

Type
boolean
Example
// Percorre o DataSet e se o campo for nulo, atribui a data
// corrente a ele
for ( ds.first; !ds.eof; ds.next() ) {
  for ( var i = 0; i < 10; i++) {
    if ( ds.fieldIsNull("DATA" + i) ) {
      ds.setField("DATA" + i, new Date() )
     }
  }
}

fieldIsProtected(fieldName)

Testa se o campo informado foi protegido contra alterações pelo método protect.

Parameters:
Name Type Description
fieldName string

Nome do campo a ser testado.
See:
Returns:

true se o campo estiver protegido.

Type
boolean

fieldWasModified(fieldId)

Verifica se o campo foi modificado desde o último applyUpdates se o DataSet tiver controle de alterações (logChanges ativo). Caso contrário, verifica se o campo foi modificado na edição corrente.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo a ser verificado.
See:
Example
ds = new DataSet();
ds.createField('CHAVE', 'int64');
ds.createField('VERSAO', 'int64');
ds.createField('CLASSE', 'int64');
ds.create();

ds.logChanges = false;
ds.append([1, null, 1]);
ds.fieldWasModified('CLASSE'); // => true
ds.post();
ds.fieldWasModified('CLASSE'); // => false
ds.setField('CLASSE', 2);
ds.fieldWasModified('CLASSE'); // => true
ds.post();
ds.fieldWasModified('CLASSE'); // => false

ds.logChanges = true;
ds.fieldWasModified('CLASSE'); // => false
ds.setField('CLASSE', 3);
ds.fieldWasModified('CLASSE'); // => true
ds.post();
ds.fieldWasModified('CLASSE'); // => true

find(searchValues)

Busca um valor ou um array de valores no DataSet. Para usar este método, é necessário que o DataSet esteja indexado.

Parameters:
Name Type Description
searchValues Object

Elementos a serem pesquisados. Array, Integer, String ou array de strings que deverá ser buscado.
See:
Returns:

True se for encontrado um registro.

Type
boolean
Example
ds.indexFieldNames = "CHAVE"
if ( ds.find( chPessoa ) ) {
  // ...
}

findField(fieldName)

Verifica se o campo existe no DataSet.

Parameters:
Name Type Description
fieldName string

Nome do campo a ser procurado.
See:
Returns:

Índice do campo. Caso não encontre, retorna -1.

Type
number
Example
// Evita um erro caso não encontre o campo
var ar = []
for ( ds.first; !ds.eof; ds.next() ) {
  for ( var i = 0; i < 15; i++) {
    if ( ds.findField("NOME" + i) != -1 ) {
      ar.push( ds.getField("NOME" + i) )
    }
  }
}

response.write( ar.join("\n"))

findKey(key)

Pesquisa um valor nos campos iKey ou CHAVE do DataSet. Este método não necessita de índices criados, quando o DataSet pertence ao Cache Local, sendo a forma mais rápida de realizar uma pesquisa de chave.

Parameters:
Name Type Description
key number

Chave a ser pesquisada.
See:
Returns:

True se for encontrado um registro.

Type
boolean
Example
if ( ds.findKey( chPessoa ) ) {
  // ...
}

findNearest(searchValues)

Busca um valor ou o imediatamente superior mais próximo.

Parameters:
Name Type Description
searchValues Object

String ou array de strings que deverá ser buscado.
See:
Example
// Se não encontrar o valor 15, procura o valor imediatamente superior.
ds.indexFieldNames = "ORDEM"
ds.findNearest("15")

first()

Posiciona o cursor no primeiro registro do DataSet. A posição dos registros no DataSet pode mudar caso os mesmos estejam indexados. Desta forma, recomenda-se atenção para as colunas indexadas antes da navegação dos registros.

See:
Example
var saldo = new DataSet()
 saldo.createField( "DEPOSITO", "string", 50 )
 saldo.createField( "VALOR", "number" )
 saldo.create()

 saldo.append()
 saldo.deposito = "DEPOSITO PRODUTOS"
 saldo.valor = 100
 saldo.post()

 saldo.append()
 saldo.deposito = "DEPOSITO MATERIAIS"
 saldo.valor = 400
 saldo.post()

 // Posiciona o cursor no Registro com DEPOSITO == "DEPOSITO PRODUTOS"
 saldo.first()

 // Ordena o DataSet "saldo" pela coluna "DEPOSITO"
 saldo.indexFieldNames = "DEPOSITO"

 // Posiciona o cursor no registro com DEPOSITO == "DEPOSITO MATERIAIS" porque o DataSet
 // "saldo" agora está indexado.
 saldo.first()

getDeltaInspector()

Retorna o objeto DeltaInspector, responsável por prover os métodos de acesso ao delta do DataSet.

See:
Returns:

Objeto DeltaInspector referente ao DataSet em questão.

Type
DeltaInspector

getField(fieldId [, options])

Obtém o conteúdo de um campo do DataSet a partir do seu nome ou índice.

O tipo do valor retornado por este método varia de acordo com o tipo e preenchimento do campo. Para sempre obter o valor em um determinado tipo, podem ser utilizados os métodos #str, #num, #date, #bool e #dbkey. Esses métodos convertem os valores nulos para o tipo desejado sempre que for possível e também suportam expressões lookups, como "CLASSE.NOME". No entanto, eles não suportam a leitura dos campos a partir dos seus índices numéricos, nem permitem indicar a origem do valor do campo por meio do parâmetro options.

Parameters:
Name Type Argument Description
fieldId number | string

Nome ou índice do campo.
options GetFieldOptions | number <optional>

Opções da classe "GetFieldOptions", separadas por "|"
See:
Returns:

Valor do campo.

Type
string | number | Date | boolean | null
Example
// GetFieldOptions usage:
let ds = database.getDataSet('SELECT iKey, iVersion From iGroupUser WHERE iKey = 123');
ds.setField('iName', 'Alice');
ds.applyUpdates();

ds = database.query('Select CHAVE, VERSAO, CODIGO From ENTIDADE Where CHAVE = 123');
ds.getField('iName'); // => 'Alice'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => 'Alice'
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => 'Alice'

ds.edit();
ds.setField('iName', 'Bob');
ds.getField('iName'); // => 'Bob'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => 'Alice'
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => 'Alice'

ds.post();
ds.getField('iName'); // => 'Bob'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => 'Bob'
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => 'Alice'

ds.applyUpdates();
ds.getField('iName'); // => 'Bob'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => 'Bob'
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => 'Bob'

ds.append();
ds.setField('iName', 'Carol');
ds.getField('iName'); // => 'Carol'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => null
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => null

ds.post();
ds.getField('iName'); // => 'Carol'
ds.getField('iName', GetFieldOptions.BEFORE_VALUE); // => 'Carol'
ds.getField('iName', GetFieldOptions.ORIGINAL_VALUE); // => null

ds.getField('unknown'; // => throws an error
ds.getField('unknown', GetFieldOptions.IGNORE_FIELD_NOT_FOUND); // => null

getFieldModified(fieldId)

Verifica se o campo foi modificado desde o último applyUpdates se o DataSet tiver controle de alterações (logChanges ativo). Caso contrário, verifica se o campo foi modificado na edição corrente.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo a ser verificado.
Deprecated:
  • Utilize o método "fieldWasModified".

getFieldName(fieldIdx)

Pega o nome de um campo do DataSet.

Parameters:
Name Type Description
fieldIdx number

Posição do campo (coluna) no DataSet, a partir de 0 até quantidade de campos -1.
See:
Example
// Cria um DataSet, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'int64')
ds.createField('CODIGO', 'string', 50)
ds.createField('TOTAL',  'number')
ds.create()
// ...
// Retorna "CODIGO"
var fieldName = ds.getFieldName(1)

getFieldNames( [opt_options])

Retorna o nome de todos os campos do DataSet.

Parameters:
Name Type Argument Description
opt_options Object <optional>

Indica que devem ser retornados os nomes dos campos em caixa baixa.
See:
Returns:

Retorna os nomes de todos os campos do DataSet.

Type
Array.<string>
Example
var users = classes.getCachedDataSet(ngin.keys.Classes.USERS);
var names = users.getFieldNames();
var namesLowerCase = users.getFieldNames({toLowerCase: true})

getFields(fields, options)

Pega valores de campos do dataset.

Parameters:
Name Type Description
fields String | Array

Lista de campos para pegar valores. Se o parâmetro for uma string, os campos devem ser separados por ; (ponto-e-vírgula).
options GetFieldOptions

Opções de obtenção do valor do campo. Os valores podem ser combinados por meio do operador bitwise OR(|): GetFieldOptions.BEFORE_VALUE, GetFieldOptions.ORIGINAL_VALUE, GetFieldOptions.IGNORE_FIELD_NOT_FOUND.
Returns:

Devolve uma array com a lista de valores dos campos informados no parâmetro seguindo a mesma ordem.

Type
Array
Example
const values = source.getFields(['CAMPO1', 'CAMPO2']);
 if (target.find(values)) {
   //...
 }

getFieldSize(fieldNameOrPositionIndex)

Tamanho do campo no DataSet.

Parameters:
Name Type Description
fieldNameOrPositionIndex Object

Nome ou índice do campo no DataSet.
Deprecated:
  • Utilize fieldDefs.get(fieldName).size
See:
Returns:
Type
number
Example
// Cria um DataSet, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'int64')
ds.createField('CODIGO', 'string', 50)
ds.createField('TOTAL',  'number')
ds.create()

// ...

// Retorna "50"
var fieldName = ds.getFieldSize(1)

getFieldType(fieldId)

Obtém o tipo de dados de um campo.

Para preservar a compatibilidade com códigos legados, este método retorna identificadores que nem sempre têm uma relação exata com o tipo real do campo. Segue abaixo o mapeamento entre os tipos de dados dos campos e os valores retornados por esta função:

  • 'int32', 'int64': 'INTEGER'
  • 'string': 'CHAR()'
  • 'memo': 'MEMO'
  • 'number': 'NUMERIC'
  • 'date', 'datetime': 'DATE'
  • 'boolean': 'BOOLEAN'
Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo no DataSet.
Deprecated:
  • Utilize fieldDefs.get(fieldName).type
See:
Example
ds = new DataSet()
 ds.createField('CLASSE', 'int64');
 ds.createField('CODIGO', 'string', 50);
 ds.createField('TOTAL',  'number');
 ds.create();

 ds.getFieldType(0); // => 'INTEGER'

getIndex()

Retorna os índices do DataSet.

See:
Returns:

Retorna um array de duas posições na [0] os índices, na [1] os índices na ordem descendente.

Type
Array.<string>
Example
// Se não encontrar o valor 15, procura o valor imediatamente superior.
ds.setIndex( "CLASSE;CODIGO;DATA", "DATA")
// ...
var arIndexFields = ds.getIndex()

getInformedField(fieldNameOrIndex)

O conceito do termo 'InformedField' trata de uma sinalização para indicar se o conteúdo de um campo do DataSet foi informado pelo usuário do sistema ou não. Geralmente esta propriedade é alterada no DataSet pela grid do Framework

Parameters:
Name Type Description
fieldNameOrIndex string | number

Nome ou índice do campo a saber se seu conteúdo foi informado pelo usuário.
Returns:

true se o conteúdo do campo consultado foi informado pelo usuário.

Type
boolean

getLocalDBInfo()

Obtém informações sobre a base de dados local IDO utilizada para armazenar a tabela manipulada por este dataset. Será retornado um objeto com as seguintes propriedades:

  • name: nome da base de dados;
  • uniqueId: id único da base de dados no Engine local; e*
  • kind: indica o tipo de base de dados utilizada, podendo ser 'temporary' ou 'persistent'.
Returns:
Type
Object

getRange()

Obtém um vetor cujo o conteúdo são as restrições de um DataSet a uma faixa de filtros.

Returns:

Vetor bidimensional com as restrições de um DataSet a uma faixa de filtros.

Type
Array

getRecordApplyUpdatesAction(key)

Indica qual ação será realizada no banco de dados com o registro informado, durante o applyUpdates. Por padrão a ação é determinada pelo DataSet com base na alteração realizada (inserção, alteração ou exclusão), mas ela pode ser modificada através do método DataSet.setRecordApplyUpdatesAction().

Parameters:
Name Type Description
key number

Chave do registro
See:
Returns:

Ação que será realizada no banco de dados. Valores possíveis: ApplyUpdatesAction.NONE, ApplyUpdatesAction.INSERT, ApplyUpdatesAction.UPDATE, ApplyUpdatesAction.FORCED_UPDATE e ApplyUpdatesAction.DELETE. A documentação do parâmetro action do método DataSet.setRecordApplyUpdatesAction() possui detalhes destas constantes.

Type
number

getRows(fieldName)

Busca todos os registros de um field.

Parameters:
Name Type Description
fieldName string

Nome do campo que vai ter seus dados retornados.
Returns:

Array com todos os registros da coluna solicitada.

Type
Array
Example
var ds = connection.cloneLocalCache('ENTIDADE')
ds.getRows('CHAVE')

getView()

Obtém a definição do filtro de classe previamente configurado pelo método #setView.

See:

gotoBookmark(bookmark)

Posiciona o dataSet no bookmark informado ou gera um erro caso a posição informada não exista mais ou tenha sido filtrada.

Parameters:
Name Type Description
bookmark string

Posição desejada, obtida anteriormente pela propriedade #bookmark

goToCurrent(ds)

Nota: Um DataSet deve, obrigatoriamente, ser clone do outro.

Parameters:
Name Type Description
ds DataSet

Dataset que deve ser mudado a posição do cursor.
See:
Example
// ds ficará com o cursor na posição do cursor de ds1
 ds1.goToCurrent(ds)
 (...)

gotoRowId(rowId)

Posiciona o dataSet no registro com informado ou gera um erro caso a o registro não exista mais ou tenha sido filtrado.

Parameters:
Name Type Description
rowId number

Identificação do registro, obtida anteriormente pela propriedade #rowId

iterate(func [, thisObj])

Percorre todos os registros chamando a função passada para cada registro percorrido.

Para sair da iteração antes de percorrer todos os registros, a função deve retornar algum valor diferente de undefined, sendo este o mesmo valor retornado pelo método iterate. Ao término da execução o registro corrente será o mesmo antes do seu início.

Importante: a função informada não pode modificar a posição corrente do DataSet durante a iteração. Por esse motivo, não é permitido excluir registros durante a iteração, nem modificar campos que possam filtrar o registro corrente.

Parameters:
Name Type Argument Description
func function

Função que será executada a cada iteração.
thisObj Object <optional>

Objeto do tipo Object que será usado como valor para "this". Se este parâmetro não for informado um objeto vazio será criado.
Examples
const  ds = new DataSet();
ds.createField('name', 'string', 50);
ds.create();

ds.append();
ds.setField('name', 'test A');
ds.post();

ds.append();
ds.setField('name', 'test B');
ds.post();

let str = '';
ds.iterate(function (ds){
  str += ds.str('name') + '; ';
});
str; // => 'test A; test B; ';
const ds = new DataSet();
ds.createField('firstName', 'string', 50);
ds.createField('lastName', 'string', 50);
ds.create();

ds.append();
ds.setField('firstName', 'First');
ds.setField('lastName', 'Last');
ds.post();

const str = ds.iterate(function (ds) {
  if (ds.str('firstName') == 'First') {
    return ds.str('firstName') + ' ' + ds.str('lastName');
  }
});
str; // => 'First Last'

last()

Posiciona o cursor no último registro do DataSet.

See:
Example
// Percorre o DataSet "ds" do último registro ao primeiro.
 for ( ds.last(); !ds.bof; ds.prior() {
    ...
 }

loadFromStream(streamObject)

Carrega o DataSet a partir de arquivo ou stream.

Parameters:
Name Type Description
streamObject File | MemoryStream

Objeto da Classe File de onde o DataSet será criado.
See:
Example
// Usaremos como exemplo o arquivo
var arquivo = new File("C:\\dataset.txt")

// O arquivo deverá obrigatoriamente ter sido
// criado pelo loadFromStream.
ds.loadFromStream( arquivo )

locate(fields, values [, searchPartialValues])

Faz uma busca no DataSet, podendo ser aproximada(levando em consideração o começo da string).
Importante: O Locate é executado percorrendo todos os registros do DataSet pesquisado, exceto quando já existe um índice criado para o campo. Nesta situação, ele internamente executa um find e depois se reposiciona para a primeira ocorrência do valor pesquisado na ordem do índice corrente.
Normalmente o Locate deve ser utilizado apenas quando não se deseja alterar o índice corrente do DataSet. Em outras situações é preferível utilizar os métodos find ou findKey. Quando seu uso for realmente necessário, deve-se garantir que o campo pesquisado já tenha sido indexado.

Parameters:
Name Type Argument Description
fields string

Campos onde deve ser feita a busca. Deve ser separado por ";" caso seja mais de um.
values string | Date | number | boolean | null | Array.<(string|Date|number|boolean|null)>

Valores que devem ser pesquisados. Este valor deve ter no mínimo 4 caracteres.
searchPartialValues boolean <optional>

Valor Padrão: false. Indica se deve fazer uma busca parcial.
See:
Returns:

True se for encontrado um registro.

Type
boolean
Examples
var ds = dbCache.getTable(tableName)
ds.indexFieldNames = "ORDEM"
ds.indexFieldNames = "NOME"

if ( ds.locate( "ORDEM", 10 ) ){
  // ...
}
// No exemplo abaixo, irá buscar em CODIGO os registros que comecem com "1.1."
// Os seguintes valores seriam localizados: "1.1.001", "1.1.002", "1.1.003", "1.1.200", ...
ds.locate( "CODIGO", "1.1.", true)
// ...
// No exemplo abaixo, irá buscar em CODIGO os registros iguais a "Maria".
ds.locate( "CODIGO", "Maria")
// ...

locateNextPattern()

Posiciona o cursor na próxima ocorrência do que foi procurado no método "locatePattern".

See:
Returns:

True se for encontrada uma próxima ocorrência.

Type
boolean
Example
ds.locatePattern( "CLASSE;CODIGO", "Despesa;Imposto", "and")

locatePattern(fields, values, logicalOperator)

Faz uma busca aproximada.

Parameters:
Name Type Description
fields string

Campos onde deve ser feita a busca. Deve ser separado por ";" caso seja mais de um.
values string

Valores que devem ser pesquisados separados por ";". Este valor deve ter no mínimo 4 caracteres.
logicalOperator string

"And" ou "Or". Indica qual regra usará na busca dos patterns.
See:
Returns:

True se for encontrado um registro.

Type
boolean

newSharedDataSet( [opt_options])

Cria um dataset compartilhado, ou seja, os dados são os mesmos, contudo o navegador, faixa de registros acessíveis, indexação e registro corrente são diferentes.

Parameters:
Name Type Argument Description
opt_options Object <optional>

Opções. Existe apenas a opção "sharedDelta". Ela é usada para permitir que o DataSet compartilhe o mesmo delta do DataSet original. Por padrão ela é falsa.
See:
  • DataSet#clone
Returns:

Dataset compartilhado.

Type
DataSet
Example
// Cria um novo dataset com dados e delta compartilhado.
var ds = sourceDs.newSharedDataSet({sharedDelta: true});

next()

Posiciona o cursor no próximo registro do DataSet.

Example
ds.first()
 while ( !ds.eof ) {
    (...)
    ds.next() // Posiciona o cursor no próximo registro.
 }

num(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo number.

Caso o valor do campo solicitado seja nulo, será retornado 0. Será gerado um erro se valor não for numérico.

Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
number
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(-1898186559)) {
   ds.num('iClass.MAE') // => -1898187811
   ds.num('iName') // => Error()
 }

post()

Confirma a alteração de um registro no DataSet. O post é chamado na navegação de registros por padrão. Ou seja, se um registro for alterado e for solicitado para ir ao próximo registro, por exemplo, as alterações são salvas.

See:
Example
var saldo = new DataSet()
saldo.createField("DEPOSITO", "string", 50 )
saldo.createField("VALOR", "number" )
saldo.create()

saldo.append()
saldo.deposito = "DEPOSITO MATERIAIS"
saldo.valor = 400
saldo.post()

prior()

Posiciona o cursor no registro anterior do DataSet.

See:
Example
for (ds.last(); !ds.bof; ds.prior()) {
}

protect(fields [, opt_options])

Protege os dados de um DataSet. A proteção pode ser contra alteração de campos, inserção, remoção e navegação em registros do DataSet.
Após a chamada do protect, os métodos de navegação, de alteração da massa de dados do DataSet, métodos de inserção, de remoção e atributos serão bloqueados, passando a disparar exceção.

Parameters:
Name Type Argument Description
fields Array.<string>

Array com os nomes dos campos que serão protegidos contra alterações.
opt_options Object <optional>

Objeto literal para uso de opções proteção

canInsert

{boolean} Indica se será permitida a inserção de registros no DataSet. Caso false, fará o método #append disparar uma exceção. O valor padrão desta propriedade é false.

canDelete

{boolean} Indica se será permitida a remoção de registros no DataSet. Caso false, fará o método #del disparar uma exceção. O valor padrão desta propriedade é false.

canNavigate

{boolean} Indica se será permitida a navegação de registros no DataSet. Caso false fará os métodos de navegação dispararem uma exceção. O valor padrão desta propriedade é true.

canPost

{boolean} Indica se será permitido realizar o Post no DataSet. Caso false fará os métodos que realizam post dispararem uma exceção. O valor padrão desta propriedade é true.

clonesInheritProtection

{boolean} Indica se as configurações de proteção de um DataSet serão copiadas ou não para um clone do DataSet. O valor padrão desta propriedade é true.
See:
Returns:

Retorna uma key, um número que deve ser guardado,sendo necessário para desproteger o DataSet.

Type
number
Example
var ds = database.query('Select * from classe');
 ds.protect(['chave', 'versao'], {canInsert: true, canDelete: false});

reload()

Recarrega um DataSet com as última definições feitas na tabela. Quando são criados novos campos em um DataSet já iniciado este método deve ser chamado em seus clones para que eles recarreguem com as novas definições de campos pois se tornaram inconsistentes.

See:

removeMultivalue(fieldId, value)

Remove um elemento de uma lista de elementos separados por ponto e vírgula. Se o elemento existir, ele será removido independente do caso. Ao alterar a lista, não há garantia de que a ordem dos elementos seja mantida.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo no DataSet com a lista de valores
value string

Elemento a ser removido
See:

resetFields()

Redefine toda a definição de campos do DataSet.

Deprecated:
  • Utilize fieldDefs.clear()
See:
Example
// Cria um dataset, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'int64')
ds.createField('CODIGO', 'string', 50)
ds.createField('TOTAL',  'number')
ds.create()

// Apaga toda a definição definida acima
ds.resetFields()

resetRange()

Limpa o range corrente no DataSet.

See:
Example
// Limita o DataSet a mostrar apenas a pessoa "Maria" da classe "Funcionários"
ds.indexFieldNames = "CLASSE;PESSOA"
ds.setRange(["Funcionários","Maria"], ["Funcionários","Maria"])
// ...
// Limpa o range. O DataSet volta ao estado original, com a quantidade de registro original.
ds.resetRange()

resetView()

Desativa o filtro de classe previamente configurado pelo método #setView.

See:

restoreState(state)

Restaura um backup da configuração de um dataSet previamente criado pela função #backupState.

As propriedades que serão restauradas são: automaticApplyUpdates, logChanges, indexFieldNames, range, view, classesFilter e o filter. A posição preservada pelo backup será restaurada se o registro ainda existir no dataSet. Caso o registro tenha sido excluído, será mantida a posição relativa (recNo) anterior.

Esta função é útil para garantir que um dataset preserve a sua configuração após a execução de uma função que manipule o dataset de forma não previsível.

Parameters:
Name Type Description
state Object

Backup do estado que será restaurado. Ele deve ter sido criado previamente pela função #backupState.
Example
var state = ds.backupState();
try {
  thirdPartyFunc(ds);
} finally {
 ds.restoreState(state);
}

rollBack()

Desfaz todas as alterações que estão registradas no delta do DataSet.

Nota: O rollBack usa o delta para desfazer as alterações no DataSet, ou seja, apenas o que estiver no delta será desfeito.

See:
Example
var ds = database.query("Select CHAVE, CLASSE, VERSAO, CODIGO " +
    "From TABELA Where CODIGO like 'Representações%'")
// Faz alterações no DataSet
for ( ds.first; !ds.eof; ds.next() ){
  ds.codigo = ds.codigo + ' & CIA.'
  // ...
}

// Deixa o DataSet na forma em que estava depois do último applyUpdates.
ds.rollBack()

saveToStream(streamObject)

Salva o DataSet em um stream.

Parameters:
Name Type Description
streamObject File | MemoryStream

Objeto stream para onde o DataSet será salvo.
See:
Example
// Usaremos como exemplo o arquivo
var file = new File("C:\\dataset.txt")
ds.saveToStream(file)

Cria um novo DataSet com os registros que satisfaçam os parâmetros de pesquisa.

Parameters:
Name Type Description
resultFields string

Lista de campos separados por "," (vírgula) que devem ser retornados no DataSet resultado da pesquisa.
searchFields string

Lista de campos separados por "," (vírgula) que devem ser pesquisados.
value string

Texto a ser pesquisado. Para pesquisas parciais, deve ser utilizado o caractere "%". Exemplo: "valor%".
inexact boolean

Indica se a pesquisa será inexata. A pesquisa inexata utiliza o algoritmo Metaphone para descobrir palavras semelhantes às pesquisadas.
limit number

Limite da quantidade de registros que devem ser localizados.
Returns:

É retornado um clone do DataSet filtrado de acordo com a pesquisa

Type
DataSet

setField(fieldId, value [, opt_ignoreInvalidFieldId])

Atribui valor a um campo do DataSet. É recomendado que se use a forma "dataset.nomeDoCampo = valor" para se atribuir o conteúdo de um campo do DataSet. A forma "dataset.setField(name, content)" é indicada apenas para casos em que o nome do campo pode ser obtido de forma dinâmica, como no exemplo que vimos.

Parameters:
Name Type Argument Description
fieldId number | string

Nome ou índice do campo.
value *

Valor a ser atribuído ao campo.
opt_ignoreInvalidFieldId boolean <optional>

Indica se deve ou não ignorar campos com nomes inválidos. Ou seja, caso seja solicitado um nome de campo que não exista no DataSet, (supondo que foi informado "true") não será gerado um erro, caso contrário, um erro é disparado informando que o campo não existe no DataSet.
See:
Example
// Gera um erro caso o campo não seja encontrado
for ( ds.first; !ds.eof; ds.next() ) {
  for ( var i = 0; i < 15; i++) {
    ds.setField("NOME" + i, "nome" + i) )
  }
}

// Desta forma, não acusa um erro caso o campo não seja encontrado
for ( ds.first; !ds.eof; ds.next() ) {
  for ( var i = 0; i < 15; i++) {
    ds.setField("NOME" + i, "nome" + i, true ) )
  }
}

setIndex(fieldNames [, opt_descendingFieldNames])

Cria índices no DataSet.

Parameters:
Name Type Argument Description
fieldNames string

Campos que devem ser indexados. Separados por ";".
opt_descendingFieldNames string <optional>

Campos que dever ser ordenados de forma descendente(Z-A). Separados por ";".
See:
Example
// Indexa o DataSet por CLASSE, CODIGO e DATA, ordenando DATA de foram descendente, ou seja,
// virá da maior para a menor
ds.setIndex( "CLASSE;CODIGO;DATA", "DATA")

setInformedField(fieldNameOrIndex, informed)

O conceito do termo 'InformedField' trata de uma sinalização para indicar se o conteúdo de um campo do DataSet foi informado pelo usuário do sistema ou não. Geralmente esta propriedade é alterada no DataSet pela grid do Framework.

Parameters:
Name Type Description
fieldNameOrIndex string | number

Nome ou índice do campo a alterar a propriedade.
informed boolean

Deve ser true se o conteúdo do campo indicado no primeiro parâmetro foi informado pelo usuário.

setRange(startVal, endVal)

Restringe o DataSet a uma faixa de registros.

Parameters:
Name Type Description
startVal *

Valor de início do range.
endVal *

Valor de final do range.
See:
Example
// Limita o DataSet a mostrar apenas a pessoa "Maria" da classe "Funcionários"
ds.indexFieldNames = "CLASSE;PESSOA"
ds.setRange(["Funcionários","Maria"], ["Funcionários","Maria"])

setRecordApplyUpdatesAction(key, action)

Indica qual ação deve ser realizada no banco de dados com o registro informado, durante o applyUpdates. Por padrão, a ação é determinada pelo DataSet com base na alteração realizada (inserção, alteração ou exclusão). Este método deve ser utilizado apenas nos casos em que a alteração realizada no DataSet não condiz com o que deve ser realizado no banco de dados.
A ação informada não será preservada caso o registro seja modificado em seguida. Exemplo: um registro com a ação UPDATE será modificado para DELETE caso seja chamado o método del().
Observação: O applyUpdates irá falhar caso o registro não exista no banco de dados e ação escolhida for UPDATE, FORCED_UPDATE e DELETE. Também não será permitida a ação INSERT caso o registro já exista no banco de dados.

Parameters:
Name Type Description
key number

Chave do registro
action number

Ação que deve ser realizada no banco de dados. Valores possíveis:
ApplyUpdatesAction.NONE - O registro no banco de dados não será alterado;
ApplyUpdatesAction.INSERT - O registro será inserido no banco de dados;
ApplyUpdatesAction.UPDATE - Os campos modificados do registro serão atualizado no banco de dados;
ApplyUpdatesAction.FORCED_UPDATE - O registro será atualizado no banco de dados, mesmo que nenhum campo tenha sido modificado. Neste caso, apenas o campo iVersion/VERSAO será atualizado no banco de dados;
ApplyUpdatesAction.DELETE - O registro será excluído do banco de dados e do DataSet.

setView(classKey [, userKey] [, securityExtraFilter])

Efetua um filtro de classe juntamente com filtros definidos no parâmetro securityExtraFilter.

Parameters:
Name Type Argument Description
classKey number

Chave da classe a partir da qual serão verificadas as permissões do usuário.
userKey number <optional>

Usuário que terá a visão restringida de acordo com suas permissões. Caso não seja informado, serão exibidos todos os registros de classKey e suas filhas.
securityExtraFilter string <optional>

Lista de nomes de campo ou lista de pares de nomes de campos usados na para filtrar os registros do DataSet.
See:
  • Connection#cloneVfsByClass
  • Connection#cloneLocalCacheByClass
  • Connection#getDataSet
Examples
var ds = database.query("Select CLASSE, ESTABELECI " +
     " From PEDIDO Where " + filtro);

// Filtra para exibir apenas os pedidos de vendas dos estabelecimentos aos quais o
// usuário tenha acesso.
// O estabelecimento usado para filtro é o especificado no cadastro de permissões da classe
// informada para o usuário informado, se não haver estabelecimento informado no cadastro
// de permissões, será utilizado.
// O estabelecimento do cadastro de usuários do sistema.
ds.setView( chaveDaClasseVendas, session.userKey , "ESTABELECI" )
var ds = database.query("Select CHAVE, CLASSE, ESTABELECI " +
     " From PEDIDO Where " + filtro);

// Para entender o exemplo abaixo, suponha que o campo 'ESTABELECI' no cadastro de
// permissões para a permissão do usuário 'session.userKey' na classe 'chaveDaClasseVendas'
// esteja vazio, mas o campo 'ESTABELECI' no cadastro de usuários está preenchido com 111111.
// Suponha também que o campo ICLASS na tabela IPERMISSION seja 222222.
// Ao executar o comando abaixo, só serão trazidos os registros da classe
// 'chaveDaClasseVendas' filtrados pela própria classe e pelos campos
// ESTABELECI = 111111 e CLASSE = 222222.
// Note o uso da palavra chave "in" em "CLASSE in ICLASS". Este recurso serve para
// especificar filtros cujos os nomes dos campos a serem testados na tabela do DataSet não
// conferem com os nomes dos campos da tabela iPermission ou iGroupUser.
// Os valores dos campos da tabela iPermission terão maior prioridade sobre os valores do
// campos da tabela iGroupUser, logo, se o campo ESTABELECI não estiver preenchido na
// iPermission, será utilizado o valor do campo ESTABELECI da iGroupUser.
ds.setView( chaveDaClasseVendas, session.userKey , "ESTABELECI;CLASSE in ICLASS" )

sql(sqlExpression)

Executa uma expressão SQL no banco de dados associado ao connection padrão e retorna o resultado para o DataSet.

Parameters:
Name Type Description
sqlExpression string

Texto com a query a ser executada no servidor.
Deprecated:
  • Utilize o método query da classe Database.
See:
Example
var ds = new DataSet()
 ds.sql("Select * From TABELA Where DATA = '01/01/1900'")

str(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local. O valor retornado sempre será um primitivo do tipo string. Ver #val para mais detalhes.

Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
string
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(-1898186559)) {
   ds.str('iClass.NOME') // => 'Usuários'
 }

sum(fieldsToGroup, fieldsToSum)

Soma os campos do DataSet, podendo somar por grupo.

A totalização realizada irá considerar o range e os filtros configurados no DataSet. Uma eventual edição pendente será efetivada automaticamente por este método e sempre que possível ele preservará a posição e as configurações do DataSet.

Parameters:
Name Type Description
fieldsToGroup string

Campos pelos quais o DataSet será agrupado. Separados por ";".
fieldsToSum string

Campos que o DataSet irá somar. Separados por ";".
See:
  • Connection#getDataSet
Returns:

Retorna um DataSet com os campos definidos nos parâmetros.

Type
DataSet
Example
// Cria um DataSet, definimos três campos
var ds = database.query("Select * From TABELA Where VALOR > 1000 and VALOR < 2000")

// Devolve um DataSet ordenado por CLASSE e NOME, somando o VALOR
var dsSum = ds.sum("CLASSE;NOME","VALOR")

testMultivalue(fieldId, value)

Testa a presença de um elemento numa lista de elementos separados por ponto e vírgula. A pesquisa é case-insensitive.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo no DataSet com a lista de valores
value string

Elemento a ser pesquisado
See:
Returns:

É retornado verdadeiro se o valor está presente na lista

Type
boolean

tryGotoBookmark(bookmark)

Tenta posicionar o dataSet no bookmark informado.

Parameters:
Name Type Description
bookmark string

Posição desejada, obtida anteriormente pela propriedade #bookmark
Returns:

True se conseguiu posicionar o dataSet, false caso a posição informada não exista mais ou tenha sido filtrada.

Type
boolean
Example
var users = classes.getCachedDataSet(classKey);
var bmk = users.bookmark;
customFunction(users);
users.tryGotoBookmark(bmk);

tryGotoRowId(rowId)

Tenta posicionar o dataSet no registro informado.

Parameters:
Name Type Description
rowId number

Identificação do registro, obtida anteriormente pela propriedade #rowId
Returns:

True se conseguiu posicionar o dataSet, false caso o registro informado não exista mais ou tenha sido filtrado.

Type
boolean
Example
var users = classes.getCachedDataSet(classKey);
var rowId = users.rowId;
customFunction(users);
users.tryGotoRowId(rowId);

undoLog(iLog [, options])

Desfaz as alterações com base na tabela iLog.

Parameters:
Name Type Argument Description
iLog DataSet

DataSet que contém as informações de log.
options ApplyUndoLogOptions <optional>

Opções de desfazimento do log transacional.
See:
Example
const log = database.query("SELECT * FROM iLog WHERE iVersion = " + toSqlString(version));
ds.undoLog(log);

unprotect(key)

Remove a proteção do DataSet.

Parameters:
Name Type Description
key number

chave do bloqueio.
See:
Returns:

[Boolean] Retorna um boolean, valor true se foi desbloqueado com sucesso.

updateAll(fieldNames, values [, options])

Atualiza os campos com os valores informados em todos os registros.

Este método efetivará qualquer edição pendente e não poderá ser utilizado em dataSets protegidos contra navegação.

Parameters:
Name Type Argument Description
fieldNames Array.<string>

Nomes dos campos que devem ser atualizados.
values Array | DataSet

Array com os valores a serem atribuídos aos campos ou dataSet de onde devem ser lidos os valores. Caso seja informado um array, ele deverá ter o mesmo tamanho de fieldNames.
options Object <optional>

Opções da atualização.

Properties
Name Type Argument Description
ignoreNonExistingFields boolean <optional>

Indica se devem ser ignorados os campos informados que não existem neste dataSet ou no eventual dataSet informado em values. Campos que existam neste dataSet, mas que não tenham correspondência no DataSet informado em values serão ignorados e não serão modificados.
See:
Example
itensPedido.updateAll(fieldNames, values, {
   ignoreNonExistingFields: true
 });

val(expr)

Retorna o valor do campo informado ou do último campo de uma expressão caso o primeiro campo dessa expressão contenha a chave de um registro que faça parte do cache local.

Tentar obter um campo que não existe na tabela de um registro produzirá um erro. Essa verificação é realizada com base nos campos da tabela gravada no cache local. Um campo recém criado no banco de dados não poderá ser utilizado por este método enquanto o Engine não for reiniciado para atualizar a estrutura do banco local.

Solicitar um campo de um valor nulo retornará null e interromperá a avaliação da expressão. Esse comportamento possibilita que uma expressão possa ser utilizada sem que seja necessário verificar se todos os valores dos campos são não nulos. Observar que esse comportamento não se aplica para uma chave inválida, como a gerada a partir de um valor não numérico ou NaN. Neste caso específico, será gerado um erro ao tentar obter o campo.

O valor retornado por este método sempre será um primitivo ou uma data, mesmo que seja solicitado o valor de um campo que contenha outras chaves no sistema. Nesse caso, será retornado o o valor numérico da chave como number.

Uma característica importante deste método é que o tipo do valor retornado poderá mudar para a mesma expressão informada. Isso ocorre quando um dos campos da expressão é null o que forçará que o retorno deste método também seja null. Portanto, ao utilizar esse método, sempre verifique se o retorno é diferente de null antes de utilizar os métodos esperados para o tipo do campo final da expressão. Preferencialmente, pode ser utilizado um dos métodos abaixo para garantir o tipo retornado:

* module:@nginstack/engine/lib/dataset/DataSet~DataSet#str
* module:@nginstack/engine/lib/dataset/DataSet~DataSet#num
* module:@nginstack/engine/lib/dataset/DataSet~DataSet#bool
* module:@nginstack/engine/lib/dataset/DataSet~DataSet#date
* module:@nginstack/engine/lib/dataset/DataSet~DataSet#dbkey
Parameters:
Name Type Description
expr string

O nome de um campo ou uma expressão de campos separados por ".".
See:
Returns:

Valor do campo.

Type
string | number | null | boolean | Date
Example
const ds = dbCache.getTable('iGroupUser');
 if (ds.findKey(-1898186559)) {
   ds.val('iName'); // => 'administrator'
   ds.val('iClass.NOME') // => 'Usuários'
   ds.val('iUnknownField') // => Error()
   ds.val('iClass.iUnknownField') // => Error()
 }