If we can initiate the get path operation, then a transaction is started. The transaction id is returned in transid and the path is returned in path, although it will not be usable until the transaction completes.
The user action calling this routine should reschedule to await this message, which will have a reason code of DITS_REA_PATHFOUND or DITS_REA_PATHFAILED. The entry transaction id will be the transaction id as returned by this routine.
If the flag DITS_M_PG_IMMED is set, then this routine will return without setting up a transaction in two cases. The first occurs if we are already getting a path to the same task, in which case, status is returned set to DITS__FINDINGPATH. The second occurs if we already have a valid path to this task. In that case, we return with status ok and transid set to 0. The DITS_M_PG_IMMED flag causes this routine to emulate the behavious of versions of DRAMA prior to V1.0.
By specifing 0 for the transid, we can inquire about and existing path. In this case, the message sizes are ignored. We analyze the task name and try to find an existing path to the specified task. If we fail, status is set to DITS__UNKNTASK and path to 0. If we find an existing path, then we return it, but will set status to DITS__INVPATH if the path is not available for sending (probably waiting for a connection to be set up). In the later case, the only sensible thing to do with the path would be to lose it using DitsLosePath. The info argument is ignored during inquiries.
Please note that there is only ever one path between any two tasks and the buffer sizes are as set up for the first path to be set up between the two tasks. Subsequent calls to set up a path just returns the existing path, using the original buffer sizes. We consider this a flaw and believe the buffer sizes should be the maximum specified in any such calls, but we don't have a way of implementing this at this time. Note that if a given task has been sending connections to your task, then a connection has already been set up.
| > | name | char * | The null terminated name the task is
thought to be registered by.
|
|---|---|---|---|
| > | node | char * | The node the task is running on. If not
supplied then either the task is already
known local (running on the local machine
or some local task already has a path to
it) or the node is specified as part of the
name item in the normal internet format.
|
| > | flags | int | Selects various options to the PathGet
operation. These are one of
|
| DITS_M_FLOW_CONTROL | The connection should be flow controlled. See the Imp documentation for more details about the effect of flow control. |
|---|---|
| DITS_M_PG_IMMED | If set, then two cases which cause transactions to start won't. The first case occurs if we are already getting a path to the same task. In this case, if this flag is set, instead setting up a transaction to be triggered when the operation completes, we will return immediately with status DITS__FINDINGPATH. The second case is if we already have a path to this task. In that case, we normaly set up a transaction to complete when the path is available for sending. If this flag is set, we return immeidatly with no transaction set up but status ok. *transid will be zero. |
| > | info | DitsPathInfoType * | Use this structure to supply
various details for the GetPath operation. The
following values should be set.
|
|---|---|---|---|
| MessageBytes | The maximum number of bytes anticipated for any message to be sent. |
|---|---|
| MaxMessages | The maximum number of messages of size MaxBytes to be queued. |
| ReplyBytes | This is the maximum number of bytes anticipated in any messages sent back to the calling task. |
| MaxReplies |
The maximum number of replies of size ReplyBytes
anticipated.
|
| < | path | DitsPathType * | The path id is written here. Full
details
of the path may or may not be known immediately.
If the task to which a path is required is already
known then this path will
be valid immediately and transid will be 0. If
the task is remote and not yet known then messages
must be sent to find it. When this happens,
transid will contain a transaction id and
the path will not become valid until an appropriate
message is received. The user's action routine
should reschedule to await invocation with
a reason of DITS_REA_PATHFOUND or
DITS_REA_PATHFAILED.
Once created, a path is not deleted until the the current task exits, although it will become invalid if the target task disconnects.
|
|---|---|---|---|
| < | transid | DitsTransIdType * | If the path is known
immediately and the
DITS_M_PG_IMMED flag is set, then
this will be set to zero. If not, it will contain
the transaction id of the transaction required
to find the path. If not this pointer is not
supplied, then just do an inquiry.
|
| ! | status | StatusType * | Modified status.
|
| Dits___PathByTask | Dits internal | Find a path given the task name |
|---|---|---|
| Dits___PathCreate | Dits internal | Create a new path |
| Dits___PathSetName | Dits internal | Set the name of a path |
| Dits___PathSetTransId | Dits internal | Set the transaction id for path creation. |
| Dits___PathSetStatus | Dits internal | Set a path status |
| Dits___PathDelete | Dits internal | Delete a path |
| Dits___PathSetConnection | Dits internal | Set the connection of a path. |
| Dits___TransIdCreate | Dits internal | Create a new transaction id. |
| Dits___TransIdDelete | Dits internal | Delete a transaction id. |
| ImpConnect | Imp | Connect to a task |
| ImpNetLocate | Imp |
Locate a remote task.
|
Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tony.farrell@mq.edu.au