Skip to content

City/state/county lookup by ZIP

This operation resolves a ZIP code to the city, state, and county combinations the vendor recognizes for it. Because the vendor returns results as one long fixed-width text buffer rather than a structured collection, the operation preallocates that buffer, calls the vendor, and parses each fixed-width row into a typed result object.

Field Value
Operation ID OP-CA-04
Trigger Caller invokes clsCleanAddress.FindCityStateInfoByZip(inZIP)
Inputs inZIP — ZIP code to look up
Outputs List(Of clsCityStateCountyInfo) — one entry per matched city/state/county row
Primary components clsCleanAddress.FindCityStateInfoByZip, clsCityStateCountyInfo, CleanAddressSvc.clsCAServices
Entry point Services\SAIF.Services.CleanAddress\clsCleanAddress.vb

Steps

  1. Create a new CleanAddressSvc.clsCAServices proxy instance and set AllowAutoRedirect = True and UseDefaultCredentials = True.
  2. Preallocate a 50-row by 55-character output buffer (a 2,750-character space-filled string) to receive the vendor's fixed-width response.
  3. Normalize inZIP to a 5-character value by padding with spaces and taking the first 5 characters; this normalized value is computed but not passed to the vendor call, which instead receives the original inZIP argument.*
  4. Call FindCityStateInfoByZip(inZIP, ByRef outResultsCount, ByRef outResults) on the proxy.
  5. For each of the outResultsCount rows returned:
  6. Parse characters 1–28 of the 55-character row as City (trimmed).
  7. Parse characters 29–30 as State.
  8. Parse characters 31–55 as County (trimmed).
  9. Add the populated clsCityStateCountyInfo to the result list.
  10. Return the populated result list to the caller.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller invokes FindCityStateInfoByZip<br>with inZIP]) --> Proxy[Create clsCAServices proxy]
    Proxy --> Buffer[Preallocate 50x55<br>character output buffer]
    Buffer --> Call[Call vendor FindCityStateInfoByZip<br>ByRef outResultsCount, outResults]
    Call --> Loop{More rows to parse?}
    Loop -->|Yes| Parse[Parse 55-char row into<br>City, State, County]
    Parse --> Add[Add clsCityStateCountyInfo<br>to result list]
    Add --> Loop
    Loop -->|No| Return([Return result list])

Failure and edge-case behavior

  • The vendor call is not wrapped in a Try/Catch; a SOAP fault or transport error propagates to the caller unhandled, unlike Address cleanse.*
  • Parsing depends entirely on the vendor returning exactly 55 characters per row up to outResultsCount; a mismatched row width would corrupt or truncate the parsed City, State, and County values with no validation in place.**
  • If outResultsCount exceeds 50, the parser reads past the preallocated buffer size assumption; behavior in that case depends on how much data the vendor actually wrote into outResults.**
  • A ZIP code with no matches is expected to return outResultsCount = 0 and an empty list, though this is not explicitly tested in the source.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • Services\SAIF.Services.CleanAddress\clsCleanAddress.vb
  • Services\SAIF.Services.CleanAddress\clsCityStateCountyInfo.vb
  • Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb