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