class LogBookRun {
public:
typedef struct _RunInfo {
int s_id;
int s_number;
std::string s_title;
} RunInfo, *pRunInfo;
typedef struct _Transition {
int s_id;
int s_transition;
std::string s_transitionName;
int s_transitionTime;
std::string s_transitionComment;
LogBookShift* s_onDuty;
} Transition, *pTransition;
typedef struct _Run {
RunInfo s_Info;
std::vector<Transition> s_transitions;
} Run, *pRun;
public:
LogBookRun(CSqlite& db, int id);
const RunInfo& getRunInfo() const;
bool isCurrent(CSqlite& db) const;
const Transition& operator[](int n) const;
size_t numTransitions() const;
int lastTransitionType() const;
const char* lastTransition() const;
bool isActive() const;
void transition(CSqlite& db, const char* type, const char* note);
//
static LogBookRun* currentRun(CSqlite& db);
static int runId(CSqlite& db, int runNumber);
static int begin(
CSqlite& db, int number,
const char* title, const char* remark=nullptr
);
static void end (
CSqlite& db, int runid,
const char* remark=nullptr
);
static void pause (
CSqlite& db, int runid,
const char* remark=nullptr
);
static void resume (
CSqlite& db, int runid,
const char* remark=nullptr
);
static void emergency_end (
CSqlite& db, int runid,
const char* remark
);
static std::vector<LogBookRun*> list(CSqlite& db);
static LogBookRun* find(CSqlite& db, int runNumber);
static bool isLegal(CSqlite& db, int runId, int proposedTransition);
};
... -I$DAQINC -L$DAQLIB -lLogbook -Wl,-rpath=$DAQLIB
Data taking is divided into time segments. Each segment of data taking is called a run. Runs and their state transitions (e.g. from active to ended) are logged in the logbook database. This logging can be automated by using the logbookbundle package with the Readout GUI.
In LogBookShift we learned that shifts are collections of people and that a shift can be set to be the current shift. When run state transitions are logged, the current shift is associated with that transition. This allows us to know who was on duty during that segment of data taking.
The LogBookShift encapsulates one run
and its transition history in the logbook database. We can think
of a run as consisting of information about the run;
the run number, run title, and a sequence of state transitions that
each contain a transition type (e.g. begining the run), the time
the transition was logged, the shift that was on-duty
and, in the logbook, a short remark
associated with the transition
Some of the methods described in this section are not intended for
general use but serve to hide implementation details from the
LogBook top level API class. Nevertheless, they are
documented here in case some unanticipated use case arises that
necessitates an application making use of them in a time-scale too urgent
to allow the needed capabilities to be put in the top level API.
These methods will be noted as not intended for general use in the
documentation below.
LogBookRun(CSqlite& db, int id);
This constructor is not intended for general use. It is used
by the LogBook class to wrap an existing
run in the database referenced by the Sqlite++ database connection
object db that has the primary
key id.
All information about the run are fetched from the database and loaded into the object under construction.
const const RunInfo& getRunInfo();
Returns a const reference to a struct within the object that
provides all information about the run. The
RunInfo structure is documented in
DATA Types below.
const bool isCurrent(CSqlite& db);
Not intended for general use but used to hide implementation
details from the LogBook class
Returns true if the object represents
the current run in the logbook database referenced by the
Sqlite++ database connection object db,
otherwise returns false.
const const Transition& operator[](int n);
Returns a const reference to a
Transition struct that describes
the n'th transition (the Begin run
transition is number 0). If n
is out of range, a std::out_of_range
error is thrown. See numTransitions
below.
const size_t numTransitions();
Returns the number of transitions the run has undergone.
operator[] can be used to
retrieve references to each transition.n
const int lastTransitionType();
Returns the integer code associated with the most recent
transition the run underwent. See
DATA TYPES for a definition of the
transition code values. It may be simpler, instead to
use lastTransition which returns
a string version of the transition.
Again see DATA TYPES.
It is the most recent transition that determines the current state of the run as understood by the logbook.
const const char* lastTransition();
Returns a text string that describes the most recent transition the run had. The most recent run state transition determines the current state of the run. See DATA TYPES for information about the possible values this can take.
const bool isActive();
Examines the last state transition the run has undergone and returns true if that transition implies the run has not ended (note that PAUSED runs are considered active too). If not false is returned
void transition(CSqlite& db, const char* type, const char* note);
This is not intended for general use. It hides the implementation
details of runs and transitions from the
LogBook class.
Attemtps to perform an arbitrary state transition. on
the run stored in the database connected to the
db Sqlite++ connection object.
The type parameter is a string
that identifies the type of transition to attempt.
See DATA TYPES for a list of legal strings.
note is a pointer to a character string
that is a remark to associate with the transition.
Several error conditions are possible which all throw
LogBook::Exception exceptions:
The transition name string does not designate a legal transition name.
The transition requested is not legal because the current state of the run forbids it. For example, a run whose prior transition was BEGIN cannot undertake a RESUME transition.
There is no current shift. The current shift is associated with the transition. If there's no current shift, no runs can undertake transitions.
Any error condition detected interacting with the database.
Note that if the state transition terminates the run (END or EMERGENCY_END), and the run is the current run, the database is told there is no current run.
static LogBookRun* currentRun(CSqlite& db);
Not intended for general use. If the logbook database
referenced by db has a current
run, it is wrapped in a dynamically created
LogBookRun and a pointer to that
object is returned. If not nullptr is
returned. It is the responsibility of the client to
dispose of the returned object via delete
when it is no longer needed.
static int runId (CSqlite& db, int runNumber);
Not intended for general use. This method returns
the primary key of the run numbered
runNumber from the logbook
database referenced by db.
If there is no run with that number a
LogBook::Exception is returned.
static int begin(CSqlite& db, int number, const char* title, const char* remark = nullptr);
Not intended for general use. This method
creates a new run with the provided
number and title
in the database referenced by db
and remark.
It then uses
transition to initiate a
BEGIN state transition to log the
beginning of that run. It then makes that
run the current run. The following errors can be thrown
as LogBook::Exception objects:
A run with this run number cannot already exist.
There cannot already be a current run.
The return value from this method is the primary key assigned to the new run by the database when it was created.
static void end(CSqlite& db, int runid, const char* remark = nullptr);
This is not intended for general use.
Attempts an end run transition on the run identified
by the primary key runid
db is the Sqlite++ database
connection object connnected to the datasbase to be modified.
remark is the comment to be associated
with the transition.
In addition to any error the transition
method may throw, an exception is, of course, thrown if
there is no run with the primary key runid.
static void pause (CSqlite& db, int runid, const char* remark = nullptr);
Same as end but attempts a
PAUSE transition to log that the
on-going data taking run has been paused.
static void resume(CSqlite& db, int runid, const char* remark = nullptr);
same as end however attempts
a RESUME transition. That is a run,
whose data taking is in the paused state due to the most
recent transition being PAUSE is marked
as actively taking data again.
static void emergency_end(CSqlite& db, int runid, const char* remark);
Attemts an EMERGENCY_END transition. This marks a run ended in a way that flags the end was not normal. The most common use of EMERGENCY_END is data acquisition system failure while a run was active. When the system starts up, it then detects that there is a currently active run in the logbook and forces an EMERGENCY_END to ensure there's no active/current run when the next BEGIN is attempted.
static std::vector<LogBookRun*> list(CSqlite& db);
Not for general use. This method returns a vector of
pointer to LogBookRun objects that
encapsulate all runs in the logbook.
The objects pointed to are dynamically instantiated. Once
they are no longer needed, you must delete
them all in order to prevent memory/resource leaks.
db is the Sqlite++ database object
that is connected to the logbook database.
static LogBookRun* find(CSqlite& db, int runNumber);
Not intended for general use. Locates the run with in
the database referenced by db with
the run number runNumber and
wraps the data associated with it in a
LogBookRun object returning a pointer to it.
If there is no match, a nullptr is returned
instead.
Note that the pointer returned points to a dynamically allocated object. To prevent memory/resource leaks, when the program no longer needs that object it should use delete to destroy it.
static bool isLegal(CSqlite& db, int runId, int proposedTransition);
Not intended for general use. Locates the run in the
database referenced by db with the
primary key runId and checks to see
if the current state of that run allows the
proposedTransition to occur.
If so true is returned otherwise
false.
This method can throw an
LogBook::Exception if, for example,
there is no matching run.
The LogBookRun class defines three public
data types. These data types, and their members are described
in this section.
RunInfoThis struct provides the run metadata. It consists of the following fields:
s_idContains the primary key of the run that is described by this run metadata.
s_numberContains the run number of the run that's described by this run metadata.
s_titleContains the title of the run described by this struct instance.
The Transition structure provide information
about a single transition the run has undergone.
LogBookRun instances contain a sequence of at least
one transitions (a BEGIN transition is what brings
a run into being).
Transition structs have the following fields:
s_idPrimary key of the transition in the transition table. See the Logbook Schema reference page for the full logbook schema.
s_transitionAn integer that describes the transition see State transition values for the values this can take.
s_transitionNameContains a text string that identifies the transition represented by this struct. See State transition values for information about the values this string can take.
s_transitionTimeThe time(2) at which this transition was logged.
s_transitionCommentA remark that can be logged with the transition. This is interpreted as plain text, however, if markdown is included, it will be properly rendered by the logbook renderers.
s_onDuty
Pointer to a LogBookShift object
that encapsulates the shift that was on duty when this
transition was logged. For more on this object type, see
LogBookShift
Table 1. State transition values
| s_transition value | s_transitionName value | Transition type |
|---|---|---|
| 1 | BEGIN | Begin run. This is always the first transition |
| 2 | END | End of run. This or EMERGENCY_END are always the last transition. |
| 3 | PAUSE | Pause run. Data taking is temporarly paused. |
| 4 | RESUME | Resume run. Indicates a paused run has resumed taking data. |
| 5 | EMERGENCY_END | Abnormal end of run. |
This struct contains all of the information about a run fetched from the database:
s_InfoContains the run metadata
s_transitionsContains all of the information about all of the transitions the run has undergone. The elements of this arrary are in chronological order.