OpenSWMM Engine  6.0.0-alpha.1
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.1)
Loading...
Searching...
No Matches
openswmm_output.h File Reference

OpenSWMM Engine — Output File Reader C API. More...

#include "openswmm_engine_export.h"
Include dependency graph for openswmm_output.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef void * SWMM_Output
 Opaque handle to an opened output file reader.
 
typedef enum SWMM_OutSubcatchVar SWMM_OutSubcatchVar
 Subcatchment result variable indices.
 
typedef enum SWMM_OutNodeVar SWMM_OutNodeVar
 Node result variable indices.
 
typedef enum SWMM_OutLinkVar SWMM_OutLinkVar
 Link result variable indices.
 
typedef enum SWMM_OutSystemVar SWMM_OutSystemVar
 System-wide result variable indices.
 

Enumerations

enum  SWMM_OutSubcatchVar {
  SWMM_OUT_SUBCATCH_RAINFALL = 0 ,
  SWMM_OUT_SUBCATCH_SNOW_DEPTH = 1 ,
  SWMM_OUT_SUBCATCH_EVAP = 2 ,
  SWMM_OUT_SUBCATCH_INFIL = 3 ,
  SWMM_OUT_SUBCATCH_RUNOFF = 4 ,
  SWMM_OUT_SUBCATCH_GW_FLOW = 5 ,
  SWMM_OUT_SUBCATCH_GW_ELEV = 6 ,
  SWMM_OUT_SUBCATCH_SOIL_MOIST = 7 ,
  SWMM_OUT_SUBCATCH_POLLUT_BASE = 8
}
 Subcatchment result variable indices. More...
 
enum  SWMM_OutNodeVar {
  SWMM_OUT_NODE_DEPTH = 0 ,
  SWMM_OUT_NODE_HEAD = 1 ,
  SWMM_OUT_NODE_VOLUME = 2 ,
  SWMM_OUT_NODE_LATERAL_INFLOW = 3 ,
  SWMM_OUT_NODE_TOTAL_INFLOW = 4 ,
  SWMM_OUT_NODE_OVERFLOW = 5 ,
  SWMM_OUT_NODE_POLLUT_BASE = 6
}
 Node result variable indices. More...
 
enum  SWMM_OutLinkVar {
  SWMM_OUT_LINK_FLOW = 0 ,
  SWMM_OUT_LINK_DEPTH = 1 ,
  SWMM_OUT_LINK_VELOCITY = 2 ,
  SWMM_OUT_LINK_VOLUME = 3 ,
  SWMM_OUT_LINK_CAPACITY = 4 ,
  SWMM_OUT_LINK_POLLUT_BASE = 5
}
 Link result variable indices. More...
 
enum  SWMM_OutSystemVar {
  SWMM_OUT_SYS_TEMPERATURE = 0 ,
  SWMM_OUT_SYS_RAINFALL = 1 ,
  SWMM_OUT_SYS_SNOW_DEPTH = 2 ,
  SWMM_OUT_SYS_EVAP = 3 ,
  SWMM_OUT_SYS_INFIL = 4 ,
  SWMM_OUT_SYS_RUNOFF = 5 ,
  SWMM_OUT_SYS_DW_INFLOW = 6 ,
  SWMM_OUT_SYS_GW_INFLOW = 7 ,
  SWMM_OUT_SYS_LAT_INFLOW = 8 ,
  SWMM_OUT_SYS_FLOODING = 9 ,
  SWMM_OUT_SYS_OUTFLOW = 10 ,
  SWMM_OUT_SYS_STORAGE = 11 ,
  SWMM_OUT_SYS_EVAP_TOTAL = 12 ,
  SWMM_OUT_SYS_PET = 13
}
 System-wide result variable indices. More...
 

Functions

SWMM_ENGINE_API SWMM_Output swmm_output_open (const char *path)
 Open a binary output file for reading.
 
SWMM_ENGINE_API void swmm_output_close (SWMM_Output handle)
 Close the output file and free all resources.
 
SWMM_ENGINE_API int swmm_output_get_version (SWMM_Output handle)
 Get the SWMM version stored in the output file.
 
SWMM_ENGINE_API int swmm_output_get_flow_units (SWMM_Output handle)
 Get the flow units code.
 
SWMM_ENGINE_API int swmm_output_get_subcatch_count (SWMM_Output handle)
 Get the number of subcatchments in the output file.
 
SWMM_ENGINE_API int swmm_output_get_node_count (SWMM_Output handle)
 Get the number of nodes in the output file.
 
SWMM_ENGINE_API int swmm_output_get_link_count (SWMM_Output handle)
 Get the number of links in the output file.
 
SWMM_ENGINE_API int swmm_output_get_pollut_count (SWMM_Output handle)
 Get the number of pollutants in the output file.
 
SWMM_ENGINE_API int swmm_output_get_period_count (SWMM_Output handle)
 Get the number of reporting periods (timesteps) in the output file.
 
SWMM_ENGINE_API int swmm_output_get_start_date (SWMM_Output handle, double *start_date)
 Get the simulation start date as a Julian date (double).
 
SWMM_ENGINE_API int swmm_output_get_report_step (SWMM_Output handle)
 Get the report step in seconds.
 
SWMM_ENGINE_API const char * swmm_output_get_subcatch_id (SWMM_Output handle, int index)
 Get the string ID of a subcatchment by index.
 
SWMM_ENGINE_API const char * swmm_output_get_node_id (SWMM_Output handle, int index)
 Get the string ID of a node by index.
 
SWMM_ENGINE_API const char * swmm_output_get_link_id (SWMM_Output handle, int index)
 Get the string ID of a link by index.
 
SWMM_ENGINE_API int swmm_output_get_subcatch_result (SWMM_Output handle, int period, int var, float *values)
 Get one subcatchment variable for all subcatchments at a given period.
 
SWMM_ENGINE_API int swmm_output_get_node_result (SWMM_Output handle, int period, int var, float *values)
 Get one node variable for all nodes at a given period.
 
SWMM_ENGINE_API int swmm_output_get_link_result (SWMM_Output handle, int period, int var, float *values)
 Get one link variable for all links at a given period.
 
SWMM_ENGINE_API int swmm_output_get_system_result (SWMM_Output handle, int period, int var, float *value)
 Get system-wide results at a given period.
 
SWMM_ENGINE_API int swmm_output_get_subcatch_series (SWMM_Output handle, int subcatch_idx, int var, int start_period, int end_period, float *values)
 Get a subcatchment variable time series across a range of periods.
 
SWMM_ENGINE_API int swmm_output_get_node_series (SWMM_Output handle, int node_idx, int var, int start_period, int end_period, float *values)
 Get a node variable time series across a range of periods.
 
SWMM_ENGINE_API int swmm_output_get_link_series (SWMM_Output handle, int link_idx, int var, int start_period, int end_period, float *values)
 Get a link variable time series across a range of periods.
 
SWMM_ENGINE_API int swmm_output_get_system_series (SWMM_Output handle, int var, int start_period, int end_period, float *values)
 Get a system variable time series across a range of periods.
 
SWMM_ENGINE_API int swmm_output_get_subcatch_attribute (SWMM_Output handle, int subcatch_idx, int period, float *values, int *count)
 Get all result variables for a single subcatchment at one period.
 
SWMM_ENGINE_API int swmm_output_get_node_attribute (SWMM_Output handle, int node_idx, int period, float *values, int *count)
 Get all result variables for a single node at one period.
 
SWMM_ENGINE_API int swmm_output_get_link_attribute (SWMM_Output handle, int link_idx, int period, float *values, int *count)
 Get all result variables for a single link at one period.
 
SWMM_ENGINE_API int swmm_output_get_period_time (SWMM_Output handle, int period, double *time)
 Get the simulation time (Julian date) for a given period.
 
SWMM_ENGINE_API int swmm_output_get_error_code (SWMM_Output handle)
 Get the error code stored in the output file footer.
 

Detailed Description

OpenSWMM Engine — Output File Reader C API.

Provides a transparent C89-compatible API for reading binary output files (.out) produced by the DefaultOutputPlugin. The binary format is the standard SWMM 5.x output format containing:

  • Header (magic, version, flow units, object counts)
  • Object ID names
  • Input properties (subcatchment areas, node geometry, link geometry)
  • Per-period time series results (subcatch/node/link/system)
  • Footer (section offsets, period count, error code)

Usage:

SWMM_Output out = swmm_output_open("model.out");
if (!out) { // handle error }
int periods = swmm_output_get_period_count(out);
float* depths = malloc(n * sizeof(float));
// depths[j] is node j depth at period 5
float ts[1];
swmm_output_get_node_time_series(out, 0, SWMM_OUT_NODE_DEPTH,
0, periods - 1, ts_buf);
OpenSWMM Engine — Output File Reader C API.
@ SWMM_OUT_NODE_DEPTH
Definition openswmm_output.h:88
void * SWMM_Output
Opaque handle to an opened output file reader.
Definition openswmm_output.h:57
SWMM_ENGINE_API int swmm_output_get_period_count(SWMM_Output handle)
Get the number of reporting periods (timesteps) in the output file.
Definition openswmm_output_impl.cpp:85
SWMM_ENGINE_API int swmm_output_get_node_result(SWMM_Output handle, int period, int var, float *values)
Get one node variable for all nodes at a given period.
Definition openswmm_output_impl.cpp:137
SWMM_ENGINE_API int swmm_output_get_node_count(SWMM_Output handle)
Get the number of nodes in the output file.
Definition openswmm_output_impl.cpp:70
SWMM_ENGINE_API SWMM_Output swmm_output_open(const char *path)
Open a binary output file for reading.
Definition openswmm_output_impl.cpp:33
SWMM_ENGINE_API void swmm_output_close(SWMM_Output handle)
Close the output file and free all resources.
Definition openswmm_output_impl.cpp:44
See also
DefaultOutputPlugin.hpp — the writer that produces these files
Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com
License\n MIT License

Typedef Documentation

◆ SWMM_OutLinkVar

Link result variable indices.

Variables stored per link per output period. Pollutant concentrations follow at indices >= SWMM_OUT_LINK_POLLUT_BASE.

◆ SWMM_OutNodeVar

Node result variable indices.

Variables stored per node per output period. Pollutant concentrations follow at indices >= SWMM_OUT_NODE_POLLUT_BASE.

◆ SWMM_Output

typedef void* SWMM_Output

Opaque handle to an opened output file reader.

◆ SWMM_OutSubcatchVar

Subcatchment result variable indices.

Variables stored per subcatchment per output period. Pollutant concentrations follow at indices >= SWMM_OUT_SUBCATCH_POLLUT_BASE.

◆ SWMM_OutSystemVar

System-wide result variable indices.

14 system-wide summary results stored per output period.

Enumeration Type Documentation

◆ SWMM_OutLinkVar

Link result variable indices.

Variables stored per link per output period. Pollutant concentrations follow at indices >= SWMM_OUT_LINK_POLLUT_BASE.

Enumerator
SWMM_OUT_LINK_FLOW 

Flow rate.

SWMM_OUT_LINK_DEPTH 

Flow depth.

SWMM_OUT_LINK_VELOCITY 

Flow velocity.

SWMM_OUT_LINK_VOLUME 

Volume.

SWMM_OUT_LINK_CAPACITY 

Fraction of conduit capacity.

SWMM_OUT_LINK_POLLUT_BASE 

First pollutant concentration slot.

◆ SWMM_OutNodeVar

Node result variable indices.

Variables stored per node per output period. Pollutant concentrations follow at indices >= SWMM_OUT_NODE_POLLUT_BASE.

Enumerator
SWMM_OUT_NODE_DEPTH 

Water depth above invert.

SWMM_OUT_NODE_HEAD 

Hydraulic head.

SWMM_OUT_NODE_VOLUME 

Stored water volume.

SWMM_OUT_NODE_LATERAL_INFLOW 

Lateral inflow rate.

SWMM_OUT_NODE_TOTAL_INFLOW 

Total inflow rate.

SWMM_OUT_NODE_OVERFLOW 

Overflow rate.

SWMM_OUT_NODE_POLLUT_BASE 

First pollutant concentration slot.

◆ SWMM_OutSubcatchVar

Subcatchment result variable indices.

Variables stored per subcatchment per output period. Pollutant concentrations follow at indices >= SWMM_OUT_SUBCATCH_POLLUT_BASE.

Enumerator
SWMM_OUT_SUBCATCH_RAINFALL 

Rainfall rate.

SWMM_OUT_SUBCATCH_SNOW_DEPTH 

Snow depth.

SWMM_OUT_SUBCATCH_EVAP 

Evaporation loss.

SWMM_OUT_SUBCATCH_INFIL 

Infiltration loss.

SWMM_OUT_SUBCATCH_RUNOFF 

Runoff flow rate.

SWMM_OUT_SUBCATCH_GW_FLOW 

Groundwater flow.

SWMM_OUT_SUBCATCH_GW_ELEV 

Groundwater table elevation.

SWMM_OUT_SUBCATCH_SOIL_MOIST 

Soil moisture content.

SWMM_OUT_SUBCATCH_POLLUT_BASE 

First pollutant concentration slot.

◆ SWMM_OutSystemVar

System-wide result variable indices.

14 system-wide summary results stored per output period.

Enumerator
SWMM_OUT_SYS_TEMPERATURE 

Air temperature.

SWMM_OUT_SYS_RAINFALL 

Average rainfall.

SWMM_OUT_SYS_SNOW_DEPTH 

Average snow depth.

SWMM_OUT_SYS_EVAP 

Average evaporation.

SWMM_OUT_SYS_INFIL 

Average infiltration.

SWMM_OUT_SYS_RUNOFF 

Total runoff flow.

SWMM_OUT_SYS_DW_INFLOW 

Dry weather inflow.

SWMM_OUT_SYS_GW_INFLOW 

Groundwater inflow.

SWMM_OUT_SYS_LAT_INFLOW 

Lateral inflow.

SWMM_OUT_SYS_FLOODING 

Total flooding.

SWMM_OUT_SYS_OUTFLOW 

Total outfall outflow.

SWMM_OUT_SYS_STORAGE 

Total storage volume.

SWMM_OUT_SYS_EVAP_TOTAL 

Total evaporation.

SWMM_OUT_SYS_PET 

Potential evapotranspiration.

Function Documentation

◆ swmm_output_close()

SWMM_ENGINE_API void swmm_output_close ( SWMM_Output  handle)

Close the output file and free all resources.

Parameters
handleOutput reader handle (NULL safe).

◆ swmm_output_get_error_code()

SWMM_ENGINE_API int swmm_output_get_error_code ( SWMM_Output  handle)

Get the error code stored in the output file footer.

Parameters
handleOutput reader handle.
Returns
Error code from the simulation (0 = success), or -1 on reader error.
Here is the call graph for this function:

◆ swmm_output_get_flow_units()

SWMM_ENGINE_API int swmm_output_get_flow_units ( SWMM_Output  handle)

Get the flow units code.

Parameters
handleOutput reader handle.
Returns
Flow units code (0=CFS, 1=GPM, 2=MGD, 3=CMS, 4=LPS, 5=MLD), or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_link_attribute()

SWMM_ENGINE_API int swmm_output_get_link_attribute ( SWMM_Output  handle,
int  link_idx,
int  period,
float *  values,
int *  count 
)

Get all result variables for a single link at one period.

Parameters
handleOutput reader handle.
link_idxZero-based link index.
periodZero-based period index.
valuesCaller-allocated array of n_link_vars floats.
countPointer to receive the number of variables written.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_link_count()

SWMM_ENGINE_API int swmm_output_get_link_count ( SWMM_Output  handle)

Get the number of links in the output file.

Parameters
handleOutput reader handle.
Returns
Link count, or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_link_id()

SWMM_ENGINE_API const char * swmm_output_get_link_id ( SWMM_Output  handle,
int  index 
)

Get the string ID of a link by index.

Parameters
handleOutput reader handle.
indexZero-based link index.
Returns
Null-terminated string owned by the reader, or NULL on error.
Here is the call graph for this function:

◆ swmm_output_get_link_result()

SWMM_ENGINE_API int swmm_output_get_link_result ( SWMM_Output  handle,
int  period,
int  var,
float *  values 
)

Get one link variable for all links at a given period.

Parameters
handleOutput reader handle.
periodZero-based period index.
varLink variable (see SWMM_OutLinkVar).
valuesCaller-allocated array of at least link_count floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_link_series()

SWMM_ENGINE_API int swmm_output_get_link_series ( SWMM_Output  handle,
int  link_idx,
int  var,
int  start_period,
int  end_period,
float *  values 
)

Get a link variable time series across a range of periods.

Parameters
handleOutput reader handle.
link_idxZero-based link index.
varLink variable.
start_periodFirst period (inclusive, zero-based).
end_periodLast period (inclusive, zero-based).
valuesCaller-allocated array of (end_period - start_period + 1) floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_node_attribute()

SWMM_ENGINE_API int swmm_output_get_node_attribute ( SWMM_Output  handle,
int  node_idx,
int  period,
float *  values,
int *  count 
)

Get all result variables for a single node at one period.

Parameters
handleOutput reader handle.
node_idxZero-based node index.
periodZero-based period index.
valuesCaller-allocated array of n_node_vars floats.
countPointer to receive the number of variables written.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_node_count()

SWMM_ENGINE_API int swmm_output_get_node_count ( SWMM_Output  handle)

Get the number of nodes in the output file.

Parameters
handleOutput reader handle.
Returns
Node count, or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_node_id()

SWMM_ENGINE_API const char * swmm_output_get_node_id ( SWMM_Output  handle,
int  index 
)

Get the string ID of a node by index.

Parameters
handleOutput reader handle.
indexZero-based node index.
Returns
Null-terminated string owned by the reader, or NULL on error.
Here is the call graph for this function:

◆ swmm_output_get_node_result()

SWMM_ENGINE_API int swmm_output_get_node_result ( SWMM_Output  handle,
int  period,
int  var,
float *  values 
)

Get one node variable for all nodes at a given period.

Parameters
handleOutput reader handle.
periodZero-based period index.
varNode variable (see SWMM_OutNodeVar).
valuesCaller-allocated array of at least node_count floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_node_series()

SWMM_ENGINE_API int swmm_output_get_node_series ( SWMM_Output  handle,
int  node_idx,
int  var,
int  start_period,
int  end_period,
float *  values 
)

Get a node variable time series across a range of periods.

Parameters
handleOutput reader handle.
node_idxZero-based node index.
varNode variable.
start_periodFirst period (inclusive, zero-based).
end_periodLast period (inclusive, zero-based).
valuesCaller-allocated array of (end_period - start_period + 1) floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_period_count()

SWMM_ENGINE_API int swmm_output_get_period_count ( SWMM_Output  handle)

Get the number of reporting periods (timesteps) in the output file.

Parameters
handleOutput reader handle.
Returns
Period count, or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_period_time()

SWMM_ENGINE_API int swmm_output_get_period_time ( SWMM_Output  handle,
int  period,
double *  time 
)

Get the simulation time (Julian date) for a given period.

Parameters
handleOutput reader handle.
periodZero-based period index.
timePointer to receive the simulation time as a double (Julian date).
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_pollut_count()

SWMM_ENGINE_API int swmm_output_get_pollut_count ( SWMM_Output  handle)

Get the number of pollutants in the output file.

Parameters
handleOutput reader handle.
Returns
Pollutant count, or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_report_step()

SWMM_ENGINE_API int swmm_output_get_report_step ( SWMM_Output  handle)

Get the report step in seconds.

Parameters
handleOutput reader handle.
Returns
Report step (seconds), or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_start_date()

SWMM_ENGINE_API int swmm_output_get_start_date ( SWMM_Output  handle,
double *  start_date 
)

Get the simulation start date as a Julian date (double).

Parameters
handleOutput reader handle.
start_datePointer to receive the start date value.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_subcatch_attribute()

SWMM_ENGINE_API int swmm_output_get_subcatch_attribute ( SWMM_Output  handle,
int  subcatch_idx,
int  period,
float *  values,
int *  count 
)

Get all result variables for a single subcatchment at one period.

Parameters
handleOutput reader handle.
subcatch_idxZero-based subcatchment index.
periodZero-based period index.
valuesCaller-allocated array of n_subcatch_vars floats.
countPointer to receive the number of variables written.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_subcatch_count()

SWMM_ENGINE_API int swmm_output_get_subcatch_count ( SWMM_Output  handle)

Get the number of subcatchments in the output file.

Parameters
handleOutput reader handle.
Returns
Subcatchment count, or -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_subcatch_id()

SWMM_ENGINE_API const char * swmm_output_get_subcatch_id ( SWMM_Output  handle,
int  index 
)

Get the string ID of a subcatchment by index.

Parameters
handleOutput reader handle.
indexZero-based subcatchment index.
Returns
Null-terminated string owned by the reader, or NULL on error.
Here is the call graph for this function:

◆ swmm_output_get_subcatch_result()

SWMM_ENGINE_API int swmm_output_get_subcatch_result ( SWMM_Output  handle,
int  period,
int  var,
float *  values 
)

Get one subcatchment variable for all subcatchments at a given period.

Parameters
handleOutput reader handle.
periodZero-based period index.
varSubcatchment variable (see SWMM_OutSubcatchVar).
valuesCaller-allocated array of at least subcatch_count floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_subcatch_series()

SWMM_ENGINE_API int swmm_output_get_subcatch_series ( SWMM_Output  handle,
int  subcatch_idx,
int  var,
int  start_period,
int  end_period,
float *  values 
)

Get a subcatchment variable time series across a range of periods.

Parameters
handleOutput reader handle.
subcatch_idxZero-based subcatchment index.
varSubcatchment variable.
start_periodFirst period (inclusive, zero-based).
end_periodLast period (inclusive, zero-based).
valuesCaller-allocated array of (end_period - start_period + 1) floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_system_result()

SWMM_ENGINE_API int swmm_output_get_system_result ( SWMM_Output  handle,
int  period,
int  var,
float *  value 
)

Get system-wide results at a given period.

Parameters
handleOutput reader handle.
periodZero-based period index.
varSystem variable (see SWMM_OutSystemVar).
valuePointer to receive the single float value.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_system_series()

SWMM_ENGINE_API int swmm_output_get_system_series ( SWMM_Output  handle,
int  var,
int  start_period,
int  end_period,
float *  values 
)

Get a system variable time series across a range of periods.

Parameters
handleOutput reader handle.
varSystem variable.
start_periodFirst period (inclusive, zero-based).
end_periodLast period (inclusive, zero-based).
valuesCaller-allocated array of (end_period - start_period + 1) floats.
Returns
0 on success, -1 on error.
Here is the call graph for this function:

◆ swmm_output_get_version()

SWMM_ENGINE_API int swmm_output_get_version ( SWMM_Output  handle)

Get the SWMM version stored in the output file.

Parameters
handleOutput reader handle.
Returns
Version number (e.g. 52001), or -1 on error.
Here is the call graph for this function:

◆ swmm_output_open()

SWMM_ENGINE_API SWMM_Output swmm_output_open ( const char *  path)

Open a binary output file for reading.

Parameters
pathPath to a .out file produced by DefaultOutputPlugin.
Returns
Opaque handle, or NULL on failure (invalid file, I/O error).