---
title: Resolve Oracle connection
summary: Populate a caller-supplied OracleConnection with a locally composed or service-resolved connection string.
status: draft
owner: SAIF Framework
last_reviewed: 2026-07-30
library: SAIF.Framework.Connection
reference_type: package
operation_id: OP-CONN-001
trigger: Caller invokes the Oracle overload of clsConnection.getConnection
---

# Resolve Oracle connection

This operation populates the `ConnectionString` of a caller-supplied `OracleConnection`. Depending on how the `clsConnection` instance was constructed, it either composes the string locally from override credentials or resolves it from the remote `ConnectInfo` SOAP service, then normalizes the result before handing control back to the caller.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CONN-001 |
| **Trigger** | Caller request to populate an `OracleConnection` |
| **Inputs** | `inInstance`, `inCode`, `inUserid` (unused), `inCnObj`, constructor state (`m_Userid`, `m_Password`, `m_ConnectStringOverride`), optional pooling arguments (`inPoolFlag`, `inLifeTime`, `inMaxPoolSize`, `inMinPoolSize`) |
| **Outputs** | `inCnObj.ConnectionString` populated with the final Oracle connection string |
| **Primary components** | `clsConnection.getConnection`, `ConnectInfo.ConnectInfo.GetOracleConnectString` |
| **Entry point** | `SAIF.Framework.Connection\clsConnection.vb` |

## Steps

1. Instantiate a `ConnectInfo.ConnectInfo` SOAP proxy and a blank `ConnectInfo.ConnectRequestInfo` request object.
   - The generated proxy constructor reads the service endpoint URL from the [`SAIF_Framework_Connection_ConnectInfo_ConnectInfo` setting](../configuration.md).
2. Evaluate whether the instance carries override state from construction.
   - If `m_ConnectStringOverride` is `True`, skip the remote lookup entirely and compose `CnString` locally from `inInstance`, `m_Userid`, and the literal placeholder `******` in place of the actual password, along with the fixed segments `Persist Security Info=False`, `Max Pool Size=20`, and `Load Balance Timeout=900;` ([BR-001](../business-rules.md#br-001-explicit-oracle-credentials-bypass-the-remote-connection-resolution-service)).
     - This branch does not populate `Composite`, does not read `inCode`, `inUserid`, or any of the pooling arguments, and — because `m_Password` is never read here — does not embed the caller's actual password in the resulting string.**
     - If `inCnObj` is `Nothing`, this branch does not allocate a replacement `OracleConnection`; the subsequent assignment to `ConnectionString` has no target and is effectively lost.
3. If override state is not active, prepare the outbound request for the remote lookup.
   - Set `Composite.Code = inCode`.
   - Set `Composite.Database = inInstance`.
   - Set `Composite.OSUserid = System.Environment.UserName`; the `inUserid` parameter passed by the caller is never consulted.
   - If `inCnObj` is `Nothing`, create a new `OracleConnection` and use it as the resolution target.
4. Resolve the Oracle connection string from the web service.
   - Call `Client.GetOracleConnectString(Composite)`.
   - Replace every occurrence of the sentinel token `ZSPECIALCHAR` in the returned string with the BEL control character `Chr(7)` ([BR-003](../business-rules.md#br-003-zspecialchar-token-is-restored-to-a-control-character-in-web-service-resolved-oracle-strings)).
5. Normalize and apply the final string, regardless of which branch produced it.
   - Remove the literal segment `Load Balance Timeout=900;` from `CnString` before assignment ([BR-002](../business-rules.md#br-002-load-balance-timeout-is-always-stripped-from-oracle-connection-strings)).
   - Assign the normalized value to `inCnObj.ConnectionString`.
   - On failure: exceptions raised during proxy construction, the SOAP call, null-object access, or the final property assignment propagate to the caller unchanged; this method has no local `Try`/`Catch` handling.
6. Return control to the caller.
   - `clsConnection` does not open, test, or dispose the `OracleConnection`; the caller owns that lifecycle from this point forward.

## Process flow

The following diagram visualizes this operation's control flow, including the two ways the final connection string can be produced.

```mermaid
flowchart TD
	Start([Caller invokes Oracle getConnection]) --> Init[Instantiate ConnectInfo proxy and request object]
	Init --> Override{Override state active?}
	Override -->|Yes| LocalBuild[Compose connection string locally with placeholder password]
	Override -->|No| Prepare[Populate Composite and ensure OracleConnection exists]
	Prepare --> Resolve[Call GetOracleConnectString]
	Resolve --> Restore[Replace ZSPECIALCHAR with Chr 7]
	LocalBuild --> Normalize[Strip Load Balance Timeout]
	Restore --> Normalize
	Normalize --> Assign[Assign ConnectionString]
	Assign --> EndOk([Return populated OracleConnection])
```

## Failure and edge-case behavior

- If `inCnObj` is `Nothing` on the override branch, this method never creates a replacement `OracleConnection` before attempting to assign `ConnectionString`, so the caller effectively receives no usable connection object.
- The Oracle overload ignores `inUserid` and all four optional pooling arguments on every code path.
- The override branch hard-codes `Max Pool Size=20` and substitutes a literal `******` placeholder instead of reading `m_Password`; the analysis found no explanation for why the stored password is not used, so this behavior is treated as an unconfirmed limitation rather than a documented design choice.**
- Any failure in proxy construction, the SOAP invocation, or the connection-string assignment exits the method without local recovery logic, surfacing directly to the caller.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.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\My Project\Settings.Designer.vb`
- `SAIF.Framework.Connection\app.config`