opaxmlextract(8)

💖 NAME 💖

opaxmlextract — bestie, this is the Linux tool that extracts element values from XML input and spits the data back out in CSV format. ✨

She's built to hang out with opareport — like, she parses and filters its XML output so you can import the filtered stuff into other tools (spreadsheets, your own customer-written scripts, whatever slays). But also? She works with any well-formed XML stream to pull element values into a delimited format. Versatile queen. 👑

Also there are five sample scripts available as prototypes for customized scripts — they mix up various calls to opareport with a call to opaxmlextract using the commonly-used parameters. 🎀

🌸 SYNTAX 🌸

opaxmlextract [-v][-H][-d  delimiter][-e  extract_element]
[-s  suppress_element][-X  input_file] [-P  param_file]

✨ OPTIONS ✨

• --help — gives you the full help text. no gatekeeping. 🫶
• -v / --verbose — turns on verbose output. That means progress reports during extraction, plus the output gets prepended wildcard characters on element names in the output header record. she's telling you everything, fr fr.
• -H / --noheader — no element name header record. she just doesn't output it. bye header. 💅
• -d / --delimit delimiter — picks a single character or string to be the delimiter between element names and element values. Default? semicolon. classic.
• -e / --extract extract_element — names the XML element you want to extract. Elements can be nested in any order, but they come out in the order specified. You can specify elements multiple times, each with a different attribute name or attribute value. And you can tack on an optional attribute (or attribute and value) with the elements, like so:
  • -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 instead of the element value, use a spec like -e FIs.Node:id. This returns the value of the id attribute of any Node elements inside the FIs element. - If you want, you can select a specific element by its attribute value, like -e MulticastFDB.Value:LID:0xc000 — which returns the value of the Value element within the 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. she contains multitudes.

• -s / --suppress suppress_element — names the XML element where extraction gets suppressed. Can be used multiple times (in any order), and it supports the same syntax as -e.
• -X / --infile input_file — parses the XML from input_file.
• -P / --pfile param_file — reads the command parameters from param_file.

🌈 EXAMPLE 🌈

Okay so here's an example of opareport output being 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;;

look at that null value at the end just chilling. iconic. 🦋

💜 DETAILS 💜

opaxmlextract is a flexible and powerful tool for processing an XML stream. The way she moves:

• She requires no specific element names to be present in the XML.
• She assumes no hierarchical relationship between elements.
• She lets extracted element values be output in any order.
• She lets an element's value be extracted only in the context of another specified element.
• She lets extraction be suppressed during the scope of specified elements.

opaxmlextract takes the XML input stream from either stdin or a specified input file. She does not use or require a connection to a fabric. independent queen, no fabric needed. 💅

She works off of two lists of elements, supplied as command line or input parameters:

1. The list of elements whose values are to be extracted — the extraction elements.
2. The list of elements for which extraction is to be suppressed — the suppression elements.

When an extraction element is encountered and extraction isn't suppressed, the value of that element is extracted for later output in an extraction record. An extraction record contains a value for all extraction elements — including the ones with a null value. no one gets left out. 🫶

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 is how you 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 tries 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. But — and this is the plot twist — mixing extraction elements from different scopes (including different XML levels) may cause opaxmlextract to produce multiple records. 😭

So she outputs an extraction record under these 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 that 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. protect her from the shell bestie. 😭

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 it's 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. it's giving pause-and-resume energy. ⏸️▶️

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. know the limits bestie. 💅

Copyright(C) 2015-2019 Intel Corporation — and that's the whole page, from the IFSFFCLIRG man page era, opaxmlextract(8). go forth and extract, my love. 🦋💖✨