Menu principal                 [Fechar]
Introdução
Divisões
Identification Division
Environment Division
Data Division
Procedure Division
Comandos CICS
VSAM - File Status
Quadros importantes
SQL - Structured Query Language
Outros programas
Rotinas prontas
Palavras reservadas
Introdução ao Oracle
Sites de busca
Sites interessantes
Meu e-mail

CICS Manual do Usuário - LINK


Volta a página anterior

Volta ao Menu Principal


Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF. - cad_cobol@hotmail.com

LINK

Links to another program expecting return.

Sintax:

Notas:

  1. LENGTH is required in C or C++ programs when COMMAREA is used.

  2. If the program is defined as running remotely, SYNCONRETURN, TRANSID and DATALENGTH can be specified without SYSID.

Descrição:

LINK passes control from an application program that is at one logical level to an application program that is at the next lower logical level. The linked-to program can be on a local or a remote system. If the program is local, CICS loads it.

A remote program can be defined as such in its Program Definitions (PD) entry, or by using the SYSID option on the LINK command. For a remote program, CICS ships the link request to the remote region. This is referred to as a Distributed Program Link (DPL).

Some restrictions apply on remote linked-to programs; for details, see the TXSeries for Multiplatforms Intercommunication Guide. The SYSID and INPUTMSG options are mutually exclusive.

When the RETURN command is executed in the linked-to program, control is returned to the program that is initiating the linkage at the next sequential executable instruction.

The following example shows how to request a link to an application program called PROG1: 

 
     EXEC CICS 
          LINK PROGRAM('PROG1')
     END-EXEC

The linked-to program operates independently of the program that issues the LINK command with regard to handling conditions, attention identifiers, and abends.

For COBOL programs, for example, the effects of HANDLE CONDITION commands in the linking program are not inherited by the linked-to program, but the original HANDLE CONDITION commands are restored on return to the linking program.

See the TXSeries for Multiplatforms Application Programming Guide for more information and an illustration of the concept of logical levels.

You can use the HANDLE ABEND command to deal with abnormal terminations in other link levels.
See the TXSeries for Multiplatforms Application Programming Guide for further details about the relationship between LINK and HANDLE ABEND.

Opção:

    COMMAREA(data-area)
  • Specifies a communication area that is to be made available to the invoked program.
  • In this option, a pointer to the data area is passed.
  • In a COBOL receiving program, you must give this data area the name DFHCOMMAREA.
  • See the TXSeries for Multiplatforms Application Programming Guide.
    DATALENGTH(data-value)
  • Specifies a 16-bit binary value that is the length of a contiguous area of storage, from the start of the COMMAREA, that is to be passed to the invoked program.
  • If the amount of data that is being passed in a COMMAREA is small, but the COMMAREA itself is large so that the linked-to program can return the requested data, you should specify DATALENGTH in the interest of performance.
  • When DATALENGTH=0 and a COMMAREA is to be returned where the length is greater than 0, the COMMAREA is all nulls on return from the link, under the following conditions:
    1. If the linked-to program does not write any data into the COMMAREA (or writes nulls)
    2. If the link fails because of a communication error, such as TERMERR
    LENGTH(data-value)
  • Specifies, as a 16-bit binary value, the length, in bytes, of the communication area.
  • If a negative value is supplied, zero is assumed.
  • LENGTH is required in C or C++ programs when COMMAREA is used.
  • See LENGTH for more information about using this option.
    INPUTMSG(data-area)
  • Specifies data that is to be supplied to the invoked program when it first issues a RECEIVE command.
  • This data remains available until the execution of a RECEIVE or RETURN command.
  • An invoked program can invoke another program and so on, creating a chain of linked programs.
  • If a linked-to chain exists, CICS supplies the INPUTMSG data to the first RECEIVE command that is executed in the chain.
  • If control returns to the program that issued the LINK with INPUTMSG before the INPUTMSG data has been accepted by a RECEIVE command, CICS assumes that a RECEIVE command has been issued.
  • This means that the original INPUTMSG data is no longer available.
  • INPUTMSG cannot be used at the same time as DATALENGTH.
  • See the TXSeries for Multiplatforms Application Programming Guide for more information about the INPUTMSG option.
    INPUTMSGLEN(data-value)
  • Specifies a halfword binary value that is to be used with INPUTMSG.
    PROGRAM(name)
  • Specifies the name of the program to which control is to be passed unconditionally and from which return is expected.
  • The name can consist of up to eight alphanumeric characters, and must have an entry in the PD (unless the SYSID option specifies a remote SYSID).
  • When developing COBOL applications that EXEC LINK each other, it is an error to have the PROGRAM-ID clause declare the program name to be the same in each case.
  • If a remote SYSID is specified on the SYSID option, the program is assumed to reside on a remote system irrespective of whether the name exists in the local PD. Otherwise, the PD is used to determine whether the program is on a local or a remote system.
    SYNCONRETURN
  • Specifies that the remote region that is requested by the SYSID option is to take a syncpoint on successful completion of the linked-to program.
  • If SYNCONRETURN is omitted, the default synchronization level is the same as that of the connection.
    SYSID(name)
  • Specifies on which CICS region the LINK is to run. The SYSID name has one through four characters.
  • For a full description of the SYSID option, refer to SYSID.
  • If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the PD entry for the program that is requested in the PROGRAM option.
    TRANSID(data-value)
  • Specifies the name of the mirror transaction that the remote region is to attach, and under which it is to run the linked-to program.
  • If TRANSID is omitted, the remote region attaches either CSMI, CPMI, or CVMI by default.
  • The transaction name that you specify on the LINK command takes priority over any transaction that is specified on the Program Definitions (PD).
  • Although you can specify your own name for the mirror transaction that is initiated by DPL requests, the transaction must be defined in the remote region, and this transaction definition must specify the mirror program, DFHMIRS.

Condições:

    INVREQ
  • Occurs for the following conditions, depending on the options that are specified on the LINK command:
    • The SYNCONRETURN option is specified, but the program that is issuing the link request is already in conversation with a mirror task (that is, a logical unit-of-work is in progress) in the remote region that is specified on the SYSID option.
    • In this case, the linked-to program is in an incorrect state to support the SYNCONRETURN option.
    • The program that is issuing the link request is already in conversation with a mirror task and the TRANSID taht is specified is different from the transaction identifier of the active mirror.
    • The TRANSID specified is all blanks.
    • A LINK command with the INPUTMSG option is issued for a program that is the subject of a DPL request; that is, SYSID is also specified.
  • Ação pré-definida: Terminates the task abnormally.
    LENGERR
  • The length that is specified on the DATALENGTH option is a negative length.
  • The length that is specified on the DATALENGTH option is greater than the length that is specified on the LENGTH option.
    NOTAUTH
  • Occurs for the following conditions:
    • When a resource security check is unsuccessful on PROGRAM(name)
    • When SYSID is specified by a transaction that is defined with the RSLCheck attribute set to either internal or external
  • Ação pré-definida: Terminates the task abnormally
    PGMIDERR
  • Occurs for the following conditions:
    • The program has no entry in the Program Definitions (PD).
    • The program is disabled.
    • The program could not be loaded because:
      • This was the first load of the program and the program load failed.
      • This is usually because the load module could not be found.
      • This was a subsequent load of the program, but the first load failed.
  • Ação pré-definida: Terminates the task abnormally.
    ROLLEDBACK
  • Occurs if the SYNCONRETURN option is specified and the server program cannot successfully take a syncpoint.
  • The server program has taken a rollback and all changes that were made to recoverable resources in the remote region within the current LUW are backed out.
    SYSIDERR
  • Occurs a problem with the communications configuration prevents the LINK from proceeding. For example:
    • The connection that is named in the SYSID option is not the name of a Communications Definition (CD) entry
    • The SYSID option references a CD entry that is incorrectly configured
    • The SYSID option references a CD entry that is marked as out of service
  • It can also occur if the connection to the remote system is closed.
  • This could be because the remote system is not available.
  • Ação pré-definida: Terminates the task abnormally.
    TERMERR
  • Occurs if an unrecoverable error occurs during conversation with the mirror (for example the session fails, or the server region fails), or a transaction definition that is specified by the TRANSID option does not exist at the region that is specified by the SYSID option.

Informações relacionadas:

© Copyright IBM Corp.