debugger.md

TDS: Depuração e execução

Requisitos

• servidor/ambiente conectado
• usuário autenticado (se requerido)
• executor configurado

Recomenda-se que pastas e arquivos não contenham caracteres especiais e/ou acentuados e sempre em mínusculas de forma a manter a compatibilidade entre os diversos sistemas operacionais suportados pelo TDS-VSCode e seus componentes. Leia [Convenção para nomenclatura de File System em ambiente Linux]https://tdn.totvs.com/x/h8BICw).

Recomendações

• NUNCA faça depuração em ambiente de produção.
• NÃO utilize o SIGAMDI nem o SIGAADV para realizar uma depuração, utilize diretamente os módulos.
• Não use appServers compartilhado com terceiros, mesmo que ambientes distintos.
• Prefira sempre um ambiente local durante a depuração.
• Clientes TCloud: Os ambientes que estão no TCloud em produção são bloqueados, por padrão, para depuração. Promova o RPO para DEV e use esse ambiente, e se necessário, promova-o de volta para produção. Para detalhes, entre em contato com o suporte do TCloud.

Por quê não depurar em "produção"?

O processo de depuração, é composto de várias partes que se comunicam entre si e muitas vezes, aguardando ações dos usuários (continua, próxima passo, ...).

Quando estamos em uma depuração, pode ocorrer do VS-Code solicitar uma informação ao appServer e este "congela" todas as threads (conexões/usuário) para atender essa solicitação. Essa "congelada" pode levar até um ou mesmo dois segundos e isso acontece toda vez que o usuário que esta depurando, precisa tomar uma ação (continua, próximo passo...) e isso pode ser sentido por todos os usuários. Além disso o próprio usuário que esta depurando, vai receber informações de cada um dos usuários conectados, gerando uma troca constante de programas fontes ou informações irrelevantes naquele momento.

O appServer também envia para o VS-Code algumas informações, tais como, "olha estou nesse fonte e nessa linha" e pergunta "O quê quer que eu faça?". Nesse ponto, pode ser necessário o usuário que está depurando, responda com acionamento de uma ação, como por exemplo, "vá para a próxima instrução" ou "execute esta função até terminar". Enquanto o appServer aguarda a resposta do VS-Code, TODAS as threads ficam congeladas. E você foi no banheiro naquele momento. Dentro de alguns minutos terá um enxurrada de reclamações que o servidor travou.

Isso pode acontecer se tiver um, dez, cem, mil, usuários. Imagina o problema. Cresce exponencialmente ao número de usuários.>

Outra razão, é que devido ao processo de depuração do appServer, normalmente é necessário que o processo de depuração seja o primeiro a ser inicializados, pois somente as threads iniciadas após eles que serão passíveis de depuração e para garantir isso, é comum encerrar na "força" todas as threads no ar, principalmente se a depuração for em jobs, schedulers, rest, e outros do tipo.

Espero ter esclarecido porquê não deve usar ambiente "produção" em processos de depuração.

Configuração de executores

Recomendamos a leitura Debugging.

Por utilizar o SmartClient para iniciar o processo de depuração no Application Server é necessário que o Sistema Operacional onde o tds-vscode está sendo executado, esteja na lista de plataformas homologadas paro o SmartClient conforme Sistemas operacionais homologados - SmartClient.

Criando um executor com assistente

Acione o atalho CTRL + SHIFT + P e execute TOTVS: Configure Launchers que lhe apresentará um assistente de configuração de executores que permite criar uma nova configuração ou editar uma já existente. Preencha as informações solicitadas e acione Save.

Observação: A seleção do Smartclient no MacOS não é suportada. Veja em Smartclient MacOS como configurar manualmente um executor do Smartclient para o MacOS.

Criando um executor manualmente

A definição de executores encontra-se no arquivo .vscode/launch.json que, normalmente, é criado através na abertura da página de Boas Vindas. Caso isso não ocorra (devido a configurações do seu ambiente), você pode criá-lo manualmente executando:

• Na barra de atividades, acione o Debug
• Na barra de ferramentas (parte superior) da visão de Debug, abra a lista de seleção e acione Add Configuration....
• Comece a digitar TOTVS e selecione o tipo desejado
  • totvs_language_debug, para usar SmartClient Desktop (padrão)
  • totvs_language_web_debug, para usar SmartClient Html
• Preencha os atributos solicitados conforme seu ambiente
• Salve o arquivo

Exemplos de configuração

TOTVS Language Debug (padrão)

{
  "version": "0.2.0",
  "configurations": [
    {
    "type": "totvs_language_debug",
    "request": "launch",
    "name": "TOTVS Language Debug",
    "program": "${command:AskForProgramName}",
    "cwb": "${workspaceFolder}",
    "smartclientBin": "c:/totvs12/bin/smartclient/smartclient.exe",
    "isMultiSession": true,
    "enableTableSync": true
    }
  ]
}

TOTVS Language Web Debug (HTML)

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "totvs_language_web_debug",
      "request": "launch",
      "name": "TOTVS Language Debug",
      "program": "${command:AskForProgramName}",
      "cwb": "${workspaceFolder}",
      "smartclientUrl": "http://localhost:8080",
      "isMultiSession": true,
      "enableTableSync": true
    }
  ]
}

No caso de efetuar uma depuração via SmartClient Html, é necessário informar qual o navegador web será utilizado. Configure o caminho completo do navegador web através das preferências de usuário, clicando em Arquivo > Preferências > Configurações e procure por Web: Navigator. Note que existem duas seções distintas, a de Usuário e a de Workspace. Aconselhamos a utilizar as configurações de Usuário que será utilizada por todas as Workspaces do usuário. Caso seja necessária uma configuração específica e diferente em uma Workspace, configure na seção Workspace e neste caso apenas esta Workspace será afetada.

Caso queira modificar o comportamento do navegador no momento da sua inicialização, você pode informar uma lista de argumentos que serão passados para o navegador via linha de comandos. Por exemplo, para forçar a abertura de uma nova janela no FireFox, informe na lista Web: Navigator Arguments com o valor ["-new-window"]. Para maiores detalhes, consulte a documentação do seu navegador.

Navegador
Firefox
Chromium
Edge Não oficial

Páginas acessadas em Maio/2024.

| Devido a uma limitação na execução do navegador Safari por linha de comando, este navegador não é suportado para depuração via SmartClient HTML.

SmartClient MacOS

A configuração do parâmetro smartclientBin para o MacOS deve seguir o exemplo a seguir.

Variáveis de substituição

| Veja Variable substitution.

Os executores do TDS-VSCode, além da variáveis de substituição do VS-Code, permite o uso de:

Variável	Uso/Função
${command:AskForProgramName}	Solicita qual o programa a ser executado

Ao utilizar ${command:AskForProgramName} na configuração do executor, lhe será solicitado qual o prorama ou função a ser executada, com ou sem parâmetros.

user function u_myFunc(p1, p2, p3)
  // processamento conforme parâmetros
  ...
return

Exemplos	Parâmetros
u_myFunc	p1=nil, p2=nil, p3=nil
u_myFunc()	p1=nil, p2=nil, p3=nil
u_myFunc("A")	p1="A", p2=nil, p3=nil
u_myFunc("A",,3)	p1="A", p2="", p3="3"
u_myFunc("A",.t.,3)	p1="A", p2=".t.", p3="3"

| A passagem de parâmetros equivale a usar o argumento -a do SmartClient.

Execução

Acione o atalho CTRL + F5 para iniciar a execução e informe o nome da função/programa a ser executado, se solicitado.

Veja Variáveis de substituição.

Depuração

Acione o atalho F5 para iniciar a depuração e informe o nome da função/programa a ser executada, se solicitado.

Veja Debuggimg Actions e Variáveis de substituição.

É possível verificar valores de variáveis, conteúdo de tabelas e executar métodos/funções durante o processo de depuração.

• Coloque um ponto de parada onde achar necessário
• Quando a depuração parar no ponto indicado, abra a visão Debug Console
• Digite uma operação ou variável AdvPL/4GL disponível em seu ambiente de depuração
• Para ver conteúdo de uma tabela, digite table:nome_da_tabela, por exemplo table:SM0

Usando Console de Depuração

Veja Debug Console REPL.

Sincronismo de tabelas durante a depuração

O sincronismo de tabelas pode ser alterado por configuração no executor, usando a chave enableTableSync. Por padrão, vem habilitado.

Também é possível alterar essa opção durante o processo de depuração acionando o atalho CTRL + SHIFT + P, executando TOTVS: Toggle table sync. Note que ao usar esse comando, o parâmetro do executor é alterado, portanto na próxima depuração irá utilizar essa definição.

Depuração HTML (webapp)

Ao iniciarmos uma depuração através de uma configuração 'totvs_language_web_debug' o processo é praticamente o mesmo de uma depuração normal.

A diferença será que ao invés de abrir o Smartclient desktop, será aberta a URL do webapp configurado no launcher no navegador configurado no settings.

O restante será basicamente o mesmo, respeitando os pontos de paradas e exibindo as informações fornecidas pelo appServer.

Depuração de serviços (jobs)

| A principal característica de um serviço, é que a sua execução não esta diretamente relacionada a interface com o usuário (SmartClient) e normalmente, é executado em segundo plano pelo appServer.

Preparação para serviços REST

1. No arquivo de configuração do appServer (ini), comente a sessão [OnStart].
2. Ainda no arquivo de configuração do appServer, na sessão [General] e ajuste a chave BUILDKILLUSERS=1.
3. Reinicie a execução do appServer.
4. Abra o arquivo .vscode\launch.json.
5. Localize a definição de executor que será utilizada e adicione a chave "enableMultiThread": true.
6. Crie um arquivo-fonte e adicione o código abaixo, adequando-o se necessário.

user function startRest()
  //O nome do job REST e ambiente de execução dele, podem ser obtidos no arquivo
  //de configuração do _appServer_.
  //Detalhes da função em https://tdn.totvs.com/display/tec/StartJob
  startjob("HTTP_START", "p12", .f.) //lwait, sempre dever ser false
  sleep(15000) //aguarda o serviço ser inicializado. Ajuste o tempo se necessário.
  alert(">> Serviço REST inicializado. <<")
return

Preparação para outros serviços

1. No arquivo de configuração do appServer (ini), na sessão [OnStart] deixe ativo somente os serviços necessários na depuração e na chave RefreshRate, informe o intervalo de 30 segundos.
2. Ainda no arquivo de configuração do appServer, na sessão [General], ajuste a chave BUILDKILLUSERS=1.
3. Reinicie a execução do appServer.
4. Abra o arquivo .vscode\launch.json.
5. Localize a definição de executor que será utilizada e adicione a chave "enableMultiThread": true;

Execução da Depuração

1. Encerre todos os serviços e conexões. Dica: Compilar qualquer fonte, encerra todos os serviços e conexões existentes.
2. Coloque um ponto de parada que será executado quando o serviço for requisitado.
3. Iniciar a depuração executando qualquer função do RPO para que mantenha uma conxão do depurador com o appServer. Se serviço REST, execute a função u_startRest e aguarde a mensagem de serviço inicializado.
4. Acione o serviço por fora do VS-CODE, por exemplo executando o SmartClient, uma requisição (http, rest, etc)
5. Quando a depuração parar no ponto de parada, prossiga com a depuração normalmente.

Depuração de PO UI

| Existe uma particularidade encontrada nas novas rotinas de PO UI. Elas rodam em um processo diferente do executado inicialmente, então ao depurar estes processos, precisamos realizar uma pequena configuração, caso não esteja ativada ainda.

Preparação para rotinas PO UI

1. Abra o arquivo .vscode\launch.json.
2. Localize a definição de executor que será utilizada e adicione a chave "enableMultiThread": true.
3. Quando a depuração parar no ponto de parada, prossiga com a depuração normalmente.

Funcionalidades estendidas de depuração

Por padrão, as funcionalidades estendidas estão desligadas. Para ligá-las, adicionar na configuração do lançador de depuração a chave extend.Features, ligando as funcionalidades que deseja ativar.

Algo semelhante a:

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "totvs_language_debug",
			"request": "launch",

      ...

      "extendFeatures": {
				"charDetails": true
			}
		}
	],

...

}

Funcionalidade estendida: charDetails

Quando desligada (padrão) a depuração de tipos char (string), não apresenta alteração e e ativada, passa a apresentar detalhes sobre a variável/campo, mudando a forma de visualização.

Desligada	Ligada

Variáveis do tipo string (character), podem conter dados nos formatos CP1252/CP1251 ou UTF8, que podem ser diferenciadas pelo prefixo UTF8 em seus valores nas visões Variables e Watches e ao passar o mouse sobre a variável.

Na imagem acima, <variável> esta com conteúdo CP1252 (padrão AdvPL) e <variável2>, o conteúdo é UTF8. Ao expandir a <variável>, você obterá mais detalhes.

Onde:

Raw	É o dado bruto (como armazenado na memória do Protheus).
Length	É o tamanho da string do dado bruto.
<variável> (ASCII)	Sequencia byte a byte da string, apresentando o caractere ASCII, seu código em hexadecimal e seu código decimal.

Ao utilizar o console de debug (REPL) para entrada de expressões, esta será tratada para apresentar da mesma forma. Lembre-se que o padrão é CP1252/CP1251.

Caso queira informar conteúdo em UTF-8, deverá usar a função encodeUTF8.

Ao comparar variáveis com conteúdo em formato diferente, sempre resultará em .F. (veja a sequencia de bytes).

Outras operações com strings terão comportamento diferente se o conteúdo for UTF8.