Running XBinder from the Command-line

---

The XBinder distribution contains a command-line compiler executable as well as a graphical user interface (GUI) wizard that can aid in the specification of compiler options. This section describes how to run the command-line version; the operation of the GUI is described in the online help files built into the wizard.

To test if XBinder was successfully installed, enter xbinder with no parameters as follows (note: if you have not updated your PATH variable, you will need to enter the full pathname):

	xbinder
 

You should observe the following display (or something similar):

 
XBinder Compiler, Version 1.4.x
 
Copyright (c) 2002-2008 Objective Systems, Inc. All Rights Reserved.
 

 
Usage: xbinder <filename> options
 

 
    <filename>         XML schema or WSDL source file name(s).
 
                         Multiple filenames may be specified.
 
                         * and ? wildcards are allowed.
 

 
  Basic options:
 
    -xml               Generate XML encode/decode functions
 
    -dom               Generate DOM encode/decode functions (C only)
 
    -sax               Generate SAX-based decoders (default is pull-parser)
 
    -c                 Generate C code
 
    -c++ or -cpp       Generate C++ code
 
    -config <file>     Specify schema bindings file.
 
    -nodecode          Do not generate decode functions
 
    -noencode          Do not generate encode functions
 
    -o <directory>     Output file directory
 
    -I <directory>     Import file directory
 
    -all               Compile all dependent files
 
    -modularize        Handle included schemas as separate modules
 
    -warnings          Output compiler warning messages
 
    -trace             Add trace diag msgs to generated code
 
    -compat <version>  Generate code compatible with previous
 
                         compiler version. <version> format is 
 
                         x.x (for example, 1.0)
 

 
  Options to reduce amount of generated code:
 
    -lax               Generate code that does lax error checking
 
    -nocopy            Do not generate copy methods (C++ only)
 
    -noderiv           Do not generate special derived type code
 
    -noheader          Do not add code to encode XML header (<? xml ...)
 
    -noxmlns           Do not generate namespace attributes in all structs
 

 
  Options to alter generated code:
 
    -c14n              Generate C14N format encode functions
 
    -cppns <ns>        Add given C++ namespace to generated code (C++ only)
 
    -fragments         Generate code to encode XML fragments
 
                         (start element, contents, end element)
 
    -static            Generate code that uses static memory
 
                         (when possible, C only)
 
    -initlists         Generate code that initializes lists to default
 
                         (when possible)
 
    -namespace         Specify a namespace prefix for all generated items
 
    -nodatestamp       Do not put date stamp in header
 
    -nomixed           Do not generate string structure for mixed content
 
    -numDateTime       Use numeric structures for all date/time types
 
    -pdu <element>     Designate element to be a PDU
 
    -elemCasing <value> Set element name case to lower/upper
 
    -typeCasing <value> Set type name case to lower/upper
 
    -soap, -soap12     Generate code to format/parse SOAP v1.2 messages
 
    -soap11            Generate code to format/parse SOAP v1.1 messages
 
    -strict            Generate code that does strict syntax checking
 
    -useNSPfx          Use XSD namespace prefixes in C/C++ code
 
    -useflteq          Use float equality functions to ignore rounding
 
                         errors in floating-point comparisons
 
    -usestl            Use C++ Standard Template Library (STL)
 

 
  Options for the generation of additional code:
 
    -genMake           Generate makefile 
 
    -genWriter         Generate writer test program
 
    -genReader         Generate reader test program
 
    -genFree           Generate memory free functions (C only)
 
    -genPrint          Generate print functions
 
    -genRWTest         Generate read/write test program
 
    -genStubs          Generate web service client functions from WSDL
 
    -genTest [<xmlfile>]  Generate test code.  If XML instance provided,
 
                          this will be used; otherwise, random data
 
    -genValid          Generate validation functions
 
    -usePDU <element>  Use PDU for writer/reader test program
 
    -w32               Use with '-genMake' to generate Windows NMAKE file
 
                         (default = GNU)
 

 
  Compression options:
 
    -exi               Add code to generated reader/writer to use
 
                         Efficient XML Interchange (EXI) format
 
    -zip               Add code to generated reader/writer to use
 
                         standard gzip compression (requires zlib install)
 

 

To use the compiler, at a minimum, a single XSD or WSDL source file must be provided along with at least one set of encoding rules and a target output language. The current version of XBinder supports the generation of C (-c option) or C++ (-cpp option) source code and the generation of code to encode/decode XML (-xml).

The source file specification can be a full pathname or only what is necessary to qualify the file. If directory information is not provided, the user's current default directory is assumed. Multiple source filenames may be specified on the command line to compile a set of files. The wildcard characters `*' and `?' are also allowed in source filenames (for example, the command `xbinder *.xsd -c -xml' will compile all XSD files in the current working directory).

The following table lists all of the command line options in alphabetical order and what they are used for:

Option	Argument	Description
-all	None	This option is used to tell the compiler to generate code for all dependent files in a given compilation. This includes the main XSD files specified on the command line as well as all imported and included schema files.
-c	None	Generate C source code.
-c++ -cpp	None	Generate C++ source code.
-c14n	None	This option instructs the compiler to generate encode functions which use Canonical XML (http://www.w3.org/TR/xml-c14n) mode by default.
-cppns	<name>	This option causes the given name to be added to generated C++ code as a C++ namespace declaration.
-compat	<version>	This option causes code to be generated that is compatible with an older version of the XBinder compiler. The format of the version number is "n.n" (for example, 1.0).
-config	<filename>	This option is used to specify the name of a file containing configuration information for the source file being parsed. This is similar to the `binding schema' used with some other XML data binding applications.
-dom	None	Encode to or decode from a Document Object Model (DOM) tree structure instead of directly to/from XML text format. This allows processing unique to DOM to be done prior to serialization/deserialization (for example, XPath searches).   Note that this option is currently only available with C code generation (not C++).
-elemCasing	lower or upper	This option is used to change the case of the first letter in element names in the C or C++ code from what is specified in the XSD file. This option is typically used when the XSD file contains type, element, and/or attribute names that are the same. It provide a way to make the name disambiguous in the generated C or C++ code. Typically, element names are set to lower case.   See -typeCasing for changing the case of type names.
-exi	None	This option is used to add API calls to generated reader and writer programs to convert XML data to and from Efficient XML Interchange (EXI) format as described in http://www.w3.org/TR/2007/WD-exi-20070716/.
-fragments	None	This option is used to generate additional encode functions that allows fragments (parts) of an XML document to be created without having to create an entire document. The start element, contents, and end element fragments for any given type can be created using these functions. This is useful for stream-oriented protocols such as XMPP.
-genfree	None	This option instructs the compiler to generate memory free utility functions. Memory free functions are C functions that allow all memory within a given structure to be freed. It is possible to free memory without these functions by using the rtxMemFree function on a context. This frees all memory held by the context. But some applications require the capability to free the memory associated with a given structure.
-genmake	None	This option is used to generate a makefile to build the generated code. The makefile is compatible with either the GNU make utility or the Visual Studio nmake utility. A Windows Visual Studio nmake file is generated if -w32 is added to the command-line.
-genreader	None	This option is used to generate a complete reader program similar to what can be found in the sample subdirectory. This program will read an encoded XML document from an input file, decode it, and then print the decoded field values to standard output.
-genrwtest	None	This option is used to generate a read/write test program. This program will read an XML document corresponding to a specified global element definition in the compiled schema document, decode it, and then re-encode it and write it to an output file.
-gentest	<xmlfile> (optional)	This option instructs the compiler to generate test utility functions. Test functions populate an instance of each global element defined within a schema with random test data to be encoded. The functions provide a good template for writing code to populate the generated programatic variables. The functions are written to <modulename>Test.c files where <modulename> is the base name of the XSD source file that was parsed.   If the optional XML filename argument is provided, the generated test functions will use data from the given XML instance instead of generating random test data.
-genstubs	None	This option instructs the compiler to generate stub functions. A "stub", in web service terms, is a function that works like a remote procedure call. It sends a request to a server and then turns around and waits for a response. The stub functions can be called from a test client program for a web service. The functions are written to the <modulename>WSDLSoapClientStubs.c file where <modulename> is the base name of the WSDL source file that was parsed.
-genvalid	None	This option is used to generate validation functions. These functions are used to validate a given XML instance against the compiled schema. The functions are written to <modulename>Vldt.c files where <modulename> is the base name of the XSD source file that was parsed.
-genwriter	None	This option is used to generate a complete writer test program similar to what can be found in the sample subdirectory. This program will populate a record with test data, encode the data into XML, and then write the encoded record to an output file.
-I	<directory>	This option is used to specify a directory that the compiler will search for XSD <import> and <include> items. Multiple -I qualifiers can be used to specify multiple directories to search.
-initlists	None	This option instructs the compiler to generate InitLists_ functions for complex types which have a repeating element with a default value.
-lax	None	This option causes decode/validation functions to be generated that contain less schema-validation error checking code. This can be useful for working with XML documents that are not completely valid with regards to the schema.
-modularize	None	This option is used when XSD <include> directives are included in a schema to tell the processor to put the generated code in separate output files based on the include file names. The default behavior if this is not used is to include all of the code in the main file that is including the definitions. This can only be used if the included files can be successfully compiled on their own (i.e. are not dependent on definitions from the parent module).
-namespace	<prefix>	This option causes a prefix to be prepended to all generated items (typedefs and functions). This makes it possible to disambiguate items with the same names that are in different schemas. Note that the -useNSPfx option can be used to use namespace prefixes that are defined in the XSD document for this purpose (see the description of this option below).
-nodatestamp	None	This option instructs the compiler not to insert a date stamp in the header of each generated file. It can be useful when using a source control system to prevent identical source files from appearing different.
-noencode	None	This option suppresses the generation of encode functions.
-nodecode	None	This option suppresses the generation of decode functions.
-noderiv	None	This option suppresses the generation of extra code for run-time derived type handling. This code makes it possible to decode complexContent types using xsi:type declarations.
-noheader	None	This option suppresses the generation of code within the encode functions to add the XML header line to generated documents. This is the first line in the document that begins with `<?xml'.
-nomixed	None	This option suppresses generation of a structure which can hold mixed content. The generated code will more closely match the schema layout. However, mixed content will not be supported.
-noxmlns	None	This option suppresses the generation of namespace attribute lists in all generated C structures. In general, advanced namespace processing is not needed for many applications and the addition of the namespace attributes lists adds a considerable amount of size to the code.
-numDateTime	None	This option causes numeric date/time structures to be used for all XSD data/time types (date, time, dateTime). The default is to use strings for these items.
-o	<directory>	This option is used to specify the name of a directory to which all of the generated files will be written.
-pdu	<element>	This option tells the compiler to recognize the given global element as a protocol data unit (PDU). A PDU is a main message type in the module for which encode and decode functions are generated. By default, the compiler only recognizes non-referenced global elements as PDU's. This allows this default behavior to be overridden.
-print	None	This option instructs the compiler to generate print utility functions. Print functions are debug functions that allow the contents of generated type variables to be written to stdout. The functions are written to <modulename>Print.c files where <modulename> is the base name of the XSD source file that was parsed.
-sax	None	This option causes SAX handlers to be generated for decoding XML documents. Prior to XBinder version 1.2, this was the default (and only) method for decoding XML messages. XBinder 1.2 uses a pull-parser by default for XML decoding.
-soap	None	This option causes additional code to be generated to add or parse SOAP envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP client or server application. The version of SOAP supported by this option is set to the highest version currently supported by the application. This is currently version 1.2.
-soap11	None	This option causes additional code to be generated to add or parse SOAP 1.1 envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP 1.1 client or server application.
-soap12	None	This option causes additional code to be generated to add or parse SOAP 1.2 envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP 1.2 client or server application.
-static	None	This option instructs the compiler to use static memory whenever possible when generating C source code. The array's size will be determined by the type's maxLength or length facet.
-trace	None	This option is used to tell the compiler to add trace diagnostic messages to the generated code. These messages cause printf statements to be added to the generated code to print entry and exit information into the generated functions. This is a debugging option that allows encode/decode problems to be isolated to a given production processing function. Once the code is debugged, this option should not be used as it adversely affects performance.
-typeCasing	lower or upper	This option is used to change the case of the first letter in type names in the C or C++ code from what is specified in the XSD file. This option is typically used when the XSD file contains type, element, and/or attribute names that are the same. It provides a way to make the name disambiguous in the generated C or C++ code. Typically, type names are set to upper case.   See -elemCasing for changing the case of element names.
-useNSPfx	None	This option instructs the compiler to add the namespace prefixes defined in the XSD source files to the generated C/C++ names. The format of the names generated when this is specified is <prefix>_<name>. This is useful when an XSD specification consists of multiple shemas defined in multiple namespaces and the same names are used for entities across the specifications but within different namespaces. This prevents name collisions in the generated code at the expense of creating more verbose names.
-useflteq	None	This option instructs the compiler to generate code which uses functions that account for a small margin of error to compare floating-point numbers.
-usepdu	<element>	This option causes the given protocol data unit (i.e. global element) to be used as the basis for generated reader and writer programs. If not specified and the compiled schema contains multiple unreferenced global elements, a type will be chosen at random.
-usestl	None	This option instructs the compiler to use Standard Template Library (STL) classes in the generation of C++ code. By default, STL is not used in generated code.
-warnings	None	Output information on compiler generated warnings.
-w32	None	This option causes the compiler to make adjustments to the code generation that are specific to the Windows operating system. For example the backslash character (\) is used as a path separator instead of forward slash (/). The format of the generated makefile is also in Visual Studio nmake format (see -genmake above).
-xml	None	Generate encode/decode functions that marshall programatic data to and from XML format.
-zip	None	This option causes the compiler to add standard gzip compression function calls to generated reader and writer programs. It requires that zlib be installed on the target system.