NAME

       opaxmlextract

       (Linux)  Extracts  element  values  from  XML  input and outputs the data in CSV format. opaxmlextract is
       intended to be used with opareport, to parse and filter its XML output, and to allow the filtered  output
       to be imported into other tools such as spreadsheets and customer-written scripts. opaxmlextract can also
       be used with any well-formed XML stream to extract element values into a delimited format.

       Five  sample  scripts  are  available as prototypes for customized scripts. They combine various calls to
       opareport with a call to opaxmlextract with commonly used parameters.

Syntax

       opaxmlextract [-v][-H][-d  delimiter][-e  extract_element]

       [-s  suppress_element][-X  input_file] [-P  param_file]

Options

       --help

                 Produces full help text.

       -v/--verbose

                 Produces verbose  output.  Includes  output  progress  reports  during  extraction  and  output
                 prepended wildcard characters on element names in output header record.

       -H/--noheader

                 Does not output element name header record.

       -d/--delimit delimiter

                 Uses  single  character  or  string  as the delimiter between element names and element values.
                 Default is semicolon.

       -e/--extract extract_element

                 Specifies the name of the XML element to extract. Elements can be nested in any order, but  are
                 output  in  the  order  specified.  Elements  can be specified multiple times, with a different
                 attribute name or attribute value. An optional attribute (or attribute and value) can  also  be
                 specified with elements:

                 •      -e element

                 •      -e element:attrName

                 •      -e element:attrName:attrValue

              NOTE:

              •      Elements  can  be  compound values separated by a dot. For example, Switches.Node is a Node
                     element contained within a Switches element.

              •      To output the attribute value as opposed to the element value, a specification such  as  -e
                     FIs.Node:id  can  be  used.  This  will  return  the  value of the id attribute of any Node
                     elements within FIs element.

              •      If desired, a specific element  can  be  selected  by  its  attribute  value,  such  as  -e
                     MulticastFDB.Value:LID:0xc000  which  will  return  the  value  of the Value element within
                     Multicast FDB element where the Value element has an attribute  of  LID  with  a  value  of
                     0xc000.

              •      A  given  element  can  be  specified  multiple  times  each  with  a different AttrName or
                     attrValue.

       -s/--suppress suppress_element

                 Specifies the name of the XML element to suppress extraction. Can be used  multiple  times  (in
                 any order). Supports the same syntax as -e.

       -X/--infile input_file

                 Parses XML from input_file.

       -P/--pfile param_file

                 Reads command parameters from param_file.

Example

       Here is an example of opareport output filtered by opaxmlextract :

       # opareport -o comps -s -x | opaxmlextract -d ; -e NodeDesc

       -e SystemImageGUID -e NumPorts -s Neighbor

       Getting All Node Records...

       Done Getting All Node Records

       Done Getting All Link Records

       Done Getting All Cable Info Records

       Done Getting All SM Info Records

       Getting All Port Counters...

       Done Getting All Port Counters

       NodeDesc;SystemImageGUID;NumPorts

       phs1fnivd13u07n4 hfi1_0;0x00117501016033c7;1

       phs1fnivd13u07n2 hfi1_0;0x00117501016033ef;1

       phs1fnivd13u07n1 hfi1_0;0x001175010160347a;1

       phs1fnivd13u07n3 hfi1_0;0x0011750101603593;1

       phs1swivd13u21;0x00117501ff6a5619;48

       phs1fnivd13u07n1 hfi1_0;;

Details

       opaxmlextract is a flexible and powerful tool to process an XML stream. The tool:

       •      Requires no specific element names to be present in the XML.

       •      Assumes no hierarchical relationship between elements.

       •      Allows extracted element values to be output in any order.

       •      Allows an element's value to be extracted only in the context of another specified element.

       •      Allows extraction to be suppressed during the scope of specified elements.

       opaxmlextract  takes the XML input stream from either stdin or a specified input file. opaxmlextract does
       not use or require a connection to a fabric.

       opaxmlextract works from two lists of elements supplied as command line or input parameters. The first is
       a list of elements whose values are to be extracted, called extraction elements. The second is a list  of
       elements  for  which  extraction  is  to  be  suppressed, called suppression elements. When an extraction
       element is encountered and extraction is not suppressed, the value of the element is extracted for  later
       output  in  an  extraction  record.  An  extraction  record contains a value for all extraction elements,
       including those which have a null value.

       When a suppression element is encountered, then no extraction is performed  during  the  extent  of  that
       element,  from start through end. Suppression is maintained for elements specified inside the suppression
       element, including elements which may happen to match extraction elements. Suppression  can  be  used  to
       prevent  extraction  in  sections  of  XML  that  are  present, but not of current interest. For example,
       NodeDesc or NodeGUID inside a Neighbor specification of opareport.

       opaxmlextract attempts to generate extraction records with data values that are valid at the  same  time.
       Specifying  extraction  elements that are valid in the same scope produces a single record for each group
       of extraction elements. However, mixing extraction elements from different  scopes  (including  different
       XML levels) may cause opaxmlextract to produce multiple records.

       opaxmlextract outputs an extraction record under the following conditions:

       •      One  or more extraction elements containing a non-null value go out of scope (that is, the element
              containing the extraction elements is ended) and a record containing the element  values  has  not
              already been output.

       •      A  new  and  different  value  is  specified  for  an  extraction element and an extraction record
              containing the previous value has not already been output.

       Element names (extraction or suppression) can be made context-sensitive with an  enclosing  element  name
       using  the  syntax  element1.element2.  In this case, element2 is extracted (or extraction is suppressed)
       only when element2 is enclosed by element1.

       The syntax also allows ' * ' to be specified as a wildcard. In this case, *.element3  specifies  element3
       enclosed    by   any   element   or   sequence   of   elements   (for   example,   element1.element3   or
       element1.element2.element3). Similarly, element1.*.element3 specifies element3 enclosed by element1  with
       any number of (but at least 1) intermediate elements.

       opaxmlextract  prepends  any entered element name not containing a ' * ' (anywhere) with ' *. ', matching
       the element regardless of the enclosing elements.

       NOTE: Any element names that include a wildcard should be quoted to  the  shell  attempting  to  wildcard
       match against filenames.

       At  the  beginning  of operation, opaxmlextract, by default, outputs a delimited header record containing
       the names of the extraction elements. The order of the names is the same as specified on the command line
       and is the same order as that of the extraction record. Output of the header record can be disabled  with
       the  -H  option.  By  default,  element  names are shown as they were entered on the command line. The -v
       option causes element names to be output as they are used during extraction, with any prepended  wildcard
       characters.

       Options  (parameters)  to  opaxmlextract  can be specified on the command line, with a parameter file, or
       using both methods. A parameter file is specified with -P param_file. When a parameter file specification
       is encountered on the command line, option processing on the command line  is  suspended,  the  parameter
       file is read and processed entirely, and then command line processing is resumed.

       Option  syntax  within  a  parameter  file  is  the  same as on the command line. Multiple parameter file
       specifications can be made, on the command line or within other parameter files. At  each  point  that  a
       parameter  file  is  specified,  current  option  processing  is  suspended  while  the parameter file is
       processed, then resumed. Options are processed in the order they are encountered on the command  line  or
       in  parameter  files.  A  parameter  file  can  be  up  to  8192  bytes in size and may contain up to 512
       parameters.

Copyright(C) 2015-2019                          Intel Corporation                               opaxmlextract(8)