kc_osi_lpap_str - Properties of OSI TP partner applications

The data structure kc_osi_lpap_str is defined for the object type KC_OSI_LPAP. In the case of KC_GET_OBJECT, UTM returns the following in kc_osi_lpap_str:

• The logical properties of an OSI TP partner application.
  The logical properties of an OSI TP partner application are defined in the KDCDEF generation in which an OSI-LPAP partner is created and assigned to this partner application.

• The status of the connection to the partner application.

• Statistical information on the connection load.

mod 1	Data structure kc_osi_lpap_str
-	char ol_name[8];
-	char application_context[8];
-	char application_entity_qualifier[8];
-	char application_process_title[10][8];
-	char association_names[8];
-	char associations[5];
x(GPD)	char auto_connect_number[5];
-	char contwin[5];
-	char kset[8];
x(GPD)	char idletime_sec[5];
x(GPD)	char state;
-	char permit;
-	char qlev[5];
-	char termn[2];
x(A)	char connect_number[5];
x(IR)	char quiet_connect;
-	char osi_con[8];
-	char out_queue[5];
-	char ass_kset[8];
-	char nbr_dputs[10];
-	char master[8];
-	char bundle;
-	char out_queue_ex[10];
x(GPD)	char dead_letter_q;

¹  The contents of the field can be modified with KC_MODIFY_OBJECT; see "obj_type=KC_OSI_LPAP"

The fields in the data structure have the following meanings:

ol_name

Contains the name of the OSI-LPAP partner of the partner application. The partner application will be addressed by the program units of the local application using this name. The name consists of a maximum of 8 alphanumeric characters.

application_context

Specifies which application context from the partner application will be used. For details on application context, please refer to the openUTM manual “Generating Applications”, KDCDEF statement APLLICATION-CONTEXT.

application_entity_qualifier

Contains the application entity qualifier of the partner application. The application entity qualifier is used together with the application process title for addressing a partner application for a heterogeneous link. The application entity qualifier is a positive integer between 1 and 67108863 (= 2²⁶-1).

You will find more information on the application entity qualifier in the openUTM manual “Generating Applications”.

application_entity_qualifier='0' means that no AEQ is defined for the partner application.

application_process_title

Contains the application process title (APT) of the partner application. The APT is used together with the application entity qualifier for addressing a partner application for a heterogeneous link.

An APT consists of at least two, but at most ten components. The individual components are positive integers.

The position of the individual components as well as their number is relevant in an application process title. For example, (1,2,3), (1,2,3,0,0) and (0,1,2,3,0) indicate different application process titles.

You will find more information on the application process title in the openUTM manual “Generating Applications”.

UTM returns one field element per component of the APT, i.e. the number of field elements containing data in application_process_title corresponds to the number of components generated. The remaining field elements contain binary zero.

If no APT was generated for the partner application, then all field elements of application_process_title contain binary zero.

association_names

Contains the prefix of the names that are assigned to the logical connections (associations) to the partner application within the local application.

The name of the connection is composed of the value of association_names as its prefix and a sequential number. The sequential number lies between 1 and the number of parallel connections (associations field) generated. The entire name for a connection can be up to 8 characters long. The maximum length of association_names depends, therefore, on the number of parallel connections in associations.

Example
association_names ='ASSOC' and associations = '10', then the connections to the partner application that are assigned to the OSI-LPAP partner have the following names: ASSOC01, ASSOC02, ..., ASSOC10.

associations

Contains the maximum number of parallel connections to the partner application. The maximum possible number of parallel connections to a partner application depends on the transport system used and on the size of the name space of the UTM application (see the openUTM manual “Generating Applications”).

auto_connect_number

Contains the number of connections to the partner application that will be automatically established at start of the local application as long as the partner application is available at this point in time. The establishing of a connection at the start of the application can be requested by the local application as well as by the partner application. In this manner, you can ensure that the connection is automatically established as soon as both partners are available.

auto_connect_number = '0' means that the connection is not set up automatically.

Minimum value: '0'
Maximum value: maximum number of parallel connections (associations)

contwin

Contains the number of connections for which the local application is the contention winner. For the rest of the connections (difference: associations - contwin ), the local application is the contention loser.

The contention winner takes over the administration of the association. Jobs can be started, however, by the contention winner as well as by the contention loser. In case of a conflict, such as when both communication partners want to start a job at the same time, the association from the job of the contention winner will be used.

kset

Contains the name of the key set with the maximum access privileges of the OSI TP partner application in the local application.

If the OSI TP partner passed a user ID when an association is established, the key set in kset becomes effective. The access privileges of the association correspond to the key codes contained both in kset and in the key set of the user ID.

If the OSI TP partner application for the association does not pass a user ID to openUTM the access privileges for the association form the subset of the key codes in kset and ass_kset (minimum access privileges).

If the partner application is not assigned a key set, then kset contains blanks.

idletime_sec

Contains the maximum time in seconds that an association to the partner application may be in the idle state before UTM closes the connection to the partner application. The idle state means that the session is not handling any jobs.
idletime_sec = '0' means that the idle state will not be monitored. The connection remains established until an explicit request to close the connection is sent.

Minimum value: '60'
Maximum value: '32767'

state

Specifies if the OSI-LPAP partner is currently disabled.

'Y'	The OSI-LPAP partner is not disabled. Connections between the partner application and the local application can be established or connections already exist.
'N'	The OSI-LPAP partner is disabled. No connections between the partner application and the local application can be established.

permit Specifies which privileges the partner application has within the local application.

'A'	(ADMIN) The partner application has administration privileges. It may execute all administration functions in the local application.
'N'	(NONE) The partner application does not have any administration privileges. Only on BS2000 systems: If the local application is a UTM application on a BS2000 system, then the partner application is also not allowed to execute any UTM SAT administration functions.
'B'	(BOTH, only on BS2000 systems) The partner application may execute administration functions and UTM SAT administration functions in the local application.
'S'	(SAT, only on BS2000 systems) The partner application only has UTM SAT administration privileges. It may execute preselection functions in the local application, i.e. it can enable or disable the SAT logging for certain events.

qlev ( queue level)

qlev specifies the maximum number of asynchronous messages allowed in the message queue of the OSI-LPAP partner. If this control value is exceeded, then any additional asynchronous jobs sent to this OSI-LPAP partner will be rejected (i.e. '40Z' will be returned for any APRO-AM calls thereafter).

termn

Contains the code for the type of communication partner. The code is entered in the communication area header of the job-receiving service that was started in the local application by the partner application. The code is defined by the user and serves to divide the communication partners into groups of a certain type. It is not evaluated by UTM. The code is a maximum of 2 characters long.

connect_number

Contains the number of parallel connections to the partner application that are currently established or that are currently to be established.

connect_number = '0' means that no connection to the partner application currently exists or all existing connections are to be disconnected.

Minimum value: '0'
Maximum value: the number in associations

quiet_connect

Specifies if the QUIET property is set or is to be set for the partner application. QUIET means that UTM closes all connections to the partner application as soon as they are not being used for dialog jobs or asynchronous jobs. No more new dialog jobs are accepted for the partner application.

'Y'	The QUIET property is set for the partner application.
'N'	The QUIET property is not set.

osi_con

Contains the name of the transport connection via which communication with the partner application will occur, i.e. all connections (associations) with the partner application are handled via this transport connection. The name is assigned to the transport connection in the KDCDEF generation (OSI-CON statement assigned to the OSI-LPAP partner). osi_con indicates the transport connection that is currently set to active, i.e. that is not deactivated as a substitute connection (see the openUTM manual “Generating Applications”).

out_queue

The number of messages in the message queue of the OSI-LPAP partners that still have to be sent to the partner application.

If this number of messages is greater than 99999, then the number is not displayed in full. You should therefore use the field out_queue_ex since larger numbers can be entered in full here.

ass_kset

Only applies if the application is generated with user IDs.
ass_kset contains the name of the key set specifying the minimum access privileges of the OSI TP partner which the partner application can use in the local application.

The key set specifies in ass_kset becomes effective when the partner application does not pass a user ID to openUTM while an association is established (see also kset). ass_kset describes the access privileges of the association user.

Default: no key set, i.e. the access privileges in kset always apply.

nbr_dputs

The number of pending time-driven jobs for this OSI-LPAP whose starting time has not yet been reached.

master

Associated OSI-LPAP if the OSI-LPAP is a slave OSI-LPAP in an OSI-LPAP bundle.

bundle

Specifies whether the OSI-LPAP belongs to an OSI-LPAP bundle.

'N'	The OSI-LPAP does not belong to an OSI-LPAP bundle.
'M'	The OSI-LPAP is the master OSI-LPAP in an OSI-LPAP bundle. In this event, the following applies: Only the state field can be modified with KC_MODIFY_OBJECT. Only the ol_name, application_context, state and bundle fields are relevant withKC_GET_OBJECT.
'S'	The OSI-LPAP is the slave OSI-LPAP in an OSI-LPAP bundle.

out_queue_ex

See out_queue.

dead_letter_q

specifies whether an asynchronous message to an OSI-LPAP partner is saved in the dead letter queue if it could not be sent because of a permanent error.

'Y'	Asynchronous messages to this OSI-LPAP partner which could not be sent because of a permanent error are saved in the dead letter queue, as long as (in case of message complexes) no negative confirmation job was defined.
'N'	Asynchronous messages to this OSI-LPAP partner which could not be sent because of a permanent error are not saved in the dead letter queue but deleted.