If you use the event exit FORMAT, you are implicitly doing without the output support provided by the system components FHS and VTSU. You will therefore need to write your own formatting and may need to handle screen restarts manually. openUTM recognizes the event exit FORMAT by means of the “-” prefix to the format identifier in KCMF/kcfn.
The event exit FORMAT must be generated in the EXIT statement with the operand USAGE=FORMAT. Only one event exit FORMAT is permitted per application. Subformats must not be used.
The event exit FORMAT can be written in any of the programming languages supported by openUTM. The programming languages Assembler and C/C++ are, however, particularly well suited to this purpose. The description of the FORMAT exit provided in the remainder of this section is based on the Assembler language. Nevertheless, here is a brief example of the prototype of a FORMAT exit in C:
void FORMATEX( struct kc_ca * const pKB
,char * const pSPAB
,char * const pFormatName
,char * const pDevice
,char * const pFormatArea
,char * const pPhysicallyInOutArea
,char * const pRestartArea
,char * const pFormatControlArea
,char * const pInOutIndicator
,char * const pSecondaryReturnCode
);
Address list
When the event exit is called, openUTM provides the following address list:
Sequence of word addresses | Contents |
|---|---|
1. | Address of the KB |
2. | Address of the SPAB |
3. | Address of the format name |
4. | Address of the terminal type |
5. | Address of the formatting user area |
6. | Address of the physical input/output area |
7. | Address of a restart area |
8. | Address of the formatting control area |
9. | Address of the input/output indicator |
openUTM calls the formatting routine if you use a -format in the KDCS calls MPUT, FPUT, DPUT, MGET or FGET.
A dialog output message (MPUT) is not formatted until after the PEND or PGWT call. The contents of KB and SPAB are identical to those of the PEND or PGWT call. An asynchronous output message is not formatted until it is sent. The contents of KB and SPAB are undefined in this case, i.e. they no longer relate to the program unit which called FPUT or DPUT.
A dialog input message is formatted during MGET handling. KB and SPAB have the contents of the MGET call. This applies only for the event exit FORMAT: normally, openUTM formats messages before the INIT.
An asynchronous input message is formatted when the message is received, not when the FGET occurs. The contents of KB and SPAB are therefore undefined.
Please ensure that there are no fields that precede the transaction code, since openUTM identifies the TAC without calling the format exit.
Format name (address in word 3)
In the case of input formatting: The format name used for this terminal during the previous output formatting operation (calls: MPUT, FPUT, DPUT or the command KDCFOR).
In the case of output formatting: The specification made in KCMF/kcfn in the parameter area for the MPUT or FPUT call.
Terminal type and additional information (address in word 4)
t | is the physical device type which can be queried by means of a TSTAT macro with TCHAR. The codes can be looked up in the DCSTA macro (see the BS2000 manual “Executive Macros”). |
If the specified terminal type is not supported by the event exit FORMAT, a formatting error must be forced. | |
z | is an item of additional information: |
X’00’ = delete screen. | |
X’01’ = do not delete screen. | |
ba | is the screen output function: |
X’0001’: KCRESTRT | |
X’0001’: KCREPL | |
X’0002’: KCERAS | |
X’0004’: KCALARM | |
X’0008’: KCREPR | |
X’2000’: KCEXTEND | |
X’4000’: KCCARD | |
qa | is an identifier which indicates whether confirmation must be requested - applies to output to printers only. |
X’00’ = request confirmation | |
X’01’ = do not request confirmation | |
q1,q2 | If qa = X’01’, then these two bytes will contain the confirmation numbers in EBCDIC code. |
dc | device characteristics; contains 8 bytes of information on the device type and configuration, in the format that would be generated in PDN with XSTAT and XOPCH. |
Formatting user area (address in word 5)
Input formatting:
Once the format exit has been called, openUTM expects the logical message here in the input format (see "Message formats"). The maximum length is determined by the generated value (see MAX statement, operand NB, in the openUTM manual “Generating Applications”). openUTM enters this maximum length in the length field of the formatting user area before the call is made.
If conversion of the logical message to a physical message causes it to exceed the length of this area, a formatting error must be forced.
Output formatting:
The area contains the message to be formatted in the form in which it was made available in the message area with MPUT or FPUT. The message is structured in input format. Subformats are not permitted.
Physical input/output area (address in word 6)
Input formatting:
openUTM passes the message as it is received from the terminal in the input format.
Output formatting:
Once the format exit has been called, openUTM expects to find the formatted message here in output format.
The maximum length is determined by the maximum message length allowed on the connection to the client. openUTM enters this maximum length in the length field of the physical input/output area before the call is made.
If conversion of the logical message to a physical message causes it to exceed the length of this area, a formatting error must be forced or an alternative message must be generated.
Restart area (address in word 7)
The restart area must be used to reconstruct screen formats where necessary, which can arise in three different situations, for example:
with the KDCDISP command (display last screen)
if the terminal user wants to continue an interrupted service with the most recently entered format (e.g. after a connection has been lost or after the command KDCOFF has been issued while a service was still running).
if the screen is destroyed by an asynchronous output and is to be restored again.
You must ensure that the restart area always contains the current logical message so that this can be output if the need arises.
If you first want to delete the old screen when formatting output, you must refresh the restart area.
If you do not want the old screen to be deleted in this case, you need only modify (overwrite) those fields in the restart area that are also modified at the terminal.
After input has been made at the terminal, the restart area must be updated accordingly.
In the case of a PEND, the restart area is backed up to the length specified for the user area for this format when the output was last formatted (KCLM for MPUT).
In the event of a restart, output formatting takes place. The address of the formatting user area is the same as that of the restart area (i.e. there is only a restart area).
Formatting control area (address in word 8)
As of address + 1 in this area, you must store in the event exit FORMAT a (hexadecimal) return code which indicates whether formatting was successful.
The return code must be one of the following:
X’00’ | Output formatting was successful. |
X’xy’ | User error messages were passed in the form of UTM return code "FRxy" in the field KCRCDC (formatting errors). The entries X’01’, X’02’, X’03’, X’04’, X’08’, X’10’ and X’99’ are not permitted: these return codes are reserved for cooperation between openUTM and FHS. |
Input/output indicator (address in word 9)
The first byte of the indicator contains the value:
| X'00': | for input formatting |
| X'01': | for output formatting |
| X'02': | for a restart |
| X'03': | for KDCFOR |
In the case of a restart, the addresses of the formatting and restart areas are identical.
Message formats
Two different message formats are used in the event exit FORMAT (see previous section). These formats do not necessarily adhere to the half-word boundary.
input format -------------------------------------------
| length | b | b | (partial) message |
-------------------------------------------
0 2 4
output format --------------------------------------------------
| length | b | b | b | (partial) message |
--------------------------------------------------
0 2 5
length | is the length of the entire message (binary), including the prefix, which |
b | is a blank (X’40’) |
For more information on the structure of physical messages, refer to the manuals for your terminal.
FEXIT CSECT
STM 14,12,12(13)
BALR 12,0
USING *,12
USING KB,2
USING SPAB,3
USING DFORMNAM,4
USING DFORMSDE,5
USING DADUSERA,6
USING DAREAFMI,7
USING DADRSRTA,8
USING DMDCBUSE,9
USING DFORMMOD,10
LM 2,10,0(1)
*
* INPUT OR OUTPUT FORMATTING, RESTART OR KDCFOR ?
*
CLI FORM#IND,X'00' 00=INPUT, 01=OUTPUT
BE EINFORM 02=RESTART, 03=KDCFOR
CLI FORM#IND,X'01'
BE AUSFORM
CLI FORM#IND,X'02'
BE RESTFORM
CLI FORM#IND,X'03'
BE FORFORM
*
* SET FORMATTING ERROR: INVALID OPCODE !
*
********************************************************* K D C F O R
*
FORFORM DS 0H
*
* A) SET UP PHYSICAL MESSAGE AS PER FORMAT NAME
* AND PREASSIGN WITH "STD." VALUES
* B) ANALYZE CONFIRMATION REQUEST ('FORMQA')
* AND SUPPLY MESSAGE HEADER
* C) SET UP RESTART AREA
* D) SET RETURN CODE IN FORMATTING CONTROL AREA
*
END#EXIT LM 14,12,12(13)
BR 14
*
*********************************************** INPUT FORMATTING
*
EINFORM CNOP 0,4
*
* A) ANALYZE PHYSICAL NAME AS PER FORMAT NAME AND
* SET UP FORMATTING USER AREA ('DADUSERA') AS PER
* MESSAGE FORMAT FOR INPUT
* B) SUPPLY RESTART AREA
* C) SET RETURN CODE IN FORMATTING CONTROL AREA
*
B END#EXIT
EJECT
************************************************ OUTPUT FORMATTING
*
AUSFORM CNOP 0,4
*
* A) SET UP PHYSICAL MESSAGE
* THE FOLLOWING ELEMENTS ARE ANALYZED:
* - FORMATTING USER AREA
* - FORMAT NAME
* - STATION TYPE AND ADDITIONAL INFORMATION
* WITH
* 1) 'FORMCLMO' (DELETE SCREEN?
* I.E. "FORMAT OLD" = "FORMAT NEW" ?)
* 2) 'FORMBA' (SCREEN OUTPUT FUNCTION)
* 3) 'FORMQA' AND GGF. 'FORMRB'
* B) SUPPLY RESTART AREA
* C) SET RETURN CODE IN FORMATTING CONTROL AREA
*
B END#EXIT
***************************************************** R E S T A R T
*
RESTFORM CNOP 0,4
*
* A) ANALYZE RESTART AREA
* AND SET UP PHYSICAL MESSAGE
* B) SET RETURN CODE IN FORMATTING CONTROL AREA
*
B END#EXIT
*
EJECT
*
* DSECTS FOR PARAMETERS PASSED BY UTM
* >>>>>>>>>>>>>>>>>> DEFINITION INCOMPLETE
*
KB KCKBA D
*
SPACE 5
SPAB KCPAA D
*
EJECT
DFORMNAM DSECT
FORMNAME DS CL8
*
DFORMSDE DSECT
FORMSDEV DS C
FORMCLMO DS C
FORMBA DS CL2
FORMQA DS C
FORMRB DS CL2
*
DADUSERA DSECT
DS 0H
*
DAREAFMI DSECT
DS 0H
*
DADRSRTA DSECT
DS 0H
*
DMDCBUSE DSECT
DS 0H
*
DFORMMOD DSECT
FORM#IND DS X
END