KDCLPAP - Administer connections to (OSI-)LPAP partners

KDCLPAP allows you to perform the following actions:

• arrange for connections to be established

• shut down connections

• disable connections or release disabled connections

• define partner applications for which UTM is automatically to establish connections at every application start

• define the number of parallel connections to OSI TP partner applications

• activate replacement connections to OSI TP partner applications - these replacement connections must have been generated with KDCDEF

• change the time for monitoring the idle time modes of sessions and associations

Connections are specified using the name of the LPAP or OSI-LPAP partner to which they are assigned. Replacement connections are identified by the replacement connection name defined in the KDCDEF control statement OSI-CON.

Special issues relating to the establishment and termination of connections

KDCLPAP...,ACT=CON or (CON,number) merely initiates the establishment of a connection. Successful execution of this command does not therefore mean that the connections have in fact been established or that it is possible to establish them (there may be errors in the transport system). You should therefore use KDCINF to check whether a UTM connection can genuinely be established, with the following entry, for example:

KDCINF OSI-LPAP, LIST=(osi-lpapname_1,...osi-lpapname_10) for OSI-LPAP partners

KDCINF CON, LIST=KDCCON for LPAP partners

If you wish to establish a connection to a disabled LPAP or OSI-LPAP partner (STATUS=OFF) you must make two KDCLPAP calls:

1. One KDCLPAP call to re-enable the (OSI-)LPAP partner, e.g.:
   KDCLPAP [OSI-]LPAP=lpapname,STATUS=ON

2. One KDCLPAP call to ensure that the connection is established, e.g.:
   KDCLPAP [OSI-]LPAP=lpapname,ACTION=CON

In conjunction with ACTION=CON and STATUS=ON, KDCLPAP will not be processed.

If you wish to reduce the number of parallel connections to an OSI-LPAP partner, call KDCLPAP with ACTION=(CON,number). To do this, you should enter the number of connections you wish to retain in the number field.

Effect in UTM cluster applications

The effect in UTM cluster applications is described in the sections devoted to the individual operands since some of the changes made with KDCLPAP apply locally to the node whereas others take effect globally in the cluster.

Period of validity of the change

The period of validity of these changes depends on the type of change and is therefore specified in the description of these operands.

---

KDCLPAP    { LPAP ={ lpapname | (lpapname_1,...,lpapname_10) } |
             OSI-LPAP={ osi-lpapname | (osi-lpapname_1,..,osi-lpapname_10) }|  
             OSI-CON = osi-conname } 
           [ ,ACTION={ CON| (CON,number) | DIS | ACON | (ACON,number) |
                       NACON | QUIET } ]  
           [ ,IDLETIME=time_sec ] 
           [ ,STATUS={ ON| OFF } ]

---

For administration using message queuing you must enter KDCLPAPA.

LPAP = (lpapname_1,...,lpapname_10)
		Connections to the partner applications to which the LPAP partners lpapname_1,...,lpapname_10 are assigned are to be administered. For lpapname_1,...,lpapname_10, enter the logical names of partner applications generated by the KDCDEF control statement LPAP for distributed processing by LU6.1. You can enter a maximum of 10 LPAP names for each KDCLPAP call, i.e. you can administer the connections to a maximum of 10 LPAP partners. If you only enter one LPAP name, you do not need to key in the parentheses.
OSI-LPAP = (osi-lpapname_1,...,osi-lpapname_10)
		The connections to the partner applications to which the OSI-LPAP partners osi-lpapname_1,...,osi-lpapname_10 are assigned are to be administered. For osi-lpapname_1,...,osi-lpapname_10 enter the logical names of partner applications generated by the KDCDEF control statement OSI-LPAP for distributed processing via OSI TP. You can enter a maximum of 10 OSI-LPAP names for each KDCLPAP call, i.e. you can administer the connections to a maximum of 10 OSI-LPAP partners. If you only enter one OSI-LPAP name, you do not need to key in the parentheses.  If the specified OSI-LPAP is the master LPAP of an OSI-LPAP bundle, it only makes sense to specify STATUS=ON/OFF.
OSI-CON=osi-conname
		KDCLPAP OSI-CON=osi-conname activates a log connection to an OSI TP partner (OSI-LPAP). The log connection osi-con must have been generated statically with the KDCDEF control statement OSI-CON. For osi-conname is, enter the name generated in OSI-CON.  You can query the names of all log connections generated for an OSI-LPAP partner with KDCINF OSI-LPAP. When you enter the command, no connections are permitted to the OSI-LPAP partner to which the log connection was assigned for generation.  Before UTM activates the log connection, UTM first deactivates the most recent active connection to the OSI-LPAP partner. The log connection remains active until the end of the application run or until the next time a log connection is selected for the same OSI-LPAP, or until the connection is deactivated. Entering other operands has no effect. Assignment to the OSI-LPAP partner takes place implicitly using osi-conname.
ACTION=		ACTION allows you to arrange for connections which were specified in LPAP or OSI-LPAP to be established and shut down. You can define whether or not UTM should automatically establish connections to specified partner applications when the application starts.
	CON	openUTM arranges for connections to be established to the specified partner applications. All parallel connections generated in the KDCDEF control statement OSI-LPAP for OSI TP partners specified in OSI-LPAP are to be established. In UTM cluster applications, the operand applies locally in the node. Successful execution of this command does not mean that the required connections have in fact been established. You can use a KDCINF query to find out whether or not a connection has been established successfully. If a connection is to be established for a disabled LPAP or OSI-LPAP partner, the partner must be re-enabled with its own KDCLPAP call before the connection is established.
	(CON,number)
		An entry for number is only useful for connections to OSI-LPAP partners. For an LU6.1 partner specified in LPAP, (CON,number) acts like CON and the entry for number is ignored. In UTM cluster applications, the operand applies locally in the node. For OSI-LPAP partners, number represents the number of parallel connections to the partner application that are to be established to each of the specified OSI TP partners after the KDCLPAP call. This makes the effect of the call dependent on the entry for number. A distinction must be drawn between the following cases: If number for one of the OSI-LPAP partners specified in OSI-LPAP is greater than the number of parallel connections currently established, openUTM tries to establish the correct number of connections, i.e. the same number of connections to OSI-LPAP partners as specified in number.  The maximum number of parallel connections to one OSI-LPAP partner is defined for KDCDEF generation in the OSI-LPAP statement. If the value for number exceeds the generated maximum number of specified OSI-LPAP partners, openUTM only establishes the generated maximum number of connections for this partner.  Successful execution of this command does not mean that the required connections have been established. You can use a KDCINF query to find out whether or not a connection has been established successfully. If a connection is to be established for a disabled OSI-LPAP partner, the partner must be re-enabled first. If number is less than the number of parallel connections currently established to a OSI-LPAP partner, UTM shuts down connections to the OSI-LPAP partner until only the number of connections specified in number are still in existence.  (CON,0) has the same effect as ACTION=DIS. UTM immediately shuts down all connections for the specified OSI-LPAP partner. Minimum value of number: 0  Maximum value of number: Number of parallel connections generated.
	DIS	Connections to the partners specified in LPAP are shut down immediately.  All existing parallel connections to the partners specified in OSI-LPAP are shut down. In UTM cluster applications, the operand applies locally in the node. Termination of a connection with DIS has the effect of shutting down all connections immediately. This may cause services to be terminated abnormally. It would be better to use ACTION=QUIET.
	ACON	(automatic connection)  For the next start and for subsequent starts of this application, UTM is automatically to establish connections to the partner applications specified in LPAP or OSI-LPAP. In the case of OSI TP partners, parallel connections should be established up to the number specified in the appropriate OSI-LPAP statement during KDCDEF generation. In UTM cluster applications, the operand applies globally in the cluster.
	(ACON,number)
		Entering number is only meaningful for connections to OSI-LPAP partners.  In all subsequent starts of the application, UTM should establish connections to the partners specified in OSI-LPAP automatically (automatic connection). The value for number defines the number of parallel connections that are to be established to the specified OSI TP partners. In UTM cluster applications, the operand applies globally in the cluster. The maximum number of parallel connections to a partner is defined in the OSI-LPAP statement for KDCDEF generation.  If the value in number exceeds the generated maximum number for one of the specified OSI-LPAP partners, UTM only establishes the statically generated number of connections for this partner. For an LU6.1 partner specified in LPAP, (ACON,number) has the same effect as ACON; the entry for number is ignored. Minimum value of number: 0  Maximum value of number: Number of generated parallel connections.
	NACON	(no automatic connection)  If the ACON property is entered for these connections during generation or by means of system administration functions, it is to be deleted, i.e. openUTM should no longer establish automatic connections to the partner applications specified in LPAP or OSI-LPAP with effect from the next application start.  The entry ACTION=NACON extends beyond the duration of the current application run. In UTM cluster applications, the operand applies globally in the cluster.
	QUIET	The connections specified in LPAP or OSI-LPAP are shut down. For OSI-LPAP partners, all parallel connections are shut down. In UTM cluster applications, the operand applies locally in the node. With QUIET, connections are not shut down until the sessions or associations generated for the specified LPAP- or OSI-LPAP partners are no longer assigned by dialog or asynchronous jobs. However, no further dialog jobs are accepted for the specified (OSI-)LPAP partners.  The QUIET property can be reset with ACTION=CON.
IDLETIME=time_sec
		Time for monitoring the idle state of the sessions or associations generated for the specified LPAP or OSI-LPAP partners. In UTM cluster applications, the operand applies globally in the cluster. A change made to IDLETIME remains effective for a defined session or association if it reaches the idle mode next time this command is entered (during establishment of the connection or after completion of the job).  If the session or association is not assigned by a job during the period of time specified in time_sec, openUTM shuts down the connection. time_sec is defined in seconds. IDLETIME=0 prevents monitoring of the idle state. Maximum value: 32767  Minimum value: 60  In the case of values that arre smaller than 60 but not equal to 0, the value 60 is used.
STATUS=		Disables or re-enables LPAP or OSI-LPAP partners. In UTM cluster applications, the operand applies globally in the cluster.
	OFF	Disables LPAP or OSI-LPAP partners; openUTM does not establish any further connections to this partner application until the LPAP or OSI-LPAP partner is released once again. No logical connections to the related partner application can be established when an LPAP or OSI-LPAP partner is disabled.
	ON	Approve LPAP or OSI-LPAP partner again.  This change applies throughout the entire application run.

Output from KDCLPAP

New and old properties are output at the administrator terminal (NEW, OLD).

The following output is produced when KDCLPAP LPAP=... is entered:

LPAP        STATUS       CONNECTION          IDLETIME
            NEW  OLD    NEW       OLD        NEW    OLD
lpapname    ON   ON     CON  A Q  CON  A Q   sec    sec
            OFF  OFF    DIS       DIS
                             W         W

The following output is produced when KDCLPAP OSI-LPAP=... is entered:

OSI-LPAP      STATUS          CONNECTED          IDLETIME       AUTOCON
           NEW      OLD      NEW      OLD       NEW    OLD    NEW     OLD
osi-lpap   ON  Q    ON  Q    number   number    sec    sec    number  number
           OFF      OFF

The following output is produced when KDCLPAP OSI-CON=... is entered:

OSI-LPAP      OSI-CON
            NEW     OLD
osi-lpap1  osi-con1 osi-con2

Explanation of the output

AUTOCON	Number of connections to the OSI-LPAP partner that UTM should establish automatically when an application starts.
CONNECTED	Number of parallel connections currently established to the OSI-LPAP partner.
CONNECTION	1st column:  Connection to the LPAP partner is established (CON), shut down (DIS), or UTM is currently trying to establish a connection (W = waiting for connection). 2nd column:  A (automatic) indicates that openUTM will try to establish the connection automatically when the application starts.  Q (quiet) indicates that the connection will be shut down and that no further dialog jobs will be accepted for this partner application.
IDLETIME	Monitoring time for the idle state of a session or association on the connection
OSI-CON	The name generated with the KDCDEF control statement OSI-CON for the logical connection to the partner application.  osi-con1 is the name of the connection that was active before the changeover; osi-con2 is the name of the existing replacement connection.
STATUS	A connection to the partner application exists or can be established (ON), or cannot be established (OFF).  Q (QUIET) indicates that no further dialog jobs will be accepted for the OSI-LPAP partner and that the connection will be shut down.