Running XBinder from the Command-line

Running XBinder from the Command-line
Prev	Chapter 2. Using XBinder	Next

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 2.2.x
Copyright (c) 2002-2010 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.

  Language options (choose only one):
    -c                 Generate C code
    -c++ or -cpp       Generate C++ code
    -c# or -csharp     Generate C# code
    -java              Generate Java code

  Basic options:
    -xml               Generate XML encode/decode functions
    -config <file>     Specify schema bindings file.
    -o <directory>     Output file directory
    -I <directory>     Import file directory
    -all               Compile all dependent files
    -warnings          Output compiler warning messages
    -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
    -noderiv           Do not generate special derived type code

  Options to alter generated code:
    -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
    -elemCasing <value> Set element name case to lower/upper
    -typeCasing <value> Set type name case to lower/upper

  Options for the generation of additional code:
    -genPrint or
    -print             Generate print functions

  C/C++ basic options:
    -dom               Generate DOM encode/decode functions (C only)
    -json              Generate JSON encode/decode functions (C only)
    -sax               Generate SAX-based decoders (default is pull-parser)
    -modularize        Handle included schemas as separate modules
    -nodecode          Do not generate decode functions
    -noencode          Do not generate encode functions
    -trace             Add trace diag msgs to generated code

  C/C++ options to reduce amount of generated code:
    -compact           Generate compact code
    -nocopy            Do not generate copy methods (C++ only)
    -noheader          Do not add code to encode XML header (<? xml ...)
    -noxmlns           Do not generate code to support XML namespaces

  C/C++ options to alter generated code:
    -borland           Generate special code for Borland C++ compiler
    -c14n              Generate C14N format encode functions
    -cppns <ns>        Add given C++ namespace to generated code (C++ only)
    -derivModel <model>  Set the derivation model to extended/interface
    -enumchoice        Generate enum type for type selector for choice types
    -fragments         Generate code to encode XML fragments
                         (start element, contents, end element)
    -initlists         Generate code that initializes lists to default
                         (when possible)
    -noEncDefault      Do not add schema default/fixed values to XML instance
    -noDefaultNs       Do not use default namespace in XML instance
    -noNamedBits       Do not generate named bits for EnumList, 
                         use regular list instead
    -numDateTime       Use numeric structures for all date/time types
    -pdu <element>     Designate element to be a PDU
    -project <prj_name> Set project name
    -soap, -soap12     Generate code to format/parse SOAP v1.2 messages
    -soap11            Generate code to format/parse SOAP v1.1 messages
    -static            Generate code that uses static memory
                         (when possible, C only)
    -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)
                         (currently, only STL string type is used)
    -noenumvars        Do not generate fields using generated enum types;
                         revert to prior behavior (generate OSUINT16 instead)
                         

  C/C++ options for the generation of additional code:
    -genWriter         Generate writer test program
    -genReader         Generate reader test program
    -genFree           Generate memory free functions (C only)
    -genFactory        Generate Factory functions
    -genRWTest         Generate read/write test program
    -genStubs          Generate SOAP client stub functions from WSDL
    -genSkel           Generate SOAP skeleton server program from WSDL
    -genClient         Generate web service client test program from WSDL
    -genSSLClient      Generate a secure HTTP client test program using OpenSSL
    -genSSLStubs       Generate secure HTTP stub functions using OpenSSL
    -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)

  C/C++ options for makefile or project generation:
    -genMake           Generate makefile 
    -genMakeLib [<libname>]  Generate code in makefile to put all objects
                             into a static library 
    -genMakeDLL [<dllname>]  Generate code in makefile to build shared object
    -genvcproj [<version>]  Generate Visual Studio project files
                            [<version>] is 2012, 2010, 2008, 2005, 2003, vc6 (Windows only)
    -makeopts <dynamiclib | staticlib | multithreaded>
         Use compilation options for dynamic, static, and multithreaded
         libraries.

  C/C++ compression options:
    -zip               Add code to generated reader/writer to use
                         standard gzip compression (requires zlib install)

  C# extra options:
    -csfile <name>     Specifies one .cs file for all generated code
                       Set <name> to '*.cs' for one .cs file per .xsd file
    -csnsname <name>   Name for C# namespace
    -csnspfx <prefix>  C# namespace names will be this prefix, followed by 
                       schema name
    -genMake           Generate makefile
    -genWriter         Generate writer test program
    -genReader         Generate reader test program
    -usePDU <element>  Use PDU for writer/reader test program

  Java extra options:
    -pkgname <name>    Name for Java package
    -pkgpfx <prefix>   Java package names will be this prefix, followed by 
                       schema name
    -genMake           Generate Apache Ant buildfile (build.xml)
    -genWriter         Generate writer test program
    -genReader         Generate reader test program
    -usePDU <element>  Use PDU for writer/reader test program
    -xpp               Use XmlPull API rather than StAX (StAX is default)

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), C++ (-cpp), C# (-csharp), or Java (-java) source code and the generation of code to encode/decode to/from XML (-xml), DOM (-dom), or JSON (-json).

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 for C/C++ in alphabetical order. Java/C# command-line options are documented in the XBinder v2.2 Java/C# User Manual.

Option	Argument	Description
-all	None	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.
-borland	None	Generate special code for Borland C++ compiler.
-c	None	Generate C source code.
-c++ -cpp	None	Generate C++ source code.
-c14n	None	Generate encode functions which use Canonical XML (http:// www.w3.org/TR/xml-c14n) mode by default.
-compact	None	Generate more compact code. This is useful for generating code for embedded applications where code-size footprint is important. The main optimization made to generate more compact code is the omission of error message text and parameter code. The -lax option can also be used to reduce the amount of generated code.
-compat	<version>	Generate code 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.
-cppns	<name>	This option is used to specify a C++ namespace declaration to be added to generated code. A configuration file entry can be used to specify particular C++ namespaces for parts of your schema. See the discussion on <cppNamespace> elements under <schemaBindings>.
-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 provides 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.
-enumChoice	none	This option is used to cause XBinder to generate and use enum types as the "selector" type for choice-related types. This includes choice groups, union types, and classes generated to support element substitution groups and type derivation. It is useful for improving type safety.
-fragments	None	Generate additional encode functions that allow 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.
-genclient	None	Generate a sample web services client program. This option must be used with option -genTest. The sample client program populates a request messasge with test data, sends to the server, and waits to receive the response message.
-genfree	None	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	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.
-genmakelib	<libname> (optional)	Generate a makefile to put objects into a static library named <libname>. If <libname> is omitted, the parent directory name would be used as the base name for the library.
-genmakedll	<dllname> (optional)	Generate a makefile to build a shared object named <dllname>. If <dllname> is omitted, the parent directory name would be used as the base name for the DLL.
-genreader	None	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	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.
-genskel	None	Generate a server skeleton program. This option must be used with option -genTest. The skeleton server receives a request message, populates response message with test data, and sends the response message back to the client. A stub (empty) function is generated for each WSDL operation. These functions should be supplied by the Web Service developers. In the generated server code, some comments are put in place for calling of the these functions.
-genSSLClient	None	Generate a secure HTTP client test program using OpenSSL. This option must be used with option -genTest. Note: this assumes OpenSSL is in place on the target platform. The client test program opens a TCP connection to port 443 on server. The server hostname is provided by option -hostname of the client program, and the port number can be changed using -port option of the client. The client then initiates the SSL handshake over the TCP connection; and sends HTTP request over SSL.
-genSSLStubs	None	Generate secure HTTP stub functions using OpenSSL. A stub function sends a request to a server over SSL and then turns around and waits for a response. The stub functions can be called from a test client program. The functions are written to the <modulename>WSDLSSLClientStubs.c(pp) file where <modulename> is the base name of the WSDL source file that was parsed.
-genstubs	None	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.
-gentest	<xmlfile> (optional)	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.
-genvalid	None	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.
-genvcproj	<vc6\|2003\|2005\|2008\|2010\|2012\|2013\|2015> (optional)	This option instructs the compiler to generate Visual C++- or Visual Studio-compatible project files to compile generated source code. This is a Windows-only option. By passing one of the listed Visual Studio versions, the compiler will generate a project that links against libraries provided for those versions of Visual Studio. For example, specifying 2010 will generate a project that links against libraries in the `*_vs2010` directory. Not specifying a year will cause the compiler to link against libraries compiled for Visual Studio 2013.
-genwriter	None	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.
-getset	None	Generate C++ getter and setter methods.
-I	<directory>	This option is used to specify a directory that will be searched for XSD <import> and <include> items. Multiple –I qualifiers can be used to specify multiple directories to search.
-initlists	None	Generate linked list initialization functions for complex types that 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: Decoding continues when a required attribute is missing. Decode/validation functions do not contain pattern/facets/MinMaxOccurs/datetime tests. Decoded enumerated value is not verified to be within the defined numeration set. If an attribute has fixed value and content is decoded, do not verify the content matches the fixed value. Decode sequence in lax mode. 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>	Add the given prefix 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	Do not insert a date stamp in the header of each generated file. This can be useful when using a source control system to prevent identical source files from appearing different.
-noencode	None	Do not generate encode functions.
-nodecode	None	Do not generate decode functions.
-noDefaultNS	None	Do not use default namespace in XML instance.
-noderiv	None	Suppress generation of extra code for run-time derived type handling. This code makes it possible to decode complexContent types using xsi:type declarations.
-noenumvars	None	Do not generate fields using generated enum types; revert to prior behavior (generate OSUINT16 instead). This may save some space when used with some compilers.
-noheader	None	Do not add an XML header to generated documents. This the first line in the document that begins with ‘<?xml’.
-nomixed	None	Do not generate a special structure to hold mixed content items. The generated code will more closely match the schema layout. However, mixed content will not be supported.
-noNamedBits	None	Do not generate a named bits structure for enumerated list items. Many application use an XSD list of enumerated items to express a bit map like structure for the specification of properties. By default, XBinder generates a corresponding bit structure to make setting the properties easier. However, some applications may have a need to repeat an enumerated item in a list more than one time. In this case, specification of this option will cause a standard linked list structure to be used.
-noxmlns	None	Do not generate 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	Use numeric date/time structures 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>	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	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.
-project	<name>	Set project name. By default, parent directory name is the used for the project name.
-sax	None	Generate SAX handlers 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	Generate additional code 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	Generate additional code 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	Generate additional code 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.
-strict	None	This option causes encode/decode/validation functions to be generated that does strict syntax checking: Validate a UTF-8 string before encode it. If the the string is not correctly encoded in UTF-8, encoding stops and returns an error. When an invalid enum value is encountered during decoding, decoding stops immediately and returns an error.
-trace	None	Add trace diagnostic messages to generated code. These messages cause printf statements to be added 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	Add 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	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 global element will be chosen at random.
-usestl	None	Use Standard Template Library (STL) classes (currently, std::string and std::vector) in generated C++ code. By default, STL is not used in generated code.
-warnings	None	Output information on compiler generated warnings.
-w32	None	Indicate code generation is being done for use on 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.
-xpp	None	Java option that causes the XmlPull API to be used rather than StAX.
-zip	None	Add standard gzip compression function calls to generated reader and writer programs. This requires that zlib be installed on the target system.