Comunicação do subsistema de programação com o SRC

Comandos SRC (System Resource Controller) são programas executáveis que levam opções a partir da linha de comando.

Após a verificação da sintaxe do comando, os comandos chamam as sub-rotinas de tempo de execução do SRC para construir um datagrama User Datagram Protocol (UDP) e enviá-lo ao daemon srcmstr.

As seções a seguir fornecem mais informações sobre subroutines SRC e como elas podem ser usadas por subsistemas para se comunicar com o processo principal do SRC:

Programar subsistemas para receber solicitações de SRC

As tarefas de programação associadas ao recebimento de pedidos de SRC variam com o tipo de comunicação especificado para o subsistema. O daemon srcmstr usa sockets para receber solicitações de trabalho de um processo de comando e constrói a fila de socket ou mensagem necessária para encaminhao solicitações de trabalho. Cada subsistema precisa verificar a criação de sua fila de socket ou mensagem. Leia as seções a seguir para obter informações sobre as diretrizes específicas da comunicação sobre a programação do seu subsistema para receber pacotes de solicitação de SRC.

Nota: Todos os subsistemas, independentemente do tipo de comunicação, devem definir uma rotina de catcher de sinal para tratar a solicitação SIGTERM .

Recebendo sinais SRC

Os subsistemas que usam sinais como seu tipo de comunicação devem definir uma rotina de catcher de sinal para capturar os sinais SIGNORM e SIGFORCE . O método de captura de sinal utilizado é dependente do subsistema. A seguir estão dois exemplos dos tipos de subroutines que podem ser utilizados para este fim.

Recebendo pacotes de solicitação de SRC usando sockets

Utilize as seguintes diretrizes ao programar subsistemas de soquetes para receber pacotes de solicitação SRC:

• Inclua a estrutura do subsistema SRC em seu código do subsistema, especificando o arquivo /usr/include/spc.h . Este arquivo contém as estruturas que o subsistema usa para responder aos comandos SRC. Além disso, o arquivo spc.h inclui o arquivo srcerrno.h que não precisa ser incluído separadamente. O arquivo srcerrno.h contém definições de código de erro para o suporte do daemon
• Quando um subsistema de soquetes é iniciado, o soquete no qual o subsistema recebe pacotes de solicitação SRC é configurado como descritor de arquivo 0. O subsistema deve verificar isso chamando o subroutine getsockname , que retorna o endereço do soquete do subsistema. Se o descritor de arquivo 0 não for um socket, o subsistema deverá registrar um erro e, em seguida, sair. Veja "Reading Internet Datagramas Exemplo Program" em Conceitos de Programação de Comunicações para obter informações sobre como a subroutine getsockname pode ser usada para retornar o endereço de um soquete do subsistema.
• Se um subsistema pesquisa mais de um soquete, use a subroutine select para determinar qual soquete tem algo a ler. Veja "Checking for Pending Connections Exemplo Program" em Conceitos de Programação de Comunicações para obter mais informações sobre como a subroutine select pode ser usada para esta finalidade.
• Use a subroutine recvfrom para obter o pacote de solicitação do socket.

  Nota: O endereço de retorno para o pacote de resposta do subsistema está no pacote de solicitação SRC recebido. Este endereço não deve ser confundido com o endereço que a subroutine recvfrom retorna como um de seus parâmetros.

  Após a subroutine recvfrom completar e o pacote ter sido recebido, use o subroutine srcrrqs para retornar um ponteiro para uma estrutura srchdr estática. Este ponteiro contém o endereço de retorno para a resposta do subsistema. Esta estrutura é sobrescrita cada vez que a subroutine srcrrqs é chamada, assim, seu conteúdo deve ser armazenado em outro lugar se eles serão necessários após a próxima chamada para a subroutine srcrrqs .

Recebendo pacotes de solicitação de SRC usando filas de mensagens

Utilize as seguintes diretrizes ao programar subsistemas de fila de mensagens para receber pacotes de solicitação de SRC:

• Include a estrutura do subsistema SRC em seu código do subsistema especificando o arquivo /usr/include/spc.h . Este arquivo contém as estruturas que o subsistema usa para responder aos comandos SRC. Além disso, o arquivo spc.h inclui o arquivo include srcerrno.h , que não precisa ser incluído separadamente. O arquivo srcerrno.h contém definições de código de erro para o suporte do daemon
• Especifique -DSRCBYQUEUE como uma opção de compilação. Isso coloca um tipo de mensagem (mtype) campo como o primeiro campo na estrutura srcreq . Essa estrutura deve ser usada a qualquer momento que um pacote SRC seja recebido.
• Quando o subsistema foi iniciado, use o subroutine msgget para verificar se uma fila de mensagens foi criada na inicialização do sistema. O subsistema deve registrar um erro e sair se uma fila de mensagens não foi criada.
• Se um subsistema pesquisa mais de uma fila de mensagens, use a subroutine select para determinar qual fila de mensagens tem algo a ler. Veja "Checking for Pending Connections Exemplo Program" em Conceitos de Programação de Comunicações para obter informações sobre como a subroutine select pode ser usada para esta finalidade.
• Use o subroutine msgrcv ou msgxrcv para obter o pacote a partir da fila de mensagens. O endereço de retorno para o pacote de resposta do subsistema está no pacotaço recebido.
• Quando a subroutine msgrcv ou msgxrcv é concluída e o pacote foi recebido, chamar a subroutine srcrrqs para terminar o processo de recepção. O subroutine srcrrqs retorna um ponteiro para uma estrutura srchdr estática que é sobrescrita cada vez que a subroutine srcrrqs é chamada. Este ponteiro contém o endereço de retorno para a resposta do subsistema.

Programar subsistemas para processar pacotes de solicitação SRC

Os subsistemas devem ser capazes de processar pedidos de parada. Opcionalmente, os subsistemas podem suportar solicitações de início, status, rastreio e atualização.

Os pacotes de solicitação de processamento envolvem um processo de duas etapas:

Lendo pacotes de solicitação de SRC

Os pacotes de solicitação de SRC são recebidos por subsistemas na forma de uma estrutura srcreq conforme definido no arquivo /usr/include/spc.h . A solicitação do subsistema reside na estrutura subreq da estrutura 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*/

Os comandosobjectcampo da estrutura subreq indica o objeto ao qual a solicitação se aplica. Quando a solicitação se aplica a um subsistema, oobjectcampo é configurado para a constante SUBSISTEMA. Caso contrário, oobjectcampo é configurado para o ponto de código do subservidor ou oobjnamecampo é configurado para o PID do subservidor como uma sequência de caracteres. É de responsabilidade do subsistema determinar o objeto ao qual a solicitação se aplica.

Os comandosactioncampo especifica a ação solicitada ao subsistema. Os subsistemas devem entender os códigos de ação START, STOP e STATUS. Os códigos de ação TRACE e REFRESH são opcionais.

Os comandosparm1eparm2os campos são usados de forma diferente por cada uma das ações.

As ações do subservidor START e REFRESH não utilizam oparm1eparm2Campos.

Programar resposta do subsistema às solicitações de SRC

As ações de subsistema adequadas para a maioria das solicitações de SRC são programadas quando o objeto do subsistema é definido para o SRC. As estruturas que os subsistemas usam para responder às solicitações de SRC são definidas no arquivo /usr/include/spc.h . Os subsistemas podem utilizar os seguintes sub-rotinas de execução de SRC para atender aos requisitos de processamento de comandos:

O processamento de solicitação de status requer uma combinação de tarefas e subroutines.

Quando os subsistemas recebem pedidos eles não podem processar ou que são inválidos, eles devem enviar um pacote de erro com um código de erro de SRC_SUBICMD em resposta ao desconhecido, ou inválido, solicitar. SRC reserva códigos de ação 0-255 para uso interno do SRC. Se o seu subsistema receber uma solicitação contendo um código de ação que não é válido, seu subsistema deverá retornar um código de erro de SRC_SUBICMD. Os códigos de ação válidos suportados pelo SRC são definidos no arquivo spc.h Você também pode definir códigos de ação específicos do subsistema. Um código de ação não é válido se ele não for definido pelo SRC ou seu subsistema.

Nota: Os códigos de ação 0-255 são reservados para uso do SRC.

Solicitações de status SRC

Os subsistemas podem ser solicitados para fornecer três tipos de relatórios de status: status de subsistema longo, status de subservidor curto e status de subservidor longo.

Nota: O relatório de status do subsistema curto é executado pelo daemon srcmstr . Statcode e responder-valor de status constantes para este tipo de relatório são definidos no arquivo /usr/include/spc.h . As listas de tabelas Status Value Constantes exigiram e sugeriram códigos de valor de status de resposta.

Responder códigos de valor de status

O comando SRC lssrc exibe as informações recebidas sobre a saída padrão. As informações retornadas por subsistemas em resposta a uma solicitação de status longo são deixadas para a discrição do subsistema. Os subsistemas que possuem subservidores são responsáveis por acompanhar e relatar as mudanças de estado dos subservidores, se desejados. Use o subroutine srcstathdr para recuperar um cabeçalho de status padrão para repassar no início de seus dados de status.

As seguintes etapas são recomendadas em solicitações de status de processamento:

1. Para retornar status de um subsistema (curto ou longo), alocar uma matriz de estruturas statcode mais uma estrutura srchdr . A estrutura srchdr deve iniciar o buffer que você está enviando em resposta para a solicitação de status. A estrutura statcode é definida no arquivo /usr/include/spc.h .

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

2. Preencha oobjtypecampo com a constante SUBSISTEMA para indicar que o status é para um subsistema, ou com um ponto de código subservidor para indicar que o status é para um subservidor.
3. Preencha ostatuscom uma das constantes de status do SRC definidas no arquivo spc.h
4. Preencha oobjtextcampo com o texto NLS que você deseja exibido como status. Este campo deve ser uma string terminada NULL.
5. Preencha oobjnamecampo com o nome do subsistema ou subservidor para o qual oobjtextcampo se aplica. Este campo deve ser uma string terminada NULL.

   Nota: O subsistema e o solicitante podem concordar em enviar outras informações definidas pelo subsistema de volta para o solicitante.

Programar subsistemas para enviar pacotes de resposta

O pacote que um subsistema retorna para o SRC deve estar na forma da estrutura srcrep conforme definido no arquivo /usr/include/spc.h . A estrutura svrresposta que faz parte da estrutura srcrep conterá a resposta do 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*/
};

Use a subroutinha srcsrpy para retornar um pacote para o solicitante.

Criando uma resposta

Para programar uma resposta do subsistema, utilize o seguinte procedimento:

1. Preencha o rtncodecampo com o código de erro SRC que se aplica. Use SRC_SUBMSG como ortncodecampo para retornar uma mensagem NLS específica do subsistema.
2. Preencha oobjtypecampo com a constante SUBSISTEMA para indicar que a resposta é para um subsistema, ou com o ponto de código do subservidor para indicar que a resposta é para um subservidor.
3. Preencha oobjnamecampo com o nome do subsistema, tipo de subservidor ou objeto subservidor que se aplica à resposta.
4. Preencha ortnmsgcampo com a mensagem NLS específica do subsistema.
5. Chave a entrada apropriada no parâmetro srcsrpy Continued . Consulte "Pacotes de Continuação Srcsrpy" para obter mais informações.

   Nota: O último pacote do subsistema deve sempre ter END especificado no parâmetro Continuação para o subroutine srcsrpy .

pacotes de continuação srcsrpy

As respostas do subsistema às solicitações de SRC são feitas sob a forma de pacotes de continuação. Podem ser especificados dois tipos de pacotes de continuação: Mensagem Informativa e pacotes de resposta.

A mensagem informativa não é repassada para o cliente. Em vez disso, ele é impresso para a saída padrão do cliente. A mensagem deve consistir no texto NLS, com tokens de mensagens preenchidos pelo subsistema de envio. Para enviar este tipo de pacote de continuação, especifique CONTINUOU no parâmetro srcsrpy subroutine Continued .

Nota: A ação do subsistema STOP não permite nenhum tipo de continuação. No entanto, todos os outros pedidos de ação recebidos pelo subsistema a partir da SRC podem ser enviados uma mensagem informativa.

O pacote de resposta é transmitido de volta para o cliente para processamento adicional. Portanto, o pacote deve ser acordado mediante o subsistema e o solicitante. Um exemplo desse tipo de continuação é um pedido de status. Ao responder a solicitações de status do subsistema, especifique STATCONTINUOU no parâmetro srcsrpy Continued . Quando o relatório de status foi concluído, ou todos os pacotes de resposta definidos pelo subsistema foram enviados, especifique END no parâmetro srcsrpy Continued . O pacote é então passado para o cliente para indicar o fim da resposta.

Programar subsistemas para retornar pacotes de erro SRC

Os subsistemas são necessários para retornar pacotes de erro para os erros de SRC e erros não SRC.

Ao retornar um erro do SRC, o pacote de resposta que o subsistema retorna deve estar na forma da estrutura svrresposta da estrutura srcrep , com oobjnamecampo preenchido com o nome do subsistema, tipo de subservidor ou objeto subservidor em erro. Se a mensagem NLS associada ao número de erro do SRC não incluir nenhum tokens, o pacote de erro será retornado em formato curto. Isto significa que o pacote de erro contém o número de erro SRC apenas. No entanto, se tokens estiverem associados ao número de erro, deverá ser retornado o texto padrão da mensagem NLS do catálogo de mensagens.

Ao retornar um erro não SRC, o pacote de resposta deverá ser uma estrutura svrresposta com ortncodecampo configurado para a constante SRC_SUBMSG e ortnmsgcampo configurado para uma mensagem NLS específica do subsistema. Os comandosrtnmsgcampo é impresso para a saída padrão do cliente.

Respondendo a solicitações de rastreio

O suporte para os comandos traceson e tracesoff é dependente de subsistema. Se você optar por suportar esses comandos, as ações de rastreio podem ser especificadas para subsistemas e subservidores.

Os pedidos de rastreio do subsistema chegarão da seguinte forma: Um pedido de rastreio do subsistema terá o subreq actioncampo configurado para a constante TRACE e o subreq objectcampo configurado para a constante SUBSISTEMA. A ação de rastreio usaparm1para indicar o rastreio LONGTRACE ou SHORTTRACE, eparm2para indicar TRACEON ou TRACEOFF.

Quando o subsistema recebe um pacotão de subsistema de rastreio comparm1configurado para SHORTTRACE eparm2configurado para o TRACEON, o subsistema deve ficar curto rastreio em. Inversamente, quando o subsistema recebe um pacote de subsistema de rastreio comparm1configurado para LONGTRACE eparm2configurado para o TRACEON, o subsistema deve ativar o rastreio longo. Quando o subsistema recebe um pacotão de subsistema de rastreio comparm2definido para TRACEOFF, o subsistema deve transformar o rastreio do subsistema.

Os pedidos de rastreio do subservidor chegarão no formulário a seguir: a solicitação de rastreio do subservidor terá o subreq actioncampo configurado para a constante TRACE e o subreq objectcampo configurado para o ponto de código subservidor do subservidor para envio de status. A ação de rastreio usaparm1para indicar LONGTRACE ou SHORTTRACE, eparm2para indicar TRACEON ou TRACEOFF.

Quando o subsistema recebe um pacote de subservidor de rastreio comparm1configurado para SHORTTRACE eparm2configurado para TRACEON, o subsistema deve transformar o rastreio curto do subservidor em. Inversamente, quando o subsistema recebe um pacote de subservidor de rastreio comparm1configurado para LONGTRACE eparm2configurado para TRACEON, o subsistema deve transformar o rastreio de subservidor longo em. Quando o subsistema recebe um pacote de subservidor de rastreio comparm2configurado para TRACEOFF, o subsistema deve transformar o rastreio do subservidor.

Respondendo a solicitações de atualização

O suporte para solicitações de atualização do subsistema é dependente do subsistema. Programadores de subsistema que optam por suportar o comando refresh devem programar seus subsistemas para interagir com o SRC da seguinte maneira:

• Uma solicitação de atualização do subsistema terá a estrutura subreqactioncampo configurado para a constante REFRESH e a estrutura subreqobjectcampo configurado para a constante SUBSISTEMA. A ação do subsistema de atualização não usaparm1ouparm2.
• Quando o subsistema recebe a solicitação de atualização, o subsistema deverá se reconfigurar.