Class: DataSet

erp-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


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 ( usuarioConfirmouAGravacao ) {
    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 = connection.getDataSet("
    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

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

ignoredFieldNamesOnApplyUpdates :string

Nomes dos campos que não serão atualizados no banco 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 USUARIO"
 ds.nome = "NOME COMPLETO DO USUÁRIO"
 ds.cgccpf = "000.000.000-00"
 (...)
 ds.post()

 // Neste ponto, o campo CHAVE do DataSet "ds" receberá um valor disponível da sequência
 // de chaves do Sistema INTEQ. 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 metodo 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:

state :number

Indica em que estado o DataSet está no momento.

Type:
  • number
See:
  • DataSetStates
Example
var ds = new DataSet()
 this.checkEquals( DataSetStates.INACTIVE, ds.state)
 ds.createField( 'key', 'integer')
 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


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( "NUCLEO", "string", 50 )
saldo.createField( "VALOR", "number" )
saldo.create()

saldo.append()
saldo.nucleo = "ALMOX MATERIAIS"
saldo.valor = 400
saldo.post()

// ...

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

ds.append()
ds.nucleo = "ALMOX 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)

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

Parameters:
Name Type Description
iLog DataSet

Dataset que contém as informações de log.

See:
Example
var iLog = connection.getDataSet( "select * from iLog where ..." )
ds.applyLog( iLog )

applyUpdates( [opt_waitDBCacheSync] [, opt_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
opt_waitDBCacheSync boolean <optional>

Indica se deve aguardar a sincronização do cache local após a atualização do servidor.

opt_logChanges boolean <optional>

Indica se as alterações devem ser incluídas na tabela de Log. Obs: Este parâmetro não será considerado se a tabela pertencer ao cache local, porque o sincronismo do cache depende da tabela de Log.

See:
Returns:

Versão das alterações ou zero caso não exista diferenças a serem gravadas.

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);
}

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 = connection.getDataSet("
  Select CHAVE, CLASSE, VERSAO, CODIGO, ALTERACAO
  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 ALTERACAO do DataSet para a data corrente
for ( ds.first; !ds.eof; ds.next() ){
  ds.alteracao = 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(dataSource [, opt_options])

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

Parameters:
Name Type Argument Description
dataSource 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', 'Integer')
ds.createField('CODIGO', 'Char(50)')
ds.createField('TOTAL',  'Numeric(20,5)')
ds.create()
// ...
ds.close()
ds.createField('CAMPO1', 'Integer')
ds.createField('CAMPO2', 'Char(50)')
ds.createField('CAMPO3', 'Numeric(20,5)')
ds.create()

copy(dataSource)

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
dataSource 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", "integer" )
ds.createField( "VALOR", "number" )
ds.create()

createField(fieldName, fieldType [, opt_fieldSize])

Cria um novo Campo no DataSet. A partir da versão 11.1.0.10 é 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. "integer", "date", "number", "string", "boolean". O Tipo "numeric" não deverá ser mais utilizado devido à obrigatoriedade de se informar a quantidade de casas decimais do campo. Quando houver esta necessidade, deverá ser utilizado o tipo "numeric".

opt_fieldSize number <optional>

Tamanho do Campo. Obrigatório quando o Tipo do Campo for "string" ou "numeric"

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

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 metodo 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 CLASSETESTE 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

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:
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:
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( "NUCLEO", "string", 50 )
 saldo.createField( "VALOR", "number" )
 saldo.create()

 saldo.append()
 saldo.nucleo = "ALMOX PRODUTOS"
 saldo.valor = 100
 saldo.post()

 saldo.append()
 saldo.nucleo = "ALMOX MATERIAIS"
 saldo.valor = 400
 saldo.post()

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

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

 // Posiciona o cursor no registro com NUCLEO == "ALMOX 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.


getField(fieldId [, opt_options])

Pega o conteúdo de um campo do DataSet Nota: É recomendado que se use a forma "dataset.nomeDoCampo" para se obter o conteúdo do campo do DataSet. A forma "dataset.getField(nomeDoCampo)" é 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.

opt_options GetFieldOptions | number <optional>

Opções da Classe "GetFieldOptions", separadas por "|"

See:
Returns:

Valor do campo.

Type
string | number | Date | boolean | null
Example
var ds = connection.getDataSet( "Select CHAVE, VERSAO, CODIGO From ENTIDADE Where CHAVE = 123")
ds.codigo = 'maria'
ds.applyUpdates()

var ds = connection.getDataSet( "Select CHAVE, VERSAO, CODIGO From ENTIDADE Where CHAVE = 123")
this.checkEquals( 'maria', ds.getField('CODIGO'))
this.checkEquals( 'maria', ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( 'maria', ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

ds.codigo = 'jose'
this.checkEquals( 'jose', ds.getField('CODIGO'))
this.checkEquals( 'maria', ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( 'maria', ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

ds.post()
this.checkEquals( 'jose', ds.getField('CODIGO'))
this.checkEquals( 'jose', ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( 'maria', ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

ds.applyUpdates()
this.checkEquals( 'jose', ds.getField('CODIGO'))
this.checkEquals( 'jose', ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( 'jose', ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

ds.append()
ds.codigo = 'francisco'
this.checkEquals( 'francisco', ds.getField('CODIGO'))
this.checkEquals( null, ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( null, ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

ds.post()
this.checkEquals( 'francisco', ds.getField('CODIGO'))
this.checkEquals( 'francisco', ds.getField('CODIGO', GetFieldOptions.BEFORE_VALUE))
this.checkEquals( null, ds.getField('CODIGO', GetFieldOptions.ORIGINAL_VALUE))

// This call returns null
ds.getField('fieldX', GetFieldOptions.IGNORE_FIELD_NOT_FOUND)

// This call throw error
ds.getField('fieldX')

getFieldModified(fieldNameOrPositionIndex)

Se campo foi modificado ( comparando com o delta ).

Parameters:
Name Type Description
fieldNameOrPositionIndex Object

Nome ou índice do campo no dataset.

See:
Example
// Cria um dataset, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'Integer')
ds.createField('CODIGO', 'Char(50)')
ds.createField('TOTAL',  'Numeric(20,5)')
ds.create()

// ...

ds.logChanges = false
ds.insert()
ds.classe = 1
ds.post()

// Retorna false
var fieldModified = ds.getFieldModified(1)
ds.logChanges = false
ds.classe = 2
ds.post()

// Retorna true
var fieldModified = ds.getFieldModified('classe')

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', 'Integer')
ds.createField('CODIGO', 'Char(50)')
ds.createField('TOTAL',  'Numeric(20,5)')
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})

getFieldSize(fieldNameOrPositionIndex)

Tamanho do campo no DataSet.

Parameters:
Name Type Description
fieldNameOrPositionIndex Object

Nome ou índice do campo no DataSet.

See:
Returns:
Type
number
Example
// Cria um DataSet, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'Integer')
ds.createField('CODIGO', 'Char(50)')
ds.createField('TOTAL',  'Numeric(20,5)')
ds.create()

// ...

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

getFieldType(fieldId)

Tipo de dados do campo.

Parameters:
Name Type Description
fieldId number | string

Nome ou índice do campo no DataSet.

See:
Example
// Cria um DataSet, definimos três campos
ds = new DataSet()
ds.createField("CLASSE", "integer")
ds.createField("CODIGO", "string", 50 )
ds.createField('TOTAL',  "number" )
ds.create()
// ...

// Retorna "integer"
var fieldName = ds.getFieldType(0)

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()

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, do DataSet, 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.

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
var ds = new DataSet();
ds.createField('nome', 'String', 30);
ds.create();

ds.append();
ds.nome = 'teste1';
ds.post();
ds.append();
ds.nome = 'teste2';
ds.post();

var str = '';
ds.iterate(function(){
        str += ds.nome + '; ';
      });
str;
var ds = new DataSet();
ds.createField('firstName', 'String', 30);
ds.createField('lastName', 'String', 30);
ds.create();

ds.append();
ds.firstName = 'teste1';
ds.lastName = 'teste2';
ds.post();

var str = ds.iterate(function(){
        if (ds.firstName == 'teste1'){
          return ds.firstName + ' ' + ds.lastName;
        }
      });

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 * | Array.<*>

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:
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:
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:

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.
 }

pivot(pivotFieldName, totalFieldsNames, options)

Executa a operação de pivot no DataSet e retorna o DataSet pivoteado.

Parameters:
Name Type Description
pivotFieldName string

Nome do campo pivot.

totalFieldsNames String | Array

Lista de nomes de campos totalizadores. A lista pode ser uma string com os nomes dos campos separados por ;(ponto-e-vírgula) ou um Array com os nomes

options Object

Objeto literal com propriedade de configuração da operação de pivot.
As propriedades de configuração são:

  • noGroupingColumns - Vetor com os nomes da colunas que serão excluídas do agrupamento de colunas da operação de pivot.
  • totalizePivot - Valor booleano que se for true, a operação de pivot irá criar um coluna adicional com o total pivoteado.
  • defaultNumeric - Informa o valor default para valores numéricos pivoteados. O valor padrão desta propriedade é null.
Example
var ds = new DataSet();
ds.createField("ANO", "integer");
ds.createField("ESTAB", "string", 10);
ds.createField("MES", "string", 10);
ds.createField("VALOR", "integer");
ds.createField("QDE", "integer");
ds.create();

ds.append([2003, "Estab_01", "Janeiro", 20, 20]);
ds.append([2003, "Estab_01", "Fevereiro", 10, 5]);
ds.append([2003, "Estab_01", "Fevereiro", 30, 20]);
ds.append([2003, "Estab_01", "Abril", 30, 20]);
ds.append([2003, "Estab_02", "Fevereiro", 1, 4]);
ds.append([2003, "Estab_03", "Março", 20, 10]);
ds.append([2004, "Estab_01", "Março", 60, 4]);
ds.append([2004, "Estab_02", "Janeiro", 40, 30]);
ds.append([2004, "Estab_02", "Abril", 70, 20]);
ds.append([2004, "Estab_03", "Fevereiro", 50, 10]);
ds.append([2005, "Estab_03", "Janeiro", 80, 30]);
ds.append([2005, "Estab_03", "Janeiro", 20, 20]);
ds.append([2005, "Estab_03", "Janeiro", 20, 20]);

ds.pivot('MES', ['VALOR', 'QDE']);
 

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( "NUCLEO", "string", 50 )
saldo.createField( "VALOR", "number" )
saldo.create()

saldo.append()
saldo.nucleo = "ALMOX 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.

See:
Example
// Cria um dataset, definimos três campos
ds = new DataSet()
ds.createField('CLASSE', 'Integer')
ds.createField('CODIGO', 'Char(50)')
ds.createField('TOTAL',  'Numeric(20,5)')
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 = connection.getDataSet("Select CHAVE, CLASSE, VERSAO, CODIGO, ALTERACAO " +
    " 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")

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 = connection.getDataSet("Select CLASSE, ESTABELECI, EMISSAO, CHCRIACAO " +
     " From PEDIDO Where " + condicao);

// 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 Bematech.
ds.setView( chaveDaClasseVendas, session.userKey , "ESTABELECI" )
var ds = connection.getDataSet("Select CHAVE, CLASSE, ESTABELECI, EMISSAO, CHCRIACAO " +
     " From PEDIDO Where " + condicao);

// 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:
  • Yes
See:
  • Connection#getDataSet
Example
var ds = new DataSet()
 ds.sql("Select * From TABELA Where DATA = '01/01/1900'")

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 Argument Description
fieldsToGroup string <optional>

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 = connection.getDataSet("Select * From TABELA Where VALOR > 1000 and VALOR < 2000")

// Devolve um DataSet ordenado por CLASSE e VALOR, 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)

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

Parameters:
Name Type Description
iLog DataSet

DataSet que contém as informações de log.

See:
Example
var dsLog = connection.getDataSet( "select * from iLog where ..." )
ds.undoLog( dsLog )

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(camposCabecalho, cabecalhoPedido, {
   ignoreNonExistingFields: true
 });