GTDA Read from TLS

The GTDA (get data) call enables you to read a TLS block (terminal specific long-term storage) into the specified message area. The block name is assigned during generation (TLS statement for KDCDEF).

A program unit of a dialog service can only read blocks from its "own" TLS, i.e. only the TLS of the LTERM/LPAP/OSI LPAP partner, via which the service was started.

A program unit run of an asynchronous service can read blocks from all the  LTERM/LPAP/OSI-LPAP/Master-LPAP partners of a UTM application.

Setting the KDCS parameter area (1st parameter)

The table below shows the necessary entries in the KDCS parameter area.

Function of the call	Entries in the KDCS parameter area
	KCOP	KCLA	KCRN	KCLT
Read from TLS (in dialog program)	"GTDA"	Length	Block name	——
Read from TLS (in asynchronous program)	"GTDA"	Length	Block name	LTERM / LPAP / OSI-LPAP / Master-LPAP name

Setting the 2nd parameter

Here you have to supply the address of the message area into which openUTM is to read the message.

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"GTDA"
KCLA	Length in bytes
KCRN	Block name
KCLT	LTERM / LPAP / OSI-LPAP / Master-LPAP / -

KDCS call
1st parameter	2nd parameter
KDCS parameter area	Message area

C/C++ macro call
Macro names	Parameters
KDCS_GTDA	(nb,kcla,kcrn,kclt)

openUTM return information
Message area	Contents
	Data
Field name in the KB return area
KCRLM	Actual block length
KCRCCC	Return code
KCRCDC	Internal return code

For the GTDA call you make the following entries in the KDCS parameter area:

KCOP

In the KCOP field, the GTDA operation code.

KCLA

In the KCLA field, the length of the data to be transferred from the TLS.

KCRN

In the KCRN field, the name of the TLS block from which openUTM is to transfer data.

KCLT

For asynchronous programs only:
in the KCLT field, the name of  LTERM/LPAP/OSI-LPAP/Master-LPAP partner whose TLS is to be read from (this field is not evaluated by dialog programs).

You enter the following for the KDCS call:

1st parameter

The address of the KDCS parameter area

2nd parameter

The address of the message area to which openUTM is to read the message. You enter the address of the message area even if you have entered the length 0 in KCLM.

Macro names

The use of C/C++ calls is described in detail in the section "C/C++ macro interface".

openUTM returns:

Message area

The desired data in the specified message area.

KCRLM

In the KCRLM field, the actual length of the data in the TLS so that the program can detect deviations from the KCLA entry (important if KCLA entry is smaller). Exception: for KCLA = 0 you always have 0 returned in KCRLM.

KCRCCC

In the KCRCCC field, the KDCS return code, see next page.

KCRCDC

In the KCRCDC field, the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).

KDCS return codes in the KCRCCC field for the GTDA call

The following codes can be analyzed in the program:

000	Operation carried out.
40Z	System cannot perform operation (generation error or system error, deadlock, time-out); see KCRCDC.
41Z	Call was issued in the first part of the sign-on service although this is not permitted by the generation.
43Z	Length entry in KCLA invalid (e.g. negative).
44Z	Block name in KCRN unknown or invalid.
46Z	The  LTERM/LPAP/OSI-LPAP/Master-LPAPname in KCLT invalid (with asynchronous programs only).
47Z	Message area missing or cannot be accessed in the specified length.

An additional error code can be found in the dump:

71Z	INIT missing in this program.

Features of the GTDA call

• A GTDA call locks the referenced TLS block against access for all the competing program units. All other TLS block of the referenced LTERM, LPAP or OSI LPAP partner are free
  The TLS block can be explicitly unlocked with the UNLK call.
  The TLS block is also unlocked by the PEND RE/FI/SP/FC/RS/ER/FR and RSET calls.With PEND PA/PR/KP and PGWT KP/PR the lock remains in effect.

  In the section "Action with locked storage areas (TLS, ULS and GSSB)", there is a description of how openUTM reacts when the desired TLS block is locked.

• The TLS block is transferred in its actual length, but no longer than the length specified in KCLA. If the contents of KCLA > 0 for the GTDA call, the actual length of the data in the TLS is returned in the KCRLM field.