DitsAppInit - Initialise Dits.

Function

Initialise Dits.

Description

Allocate memory for the variable DitsTask, which maintains all information about the task. When running under VxWorks, we must add this to the Task context switch block as all tasks run in common memory.

Register this task as a DRAMA (Imp) task.

Under VMS an exit handler is setup to handle an unexpected program exit correctly.

Under Unix, we attempt to setup an exit handler by setting up traps for the signals (when available)

SIGINT Interrupt.
SIGQUIT quit.
SIGPIPE Write on a pipe or socket with no one to read.
SIGHUP Hangup.
SIGTERM Software termination signal.
SIGABRT used by abort
SIGFPE floating point exception
SIGILL illegal instruction
SIGSEGV segmentation violation
SIGALRM Alarm clock.
SIGBUS bus error
SIGEMT EMT instruction
SIGIOT IOT Instruction
SIGSYS bad argument to system call
SIGTRAP trace trap (not reset when caught)
SIGXCPU Cpu time limit expired.
SIGXFSZ File size limit exceeded.

You may insert your own signal handlers for these signals but try to ensure your program calls DitsStop when it exits. The Dits signal handler will shutdown dits and calls exit(3) in a forked subprocess and invokes the systems default handler for the signal

Under VxWorks, if this is the first Dits task, then a delete hook is created to be called when the task is deleted. The hook is only added by the first Dits task. A list is maintained of all active Dits tasks and when a Dits task exits, the exit handler is called. The last Dits task to exit will delete the hook.

Message codes for the DITS, SDS, IMP ERS and ARG libraries are enabled using MessPutFacility.

The the environment variable/logical name DITS_LOG is defined with an integer value, this is used as the initial value of the internal debug flag.

Language

C

Call

(Void) = DitsAppInit (taskname, bytes, flags, initInfo, status )

Parameters

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

>tasknameChar *The name the task is to be known by.
>bytesIntThis argument indicates how many bytes should be allocated to the message buffer

This value is not allowed to be less then DITS_C_MINSIZE, which is the size of an OBEY command which has a zero length argument. Note that you should consider a buffer size equivalent to the maximum message size multiplied by the number of such messages that may be queued at any one time.

Each time another task opens a path to this task, it allocates some the space in this task's buffer for messages from the it.

It it hoped that the underlying message protocol will allow some technique for changing this buffer size, but it will nearly always be more efficient to get it right at this point.

>flagsIntA flag word containing some options. Set the following bits to enable the options.

DITS_M_NO_LOCAL_SDS Don't use Sds for local messages.
DITS_M_X_COMPATIBLE specifies that the notification mechanism used by the task must be one that can coexit with the X-windows system. X systems can use the XtAppAddInput procedure call to specify that there are other events in the system that need to be handled, and if this flag is set, a suitable message notification mechanism will be used for incomming messages. (Note that this may be slower than the default mechanism). The routine DitsGetXInfo() can be used to get the information about the mechanism required for XtAppAddInput. *** WARNING *** Under VxWorks, the use of this notification method is incompatiable with using any of the DitsSignal*() series of routines from either and ISR or another task. A warning will be issued by the DitsSignal*() serious of routines if you attempt this. (The problem is that the notification method may theoretically block for a short period - which cannot be allowed from an ISR and can cause a task reschedule event when called from another task - even when the calling task has called taskLock(). The occurance and its impact are somewhat random.)
DITS_M_MAY_LOAD If a load operation fails for a task on the local machine due to the IMP network tasks not existing, then the task may complete the load itself.
DITS_M_NOEXHAND Don't install the exit handler. If you specify this flag then you a responsible for calling DitsStop in the event of a signal which normally causes the program to exit immediately. This flag allows you to handle all signals yourself.
DITS_M_NO_FC_AC Indicates the connections accepted by this task (when other tasks attempts to initiate connections with this task) should not use flow control. By default flow control is enabled. This flag is ignored if you put your own connect handler using DitsPutConnectHandler, when you can set it from you connect handler on a task specific basis. In addition, it is also ignored when local tasks connect to this task (when it is not relevant).
DITS_M_FC_IC Indicates the connections to other tasks initiated by DitsGetPath should have flow control enabled. You can override this on a connection specific basic by using DitsPathGet instead of DitsGetPath.
DITS_M_SELF_BYTES Indicates the selfBytes item in the initInfo structure has been set.
DITS_M_GP_OLD Indicates the DitsGetPath should operate in the old mode of returned immediately if the path already exists or we are already getting a path to the same task. See the DITS_M_PG_IMMED flag of the new DitsPathGet call for details
DITS_M_SEP_SIG_BUF Indicates the task should create a second buffer of the same size as the self buffer, for use by DitsSignal() calls. This should be done if you may being calling DitsSignal() from ISR's and otherwise sending messages from the main line of the code.

DITS_M_REGISTRAR specifies that the task wants to be notified when any task registers successfully with the IMP system. Such a task will receive messages that result in the routine specified by

DitsPutRegistrationHandlerbeing invoked.

>initInfoDitsInitInfoType *Various items, dependent on which flags are set. If none of the relevant flags are set, this item is ignored so you may specify an address of 0.

selfBytes Used if DITS_M_SELF_BYTES flag is set. This Number of bytes for the self buffer. This buffer is used for signal messages and for other cases where we want to send messages to ourselves. It should be at least 2000 bytes.

!statusStatusType *Modified status.

Include files

DitsSys.h

External functions used

Dits___ExHandDeclareDits internal Setup exit handlers.

mallocCRTL Allocate memory
taskVarAddVxWorks When running under VxWorks only, add a variable to the task's switch block.
ImpRegisterIMP Register a task with the message system.
Dits___SdsIdCreateTapDits internal Create an Sds id.
Dits___SdsIdCreateGsokDits internal Create an Sds id.
MessPutFacilityMess Add a new message facility.
MessGetMsgMess Get the message text for an error code.
ErsStartErs Startup Ers.

External values used

DitsTask - Details of the current task

Prior requirements

Should be called before any other Dits calls.

See Also

The Dits Specification Document, DitsInit(3), DitsPutActions(3), Imp manual, Ers manual, Sds manual, Messgen manual.

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