#!/usr/bin/env ruby
#
# zp4.rb: a ruby interface to ZP4 Address Correction software
#
# Author: John Chesley
# Date: July 21, 2006
#

require "dl"

module ZP4
  LIB = DL.dlopen('/cygdrive/c/WINDOWS/ZP4.DLL')
  REFS = {
    :ZP4StartSession => LIB['ZP4StartSession', '0l'],
    :ZP4StopSession => LIB['ZP4StopSession', '0L'],
    :ZP4StartCASS => LIB['ZP4StartCASS', 'LLI'],
    :ZP4StopCASS => LIB['ZP4StopCASS', 'LcI'],
    :ZP4TimeLimit => LIB['ZP4TimeLimit', '0LL'],
    :ZP4InputOrder => LIB['ZP4InputOrder', 'LLs'],
    :ZP4OutputOrder => LIB['ZP4OutputOrder', 'LLs'],
    :ZP4Correct => LIB['ZP4Correct', 'LLSs'],
    :ZP4AllErrorsLength => LIB['ZP4AllErrorsLength', '0l'],
    :ZP4AllErrors => LIB['ZP4AllErrors', '0s'],
    :ZP4AllOutputsLength => LIB['ZP4AllOutputsLength', '0Ll'],
    :ZP4AllOutputs => LIB['ZP4AllOutputs', '0Ls'],
    :ZP4Count => LIB['ZP4Count', 'LLLL'],
    :ZP4Get => LIB['ZP4Get', 'LLLLLs']
  }

  # ZP4StartSession: obtain and return a ZP4 session ID
  # session ID is 0 on error
  def ZP4.StartSession()
    r,rs = REFS[:ZP4StartSession].call(0)
    return rs[0]
  end

  # ZP4StopSession: End the specified session
  # returns nil
  def ZP4.StopSession(session)
    r,rs = REFS[:ZP4StopSession].call(session)
    return r
  end

  # ZP4TimeLimit: Set a time limit, in milliseconds, for the ZP4 session
  # A new time limit can be set at any time. The default is over 24 days
  def ZP4.TimeLimit(session, limit)
    r, rs = REFS[:ZP4TimeLimit].call(session, limit)
    return r
  end

  # ZP4StartCASS: Tell ZP4 to start collecting statistics
  # the certify argument is ignored by ZP4
  # Returns 0 on error
  def ZP4.StartCASS(session, certify=0)
    r, rs = REFS[:ZP4StartCASS].call(session, certify)
    return r
  end

  # ZP4StopCASS: Tell ZP4 to stop collecting statistics and
  # write collected stats to specified file
  # the perfect argument is ignored and should be left at 0
  # Returns 0 on error
  def ZP4.StopCASS(session, filename, perfect=0)
    r, rs = REFS[:ZP4StopCASS].call(session, filename, perfect)
    return r
  end

  # ZP4InputOrder: tell ZP4 what order input fields will be in
  # when we call ZP4Correct. This can be called any number of times,
  # and the latest call supersedes any previous call
  # Returns 0 if the call fails
  def ZP4.InputOrder(session, fieldlist)
    r, rs = REFS[:ZP4InputOrder].call(session, fieldlist)
    return r
  end

  # ZP4OutputOrder: tell ZP4 what order to return corrected fields in.
  # This can be called any number of times after at least one call to
  # ZP4InputOrder. The latest call subersedes any previous calls.
  # Returns 0 if the call fails.
  def ZP4.OutputOrder(session, fieldlist)
    r, rs = REFS[:ZP4OutputOrder].call(session, fieldlist)
    return r
  end

  # ZP4Correct: Submits a tab-delimited string of address fields
  # to ZP4 for correction. Returns the corrected address in the format
  # specified by the latest call to ZP4OutputOrder, or 0 if the call fails
  def ZP4.Correct(session, inputs, outputs)
    r,rs = REFS[:ZP4Correct].call(session, inputs, outputs)
    corrected = rs[2]
    if corrected then
      return corrected
    else
      return r
    end
  end

  def ZP4.AllErrorsLength(size)
    r, rs = REFS[:ZP4AllErrorsLength].call(size)
    return rs[0]
  end

  def ZP4.AllErrors(list)
    r, rs = REFS[:ZP4AllErrors].call(list)
    return rs[0]
  end

  # ZP4AllOutputsLength: returns the size of the string needed to hold the ouput
  # from ZP4AllOutputs(). Call after ZP4InputOrder since input fields determine
  # which output fields are available
  def ZP4.AllOutputsLength(session, size)
    r, rs = REFS[:ZP4AllOutputsLength].call(session, size)
    return rs[1]
  end

  # ZP4AllOutputs: returns a tab-delimited list of all the available output fields
  def ZP4.AllOutputs(session, list)
    r, rs = REFS[:ZP4AllOutputs].call(session, list)
    return rs[1]
  end

  # ZP4Count:
  def ZP4.Count(statenum, citynum, strnum)
    r, rs = REFS[:ZP4Count].call(statenum, citynum, strnum)
    return r
  end

  # ZP4Get:
  def ZP4.Get(statenum, citynum, strnum, adrnum, dest)
    r, rs = REFS[:ZP4Get].call(statenum, citynum, strnum, adrnum, dest)
    return rs[4]
  end

end