/ 
DB2-Admin-3.1
River stage zero No dependents
/ DB2::Admin::DataStream

NAME

DB2::Admin::DataStream - Support for DB2 self-describing data stream

SYNOPSIS

use DB2::Admin::DataStream;

#
# Get binary data from snapshot or event file/pipe, then...
#
my $stream = DB2::Admin::DataStream::->new($binary_data);

#
# For quick and dirty formatting (or figuring out the format)
#
print $stream->Format();

#
# Access to a particular node (two alternatives)
#
my $node = $stream->findNode('SWITCH_LIST/UOW_SWITCH/SWITCH_SET_TIME/SECONDS');
my $time_sec = $node->getValue();
my $time_msec = $stream->findValue('SWITCH_LIST/UOW_SWITCH/SWITCH_SET_TIME/MICROSEC');

#
# Access to many similar nodes
#
my @appl_info = $stream->findNodes('APPL/APPL_INFO');

#
# Access to child nodes
#
my @children = $stream->getChildnodes();
my $name = $children[0]->getName();
my $desc = $children[0]->getDescription();

#
# Access to all direct data elements of a node (hash-reference)
#
my $values = $node->getValues();

DESCRIPTION

The DB2 administrative API returns several types of return values in a so-called 'self-describing data stream'. The data stored in event files or written to event pipes is in the same format. The data format and all element types plus their values, are described in the "System Monitor Guide and Reference" (SC09-4847).

This module provides a method to decode this data stream and convert it to a perl object that provides access to the data. The code postpones the work decoding the data until is is queried for, which in most cases is considerably faster than decoding it all upfront.

Access is provided using an API loosely moduled after XML::LibXML, though it intentionally is far less powerful. Like an XML document, the data stream is a hierarchical tree. Each node in the tree is a Db2API::DataStream object; the leaves actually hold the data and are DB2::Admin::DataElement objects.

METHODS

new

This method receives a binary datastream and creates a DB2::Admin::DataStream object. Later accesses to the object will cause it to create child objects of both the DB2::Admin::DataStream and DB2::Admin::DataElement classes.

getName

This method returns the name of a node, e.g. 'DBASE'. The DB2::Admin::DataElement class supports the same method, so this can safely be invoked on any object.

getDescription

This method returns the description of a node, e.g. 'database information'. This description is parsed from the DB2 header files at DB2::Admin module compile time. The DB2::Admin::DataElement class supports the same method, so this can safely be invoked on any object.

getChildnodes

This method returns all children of the current node, which can be a mixture of DB2::Admin::DataStream and DB2::Admin::DataElement objects. This is only useful when traversing all data or when the contents of the data is unknown; in most cases, the findNode, findNodes or findValue methods should be used instead.

getValues

This method returns a hash-reference with the names and display values of all direct children that are leaf nodes (DB2::Admin::DataElement). This is useful for those tree nodes that are known to be containers for a set of leaves, e.g. 'DBASE' or 'APPL_INFO'. If you need to process a large number of data elements that are all children of the same node, this is the most efficient method to get at the data.

findNode

This method returns the first node that matches a path expression. It is related to findNodes, which returns all nodes matching an expression, and findValue, which returns the value of the first node matching an expression.

In order to explain path expressions, suppose an application snapshot contains the following data (the example uses simplified Format output):

- DATA_COLLECTED
  - APPL
    - APPL_INFO
      - APPL_ID: appl_info_1
      - AGENT_ID: 12
      ... data omitted ...
    - OTHER_APPL_DATA
    - MORE_APPL_DATA
  - APPL
    - APPL_INFO
      - APPL_ID: appl_info_2
      - AGENT_ID: 20
      ... data omitted ...
    - OTHER_APPL_DATA
    - MORE_APPL_DATA

Starting with the main 'DATA_COLLECTED' node, which is returned by the GetSnapshot method, there are multiple 'APPL' nodes, each of which contains an 'APPL_INFO' node, which in turn contains leaf elements for 'APPL_ID' and 'AGENT_ID'.

For the above data, the following can be done:

my $node1 = $snapshot->findNode('APPL/APPL_INFO'); # First APPL node's APPL_INFO node
my $agent_id = $appl_info->findNode('AGENT_ID')->getValue(); # 12
my $appl_id = $appl_info->findValue('APPL_ID'); # appl_info_1
my @all_appl_info = $snapshot->findNodes('APPL/APPL_INFO'); # All APPL_INFO nodes

When following a path, these methods all start looking at the children of the current DB2::Admin::ParseStream object. Each forward slash implies a single step further down the hierarchical tree. The results may be DB2::Admin::DataStream or DB2::Admin::DataElement objects; the former can be used for further searches, while the latter can be used to get values.

findNodes

This method returns all nodes that matche a path expression. It is related to findNode, which returns the first node matching an expression, and findValue, which returns the value of the first node matching an expression. See findNode for more details.

findValue

This method returns the value of the first node that matches a path expression. It is related to findNode, which returns the first node matching an expression, and findNodes, which returns all nodes matching an expression. See findNode for more details.

Format

This method takes a DB2::Admin::DataStream object and returns a string suitable for display purposes. This is useful to study the data structure when writing or debugging applications.

AUTHOR

Hildo Biersma

SEE ALSO

DB2::Admin(3), DB2::Admin::Constants(3), DB2::Admin::DataElement(3)