OCM Data Acquisition Control

Note

daqOcmServer hosts the Data Acquisition control interface daqif.OcmDaqControl under URI path /daq.

class daqif.OcmDaqControl

OCM Data Acquisition control interface.

StartDaq(id, file_prefix, prim_sources, meta_sources, properties) → DaqReply

Create and start new data acquisition with v1 merge-heuristics. If id is not provided (left empty) daqOcmServer will create a unique identifer automatically.

Heuristics

The following heuristics is used to determine how results are merged together. For more control use StartDaqV2().

• If a single primary data source produce a single FITS file this will selected as the in-place merge target. - Otherwise data sources produce multi-extension FITS files with no data in primary HDU. - Data sources have the following relative priority:

  Note

  Order determines merge order of keywords and extensions.

  1. Primary data sources in the order user specified in prim_sources.

  2. Metadata sources in the order user specified to meta_sources.

• Each data source produce keywords that will be merged to Data Product primary HDU returned via metadaqif or with FITS file primary HDU.

• There is currently no way to provide keyword rules that select and transforms keywords. All keywords in user class will be merged.

Arguments

The format for prim_sources and meta_sources is a space separated list of sources in the format: <name>@<rr-uri>, e.g. meta-source@zpb.rr://example:1234/daq.

There must be at least 1 data source.

Fail-fast

If any source fails to start the command will fail.

Parameters:

• id (str) – Optional unique identifier of data acquisition.

• file_prefix (str) – Optional file name prefix.

• prim_sources (str) – List of primary data sources (e.g. detectors).

• meta_sources (str) – List of metadata sources (e.g. FCF Device Manager or CCS).

• properties (str) – JSON properties (see StartDaqV1Properties {JSON}).

Returns:

If id was provided that is returned as an acknowledgement, otherwise the id generated by daqOcmServer is returned.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

StartDaqV2(specification) → DaqReply

New in version 2.1.0.

Create and start new data acquisition from JSON specification.

StartDaqV2() was introduced in to enable the capabilities of daqDpmMerge that was not possible to express using StartDaq(). The decision was also made to use JSON to express the specification to allow more flexible extensibility.

See Start DAQ v2 for detailed documentation of the JSON schema.

Note

This version is strictly more capable than StartDaq() and is required when additional control of the outcome is required. Unlike StartDaq() it also supports specifying how to merge FITS files that already exist.

Fail-fast

If any source fails to start the command will fail.

Parameters:

specification (str) – Serialized JSON document. See StartDaqV2Specification {JSON} for details.

Returns:

If id was provided that is returned as an acknowledgement, otherwise the id generated by daqOcmServer is returned.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

StopDaq(id) → DaqReply

Stops data acquisition and keep any data acquired.

Fail-Fast

If all data sources fail the command will report error by throwing DaqException. A partially successful execution is reported using normal status reply (which includes information about any partial failure). This is done because it is prioritized to create a partially complete data product over discarding all acquired data.

Parameters:

id (str) – Id of data acquisition to stop.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

ForceStopDaq(id) → DaqReply

Like StopDaq() the command stops data acquisition and keeps any data acquired. The only difference is that if non-fatal error occurs the Data Acquisition is marked as stopped whereas StopDaq() would not.

Fail-slow

The command is resilient to non-fatal errors. If any non-fatal errors occur the error flag in the reply is set but no exception is thrown. If fatal error occur DaqException is thrown.

Warning

Any data source that failed to stop properly will not be able to provide data to the Data Acquisition or the final Data Product.

Although daqOcmServer is always left in a consistent state, any data source that failed to stop may not. Manual intervention may be necessary to restore a problematic data source to a functional state.

Parameters:

id (str) – Id of data acquisition to forcibly stop.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

AbortDaq(id) → DaqReply

Aborts data acquisition and discards any data acquired.

Fail-fast

If any error occur DaqException is thrown and the DAQ state remains in Aborting.

Parameters:

id (str) – Id of data acquisition to abort.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

ForceAbortDaq(id) → DaqReply

Like AbortDaq() the command aborts data acquisition and discards any data acquired. The only difference is that if non-fatal error occurs the Data Acquisition is marked as aborted whereas AbortDaq() would not.

Fail-slow

The command is resilient to non-fatal errors. If any non-fatal errors occur the error flag in the reply is set but no exception is thrown. If fatal error occur DaqException is thrown.

Warning

Although daqOcmServer is always left in a consistent state, any data source that failed to abort may not. Manual intervention may be necessary to restore a problematic data source to a functional state.

Parameters:

id (str) – Id of data acquisition to forcibly abort.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

UpdateKeywords(id: str, keywords: str) → DaqReply

Update keywords for specified Data Acquisition. For each keyword:

• If it already exist [1], it is updated with the provided value,

• otherwise it is added.

[1]

OCM will compare keyword name as provided, while considering if it’s an ESO hiearchical keyword or standard FITS keyword.

Fail-fast

Command will not make any attempt to be robust against errors. Failures are treated as fatal and DaqException will be thrown.

Parameters:

• id (str) – Id of data acquisition to update.

• keywords (str) – JSON encoded set of keywords. Refer to JSON keywords schema for details.

Return type:

DaqReply

Raises:

DaqException – On fatal error.

RetryMergeDaq(id: str) → None

New in version 3.2.0.

Unblocks Data Acquisition that has been blocked from progress due to a failure in state DaqState.StateMerging. If for example Data Acquisition failed to transfer a source file this can be attempted again by sending RetryMerge().

Command is valid in state DaqState.StateMerging, after DaqSubState.Scheduled, and will return immediately after unblocking.

Parameters:

id (str) – Id of data acquisition with error to retry.

Raises:

DaqException – On error, e.g. if command is rejected.

AwaitDaqState(id, state, substate, timeout) → AwaitDaqReply

Replies when Data Acquisition reaches the requested state or when this state is impossible to reach. This is mainly used to support sequencing of higher level coordination activities.

The command will reply when condition is fulfilled or times out. When it times out this is indicated in the reply with AwaitDaqReply.timeout set to true.

Condition is fulfilled if Data Acquisition either:

1. Enters requested state. In this case the current state in reply is the same as the requested state.

2. Enters or is already in a state such that there is no valid transition to the requested state. In this case the current state in reply will not be the same as the requested state.

Note

If Data Acquisition is archived the request will reply if condition is already fulfilled otherwise exception will be raised.

Parameters:

• id (str) – Id of Data Acquisition to await.

• state (DaqState) – State of Data Acquisition to await.

• substate (DaqSubState) – Substate of Data Acquisition to await.

• timeout (float) – Duration in seconds to wait for condition to be fulfilled. Must be > 0.

Returns:

Current Data Acquisition status and indication if operation timed out.

Return type:

AwaitDaqReply

Raises:

DaqException – On fatal error (e.g. invalid arguments).

GetStatus(id) → DaqStatus

Get status of a Data Acquisition.

Note

If Data Acquisition has completed daqOcmServer will try to reply with status from most recently archived Data Acquisition with the same id.

Parameters:

id (str) – Id of Data Acquisition to get status for.

Return type:

DaqStatus

Raises:

DaqException – On fatal error.

GetActiveList() → List[DaqStatus]

Get list of active Data Acquisitions (i.e. not in daqif.DaqState.StateCompleted).

Returns:

List of active Data Acquisitions.

Return type:

List[DaqStatus]

Raises:

DaqException – On fatal error.