.\" .\" *********************************************************************
.\" .\" *                                                                   *
.\" .\" *             Copyright 2020-2022, Intel Corporation                *
.\" .\" *                                                                   *
.\" .\" *                       All Rights Reserved.                        *
.\" .\" *                                                                   *
.\" .\" *********************************************************************

.TH ethxmlgenerate 8 "Intel Corporation" "Copyright(C) 2020\-2022" "EFSFFCLIRG (Man Page)"
.SH NAME
ethxmlgenerate


.PP
Takes comma-separated-values (CSV) data as input and generates sequences of XML containing user-specified element names and element values within start and end tag specifications. Use this tool to create an XML representation of fabric data from its CSV form.
.SH Syntax
ethxmlgenerate [-v] [-d  \fIdelimiter\fR] [-i  \fInumber\fR] [-g  \fIelement\fR]
.br

[-h  \fIelement\fR] [-e  \fIelement\fR] [-X  \fIinput\(ulfile\fR] [-P  \fIparam\(ulfile\fR]
.SH Options

.TP 10
--help

Produces full help text.

.TP 10
-g/--generate \fIelement\fR

Generates value for \fIelement\fR using value in next field from the input file. Can be used multiple times on the command line. Values are assigned to elements in order.

.TP 10
-h/--header \fIelement\fR

Name of the XML element that is the enclosing header start tag.

.TP 10
-e/--end \fIelement\fR

Name of the XML element that is the enclosing header end tag.

.TP 10
-d/--delimit \fIdelimiter\fR

Specifies the delimiter character that separates values in the input file. Default is semicolon.

.TP 10
-i/--indent \fInumber\fR

Number of spaces to indent each level of XML output. Default is 0.

.TP 10
-X/--infile \fIinput\(ulfile\fR

Generates XML from CSV in input\(ulfile. One record per line with fields in each record separated by the specified delimiter.

.TP 10
-P/--pfile \fIparam\(ulfile\fR

Uses input command line options (parameters) from param\(ulfile.

.TP 10
-v/--verbose

Produces verbose output. Includes output progress reports during extraction.


.SH Details

.PP
ethxmlgenerate takes the CSV data from an input file. It generates fragments of XML, and in combination with a script, can be used to generate complete XML sequences. ethxmlgenerate does not use nor require a connection to an Intel(R) Ethernet Fabric.
.PP
ethxmlgenerate reads CSV element values and applies element (tag) names to those values. The element names are supplied as command line options to the tool and constitute a template that is applied to the input.
.PP
Element names on the command line are of three (3) types, distinguished by their command line option - Generate, Header, and Header\(ulEnd. The Header and Header\(ulEnd types together constitute enclosing element types. Enclosing elements do not contain a value, but serve to separate and organize Generate elements.
.PP
Generate elements, along with a value from the CSV input file, cause XML in the form of <element\(ulname> \fIvalue\fR</element\(ulname> to be generated. Generate elements are normally the majority of the XML output since they specify elements containing the input values. Header elements cause an XML header start tag of the form: <element\(ulname> to be generated. Header\(ulEnd elements cause an XML header end tag of the form </element\(ulname> to be generated. Output of enclosing elements is controlled entirely by the placement of those element types on the command line. ethxmlgenerate does
\fBnot\fR
check for matching start and end tags or proper nesting of tags.
.PP
Options (parameters) to ethxmlgenerate can be specified on the command line, with a parameter file, or both. A parameter file is specified with -P \fIparam\(ulfile\fR. 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.

.SH Using ethxmlgenerate to Create Topology Input Files

.PP
ethxmlgenerate can be used to create scripts to translate from user-specific format into the ethreport topology\(ulinput file format. ethxmlgenerate itself works against a CSV style file with one line per record. Given such a file it can produce hierarchical XML output of arbitrary complexity and depth.
.PP
The typical flow for a script which translates from a user-specific format into ethreport topology\(ulinput would be:
.IP \(bu
As needed, reorganize the data into link and node data CSV files, in a sequencing similar to that used by ethreport topology\(ulinput. One link record per line in one temporary file and one node record per line in another temporary file.
.IP \(bu
The script must directly output the boilerplate for XML version, etc.
.IP \(bu
ethxmlgenerate can be used to output the Link section of the topology\(ulinput, using the link record temporary file.
.IP \(bu
ethxmlgenerate can be used to output the Node sections of the topology\(ulinput using the node record temporary file. If desired, there could be separate node record temporary files for NIC s and Switches.
.IP \(bu
The script must directly output the closing XML tags to complete the topology\(ulinput file.
