A format (also called a mask) is simply a form displayed at a terminal or output to a printer. Like any other form, a format consists of fields which you can fill in (input fields) and texts belonging to the form (text fields). This means that formats are forms which are stored in a computer and output at a terminal or printer when necessary (see also section "Output to printers").
A format also contains information on how a field is represented on the screen (e.g. flashing), what you can enter in a field (e.g. numeric values only), or where the cursor should be found in the format display.
Interaction with the formatting system
openUTM cooperates with the format handler FHS (format handling system) via IUTMFORM interface.
You can use the format generator IFG (Interactive Format Generator) to create FHS formats simply and quickly within a guided dialog. Addressing aids are automatically generated which you can use in the program units to structure the message areas. The finished formats are stored in under in libraries.
If you want to perform input/output in program units, you have to set the required format identifier in the KCMF/kcfn field. Interacting with the format handling system, openUTM then automatically formats the messages.
The format identifier consists of:
the prefix (*, + or #) which determines the type of the format (see next section).
You can also use the "-" character.the format name (up to a maximum of 7 characters).
Format types
openUTM distinguishes between *formats, +formats and #formats:
*formats | use these formats if you do not want to change the attributes of the format fields (e.g. display attributes) in the program. If you use *formats only the data fields are transferred in inputs/outputs. |
+formats | are formats in which you are allowed to change the attributes of individual format fields in the program. For example, you can return an incorrect entry back to the terminal in flashing mode. Each data field is prefixed with a 2-byte attribute field which you can use to insert the required attribute combination in the program. If you enter binary zero, the attribute combination which was defined when the format was generated applies. |
openUTM provides you with all the permissible attribute combinations in language-specific data structures, in the KCATC element in COBOL and in the kcat.c include file in C/C++. | |
#formats | are formats in which you are allowed to change both the attributes of the format fields and the global attributes of the format in the program. For input/output, the attribute fields and data fields are divided into separate blocks. For further information refer to the formatting system manual. |
You can also use -formats. -formats are not formatted by the formatting system, but by the event exit FORMAT, see "Event exit FORMAT (BS2000 systems)". If the format identifier starts with the "-" character, openUTM branches to this user-defined formatting routine.
Positioning the cursor
When formatting output with +formats and *formats, it is possible to control the position of the cursor in a program (function KDSCUR).
When setting the cursor, you have to specify the address of either the attribute field or the data field. Which is required depends on what is specified in the FHS start parameter ATTR or NOATTR:
ATTR (only permissible with +formats): the address of the attribute field is specified
NOATTR (for *formats and +formats): the address of the data field is specified
The cursor can be placed at the beginning of the assigned data field by correspondingly marking the attribute field. The position of the corresponding screen field is known from the format description. If several attribute fields of an output message are marked at the same time in the program run, then only the first entry is used.
The cursor can be placed on a specific field by calling the KDCSCUR() function. The field at which the cursor is to be placed the next time something is output is specified in the message area as an argument of the function.
Setting the cursor in COBOL program units:
CALL "KDCSCUR" USING FNAME.
Setting the cursor in C/C++ program units:
KDCSCUR (field name); (The result of the function is of type void)
The following arrangement is valid regarding the KDCS attribute functions (+formats and *formats):
The cursor can be positioned at the beginning of a message field F(i) by calling the "KDCSCUR" subroutine with the i-th attribute field AF(i) as a parameter. The subroutine contains the cursor identifier as a constant and adds this constant to the attributes already specified in the attribute field passed as a parameter.
Example:
CALL "KDCSCUR" USING AF1.
The program unit run would like to place the cursor at the beginning of the message field F1 in addition to the field attribute already defined.
Changing format between input and output
If openUTM outputs a message with a particular format identifier, you have to specify the same format name in the KCMF/kcfn field with MGET for the next input.
Exception:
If you do not use partial formats, openUTM tolerates for MGET an incorrect format identifier in KCMF/kcfn: the message is nevertheless formatted in accordance with the last screen format, the 05Z return code is set and the format identifier of the last employed format is displayed in KCRMF/kcrfn.
If an incorrect format identifier is specified in the KCMF/kcfn field when reading partial formats, openUTM sets return code 03Z, returns the correct format identifier in KCRMF/kcrfn and sets KCRLM to 0. There is no entry in the message area.