User Defined Command Line Parameters

Background

An OPC-UA server may be a rather complex process, as such, developers may well want to provide implementation specific command line options - to allows end-users to control aspects of the server’s runtime behaviour, say specifying additional configuration options outside of the quasar generated configuration file for example. This document describes the means by which a developer can add their own command line options to a server developed using quasar and retrieve the end-user values for those options for treatment in their implementation code.

Boost Program Options

quasar handles command line options using the Boost C++ library, specifically the program_options library subset. To understand this document, some knowledge of the program_options library is required:

Boost’s full program options documentation can be found at boost.org
The program options tutorial could be a good place to start

The remainder of this document assumes sufficient knowledge of the program options library.

Adding the command line options

As is often the case in quasar, user specific implementation code is included in the server by overriding methods. The virtual method to override is ````

BaseQuasarServer::appendCustomCommandLineOptions(boost::program_options::options_description& commandLineOptions, boost::program_options::positional_options_description& positionalOptionsDescription)

During quasar server startup, on parsing the command line, overridden method ‘appendCustomCommandLineOptions’ will be called - this adds any implementation specific options to object ‘commandLineOptions’ and ‘positionalOptionsDescription’ which is subsequently used to extract target values from the command line parameters supplied.

Note that both parameters ‘commandLineOptions’ and ‘positionalOptionsDescription’ are references to objects of class types defined in boost::program_options - for a full guide to the interface of this class see the boost documentation, what follows is just a simple example.

A Simple Example

This example shows how to add the 2 command line options listed below such that a quasar OPC-UA server executable, once built, will parse for these options, complete with end-user facing, option specifc, documentation:

some_switch: A simple boolean switch (i.e. without any value; specifying the value at the command line implies TRUE, otherwise FALSE
some_string: A named string value

So, we want to be able to start the server process wit a command line like: ````

./myServerExecutable [possibly other options here] --some_switch --some_string="hello, world!"

Add variables to hold the specific command line values in C++ code,.
In this case add them to class QuasarServer.
Also add the virtual method override (also to class QuasarServer) Now
the class definition pseudo code looks like…
````

class QuasarServer : ...etc...
{
    ...etc...
    virtual void appendCustomCommandLineOptions(boost::program_options::options_description& commandLineOptions,
                                                    boost::program_options::positional_options_description& positionalOptionsDescription

); … etc … bool m_someSwitch; std::string m_someString; }

Now add the implementation of the method ‘appendCustomCommandLineOptions’, for example ````

void QuasarServer::appendCustomCommandLineOptions(boost::program_options::options_description& commandLineOptions,                                                                           boost::program_options::positional_options_description& positionalOptionsDescription

) { commandLineOptions.add_options() (“some_switch”, boost::program_options::bool_switch(&m_someSwitch)->default_value(false), “User documentation of some_switch”) (“some_string”, boost::program_options::value(&m_someString)->default_value(“anyDefaultValue”), “User documentation of some_string”); }

Now, starting the server process with a command line above will result in values ````

QuasarServer::m_someSwitch  = true
QuasarServer::m_someString "hello, world!"

Furthermore, starting the server process with a command line like ````

./myServerExecutable -help

will print the help documentation described above, at the command line, for example: ````

...etc...
 --some_switch        User documentation of some_switch
 --some_string arg   User documentation of some_string