Comunicación del subsistema de programación con el SRC

Los mandatos del Controlador de recursos del sistema (SRC) son programas ejecutables que toman opciones de la línea de mandatos.

Una vez verificada la sintaxis del mandato, los mandatos llaman a las subrutinas de tiempo de ejecución SRC para construir un datagrama UDP (User Datagram Protocol) y enviarlo al daemon srcmstr .

Las secciones siguientes proporcionan más información sobre las subrutinas de SRC y cómo las pueden utilizar los subsistemas para comunicarse con el proceso principal de SRC:

Subsistemas de programación para recibir solicitudes de SRC

Las tareas de programación asociadas con las peticiones SRC de recepción varían según el tipo de comunicación especificado para el subsistema. El daemon srcmstr utiliza sockets para recibir solicitudes de trabajo de un proceso de mandatos y construye el socket o cola de mensajes necesarios para reenviar solicitudes de trabajo. Cada subsistema necesita verificar la creación de su socket o cola de mensajes. Lea las secciones siguientes para obtener información sobre las directrices específicas de tipo de comunicación sobre la programación del subsistema para recibir paquetes de solicitud SRC.

Nota: Todos los subsistemas, independientemente del tipo de comunicación, deben definir una rutina de receptor de señal para manejar la solicitud SIGTERM .

Recepción de señales SRC

Los subsistemas que utilizan señales como su tipo de comunicación deben definir una rutina de receptor de señales para capturar las señales SIGNORM y SIGFORCE . El método de captura de señal utilizado depende del subsistema. A continuación se muestran dos ejemplos de los tipos de subrutinas que se pueden utilizar para este fin.

Recepción de paquetes de solicitud SRC utilizando sockets

Utilice las directrices siguientes al programar subsistemas de sockets para recibir paquetes de solicitud SRC:

• Incluya la estructura del subsistema SRC en el código del subsistema especificando el archivo /usr/include/spc.h . Este archivo contiene las estructuras que el subsistema utiliza para responder a los mandatos SRC. Además, el archivo spc.h incluye el archivo srcerrno.h , que no es necesario que se incluya por separado. El archivo srcerrno.h contiene definiciones de código de error para el soporte de daemon.
• Cuando se inicia un subsistema de sockets, el socket en el que el subsistema recibe paquetes de solicitud SRC se establece como descriptor de archivo 0. El subsistema debe verificarlo llamando a la subrutina getsockname , que devuelve la dirección del socket del subsistema. Si el descriptor de archivo 0 no es un socket, el subsistema debe registrar un error y, a continuación, salir. Consulte "Reading Internet Datagrams Example Program" en Communications Programming Concepts para obtener información sobre cómo se puede utilizar la subrutina getsockname para devolver la dirección de un socket de subsistema.
• Si un subsistema sondea más de un socket, utilice la subrutina select para determinar qué socket tiene algo que leer. Consulte "Comprobación del programa de ejemplo de conexiones pendientes" en Conceptos de programación de comunicaciones para obtener más información sobre cómo se puede utilizar la subrutina select para este fin.
• Utilice la subrutina recvfrom para obtener el paquete de solicitud del socket.

  Nota: La dirección de retorno del paquete de respuesta del subsistema está en el paquete de solicitud SRC recibido. Esta dirección no debe confundirse con la dirección que la subrutina recvfrom devuelve como uno de sus parámetros.

  Después de que se complete la subrutina recvfrom y se haya recibido el paquete, utilice la subrutina srcrrqs para devolver un puntero a una estructura srchdr estática. Este puntero contiene la dirección de retorno para la respuesta del subsistema. Esta estructura se sobrescribe cada vez que se llama a la subrutina srcrrqs , por lo que su contenido debe almacenarse en otro lugar si serán necesarios después de la siguiente llamada a la subrutina srcrrqs .

Recepción de paquetes de solicitud SRC utilizando colas de mensajes

Utilice las directrices siguientes al programar subsistemas de cola de mensajes para recibir paquetes de solicitud SRC:

• Incluya la estructura del subsistema SRC en el código del subsistema especificando el archivo /usr/include/spc.h . Este archivo contiene las estructuras que el subsistema utiliza para responder a los mandatos SRC. Además, el archivo spc.h incluye el archivo de inclusión srcerrno.h , que no es necesario que se incluya por separado. El archivo srcerrno.h contiene definiciones de código de error para el soporte de daemon.
• Especifique -DSRCBYQUEUE como opción de compilación. Esto coloca un tipo de mensaje (mtype) como primer campo de la estructura srcreq . Esta estructura debe utilizarse siempre que se reciba un paquete SRC.
• Cuando se haya iniciado el subsistema, utilice la subrutina msgget para verificar que se ha creado una cola de mensajes al iniciar el sistema. El subsistema debe registrar un error y salir si no se ha creado una cola de mensajes.
• Si un subsistema sondea más de una cola de mensajes, utilice la subrutina select para determinar qué cola de mensajes tiene algo que leer. Consulte "Comprobación del programa de ejemplo de conexiones pendientes" en Conceptos de programación de comunicaciones para obtener información sobre cómo se puede utilizar la subrutina select para este fin.
• Utilice la subrutina msgrcv o msgxrcv para obtener el paquete de la cola de mensajes. La dirección de retorno para el paquete de respuesta del subsistema está en el paquete recibido.
• Cuando se completa la subrutina msgrcv o msgxrcv y se ha recibido el paquete, llamar a la subrutina srcrrqs para finalizar el proceso de recepción. La subrutina srcrrqs devuelve un puntero a una estructura srchdr estática que se sobrescribe cada vez que se llama a la subrutina srcrrqs . Este puntero contiene la dirección de retorno para la respuesta del subsistema.

Subsistemas de programación para procesar paquetes de solicitud SRC

Los subsistemas deben ser capaces de procesar solicitudes de detención. Opcionalmente, los subsistemas pueden dar soporte a solicitudes de inicio, estado, rastreo y renovación.

El proceso de paquetes de solicitud implica un proceso de dos pasos:

Lectura de paquetes de solicitud SRC

Los subsistemas reciben los paquetes de solicitud SRC en forma de una estructura srcreq tal como se define en el archivo /usr/include/spc.h . La solicitud de subsistema reside en la estructura subreq de la estructura 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*/

Los 2objectEl campo de la estructura subreq indica el objeto al que se aplica la solicitud. Cuando la solicitud se aplica a un subsistema, elobjectse establece en la constante SUBSYSTEM. De lo contrario, elobjectel campo se establece en el punto de código de subservidor o elobjnamese establece en el PID de subservidor como una serie de caracteres. Es responsabilidad del subsistema determinar el objeto al que se aplica la solicitud.

Los 2actionespecifica la acción solicitada del subsistema. Los subsistemas deben comprender los códigos de acción START, STOP y STATUS. Los códigos de acción TRACE y REFRESH son opcionales.

Los 2parm1yparm2se utilizan de forma diferente en cada una de las acciones.

Las acciones START subserver y REFRESH no utilizan elparm1yparm2.

Respuesta del subsistema de programación a solicitudes de SRC

Las acciones de subsistema adecuadas para la mayoría de solicitudes de SRC se programan cuando el objeto de subsistema se define en el SRC. Las estructuras que utilizan los subsistemas para responder a las solicitudes SRC se definen en el archivo /usr/include/spc.h . Los subsistemas pueden utilizar las siguientes subrutinas de tiempo de ejecución de SRC para cumplir los requisitos de proceso de mandatos:

El proceso de solicitud de estado requiere una combinación de tareas y subrutinas.

Cuando los subsistemas reciben solicitudes que no pueden procesar o que no son válidas, deben enviar un paquete de error con un código de error de SRC_SUBICMD en respuesta a la solicitud desconocida o no válida. SRC reserva los códigos de acción 0-255 para uso interno de SRC. Si el subsistema recibe una solicitud que contiene un código de acción que no es válido, el subsistema debe devolver un código de error de SRC_SUBICMD. Los códigos de acción válidos soportados por SRC se definen en el archivo spc.h . También puede definir códigos de acción específicos del subsistema. Un código de acción no es válido si no está definido por el SRC o el subsistema.

Nota: Los códigos de acción 0-255 están reservados para uso de SRC.

Proceso de solicitudes de estado de SRC

Se puede solicitar a los subsistemas que proporcionen tres tipos de informes de estado: estado de subsistema largo, estado de subservidor corto y estado de subservidor largo.

Nota: El daemon srcmstr realiza la notificación de estado de subsistema corto. Las constantes de valor de código de estado y estado de respuesta para este tipo de informe se definen en el archivo /usr/include/spc.h . La tabla Constantes de valor de estado lista los códigos de valor de estado de respuesta necesarios y sugeridos.

Códigos de valor de estado de respuesta

El mandato lssrc de SRC muestra la información recibida en la salida estándar. La información devuelta por los subsistemas en respuesta a una solicitud de estado largo se deja a la discreción del subsistema. Los subsistemas que poseen subservidores son responsables de realizar el seguimiento y notificar los cambios de estado de los subservidores, si lo desea. Utilice la subrutina srcstathdr para recuperar una cabecera de estado estándar para devolverla al principio de los datos de estado.

Se recomiendan los pasos siguientes en las solicitudes de estado de proceso:

1. Para devolver el estado de un subsistema (corto o largo), asigne una matriz de estructuras statcode más una estructura srchdr . La estructura srchdr debe iniciar el almacenamiento intermedio que está enviando en respuesta a la solicitud de estado. La estructura statcode se define en el archivo /usr/include/spc.h .

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

2. Rellene elobjtypecon la constante SUBSYSTEM para indicar que el estado es para un subsistema, o con un punto de código de subservidor para indicar que el estado es para un subservidor.
3. Rellene elstatuscon una de las constantes de estado de SRC definidas en el archivo spc.h .
4. Rellene elobjtextcon el texto NLS que desea que se visualice como estado. Este campo debe ser una serie terminada en NULL.
5. Rellene elobjnamecon el nombre del subsistema o subservidor para el queobjtextse aplica el campo. Este campo debe ser una serie terminada en NULL.

   Nota: El subsistema y el solicitante pueden aceptar enviar otra información definida por el subsistema de nuevo al solicitante.

Subsistemas de programación para enviar paquetes de respuesta

El paquete que un subsistema devuelve al SRC debe tener el formato de la estructura srcrep tal como se define en el archivo /usr/include/spc.h . La estructura svrreply que forma parte de la estructura srcrep contendrá la respuesta del subsistema:

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*/
};

Utilice la subrutina srcsrpy para devolver un paquete al solicitante.

Creación de una respuesta

Para programar una respuesta de subsistema, utilice el procedimiento siguiente:

1. Rellene el rtncodecon el código de error SRC que se aplica. Utilice SRC_SUBMSG comortncodepara devolver un mensaje NLS específico del subsistema.
2. Rellene elobjtypecon la constante SUBSYSTEM para indicar que la respuesta es para un subsistema, o con el punto de código de subservidor para indicar que la respuesta es para un subservidor.
3. Rellene elobjnamecon el nombre de subsistema, tipo de subservidor u objeto de subservidor que se aplica a la respuesta.
4. Rellene elrtnmsgcon el mensaje NLS específico del subsistema.
5. Teclee la entrada adecuada en el parámetro srcsrpy Continued . Consulte "Paquetes de continuación de srcsrpy" para obtener más información.

   Nota: El último paquete del subsistema siempre debe tener END especificado en el parámetro Continuado en la subrutina srcsrpy .

Paquetes de continuación de srcsrpy

Las respuestas del subsistema a las solicitudes de SRC se realizan en forma de paquetes de continuación. Se pueden especificar dos tipos de paquetes de continuación: Mensaje informativo y paquetes de respuesta.

El mensaje informativo no se devuelve al cliente. En su lugar, se imprime en la salida estándar del cliente. El mensaje debe constar de texto NLS, con señales de mensaje rellenadas por el subsistema emisor. Para enviar este tipo de paquete de continuación, especifique CONTINUOUS en el parámetro Continued de la subrutina srcsrpy .

Nota: La acción del subsistema STOP no permite ningún tipo de continuación. Sin embargo, todas las demás solicitudes de acción recibidas por el subsistema desde el SRC pueden recibir un mensaje informativo.

El paquete de respuesta se devuelve al cliente para su posterior procesamiento. Por lo tanto, el subsistema y el solicitante deben acordar el paquete. Un ejemplo de este tipo de continuación es una solicitud de estado. Al responder a solicitudes de estado de subsistema, especifique STATCONTINUOUS en el parámetro srcsrpy Continued . Cuando se haya completado la notificación de estado, o cuando se hayan enviado todos los paquetes de respuesta definidos por el subsistema, especifique END en el parámetro srcsrpy Continuación . A continuación, el paquete se pasa al cliente para indicar el final de la respuesta.

Subsistemas de programación para devolver paquetes de error SRC

Los subsistemas son necesarios para devolver paquetes de error tanto para errores SRC como para errores no SRC.

Al devolver un error de SRC, el paquete de respuesta que devuelve el subsistema debe tener el formato de la estructura svrreply de la estructura srcrep , con elobjnamecampo rellenado con el nombre de subsistema, tipo de subservidor u objeto de subservidor erróneo. Si el mensaje NLS asociado con el número de error SRC no incluye ninguna señal, el paquete de error se devuelve en formato abreviado. Esto significa que el paquete de error sólo contiene el número de error SRC. Sin embargo, si las señales están asociadas con el número de error, se debe devolver el texto de mensaje NLS estándar del catálogo de mensajes.

Al devolver un error no SRC, el paquete de respuesta debe ser una estructura svrreply con elrtncodecampo establecido en la constante SRC_SUBMSG y elrtnmsgcampo establecido en un mensaje NLS específico del subsistema. Los 2rtnmsgse imprime en la salida estándar del cliente.

Respuesta a solicitudes de rastreo

El soporte para los mandatos traceson y tracesoff depende del subsistema. Si elige dar soporte a estos mandatos, se pueden especificar acciones de rastreo para subsistemas y subservidores.

Las solicitudes de rastreo de subsistema llegarán con el formato siguiente: una solicitud de rastreo de subsistema tendrá la solicitud subreq actioncampo establecido en la constante TRACE y la subreq objectcampo establecido en la constante SUBSYSTEM. La acción de rastreo utilizaparm1para indicar LONGTRACE o SHORTTRACE, yparm2para indicar TRACEON o TRACEOFF.

Cuando el subsistema recibe un paquete de subsistema de rastreo conparm1establecer en SHORTTRACE yparm2Establecido en TRACEON, el subsistema debe activar el rastreo corto. Por el contrario, cuando el subsistema recibe un paquete de subsistema de rastreo conparm1establecer en LONGTRACE yparm2Establecido en TRACEON, el subsistema debe activar el rastreo largo. Cuando el subsistema recibe un paquete de subsistema de rastreo conparm2establecer en TRACEOFF, el subsistema debe desactivar el rastreo del subsistema.

Las solicitudes de rastreo de subservidor llegarán en el formato siguiente: la solicitud de rastreo de subservidor tendrá la solicitud subreq actioncampo establecido en la constante TRACE y la subreq objectcampo establecido en el punto de código de subservidor del subservidor en el que enviar el estado. La acción de rastreo utilizaparm1para indicar LONGTRACE o SHORTTRACE, yparm2para indicar TRACEON o TRACEOFF.

Cuando el subsistema recibe un paquete de subservidor de rastreo conparm1establecer en SHORTTRACE yparm2establecido en TRACEON, el subsistema debe activar el rastreo corto del subservidor. Por el contrario, cuando el subsistema recibe un paquete de subservidor de rastreo conparm1establecer en LONGTRACE yparm2establecido en TRACEON, el subsistema debe activar el rastreo largo del subservidor. Cuando el subsistema recibe un paquete de subservidor de rastreo conparm2establecer en TRACEOFF, el subsistema debe desactivar el rastreo de subservidor.

Respuesta a solicitudes de renovación

El soporte para las solicitudes de renovación del subsistema depende del subsistema. Los programadores de subsistemas que opten por dar soporte al mandato refresh deben programar sus subsistemas para interactuar con el SRC de la siguiente manera:

• Una solicitud de renovación de subsistema tendrá la estructura subreqactioncampo establecido en la constante REFRESH y la estructura subreqobjectcampo establecido en la constante SUBSYSTEM. La acción de renovar subsistema no utilizaparm1oparm2.
• Cuando el subsistema recibe la solicitud de renovación, el subsistema debe reconfigurarse a sí mismo.