AAO DRAMA/DRAMA2 C++ Interface

This page is the front page for the documentation for the DRAMA 2 C++ interfaces to DRAMA.

The core of DRAMA is written in C and was done well before C++ was available in a standard way on all the machines of interest. As a result, the C++ interfaces came later. There are a set of older C++ interfaces which have been distributed for some years, but which are a poor mapping to modern C++ and should not be used for new work.

DRAMA2 provides a new C++ interface to DRAMA, interfaces which presume C++11 or later is available and makes extensive use of features of the upgraded compilers.

This documentation is generated automatically from the source code headers using the doxygen tool.

There is also a set of examples and a document describing how to use these interfaces - the document is the preferred way to learn DRAMA2.
These are available in the DRAMA sub-system Drama2Examples. The Document as a PDF is available.

Below we have a quick introduction to each of the significant classes. There are various other minor classes and types. See the drama namespace namespace for the full contents.

• drama::sds::Id This is a class which provides an interface to the the DRAMA SDS Library. See the Self Defining Data System for full details on SDS itself. Of particular interest is that the C++ interface removes, in most cases, the need to tidy up SDS, by using C++ destructors. This class also implements creation of and access to typical DRAMA command argument structures, traditionally done with the Arg series of routines.

• drama::sds::DataPointer provides template classes for accessing the data of an SDS item.
• drama::sds::IdIterator Provides an iterator for working through SDS structures.
• drama::sds::ArrayWriteHelper and drama::sds::ArrayReadHelper provide help in accessing arrays of primitive items in an SDS structure.

• drama::Parameter This class provides for creation of DRAMA Sdp parameters and access to those parameters

• drama::ParSys This class provides for more general access to DRAMA Sdp parameters, no reference to the creating class is needed.

• drama::ParId Provides access to DRAMA Sdp parameters via their SDS Id. A sub-class of drama::sds::Id which can be returned by drama::ParSys Get methods.

• drama::Exception This is a class which is thrown as an exception any time the DRAMA C layers return an error to the C++ layers.

• drama::Task This class implements a DRAMA task. Running the constructor creates the task and methods within it allow you to run the task. Methods are provided to add Actions to the tasks.

• drama::EntryInfo This class is used to access details about an action entry (the action argument etc).

• drama::logging::Logger Implements task logging. An object of this type is created automatically by a drama::Task and is available via the drama::Task::RefTaskLogger() method.
  But logging is not started until drama::logging::Logger::Open() is invoked.

• drama::MessageHandler This class is an interface which must be implemented by task authors to implement their actions.
• drama::Spawnable This class is an interface which must be implemented by task authors to implement spawnable actions.

• drama::thread::TAction A class used for implementing actions which run as separate threads.

• drama::thread::TUface A class which can be used to allow non-action threads to send DRAMA messages and block waiting for their replies. This uses the DRAMA UFACE (User Interface) context, as a typical use is the implementation of user interfaces.

• drama::thread::KickNotifier - An object used to obtain notifications of Kick messages in compute intensive operations.

• drama::thread::SignalBlocker Constructing an object of this type will block all block-able UNIX signals in the current thread

• drama::Path A class which provides access to DRAMA's facilities for initiating messages to other tasks. The methods will be invoked from actions implemented via drama::thread::TAction or UFACE threads which have created a drama::thread::TUface object.

• drama::MessageEventHandler A class used to process replies to DRAMA messages send using Path objects.
  

• drama::thread::Monitor An abstract class used to implement DRAMA parameter monitors (monitoring of the change of the value of a parameter in another task.

• drama::thread::MonitorByType A concrete sub-class of drama::thread::Monitor which can be used to monitor parameters with particular methods invoked for each changes of the different parameter type. The user must sub-class this to handle parameter types of interest.

• drama::thread::MonitorToParam A concrete sub-class of drama::thread::Monitor which can be used to monitor parameters values copied directly to parameters in the invoking task.

• drama::git::Task Create a DRAMA task which obeys the GIT (AAO Generic Instrumentation Task) specification. Such a task can be easily loaded and run by Standard AAO Control tasks.
  Clients should sub-class this to add their own actions and parameters.

• drama::git::Path A path for communicating with tasks that obey the GIT specification.

• drama::BulkData Defines and optionally creates a shared memory section for sending bulk data messages.

• drama::BulkDataSds Defines and optionally creates a shared memory section containing an SDS item.

• drama::BulkDataArg A class used to manage a bulk data argument to an action.

• drama::BulkDataArgSds A class used to manage a bulk data argument to an action, which contains an SDS item.

• drama::EntryInfo Used to access details about a DRAMA event entry.

• drama::gitarg::Bool A class used to read logical values from SDS argument structures typically used in DRAMA commands (e.g. as send by ditscmd).

• drama::gitarg::Enum A class used to read enumerated values from SDS argument structures typically used in DRAMA commands (e.g. as send by ditscmd).

• drama::gitarg::Int A class used to read integer values from SDS argument structures typically used in DRAMA commands (e.g. as send by ditscmd).

• drama::gitarg::Real A class used to read real number values from SDS argument structures typically used in DRAMA commands (e.g. as send by ditscmd).

• drama::gitarg::String A class used to read string values from SDS argument structures typically used in DRAMA commands (e.g. as send by ditscmd).

• drama::gitarg::Id A class used to read SDS ID values from SDS argument structures typically used in DRAMA commands.
  It can fetch its value from an Sds structure in the command argument or a file.

• drama::logging::Logger A class which implements the DRAMA 2 logging system
• drama::logging::LogStreamBuf A class allows logging using C++ Stream features.

Other classes documented are generally used to support one of the above classes.

The "Hello World" example is included below, but the document and its examples from the Drama2Examples module is probably the best way to learn DRAMA2.

 
/*                      D R A M A H E L L O 
 
 *  Module name:
      dramahello.cpp
 
 *  Function:
      DRAMA 2 Hello World.
 
 *  Description:
      Responds to the following commands
                HELLO   -  Outputs  message.
                EXIT     - Cause this task to exit.
 
 
 *  Language:
      C++
 
 * Copyright (c) Australian Astronomical Observatory, 2014.
   Not to be used for commercial purposes without permission.
   No warranty of any form unless subject to a specific agreement.
 
 
 *  Support: Tony Farrell, AAO
 
 
 *  @(#) $Id$
 
  
 */
 
static const char *rcsId="@(#) $Id$";
static void *use_rcsId = (0 ? (void *)(&use_rcsId) : (void *) &rcsId);
 
#include "drama.hh"
 
#include "drama/sds.hh"
#include "drama2_err.h"
 
class HelloAction : public drama::MessageHandler {
public:
    HelloAction() {}
    ~HelloAction() {}
private:
 
    drama::Request MessageReceived() {
        /*
         * Send a message to the user.  (Method of MessageHandler)
         */
        MessageUser("Hello World - from DRAMA 2, action %", GetActionName());
 
        /*
         * Access any argument to this action.
         *    (GetEntry() is a method of MesageHandler.)
         */
        drama::sds::Id Arg = GetEntry().Argument();
        if (Arg) 
        {
            /*
             * Print the argument.
             */
            Arg.List(SdsListToUser());
            /*
             * If the message is in standard format, the name
             * of the first item will be Argument1.
             */ 
            std::string MyArgument;
            Arg.Get("Argument1", &MyArgument);
            MessageUser(MyArgument);
            
            /*
             * Alternatively, 
             */
            MessageUser(Arg.toString());
 
            /*
             * And another version
             */
            MessageUser("Argument is \"%\"", MyArgument);
        }
        StatusType status = DRAMA2__TEST;
        drama::ErsReport(&status, 
                        "Demonstration of error report with format of value %", 33);
 
        /*
         * Tell DRAMA the action has ended.
         */
        return  drama::RequestCode::End;
    } 
};
 
 
 
class DramaHello : public drama::Task {
 
private:
    HelloAction HelloActionObj;
    
public:
 
    DramaHello() : drama::Task("DRAMAHELLO") {
 
        Add("HELLO", drama::MessageHandlerPtr(&HelloActionObj, drama::nodel()));
        Add("EXIT", drama::SimpleExitAction);
    }
    ~DramaHello() {
 
    }
};
 
int main()
{
    try 
    {
        // Make this program a DRAMA task named ticker
        DramaHello task;
 
    
        // Process DRAMA messages.
        task.RunDrama();
 
 
    } 
    catch (const drama::Exception &e) 
    {
        fprintf(stderr,"DRAMA Exception thrown and caught in main\n");
        fprintf(stderr,"%s\n", e.toString().c_str());
        fprintf(stderr,"DRAMA Status = 0X%lx, %s\n",
                static_cast<long int>(e.dramaStatus()), 
                e.dramaStatusStr().c_str());
 
        exit (e.statusAsSysExitCode());
    }
 
    return 0;
}

Author

Tony Farrell, AAO $Revision$ $Date$