DramaPath (DRAMA Java Interface

Package

Class

Tree

Deprecated

Index

Help

DJAVA

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

au.gov.aao.drama
Class DramaPath

java.lang.Object
  au.gov.aao.drama.DramaPath

public class DramaPath
extends Object
extends Object

This class implements an interface to sending DRAMA messages. Creating Objects of this type require an existing DramaTask object. To send messages to another DRAMA task, you create a DramaPath object, e.g.

 target = new DramaPath(DramaTask, Name, Node);

You can then use this object to initiate getting the underlying DRAMA path to the target task and then to send messages to that task, e.g.

 target.GetPathW();
 target.GetPath();
 target.ObeyW("TICK");
 target.Obey("TICK");

etc.

Methods which send DRAMA messages and wait for message completion.

These methods have a "W" as the last character in the name. They send the specified DRAMA message and wait for completion (optionally with a timeout).

They are often the easiest way to send a DRAMA message from DRAMA code but they are far less efficent and the non-waiting approach (in several ways). As a result, they should only be used where the efficency of the resulting code is not of concern. In addition, there are a restrictions on how they can be used since they block the DRAMA message loop to wait for completion. In particular, if you make calls to these more then once at a time in a DRAMA task, then the methods will always unblock (return) in reverse order, rather then in the order in which the responses arrive. See DulMessageW(3) for more details.

These methods may cause a GUI to hang whilst waiting for completion. They should normally only be used for sending DRAMA messages which will reply quickly. There are no such methods for sending Monitor messages at the moment (Monitor ADD/CANCEL/DELETE should be added at a later date. Monitor FORWARD/START messages don't make sense).

Methods send DRAMA message and don't wait for message completion.

These methods use the standard DRAMA technique instead of waiting for message completion, providing asynchronous notification of message completion. They are somewhat harder to use but are more efficent at run time and have no significant restrictions. These methods do not have a trialing W in their names.

There are various forms of the methods which initiate messages, supporting arguments etc. All can take as an extra parameter a DramaPath.ResponseHandler type. e.g

 target.Obey("TICK", new DramaPath.ResponseHandler(target));

Objects of this class handle responses to the DRAMA messages, in conjuction with a DramaPath.RescheduleHandler object. The DramaPath.RescheduleHandler object is used to handle rescheduling of your action (of UFACE context). It examines the reason for the reschedule event and if this is a message, will invoke the DramaPath.ResponseHandler to handle the message.

You can sub-class DramaPath.ResponseHandler to handle messages from subsidary messages as per your application's requirements. When sub-classing DramaPath.ResponseHandler, the following methods may be overridden.

public boolean Success(DramaPath, DramaTask);: Invoked when the message has completed successfully
public boolean Error(DramaPath, DramaTask);: Invoked when the message has completed with an error.
public boolean Trigger(DramaPath, DramaTask);: Invoked when trigger messages are received.
public boolean Msg(DramaPath, DramaTask);: Invoked when MsgOut messages are received (Normaly only when the original message was sent from UFACE context)
public boolean Ers(DramaPath, DramaTask);: Invoked when Ers messages are received (Normaly only when the original message was sent from UFACE context)

Note that the handling of MsgOut and Ers can be changed using DitsInterested(). (C Interface, the JAVA method has not yet been written).

As mentioned above, for this to work, you need to hand control of the rescheduling of your action over to an object of type DramaPath.RescheduleHandler. (This class implements the DramaTask.Action interface required of an action reschedule handler).

This can be done as follows.

 ActionRescheduleHandler = new DramaPath.RescheduleHandler(DramaTask);

 ActionRescheduleHandler = new DramaPath.RescheduleHandler();
 ActionRescheduleHandler.Enable(task);

The DramaPath.RescheduleHandler.Enable(DramaTask) method does an implict DramaTask.PutObeyHandler(DramaTask.Action). If you supply a DramaTask object is supplied as the first argument of the constructor, then DramaPath.RescheduleHandler.Enable(DramaTask) is done within the constructor. You might want to use DramaPath.RescheduleHandler.Enable(DramaTask) separately if using the one object to handle rescheduling for different actions (which is quite acceptable).

If you are sending messages from UFACE code (i.e. not within a DRAMA action, probably from a User Interface Triggered Event), then a similar procedure is required, eg.

 UfaceEventHandler = new DramaPath.RescheduleHandler(task);

Unlike the action case, in the UFACE case, this must be done before you send any messages and this handler only applies for messages sent from then until the the DRAMA message loop is processed. The same handler also will be available when handling replies to the messages, unless overriden by creating a new handler at that point.

In the action case, the handler applies to the all future events for that action, regardless of when the message was sent, until a new handler is enabled.

The UFACE case is complicated by JAVA's threads. If the case in question is a response handler for a DRAMA message, then things are ok as these run within the JAVA thread which handles DRAMA messages. But if the case in question runs outside the DRAMA JAVA thread - say as a result of a GUI event, then JAVA's threads may cause problems. As a result, DJAVA insists that UFACE messages are only sent if the DRAMA semaphore has been taken (Unless the DRAMA Message loop - DramaTask.RunDrama() - has not yet been run). This is always true if in the DRAMA message thread. But if not, you must explicitly take the DRAMA semaphore and you should do this before enabling your handler. If you try to send a message from UFACE context without having taking the DRAMA semaphore, you will get a DramaException exception with a DRAMA status code of UFACE_NOSEM. To avoid this, use the Drama semaphore in the following fashion

   DramaSem.Take();
   try {
       UfaceEventHandler = new DramaPath.RescheduleHandler(task);
       ticker.GetPath()  // Message sending call of some type.
   }
   finally {
       DramaSem.Release();
   }

DramaPath.RescheduleHandler will completly handle the rescheduling of an action (or UFACE Context). When messages related to a DramaPath object arrive, it arranges for the Success/Error/Trigger/Ers/Msg routines of your DramaPath.ResponseHandler object to be invoked as appropriate and you can sub-class DramaPath.ResponseHandler to handle each of these messages youself.

You can also sub-class DramaPath.RescheduleHandler to override certain aspects of action rescheduling. You might want to override

public void NotHandled(DramaTask);: Invoked if a message was not handled by any other handler for any reason.
public void OrphanHandler(DramaTask);: Invoked for orphaned transactions.
public void Finished(DramaTask);: Invoked when all messages have completed. If not overriden, the action will complete.
public boolean Timeout(DramaTask);: Invoked if a timeout occurs.
public boolean Signal(DramaTask);
public void ThreadError(DramaTask, DramaException);: Invoked if a JAVA Excepption occurs dispatching a message thread.
public void SystemError(DramaTask, DramaException );: Invoked if a JAVA Exception occurs whilst handling messages.

Note, there is often confusion in this area, objects of type DramaPath.ResponseHandler are used to handle replies to each message sent with methods like DramaPath.Obey(). Objects of type DramaPath.RescheduleHandler are used to handle action reschedule events, dispathing to DramaPath.ResponseHandler objects for each message.

At this point we must explain the concept of DRAMA message threads as implemented by DramaPath.RescheduleHandler.

A DramaPath.RescheduleHandler object can control rescheduling for multiple DRAMA messages sent by one action (sending multiple Obey/Set/Get/etc. with one DramaPath object or messages to multiple DramaPath objects). Replies from each of these messages results in individual reschedule events for the action which sent the original message.

To distingish between the replies sent in relation to the mutiple messages originated by an action, we can use a "DRAMA message thread" for each one. This is not to be confused with Java threads, which are unrelated to this concep). When a success or error reply message is received, the appropiate method, Success or Error, is invoked. When a Success or Error response method returns false, it is considered that a DRAMA message thread has completed. If you start a new message in your Success or Error response method, you should return true indicating the thread is not yet complete. In this way, you can sequence message operations using one DramaPath.RescheduleHandler object.

If you wish to start more then one concurrent DRAMA message (i.e. send Obeys to multiple tasks or multiple obeys to the one task at same time), you should tell the DramaPath.RescheduleHandler about it by invoking the NewThread method for each extra message. Note that the default constructors assume one DRAMA message thread. You can make them start from zero (such that NewThread can be called consisently) using different constructors. (you add a boolean argument, the value is ignored but if this argument exists, the thread count is initialised to zero)

Now we go back to the DramaPath.RescheduleHandler methods you may wish to override.

If an action reschedule event with DramaTask.GetEntReason() == DramaTask.REA_RESCHED is received, this indicates a timeout and the DramaPath.RescheduleHandler.Timeout(DramaTask) method is invoked. If Timeout() returns true, the action waits for more DRAMA message threads to complete, otherwise it completes immediately. The default behaviour in this case is to throw a JAVA exception, which would result in the action being terminated with bad status and the JAVA exception reported using ERS.

Timeouts are associated with the DramaPath.RescheduleHandler object. To specify a timeout value, add a "double" argument containing the value to the DramaPath.RescheduleHandler object constructor. You can also use the DramaPath.RescheduleHandler.SetTimeout(double) method to change the timeout. The default timeout is 0, meaning never. For example, all of the following specify a one second timeout. The first three also specify a zero initial thread count.

 handler = new DramaPath.RescheduleHandler(DramaTask,1.0,true);
 handler = new DramaPath.RescheduleHandler(DramaTask,true,1.0);
 handler = new DramaPath.RescheduleHandler(1.0,true);
       
 handler = new DramaPath.RescheduleHandler(DramaTask,1.0);
 handler = new DramaPath.RescheduleHandler(1.0);

If an action reschedule event with DramaTask.GetEntReason() == DramaTask.REA_SIGNAL is received, the action has been signalled with DramaTask.Signal() and the DramaPath.RescheduleHandler.Signal(DramaTask) method is invoked. If Signal() returns true, the action waits for more DRAMA message threads to complete, otherwise it completes immediately. The default behaviour is to ignore these events.

DramaPath.RescheduleHandler.ThreadError(DramaTask,DramaException) is invoked if a JAVA exception occurs whilst dispatching messages for a thread. The default ThreadError() routine ensures that all threads complete before an error is thrown. If more threads are to complete, the exception is saved and then reported after the last thread has completed. Otherwise, the exception is thrown immediately, resulting in DramaPath.RescheduleHandler.SystemError(DramaTask,DramaException) being invoked.

DramaPath.RescheduleHandler.SystemError(DramaTask,DramaException) is invoked if an exception occurs at any time other then dispatching the message, or if the ThreadError() threw an exception itself. The default behaviour is to rethrow the exception which will result in the action completing. The DRAMA status of the action completion will be set to that associated with the exception and the exception details will be reported using Ers.

DramaPath.RescheduleHandler.Finished(DramaTask) is invoked after the last message on the last thread has completed, or if Signal()/Timeout() returned false. It indicates the message handling sequence is complete. The default version will allow the action to complete, but if a thread error had occured, it will throw that error.

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

Nested Class Summary
`static class`	`DramaPath.Buffers` A helper class for defining buffer sizes for use with DramaPath objects.
`static interface`	`DramaPath.DisconnectHandler` This interface is to be used by objects which are specified with with `DramaPath.SetDisconnect`.
`static class`	`DramaPath.RescheduleHandler` A class which handles rescheduling of a DRAMA Action using the DramaPath class to messages to other DRAMA tasks.
`static class`	`DramaPath.ResponseHandler` A class which handles responding to DRAMA messages initiated using a DramaPath object.

Field Summary
`static String`	`RCSID` The RCS (ACMM) ID.
`static boolean`	`ufaceCheck` Deprecated. Fix the code, don't set this flag.

Constructor Summary
`DramaPath(DramaTask MyTask)` Construct a DramaPath object to this task.
`DramaPath(DramaTask MyTask, String Name)` Contruct a DramaPath object, task known locally, assumes the task is already loaded.
`DramaPath(DramaTask MyTask, String Name, String Node)` Contruct a DramaPath object, assumes the task is already loaded but allows the node to be specified.
`DramaPath(DramaTask MyTask, String Name, String Node, String Filename)` Contruct a DramaPath object with full specification such that the task can be loaded if need be.

Method Summary
`boolean`	`Active()` Indicates if the path is active (you can send messages along it).
`boolean`	`Busy()` Indicates if operations are currently in progress to set up a path to the task.
`void`	`ClearNames()` Clear Names load time flag.
`void`	`ClearProg()` Clear PROG load time flag.
`void`	`ClearState()` Clear the task state.
`void`	`ClearSymbols()` Clear Symbols load time flag.
`void`	`Control(String Name)` Control message with name only, default reponse handler.
`void`	`Control(String Name, DramaPath.ResponseHandler handler)` Control message with name and handler.
`void`	`Control(String Name, SdsID arg)` Control message with name and argument, default reponse handler.
`void`	`Control(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Control message with name and argument and handler.
`Arg`	`ControlW(String Name)` Send Control Message with name only, wait for completion.
`Arg`	`ControlW(String Name, double Timeout)` Send control message, wait for completion with timeout.
`Arg`	`ControlW(String Name, SdsID arg)` Send Control message with argument, wait for completion.
`Arg`	`ControlW(String Name, SdsID arg, double Timeout)` Send control message with argument, wait for completion with timeout.
`boolean`	`Died()` Indicates if the related task has died.
`protected void`	`finalize()` DramaPath finalizer.
`void`	`Get(String Name)` Get Parameter with name only, default reponse handler.
`void`	`Get(String[] Names)` Multiple Parameter Get with names only, default response handler.
`void`	`Get(String[] Names, DramaPath.ResponseHandler handler)` Multiple Parameter Get with name and response handler.
`void`	`Get(String Name, DramaPath.ResponseHandler handler)` Get Parameter with name and handler.
`void`	`GetPath()` Get a path to the task - using a default response handler.
`void`	`GetPath(DramaPath.ResponseHandler MessageHandler)` Get a path to the task, using default buffers.
`void`	`GetPath(DramaPath.ResponseHandler MessageHandler, DramaPath.Buffers buffers)` Get a path to the task, specifying buffer sizes.
`boolean`	`GetPathLoaded()` Indicate if GetPath caused the task to be loaded.
`void`	`GetPathW()` Get a path to the task - waiting for completion.
`void`	`GetPathW(double Timeout)` Get a path to the task - waiting for completion, but with timeout.
`void`	`GetPathW(DramaPath.Buffers buffers)` Get a path to the task, waiting for completion, specifying buffer sizes and timeout.
`void`	`GetPathW(DramaPath.Buffers buffers, double Timeout)` Get a path to the task, waiting for completion, specifying buffer sizes and timeout.
`Arg`	`GetW(String Name)` Get a parameter value and wait for completion.
`Arg`	`GetW(String[] Names)` Get Multiple parameter values and wait for completion.
`Arg`	`GetW(String[] Names, double Timeout)` Get multiple parameter values and wait for completion and timeout.
`Arg`	`GetW(String Name, double Timeout)` Get a parameter value and wait for completion and timeout.
`boolean`	`Initial()` Indicates if GetPath is needed.
`void`	`Kick(String Name)` Kick with name only, default reponse handler.
`void`	`Kick(String Name, DramaPath.ResponseHandler handler)` Kick with name and handler.
`void`	`Kick(String Name, SdsID arg)` Kick with name and argument, default reponse handler.
`void`	`Kick(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Kick with name, argument and handler.
`void`	`KickForget(String Name)` Kick with name only, default reponse handler, transaction orphaned.
`void`	`KickForget(String Name, DramaPath.ResponseHandler handler)` Kick with name and handler, transaction orphaned.
`void`	`KickForget(String Name, SdsID arg)` Kick with name and argument, default reponse handler, orphaned.
`void`	`KickForget(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Kick with name, argument and handler.
`Arg`	`KickW(String Name)` Kick with name only, wait for completion.
`Arg`	`KickW(String Name, double Timeout)` Kick with name, wait for completion with timeout.
`Arg`	`KickW(String Name, SdsID arg)` Kick with name and argument, wait for completion.
`Arg`	`KickW(String Name, SdsID arg, double Timeout)` Kick with name and argument, wait for completion with timeout.
`String`	`LoadArg()` Return task load argument
`static void`	`LoggingOff()` Turn logging off for all tasks.
`static void`	`LoggingOn()` Turn logging on for all tasks.
`void`	`LosePath()` Lose the path and rest the state.
`void`	`Monitor(String Name, SdsID arg, DramaPath.ResponseHandler handler, boolean SendCurrent)` Send a Monitor message.
`void`	`MonitorForget(String Name, SdsID arg, DramaPath.ResponseHandler handler, boolean SendCurrent)` Send a Monitor message and forget.
`String`	`NodeName()` Returns the node this task is to be loaded on.
`void`	`Obey(String Name)` Obey with name only, default reponse handler.
`void`	`Obey(String Name, DramaPath.ResponseHandler handler)` Obey with name and handler.
`void`	`Obey(String Name, SdsID arg)` Obey with name and argument, default reponse handler.
`void`	`Obey(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Obey with name, argument and handler.
`void`	`Obey(String Name, SdsID arg, DramaPath.ResponseHandler handler, SdsID transID)` Obey with name, argument, handler and return of transaction id.
`void`	`ObeyForget(String Name)` Obey with name only, default reponse handler, Transaction orphanded.
`void`	`ObeyForget(String Name, DramaPath.ResponseHandler handler)` Obey with name and handler, transaction orphaned.
`void`	`ObeyForget(String Name, SdsID arg)` Obey with name and argument, default reponse, transaction orphaned.
`void`	`ObeyForget(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Obey with name, argument and handler, transaction orphaned.
`void`	`ObeyForget(String Name, SdsID arg, DramaPath.ResponseHandler handler, SdsID transID)` Obey with name, argument, handler and return of transaction id, orphaned.
`Arg`	`ObeyW(String Name)` Obey with name only, wait for completion.
`Arg`	`ObeyW(String Name, double Timeout)` Obey with name, wait for completion with timeout.
`Arg`	`ObeyW(String Name, SdsID arg)` Obey with name and argument, wait for completion.
`Arg`	`ObeyW(String Name, SdsID arg, double Timeout)` Obey with name and argument, wait for completion with timeout.
`void`	`RequestNotify(DramaPath.ResponseHandler handler)` Request a notification when all outstanding messages have been sent.
`void`	`Set(String Name, SdsID arg)` Set with default response handler.
`void`	`Set(String Name, SdsID arg, DramaPath.ResponseHandler handler)` Set with response handler.
`void`	`SetAbsPriority(int Priority)` Set the load time absolute priority - only if not loaded.
`void`	`SetBuffers(DramaPath.Buffers buffers)` Change the buffer allocation, only if GetPath not performed.
`void`	`SetDisconnect(DramaPath.DisconnectHandler handler)` Set a handler to be invoked if the task this DramaPath communicates with disconnects.
`void`	`SetFile(String File)` Change the load file - only effective if the task is not already loaded.
`void`	`SetLoadArg(String Argument)` Set the load time argument - only if not already loaded.
`void`	`SetNames()` Set Names load time flag.
`void`	`SetNode(String Node)` Change the task node - only if task not already found.
`void`	`SetProcess(String ProcessName)` Set the load time process name - only if not already loaded.
`void`	`SetProg()` Set PROG load time flag.
`void`	`SetRelPriority(int Priority)` Set the load time relative priority - only if not loaded.
`void`	`SetStackSize(int bytes)` Set the load time stack size.
`void`	`SetSymbols()` Set Symbols load time flag.
`void`	`SetTaskName(String Name)` Change the task name - only if not already loaded.
`void`	`SetW(String Name, SdsID arg)` Set, wait for completion.
`void`	`SetW(String Name, SdsID arg, double Timeout)` Set, wait for completion with timeout.
`DramaTask`	`Task()` Return the DramaTask object associated with this task
`void`	`TaskLoggingOff()` Turn logging off for the object.
`void`	`TaskLoggingOn()` Turn logging on for the object.
`String`	`TaskName()` Return the name of the subject task.
`String`	`toString()` Returns the name and state information on the DRAMA Path.

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

ufaceCheck

public static boolean ufaceCheck

Deprecated. Fix the code, don't set this flag.

Should we check UFACE transactions for semaphore errors.

If this flag is set true, the default, then any attempt to send a message in UFACE context without the DRAMA Semaphore being taken will trigger an error (if the DRAMA message receive loop is or was running).

You should not in general change the value of this flag and it will be removed at some point (add assumed to be true). Some older applications may want to set it false while they are being debugged - but the underlying code must fix.

Constructor Detail

DramaPath

public DramaPath(DramaTask MyTask,
                 String Name)

Contruct a DramaPath object, task known locally, assumes the task is already loaded.

Note, we cannot send Obey() etc. messages to this task until we do a GetPath() operation

Parameters:: MyTask - The current DRAMA task.; Name - The name of the target task.

DramaPath

public DramaPath(DramaTask MyTask,
                 String Name,
                 String Node)

Contruct a DramaPath object, assumes the task is already loaded but allows the node to be specified.

Note, we cannot send Obey() etc. messages to this task until we do a GetPath() operation

Parameters:: MyTask - The current DRAMA task.; Name - The name of the target task.; Node - The node on which this task is running, if not known locally.

DramaPath

public DramaPath(DramaTask MyTask,
                 String Name,
                 String Node,
                 String Filename)

Contruct a DramaPath object with full specification such that the task can be loaded if need be.

Note, we cannot send Obey() etc. messages to this task until we do a GetPath() operation. In this version of DramaPath, if the task is not loaded, then we will attempt to load it from the specified file on the specified Node.

Parameters:: MyTask - The current DRAMA task.; Name - The name of the target task.; Node - The node on which this task is running, if not known locally.; Filename - The name of the file containing this task. Must be acceptable to the IMP system on the target Node.

DramaPath

public DramaPath(DramaTask MyTask)

Construct a DramaPath object to this task.

This constructs a DramaPath objects which allows us to send messages to outself. Can be used immediately, no GetPath is required.

Parameters:: MyTask - The current DRAMA task.

Method Detail

LoggingOn

public static void LoggingOn()

Turn logging on for all tasks.

LoggingOff

public static void LoggingOff()

Turn logging off for all tasks.

TaskLoggingOn

public void TaskLoggingOn()

Turn logging on for the object.

TaskLoggingOff

public void TaskLoggingOff()

Turn logging off for the object.

GetPathLoaded

public boolean GetPathLoaded()

Indicate if GetPath caused the task to be loaded.

Returns:: true if the GetPath loaded the task.

TaskName

public String TaskName()

Return the name of the subject task.

Returns:: The name of the task this DramaPath object communications with.

Task

public DramaTask Task()

Return the DramaTask object associated with this task

Returns:: The DramaTask object specified when this DramaPath was created

NodeName

public String NodeName()

Returns the node this task is to be loaded on.

Returns:: The name of the node.

LoadArg

public String LoadArg()

Return task load argument

Returns:: The task load argument string

SetTaskName

public void SetTaskName(String Name)

Change the task name - only if not already loaded.

Parameters:: Name - The new name for the task.

SetNode

public void SetNode(String Node)

Change the task node - only if task not already found.

Parameters:: Node - The node to find/load the task on.

SetFile

public void SetFile(String File)

Change the load file - only effective if the task is not already loaded.

Parameters:: File - The file to load the task from if not already loaded.

SetBuffers

public void SetBuffers(DramaPath.Buffers buffers)

Change the buffer allocation, only if GetPath not performed.

Parameters:: buffers - The buffer sizes.

SetProcess

public void SetProcess(String ProcessName)

Set the load time process name - only if not already loaded.

Parameters:: ProcessName - The name for the process when the task is loaded.

SetStackSize

public void SetStackSize(int bytes)

Set the load time stack size. Only used when the target operating system supports setting the task stack size.

Parameters:: bytes - The stack size in bytes.

SetLoadArg

public void SetLoadArg(String Argument)

Set the load time argument - only if not already loaded.

Parameters:: Argument - The load time argument

SetRelPriority

public void SetRelPriority(int Priority)

Set the load time relative priority - only if not loaded.

Last of SetRelPriority() or SetAbsPriority() is used. See IMP manual for restrictions.

Parameters:: Priority - The requested priority.

SetAbsPriority

public void SetAbsPriority(int Priority)

Set the load time absolute priority - only if not loaded.

Last of SetRelPriority() or SetAbsPriority() is used. See IMP manual for restrictions.

Parameters:: Priority - The requested priority.

SetNames

public void SetNames()

Set Names load time flag.

See IMP manual for details.

ClearNames

public void ClearNames()

Clear Names load time flag.

See IMP manual for details.

SetSymbols

public void SetSymbols()

Set Symbols load time flag.

See IMP manual for details.

ClearSymbols

public void ClearSymbols()

Clear Symbols load time flag.

See IMP manual for details.

SetProg

public void SetProg()

Set PROG load time flag.

See IMP manual for details.

ClearProg

public void ClearProg()

Clear PROG load time flag.

See IMP manual for details.

ClearState

public void ClearState()

Clear the task state. Allows us to start again.

Normally, you would use the LosePath operation instead of this operation since this operation does not tidy up the path.

Active

public boolean Active()

Indicates if the path is active (you can send messages along it).

Died

public boolean Died()

Indicates if the related task has died.

Initial

public boolean Initial()

Indicates if GetPath is needed. This is required if the path is in its initial state or the related task has died..

Busy

public boolean Busy()

Indicates if operations are currently in progress to set up a path to the task.

GetPath

public void GetPath(DramaPath.ResponseHandler MessageHandler)
             throws DramaException

Get a path to the task, using default buffers.

The default buffer are MessageBytes = 800, ,MaxMessages = 1, ReplyBytes = 800, MaxReplies = 10.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

Parameters:: MessageHandler - Used to handle resultant messages.
Throws:: DramaException - Thrown on errors in the DRAMA code.

GetPath

public void GetPath(DramaPath.ResponseHandler MessageHandler,
                    DramaPath.Buffers buffers)
             throws DramaException

Get a path to the task, specifying buffer sizes.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

Parameters:: MessageHandler - Used to handle resultant messages.; buffers - Override DramaPath object Buffer sizes with these buffer sizes.
Throws:: DramaException - Thrown on errors in the DRAMA code.

GetPath

public void GetPath()
             throws DramaException

Get a path to the task - using a default response handler.

Due to the default message response handler, you can only find out if this operation is complete by overriding the DramaPath.RescheduleHandler finished() method. Otherwise, the action invoking this operation will simply complete when the path has been found.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

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

GetPathW

public void GetPathW(DramaPath.Buffers buffers)
              throws DramaException

Get a path to the task, waiting for completion, specifying buffer sizes and timeout.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

Parameters:: buffers - Override DramaPath object Buffer sizes with these buffer sizes.
Throws:: DramaException - Thrown on errors in the DRAMA code.

GetPathW

public void GetPathW(DramaPath.Buffers buffers,
                     double Timeout)
              throws DramaException

Get a path to the task, waiting for completion, specifying buffer sizes and timeout.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

Parameters:: buffers - Override DramaPath object Buffer sizes with these buffer sizes.; Timeout - The timeout for the operation, in seconds.
Throws:: DramaException - Thrown on errors in the DRAMA code.

GetPathW

public void GetPathW()
              throws DramaException

Get a path to the task - waiting for completion.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

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

GetPathW

public void GetPathW(double Timeout)
              throws DramaException

Get a path to the task - waiting for completion, but with timeout.

If the path is not loaded and sufficent information is available to attempt to load it (see the contructors etc) the an attempt to load the task is made, followed by getting a path to it.

Parameters:: Timeout - The timeout for the operation, in seconds.
Throws:: DramaException - Thrown on errors in the DRAMA code.

LosePath

public void LosePath()
              throws DramaException

Lose the path and rest the state. This method causes DRAMA to lose the underlying DRAMA path to the task this object points to. As a result, a GetPath() operation will cause a new path to be set up. See DitsLosePath() for full details on this operation - which is a little complex in some cases.

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

Obey

public void Obey(String Name)
          throws DramaException

Obey with name only, default reponse handler.

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

Obey

public void Obey(String Name,
                 DramaPath.ResponseHandler handler)
          throws DramaException

Obey with name and handler.

Parameters:: Name - The name of the action to be Obeyed.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Obey

public void Obey(String Name,
                 SdsID arg)
          throws DramaException

Obey with name and argument, default reponse handler.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Obey

public void Obey(String Name,
                 SdsID arg,
                 DramaPath.ResponseHandler handler)
          throws DramaException

Obey with name, argument and handler.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Obey

public void Obey(String Name,
                 SdsID arg,
                 DramaPath.ResponseHandler handler,
                 SdsID transID)
          throws DramaException

Obey with name, argument, handler and return of transaction id.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.; handler - Used to handle replies to this message.; transID - Used to return the transaction id for use when kicking spawnable actions. If this is a null SDS id, then a new spawn kick argument is created. Otherwise, it is considered we are updating an existing spawn kick argument.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Kick

public void Kick(String Name)
          throws DramaException

Kick with name only, default reponse handler.

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

Kick

public void Kick(String Name,
                 DramaPath.ResponseHandler handler)
          throws DramaException

Kick with name and handler.

Parameters:: Name - The name of the action to be Kicked.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Kick

public void Kick(String Name,
                 SdsID arg)
          throws DramaException

Kick with name and argument, default reponse handler.

Parameters:: Name - The name of the action to be Kicked.; arg - The SdsID of an argument for the Kick message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Kick

public void Kick(String Name,
                 SdsID arg,
                 DramaPath.ResponseHandler handler)
          throws DramaException

Kick with name, argument and handler.

Parameters:: Name - The name of the action to be Kicked.; arg - The SdsID of an argument for the Kick message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Set

public void Set(String Name,
                SdsID arg)
         throws DramaException

Set with default response handler.

Parameters:: Name - The name of the parameter to be Set.; arg - The SdsID of an argument for the Set message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Set

public void Set(String Name,
                SdsID arg,
                DramaPath.ResponseHandler handler)
         throws DramaException

Set with response handler.

Parameters:: Name - The name of the parameter to be Set.; arg - The SdsID of an argument for the Set message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Control

public void Control(String Name)
             throws DramaException

Control message with name only, default reponse handler.

Parameters:: Name - The name of the control message..
Throws:: DramaException - Thrown on errors in the DRAMA code.

Control

public void Control(String Name,
                    DramaPath.ResponseHandler handler)
             throws DramaException

Control message with name and handler.

Parameters:: Name - The name of the control message; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Control

public void Control(String Name,
                    SdsID arg)
             throws DramaException

Control message with name and argument, default reponse handler.

Parameters:: Name - The name of the control message; arg - The SdsID of an argument for the Control message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Control

public void Control(String Name,
                    SdsID arg,
                    DramaPath.ResponseHandler handler)
             throws DramaException

Control message with name and argument and handler.

Parameters:: Name - The name of the control message; arg - The SdsID of an argument for the Control message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(String Name)
         throws DramaException

Get Parameter with name only, default reponse handler.

Parameters:: Name - The name of the parameter to get.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(String Name,
                DramaPath.ResponseHandler handler)
         throws DramaException

Get Parameter with name and handler.

Parameters:: Name - The name of the parameter to Get.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(String[] Names,
                DramaPath.ResponseHandler handler)
         throws DramaException

Multiple Parameter Get with name and response handler.

Parameters:: Names - The names of the parameters to get.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(String[] Names)
         throws DramaException

Multiple Parameter Get with names only, default response handler.

Parameters:: Names - The names of the parameters to get.
Throws:: DramaException - Thrown on errors in the DRAMA code.

Monitor

public void Monitor(String Name,
                    SdsID arg,
                    DramaPath.ResponseHandler handler,
                    boolean SendCurrent)
             throws DramaException

Send a Monitor message.

Normally only used by the DramaMonitor class, although you can use it directly if you prefer.

Parameters:: Name - The Monitor message name; arg - The SdsID of the argument to the monitor message; handler - The message response handler; SendCurrent - IF true, the current value of the parameter is sent immediately (START and ADD messages only).
Throws:: DramaException - Thrown on errors in the DRAMA code.

ObeyForget

public void ObeyForget(String Name)
                throws DramaException

Obey with name only, default reponse handler, Transaction orphanded.

This method can be used to start an obey and immediately pass control to the DRAMA task orphan handler system.

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

ObeyForget

public void ObeyForget(String Name,
                       DramaPath.ResponseHandler handler)
                throws DramaException

Obey with name and handler, transaction orphaned.

This method can be used to start an obey and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Obeyed.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

ObeyForget

public void ObeyForget(String Name,
                       SdsID arg)
                throws DramaException

Obey with name and argument, default reponse, transaction orphaned.

This method can be used to start an obey and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

ObeyForget

public void ObeyForget(String Name,
                       SdsID arg,
                       DramaPath.ResponseHandler handler)
                throws DramaException

Obey with name, argument and handler, transaction orphaned.

This method can be used to start an obey and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

ObeyForget

public void ObeyForget(String Name,
                       SdsID arg,
                       DramaPath.ResponseHandler handler,
                       SdsID transID)
                throws DramaException

Obey with name, argument, handler and return of transaction id, orphaned.

This method can be used to start an obey and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Obeyed.; arg - The SdsID of an argument for the Obey message.; handler - Used to handle replies to this message.; transID - Used to return the transaction id for use when kicking spawnable actions. If this is a null SDS id, then a new spawn kick argument is created. Otherwise, it is considered we are updating an existing spawn kick argument.
Throws:: DramaException - Thrown on errors in the DRAMA code.

KickForget

public void KickForget(String Name)
                throws DramaException

Kick with name only, default reponse handler, transaction orphaned.

This method can be used to start a Kick and immediately pass control to the DRAMA task orphan handler system.

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

KickForget

public void KickForget(String Name,
                       DramaPath.ResponseHandler handler)
                throws DramaException

Kick with name and handler, transaction orphaned.

This method can be used to start a Kick and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Kicked.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

KickForget

public void KickForget(String Name,
                       SdsID arg)
                throws DramaException

Kick with name and argument, default reponse handler, orphaned.

This method can be used to start a Kick and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Kicked.; arg - The SdsID of an argument for the Kick message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

KickForget

public void KickForget(String Name,
                       SdsID arg,
                       DramaPath.ResponseHandler handler)
                throws DramaException

Kick with name, argument and handler.

This method can be used to start a Kick and immediately pass control to the DRAMA task orphan handler system.

Parameters:: Name - The name of the action to be Kicked.; arg - The SdsID of an argument for the Kick message.; handler - Used to handle replies to this message.
Throws:: DramaException - Thrown on errors in the DRAMA code.

MonitorForget

public void MonitorForget(String Name,
                          SdsID arg,
                          DramaPath.ResponseHandler handler,
                          boolean SendCurrent)
                   throws DramaException

Send a Monitor message and forget.

This method can be used to start a Monitor and immediately pass control to the DRAMA task orphan handler system.

Normally only used by the DramaMonitor class.

Parameters:: Name - The Monitor message name; arg - The SdsID of the argument to the monitor message; handler - The message response handler; SendCurrent - IF true, the current value of the parameter is sent immediately (START and ADD messages only).
Throws:: DramaException - Thrown on errors in the DRAMA code.

RequestNotify

public void RequestNotify(DramaPath.ResponseHandler handler)
                   throws DramaException

Request a notification when all outstanding messages have been sent.

Parameters:: handler - The message response handler. The Success method will be invoked when the notification is received.
Throws:: DramaException - Thrown on errors in the DRAMA code.