Condições: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR
Este comando é threadsafe se o arquivo ao qual se refere for:
Definido como remoto e a função do comando é enviada por meio de uma conexão IPIC para uma região CICS remota.
Definido como VSAM ou RLS local.
Este comando não é thread-safe se o arquivo ao qual se refere for:
Definido como remoto e a função do comando é enviada por meio de uma conexão não IPIC.
Definido como uma tabela de dados compartilhados, tabela de dados do recurso de acoplamento ou arquivo BDAM.
Descrição:
READNEXT pode ser usado repetidamente para ler registros em ordem sequencial de um arquivo em um sistema local ou remoto. Essa série de comandos de leitura sequencial é conhecida como navegação pelo arquivo. Uma navegação também pode consistir em uma sequência de comandos READNEXT e READPREV em qualquer ordem. Uma navegação deve ser iniciada com o comando STARTBR, para identificar o ponto de partida da navegação, e finalizada com o comando ENDBR.
Você deve fornecer, na opção RIDFLD, uma área de dados que seja suficientemente grande para conter um identificador completo (chave completa, RBA ou RRN) dos registros no arquivo. Esta área de dados pode ser usada como saída e como parâmetro de entrada.
Ele é usado como um parâmetro de saída quando o CICS, após a conclusão de cada comando READNEXT, coloca o identificador completo do registro recém-recuperado na área de dados RIDFLD. O CICS então mantém esse identificador para marcar o ponto a partir do qual o READNEXT subsequente deve continuar.
Ele pode, exceto para BDAM, também ser usado como um parâmetro de entrada. Modificar o RIDFLD antes de emitir o próximo comando READNEXT faz com que esse comando reposicione a navegação para o novo identificador, a partir do qual continua da maneira usual. Se a navegação foi iniciada com a opção GENERIC, o RIDFLD modificado deve ser genérico. Se a navegação foi iniciada com a opção GTEQ, o próximo registro retornado é o primeiro registro no conjunto de dados com uma chave maior ou igual ao RIDFLD modificado.
Um comando READNEXT após um READPREV, ou um STARTBR ou RESETBR que especificou um valor de chave 'último', é tratado como se o valor RIDFLD tivesse sido modificado e resulta em uma reposicionamento (como acima).
Lendo arquivos acessados no modo RLS
Para arquivos acessados no modo RLS, você pode incluir a palavra-chave UPDATE na solicitação READNEXT para atualizar alguns registros durante a navegação. Se você especificar UPDATE, também deverá especificar TOKEN. Você pode então atualizar o registro emitindo um comando DELETE ou REWRITE que especifica o TOKEN retornado na função de navegação.
Nota: TOKEN sem a palavra-chave UPDATE implica UPDATE.
O uso da opção ATUALIZAR está sujeito às seguintes regras:
Você pode especificar UPDATE em um comando READNEXT apenas se o arquivo for acessado no modo RLS. Se você especificar UPDATE para um arquivo acessado no modo não RLS, o CICS retornará INVREQ.
Você pode especificar UPDATE em READNEXT, mas não nos comandos STARTBR ou RESETBR.
Você pode combinar as solicitações de atualização e não atualização no mesmo navegador.
O CICS não preserva a opção UPDATE para você de um comando READNEXT para o próximo.
O CICS suporta apenas um TOKEN em uma sequência de navegação e o valor TOKEN em cada READNEXT invalida o valor anterior.
Bloqueios para ATUALIZAÇÃO:
Especificar UPDATE em um comando READNEXT adquire um bloqueio exclusivo. A duração desses bloqueios exclusivos em uma navegação depende da ação que seu programa de aplicativo realiza:
Se você decidir EXCLUIR ou REWRITE o último registro adquirido por um READNEXT UPDATE em uma navegação, usando o token associado, o bloqueio permanece ativo da seguinte maneira:
Se o arquivo for recuperável, o bloqueio será liberado na conclusão do próximo ponto de sincronização ou reversão.
Se o arquivo não puder ser recuperado, o bloqueio será liberado quando o ENDBR for concluído, mas pode ser liberado antes.
Se você decidir não atualizar o último registro lido, o CICS libera o bloqueio exclusivo quando seu programa emite outro comando READNEXT ou READPREV ou termina a navegação.
Importante: O comando DESBLOQUEAR se não libertar um bloqueio exclusivo realizado por VSAM contra um registro adquirida pela READNEXT UPDATE. Um UNLOCK em uma navegação invalida o TOKEN retornado pela última solicitação.
Bloqueios para integridade de leitura
Especificar uma das opções de integridade de leitura adquire um bloqueio compartilhado em cada READNEXT. A duração desses bloqueios compartilhados com uma navegação depende do tipo de integridade de leitura que você especificar:
Se você especificar integridade de leitura CONSISTENTE, o bloqueio compartilhado será mantido apenas durante cada solicitação de leitura - ou seja, até que o registro seja retornado ao seu programa.
Se você especificar a integridade de leitura REPEATABLE, o bloqueio compartilhado será mantido durante a unidade de trabalho na qual a procura é executada. Nesse caso, seu programa pode adquirir um grande número de bloqueios compartilhados, o que impedirá a concessão de bloqueios exclusivos para funções de atualização. Você deve usar integridade de leitura REPEATABLE em uma navegação com cuidado.
Envio de função READNEXT com UPDATE ou integridade de leitura
Se um comando READNEXT que especifica UPDATE ou uma das opções de integridade de leitura for enviado por função a um membro da família de produtos CICS que não suporta UPDATE ou as opções de integridade de leitura, a solicitação falha:
Se um link ISC for usado, a solicitação receberá uma noite ATNI.
Se um link MRO for usado, a solicitação receberá uma noite AXF8.
AXF8 é um código de abend, recebido pelo lado de envio de uma solicitação enviada com função. Indica que foi feita uma tentativa de enviar uma solicitação que especifica UPDATE em um link MRO para uma região CICS que não suporta as opções de atualização ou integridade de leitura.
Integridade de leitura
Quando um arquivo é acessado no modo RLS, as solicitações de leitura sem atualização podem especificar opções de integridade de leitura: UNCOMMITTED, CONSISTENT ou REPEATABLE.
Se você não especificar nenhuma dessas palavras-chave, o CICS usará o valor especificado no parâmetro READINTEG da definição de recurso FILE, para o qual o padrão é UNCOMMITTED.
Se você deseja usar o nível de integridade de leitura especificado na palavra-chave READINTEG da definição de FILE e, em seguida, precisa mudar de um arquivo local para um arquivo remoto, ou se alterar a localização de um arquivo remoto, certifique-se de que:
A região remota de propriedade do arquivo está no nível do CICS Transaction Server para OS / 390®, Versão 1 Release 1 (ou posterior).
A definição de FILE no sistema remoto especifica:
Modo RLS
Os valores de integridade de leitura corretos para seu aplicativo.
Bloqueios retidos e ativos
RECORDBUSY refere-se a bloqueios ativos e LOCKED refere-se a bloqueios retidos.
Esses bloqueios afetam as solicitações READNEXT que adquirem bloqueios; ou seja, solicitações de atualização e solicitações com integridade de leitura. Esses são os tipos de solicitações READNEXT mencionadas nos marcadores a seguir. Outras solicitações READNEXT não são afetadas pela presença de bloqueios retidos ou ativos.
Solicitações READNEXT para registros que retiveram bloqueios são sempre rejeitadas com uma resposta LOCKED.
Os pedidos READNEXT para registros que possuem bloqueios ativos aguardam a liberação do bloqueio, exceto quando a palavra-chave NOSUSPEND é especificada, caso em que o CICS retorna a resposta RECORDBUSY.
Opções:
CONSISTENTE (apenas RLS)
O registro é lido com um nível de integridade de leitura fornecido por um bloqueio compartilhado VSAM que dura durante a solicitação.
Se o registro estiver sendo modificado por outra tarefa, que portanto mantém um bloqueio exclusivo, a solicitação READNEXT aguarda até que a atualização seja concluída (a menos que NOSUSPEND também seja especificado) da seguinte forma:
Para uma solicitação READNEXT em um arquivo não recuperável, a READ é concluída assim que qualquer solicitação VSAM executando a atualização for concluída.
Para uma solicitação READNEXT em um arquivo recuperável, a solicitação READ é concluída quando a tarefa de atualização conclui seu próximo ponto de sincronização ou reversão.
ARQUIVO ( nome do arquivo )
especifica o nome do arquivo a ser pesquisado.
Se SYSID for especificado, o conjunto de dados ao qual este arquivo se refere é considerado como estando em um sistema remoto, independentemente de o nome estar definido para o CICS. Caso contrário, a definição do recurso é usada para descobrir se o conjunto de dados está em um sistema local ou remoto.
INTO ( área de dados )
especifica a área de dados na qual o registro recuperado do conjunto de dados deve ser gravado.
KEYLENGTH ( valor de dados )
especifica o comprimento (binário de meia palavra) da chave que foi especificada na opção RIDFLD, exceto quando RBA ou RRN é especificado, caso em que KEYLENGTH não é válido.
Se a navegação foi iniciada sem a opção GENERIC (que é uma navegação de chave completa) e se o comprimento especificado for diferente do comprimento definido para o conjunto de dados, ocorre a condição INVREQ.
Se a procura foi iniciada com a opção GENERIC (ou seja, uma procura de chave genérica) e se o comprimento especificado for maior que o comprimento especificado para o conjunto de dados, ocorre a condição INVREQ.
Se GTEQ e GENERIC foram especificados no comando STARTBR ou RESETBR mais recente, emitir READNEXT com KEYLENGTH (0) reposiciona o BROWSE no início do arquivo. Se EQUAL tivesse sido especificado, o efeito de READNEXT KEYLENGTH (0) seria imprevisível.
Para uma navegação genérica, o CICS mantém um comprimento de chave atual para a navegação. O comprimento da chave atual é inicializado para ser o valor especificado como KEYLENGTH no comando STARTBR.
Você pode modificar o comprimento da chave atual especificando KEYLENGTH em um comando READNEXT ou RESETBR. Se o comprimento da chave atual for alterado, o navegador será reposicionado. O navegador é reposicionado para a chave cujos caracteres iniciais correspondem ao valor especificado no RIDFLD para o comprimento da chave atual.
O comprimento da chave atual é zero após uma solicitação que especifica KEYLENGTH (0).
SE KEYLENGTH for omitido em um comando READNEXT, o comprimento da chave atual permanece o mesmo e a navegação continua sem reposicionamento.
Se KEYLENGTH for especificado em um comando READNEXT e for igual ao comprimento da chave atual, isso será tratado como sem alteração e o navegador não será reposicionado. A única exceção é quando KEYLENGTH (0) é especificado, o que sempre faz com que o navegador seja reposicionado no início do arquivo.
KEYLENGTH pode ser especificado durante uma navegação genérica com um valor igual ao comprimento total da chave. Isso não altera o comprimento da chave atual e a navegação não é reposicionada. A capacidade de especificar o comprimento total da chave durante uma navegação genérica é fornecida para permitir que as solicitações que especificam SYSID possam dizer aos transformadores de envio de função quanto tempo a chave tem, para que os transformadores possam enviar a chave para a região proprietária do arquivo .
Um navegador pode ser reposicionado modificando a área de dados RIDFLD. Um navegador genérico é reposicionado apenas se a modificação de RIDFLD alterar a parte de RIDFLD correspondente ao comprimento da chave atual. Uma consequência disso é que o navegador não pode ser reposicionado modificando a área de dados RIDFLD se o comprimento da chave atual for zero.
Para arquivos remotos, o KEYLENGTH pode ser especificado na definição de FILE. Se KEYLENGTH não estiver definido lá e não for especificado no programa de aplicativo, e a chave tiver mais de 4 caracteres, o valor padrão será 4.
LENGTH ( área de dados )
especifica o comprimento, como um valor binário de meia palavra, da área de dados onde o registro deve ser colocado. Após a conclusão do comando READNEXT, o parâmetro LENGTH contém o comprimento real do registro.
Esta opção deve ser especificada se SYSID for especificado.
Se o arquivo estiver em um sistema remoto, o parâmetro LENGTH não precisa ser definido aqui, mas deve ser definido na definição de recurso do arquivo.
Se o arquivo estiver em um sistema local, o parâmetro LENGTH deve ser definido para registros de comprimento variável, usando a opção INTO, mas não para registros de comprimento fixo. É, no entanto, aconselhável especificar o comprimento para registros de comprimento fixo porque:
Isso faz com que uma verificação seja feita se o registro que está sendo lido não é muito longo para a área de dados disponível.
Ao navegar por registros de comprimento fixo em uma área maior do que o registro que está sendo acessado, a condição LENGERR é levantada para aplicativos COBOL, C, PL / I e linguagem assembler se a opção LENGTH for especificada. Se a opção LENGTH não for especificada explicitamente, a condição LENGERR será retornada se o comprimento puder ser inferido da área de dados. Se o comprimento especificado exceder o comprimento do registro do arquivo, o CICS usará o comprimento maior para a movimentação. Se a área de destino no programa de aplicativo não for grande o suficiente, o armazenamento será sobreposto além da área de destino.
Se você especificar a opção SET, não será necessário especificar também a opção LENGTH.
Ao navegar em uma área de dados de destino mais longa do que o registro que está sendo lido, o conteúdo da área de dados de destino, do final do registro recuperado ao final da área de dados de destino, é imprevisível.
Se você especificar a opção INTO, o argumento LENGTH deve ser uma área de dados que especifica o maior registro que o programa aceita. Se o registro recuperado for maior que o valor especificado na opção LENGTH, o registro será truncado para o valor especificado e a condição LENGERR ocorrerá. Nesse caso, a área de dados LENGTH é definida para o comprimento do registro antes do truncamento.
Observe que um comando de controle de arquivo emitido em um registro de comprimento variável em um arquivo definido no sistema CICS local falha com uma condição LENGERR se um comprimento não for especificado. No entanto, se o mesmo comando for emitido em um arquivo definido em um sistema remoto, o comando não falhará.
NOSUSPEND (apenas RLS)
A solicitação não espera se o registro estiver bloqueado pelo VSAM com um bloqueio ativo, incluindo registros bloqueados como resultado de um DEADLOCK.
Nota: As solicitações que especificam NOSUSPEND aguardam pelo menos 1 segundo antes que o CICS retorne a resposta RECORDBUSY.
RBA
(Conjuntos de dados de base VSAM KSDS ou ESDS ou tabelas de dados mantidas por CICS apenas, mas não caminhos) especifica que o campo de identificação de registro especificado na opção RIDFLD contém um endereço de byte relativo.
Esta opção deve ser especificada quando o comando STARTBR ou RESETBR especifica a opção RBA. Não deve ser especificado quando o comando STARTBR ou RESETBR não especificou RBA.
Você não pode usar RBA para:
- Tabelas de dados mantidos pelo usuário
- Tabelas de dados do recurso de acoplamento
- Qualquer arquivo KSDS aberto no modo de acesso RLS
- Arquivos KSDS que usam endereçamento estendido
Além disso, é recomendável não usar RBA para arquivos ESDS com mais de 4 GB. (Em vez disso, use XRBA.)
REPETÍVEL (apenas RLS)
O registro é lido com um nível de integridade de leitura fornecido por um bloqueio compartilhado VSAM que dura a unidade de trabalho na qual a solicitação de leitura é emitida.
Se o registro estiver sendo modificado por outra tarefa, que portanto mantém um bloqueio exclusivo, a solicitação READNEXT aguarda até que a atualização seja concluída (a menos que NOSUSPEND também seja especificado) da seguinte forma:
Para um arquivo recuperável, a solicitação READNEXT é concluída quando a transação de atualização completa seu próximo ponto de sincronização ou reversão.
Para um arquivo não recuperável, o READNEXT é concluído assim que a solicitação VSAM que executa a atualização é concluída.
Após a conclusão da solicitação READNEXT, o registro permanece bloqueado para a tarefa que emitiu o READNEXT. Outras tarefas podem continuar a ler o registro, mas nenhuma outra tarefa tem permissão para atualizar o registro até que a tarefa que emitiu o READNEXT execute seu próximo ponto de sincronização ou reversão.
REQID ( valor dos dados )
especifica como um valor binário de meia palavra um identificador de solicitação exclusivo para uma navegação, usado para controlar várias operações de navegação em um arquivo. Se esta opção não for especificada, um valor padrão de zero será assumido.
RIDFLD ( área de dados )
especifica o campo de identificação do registro. O conteúdo pode ser uma chave, um endereço de byte relativo ou número de registro relativo (para conjuntos de dados VSAM) ou uma referência de bloco, chave física e argumento de desbloqueio (para conjuntos de dados BDAM). Para um endereço de byte relativo ou um número de registro relativo, o formato deste campo deve ser binário de palavra inteira. Para um endereço de byte relativo, o RIDFLD pode ser maior ou igual a zero. Para um número de registro relativo, o valor RIDFLD pode ser maior ou igual a 1.
Consulte Identificando registros BDAM e Identificando registros VSAM para obter mais informações sobre como definir o campo de identificação de registro.
Mesmo se o navegador for genérico, esse RIDFLD deve ser sempre grande o suficiente para acomodar o identificador de registro completo. Isso ocorre porque, após a conclusão do comando READNEXT, o campo é atualizado pelo CICS com a identificação completa do registro recuperado.
RRN
(VSAM RRDS) especifica que o campo de identificação de registro especificado na opção RIDFLD contém um número de registro relativo.
SET ( ptr-ref )
especifica a referência do ponteiro que deve ser definida para o endereço do registro recuperado.
Em linguagem assembler, se a condição DUPKEY ocorrer, o registro especificado não terá sido definido, mas pode ser carregado a partir de DFHEITP1.
A referência do ponteiro é válida até que o próximo comando READNEXT ou READPREV especifique SET para o mesmo navegador (REQID) para o mesmo arquivo. O ponteiro não é mais válido após um comando ENDBR ou SYNCPOINT. Se você deseja reter os dados dentro do campo endereçado pelo ponteiro, você deve movê-lo para sua própria área.
Se DATALOCATION (QUALQUER) estiver associado ao programa aplicativo, o endereço dos dados pode estar acima ou abaixo da linha de 16 MB.
Se DATALOCATION (BELOW) estiver associado ao programa aplicativo, o endereço retornado no ponteiro SET está abaixo da linha de 16 MB.
Se TASKDATAKEY (USER) for especificado para a tarefa em execução, os dados retornados estarão no armazenamento da chave do usuário; caso contrário, é um armazenamento de chave CICS.
SYSID ( nome do sistema )
especifica o nome do sistema para o qual a solicitação é direcionada.
Se você especificar SYSID e omitir RBA e RRN, também deverá especificar LENGTH e KEYLENGTH; eles não podem ser encontrados na definição de recurso.
TOKEN (área de dados) (apenas RLS)
Retorna, como um valor binário de palavra inteira, o identificador de solicitação para esta solicitação READNEXT UPDATE. Este é um valor de saída retornado pelo controle de arquivo para a tarefa solicitante, para uso na associação de uma solicitação REWRITE ou DELETE (ou UNLOCK) subsequente com o registro retornado neste comando READNEXT.
Você deve especificar o TOKEN retornado em um comando REWRITE ou DELETE subsequente para identificar o registro que está sendo reescrito ou excluído. Você também pode especificar o valor retornado pelo CICS na opção TOKEN em um comando UNLOCK subsequente, para identificar o token que está sendo invalidado.
Você deve especificar TOKEN se especificar UPDATE (mas UPDATE será assumido se especificar TOKEN sem UPDATE).
O CICS suporta apenas um TOKEN ativo por vez para um determinado REQID. Portanto, um valor TOKEN permanece válido apenas até o seguinte comando READNEXT, READPREV, RESETBR ou ENDBR para este navegador, ou até um comando REWRITE, DELETE ou UNLOCK (o que ocorrer primeiro).
O TOKEN pode ser enviado com a função. No entanto, se uma solicitação especificando TOKEN for enviada a um membro da família de produtos CICS que não reconhece essa palavra-chave, a solicitação falhará.
NÃO COMPROMETIDO
O registro é lido sem integridade de leitura. Os dados atuais, conforme conhecidos pelo VSAM, são retornados. Nenhuma tentativa é feita para serializar este pedido de leitura com qualquer atividade de atualização simultânea para o mesmo registro. O registro pode estar sendo atualizado por outra transação, portanto, o valor do registro pode mudar posteriormente se essa atualização for posteriormente desfeita.
ATUALIZAÇÃO (somente RLS)
Especifica que o registro deve ser obtido para atualização ou exclusão. Se esta opção e o TOKEN forem omitidos, será assumido somente leitura.
Se você especificar UPDATE, também deverá especificar TOKEN.
UPDATE só é válido para arquivos definidos para a região local
XRBA
especifica que o campo de identificação de registro especificado na opção RIDFLD contém um endereço de byte relativo estendido. Esta opção deve ser usada ao navegar pelos registros em um conjunto de dados de endereçamento estendido ESDS.
Você não pode especificar XRBA em um comando READNEXT, a menos que o comando STARTBR ou RESETBR associado também tenha especificado XRBA.
Os conjuntos de dados KSDS não podem ser acessados por XRBA.