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

=============================================================================