Skip to content

Create a print batch with documents

This operation is the primary way a batch of documents is queued for printing. A caller starts a new clsXDocumentCollection, which builds an in-memory print-control header, adds one or more documents to the collection, and calls Save(). Saving persists the header first, then every document, so a batch and its documents are always created together in this workflow.

Field Value
Operation ID OP-003
Trigger Caller invokes clsXDocumentCollection.NewXDocumentCollection(...), calls AddXDocument() for each document, and calls Save()
Inputs XPrintControlSeqNum, directory name, XML file name, duplex mode, optional MD5 hash (for the header); per document: file name, document type code, email address, fax number, indexed contents text, ten sort values, start value, print group text
Outputs Inserted row in XPRINT_CONTROL; one inserted row per document in XDOCUMENT; error messages on row-count contention for either
Primary components clsXDocumentCollection.Create, clsXDocumentCollection.AddXDocument, clsXDocumentCollection.Save, clsXDocument.Create, clsXDocument.BeforeInsert/AfterInsert
Entry point Services\SAIF.Services.Printing.Remote\clsXDocumentCollection.vb, Services\SAIF.Services.Printing.Remote\clsXDocument.vb

Steps

  1. Start a new batch. Caller invokes clsXDocumentCollection.NewXDocumentCollection(inDataportal, inXPrintControlSeqNum, inDirectoryName, inXMLFileName, inDuplexMode, inMD5HashValue), which calls Create().
  2. Build the in-memory header. Create() sets XPrintControlSeqNum from the criteria, then constructs the header via clsXPrintControl.NewXPrintControl(MyCriteria.DataPortalInfo, XPrintControlSeqNum) and populates its directory name, duplex mode, XML file name, and MD5 hash from the criteria. The header is held in memory only at this point — it is not yet saved.
  3. This header construction and its later persistence follow the same Create/Insert behavior described in Print-control batch header lifecycle; this operation does not duplicate that header logic, it invokes it as part of Save() (step 5).
  4. Add documents to the batch. Caller calls AddXDocument() one or more times. Each call invokes clsXDocument.NewXDocument(MyCriteria.DataPortalInfo, XPrintControlSeqNum, PrintGroupText), which calls clsXDocument.Create():
  5. If the document's criteria XDocumentSeqNum is 0: Create() calls MyCriteria.DataPortalInfo.GetNextSeqNum("XDOCUMENT_SEQ") to generate the primary key.
  6. Create() sets PrintGroupText and XPrintControlSeqNum from the criteria, then defaults CopiesCount = 1 and XBinTypeCode = "AUTO" (BR-005).
  7. AddXDocument() also applies the batch's DuplexMode to the new document before adding it to the collection.
  8. Increment the print-group counter (optional). Caller may invoke IncrementPrintGroupNumber() between AddXDocument() calls to advance the batch's print-group sequence number, which feeds the PrintGroupText computed property (prefix + timestamp + group number) used by subsequent documents.
  9. Save the batch. Caller calls Save(), which first calls ApplyEdit(), then XPrintControl.Save() to persist the header.
  10. If the header save succeeds: MyBase.Save() runs, persisting each added document in turn via its own BeforeInsert/AfterInsert lifecycle, executing SQL-006 (INSERT INTO XDOCUMENT ..., XDOCUMENT) for each document with its 22 bound parameters (copies, document type code, email address, fax number, file name, indexed contents text, ten sort values, start value, bin type code, document sequence number, print-control sequence number, print group text, duplex code).
    • Each document's AfterInsert checks RowsAffected <> 1 and adds InsertError on contention (BR-001).
  11. If the header save fails (XPrintControl.Save() returns False): the collection's own Save() does not explicitly return a value for this branch, so the outcome for the caller in this path is not confirmed from source.**

Process flow

The following diagram visualizes building and saving a print batch with its documents.

flowchart TD
    Start([Caller starts NewXDocumentCollection]) --> Hdr[Create: build in-memory<br>XPrintControl header]
    Hdr --> AddLoop[Caller calls AddXDocument<br>for each document]
    AddLoop --> DocCreate[Document Create:<br>generate seq num,<br>default CopiesCount=1,<br>XBinTypeCode=AUTO]
    DocCreate --> More{More documents?}
    More -->|Yes| AddLoop
    More -->|No| Save[Caller calls Save]
    Save --> HdrSave[XPrintControl.Save<br>Insert into XPRINT_CONTROL]
    HdrSave --> HdrCheck{Header save succeeded?}
    HdrCheck -->|No| Unclear([Outcome not confirmed<br>from source])
    HdrCheck -->|Yes| DocSave[Base Save: Insert each<br>document into XDOCUMENT]
    DocSave --> DocCheck{RowsAffected = 1<br>per document?}
    DocCheck -->|No| DocErr([InsertError added<br>per failing document])
    DocCheck -->|Yes| Done([Batch and documents persisted])

Failure and edge-case behavior

  • The header is saved before any document; if the header insert fails contention-wise, AfterInsert on the header adds an error, but whether that error alone prevents document persistence (short-circuits Save()) is not fully confirmed — XPrintControl.Save()'s boolean return is checked, but its exact failure semantics under contention (versus a hard exception) are not verifiable purely from this library's source.**
  • Newly added documents always receive CopiesCount = 1 and XBinTypeCode = "AUTO" regardless of caller intent unless the caller explicitly overrides these properties after AddXDocument() returns (BR-005).
  • PrintGroupText is computed from a prefix, a timestamp captured at collection construction, and a group number that only advances when the caller explicitly calls IncrementPrintGroupNumber() — documents added without an intervening call share the same print group text.
  • clsXDocument has no live update or delete lifecycle — once a document is inserted via this operation, no method in this library modifies or removes it individually; documents are only removed in bulk via Delete documents for a batch.

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

  • Services\SAIF.Services.Printing.Remote\clsXDocumentCollection.vb
  • Services\SAIF.Services.Printing.Remote\clsXDocument.vb
  • Services\SAIF.Services.Printing.Remote\clsXPrintControl.vb