DJAVA

au.gov.aao.drama
Class DramaTask

java.lang.Object
  extended by au.gov.aao.drama.DramaTask

public class DramaTask
extends Object

This class implements an AAO DRAMA task in Java. Typically, you create an object of this class, optionally use the Add methods to add Action definitions and then run the task using the RunDrama() method. If you want to create a DRAMA user interface, run the DRAMA task in a different thread.

The following example shows the creation of a DRAMA task supporting the kickable action "TICKER". Both the Obey and Kick routines use MsgOut to output messages to the user.
 import au.gov.aao.drama.DramaException;
 import au.gov.aao.drama.DramaTask;

 class main {

 public static void main(String[] args) throws DramaException {

      DramaTask task = new DramaTask("TICKER");
      task.Add("TICK",new MyAction());
      task.Add("EXIT",new ExitAction());
      task.RunDrama();
      task.Close();

   }
}

 class MyAction implements DramaTask.KickableAction {
    public void Obey(DramaTask t) throws DramaException  {
        t.MsgOut("Obey routine hit");
        t.PutRequestWait(10);
    }
    public void Kick(DramaTask t) throws DramaException {
        t.MsgOut("Kick routine hit");
        t.PutRequestEnd();
    }
 }

 class ExitAction implements DramaTask.Action {
    public void Obey(DramaTask t) throws DramaException  {
        System.out.println("EXIT action invoked");
        t.PutRequestExit();
    }
 }

Use the DramaErs to report error messages as per the DRAMA ERS library. The DramaException class is used to convert DRAMA status codes to JAVA exceptions and may be signalled by most DRAMA functions. Use the Arg and SdsId class to manage SDS structures. To send messages to other DRAMA tasks, use the DramaPath class.

Version:
@(#) $Id: ACMM:DramaJava/DramaTask.java,v 3.52 17-Sep-2009 14:08:18+10 tjf $
Author:
Tony Farrell
See Also:
DramaPath, DramaStatus, DramaException, DramaErs, SdsID, Arg

Nested Class Summary
static interface DramaTask.Action
          This interface is be used by objects which implement DRAMA Obey message handlers.
static interface DramaTask.ErsHandler
          An inteface to be implemented by objects which output ERS messages.
static class DramaTask.ErsMessage
          A Class used to represent a DRAMA ERS message report.
static interface DramaTask.KickableAction
          This interface is be used by objects which implement DRAMA Obey message handlers.
static interface DramaTask.KickHandler
          This interface is be used by objects which implement DRAMA Kick message handlers.
static interface DramaTask.MsgHandler
          An inteface to be implemented by objects which output MsgOut messages.
static class DramaTask.TaskInfo
          A class used with the DramaTask.Tasks() function, to return the details of currently known DRAMA tasks.
 
Field Summary
static int ARG_COPY
          A flag supplied to RequestExit()/RequestEnd() which indicates the argument should be copied immediately and deleted by DRAMA when appropiate.
static int ARG_DELETE
          A flag supplied to RequestExit()/RequestEnd() which indicates the argument should be deleted by DRAMA when appropiate.
static int ARG_FREEID
          A flag supplied to RequestExit()/RequestEnd() which indicates the argument (and SDS id) should be free-ed by DRAMA when appropiate.
static int ARG_NODELETE
          A flag supplied to RequestExit()/RequestEnd() which indicates the argument should not be deleted and not be copied.
static int ARG_READFREE
          A flag supplied to RequestExit()/RequestEnd() which indicates the argument is an SDS id obtained by reading an SDS file and should be cleaned-up appropiately by DRAMA when appropiate.
static int CTX_KICKED
          Possible value from GetContext - Indicates Kick context.
static int CTX_OBEY
          Possible value from GetContext - Indicates Obey context.
static int CTX_UFACE
          Possible value from GetContext - Indicates User Interface context..
static int FC_IC
          Possible flag to DramaTask constructor.
static int LOG_ACT
          Possible value for SetDebug - Output details of action handling.
static int LOG_ALL
          Possible value for SetDebug - Log everything.
static int LOG_BASIC
          Possible value for SetDebug - Basic level debugging.
static int LOG_BULK
          Possible value for SetDebug - Log details of bulk data operations.
static int LOG_DETAILS
          Possible value for SetDebug - Log details of such things as message lengths.
static int LOG_IMPEVENTS
          Possible value for SetDebug - Turn IMP level event logging on.
static int LOG_IMPINIT
          Possible value for SetDebug - Output details of calls which initiaite IMP operations.
static int LOG_IMPSYS
          Possible value for SetDebug - Output details of IMP System messages
static int LOG_INST
          Possible flag to DramaTask.Log.
static int LOG_LIBS
          Possible value for SetDebug - Log details of some libraries (DCPP).
static int LOG_MON
          Possible value for SetDebug - Output details of monitor system.
static int LOG_OFF
          Possible value for SetDebug - Turn debugging off
static int LOG_RXLPEXIT
          Possible value for SetDebug - Log a message indicating exit from the main message receiving routine.
static int LOG_STARTUP
          Possible flag to DramaTask.Log.
static int LOG_USER1
          Possible flag to DramaTask.Log.
static int LOG_USER2
          Possible flag to DramaTask.Log.
static int MAY_LOAD
          Possible flag to DramaTask constructor.
static int NO_FC_AC
          Possible flag to DramaTask constructor.
static String RCSID
          The RCS (ACMM) ID.
static int REA_ASTINT
          Deprecated. Replaced by REA_SIGNAL.
static int REA_BULK_DONE
          Possible return value from GetReason - Indicates notification of bulk data transfer complete.
static int REA_BULK_TRANSFERRED
          Possible return value from GetReason - Indicates notification of bulk data transfer progress.
static int REA_COMPLETE
          Possible return value from GetReason - Indicates a Subsidary Action/ message has completed.
static int REA_DIED
          Possible return value from GetReason - Indicates a Subsidary Task died whilst an action was outstanding.
static int REA_ERROR
          Possible return value from GetReason - Indicates an Ers message has been recevied from a subsidary task.
static int REA_EXIT
          Possible return value from GetReason - Indicates an "Loaded Task has Exited" message has been received.
static int REA_KICK
          Possible return value from GetReason - Indicates Kick entry.
static int REA_LOAD
          Possible return value from GetReason - Indicates a Load Success message entry.
static int REA_LOADFAILED
          Possible return value from GetReason - Indicates Load Failure message entry.
static int REA_MESREJECTED
          Possible return value from GetReason - Indicates Message Rejected message entry.
static int REA_MESSAGE
          Possible return value from GetReason.
static int REA_NOTIFY
          Possible return value from GetReason - Indicates notification of buffer empty has been received.
static int REA_OBEY
          Possible return value from GetReason - Indicates Obey entry.
static int REA_PATHFAILED
          Possible return value from GetReason - Indicates a Get Path failure message has been received.
static int REA_PATHFOUND
          Possible return value from GetReason - Indicates a Path Found message has been received.
static int REA_RESCHED
          Possible return value from GetReason - Indicates Reschedule Event (timeout) entry.
static int REA_SIGNAL
          Possible return value from GetReason - Indicates entry for reception of a Signal message (Signal functions).
static int REA_TRIGGER
          Possible return value from GetReason - Indicates entry for reception of a Trigger message from a subsidary task.
static int UNIQUE
          Possible flag to DramaTask constructor.
 
Constructor Summary
DramaTask(String name)
          Creates a DRAMA task of a given name, default initializations.
DramaTask(String name, int bytes)
          Creates a DRAMA task of a given name with global buffer size specified.
DramaTask(String name, int bytes, int flags)
          Creates a DRAMA task of a given name, global buffer and flags specified.
DramaTask(String name, int bytes, int flags, int selfbytes)
          Creates a DRAMA task of a given name with all details specified.
 
Method Summary
 void Add(String name, DramaTask.Action obj)
          Add an action to the task.
 void Add(String name, DramaTask.KickableAction obj)
          Add a kickable action to the task.
 void Close()
          Deprecated. Replaced by DramaTask.CloseTask() which does not throw any checked exceptions.
 int CloseTask()
          Close down a DRAMA task.
 int CloseTask(DramaException exception)
          Close down a DRAMA task.
 int CloseTask(int status)
          Close down a DRAMA task.
protected  void finalize()
          DramaTask Destructor.
 void ForceMsgLoopExit()
          Force RunDrama() to retrun.
 int GetActIndex()
          Returns the action index of the current action.
 Arg GetArgument()
          Get action argument.
 int GetContext()
          Return DRAMA Context.
 String GetEntName()
          Get the entry name.
 int GetEntReason()
          Get the Reason for this action entry.
 DramaStatus GetEntStatus()
          Get the DRAMA Status associated with this action entry.
 long GetEntTransId()
          Get the entry transaction id.
 String GetName()
          Get the action name.
 int GetSeq()
          Return DRAMA action Sequence number.
static String GetSymbol(String name)
          Get a symbol (environment variable) value.
 String GetTaskName()
           
 void GitLogger(String system)
          Enable the GIT Logger.
 void GitLogger(String system, String dir)
          Enable the GIT Logger.
 boolean IsOrphan(long transid)
          Indicate if a transaction has been orphaned.
 void Kill(int index, DramaStatus killstat)
          Indicate that the SDS argument to an action should not be freeed or deleted on return of the action.
 void Kill(int index, SdsID arg, DramaStatus killstat)
          Kill an action by index.
 void Kill(String name, DramaStatus killstat)
          Kill an action by name.
 void Kill(String name, SdsID arg, DramaStatus killstat)
          Kill an action by name.
 void Log(int level, String prefix, String message)
          Log a message using the DRAMA Logging system.
 void MsgOut(String message)
          Use DRAMA to send a message to user interface.
 void PrintReason()
          Print using DRAMA MsgOut/Ers routines the reason for an entry.
 void PutHandlers(DramaTask.KickableAction obj)
          Change both the Obey and Kick handlers for the next reschedule.
 void PutKickHandler(DramaTask.Action obj)
          Change the Kick handler for the next attempt to kick this action.
 void PutKickHandler(DramaTask.KickableAction obj)
          Change the Kick handler for the next attempt to kick this action.
 void PutObeyHandler(DramaTask.Action obj)
          Change the Obey handler for the next reschedule event of this action.
 void PutRequestEnd()
          Request action completion.
 void PutRequestEnd(SdsID argument, int mode)
          Request action completion and return an argument to the parent.
 void PutRequestExit()
          Request action completion and task exit.
 void PutRequestExit(SdsID argument, int mode)
          Request action completion and task exit, return argument.
 void PutRequestSleep()
          Request action delay.
 void PutRequestWait(double delay)
          Request action delay.
 void PutRequestWaitMessage()
          Request action wait for message with no timeout.
 void PutRequestWaitMessage(double timeout)
          Request action wait for message with timeout.
 void PutUfaceErsHandler(DramaTask.ErsHandler obj)
          Supply a handler for UFACE context Ers messages.
 void PutUfaceMsgHandler(DramaTask.MsgHandler obj)
          Supply a handler for UFACE context MsgOut messages.
static void ReadFacility(String name)
          Read a DRAMA Facility file into the task.
static void ReadFacilityEnv(String directory, String file)
          Read a DRAMA Facility file into the task but don't complain if not found.
 void RemoveKickHandler()
          Clear the Kick handler.
 void RunDrama()
          Run the DRAMA task - enter the DRAMA message received loop.
 void SetDebug(int flag)
          Set DRAMA internal debugging level.
 void SetDetails(int type, String description)
          Set the task details.
 void Signal(int index)
          Signal an action by index.
 void Signal(int index, SdsID arg)
          Signal an action by index.
 void Signal(String name)
          Signal an action by name.
 void Signal(String name, SdsID arg)
          Signal an action by name.
 void TakeOrphans()
          Take over orphan transactions.
 DramaTask.TaskInfo[] Tasks()
          Returns an array of details on all the locally known running DRAMA tasks.
 void TimerCanel(long timerId)
          Cancel a timer setup with TimerInit.
 long TimerInit(DramaTask.Action obj, double timeout)
          Invoke a handler after a timeout, using DRAMA's timeout code.
 String toString()
          Returns the name of the DRAMA task.
 void Trigger(SdsID id)
          Trigger parent action.
 void UfaceCtxEnable(DramaTask.Action obj)
          Enable DRAMA's UFACE context.
 void UfaceRespond()
          Invoke the DRAMA standard response to a UFACE message entry.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

RCSID

public static final String RCSID
The RCS (ACMM) ID. This field returns the source code archive ID of this class's source file.

The returned string corresponds to the version string seen above (in the class description comments), but will contain the version details of the compiled class file's actual source file.

(ACMM is the source code archive system used by the AAO. If the string returned by RCSID does not contain the string ACMM, then it is likely the source code has been archived again outside the AAO).

See Also:
Constant Field Values

FC_IC

public static final int FC_IC
Possible flag to DramaTask constructor.

Indicates the connections to other tasks initiated by DitsGetPath should have flow control enabled.

See Also:
Constant Field Values

MAY_LOAD

public static final int MAY_LOAD
Possible flag to DramaTask constructor.

If a load operation fails for a task on the local machine due to the IMP network tasks not existing, then the task may complete the load itself if possible.

See Also:
Constant Field Values

NO_FC_AC

public static final int NO_FC_AC
Possible flag to DramaTask constructor.

Indicates the connections accepted by this task (when other tasks attempts to initiate connections with this task) should not use flow control. By default flow control is enabled. This flag is ignored if you put your own connect handler using DitsPutConnectHandler, when you can set it from you connect handler on a task specific basis. In addition, it is also ignored when local tasks connect to this task (when it is not relevant).

See Also:
Constant Field Values

UNIQUE

public static final int UNIQUE
Possible flag to DramaTask constructor.

Indicates the task name should have a unique component appended to it - such that the task is unique on the machine. For this to be certain, your supplied task name should be less then 11 characters long, otherwise some truncation may occur.

See Also:
Constant Field Values

REA_OBEY

public static final int REA_OBEY
Possible return value from GetReason - Indicates Obey entry.

See Also:
Constant Field Values

REA_KICK

public static final int REA_KICK
Possible return value from GetReason - Indicates Kick entry.

See Also:
Constant Field Values

REA_RESCHED

public static final int REA_RESCHED
Possible return value from GetReason - Indicates Reschedule Event (timeout) entry.

See Also:
Constant Field Values

REA_TRIGGER

public static final int REA_TRIGGER
Possible return value from GetReason - Indicates entry for reception of a Trigger message from a subsidary task.

See Also:
Constant Field Values

REA_ASTINT

public static final int REA_ASTINT
Deprecated. Replaced by REA_SIGNAL.
Possible return value from GetReason - Indicates entry for reception of a Signal message (Signal functions).

See Also:
Constant Field Values

REA_SIGNAL

public static final int REA_SIGNAL
Possible return value from GetReason - Indicates entry for reception of a Signal message (Signal functions).

See Also:
Constant Field Values

REA_LOAD

public static final int REA_LOAD
Possible return value from GetReason - Indicates a Load Success message entry.

See Also:
Constant Field Values

REA_LOADFAILED

public static final int REA_LOADFAILED
Possible return value from GetReason - Indicates Load Failure message entry.

See Also:
Constant Field Values

REA_MESREJECTED

public static final int REA_MESREJECTED
Possible return value from GetReason - Indicates Message Rejected message entry.

See Also:
Constant Field Values

REA_COMPLETE

public static final int REA_COMPLETE
Possible return value from GetReason - Indicates a Subsidary Action/ message has completed.

See Also:
Constant Field Values

REA_DIED

public static final int REA_DIED
Possible return value from GetReason - Indicates a Subsidary Task died whilst an action was outstanding.

See Also:
Constant Field Values

REA_PATHFOUND

public static final int REA_PATHFOUND
Possible return value from GetReason - Indicates a Path Found message has been received.

See Also:
Constant Field Values

REA_PATHFAILED

public static final int REA_PATHFAILED
Possible return value from GetReason - Indicates a Get Path failure message has been received.

See Also:
Constant Field Values

REA_MESSAGE

public static final int REA_MESSAGE
Possible return value from GetReason. Indicates an MsgOut() message has been recevied from a subsidary task.

See Also:
Constant Field Values

REA_ERROR

public static final int REA_ERROR
Possible return value from GetReason - Indicates an Ers message has been recevied from a subsidary task.

See Also:
Constant Field Values

REA_EXIT

public static final int REA_EXIT
Possible return value from GetReason - Indicates an "Loaded Task has Exited" message has been received.

See Also:
Constant Field Values

REA_NOTIFY

public static final int REA_NOTIFY
Possible return value from GetReason - Indicates notification of buffer empty has been received. See RequestNotify for more details.

See Also:
Constant Field Values

REA_BULK_TRANSFERRED

public static final int REA_BULK_TRANSFERRED
Possible return value from GetReason - Indicates notification of bulk data transfer progress.

See Also:
Constant Field Values

REA_BULK_DONE

public static final int REA_BULK_DONE
Possible return value from GetReason - Indicates notification of bulk data transfer complete.

See Also:
Constant Field Values

CTX_OBEY

public static final int CTX_OBEY
Possible value from GetContext - Indicates Obey context.

See Also:
Constant Field Values

CTX_KICKED

public static final int CTX_KICKED
Possible value from GetContext - Indicates Kick context.

See Also:
Constant Field Values

CTX_UFACE

public static final int CTX_UFACE
Possible value from GetContext - Indicates User Interface context..

See Also:
Constant Field Values

LOG_OFF

public static final int LOG_OFF
Possible value for SetDebug - Turn debugging off

See Also:
Constant Field Values

LOG_BASIC

public static final int LOG_BASIC
Possible value for SetDebug - Basic level debugging.

See Also:
Constant Field Values

LOG_IMPSYS

public static final int LOG_IMPSYS
Possible value for SetDebug - Output details of IMP System messages

See Also:
Constant Field Values

LOG_IMPINIT

public static final int LOG_IMPINIT
Possible value for SetDebug - Output details of calls which initiaite IMP operations.

See Also:
Constant Field Values

LOG_MON

public static final int LOG_MON
Possible value for SetDebug - Output details of monitor system.

See Also:
Constant Field Values

LOG_ACT

public static final int LOG_ACT
Possible value for SetDebug - Output details of action handling.

See Also:
Constant Field Values

LOG_DETAILS

public static final int LOG_DETAILS
Possible value for SetDebug - Log details of such things as message lengths.

See Also:
Constant Field Values

LOG_BULK

public static final int LOG_BULK
Possible value for SetDebug - Log details of bulk data operations.

See Also:
Constant Field Values

LOG_LIBS

public static final int LOG_LIBS
Possible value for SetDebug - Log details of some libraries (DCPP).

See Also:
Constant Field Values

LOG_IMPEVENTS

public static final int LOG_IMPEVENTS
Possible value for SetDebug - Turn IMP level event logging on.

This does what is normally done by the IMP tasklog command. When turned off or if still running when the task is shutdown, then the log is written to a file named "taskname.imp_log" where taskname is the name of the DRAMA task.

See Also:
Constant Field Values

LOG_RXLPEXIT

public static final int LOG_RXLPEXIT
Possible value for SetDebug - Log a message indicating exit from the main message receiving routine.

See Also:
Constant Field Values

LOG_ALL

public static final int LOG_ALL
Possible value for SetDebug - Log everything.

See Also:
Constant Field Values

ARG_NODELETE

public static final int ARG_NODELETE
A flag supplied to RequestExit()/RequestEnd() which indicates the argument should not be deleted and not be copied.

See Also:
Constant Field Values

ARG_DELETE

public static final int ARG_DELETE
A flag supplied to RequestExit()/RequestEnd() which indicates the argument should be deleted by DRAMA when appropiate.

See Also:
Constant Field Values

ARG_COPY

public static final int ARG_COPY
A flag supplied to RequestExit()/RequestEnd() which indicates the argument should be copied immediately and deleted by DRAMA when appropiate.

See Also:
Constant Field Values

ARG_FREEID

public static final int ARG_FREEID
A flag supplied to RequestExit()/RequestEnd() which indicates the argument (and SDS id) should be free-ed by DRAMA when appropiate.

See Also:
Constant Field Values

ARG_READFREE

public static final int ARG_READFREE
A flag supplied to RequestExit()/RequestEnd() which indicates the argument is an SDS id obtained by reading an SDS file and should be cleaned-up appropiately by DRAMA when appropiate.

See Also:
Constant Field Values

LOG_STARTUP

public static final int LOG_STARTUP
Possible flag to DramaTask.Log.

Indicates the log level STARTUP - task startup releated logs.

See Also:
Constant Field Values

LOG_INST

public static final int LOG_INST
Possible flag to DramaTask.Log.

Indicates the log level INST - instrument control releated logs.

See Also:
Constant Field Values

LOG_USER1

public static final int LOG_USER1
Possible flag to DramaTask.Log.

Indicates the log level USER 1 - user defined level 1.

See Also:
Constant Field Values

LOG_USER2

public static final int LOG_USER2
Possible flag to DramaTask.Log.

Indicates the log level USER 2 - user defined level 2.

See Also:
Constant Field Values
Constructor Detail

DramaTask

public DramaTask(String name)
          throws DramaException
Creates a DRAMA task of a given name, default initializations. Uses a global buffer space of 10000 bytes and default initialisation flags and self buffer size. Note that in the current scheme, you can have only on DramaTask object in a given process. Any attempt to create a second DramaTask object will cause an exception.

Parameters:
name - The name for the task
Throws:
DramaException - Thrown on errors in the DRAMA code.

DramaTask

public DramaTask(String name,
                 int bytes)
          throws DramaException
Creates a DRAMA task of a given name with global buffer size specified.

Use the specified global buffer size and default initialisation flags and self buffer size. Note that in the current scheme, you can have only on DramaTask object in a given process. Any attempt to create a second DramaTask object will cause an exception.

Parameters:
name - The name for the task
bytes - Global buffer space for this task.
Throws:
DramaException - Thrown on errors in the DRAMA code.

DramaTask

public DramaTask(String name,
                 int bytes,
                 int flags)
          throws DramaException
Creates a DRAMA task of a given name, global buffer and flags specified.

Use the specified global buffer size and default initialisation flags and self buffer size.

Parameters:
name - The name for the task
bytes - Global buffer space for this task.
flags - The initialisation flags. An exclusive or of one or more of MAYLOAD, NOEXHAND, NO_FC_AC, FC_IC.
Throws:
DramaException - Thrown on errors in the DRAMA code.

DramaTask

public DramaTask(String name,
                 int bytes,
                 int flags,
                 int selfbytes)
          throws DramaException
Creates a DRAMA task of a given name with all details specified.

Use the specified global buffer size and default initialisation flags and self buffer size.

Parameters:
name - The name for the task
bytes - Global buffer space for this task.
flags - The initialisation flags. An exclusive or of one or more of MAYLOAD, NO_FC_AC, FC_IC.
selfbytes - The number of bytes for the self message buffer.
Throws:
DramaException - Thrown on errors in the DRAMA code.
Method Detail

UfaceCtxEnable

public void UfaceCtxEnable(DramaTask.Action obj)
                    throws DramaException
Enable DRAMA's UFACE context. This mode is used to enable the sending of DRAMA messages when you are not within an action handler.

Parameters:
obj - This argument is an object which implements the Action interface. The method Obey(DramaTask) throws DramaException will be invoked for any responses to messages started after the call to UfaceCtxEnable.
Throws:
DramaException - Thrown on errors in the DRAMA code.

UfaceRespond

public void UfaceRespond()
                  throws DramaException
Invoke the DRAMA standard response to a UFACE message entry. This uses ErsOut and MsgOut to output messages to the user describing the reason for the entry. For most messages, a simple string is output giving the reason and associated status for an entry.

For Informational and Error messages received from a subsidiary task (messages sent by ErsOut/ErsFlush and MsgOut), the message is decoded and output using ErsRep and MsgOut as appropriate.

This method may only be called within a DRAMA action handler or UFACe handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

Add

public void Add(String name,
                DramaTask.Action obj)
         throws DramaException
Add an action to the task. You specify the name and object to implement this action. Any other action definition with the same name is overriden.

Parameters:
name - The name for this action. Should not exceed 19 characters in length. Case sensitive.
obj - This argument is an object which implements the Action interface. The method "Obey(DramaTask) throws DramaException" will be invoked for when an Obey message with the specified name is received.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Add

public void Add(String name,
                DramaTask.KickableAction obj)
         throws DramaException
Add a kickable action to the task.

You specify the name of the action and an object to implement this action. Any other action definition with the same name is overriden.

Parameters:
name - The name for this action. Should not exceed 19 characters in length. Case sensitive.
obj - This argument is an object which implements the KickableAction interface. The method "Obey(DramaTask) throws DramaException" will be invoked for when an Obey message with the specified name is received. The method "Kick(DramaTask) throws DramaException" will be invoked when an Kick message with the specified name is received.
Throws:
DramaException - Thrown on errors in the DRAMA code.

RunDrama

public void RunDrama()
              throws DramaException
Run the DRAMA task - enter the DRAMA message received loop. The DRAMA task is run - messages are received and processed. This functions returns on error, on an action routine putting the EXIT request or after the ForceExit() method has been invoked. In order to run other Java features, such as a GUI, execute this method in a thread. Note that all action handlers are invoked in the context of whatever thread calls this method.

Note that it is quite acceptable to call this routine again after it has returned - in order to continue processing DRAMA messages.

Throws:
DramaException - Thrown on errors in the DRAMA code.

TimerInit

public long TimerInit(DramaTask.Action obj,
                      double timeout)
               throws DramaException
Invoke a handler after a timeout, using DRAMA's timeout code. This routine uses the DRAMA UFACE Timer code to invoke the Obey interface of an action object. It can be invoked from any JAVA thread but the message is always handled in the DRAMA thread as a UFACE message.

Parameters:
obj - This argument is an object which implements the Action interface. The method "Obey(DramaTask) throws DramaException" will be invoked when the timeout expires.
timeout - The time in seconds after which the timeout will be triggered. If 0 or negative, it happens immediately.
Returns:
A value which can be supplied to DramaTimerCancel to cancel this timer.
Throws:
DramaException - Thrown on errors in the DRAMA code.

TimerCanel

public void TimerCanel(long timerId)
                throws DramaException
Cancel a timer setup with TimerInit.

Parameters:
timerId - A value returned by TimerInit.
Throws:
DramaException - Thrown on errors in the DRAMA code.

ForceMsgLoopExit

public void ForceMsgLoopExit()
                      throws DramaException
Force RunDrama() to retrun. This can be invoked from another JAVA thread to force the RunDrama() in the DRAMA thread to return.

From within the DRAMA thread, you can use this call or use PutRequestExit().

This function works for sending a message to the DRAMA code which, when processed, will call PutRequestMessage().

Throws:
DramaException - Thrown on errors in the DRAMA code.

Close

public void Close()
           throws DramaException
Deprecated. Replaced by DramaTask.CloseTask() which does not throw any checked exceptions.

Close down a DRAMA task.

Since in Java a finializer may never run, the safe way to shutdown a DRAMA task is to call this function. After calling Close, future calls to other DRAMA calls are invalid (but we don't yet check for this. It is suggested the variable is assigned the value null to ensure it is never used again.

After this call, the JAVA program is no longer a DRAMA task. Other DRAMA tasks we are communicating with will be told we have exited (but the JAVA program does not exit)

Note - the fact that this method may throw a checked expection has proved a pain - since you are often shutting down the task due to an exception at this point. So it has been deprecated in faviour of DramaTask.CloseTask()

Throws:
DramaException - Thrown on errors in the DRAMA code.

CloseTask

public int CloseTask(int status)
Close down a DRAMA task.

Since in Java a finializer may never run, the safe way to shutdown a DRAMA task is to call this function. After calling CloseTask, future calls to other DRAMA calls are invalid (but we don't yet check for this. It is suggested the variable is assigned the value null to ensure it is never used again.

After this call, the JAVA program is no longer a DRAMA task. Other DRAMA tasks we are communicating with will be told we have exited (but the JAVA program does not exit)

The return value of this function is appropriate for use with System.exit()

Parameters:
status - The shutdown status of the task. Zero indicates success. Othervalues result in an error message and the return value indicating an error. Other versions take a DramaException or nothing here.

CloseTask

public int CloseTask(DramaException exception)
Close down a DRAMA task.

Since in Java a finializer may never run, the safe way to shutdown a DRAMA task is to call this function. After calling CloseTask, future calls to other DRAMA calls are invalid (but we don't yet check for this. It is suggested the variable is assigned the value null to ensure it is never used again.

After this call, the JAVA program is no longer a DRAMA task. Other DRAMA tasks we are communicating with will be told we have exited (but the JAVA program does not exit)

The return value of this function is appropriate for use with System.exit()

Parameters:
exception - An exception releated to the shutdown of the task. If this is null, then a successfull shutdown is presumed. If non-null, then a report is made to stderr and the assoicated DramaStatus is used to shutdown the task and will cause the return value to be set to indicate the status.

CloseTask

public int CloseTask()
Close down a DRAMA task.

Since in Java a finializer may never run, the safe way to shutdown a DRAMA task is to call this function. After calling CloseTask, future calls to other DRAMA calls are invalid (but we don't yet check for this. It is suggested the variable is assigned the value null to ensure it is never used again.

After this call, the JAVA program is no longer a DRAMA task. Other DRAMA tasks we are communicating with will be told we have exited (but the JAVA program does not exit)

The return value of this function is appropriate for use with System.exit() but will only indicate a error shutdown if the underlying shutdown fails.


finalize

protected void finalize()
                 throws DramaException,
                        Throwable
DramaTask Destructor.

See DramaTask.Close for details of what happens to the DRAMA task, but no problems will occur if both Close and finialize are invoked.

Overrides:
finalize in class Object
Throws:
DramaException - Thrown on errors in the DRAMA code.
Throwable - As per java.lang.Object.

MsgOut

public void MsgOut(String message)
            throws DramaException
Use DRAMA to send a message to user interface.

When executing in an action handler, the message returns to the user interface which initiated the action. If executed from code which is not an action handler, the message is directed to the current programs user interface.

Parameters:
message - The message to be written to the user.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestExit

public void PutRequestExit()
                    throws DramaException
Request action completion and task exit.

Requests that the message loop (RunDrama() method) exit when this action's method returns. If invoked by an Action Handler, the parent task is told the action has completed.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestExit

public void PutRequestExit(SdsID argument,
                           int mode)
                    throws DramaException
Request action completion and task exit, return argument.

Requests that the message loop (RunDrama() method) exit when this action's method returns. If invoked by an Action Handler, the parent task is told the action has completed and the supplied argument is returned to the parent.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Parameters:
argument - The argument to return to the parent action with the action completion message.
mode - How to handle the argument, one of ARG_COPY, ARG_DELETE or ARG_NODELETE.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestEnd

public void PutRequestEnd()
                   throws DramaException
Request action completion.

Request that when this action returns, the action is marked as completed and an appropiate message sent to the parent task.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestEnd

public void PutRequestEnd(SdsID argument,
                          int mode)
                   throws DramaException
Request action completion and return an argument to the parent.

Request that when this action returns, the action is marked as completed and an appropiate message sent to the parent task, with the supplied argument attached.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Parameters:
argument - The argument to return to the parent action with the action completion message.
mode - How to handle the argument, one of ARG_COPY, ARG_DELETE or ARG_NODELETE.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestWait

public void PutRequestWait(double delay)
                    throws DramaException
Request action delay.

Request that when this action returns, the action is put to sleep for the specified time before being rescheduled with a reason of REA_RESCHED.

This method may only be called within a DRAMA action handler implementation method.

Parameters:
delay - The delay in seconds.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestSleep

public void PutRequestSleep()
                     throws DramaException
Request action delay.

Request that when this action returns, the action is put to sleep indefinitely. Normaly such a action can be woken up by invoking the Signal() method.

This method may only be called within a DRAMA action handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestWaitMessage

public void PutRequestWaitMessage(double timeout)
                           throws DramaException
Request action wait for message with timeout.

Request that when this action returns, that it awaits for a message from a subsidary task in response to messages started by this action. A timeout is applied.

This method may only be called within a DRAMA action handler implementation method.

Parameters:
timeout - The maximum wait. Should be positive.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutRequestWaitMessage

public void PutRequestWaitMessage()
                           throws DramaException
Request action wait for message with no timeout.

Request that when this action returns, that it awaits for a message from a subsidary task in response to messages started by this action.

This method may only be called within a DRAMA action handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

GetEntStatus

public DramaStatus GetEntStatus()
Get the DRAMA Status associated with this action entry.

Returns:
The Entry Status

GetEntReason

public int GetEntReason()
Get the Reason for this action entry.

See the various REA_ integer flags for the possible values.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Returns:
The entry reason as an integer.

GetArgument

public Arg GetArgument()
Get action argument.

Returns the SdsID of any argument associated with this action entry using the "Arg" type.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

WARNING 1: When the DRAMA action handler returns, the underlying SDS ID becomes invalid and may be reassigned. You must not keep references to this item, instead, if you wish to keep it about, create a deep copy of the item.

WARNING 2: In the future, DJAVA may modified such that any reference returned by this call will refer to a clearly invalid SDS ID after the action handler has returned. This will not impact correct code but may impact incorrect code that happens to work.

Returns:
An Arg class item contained the SDS ID of any argument.

GetEntTransId

public long GetEntTransId()
Get the entry transaction id.

If this action entry is associated with a subsidary task message, return an integer representation of the transaction id.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Returns:
A long representation of the transaction id.

GetEntName

public String GetEntName()
                  throws DramaException
Get the entry name.

If this action entry is associated with a subsidary task message, return an name assocaited with the transaction.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Returns:
The name associated with the entry.
Throws:
DramaException - Thrown on errors in the DRAMA code.

GetName

public String GetName()
               throws DramaException
Get the action name.

This method may only be called within a DRAMA action handler handler implementation method.

Returns:
The action name
Throws:
DramaException - Thrown on errors in the DRAMA code.

GetSymbol

public static String GetSymbol(String name)
                        throws DramaException
Get a symbol (environment variable) value.

Most systems provide a means of setting a named symbol to an equivalent string. VMS has logical names, UNIX and VxWorks have environment variables. These can be used to exercise control over the detailed operation of programs without needing a dialogue with the user or a change to the program itself. This routine is passed the name of such a symbol and returns the string - if any - to which it has been equivalenced.

Parameters:
name - The name of the symbol to get the value of
Returns:
The symbol (environment variable) value. null if there is no such simbol.
Throws:
DramaException - Thrown on errors in the DRAMA code.

IsOrphan

public boolean IsOrphan(long transid)
Indicate if a transaction has been orphaned.

Given an integer representation of a transaction id, return true if the transaction has been orphaned.

This method may only be called within a DRAMA action handler or uface handler implementation method.

Returns:
true if the specified transaction is an orphan.

GetContext

public int GetContext()
Return DRAMA Context.

The DRAMA context indicates what message we are trying to process, Obey or Kick. In addition, there is User Interface Context, which is entered by UfaceCtxEnable or on reception of a response to a message sent in user interface context. See the CTX_ flags for possible values.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Returns:
The context as an integer.

GetSeq

public int GetSeq()
Return DRAMA action Sequence number.

This number indicates the number of action reschedule events for the current action. It starts are zero for the entry trigged by the start of the action and increments for each entry.

This method may only be called within a DRAMA action handler implementation method.

Returns:
The sequence number

Trigger

public void Trigger(SdsID id)
             throws DramaException
Trigger parent action.

This routine sends a message to the parent action of this action, with the specified argument attached. The parent action willk rechedule with an reason of REA_TRIGGER.

This method may only be called within a DRAMA action handler handler implementation method.

Throws:
DramaException

PrintReason

public void PrintReason()
                 throws DramaException
Print using DRAMA MsgOut/Ers routines the reason for an entry.

This method may only be called within a DRAMA action handler or UFACE handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

PutObeyHandler

public void PutObeyHandler(DramaTask.Action obj)
                    throws DramaException
Change the Obey handler for the next reschedule event of this action.

There is no effect on kick handler. The Obey handler is reset to the original value when the action completes.

This method may only be called within a DRAMA action handler handler implementation method.

Parameters:
obj - This argument is an object which implements the Action interface. The method "Obey(DramaTask) throws DramaException" will be invoked for the next stage of this action.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutKickHandler

public void PutKickHandler(DramaTask.Action obj)
                    throws DramaException
Change the Kick handler for the next attempt to kick this action.

There is no effect on Obey handler. The Kick handler is reset to the original value when the action completes. NOTE, uses the Obey method of an Action Interface.

This method may only be called within a DRAMA action handler implementation method.

Parameters:
obj - This argument is an object which implements the Action interface. The method "Obey(DramaTask) throws DramaException" will be invoked if a Kick message is received for this action.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutKickHandler

public void PutKickHandler(DramaTask.KickableAction obj)
                    throws DramaException
Change the Kick handler for the next attempt to kick this action.

There is no effect on Obey handler. The Kick handler is reset to the original value when the action completes.

This method may only be called within a DRAMA action handler implementation method.

Parameters:
obj - This argument is an object which implements the KickableAction interface. The method "Kick(DramaTask) throws DramaException" will be invoked if a Kick message is received for this action. The Obey method is ignored.
Throws:
DramaException - Thrown on errors in the DRAMA code.

PutHandlers

public void PutHandlers(DramaTask.KickableAction obj)
                 throws DramaException
Change both the Obey and Kick handlers for the next reschedule.

Both handlers are reset to their default values when the action completes.

This method may only be called within a DRAMA action handler implementation method.

Parameters:
obj - This argument is an object which implements the KickableAction interface. The method "Obey(DramaTask) throws DramaException" will be invoked for the next reschedule of this action. The method "Kick(DramaTask) throws DramaException" will be invoked for a kick message.
Throws:
DramaException - Thrown on errors in the DRAMA code.

RemoveKickHandler

public void RemoveKickHandler()
                       throws DramaException
Clear the Kick handler.

This indicates that until reset with a PutKickHandler or PutHandlers call, this action should reject any kick messages.

This method may only be called within a DRAMA action handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

PutUfaceMsgHandler

public void PutUfaceMsgHandler(DramaTask.MsgHandler obj)
                        throws DramaException
Supply a handler for UFACE context MsgOut messages.

This method allows you to override the default handling of DRAMA MsgOut messages related to messages started in UFACE context. By default, these messages are written to stdout.

Use this method if for example you want to write MsgOut messages into a GUI scrolling message area. Supply an object which implements the PrintLine() method of the DramaTask.MsgHandler interface and use that method to direct message to your desired location.

Parameters:
obj - The object to handle MsgOut messages received in UFACE context. Must implement the MsgHandler interface.
Throws:
DramaException - Thrown on a DRAMA error.

PutUfaceErsHandler

public void PutUfaceErsHandler(DramaTask.ErsHandler obj)
                        throws DramaException
Supply a handler for UFACE context Ers messages.

This method allows you to override the default handling of DRAMA ERS messages related to messages started in UFACE context. By default, these messages are written to stderr.

Use this method if for example you want to write ERS messages into a GUI scrolling message area. Supply an object which implements the PrintLines() method of the DramaTask.ErsHandler interface and use that method to direct message to your desired location.

Parameters:
obj - The object to handle Ers messages received in UFACE context. Must implement the ErsHandler interface.
Throws:
DramaException - Thrown on a DRAMA error.

GetTaskName

public String GetTaskName()

toString

public String toString()
Returns the name of the DRAMA task.

Overrides:
toString in class Object

GetActIndex

public int GetActIndex()
                throws DramaException
Returns the action index of the current action.

This method may only be called within a DRAMA action handler implementation method.

Returns:
The action index as an integer.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Signal

public void Signal(int index)
            throws DramaException
Signal an action by index. The specified action will be rescheduled with a reason of REA_SIGNAL and no argument.

Parameters:
index - The index of the action to signal. See GetActIndex().
Throws:
DramaException - Thrown on errors in the DRAMA code.

Signal

public void Signal(String name)
            throws DramaException
Signal an action by name. The specified action will be rescheduled with a reason of REA_SIGNAL and no argument

Parameters:
name - The name of the action to signal.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Signal

public void Signal(int index,
                   SdsID arg)
            throws DramaException
Signal an action by index. The specified action will be rescheduled with a reason of REA_SIGNAL and the specified argument will be supplied.

Parameters:
index - The index of the action to signal. See GetActIndex().
arg - An SDS argument to be sent with the signal. You should call ClearFree() and ClearDelete() on this to ensure the underyting SDS structure still exists when the action is rescheduled.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Signal

public void Signal(String name,
                   SdsID arg)
            throws DramaException
Signal an action by name. The specified action will be rescheduled with a reason of REA_SIGNAL and the specified argument will be supplied.

Parameters:
name - The name of the action to signal.
arg - An SDS argument to be sent with the signal. You should call ClearFree() and ClearDelete() on this to ensure the underyting SDS structure still exists when the action is rescheduled.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Kill

public void Kill(int index,
                 DramaStatus killstat)
          throws DramaException
Indicate that the SDS argument to an action should not be freeed or deleted on return of the action. This is only usefull when the] entry reason is REA_SIGNAL and allows simple integers to be passed using DitsSignal, rather then full SDS structures.

This method may only be called within a DRAMA action handler implementation method.

Throws:
DramaException - Thrown on errors in the DRAMA code.

Kill

public void Kill(String name,
                 DramaStatus killstat)
          throws DramaException
Kill an action by name. The specified action will be killed immediately and will not reschedule again. The originator will be sent an action completion message with the specified completion status.

Parameters:
name - the name the action to kill.
killstat - The completion status for the action.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Kill

public void Kill(int index,
                 SdsID arg,
                 DramaStatus killstat)
          throws DramaException
Kill an action by index. The specified action will be killed immediately and will not reschedule again. The originator will be sent an action completion message with the specified completion status and argument.

Parameters:
index - The index of the action to kill. See GetActIndex().
arg - An SDS argument to be sent with the specified argument.
killstat - The completion status for the action.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Kill

public void Kill(String name,
                 SdsID arg,
                 DramaStatus killstat)
          throws DramaException
Kill an action by name. The specified action will be killed immediately and will not reschedule again. The originator will be sent an action completion message with the specified completion status and argument.

Parameters:
name - the name the action to kill.
arg - An SDS argument to be sent with the specified argument.
killstat - The completion status for the action.
Throws:
DramaException - Thrown on errors in the DRAMA code.

TakeOrphans

public void TakeOrphans()
                 throws DramaException
Take over orphan transactions.

This function makes the current action adopt oprhaned transactions - messages sent do other tasks the parent action of which has died.

Throws:
DramaException - Thrown on errors in the DRAMA code.

ReadFacility

public static void ReadFacility(String name)
                         throws DramaException
Read a DRAMA Facility file into the task.

The message facility table file is a C include file is generated by the messgen program and which defines a couple of structures which are normally passed directly to MessPutFacility. This normally means all facilities must be known at compile type. This function reads such an include file and creates the required structures dynamically. It then makes this facility known using MessPutFacility. This allows facilities not known at compile time to be added to a task.

Parameters:
name - The name of the facility file to load.
Throws:
DramaException - Thrown on errors in the DRAMA code.

ReadFacilityEnv

public static void ReadFacilityEnv(String directory,
                                   String file)
                            throws DramaException
Read a DRAMA Facility file into the task but don't complain if not found.

The message facility table file is a C include file is generated by the messgen program and which defines a couple of structures which are normally passed directly to MessPutFacility. This normally means all facilities must be known at compile type. This function reads such an include file and creates the required structures dynamically. It then makes this facility known using MessPutFacility. This allows facilities not known at compile time to be added to a task. This version of this method allows you to specify a directory as an environment variable and does not throw an exception if the file does not exist, rather reporting an error using Ers. *

Parameters:
directory - The name of an environment variable pointing to the directory containing the file.
file - The name of the facility file to load.
Throws:
DramaException - Thrown on errors in the DRAMA code.

SetDebug

public void SetDebug(int flag)
              throws DramaException
Set DRAMA internal debugging level.

When enabled, DITS will output information at appropriate times to assist in debugging. The following values are possible for the flags value.

LOG_OFF, LOG_BASIC, LOG_IMPSYS, LOG_IMPINIT, LOG_MON, LOG_MON, LOG_DETAILS, LOG_IMPEVENTS LOG_BULK, LOG_LIBS, LOG_RXLPEXIT, LOG_ALL

Parameters:
flag - The debugging flag to set.
Throws:
DramaException - Thrown on errors in the DRAMA code.

Tasks

public DramaTask.TaskInfo[] Tasks()
                           throws DramaException
Returns an array of details on all the locally known running DRAMA tasks. A task is locally known if it is running on the current machine or a task on the current machine has a path to the task.

Throws:
DramaException - Thrown on errors in the DRAMA code.

SetDetails

public void SetDetails(int type,
                       String description)
                throws DramaException
Set the task details.

This is used to set the task type and description, as will be seen by DitsGetTaskType(3) and DitsGetTaskDescr(3), DitsScanTask(3) and the TaskInfo() method.

Parameters:
type - An integer value which becomes the task type. These values are defined by system developers.
description - A string which becomes the task description.
Throws:
DramaException - Thrown on errors in the DRAMA code.

GitLogger

public void GitLogger(String system)
               throws DramaException
Enable the GIT Logger.

The DRAMA GIT package provides a simple logging system - the GitLogger class. This call enables the GIT Logger for this task.

This uses the parameter LOG_LEVEL and action LOG_LEVEL

Note 1. If invoked in a user action, rather then from UFACE code, then the action LOG_LEVEL and the parameter LOG_LEVEL must already exist Note 2. If invoked from UFACE code then the action LOG_LEVEL and parameter LOG_LEVEL will be created if needed. The pararameter system will be created if it has not been (hence if you are creating a parameter system, do this before invoking this method).

The definition of the LOG_LEVEL action will be overriden if it already existed.

This call opens/re-opens the log file and sets the default logging levels to those specified in the LOG_LEVEL parameter. If that parameter has the value "NONE" and the {system}_LOG_LEVEL environment variable is set, then the initial logging levels are set to to those.

The log file name is {taskname}-{date}.log with date in the format "DDMMMYYYY". This file is appended to if it already exists. The value of the DRAMA_LOGDIR environment variable is examined to find the log directory. If this is not defined, then the default directory is used.

See the GitLogger C++ class for full details. This method creates a new GitLogger object.

Parameters:
system - The logging system name. Normally releated to the task name or the task type and appropaite for setting an environment variable.
Throws:
DramaException - Thrown on errors in the DRAMA code.
See Also:
Log(int, String, String)

GitLogger

public void GitLogger(String system,
                      String dir)
               throws DramaException
Enable the GIT Logger.

The DRAMA GIT package provides a simple logging system - the GitLogger class. This call enables the GIT Logger for this task.

This uses the parameter LOG_LEVEL and action LOG_LEVEL

Note 1. If invoked in a user action, rather then from UFACE code, then the action LOG_LEVEL and the parameter LOG_LEVEL must already exist Note 2. If invoked from UFACE code then the action LOG_LEVEL and parameter LOG_LEVEL will be created if needed. The pararameter system will be created if it has not been (hence if you are creating a parameter system, do this before invoking this method).

The definition of the LOG_LEVEL action will be overriden if it already existed.

This call opens/re-opens the log file and sets the default logging levels to those specified in the LOG_LEVEL parameter. If that parameter has the value "NONE" and the {system}_LOG_LEVEL environment variable is set, then the initial logging levels are set to to those.

The log file name is {taskname}-{date}.log with date in the format "DDMMMYYYY". This file is appended to if it already exists. The "dir" argument specifies the directory to put the log file in.

See the GitLogger C++ class for full details. This method creates a new GitLogger object.

Parameters:
system - The logging system name. Normally releated to the task name or the task type and appropaite for setting an environment variable.
dir - The directory to put the log file in.
Throws:
DramaException - Thrown on errors in the DRAMA code.
See Also:
Log(int, String, String)

Log

public void Log(int level,
                String prefix,
                String message)
         throws DramaException
Log a message using the DRAMA Logging system.

DRAMA supports a logging system. Through the actual low level logging system is application specific (The GitLogger is an example, but others could be used). Regardless of the actual logging system in used, this function is a standard interface for outputing log messages. If no log system is enabled, then this routine will do nothing.

Parameters:
level - The logging level to specify. A mask of LOG_STARTUP LOG_INST, LOG_USER1, LOG_USER2.
prefix - A prefix for the log message, allowing you to indicate say the class which is outputting the message.
message - The log message itself.
Throws:
DramaException - Thrown on errors in the DRAMA code.
See Also:
GitLogger(String), GitLogger(String, String)

DJAVA

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

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