---
title: Load help text from the database
summary: Retrieves help text (single entry or full list) for an application code from the APPLICATION_HELP tables.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.AJAX.Infragistics111
reference_type: package
operation_id: OP-AJAX-07
trigger: Consumer code populates a HoverHelp control via Fill(clsHelpText), or requests the full list for an application code
---

# Load help text from the database

This operation retrieves help text from `APPLICATION_HELP_MASTER` / `APPLICATION_HELP_DETAIL` for a single reference key ( `clsHelpText.GetHelpText` ) or for every reference key under an application code ( `clsHelpTextCollection.GetHelpTexts` ), then feeds the result into a `HoverHelp` control.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-AJAX-07 |
| **Trigger** | Consumer code populating a `HoverHelp` control via `Fill(clsHelpText)`, or requesting the full help-text list for an application code |
| **Inputs** | `IDataPortalInfo`, `ApplicationCode`, `ReferenceKeyValue` (single-entry variant only) |
| **Outputs** | Populated `clsHelpText` (single) or `clsHelpTextCollection` (multi-row) instance |
| **Primary components** | `clsHelpText.GetHelpText`, `clsHelpTextCollection.GetHelpTexts`, `HoverHelp.Fill` |
| **Entry point** | `SAIF.Presentation.Web.Controls.AJAX.Infragistics111/clsHelpText.vb` |

## Steps

1. Construct `Criteria(dpi, applicationCode, referenceKeyValue)` and call `RetrieveObject`.
   - `clsHelpText.Criteria` and `clsHelpTextCollection.Criteria` implement `IBusinessCriteria`, so the retrieve call is dispatched through the framework's criteria-based data-portal pipeline rather than direct ADO.NET access.
   - **Retrieve business object from criteria** — uses the `IBusinessCriteria` instance with populated `DataPortalInfo`, exposed as `IDataAccess.RetrieveObject(criteria)`.

> **Origin**: This sub-step is implemented in `IBusinessCriteria` / `IDataAccess.RetrieveObject` (`SAIF.Framework.Core`) and executed on behalf of this operation.
2. `BeforeRetrieve` creates a request with ID `BOC.RetrieveSQL`, `CommandType.Text`, statement `RetrieveSQL`, and binds `ApplicationCode` (max 5) and `ReferenceKeyValue` (max 40, single-entry variant only). ([BR-AJAX-017](../business-rules.md#br-ajax-017-help-text-is-identified-by-an-application-code-and-reference-key-with-length-ceilings), [BR-AJAX-018](../business-rules.md#br-ajax-018-help-content-is-assembled-by-joining-master-and-detail-on-the-reference-key), [SQL-001](../sql/SQL-001-help-text-retrieve-by-key.md), [SQL-002](../sql/SQL-002-help-text-list-retrieve.md)). Tables: [APPLICATION_HELP_MASTER](../database-tables.md#application_help_master), [APPLICATION_HELP_DETAIL](../database-tables.md#application_help_detail).
3. **Single-entry variant (`clsHelpText`):** `AfterRetrieve` casts the result to `clsSAIFDataReader`, reads at most one row, calls `Fill` (mapping `ApplicationCode`, `ReferenceKeyDescription`, `ReferenceKeyValue`, `HelpText`), then `MarkOld`. ([BR-AJAX-019](../business-rules.md#br-ajax-019-a-help-lookup-that-matches-nothing-yields-empty-text-not-an-error))
   - If no row matches, the object is returned with empty-string properties rather than `Nothing`.
4. **Multi-row variant (`clsHelpTextCollection`):** `AfterRetrieve` casts the result to `IDataReader` and loops while rows remain, constructing a `clsHelpText` per row via `Load`, and adding it to the collection.
5. `HoverHelp.Fill(inHelpObject)` then assigns `ContentText = inHelpObject.HelpText`, ignoring a `Nothing` argument. ([BR-AJAX-020](../business-rules.md#br-ajax-020-filling-a-help-control-with-a-null-help-object-leaves-content-unchanged))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Consumer requests help text]) --> Criteria[Construct Criteria with dpi, ApplicationCode, ReferenceKeyValue]
	Criteria --> Retrieve[IDataAccess.RetrieveObject via IBusinessCriteria]
	Retrieve --> Bind[BeforeRetrieve binds ApplicationCode / ReferenceKeyValue]
	Bind --> Exec[Execute the retrieve statement]
	Exec --> Single{Single-entry<br>variant?}
	Single -->|Yes| ReadOne[Read at most one row, Fill, MarkOld]
	Single -->|No| ReadMany[Loop rows, construct clsHelpText per row]
	ReadOne --> FillHover[HoverHelp.Fill sets ContentText]
	ReadMany --> EndCollection([clsHelpTextCollection populated])
	FillHover --> EndOne([HoverHelp content set])
```

## Failure and edge-case behavior
- A lookup that matches no row returns a `clsHelpText` with empty-string properties rather than `Nothing` or an exception. ([BR-AJAX-019](../business-rules.md#br-ajax-019-a-help-lookup-that-matches-nothing-yields-empty-text-not-an-error))
- Passing a `Nothing` help object to `HoverHelp.Fill` leaves the control's existing content unchanged rather than raising a null-reference error. ([BR-AJAX-020](../business-rules.md#br-ajax-020-filling-a-help-control-with-a-null-help-object-leaves-content-unchanged))

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

## Sources
- `SAIF.Presentation.Web.Controls.AJAX.Infragistics111/clsHelpText.vb`
- `SAIF.Presentation.Web.Controls.AJAX.Infragistics111/clsHelpTextCollection.vb`
- `SAIF.Presentation.Web.Controls.AJAX.Infragistics111/HoverHelp.vb`