DitsPutRegistrationHandler - Put a routine to be invoked when another task registers with IMP.

Function

Put a routine to be invoked when another task registers with IMP.

Description

This function inserts a function which will be invoked whenever another task registers with IMP. This will only occur if this this has specified the DITS_M_REGISTRAR flag when it invoked DitsAppInit(). If you call this routine without having specified DITS_M_REGISTRAR, then the error code DITS__REGISTRAR will be returned.

The previous handler's address and client data are returned allowing you to link operations.

The registration handler is invoked in UFACE context. To send DRAMA messages from this routine, you should first invoke DitsUfaceCtxEnable() to specify an appropriate handler for reponses to your message. Alternatively, if you want to communicate with an action in your task which is already running, you can use one of the DitsSignal() series of routines or use a shared variable that will be examined the next time the action is rescheduled. (You can communicate with a running action in your task by sending it a Kick message, but DitsSignal() is the prefered approach, as it is a simpler interface since and you don't need the call to DitsUfaceCtxEnable() or a path to your task).

For this to work with tasks registering on remote machines, the IMP Startup file on that machine must specify that such messages are to be forwarded to this machine. For example, lines such at the following:

forward registrations to machine1 machine2 machine3

There may be mulitple such lines and as many machines as you want on each line.

Note that only tasks which are built against IMP Version 3.43 or later will send registration messages.

Language

C

Call

(void) = DitsPutRegistrationHandler(routine,client_data, old_routine,old_c_data,status)

Parameters

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

>routineDitsRegistrationRoutineTypeThe new registration routine.
>client_datavoid *Passed directly to the routine as its client_data argument.
!old_routineDitsRegistrationRoutineType *If non-null, return the previous handler address here. This address may be null.
!old_c_datavoid **If non-null, return the previous connect handlers client data here.
!statusStatusType *Modified status.

Function Prototypes Used

typedef int (*DitsRegistrationRoutineType)( DVOIDP client_data, DCONSTV char * taskName, DCONSTV char * nodeName, StatusType * status);

Parameters

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

>client_datavoid *The value passed to DitsPutRegistrationHandler().
>taskNameconst char *The name of the registering task.
>nodeNameconst char *The node the task registered on.
!statusStatusType *Modified status.

Include files

DitsSys.h

External functions used

None

External values used

DitsTask

Prior requirements

DitsAppInit should have been called with the DITS_M_REGISTRAR flag set.

See Also

The Dits Specification Document, DitsAppInit(3), DitsPutConnectHandler(3), DitsPathGet(3).

Support

Tony Farrell, AAO

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

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