DRAMA - DRAMA Version Release notes

Shared Library Linking

DRAMA has long had a shared library - but other then on VxWorks, it was not used and often broke. Support has now been improved and it is easy to link against the shared library. Just replace you use of DramaProgramTarget() and DramaCPPProgramTaret() in your dmakefile with DramaProgramTargetLS(). This will link your application against $GIT_LIB/libgit.so. This may or may not have to be in your shared library path (LD_LIBRARY_PATH or equivalent) dependent on your OS.

If the machine you are running on does not support shared libraries, then DramaProgramTargetLS() defaults to DramaCPPProgramTaret().

Version 1.6.3

Mac OS X architecture selection at dramastart

If the dramastart command on MacOsX cannot find a build of DRAMA for the default achitecture on a machine, it will search for any build that will work. This means you now only have to define environment variables like DRAMA_MAC_32BIT_ONLY when you are buliding DRAMA, not when you are running dramastart (unless you have multiple builds and need to select between them).

Selecting compilers

By default DRAMA uses the compiler with the cc or gcc command found in its path. If you want to force the use of gcc on a machine which has an ansi-C compatible cc, you must use the -forcegcc option to drama_make.

You can change this if you want using your drama_local.cf file. If it is a version of gcc you still need to apply the -forcegcc option to drama_make, but you can change the actual compiler command if you desire. For example, the following lines can be added to your drama_local.cf file to change both the C compiler and the C++ compiler to be used to ones available in the Mac OS X Snow Leopard developer release, but which are not the standard compilers.
#undef CcCmd
#undef CccCmd
#define CcCmd  /Developer/usr/bin/clang
#define CccCmd /Developer/usr/bin/llvm-g++
Note that DRAMA will still use the standard cc or gcc command to build the imake command, but all of DRAMA itself will be built using the commands you have specified.

DRAMA for MacOsX has now been built using clang and llvm-gcc as C compilers and llvm-g++ as the C++ compiler on the Mac, using this approach.

imake upgrade

The version of the imake command used by dmkmf has been upgraded to version 1.0.2 - the last version to be released with X11. It is now used on Linux and MacOsX rather then the OS version, which disappears if you have a later version of X11 (such as on MacOsX Snow Leopard).

Replacment of "make depend"

The make depend command was using the X11 makedepend program to generate include file dependencies. This was rarely being used in practice as programmers had to make a point of using it, did not work on MacOsX, and had various other issues. From this version of DRAMA, if we are using GCC and Gnu Make (e.g. Linux and MacOsX), then features in those programs are used to do the job, and it is done automatically when make is invoked. Basically a bunch of files are generated and then included into the Makefile describing the include file dependencies for each C and C++ source file. The files are named source.d where source is the name of the source C or C++ file, minus its extension.

This new feature can be disabled using the -nodepend option to the drama_make and dmkmf commands, or by defining the cpp macro UserNoGnuMakeDepends in your dmakefile. You might want to disable it at the drama_make and dmkmf command if you always do make clean before doing your bulid, since you will save time.

The list of files which are checked for depedencies using this feature are those set by the SRC1 .. SRC5 series of macros (as per make depend command). You need to have all your C and C++ source listed in these macros. You can list them explictly, or just set them using
SRC1=$(shell ls *.c *.C *.cpp)
(dropping file types you do not use). You would set them explictly if your set of source files might change (say on different machines).

You can use the make depsrcschk to compare the list of source files with those set in your macros.

AutoTest macro

A new dmakefile macro AutoTest() has been added. This is intended to wrap up targets which run tests when doing default builds. By wrapping them up this way, you can disable the tests using the -noautotest macro to the drama_make and dmkmf commands.


We have removed support for Ultrix, OSF and SunOs (pre solaris) hosts, as there has been no request for these for a very long time and no test facilities are available.

Version 1.6

A collection of bug fixes and relatively updates generated over the past few years.

Of particular note is that addition of the running of a lot more tests during the build process. This will make the build take longer then normal, but helps ensure the software is working correctly. Also, a new sub-system, DramaTest has been added, which uses tcltest package to run various tests. It still have a long way to go and many of the existing tests are in the sub-systems.

Starlink support removed

The SDS library had some support for interfacing with Starlink systems. This has been removed as we beleive nobody is using it.

SDS and ARG libraries

Add new constant SDS_C_MAXARRAYDIMS for the maximumn number of arry dimentions.

Add ArgCheckItem(3) function and Arg::CheckItem method. These check that a specified SDS item has the right format - type code, number of dimenions etc.

sdslist(1) no longer crashes on bad arguments and various errors fixed in SdsRead(3)

Memory fragmentation issues triggered by the Arg series of routines have been fixed.

Expand the SdsSetWatch(3) routine functionality to cover most SDS events.

SDS Leak checking

Additions have been made to help trace SDS leaks in DRAMA code. Please see these notes for more information.

IP Interface selection issues

If the local machine does not have a valid IP address, then is used, allowing DRAMA to be run on the machine. Previously you could have trouble getting DRAMA to run on a machine without an IP address.

On architectures which support the getifaddrs(3) system call (Mac Os X, Linux), then that routine is used to determine the IP interface to use (and which IP address DRAMA will bind to). If there are multiple valid interfaces, the first is chosen and a message is output to stderr indicating this. You can set the IMP_INTERFACE envrionment variable to override this or stop the warning (the message gives the details). The message is only output for the first DRAMA task to be registered in a DRAMA system on a given machine (the task which creates the common global noticeboard used to list the DRAMA tasks).

Registrar tasks

A DRAMA task can now declare itself as being a Registrar task. Such a task will receive a message each time a new task registers. To handle these messages it should use the DitsPutRegistrationHandler(3) routine or the DitsRegistrationHandler(n) Tcl command. To declare itself a registrar task, a task should specify the flag DITS_M_REGISTRAR to DitsAppInit(3). All tasks built using the standard Tcl/Tk interfaces are declared to be registrar tasks. By default, this scheme only works for the local machine, but if you add a line of the form
forward registrations to machine1 machine2 machine3..
to your IMP Startup File you can cause these messages to be sent to other machines. You can specify as many machines as you desire.


DitsKillByName(3) now kills all actions of the specified name when the action is spawnable (previously it failed in these cases).

Added the new flags DITS_ARG_READFREE and DITS_ARG_FREE to DitsPutArgument(3). These make it more flexible in terms of the type of SDS argument it can support.

A new control message, PRINTENV will print the values of environment variables available to the task. If a argument are supplied, they are the names of envrionment variables to print the value of. If no argument is supplied, print all envrionment variables.

The new ditssavearg(1) command provides a simple way to save the value of arguments to DRAMA actions. You can specify the task name and the action name to be implement and the argument to the action will be written to a file. Provides a quick way of capturing the complex SDS arguments created by some tasks.

Documented that you can't use the DITS_M_X_COMPATIBLE nofication method (flag to DitsAppInit(3)) on VxWorks if also using DitsSignal*() from an ISR or another task - as the notification method may in some rare cases block. Warning messages are also output from DitsSignal*() to the VxWorks console if this is triggered.

Action/UFACE waits via transaction ID

Added new versions of the waiting routines which wait on particular transaction ID's - DitsActionTransIdWait(3) and DitsUfaceTransIdWait(3) This resulted in a signficant revamp of the relevant code with many bug fixes and improvements in operation. Additionally, the Dul routines which call these - DulGetPathW(3) and DulMessageW(3) use these versions and are no longer confused if other transactions come in.

ditscmd changes

Added -a [file] argument to ditscmd. This specifies a file containing the SDS argument to be attached to the command.

Added -z [c] argument to ditscmd. This allows the user to change the "equals" flag in the Name=value argument naming convention to using the specified character.

ditscmd now sizes it global buffer appropiately for the reply buffer and the message buffer appropiately for the argument.

Added -z argument to ditscmd. If specified, the program does not return bad status if sub task disconnects.

Added -h argument to ditscmd. Outputs detailed help.

DTCL changes

Added DitsRegistrationHandler(n) Tcl command, allowing the specification of a handler for registration messages.

Added DitsConnectHandler(n) Tcl command, allows the specification of a handler for connection messages.

Added DitsTaskNode(n) Tcl command (determines the node a task is running on).

Added -argreadfree and -argfreeid options to the message sending commands.

Add new READFREE and FREEID argument values to DitsPutArgument(n) command.

Automatically size the global buffer based on the reply buffer size in the dtk and dtcl commands..

DtclTkDialog(n) now supports buttons being in different colors, depending on flags previed to button names. Add the DtclTkDialogButOpts(n) command to set these colors.

Add DtclTkDialogPosition(n) (positions a dialog according to Dtk rules, DtclTkDialogCentre(n) (positions dialog in screen centre) and DtclTkDialogPosUnderMouse(n) (positions dialog under mouse.

Add DtclTkDialogPositionSetUnderMouse and DtclTkDialogPositionSetCenter to change the default behaviour of DtclTkDialogPosition(n) (they still need documentation pages, but take no arguments, you just call them).

Add new Tcl commands to DitsGetTaskType(n) and to DitsGetTaskDescr(n) reflecting the C equivalents.

Added DtclTkScreenInfo DtclTkScreenInfo(n) command to the Tcl/Tk interface. This allows Dtcl to determine information about Multiple display X11 devices. It requires the Xinerama library be supported on the operating system in question. This is used to position Tk windows.

Mac OS X Intel support

Mac OS X intel support added. Version 1.6 supports 32 bit, 64 bit and 32/64 bit fat builds. The rules are a little complicated due to the various options which are possible and varying support across different versions of MacOsX.

The hosttype you build or run for on a 64 bit capable MacOsX host is dependent on the OS version and on environment variables.

If the environment variable DRAMA_MAC_64BIT_ONLY is set, and the OS version is 10.5 or later, build for 64 bit intel.

If the environment variable DRAMA_MAC_32BIT_ONLY is set and the OS version is 10.6 or earlier, build for 32 bit intel.

If the environment variable DRAMA_MAC_INTEL_FAT is set, and the OS version is 10.5 or 10.6, do a FAT build, targeting 32 bit and 64 bit intel.

For MacOsX 10.7 or later, the only option is a 64 bit build as we are presuming that 10.7 will be 64 bit only. If this changes, we will remove this restriction.

For MacOsX 10.6 (Snow Lepoard), the default is a FAT build. 32bit or 64 bit possible. You may want to use the environment variable to change this if you don't have all the libraries you need in your applicatin in FAT format

For MacOsX 10.5, (Lepoard) the default is a 32 bit build, but 64 bit or FAT are possible. You must have FAT or 64 bit versions of all the required libaries.

For MacOsX 10.4 (Tiger) or earlier. only option is 32 bit build. (If you really want 64 bit on Tiger, this may be possible - please contact me).

On a 32 bit MacOsX machine, you can also generate a FAT build by setting DRAMA_MAC_INTEL_FAT to be true. You can't generate a 64 bit build, since some DRAMA tools are needed by the build. (It might be possible to generate a 64 bit build on a 32 bit Mac, using DRAMA cross compiler support, but I haven't tried it and there are so few machines that this applies to that I haven't bothered trying)

It is probably not hard to add power pc builds into a FAT build as well, but I haven't bothered as I think they will largely be gone soon and they do compilcate some of the linking.

General changes

Many improvements in 64 bit architeture support.

Add JavaErrorFile macro for us in dmakefile's.

Add -x option to the messgen command, allow the output file name to be specified explictly, rather then manufactured from the input name. Makes it easier to write high quality make rules involving the messgen(1) command.

Java and Tcl versions of all DRAMA error include files are now released during the DRAMA build. The Fortran version of the Arg error include is released.

The cleanup(1) command no longer cleans up tasks which were known to the IMP system in which cleanup is running (same value of IMP_SCRATCH). The new -k reverts to the old behavious of killing anything that looks like a DRAMA task. This change allows you to run multiple IMP/DRAMA systems on the one machine and under the one user account, as long as the value of IMP_SCRATCH is different. You will need to set up the IMP ports correctly if using networking.

The dramastart(1) command now passes arguments to programs to be run.

Various shared library build problems fixed. We beleive these now work correctly for Linux and MacOsX, possibly Solaris.

Add GitLoggerTune function to allow tuning of GitLogger.

GitLogger now implements a file size limit of 1/2Gb - with the file re-opened with a different name under these conditions. We never open an old log file anymore

Changed the GitLogger logfile name format from {taskname}-DDMMYYYY.log to {taskname}-YYYY-MM-DD.<nn>.log. <nn> is the number of the log file on that date (we never reopen an old log file anymore).

GitLogger log files may be compressed automatically if specified by the caller.

Version 1.5.2

Incorporates a number of fixes and minor new features.

I'm afraid I had to make Incompatable changes in the Arg and Sdp C++ interfaces to ensure portability of applications to 64 bit macines.

Support 64 Bit Intel machines running linux (type linux_x86_64).

The standard user interfaces now handle getting of the special parmeters _ALL_ and _NAMES in a more intelligent fashion.

New functions DitsPathToName() (returns of task name from of a path), DitsGetActNameFromIndex() (given an action index, return the action name), DulFitsRead() (implements a Tcl command to read a Fits file into an SDS structure), DulFitsWrite() (implements a Tcl command to write a SDS structure into a FITS file),

There is a new set of C++ interfaces to the GitArg() set of functions. There are in the GitTpl namespace. See C++ Interfaces or $GIT_DIR/gittpl.h for details.

There is a new set of array access methids with the SDS C++ classes.

DJAVA has new RCSID constants in call classes. The Arg Class has a greater range of constructors. DJAVA has been ported to JAVA 1.5, through we don't yet use any of the new features.

DtclTkDialog now trys to be sensible about where it places the dialog when on a dual screen monitor - through it just guesses it is on a dual-screen monitor by looking at the screen size.

You can now override IMP_MAX_TASKS in your local configuration files by defining ImpMaxTasks in your drama_local.cf file. For example

#define ImpMaxTasks 64 This must be in place when building IMP.

Many of the sub-systems now run test programs during the build - to check that things have been built correctly.

Arg/Sdp C++ Interface changes

I have made some changes to the DRAMA Arg/Sdp C++ interfaces which will likely cause compilation failures in existing code. This is a pain but I believe this is necessary, as I explain below.

The problem will occur if you compile with SDS version r1_4_3_26 or later (Arg is within the SDS library) and DITS version r3_36 or later (Sdp is within the DITS library).

GNU C++ will report a problem of this form:

SequencerIris2Task::CreateTclArgStructure(int, char**, bool*, std::string*, Arg*, StatusType*)': seq_iris2_task.C:629: call of overloaded `Put(const char[10], long int&, StatusType*&)' is ambiguous /instsoft/drama/release/sds/r1_4_3_26/arg.h:311: candidates are: void Arg::Put(const char*, bool, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:330: void Arg::Put(const char*, char, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:347: void Arg::Put(const char*, short int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:366: void Arg::Put(const char*, short unsigned int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:385: void Arg::Put(const char*, int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:404: void Arg::Put(const char*, unsigned int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:422: void Arg::Put(const char*, long long int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:440: void Arg::Put(const char*, long long unsigned int, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:458: void Arg::Put(const char*, float, StatusType*) /instsoft/drama/release/sds/r1_4_3_26/arg.h:476: void Arg::Put(const char*, double, StatusType*) The relevant bit of code is if (argc >= 3) { string numSteps = string(argv[2]); long int numStepsInt = atoi(numSteps.c_str()); arg->Put("Argument1", numStepsInt, status); /* LINE 629 */ commandOK = true; } The problem is that my change to Arg C++ interface makes this call ambiguous - the compiler cannot work out what to do with a "long int" argument to Arg::Put(). It is trying to chose from the following implementations: void Put (const char *name, bool value, StatusType * const status); /* arg.h:311 */ void Put (const char *name, char value, StatusType * const status); /* arg.h:330 */ void Put (const char *name, short value, StatusType * const status); /* arg.h:347 */ void Put (const char *name, unsigned short value, StatusType * const status); /* arg.h:366 */ void Put (const char *name, INT32 value, StatusType * const status); /* arg.h:385 */ void Put (const char *name, UINT32 value, StatusType * const status); /* arg.h:404 */ void Put (const char *name, INT64 value, StatusType * const status); /* arg.h:424 */ void Put (const char *name, UINT64 value, StatusType * const status); /* arg.h:440 */ void Put (const char *name, float value, StatusType * const status); /* arg.h:458 */ void Put (const char *name, double value, StatusType * const status); /* arg.h:476 */ but can't work out what to do. Why has this changed - because there is no longer a version that looks like this void Put (const char *name, long int value, StatusType * const status); The problem is the the implementation of this function was itself ambiguous - on most of the machines we have used so far "long int" is 32 bits. But on machines which are naturally 64 bit, this "long int" would be 64 bits (Alpha and Intel/AMD 64 bit machines, for example). The old approach would bite in strange ways and it was a real fudge to implement, I had to drop either the INT32 or the INT64 version depending on the machine it was being compiled for, with the result that something like arg->Put("Argument1", 10, status); Would not always compile (argument is a plain "int") - you always had to cast the argument to a different type, with "long int" often used. Also, the underlying SDS type could end up different (SDS_INT64 rather then SDS_INT) depending on the architecture of the machine on which the code is running - which would be a real problem if a SDS_INT64 item ended up on a machine without a 64 bit integer implementation.

Equivalent problems occur with the "Get" functions and the Sdp class equivalents.

As far as I have been able to determine (looking at some best-practice examples), the best approach was simply to have the INT32/INT64 versions - forcing the user to select the version they want (normally INT32). Similarly for the unsigned versions (UINT32/UINT64). As a plus, it will now work with plain "int" arguments.

The reason I got into this mess is probably partly due to the different ways C++ resolved this type of thing as the Standard developed, plus not having 64 bit machines around enough.

The solution in the above example is to change the declaration of "numStepsInt" to be of type INT32. E.g. if (argc >= 3) { string numSteps = string(argv[2]); INT32 numStepsInt = atoi(numSteps.c_str()); /* Declaration changed here */ arg->Put("Argument1", numStepsInt, status); /* LINE 629 */ commandOK = true; } This will now produce the same result regardless of the machine architecture. You could also cast as required, e.g. arg->Put("Argument1",(INT32) numStepsInt, status); Or more correctly but verbosely: arg->Put("Argument1", static_cast<INT32>(numStepsInt), status);

Version 1.5.1

Incorporates a number of fixes and minor new features.

Many documentation improvements. Links from C++ html pages to C pages now work. Callback routines are now documented throughout.

IMP now supports recording the IMP event log in shared memory, using tasklog on shared. The new taskmon utility can then display the event log from another task while it is running, even if it has hung or (if the shared file hasn't been deleted) crashed.

Added the following new control messages

Flush the log file to disk
Write the argument as a string to the log file
Send this control message to a task to help debug SDS id leaks

Add a new command under VxWorks - reset. This will neatly shutdown DRAMA under VxWorks and then reboot the machine.

Added the new function SdsSetWatch() which allows you to watch events on an SDS Id.

Added the new function DitsGetSelfPath() which allows you easily fetch the path used for a task to send messages to itself.

Added the new function DitsGetDebug() which allows you get the current internal debugging levels as set by DitsSetDebug()

Added the the new function DitsPutForwardMonSetupHandler() which allows you to adjust the path buffer sizes used in a forward monitor connection.

Added the new Wait() and WaitAll methods to DcppHandler. Allows you to wait for events to occur. Also a new DcppHandler constructor was added, taking an argument of type DcppCallbackBase instead of function pointers.

Now supports the use of long long and unsigned long long in GNU compilers to implement the SDS types INT64 and UINT64. Previously this was done using structures containing 2 32bit items. Note that for VxWorks version 5.5 onwards, you should add the following line to you drama_local.cf file.

#define VxWorksDefinesINT64

Add DJAVA DramaTask.CloseTask() (three versions) method - which replaces DramaTask.Close() and allows better handling of exceptions during task shutdown.

Add DJAVA DramaError class which allows a DramaException to be converted to a non-checked exception.

Add new DJAVA SdsID class methods SetDebugging(), EnableFreeIDWatch() and ClearFreeIDWatch() which are usefull when you need to debug SDS ID leaks.

The JAVABASE Make macro is now used to set the location of JAVA. Local configuration files can set "JavaBase" to set this value. Default values are set up for MacOsX and Solaris. E.g. to specify JAVA in a different location from the default, edit your drama_local.cf file to add the following lines

#ifdef JavaBase
#undef JavaBase
#define JavaBase 

The cfitsio library is supported by the configuration file. If you have a copy of this library, you can enable its use by DRAMA by adding the following lines to your drama_local.cf file.

#define HasCFITSIO
CFITSIO_LIB=-L/usr/local/lib -lcfitsio
You then use the CFITSIO(x) macro in your dmakefile to do x only if cfitsio is enabled. Specify $(CFITSIO_INCL) for the include search path and $(CFITSIO_LIB) to link the library. DRAMA uses cfitsio to implement the fucntion DulFitsRead() and a FITS file image type in dtk. These functions are not new, but previously they required Starlink and Fortran libraries, rather then CFITSIO.

The new command drama_gen_defaultver generates a version file specifying the current defaults versions. The new command drama_rel_cleanup prompts you to delete all releases of sub-systems which are not either the default or in a version file.

Version 1.5.0

I'm afraid some of these notes were reconstructed well after the release.

Version 1.5.0 represents the version of DRAMA being used on the AAO's new CCD controller software as deployed in March 2004. Additionaly, some bug fixes and improvements and a WIN32 support update have been added (all supplied by Nick Rees at JACH).

The web documentation has, (at long last) been updated, with details for some previously undocumented versions added as well as the 1.5.0 changes. (I'm afraid the latex documentation has not been updated).

This version is expected to be quickly replaced by 1.5.1, but that will only be minor fixes.

Of particular note is that the IMP maximum number of task has been increased from 32 to 48. This means that tasks built with this version are incompatible with older tasks (to a minor extent) and as a result the IMP version number has been increased. You will get warning messages if you try to run tasks with different IMP versions. Note that it is possible to reverse this change before you build DRAMA, if you desire.

Added the following new functions.

A function which allows the details of current monitoring operations to be output.
Allows the redirection of ImpConnect and ImpNetLocate calls to, for example, force system-widw path handling which can set task locations and path sizes.
This function allows you to specify a function to be invoked when an action ends - regardless of why it ends.
Format a reason code and status into a string
Iterate through the transactions assoicated with an action.
Send a message and wait for completion. Return the argument associated with the completion message (which is not avaiable from DulMessageW()).
Indicate if the task on the path has died.
Indicate that we have not yet tried to get a path to the task.
Indicate if we are currently getting a path to the task or waiting for a notify operation to complete.
Delete the task on the path.
Install a disconnect handler object for a path.
Returns the underlying DitsPathType object assoicated with the DcppTask object.
Set the stack size to be used when the task is loaded (VxWorks only).
Forget all transactions associated with the current action.
Accesses a descendent of a structured Sds item using the descendent's name only.
Determine if a SDS item is defined.

Added DUMPMON (dump parameter monitor details) and LOGNOTE (write a message to the log file) control messages. It should be noted that if you send a invalid control message to a task, the list of supported control messages it output.

Added support for named arguments to ditscmd and make the -g do a multiple parameter get rather then a signal parameter get (it becomes an alias for -l. Add the -v option which causes any reply values to be output using SdsList().

Add SdpUpdate, DitsLogMsg and DitsLogSysEnabled DTCL commands.

Replace DITS_REA_SIGNAL by DITS_REA_ASTINT through the later remains for compatibility.

The DITS_M_SET_BYTES load flag is now supported throughout - allowing you to set the stack size of a VxWorks tasks.

The Sdp and Arg C++ classes now support std::string in places where char * were used previously. You must define the macro DRAMA_ALLOW_CPP_STDLIB before including Sdp.h for these functions to be defined.

The Sdp C++ class now supports bool types values (Sdp::Get() and Sdp::Put().

The DcppBuffers class now specifies appropiate default values.

The DcppHandler class has been revamped to change the public interface to virtual functions. DcppHandler now catches the object being deleted in the middle of being used an prints a warning.

Added the GitTask class - which wraps up various typical operations used with AAO GIT tasks.

The dramastart command target argument now accepts the special value host - indicating the current host.

The new dnet command will start up the DRAMA networking only if it is not currently running. (Avoiding the error messages that dits_netstart outputs in this case.

SdsList() and sdslist etc. will now list extra data on next line within [].

DJAVA now supports sending messages with a wait, e.g. DramaPath.ControlW(), DramaPath.GetPathW(), DramaPath.GetW(), DramaPath.KickW(), DramaPath.ObeyW(), DramaPath.SetW(). You can now specify a timeout on a DramaSem operation - see DramaSem.SetTimeout(). The default timeout is 30 seconds. Added DramaSem.CheckWeHaveIt() and DramaSem.WeHaveIt() methods.

You can enable the GitLogger in a DJAVA application using DramaTask.GitLogger() and log messages using DramaTask.DramaTask.Log(). The DJAVA documentation has been significantly improved throughout, but please take particular note of the Swing issues on the DJAVA package page. DJAVA is expected to work with JAVA versions 1.2 through to 1.4.

The DRAMA C++ interfaces are now documented on the web pages (thanks to doxygen).

DRAMA Logging Facilities have been dramatically improved. Please see DRAMA logging for details.

Version 1.4.2

I'm afraid these notes were reconstructed well after the release.

Added dprintenv command to VxWorks commands (those that come with dramastart under VxWorks. The argument is the name of an environment variable to be translated.

Considerable work on DJAVA. In particular, note that it now complains if you do not have the DramaSem semaphore taken when sending a message from UFACE context.

Version 1.4.1

I'm afraid these notes were reconstructed well after the release.

The DRAMA Java Interface - DJAVA is now part of the release. Many changes over the initial release of this sub-system. DJAVA can be used for building GUI's or normal tasks.

Version 1.4

I'm afraid these notes were reconstructed well after the release.

Added DitsPutActStatus and DitsPutArgument commands to DTCL. They are only available when handling an action.

Dropped function DitsArgNoDel as it turned out to be dangerous

Added the following new functions.

DitsSignalByIndexPtr(), DitsSignalByNamePtr() and DitsGetSigArg
These replace the use DitsArgNoDel to pass non-SDS information from interrupt handlers to main-line code.
Used to specify functions to be invoked to log the DRAMA internals.
A general logging function - making use of whatever logging system is available, if any.
Allows the code (as returned by DitsGetCode() associated with an action to be changed.
Allows the ERS Task ID to be retrived.
Used to support a change of the logging system for Ers messages.
Initialise the GitLogger. See the GitLogger class for more details.

Introduced the GitLogger class - a general logging system.

The IMP layer now supports VME backplane shared memory

Added the raw2sds program- for converting simple raw images into SDS image structures

Added the VERSIONS DUMPACTACTIVE and DUMPACTALL control messages.

Version 1.3

I'm afraid these notes were reconstructed well after the release.

The DRAMA start up scripts ($DRAMA/drama.sh and $DRAMA/drama.csh) now automatically source equivalent hidden files in the user's home directories ($HOME/.drama.sh or $HOME/drama.csh).

The DRAMA_VERFILE environment variable is now defined by the dramastart command (Unix version) to the name of the DRAMA version file, if any.

Support for VxWorks on Power PC (targets vwppc and mv2700).

New routines

Fetch the action index of any action given't its name.
Check if an action is active.
Indicates if a subsidary transaction is complete.
Wait for, but don't read, the next DRAMA messages.
DulInt series of routines
These functions ( DulIntInit(), DulIntSignal(), DulIntTidy(), DulIntISR()) make is significantly easier to write interrupt service routines and other functions which have traditionally used DitsSignal(), particularly under Vxworks.
This function replaces the increment operators on a DcppHandler object.
Add versions of this method which return the transaction id already wrapped up in an SDS class.
Add versions of this method which provides a StartedHandler argument.
Allows specifiction of a timeout handler routines.
DcppSpawnKickArg() and DcppSpawnKickArgUpdate()
C++ interfaces to the Dits routines with similar names.
SdsExportDefined(), SdsIsExternal, SdsExternInfo, SdsSizeDefined()
New SDS functions to help work when workign with external SDS structures, particularly when used with Bulk data.

Add new DcppShared class supporting bulk data from the C++ interface.

The DcppMonitor class Monitor() and Forward() methods which accept variable format argument lists now provide a mode which has accepts a list of parameters in a string.

Added the dversion command (Under Unix only). This allows you to select a new DRAMA version without having to restart DRAMA. The argument is a version specification as would normally be accepted by the -v argument to dramastart.

Version 1.2

This version brings a major revamp to some areas of IMP in order to improve reliability. Various minor changes, improvements and bug fixes are also provided. In addition, DRAMA has been ported to Linux and a port to WIN 32 (Windows NT/Windows 95) is well under way.

Please note that under Solaris 2.6, if you are using the GCC compiler, you will need to have rebuilt GCC under Solaris 2.6. You can't use a version of GCC built under an earilier version of Solaris. This is due to significant changes in the Solaris 2.6 system headers which must be incorporated by GCC. (I think all you really need to do is run fix_includes again, but it is probably easier to rebuild the entire compiler). This is a Solaris 2.6/GCC problem, not a DRAMA problem. The problem causes a failure of compilation at the IMP layer, due to missing type definitions within a structure. Note that the rebuilt compiler will probably not work with older versions of Solaris.

To build DRAMA under RedHat linux 4.x versions, you will probably have to edit the file drama_source/imp/impz_linux.h. Add the line #define IMPZ_REDHAT_4_2 at the begining of the file.

The WIN32 release basically works. There are just some installation problems to sort out.

The following changes which may cause incompatibilities existing code. For recompiled code, I believe the chance of this happening are remote. Other significant changes, mainly new features.

Version 1.1.1

A patch to Version 1.0 which provides some more bug fixes required by RGO.

Version 1.1

A patch to Version 1.0 which provides some bug fixes required by RGO.

Version 1.0

This is basically the Beta 1.0 version with the bugs sorted. Considerable work has gone into resouce leaks and reconnections after failures with most problems in these areas now elimated.

The documentation is now available in HTML format. A full release of DRAMA will include this in ~drama/html. The entry point it ~drama/html/DramaIntro.frames.html. Alternatively, the documentation is available on lone at the AAO

The following are the possible compatibilty problems you may strike with this version

Note that if you wish to move your source between this version and a previous versions, consider using the DRAMA_MAJOR_VERSION macro. E.g.

    DitsPutDisConnectHandler(disconHandler,0, &oldDiscon,&oldDisconData,status); 
# else 
    oldDiscon = 0; 
# endif 

Other Changes.

Beta Verson 1.0

This version was to test the new CD ROM release system and allow the testing of the 1.0 release.

In bug reports about this version, please quote the contents of the file drama_source/checkpoint.

WARNING! Calling sequence changes - In order to improve general structure, calling sequences of some little used routines have change.

Inaddition, the defintion of the routine type DitsDitsconnectRoutineType has changed.

These changes should be picked up as compilation warnings when running an ANSI compiler with prototype checking enabled.

Calls to the routine DitsPutParSys can probably be removed as its function is now preformed by SdpInit.

Configuration System.
DramaProgramTarget() macro now includes DUL and GIT libraries, as does The DramaIncl macro. Major update to configuration software now supports local configuration files. See the file local_configs.note.
A complete DRAMA system, libdrama.o, is now available to replace libdits.o. The later did not include Git and Dul where as the former does. libdrama.o is currently found in GIT_LIB but will be moved to a better location in the next release.
A new routine Dtcl_Init is provides for Tcl version 7.6 and later. This allows you to build DTCL into Tcl applications in the normal Tcl way. A sharable library is provided which can be loaded into any Tcl application (Tcl 7.6 and later). Add the following lines to your Tcl pkgIndex.tcl file.
package ifneeded Dtcl 1.0 { 
    global env
    if {[lsearch -exact [array names env] DTCL_DEV] != -1} {
        load $env(DTCL_DEV)/libdtcl.so
    } else {
        error "DTCL_DEV environment varaibler not defined, have you started up drama"

This will enable the Tcl command

package require Dtcl

The VMS versions of Dtcl/Dtk will now output message responses correctly instead of waiting until standard input is processed.

dtcl now supports the -nostdin option, which says that is should not prompt stdin for commands. Likewise, dtk now supports -stdin which indicates is should prompt, event when it had an initailisaction script.

If DRAMA gets corrupted messages, it will retry a number of times before the task exits (currently fixed at 10 times). Added DitsPutPathData and DitsGetPathData, which allow user data to be assocaited with a path. Integrate new imp and support SYNC messages. Dits will now ensure action completion and error messages are returned to the parent event when its buffer is full by using RequestNotify techniques. We now support a new message type, MGET. This can be used to get the values of multiple parameters. These are handled transparently by the user interfaces (dtcl/xditscmd/ditscmd). Add DitsArgNoDel function which allows Sds structures supplied by DitsSignal calls to be left alone by DRAMA Major revamp of parameter system initialisation. You now don't need to invoke DitsPutParSys. A new routine, DitsAppParamSys (normally invoked by SdpInit()) can be used to get and change parameter system hook routines.
IMP V1.2 released and integrated.
New programs. sdsdump allows you to dump parts of an Sds file. sdspoke allows you to change parts of an Sds structure in a file.

Beta Version 0.6

An earily release of what was to become V1.0. It got out due to demand before I realized the changes were significant enough to justify V1.0

SDSC (the Sds compiler) now supports structured arrays, and the types INT32, UINT32 INT64 and UINT64. New Sds routine - SdsInsertCell, inserts a cell into a structured array. SdsInsertCell and SdsCell now allow you to treat multidimensional arrays as one dimensional. Sds memory leaks fixed.
dits_netclose now works quickly. cleanup command now only clean's up scratch files for the current host.
Dits changes
Many of the DitsPut??Handler routines now return the original values. Where there was no client_data item, they simply return the value and no application change is required. Where there was a client_data item, there are now extra arguments to return both the old routine and client_data items. DitsAppInit calling sequence has changed and some new flags have been added. DitsAppInit should now replace DitsInit, which is retained for compatibility reasons. DitsDisconnectRoutineType now has a flags argument. New DitsPathGet routine replaces DitsGetPath, adding new arguments and putting the buffer sizes in a structure. DitsGetPath remains but is implemented in terms of DitsPathGet. DitsPutActions argument structure has changed to provide an action cleanup routine. This is invoked when the task is shutdown or in the case of spawnable actions, when spawned actions complete. Improved error reporting when buffer allocation problem occur but only when local tasks are involved. Currently, buffer allocation problems involving remote tasks cause system errors due to bugs in Imp. Hopefully, this will be fixed in the DitsGetEntInfo/DitsGetEntName now returns the name of the subsidary action when the reschedule reason involves such a transaction. A new DITS_M_REP_MON_LOSS flag to DitsInitiateMessage which tells the monitor system to report monitors lost due to waiting for buffer empty notifications. Action completion messages now try much harder to get though, using the Imp RequestNotify mechanisum. You now cannot set a structured Sdp parameter from outside a task.. A new routine SdpSetReadonly now allows you to make a parameter system readonly. There are now SDP_type codes to replace the use of SDS_type and ARG_type codes. DitsPutParSys is now done as part of SdpInit. This won't cause problems if done as part of the user code, but it is now unnecessary in the use code. Added DitsTaskIsLocal routine
DitsActionWait etc.
Fixed a number of problems in the DitsActionWait/DulGetPathW/DulLoadW stuff. Interfaces to DulLoadW and DulGetPathW changed to incorporate use of DitsPathGet instead of DitsGetPath.
This now uses ADAM net 4, instead of ADAM net 3. Use the form

instead of


when comunincating with DRAMA tasks from ADAM tasks.

In addition, a Drama task name of form task@LOCAL or task@LOCALHOST can be used to refer to a DRAMA task on the local machine, instead of having to know the local machine name.

VMS DRAMA handles lack of ADITS sliently when starting up network.

Dtcl changes.
A host of new commands added to Dtcl. For general operations, the relevent new ones are DitsScanTask/ DitsTaskIsLocal/DitsSetDetails The other additions support adding to actions to the task using Tcl and implemented in Tcl. (DitsPutAction, DitsGetSeq, DitsPutRequest,DitsMsgOut,DitsPutAction, DitsPutObeyHandler, DitsPutKickHandler, DitsGetActIndex, DitsGetEntTransId, DitsGetEntName, DitsMessage, DitsGetPath, DitsLoad,DitsRequestNotify,DitsActionWait) Some new C level functions were also added to support adding Tcl actions from the C level. (DtclPutAction, DtclPutTclObeyHandler, DtclPutTclKickHandler)
C++ interface.
DcppHandler Dcppobject now allows you to wait for multiple threads to complete.
General changes.
We now provide dul_cc/dul_link/dtcl_cc/dtcl_link to help in the building of programs. (dtcl stuff does not actually include Tcl since these routines don't know where it is) Solaris link lines now specify -R to enable finding of sharables at runtime

Version 0.5

The following changes have been made-

  1. The C++ interface, Dcpp has been revamped (as per the document I passed around a bit back. SdsId class created and Arg is now derived from it. SdsId is used in all cases where Sds Id's are required, replacing some usage of Arg (This should have no effect on code).
  2. An optional OFFSETS item is added to the ImageStructure definition, allowing IMG to find out the offset of an image within a detector.
  3. Added DitsScanTasks. This allows you to scan known tasks.
  4. Added DitsActionWait, DitsUfaceWait and DitsPutEventWaitRoutine. These are used to allow Obey with wait style programing. Of more interest are the Dul routines based on these - DulMessageW/DulGetPathW and DulLoadW. (DulLoadW does a load and Get Path operation). A basic demonstration of there use is given in the attached "waittest" program.
  5. DitsAltInType changed in order to simplify include files, but this should not effect user programs unless the assumed the inclusion of the system include file "sys/types.h" (unix) or "selectLib.h" (VxWorks).

Version 0.4.2

Added SdsReadFree() which should be used with id returned by SdsRead, instead of using SdsDelete.
ArgCvt now handles 64bit integers correctly. (Note - side-effect, when calling SdpCreate, items of type SDS_INT/SDS_UINT must use type INT32/UINT32 while SDS_I65/SDS_UI64 must use types INT64/UINT64) New routines ArgGeti64/ArgGetu64/ArgPuti64/ArgPutu64 SdpGeti64/SdpGetu64/SdpPuti64/SdpPutu64
now supports Tk 4.0. A new Tk photo image type supports Sds images. Dul library provides an addition photo image type which supports Fits images. Added new routine DtclErsRep. Fixed reporting of errors when Tcl scripts are read such that we get full stack dump of error. In addition, DTCL_COMMAND will also return the stack dump of any error.
Fixed bug where arguments passed using DitsSignal are not deleted. DitsMonitorMsg rejects messages where parameters are not found. Fix bug in Dui stuff where success handler would be called if error handler not supplied, regardless of the status code.
Ensure Imp fixes reflected in DRAMA copy of Imp code.

Version 0.4

Support for Alpha/OSF1 and Solaris 2.0.x
The documentation in ~drama/doc has been updated as have the man pages in ~drama/man. Note the man pages are now arranged correctly, with programs in section 1, routines in section 3 and tcl commands in section n. For example, to find each version of SdsList
man 1 sdslist
to get the page on the program sdslist.
man 3 SdsList
to get the page on the routine SdsList.
man n SdsList
to get the page on the Dtcl command SdsList.
New document. New routines DulFindFile and DulParseFile. These routines implement logical name search paths in a portable maner. These also support wildcarding and defaults. An interesting example is

which I use in a Dtk based application to find the initial script. tclScript is the user supplied script name. The search path is "." followed by the translaction of the environment variable "FGT_DIR". The default name is "agcalib" and the default filetype "tcl".

The programs "dfindfile" and "dparsefile" can be used in scripts.

New routines which did not make the documentation update support reading a Fits file into an Sds structure (DulFitsRead) and reading a Fits file into a Tk 4.0 photo image widget (DulFitsImageCreate).

The new routine "DitsRequestNotify" can be used to request notification when the buffers in a target task empty. When doing Forward monitoring, the size of the buffers to the task to which forwarding is being done is now determined from the size of the largest parameter in the initial parameter list. In additon, the last parameter value is always sent (ensuring that user interfaces are up to date)
Commands now set the tcl variable "errorCode" to a list which contains details of the DRAMA status which caused the error. Dtk and Dtcl now accept the flag "-mayload" to allow it to load programs directly. New commands
interface to DulFindFile
interface to DulParseFile
interface to DitsRequestNotify

In Dtk, "exit" now invokes the original Tk exit procedures after shutting down Dits. They ensures windows are cleaned up correctly.

Ported to Tk 4.0, Under Tk 4.0, will support putting Sds images using Tk 4.0 photo widget. This will be automatically enabled if compiled with Tk 4.0 include files.

Version 0.3

In additon of a large number of reliability related changes, it contains the following changes. Note, there are quite a number of changes here. AAO specific notes can be found at the bottom.

  1. There is a new utility program - messana. This program will display the facility number, message number and severity for message status codes. For example,
  2. messana 0xF3F8012

    will return

    Message f3f8012 - Facility:1855, Number:2, Severity:2

    Likewise for the integer equivalent of 0xF3F8012.

    messana 255819794

    The intention is to make it easier to lookup message codes. Use the facility number (1855 above) to look up the facility in the PROG bulletin folder.

    A new sub-system has been added to DRAMA. The DUL library is intented to contain items which are not part of the core of DRAMA but which should probably be kept with DRAMA. I will probably move some items from DITS and GIT into DUL at some point. At the moment, DUL contains

    The X windows DRAMA command interface, moved from DITS.
    The experimental DRAMA C++ interface. I have a document for this.

    And the following utility routines

    DulReadFacility(char * filename, StatusType * status) 

    Reads a message facility table (_msgt.h) file and dynamically adds the facility to the current program.

    DulTranslate(char *instring, int outlen, char * outstring,
                                StatusType * status)

    Translate environment variables and logical names in strings using the unix shell style.

    Documentation is not yet available for these routines, but feel free to look at the source if you want to use these routines.

  3. The XDITSCMD program can now automatically load message facility definition tables (_msgt.h files) on startup. You specify these files using X resources. There a various ways of doing this, but an example is to create a file Xditscmd in your home directory. To automatically log the message tables for DUL and GIT, put a line containing the following in this file.
  4. *facilities: GIT_DIR:Git_Err_msgt.h DUL_DIR:dul_err_msgt.h

    In this caes, GIT_DIR and DUL_DIR are environment variables specifing the directories to find the files Git_Err_msgt.h and dul_err_msgt.h in.

  5. Dtcl/Dtk supports a new command - "PutFacility". This command allows message facility definition tables to be loaded. PutFacility takes one argument, the name of the definition table file to be loaded. For example
  6.         PutFacility [TranslateName DUL_DIR -file dul_err_msgt.h]
            PutFacility [TranslateName GIT_DIR -file Git_Err_msgt.h]
  7. Programs which link against the Dtcl/Dtk libraries must now also link agains DUL, in the same way that you would link against GIT.
  8. DtclMainLoop has been replaced by DtclAppMainLoop, and DtclTkMainLoop by DtclAppMainLoop. The old interfaces still exist, but you should modify any code to remove them. The new interfaces support the passing through to Dtcl of the program arguments (argc, argv). This allows these arguments to be passed to the Tcl scripts (in the argc, argv0 and argv variables) and allows Dtcl/Dtk to interpt some arguments (such as -display in the Dtk case) itself.
  9. Programs using Dtk will now automatically load the tcl script DTCL_DIR/dtcltk.tcl. This file contains default definitions of two procedures. The first is DtclError, which is invoked automatically by Dtcl to handle background errors (it is the thing which provides stack dumps for Drama errors). The second procedure is DtclTkDialog. This procedure will setup a prompt dialog in in the form of the tk_dialog procedure, but which does not conflict with incomming DRAMA messages. You should change all invocations of tk_dialog to DtclTkDialog to avoid problems. Note that a change in style is required - for the moment, see the source of DTCL_DIR/dtcltk.tcl for details. I will update the Dtcl document soon.
  10. Solaris 2 is supported. Alpha/osf1 support comming soon.
  11. As part for of the move to support the Alpha, any Sdp routines which used "long int" or "unsigned long int" arguments, not use "INT32" and "UINT32". For example SdpGeti(). The same applies to GitArg routines.
  12. You can now add a target to you dmakefile which will help ensure you don't get caught by a mismatch between the current DRAMA target and the target your Makefile was built for. This problem occurs, for example, if you ran dmkmf after doing "dramastart -t vw68k", but then tried to run make after doing a plain "dramastart" command. You generally get heaps of errors.
  13. Add the following line to you dmakefile file


    I also suggest, that if you have a target "All", you add checktarget as its first target. I.e.

    DummyTarget(All, tdfct_err.h tdfct)


    DummyTarget(All, checktarget tdfct_err.h tdfct)

    Now if the mismatch occurs, you get a message telling you to rerun dmkmf.

  14. Two new utility programs
  15. ditsloadcmd
    Loaded programs using DRAMA task loading facilities. The major benifit of this program is the ability to wait until the task is loaded before preceeding.
    Return infomation about a task

Click here for the DRAMA home page and here for the AAO home page.

 For more information, contact tjf@aao.gov.au