Escrita de um procedimento de migração específica.

princípios de base

No momento da validação do dossier

• cada tabela de fluxo está renomeado (por defeito em fazendo o seu nome pela letra U). Afeta-se o código de atividade MIG (o que permite de os identificar no momento da supressão final das tabelas temporárias, uma vez que a migração terá sido validada)
• o seu conteúdo está bem entendido guardado ao idêntico de fluxo de origem.
• Os seus índices são suprimidas (com exceção do primeiro de entre eles e eventualmete de um índice suplementar que será útil para acelerar o tratamento de migração).
• uma ou das novas tabelas de fluxo são criadas vazias conforme ao dicionário da nova versão (em integrando bem entendido os campos específicos ou as modificações específicas de campos standard feitas sobre a tabela de origem). Frequentemente, a tabela vazia leva o mesmo nome que a tabela de origem, mas não é forçosamente o caso (esta tabela pode não exsitir mais na nova versão, por exemplo porque os dados que eles contém foram transferidos numa nova tabela).

É possível de gerir as migrações de tabelas específicas com o mesmo mecanismo. Este está descrito no parágrafo a seguir.

O sub-programa seguinte permite de conhecer o nome da tabela taç que foi renomeada :
     # FOLDER = código do dossier
     # PTABLE = nome da tabela de movimento antes migração
     # MTABLE = nome da tabela de movimento renomeado
     # Si ERR>0  : um erro apareceu (o tratamento deverá se parar)
Call MIGTABNAME(FOLDER,PTABLE, MTABLE, ERR) From TRTMIG

A regra de base de uma renomeação (mas ela tem exceções, nomeadamente se o nome da tabela excede 12 caracteres) consiste a renomear a tabela XXX em a préfixando por um "U". Assim. uma tabela nomeada ZMYTABLE será renomeada em UZMYTABLE. O ponto de entrada TABNAME em TRTMIG permite de afetar MTABLE em conhecimento PTABLE com uma regra eventualmente diferente.

Cada procedimento unitário está definido por um programa migrando uma ou várias tabelas da base. Este trataemnto deve chamar UUMGSPExxxnn, xxx sendo uma raíz identificando a tabela a migrar e nn sendo duas cifras (para permitir de dispor se necessário de vários tratamentos). O su princípio de funcionamento é o seguinte :

• Vai ler a ou as tabelas de origem (em encontrando o seu nome graças ao sub-programa acima), mas não o atualizar.
• Deve escrever nas tabelas finais, os dados modificados, completados ou transcodificados. Estas tabelas finais foram descritas no dicionário da nova versão. Existem, mas são reputadas ser vazias ao onício da migração.
• Não é mais "unitário" possível, afim de permitir, quando é possível, uma decomposição da migração em procedimentos paralelizados.

Afim de obter as melhores performances possíveis :

• a tabela final está entregue na partida, e ela está indecada a minima (um único índice). Os outros índices serão criados no fim do procedimeto unitário.
• permiter-se-á realizar o tratamento parcial das informações de partida (por exemplo em não emigrando que os 2 últimos exercícios), e permitindo o tratamento posterior dos dados não migrados
• a escrita nesta tabela se fará de preferêcia em modo agrupado (em utilizando as sintaxes Writeb), em fazendo Commit sobre a tabela a cada pacote de N registos (N sendo fixada a um valor razoável) .
• o rasto de mogração será atualizado de maneira otimizada

Afim de permitir uma retoma e uma interrupção fácil dos procedimentos unitários :

• escrever-se-á numa tabela dedicada, a cada Commit, um apontador indicando quais são os dados já tratados, assim que as informações complementares.
• testar-se-á cada Commit, se um pedido de interrupção foi feito.
• escrever-se-á o procedimento de tal maneira que ela possa ser reexecutada em repartindo as tabelas destino vazias.

Descriação do tratamento de migração

No tratamento de migração, encontrar-se-á os elementos seguintes :

• No início, as linhas permitem de desencadear direto do procedimento.
• Um sub-programa RAZ_UUMGSPExxxnn que servirá a remeter à situação inicial afim de poder relançar o procedimento.
• Um sub-programa MAJ_UUMGSPExxxnn contendo o procedimento de migração.
• Um sub-programa PATCH.
• Um sub-programa UTI_MOUL.

Estes sub-programas são decritos a seguir.

Supor-se-á nos exemplos dados que o tratamento UUMGTRTZMY01 corresponde à fase de migração unitária de uma tabela única, que se chama ZMYTABLE. A fase preliminar de revalidação de dossier faz as escolhas seguintes :

• ela renomeou ZMYTABLE conforme a regra definida a seguir (a tabela substitui com os valores antes migração se chama por defeito UZMYTABLE).
• Ela criou a nova tabela ZMYTABLE com a nova estrutura, mas esta tabela está vazia.

O procedimento da migração vai-se anexar a preencher a tabela ZMYTABLE a partir das informações da tabela UZMYTABLE.

As linhas preliminares

As linhas preliminares permitem de lançar o tratamento directamente depois o editor, pela função Execução. Encontramos normalmete as linhas seguintes :

# Definição do dossier corrente, e leitura da tabela dos dossiers
Local Char FOLDER(30) : FOLDER = nomap
# Nome do procedimento de migração
Local Char PROG(20) : PROG="UUMGTRTZMY01"
If !GSERVEUR
  Call SAIDOS(FOLDER,"") From SAIDOS
Endif
If FOLDER<> ""
  If clalev([F:ADS])=0  : Local File ADOSSIER [ADS] : Endif
  Read [ADS] DOSSIER=[L]FOLDER : If fstat : Raz [F:ADS] : Endif
  # Abertura do rasto e afixação de uma janela de temporização
  If !GSERVEUR
    Call TEMPON("O") From GESECRAN
    Call OUVRE_TRACE(PROG) From LECFIC
  Endif
  # Lançamento do procedimento
  Call MAJ_UUMGSPEZMA00(FOLDER)
  # Fecho rasto
  If !GSERVEUR
    Call TEMPOFF     From GESECRAN
    Call FERME_TRACE From LECFIC
    Call LEC_TRACE From LECFIC
  Endif
Endif
End

O sub-programa de colocação a zero

O sub-programa declarado por
Subprog RAZ_UUMGTRTZMY01(FOLDER)
serve a se remeter na situação iincial se necessário, afim de poder relançar o procedimento.

Deve seguir ao mínimo as etapas de base seguintes :

• Verificar que as tabelas de origem e de destino existem bem, por exemplo com as linhas seguintes :
        # Encontrar a tabela de origem para a tabela a preencher (ici UZMYTABLE)
        Call MIGTABNAME(FOLDER,"ZMYTABLE",OLDTABLE,ERR) From TRTMIG
        If ERR : End : Endif
        # A tabela de origem existe?
        If filinfo(filpath("FIL",OLDTABLE,"fde",[F:ADS]DOSSIER),0)<0
             End
        Endif
• Não fazer rastos que por erros (nenhuma mensagem de avanço ou advertência)
• Esvaziar a ou as tabelas nas quais o porcedimento MAJ insere os dados. Para este facto, dispõe-se do sub-programa seguinte:
        # Esvaziamento brutal e irreversível da tabela ZMYTABLE
        Call MIGTABRAZ(FOLDER,"ZMYTABLE",ERR)
        If ERR : End : Endif
• Se as tabelas comuns a vários tratamentos devem estar parcialmente expurgados, utilizar-se-á as transações clássicas do tipo :
  Trbegin [...] : Delete [...] Where ... : Commit
• Colocar a zero as infromações sobre o fluxo já migrado para esta tabela, pelo sub-programa seguimento :
        # Sem linhas migradas a este instante
        Call MIGRAZKEY(FOLDER,"UUMGTRTZMY01",ERR) From TRTMIG

O sub-programa da atualização.

O sub-programa MAJ_UUMGTRTZMY01, servindo a transcodificar o conteúdo da tabela UZMYTABLE para preencher a tabela ZMYTABLE, deve realizar as tarefas seguintes :

• O nome do procedimento de migração deve estar definido na partida
  Local Char PROG(20) : PROG="UUMGTRTZMY01"
• Colocar-se-á o estatuto do procedimento com o sub-programa seguinte (compreendido se uma condição preliminar torna o lançamento inútil, por exemplo se não a tratar : falta então que o estatuto seja Terminado para que o procedimento seja considerado como feito e que os seguintes possam se encedear). Senão, colocar-se-á o estatuto a Em curso :
        # CURSTAT variável Integergerando o estatuto (menu local 21)
        # Os valores possíveis sendo Espera, Em curso, Terminado...
        # Se o procedimento está lançado, ter-se-á CURSTAT=2
        # Se ela está terminada, utilizar-se-á CURSTAT=3
        # Em caso de erro, falta o posicionar a 7
        # No seguimento, a variável PROG contém o nome do procedimento
        #  (UUMGTRTZMY01 por exemplo)
        Call MIGSTKENDFLG (DOSSIER,PROG,CURSTAT,ERR) From TRTMIG
• Testar-se-á a presença das tabelas e das tabelas anteriores em utilizando o sub-programa MIGTABNAME no instar do que é feito no sub-programa de inicialização. Em caso de erro, não esquecer de atualizar o estatuto da tarefa ao bom valor (7) com o sub-programa MIGSTKENDFLG.
• Abre-se em seguida as tabelas necessárias à migração. A abertura dos limites internos do procedimento de migração se faz por :
  Call MIG_OUVRE From TRTMIG
• Os rastos serão utilizadas com parcimónia (inútil de colocar uma sobre cada linha, vimos as migrações se parar de colocar disco para escrever os rastos). É por outro lado útil de colocar um rasto começando por uma mensagem de tipo "Arranque da fase colocada em dia xxx" assim que uma linha de hora e data com uma mensagem tal que "Início do processo a :". Estes rastos utilizarão os sub-programas seguintes:
  # Linha de rasto se ERR=0, linha de erro senão
  Call ECR_TRACE("message",ERR) From GESECRAN
  #Linha de rasto hora e data
  Call ECR_TIME("message") From DOSSUB

• Afim de melhorar o tempo de inserção nas tabelas, suprimem-se os índices em não deixando que o primeiro ativo em início de procedimento e recriam-se em fim de procedimento, para os sub-programas :
        Call MIGTABINIT(FOLDER,"ZMYTABLE",ERR) From TRTMIG
  Mas tal impõe que o procedimemto seja apenas a trabalhar sobre a tabela no momento onde se executa. Nenhum outro procedimemento não deve ser lido, modificado na tabela durante a execução do procedimento. Se a tabela deve estar acesiso por vários procedimetos, não falta utilizar este sub-programa.

• Encontraremos então a primeira chave a tratar no anel de tratamento. Com efeito, retoma-se a migração após uma interrupção, esta chave não está vazia. Encontrar-se-á pelo sub-programa descrito a seguir :
  
  # TBMKEY(1..NBMKEY) é um quadro dos valores de chaves
  # onde Encontramos ao mínimo os componentes
  # do último valor da chave tratada, mas não se pode re-actrescentar
  # um segmento que poderá indicar o nível de rutura esperada
  # sobre uma chave múltipla. TBMKEY deve estar vazio antes a chamada
         #   Se está vazio ao retorno, nenhum valor de chave corrente existia
         #   (arranca-se então o procedimeto ao início).
         # NBMKEY permite definir o número de valores que se espera
         # NBL e NBUP contam as linhas lidas e atualizadas até
         Call MIGGETKEY (FOLDER,PROG,NBMKEY,TBMKEY,NBL,NBUP,ERR)
         &    From TRTMIG
• Poder-se-á então entrar no anel de leitura da tabela ou das datas de origem e escrita das tabelas de destino. Para razões de performance, é preferivel de banir as ordens de leitura isolados sobre as tabelas e priviligiar as instruções Link, de preferência com os juntos estritos (sintaxe CLE~=... ). Se uma leitura deve estar feita sobre um "pequena" tabela por razões de inicilalização ou de controlo (por "pequeno", entende-se menos de 1000 linhas), é frequente de guardar o conteúdo útil desta tabela nas variáveis em memória antes de começar o anel.
• Afim de evitar os erros ligados à escrita de um muito grande número de linhas, completar-se-á o número de linhas escritas e interromper-se-á o anel todas as N linhas (N podendo ser ficxados a 50.000 por exemplo, pelo intermédio da variável global GMAXUPDTRS).
• Para razões de performance, utilizr-se-á também assim de preferência a instrução Writeb (que foi introduzido a partir do motor em versão 6.4). Esta instrução agrupa as escritas e amelhora as performances, nomeadamente sobre uma arquitetura multi-terceiros. Esta instrução não está utilizável que se relê na tabela num conjunto (ex: releitura para saber se o registo existe já). Ela supõe de fixar o fator de grupagem por uma variável sistema nomeado adxwrb (10 parece um bom valor). Falta então empilhar os valores de chaves escritas para poder restituir o conjunto das chaves em curso em caso de erro (este erro se produz então sobre a instrução Flush e não os Writeb). O sub-programa seguinte pode ser utilizado :
          # Empilhamento das chaves.
          # KEY_ARRAY é um quadro alfanumérico declarado por
          # Local Char KEY_ARRAY(N)(adxwrb)  em início de tratamento
          # (o tamanho N depende do tamanho dos valores de chaves)
          # NUMBER uma variável Shortintindicando o número de chaves empilhadas
          # KEY_VALUE valor desta chave encodificada se a chave está em várias partes
          Call STK (KEY_ARRAY, NUMBER,KEY_VALUE) From TRTMIG
• Em caso de saída de anel (após B anéis, ou porque o tratamento está terminado), far-se-á um Flush sobre a tabela (si Writebestá utilizado) em gerando um eventual erro. Se um erro está produzido, e se adxwrbestá superior a 1, poder-se-á reencontrar as chaves sobre as quais o erro pode se produzir no quadro KEY_ARRAY, sobre os adxwrbprimerios índices : far-se-á um Rollback antes de colocar o procedimento em lista Terminado com erros e de terminar o tratamento.
• Se tudo se está bem passado, atualizar-se-á o número de linhas lidas e atualizadas por chamada seguinte:
       Call MIGSTKKEY (FOLDER,PROG,NBMKEY,TBMKEY,NBL,NBUP,ERR)
       &    From TRTMIG
  Far-se-á em seguida um Commit.
• Podr-se-á em seguida testar se um pedido de paragem foi feita. Se não é o caso, e se todas as linhas não foram tratados, recomecar-se-á um anel sobre N linhas. O teste de paragens se faz pelo sub-programa seguinte :
        # A variável STOP reenvia igual a 0 se um pedido de paragem foi feita
        Call MIGSTKPROGRESS (FOLDER,PROG,STOP,ERR) From TRTMIG
• Se um pedido de paragem foi feito (ou se o tratamento está terminado), far-se-ão as operações seguintes :
        # Indexação da ou das tabelas tratadas
        # (unicamente se MIGTABINIT foi utilizado)
           Call MIGTABEND(FOLDER,"ZMYTABLE",ERR) From TRTMIG
        # Assinalar ao monitor no fim do tratamento
           Call MIGTRTEND(FOLDER,PROG) From TRTMIG
           Call ECR_TIME(PROG+" : Tarefa terminada") From DOSSUB

Poder-se-á em seguida fechar as tabelas e liberar os recusros se se tem, depois parar o sub-programar pela instrução End.

O sub-programa PATCH.

Este sub-prograam permite um lançamento por patch. Deve-se assegurar que a tabela ADOSSIER está aberto, ler o registo correspondente ao dossier a tratar, depois lançar o procedimento de migração. Poderá, por exemplo, estar escrito como segue :

Subprog PATCH(FOLDER)
Value Char FOLDER
# Sem lançamento sobre o dossier supervisor
If FOLDER=GDOSX3 : End : Endif

#Alteração da classe [F:ADS]
If clalev([F:ADS])=0  Local File ADOSSIER [ADS] : Endif
Read [ADS] DOSSIER=FOLDER : If fstat : Raz [F:ADS] : Endif
# Lançamento do procedimento
Call MAJ_UUMGTRTZMY01(FOLDER)
End

Um sub-programa UTI_MOUL.

Este sub-prograam permite um lançamento no momento da validação do dossier. É suficiente similar ao sub-programa PATCH, mas não tem necessidade de se assegurar que a tabela ADOSSIR está aberto, nem de ler o registo correspondente ao dossier a tratar, poisque isto não está assegurado pelo tratamento chamador. A única tarefa é então de lançar o procedimento correspondente. Poderá, por exemplo, estar escrito como segue :

Subprog UTIL_MOUL(FOLDER)
Value Char FOLDER
# Sem lançamento sobre o dossier supervisor
If FOLDER=GDOSX3 : End : Endif

# Lançamento do procedimento
Call MAJ_UUMGTRTZMY01(FOLDER)
End

O ponto de entrada MIGTAB

Se deseja que as tabelas de fluxos específicos sejam gerados pelo tratamento de migração de uma maneira análoga (quer dizer renomeados da mesma maneira no início da validação de dossier, depois criados com a nova estrutura), as etapas seguintes são a fazer :

• Falta utilizar o ponto de entrada MIGTAB para indicar que uma tabela de fluco específico deverá ser tratado da mesma maneira que as tabelas standard na primeira fase (renomeada e supressão dos índices futuros).
• Falta criar no dossier supervisor (ou no dossier de referência se está ou não numa arquitetura a 3 níveis) na descrição das tabelas específicas cuja estrutura altera no mometo de alteração de versão, senão as novas tabelas de fluxo não serão criados vazios com a nova estrutura
• Isto é uma exceção um pouco particular à regra que indica que, normalmente não se cria a tabela específica no dossier supervisor. A razão está simples : temos necessidade de dispor de um dicionário "de referência" neste caso particular. Ou o limite cujo se dispõe, se está numa arquitetura a dois níveis (caso o mais frequente) é aquele do dossier "supervisor" (X3 no caso de Sage X3). É então de referir que estas tabelas específicas criadas no dossier supervisor podem estar destruidos sem pré-aviso se intala uma nova versão do dossier supervisor. Falta considerar que a presença de tabelas específicas em X3 é temporário e que uma salvaguarda da descrição destas tabelas deve existir por outro lado.
• Uma tabela específica podendo ser utilizada para alimetar os campos específicos de uma tabela standard, não é forçosamente necessário de criar uma nova tabela específica no momento da alteração de versão. Nestes casos, renomerar-se-á a tabela específica em utilizando o ponto de entrada MIGTAB, e utilizar-se-á os pontos de entrada nos procedimentos standard ou dos porcedimentos complemetares para fazer as atualizações sem criar de tabela novas no dicionário de chegada.

Se este ponto de entrada não está utilizado, as tabelas específicas, protegidas por um código de atividade específico, não serão absolutamente tocados. Encontrar-mos-á no estado de origem, o que corresponderá frequentemente o que deve ser feito por defeito se a alteração de versão não teve incidência sobre a estrutura das tabelas específicas.

Assim de todo o campo específico apresenta numa tabela de fluxo standard e cujo conteúdo deverá ser transferido ao idêntico não necessita nenhuma precaução particular : os tratamentos standard de migração utilizam as afetações de classes para realizar as cópias de dados.

O nome do tratamento onde se encontra o ponto de entrada MIGTAB depende do software baseado sobre SAFE X3 No caso de Sage X3, este ponto de entrada MIGTAB se encontra no tratamento TRTMIGTABX3.

Acrescentar-se-á neste tratamento das linhas deste tipo:
Call MIGTABTABADD(DOSSIER,"ZMYTABLE","ZMY","index",
&NBTAB,WTABLE,WTABLEJ,WABRJ,WTABIDX,ERR) From TRTMIG

Em sabendo que os nomes de variáveis dadas aqui são para a maior parte fixos :

• DOSSIER é o código do dossier.
• o nome da tabela a migrar dado como exemplo aqui é "ZMYTABLE".
• "ZMY" corresponde à abreviação da tabela de origem após que ela tenha renomeado. Se este valor está vazio, uma abreviação temporária está determinada, sob a forma de U## ou W## é um número.
  Em todos os casos esta abreviação não está utilizada nos tratamentos. Nos procedimentos, utiliza-se uma outra abreviação temporária como [XXXM] onde XXX é a abreviação da tabela migrada.
• NBTAB é a variável contendo o número da tabela de fluxo definidos como devendo ser migrados (cada chamada a TRTMIG incrementa esta variável).
• WTABLE, WTABLEJ, WABRJ, WTABIDX são os quadros contendo o conjunto dos elementos ligados às tabelas de fluxo já declarados.
• ERR reenvia um valor não nulo em caso de erro.

Os pontos de entrada dos tratamentos de migração standard.

Cada procedimente de migração standard dispõe por outro lado de pontos de entrada permitindo interagir com a lógica de troca das tabelas standard. Estes pontos de entrada são os seguintes :

• CRISEL permite de alimentar a variável CRITERESPE para filtrar os dados a tratar. O detalhe do contexto utilizável está definido no anexo descrevendo os procedimetos de migração.
• VERIFSEL permite recalcular as zonas da tabela de origem em curso de leitura durante o tratamento, e eventualmente de excluir um registo que não será então reescrito em coocando ISVALID a 0. O detalhe do contexto utilizável está definido no anexo descrevendo os procedimentos de migração.