Common Base Event format

Common Base Event formatted business events on the z/TPF system are formatted based on the Common Base Event Specification V1.0.1.

Common Base Event formatted data consists of different sections depending on the content of the business event specification.

If the business event specification includes the <esEventMessageFormat> element, Common Base Event formatted data consists of the following sections:
  • Standard Common Base Event information as defined by the Common Base Event Specification V1.0.1.
  • The unique business event data defined by the DFDL schema that is associated with the event by the <esEventMessageFormat> element in the business event specification.
If the business event specification includes the <Object> or <ObjectList> element, Common Base Event formatted data consists of the following sections:
  • Standard Common Base Event information as defined by the Common Base Event Specification V1.0.1.
  • Start of changeThe z/TPF unique data defined by the tpf_cbe_object.se.xsd schema file that is shipped with the z/TPF system.End of change
  • The unique business event data that is associated to the event by using the <Object> or <ObjectList> element in the business event specification.

There is a unique XML name space for each section of the Common Base Event formatted output.

Start of changeThe Common Base Event document that is produced by this format is encoded by using the IBM-1047 character set. To specify the Common Base Event format, set the <afStandardFormat> element to CBE in the business event dispatch adapter specification.End of change

Note: Object signal events, which are specified by using the <Object> or <ObjectList> element, are deprecated. Use event message signal events to define new signal events.

Element and attribute details

The following tables describe the default fields that are populated by z/TPF business event processing when you specify the Common Base Event data format.

You can use the application enrichment and dispatch enrichment programs to pass user data and standard format user data to Common Base Event formatting. User data is defined by the tpf_bev_data_format_user_data structure in the ibev.h header file and is passed to the Common Base Event data user exit (ubev_cbeData_user_exit). Standard format user data is defined by the tpf_bev_standard_format_user_data structure in the ibev.h header file. You can use the standard format user data to add or modify elements and attributes in the Common Base Event XML file that is defined by the Common Base Event specification version 1.0.1.

Table 1. Common Base Event format elements
Element name Description Element usage
<CommonBaseEvent> The root element for a Common Base Event formatted XML file.

For information about the attributes for this element, see Table 2; for information about the subelements for this element, see Table 3.

One element; multiple attributes; multiple subelements
Table 2. <CommonBaseEvent> attributes
<CommonBaseEvent>
Attribute name Description
version A 1- to 16-character version for the Common Base Event specification. This value must be consistent with the version specified in the schema header.
creationTime

The Universal Coordinated Time (UTC) date and time that the business event occurred. This value is defined by the dateTime schema data type. The time is represented as hours, minutes, seconds, and microseconds.

Table 3. <CommonBaseEvent> elements
<CommonBaseEvent>
Element name Description Element usage
<sourceComponentId> Identifies the component that is affected by the business event.

For information about the attributes for this element, see Table 4.

One element; multiple attributes
<situation> The type of situation that caused the business event.

For information about the attribute for this element, see Table 5; for information about the subelement for this element, see Table 6.

One element; one attribute; one subelement
<event>
Deprecated: This element is deprecated as of PUT 11. This element is valid only with the <Object> or <ObjectList> element.
Note: This element is mutually exclusive with the <Event> element.

The event information for an object signal event that is specified by using the <Object> or <ObjectList> element.

For information about the subelements for this element, see Table 7.

One element; multiple subelements
<Event>
Note: This element is mutually exclusive with the <event> element.

The event information for an event message business event. The event information includes an event header, event ECB context, event user context, and the event data.

For more information about the subelements for this element, see Table 8.

One element; multiple subelements
Table 4. <sourceComponentId> attributes
<CommonBaseEvent><sourceComponentId>
Attribute name Description
component A 1- to 256-character name that specifies the logical identify of a component. For example, the name of an application or subsystem.

For all z/TPF Common Base Event formatted files, the value for the component attribute is the z/TPF enterprise name. The z/TPF enterprise name is defined by the ENTERPRISE parameter on the CONFIG macro during in the system initialization process (SIP).

componentIdType A 1- to 32-character name that specifies the type for the component.

For all z/TPF Common Base Event formatted files, the value for the componentIdType attribute is SystemName.

componentType A 1- to 512-character name that is used to characterize all instances of a particular component.

For all z/TPF Common Base Event formatted files, the value for the componentType attribute is zTPF Enterprise.

location A 1- to 256-character name that specifies the physical address of the component.

For all z/TPF Common Base Event formatted files, the value for the location attribute is obtained from the gethostname function.

locationType A 1- to 32-character name that specifies the format and meaning of the value of the location attribute.

For all z/TPF Common Base Event formatted files, the value for the locationType attribute is HostName.

subComponent A 1- to 512-character name that specifies an additional distinction for the component attribute.

For all z/TPF Common Base Event formatted files, the value for the subComponent attribute is set to the intercept name that generated the event.

Table 5. <situation> attributes
<CommonBaseEvent><situation>
Attribute name Description
categoryName A 1- to 64-character name that specifies the type of situation that caused the event.

For all z/TPF Common Base Event formatted files, the default value for the categoryName attribute is OtherSituation.

Table 6. <situation> elements
<CommonBaseEvent><situation>
Element name Description Element usage
<situationType> The type of situation that caused the event.

For information about the attribute for this element, see Table 9; for information about the subelement for this element, see Table 10.

One element; one attribute; one subelement
Table 7. <event> elements
<CommonBaseEvent><event>
Element name Description Element usage
<context-info> Contains information that is static for all business events that occur on a z/TPF system.

For information about the elements for this element, see Table 11.

One element; multiple subelements
<payload-data> Contains the data that is generated for a particular business event based on the business event specification for that event

The XML name space for these elements is based on the <esName> and <esUserTag> elements defined in the business event specification. The relative name space is value_of_esUserTag/value_of_esName. The base name space for the data is http://www.ibm.com/xmlns/prod/ztpf/events/.

For information about the elements for this element, see Table 12.

One element; undefined number of subelements
Deprecated: The <context-info> and <payload-data> elements are deprecated as of PUT 11. These elements are valid only with the <Object> or <ObjectList> element.
Table 8. <Event> elements
<CommonBaseEvent><Event>
Element name Description Element usage
<EventHeader> The event header. One element; multiple subelements
<EventECBContext> The event ECB context information. This element is optional. One element; multiple subelements
<EventUserContext> The event user context information. This element is optional. One element; multiple subelements
<EventData> The event data.

For event message data events, the event data includes a data header, z/TPFDF subfile information, and z/TPFDF LREC data for zero or more z/TPFDF LRECs. The z/TPFDF subfile information includes a count of the z/TPFDF LRECs in the data.

For event message signal events, you can define the event data.

One element; multiple subelements
Note: For information about the subelements of each <Event> element, see the type attribute values on the element that is defined in the DFDL schema associated with the event message data event by using the <esEventMessageFormat> element in the business event specification. The type attribute associates a complexType with the element that defines the subselements.
Table 9. <situationType> attributes
<CommonBaseEvent><situation><situationType>
Attribute name Description
reasoningScope A 1- to 64-character name that specifies the scope of the impact of the event.

For all z/TPF Common Base Event formatted files, the default value for the reasoningScope attribute is INTERNAL.

Table 10. <situationType> elements
<CommonBaseEvent><situation><situationType>
Element name Description Element usage
<zTPFApplicationEvent>

The situation type that identifies the business event as an object signal event.

One element
<zTPFSignalEvent>

The situation type that identifies the business event as an event message signal event.

One element
<zTPFDataEvent>

The situation type that identifies the business event as an event message data event.

One element
Note: You can extend the <zTPFApplicationEvent>, <zTPFSignalEvent>, and <zTPFDataEvent> elements with any additional data by using the Common Base Event data user exit (ubev_cbeData_user_exit).
Table 11. <context-info> elements
<CommonBaseEvent><event><context-info>
Element name Description Element usage
<eventName> The 1- to 16-character name of this business event. One element
<userTag> The UserTag that was passed for this business event. One element
<timeStamp>

The Universal Coordinated Time (UTC) date and time that the business event occurred. This value is defined by the dateTime schema data type. The time is represented as hours, minutes, seconds, and microseconds.

One element
<interceptName> The 1- to 512-character string that identifies the capture point of this business event. One element
<ssuName> The name of the subsystem user that this business event was generated on. One element
Deprecated: The <context-info> subelements are deprecated as of PUT 11. These elements are valid only with the <Object> or <ObjectList> element.
Table 12. <payload-data> elements
<CommonBaseEvent><event><payload-data>
Element name Description Element usage
  The data structure for the business event.

The name and value for the <payload-data> subelements are defined by the business event specification.

Undefined number of elements
Deprecated: The <payload-data> subelements are deprecated as of PUT 11. These elements are valid only with the <Object> or <ObjectList> element.

Examples

The following example shows a sample event message signal event in Common Base Event format. The event does not include event ECB context or event user context data.
<?xml version="1.0" encoding="utf-8" ?>
<cbe:CommonBaseEvent xmlns:cbe="http://www.ibm.com/AC/commonbaseevent1_0_1"
     version="1.0.1" creationTime="2015-02-27T16:52:00.713527Z">
 <cbe:sourceComponentId component=" DANBURY" subComponent="from AIRL/airSendLetter force"  
      componentIdType="SystemName" componentType="zTPF Enterprise"  
      location="CO0901B" locationType="Hostname"/>
 <cbe:situation categoryName="OtherSituation">
  <cbe:situationType reasoningScope="INTERNAL"  
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
       xsi:type="cbe:OtherSituation">
   <zTPFSignalEvent/>
  </cbe:situationType>
 </cbe:situation>
 <sendLetter:Event xmlns:sendLetter="http://www.ibm.com/xmlns/prod/ztpf/dfdl/se/sendLetter">
  <sendLetter:EventHeader>
   <ibev:structID xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">C5C8
         </ibev:structID>
   <ibev:version xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">1
         </ibev:version>
   <ibev:eventName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">sendLetter
         </ibev:eventName>
   <ibev:eventType xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">1
         </ibev:eventType>
   <ibev:ssuName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">HPN
         </ibev:ssuName>
   <ibev:eventTime xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">
         2015-02-27T16:52:00.713527Z</ibev:eventTime>
   <ibev:interceptName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">
         from AIRL/airSendLetter force</ibev:interceptName>
  </sendLetter:EventHeader>
  <sendLetter:EventData>
   <overdue:name xmlns:overdue="http://www.ibm.com/xmlns/prod/ztpf/dfdl/user/overdue">
            J. Russell Finch</overdue:name>
   <overdue:employer xmlns:overdue="http://www.ibm.com/xmlns/prod/ztpf/dfdl/user/overdue">
            Pacific Edible Seaweed Company</overdue:employer>
   <overdue:address xmlns:overdue="http://www.ibm.com/xmlns/prod/ztpf/dfdl/user/overdue">
            2790 Penrose Blvd, Fresno Ca, 93701</overdue:address>
   <overdue:email xmlns:overdue="http://www.ibm.com/xmlns/prod/ztpf/dfdl/user/overdue">
            username@example.com</overdue:email>
   <overdue:balance xmlns:overdue="http://www.ibm.com/xmlns/prod/ztpf/dfdl/user/overdue">
            3.5e+04</overdue:balance>
  </sendLetter:EventData>
 </sendLetter:Event>
</cbe:CommonBaseEvent>
The following example shows a sample event message data event that includes a single z/TPFDF LREC in Common Base Event format. The event does not include event ECB context or event user context data.
<?xml version="1.0" encoding="utf-8" ?>
<cbe:CommonBaseEvent xmlns:cbe="http://www.ibm.com/AC/commonbaseevent1_0_1"  
     version="1.0.1" creationTime="2015-01-27T15:13:59.168948Z">
 <cbe:sourceComponentId component=" DANBURY" subComponent="CADB"  
      componentIdType="SystemName" componentType="zTPF Enterprise"  
      location="CO0901B" locationType="Hostname"/>
 <cbe:situation categoryName="OtherSituation">
  <cbe:situationType reasoningScope="INTERNAL" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
       xsi:type="cbe:OtherSituation">
   <zTPFDataEvent/>
  </cbe:situationType>
 </cbe:situation>
 <HotelGuests:Event xmlns:HotelGuests="http://www.ibm.com/xmlns/prod/ztpf/dfdl/de/HotelGuests">
  <HotelGuests:EventHeader>
   <ibev:structID xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">C5C8
         </ibev:structID>
   <ibev:version xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">1
         </ibev:version>
   <ibev:eventName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">HotelGuests
         </ibev:eventName>
   <ibev:eventType xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">2
         </ibev:eventType>
   <ibev:ssuName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">HPN
         </ibev:ssuName>
   <ibev:eventTime xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">2015-01-27T15:13:59.168948Z
         </ibev:eventTime>
   <ibev:interceptName xmlns:ibev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/ibev">CADB
         </ibev:interceptName>
  </HotelGuests:EventHeader>
  <HotelGuests:EventData>
   <HotelGuests:EventDataHdr>
    <cdev:size xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">187
          </cdev:size>
    <cdev:structID xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">C5C4
          </cdev:structID>
    <cdev:version xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">1
          </cdev:version>
    <cdev:dataType xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">1
          </cdev:dataType>
    <cdev:changeType xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">02
          </cdev:changeType>
    <cdev:errFlag xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">00
          </cdev:errFlag>
    <cdev:offsetToData xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">120
          </cdev:offsetToData>
    <cdev:dfsubfile xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">
     <cdev:filename>DR31ED</cdev:filename>
     <cdev:fileID>B231</cdev:fileID>
     <cdev:accessFlags>40</cdev:accessFlags>
     <cdev:controlFlags>00</cdev:controlFlags>
     <cdev:ssName>BSS</cdev:ssName>
     <cdev:ssUserName>HPN</cdev:ssUserName>
     <cdev:primeFA>3494232528</cdev:primeFA>
     <cdev:lrecCount>1</cdev:lrecCount>
     <cdev:sequence>5</cdev:sequence>
     <cdev:timestamp>00CE6B3FD074569D60000000011E0000</cdev:timestamp>
     <cdev:ordinal>116</cdev:ordinal>
     <cdev:partition>0</cdev:partition>
     <cdev:interleave>0</cdev:interleave>
     <cdev:algorithmType>0</cdev:algorithmType>
     <cdev:algorithmPath>0</cdev:algorithmPath>
     <cdev:algorithmLength>0</cdev:algorithmLength>
    </cdev:dfsubfile>
   </HotelGuests:EventDataHdr>
   <HotelGuests:DEVLRECS>
    <HotelGuests:devLrecHdr>
     <cdev:size xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">67
           </cdev:size>
     <cdev:version xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">1
           </cdev:version>
     <cdev:errInd xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">00
           </cdev:errInd>
     <cdev:changeType xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">02
           </cdev:changeType>
     <cdev:lrecID xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">30
           </cdev:lrecID>
     <cdev:sequence xmlns:cdev="http://www.ibm.com/xmlns/prod/ztpf/dfdl/lib/cdev">5
           </cdev:sequence>
    </HotelGuests:devLrecHdr>
    <HotelGuests:prefixedLrec>
     <ns0:LRECPrefix xmlns:ns0="http://www.ibm.com/xmlns/prod/ztpf/dfdl/tpfdf/DR31BI">
      <ns0:size>57</ns0:size>
      <ns0:spare>0000</ns0:spare>
     </ns0:LRECPrefix>
     <ns0:DFLREC xmlns:ns0="http://www.ibm.com/xmlns/prod/ztpf/dfdl/tpfdf/DR31BI">
      <ns0:lrecLength>51</ns0:lrecLength>
      <ns0:lrecKey>30</ns0:lrecKey>
      <ns0:HotelRecord>
       <ns0:Brand>0</ns0:Brand>
       <ns0:Version>1</ns0:Version>
       <ns0:Spare0>000000</ns0:Spare0>
       <ns0:FrequentGuestNumber>10022</ns0:FrequentGuestNumber>
       <ns0:FullName>
        <ns0:FirstName>RIDLEY</ns0:FirstName>
        <ns0:LastName>EARHART</ns0:LastName>
       </ns0:FullName>
       <ns0:Spare/>
       <ns0:Balance>5.368709e+08</ns0:Balance>
       <ns0:Comments>N/A</ns0:Comments>
      </ns0:HotelRecord>
     </ns0:DFLREC>
    </HotelGuests:prefixedLrec>
   </HotelGuests:DEVLRECS>
  </HotelGuests:EventData>
 </HotelGuests:Event>
</cbe:CommonBaseEvent>