DitsPathGet - Initiates the getting of or returns a path to a task.

Function

Initiates the getting of or returns a path to a task.

Description

A path is required for a Dits task to send messages to other Dits tasks. This routine will either return a path to the specified task or initiate actions to obtain the path.

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.

Language

C

Call

(Void) = DitsPathGet (name, node, flags, info ,path, transid, status)

Parameters

(">" input, "!" modified, "W" workspace, "<" output)

>namechar *The null terminated name the task is thought to be registered by.

>nodechar *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.

>flagsintSelects 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.

>infoDitsPathInfoType *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.

<pathDitsPathType *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.

<transidDitsTransIdType *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.

!statusStatusType *Modified status.

External functions used

Dits___PathByTaskDits internal Find a path given the task name
Dits___PathCreateDits internal Create a new path
Dits___PathSetNameDits internal Set the name of a path
Dits___PathSetTransIdDits internal Set the transaction id for path creation.
Dits___PathSetStatusDits internal Set a path status
Dits___PathDeleteDits internal Delete a path
Dits___PathSetConnectionDits internal Set the connection of a path.
Dits___TransIdCreateDits internal Create a new transaction id.
Dits___TransIdDeleteDits internal Delete a transaction id.
ImpConnectImp Connect to a task
ImpNetLocateImp Locate a remote task.

Include files

DitsInteraction.h

External values used

DitsTask - Details of the current task

Prior requirements

Can only be called from a Dits application routine or when the context if DITS_CTX_UFACE.

See Also

The Dits Specification Document, DitsGetPath(3), DitsAppInit(3), DitsInititateMessage(3), DulGetPathW(3), DuiExecuteCmd(3), DitsPathGetInit(3).

Support

Tony Farrell, AAO

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

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