Manual SURPAC

Manual SURPAC

SCL & TCL

Setembro de 2005

Obs: Criar links para as palavras sublinhadas

Autor: Welenn Cássio Mota Araújo

Email: welenn.araujo@geoexplore.com.br

Índice

1
 Manual SURPAC

1 SCL 2

1.1 SCL – Visão Geral 2

1.2 SCL Perguntas Frequentemente Respondidas (FAQs) 2
1.3 Guia de Conversão CMD para SCL 4

1 SCL
1.1 SCL – Visão Geral
A SURPAC Command Language (SCL) substitui a antiga Macro Language
que era incluída nos produtos da SURPAC Software International
previamente na versão 4.0.

SCL é baseada na Tool Command Language (TCL) e inclui um número de

extensões para torná-la especialmente compatível às exigências dos
usuários de produtos da SSI.

The following links will be useful in learning and using TCL and the
SCL extensions to TCL:

1. TCL Syntax
2. A tutorial on TCL & SCL
3. SCL extensions to TCL
4. Conversion guide from Macros to SCL
5. Frequently Asked Questions about SCL
6. Complete TCL reference manual

1.2 SCL Perguntas Frequentemente Respondidas

(FAQs)

O que é TCL?
TCL é referente à Tool Command Language. Referência
http://www.scriptics.com site central para maiores informações.

O que é SCL e por que migrar pra isto?

SCL é a nova SURPAC Command Language que é intergrada na
família da SSI de produtos de software posteriormente a versão 4.0.

2
 Manual SURPAC

SCL irá substituir a velha SURPAC macro language command futuramente.

SCL é fundamentalmente uma extensão à linguagem script TCL e
consequentemente irá fornecer aos usuários SURPAC o poder desenvolver
scripts em TCL específicos para o SURPAC.

Quais extensões da SCL estarão disponíveis?

SCL irá suportar todas as funcionalidades atualmente disponíveis na
velha macro command language do SURPAC tanto implicitamente pelos
comandos TCL sublinhados our por extensões SCL específicas. O Playback
os scripts de ambas SCL e macro command language serão suportados,
mas será possível gravar macros apenas na nova SCL. Usuários serão
encorajados a migrar suas macros existentes para a nova linguagem assim
eles se beneficiarão da nova funcionalidade.

O que é TK?
Tk é um Toolkit (kit de ferramentas) TCL que fornece uma interface
com o X Windows e interfaces toolkit Microsoft Windows (dependendo da
plataforma naturalmente). Referência http://www.scriptics.com para maiores
informações.

O TK toolkit será suportado no SURPAC Vision?

O Tk Toolkit não é incluso na SCL. Mesmo assim qualquer
desenvolvimento de scripts necessitando da capacidade GUI (Graphical User
Interface) irá usar o módulo SURPAC Graphical User Interface Desing
Objects (Guido).

Terá uma ferramenta debugadora disponível?

O TCL ProDebugger será suportado, porém o TCLPro não estará
incluído. O TCL ProDebugger e outras soluções TCL comerciais podem ser
adquiridas do Scriptics WWW site. O TCLPro debugger foi testado com SCL e
foi provado ser um dae (dispositivo automático de entrada) valioso em
eliminar erros de scripts complexos.

O que é TCLPro e isto será incluído na distribuição do SURPAC ?

O TCLPro não será incluído na distribuição do SURPAC Vision neste
estágio. TCLPro é um ambiente de desenvolvimento fornece ferramentas
integradas tais como debugador, compilador, checador de script, extensões
e interpretadores implementados.

3
 Manual SURPAC

A velha macro command language será suportada?

Será suportado rodar a velha SURPAC macro command language,
mas será possível apenas gravar macros na nova SCL.

1.3 Guia de Conversão CMD para SCL

Macro
SCL/TCL Equivalente Detalhes de implementação Exemplos
Característica
_MACRO_STATUS Retorno de valores de Todo comando de extensão SCL if {[SclRangeExpand range
comandos SCL retorna um valor para indicar o status "1,10,1"] == $SCL_OK} {
de conclusão do comando. O status puts "Range expanded
de conclusão pode ser atribuído a OK"
qualquer variável usando o comando } else {
set. puts "Range expansion
failed range =
$SCL_UNDEFINED_HANDLE"
Alguns valores especiais são }
definidos pela SCL por unset range
conveniência dos autores dos
scripts SCL.

Esses valores são:

SCL_OK
O comando foi completado
com sucesso.
SCL_ERROR
O comando foi concluído com
algum tipo de erro
condicional.
SCL_UNDEFINED_HANDLE
O comando retorna o
parâmetro a uma variável-
objeto que é passada por
referência. Por alguma razão
o comando falhou. Quando
isto ocorre, a variável que se
esperava receber o
parâmetro do objeto será
atribuído o valor de
$SCL_UNDEFINED_HANDL
E desta forma um teste
apropriado pode ser realizado
se necessário.

4
 Manual SURPAC

# # O caractere # é padrão para # Tudo que é

comentários em TCL. procedido do # é um
comentário.
puts "Comentário ao
O caractere # é apenas significante final da linha de
como um comentário se isto comentário"; #
ocorrer onde o interpretador TCL
estiver esperando o início de um
novo comando.

Comentários são comumente

encontrados com o caractere # no
início de uma nova linha.

Comentários podem ser incluídos

no final de um comando usando o
caractere ; para terminar um
comando.
Veja o exemplo.
\ \ Como ultimo caractere na linha o \ for {set i 0} \
serve como um caractere de {i < 10} \
continuação de linha para permitir {incr i} \
comandos em linhas múltiplas como {puts "i = $i"}
um dae (dispositivo automático de
entrada) como formatação do script.

O caractere in TCL também serve

como caractere de escape (fim)
para permitir caracteres especiais
para serem definidos. Detalhes de
características de caracteres
especiais de escape \ podem ser
econtrados here.

5
 Manual SURPAC

Variáveis Variáveis Nomes de variáveis em TCL set i 0

nomeDaVariável, nomeDaVariável, precisam começar com uma letra e
@(nomeDaVariável) $nomeDaVariável podem consistir de qualquer número
de letras, caracteres ou sobrescritas.
Espaços não são permitidos nos
nomes de variáveis.
Arrays (vetores) são permitidos e
são e denotados por um nome de
variável e um índice de vetor entre
parênteses ().
puts $i
set names(1) "John Smith"
set names(2) "Mary Smith"
puts "names1=$names(1),
names2=$names(2)"
set name(first) "John" set name(last)
"Smith" puts "First
name=$name(first), Last
name=$name(last)"

Os valores de variáveis são

obtidos prefixando o nome da
variável pela operação substituta
de variável, $.

Nome de variáveis, são case

sensitive (identificador de
maiúscula e minúscula).
@assign set Comando TCL criador. set variável 5
set variável "to this value"

Variáveis são criadas em TCL

usando o comando set . Até que a
variável seja criada (setada) isto
não existe.
@unassign unset Comando TCL criador. unset variável

Variáveis são dispostas usando o

comando unset .

Quando a variável é referente a um

objeto SCL (dtm ou arquivo string
que foi carregado usando
comandos da extensão SCL)
unsetando a variável fará com o
objeto seja removido da memória.

6
 Manual SURPAC

@function SclFunction nome_daFunção Descrição do comando. set status [ SclFunction

parâmetros_daFunção "CREATE DTM" {
frm00126={
O commando SCLFunction é {
usado para executar funções no _action="display"
software que são normalmente location="gol"
acessadas escolhendo um item do id="1"
menu, por exemplo, CREATE swadesc="Y"
break="Y"
DTM ou RECALL FILE. anyspots="N"
brktest="Y"
O commando SCLFunction exige
um argumento imperativo, o nome check_distance="0.005"
}
da função que está sendo chamada.
}
Opcionalmente a SCLFunction }]
pode ter um corpo que contém
uma lista de pares nome = valor
que definem parâmetros para
aquela função.

Os parâmetros _action, _error,

_missing and _pause podem ser
usados para controle de
comportamento de formulários
que são exigidos quando a função
é executada. Note que estes
parâmetros NÃO são gravados
com os scripts como
comportamento padrão, para
cada um destes parâmetros é
apropriado para a maioria dos
casos.

Autores experientes de scripts

acharão estes parâmetros úteis
para habilitar comportamentos
particulares em circunstâncias nas
quais formulários podem falhar em

7
 Manual SURPAC

vários critérios de validação e

você será capaz de dar controle
interativo ao usuário para realizar
correções aos parâmetros do
formulário.

@form Não há equivalente em TCL. O comando de extensão SclFunction

Inclui detalhes para todos os
parâmetros necessários por uma
função sem qualquer referência aos
formulários que estão sendo usados
para entrada de parâmetros da
função. Consequentemente não há
necessidade de um comando
equivalente para SCL.
@macro package Característica TCL interna. Create a package from files in
pkg_mkIndex the temp directory
proc pkg_mkIndex c:/temp/*.tcl
c:\temp\SsiMain.tcl
A velha linguagem macro permitia package require
que macros chamassem outras SsiPackage
macros para auxiliar num SayHelloWorld
desenvolvimento de soluções mais c:\temp\SsiPackage.tcl
complexa. Cada macro existia em package provide
SsiPackage 1.0
seu próprio arquivo .cmd. proc SayHelloWorld {} {
puts "HELLO
TCL fornece procedimentos para WORLD"
este fim. Procedimentos precisam }
existir num mesmo script ao Chamando precedimentos e
modificando argumentos para
menos se forem definidos num retorno de valores do
pacote de bibliotecas para permitir procedimento
que eles possam ser usados por Isto funciona passando nomes de
outro arquivo script. argumentos ao invest de valores e
usando upvar para acessar as
variáveis no frame de chamada de
A velha linguagem macro permitia empilhamento.
a passagem por argumentos à sample.tcl
outras macros mas não permitia o proc changevars {arg1name
retorno de valores das macros arg2name} {
upvar $arg1name x
chamadas. upvar $arg2name y
set x [expr $x + 1]

8
 Manual SURPAC

set y [expr $y + 2]
}
TCL permite o retorno de valores set a 1
por alguns ou todos os argumentos set b 2
a um procedimento. Isto é set status [externproc a
conseguido usando o comando b]
upvar. puts "a is now $a, b is
now $b"
a is now 2, b is now 3

Procedure Example

proc sum_proc {a b} {
return [expr $a + $b]
}
proc magnitude {num} {
if {$num > 0} {
return $num
}
set num [expr $num *
(-1)]
return $num
}
set num1 12
set num2 14
set sum [sum_proc $num1
$num2]
puts "The sum is $sum"
puts "The magnitude of 3
is [magnitude 3]"
puts "The magnitude of -2
is [magnitude -2]"

Output:
The sum is 26
The magnitude of 3 is 3
The magnitude of -2 is 2
@pause SclPause período Comando de extensão. SclPause 5

Pausar a aplicação por um

períodos de segundos se o período
for definido ou até o
pressionamento de uma tecla do
teclado se o período não for
definido.
@message puts Comando interno TCL. puts "Hello World!"

Exibe a messagem na tela de

mensagens usada pela classe de
mensagens Report. O

9
 Manual SURPAC

comportamento normal do puts é

alterado se nenhum canal explícito
de saída for definido e a
mensagem é direcionada à janela
de logs de mensagens do
SURPAC.
@alert SclBeep Mensagem Opcional Comando de extensão. SclBeep "Condição de erro
encontrada"
SclBeep irá um toque simples de
campainha e também exibirá o
texto, se isto estiver presente, da
Mensagem Opcional na janela de
mensagens.
@return return Comando TCL interno. return 0
return $var
Causa um retorno imediato do
procedimento que executa
atualmente e retorna um valor ao
procedimento da chamada.
@menu SclCreateGuido guido_object Comandos de extensão. An SCL script that uses a Guido
@var_prompt $script user interface
@var_default Os macros velhos usam somente o #setCriar um objeto Guido
@gui_str status
$guido_object SclRunGuido @menu gravar os menus indicados [ SclCreateGuido
@gui_file
@gui_str(simple_for durante a execução macro. guido_object "inputs.tcl"
m …) $guido_object Realmente não servem a nenhuma ]
@gui_str(dialog_form SclSetGuidoValue $name finalidade real aparte de mostrar if { $status == $SCL_OK }
…) $value {
os menus que mudam durante o # Inicializar o
playback. objeto Guido
$guido_object $guido_object
SclGetGuidoValue $name Graphical User Interface Design SclSetGuidoValue
value Objects, Guido, é o componente "location" "topo"
$guido_object
de sistema que é usado para SclSetGudioValue "id" "1"
unset guido_object construção de uma interia interface $guido_object
de usuário. Guido é desenvolvido SclSetGuidoValue
também em TCL e por este motivo "breaklines" "Y"
é muito fácil graver Guido sscripts Guido# Executar o objeto
que contém componentes de set status
interface de usuário para [ $guido_object
SCL/TCL scripts. SclRunGuido ]
if { $status ==
$SCL_OK } {
Todos os commandos de interface # Examine the
com o usuário na velha linguagem guido object after it has
macro são consequentemente returned

10
Manual SURPAC

$guido_object
SclGetGuidoValue
substituídos por um aagrpamento "location" location
de commandos para crier e $guido_object
executar objetos Guido através de SclGetGuidoValue "id" id
SCL. $guido_object
SclGetGuidoValue
"breaklines" breaklines
}
# Clean up - this
destroys the Guido object
unset guido_object
}

The Guido user interface script -

inputs.tcl

GuidoForm inputs {
-default_buttons
-label "User Interface
Example"
-layout BoxLayout
Y_AXIS
-tip "Help that is
displayed with the
pointer over the form"
GuidoPanel panel1 {
-border etched true
-label "User inputs"
-layout
CentreLineLayout
GuidoFileBrowserField
location {
-display_length 26
-file_mask *.dtm
-link id
-label Location
-max_length 252
-tip "select the
file to be processed"
}
GuidoField id {
-display_length 16
-format real_8
-label "ID number"
-max_length 16
}
GuidoCheckBox
breaklines {
-default true
-font_style bold
-label "Breaklines
"
-selected_value Y
11
 Manual SURPAC

-unselected_value N
-tip "Tick the
checkbox to use
breaklines"
}
}
}

@while while Comando TCL interno set x 0

@endwhile while {$x<10} {
puts "x is $x"
O exemplo mostra um simples uso incr x
do comando while. }

Parênteses {} são usados como

delimitadores para a parte
condicional do while e para o
corpo da declaração do while.
@range SclRangeExpand handle Comando de extensão. set status
@endrange range_expression [SclRangeExpand handle
"1,16,2"]
Fornece uma iteração para um if {$handle ==
SclRangeGet $handle $item intervalo SSI. A expressão do SCL_UNDEFINED_HANDLE} {
value intervalo pode ser qualquer puts "Undefined range
intervalo SSI válido incluindo um handle"
SclRangeGetCount $handle arquivo de intervalo cujo nome é } else {
# Loop through the
precedido pelo símbolo @. range
SclRangeIncludes $handle set count
$value epsilon [ SclRangeGetCount
$handle ]
for { set i 0 } { $i
< $count } { incr i } {
set status
[ SclRangeGet $handle $i
value ]
if {$status ==
$SCL_OK} {
# Do some
processing with $value
} else {
puts "Error
getting range value"
break
}

12
 Manual SURPAC

}
# destroy the range
object by unsetting the
handle variable
unset handle
}
@goto N/A Não há equivalente em TCL.
@label
Práticas de Programação estruturada
while, for, if, switch, etc, são
necessárias para lidar com
execuções condicionais do código
para scripts TCL/SCL.

@if if {expr} { Comando TCL interno set temp 95

@elseif } elseif {expr} { if {$temp < 80} {
@else } else { puts "It's a little
}
If, elseif, else e switch fornecem chilly."
@endif
switch diferentes métodos de códigos de } else {
execução condicionais. O switch é puts "Warm enough for
um meio melhor para lidar com me."
um grande número de alternativas }
set num_legs 4
do que a repetição de comandos switch $num_legs {
elseif. 2 {puts "It could be a
human."}
4 {puts "It could be a
cow."}
6 {puts "It could be an
ant."}
8 {puts "It could be a
spider."}
default {puts "It could
be anything."}
}
@isset info exists Comando TCL interno. info exists varname.

Retorna 1 se a variável de nome The info command may be used for a

requisitada existir, ou 0 caso variety of other purposes also.
contrário.

13
 Manual SURPAC

@(0), @(1), etc. Automatically created argv O argumento posicional passado por
variable. referência da velha macro é ainda 1.3.1.2 Passing arguments
suportado na TCL/SCL mesmo que o form MACRO
argumento seja de certa forma PLAYBACK example
diferente. The script sample below exists in
the file a.tcl. It invokes the script
Quando usada a função MACRO b.tcl and passes the 10 optional
parameters to b.tcl through the
PLAYBACK para chamar um automatically created argv
script TCL com máximo 10 variable.
argumentos opcionais passados
por referência para o script TCL
para ser executado. Isto é feito
criando uma variável TCL do tipo set status [ SclFunction
lista argv que contém uma entrada "MACRO PLAYBACK" {
frm00197={
para cada valor que é inserido nos {
campos do formulário da função
MACRO PLAYBACK. continue_on_error="N"
slow_motion="N"
macro_name="b.tcl"
arg1="This input
came via arg1"
1.3.1.1 Procedimentos com arg2="This input
tamanho de variáveis came via arg2"
do tipo lista arg3="This input
came via arg3"
arg4="This input
Se necessário o tamanho da variável came via arg4"
de argumento tipo lista pode ser arg5="This input
suportado fazendo o último came via arg5"
parâmetro formal num procedimento arg6="This input
de argumento do tipo lista args. came via arg6"
arg7="This input
Isto resulta numa variável came via arg7"
chamada args estando disponível arg8="This input
came via arg8"
para o procedimento. Esta variável arg9="This input
contém uma list de valores do came via arg9"
argumento opcional e os valores arg10="This input
deste argumentos podem ser came via arg10"
obtidos através do uso das funções }
}
de processamento de lista da TCL. }]

Llength para pegar o número de The script sample below exists in the
argumentos de uma lista file b.tcl. It shows how the optional
Lindex para pegar um item da lista arguments are passed to the argv list
foreach para interagir com cada variable and how each value can be
obtained.
elemento da lista
for {set i 0} {$i <
[llength $argv]} {incr i}

14
 Manual SURPAC

{
puts "argument
$i=[lindex $argv $i]"
}

1.3.1.3 Variable length

argument list example
proc testproc {arg1 arg2
args} {
puts "arg1=$arg1"
puts "arg2=$arg2"

set numargs [llength

$args]
if {numargs > 0} {
puts "$numargs
optional arguments to the
procedure"
set count 1
foreach optarg $args
{
puts "Optional
argument #$1=$optarg"
incr count
}
} else {
puts "No optional
arguments to the
procedure"
}
}

gui_digitise SclDigitise "prompt string" Comando de extensão set status [ SclDigitise

xvarname yvarname zvarname "Digitise a location on
Exibe um prompt para instruir o the z ]
graphics window" x y
usuário a usar o mouse para digitar if { $status == $SCL_OK }
15
 Manual SURPAC

{
puts "x = $x, y = $y, z
uma posição (location) na = $z"
viewport 2D ou 3D. } else {
puts "Status = $status"
The digitise event may be }
generated in any 2D or 3D
graphics window. The digitise
request may be cancelled by
pressing the Escape key. If no 2D
or 3D graphics windows presently
exist then the only valid action is
to cancel the digitise request by
pressing Escape.

The digitised location is returned

in variables whose names are
passed as arguments to the
command.

The function returns SCL_OK on

success and SCL_ERROR for
failure.

All commands that permit graphic

selections, unless otherwise stated,
behave the same in that they return
SCL_OK for success and
SCL_ERROR for failure. Values
are returned by passing the names
of the variables to which digitised
or selected values are assigned.

gui_rect_center_corn SclDragRectCentreCorner Extension command. set status

16
 Manual SURPAC

er "prompt text" x1 y1 z1 x2 y2 z2 [SclDragRectCenterCorner

gui_drag_rect_center Prompt the user to use the mouse "prompt text" x1 y1 z1 x2 y2 z2]
_corner
to click and drag to define a
rectangle on the screen by defining
its centre point and the point
where the mouse is released.

x1,y1,z1 are returned with the

coordinates where the mouse
button is depressed

x2, y2, z2 are returned with the

coordinates where the mouse
button is released.
Gui_rect_corner_corn SclDragRectCornerCorner Extension command. set status
er $prompt x1 y1 z1 x2 y2 z2 [SclDragRectCornerCorner
Gui_drag_rect_corner Prompt the user to use the mouse "prompt text" x1 y1 z1 x2 y2 z2]
_corner
to click and drag to define a
rectangle on the screen by defining
its two corners.

x1,y1,z1 are returned with the

coordinates of the corner where
the mouse button is depressed.

x2, y2, z2 are returned with the

coordinates of the corner where
the mouse button is released.
Gui_line SclDragLine $prompt x1 y1 z1 Extension command. set status [SclDragLine "prompt
Gui_drag_line x2 y2 z2 text" x1 y1 z1 x2 y2 z2]
Prompt the user to use the mouse
to define a line on the screen and
return the coordinates of the two
ends of the line

Gui_drag_string SclDragString string_handle Extension commands. set string [SclDragString "prompt

17
 Manual SURPAC

Gui_drag_segment $prompt delx dely delz text" delx dely delz]

Gui_drag_point Prompt the user to select and drag set segment [SclDragSegment
SclDragSegment "Prompt text" delx dely delz]
a string, segment or point from its set point [SclDragPoint "Prompt
segment_handle $prompt current location to a new location. text" delx dely delz]
delx dely delz
Note that the string, segment or
SclDragPoint point_handle point is not changed.
$prompt delx dely delz
The purpose of the function is to
display feedback of the drag
operation and to return the
displacement defined by the drag
operation.

The handle of the selected string,

segment or point is returned in the
string/segment/point_handle
variable.
Gui_drag_string_Con SclDragStringConstrained Extension commands. set string
strained string_handle $prompt [SclDragStringConstrained
Gui_drag_segment_ $constraint delx dely delz Prompt the user to select and drag "prompt text" $constraint delx dely
Constrained delz]
Gui_drag_point_Cons SclDragSegmentConstrained a string, segment or point from its
trained current location to a new location set segment
segment_handle $prompt and constrain the movement to be [SclDragSegmentConstrained
$constraint delx dely delz in a particular direction or plane. "Prompt text" $constraint delx dely
delz]
SclDragPointConstrained Note that the string, segment or
point_handle $prompt point is not changed. set point [SclDragPointConstrained
$constraint delx dely delz "Prompt text" $constraint delx dely
delz]
The purpose of the function is to
display feedback of the drag
operation and to return the
displacement defined by the drag
operation.

The handle of the selected string,

segment or point is returned in the
string/segment/point_handle
variable.

The constraint defines the number

of degrees of freedom in the drag
operation. Permitted values are
any combination of the letters X,

18
 Manual SURPAC

Y and Z.

XYZ = 3 degrees of freedom

XY = 2 degrees of freedom and
movement in the XY plane only,
etc.

File_access file exists Inbuilt Tcl command set status [file exists filename]

Returns 1 if the file exists, 0

otherwise
FILE_OPEN open Inbuilt Tcl command set file [open newfile.abc w]

Returns a handle to the file for use

in read, puts, gets and close
commands.
File_readline gets Inbult Tcl commands. gets $file inline
File_writeline read puts $file outline
puts Read and write from/to a file
previously opened using open.
eof eof Inbuilt tcl command set filestate [eof $file]

Returns 1 if the last gets command

resulted in an end of file condition,
0 otherwise
file_close close Inbuilt tcl command close $file

Closes currently open file.

19
 Manual SURPAC

expr SclExpr "arithmetic expression" Extension command & inbuilt SclExpr "1 + 2"
command. SclExpr "cosd(90)"

The Tcl interpreter includes an

expression evaluation command
expr, that does a lot of what the
expr command implemented in the
existing macro system does at
present.

It does not however do everything

that the expr command in the old
macro language did. Consequently
the SclExpr command has been
created to emulate this older expr
command.

The SclExpr command accepts

one argument. This is the
expression that is to be evaluated
and must be delimited by "
characters.

20