--- title: SAIF.Framework.Connection architecture summary: Architectural responsibilities, boundaries, and interaction patterns. status: draft owner: last_reviewed: 2026-07-23 library: SAIF.Framework.Connection reference_type: package --- # SAIF.Framework.Connection architecture `SAIF.Framework.Connection` is a thin, single-purpose connection-string resolution helper built around a single public class, `clsConnection`. It does not open, execute, or manage database commands itself; it only builds or resolves a `ConnectionString` value on a caller-supplied `OracleConnection` or `SqlConnection` object, delegating the actual string resolution to a remote `ConnectInfo` SOAP web service (with a local, Oracle-only override path when explicit credentials are supplied at construction). ## Responsibilities - Resolve Oracle connection strings by populating the `ConnectionString` property of a caller-supplied `OracleConnection` object, via `getConnection(inInstance, inCode, inUserid, ByRef inCnObj As OracleConnection, ...)`. - Resolve SQL Server connection strings by populating the `ConnectionString` property of a caller-supplied `SqlConnection` object, via `getConnection(inServer, inCode, inDatabase, ByRef inCnObj As SqlConnection)`. - Delegate connection-string resolution to the remote `ConnectInfo` ASMX/SOAP web service for both Oracle and SQL Server, except when explicit Oracle credentials are supplied at construction. - Provide a local, Oracle-only override path that bypasses the web service when the caller constructs `clsConnection` with explicit user/password credentials (`New(inOracleUser, inOraclePassword)`). - Apply post-processing to web-service-resolved Oracle connection strings: strip the literal `Load Balance Timeout=900;` clause and replace the `ZSPECIALCHAR` token with the BEL control character (`Chr(7)`).* ## Component boundaries - `clsConnection` (`SAIF.Framework.Connection` namespace): the sole public entry point. Owns constructor-based override state (`m_ConnectStringOverride`) and both `getConnection` overloads. Contains no SQL execution, no business-object base-class inheritance (`clsBusinessBase`/`clsBusinessCollectionBase`), and no direct database I/O. - `ConnectInfo.ConnectInfo` (auto-generated SOAP client proxy, `SAIF.Framework.Connection.ConnectInfo` namespace): inherits `SoapHttpClientProtocol`; exposes `GetOracleConnectString`, `GetDB2ConnectString`, and `GetSQLConnectString` (sync and async overloads). Only `GetOracleConnectString` and `GetSQLConnectString` are invoked by `clsConnection`; `GetDB2ConnectString` is present but unused within this library.* - `ConnectInfo.ConnectRequestInfo` (auto-generated DTO): carries `OSUserid`, `Code`, `Database`, and `Server` values as the request composite passed to the SOAP proxy. - Remote `ConnectInfo` ASMX web service (external boundary, not part of this library): the authoritative source of Oracle and SQL Server connection strings, hosted at `http://saifonline/WebServices/wsDBConnections/ConnectInfo.asmx`. - Caller (any consumer of this library): supplies instance/server/database/code identifiers plus a `ByRef` `OracleConnection` or `SqlConnection` object, and is solely responsible for opening, using, and disposing that connection after `getConnection` returns. ## Interaction model - The caller instantiates `clsConnection`, optionally supplying explicit Oracle credentials to the parameterized constructor, which sets `m_ConnectStringOverride = True`. - The caller invokes the Oracle or SQL Server overload of `getConnection`, passing identifying parameters and a `ByRef` connection object. - For the Oracle overload: if the override flag is set, `clsConnection` builds the connection string locally from the stored credentials; otherwise it instantiates the `ConnectInfo` SOAP proxy, builds a `ConnectRequestInfo` (Code, Database, current `System.Environment.UserName` as `OSUserid`), calls `GetOracleConnectString`, replaces `ZSPECIALCHAR` with `Chr(7)`, and strips `Load Balance Timeout=900;` from the result.* - For the SQL Server overload: `clsConnection` always builds a `ConnectRequestInfo` (Code, Database, Server, OSUserid) and calls `GetSQLConnectString` via the SOAP proxy; there is no local override path for SQL Server. - The resolved connection string is assigned to the caller's connection object's `ConnectionString` property; `clsConnection` returns control to the caller, which is responsible for opening/using/disposing the connection. - The `ConnectInfo` SOAP proxy's endpoint URL is read once, at proxy construction, from an auto-generated `ApplicationSettingsBase` (`My.Settings`) value (`SAIF_Framework_Connection_ConnectInfo_ConnectInfo`), declared in `app.config`. The following diagram shows high-level component interactions. ```mermaid flowchart TD Caller["Caller
(business/application code)"] --> ClsConnection["clsConnection
(getConnection overloads)"] ClsConnection -->|"override path
(Oracle only)*"| LocalBuild["Local connection-string
builder"] ClsConnection -->|"non-override path"| Proxy["ConnectInfo SOAP proxy
(SoapHttpClientProtocol)"] Proxy --> WebService["Remote ConnectInfo
ASMX web service"] LocalBuild --> Result["OracleConnection /
SqlConnection.ConnectionString"] Proxy --> Result Result --> Caller ``` ## Sequence diagram The following diagram shows the primary request/response sequence for the non-override (web-service-resolved) path. ```mermaid sequenceDiagram participant Caller participant clsConnection participant ConnectInfoProxy as ConnectInfo proxy participant ConnectInfoService as Remote ConnectInfo service Caller->>clsConnection: getConnection(instance/server, code, database, ByRef cnObj) clsConnection->>ConnectInfoProxy: New ConnectRequestInfo(Code, Database, OSUserid[, Server]) ConnectInfoProxy->>ConnectInfoService: GetOracleConnectString / GetSQLConnectString ConnectInfoService-->>ConnectInfoProxy: connection string ConnectInfoProxy-->>clsConnection: connection string clsConnection->>clsConnection: replace ZSPECIALCHAR with Chr(7) and strip "Load Balance Timeout=900" (Oracle only)* clsConnection-->>Caller: cnObj.ConnectionString populated ``` ## Design constraints - No `IBusinessCriteria`, `clsBusinessBase`, or `clsBusinessCollectionBase` inheritance — this is a low-level infrastructure/utility class, not a business object. - No direct SQL execution: `clsConnection` never calls `Open()`, `ExecuteReader`, or `ExecuteNonQuery`; opening and using the connection is entirely the caller's responsibility. - The non-override path introduces a runtime dependency on a network call to an external SOAP web service (`ConnectInfo.asmx`), not merely a design-time reference.* - The local override path is Oracle-only; no equivalent override exists for SQL Server, which always depends on the remote web service. - The Oracle connection-string post-processing (stripping `Load Balance Timeout=900;` and substituting `ZSPECIALCHAR` with `Chr(7)`) is undocumented in code comments; its business rationale is inferred from behavior only.* - The library has no authentication, authorization, or security-check logic; the only identity-related data point is the outbound use of `System.Environment.UserName` as an audit/context parameter (`Composite.OSUserid`), not an authorization check. - A large commented-out `` block in `app.config` defines a self-hosted WCF service configuration (`wcfDBConnections.ConnectInfo`) that is inactive and excluded from these findings. ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Dependencies](dependencies.md) - [Operations and processes](operations-processes.md) - [Business rules](business-rules.md) - [Configuration](configuration.md) - [API reference](api/index.md) > **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 - `SAIF.Framework.Connection\clsConnection.vb` - `SAIF.Framework.Connection\Web References\ConnectInfo\Reference.vb` - `SAIF.Framework.Connection\Web References\ConnectInfo\Reference.map` - `SAIF.Framework.Connection\Web References\ConnectInfo\ConnectInfo.wsdl` - `SAIF.Framework.Connection\app.config` - `SAIF.Framework.Connection\SAIF.BOF.Framework.Connection.vbproj`