Documentação da interface do TinyCobol com tcl/tk. (C) Copyright 2001, 2004 - Rildo Pragana Este software é livre para todos os usos, inclusive em aplicações comerciais. Crédito de autoria é agradecido, mas não explicitamente requerido. O software e a documentação seguem a mesma licença que a linguagem tcl. A única coisa que você não pode fazer, essencialmente, é se declarar autor desse programa. Apesar de ter sido escrito para uso conjunto com o TinyCobol, este programa é disponibilizado separadamente e segue licença diferente do TinyCobol. Changes: 20040513 - adicionada função stcleval para avaliar um comando arbitrário no tcl, retornando o resultado (primeiros 80 chars) (veja ítem 1.d, abaixo) 1. Utilização básica a) Chamar a função "initTcl" antes de qualquer outra, uma só vez. b) Declarar (Cobol) um ítem de grupo contendo todas as variáveis a transferir entre o cobol e o tcl, sendo todos os ítens do grupo com picture X. (*ELIMINADO*)Declarar um contador com o tamanho total desse item de grupo, em caracteres. Finalmente, declarar uma variável contendo o nome do script tcl a ser executado, podendo ser dado o caminho (path) completo, ou somente o nome, se este estiver no diretório corrente. No lugar da variável, podemos entrar diretamente uma string literal, contendo o nome do script seguido de pelo menos um espaço (exemplo: "formA.tcl "). c) executar a chamada à função (definida em C) tcleval, com os seguintes argumentos: variável de grupo com a transferência, e uma variável texto PIC X(64) com o nome do script tcl a ser avaliado, ou literal terminado por espaço (veja acima). 01 DATA-BLOCK. 05 NAME PIC X(40). 05 W-ADDRESS PIC X(50). 05 PHONE PIC X(15). 05 END-PGM PIC X. 05 QUICK-RET PIC X. 77 GUI-01 PIC X(64) VALUE "formA.tcl". CALL "tcleval" USING DATA-BLOCK DATA-BLOCK-SIZE GUI-01 A ordem de carga dos scripts é a seguinte: (i) o script "cobtools" definido internamente no programa C é avaliado; (ii) o script definido pelo usuário é avaliado, mas suas variáveis globais (definidas em cobol_fileds) não são ainda inicializadas. Podemos aguardar essa inicialização adicionando um "trace" na variável "ready", como no exemplo abaixo: (*MODIFICADO*) trace add variable ::ready write check_quickret No lugar do trace acima (que deve ser evitado de agora em diante), podemos definir a proc "cobol_preprocess" que será executado quando todas as variáveis globais forem definidas. Assim, a rotina "check_quickret" será executada logo após definidas todas as variáveis globais. Somente após essa definição, poderemos chamar a função "do_exit", que retorna do tcl para o cobol. Da segunda, terceira, e demais vezes que o mesmo script é chamado, sem uma chamada prévia à função "newGui", não teremos mais interpretações do script definido pelo usuário, mas apenas a chamada da proc "cobol_update", se esta for definida. Após um "call newGui", a função cobol_update não é mais executada, e o novo script (ou o mesmo) passado como argumento na chamada a "tcleval" será reinterpretado. A chamada "newGui" também destroi todos os widgets filhos do toplevel "." (ponto) do tk. d) Opcionalmente, podemos chamar a função "stcleval" para executar um script arbitrário no tcl, retornando o resultado como string. Nesse caso, a variável T-STRING (exemplo abaixo) será uma string terminada pelo caracter NULL (LOW-VALUES ou X"00" em Cobol) e a variável T-RESULT deverá conter pelo menos 80 caracteres, ou haverá estouro de memória. CALL "tcleval" USING T-STRING T-RESULT Essa chamada precisa ser realizada com bastante conhecimento (e responsabilidade) do programador, pois podera deixar o interpretador em um estado instável se um comando errado ou incompleto for passado. Entretanto, ela pode ser útil para fazer certos tipos de testes, ou para passar de maneira bastante rápida atribuições para variáveis ou consultas de seus valores entre o cobol e o tcl. e) Uma sugestão aos programadores Cobol para fazerem testes de programas em tcl, é chamar uma console tkcon (comando "source tkcon") de uma interface GUI normal criada no tctcl. Executando "Attach to Main(tk)" ou Ctrl-3 no tckon, poderemos acessar as variáveis e procedures definidas pelo nosso programa tcl, inclusive as variáveis passadas pelo Cobol. Da mesma forma, outros programas como o tkinspect, etc, podem ser usados com a mesma finalidade. No exemplo estamos chamando o tkcon já instalado no nosso sistema (/usr/local/bin/tkcon). Se o seu estiver em outro lugar, modifique o comando associado ao botão "tkcon", refletindo o local correto. 2. Scripts executados (evaluated) na interface Os tres fragmentos de script abaixo são interpretados (melhor dizendo, "evaluated") nas seguintes situações: cobtools -- antes de carregar o script definido pelo usuário wait_ready -- após carregado o script do usuário, aguardando a chamada da proc do_exit para retornar ao cobol newgui -- na chamada da função C newGui() pelo programa cobol. ########## cobtools set argc 0 set argv {} proc split_fields {} { global data_block cobol_fields result_format set ix 0 set result_format "" foreach {varname size} $cobol_fields { global $varname set $varname [string range $data_block $ix [expr $ix+$size-1]] incr ix $size append result_format "%-$size.${size}s" } } proc do_exit {} { global result_format result ready cobol_fields set vars {} foreach {varname size} $cobol_fields { upvar $varname v lappend vars $v } set result [eval format $result_format $vars] set ready 1 } proc cobol_update {} { } ######### wait_ready split_fields set ready 0 tkwait variable ready ######### newgui foreach child [winfo children .] { destroy $child } 3. Observações As seguintes variáveis globais são reservadas pela interface e não devem ser usadas em scripts: data_block, ready, cobol_fields, result, result_format exceto onde for explicitamente documentado. Dúvidas e sugestões sobre o programa e sua documentação são benvindas. Se alguém quiser traduzir para outras línguas, por gentileze me envie o documento traduzido para eu anexar ao pacote. 4. Windows Windows é uma plataforma cheia de problemas, por isso, siga rigorosamente as seguintes instruções para obter resultados satisfatórios. 1- Instale MinGW/MSYS. 2- Instale ActiveTcl 8.4.4 ou posterior, no diretório default C:/Tcl 3- Execute em um terminal o comando (atenção: barras não não invertidas): export TCL-LIBRARY=C:/Tcl/lib/tcl8.4/ 4- Siga as instruções genéricas para Linux/Unix. Recife, 24 de março de 2004 Rildo Pragana