Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

Event exit INPUT

You can use this event exit to determine the effect of terminal input.

openUTM calls the event exit INPUT - with a few exceptions - every time input is made at a terminal. The exceptions are as follows:

  • input if no user is as yet signed on

  • input in the event service SIGNON

  • input using a function key generated with

  • input after a program has issued the call SIGN OB/OF.

openUTM passes the address of the parameter area, comprising an input area and an output area, to the program for an INPUT exit.

Programming language-specific data structures are available for declarations in the parameter area: COBOL uses the COPY member KCINPC, whereas C/C++ use the header file kcinp.h. For an explanation of the individual fields in the parameter area and the meanings of these fields, see pages from table "Parameter area KDCINPC/kdcinp.h".

On BS2000 systems, openUTM also passes a second parameter to the input exit containing additional input fields. Once again, a programming language-specific data structure is available for the structure of the second parameter as well: the COBOL structure is the COPY member KCCFC; the C/C++ structure is the header file kccf.h. The second parameter area is described on pages from section "Second parameter area KCCFC/kccf.h (BS2000 systems)".

The program analyzes the values entered in the input area and sets the output area accordingly. Depending on the values entered in the output area, openUTM decides which of the following actions is to be executed:

  • continue the service or

  • start a new service or

  • stack a service and start a new service or

  • execute a user command, e.g. KDCOFF or

  • send a message with error information to the terminal.

Possible applications

The input exit provides the terminal interface with greater freedom regarding the layout of the user interface.

  • Position of transaction codes or KDC commands in the message:
    transaction codes or KDC commands do not have to appear at the start of a message.

  • Visibility of transaction codes on screen:
    The Transaction code has not to be visible on screen if you want to start a service.For example, a menu might offer a number of activities. The terminal user enters a text or a number to choose one of them. This input itself does not have to be a transaction code: it is only the INPUT exit which converts it to a transaction code (a service TAC). In this way transaction codes, which are an element of generation information, become independent of the dialog interface.

  • Representation of command names:
    There is no need to specify “KDC...” in order to issue a KDC command.
    If it is felt to be useful, commands can be represented in some other form, e.g. “/” instead of “KDC”.

Parameter area KDCINPC/kdcinp.h

Input area (supplied by openUTM)

Field name

Contents

KCIFCH

First 8 characters of the input

KCIMF/kcifn

Format identifier

KCICVTAC

Service transaction code

KCICVST

Service status

KCIFKEY

Value of F key: 1,...,20 / binary zero

KCIKKEY

Binary zero / on BS2000 systems: value of K key: 1,...,20

KCICFINF: "NO"/"MO"/"ON"/"UN" 1

Formatting information

KCILTERM

Current LTERM partner

KCIUSER

Current user ID

Output area (supplied by the INPUT exit)

Field name

Contents

KCINTAC or
KCINCMD

Next service TAC or
next user command

KCICCD

Code for the effect of the input: "ER"/"CC"/"SC"/"ST"/"CD"

KCICUT

Truncate TAC: "Y"/"N"

KCIERRCD

Error info for terminal (4 bytes)

1 "MO" / "ON" / "UN" (only on BS2000 systems)

openUTM enters the following values in the appropriate fields of the input area:

KCIFCH

the first 8 characters of the input, at most, however, up to the first blank.

KCIMF/kcifn

the format identifier:

  • Blanks in line mode or

  • the format identifier of the format on the screen (only on BS2000 systems).

Only on BS2000 systems: The field KCIMF/kcifn can also contain the format identifier #!POPUP. #!POPUP indicates that a box “pops up” on screen. You can use the FHS service function KDCFHS with the USER-CODE INFD to display the names of all formats on the screen.

KCICVTAC

the transaction code used to start the current service (if any).

KCICVST

the service status:

  • ES(End of dialog Step)
    End of the dialog step with PEND KP or PGWT KP

  • ET(End of Transaction)
    End of the transaction with PEND RE

  • RS(Return from Stack)
    End of the inserted service; the input is intended for the stacked service.

  • EC(End of Conversation)
    The last dialog step was terminated with PEND FI; the input is intended for a new service.

KCIFKEY

the value of the F key (1 - 20, on BS2000 systems: 1 - 24) if pressed, otherwise binary zero.

KCIKKEY

binary zero
or (on BS2000 systems) the value of the K key (1 - 14), if pressed

KCICFINF

Information of the formatting system:

  • NO (NO control field)

    • The input does not contain any control fields; either the input was in line mode

    • or (on BS2000 systems) the format does not contain any control fields or one of the control fields was empty.

Only on BS2000 systems:

  • MO (MOre control fields)
    The input contains several control fields.

  • ON (ONe control field)
    The input contains exactly one control field.

  • UN (UNsuccessful)
    Input could not be formatted.
    Therefore no control field specifications were possible; this entry is made, for instance, after input in a format fetched with KDCOUT

KCILTERM

name of the LTERM partner via which the terminal is connected.

KCIUSER

the current user ID.KCICVST

You input the following in the fields of the output area:

KCINTAC

if a new service is to be started: the TAC of the program unit which starts the next service.

KCINCMD

if a user command is to be executed: the user command (KDC command).

Blanks have to be entered in the case of an error message (KCICCD = ER) or continuation of the service (KCICCD = CC, follow-up TAC is entered with PEND!).

KCICCD

depending on the required effect of the input:

  • ER (ERror indication)
    for an error message to the data display terminal. You can then enter an insert in the KCIERRCD field for this message.

  • CC (Continue Conversation)
    for continuing the service. This must not be specified after end of service (KCICVST = EC).

  • SC (Start new Conversation)
    if a new service is to be started; only allowed after end of service (KCICVST = EC).

  • ST (STack Conversation)
    if the current service is to be stacked and a new service is to be started; allowed only at end of transaction (KCICVST = ET/RS).

  • CD (process CommanD)
    if openUTM is to execute a user command.

KCICUT

the value Y if the TAC is to be truncated at the start of a service (permissible only where KCICCD = SC/ST), otherwise N.

KCIERRCD

a character string of up to 4 bytes to be sent to the terminal with the UTM message K098 if KCICCD=ER. Otherwise (KCICCD != ER) blank.

Second parameter area KCCFC/kccf.h (BS2000 systems)

openUTM uses the second parameter to pass the contents of the control fields from the screen formats to the program unit - which is why this second parameter area is also referred to as the control field area. openUTM can use the field KCCFS to pass input made in various control fields for a format (and even in different subformats of a format).

The first two fields, KCCFCREM and KCCFCFLD, correspond to the control field area in earlier openUTM versions. They have been kept for compatibility reasons. The fields KCCFNOCF and KCCFS are relevant.

The table below illustrates the structure of the control field area in which openUTM makes the input parameters available:

Second parameter area (supplied by openUTM)

Field name

Contents

KCCFCREM (bytes 1 - 8)

First 8 characters of the input

KCCFCFLD (bytes 9 - 140)

Format identifier

KCCFNOCF (bytes 141 - 144)

Service transaction code

KCCFS (bytes 145 - 7744)                     

Table (array) of control field information: each array element contains the information for one control field. There can be up to 50 elements. The elements are structured as follows:

  • KCCFFNAM (8 bytes)

    Name of the format or subformat containing the control field

  • KCCFREM (8 bytes)

    Remark defined as with IFG

  • KCFLOFL (4 bytes)

    Length of the control field 

  • KCCFFLD (132 bytes)

    Contents of the control field

In the second parameter area, openUTM supplies the following values:

KCCFCREM

contains the remark defined for the control field when the format was generated with IFG and whose contents are included in KCCFCFLC. If no remark was created when the format was generated, or if no entry was made in the control field, the 8 bytes in this field are filled with blanks.

KCCFCFLD

contains the entry for a control field in the format, provided that at least one control field is defined in the format and that an entry has been made in it. KCCFCFLD contains this entry with the length permitted by the control field. The remainder of the KCCFCFLD field is padded with blanks.
If no entry has been made in a control field, or if the format does not have any control fields, then both KCCFCREM and KCCFCFLD will contain blanks and KCCFNOCF will have the value null.
If the format has several control fields which, in some cases, will be in different subformats, then both the remark and the contents of the control field will refer to a control field in which an entry has been made. If entries were made in more than one control field, KCCDCFLD will assume the entry made in the first control field in the uppermost subformat on the screen. KDDFCRREM will then contain the corresponding remark.

KCCFNOCF

contains the number of control fields in the format in which entries have been made.

KCCFS

contains an array which covers all the control fields passed by FHS, including the control field whose data is already entered in the fields KCCFCFLD and KCCFCREM. The number of valid array elements is stored in the field KCCFNOCF.
Each array element consists of a structure containing the following fields:

KCCFFNAM

contains (in 8 bytes) the (sub-) format name of the format to which the control field belongs. If the name is less than 8 characters long, the rest of the field is padded with blanks.

KCCFREM

contains the remark defined for this control field when the format was generated with IFG. If no remark was created when the format was generated, or if no entry was made in the control field, the 8 bytes in this field are filled with blanks.

KCCFLOFL

length of the control field.

KCCFFLD

contains the entry for a control field in the format. KCCFFLD contains this entry with the length permitted by the control field. The remainder of the KCCFCFLD field is padded with blanks.

Input in control fields (BS2000 systems)

Input can be made in a control field from a variety of sources:

  • Terminal users can make entries in the control field.

  • The field may have been defined with the property “automatic input” during format generation with IFG.

  • In the case of ∗formats or +formats: The field has the property “unprotected” and the FHS start parameter ISTD=RUNP (read unprotected) is set.

Errors with INPUT exit

If there are errors in the INPUT exit, an open service is not terminated; however, the terminal user is informed of the error with message K098 if

  • the entry in KCICCD (effect of the input) is invalid or

  • the entry in KCICCD does not match the values of the other output fields.

In both cases, a UTM dump with REASON=INPERR is supplied for error diagnosis.On BS2000 systems, a USERDUMP is also generated in such cases.

Database calls are not permitted in the INPUT exit.
If database calls are nevertheless included, a USERDUMP is generated on BS2000 systems with the error code KDCDB10.

Generation notes

The event exit INPUT must be defined during generation with the EXIT statement and the operand USAGE=(INPUT,...). You can also defined several INPUT exits for a variety of purposes. The following options are available:

  • An application contains just one universal INPUT exit which is called with inputs in formatted mode and with inputs in line mode. This universal exit is generated with USAGE=(INPUT,ALL). Other INPUT exits are not allowed in this case.

  • A special INPUT can be generated for each type of format identifier. There are two possible types; no more than one of each type may be defined:

    • With USAGE=(INPUT,LINEMODE), an INPUT exit is defined for input in line mode.

    Only on BS2000 systems:

    • With USAGE=(INPUT,FORMMODE) an INPUT exit is defined for +fomrats and *formats. An INPUT exit generated in this way will also be called for the #formats.

    • With USAGE=(INPUT,USERFORM), an INPUT exit is defined for the user’s own formatting routines (-formats).

If special INPUT exits are used in an application, then it is not allowed to define a universal type with USAGE=(INPUT,ALL).

Powered by Atlassian Confluence and Scroll Viewport.