DitsSetLogSys - Set the logging system to be used by DITS.

Function

Set the logging system to be used by DITS.

Description

DITS supports logging through an external log system. By default, no longer is provided. This routine can be used to provide a logging system or to inquire about the current enabled logging system, if any.

Language

C

Call

(void) = DitsSetLogSys (newLogSys, oldLogSys, status)

Parameters

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

>newLogSysDitsLogSysType *The new logging system, see below.
>oldLogSysDitsLogSysType *The old logging system, see below.
!statusStatusType *Modified status.

Include files

DitsUtil.h

Logging Systems

A logging system implements a number of routines which are invoked by DRAMA at various points to allow it to log operations. DITS does not provide such a logging system and it must be provided through this call (since efficency reaons and local requirements determine what logging should be done and how).

If the "newLogSys" argument is supplied, it is the address of a structure containing a client data item and a bunch of routine pointers. Particular ones of these routines are invoked at various points to log DRAMA operations. If any routine is null - the relevant items are not logged - so you can choose what you wish to log.

If the "oldLogSys" argument is supplied, it is the address of a structure into which the current log system details are placed.

Note that the logErs routine is passed down to Ers using ErsSetLogRoutine(). It is assumed that only DRAMA is changing the Ers log routine. Routines marked with (*) are not yet implemented.

It is suggested that you use memset() to zero the contents of this structure before setting the routines of interest. This will ensure upward compatbility of your code.

The are a large number of different routines since there are many points in DRAMA which you may want to log and they tend to pass different items which you may want to log.

Note that when these calls are invoked, then can use DitsGetContext() to get the current action context. If this is NOT DITS_CTX_UFACE, then they can use DitsGetName() to get the action name and DitsGetSeq() to get the action sequence counter value.

DitsLogSysType contains the following item.

clientData A void * item which is passed to each log routine then invoked.
logActEnt A routine invoked just before action entry and UFACE routine entry. Type DitsLogActEntRoutineType.
logActReturn A routine invoked when an action/UFACE entry returns. Note that the request argument to this routine might be set to the value -1. This happens for a log made on entry to DitsActionWait(3)/DitsUfaceWait(3). Type DitsLogActReturnRoutineType.
logGetPath A routine invoked when a GetPath operation is started (If the return status is bad then the status of this call is bad). Type DitsLogGetPathRoutineType.
logSignal A routine invoked when a DitsSignal operation is performed. (If the return status is bad then the status of this call is bad). NOTE. Many DRAMA applications uses this from Interrupt/Unix Signal context. The logging routine must handle mode correctly. Type DitsLogGetPathRoutineType.
logMsgSend A routine invoked when a message is sent to another task (If the return status is bad then the status of this call is bad). Type DitsLogSendRoutineType.
logLoad A routine invoked when a load operation is initiated (If the return status is bad then the status of this call is bad). Type DitsLogLoadRoutineType.
logNotify A routine invoked when a GetNotify operation is initiated. Type DitsLogNotifyReqRoutineType.
logTrigger A routine invoked after sending a trigger message. Type DitsLogTriggerRoutineType.
logTrigBulk A routine invoked after sending a bulk data trigger message. Type DitsLogTrigerBulkRoutineType.
logBulkMsg A routine invoked after sending a bulk data message. type DitsLogBulkSendRoutineType.
logMsgOut A routine invoked to log MsgOut messages. Type DitsLogMsgOutRoutineType.
logErs A routine invoked to log Ers reports. Type ErsLogRoutineType (defined by Ers.h).
logLogMsg A routine used to implement DitsLogMsg(). Will also be invoked when DRAMA's internal logging is enabled (see DitsSetDebug(3)) with a level of DITS_LOG_INTERNAL. Type DitsLogLogMsgRoutineType.
logShutdown A routine invoked when the task is shutting down. In addition to giving the ability to log task shutdown, allows the logging system to be tidied up. It will never be invoked again by DRAMA after this call. Type DitsLogShutdownRoutineType.
logFlush Invoked to flush the log to disk. See DitsLogFlush(). Prototype DitsLogFlushRoutineType
logInfo Output to stdout details of the logging system. Prototype DitsLogInfoRoutineType.

Function Prototypes Used

typedef DVOID (*DitsLogActEntRoutineType)( DVOIDP client_data, StatusType *status);

typedef DVOID (*DitsLogActReturnRoutineType)( DVOIDP client_data, int argDelete, SdsIdType argOut, DitsReqType request, int delaySet, DCONSTV DitsDeltaTimeType * delay, StatusType exitStatus, StatusType *status);

typedef DVOID (*DitsLogGetPathRoutineType)( DVOIDP client_data, DCONSTV char * TaskName, DCONSTV char * node, int pathFlags, DCONSTV DVOIDP pathInfo, DitsPathType path, DitsTransIdType transid, StatusType * status);

typedef DVOID (*DitsLogSignalRoutineType)( DVOIDP client_data, long int actptr, DCONSTV DVOIDP ptr, SdsIdType argSignal, StatusType *status);

typedef DVOID (*DitsLogMsgSendRoutineType)( DVOIDP client_data, long int sendflags, DitsPathType path, DitsTransIdType transid, DCONSTV DitsGsokMessageType * message, StatusType *status);

typedef DVOID (*DitsLogLoadRoutineType)( DVOIDP client_data, DCONSTV char * node, DCONSTV char * TaskName, DCONSTV char * loadArgString, long int loadFlags, DCONSTV DitsTaskParamType * TaskParams, DitsTransIdType transid, StatusType *status);

typedef DVOID (*DitsLogNotifyReqRoutineType)( DVOIDP client_data, int notifyRequested, DitsPathType path, DitsTransIdType transid, StatusType *status);

typedef DVOID (*DitsLogTriggerRoutineType)( DVOIDP client_data, SdsIdType triggerArg, StatusType *status);

typedef DVOID (*DitsLogTrigBulkRoutineType)( DVOIDP client_data, DCONSTV DVOIDP SharedMemInfo, int sds, int NotifyBytes, DitsTransIdType transid, StatusType *status);

typedef DVOID (*DitsLogBulkSendRoutineType)( DVOIDP client_data, DCONSTV long int BulkFlags, DCONSTV DitsPathType path, DCONSTV DVOIDP SharedMemInfo, int NotifyBytes, DitsTransIdType transid, DCONSTV DitsGsokMessageType * message, StatusType * status);

typedef DVOID (*DitsLogMsgOutRoutineType)( DVOIDP client_data, DCONSTV char * messageText, StatusType *status);

typedef DVOID (*DitsLogLogMsgRoutineType)( DVOIDP client_data, unsigned level, DCONSTV char * prefix, DCONSTV char * fmt, va_list ap, StatusType *status);

typedef DVOID (*DitsLogShutdownRoutineType)( DVOIDP client_data, int taskShutdown, StatusType * status);

typedef DVOID (*ErsLogRoutineType)( DVOIDP client_data, DCONSTV ErsMessageType * errorReport, StatusType * status);

typedef DVOID (*DitsLogFlushRoutineType)( DVOIDP client_data, StatusType * status);

typedef DVOID (*DitsLogInfoRoutineType)( DVOIDP client_data, StatusType * status);

Parameters

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

>client_datavoid *The clientData item found in the newLogSys structure.
>argDeleteintIf argOut is valid (non-zero), then this flag is true if DITS will be deleting the argument when processing of this message completes.
>argOutSdsIdTypeThe SDS ID of any action/message output argument (which is to be returned to the initiator of this message). Zero if there is not any.
>requestDitsReqTypeThe action request - see DitsPutRequest.
>delaySetintHas the action set a delay with DitPutDelay.
>delayconst DitsDeltaTimeTypeThe delay, if set. Otherwise may be a null pointer.
>exitStatusStatusTypeThe status the action exited with.
>TaskNameconst char *The name of the task. For loading, the name of the program to be loadded.
>nodeconst char *The name of the node. Note, may be a null pointer or zero length string if no node name is specified.
>pathFlagsintThe flags to a PathGet operations. See DitsPathGet().
>pathInfovoid *Details passed ot DitsPathGet in its info structure. Only valid if NOT an inquiry, (transid != 0) in which case it can be cast to a (DitsPathInfoType *).
>transidintThe transaction id.
>actptrintThe index of the action being signaled.
>ptrconst void *A poonter value passed to a signalling routine.
>argSignalSdsIdTypeThe Argument to a signalling routine.
>sendFlagsintThe send flags.
>messageconst DitsGsokMessageType *The message sent.
>loadArgStringconst char *The load argument string.
>loadFlagslongLoad flags.
>TaskParamsconst DitsTaskParamType *The task load parameters.
>triggerArgSdsIdTypeThe agument to the trigger message.
>SharedMemInfovoid *Details of shared memory.
>sdsintDoes thee shared memory contain SDS.
>NotifyBytesintBulk data notification interval.
>BulkFlagslongFlags to a bulk data send
>messageTextcons char *The message text to be output.
>levelunsignedLogging level - see DitsLogMsg() flag with the possible addition of DITS_LOG_INTERNAL.
>prefixconst char *Prefix string to DitsLogMsg().
>fmtconst char *A C printf style formating string.
>apva_listArgument list for a C printf style formating string.
>errorReportconst ErsMessageType *Details of an error report.
>statusStatusType *Modified status. See the DitsLogSysType notes above for details on status usage for each function.

External functions used

External values used

DitsTask

Prior requirements

Can only be called from a Dits Application routine

See Also

The Dits Specification Document. DitsLogMsg(3), ErsSetLogRoutine(3), ErsStart(3), DitsSetDebug(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