Q220967: Explanation of COMTI Metadata Elements
Article: Q220967
Product(s): Microsoft SNA Server
Version(s): WINDOWS:1.0,1.0 SP1,4.0 SP2
Operating System(s):
Keyword(s):
Last Modified: 05-APR-2000
-------------------------------------------------------------------------------
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 :
Technology : kbAudDeveloper kbCOMTISearch kbCOMTI100 kbCOMTI100SP1 kbCOMTI400SP2
Version : WINDOWS:1.0,1.0 SP1,4.0 SP2
Hardware : ALPHA x86
Issue type : kbinfo
=============================================================================
THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.
Copyright Microsoft Corporation 1986-2002.