Retorne o controle do programa.
Condições: CHANNELERR , INVREQ, LENGERR
Este comando é threadsafe.
Descrição:
RETURN retorna o controle de um programa de aplicativo para um programa de aplicativo no próximo nível lógico superior ou para o CICS®.
Ao retornar uma área de comunicação (COMMAREA), a opção LENGTH especifica o comprimento dos dados a serem passados. O valor LENGTH que está sendo transmitido não deve ser maior que o comprimento da área de dados especificada na opção COMMAREA. Se for, os resultados são imprevisíveis e podem resultar em uma condição LENGERR, conforme descrito na seção sobre como passar dados para outros programas em Passando dados para outros programas .
O intervalo válido para o comprimento COMMAREA é de 0 a 32.763 bytes. Se o comprimento fornecido estiver fora dessa faixa, a condição LENGERR ocorre.
As opções COMMAREA, IMMEDIATE e CHANNEL podem ser usadas apenas quando o comando RETURN está retornando o controle ao CICS; caso contrário, ocorre a condição INVREQ.
Nenhuma verificação de segurança de recurso ocorre no comando RETURN TRANSID. No entanto, a verificação de segurança da transação ainda está disponível quando o CICS anexa a transação retornada.
Opções:
CANAL ( nome )
especifica o nome (1–16 caracteres) de um canal que deve ser disponibilizado para o próximo programa que recebe o controle. Os caracteres aceitáveis são AZ az 0-9 $ @ # /% &? ! : | "= ¬,; <>. - e _. Caracteres em branco à esquerda e incorporados não são permitidos. Se o nome fornecido tiver menos de 16 caracteres, ele será preenchido com espaços em branco à direita de até 16 caracteres. Se o canal não existir, ele é criado. Este novo canal permanece no escopo até que o nível do link seja alterado. Para obter mais informações sobre o escopo do canal, consulte O escopo de um canal .
Os nomes dos canais estão sempre em EBCDIC. O conjunto permitido de caracteres para nomes de canais, listados acima, inclui alguns caracteres que não têm a mesma representação em todas as páginas de código EBCDIC. Portanto, recomendamos que, se um canal for enviado entre regiões (ou seja, se a transação nomeada na opção TRANSID for remota), os caracteres usados na nomenclatura devem ser restritos a AZ az 0-9 &: =,; <>. - e _.
Você pode especificar o nome do canal DFHTRANSACTION para usar um canal de transação. Um canal de transação não sai do escopo quando o nível do link muda: ele está sempre acessível na transação. Para obter mais informações, consulte Canais e contêineres .
O programa que emite o comando RETURN pode fazer um dos seguintes:
- Já criou o canal por meio de um ou mais comandos PUT CONTAINER CHANNEL
- Especifique seu canal atual, por nome
- Nomeie um canal inexistente, caso em que um novo canal vazio é criado
Esta opção é válida apenas em um comando RETURN emitido por um programa no nível lógico mais alto; ou seja, um programa que retorna o controle ao CICS.
COMMAREA ( área de dados )
especifica uma área de comunicação que deve ser disponibilizada para o próximo programa que recebe o controle. Em um programa de recebimento COBOL, você deve dar a essa área de dados o nome DFHCOMMAREA. Consulte Compartilhando Dados entre Transações para obter mais informações sobre o CICS COMMAREA. Como a área de dados é liberada antes do próximo programa iniciar, uma cópia da área de dados é criada e um ponteiro para a cópia é passado.
A área de comunicação especificada é passada para o próximo programa executado no terminal. Para garantir que a área de comunicação seja passada para o programa correto, inclua a opção IMEDIATA.
Esta opção é válida apenas em um comando RETURN emitido por um programa no nível lógico mais alto, ou seja, um programa que retorna o controle para o CICS.
ENDACTIVITY
Esta opção deve ser usada por programas que implementam atividades de serviços de transação de negócios (BTS) do CICS. Ele especifica que a atividade atual está sendo concluída e não deve ser reativada.
Se não houver eventos de usuário no pool de eventos da atividade, a atividade será concluída normalmente.
Se houver eventos de usuário (disparados ou não disparados) no pool de eventos da atividade:
Se um ou mais dos eventos forem eventos de conclusão de atividade, a atividade termina de forma anormal. Tentar forçar a conclusão de uma atividade antes de ela lidar com uma ou mais de suas atividades filho é um erro de lógica do programa.
Se nenhum dos eventos forem eventos de conclusão de atividade, os eventos serão excluídos e a atividade será concluída normalmente.
Para obter informações sobre o BTS em geral e a opção ENDACTIVITY em particular, consulte Conclusão da atividade .
Esta opção é ignorada fora do ambiente CICS BTS.
IMMEDIATE
garante que a transação especificada na opção TRANSID seja anexada como a próxima transação, independentemente de quaisquer outras transações enfileiradas pela ATI para este terminal. A próxima transação começa imediatamente e aparece para o operador como tendo sido iniciada pelos dados do terminal. Se o terminal estiver usando o protocolo de suporte, o terminal também será mantido em um suporte. Esta opção é válida apenas em um comando RETURN emitido por um programa no nível lógico mais alto, ou seja, um programa que retorna o controle ao CICS.
Observe que, em um ambiente multirregional, o uso de IMMEDIATE não afeta a definição da transação, pois ela ainda é encontrada na região de propriedade do terminal (TOR).
INPUTMSG ( área de dados )
especifica os dados a serem passados para outra transação, identificada pela opção TRANSID, ou para um programa de chamada em uma transação de multiprograma. Você também pode usar INPUTMSG ao retornar o controle para o CICS a partir de um programa de roteamento de transação dinâmico escrito pelo usuário, quando desejar modificar a entrada inicial.
Em todos os casos, os dados da área de dados INPUTMSG são passados para o primeiro programa a emitir um comando RECEIVE após RETURN.
Consulte INPUTMSG para obter mais informações e ilustrações sobre o uso de INPUTMSG.
INPUTMSGLEN ( valor de dados )
especifica um valor binário de meia palavra a ser usado com INPUTMSG.
LENGTH ( valor de dados )
especifica um valor binário de meia palavra que é o comprimento em bytes da COMMAREA. Para obter uma descrição de um limite superior seguro, consulte as opções de LENGTH em comandos CICS .
TRANSID ( nome )
especifica o identificador de transação (1–4 caracteres) a ser usado com a próxima mensagem de entrada inserida no terminal com o qual a tarefa que emitiu o comando RETURN foi associada. O nome especificado deve ter sido definido como uma transação para o CICS.
Se TRANSID for especificado para um programa em execução em um terminal definido com um ID de transação permanente, a transação permanente do terminal será iniciada em seguida, em vez da transação especificada em RETURN.
Se você especificar um TRANSID de zeros binários, o identificador de transação para o próximo programa a ser associado ao terminal pode ser determinado a partir da entrada subsequente do terminal. Emitir um RETURN com um TRANSID de zeros binários e uma COMMAREA pode causar resultados imprevisíveis se a próxima transação não for codificada para lidar com a COMMAREA ou se receber uma COMMAREA não destinada a ela.
Se você especificar TRANSID em um programa que não está no nível mais alto e houver um erro subsequente em COMMAREA, INPUTMSG ou CHANNEL no RETURN final, o TRANSID será limpo.
O próximo identificador de transação também é limpo em um encerramento anormal da transação.
Se IMMEDIATE for especificado com esta opção, o controle é passado para a transação especificada na opção TRANSID, de preferência para quaisquer transações enfileiradas pela ATI.
Se IMEDIATA não for especificado com esta opção, uma transação iniciada por ATI com o mesmo nome enfileirada no terminal anula esta opção.
Esta opção não é válida se a transação que emite o comando RETURN não estiver associada a um terminal ou estiver associada a uma unidade lógica APPC.