liblog-bdm/lib/liblog.3

'\" t
.\" @(#)LIBLOG.3 1.0 00/07/04 SMA;
.TH LIBLOG 3 "07 Apr 2000"
.SH NOM
LIBLOG (librairie d'interface avec le systeme de suivi et de pilotage)
.SH SYNOPSIS
.LP
.BI "cc [flag ...] file ... -lver -ldl -lnode -lshmem -ldatastr -lmsg -ladm -lgen -llog [library ...]"
.LP
.BI "#include <log.h>"
.LP
.BI "LOGT_Status LOG_Library_Open ( int " Instance ", LOGT_Flags " Open_Mode ");"
.LP
.BI "LOGT_Status LOG_Library_Close ( LOGT_Flags " Close_Mode ");"
.LP
.BI "LOGT_Status LOG_Library_Stderr_Set ( FILE * " Out ");"
.LP
.BI "LOGT_Status LOG_Channel_Open ( LOGT_Channel ** " Channel ", int " Pid ", int " Channel_Id ", char * " Module_Name ", char * " Master_Module_Name ");"
.LP
.BI "LOGT_Status LOG_Channel_Enter ( LOGT_Channel * " Channel ", char * " Sub_Module_Name ");"
.LP
.BI "LOGT_Status LOG_Channel_Leave ( LOGT_Channel * " Channel ", char * " Sub_Module_Name ");"
.LP
.BI "LOGT_Status LOG_Channel_Close ( LOGT_Channel * " Channel ");"
.LP
.BI "LOGT_Status LOG_RTab_Alloc ( LOGT_RTab ** " Rtab ", char * " Name " );"
.LP
.BI "LOGT_Status LOG_RTab_Setup ( LOGT_RTab * " RTab ", LOGT_RuleClass " Rule_Class ", LOGT_Rule " Rule ", LOGT_Rooting " Value ");"
.LP
.BI "LOGT_Status LOG_RTab_Add ( LOGT_Channel * " Channel ", LOGT_RTab * " RTab ");"
.LP
.BI "LOGT_Status LOG_RTab_Remove ( LOGT_Channel * " Channel ", LOGT_RTab * " RTab ");"
.LP
.BI "LOGT_Status LOG_RTab_Free ( LOGT_RTab * " RTab ");"
.LP
.BI "LOGT_Status LOG_Trigger_Add ( LOGT_Trigger ** " Trigger ", LOGT_Channel * " Channel ", LOGT_RTab * " RTab ", char * " Event_Type ", LOGT_Flags " Trigger_Mode ");"
.LP
.BI "LOGT_Status LOG_Trigger_Remove ( LOGT_Trigger * " Trigger ");"
.LP
.BI "LOGT_Status LOG_Event_Send ( LOGT_Channel * " Channel ", LOGT_RC * " Return_Code ", char * " Cd_Support ", va_list " Data ");"
.LP
.BI "LOGT_RC LOG_Event_External_Send ( LOGT_Channel * " Channel ", char * " Cd_Support ", char * " Data ");"
.LP
.BI "LOGT_Status LOG_Event_Info_Get ( LOGT_Channel * " Channel ", LOGT_Info * " Info ", va_list " Data ");"
.LP
.BI "LOGT_Status LOG_Event_Cpt_Get ( LOGT_Channel * " Channel ", int * " Cpt "[LOGD_RC_SIZE], char * " Reg_Expr ");"
.LP
.SH FONCTIONS
.LP
.BI "LOGT_Status LOG_Library_Open ( int " Instance ", LOGT_Flags " Open_Mode ");"
.LP
.RS 3
La librairie LIBLOG met en place des ressources partagees par tous les traitements qui utilise la meme instance de la librairie LIBLOG :
.LP
.RS 3
- les tables de routage systeme (GMRT et GDRT)
.LP
- le cache des modules
.LP
- le cache des formats d'evenement
.LP
- la queue de messages pour inserer les evenements en base
.RS -3
.LP
Cette fonction permet d'acceder a ces ressources partagees pour une instance particuliere de la librairie:
.LP
.RS 3
- en creation si
.I Open_Mode
vaut
.B LOGD_CREATE
.LP
- en ouverture simple si
.I Open_Mode
vaut
.B LOGD_OPEN
.RS -3
.LP
.I NB
: l'indicateur d'ouverture
.I Open_Mode
pourra etre combinee avec un mode de debugging (
.B MSGD_DEBUG_NONE
: aucun message d'erreur n'est affiche
.LP
.B MSGD_DEBUG
: les messages d'erreur generes par la librairie LIBMSG sont affiches sur la sortie standard d'erreur
.LP
.B MSGD_DEBUG_ALL
: les messages d'erreur generes par toutes les librairies sous-jacentes a la LIBMSG sont affiches sur la sortie standard d'erreur
.LP
.I NB
: l'appel a cette fonction est obligatoire avant d'utiliser toute autre fonction de la librairie LIBLOG.
.LP
Le mode
.B LOGD_CREATE
est exclusivement reserve aux administrateurs !
.LP
.RS -3
.BI "LOGT_Status LOG_Library_Close ( LOGT_Flags " Close_Mode " );"
.LP
.RS 3
Cette fonction permet de fermer ou de supprimer les ressources partagees de l'instance qu a ete ouverte :
.LP
.RS 3
- Suppression si
.I Close_Mode
vaut
.B LOGD_DESTROY
.LP
- Fermeture simple si
.I Close_Mode
vaut
.B LOGD_CLOSE
.RS -3
.LP
.I NB
: la fermeture de la librairie est absolument necessaire une fois qu'un traitement a fini de l'utiliser.
.LP
Le mode
.B LOGD_DESTROY
est exclusivement reserve aux administrateurs !
.LP
.RS -3
.BI "LOGT_Status LOG_Library_Stderr_Set ( FILE * " Out " );"
.LP
.RS 3
Cette fonction permet de definir
.I Out
comme la sortie standard des messages d'erreur de la librarie.
.RS -3
.LP
.BI "LOGT_Status LOG_Channel_Open ( LOGT_Channel ** " Channel ", int " Pid ", int " Channel_Id ", char * " Module_Name ", char * " Master_Module_Name ");"
.LP
.RS 3
Cette fonction permet de creer un channel a travers lequel des evenements seront envoyes au systeme de suivi.
Elle requiert les arguments suivants :
.RS 3
.LP
* (Out)
.I Channel
: l'adresse du pointeur sur le channel a creer
.LP
* (In)
.I Pid
: l'identifiant du processus proprietaire du channel
.LP
* (In)
.I Channel_Id
: l'identifiant du channel
.LP
* (In)
.I Module_Name
: le nom du module proprietaire du channel
.LP
* (In)
.I Master_Module_Name
: le nom du module maitre (facultatif)
.RS -3
.LP
.I Pour info
: 
Le nom du module proprietaire du channel permet de connaitre le traitement qui est a l'origine des evenements qui sont envoyes au suivi. Le nom du module maitre permet de connaitre le contexte de lancement de ce traitement.
.LP
Le numero du processus permet de distinguer differents processus realisant un meme traitement.
.LP
L'identifiant du channel permet de distinguer les differents channels d'un meme processus.
.LP
.I NB
: si le numero de processus passe en parametre vaut 0, alors c'est le processus courant qui sera considere comme processus proprietaire.
Ce parametre doit surtout etre renseigne pour les programmes shell, afin que ce ne soit pas le numero de processus demon qui soit pris en compte. 
.LP
Par convention, en fonctionnement mono-thread, l'identifiant du channel sera fixe a 0. En fonctionnement multi-thread, l'utilisateur est libre de fixer ce parametre comme il le veut.
.LP
.I NB
: si le nom du module maitre vaut NULL, alors il sera renseigne avec le nom du module proprietaire du channel.
.LP
.RS -3
.BI "LOGT_Status LOG_Channel_Enter ( LOGT_Channel * " Channel ", char * " Sub_Module_Name " );"
.LP
.RS 3
Cette fonction permet d'affecter un sous-module a un channel.
Un sous-module correspond en general au nom d'une fonction du traitement. Il permet de mieux identifier la partie du traitement qui genere les evenements.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Channel 
: le pointeur sur le channel de communication
.LP
* (In)
.I Sub_Module_Name
: le nom du sous-module a attacher au channel
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_Channel_Leave ( LOGT_Channel * " Channel ", char * " Sub_Module_Name " );"
.LP
.RS 3
Cette fonction permet de supprimer un sous-module d'un channel.
Le sous-module qui lui avait ete precedemment affecte est devient alors le sous-module actif.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Channel
: le pointeur sur le channel de communication
.LP
* (In)
.I Sub_Module_Name
: le nom du sous-module a supprimer du channel
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_Channel_Close ( LOGT_Channel * " Channel " );"
.LP
.RS 3
Cette fonction permet de fermer un channel.
.LP
.I Channel
est un pointeur sur le channel a fermer
.LP
.RS -3
.BI "LOGT_Status LOG_RTab_Alloc ( LOGT_RTab ** " Rtab ", char * " Name " );"
.LP
.RS 3
Cette fonction permet de creer une table de routage utilisateur.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (Out) RTab
: adresse d'un pointeur sur la table de routage a creer.
.LP
* (In) Name
: nom de la table de routage.
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_RTab_Setup ( LOGT_RTab * " RTab ", LOGT_RuleClass " Rule_Class ", LOGT_Rule " Rule ", LOGT_Rooting " Value " );"
.LP
.RS 3
Cette fonction permet de parametrer une table de routage utilisateur, par ajout d'une regle de routage.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I RTab
: un pointeur sur la table de routage
.LP
* (In)
.I Rule_Class
: la classe de la nouvelle regle
.LP
* (In)
.I Rule
: la nouvelle regle
.LP
* (In)
.I Value
: la valeur de la nouvelle regle
.RS -3
.LP
La classe de regle designe la maniere de selectionner les types d'evenement concernes par la nouvelle regle : 
.LP
.RS 3
-
.B LOGD_SELECT_ALL
: selection de tous les types d'evenements
.LP
-
.B LOGD_SELECT_GRV
: selection des types d'evenement selon leur gravite
.LP
-
.B LOGD_SELECT_RC
: selection des types d'evenement selon le code retour qui y est associe
.LP
-
.B LOGD_SELECT_TYPE
: selection des types d'evenement selon leur nom
.RS -3
.LP
La regle depend de la classe de regle choisie:
.LP
.RS 3
- NULL pour la classe
.B LOGD_SELECT_ALL
.LP
- code gravite pour la classe
.B LOGD_SELECT_GRV
.LP
- code retour pour la classe
.B LOGD_SELECT_RC
.LP
- nom du type d'evenement (expression reguliere) pour la classe
.B LOGD_SELECT_TYPE
.RS -3
.LP
La valeur de la regle est le type de routage a appliquer aux types d'evenement concernes par la regle :
.RS 3
.LP
-
.B LOGD_NULL
: routage vers /dev/null (aucun traitement de l'evenement)
.LP
-
.B LOGD_STDERR
: affichage de l'evenement sur la sortie standard d'erreur
.LP
-
.B LOGD_DATABASE
: insertion de l'evenement dans la base de donnees du suivi
.LP
-
.B LOGD_DEFAULT
: routage par defaut
.LP
-
.B LOGD_PREVIOUS
: routage defini dans la table de routage precedente
.RS -3
.LP
Pour parametrer une table de routage utilisateur, on commencera par definir les regles les plus generales (LOGD_ALL) et finir avec les regles les plus specifiques.
.LP
.RS -3
.BI "LOGT_Status LOG_RTab_Add ( LOGT_Channel * " Channel ", LOGT_RTab * " RTab " );"
.LP
.RS 3
Cette fonction permet d'affecter une nouvelle table de routage utilisateur a un channel.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (In)
.I RTab
: un pointeur sur la table de routage
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_RTab_Remove ( LOGT_Channel * " Channel ", LOGT_RTab * " RTab " );"
.LP
.RS 3
Cette fonction permet de supprimer l'association d'une table de routage utilisateur a un channel.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (In)
.I RTab
: un pointeur sur la table de routage
.RS -3
.LP
L'utilisateur pourra utiliser la constante LOGD_TOP_RTAB comme deuxieme argument, pour supprimer la table de routage de tete (la plus recemment associee au channel).
.LP
.RS -3
.BI "LOGT_Status LOG_RTab_Free ( LOGT_RTab * " RTab " );"
.LP
.RS 3
Cette fonction permet de supprimer une table de routage utilisateur.
.LP
.I RTab
est un pointeur sur la table de routage a supprimer.
.LP
NB : avant de supprimer une table de routage, on verifiera qu'elle n'est attachee a aucun channel.
.LP
.RS -3
.BI "LOGT_Status LOG_Trigger_Add ( LOGT_Trigger ** " Trigger ", LOGT_Channel * " Channel ", LOGT_RTab * "RTab ", char * " Event_Type ", LOGT_Flags " Trigger_Mode " );"
.LP
.RS 3
Cette fonction permet d'ajouter un trigger a un channel.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (Out)
.I Trigger
: l'adresse du pointeur sur le nouveau trigger
.LP
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (In)
.I RTab
: un pointeur sur la table de routage concernee
.LP
* (In)
.I Event_Type
: le type d'evenement declencheur (expression reguliere)
.LP
* (In)
.I Trigger_Mode
: le mode de fonctionnement du trigger
.RS -3
.LP
.I Rappel
:
.LP
Si un trigger fonctionne sur le mode
.B LOGD_ONESHOT
, il est automatiquement supprime des lors qu'il a ete active. En mode
.B LOGD_PERMANENT
, le trigger reste active en permanence.
.LP
Si un trigger fonctionne sur le mode
.B LOGD_ADD
, l'activation du trigger provoque l'association de la table de routage avec le channel. Avec le mode
.B LOGD_REMOVE
, l'activation du trigger correspond a leur dissociation.
.LP
Les differents modes de fonctionnement peuvent etre combines par addition binaire.
.LP
.I NB
: plusieurs triggers peuvent etre poses sur un meme channel.
.LP
.RS -3
.BI "LOGT_Status LOG_Trigger_Remove ( LOGT_Trigger * " Trigger " );"
.LP
.RS 3
Cette fonction permet de supprimer un trigger positionne sur un channel.
.LP
.I Trigger
est un pointeur sur le trigger a supprimer.
.LP
.RS -3
.BI "LOGT_Status LOG_Event_Send ( LOGT_Channel * " Channel ", LOGT_RC * " Return_Code ", char * " Cd_Support ", va_list " Data ");"
.LP
.RS 3
Cette fonction permet d'envoyer un evenement a travers un channel et de recuperer le code retour associe au type d'evenement (pilotage).
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (Out)
.I RC
: un pointeur sur le code retour
.LP
* (In)
.I Cd_Support
: le code du support source
.LP
* (In)
.I Data
: une liste d'arguments contenant les donnees de l'evenement
.RS -3
.LP
.RS -3
.BI "LOGT_RC LOG_Event_External_Send ( LOGT_Channel * " Channel ", char * " Cd_Support ", char * " Data ");"
.LP
.RS 3
Cette fonction est definie pour tous les appels a partir de programmes ecrits en PL/SQL.
Elle permet d'envoyer un evenement a travers un channel et de recuperer le code retour associe au type d'evenement (pilotage).
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (In)
.I Cd_Support
: le code du support source
.LP
* (In)
.I Data
: une chaine de caracteres contenant les donnees de l'evenement
.RS -3
.LP
.I NB
: la fonction retourne le code retour associe au type d'evenement.
.LP
.RS -3
.BI "LOGT_Status LOG_Event_Info_Get ( LOGT_Channel * " Channel ", LOGT_Info * " Info ", va_list " Data " );"
.LP
.RS 3
Cette fonction permet de simuler l'envoi d'un evenement et de recuperer toutes les informations concernant le type par lequel il a ete resolu.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (Out)
.I Info
: un pointeur sur les informations a recuperer
.LP
* (In)
.I Data
: une liste d'arguments contenant les donnees de l'evenement a tester
.RS -3
.LP
.I NB
: le type LOGT_Info est une structure qui contient les informations suivantes :
.LP
.RS 3
-
.B EvtType
(type d'evenement par lequel l'evenement est resolu) de type char *
.LP
-
.B RC
(code retour associe) de type
.B LOGT_RC
.LP
-
.B Gravite
(code gravite associe) de type
.B LOGT_Gravite
.LP
-
.B Rooting
(routage associe) de type
.B LOGT_Rooting
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_Event_Info_External_Get ( LOGT_Channel * " Channel ", LOGT_Info * " Info ", char * " Event_Name " );"
.LP
.RS 3
Cette fonction permet de simuler l'envoi d'un evenement et de recuperer toutes les informations concernant le type par lequel il a ete resolu.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (Out)
.I Info
: un pointeur sur les informations a recuperer
.LP
* (In)
.I Event_Name
: le nom de l'evenement a tester
.RS -3
.LP
.RS -3
.BI "LOGT_Status LOG_Event_Cpt_Get ( LOGT_Channel * " Channel ", int * " Cpt " [LOGD_RC_SIZE], char * " Reg_Expr " );"
.LP
.RS 3
Cette fonction permet de recuperer les compteurs d'evenements dont le nom correspond a une expression reguliere.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Channel
: un pointeur sur le channel
.LP
* (Out)
.I Cpt
: un pointeur sur un tableau de compteurs
.LP
* (In)
.I Reg_Expr
: une expression reguliere
.RS -3
.LP
.I NB
: le tableau de compteurs doit etre alloue par l'utilisateur.
.LP
La fonction retourne dans ce tableau le nombre d'evenements correspondant a l'expression reguliere ayant ete envoyes via le channel pour chacun des codes retour.
.LP
.I Exemple
: Cpt[LOGD_RC_OK] contiendra le nombre d'evenements envoyes ayant retourne le code LOGD_RC_OK.
.SH CODES RETOUR
.LP
Toutes les fonctions constituant l'API de la librairie LIBLOG retournent un code de type
.B LOGT_Status
:
.LP
.RS 3
-
.B LOGS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B LOGS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B LOGS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B LOGS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.LP
-
.B LOGS_ERRSHM
: la fonction ne s'est pas correctement executee pour un probleme relatif a la memoire partagee
.LP
-
.B LOGS_ERRSIG
: une operation sur semaphore a ete interrompue par un signal
.LP
-
.B LOGS_ERRSEM
: la fonction ne s'est pas correctement executee pour un probleme relatif a l'utilisation des semaphores
.LP
-
.B DSS_ERRDLL
: la fonction ne s'est pas correctement executee pour un probleme de chargement dynamique d'objet
.LP
.RS -3
.I NB
: la macro
.B LOG_ERROR()
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable
.B LOG_Error_Msg
contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP