Communication du sous-système de programmation avec le code SRC

Les commandes SRC (System Resource Controller) sont des programmes exécutables qui prennent des options à partir de la ligne de commande.

Une fois la syntaxe de commande vérifiée, les commandes appellent les sous-routines d'exécution SRC pour construire un datagramme UDP (User Datagram Protocol) et l'envoyer au démon srcmstr .

Les sections suivantes fournissent des informations supplémentaires sur les sous-programmes SRC et sur la façon dont ils peuvent être utilisés par les sous-systèmes pour communiquer avec le processus principal SRC:

Sous-systèmes de programmation pour la réception de demandes SRC

Les tâches de programmation associées à la réception de demandes SRC varient en fonction du type de communication indiqué pour le sous-système. Le démon srcmstr utilise des sockets pour recevoir des demandes de travail à partir d'un processus de commande et construit le socket ou la file d'attente de messages nécessaire pour transmettre les demandes de travail. Chaque sous-système doit vérifier la création de son socket ou de sa file d'attente de messages. Lisez les sections suivantes pour obtenir des informations sur les instructions spécifiques au type de communication relatives à la programmation de votre sous-système afin de recevoir des paquets de demande SRC.

Remarque: Tous les sous-systèmes, quel que soit le type de communication, doivent définir une routine de l'intercepteur de signaux pour traiter la demande SIGTERM .

Réception de signaux SRC

Les sous-systèmes qui utilisent des signaux comme type de communication doivent définir une routine de traitement des signaux pour intercepter les signaux SIGNORM et SIGFORCE . La méthode d'interception de signal utilisée dépend du sous-système. Voici deux exemples des types de sous-routines qui peuvent être utilisés à cette fin.

Réception de paquets de demande SRC à l'aide de sockets

Utilisez les instructions suivantes lors de la programmation de sous-systèmes de sockets pour recevoir des paquets de demande SRC:

• Incluez la structure de sous-système SRC dans votre code de sous-système en spécifiant le fichier /usr/include/spc.h . Ce fichier contient les structures utilisées par le sous-système pour répondre aux commandes SRC. En outre, le fichier spc.h inclut le fichier srcerrno.h , qui n'a pas besoin d'être inclus séparément. Le fichier srcerrno.h contient des définitions de code d'erreur pour la prise en charge du démon.
• Lorsqu'un sous-système de sockets est démarré, le socket sur lequel le sous-système reçoit les paquets de demandes SRC est défini comme descripteur de fichier 0. Le sous-système doit le vérifier en appelant la sous-routine getsockname , qui renvoie l'adresse du socket du sous-système. Si le descripteur de fichier 0 n'est pas un socket, le sous-système doit consigner une erreur, puis quitter. Voir "Reading Internet Datagrams Example Program" dans Communications Programming Concepts pour plus d'informations sur la façon dont la sous-routine getsockname peut être utilisée pour renvoyer l'adresse d'un socket de sous-système.
• Si un sous-système interroge plusieurs sockets, utilisez la sous-routine select pour déterminer quel socket doit être lu. Pour plus d'informations sur la façon dont la sous-routine select peut être utilisée à cette fin, voir "Vérification de l'exemple de programme de connexions en attente" dans Communications Programming Concepts .
• Utilisez la sous-routine recvfrom pour obtenir le paquet de demande du socket.

  Remarque: L'adresse de retour du paquet de réponse du sous-système se trouve dans le paquet de demande SRC reçu. Cette adresse ne doit pas être confondue avec l'adresse que la sous-routine recvfrom renvoie comme l'un de ses paramètres.

  Une fois que la sous-routine recvfrom est terminée et que le paquet a été reçu, utilisez la sous-routine srcrrqs pour renvoyer un pointeur vers une structure srchdr statique. Ce pointeur contient l'adresse de retour de la réponse du sous-système. Cette structure est remplacée chaque fois que la sous-routine srcrrqs est appelée. Son contenu doit donc être stocké ailleurs s'il est nécessaire après le prochain appel à la sous-routine srcrrqs .

Réception de paquets de demandes SRC à l'aide de files d'attente de messages

Utilisez les instructions suivantes lorsque vous programmez des sous-systèmes de file d'attente de messages pour recevoir des paquets de demande SRC:

• Incluez la structure de sous-système SRC dans le code de votre sous-système en spécifiant le fichier /usr/include/spc.h . Ce fichier contient les structures utilisées par le sous-système pour répondre aux commandes SRC. En outre, le fichier spc.h inclut le fichier d'inclusion srcerrno.h , qui n'a pas besoin d'être inclus séparément. Le fichier srcerrno.h contient des définitions de code d'erreur pour la prise en charge du démon.
• Spécifiez -DSRCBYQUEUE comme option de compilation. Permet de placer un type de message (mtype) comme première zone de la structure srcreq . Cette structure doit être utilisée chaque fois qu'un paquet SRC est reçu.
• Lorsque le sous-système a été démarré, utilisez la sous-routine msgget pour vérifier qu'une file d'attente de messages a été créée au démarrage du système. Le sous-système doit consigner une erreur et se fermer si aucune file d'attente de messages n'a été créée.
• Si un sous-système interroge plusieurs files d'attente de messages, utilisez la sous-routine select pour déterminer quelle file d'attente de messages doit être lue. Voir "Vérification de l'exemple de programme de connexions en attente" dans Communications Programming Concepts pour plus d'informations sur la façon dont la sous-routine select peut être utilisée à cette fin.
• Utilisez la sous-routine msgrcv ou msgxrcv pour extraire le paquet de la file d'attente de messages. L'adresse de retour du paquet de réponse du sous-système se trouve dans le paquet reçu.
• Lorsque la sous-routine msgrcv ou msgxrcv se termine et que le paquet a été reçu, appeler la sous-routine srcrrqs pour terminer le processus de réception. La sous-routine srcrrqs renvoie un pointeur vers une structure srchdr statique qui est remplacée chaque fois que la sous-routine srcrrqs est appelée. Ce pointeur contient l'adresse de retour de la réponse du sous-système.

Sous-systèmes de programmation pour le traitement des paquets de demande SRC

Les sous-systèmes doivent être capables de traiter les demandes d'arrêt. Les sous-systèmes peuvent éventuellement prendre en charge les demandes de démarrage, d'état, de trace et d'actualisation.

Le traitement des paquets de demande implique un processus en deux étapes:

Lecture des paquets de demande SRC

Les paquets de demande SRC sont reçus par des sous-systèmes sous la forme d'une structure srcreq telle que définie dans le fichier /usr/include/spc.h . La demande de sous-système réside dans la structure subreq de la structure srcreq :

struct subreq
   short object;         /*object to act on*/
   short action;         /*action START, STOP, STATUS, TRACE,\
                           REFRESH*/
   short parm1;          /*reserved for variables*/
   short parm2;          /*reserved for variables*/
   char objname;         /*object name*/

:NONE.objectLa zone de la structure subreq indique l'objet auquel la demande s'applique. Lorsque la demande s'applique à un sous-système, laobjectest définie sur la constante SUBSYSTEM. Sinon, leobjectest défini sur le point de code du sous-serveur ou sur leobjnameest défini sur le PID du sous-serveur sous la forme d'une chaîne de caractères. Il incombe au sous-système de déterminer l'objet auquel la demande s'applique.

:NONE.actionindique l'action demandée au sous-système. Les sous-systèmes doivent comprendre les codes d'action START, STOP et STATUS. Les codes d'action TRACE et REFRESH sont facultatifs.

:NONE.parm1etparm2sont utilisées différemment par chacune des actions.

Les actions START subserver et REFRESH n'utilisent pasparm1etparm2zones.

Réponse du sous-système de programmation aux demandes SRC

Les actions de sous-système appropriées pour la majorité des demandes SRC sont programmées lorsque l'objet de sous-système est défini dans le code SRC. Les structures utilisées par les sous-systèmes pour répondre aux demandes SRC sont définies dans le fichier /usr/include/spc.h . Les sous-systèmes peuvent utiliser les sous-programmes d'exécution SRC suivants pour répondre aux exigences de traitement des commandes:

Le traitement des demandes de statut nécessite une combinaison de tâches et de sous-routines.

Lorsque des sous-systèmes reçoivent des demandes qu'ils ne peuvent pas traiter ou qui ne sont pas valides, ils doivent envoyer un paquet d'erreur avec le code d'erreur SRC_SUBICMD en réponse à la demande inconnue ou non valide. Le code SRC réserve les codes d'action 0 à 255 pour une utilisation interne du code SRC. Si votre sous-système reçoit une demande contenant un code d'action non valide, il doit renvoyer le code d'erreur SRC_SUBICMD. Les codes d'action valides pris en charge par le code SRC sont définis dans le fichier spc.h . Vous pouvez également définir des codes d'action spécifiques au sous-système. Un code d'action n'est pas valide s'il n'est pas défini par le code SRC ou votre sous-système.

Remarque: Les codes d'action 0 à 255 sont réservés à l'utilisation du code SRC.

Traitement des demandes de statut SRC

Les sous-systèmes peuvent être invités à fournir trois types de rapports de statut: statut de sous-système long, statut de sous-serveur court et statut de sous-serveur long.

Remarque: la génération de rapports de statut de sous-système court est effectuée par le démon srcmstr . Les constantes de valeur statcode et reply-status de ce type de rapport sont définies dans le fichier /usr/include/spc.h . La table des constantes de valeur de statut répertorie les codes de valeur de statut de réponse requis et suggérés.

Codes de valeur de statut de réponse

La commande SRC lssrc affiche les informations reçues sur la sortie standard. Les informations renvoyées par les sous-systèmes en réponse à une demande de statut long sont laissées à la discrétion du sous-système. Les sous-systèmes qui possèdent des sous-serveurs sont responsables du suivi et de la génération de rapports sur les changements d'état des sous-serveurs, si nécessaire. Utilisez la sous-routine srcstathdr pour extraire un en-tête de statut standard à transmettre au début de vos données de statut.

Les étapes suivantes sont recommandées pour le traitement des demandes de statut:

1. Pour renvoyer le statut d'un sous-système (court ou long), allouez un tableau de structures statcode plus une structure srchdr . La structure srchdr doit démarrer la mémoire tampon que vous envoyez en réponse à la demande de statut. La structure statcode est définie dans le fichier /usr/include/spc.h .

   struct statcode
   {
      short objtype;
      short status;
      char objtext [65];
      char objname [30];
   };

2. Remplissez leobjtypeavec la constante SUBSYSTEM pour indiquer que le statut est pour un sous-système ou avec un point de code de sous-serveur pour indiquer que le statut est pour un sous-serveur.
3. Remplissez lestatusavec l'une des constantes d'état SRC définies dans le fichier spc.h .
4. Remplissez leobjtextavec le texte NLS que vous souhaitez afficher en tant que statut. Cette zone doit être une chaîne à terminaison NULL.
5. Remplissez leobjnameavec le nom du sous-système ou du sous-serveur pour lequel leobjtexts'applique. Cette zone doit être une chaîne à terminaison NULL.

   Remarque: Le sous-système et le demandeur peuvent accepter de renvoyer d'autres informations définies par le sous-système au demandeur.

Sous-systèmes de programmation pour l'envoi de paquets de réponse

Le paquet renvoyé par un sous-système au code SRC doit être sous la forme de la structure srcrep définie dans le fichier /usr/include/spc.h . La structure svrreply qui fait partie de la structure srcrep contiendra la réponse du sous-système:

struct svrreply
{
   short rtncode;        /*return code from the subsystem*/
   short objtype;        /*SUBSYSTEM or SUBSERVER*/
   char objtext[65];     /*object description*/
   char objname[20];     /*object name*/
   char rtnmsg[256];     /*returned message*/
};

Utilisez la sous-routine srcsrpy pour renvoyer un paquet au demandeur.

Création d'une réponse

Pour programmer une réponse de sous-système, procédez comme suit:

1. Remplissez le rtncodeavec le code d'erreur SRC qui s'applique. Utilisez SRC_SUBMSG commertncodepour renvoyer un message NLS spécifique au sous-système.
2. Remplissez leobjtypeavec la constante SUBSYSTEM pour indiquer que la réponse est destinée à un sous-système ou avec le point de code du sous-serveur pour indiquer que la réponse est destinée à un sous-serveur.
3. Remplissez leobjnameavec le nom du sous-système, le type de sous-serveur ou l'objet sous-serveur qui s'applique à la réponse.
4. Remplissez lertnmsgavec le message NLS spécifique au sous-système.
5. Entrez l'entrée appropriée dans le paramètre srcsrpy Suite . Pour plus d'informations, voir "srcsrpy Continuation Packets".

   Remarque: END doit toujours être spécifié dans le paramètre Suite du dernier paquet du sous-programme srcsrpy .

paquets de continuation srcsrpy

Les réponses des sous-systèmes aux demandes SRC sont effectuées sous la forme de paquets de continuation. Deux types de paquets de continuation peuvent être spécifiés: les messages d'information et les paquets de réponse.

Le message d'information n'est pas renvoyé au client. Au lieu de cela, il est imprimé dans la sortie standard du client. Le message doit être constitué de texte NLS, avec des jetons de message remplis par le sous-système d'envoi. Pour envoyer ce type de paquet de continuation, indiquez SUITE dans le paramètre Suite de la sous-routine srcsrpy .

Remarque: L'action du sous-système STOP n'autorise aucune continuation. Toutefois, toutes les autres demandes d'action reçues par le sous-système à partir du code SRC peuvent recevoir un message d'information.

Le paquet de réponse est renvoyé au client pour traitement ultérieur. Par conséquent, le paquet doit être accepté par le sous-système et le demandeur. Un exemple de ce type de continuation est une demande de statut. Lorsque vous répondez à des demandes de statut de sous-système, spécifiez STATCONTINU dans le paramètre srcsrpy Suite . Lorsque la génération de rapports d'état est terminée ou que tous les paquets de réponse définis par le sous-système ont été envoyés, indiquez END dans le paramètre srcsrpy Suite . Le paquet est ensuite transmis au client pour indiquer la fin de la réponse.

Sous-systèmes de programmation renvoyant des paquets d'erreur SRC

Les sous-systèmes doivent renvoyer des paquets d'erreur pour les erreurs SRC et non-SRC.

Lors du renvoi d'une erreur SRC, le paquet de réponse renvoyé par le sous-système doit être sous la forme de la structure svrreply de la structure srcrep , avecobjnamezone remplie avec le nom de sous-système, le type de sous-serveur ou l'objet de sous-serveur erroné. Si le message NLS associé au numéro d'erreur SRC n'inclut aucun jeton, le paquet d'erreur est renvoyé sous forme abrégée. Cela signifie que le paquet d'erreur contient uniquement le numéro d'erreur SRC. Toutefois, si des jetons sont associés au numéro d'erreur, le texte de message NLS standard du catalogue de messages doit être renvoyé.

Lors du renvoi d'une erreur non-SRC, le paquet de réponse doit être une structure svrreply avec lertncodezone définie sur la constante SRC_SUBMSG et la valeurrtnmsgdéfini sur un message NLS spécifique au sous-système. :NONE.rtnmsgest imprimé dans la sortie standard du client.

Réponse aux demandes de trace

La prise en charge des commandes traceson et tracesoff dépend du sous-système. Si vous choisissez de prendre en charge ces commandes, des actions de trace peuvent être spécifiées pour les sous-systèmes et les sous-serveurs.

Les demandes de trace de sous-système se présentent sous la forme suivante: une demande de trace de sous-système aura la sous-demande actiondéfini sur la constante TRACE et sur la subreq objectdéfini sur la constante SUBSYSTEM. L'action de trace utiliseparm1pour indiquer la trace LONGTRACE ou SHORTTRACE, etparm2pour indiquer TRACEON ou TRACEOFF.

Lorsque le sous-système reçoit un paquet de sous-système de trace avecparm1défini sur SHORTTRACE etparm2défini sur TRACEON, le sous-système doit activer le traçage court. Inversement, lorsque le sous-système reçoit un paquet de sous-système de trace avecparm1définir sur LONGTRACE etparm2défini sur TRACEON, le sous-système doit activer la fonction de trace longue. Lorsque le sous-système reçoit un paquet de sous-système de trace avecparm2défini sur TRACEOFF, le sous-système doit désactiver la fonction de trace du sous-système.

Les demandes de trace de sous-serveur se présentent sous la forme suivante: la demande de trace de sous-serveur aura la valeur subreq actiondéfini sur la constante TRACE et sur la subreq objectdéfini sur le point de code de sous-serveur du sous-serveur sur lequel envoyer le statut. L'action de trace utiliseparm1pour indiquer LONGTRACE ou SHORTTRACE, etparm2pour indiquer TRACEON ou TRACEOFF.

Lorsque le sous-système reçoit un paquet de sous-serveur de trace avecparm1défini sur SHORTTRACE etparm2défini sur TRACEON, le sous-système doit activer la fonction de trace abrégée du sous-serveur. Inversement, lorsque le sous-système reçoit un paquet de sous-serveur de trace avecparm1définir sur LONGTRACE etparm2défini sur TRACEON, le sous-système doit activer la fonction de trace longue du sous-serveur. Lorsque le sous-système reçoit un paquet de sous-serveur de trace avecparm2défini sur TRACEOFF, le sous-système doit désactiver la fonction de trace du sous-serveur.

Réponse aux demandes d'actualisation

La prise en charge des demandes d'actualisation de sous-système dépend du sous-système. Les programmeurs de sous-système qui choisissent de prendre en charge la commande refresh doivent programmer leurs sous-systèmes pour interagir avec le code SRC de la manière suivante:

• Une demande d'actualisation de sous-système aura la structure subreqactionzone définie sur la constante REFRESH et la structure subreqobjectdéfini sur la constante SUBSYSTEM. L'action d'actualisation du sous-système n'utilise pasparm1ouparm2.
• Lorsque le sous-système reçoit la demande d'actualisation, il doit se reconfigurer lui-même.