Skip to content

ATM participation and status

This operation covers the three façade methods that interact with the ATM vendor service: IsATMParticipant checks whether a routing number participates in the ATM network, GetATMAccountStatus retrieves and translates an account status (checking participation first), and TranslateStatusCode translates a status code the caller already has in hand. This is the only operation group in the library with two distinct fault/edge behaviors captured as business rules.

Field Value
Operation ID OP-BV-04
Trigger Caller calls IsATMParticipant(inRoutingNum), GetATMAccountStatus(inRoutingNum, inAccountNum, inAmount, outStatusDescription), or TranslateStatusCode(inStatus) on a constructed clsValidateBank
Inputs Routing number; for GetATMAccountStatus, also account number and amount; for TranslateStatusCode, a status code
Outputs Boolean participation flag (IsATMParticipant); Integer status code plus an outStatusDescription byref string (GetATMAccountStatus); or a translated description string (TranslateStatusCode)
Primary components clsValidateBank.IsATMParticipant, clsValidateBank.GetATMAccountStatus, clsValidateBank.TranslateStatusCode, clsValidateBank.LogonATM, clsValidateBank.LogoffATM
Entry point Legacy\BankValidator\clsValidateBank.vb

Steps

  1. Log on to the ATM service. LogonATM() increments m_LogonAttempts, lazily constructs ATMService.ATMService if needed, sets its Url from URLATM, and calls ATM.Logon(CompanyId, UserId, Password) to obtain a LogonToken (BR-002).
  2. On failure: recursively retries LogonATM() while m_LogonAttempts < m_LogonAttemptsMax, then throws ApplicationException("Unable to logon to ATM web service.", ex) once exhausted.
  3. IsATMParticipant — check participation. Wrapped in Try/Catch, call ATM.IsParticipant(LogonToken, inRoutingNum) and assign the result to isValid.
  4. On SoapException: assign isValid = False, treating the fault as non-participation (BR-005).
  5. On any other exception: throw ApplicationException("Error while trying to check the ATM participant", ex).
  6. LogoffATM() runs in Finally regardless of outcome.
  7. GetATMAccountStatus — initialize defaults. statusCode is set to -1 and outStatusDescription is set to "Unknown" before any vendor call, establishing the fallback outcome up front.
  8. GetATMAccountStatus — check participation. Call ATM.IsParticipant(LogonToken, inRoutingNum) (not wrapped in Try/Catch at this call site).
  9. If the bank participates: call ATM.GetStatusCode(LogonToken, inRoutingNum, inAccountNum, inAmount.ToString("0000000.00")) to get statusCode, then call ATM.TranslateStatusCode(LogonToken, statusCode) to resolve outStatusDescription.
  10. If the bank does not participate: leave statusCode = -1 and outStatusDescription = "Unknown" (BR-004).
  11. Because this method has no Try/Catch, any exception from ATM.IsParticipant, ATM.GetStatusCode, or ATM.TranslateStatusCode propagates directly to the caller and LogoffATM() is skipped.*
  12. TranslateStatusCode — translate a code. Call ATM.TranslateStatusCode(LogonToken, inStatus) and assign the result to result (default "Unknown").
  13. Not wrapped in Try/Catch; an exception propagates directly to the caller and skips LogoffATM().*
  14. Log off the ATM service. LogoffATM() calls ATM.Logoff(LogonToken), disposes the ATM proxy, and sets it to Nothing (guaranteed via Finally only for IsATMParticipant; called unconditionally at the end of GetATMAccountStatus and TranslateStatusCode when no exception is thrown).
  15. On failure: the exception is silently swallowed (the Throw line is commented out).
  16. Return the result. IsATMParticipant returns the participation Boolean; GetATMAccountStatus returns statusCode and sets outStatusDescription by reference; TranslateStatusCode returns the description string.

Process flow

The following diagram visualizes the three method flows, highlighting the participation-check branch used by GetATMAccountStatus and the fault handling unique to IsATMParticipant.

flowchart TD
    Start([Caller calls IsATMParticipant,<br>GetATMAccountStatus, or TranslateStatusCode]) --> Logon[LogonATM:<br>logon with retry up to m_LogonAttemptsMax]
    Logon --> LogonOk{Logon succeeded?}
    LogonOk -->|No, retries exhausted| Ex([ApplicationException thrown])
    LogonOk -->|Yes| Which{Which method?}
    Which -->|IsATMParticipant| Part[ATM.IsParticipant]
    Part --> PartFault{SoapException?}
    PartFault -->|Yes| NonPart[isValid = False]
    PartFault -->|No, other| PartEx([ApplicationException thrown])
    PartFault -->|No| PartOk[isValid = vendor result]
    Which -->|GetATMAccountStatus| Defaults[statusCode = -1<br>outStatusDescription = Unknown]
    Defaults --> Part2[ATM.IsParticipant]
    Part2 --> IsPart{Participant?}
    IsPart -->|No| KeepDefaults([Return -1 / Unknown])
    IsPart -->|Yes| GetStatus[ATM.GetStatusCode]
    GetStatus --> Translate[ATM.TranslateStatusCode]
    Translate --> StatusResult([Return status code<br>and description])
    Which -->|TranslateStatusCode| Trans[ATM.TranslateStatusCode]
    Trans --> TransResult([Return description string])
    NonPart --> Logoff[LogoffATM:<br>release token, dispose proxy]
    PartOk --> Logoff
    Logoff --> Done([Return result])
    StatusResult --> Logoff2[LogoffATM]
    TransResult --> Logoff3[LogoffATM]

Failure and edge-case behavior

  • If the ATM logon fails repeatedly, the caller receives an ApplicationException after m_LogonAttemptsMax retries (BR-002); no ATM check is attempted for any of the three methods.
  • IsATMParticipant is the only one of the three methods that wraps the vendor call in Try/Catch: a SoapException resolves to False (BR-005) and LogoffATM() is guaranteed via Finally.
  • GetATMAccountStatus has no exception handling around ATM.IsParticipant, ATM.GetStatusCode, or ATM.TranslateStatusCode; a vendor fault propagates unhandled and LogoffATM() is skipped, unlike IsATMParticipant.*
  • GetATMAccountStatus returns -1 and "Unknown" specifically when the routing number is not an ATM participant (BR-004) — a different code path from the SoapException handling in IsATMParticipant (BR-005); the two rules must not be conflated.
  • TranslateStatusCode has no participation check and no exception handling; it assumes the caller already has a valid status code from a prior GetATMAccountStatus call.*
  • LogoffATM failures are intentionally swallowed and never surface to the caller.*
  • Historical source comments note the ATM web service was discontinued by the vendor as of 11/30/2006 and re-enabled as of 01/08/2007; the current code paths reflect the re-enabled, fully functional service.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Legacy\BankValidator\clsValidateBank.vb