Load a SPARK problem at runtime

This section shows how to load a SPARK problem at runtime from the problem description defined in the *.xml file. See Build a SPARK problem dynamically.

The instance of the class SPARK::TProblem that internally describes the problem under study is actually allocated at runtime from the topology information contained in the *.xml file.

This loading scheme is also referred to as dynamic build. It is the default loading scheme used in the SPARK stand-alone driver. The API functions specific to this loading approach can be found in the namespace SPARK::Problem::DynamicBuild.

Note:

Another loading approach consists in compiling the C++ file that defines the data structures representing the topology of the problem and then linking the resulting object file(s) along with the driver's object file to produce the stand-alone executable. This loading approach is known as static build. Problems built this way are loaded in a different manner. See Load a statically-built SPARK problem.

Retrieve the required command-line arguments

The utility function SPARK::Problem::DynamicBuild::ParseCommandLine() can be used to process the command-line arguments in order to retrieve:

• the name of the *.run file,
• the name of the *.prf file, and
• the name of the *.xml file.

For a program called sparksolver (which would be called sparksolver.exe on a Windows platform), the SPARK usage at the command line with the default driver program is:

    sparksolver prefFile.prf runFile.run xmlFile.xml  <enter>

The API function SPARK::Problem::DynamicBuild::ParseCommandLine() identifies each file name by parsing its extension and returns the name of each file matching the desired extension in the pointers to char passed as arguments.

    char* RunFileName;
    char* PrfFileName;
    char* XmlFileName;
   
    SPARK::Problem::DynamicBuild::ParseCommandLine(
           argc-1,         // number of entries in argv 
           argv+1,         // we skip the first entry which is the full program name 
           RunFileName,    // returns full name of *.run file
           PrfFileName,    // returns full name of *.prf file
           XmlFileName     // returns full name of *.xml file
    );

If any of the three file names with the desired extensions cannot be detected in argv[], the function throws a SPARK::XInitialization exception.

If you write your own customized driver function, you could either specify these files at the command-line (like we do with the default driver function) or have these names hard-coded in the body of the function.

See the example driver function void main() implemented in the file multiproblem_example1.cpp in the Examples section.

Load the problem at runtime

A new SPARK problem object can be constructed using the API function SPARK::Problem::DynamicBuild::Load(). Each instantiated problem must also be assigned a unique, case-sensitive string identifier. Many instances can be constructed from the same description as long as they are each given a different and unique name.

If the API function fails to load the problem, then it returns false. It is good practice to test whether the loading operation failed or not before proceeding. In the next example, we force to exit the simulation if this is the case.

    const string XmlFileName("problem.xml");             // name of the *.xml file with the problem description
    const string ProblemName("My unique problem name");  // unique problem name
   
    if ( !SPARK::Problem::DynamicBuild::Load(ProblemName.c_str(), XmlFileName.c_str()) ) {
           ostringstream ErrMsg;
        
       ErrMsg << "Could not load the problem \"" << ProblemName.c_str() << "\" at runtime from " 
              << "the XML description in file \"" << XmlFileName << "\"" << ends;
   
       SPARK::ExitWithError(
          SPARK::ExitCode_ERROR_INVALID_PROBLEM,
          __FILE__,
          ErrMsg.str()
       );
    }

One reason why the loading operation might fail is that the required dynamic libraries implementing the atomic classes used in the problem under study cannot be located at runtime. See Build a SPARK problem dynamically.

---