openUTM creates the KB when a new service is started. The KB is retained until the service is terminated. The contents of the KB are transferred to the program currently being executed. The size of the KB can be adapted to the data to be transferred, i.e. it can be increased or decreased for individual processing steps.
There are two areas of fixed lengths at the beginning of each KB. These are used for communication between openUTM and the program:
the KB header
the KB return area.
Language-specific data structures are available for structuring these areas: for COBOL in the KCKBC COPY element, and for C/C++ in the kcca.h include file.
In the KB header you can find current information about the service, program unit and communication partner after calling INIT, and after each subsequent call.
In the KB return area, openUTM transfers its return data to the program after each call (except PEND). The evaluation, in particular of the return code, provides information about whether or not a call has been executed successfully and can be used for specific control measures in the program (see also section "Programming error routines").
Additionally, you can define an area of variable length in the KB, the KB program area, whose structure you can determine freely. While the KB header and the KB return area are always present, you can select whether or not you want to use a KB program area. It can be used to transfer and store service-specific data of any type.
The maximum length of this area is specified when the application is generated (KB operand in the MAX statement). In the program, you use INIT to specify the length which the program currently expects. This length may not be longer than the value you generated with the KB operand. When the next synchronization point is reached the KB is saved in the length specified by INIT. Therefore only enter the absolutely necessary minimum length for the KB when calling INIT. In this way you avoid unnecessary information being saved.
If multiple programs with KB program areas of differing length process the same service, length conflicts may occur during data transfer between programs. A program always receives data in the length specified in the KCLKBPRGE field by the predecessor program when INIT was called. If the receiving program provides longer data fields, then the remaining area is undefined. If the receiving program defines a shorter KB, it nevertheless receives the data in its full length. The truncation only takes effect when the data is passed on again (see diagram next page).
Freely selectable fill characters
When you generate a UTM application you can specify a fill character of your choice (in the CLRCH operand of the KDCDEF statement MAX). openUTM then overwrites the SPAB with this character at the end of the service. After the start of the application program the area is filled with the specified character in the generated length.
This function is important for program testing because it facilitates the discovery of certain errors in single-process mode; additionally, you can use this function for data protection.
Figure: KB program area for data transfer