HPCC-22882 Document Std.System.Store module

[JamesDeFabia]

Type of change:

• This change is a bug fix (non-breaking change which fixes an issue).
• This change is a new feature (non-breaking change which adds functionality).
• This change improves the code (refactor or other change that does not change the functionality)
• This change fixes warnings (the fix does not alter the functionality or the generated code)
• This change is a breaking change (fix or feature that will cause existing behavior to change).
• This change alters the query API (existing queries will have to be recompiled)

Checklist:

• My code follows the code style of this project.
  • My code does not create any new warnings from compiler, build system, or lint.
• The commit message is properly formatted and free of typos.
  • The commit message title makes sense in a changelog, by itself.
  • The commit is signed.
• My change requires a change to the documentation.
  • I have updated the documentation accordingly, or...
  • I have created a JIRA ticket to update the documentation.
  • Any new interfaces or exported functions are appropriately commented.
• I have read the CONTRIBUTORS document.
• The change has been fully tested:
  • I have added tests to cover my changes.
  • All new and existing tests passed.
  • I have checked that this change does not introduce memory leaks.
  • I have used Valgrind or similar tools to check for potential issues.
• I have given due consideration to all of the following potential concerns:
  • Scalability
  • Performance
  • Security
  • Thread-safety
  • Cloud-compatibility
  • Premature optimization
  • Existing deployed queries will not be broken
  • This change fixes the problem, not just the symptom
  • The target branch of this pull request is appropriate for such a change.
• There are no similar instances of the same problem that should be addressed
  • I have addressed them here
  • I have raised JIRA issues to address them separately
• This is a user interface / front-end modification
  • I have tested my changes in multiple modern browsers
  • The component(s) render as expected

Smoketest:

• Send notifications about my Pull Request position in Smoketest queue.
• Test my draft Pull Request.

Testing:

[github-actions]

Jira Issue: https://hpccsystems.atlassian.net//browse/HPCC-22882

Jirabot Action Result:
Workflow Transition To: Merge Pending
Updated PR

[Copilot]

Pull request overview

Adds Standard Library Reference documentation for the STD.System.Store module (key/value store support) so users can discover and use the SOAP-backed store APIs from ECL.

Changes:

• Introduces a new DocBook chapter describing key/value store concepts (stores, namespaces, keys/values).
• Documents STD.System.Store(...) and its operations (CreateStore/ListStores/ListNamespaces/WithNamespace and key CRUD APIs).
• Adds a “Record Definitions” section describing response record structures.

Comments suppressed due to low confidence (3)

docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml:6

• This new Store module chapter doesn't appear to be included anywhere in the Standard Library Reference build (e.g., there's no xi:include for ECLStandardLibraryReference/SLR-Mods/Store.xml in docs/EN_US/ECLStandardLibraryReference/SLR-includer.xml), so it likely won't show up in the rendered documentation. Add an appropriate <xi:include ...Store.xml...> entry under the relevant chapter in SLR-includer.xml (or wherever Store docs are aggregated).

<chapter id="Store">
  <title><emphasis>Key/Value Store Support</emphasis></title>

docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml:101

• The espURL parameter description references Std.File.GetEspURL(), but the Std library reference documents this function as STD.File.GetEspUrl() (and the docs generally use the STD. prefix). For consistency and easier cross-referencing, update this mention to match the documented function name/casing and module prefix used elsewhere in the SLR.

            <entry>The full URL for accessing the esp process running on the
            HPCC Systems cluster (this is typically the same URL as used to
            access ECL Watch); set to an empty string to use the URL of the
            current esp process as found via Std.File.GetEspURL(); OPTIONAL,
            defaults to an empty string</entry>

docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml:1358

• GetAllKeysResponseRec (and other response records below) references nested dataset record types like KeySetRec / KeyValueRec / NamespaceLayout, but those layouts are not documented anywhere in the “Record Definitions” section. Since these define the fields users actually read (e.g., keys.key, key_values.key/value, namespaces.namespace), please add documentation for these record layouts (as additional sect2 entries or by expanding the field descriptions).

      <programlisting format="linespecific">EXPORT GetAllKeysResponseRec := RECORD
  STRING                      namespace;
  DATASET(KeySetRec)          keys;
  BOOLEAN                     has_exceptions;

[g-pan]

one minor comment about the DTD

[g-pan]

change the doctype declaration to chapter from sect1

[dcamper]

This looks accurate and complete. As such, I'll approve the PR.

One thing to consider: I find it useful to have relevant record structures explicitly listed with the functions that use/return them. To pick a random example. Std.File.LogicalFileList() returns a dataset and its record structure is listed in that same section. A similar layout could be applied here, especially since every function (that returns a dataset or record) has its own record definition.

Where my recommendation falls down concerns the ExceptionListLayout. That is a child dataset that is optionally included in all of the other datasets. It may be odd to duplicate that layout for every function. Maybe that could be placed at the end?

Anyway, it is your call on whether or not to rearrange anything. I think it would be more consistent with the rest of the document, and IMO more useful.

[g-pan]

seems reasonable.

[JamesDeFabia]

This looks accurate and complete. As such, I'll approve the PR.

One thing to consider: I find it useful to have relevant record structures explicitly listed with the functions that use/return them. To pick a random example. Std.File.LogicalFileList() returns a dataset and its record structure is listed in that same section. A similar layout could be applied here, especially since every function (that returns a dataset or record) has its own record definition.

Where my recommendation falls down concerns the ExceptionListLayout. That is a child dataset that is optionally included in all of the other datasets. It may be odd to duplicate that layout for every function. Maybe that could be placed at the end?

Anyway, it is your call on whether or not to rearrange anything. I think it would be more consistent with the rest of the document, and IMO more useful.

As we discussed, this is resolved

[github-actions]

Jirabot Action Result:
Added fix version: 10.2.18
Workflow Transition: 'Resolve issue'