pdcomm_gem_formatted_program_execution_start
Function
Starts tracking an execution of the selected program and returns its Start action.
PdcommStatus pdcomm_gem_formatted_program_execution_start(PdcommTcpEndpoint *endpoint, const PdcommGemFormattedProgramSelectionToken *selection_token, const PdcommGemFormattedProgramDryRunReportHandle *dry_run_report, PdcommGemFormattedProgramExecutionToken *out_execution_token, PdcommGemFormattedProgramExecutionActionHandle **out_action)Equipment only. The selection must still be current and the HSMS session must be selected. dry_run_report must come from this endpoint, must not be REJECT, and must still match the selection, the capability catalog presence and revision, and the program identity and command count.
When an execution is in START_PENDING for the same selection, report, and catalog, the call returns a new handle to the same pending Start action instead of starting another execution.
Parameters
| Name | Description |
|---|---|
endpoint | Equipment endpoint with formatted program queries configured. |
selection_token | Token from pdcomm_gem_formatted_program_select(). |
dry_run_report | Report from pdcomm_gem_formatted_program_dry_run(). It is only read; the caller keeps ownership. |
out_execution_token | Caller storage initialized with struct_size, version, and a zero reserved. On success the identity fields are written and struct_size is preserved. Not modified on failure. |
out_action | Receives the Start action. When endpoint is valid and not poisoned and both outputs are non-NULL, it is set to NULL first, so it is NULL after every later failure. |
Returns
#PDCOMM_OK on success; #PDCOMM_INVALID_ARGUMENT when a pointer is NULL or a token structure has an invalid size, version, or reserved field; #PDCOMM_STALE_TOKEN when the selection is not current, the report is from another endpoint, or the selection, catalog, or program changed since the dry run; #PDCOMM_INVALID_STATE when the endpoint is not a GEM equipment, formatted program queries are not configured, the HSMS session is not selected, the dry run outcome is REJECT, or another execution is not terminal; #PDCOMM_LIMIT_EXCEEDED when the program exceeds the configured limits or a counter is exhausted; #PDCOMM_BACKPRESSURE when the endpoint holds a staged TCP event; #PDCOMM_ALLOCATION_FAILED; #PDCOMM_POISONED.
Notes
- Ownership: release the action with pdcomm_gem_formatted_program_execution_action_destroy().