INF: Explanation of COMTI Metadata Elements

ID: Q220967

The information in this article applies to:

Microsoft COM Transaction Integrator for CICS and IMS, versions 1.0, 1.0 SP1, 4.0 SP2

SUMMARY

This article enumerates the elements contained by the COMTI metadata structure and explains their use. You are also advised to review the COM Transaction Integrator (COMTI) online Help file for related information.

Metadata is an optional feature of COMTI. To use metadata, open a component library in Component Builder or create a new component library. In the left pane, select the name of a method, right-click, and open the Properties dialog box. Click the Advanced tab.

There are three options in the "Meta data" block:

None

Include method name

Include all information

None is the default. For either of the other two options, a block of data is transmitted to the host and made available to the host server program in CICS or IMS. Metadata is not available to the client side of the application.

To produce the examples in this article, a component library with the following properties was used:

Remote environment type: CICS and IMS using TCP/IP

Target environment: CICS

Server mode: Concurrent Server

The contents of the metadata block are the same regardless of how these properties are set.

If you select Include method name, the following block of data is transmitted, where the method name variable is [input] data:


01  METHOD1-INPUT-AREA.
* META-DATA GENERATED BY COM TRANSACTION INTEGRATOR.
    05  MD-METHOD-NAME                   PIC X(32).

If you select Include all information, the following block of data is transmitted, where the variables are [in/out] data:


 01  METHOD1-META-DATA.
* META-DATA GENERATED BY COM TRANSACTION INTEGRATOR.
     05  METADATAERRBLK.                                          
         10  LMETADATALEN                 PIC 9(9) COMP.          
         10  BSTRRUNTIMEVERSION           PIC X(32).              
         10  BSTRMETHODNAME               PIC X(32).              
         10  BSTRPROGID                   PIC X(40).              
         10  BSTRCLSID                    PIC X(40).              
         10  USMAJORVERSION               PIC 9(4) COMP.          
         10  USMINORVERSION               PIC 9(4) COMP.          
         10  SREADYTOCOMMIT               PIC 9(4) COMP.          
         10  SWILLINGTODOMORE             PIC 9(4) COMP.          
         10  SRETURNERRORTOCLIENT         PIC 9(4) COMP.          
         10  SERRORCODE                   PIC 9(4) COMP.          
         10  LHELPCONTEXT                 PIC 9(9) COMP.          
         10  BSTRHELPSTRING               PIC X(256).

MORE INFORMATION

MD-METHOD-NAME and BSTRMETHODNAME contain the name of the method invoked by the client application. One possible use of this value is to provide a means for dealing with COBOL REDEFINES data. For example, each of multiple methods can invoke the same COBOL program. The COBOL program can obtain the method name from the metadata variable to determine which definition of application data is appropriate, that is, which COBOL REDEFINES to use.

Another use of metadata is to return application error information to the client application.

SRETURNERRORTOCLIENT: Set to either 0 (False) or non-zero (True). Must be true to have error information returned to the client application.

SERRORCODE: The error code to be assigned by COMTI runtime to the Err object. To distinguish COMTI error messages from metadata messages returned from the mainframe, COMTI adds +10000 to the number of any metadata error message returned from the mainframe. For example, if the host server program assigns +42 to this variable, +10042 is assigned to Err.Number when control is returned to a Visual Basic client application.

BSTRHELPSTRING: The server program on the host can assign any meaningful string data to this variable. It is contained in the value assigned by COMTI runtime to Err.Description when control is returned to a Visual Basic client application.

Additionally, the following record is written to the application event log when the previous metadata variables are initialized to signal an error. For this example, the host server program assigned +1 to SRETURNERRORTOCLIENT, +42 to SERRORCODE, and "METADATA ERROR MESSAGE" to BSTRHELPSTRING.
Event ID: 102
Source: COMTI
Type: Error
Category: General

Exception description:
(1521) Exception returned from host: "METADATA ERROR MESSAGE"
Examine the mainframe server application program to determine why it returned an error indication in the COM Transaction Integrator specified meta-data.
Here are the remaining elements, presented in order of occurrence in the structure. Values assigned by COMTI runtime are given.

LMETADATALEN (long): Contains the length of the metadata structure (420 bytes; 0x000001a4)

BSTRRUNTIMEVERSION (string): "Microsoft COMTI Version 1.0.0" -- The version of the COMTI runtime component.

BSTRPROGID (string): MetaData.Echo.1

BSTRCLSID (string): {54A7A454-F436-11D2-80F7-00A0C9039FF9} -- a GUID that uniquely identifies this block of metadata. It helps ensure the metadata received by the host server program is valid.

USMAJORVERSION (short): 0x0001. This is the major version of COMTI Component Builder used to build the component library.

USMINORVERSION (short): 0x0000. This is the minor version of COMTI Component Builder used to build the component library.

SREADYTOCOMMIT (short): 0x0001. Set to true by default and the host server program should set it to zero if it is not willing to commit. This gives the server program an opportunity to participate in the two-phase commit "decision-making" process.

SWILLINGTODOMORE (short): 0x0000. Reserved for future use.

LHELPCONTEXT (long): 0x00000000. Reserved for future use.

Additional query words: meta meta-data metadata

Keywords :
Version : WINDOWS:1.0,1.0 SP1,4.0 SP2
Platform : WINDOWS
Issue type : kbinfo