Building a command-line C++ application

Click here to get the sample associated with this walkthrough.

In this topic

• Project description
• Concepts
• Design
• Requirements
• Implementation
• Deployment
• Additional References

Project description

• Programming with the ArcObjects SDK for Cross Platform C++ in a standard text editor.
• Parsing command-line arguments
• Enabling extensions—in particular, the Spatial extension.
• Performing the calculation of slope on a raster dataset.
• Persisting the resultant raster dataset.
• Deploying the application on all platforms supported by the ArcGIS Engine C++ API.

Concepts

Design

• An installation of the ArcObjects SDK for Cross Platform C++ with an authorization file enabling it for development use.
• A text editor, such as Notepad or Microsoft Visual C++.
• A supported C/C++ compiler. This scenario uses the Microsoft Visual C++ Compiler .NET 2008 (9.0).
• A configured ArcObjects environment.
• ArcSDK.h: the ArcGIS Engine C++ API header file.
• A familiarity with the operating system you have chosen to work on and a basic foundation in C++ programming.
• While no experience with other ESRI software is required, previous experience with ArcObjects and a basic understanding of maps is advantageous.
• Access to the solution code and makefiles that come with this scenario. This is located at:
  <install_location>\DeveloperKit10.0\Samples\ArcObjectsCPP\Rasters\Computing_the_Slope_of_a_Raster_DatasetCpp.zip

• An ArcGIS Spatial Analyst or ArcGIS Engine Runtime with Spatial extension license is required for the application to run once deployed.
• To run the application, you will need a raster dataset.

Implementation

• RasterSlope.cpp—Main C++ source file.
• RasterSlope.h—Main C++ header file.
• Makefile.Windows.template—nmake utility file template. During this exercise, you will copy this file from the solution code and rename it Makefile.Windows. You will then update it while following the scenario.

• Makefile.Windows—nmake utility file that specifies compiler settings and rules, file dependencies, input arguments, and an execution rule for our application. In the solution code, this file is the completed makefile for the scenario. As you work through the scenario, the name will refer to the makefile you are building.
• PathUtilities.cpp—Platform-independent path processing helper function implementation file.
• PathUtilities.h—Platform-independent path processing helper function header file.

Creating your build environment

1. Rename your copy of Makefile.Windows.template to 'Makefile.Windows'.
2. Open the newly renamed Makefile.Windows.

3. Update PROGRAM to be RasterSlope.exe.
4. Update INCLUDEDIRS macro, which contains the include directories to pass to the compiler, to reflect where you installed ArcGIS Engine.
5. Update CPPSOURCES to be RasterSlope.cpp.
6. Update CPPOBJECTS to be RasterSlope.obj.
7. Update the dependencies line from basic_sample.obj to be for RasterSlope.obj and to depend on RasterSlope.cpp and RasterSlope.h.

Setting execution parameters

1. Near the beginning of Makefile.Windows, find the lines:
   
         #
         # Command line parameters: Edit these parameters so that you can
         # easily run the sample by typing "nmake /f Makefile.Windows run".
         #
         # You will need to:
         # (1) Describe parameters here. ex: IN_SHAPEFILE is the input shapefile
         # (2) Define parameters below this comment box.
         #       ex: IN_SHAPEFILE = "c:\data\shapefile.shp"
         # (3) Add the parameters to the run target at the end of this file
         #       ex: $(PROGRAM) $(IN_SHAPEFILE)
         #

2. Below it, add parameters for running this sample. For example, if your input raster is "C:\MyComputer\Rasters\RasterDataset" and your output dataset is going to be named "tempslope", you will add the following lines:
   
   
   IN_RASTER = "C:\MyComputer\Rasters\RasterDataset"
   OUT_RASTER = "tempslope"
   

Processing the arguments

1. Create a new file, RasterSlope.h, in your text editor. Place the contents of the file in a #ifndef and #define section. Include a standard C++ header file so that information, such as a usage message, can be displayed to the user.
   
   
   #ifndef __RASTERSLOPE_ESRISCENARIO_h__
   #define __RASTERSLOPE_ESRISCENARIO_h__
   #include <iostream>
   #endif // __RASTERSLOPE_ESRISCENARIO_h__
   
2. In another new file, RasterSlope.cpp, begin implementing your slope application. First include the header file you created in the last step. Then start writing the main function. For now, just process the arguments in it. Make sure the correct number of arguments was entered, else print out a usage message and exit. Since the first argument will be the program name, it can be ignored. The second argument is the input data, and the third is the resulting slope file. You will check if the arguments passed are valid later in the program's execution.

          #include
          "RasterSlope.h"
          int main(int argc, char *argv[])
{
  if (argc != 3)
  {
    std::cerr << "Usage: RasterSlope [sourceFile] [outputFile]" << std::endl;
    return 0;
  }
  char *source = argv[1];
  char *result = argv[2];
  return 0;
}

          #ifndef __PATHUTILITIES_ESRISCENARIO_H__
  #define __PATHUTILITIES_ESRISCENARIO_H__

  #include <iostream>
  #include <ArcSDK.h>

  // Extract the shapefile name from the full path of the file.
  HRESULT GetFileFromFullPath(constchar *inFullPath, BSTR *outFileName);

  // Remove the filename from the full path and return the directory.
  HRESULT GetParentDirFromFullPath(constchar *inFullPath, BSTR *outFilePath);

#endif// __PATHUTILITIES_ESRISCENARIO_H__

          #include
          "PathUtilities.h"
          // Function to remove the filename from the full path and return the
          // path to the directory. Caller is responsible for freeing the memory
          // in outFilePath (or pass in a CComBSTR, which has been cast to a BSTR
          // to let the CComBSTR handle memory management).
HRESULT GetParentDirFromFullPath(constchar *inFullPath, BSTR *outFilePath)
{
  if (!inFullPath || !outFilePath)
    return E_POINTER;
  // Initialize output.
  *outFilePath = 0;
  constchar *pathEnd = strrchr(inFullPath, '/'); // UNIXif (pathEnd == 0)
    pathEnd = strrchr(inFullPath, '\\');
  // Windows
  if (pathEnd == 0)
    return E_FAIL;
  int size = strlen(inFullPath) - strlen(pathEnd);
  char *tmp = new char[size + 1];
  strncpy(tmp, inFullPath, size);
  *(tmp + size) = '\0';
  CComBSTR bsTmp(tmp);
  delete [] tmp;
  if (!bsTmp)
    return E_OUTOFMEMORY;
  *outFilePath = bsTmp.Detach();
  return S_OK;
}

// Function to extract the file (or directory) name from the full path
// of the file. Caller is responsible for freeing the memory in
// outFileName (or pass in a CComBSTR, which has been cast to a BSTR
// to let the CComBSTR handle memory management).
HRESULT GetFileFromFullPath(const char *inFullPath, BSTR *outFileName)
{
  if (!inFullPath || !outFileName)
    return E_POINTER;
  *outFileName = 0;
  const char *name = strrchr(inFullPath, '/'); // UNIX
  if (name == 0)
    name = strrchr(inFullPath, '\\');
  // Windowsif (name == 0)
    return E_FAIL;
  name++;
  char *tmp = newchar[strlen(name) + 1];
  strcpy(tmp, name);
  CComBSTR bsTmp(tmp);
  delete [] tmp;
  if (!bsTmp)
    return E_OUTOFMEMORY;
  *outFileName = bsTmp.Detach();
  return S_OK;
}

          #include <iostream>
#include"PathUtilities.h"

          char *result = argv[2];

// Parse path.
CComBSTR sourceFilePath;
CComBSTR sourceFileName;
HRESULT hr = GetParentDirFromFullPath(source, &sourceFilePath);
if (FAILED(hr) || sourceFilePath.Length() <= 0)
{
  std::cerr << "Couldn't parse source file path." << std::endl;
  return 0;
}

hr = GetFileFromFullPath(source, &sourceFileName);
if (FAILED(hr) || sourceFileName.Length() <= 0)
{
  std::cerr << "Couldn't parse source file name." << std::endl;
  return 0;
}

return 0;

6. Update the makefile to reflect the new PathUtilities.cpp and PathUtilities.h files, including RasterSlope's dependency on it.
7. Compile and run the application. It should simply exit and not appear to do anything although it is parsing the arguments.

Accessing ArcGIS Engine

1. At the top of RasterSlope.h, but below the inclusions for iostream and PathUtilities.h, add an inclusion for ArcSDK.h. It should now appear as follows:

          #include <iostream>
#include"PathUtilities.h"#include <ArcSDK.h>

          int main(int argc, char *argv[])
{
  if (argc != 3)
  {
    std::cerr << "Usage: RasterSlope [sourceFile] [outputFile]" << std::endl;
    AoExit(0);
    //return 0;
  }
  char *source = argv[1];
  char *result = argv[2];

  /* additional code will be in here */

  {
    std::cerr << "Couldn't parse source file path." << std::endl;
    AoExit(0);
    //return 0;
  }
  hr = GetFileFromFullPath(source, &sourceFileName);
  if (FAILED(hr) || sourceFileName.Length() <= 0)
  {
    std::cerr << "Couldn't parse source file name." << std::endl;
    AoExit(0);
    //return 0;
  }
  AoExit(0);
  //return 0;
}

          #include <ArcSDK.h>
bool InitializeWithExtension(esriLicenseProductCode product,
  esriLicenseExtensionCode extension);
void ShutdownApp(esriLicenseExtensionCode license);

bool InitializeWithExtension(esriLicenseProductCode product,
  esriLicenseExtensionCode extension)
{
  ::AoInitialize(0);
  IAoInitializePtr ipInit(CLSID_AoInitialize);
  esriLicenseStatus licenseStatus = esriLicenseFailure;
  ipInit->IsExtensionCodeAvailable(product, extension, &licenseStatus);
  if (licenseStatus == esriLicenseAvailable)
  {
    ipInit->Initialize(product, &licenseStatus);
    if (licenseStatus == esriLicenseCheckedOut)
      ipInit->CheckOutExtension(extension, &licenseStatus);
  }
  return (licenseStatus == esriLicenseCheckedOut);
}

void ShutdownApp(esriLicenseExtensionCode license)
{
  // Scope ipInit so released before AoUninitialize call
  {
    IAoInitializePtr ipInit(CLSID_AoInitialize);
    esriLicenseStatus status;
    ipInit->CheckInExtension(license, &status);
    ipInit->Shutdown();
  }
  ::AoUninitialize();
}

          if (FAILED(hr) || sourceFileName.Length() <= 0)
{
  std::cerr << "Couldn't parse source file name." << std::endl;
  AoExit(0);
}

if (!InitializeWithExtension(esriLicenseProductCodeEngine,
  esriLicenseExtensionCodeSpatialAnalyst))
  if (!InitializeWithExtension(esriLicenseProductCodeArcView,
    esriLicenseExtensionCodeSpatialAnalyst))
    if (!InitializeWithExtension(esriLicenseProductCodeArcEditor,
      esriLicenseExtensionCodeSpatialAnalyst))
if (!InitializeWithExtension(esriLicenseProductCodeArcInfo,
  esriLicenseExtensionCodeSpatialAnalyst))
{
  std::cerr << 
    "Exiting Application: Engine Initialization failed. No suitable license found." << std::endl;
  ShutdownApp(esriLicenseExtensionCodeSpatialAnalyst);
  AoExit(0);
}

//This is a placeholder comment to indicate where additional code will be placed later in the exercise.

ShutdownApp(esriLicenseExtensionCodeSpatialAnalyst);

AoExit(0);

Compile the application using the nmake utility as you did earlier in the scenario.
Run the application. It still appears not to do anything; however, it is now performing the license checking.

Computing the slope

1. Place a declaration for CalculateSlope() in RasterSlope.h after the declaration of ShutdownApp. Give it an HRESULT return type so that it can be used for error checking.

HRESULT CalculateSlope(BSTR inPath, BSTR inName, BSTR outFile);

HRESULT CalculateSlope(BSTR inPath, BSTR inName, BSTR outFile){

}

HRESULT CalculateSlope(BSTR inPath, BSTR inName, BSTR outFile)
{
  // Open the workspace.
  IWorkspaceFactoryPtr ipWorkspaceFactory(CLSID_RasterWorkspaceFactory);
  IWorkspacePtr ipWorkspace;
  HRESULT hr = ipWorkspaceFactory->OpenFromFile(inPath, 0, &ipWorkspace);
  if (FAILED(hr) || ipWorkspace == 0)
  {
    std::cerr << "Could not open the workspace factory." << std::endl;
    return E_FAIL;
  }
}

          // Open the raster dataset.
IRasterWorkspacePtr ipRastWork(ipWorkspace);
IRasterDatasetPtr ipRastDataset;
hr = ipRastWork->OpenRasterDataset(inName, &ipRastDataset);
if (FAILED(hr) || ipRastDataset == 0)
{
  std::cerr << "Could not open the raster dataset." << std::endl;
  return E_FAIL;
}

          // Set up the ISurfaceOp interface to calculate slope.
IRasterAnalysisEnvironmentPtr ipRastAnalEnv(CLSID_RasterSurfaceOp);
ipRastAnalEnv->putref_OutWorkspace(ipWorkspace);
ISurfaceOpPtr ipSurfOp(ipRastAnalEnv);

IGeoDatasetPtr ipGeoDataIn(ipRastDataset);
IGeoDatasetPtr ipGeoDataOut;
HRESULT slopeHR = ipSurfOp->Slope(ipGeoDataIn, esriGeoAnalysisSlopeDegrees, 0, 
  &ipGeoDataOut);
if (FAILED(slopeHR) || ipGeoDataOut == 0)
{
  std::cerr << "slopeHR = " << slopeHR << std::endl;
  return slopeHR;
}

return slopeHR;

hr = CalculateSlope(sourceFilePath, sourceFileName, CComBSTR(result));
if (FAILED(hr))
  std::cerr << "The slope calculation failed." << std::endl;
else
  std::wcerr << L "The slope of " << (BSTR)sourceFileName << L 
    " has been calculated." << std::endl;

8. Compile the application, then run it. Notice that the output data's path information is never used and that the result of the slope calculation is not stored anywhere.

Persisting the result

1. Since you cannot create a new raster dataset where one already exists, make sure that the output slope file does not exist yet. This can be done in the CalculateSlope() function by trying to open a workspace with the desired name. If such an open is successful, then there is already a dataset with that name.
   
   To perform this check, place the following code in CalculateSlope(). It should follow the call to OpenRasterDataset() and the if statement that checks the result of opening the dataset.

          // Check for existence of a dataset with the desired output name.
IRasterDatasetPtr ipExistsCheck;
hr = ipRastWork->OpenRasterDataset(outFile, &ipExistsCheck);
if (SUCCEEDED(hr))
{
  std::cerr << "A dataset with the output name already exists!" << std::endl;
  return E_FAIL;
}

          // Persist the result.
IRasterBandCollectionPtr ipRastBandColl(ipGeoDataOut);
IDatasetPtr ipOutDataset;
ipRastBandColl->SaveAs(outFile, ipWorkspace, CComBSTR(L "GRID"), &ipOutDataset);

3. Compile and run the application. Browse to where the slope data was created. A new ESRI grid was generated with your output name.

Deployment

• An installation of ArcGIS Engine Runtime with Spatial extension on the user machine.
• The user's machine will need to have its ArcGIS Engine Runtime initialized.
• A copy of the application's executable, created at compile time, residing on the end user's machine.

Additional References

• Additional documentation available in the ArcObjects SDK for Cross Platform C++ including ArcGIS Developer Help, component help, object model diagrams, and samples to help you get started.
• ESRI Developer Network—Web site providing the most up-to-date information for ArcGIS developers including updated samples and technical documents. Go to http://edn.esri.com.
• ESRI online discussion forums—Web sites providing invaluable assistance from other ArcGIS developers. Go to http://support.esri.com and click the User Forums tab.
• Burrough, Peter A., and Rachel A. McDonnell. Principles of Geographical Information Systems. Oxford University Press. 1998.