The different variants of the INFO (information) call enable you to obtain the following information:
INFO CD (Card), only on BS2000 systems
the information stored on the user’s ID card (only if terminal users have to prove their authorization via card reader during sign on) or Kerberos information.INFO DT (Date/Time)
date and time of the start of the application and program unitINFO SI (System Information)
system information (e.g. the name of the application and the host)INFO PC (Predecessor Conversation)
information on a stacked serviceINFO LO (LOcale Information)
information on the language environment of the LTERM partnerINFO CK (ChecK)
the KCRCCC return code, normally returned by an MPUT, FPUT or PEND call.
These variants of the INFO call differ in the meaning of the 2nd parameters (message area) to be specified in the INFO call.
openUTM provides language specific data structures to structure the message area: for COBOL in the COPY element KCINFC, for C/C++ in the kcinf.h. include file.
Setting the KDCS parameter area (1st parameter) and the 2nd parameter
The table below shows the five types of INFO call and the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCSparameter area | Meaning of the 2nd parameter | |||
|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCLT | ||
BS2000 systems: | "INFO" | "CD" | Length | — | Area for ID card or Kerberos information |
Obtain date and time of application and program starts | "INFO" | "DT" | 30 | — | Area for date and time, see data structure for INFO DT. |
Information about language environment of LTERM partner | "INFO" | "LO" | 68 | LTERM name | Area for requested name, see data structure for INFO LO. |
Information on a stacked service | "INFO" | "PC" | 39 | — | Area for requested names, see data structure for INFO PC. |
Obtain system information | "INFO" | "SI" | 180 | — | Area for requested names, see data structure for INFO SI |
Check UTM call | "INFO" | "CK" | — | — | Parameter area, to be checked |
Due to the different meanings of the 2nd parameter, the INFO call is presented here in two formats:
Format 1: INFO CD/DT/LO/PC/SI (see next page).
Format 2: INFO CK (see "INFO CK call").
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"INFO" | |
"CD"/"DT"/"LO"/"PC"/"SI" | |
Length of message area in bytes | |
Name of LTERM partner / — | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_INFOCD/KDCS_INFODT/KDCS_INFOSI/KDCS_INFOPC | (nb,kcla) |
KDCS_INFOLO | (nb,kcla,kclt) |
openUTM return information | |
|---|---|
Contents | |
Data | |
Field name in the KB return area | |
Actual block length | |
Return code | |
Internal return code | |
For the INFO call you make the following entries in the KDCS parameter area to read the ID card information, obtain date and time, obtain system information and obtain information on the predecessor or on the language environment of the LTERM partner:
KCOP
In the KCOP field, enter the INFO operation code
KCOM
In the KCOM field, enter the desired function of the call:
CD to read ID card or Kerberos information (CARD), only on BS2000 systems
DT to obtain time and date of the start of the application and program unit (DATE/TIME)
LO to obtain information on the language environment of the LTERM partner
PC to obtain information on the predecessor in the stack
SI to obtain system information
KCLA
In the KCLA field, the length of the message area used in which openUTM is to store the information. You have to specify the length in bytes. openUTM transfers the information up to a maximum length of KCLA.
Only with INFO LO:
KCLT
in the KCLT field, enter the name of the LTERM partner whose language environment is to be obtained.
If KCLT is set to binary zero before the call, openUTM transfers the data of the LTERM partner via which the service is to be started.
Only on BS2000 systems:
If the LTERM partner belonging to the program unit run is specified in KCLT, openUTM transfers additional information about the associated physical terminal (PTERM).
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area
2nd parameter:
The address of the message area into which openUTM is to write the information. openUTM transfers the requested information in a fixed structure. For this, language specific data structures are available: for COBOL in the KCINFC COPY element, for C/C++ in kcinf.h. include file.
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 transferred.
With KCRCCC >= 40Z the length is 0.
Only on BS2000 systems:
With INFO CD, KCRLM specifies the length of the Kerberos information transferred to the receiving area.
KCRCCC
In the KCRCCC field, the KDCS return code. 0
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 INFO CD/DT/LO/PC/SI calls
The following codes can be analyzed in the program:
000 | The requested information was transferred to the message area in its full length. |
01Z | Information was transferred. However, the message area is too short and the information was truncated. |
09Z | only on BS2000 systems: |
40Z | Generation error or system error. See KCRCDC. |
41Z | INFO call with KCOM = CD/PC not permitted in asynchronous program. |
42Z | KCOM invalid. |
43Z | KCLA invalid. |
46Z | Only with INFO LO: |
47Z | Message area missing or cannot be accessed in the specified length |
49Z | Only with INFO LO: |
An additional error code can be found in the dump:
71Z | INIT not yet issued in this program unit |
Features of the INFO CD call (BS2000 systems)
With this function the INFO call reads the ID card information stored during sign-on to the specified message area if the user used a magnetic strip card for authentication during sign on. For more information see also section "Support for ID card readers on BS2000 systems".
The stored Kerberos information (= Kerberos Principal name) can be read if either the user was signed on by means of Kerberos, or a Kerberos dialog has been executed for the client and afterwards no further user signed on using a magnetic strip card.
The INFO CD call for reading ID card information or Kerberos information is permitted in dialog programs only.
In order to be able to call the ID card information in the program, you have to set the following operands during generation:
the CARD= operand must be specified for the current user ID in the KDCDEF control statement USER, and
the CARDLTH= operand in the KDCDEF control statement MAX.
Features of the INFO DT call
With this function the INFO call writes the start times of the application and program unit to the specified area, using a length of 30 bytes. The information is structured as follows:
Field name | Field name | Byte | Meaning of the information |
|---|---|---|---|
KCDATAS | — | 1 - 6 | Date of application startup in the form ddmmyy, where: |
KCTAGAS | as_day | 1 - 2 | dd - day (value range 01 - 31) |
KCMONAS | as_mon | 3 - 4 | mm - month (value range 01 - 12) |
KCJHRAS | as_year | 5 - 6 | yy - year (value range 00 - 99) |
KCTJHAS | as_doy | 7 - 9 | Day of application startup |
KCUHRAS | — | 10 - 15 | Time of application startup in the form hhmmss, where: |
KCSTDAS | as_hour | 10 - 11 | hh - hour (value range 00 - 23) |
KCMINAS | as_min | 12 - 13 | mm - minute (value range 00 - 59) |
KCSEKAS | as_sec | 14 - 15 | ss - second (value range 00 - 59) |
KCDATAK | — | 16 - 21 | Date of program unit startup in the form ddmmyy, where: |
KCTAGAK | ps_day | 16 - 17 | dd - day (value range 01 - 31) |
KCMONAK | ps_mon | 18 - 19 | mm - month (value range 01 - 12) |
KCJHRAK | ps_year | 20 - 21 | yy - year (value range 00 - 99) |
KCTJHAK | ps_doy | 22 - 24 | Day of application startup |
KCUHRAK | — | 25 - 30 | Time of program unit start in the form hhmmss, where: |
KCSTDAK | ps_hour | 25 - 26 | hh - hour (value range 00 - 23) |
KCMINAK | ps_min | 27 - 28 | mm - minute (value range 00 - 59) |
KCSEKAK | ps_sec | 29 - 30 | ss - second (value range 00 - 59) |
Features of the INFO LO call (BS2000 systems)
Using the INFO LO variant of the INFO call the program unit run can request information about the location of LTERM partners and application. The location of an LTERM partner determines the language environment of the client. The location of the application determines the default setting for the language environment.
The call returns the following data:
the location of the LTERM partner whose name is specified in the KCLT field
the location of the application
If KCLT is set to binary zero before the call, openUTM transfers the data of the LTERM partner via which the service was started.
If the call is executed in a dialog service and the name of the LTERM partner is set in the KCLT field associated with the program unit run, openUTM also provides the following data about the associated physical terminal (PTERM):
number of extended ISO character sets supported by the terminal or printer
ISO variant numbers of all supported character sets
default user character set, allocated to the BS2000 user ID under which the UTM application is running.
With the INFO LO call openUTM displays the data in the message area structured as follows:
Field name | Byte | Meaning of contents |
|---|---|---|
KCLTLANG | 1 - 2 | Language identifier of LTERM partner |
KCLTTERR | 3 - 4 | Territory identifier of LTERM-partner |
KCLTCCSN | 5 - 12 | CCS-name of LTERM-partner |
13 - 20 | Blanks | |
KCAPLANG | 21 - 22 | Language identifier of application |
KCAPTERR | 23 - 24 | Territory identifier of application |
KCAPCCSN | 25 - 32 | CCS-name of application |
33 - 40 | Blanks | |
KCDEFCCS | 41 - 48 | User default character set of BS2000 user ID under which the UTM application runs |
Information about the connected terminal | ||
KCCCSNO | 49 | Number of the extended ISO-character sets supported by the terminal |
KCHSET1 | 50 | Variant number of the first supported ISO character set |
KCHSET2, | 51 - 65 | Variant numbers of other ISO character sets supported by the physical terminal. Length of each field is 1 byte. |
65 - 68 | Blanks | |
Features of the INFO LO call (Unix, Linux and Windows systems)
With the INFO LO variant of the INFO call, the program unit run can request information about the language currently set for the LTERM partner.
This function enables you to run program units in multiple languages. In the program unit run, the language set for an LTERM partner can be queried with INFO LO and messages sent in the same language.
INFO LO returns the following information:
Language and territory identifiers as well as the $LANG variable of the LTERM partner specified in KCLT. The cell outputs the currently set $LANG variable of the user ID under which the associated dialog terminal process was started.
Language and territory identifiers as well as the $LANG variable of the UTM application. The cell outputs the currently set $LANG variable of the user ID under which the associated application was started.
Language and territory identifiers are retrieved from the $LANG variable at program runtime. Example: From $LANG=En_US.ASCII, openUTM creates the language identifier En and the territory identifier US.
The INFO LO call provides data structured as follows:
Field name | Byte | Meaning of the contents |
|---|---|---|
KCLTLANG | 1 - 2 | Language identifier of the LTERM partner |
KCLTTERR | 3 - 4 | Territory identifier of the LTERM partner |
KCLTNLSL | 5 - 20 | $LANG variable of the specified LTERM partner |
KCAPLANG | 21 - 22 | Language identifier of the application |
KCAPTERR | 23 - 24 | Territory identifier of the application |
KCAPNLSL | 25 - 40 | $LANG variable of the application |
41 - 68 | Blanks |
Features of the INFO PC call
With this call you can query information about a stacked service.
If the current service was started by service stacking, the INFO PC call provides, for example, the following information about the preceding service (that is the service that is immediately before the current service in the stack):
date and time of last processing
format identifier of last screen output
the next TAC
the service TAC
openUTM writes this information to the specified area, using a total length of 39 bytes.
Field name | Byte | Meaning of the information |
|---|---|---|
KCPFN | 1 - 8 | Format identifier of the last screen output |
KCPNXTAC | 9 - 16 | Name of the next TAC |
KCPCVTAC | 17 - 24 | Name of the service TAC |
KCPLDATE1 | 25 - 33 | Date of last processing in the form ddmmyy, where: |
KCPLDAY | 25 - 26 | dd - day (value range 01 - 31) |
KCPLMON | 27 - 28 | mm - month (value range 01 - 12) |
KCPLYEAR | 29 - 30 | yy - year (value range 00 - 99) |
KCPLDOY | 31 - 33 | Working day of last processing, value range 001 - 366 |
KCPLTIME1 | 34 - 39 | Time of last processing in the form hhmmss, where: |
KCPLHOUR | 34 - 35 | hh - hour (value range 00 - 23) |
KCPLMIN | 36 - 37 | mm - minute (value range 00 - 59) |
KCPLSEC | 38 - 39 | ss - second (value range 00 - 59 |
1For C/C++ the summary fields KCPLDATE and KCPLTIME are not defined. However, the specific fields for day/month/year/working day/hour/minute/second are defined.
If there is no stacking, openUTM returns blanks.
Features of INFO SI call
With this call, you can query information on the application and system, e.g. the name of the application and the host on which the application is running.
In dialog services INFO SI also provides the PTERM name, host name and application name of the communication partner.
openUTM writes this information to the specified area as follows - byte 17 - 40 are set to binary zero in asynchronous services.
Field name | Byte | Meaning of the information |
|---|---|---|
KCAPPLNM/applnam | 1 - 8 | Name of the UTM application |
KCHOSTNM/hostname | 9 - 16 | BS2000 systems:
|
Unix, Linux and Windows systems:
| ||
KCPTRMNM | 17 - 24 | In a dialog service
In an asynchronous service: Blanks |
KCPRONM | 25 - 32 | In a dialog service
In an asynchronous service: Blanks |
KCBCAPNM | 33 - 40 | In a dialog service
In an asynchronous service: Blanks |
KCVERS | 41 - 46 | openUTM version Vnn.nx (e.g. V07.0A) |
KCIVER | 47 - 48 | Version number of the KDCS interface1 |
KCIVAR | 49 | "B" for BS2000 systems, "X" for Unix and Linux system or "N" for Windows system |
KCFILL1 | 50 | Not currently used |
KCLANG | 51 - 52 | Only on Unix, Linux and Windows systems:
|
KCHSTNML | 53 - 116 | BS2000 systems:
|
Unix, Linux and Windows systems:
| ||
KCPRONML | 117 - 180 | In a dialog service
In an asynchronous service: Blanks |
1 The version number indicates the version of function extensions available, irrespective of the product variant. In this way, UTM application programs can be created to run in different product variants and openUTM versions. As the functionality of the KDCS interface is extended, the version number is increased. For openUTM V7.0 it is 9.
The version number of the KDCS interface is not incremented if the extended functionality of the KDCS interface affects data structures of KDCS calls that have a separate version number.