---
title: Retrieve documents for printing
summary: Loads a batch's documents joined to printer/bin routing, either per document in sort order or grouped for single-job printing.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Services.Printing.Remote
reference_type: package
operation_id: OP-005
trigger: A print job calls clsXDocumentCollection.Retrieve/GetXDocumentCollection with a print-control batch and printer, selecting a PrintType
---

# Retrieve documents for printing

This operation loads the documents belonging to a print-control batch, resolved against the physical printer and bin routing tables, in one of two shapes selected by `PrintType`: per-document (`ByDocSeq`), for iterating and printing each document individually in sort order, or grouped (`ByPrintGroup`), for print jobs that treat an entire print group as a single unit. Both shapes are produced by the same `clsXDocumentCollection` retrieve path and share the same join and parameters — they differ only in the SQL text selected and the shape of the result set.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-005 |
| **Trigger** | Caller invokes `clsXDocumentCollection.GetXDocumentCollection(inXPrintControlSeqNum, inPrinterID, inPrintType)` |
| **Inputs** | `XPrintControlSeqNum`, `PrinterID`, `PrintType` (`ByDocSeq` or `ByPrintGroup`) |
| **Outputs** | Collection of `clsXDocument`, each carrying resolved `XBinNumber` and `PrinterNetworkName` |
| **Primary components** | `clsXDocumentCollection.BeforeRetrieve`, `clsXDocumentCollection.AfterRetrieve` |
| **Entry point** | `Services\SAIF.Services.Printing.Remote\clsXDocumentCollection.vb` |

## Steps

1. **Select the retrieval shape.** Caller invokes `GetXDocumentCollection(...)` with `PrintType = ByDocSeq` (per-document) or `PrintType = ByPrintGroup` (grouped). `BeforeRetrieve` binds `:XPrintControlSeqNum` and `:PrinterID` regardless of which shape is selected.
2. **Per-document retrieval (`ByDocSeq`).** `BeforeRetrieve` sets the request's SQL text to `MyCriteria.RetrieveSQL`, executing [SQL-011](../sql/SQL-011-saif-services-printing-remote.md): a three-table join across `XDOCUMENT`, `XPRINTER_BIN`, and `XPRINTER` ([XDOCUMENT](../database-tables.md#xdocument), [XPRINTER_BIN](../database-tables.md#xprinter_bin), [XPRINTER](../database-tables.md#xprinter)) that resolves the physical bin number (`BIN_NUM`) and printer network name (`NETWORK_NAME`) for the given printer and batch, ordered by the ten sort-value columns.
3. **Grouped retrieval (`ByPrintGroup`).** `BeforeRetrieve` sets the request's SQL text to `MyCriteria.RetrievePrintSQL`, executing [SQL-012](../sql/SQL-012-saif-services-printing-remote.md): a `SELECT DISTINCT` variant of the same join, keyed on `PRINT_GROUP_TEXT` with literal placeholder values (`'n/a'`, fixed `CopiesCount = 1`) standing in for per-document columns that are not meaningful at group level, ordered by `PRINT_GROUP_TEXT`.
4. **Load the result.** `AfterRetrieve` iterates the `IDataReader` and constructs a `clsXDocument` per row via `Load()`, adding each to the collection — for the grouped shape, the result drives "print as one group" scenarios rather than per-document iteration.*

## Process flow

The following diagram visualizes the two retrieval shapes sharing the same join.

```mermaid
flowchart TD
	Start([Caller calls GetXDocumentCollection<br>with XPrintControlSeqNum, PrinterID, PrintType]) --> Which{PrintType?}
	Which -->|ByDocSeq| PerDoc[Join XDOCUMENT, XPRINTER_BIN, XPRINTER<br>resolve BinNum + NetworkName<br>order by 10 sort values]
	Which -->|ByPrintGroup| Grouped[SELECT DISTINCT on same join<br>keyed on PrintGroupText<br>literal placeholders for per-doc columns]
	PerDoc --> Load[Load rows into<br>clsXDocument collection]
	Grouped --> Load
	Load --> End([Collection returned to caller])
```

## Failure and edge-case behavior

- Both shapes require a matching `XPRINTER_BIN` row for the document's `XBIN_TYPE_CODE` and the given `PrinterID` — a document whose bin type has no configured route for that printer is excluded from either result set (inner join semantics).
- The grouped shape's placeholder values (`'n/a'`, fixed `CopiesCount = 1`) mean per-document fields are not usable from a grouped result; callers needing per-document detail must use `ByDocSeq` instead.
- `PrintType` defaults to `ByDocSeq` on the criteria class when not explicitly specified via the three-argument overload.

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

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

## Sources
- `Services\SAIF.Services.Printing.Remote\clsXDocumentCollection.vb`