DitsInitMessBulk - Send a message to another task, sending a bulk data argument.

Function

Send a message to another task, sending a bulk data argument.

Description

This is a bulk data version of the general message sending routine DitsInitiateMessage(3). You can use this routine to send OBEY, KICK etc. messages.

In this version of DitsInitiateMessage(3), you can attach an amount of bulk data defined by an DITS shared memory segment. The bulk data is passed as efficiently as possible to the target task.

If the bulk data contains an exported SDS item, then the target task can receive the bulk data without doing any more work. Alternatively, and required if SDS is not involved, the target task can use various DITS inquiry functions to handle it specially.

In addition to the normal messages associated with a message transaction, you will also receive notifications about the bulk data transfer. The sending action may receive additional reschedule events with an entry reason of DITS_REA_BULK_TRANSFERRED indicating the progress of the transfer. It will also receive an entry with a reason of DITS_REA_BULK_DONE when the target task releases the shared memory. You can then call DitsGetEntBulkInfo() to retrieve details of the transfer.

The reception of DITS_REA_BULK_TRANSFERRED messages are dependent on the behavour of the target task. If it is a local task, then these mesages are recevid each time it calls DitsBulkArgReport(). If the target task is remote, these messages are sent by the local IMP transmitter task at a rate determined by it. If NotifyBytes is non-zero it indicates a hint to the target target about the rate at which these nofications are requested.

You should not delete the shared memory yourself until get the first message using one of these codes. When you get DITS_REA_BULK_DONE you are free to reuse all the shared memory as the target task has finished accessing the shared memory. You get reuse parts of the shared memory earily by making use of information retreived by DitsGetEntBulkInfo() to determine what parts of the bulk data have been used.

If the target task is local, then DITS_REA_BULK_DONE is received when the target task action entry returns or alternatively if the task invoked DitsBulkArgInfo(3), when it has called DitsBulkArgRelease(3).

If the target task is remote, then DITS_REA_BULK_DONE is recevied when the local transmitter task has finished forwarding the data to the remote machine.

As a result, in the remote task case, you are not notified when the target task has finished accessing the data, just when it is safe for you to re-use the local shared memory.

Full details about the parameters of this call common to DitsInitiateMessage(3) can be obtained from the documentation for that call. The only new argments are SharedMemInfo and NotifyBytes. There is an additional flag, DITS_M_SDS.

If the target task did not accept the message, you will receive an reschedule event with a reason of DITS_REA_MESREJECTED and the status returned by DitsGetEntStatus(3) will return the status associated with the rejection. This may occur before or after an reschedule event with reason of DITS_REA_BULK_DONE. If it occurs before, you will not receive the DITS_REA_BULK_DONE reschedule event.

If and only if you are sending a KICK message, the bulk data messages (DITS_REA_BULK_DONE and DITS_REA_BULK_TRANSFFERED) may be received after you have recived DITS_REA_COMPLETE. This would occur because the target action's kick handler has invoked DitsBulkArgInfo(3) but the corresponding DitsBulkArgRelease(3) occurs in the action's obey handler. As a result, the kick message completion occurs before the bulk data is released. Use the routine DitsGetEntCompleted(3) to determine if a DITS_REA_BULK_DONE or DITS_REA_COMPLETE message indicates completion. This can only happen if the target task is a local task.

Language

C

Call

(void) = DitsInitMessBulk(flags,path,SharedMemInfo,NotifyBytes, transid,message,status)

Parameters

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

>flagslong intA flag word controlling some options. See DitsInitiateMessage(3) for full details. In addition to options accepted by DitsInitiateMessage(3), you can specify DITS_M_SDS. Set this if the shared memory item contains an exported SDS item. If set, the target task can access the item as and argument using SDS in the normal way. (see DitsGetArgument(3). If set, this flag causes the target task to pass pass the shared memory address to the routine SdsAccess(3). If false, the shared memory contains data in an application private format and DRAMA makes no attempt to interpret it.
>pathDitsPathTypePath to the task involved.
>SharedMemInfoDitsSharedMemInfoType *A structure describing the shared memory section containing the bulk data to be sent. This is set up with the routine DitsDefineShared(3) You should not delete this shared memory until you receive a response to this transaction with code DITS_REA_BULK_TRANSFERRED or DITS_REA_BULK_DONE.
>NotifyBytesintIf non-zero, it indicates your action should be notified (using DITS_REA_BULK_TRANSFERRED entries) every time the specified number of bytes are transferred. Note the this effect is somewhat dependent on the target task behavious and you may only receive the finial DITS_REA_BULK_DONE message.
<transidDitsTransIdType *Transaction id for the transaction started. See DitsInitiateMessage(3) for full details.
!messageDitsGsokMessageType *The message details. See DitsInitiateMessage(3) for full details.
!statusStatusType *Modified status.

Include files

DitsBulk.h

See Also

DitsInitiateMessage(3), DitsInitMessPtr(3), DitsTriggerBulk(3), DitsGetEntReason(3), DitsGetEntBulkInfo(3), DitsPutActions(3), DitsArgIsBulk(3), DitsBulkArgRelease(3), DitsDefineShared(3), DitsDefineSdsShared(3), DitsBulkArgInfo(3), DitsGetArgument(3), DitsGetEntStatus(3).

Support

Tony Farrell, AAO

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

 For more information, contact tony.farrell@mq.edu.au