Condições: ENDDATA, ENVDEFERR, INVREQ, IOERR, LENGERR
Nota para roteamento de transação dinâmica : O uso de RETRIEVE com WAIT pode criar afinidades entre transações que afetam adversamente o uso de roteamento de transação dinâmica. Consulte Afinidade para obter mais informações sobre afinidades de transação.
Descrição:
O comando RETRIEVE recupera dados armazenados por comandos START expirados. É o único método disponível para acessar esses dados.
Uma tarefa que não está associada a um terminal pode acessar apenas o único registro de dados associado ao comando START original; ele faz isso emitindo um comando RETRIEVE. O armazenamento ocupado pelos dados associados à tarefa é normalmente liberado na execução do comando RETRIEVE ou no encerramento da tarefa se nenhum comando RETRIEVE for executado antes do encerramento.
Se o comando START especificou ATTACH, o armazenamento não é liberado. (ASSIGN STARTCODE em tal tarefa retorna 'U' em vez de 'S' ou 'SD').
Uma tarefa associada a um terminal pode acessar todos os registros de dados associados a todos os comandos START expirados com o mesmo identificador de transação e identificador de terminal que esta tarefa, ou seja, a tarefa que emite o comando RETRIEVE; ele faz isso emitindo comandos RETRIEVE consecutivos. Os registros de dados expirados são apresentados à tarefa mediante solicitação na sequência do tempo de expiração, começando com quaisquer dados armazenados pelo comando que iniciou a tarefa e incluindo dados de quaisquer comandos que tenham expirado desde o início da tarefa. Cada registro de dados é recuperado do armazenamento temporário usando o REQID do comando START original como a identificação do registro no armazenamento temporário.
Quando todos os registros de dados expirados forem recuperados, a condição ENDDATA ocorre. O armazenamento ocupado pelo único registro de dados associado a um comando START é liberado após os dados serem recuperados por um comando RETRIEVE; qualquer armazenamento ocupado por dados que não foram recuperados é liberado quando o sistema CICS é encerrado.
Se os dados recuperados contiverem FMHs (Cabeçalhos de Gerenciamento de Função), conforme especificado pela opção FMH no comando START associado, o campo EIBFMH no EIB é definido como X'FF ' . Se nenhum FMH estiver presente, EIBFMH é definido como X'00 ' .
Opções:
INTO ( área de dados )
especifica a área de dados do usuário na qual os dados recuperados devem ser gravados.
LENGTH ( área de dados )
especifica um valor binário de meia palavra para definir o comprimento da área de dados na qual os dados recuperados são gravados.
Se você especificar a opção INTO, o argumento deve ser uma área de dados que especifica o comprimento máximo dos dados que o programa está preparado para tratar. Se o valor especificado for menor que zero, zero é assumido. Se o comprimento dos dados exceder o valor especificado, os dados serão truncados para esse valor e a condição LENGERR ocorrerá. Na conclusão da operação de recuperação, a área de dados é definida para o comprimento original dos dados.
Se você especificar a opção SET, o argumento deve ser uma área de dados. Na conclusão da operação de recuperação, a área de dados é definida para o comprimento dos dados.
Para obter uma descrição de um limite superior seguro, consulte as opções de LENGTH em comandos CICS .
QUEUE ( área de dados )
especifica a área de 8 caracteres para o nome da fila de armazenamento temporário que pode ser acessada pela transação que emite o comando RETRIEVE.
RTERMID ( área de dados )
especifica uma área de 4 caracteres que pode ser usada na opção TERMID de um comando START que pode ser executado posteriormente.
RTRANSID ( área de dados )
especifica uma área de 4 caracteres que pode ser usada na opção TRANSID de um comando START que pode ser executado posteriormente.
SET ( ptr-ref )
especifica a referência do ponteiro a ser definida para o endereço dos dados recuperados.
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 (ABAIXO) estiver associado ao programa aplicativo e os dados residirem acima da linha de 16 MB, os dados serão copiados abaixo da linha de 16 MB e o endereço desta cópia será retornado.
Se TASKDATAKEY (USER) for especificado para a tarefa em execução e a proteção de armazenamento estiver ativa, os dados retornados estarão em uma chave de usuário. Se TASKDATAKEY (CICS) for especificado e a proteção de armazenamento estiver ativa, os dados retornados estarão em uma chave CICS.
Se você usar SET, também deve incluir LENGTH.
WAIT
especifica que, se todos os registros de dados expirados já tiverem sido recuperados, a tarefa deve ser colocada em um estado de espera até que outros registros de dados expirados se tornem disponíveis. Embora isso signifique que a condição ENDDATA não é levantada no momento em que o comando RETRIEVE é emitido, ela é levantada posteriormente se o CICS entrar no encerramento ou se a tarefa estiver sujeita a um tempo limite de conflito e aguardar mais do que o intervalo de tempo limite de conflito. (Consulte a opção DTIMOUT de RDO DEFINE TRANSACTION.)
Uma tentativa de emitir RETRIEVE WAIT durante o desligamento resultará em uma noite de AICB se não houver nenhum registro de dados disponível para atender à solicitação.
Se você usar WAIT, você deve ter pelo menos uma outra opção.
Exemplos:
O exemplo a seguir mostra como recuperar dados armazenados por um comando START para a tarefa e armazená-los na área de dados fornecida pelo usuário chamada DATAFLD.
EXEC CICS RETRIEVE
INTO(DATAFLD)
LENGTH(LENG)
O exemplo a seguir mostra como solicitar a recuperação de um registro de dados armazenado para uma tarefa em uma área de dados fornecida pelo CICS; a referência do ponteiro (PREF) especificada pela opção SET é definida para o endereço da área de armazenamento reservada para o registro de dados.
EXEC CICS RETRIEVE
SET(PREF)
LENGTH(LENG)