Load a statically-built SPARK problem

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 a stand-alone executable. Problems built this way are referred to as statically built problems. See Build a SPARK problem statically.

A statically-built problem is loaded in a different manner than a problem loaded at runtime (See Load a SPARK problem at runtime). This section shows how to load a statically-built SPARK problem. The API functions specific to this loading approach can be found in the namespace SPARK::Problem::StaticBuild.

Retrieve the required command-line arguments

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

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

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

    simulator prefFile.prf runFile.run  <enter>

The API function SPARK::Problem::StaticBuild::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;
   
    SPARK::Problem::StaticBuild::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
    );

If any of the two 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.

Load the statically-built problem

A previously-built SPARK problem object is registered using the API function SPARK::Problem::StaticBuild::Load(). Each problem instance must be assigned a unique, case-sensitive string identifier in the problem.cpp file that is compiled and linked to the executable simulator. Note that loading a statically-built problem at runtime does not actually instantiate any data structures as the SPARK::TProblem instance is instantiated from the declarations contained in the compiled problem.cpp file. This is the main difference with the other loading approach called a dynamic build (See Load a SPARK problem at runtime).

To declare many instances of the same problem description you must provide a separate problem.cpp file that defines a SPARK::TProblem instance with a different and unique name. Each problem.cpp file must then be compiled and linked along with the other object files for the required atomic classes to produce the self-contained executable simulator program.

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.

    // Unique problem name as specified in the compiled problem.cpp file
    const string ProblemName("My unique problem name");  
   
    if ( !SPARK::Problem::StaticBuild::Load(ProblemName.c_str()) ) {
           ostringstream ErrMsg;
        
           ErrMsg << "Could not load the statically-built problem \"" << ProblemName.c_str() << "\"" << ends;
   
           SPARK::ExitWithError(
              SPARK::ExitCode_ERROR_INVALID_PROBLEM,
              __FILE__,
              ErrMsg.str()
           );
    }

In the stand-alone driver function in SPARK, it is assumed that the name of the problem to load is derived from the name of the simulator program. In the sparksolver.cpp file that implements the default SPARK driver, the program name argv[0] is used to identify the simulation session. Thus, calling the API function SPARK::GetBaseName() returns the name of the program that is also the name of the previously-built problem. This contorted approach for identifying the unique name of problem to solve is necessary in order to be able to use the same driver function for all statically-built problems. Also, it implies that the name of the simulator program must be the name of the statically-built problem you want to solve.

---