| > | newLogSys | DitsLogSysType * | The new logging system, see below. |
|---|---|---|---|
| > | oldLogSys | DitsLogSysType * | The old logging system, see below. |
| ! | status | StatusType * | Modified status.
|
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. |
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);
| > | client_data | void * | The clientData item found in the newLogSys structure. |
|---|---|---|---|
| > | argDelete | int | If argOut is valid (non-zero), then this flag is true if DITS will be deleting the argument when processing of this message completes. |
| > | argOut | SdsIdType | The 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. |
| > | request | DitsReqType | The action request - see DitsPutRequest. |
| > | delaySet | int | Has the action set a delay with DitPutDelay. |
| > | delay | const DitsDeltaTimeType | The delay, if set. Otherwise may be a null pointer. |
| > | exitStatus | StatusType | The status the action exited with. |
| > | TaskName | const char * | The name of the task. For loading, the name of the program to be loadded. |
| > | node | const char * | The name of the node. Note, may be a null pointer or zero length string if no node name is specified. |
| > | pathFlags | int | The flags to a PathGet operations. See DitsPathGet(). |
| > | pathInfo | void * | 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 *). |
| > | transid | int | The transaction id. |
| > | actptr | int | The index of the action being signaled. |
| > | ptr | const void * | A poonter value passed to a signalling routine. |
| > | argSignal | SdsIdType | The Argument to a signalling routine. |
| > | sendFlags | int | The send flags. |
| > | message | const DitsGsokMessageType * | The message sent. |
| > | loadArgString | const char * | The load argument string. |
| > | loadFlags | long | Load flags. |
| > | TaskParams | const DitsTaskParamType * | The task load parameters. |
| > | triggerArg | SdsIdType | The agument to the trigger message. |
| > | SharedMemInfo | void * | Details of shared memory. |
| > | sds | int | Does thee shared memory contain SDS. |
| > | NotifyBytes | int | Bulk data notification interval. |
| > | BulkFlags | long | Flags to a bulk data send |
| > | messageText | cons char * | The message text to be output. |
| > | level | unsigned | Logging level - see DitsLogMsg() flag with the possible addition of DITS_LOG_INTERNAL. |
| > | prefix | const char * | Prefix string to DitsLogMsg(). |
| > | fmt | const char * | A C printf style formating string. |
| > | ap | va_list | Argument list for a C printf style formating string. |
| > | errorReport | const ErsMessageType * | Details of an error report. |
| > | status | StatusType * | Modified status. See the
DitsLogSysType
notes above for details on status usage for
each function.
|
Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tony.farrell@mq.edu.au