Objetivo

Este documento tem como objetivo relatar a funcionalidade de agendamento de tarefas no produto Logix, que realiza a execução de processos em modo background (sem a interação com o usuário), onde são executados em datas e intervalos definidos pelo usuário.

Os processos acionados pelo agendador são chamados de gatilhos e cada um possui tarefas a serem executadas pelo mesmo. Tais gatilhos são cadastrados através do programa JOB0003 – Agendador de Tarefas e o monitoramento da execução destes pode ser feito através do programa JOB0005 – Monitor de Tarefas.

1. Funcionamento

Uma vez iniciado o serviço TOTVS Tec com o agendador de tarefas ligado, imediatamente é acionado um escalonador (scheduler) que verifica ininterruptamente se há algum gatilho a ser executado conforme período e intervalos definidos pelo usuário. Estes gatilhos são executados em uma nova linha de execução (thread), para não interferir nos gatilhos que ainda estão executando.

2. Pré-requisitos

Para executar o agendador de tarefas Logix, é necessário a utilização da tecnologia TOTVS Tec e estar no mínimo com a versão 10.02 do Logix. Esta ferramenta trabalha nos servidores e banco de dados homologados pela TOTVS. 

É extremamente aconselhável criar um ambiente TOTVS Tec separado dos outros ambientes para execução do agendador de tarefas.

JOB0003 – Agendador de Tarefas Logix (Cadastro de Gatilhos)

No JOB0003 são cadastrados os gatilhos a serem executados pelo agendador de tarefas do Logix e suas especificações. Este programa é subdividido em quatro partes:

• Informações do gatilho;
• Especificação de execução;
• Tarefas;
• Informações de atualizações.

Nas informações do gatilho, são cadastradas informações básicas como: nome e descrição do gatilho, responsável pelo gatilho, e-mail do responsável e quando o sistema deverá enviar e-mails para o responsável.

Na especificação de execução, são informados o período e os intervalos de execução do gatilho. Também é possível verificar a situação do gatilho, se o mesmo está pendente para execução, em andamento ou inativo (lembrando que para que um gatilho possa ser modificado, o mesmo não pode estar em andamento).

Os períodos de execução são informados através do campo de data inicial e final e os intervalos são definidos por hora, minuto, dia, dia da semana e mês. Estas informações são 

selecionadas a partir da janela abaixo, ao clicar no botão de lupa do respectivo campo do qual o usuário deseja informar:

No cadastro das tarefas, são informadas as tarefas (processos) que serão executadas para este gatilho e possibilita também as definições de:

• Rotina;
• Observações;
• Dependentes: define se a execução da tarefa depende do término com sucesso da tarefa executada anteriormente;
• Parâmetros (simples e lista): os parâmetros simples aceitam apenas um valor e as listas aceitam diversos valores, seqüenciados conforme são adicionados na mesma.

Estes parâmetros são informados na tela abaixo:

O nome da rotina e os parâmetros das tarefas são informações técnicas que podem ser vistas com mais detalhes no item Desenvolvimento deste documento. Para finalizar, o JOB0003 indica para o usuário quando foi a inclusão do gatilho, quando foi a última alteração e qual o usuário efetuou esta alteração.

JOB0005 – Monitor de Tarefas Logix

O JOB0005 permite que sejam monitorados os gatilhos e tarefas que estão em execução, além de possibilitar a interrupção de um ou todos os gatilhos que estão em execução no momento. É possível também, visualizar o histórico de execução de todos os gatilhos cadastrados e verificar se os mesmos foram executados com sucesso ou se houve algum problema durante a execução do mesmo.

3. Configuração

Depois de cadastrados os gatilhos é necessário configurar o agendador de tarefas para a execução dos mesmos. Esta configuração consiste na criação de seções de execução dentro do arquivo de informações do servidor de aplicação (TotvsAppServer.ini) localizado dentro da pasta do servidor TOTVS Tec. As seções que deverão ser incluídas, bem como suas chaves e valores de execução, deverão estar como a seguir:

Caso seja utilizado LoadBalance para o agendador de tarefas, é possível utilizar os mesmos servidores escravos dos outros servidores de aplicação TOTVS Tec.

¹ Para questões de otimização de recursos de infra-estrutura, recomenda-se utilizar o conceito de LoadBalance para distribuição de carga entre servidores Totvstec, que podem estar no mesma máquina ou em máquinas diferentes. Este conceito utiliza-se do paradigma mestreescravo onde será criado um “servidor mestre” que irá usufruir dos recursos de seus “servidores escravos”. Neste caso, o servidor mestre distribui os processos entre os servidores escravos.

Para cada servidor de aplicação é necessário ter uma cópia do diretório appserver. Assim, sugere-se a seguinte estrutura de diretórios para o LoadBalance:

• c:\totvs\logix\bin\
• appserver0  servidor master
• appserver1  servidor slave 1
• appserver2  servidor slave 2
• appserverN  servidor slave N

Nota: Mais detalhes sobre a configuração de LOAD BALANCE, vide manual de instalação TOTVS Tec.

4. Desenvolvimento

Para que seja possível um programa do Logix ser executado através do agendador de tarefas, o mesmo deve ser adaptado conforme os padrões de desenvolvimento para os programas de execução no agendador de tarefas:

1. O processo definido na tarefa do gatilho deve ser desenvolvido no 4GL com a palavra _job após o nome da função e esta deve sempre receber como parâmetro o nome da rotina (mesmo que não informada no cadastro);
2. O parâmetro “rotina” possibilita a definição de várias rotinas JOB em um único arquivo de programa;
3. A função JOB deverá obrigatoriamente retornar uma situação, sendo o zero indicador que não houve erros ou diferente de zero caso tenha ocorrido algum erro. Esse retorno define o que será gravado no registro de execução, se o gatilho foi executado com sucesso ou não;
4. Caso tenha a necessidade de utilizar o usuário ou empresa para processamento do programa JOB, estes devem ser cadastrados como parâmetro para a tarefa e a função JOB deve ser preparada para receber estes parâmetros;
5. Os parâmetros informados para o processo devem ser recuperados dentro da função JOB através da função JOB_get_parametro_gatilho_tarefa;
6. O LOG0010 não fará retorno destes parâmetros quando executado via JOB, apenas fará a conexão com o banco de dados e a carga das variáveis de ambiente.

DATABASE logix 
   
 GLOBALS 
     DEFINE p_user        LIKE usuarios.cod_usuario 
     DEFINE p_cod_empresa LIKE empresa.cod_empresa 
 END GLOBALS 
 

#------------------------------# 
 FUNCTION sssnnnn_job(l_rotina) 
#------------------------------# 
  DEFINE l_rotina      CHAR(20)
  DEFINE l_cod_empresa LIKE empresa.cod_empresa
  DEFINE l_parametro2  CHAR(50)
  DEFINE l_parametro3  CHAR(50)
  DEFINE l_parametro4  CHAR(50)

  IF LOG_initAPP("[CHAVE_SISTEMA_LOGIX]") > 0 THEN 
     RETURN 1
  END IF

  CASE l_rotina #Idenficador registrado no campo ROTINA da tarefa registrada no cadastro do gatilho (JOB0003)
  WHEN "[NOME_ROTINA_AGENDADOR 1]"
     #BUSCA PARÂMETRO 1 DA TAREFA (Código da empresa) >>> Sempre enviar o código da empresa para qual deve registrar o processamento, caso houver necessidade de processamento para alguma empresa específica.
     CALL JOB_get_parametro_gatilho_tarefa(1,0) RETURNING status, l_cod_empresa
     IF l_cod_empresa IS NULL OR l_cod_empresa = " "   THEN
        CALL LOG_consoleError("Parâmetro 1 (Código da empresa) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     #Quando empresa é recebida como parâmetro no gatilho JOB, deve-se acionar
     #a função abaixo para garantir que todo processamento a partir deste ponto
     #considere esta empresa para processamento, seja para a rotina atual ou até 
     #para demais aplicações executadas. 
     #OBS: Não setar fixo o valor da variável global P_COD_EMPRESA pois existem muitas 
     #funcionalidades do framework que não utilizam mais esta variável como referência
     #para obter o valor do código da empresa corrente para execução.
     CALL JOB_setCompany(l_cod_empresa)

     #BUSCA PARÂMETRO 2 DA TAREFA (Descrição do parâmetro 2)
     CALL JOB_get_parametro_gatilho_tarefa(2,0) RETURNING status, l_parametro
     IF l_parametro IS NULL OR l_parametro = " "  THEN
        CALL LOG_consoleError("Parâmetro 2 (????) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     CALL sssnnnn_processamento_rotina01()

  WHEN "[NOME_ROTINA_AGENDADOR 2]" ## (OPCIONAL - CASO EXISTAM MAIS ROTINAS PREVISTAS PARA AGENDADOR NO MESMO FONTE 4GL)

     #BUSCA PARÂMETRO 1 DA TAREFA (Código da empresa)
     CALL JOB_get_parametro_gatilho_tarefa(1,0) RETURNING status, l_cod_empresa
     IF l_cod_empresa IS NULL OR l_cod_empresa = " "   THEN
        CALL LOG_consoleError("Parâmetro 1 (Código da empresa) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     #Quando empresa é recebida como parâmetro no gatilho JOB, deve-se acionar
     #a função abaixo para garantir que todo processamento a partir deste ponto
     #considere esta empresa para processamento, seja para a rotina atual ou até 
     #para demais aplicações executadas. 
     #OBS: Não setar fixo o valor da variável global P_COD_EMPRESA pois existem muitas 
     #funcionalidades do framework que não utilizam mais esta variável como referência
     #para obter o valor do código da empresa corrente para execução.
     CALL JOB_setCompany(l_cod_empresa)

     #BUSCA PARÂMETRO 2 DA TAREFA (Descrição do parâmetro 2)
     CALL JOB_get_parametro_gatilho_tarefa(2,0) RETURNING status, l_parametro2
     IF l_parametro2IS NULL OR l_parametro2 = " "  THEN
        CALL LOG_consoleError("Parâmetro 2 (????) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     #BUSCA PARÂMETRO 3 DA TAREFA (Descrição do parâmetro 3)
     CALL JOB_get_parametro_gatilho_tarefa(3,0) RETURNING status, l_parametro3
     IF l_parametro3 IS NULL OR l_parametro3 = " "  THEN
        CALL LOG_consoleError("Parâmetro 3 (????) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     #BUSCA PARÂMETRO 4 DA TAREFA (Descrição do parâmetro 4)
     CALL JOB_get_parametro_gatilho_tarefa(4,0) RETURNING status, l_parametro4
     IF l_parametro4IS NULL OR l_parametro4 = " "  THEN
        CALL LOG_consoleError("Parâmetro 4 (????) não repassado para a tarefa agendada.")
        RETURN 1
     END IF

     CALL sssnnnn_processamento_rotina02()

  END CASE

  RETURN 0  ###Gatilho executado com sucesso
 END FUNCTION