Manual SURPAC

Manual SURPAC
SCL & TCL

Setembro de 2005

Obs: Criar links para as palavras sublinhadas

Autor: Welenn Cssio Mota Arajo

Email: welenn.araujo@geoexplore.com.br

ndice
1

Manual SURPAC
1 SCL

1.1
1.2
1.3

2
2
4

SCL Viso Geral

SCL Perguntas Frequentemente Respondidas (FAQs)
Guia de Converso CMD para SCL

1 SCL
1.1 SCL Viso Geral
A SURPAC Command Language (SCL) substitui a antiga Macro Language
que era includa nos produtos da SURPAC Software International
previamente na verso 4.0.
SCL baseada na Tool Command Language (TCL) e inclui um nmero de
extenses para torn-la especialmente compatvel s exigncias dos
usurios de produtos da SSI.

The following links will be useful in learning and using TCL and the
SCL extensions to TCL:
1.
2.
3.
4.
5.
6.

TCL Syntax
A tutorial on TCL & SCL
SCL extensions to TCL
Conversion guide from Macros to SCL
Frequently Asked Questions about SCL
Complete TCL reference manual

1.2 SCL Perguntas Frequentemente Respondidas

(FAQs)
O que TCL?
TCL referente Tool Command Language. Referncia
http://www.scriptics.com site central para maiores informaes.
O que SCL e por que migrar pra isto?
SCL a nova SURPAC Command Language que intergrada na
famlia da SSI de produtos de software posteriormente a verso 4.0.

Manual SURPAC
SCL ir substituir a velha SURPAC macro language command futuramente.
SCL fundamentalmente uma extenso linguagem script TCL e
consequentemente ir fornecer aos usurios SURPAC o poder desenvolver
scripts em TCL especficos para o SURPAC.
Quais extenses da SCL estaro disponveis?
SCL ir suportar todas as funcionalidades atualmente disponveis na
velha macro command language do SURPAC tanto implicitamente pelos
comandos TCL sublinhados our por extenses SCL especficas. O Playback
os scripts de ambas SCL e macro command language sero suportados,
mas ser possvel gravar macros apenas na nova SCL. Usurios sero
encorajados a migrar suas macros existentes para a nova linguagem assim
eles se beneficiaro 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). Referncia http://www.scriptics.com para maiores

informaes.
O TK toolkit ser suportado no SURPAC Vision?
O Tk Toolkit no incluso na SCL. Mesmo assim qualquer
desenvolvimento de scripts necessitando da capacidade GUI (Graphical User
Interface) ir usar o mdulo SURPAC Graphical User Interface Desing
Objects (Guido).
Ter uma ferramenta debugadora disponvel?
O TCL ProDebugger ser suportado, porm o TCLPro no estar
includo. O TCL ProDebugger e outras solues TCL comerciais podem ser
adquiridas do Scriptics WWW site. O TCLPro debugger foi testado com SCL e
foi provado ser um dae (dispositivo automtico de entrada) valioso em
eliminar erros de scripts complexos.
O que TCLPro e isto ser includo na distribuio do SURPAC ?
O TCLPro no ser includo na distribuio do SURPAC Vision neste
estgio. TCLPro um ambiente de desenvolvimento fornece ferramentas
integradas tais como debugador, compilador, checador de script, extenses
e interpretadores implementados.

Manual SURPAC
A velha macro command language ser suportada?
Ser suportado rodar a velha SURPAC macro command language,
mas ser possvel apenas gravar macros na nova SCL.

1.3 Guia de Converso CMD para SCL

Macro
Caracterstica
_MACRO_STATUS

SCL/TCL Equivalente
Retorno de valores de
comandos SCL

Detalhes de implementao
Todo comando de extenso SCL
retorna um valor para indicar o status
de concluso do comando. O status
de concluso pode ser atribudo a
qualquer varivel usando o comando
set.

Alguns valores especiais so

definidos pela SCL por
convenincia dos autores dos
scripts SCL.

Exemplos
if {[SclRangeExpand range
"1,10,1"] == $SCL_OK} {
puts "Range expanded
OK"
} else {
puts "Range expansion
failed range =
$SCL_UNDEFINED_HANDLE"
}
unset range

Esses valores so:

SCL_OK
O comando foi completado
com sucesso.
SCL_ERROR
O comando foi concludo com
algum tipo de erro
condicional.
SCL_UNDEFINED_HANDLE
O comando retorna o
parmetro a uma varivelobjeto que passada por
referncia. Por alguma razo
o comando falhou. Quando
isto ocorre, a varivel que se
esperava receber o
parmetro do objeto ser
atribudo o valor de
$SCL_UNDEFINED_HANDL
E desta forma um teste
apropriado pode ser realizado
se necessrio.

Manual SURPAC

O caractere # padro para

comentrios em TCL.

O caractere # apenas significante

como um comentrio se isto
ocorrer onde o interpretador TCL
estiver esperando o incio de um
novo comando.

# Tudo que
procedido do # um
comentrio.
puts "Comentrio ao
final da linha de
comentrio"; #

Comentrios so comumente
encontrados com o caractere # no
incio de uma nova linha.
Comentrios podem ser includos
no final de um comando usando o
caractere ; para terminar um
comando.
Veja o exemplo.
\

for {set i 0} \
Como ultimo caractere na linha o \
{i < 10} \
serve como um caractere de
{incr i} \
continuao de linha para permitir
{puts "i = $i"}
comandos em linhas mltiplas como
um dae (dispositivo automtico de
entrada) como formatao do script.

O caractere in TCL tambm serve

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

Manual SURPAC

Variveis
Variveis
nomeDaVarivel,
nomeDaVarivel,
@(nomeDaVarivel) $nomeDaVarivel

Nomes de variveis em TCL

precisam comear com uma letra e
podem consistir de qualquer nmero
de letras, caracteres ou sobrescritas.
Espaos no so permitidos nos
nomes de variveis.

Arrays (vetores) so permitidos e

so e denotados por um nome de
varivel e um ndice de vetor entre
parnteses ().

set i 0
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 variveis so
obtidos prefixando o nome da
varivel pela operao substituta
de varivel, $.
Nome de variveis, so case
sensitive (identificador de
maiscula e minscula).
@assign

set

Comando TCL criador.

set varivel 5
set varivel "to this value"

Variveis so criadas em TCL

usando o comando set . At que a
varivel seja criada (setada) isto
no existe.
@unassign

unset

Comando TCL criador.

unset varivel

Variveis so dispostas usando o

comando unset .
Quando a varivel referente a um
objeto SCL (dtm ou arquivo string
que foi carregado usando
comandos da extenso SCL)
unsetando a varivel far com o
objeto seja removido da memria.

Manual SURPAC

@function

SclFunction nome_daFuno
parmetros_daFuno

Descrio do comando.

O commando SCLFunction
usado para executar funes no
software que so normalmente
acessadas escolhendo um item do
menu, por exemplo, CREATE
DTM ou RECALL FILE.

set status [ SclFunction

"CREATE DTM" {
frm00126={
{
_action="display"
location="gol"
id="1"
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"

O commando SCLFunction exige

um argumento imperativo, o nome check_distance="0.005"
}
da funo que est sendo chamada.
}
Opcionalmente a SCLFunction
}]
pode ter um corpo que contm
uma lista de pares nome = valor
que definem parmetros para
aquela funo.
Os parmetros _action, _error,
_missing and _pause podem ser
usados para controle de
comportamento de formulrios
que so exigidos quando a funo
executada. Note que estes
parmetros NO so gravados
com os scripts como
comportamento padro, para
cada um destes parmetros
apropriado para a maioria dos
casos.
Autores experientes de scripts
acharo estes parmetros teis
para habilitar comportamentos
particulares em circunstncias nas
quais formulrios podem falhar em
7

Manual SURPAC

vrios critrios de validao e

voc ser capaz de dar controle
interativo ao usurio para realizar
correes aos parmetros do
formulrio.

@form

No h equivalente em TCL.

O comando de extenso SclFunction

Inclui detalhes para todos os
parmetros necessrios por uma
funo sem qualquer referncia aos
formulrios que esto sendo usados
para entrada de parmetros da
funo. Consequentemente no h
necessidade de um comando
equivalente para SCL.

@macro

package
pkg_mkIndex
proc

Caracterstica TCL interna.

A velha linguagem macro permitia

que macros chamassem outras
macros para auxiliar num
desenvolvimento de solues mais
complexa. Cada macro existia em
seu prprio arquivo .cmd.
TCL fornece procedimentos para
este fim. Procedimentos precisam
existir num mesmo script ao
menos se forem definidos num
pacote de bibliotecas para permitir
que eles possam ser usados por
outro arquivo script.
A velha linguagem macro permitia
a passagem por argumentos
outras macros mas no permitia o
retorno de valores das macros
chamadas.

Create a package from files in

the temp directory
pkg_mkIndex c:/temp/*.tcl
c:\temp\SsiMain.tcl
package require
SsiPackage
SayHelloWorld
c:\temp\SsiPackage.tcl
package provide
SsiPackage 1.0
proc SayHelloWorld {} {
puts "HELLO
WORLD"
}
Chamando precedimentos e
modificando argumentos para
retorno de valores do
procedimento
Isto funciona passando nomes de
argumentos ao invest de valores e
usando upvar para acessar as
variveis no frame de chamada de
empilhamento.
sample.tcl
proc changevars {arg1name
arg2name} {
upvar $arg1name x
upvar $arg2name y
set x [expr $x + 1]
8

Manual SURPAC

TCL permite o retorno de valores

por alguns ou todos os argumentos
a um procedimento. Isto
conseguido usando o comando
upvar.

set y [expr $y + 2]
}
set a 1
set b 2
set status [externproc a
b]
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 perodo

Comando de extenso.

SclPause 5

Pausar a aplicao por um

perodos de segundos se o perodo
for definido ou at o
pressionamento de uma tecla do
teclado se o perodo no 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 explcito
de sada for definido e a
mensagem direcionada janela
de logs de mensagens do
SURPAC.
@alert

SclBeep Mensagem Opcional

Comando de extenso.

SclBeep "Condio de erro

encontrada"

SclBeep ir um toque simples de

campainha e tambm 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 extenso.
An SCL script that uses a Guido
@var_prompt
$script
user interface
um objeto Guido
@var_default
Os macros velhos usam somente o #setCriar
status
@gui_str
$guido_object SclRunGuido @menu gravar os menus indicados [ SclCreateGuido
@gui_file
durante a execuo macro.
guido_object "inputs.tcl"
@gui_str(simple_for
$guido_object
Realmente no servem a nenhuma ]
m )
@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
SclSetGuidoValue
SclGetGuidoValue $name
Graphical User Interface Design
value
Objects, Guido, o componente "location" "topo"
$guido_object
de sistema que usado para
SclSetGudioValue "id" "1"
unset guido_object
construo de uma interia interface
$guido_object
de usurio. Guido desenvolvido SclSetGuidoValue
tambm em TCL e por este motivo "breaklines" "Y"
muito fcil graver Guido sscripts Guido# Executar o objeto
que contm componentes de
set status
interface de usurio para
[ $guido_object
SclRunGuido ]
SCL/TCL scripts.
if { $status ==
$SCL_OK } {
Todos os commandos de interface
# Examine the
com o usurio na velha linguagem guido object after it has
returned
macro so consequentemente
10

Manual SURPAC

substitudos por um aagrpamento

de commandos para crier e
executar objetos Guido atravs de
SCL.

$guido_object
SclGetGuidoValue
"location" location
$guido_object
SclGetGuidoValue "id" id
$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
@endwhile

while

Comando TCL interno

O exemplo mostra um simples uso

do comando while.

set x 0
while {$x<10} {
puts "x is $x"
incr x
}

Parnteses {} so usados como

delimitadores para a parte
condicional do while e para o
corpo da declarao do while.
@range
@endrange

SclRangeExpand handle
range_expression

Comando de extenso.

Fornece uma iterao para um

SclRangeGet $handle $item intervalo SSI. A expresso do
value
intervalo pode ser qualquer
intervalo SSI vlido incluindo um
SclRangeGetCount $handle arquivo de intervalo cujo nome
precedido pelo smbolo @.
SclRangeIncludes $handle
$value epsilon

set status
[SclRangeExpand handle
"1,16,2"]
if {$handle ==
SCL_UNDEFINED_HANDLE} {
puts "Undefined range
handle"
} else {
# Loop through the
range
set count
[ 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
@label

N/A

No h equivalente em TCL.
Prticas de Programao estruturada
while, for, if, switch, etc, so
necessrias para lidar com
execues condicionais do cdigo
para scripts TCL/SCL.

@if
@elseif
@else
@endif

if {expr} {
} elseif {expr} {
} else {
}
switch

Comando TCL interno

@isset

info exists

Comando TCL interno.

info exists varname.

Retorna 1 se a varivel de nome

requisitada existir, ou 0 caso
contrrio.

The info command may be used for a

variety of other purposes also.

If, elseif, else e switch fornecem

diferentes mtodos de cdigos de
execuo condicionais. O switch
um meio melhor para lidar com
um grande nmero de alternativas
do que a repetio de comandos
elseif.

set temp 95
if {$temp < 80} {
puts "It's a little
chilly."
} else {
puts "Warm enough for
me."
}
set num_legs 4
switch $num_legs {
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."}
}

13

Manual SURPAC
@(0), @(1), etc.

Automatically created argv

variable.

O argumento posicional passado por

referncia 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 funo MACRO b.tcl and passes the 10 optional
parameters to b.tcl through the
PLAYBACK para chamar um
automatically created argv
script TCL com mximo 10
variable.

argumentos opcionais passados

por referncia para o script TCL
para ser executado. Isto feito
criando uma varivel TCL do tipo set status [ SclFunction
lista argv que contm uma entrada "MACRO PLAYBACK" {
frm00197={
para cada valor que inserido nos
{
campos do formulrio da funo
continue_on_error="N"
MACRO PLAYBACK.

came

slow_motion="N"
macro_name="b.tcl"
arg1="This input
via arg1"
arg2="This input
via arg2"
arg3="This input
via arg3"
arg4="This input
via arg4"
arg5="This input
via arg5"
arg6="This input
via arg6"
arg7="This input
via arg7"
arg8="This input
via arg8"
arg9="This input
via arg9"
arg10="This input
via arg10"

1.3.1.1 Procedimentos com

tamanho de variveis came
do tipo lista
came

Se necessrio o tamanho da varivel came

de argumento tipo lista pode ser
suportado fazendo o ltimo
came
parmetro formal num procedimento
de argumento do tipo lista args.
came

Isto resulta numa varivel

chamada args estando disponvel
para o procedimento. Esta varivel
contm uma list de valores do
argumento opcional e os valores
deste argumentos podem ser
obtidos atravs do uso das funes
de processamento de lista da TCL.

came
came
came
came

}]

Llength para pegar o nmero 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

set status [ SclDigitise

"Digitise a location on
graphics window" x y
Exibe um prompt para instruir o the
z ]
usurio a usar o mouse para digitar if { $status == $SCL_OK }

SclDigitise "prompt string"

Comando de extenso
xvarname yvarname zvarname

15

Manual SURPAC
{

uma posio (location) na

viewport 2D ou 3D.
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.

puts "x = $x, y = $y, z

= $z"
} else {
puts "Status = $status"
}

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
gui_drag_rect_center
_corner

Prompt the user to use the mouse

to click and drag to define a
rectangle on the screen by defining
its centre point and the point
where the mouse is released.

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

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
er
$prompt x1 y1 z1 x2 y2 z2
Gui_drag_rect_corner
_corner

Extension command.

Prompt the user to use the mouse

to click and drag to define a
rectangle on the screen by defining
its two corners.

set status
[SclDragRectCornerCorner
"prompt text" x1 y1 z1 x2 y2 z2]

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
Gui_drag_line

SclDragLine $prompt x1 y1 z1
x2 y2 z2

Extension command.

set status [SclDragLine "prompt

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
Gui_drag_point

$prompt delx dely delz

SclDragSegment
segment_handle $prompt
delx dely delz
SclDragPoint point_handle
$prompt delx dely delz

Prompt the user to select and drag

a string, segment or point from its
current location to a new location.

text" delx dely delz]

set segment [SclDragSegment
"Prompt text" delx dely delz]
set point [SclDragPoint "Prompt
text" delx dely delz]

Note that the string, segment or

point is not changed.
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.
strained
string_handle $prompt
Gui_drag_segment_ $constraint delx dely delz
Prompt the user to select and drag
Constrained
Gui_drag_point_Cons SclDragSegmentConstrained a string, segment or point from its
current location to a new location
trained

segment_handle $prompt
$constraint delx dely delz
SclDragPointConstrained
point_handle $prompt
$constraint delx dely delz

set string
[SclDragStringConstrained
"prompt text" $constraint delx dely
delz]
set segment

and constrain the movement to be [SclDragSegmentConstrained

in a particular direction or plane. "Prompt text" $constraint delx dely
delz]

Note that the string, segment or

point is not changed.
The purpose of the function is to
display feedback of the drag
operation and to return the
displacement defined by the drag
operation.

set point [SclDragPointConstrained

"Prompt text" $constraint delx dely
delz]

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
File_writeline

eof

gets
read
puts

Inbult Tcl commands.

eof

Inbuilt tcl command

gets $file inline

puts $file outline

Read and write from/to a file

previously opened using open.
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

command.

SclExpr "1 + 2"

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