Condições: CHANNELERR, INVREQ, LENGERR, NOTAUTH, PGMIDERR, RESUNAVAIL, ROLLEDBACK, SYSIDERR, TERMERR
Este comando é thread-safe quando é usado para se vincular a um programa em uma região CICS local ou em uma região CICS remota por meio de uma conexão IPIC. Não é thread-safe quando é usado para vincular a um programa em uma região CICS remota por meio de outro tipo de conexão.
Descrição:
O LINK passa o controle de um programa aplicativo em um nível lógico para um programa aplicativo no próximo nível lógico inferior.
Se o programa solicitado não estiver definido para o CICS e AUTOINSTALL estiver ativo, o CICS fornecerá uma definição para o programa. Se esta definição for local e o programa vinculado ainda não estiver no armazenamento principal, o CICS o carregará.
Em algumas circunstâncias, o programa vinculado pode residir em outra região CICS; consulte o link do programa distribuído .
Este comando opera no contexto do aplicativo atual. Se o comando for emitido por um programa que está sendo executado em uma tarefa para um aplicativo implementado em uma plataforma, o CICS procura primeiro o programa nomeado no diretório de programa privado do aplicativo. Se o programa nomeado não for encontrado lá, o CICS pesquisará o diretório público do programa.
Quando este comando é usado para vincular a um programa que é declarado como um ponto de entrada do aplicativo para um aplicativo implementado em uma plataforma, o pacote CICS onde o ponto de entrada do aplicativo é declarado deve ter um status de AVAILABLE. O link é feito para a versão numerada mais alta do aplicativo que está instalado, habilitado e disponível. Para vincular a uma versão especificada de um aplicativo implantado em uma plataforma, use o comando INVOKE APPLICATION em vez do comando LINK.
Quando o comando RETURN é executado no programa vinculado, o controle é retornado ao programa que inicia o link na próxima instrução executável sequencial.
A interface externa do CICS (EXCI) fornece um comando LINK que executa todos os seis comandos da interface em uma chamada. Consulte a interface EXCI CALL para obter informações sobre EXCI.
O programa vinculado opera independentemente do programa que emite o comando LINK em relação às condições de tratamento, identificadores de atenção, encerramentos anormais e chave de execução. Por exemplo, os efeitos dos comandos HANDLE CONDITION no programa de vinculação não são herdados pelo programa vinculado, mas os comandos HANDLE CONDITION originais são restaurados no retorno ao programa de vinculação. Consulte Usando o comando HANDLE CONDITION para obter mais informações e uma ilustração do conceito de níveis lógicos.
Você pode usar o comando HANDLE ABEND para lidar com terminações anormais em outros níveis de link. Consulte Usando o comando HANDLE CONDITION para obter mais detalhes sobre o relacionamento entre LINK e HANDLE ABEND .
Link do programa distribuído
Em qualquer um dos seguintes casos, o link é um link de programa distribuído (DPL):
Você especifica um nome de região remota na opção SYSID, com ou sem as opções TRANSID e SYNCONRETURN associadas.
A opção REMOTESYSTEM na definição de PROGRAM instalada especifica o nome de uma região remota.
A definição do programa instalado especifica DYNAMIC (YES), ou não há definição do programa instalado, e o programa de roteamento dinâmico roteia o pedido de link para uma região remota.
Em resposta a um link de programa distribuído, a região CICS local (a região do cliente ) envia a solicitação de link para a região remota (a região do servidor ). A região do servidor executa o programa vinculado (o programa do servidor) em nome do programa que emite a solicitação de link (o programa cliente).
As opções SYSID e INPUTMSG são mutuamente exclusivas. Se você especificar ambas as opções em um comando LINK, o conversor emitirá a mensagem de erro DFH7230E indicando opções conflitantes.
Um programa de servidor em execução na região do servidor é restrito a um subconjunto DPL da API CICS. Em resumo, o programa do servidor não pode emitir estes comandos:
- Comandos de controle de terminal que fazem referência à instalação principal
- Opções de ASSIGN que retornam atributos do terminal
- Comandos BMS
- Comandos de logon e logoff
- Comandos de troca de dados em lote
- Comandos que abordam o TCTUA
Para obter detalhes sobre o subconjunto DPL restrito da API, consulte Condições de exceção para o comando LINK .
Se um programa de servidor termina de forma anormal, o código de abend é retornado ao programa cliente. Se o programa cliente não for escrito para lidar com o abend retornado pelo programa servidor, o programa cliente termina de forma anormal com o mesmo código de abend retornado pelo programa servidor.
Não é possível usar DPL para se vincular ao programa de terminal principal do CICS, DFHEMTA, ou ao programa RDO, DFHEDAP. Os endereços passados como parâmetros para DFHEMTA e DFHEDAP são válidos apenas na região que emite o comando EXEC CICS LINK, o que significa que você não pode rotear um pedido DFHEMTA ou DFHEDAP para um CICS remoto.
Importante: Para obter exemplos do uso do comando LINK quando o programa vinculado é remoto, consulte Distributed Program Link (DPL) . Para obter informações sobre como escrever um programa de roteamento dinâmico, consulte Roteando solicitações DPL dinamicamente .
Opções:
CANAL ( nome )
Especifica o nome (1 - 16 caracteres) de um canal que deve ser disponibilizado para o programa chamado. Os caracteres aceitáveis são A - Z a - z 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 de caracteres permitidos para nomes de canais, conforme listado anteriormente, inclui alguns caracteres que não têm a mesma representação em todas as páginas de código EBCDIC. Portanto, se os canais forem enviados entre regiões, é aconselhável restringir os caracteres usados para nomeá-los 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 LINK pode fazer o seguinte:
- Já criou o canal usando um ou mais comandos PUT CONTAINER CHANNEL ou PUT64 CONTAINER .
- Especifique seu canal atual, por nome.
- Nomeie um canal que não existe atualmente. Um novo canal vazio é criado.
COMMAREA ( área de dados )
Especifica uma área de comunicação que deve ser disponibilizada para o programa chamado. Nesta opção, a área de dados é passada e você deve dar a ela o nome DFHCOMMAREA no programa de recebimento. COMMAREA não é compatível com LINK to Liberty. Consulte Passando dados para outros programas .
DATALENGTH ( data-value )
Especifica um valor binário de meia palavra que é o comprimento de uma área contígua de armazenamento, desde o início da COMMAREA, a ser transmitido ao programa chamado. Para uma solicitação LINK remota, se a quantidade de dados transmitidos em uma COMMAREA for pequena, mas a COMMAREA em si for grande para que o programa vinculado possa retornar os dados solicitados, especifique DATALENGTH no interesse do desempenho.
O valor de DATALENGTH é verificado apenas quando a solicitação LINK é remota ou dinâmica. Não é verificado para links locais estáticos.
DATALENGTH não pode ser usado ao mesmo tempo que INPUTMSG.
INPUTMSG ( área de dados )
Especifica os dados a serem fornecidos ao programa chamado quando ele emite um comando RECEIVE pela primeira vez. Esses dados permanecem disponíveis até a execução de um comando RECEIVE ou RETURN. Um programa chamado pode chamar outro programa e assim por diante, criando uma cadeia de programas vinculados. Se uma cadeia vinculada existir, o CICS fornecerá os dados INPUTMSG para o primeiro comando RECEIVE executado na cadeia. Se o controle retornar ao programa que emitiu o LINK com INPUTMSG antes que os dados INPUTMSG tenham sido aceitos por um comando RECEIVE, o CICS assumirá que um comando RECEIVE foi emitido. Nessa situação, os dados INPUTMSG originais não estão mais disponíveis.
INPUTMSG não pode ser usado ao mesmo tempo que DATALENGTH. INPUTMSG não é compatível com LINK to Liberty.
Para obter mais informações sobre a opção INPUTMSG, consulte 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 (área de comunicação). Este valor não deve exceder 24 KB se a COMMAREA for passada entre quaisquer dois servidores CICS (para qualquer combinação de produto, versão e liberação). Este limite permite a COMMAREA e espaço para cabeçalhos.
Certifique-se de que o valor especificado corresponda ao comprimento dos dados que estão sendo transmitidos na COMMAREA. Não especifique 0 (zero) para LENGTH, porque o comportamento resultante é imprevisível e o comando EXEC CICS LINK pode falhar.
Quando você usa uma COMMAREA para transmitir dados, o programa ao qual está vinculado deve verificar se o campo EIBCALEN no EIB da tarefa corresponde ao que o programa espera. Discrepâncias podem resultar em violações de armazenamento ou falhas do sistema. Para obter mais informações, consulte COMMAREA .
PROGRAM ( nome )
Especifica o identificador (1 - 8 caracteres) do programa para o qual o controle deve ser passado incondicionalmente.
Em qualquer um dos casos a seguir, o programa vinculado é um programa servidor em uma região remota:
- A opção SYSID especifica uma região remota.
- A opção REMOTESYSTEM na definição de PROGRAM instalada especifica o nome de uma região remota.
- A definição do programa instalado especifica DYNAMIC (YES), ou não há definição do programa instalado, e o programa de roteamento dinâmico roteia o pedido de link para uma região remota.
Observe o uso de aspas:
EXEC CICS LINK PROGRAM('PROGX')
PROGX está entre aspas porque é o nome do programa.
EXEC CICS LINK PROGRAM(DAREA)
DAREA não está entre aspas porque é o nome de uma área de dados que contém o nome real do programa. Se uma área de dados for usada para conter o nome do programa, essa área de dados deve ser definida como um campo de 8 bytes no armazenamento de trabalho.
Nota: Quando um link é feito para um programa CICS 3270 que deve ser executado no mecanismo de ponte Link3270, o nome do PROGRAMA deve ser DFHL3270, não o nome do programa 3270 de destino.
SYNCONRETURN
Especifica que a região do servidor nomeada na opção SYSID deve obter um ponto de sincronização na conclusão bem-sucedida do programa do servidor.
As alterações nos recursos recuperáveis feitas pelo programa do servidor são confirmadas ou revertidas independentemente das alterações nos recursos recuperáveis feitas pelo programa cliente que emite o pedido LINK ou alterações feitas pelo servidor em qualquer LINK subsequente.
A condição NORMAL é retornada se as alterações nos recursos recuperáveis forem confirmadas antes do retorno do programa do servidor.
A condição ROLLEDBACK será retornada se as alterações nos recursos recuperáveis forem revertidas antes do retorno do programa do servidor.
A condição TERMERR é levantada após a falha do link de comunicação ou do sistema no qual o programa do servidor está sendo executado. O programa cliente lida com a condição e garante que a consistência dos dados seja restaurada.
SYNCONRETURN só é aplicável a links remotos, mas será ignorado se o link for local.
SYSID ( nome do sistema )
Especifica o nome do sistema de uma região do servidor CICS para onde a solicitação de link do programa deve ser roteada.
Se você não especificar um nome de sistema remoto na opção SYSID ou omitir a opção SYSID, o CICS usará o atributo REMOTESYSTEM definido na definição de PROGRAM instalada. Se você especificar um nome de sistema local na opção SYSID ou no atributo REMOTESYSTEM, o CICS ignora o nome.
Um nome de sistema remoto especificado na opção SYSID tem prioridade sobre qualquer nome de sistema remoto especificado na definição de recurso PROGRAM ou retornado pelo programa de roteamento dinâmico.
TRANSID ( nome )
Especifica o nome da transação de espelho que a região remota deve conectar e na qual deve executar o programa do servidor.
O nome da transação que você especifica no comando LINK tem prioridade sobre qualquer transação especificada na definição de recurso do programa. Embora você possa especificar seu próprio nome para a transação de espelho iniciada por solicitações DPL, a transação deve ser definida na região do servidor e a definição da transação deve especificar o programa de espelho, DFHMIRS.
Se você omitir a opção TRANSID, será feita referência às definições de recurso PROGRAM mantidas localmente se a definição PROGRAM instalada especificar o atributo remoto DYNAMIC (YES). Caso contrário, a região do servidor conecta CSMI, CPMI ou CVMI por padrão.
Especificar a opção TRANSID com um nome de transação em branco não é válido. A resposta de erro neste caso depende de como a solicitação de link é tratada:
- Se o programa vinculado for definido localmente, a solicitação de link será bem-sucedida nessa situação.
- Se a solicitação for roteada estaticamente para uma região remota, uma resposta INVREQ será retornada ao programa que iniciou o link.
- Se a solicitação for roteada dinamicamente para uma região remota, um ID de conexão válido é retornado, mas após verificar o TRANSID, o CICS chama o programa de roteamento dinâmico novamente com o parâmetro DYRFUNC definido como 1 e o parâmetro DYRERROR definido como 8. Se o roteamento dinâmico programa responde executando o programa localmente, a solicitação de link é bem-sucedida. Se o programa de roteamento dinâmico responder tentando novamente sem sucesso, a solicitação do link será rejeitada e uma resposta PGMIDERR será retornada ao programa que iniciou o link.
Exemplos:
O exemplo a seguir mostra como solicitar um link para um programa aplicativo chamado PROGNAME:
EXEC CICS LINK PROGRAM(PROGNAME)
COMMAREA(COMA) LENGTH(LENA)
DATALENGTH(LENI) SYSID('CONX')