Apostila Com Comandos para Server, Remote, HTTP, Objetos

CLASSES VISUAIS
TSRCOBJECT
Caractersticas
Classe abstrata inicial de todas as classes de interface do Advpl. No deve ser
instanciada diretamente.
Propriedades
Propriedade Tipo
nLeft
Numrico.
nTop
Numrico.
nWidth
Numrico.
nHeight
Numrico.
cCaption
Caractere.
cTooltip
Caractere.
lShowHint Lgico.
cMsg
Caractere.
nClrText
nClrPane
Numrico.
Numrico.
bWhen
Bloco de
cdigo.
bValid
Bloco de
cdigo.
Bloco de
cdigo.
Bloco de
brClicked
cdigo.
Bloco de
blDblClick
cdigo.
oWnd
Objeto.
lVisible
Booleano.
Objeto ou
Cargo
varivel.
bLostFocus Bloco de
blClicked
PDF Creator - PDF4Free v2.0
Descrio
Coordenada horizontal em pixels.
Coordenada vertical em pixels.
Largura em pixels.
Altura em pixels.
Ttulo ou contedo do objeto.
Mensagem exibida quando objeto exibe seu tooltip.
Flag que ativa .T. ou desativa .F. a exibio do tooltip do
objeto.
Mensagem exibida na barra de status da janela principal
quando o objeto ganha foco.
Cor do texto do objeto.
Cor do fundo do objeto.
Executado quando h movimentao de foco na janela.Se
retornar .T. o objeto continua habilitado, se retornar .F. o
objeto ser desabilitado.
Executado quando o contedo do objeto modificado e
dever ser validado. Deve retornar .T. se o contedo vlido
e .F. se contedo invlido.
Executado quando acionado click do boto esquerdo do
mouse sobre o objeto.
Executado quando acionado click do boto direito do mouse
sobre o objeto.
Executado quando acionado duplo click do boto esquerdo
do mouse sobre o objeto.
Janela onde o objeto foi criado.
Se .T. o objeto visvel, se .F. o objeto invisvel.
Contedo associado ao objeto.
Executado quando objeto perde foco.
http://www.pdf4free.com
cdigo.
Bloco de
bGotFocus
cdigo.
Executado quando objeto ganha foco.
Mtodos
SetFocus
Sintaxe SetFocus( )
Descrio Fora o foco de entrada de dados mudar para o objeto.
Retorno NIL
Hide
Sintaxe Hide( )
Descrio Torna objeto invisvel.
Retorno NIL
Show
Sintaxe Show( )
Descrio Torna objeto visvel.
Retorno NIL
Enable
Sintaxe Enable( )
Descrio Habilita o objeto.
Retorno NIL
Disable
Sintaxe Disable( )
Descrio Desabilita o objeto.
Retorno NIL
Refresh
Sintaxe
Refresh( )
Fora atualizao (sincronia) de propriedades entre o programa e o
Descrio
Protheus Remote.
Caractersticas
MSDialog deve ser utilizada como padro de janela para entrada de dados. MSDialog
um tipo de janela dilogo modal, isto , no permite que outra janela ativa receba dados
enquanto esta estiver ativa.
Propriedades
Vide classes ancestrais.
Mtodos
New
Descrio
Sintaxe
Mtodo construtor da classe.

New([anTop], [anLeft], [anBottom], [anRight], [acCaption],
[cPar6], [nPar7], [lPar8], [nPar9], [anClrText], [anClrBack],
[oPar12], [aoWnd], [alPixel], [oPar15], [oPar16], [lPar17])
Parmetro Tipo / Descrio

Numrico, opcional. Coordenada vertical superior em
anTop
pixels ou caracteres.
Numrico, opcional. Coordenada horizontal esquerda
anLeft
em pixels ou caracteres.
Numrico, opcional. Coordenada vertical inferior em
anBotom
Numrico, opcional. Coordenada horizontal direita em
anRight
Parmetros
acCaption Caractere, opcional. Ttulo da janela.
cPar6
Reservado.
nPar7
Reservado.
lPar8
Reservado.
nPar9
Reservado.
anClrText Numrico,opcional. Cor do texto.
anClrBack Numrico,opcional. Cor de fundo.
oPar12
Reservado.
aoWnd
alPixel
oPar15
oPar16
nPar17
Retorno
Objeto, opcional. Janela me da janela a ser criada,

padro a janela principal do programa.
Lgico, opcional. Se .T. considera as coordenadas
passadas em pixels, se .F. considera caracteres.
Reservado.
Reservado.
Reservado.
O Dilogo criado.
Exemplo
#INCLUDE protheus.ch
User Function Teste()
// cria dilogo
Local oDlg:=MSDialog():New(10,10,300,300,Meu
dialogo,,,,,CLR_BLACK,CLR_WHITE,,,.T.)
// ativa dilogo centralizado
oDlg:Activate(,,,.T.,{||msgstop(validou!),.T.},,{||msgstop(iniciand
o) )
Return
Descrio
Utilize a classe tButton para criar um controle visual do tipo boto.
Propriedades
Nome
Tipo / Descrio
lProcessing Lgico. Se .T. indica o boto est efetuando uma ao.
bAction
Bloco de cdigo. Executado quando o boto pressionado.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [acCaption], [aoWnd], [abAction],
[anWidth], [anHeight], [nPar8], [aoFont], [lPar10],
[alPixel],[lPar12],[cPar13], [lPar14], [abWhen], [bPar16], [lPar17])

Numrico, opcional. Coordenada vertical em pixels ou
anRow
carateres.
Numrico, opcional. Coordenada horizontal em pixels
anCol
ou caracteres.
acCaption Caractere, opcional. Titulo do boto.
Objeto, opcional. Janela ou controle onde o boto
aoWnd
dever ser criado.
Bloco de cdigo, opcional. Bloco que dever ser
abAction
acionado quando o boto for pressionado.
anWidth Numrico, opcional. Largura do boto em pixels.
anHeight Numrico, opcional. Altura do boto em pixels.
nPar8
Reservado.
Objeto, opcional. Objeto tipo tFont com propriedades
Parmetros aoFont
da fonte utilizada para o ttulo do boto.
lPar10
Reservado.
Lgico, opcional. Se .T. considera as coordenadas
alPixel
passadas em pixels, se .F. (padro) considera em
caracteres.
lPar12
Reservado.
cPar13
Reservado.
lPar14
Reservado.
Bloco de cdigo, opcional. Executado quando mudana
de foco de entrada de dados est sendo efetuada na
abWhen janela onde o controle foi criado. O bloco deve retornar
.T. se o controle deve permanecer habilitado ou .F. se
no.
bPar16
Reservado.
lPar17
Reservado.
Exemplo
#include protheus.ch
User Function TesteGet()
Local oDlg, oButton, oCombo, cCombo, aItems:=
{item1,item2,item3}
cCombo:= aItems[2]
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu Combo
oCombo:= tComboBox():New(10,10,{|u|if(PCount()>0,cCombo:=u,cCombo)},;
aItems,100,20,oDlg,,{||MsgStop(Mudou item)},,,,.T.,,,,,,,,,cCombo)
// Boto para fechar a janela
oButton:=tButton():New(30,10,fechar,oDlg,{||oDlg:End()},100,20,,,,.T
.)
ACTIVATE MSDIALOG oDlg CENTERED
MsgStop( O valor +cCombo )
Return NIL
Descrio
Utilize a classe tCheckbox quando desejar criar um controle que possua dois estados .T.
ou .F..
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [acCaption], [abSetGet], [aoWnd],
[anWidth], [anHeight], [nPar8], [abClick], [aoFont], [abValid],
[anClrFore], [anClrBack], [lPar14], [alPixel], [cPar16], [lPar17],
[abWhen])

anRow
carateres.
anCol
ou caracteres.
acCaption Caractere, opcional. Texto exibido pelo controle.
Bloco de cdigo, opcional. Bloco de cdigo no formato
Parmetros
{|u| if( Pcount( )>0, <var>:= u, <var> ) } que o controle
abSetGet utiliza para atualizar a varivel <var>. <var> deve ser
tipo lgico, se <var> = .T. ento o controle aparecer
checado.
Objeto, opcional. Janela ou controle onde o controle
aoWnd
dever ser criado.
anWidth Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
nPar8
Reservado.
Bloco de cdigo, opcional. Executado quando o
abClick controle click do boto esquerdo do mouse acionado
sobre o controle.
Objeto, opcional. Objeto tipo tFont com propriedades
aoFont
da fonte utilizada para o texto do controle.
contedo do controle deve ser validado, deve retornar
abValid
.T. se o contedo for vlido e .F. quando o contedo
for invlido.
anClrFore Numrico, opcional. Cor de fundo do controle.
anClrBack Numrico, opcional. Cor do texto do controle.
lPar14
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas
alPixel
so em pixels, se .F. so em caracteres.
cPar16
Reservado.
lPar17
Reservado.
.T. se o controle deve permanecer habilitado ou .F. se
no.
Retorno
O objeto construdo.
Exemplo
Local oDlg, oButton, oCheck, lCheck:=.F.
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu programa
oCheck:= tCheckBox():New(10,10,funcionou?,;
{|u|if( pcount()>0,lCheck:=u,lCheck)};
,oDlg,100,20,,,,,,,,.T.)
oButton:=tButton():New(30,10,fechar,oDlg,{||oDlg:End()},;
100,20,,,,.T.)
If lCheck
MsgStop( Funcionou! )
Endif
Return NIL
Descrio
Utilize a classe tComboBox para cria uma entrada de dados com mltipla escolha com
item definido em uma lista vertical, acionada por F4 ou pelo boto esquerdo localizado
na parte direita do controle. A varivel associada ao controle ter o valor de um dos
itens selecionados ou no caso de uma lista indexada, o valor de seu ndice.
Propriedades
Nome Tipo / Descrio
Array. Lista de itens, caracteres, a serem exibidos. Pode ter os seguintes
aItems formatos: a) Seqencial, exemplo: {item1,item2,...,itemN} ou b)
Indexada, exemplo: {a=item1,b=item2, ..., n=itemN}.
nAt Numrico. Posio do item selecionado.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [abSetGet], [anItems], [anWidth],
[anHeight], [aoWnd], [nPar8], [abChange], [abValid], [anClrText],
[anClrBack], [alPixel], [aoFont], [cPar15], [lPar16], [abWhen],
[lPar18], [aPar19], [bPar20], [cPar21], [acReadVar])

anRow
caracteres.
anCol
ou caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no
formato {|u| if( Pcount( )>0, <var>:= u, <var> ) } que
o controle utiliza para atualizar a varivel <var>.
Parmetros abSetGet <var> deve ser tipo caracter. Se a lista for seqencial,
o controle atualizar <var> com o contedo do item
selecionado, se a lista for indexada, <var> ser
atualizada com o valor do ndice do item selecionado.
Array, opcional. Lista de items, caracteres, a serem
exibidos. Pode ter os seguintes formatos: a)
anItems
Seqencial, exemplo: {item1,item2,...,itemN}
ou b) Indexada, exemplo: {a=item1,b=item2, ...,
n=itemN}.
anWidth
anHeight
Numrico, opcional. Largura do controle em pixels.

Numrico, opcional. Altura do controle em pixels.
aoWnd
ser criado.
nPar8
Reservado.
abChange
controle modifica o item selecionado.
abValid
for invlido.
anClrBack Numrico, opcional. Cor de fundo do controle.
anClrText Numrico, opcional. Cor do texto do controle.
alPixel
Objeto, opcional. Objeto tipo tFont utilizado para
aoFont
definir as caractersticas da fonte utilizada para exibir
o contedo do controle.
cPar15
Reservado.
lPar16
Reservado.
Bloco de cdigo, opcional. Executado quando
mudana de foco de entrada de dados est sendo
abWhen efetuada na janela onde o controle foi criado. O bloco
deve retornar .T. se o controle deve permanecer
habilitado ou .F. se no.
lPar18
Reservado.
aPar19
Reservado.
bPar20
Reservado.
cPar21
Reservado.
Caractere, opcional. Nome da varivel que o controle
dever manipular, dever ser a mesma varivel
acReadVar
informada no parmetro abSetGet, e ser o retorno da
funo ReadVar( ).
Retorno
O objeto criado.
Select
Descrio
Sintaxe
Muda o item selecionado no combobox.

Select( [anItem] )
Parmetros

anItem
Numrico, opcional. Posio do item a ser selecionado.
Retorno
NIL
Exemplo
Local oDlg, oButton, oCombo, cCombo, aItems:=
{item1,item2,item3}
cCombo:= aItems[2]
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu Combo
oCombo:= tComboBox():New(10,10,{|u|if(PCount()>0,cCombo:=u,cCombo)},;
aItems,100,20,oDlg,,{||MsgStop(Mudou item)},;
,,,.T.,,,,,,,,,cCombo)
@ 40,10 BUTTON oButton PROMPT Fechar OF oDlg PIXEL ACTION oDlg:End()
MsgStop( O valor +cCombo )
Return NIL
Caractersticas
tControl a classe comum entre todos os componentes visuais editveis.
Propriedades
Nome
Tipo / Descrio
Numrico. Alinhamento do controle no espao disponibilizado pelo seu
Align
objeto parente. 0 = Nenhum (padro), 1= no topo, 2 = no rodap, 3= a
esquerda, 4 = a direita e 5 = em todo o parente.
Lgico. Se .T. indica que o contedo da varivel associada ao controle foi
lModified
modificado.
Lgico. Se .T. o contedo da varivel associada ao controle permanecer
lReadOnly
apenas para leitura.
Numrico. Handle (identificador) do objeto sobre o qual o controle foi
hParent
criado.
Bloco de cdigo. Executado quando o estado ou contedo do controle
bChange
modificado pela ao sobre o controle.
Mtodos
SetFocus
Descrio Fora mudana do foco de entrada de dados para o controle.
Sintaxe SetFocus( )
REtorno NIL
Descrio
Utilize objeto tFont para modificar a fonte padro de controles visuais.
Propriedades
Vide classes ancestrais.
Mtodos
New
Descrio
Sintaxe

New([acName], [nPar2], [anHeight], [lPar4], [alBold], [nPar6],
[lPar7], [nPar8], [alItalic], [alUnderline])

Caractere, opcional. Nome da fonte, o padro
acName
Arial.
nPar2
Reservado.
Numrico, opcional. Tamanho da fonte. O padro anHeight
11.
lPar4
Reservado.
Parmetros
alBold
Lgico, opcional. Se .T. o estilo da fonte ser negrito.
nPar6
Reservado.
lPar7
Reservado.
nPar8
Reservado.
alItalic
Lgico, opcional. Se .T. o estilo da fonte ser itlico.
Lgico, opcional. Se .T. o estilo da fonte ser
alUnderline
sublinhado.
Retorno
O objeto criado.
Exemplo
#INCLUDE "PROTHEUS.CH"
Local oDlg, oSay
Local oFont:= TFont():New("Courier New",,-14,.T.)
DEFINE MSDIALOG oDlg FROM 0,0 TO 200,200 TITLE "My dialog" PIXEL
// Apresenta o tSay com a fonte Courier New
oSay := TSay():New( 10, 10, {|| "Mensagem"},oDlg,, oFont,,,, .T.,
CLR_WHITE,CLR_RED )
/* o comando abaixo proporciona o mesmo resultado
@ 10,10 SAY oSay PROMPT "Mensagem" FONT oFont COLOR CLR_WHITE,CLR_RED
OF oDlg PIXEL
*/
oSay:lTransparent:= .F.
Return
Descrio
Use tGet para criar um controle que armazene ou altere o contedo de uma varivel
atravs de digitao. O contedo da varivel s modicado quando o controle perde o
foco de edio para outro controle.
Propriedades
Nome
Tipo / Descrio
Lgico. Se .T. o controle se comporta como entrada de dados de senha,
lPassword
exibindo asteriscos * para esconder o contedo digitado.
Picture
Caractere. Mscara de formatao do contedo a ser exibido.
Mtodos
New
Descrio
Sintaxe
Mtodo construtor do controle.

New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth],
[anHeight], [acPict], [abValid], [anClrFore], [anClrBack], [aoFont],
[lPar12], [oPar13], [alPixel], [cPar15], [lPar16], [abWhen],
[lPar18], [lPar19], [abChange], [alReadOnly], [alPassword],
[cPar23], [acReadVar], [cPar25], [lPar26], [nPar27], [lPar28])

Numrico, opcional. Coordenada vertical em pixels
anRow
ou caracteres.
anCol
ou caracteres.
abSetGet
<var> deve ser tipo caracter, numrico ou data.
aoWnd
ser criado.
anWidth
Caractere, opcional. Mscara de formatao do
acPict
contedo a ser exibido.
abValid
for invlido.
Parmetros
aoFont
lPar12
Reservado.
oPar13
Reservado.
alPixel
cPar15
Reservado.
lPar16
Reservado.
abWhen
efetuada na janela onde o controle foi criado. O bloco
lPar18
Reservado.
lPar19
Reservado.

controle modifica o valor da varivel associada.
Lgico, opcional. Se .T. o controle no poder ser
alReadOnly
editado.
Lgico, opcional. Se .T. o controle exibir asteriscos
alPassword * no lugar dos caracteres exibidos pelo controle
para simular entrada de senha.
cPar23
Reservado.
Caractere, opcional. Nome da varivel que o controle
dever manipular, dever ser a mesma varivel
acReadVar
informada no parmetro abSetGet, e ser o retorno da
funo ReadVar( ).
cPar25
Reservado.
lPar26
Reservado.
nPar27
Reservado.
lPar28
Reservado.
abChange
Retorno
O controle construdo.
Exemplo
Local oDlg, oGet1, oButton, nGet1:=0
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu Get
oGet1:= TGet():New(10,10,{|u| if(PCount()>0,nGet1:=u,nGet1}}, oDlg,;
100,20,@E 999,999.99,;
{|o|nGet1>1000.00},,,,,,.T.,,,,,,,,,,nGet1)
/* Tem o mesmo efeito
@ 10,10 MSGET oGet1 VAR nGet1 SIZE 100,20 OF oDlg PIXEL PICTURE @E
999,999.99 VALID nGet1>1000.00
*/
MsgStop( O valor +Transform(nGet1,@E 999,999.00) )
Return NIL
Descrio
Utilize a classe tGroup para criar um painel onde controles visuais podem ser agrupados
ou classificados. criada uma borda com ttulo em volta dos controles agrupados.
Mtodos
New
Descrio
Sintaxe

New([anTop], [anLeft], [anBottom], [anRight], [acCaption],
[aoWnd], [anClrText], [anClrPane], [alPixel], [lPar10])

anTop
anLeft
anBottom
Numrico, opcional. Coordenada horizontal direita em
anRight
Parmetros
acCaption Caractere, opcional. Ttulo do grupo.
aoWnd
ser criado.
anClrText Numrico, opcional. Cor do texto.
anClrPane Numrico, opcional. Cor do fundo.
Lgico, opcional. Se .T. as coordenadas informadas so
alPixel
em pixels, se .F. so em caracteres.
lPar10
Reservado.
Retorno
O objeto criado.
Exemplo
User function teste()
Local oDlg, oGroup, oGet1, oGet2, cGet1:=Space(10),;
cGet2:= Space(10)
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 TITLE My test PIXEL
oGroup:= tGroup():New(10,10,200,200,grupo de gets,oDlg,,,.T.)
@ 10,10 MSGET oGet1 VAR cGet1 SIZE 100,10 OF oGroup PIXEL

@ 30,10 MSGET oGet2 VAR cGet2 SIZE 100,10 OF oGroup PIXEL
Return NIL
Descrio
Utilize a classe tListbox para criar uma janela com itens selecionveis e barra de
rolagem. Ao selecionar um item, uma varivel atualizada com o contedo do item
selecionado.
Propriedades
Nome Tipo / Descrio
nAt Numrico. Posio do item selecionado.
aItems Array de items caracteres. Lista do itens selecionveis.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [abSetGet], [aaItems], [anWidth],
[anHeigth], [abChange], [aoWnd], [abValid], [anClrFore],
[anClrBack], [alPixel], [lPar13], [abLDBLClick], [aoFont],
[cPar16], [lPar17], [abWhen], [aPar19], [bPar20], [lPar21],
[lPar22], [abRightClick] )
Parmetro
anRow
anCol
Parmetros
abSetGet
aaItems
Tipo / Descrio
ou caracteres.
Numrico, opcional. Coordenada horizontal em
formato {|u| if( Pcount( )>0, <var>:= u, <var> )}
que o controle utiliza para atualizar a varivel
<var>. <var> deve ser tipo caracter ou numrica.
Array de items caracteres, opcional. Lista de items
selecionveis.
anWidth
anHeight

abChange
item selecionado alterado.
Objeto, opcional. Janela ou controle onde o
aoWnd
controle ser criado.
contedo do controle deve ser validado, deve
abValid
retornar .T. se o contedo for vlido e .F. quando o
contedo for invlido.
anClrFore
Numrico, opcional. Cor de fundo do controle.
anClrBack
Numrico, opcional. Cor do texto do controle.
alPixel
lPar13
Reservado.
abLDBLClick acionado duplo click do boto esquerdo do mouse
sobre o controle.
aoFont
definir as caractersticas da fonte utilizada para
exibir o contedo do controle.
cPar16
Reservado.
lPar17
Reservado.
abWhen
efetuada na janela onde o controle foi criado. O
bloco deve retornar .T. se o controle deve
permanecer habilitado ou .F. se no.
aPar19
Reservado.
bPar20
Reservado.
lPar21
Reservado.
lPar22
Reservado.
abRightClick acionado click do boto direito do mouse sobre o
controle.
Retorno
O objeto criado.
Select
Descrio
Sintaxe
Fora a seleo de um item.

Select( [anItem] )
Parmetros Parmetro Tipo / Descrio
nItem
Retorno
Numrico, opcional. Posio do item a ser selecionado.
NIL
Add
Descrio
Sintaxe
Insere ou adiciona novo item.

Add( cText, nPos )

cText
Caractere, obrigatrio. Texto do item.
Numrico, obrigatrio. Se 0 ou maior que o nmero de
Parmetros
itens, insere o item no final da lista. Se valor entre 1 e
nPos
nmero de itens, insere o item na posio informada,
empurrando o item anterior para baixo.
Retorno
NIL
Modify
Descrio
Sintaxe
Modifica o texto de um item.

Modify( cText, nPos )

cText
Caractere, obrigatrio. Novo texto do item.
Parmetros
Numrico, obrigatrio. Posio a ser modificada deve
nPos
ser maior que 0 e menor ou igual que o nmero de
itens.
Retorno
NIL
Del
Descrio
Sintaxe
Apaga um item.
Del( nPos )

Parmetros
Numrico, obrigatrio. Posio a ser excluida, deve ser
nPos
maior que 0 e menor ou igual que o nmero de itens.
Retorno
NIL
Len
Descrio Retorna o nmero de itens.
Sintaxe Len( )
Retorno Numrico. Nmero de itens.
Reset
Descrio Apaga todos os itens.
Sintaxe Reset( )
Retorno NIL
Exemplo
User Funcion Teste()
Local oDlg, oList, nList:= 1, aItems:={}
Aadd(aItems,Item
Aadd(aItems,Item
Aadd(aItems,Item
Aadd(aItems,Item
1)
2)
3)
4)
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE Teste

oList:= tListBox():New(10,10,{|u|if(Pcount()>0,nList:=u,nList)};
,aItems,100,100,,oDlg,,,,.T.)
Return NIL
Descrio
Utilize a classe tMeter para criar um controle que exibe uma rgua (gauge) de
processamento, descrevendo o andamento de um processo atraves da exibio de uma
barra horizontal.
Propriedades
Nome
Tipo / Descrio
Numrico. Nmero total de passos at o preenchimento da rgua de

processo.
lPercentage Lgico. Se .T. considera o passo de movimentao em porcentagem.
nClrBar
Numrico. Cor da barra de andamento.
nTotal
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [abSetGet], [anTotal], [aoWnd],
[anWidth], [anHeight], [lPar8], [alPixel], [oPar10], [cPar11],
[alNoPerc], [anClrPane], [nPar14], [anClrBar], [nPar16], [lPar17])

anRow
caracteres.
anCol
ou caracteres.
abSetGet
utiliza para atualizar a varivel <var>. <var> deve ser
tipo numrico.
Numrico, opcional. Numero total de passos at o
anTotal
preenchimento da rgua de processo.
aoWnd
sera criado.
Parmetros
lPar8
Reservado.
alPixel
oPar10
Reservado.
cPar11
Reservado.
Lgico, opcional. Se .T. (padro) no considera os
alNoPerc
passos de atualizao em porcentagem.
anClrPane Numrico, opcional. Cor de fundo do controle.
nPar14
Reservado.
anClrBar Numrico, opcional. Cor da barra de andamento.
nPar16
Reservado.
lPar17
Reservado.
Retorno
O objeto criado.
Set
Descrio
Sintaxe
Atualiza a posio da rgua de processamento.

Set( [nVal] )

Parmetros
Numrico, opcional. Novo valor da posio da rgua de
nVal
processamento.
Retorno
NIL
Exemplo
STATIC lRunning:=.F., lStop:=.F.
Local oDlg, oMeter, nMeter:=0, oBtn1, oBtn2
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 TITLE Teste
oMeter:= tMeter():New(10,10,{|u|if(Pcount()>0,nMeter:=u,nMeter)};
,100,oDlg,100,20,,.T.) // cria a rgua
// boto para ativar andamento da rgua
@ 30,10 BUTTON oBtn1 PROMPT Run OF oDlg PIXEL ACTION
RunMeter(oMeter)
@ 50,10 BUTTON oBtn2 PROMPT Stop OF oDlg PIXEL ACTION lStop:=.T.
Return NIL
STATIC Function RunMeter(oMeter)

If lRunning
Return
Endif
lRunning:= .T.
oMeter:Set(0) // inicia a rgua
While .T. .and. !lStop
Sleep(1000) // pra 1 segundo
ProcessMessages() // atualiza a pintura da janela, processa
mensagens do windows
nCurrent:= Eval(oMeter:bSetGet) // pega valor corrente da rgua
nCurrent+=10 // atualiza rgua

oMeter:Set(nCurrent)
if nCurrent==oMeter:nTotal
Return
endif
Enddo
lRunning:= .F.
lStop:= .F.
Return
Descrio
Utilize a classe tMultiget para criar controle de edio de texto de mltiplas linhas.
Propriedades
Nome
Tipo / Descrio
lWordWrap Lgico. Se .T., faz quebra automtica de linhas.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth],
[anHeight], [aoFont], [alHScroll], [anClrFore], [anClrBack],
[oPar11], [alPixel], [cPar13], [lPar14], [abWhen], [lPar16],
[lPar17], [alReadOnly], [abValid], [bPar20], [lPar21],
[alNoBorder], [alNoVScroll])
Parmetro
anRow
Parmetros anCol
abSetGet
Tipo / Descrio
ou caracteres.
<var> deve ser tipo caracter.

ser criado.
anWidth
anHeight
aoFont
Lgico, opcional. Se .T., habilita barra de rolagem
alHScroll
horizontal.
oPar11
Reservado.
alPixel
cPar13
Reservado.
lPar14
Reservado.
abWhen
efetuada na janela onde o controle foi criado. O bloco
lPar16
Reservado.
lPar17
Reservado.
Lgico, opcional. Se .T. o controle so permitira
alReadOnly
leitura.
abValid
for invlido.
bPar20
Reservado.
lPar21
Reservado.
alNoBorder Lgico, opcional. Se .T. cria controle sem borda.
Lgico, opcional. Se .T., habilita barra de rolagem
alNoVScroll
vertical.
aoWnd
Retorno
O objeto criado.
EnableVScroll
Descrio
Sintaxe
Habilita a barra de rolagem vertical.

EnableVScroll( lEnable )
Parmetros

lEnable Lgico, obrigatrio. Se .T. habilita se .F. desabilita a
barra de rolagem.
Retorno
NIL
EnableHScroll
Descrio
Sintaxe
Habilita a barra de rolagem horizontal.

EnableHScroll( lEnable )
Parmetros

Lgico, obrigatrio. Se .T. habilita se .F. desabilita a
lEnable
barra de rolagem.
Retorno
NIL
Exemplo
Local oDlg, oMemo, cMemo:= space(50)
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE My test
oMemo:= tMultiget():New(10,10,{|u|if(Pcount()>0,cMemo:=u,cMemo)};
,oDlg,100,100,,,,,,.T.)
@ 200,10 BUTTON oBtn PROMPT Fecha OF oDlg PIXEL ACTION oDlg:End()
MsgStop(cMemo)
Return NIL
Descrio
Utilize a classe tPanel quando desejar criar um painel esttico, onde podem ser criados
outros controles com o objetivo de organizar ou agrupar componentes visuais.
Mtodos
New
Descrio
Sintaxe
New([anRow], [anCol], [acText], [aoWnd], [aoFont], [alCentered],

[lPar6], [anClrText], [anClrBack], [anWidth], [anHeight],
[alLowered], [alRaised])
Parmetro
anRow
anCol
acText
Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels.
Numrico, opcional. Coordenada horizontal em pixels.
Caractere, opcional. Texto a ser exibido ao fundo.
Objeto, opcional. Janela ou controle onde ser criado o
aoWnd
objeto.
Lgico, opcional. Se .T. exibe o texto de ttulo ao
alCentered
centro do controle.
Reservado.
Parmetros lPar6
anClrText Numrico, opcional. Cor do texto do controle.
anClrBack Numrico, opcional. Cor do fundo do controle.
Lgico, opcional. Se .T. exibe o painel rebaixado em
alLowered
relao ao controle de fundo.
Lgico, opcional. Se .T. exibe a borda do controle
alRaised
rebaixada em relao ao controle de fundo.
Retorno
O objeto criado.
Exemplo
Local oDlg, oPanel, oBtn1, oBtn2
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE My test
oPanel:= tPanel():New(10,10,,oDlg,,,,,CLR_BLUE,100,100) // cria o
painel
@ 10,10 BUTTON oBtn1 PROMPT hide OF oPanel ACTION oPanel:Hide() //
cria boto sobre o painel
@ 200,10 BUTTON oBtn2 PROMPT show OF oDlg ACTION oPanel:Show() //
cria boto fora o painel
Return
Descrio
Utilize a classe tRadMenu para criar um controle que possibilita escolha de item atravs
de uma lista.
Propriedades
Nome Tipo / Descrio
nOption Numrico. Item selecionado.
aItems Array de caracteres. Lista de items selecionveis.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [aacItems], [abSetGet], [aoWnd], [aPar6],
[abChange], [anClrText], [anClrPan], [cPar10], [lPar11],
[abWhen], [anWidth], [anHeight], [abValid], [lPar16], [lPar17],
[alPixel])

anRow
caracteres.
anCol
ou caracteres.
aacItems Array de caracteres, opcional. Lista de opes.
abSetGet
utiliza para atualizar a varivel <var>. <var> deve ser
tipo numrico.
aoWnd
ser criado.
Parmetros
aPar6
Reservado.
Bloco de cdigo, opcional. Executado quando o item
abChange
selecionado alterado.
anClrText Numrico, opcional. Cor do texto do controle
anClrPan Numrico, opcional. Cor de fundo do controle.
cPar10
Reservado.
lPar11
Reservado.
.T. para que o controle permanea habilitado, ou .F. se
no.

abValid contedo do controle deva ser validado, retornando .T.
se o contedo for vlido, e .F. quando invlido.
lPar16
Reservado.
Lpar17 Reservado.
alPixel
Retorno
O objeto criado.
EnableItem
Descrio
Sintaxe
Habilita ou desabilita item.

EnableItem( [nItem], [lEnable])

nItem
Numrico, opcional. Item selecionado.
Parmetros
Lgico, opcional. Se .T. habilita o item se .F. desabilita
lEnable
o item.
Retorno
NIL
Exemplo
Local oDlg, oButton, oRadio, nRadio:=1
Local aOptions:={escolha1,escolha2}
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu Get
oRadio:= tRadMenu():New(10,10,aOptions,;
{|u|if(PCount()>0,nRadio:=u,nRadio)},;
oDlg,,,,,,,,100,20,,,,.T.)
MsgStop(Escolheu +aOptions[nRadio] )
Return NIL
Descrio
O objeto tipo tSay exibe o contedo de texto esttico sobre uma janela ou controle.
Propriedades
Nome
Tipo / Descrio
Lgico. Se .T. quebra o texto em vrias linhas de maneira a enquadrar o
lWordWrap
contedo na rea determinada para o controle, sendo o padro .F.
Lgico. Se .T. a cor de fundo do controle ignorada assumindo o contedo
lTransparent
ou cor do controle ou janela ao fundo, sendo o padro .T.
Mtodos
New
Descrio
Sintaxe

New([anRow], [anCol], [abText], [aoWnd], [acPicture], [aoFont],
[lPar7], [lPar8], [lPar9], [alPixels], [anClrText], [anClrBack],
[anWidth], [anHeight], [lPar15], [lPar16], [lPar17], [lPar18],
[lPar19])

anRow
caracteres.
anCol
ou caracteres.
Codeblock, opcional. Quando executado deve retornar
abText
uma cadeia de caracteres a ser exibida.
Objeto, opcional. Janela ou dilogo onde o controle
aoWnd
ser criado.
Caractere, opcional. Picture de formatao do contedo
acPicture
a ser exibido.
Parmetros
Objeto, opcional. Objeto tipo tFont para configurao
aoFont
do tipo de fonte que ser utilizado para exibir o
contedo.
lPar7
Reservado.
lPar8
Reservado.
lPar9
Reservado.
Lgico, opcional. Se .T. considera coordenadas
alPixels passadas em pixels se .F., padro, considera as
coordenadas passadas em caracteres.
anClrText Numrico, opcional. Cor do contedo do controle.
anClrBack Numrico, opcional. Cor do fundo do controle.

lPar15
Reservado.
lPar16
Reservado.
lPar17
Reservado.
lPar18
Reservado.
lPar19
Reservado.
Retorno
O objeto criado.
SetText
Descrio
Sintaxe
Modifica o contedo a ser exibido pelo controle.

SetText( [xVal] )

Parmetros
Caracter / Numrico / Data, Opcional. Valor a ser
xVal
exibido.
Retorno
NIL
Exemplo
Local oDlg, oSay
DEFINE MSDIALOG oDlg FROM 0,0 TO 200,200 TITLE My dialog PIXEL
oSay:= tSay():New(10,10,{||para exibir},oDlg,,,,;
,,.T.,CLR_WHITE,CLR_RED,100,20)
Return NIL
Descrio
Utilize a classe tScrollbox para criar um painel com scroll deslizantes nas laterais do
controle.
Mtodos
New
Descrio
Sintaxe

New([aoWnd], [anTop], [anLeft], [anHeight], [anWidth],
[alVertical], [alHorizontal], [alBorder])
Parmetro
Tipo / Descrio
aoWnd
ser criado.
anTop
Numrico, opcional. Coordenada vertical em pixels.
anLeft
pixels.
Parmetros anHeight
anWidth
Lgico, opcional. Se .T. exibe a barra de scroll
alVertical
vertical.
Lgico, opcional. Se .T. exibe a barra de scroll
alHorizontal
horizontal.
alBorder
Lgico, opcional. Se .T. exibe a borda do controle.
Retorno
O objeto criado.
Exemplo
Local oDlg, oScr, oGet1, oGet2, oGet3
Local cGet1, cGet2, cGet3
cGet1:= Space(10)
cGet2:= Space(10)
cGet3:= Space(10)
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL My test
oScr:= TScrollBox():New(oDlg,10,10,200,200,.T.,.T.,.T.) // cria
controles dentro do scrollbox
@ 10,10 MSGET oGet1 VAR cGet1 SIZE 100,10 OF oScr PIXEL
Return NIL
Caractersticas
Classe de janela principal de programa, dever existir apenas uma instncia deste objeto
na execuo do programa.
Propriedades
bInit Bloco de cdigo. Executado quando a janela est sendo exibida.
lEscClose Lgico. Se .T. habilita o <ESC> cancelar a execuo da janela.
oCtlFocus Objeto. Objeto contido na janela que est com foco de entrada de dados.
Mtodos
New
Descrio
Sintaxe
Mtodo construtor da janela.

New( [anTop], [anLeft],[anBottom], [anRight], [acTitle], [nPar6],
[oPar7] ,[oPar8],[oPar9], [aoParent], [lPar11], [lPar12],
[anClrFore], [anClrBack], [oPar15], [cPar16], [lPar17], [lPar18],
[lPar19], [lPar20], [alPixel] );

nTop
nLeft
nBottom
Numrico, opcional. Coordenada horizontal inferior em
nRight
Caractere, opcional. Ttulo da janela.
Parmetros cTitle
nPar6
Reservado.
oPar7
Reservado.
oPar8
Reservado.
oPar9
Reservado.
oParent Objeto, opcional. Janela me da janela corrente.
lPar11
Reservado.
lPar12
Reservado.
nClrFore Numrico, opcional. Cor de fundo da janela.
nClrText Numrico, opcional. Cor do texto da janela.
oPar15
cPar16
lPar17
lPar18
lPar19
lPar20
lPixel
Retorno
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. (padro) considera
coordenadas passadas em pixels, se .F. considera
caracteres.
Objeto. A janela construda.
Activate
Descrio
Sintaxe
Ativa (exibe) a janela. Chamar esse mtodo apenas uma vez.

Activate([acShow], [bPar2], [bPar3], [bPar4], [bPar5], [bPar6], [
abInit ], [bPar8], [bPar9], [bPar10], [bPar11], [bPar12] ,[bPar13],
[bPar14], [bPar15], [abValid], [bPar17], [bPar18] ).

Caracter, opcional. ICONIZED para janela iconizada
acShow
ou MAXIMIZED para janela maximizada.
bPar2
Reservado.
bPar3
Reservado.
bPar4
Reservado.
bPar5
Reservado.
bPar6
Reservado.
Bloco de cdigo. Executado quando janela est sendo
abInit
exibida.
bPar8
Reservado.
bPar9
Reservado.
Parmetros
bPar10
Reservado.
bPar11
Reservado.
bPar12
Reservado.
bPar13
Reservado.
bPar14
Reservado.
bPar15
Reservado.
Bloco de cdigo. Executado quando a janela for
solicitada de fechar. Dever retornar .T. se o contedo
abValid
da janela for vlido, ou .F. se no. Se o bloco retornar
.F. a janela no fechar.
bPar17
Reservado.
bPar18
Reservado.
Retorno
NIL
End
Descrio Solicita encerramento da janela.
Sintaxe End( )
Retorno Lgico. .T. se encerrou a janela e .F. se no.
Center
Descrio Centraliza a janela.
Sintaxe Center( )
Retorno NIL
Exemplo
USER FUNCTION Teste()
Local oWindow
Local abInit:= {||conout("ativando!")}
Local abValid:= {||conout("encerrando!"),.T.}
oWindow:= tWindow():New( 10, 10, 200, 200, "Meu
programa",,,,,,,,CLR_WHITE,CLR_BLACK,,,,,,,.T. )
oWindow:Activate("MAXIMIZED",,,,,,abInit,,,,,,,,,abValid,,)
/* os comandos abaixo proporcionam o mesmo resultado
DEFINE WINDOW oWindow FROM 10, 10 TO 200,200 PIXEL TITLE "Meu
programa" COLOR CLR_WHITE,CLR_BLACK
ACTIVATE WINDOW oWindow MAXIMIZED ON INIT abInit VALID abValid
*/
Return NIL
CLASSES NO VISUAIS
Descrio
A TMailManager uma classe que tem por finalidade criar conexes em servidores
SMTP ou POP
Mtodos
Mtodo
CHANGEFOLDER
Descrio
Mtodo CHANGEFOLDER usado apenas para conexo
IMAP.
O mtodo ChangeFolder() da classe TMailManager tem
como objetivo realizar a mudana de pasta em que estamos
conectados.
Mtodo COPYMSG usado apenas para conexo IMAP.
O mtodo CopyMsg() da classe tMailManager tem como
objetivo Copiar uma determinada mensagem da pasta
corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor, ou at mesmo
para a pasta corrente.
COPYMSG
muito importante entendermos a localizao que estamos

no server IMAP, isso quando usamos funoes que lidam
com o posicionamento no folder do servidor IMAP como
changeFolder(), createFolder() ou deleteFolder().
Para Copiar uma mensagem devemos informar qual
mensagem queremos mover atravs do primeiro parametro
da funo e a pasta de acordo com o nome no servidor
IMAP, a funo ir procurar pelo ID da mensagem apenas
na pasta em que estamos posicionados e tentar mover para
o folder informado(lembrando que o nome deve ser
identico ao criado no servidor)
Mtodo CREATEFOLDER usado apenas para conexo
IMAP
O mtodo CreateFolder() da classe tMailManager tem
como objetivo realizar a criao de uma nova pasta de
mensagens no servidor de emails IMAP.
CREATEFOLDER
DELETEFOLDER
Para se criar uma pasta no diretrio root do servidor IMAP

basta apenas passar o nome da pasta que desejamos, sem
path algum de um device.
Para se criar uma subpasta, devemos informar a hierarquia
de pastas e o nome da pasta. Para se criar uma subpasta de
Inbox, basta chamar a funo create folder informando
'Inbox\Teste' e assim por diante.
Mtodo DELETEFOLDER usado apenas para conexo
IMAP.
O mtodo DeleteFolder() da classe tMailManager, tem
como objetivo deletar uma pasta do servidor de email
IMAP.
Informando a pasta que ser deletada por parametro na
funo, que deve conter o nome passado idntico ao da
pasta no sevidor (case sensitive).
Mtodo DELETEMSG
DELETEMSG
O mtodo DeleteMsg() da classe tMailManager tem como

objetivo deletar uma determinada mensagem do servidor,
de acordo com o numero da mensagem passada por
parametro para a funo.
A funo ir retornar true caso tenha sido encontrado a
mensagem e deletada.
Mtodo GETALLFOLDERLIST usado apenas para
conexo IMAP.
O mtodo GetAllFolderList() da classe TMailManager,
tem como objetivo obter todas as pastas de determinada
conta de email, que esto no servidor email IMAP.
O mtodo retorna todas as pastas assinadas(so as pastas
abilitadas ou Subscribe)e no assinadas, esse retorno vem
em forma de array, do seguinte modo:
array[1]
GETALLFOLDERLIST
:
:
array[1][1]:cNome
array[1][2]:nNumMsg
array[1][3]:nNumMsgNaoLidas
array[1][4]:cStatus
:
:
cStatus: I = NOINFERIOS, N = NOSELECT, M =

MAKED e U = UNMARKED
nNumMsg: Quantidade de mensagens que existem na
pasta.
cNome: O respectivo nome da pasta.
nNumMsgNaoLidas: Numero de mensagens nao lidas na
pasta
Mtodo GETERRORSTRING
GETERRORSTRING
O mtodo GetErrorString da classe TMailManager, tem

como objetivo retornar um erro em forma de string,
trazendo sua descrio de acordo com algum erro que
tenha ocorrido durante alguma outra funo da classe com

SendMail(), algum connect e assim por diante.
O valor informado por parametro representa erros
definidos por padro do protocolo de conexo SMTP.
Mtodo GETFOLDER usado apenas para conexo IMAP.
GETFOLDER
O mtodo getFolder da classe tMailManager tem como

objetivo obter o folder corrente em que estamos
posicionados(est em uso) no servidor IMAP.
A funo ir retornar o nome do folder, de acordo com o
nome criado no servidor.
Mtodo GETFOLDERLIST usado apenas para conexo
IMAP.
O mtodo GetFolderList() da classe TMailManager, tem
como objetivo obter todas as pastas de determinada conta
de email, que esto no servidor email IMAP.
O mtodo retorna todas as pastas assinadas(so as pastas
abilitadas ou Subscribe), esse retorno vem em forma de
array, do seguinte modo:
array[1]
GETFOLDERLIST
:
:
array[1][1]:cNome
array[1][1]:nNumMsg
array[1][1]:cStatus
:
:
cStatus: I = NOINFERIOS, N = NOSELECT, M =

MAKED e U = UNMARKED
nNumMsg: Quantidade de mensagens que existem na
pasta.
nNumMsgNaoLidas: Numero de mensagens nao lidas da
pasta
Mtodo GETMSGBODY usado apenas para conexo
IMAP.
GETMSGBODY
O mtodo GetMsgBody() da classe de tMailManager tem

como objetivo obter o conteudo da mensagem indicada de
acordo com o parametro que representa o numero da
mensagem para a funo.
O valor informado por parametro o numero da mensagem
na pasta do servidor. O mtodo ir procurar pela mensagem
no folder que estiver posicionado no server IMAP.

Mtodo GETMSGHEADER usado apenas para conexo
IMAP.
O mtodo GetMsgHeader() da classe tMailManager tem
como objetivo se comunicar com o server de email IMAP e
obter o cabealho da mensagem requerida de acordo com o
parametro informando.
GETMSGHEADER
Esse cabealho da mensagem contem todos os dados

relativos ao email como : From, To, CC, BCC, etc...
O valor informado por parametro o numero da mensagem
na pasta do servidor.
Obs.: o servidor IMAP ir procurar pela mensagem apenas
na pasta corrente em uso, caso a pasta em uso seja a 'Inbox'
o mensagem ser procurada apenas na nesta pasta.
Mtodo GETNUMMSGS
O mtodo GetNumMsgs() da classe TMailManager tem
como objetivo retornar o numero de mensagens que
existem no servidor.
GETNUMMSGS
Devemos informar um numrico no parametro da funo

como referncia, indicando o total de mensagens aps a
execuo da funo, o valor retornado pela funo apenas
o status de funcionou ou no.
Obs.: A funo retorna o numero de mensagens total da
conta de usurio informada e nao apenas por pasta como
inbox, sent itens, etc..
Mtodo GETPOPTIMEOUT
GETPOPTIMEOUT
O mtodo GetPopTimeOut() da classe tMailManager tem

como objetivo retornar o tempo em segundos que
est estabelecido com o servidor POP para que seja
finalizada a conexo por time-out.
Obs.: caso nao tenha sido estabelecido nenhum tempo de
time-out pela funo SETPOPTIMEOUT, ser retornado
0(zero).
Mtodo GETSMTPTIMEOUT
GETSMTPTIMEOUT
O mtodo GetSMTPTimeOut() da classe tMailManager

tem como objetivo retornar o tempo em segundos que
est estabelecido com o servidor SMTP para que seja
Obs.: caso nao tenha sido estabelecido nenhum tempo de

time-out pela funo SETSMTPTIMEOUT, ser retornado
0(zero).
Mtodo GETUSER
O mtodo usado apenas para conexo IMAP.
GETUSER
A funo GetUser() da classe de email tMailManager tem

como objetivo obter o usuario corrente em que estamos
logados no momento.
A funo ir retornar uma string contendo o valor da conta
de email do usuario antes do @.
Mtodo IMAPCONNECT usado apenas para conexo
IMAP.
O mtodo IMAPConnect() da classe TMailManager tem
como objetivo realizar a conexo em um IMAP e-mail
server e sincroniza o mailbox folders.
IMAPCONNECT
A conexo atravs de IMAP trata-se de um mtodo de

acesso a mensagens eletrnicas armazenadas em um
servidor local ou remoto.
O mtodo ir se conectar de acordo com os dados
informados atravs do mtodo init().
Obs.:Uma caracterstica importante do IMAP
permitir que a manipulao de mensagens e pastas seja
feita como se estivessem no computador local. Sempre
que for estabelecida uma conexo com servidor IMAP
atravs da funo imapConnect() importante finalizar
a conexo utilizando a imapDisconnect().
Mtodo IMAPDISCONNECT usado apenas para conexo
IMAP.
IMAPDISCONNECT
O mtodo IMAPDisConnect() da classe TMailManager

tem como objetivo realizar o fim da conexo entre a
aplicao e um IMAP e-mail server.
Obs.: sempre que for estabelecida uma conexo com
servidor IMAP atravs da funo imapConnect()
importante finalizar a conexo utilizando a disconnect.
Mtodo IMAPSTORE usado apenas para conexo IMAP
IMAPSTORE
O mtodo imapStore() da classe tMailManager tem como

objetivo armazenar uma determinada mensagem em algum
folder do servidor IMAP.
Obs.: A funo muito util quando por exemplo desejamos

que ao enviar uma mensagem ela seja salva em alguma
pasta do server IMAP.
Mtodo INIT
Atravs desse mtodo da classe tMailManager,
iniciamos uma nova conexo com um servidor de
emails POP ou SMTP.
INIT
Quando informamos por argumento o servidor pop (Ex.:

pop3.microsiga.com.br) que siginifica o protocolo usado
na internet para a recebimento de mensagens ao usurio
final e o servidor smtp (Ex.: smtp.microsiga.com.br) que
siginifica o protocolo usado na internet para a envio de
mensagens ao usurio final, devemos tambm informar um
usuario que esteja devidamente cadastrado no servidor e
sua senha.
Podemos ainda informar o tempo de timeout para queda da
conexo e ainda o numero de porta, caso a porta do
servidor desejado no seja a default de um smtp
Mtodo MOVEMSG usada apenas para conexo IMAP.
A funo MoveMsg() da classe tMailManager tem como
objetivo mover uma determinada mensagem da pasta
corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor.
MOVEMSG
muito importante entendermos a localizao que estamos

no server IMAP, isso quando usamos funoes que lidam
com os folder como changeFolder(), createFolder() ou
deleteFolder().
Para mover uma mensagem devemos informar qual
mensagem queremos mover atravs do primeiro parametro
da funo e a pasta de acordo com o nome no servidor
IMAP, a funo ir procurar pelo ID da mensagem apenas
na pasta em que estamos posicionados e tentar mover para
o folder informado(lembrando que o nome deve ser
identico ao criado no servidor)
Contrutor da Classe tMailManager.
Retorna uma nova instncia do Objeto da Classe
tMailManager.
NEW
POPCONNECT
Antes da utilizao das funes e/ou propriedades da classe

de email necessario criarmos uma instancia da classe
atravs do contrutor New().
Mtodo POPCONNECT
O mtodo PopConnect() da classe TmailManager se

conecta com o servidor de email, atravs dos parametros
que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor POP,
ou seja, apenas realizaremos o recebimento das mensagens
existentes na caixa postal do usuario informado.
Mtodo POPDISCONNECT
POPDISCONNECT
O mtodo POPDisconnect() da classe TMailManager ir

realizar o fim da conexo com o servidor POP, se
desconectando apenas com o servidor POP.
Ao solicitar a finalizao da conexo com o servidor
POP, a funo ir retornar o status da operao, caso tenha
sido bem sucedida retorna 0, outros valores de erro caso
contrrio.
Mtodo PURGE usado apenas para conexo IMAP
PURGE
O metodo purge() da classe tMailManager

Mtodo RENAMEFOLDER usado apenas para conexo
IMAP.
RENAMEFOLDER
SENDMAIL
A funo RenameFolder() da classe tMailManger tem

como objetivo realizar a mudana entre os nomes da pastas
no servidor de e-mails IMAP.
Mtodo SENDMAIL
O mtodo SendMail() da classe TMailManager tem a
funo de mandar um e-mail de acordo com os dados
passados por parametro para a funo.
Ao informar os parametros que representam os
destinatarios pode-se informar mais de uma conta de email,
porm devidamente separada por ; Ex.:
user1@server.com.br; user2@server.com.br
Mtodo SETFOLDERSUBSCRIBE usado apenas para
conexo IMAP.
SETFOLDERSUBSCRIBE
A funo setFolderSubscribe da classe tMailManager tem

como objetivo tornar uma pasta do servidor de email IMAP
assinada.
Tornar uma pasta assinada, tem um significado parecido
como deixa-l visivel em nossa caixa de email, as
mensagens para esta pasta sero 'baixadas'.
SETMSGFLAG
A pasta Inbox por exemplo, sempre assinada por default.

Mtodo SETMSGFLAG usado apenas para conexo
IMAP.
A funo SetMsgFlag() da classe tMailManager tem como
objetivo indicar o status para uma determinada mensagem
indicada de acordo com o parametro informado para a
funo.
Os estados possiveis para setar na mensagem so:
A = ANSWERED, F = FLAGGED, D = DELETED, S = SEEN, R =
DRAFT, C = RECENT, P = SPECIAL
Mtodo SETPOPTIMEOUT
SETPOPTIMEOUT
O mtodo SetPopTimeOut() da classe tMailmanager ir

configurar um tempo para que uma conexo
estabelecida com servidor POP seja finalizada por timeout.
Obs.: O tempo informado pelo mtodo deve ser em
segundos.
Mtodo SETSMTPTIMEOUT
SETSMTPTIMEOUT
O mtodo SetSMTPTimeOut() da classe tMailmanager ir

configurar um tempo para que uma conexo
estabelecida com servidor SMTP seja finalizada por timeout.
Obs.: O tempo informado pelo mtodo deve ser em
segundos.
Mtodo SMTPCONNECT
SMTPCONNECT
O mtodo SMTPConnect() da classe TmailManager se

conecta com o servidor de email, atravs dos parametros
que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor
SMTP, ou seja, apenas realizaremos o envio de
mensagens para uma determinada conta de usuario,
informados anteriormente pelo metodo INIT().
Mtodo SMTPDISCONNECT
SMTPDISCONNECT
O mtodo SMTPDisconnect() da classe TMailManager ir

realizar o fim da conexo com o servidor SMTP, se
desconectando apenas com o servidor SMTP.
Ao solicitar a finalizao da conexo com o servidor
SMTP, a funo ir retornar o status da operao, caso
tenha sido bem sucedida retorna 0, outros valores de erro
caso contrrio.
Mtodo SETUSEREALID usado apenas para conexo

IMAP.
A funo SetUseRealID() da classe tMailManager tem
como objetivo definir qual id ser usado para busca das
mensagens.
Uma mensagem de email possui dois modos de se
identificada no servidor IMAP:
SETUSEREALID
-Atravs do seu nmero(o servidor mantm um

'contador' do numero de mensagens que chegam para
determinada conta e atribui esse numero a mensagem. Ex:
Imagine uma conta que acabou de ser criada, ao receber
sua 1 msg, esta recebera um identificador de numero 1 e
assim por diante..).
-Atravs de um ID nico que o servidor atribui para a
mensagem.
Por default as funoes usam o numero da mensagem,
podemos usar a funo SetUseRealID() para mudar isso,
passando um parametro booleano para a funo.
Mtodo ENDGETALLMSGHEADER usado apenas para
conexo IMAP.
A funo EndGetAllMsgHeader() da classe tMailManager
usada aps a chamada da funo
StartGetAllMsgHeader() que inicia o processo de pegar o
header das mensagens.
ENDGETALLMSGHEADER
A funo recebe um array como parametro que deve ser

passado como referncia pois os headers das mensagens
iro ser retornados atravs deste array.
Quando o servidor terminar de baixar as mensagens ser
retornado true atravs da funo, enquanto for retornado
false o parametro nao vem populado com as mensagens.
Mtodo STARTGETALLMSGHEADER usado apenas
para conexo IMAP.
A funo StartGetAllMsgHeader() da classe tMailManager
tem como objetivo dar inicio ao processo de obteno de
STARTGETALLMSGHEADER todos os cabealhos(headers) de todas as mensagens de
uma determinada pasta.
A funo ir avisar ao servidor IMAP que um processo de
obteno das mensagens vai ocorrer, definindo qual a
pasta(folder) deve se iniciar o processo e qual as infomao
no header da mensagem deve ser retornada.

obs.: a funo apenas inicia o processo, para pegar os
cabealhos das mensagens da pasta use a funo
EndGetAllMsgHeader().
Este exemplo tem como objetivo principal documentar a classe tMailManager, com
foco nas funoes que so usadas apenas por conexo IMAP.
Este exemplo ir fazer basicamente manipulao dos folders de uma conta de email,
atravs de uma conexo com o servidor IMAP. Ex: imap.microsiga.com.br
#include "Protheus.ch"
STATIC oMailManager := Nil
User Function
Local
Local
Local
tstIMAP()
aStPastas := {}
sFolder := "TSTIMAP"
sErro := ""
if !myConnect( "imap.microsiga.com.br", "", "seuNomeAntesDo@",

"senhadoemail", @sErro )
return .F.
endif
//tento ir para o folder TSTIMAP
If ! oMailManager:ChangeFolder( ConvFdlName( sFolder, .F. ) )
//entrei aqui pq o folder nao existe, entao crio ele
CreateFolder( sFolder )
EndIf
//pego os folders(pastas) existentes no servidor, incluido o
TSTIMAP
GetFolderList( @aStPastas )
varinfo("PASTAS", aStPastas)
//Verificamos o folder corrente em uso
GetFolder( @sFolder )
conout("Folder Corrente" + sFolder)
If !oMailManager:DeleteFolder( ConvFdlName( sFolder, .F. ) )

conout("nao foi possivel deletar a pasta" + sFolder)
Return .F.
EndIf
myDisconnect()
return .T.
function myConnect( sSrvIMAP, sSrvSMTP, sLogin, sPass, sErro )
Local nErro := 0
//obtenho uma nova instancia da classe de email.
oMailManager := TMailManager():New()
//uso a funo init para setar os dados.
If (nErro := oMailManager:Init( sSrvIMAP, sSrvSMTP, sLogin,
sPass )) != 0
sErro := oMailManager:GetErrorString( nErro )
Conout( sErro )
Return .F.
EndIf
//realizo uma CONEXAO IMAP
If (nErro := oMailManager:IMAPConnect()) != 0
sErro := oMailManager:GetErrorString( nErro )
Conout( sErro )
Return .F.
EndIf
//informo o server que iremos trabalhar com ID real da mensagem
oMailManager:SetUseRealID( .T. )
Return .T.
function myDisconnect()
oMailManager:IMAPDisconnect()
Return .T.
function GetFolderList( aStPastas )
Local nI := 0, nTam := 0
Local aTemp := {}
Local aFolder
aTemp := oMailManager:GetFolderList()
nTam := Len( aTemp )
For nI := 1 To nTam
//crio um array temp {nome, nTotalMensagens,
nMensagensNaoLidas, lAssinada}
aFolder := {}
aAdd(aFolder, ConvFdlName( aTemp[ nI ][1], .T. ))
aAdd(aFolder, aTemp[ nI ][3])
aAdd(aFolder, aTemp[ nI ][5])
aAdd(aFolder, .T.)
//adiciono no array de referencia do parametro
aAdd( aStPastas, aFolder )
aFolder := NIL
Next
Return .T.
// Retorna a pasta que esta em uso, sFolder referencia
function GetFolder( sFolder )
sFolder := ConvFdlName( oMailManager:GetFolder(), .F. )
Return .T.
Function CreateFolder( sFolder )

sFolder := ConvFdlName( sFolder, .F. )
//tento criar o folder no server IMAP
If ! oMailManager:CreateFolder( sFolder )
Return .F.
EndIf
//set o folder como assinado, para aparecer
If ! oMailManager:SetFolderSubscribe( sFolder, .T. )
Return .F.
EndIf
Return .T.
Sintaxe
oObj:CHANGEFOLDER ( < sFolder > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
Representa o nome da pasta na qual desejamos nos
Caracter
mudar(conectar) no servidor IMAP.
sFolder
Retorno
Tipo
Lgico
Descrio
Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP,
false caso contrario.
Descrio
Mtodo CHANGEFOLDER usado apenas para conexo IMAP.
O mtodo ChangeFolder() da classe TMailManager tem como objetivo realizar a
mudana de pasta em que estamos conectados.
oObj:COPYMSG ( < nMsg > , < sFolder > ) --> lRet

Parmetros
Argumento
nMsg
sFolder
Tipo
Descrio
Valor numerico da mensagem no servidor de email IMAP
Numrico
ou seu ID.
Caracter Indica o nome da pasta no servidor de email IMAP, no
qual desejamos transferir a mensagem.

Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
Copiar para a pasta informada, false caso contrrio.
Descrio
O mtodo CopyMsg() da classe tMailManager tem como objetivo Copiar uma
determinada mensagem da pasta corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor, ou at mesmo para a pasta corrente.
muito importante entendermos a localizao que estamos no server IMAP, isso
quando usamos funoes que lidam com o posicionamento no folder do servidor
IMAP como changeFolder(), createFolder() ou deleteFolder().
Para Copiar uma mensagem devemos informar qual mensagem queremos mover atravs
do primeiro parametro da funo e a pasta de acordo com o nome no servidor IMAP, a
funo ir procurar pelo ID da mensagem apenas na pasta em que estamos posicionados
e tentar mover para o folder informado(lembrando que o nome deve ser identico ao
criado no servidor)
oObj:COPYMSG ( < nMsg > , < sFolder > ) --> lRet
Parmetros
Argumento
nMsg
sFolder
Tipo
Descrio
Valor numerico da mensagem no servidor de email IMAP
Numrico
ou seu ID.
Indica o nome da pasta no servidor de email IMAP, no
Caracter
Retorno
Tipo
Lgico
Descrio
Copiar para a pasta informada, false caso contrrio.
Descrio
O mtodo CopyMsg() da classe tMailManager tem como objetivo Copiar uma

IMAP para uma outra pasta no servidor, ou at mesmo para a pasta corrente.
quando usamos funoes que lidam com o posicionamento no folder do servidor
IMAP como changeFolder(), createFolder() ou deleteFolder().
Para Copiar uma mensagem devemos informar qual mensagem queremos mover atravs
criado no servidor)
Sintaxe
oObj:DELETEFOLDER ( < cFolder > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
Representa o nome da pasta na qual desejamos deletar no
Caracter
servidor IMAP.
cFolder
Retorno
Tipo
Lgico
Descrio
Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP,
false caso contrario.
Descrio
Mtodo DELETEFOLDER usado apenas para conexo IMAP.
O mtodo DeleteFolder() da classe tMailManager, tem como objetivo deletar uma pasta
do servidor de email IMAP.
Informando a pasta que ser deletada por parametro na funo, que deve conter o nome
passado idntico ao da pasta no sevidor (case sensitive).
Sintaxe
oObj:DELETEMSG ( < nMsg > ) --> lRet
Parmetros
Argumento
nMsg
Tipo
Descrio
Numrico Numero da mensagem a ser deletada.
Retorno
Tipo
(NULO)
Descrio
Retorna true, caso tenha sido possivel deletar a mensagem. Caso contrrio
retorna false.
Descrio
Mtodo DELETEMSG
O mtodo DeleteMsg() da classe tMailManager tem como objetivo deletar uma
determinada mensagem do servidor, de acordo com o numero da mensagem passada
por parametro para a funo.
A funo ir retornar true caso tenha sido encontrado a mensagem e deletada.
Sintaxe
oObj:ENDGETALLMSGHEADER ( < aHeaders > ) --> lRet
Parmetros
Argumento
Tipo Descrio
Array usado como referncia para o retorno dos headers das
Array
mensagens.
aHeaders
Retorno
Tipo
Lgico
Descrio
Retorna true quando o servidor IMAP terminou de mandar todos os
headers das mensagens, false caso contrrio.
Descrio
Mtodo ENDGETALLMSGHEADER usado apenas para conexo IMAP.
A funo EndGetAllMsgHeader() da classe tMailManager usada aps a chamada da
funo StartGetAllMsgHeader() que inicia o processo de pegar o header das mensagens.
A funo recebe um array como parametro que deve ser passado como referncia pois
os headers das mensagens iro ser retornados atravs deste array.
Quando o servidor terminar de baixar as mensagens ser retornado true atravs da
funo, enquanto for retornado false o parametro nao vem populado com as mensagens.
Sintaxe
oObj:GETALLFOLDERLIST ( ) --> aRet

Retorno
Tipo
Descrio
Retorna um Array contendo todas as pastas (Assinadas/Nao Assinadas) e
informaoes sobre a respectiva pasta, como est status, o seu nome e
numero de mensagens existentes nela.
Array
Descrio
Mtodo GETALLFOLDERLIST usado apenas para conexo IMAP.
O mtodo GetAllFolderList() da classe TMailManager, tem como objetivo obter todas
as pastas de determinada conta de email, que esto no servidor email IMAP.
O mtodo retorna todas as pastas assinadas(so as pastas abilitadas ou Subscribe)e no
assinadas, esse retorno vem em forma de array, do seguinte modo:
array[1]
:
:
array[1][1]:cNome
array[1][2]:nNumMsg
array[1][4]:cStatus
:
:
cStatus: I = NOINFERIOS, N = NOSELECT, M = MAKED e U = UNMARKED

nNumMsg: Quantidade de mensagens que existem na pasta.
nNumMsgNaoLidas: Numero de mensagens nao lidas na pasta
Sintaxe
oObj:GETERRORSTRING ( < nError > ) --> cRet
Parmetros
Argumento
nError
Tipo
Descrio
Representa um valor numrico a ser passado de algum
Numrico
erro de acordo como SMTP.
Retorno
Tipo
Caracter
Descrio
Retorna uma cadeia de caracteres com a descrio, de acordo com o valor
do erro passado.
Descrio
Mtodo GETERRORSTRING
O mtodo GetErrorString da classe TMailManager, tem como objetivo retornar um erro
em forma de string, trazendo sua descrio de acordo com algum erro que tenha
ocorrido durante alguma outra funo da classe com SendMail(), algum connect e assim
por diante.
O valor informado por parametro representa erros definidos por padro do protocolo de
conexo SMTP.
Sintaxe
oObj:GETFOLDER ( ) --> cFolder
Retorno
Tipo
Caracter
Descrio
Retorna uma string contendo o nome do folder em uso pela aplicao.
Descrio
Mtodo GETFOLDER usado apenas para conexo IMAP.
O mtodo getFolder da classe tMailManager tem como objetivo obter o folder corrente
em que estamos posicionados(est em uso) no servidor IMAP.
A funo ir retornar o nome do folder, de acordo com o nome criado no servidor.
Sintaxe
oObj:GETFOLDERLIST ( ) --> aRet
Retorno
Tipo
Array
Descrio
Retorna um Array contendo todas as pastas e informaoes sobre a
respectiva pasta, como se est status, o seu nome e numero de mensagens
existentes nela.
Descrio
Mtodo GETFOLDERLIST usado apenas para conexo IMAP.
O mtodo GetFolderList() da classe TMailManager, tem como objetivo obter todas as
pastas de determinada conta de email, que esto no servidor email IMAP.
O mtodo retorna todas as pastas assinadas(so as pastas abilitadas ou Subscribe), esse

retorno vem em forma de array, do seguinte modo:
array[1]
:
:
array[1][1]:cNome
array[1][1]:nNumMsg
array[1][1]:cStatus
:
:
cStatus: I = NOINFERIOS, N = NOSELECT, M = MAKED e U = UNMARKED

nNumMsg: Quantidade de mensagens que existem na pasta.
nNumMsgNaoLidas: Numero de mensagens nao lidas da pasta
Sintaxe
oObj:GETMSGBODY ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo GETMSGBODY usado apenas para conexo IMAP.
O mtodo GetMsgBody() da classe de tMailManager tem como objetivo obter o
conteudo da mensagem indicada de acordo com o parametro que representa o numero
da mensagem para a funo.
O valor informado por parametro o numero da mensagem na pasta do servidor. O
mtodo ir procurar pela mensagem no folder que estiver posicionado no server IMAP.
Sintaxe
oObj:GETMSGHEADER ( < nMsg > ) --> lRet
Parmetros
Argumento
nMsg
Tipo
Descrio
Valor numerico da mensagem no servidor de email
Numrico
IMAP.
Retorno
Tipo
Lgico
Descrio
retornar seu cabealho, false caso contrrio.
Descrio
Mtodo GETMSGHEADER usado apenas para conexo IMAP.
O mtodo GetMsgHeader() da classe tMailManager tem como objetivo se comunicar
com o server de email IMAP e obter o cabealho da mensagem requerida de acordo
com o parametro informando.
Esse cabealho da mensagem contem todos os dados relativos ao email como : From,
To, CC, BCC, etc...
O valor informado por parametro o numero da mensagem na pasta do servidor.
Obs.: o servidor IMAP ir procurar pela mensagem apenas na pasta corrente em uso,
caso a pasta em uso seja a 'Inbox' o mensagem ser procurada apenas na nesta pasta.
Sintaxe
oObj:GETNUMMSGS ( < nNumMsg > ) --> nRet
Parmetros
Argumento
nNumMsg
Tipo
Descrio
Parametro passado por referencia, retorna nele o numero
Numrico
de mensagens que esto no servidor.
Retorno
Tipo
Numrico
Descrio
0 = Lista recebida com sucesso
Descrio
Mtodo GETNUMMSGS
O mtodo GetNumMsgs() da classe TMailManager tem como objetivo retornar o
numero de mensagens que existem no servidor.
Devemos informar um numrico no parametro da funo como referncia, indicando o

total de mensagens aps a execuo da funo, o valor retornado pela funo apenas o
status de funcionou ou no.
Obs.: A funo retorna o numero de mensagens total da conta de usurio informada e
nao apenas por pasta como inbox, sent itens, etc..
Sintaxe
oObj:GETPOPTIMEOUT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna o tempo em segundos para a finalizao por time out da conexao
POP.
Descrio
Mtodo GETPOPTIMEOUT
O mtodo GetPopTimeOut() da classe tMailManager tem como objetivo retornar o
tempo em segundos que est estabelecido com o servidor POP para que seja finalizada
a conexo por time-out.
Obs.: caso nao tenha sido estabelecido nenhum tempo de time-out pela funo
SETPOPTIMEOUT, ser retornado 0(zero).
Sintaxe
oObj:GETSMTPTIMEOUT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna um tempo em segundos, que representa o tempo para a finalizao
da conexo com o servidor SMTP.
Descrio
Mtodo GETSMTPTIMEOUT
O mtodo GetSMTPTimeOut() da classe tMailManager tem como objetivo retornar o
tempo em segundos que est estabelecido com o servidor SMTP para que seja
Obs.: caso nao tenha sido estabelecido nenhum tempo de time-out pela funo
SETSMTPTIMEOUT, ser retornado 0(zero).
Sintaxe
oObj:GETUSER ( ) --> sRet
Retorno
Tipo
Caracter
Descrio
Retorna uma String contento o nome do usuario da conta de email que
estamos conectados.
Descrio
Mtodo GETUSER
O mtodo usado apenas para conexo IMAP.
A funo GetUser() da classe de email tMailManager tem como objetivo obter o usuario
corrente em que estamos logados no momento.
A funo ir retornar uma string contendo o valor da conta de email do usuario antes do
@.
Sintaxe
oObj:IMAPCONNECT ( ) --> lRet
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possvel realizar a conexo no servidor Imap,
false caso contrrio.
Descrio
Mtodo IMAPCONNECT usado apenas para conexo IMAP.
O mtodo IMAPConnect() da classe TMailManager tem como objetivo realizar a
conexo em um IMAP e-mail server e sincroniza o mailbox folders.
A conexo atravs de IMAP trata-se de um mtodo de acesso a mensagens eletrnicas
armazenadas em um servidor local ou remoto.
O mtodo ir se conectar de acordo com os dados informados atravs do mtodo init().

Obs.:Uma caracterstica importante do IMAP permitir que a manipulao de
mensagens e pastas seja feita como se estivessem no computador local. Sempre que
for estabelecida uma conexo com servidor IMAP atravs da funo
imapConnect() importante finalizar a conexo utilizando a imapDisconnect().
Sintaxe
oObj:IMAPDISCONNECT ( ) --> lRet
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possvel realizar a finalizao da conexo no
servidor Imap, false caso contrrio.
Descrio
Mtodo IMAPDISCONNECT usado apenas para conexo IMAP.
O mtodo IMAPDisConnect() da classe TMailManager tem como objetivo realizar o
fim da conexo entre a aplicao e um IMAP e-mail server.
Obs.: sempre que for estabelecida uma conexo com servidor IMAP atravs da funo
imapConnect() importante finalizar a conexo utilizando a disconnect.
Sintaxe
oObj:IMAPSTORE ( < cFolder > , < oMsg > ) --> nRet
Parmetros
Argumento
Tipo
Descrio
Representa uma String que contm o nome da
Caracter
pasta(folder) no qual desejamos armazenar a mensagem.
Indica um objeto tMailMessage que contem as
Objeto
informaoes da mensagem que desejamos armazenar.
cFolder
oMsg
Retorno
Tipo
Numrico
Descrio
Retorna um inteiro informando o status da operao, caso retornado 1
ocorreu erro durante a funo, caso contrario retorna outros valores de
informao.
Descrio
Mtodo IMAPSTORE usado apenas para conexo IMAP
O mtodo imapStore() da classe tMailManager tem como objetivo armazenar uma
determinada mensagem em algum folder do servidor IMAP.
Obs.: A funo muito util quando por exemplo desejamos que ao enviar uma
mensagem ela seja salva em alguma pasta do server IMAP.
Sintaxe
oObj:INIT ( < cPopImap > , < cSmtp > , < cUser > , < cPass > , < nTimeOut > , <
nPorta > ) --> NIL
Parmetros
Argumento
cPopImap
cSmtp
cUser
cPass
nTimeOut
nPorta
Tipo
Descrio
Endereo do servidor POP ou IMAP, no caso de conexo
Caracter
SMTP passe esse como ""(branco).
Endereo do servidor SMTP, no caso de conexo POP
Caracter
passe esse como ""(branco)
Caracter Login no servidor.
Caracter Senha no servidor.
Numrico Time out para a conexo.
Numrico Porta para se conectar.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo INIT
Atravs desse mtodo da classe tMailManager, iniciamos uma nova conexo com um
servidor de emails POP ou SMTP.
Quando informamos por argumento o servidor pop (Ex.: pop3.microsiga.com.br) que
siginifica o protocolo usado na internet para a recebimento de mensagens ao usurio
final e o servidor smtp (Ex.: smtp.microsiga.com.br) que siginifica o protocolo usado
na internet para a envio de mensagens ao usurio final, devemos tambm informar um
usuario que esteja devidamente cadastrado no servidor e sua senha.
Podemos ainda informar o tempo de timeout para queda da conexo e ainda o numero
de porta, caso a porta do servidor desejado no seja a default de um smtp
Sintaxe
oObj:MOVEMSG ( < nNumMsg > , < sFolder > ) --> lRet
Parmetros
Argumento
nNumMsg
sFolder
Tipo
Descrio
Valor numerico da mensagem no servidor de email
Numrico
IMAP.
Indica o nome da pasta no servidor de email IMAP, no
Caracter
Retorno
Tipo
Lgico
Descrio
mover para a pasta informada, false caso contrrio.
Descrio
Mtodo MOVEMSG usada apenas para conexo IMAP.
A funo MoveMsg() da classe tMailManager tem como objetivo mover uma
IMAP para uma outra pasta no servidor.
quando usamos funoes que lidam com os folder como changeFolder(), createFolder()
ou deleteFolder().
Para mover uma mensagem devemos informar qual mensagem queremos mover atravs
criado no servidor)
Sintaxe
tMailManager():NEW ( ) --> oObjtMailManager
Retorno
Tipo
Objeto
Descrio
Retorna uma nova instncia do Objeto da Classe tMailManager.
Descrio
Contrutor da Classe tMailManager.
Retorna uma nova instncia do Objeto da Classe tMailManager.
Antes da utilizao das funes e/ou propriedades da classe de email necessario
criarmos uma instancia da classe atravs do contrutor New().
Sintaxe
oObj:POPCONNECT ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo POPCONNECT
O mtodo PopConnect() da classe TmailManager se conecta com o servidor de email,
atravs dos parametros que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor POP, ou seja, apenas realizaremos
o recebimento das mensagens existentes na caixa postal do usuario informado.
Sintaxe
oObj:POPDISCONNECT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna 0 quando for Disconectado, outro valor caso contrrio.
Descrio
Mtodo POPDISCONNECT
O mtodo POPDisconnect() da classe TMailManager ir realizar o fim da conexo com
o servidor POP, se desconectando apenas com o servidor POP.
Ao solicitar a finalizao da conexo com o servidor POP, a funo ir retornar o status
da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso
contrrio.
Sintaxe
oObj:PURGE ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo PURGE usado apenas para conexo IMAP
O metodo purge() da classe tMailManager
Sintaxe
oObj:RENAMEFOLDER ( < sOldFolder > , < sNewFolder > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
Representa o nome atual que a pasta tem no servidor de
email IMAP, o valor aqui informado deve ser idntico ao
Caracter
gravado no servidor, caso contrrio a pasta no ser
encontrada.
Indica o novo nome no qual desejamos atribuir para a
Caracter
pasta.
sOldFolder
sNewFolder
Retorno
Tipo
(NULO)
Descrio
Retorna true caso tenha sido possvel realizar a mudana de nome das
pastas, false caso contrrio.
Descrio
Mtodo RENAMEFOLDER usado apenas para conexo IMAP.
A funo RenameFolder() da classe tMailManger tem como objetivo realizar a mudana
entre os nomes da pastas no servidor de e-mails IMAP.
Sintaxe
oObj:SENDMAIL ( < sFrom > , < sTo > , < sSubject > , < sBody > , [ sCC ] , [ cBCC ]
, [ aAttach ] , [ nNumAttach ] ) --> nRet
Parmetros
Argumento
sFrom
sTo
sSubject
sBody
sCC
cBCC
aAttach
nNumAttach
Tipo
Descrio
Indica uma conta de email no qual ser usada para
Caracter representar de quem foi mandado o email. Ex:
Deusuario@microsiga.com.br
Indica a conta de email no qual ser usada para enviar o
Caracter respectivo email.
Ex: Parausuario@microsiga.com.br
Representa o assunto do email ou mensagem, que ser
Caracter
enviado para a conta de email indicada.
Caracter Representa o conteudo da mensagem que ser enviada.
Opcional. Parametro para adicionar endereos ao qual
Caracter
ser enviado na seo Com Cpia(CC).
Opicional. Parametro para adicionar endereos de email
Caracter
no qual ser enviado na seo Com Cpia Oculta(BCC)
Opcional. Parametro no qual podemos informar um Array
Array
de strings contento de o Path dos arquivos que desejamos
enviar como atachados ao email.
Opicional. Quando desejamos enviar arquivos atachados
devemos informar esse argumento que contem a
Numrico
quandidade de arquivos que sero atachados no email, no
caso a quantidade de elementos do array.
Retorno
Tipo
(NULO)
Descrio
Retrona 0, quando o E-mail for enviado com sucesso, outro valor qualquer
caso contrario.
Descrio
Mtodo SENDMAIL
O mtodo SendMail() da classe TMailManager tem a funo de mandar um e-mail de
acordo com os dados passados por parametro para a funo.
Ao informar os parametros que representam os destinatarios pode-se informar mais de
uma conta de email, porm devidamente separada por ; Ex.: user1@server.com.br;
user2@server.com.br
Sintaxe
oObj:SETFOLDERSUBSCRIBE ( < cFolder > , < lAssinado > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
Representa o nome do folder no servidor de email IMAP
Caracter
que desejamos deixar subscribe ou no.
True caso desejamos que o folder esteja
Lgico
assinado(subscribe), falso caso contrrio.
cFolder
lAssinado
Retorno
Tipo
Lgico
Descrio
Retorna true caso a operao tenha sido realizada com sucesso, falso caso
contrrio.
Descrio
Mtodo SETFOLDERSUBSCRIBE usado apenas para conexo IMAP.
A funo setFolderSubscribe da classe tMailManager tem como objetivo tornar uma
pasta do servidor de email IMAP assinada.
Tornar uma pasta assinada, tem um significado parecido como deixa-l visivel em nossa
caixa de email, as mensagens para esta pasta sero 'baixadas'.
A pasta Inbox por exemplo, sempre assinada por default.
Sintaxe
oObj:SETMSGFLAG ( < nNumMsg > , < sFlag > ) --> lRet
Parmetros
Argumento
Tipo Descrio
Indica o numero da mensagem que desejamos alterar seu
Array
status(flag).
Array Informa o novo status que desejamos para a mensagem.
nNumMsg
sFlag
Retorno
Tipo
Lgico
Descrio
Retorna true caso a mensagem tenha sido setada corretamente, caso
contrrio false.
Descrio
Mtodo SETMSGFLAG usado apenas para conexo IMAP.
A funo SetMsgFlag() da classe tMailManager tem como objetivo indicar o status

para uma determinada mensagem indicada de acordo com o parametro informado para a
funo.
Os estados possiveis para setar na mensagem so:
A = ANSWERED, F = FLAGGED, D = DELETED, S = SEEN, R = DRAFT, C = RECENT, P =
SPECIAL
Sintaxe
oObj:SETPOPTIMEOUT ( < nTimeOut > ) --> nRet
Parmetros
Argumento
nTimeOut
Tipo
Descrio
Numrico Tempo para que a conexo seja fechada por Time-Out.
Retorno
Tipo
Numrico
Descrio
0 = Time out setado
Descrio
Mtodo SETPOPTIMEOUT
O mtodo SetPopTimeOut() da classe tMailmanager ir configurar um tempo para que
uma conexo estabelecida com servidor POP seja finalizada por time-out.
Obs.: O tempo informado pelo mtodo deve ser em segundos.
Sintaxe
oObj:SETSMTPTIMEOUT ( < nTime > ) --> nRet
Parmetros
Argumento
nTime
Tipo
Descrio
Numrico Tempo para que a conexo seja fechada por Time-Out.
Retorno
Tipo
Descrio
Numrico
0 - Time out configurado
Descrio
Mtodo SETSMTPTIMEOUT
O mtodo SetSMTPTimeOut() da classe tMailmanager ir configurar um tempo para
que uma conexo estabelecida com servidor SMTP seja finalizada por time-out.
Obs.: O tempo informado pelo mtodo deve ser em segundos.
Sintaxe
oObj:SETUSEREALID ( < lOpt > ) --> NIL
Parmetros
Argumento
Tipo
Descrio
Indica qual tipo de Identificador deseja-se usar, caso
Lgico informado true ser usado o ID real da mensagem, caso
informado false ser usado o numero da mensagem.
lOpt
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SETUSEREALID usado apenas para conexo IMAP.
A funo SetUseRealID() da classe tMailManager tem como objetivo definir qual id
ser usado para busca das mensagens.
Uma mensagem de email possui dois modos de se identificada no servidor IMAP:
-Atravs do seu nmero(o servidor mantm um 'contador' do numero de mensagens
que chegam para determinada conta e atribui esse numero a mensagem. Ex: Imagine
uma conta que acabou de ser criada, ao receber sua 1 msg, esta recebera um
identificador de numero 1 e assim por diante..).
-Atravs de um ID nico que o servidor atribui para a mensagem.
Por default as funoes usam o numero da mensagem, podemos usar a funo
SetUseRealID() para mudar isso, passando um parametro booleano para a funo.
Sintaxe
oObj:SMTPCONNECT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
0 - Conectado
Descrio
Mtodo SMTPCONNECT
O mtodo SMTPConnect() da classe TmailManager se conecta com o servidor de email,
atravs dos parametros que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor SMTP, ou seja, apenas
realizaremos o envio de mensagens para uma determinada conta de usuario, informados
anteriormente pelo metodo INIT().
Sintaxe
oObj:SMTPDISCONNECT ( ) --> nRet
Retorno
Tipo
(NULO)
Descrio
0 = Disconectado
Descrio
Mtodo SMTPDISCONNECT
O mtodo SMTPDisconnect() da classe TMailManager ir realizar o fim da conexo
com o servidor SMTP, se desconectando apenas com o servidor SMTP.
Ao solicitar a finalizao da conexo com o servidor SMTP, a funo ir retornar o
status da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso
contrrio.
Sintaxe
oObj:STARTGETALLMSGHEADER ( < sFOlder > , < aHeader > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
sFOlder
Caracter
aHeader
Array
Indica qual o folder no servidor que desejamos obter os

cabealhos das mensagens.
Array que representa as informaoes que desejamos serem
retornadas nos cabealhos das mensagens.
Retorno
Tipo
Descrio
Retorna true caso tenha sido possivel iniciar o processo de obteno de
cabealho das mensagens, false caso contrario.
Lgico
Descrio
Mtodo STARTGETALLMSGHEADER usado apenas para conexo IMAP.

A funo StartGetAllMsgHeader() da classe tMailManager tem como objetivo dar
inicio ao processo de obteno de todos os cabealhos(headers) de todas as mensagens
de uma determinada pasta.
A funo ir avisar ao servidor IMAP que um processo de obteno das mensagens vai
ocorrer, definindo qual a pasta(folder) deve se iniciar o processo e qual as infomao no
header da mensagem deve ser retornada.
obs.: a funo apenas inicia o processo, para pegar os cabealhos das mensagens da
pasta use a funo EndGetAllMsgHeader().
Tmailmessage
Este exemplo tem como objetivo principal mostrar o uso dos mtodos da classe
tMailMessage. Para isto usamos a classe tMailManager(responsavel por estabelecer a
conexo de fato).
A classe tMailMessage possu uma dependencia direta com a classe tMailManager,
devemos imaginar a classe tMailMessage como a mensagem que ser enviada de fato
e tendo atravs dos mtodos e propriedades a forma que iremos preencher os dados
necessrios para um email como: Assunto, Corpo da Mensagem, 'Com Cpia', etc..
Assim atravs da classe podemos customizar tambm a mensagem que queremos
enviar. Acompanhe o exemplo abaixo.
#include "Protheus.ch"
user Function EMail()
Local oServer
Local oMessage
Local nNumMsg := 0
Local nTam
Local nI
:= 0
:= 0
//Crio a conexo com o server STMP ( Envio de e-mail )

oServer := TMailManager():New()
oServer:Init( "", "smtp.microsiga.com.br", "ricardo.reis",
"rica4758", 0, 25 )
//seto um tempo de time out com servidor de 1min
If oServer:SetSmtpTimeOut( 60 ) != 0
Conout( "Falha ao setar o time out" )
Return .F.
EndIf
//realizo a conexo SMTP
If oServer:SmtpConnect() != 0
Conout( "Falha ao conectar" )
Return .F.
EndIf
//Apos a conexo, crio o objeto da mensagem
oMessage := TMailMessage():New()
//Limpo o objeto
oMessage:Clear()
//Populo com os dados de envio
oMessage:cFrom
:= "Microsiga "
oMessage:cTo
:=
"microsiga@microsiga.com.br;microsiga@microsiga.com.br"
oMessage:cCc
:= "microsiga@microsiga.com.br"
oMessage:cBcc
:= "microsiga@microsiga.com.br"
oMessage:cSubject
:= "Teste de Email"
oMessage:cBody
:= "Conteudo do e-mail"
//Adiciono um attach
If oMessage:AttachFile( "arquivo.txt" ) < 0
Conout( "Erro ao atachar o arquivo" )
Return .F.
Else
//adiciono uma tag informando que um attach e o nome
do arq
oMessage:AddAtthTag( 'Content-Disposition: attachment;
filename=arquivo.txt')
EndIf
//Envio o e-mail
If oMessage:Send( oServer ) != 0
Conout( "Erro ao enviar o e-mail" )
Return .F.
EndIf
//Disconecto do servidor
If oServer:SmtpDisconnect() != 0
Conout( "Erro ao disconectar do servidor SMTP" )
Return .F.
EndIf
//Crio uma nova conexo, agora de POP
oServer := TMailManager():New()
oServer:Init( "pop3.microsiga.com.br", "", "SeunomeAntesDo@",
"senhaDoEmail", 0, 110 )
If oServer:SetPopTimeOut( 60 ) != 0
Conout( "Falha ao setar o time out" )
Return .F.
EndIf
If oServer:PopConnect() != 0
Conout( "Falha ao conectar" )
Return .F.
EndIf
//Recebo o nmero de mensagens do servidor
oServer:GetNumMsgs( @nNumMsg )
nTam := nNumMsg
For nI := 1 To nTam
//Limpo o objeto da mensagem
oMessage:Clear()
//Recebo a mensagem do servidor
oMessage:Receive( oServer, nI )
//Escrevo no server os dados do e-mail recebido
Conout( oMessage:cFrom )
Conout( oMessage:cTo )
Conout( oMessage:cCc )
Conout( oMessage:cSubject )
Conout( oMessage:cBody )
Next
//Deleto todas as mensagens do servidor
For nI := 1 To nTam
oServer:DeleteMsg( nI )
Next
//Diconecto do servidor POP
oServer:POPDisconnect()
Return .T.
Sintaxe
oObj:ADDATTHTAG ( < cTag > ) --> NIL
Parmetros
Argumento
Tipo
Descrio
Representa os dados que desejamos informa no caso de um
Caracter
arquivo atachado.
cTag
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo ADDATTHTAG
O mtodo addAttTag() da classe tMailMessage tem como objetivo setar alguma
informao especial quando passado algum arquivo atachado para a mensagem que
ser enviada.
Ex: AddAtthTag( 'Content-Disposition: attachment; filename=arquivo.txt')
adiciono uma tag informando que um attach e o nome do arquivo.
Sintaxe
oObj:ATTACHFILE ( < cArq > ) --> NIL
Parmetros
Argumento
cArq
Tipo
Descrio
Caracter Indica o nome do arquivo a ser adicionado no e-mail.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo ATTACHFILE
O mtodo AttachFile() da classe tMailMessage tem como objetivo adicionar um arquivo
ao objeto de e-mail, 'um Attach'.
Sintaxe
oObj:CLEAR ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo CLEAR
O mtodo clear() da classe tMailMessage tem como objetivo limpar o conteudo do

objeto, assim podemos receber varias mensagem no mesmo objeto, apenas limpando o
seu conteudo antes.
Usando a funo clear, nao precisamos criar varias vezes o mesmo objeto, para receber
mais de uma mensagem.
Sintaxe
oObj:GETATTACH ( < cNumMsg > ) --> sRet
Parmetros
Argumento
cNumMsg
Tipo
Descrio
Representa o Id(numero da mensagem) que desejamos
Numrico
obter informaes.
Retorno
Tipo
Caracter
Descrio
Retorno uma String(cadeia de caracteres) contendo o conteudo do arquivo
atachado na mensagem.
Descrio
Mtodo GETATTACH
O mtodo getAttach da classe tMailMessage tem como objetivo obter o conteudo do
arquivo atachado e retornar esse conteudo atravs de uma String.
Devemos informar o numero da mensagem que desejamos obter o attach.
Sintaxe
oObj:GETATTACHCOUNT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna o numero de anexos a mensagem.
Descrio
Mtodo GETATTACHCOUNT
O mtodo getAttachCount() da classe tMailMessage tem como objetivo informar qual a

quantidade de arquivos anexados a mensagem.
Sintaxe
oObj:GETATTACHINFO ( < nMsg > ) --> NIL
Parmetros
Argumento
nMsg
Tipo
Descrio
Numrico Indica o numero da mensagem que desejamos verificar.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo GETATTACHINFO
O mtodo getAttachInfo() da classe tMailMessage tem como objetivo trazer todas
informaoes sobre um attachment em alguma mensagem.
Devemos informar o numero da mensagem que desejamos trazer as informaoes sobre
os attachments, o mtodo ir retornar as seguintes informaes:
ShortName: O nome do attachment
Type: O tipo do attachment, podendo ser FILE e TEXT por exemplo.
Disposition: Tipo do arquivo
DispositionName: informa o nome do tipo de arquivo
Id: Identificao do attachment
Location: Local fisico do attachment
Sintaxe
tMailMessage():NEW ( ) --> oObjtMailMessage
Retorno
Tipo
Objeto
Descrio
Retorna uma nova instncia do Objeto da Classe tMailMessage.
Descrio
Contrutor da Classe tMailMessage.

Retorna uma nova instncia do Objeto da Classe tMailMessage, representa uma
mensagem
Sintaxe
oObj:RECEIVE ( < oServer > , < nMsg > ) --> nRet
Parmetros
Argumento
Tipo
Descrio
Indica o Objeto do servidor POP, criado atraves no
Memo
obejeto TMailManager.
Indica o Nmero da mensagem a ser criada, recebido
Numrico
atraves do metodo TMailManager:GetNumMsgs.
oServer
nMsg
Retorno
Tipo
Numrico
Descrio
Retorna 0(zero) quando o E-mail foi recebido com sucesso, outro valor
caso contrrio.
Descrio
Mtodo RECEIVE
O mtodo receive() da classe tMailMessage, tem como objetivo receber uma nova
mensagem do servidor populando o objeto da mensagem.
Sintaxe
oObj:SAVE ( < cNumMsg > ) --> NIL
Parmetros
Argumento
cNumMsg
Tipo Descrio
Array Representa o numero da mensagem que desejamos salvar.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SAVE
O mtodo save() da classe tMailMessage tem como objetivo obter todo o conteudo de
uma determinada mensagem, que ser encontrada atravs do parametro informado, que
repesenta o Id(numero da mensagem) e salvar a mensagem.
Sintaxe
oObj:SEND ( < oServer > ) --> NIL
Parmetros
Argumento
Tipo
Descrio
Indica o objeto da classe tMailManager para o envio da
Objeto
mensagem.
oServer
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SEND
O mtodo Send() da classe TMailMessage tem a funo de enviar um e-mail de acordo
com os dados passados pelo objeto da classe tMailManager por parametro para a
funo.
Para que a funo seja usada corretamente preciso antes popular algumas das
propriedades da classe tMailMessage basicas para o envio como:
cFrom: Email de quem est mandando.
cTo: Email(s) para o qual desejamos enviar a mensagem.
cCc: Email(s) para o qual desejamos enviar a mensagem na seo "com cpia".
cBcc: Email(s) para o qual desejamos enviar a mensagem na seo "com cpia Oculta".
cSubject: Assunto da mensagem que ser enviada.
cBody: Conteudo da mensagem.
Descrio
Esta classe permite estabelecer uma conexo cliente de socket do tipo TCP genrica.
Enviar e receber dados atravs de uma socket genrico e tambm pode ser usada como
base para implementao de protocolos no suportados pelo protheus.
Mtodos
Mtodo
CloseConnection
Connect
IsConnected
New
Receive
Reset
Send
Descrio
Finaliza a conexo TCP genrica (socket ) do objeto corrente.
Estabelece um conexo TCP genrica (socket ).
Verifica se existe conexo valida no objeto corrente.
Cria o objeto tSocketClient, sem conexo ativa.
Recebe os dados pela conexo ativa do objeto, qualquer tipo de
dado pode ser recebido.
Finaliza anormalmente a conexo, no avisa o outro lado que a
conexo ser finalizada.
Deve ser utilizado apenas em casos extremos.
Transmite o buffer pela conexo TCP Genrica ativa.
O Exemplo abaixo exemplifica a utilizao de um cliente socket, note que para o

programa funcionar corretamente, deve-se alterar os parametros da conexo.
user function MySocket
Local oObj := tSocketClient():New()
nResp := oObj:Connect( 999, "172.255.255.255", 1000 )
if(nResp == 0 )
Conout( "Conexo OK!" )
else
Conout( "Erro na Conexo OK! ", nResp )
return
endif
cSend = "Ola!!!! Estou transmitindo um dado!"
nResp := oObj:Send( cSend )
if( nResp != len( cSend ) )
conout( "Erro! Dado nao transmitido" )
else
conout( "Dado Enviado" )
endif
cBuffer := ""
nQtd = oObj:Receive( cBuffer, 10000 )
if( nQtd >= 0 )
conout( "Dados Recebidos " + Str( nQtd, 4, 0 ), cBuffer )
else
conout( "Nao recebi nada" )
endif
cSend = "Dados que ser transmitido!!!"
nResp := oObj:Send( cSend )
if( nResp != len( cSend ) )
conout( "Erro! Dado nao transmitido" )
else
conout( "Dado Enviado" )
endif
if( oObj:IsConnected() )
conout( "OK! Estou conectado" )

else
conout( "Ops! Nao estou conectado" )
endif
oObj:CloseConnection()
if( !oObj:IsConnected() )
conout( "Desconectei" )
else
conout( "Ainda estou conectado, erro na desconexao" )
endif
return
Sintaxe
oObj:CloseConnection ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Sintaxe
oObj:CloseConnection ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Abrangncia
Verso 6.09
Verso 7.10
Verso 8.11
Sintaxe
oObj:IsConnected ( ) --> lLogico

Retorno
Tipo
Lgico
Descrio
Retorna True se a conexo esta ativa e false caso esteja
invlida/desconectado.
Descrio
Verifica se existe conexo valida no objeto corrente.
Sintaxe
tSocketClient():New ( ) --> oSocket
Retorno
Tipo
Objeto
Descrio
Retorna um Objeto do tipo tSocketClient
Descrio
Cria o objeto tSocketClient, sem conexo ativa.
Sintaxe
oObj:Receive ( < @cBuffer > , < nTimeout > ) --> nQtdRecebida
Parmetros
Argumento
cBuffer
nTimeout
Tipo
Descrio
Caracter Buffer que conter os dados a serem recebidos.
tempo em milisegundos que a funo receive espera at
Numrico
receber algum dado pela conexo.
Retorno
Tipo
Numrico
Descrio
Qtde de bytes recebidos, se houver algum erro nQtdRecebida ser menor
que zero.
Descrio
Recebe os dados pela conexo ativa do objeto, qualquer tipo de dado pode ser recebido.
Sintaxe
oObj:Reset ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Finaliza anormalmente a conexo, no avisa o outro lado que a conexo ser finalizada.
Deve ser utilizado apenas em casos extremos.
Sintaxe
oObj:Send ( [ cBuffer ] ) --> nQtdTrasmitido
Parmetros
Argumento
cBuffer
Tipo
Descrio
Caracter Buffer com os dados a serem transmitidos pela conexo.
Retorno
Tipo
Numrico
Descrio
Numero de bytes transmitidos, caso o numero seja diferente do tamanho
de cBuffer, algum erro aconteceu.
Descrio
Transmite o buffer pela conexo TCP Genrica ativa.
BANCO DE DADOS
Copy
Sintaxe
COPY [ FIELDS <campo,...> ] TO xcFile [ escopo ] [ WHILE <lCondicao> ] [ FOR
<lCondicao> ] [ SDF | DELIMITED [WITH <xcDelimiter>] ] [ VIA <xcDriver> ]
Parmetros
Argumento
FIELDS
<campo,...>
TO xcFile
Tipo
Descrio
FIELDS <campo,...> especifica um ou mais campos,
separados por vrgula, a serem copiados para a tabela de
Caracter
destino. Caso no especificado este parmetro, sero
copiados todos os campos da tabela de origem.
TO <xcFile> especifica o nome do arquivo de destino. O
nome do arquivo de destimno pode ser especificado de
forma literal direta, ou como uma expresso Advpl, entre
parnteses.
Caracter
Caso sejam especificadas as clusulas SDF ou
DELIMITED, gerado um arquivo ASCII, com extenso
.txt por default.
<escopo> define a poro de dados da tabela atual a ser
coipiada. Por default, so copiados todos os registros
(ALL). Os escopos possveis de uso so:
escopo
ALL - Copia todos os registros.

REST - Copia, a partir do registro atualmente posicionado,
Caracter at o final da tabela.
NEXT <n> - Copia apenas <n> registros, iniciando a partir
do registro atualmente posicionado.
OBSERVAO : Vale a pena lembrar que o escopo

sensvel tambm s demais condies de filtro ( WHILE /
FOR ).
WHILE <lCondicao> permite especificar uma condio
para realizao da cpia, a partir do registro atual,
WHILE
Lgico executada antes de inserir cada registro na tabela de
<lCondicao>
destino, sendo realizada a operao de cpia enquanto esta
condio for verdadeira.
FOR <lCondicao> especifica uma condio para cpia de
registros, executada antes de inserir um registro na tabela
FOR <lCondicao> Lgico
de destino, sendo a operao realizada apenas se
lCondicao ser verdadeira ( .T. )
[ SDF | DELIMITED [WITH <xcDelimiter>] ]
[ SDF |
DELIMITED
[WITH
<xcDelimiter>] ]
SDF especifica que o tipo de arquivo de destino gerado

um arquivo no formato "System Data Format" ASCII,
onde registros e campos possuiem tamanho fixo no
arquivo de destino.
Caracter
DELIMITED especifica que o arquivo ASCII de destino

ser no formato delimitado, onde os campos do tipo
Caractere so delimitados entre aspas duplas ( delimitador
Default ). Registros e campos tm tamanho varivel no
arquivo ASCII.
DELIMITED WITH <xcDelimiter> permite especificar
um novo caractere, ou sequncia de caracteres, a ser

utilizada como delimitador, ao invs do default ( aspas
duplas ). O caractere delimitador pode ser escrito de forma
literal, ou como uma expresso entre parnteses.
Nas Tabelas complementares A e B, na documentao do
comando, so detalhadas as especificaes dos formatos
SDF e DELIMITED.
VIA <xcDriver> permite especificar o driver utilizado para
criar a tabela de destino dos dados a serem copiados.
VIA <xcDriver>
Caracter
O Driover deve ser especificado como uma expresso

caractere. Caso especificado como um valor literal direto,
o mesmo deve estar entre aspas.
Descrio
COPY TO um comando de banco de dados, que permite a cpia de todos ou parte
dos registros da tabela atualmente selecionada na rea de trabalho atual, para um novo
arquivo. Os registros considerados para a cpia podem ser limitados pela clusula
<escopo>, atravs de expresses FOR / WHILE , e/ou atravs de um filtro.
Se o filtro para registros deletados ( SET DELETED ) estiver desligado (OFF),
registros deletados ( marcados para deleo ) so copiados para o arquivo de destino,
mantendo este status. Caso contrrio, nenhum registro deletado copiado. Da mesma
maneira, caso exista uma condio de filtro na tabela atual ( SET FILTER ), apenas os
registros que satisfaam a condio de fintro sero copiados.
Os registros so lidos na tabela atual, respeitando a ordem de ndice setada. Caso no
hajam ndices abertos, ou a ordem de navegao nos ndices (SET ORDER ) seja 0
(zero), os registros so lidos em orden natural ( ordem de RECNO ) .
A tabela de destino dos dados copiados criada, e aberta em modo exclusivo, antes
da operao de cpia efetiva ser iniciada.
Tabela A : Especificao do formato SDF ( System Data Format )
Elemento do Arquivo
Campos 'C' Caractere
Campos 'D' Data
Campos 'L' lgicos
Campos 'M' Memo
Campos 'N' Numricos
Delimitador de Campos
Separador de Registros
Marca de final de arquivo
(EOF)
Formato
Tamanho fixo, ajustado com espaos em branco
Formato aaaammdd ( ano, ms, dia )
T ou F
(campo ignorado)
Ajustados direita, com espaos em branco.
Nenhum
CRLF ( ASCII 13 + ASCII 10 )
Nenhum
Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED WITH

<xcDelimiter> )
Elemento do Arquivo
Campos 'C' Caractere
Campos 'D' Data
Campos 'L' lgicos
Campos 'M' Memo
Campos 'N' Numricos
Delimitador de Campos
Separador de Registros
Marca de final de arquivo
(EOF)
Formato
Delimitados, ignorando espaos direita
Formato aaaammdd ( ano, ms, dia )
T ou F
(campo ignorado)
sem espaos em branco.
Vrgula
CRLF ( ASCII 13 + ASCII 10 )
Nenhum
Observaes
A Linguagem Advpl, antes do Protheus, suportava a gerao de uma tabela

delimitada diferenciada, obtida atravs do comando COPY TO (...) DELIMITED
WITH BLANK . No Protheus este formato no suportado. Caso utilize-se este
comando com a sintaxe acima, o arquivo ASCII gerado ser delimitado,
utilizando-se a sequncia de caracteres 'BLANK' como delimitadora de campos
Caractere.
COPY STRUCTURE
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Sintaxe
COPY STRUCTURE TO <xcDataBase>
Parmetros
Argumento
Tipo
Descrio
Deve ser especificado em xcDatabase o nome da tabela a
TO <xcDataBase> Caracter
ser criada.
Descrio
COPY STRUCTURE um comando de banco de dados, que cria uma nova tabela,
vazia, com a estrutura da tabela ativa na rea de trabalho atual. Se a tabela a ser criada j
exista, a mesma sobrescrita. A tabela de destino criada utiliza o mesmo RDD da tabela
de origem ( tabela ativa na rea de trabalho atual ).
Observaes
A Linguagem Advpl, antes do Protheus, suportava a parametrizao de uma lista

de campos da tabela atual, para compor a estrutura da tabela de destino, atravs
da clusula FIELDS <campo,...>. Esta opo no suportada no Protheus. Caso
seja utilizada, o programa ser abortado com a ocorrncia de erro fatal :
'DBCopyStruct - Parameter <Fields> not supported in Protheus'
FUNES GENRICAS
Sintaxe
EXISTDIR ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo ExistDir tem como objetivo determinar se um path de diretrio existe e
valido.
Exemplo no server a partir do rootPath:
ExistDir('\teste')
Exemplo no client, passando o fullPath:
ExistDir('c:\APO')
Sintaxe
FTPVERSION ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
Retorna uma String contendo o valor da verso de FTP.
Descrio
A funo FtpVersion tem como objetivo determinar qual a verso do Protocolo de
Transferncia de Arquivos.
Sintaxe
GETCOMPUTERNAME ( ) --> Nome da mquina
Retorno
Tipo
Caracter
Descrio
Nome da mquina
Descrio
Retorna o nome da mquina (HOSTNAME) que est executando o Protheus Remote
Sintaxe
GETENV ( < cVariavel > ) --> cRet
Parmetros
Argumento
Tipo
Descrio
Nome da variavel de ambiente do sistema que desejamos
Caracter
obter.
cVariavel
Retorno
Tipo
Caracter
Descrio
Retorna o contedo da varivavel de ambiente, se encontrada na tabela de
variaveis de sistema. Caso contrrio, retorna NIL.
Descrio
A funo GetEnv() tm como objetivo determinar o valor de uma
varivel do environment da plataforma(Sistema Operacional) em uso, no ambiente do
Protheus Server.
O valor de retorno da funo ser NIL se o parametro varname informado no for
encontrado na tabela das variveis de ambiente do Sistema Operacional.
Exemplo:
cSysPath := GetEnv('PATH')
Sintaxe
GETENVSERVER ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
String contendo o nome do environment em execuo.
Descrio
A funo GetEnvServer() tem como objetivo retornar uma string que nos permite
determinar o nome do Environment que est rodando atualmente no Server Protheus.
Um exemplo interessante da funo quando desejamos rodar um programa e nao
sabemos em qual environment estaremos.
StartJob('Teste', GetEnvServer(), .T., '99', '01' )
Sintaxe
GETREMOTETYPE ( ) --> nRmtType
Retorno
Tipo
Numrico
Descrio
nRmtType corresponde o nmero correspondente interface utilizada.
Descrio
Atravs da funo GetRemoteType(), possvel identificar sob qual interface o
programa atual est em execuo.
Esta funo est disponvel a partir do Protheus 8, Build 7.00.040308a
Pode-se utilizar as constantes abaixo, para avaliar o retorno da funo.
NO_REMOTE
REMOTE_QT_WIN32
REMOTE_QT_LINUX
-1 // Job, Web ou Working Thread ( Sem remote )

1 // Remote em ambiente Windows
2 // Remote em ambiente Unix/Linux
Sintaxe
GETSCREENRES ( ) --> Resoluo[2]
Retorno
Tipo
Array
Descrio
Retorno da funo onde:
Resoluo[1] = Resoluo horizontal
Resoluo[2] = Resoluo vertical
Descrio
Retorna Array com a resoluo de tela da mquina executando o Protheus Remote
Sintaxe
IPCCount ( < cSemaforo > ) --> nRet
Parmetros
Argumento
Tipo
Descrio
Indica o local ou Semafora em que as Threads foram
Caracter
iniciados.
cSemaforo
Retorno
Tipo
Numrico
Descrio
A funo retorna um inteiro indicando oo numero de Threads LIVRES de
acordo com o semaforo indicado por parametro.
Descrio
A funo IPCCount tem como objetivo obter todas as Threads que esto no ar em um
determinado ambiente indicado pelo semaforo.
A funo ir retornar um inteiro indicando o total de threads livres que esto esperando
um IPCGo.
Sintaxe
IPCGo ( < cSemaforo > ) --> Nil
Parmetros
Argumento
Tipo
Descrio
Indica o local ou Semaforo em que as Threads foram
Caracter
iniciados.
cSemaforo
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo IPCGo tem como objetivo mandar uma chamada para uma Thread, na qual
nao precisa ser necessariamente em mesmos ambientes, que esteja em wait.
A IPCGo devemos atravs de um primeiro argumento da funo, especificar o semaforo
que desejamos, a funo ir pegar a primeira Thread Livre que encontrar em
IPCWait.
A funo recebe mais 15 argumentos opcionais para passagem de dados, porm este
valor no pode ser um Boolean ou um CodeBlock.
Sintaxe
IPCWait ( < nTimeOut > ) --> lRet
Parmetros
Argumento
nTimeOut
Tipo
Descrio
Numerico que Indica um tempo de timeOut em
Numrico
milissegundos, para a thread sair do ar.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao
recebeu nehuma chamada ou saiu por timeOut.
Descrio
A funo IPCWait() tem como objetivo colocar em modo de espera uma Thread que
acabou de ser carregada e fica aguardando oo chamado de uma IPCGo(). A funo
recebe um parametro numrico que indica o timeOut em milissegundos de tempo para
que a Thread seja derrubada.
A IPCWait() recebe mais 15 parametros opcionais - que indica os parametros passados

pela IPCGo() Retorna true caso tenha chegado um chamado da IPCGo(), false no recebeu nenhum
IPCGo ou saiu por timeOut.
obs: note que nao foi indicado um valor de semaforo para a funo, pois est
implicito o programa que iniciou a Thread.
Sintaxe
IPCWaitEx ( < cSemaforo > , < nTimeOut > ) --> nRet
Parmetros
Argumento
cSemaforo
nTimeOut
Tipo
Descrio
Caracter Indica o nome do Semaforo que estamos trabalhando.
Numerico que Indica um tempo de timeOut em
Numrico
milissegundos, para a thread sair do ar.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao
recebeu nehuma chamada ou saiu por timeOut.
Descrio
A funo IPCWaitEx() tem como objetivo colocar em modo de espera uma Thread que
acabou de ser carregada e fica aguardando oo chamado de uma IPCGo(). Na
IPCWaitEx() devemos indicar o nome do semaforo que queremos.
A funo recebe como segundo parametro numrico que indica o timeOut em
milissegundos de tempo para que a Thread seja derrubada.
A IPCWaitEx() recebe mais 15 parametros opcionais - que indica os parametros
passados pela IPCGo() Retorna true caso tenha chegado um chamado da IPCGo(), false no recebeu nenhum
IPCGo ou saiu por timeOut.
Obs: note que na IPCWaitEx foi indicado um valor de semaforo para a funo.
Sintaxe
ISSRVUNIX ( ) --> lisUnix
Retorno
Tipo
Lgico
Descrio
Se .T. o servidor est sendo executado em ambiente Unix(r) ou Linux(r)
Se .F. o servidor est sendo executado em ambiente Windows(r)
Descrio
Informa se o servidor Advanced Protheus est sendo executado em ambiente UNIX ou
Linux.
Exemplo das funes IsSrvUnix e

GetRemoteIniName
Reviso: 12/06/2003
Abrangncia
Verso 6.09
Verso 7.10
Verso 8.11
Atravs do exemplo abaixo, podemos obter o path de execuo do AP Remote.

#include "protheus.ch"
Function TstRmtPath()
Local cIniName:= GetRemoteIniName()
Local lUnix:= ISSRVUNIX()
Local nPos:= Rat( IIf(lUnix,"/","\"),cIniName )
Local cPathRmt
if nPos!=0
cPathRmt:= Substr( cIniName,1,nPos-1 )
else
cPathRmt:=""
endif
QOut( cPathRmt )
Return
Sintaxe
KILLAPP ( [ lKill ] ) --> lRet

Parmetros
Argumento
Tipo
Descrio
Parametro opcional indicando se Thread corrente deve ser
Lgico
finalizada.
lKill
Retorno
Tipo
Lgico
Descrio
retorna se thread corrente j recebeu algum aviso para ser finalizada(true),
caso contrrio retorna false.
Descrio
A funo KillApp pode ser usada com dois objtivos diferentes de acordo com a
passagem de parametro.
Quando for feita uma chamada da funao KillApp sem valor de parametro nenhum
informado, a funo tem como objetivo retornar se a thread recebeu uma chamada para
ser finalizada. Um exemplo dessa situao quando atravs do monitor de tarefas do
Protheus queremos derrubar uma determinada Thread porm esperamos o final da sua
utilizao.
Exemplo:
//Thread ir ser finalizada
If KillApp()
/*tratamento de finalizao*/
Endif
Quando for realizada a chamada da Funo, passando um parametro booleano, ela tem
como objetivo finalizar a Thread no qual foi realizada a chamada da KillApp.
KillApp( .T. )
MSAPPBRINGTOFRONT ( ) --> Nil

Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Se o Protheus Remote est sendo executado em background (abaixo de outras janelas de

outros programas no desktop do usurio), a funo MSAPPBRINGTOFRONT( ) pode
ser utilizada para avisar ao sistema operacional para que mude a disposio das janelas
ativas no desktop para que exiba a janela do Protheus Remote acima de todas as janelas
das outras aplicaes em execuo.
Nos sistemas operacionais Windows, se o sistema operacional no conseguir executar o
comando para movimentar as janelas, a barras de janelas do Windows ficar piscando
sobre a ocorrncia do Protheus Remote para avisar o usurio sobre a inteno do
programa (Protheus Remote) ser visualizado.
Sintaxe
MSCRC32 ( < cString > ) --> nCRC
Parmetros
Argumento
Tipo
Descrio
String de onde ser calculado um CRC32, garantido que
para a mesma string sempre se obter um mesmo nmero,
Caracter
porm, no garantido que para strings diferentes, os
nmeros sejam sempre diferentes.
cString
Retorno
Tipo
Numrico
Descrio
Um nmero inteiro , com at 10 (dez) dgitos , correspondente ao CRC da
string informada como parmetro.
Descrio
Calcula um CRC de uma string. A funo MSCRC32() calcula um CRC de uma string
informada e retorna um nmero com esse clculo.
Note que strings iguais retornam CRC iguais, porm, nem sempre strings diferentes
retornam CRC diferentes.
Atravs do exemplo abaixo , calculamos o CRC das strings informadas.
// Le o arquivo lista.txt no ambiente do servidor
// e calcula o CRC do mesmo.
cString := memoread('\lista.txt')
nCRC1 := MSCRC32(cString)
MsgStop('CRC = '+str(nCRC1,10))
Sintaxe
MSCRC32STR ( < cString > ) --> cCRC32
Parmetros
Argumento
Tipo
Descrio
String a partir da qual ser calculado o CRC32.
garantido que para a mesma string sempre ser obtido um
Caracter
mesmo CRC , mas no garantido que para strings
diferentes os CRCs sejam sempre diferentes.
cString
Retorno
Tipo
Caracter
Descrio
Uma string com o CRC da string informada.
Descrio
MSCRC32STR() calcula um CRC de uma string informada , retornando uma string com
esse clculo.
Note que strings iguais retornam CRC iguais, porm nem sempre strings diferentes
retornam CRC diferentes.
Atravs do exemplo abaixo , calculamos o CRC das string informada.
// Le o arquivo lista.txt no ambiente do servidor
// e calcula o CRC32 do mesmo.
cString := memoread('\lista.txt')
cCRC32 := MSCRC32STR(cString)
MsgStop('CRC = ['+cCRC32+']')
Sintaxe
PROCESSMESSAGES ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Muitas vezes desenvolvemos rotinas de durao longa que quando chamadas atravs de
uma ao no Protheus Remote (Exemplo: Opo acionada no menu) provocam um
'congelamento' temporrio nas telas do Protheus Remote.
Para minimizar esse efeito, podemos utilizar a funo PROCESSMESSAGES( ) para

que o Protheus Remote possa renovar a pintura de suas janelas ou reagir a ao do
mouse durante um processamento longo sendo executado no Protheus Server. Como o
exemplo a seguir :
while nRecs<1000
ProcessMessages( )
// Processo Longo
DoSomethingLongTime( )
nRec-enddo
Cuidado: O uso intensivo da funo ProcessMessages( ) provocar trfego elevado
de rede entre o Protheus Remote e Protheus Server comprometendo o uso dos
recursos de rede na rede inteira da Empresa. Portanto a funo deve ser utilizada
com muita cautela. Cdigo como o abaixo deve ser evitado:
for i:=1 to 10
ProcessMessages( )
next i
Sintaxe
RANDOMIZE ( < nMinimo > , < nMaximo > ) --> nAleatorio
Parmetros
Argumento
nMinimo
nMaximo
Tipo
Descrio
Numrico Corresponde ao menor numero a ser gerado pela funo.
Corresponde ao maior nmero ( menos um ) a ser gerado
Numrico
pela funo.
Retorno
Tipo
Numrico
Descrio
Numero randmico , compreendido no intervalo entre (nMinimo) e
(nMaximo-1) : O numero gerado pode ser maior ou igual nMinimo e
menor ou igual a nMaximo-1 .
Descrio
Atravs da funo randomize() , geramos um numero inteiro aleatrio, compreendido
entre a faixa inferior e superior recebida atravs dos parmetros nMinimo e nMaximo,
respectivamente.
Observao :
O limite inferior recebido atravs do parmetro nMinimo "maior ou igual a ", podendo
ser sorteado e fazer parte do retorno; porm o limite superior "menor que", de modo a
nunca ser atingido ou devolvido no resultado. Por exemplo , a chamada da funo
randomize(1,2) sempre retornar 1 .
Sintaxe
SENDTOFORE ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Esta funo no retorna valor
Descrio
Esta funo torna a aplicao do Remote foreground na estao em que est sendo
executado.
Faz com que a janela ativa do Remote fique acima de todas as janelas de outras
aplicaes executadas na estao.
Extremamente dependente do sistema operacional em uso, as vezes pode falhar devido
ao sistema operacional no suportar o comando ou devido a carga excessiva do sistema,
o sistema operacional pode ignorar o comando.
Sintaxe
SOCKETCONN ( < cIP > , < nPort > , < cReq > , < nTimeOut > ) --> Nil
Parmetros
Argumento
cIP
nPort
Tipo
Descrio
Representa uma String com o endereo IP ou nome da
Caracter
mquina do destino desejado.
Numrico Indica o nmero da porta pelo qual ser realizada a
cReq
nTimeOut
conexo.
Representa a requisio que ser feita para a maquina
Caracter
desejada, assim que a conexo for estabelecida.
Indica o valor de tempo em segundos no qual a conexo
Numrico
ser encerrada por tempo de inatividade(time out).
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo SocketConn usada para criar uma conexo com um determinado destino,
atravs da conexo de um Socket Client.
Para Realizar esta conexo informamos o destino, no qual pode ser informado em forma
de IP ou atravs de um nome de mquina. Em seguida informamos o numero de
porta na qual ser realizado um bind atravs dessa porta.
Em seguida informamos atravs de string o tipo de requisio que iremos realizar, pois
quando a conexo ao socket destino completada com sucesso, a funo ir enviar e
receber dados de acordo com a requisio que fizemos.
Por ltimo informamos o total de tempo em segundos que a funo ir ficar esperando
por uma resposta do destino informado.
Sintaxe
XMLERROR ( ) --> nXmlStatus
Retorno
Tipo
Caracter
Descrio
Retorna o status da ultima operao de Criao de Objeto XML realizado
pelo comando CREATE oXml ...
Descrio
A funcao XmlError() retorna um status da execuo da ultima rotina de criao de
Objeto XML realizada pelo comando CREATE oXML. Podemos utilizar-nos das
constantes definidas no arquivo #INCLUDE "XmlxFun.CH" para realizar o tratamento
de erro. Vide tabelas de constantes abaixo :
---------------------------------------Constante Valor
----------------------------------------
XERROR_ONLYFIRSTNODE -1
XERROR_SUCCESS 0
XERROR_FILE_NOT_FOUND 1
XERROR_OPEN_ERROR 2
XERROR_INVALID_XML 3
----------------------------------------
#INCLUDE "XmlXFun.xh"
Local oXml , nXmlStatus
CREATE oXML XMLFILE "\exemplo.xml"
nXmlStatus := XMLError()
If ( nXmlStatus != XERROR_SUCCESS )
Alert("Falha ("+str(nXmlStatus,3)+") na criao do XMLl")
Else
//processamento dop XML ....
Endif
Sintaxe
compress ( < @cBufferOut > , < @nLenghtOut > , < @cBufferIn > , < @nLengthIn > )
--> bOk
Parmetros
Argumento
cBufferOut
nLenghtOut
cBufferIn
nLengthIn
Tipo
Descrio
Retorna o buffer compactado, a varivel dever ser do
Caracter
tipo caracter. O Retorno compactado conter caracteres
binrios, incluindo zero binrio.
Retorna o tamanho do buffer compactado, quando os
Numrico dados compactados so pequenos, o buffer de sada pode
ser maior que o buffer original.
Buffer que dever ser compactado, podem conter
Code-Block
caracteres binrios, o buffer pode ter no mximo 1Mb.
Numrico Tamanho do buffer a ser compactado.
Retorno
Tipo
Lgico
Descrio
Retorna .T., caso o buffer foi compactado com sucesso.
Retorna .F., caso no seja possvel compactar o buffer.
Descrio
Compacta um buffer recebido, atravs do algoritmo proprietrio.
Na maioria dos casos o buffer recebido ser menor do que o buffer original, em casos
onde o buffer original muito pequeno, menos de 128 bytes, o buffer de sada poder
ser maior do que o o buffer original.
Essa funo aceita e retorna caracteres binrios de vrios tipos, incluindo o zero binrio.
O Resultado dessa funo no dever ser gravado em banco de dados, especialmente
TopConnect.
Exemplos
user function TSTComp
Local cNaoComp := replicate( 'A', 1024 )
Local cComp := '', cResult := ''
Local nTamNaoComp := len( cNaoComp )
Local nTamComp := 0
Local bResp
bResp := compress( @cComp, @nTamComp, cNaoComp, nTamNaoComp )
If( bResp )
Alert( "Buffer Compactado - Tamanho Compactado" + str( nTamComp
) )
else
Alert( "Falha ao compactar o Buffer!" )
return
endif
bResp := uncompress( @cResult, @nTamNaoComp, cComp, nTamComp )
If( !bResp )
Alert( "Falha ao descompactar o Buffer!" )
return
endif
if( cResult != cNaoComp )
Alert( "Buffer descompactado diferente do buffer original" )
else
Alert( "Buffer descompactado igual ao buffer original" )
endif
return .t.
Sintaxe
uncompress ( < @cBufferOut > , < @nLengthOut > , < cBufferIn > , < @nLengthIn > )
--> bOK
Parmetros
Argumento
cBufferOut
Tipo
Descrio
Buffer descompactado, exatamente o buffer que foi
Caracter
passado pela funo compress.
nLengthOut
cBufferIn
nLengthIn
Numrico Tamanho do buffer descompactado

Caracter Buffer compactado pela funo compress.
Tamanho do buffer compacto, informao fundamental
Numrico
para a correta descompactao do buffer.
Retorno
Tipo
Lgico
Descrio
Retorna .t., caso o buffer foi descompacto com sucesso.
Retorna .F., caso no seja possvel descompactar o buffer.
Descrio
Descompacta um buffer recebido, atravs do algoritmo proprietrio.
Este buffer devera ser gerado pela funo compress.
Essa funo aceita e retorna caracteres binrios de vrios tipos, incluindo o zero binrio.
FUNES DE IMPRESSO
Sintaxe
GETIMPWINDOWS ( < lServer > ) --> aPrinters
Parmetros
Argumento
Tipo
Descrio
Informar .T. se a lista de impressoras deve ser obtida do
Lgico Protheus Server ou .F. para obter lista de imporessoras da
estao Remota. Este parmetro obrigatrio.
lServer
Retorno
Tipo
Array
Descrio
Array com nome das impressoras disponveis. Vale lembrar que esta
funo no verifica o status atual da(s) impressora(s) encontrada(s).
Descrio
GETIMPWINDOWS( ) retorna uma lista de impressoras disponveis no spool do Server
ou Remote. Se o Server est em ambiente Unix, a GETIMPWINDOWS() retornar a
lista com os nomes de impressoras cadastradas na chave PRINTERSNAME do arquivo
de configurao do Protheus Server.
Caso no seja encontrada nenhuma impressora , retornado um array com 1 elemento ,

contendo a String "Nenhuma Impressora Disponivel".
Observao : Caso a funo seja passada com o argumento .F. ( buscar
impressoras da estao Remote ) , porm a funo seja executada a partir de um
JOB ( programa sem a interface Remota ) , o array retornado ter apenas 1
elemento , contendo a String "Nenhuma Impressora Disponivel".
Exemplos
No exemplo abaixo , determinamos as impressoras disponveis na estao Remote e no
Server , respectivamente. E , mostramos no Console do Server a(s) impressora(s)
encontrada(s).
aImpRemote := GetImpWindows(.F.)
conout('Impressoras na estao remota')
aeval(aImpRemote , { |x| conout(x) })
aImpServer := GetImpWindows(.T.)
conout('Impressoras no Servidor')
aeval(aImpServer , { |x| conout(x) })
Sintaxe
GETPORTACTIVE ( < lServer > ) --> aPortImp
Parmetros
Argumento
Tipo
Descrio
CAso especificado .T. , a lista de impressoras ser obtida
Lgico
do Server, caso .F. a lista ser obtida da estao (Remote).
lServer
Retorno
Tipo
Array
Descrio
Array com as portas de impresso disponveis.
Descrio
Retorna lista de portas de impresso disponveis. A funo GETPORTACTIVE( )
retorna uma lista de portas de impresso disponveis do Protheus Server ou Remote. Se
o Protheus Server est em ambiente Unix, a GETPORTACTIVE() retornar uma lista
com os nomes de devices possveis para impresso.
Caso no sejam encontradas portas para impresso , retornado um array com apenas
um elemento , contendo a string "Nao existem portas disponiveis".
Observao : Caso a funo seja chamada com o parmetro .F. , para obter as
portas de impresso da estao remota , porm a funo seja chamada atravs de

um JOB ( programa sem a interface Remote ) , a mesma retornar um array com
um elemento , contendo a string "Nao existem portas disponiveis".
[RELEASE] Builds superiores a 7.00.041130p
Ao verificar os devices de impresso disponveis no SERVER, os devices especificados
na configurao de bloqueio de portas de impresso ( DisableDevicePort ) no server
no so listados por esta funo.
Quando executada em ambiente Linux, os devices de impresso disponveis no
SERVER, a funo deixa de retornar os devices como /dev/lp0 e /dev/ttys0 ... e passa a
retorn-los a nomenclatura LPT1:...COM1:... , limitando o retorno em no mximo
4 portas paralelas e 4 portas seriais.
Exemplos
No exemplo abaixo, determinamos as portas de impresso disponveis na estao
Remote e no Server, respectivamente. E mostramos no Console do Server a(s) porta(s)
encontrada(s).
aPortRemote := GetPortActive(.F.)
conout('Impressoras na estao remota')
aeval(aPortRemote , { |x| conout(x) })
aPortServer := GetPortActive(.T.)
conout('Impressoras no Servidor')
aeval(aPortServer , { |x| conout(x) })
Veja abaixo um exemplo do que foi mostrado no console do Protheus Server, apos a
execuo da rotina.
Impressoras na estao remota
COM1:
COM2:
COM3:
COM4:
FILE:
LPT1:
LPT2:
LPT3:
\\prnserver\prx-lp1
Impressoras no Servidor
COM1:
COM2:
COM3:
COM4:
FILE:
LPT1:
LPT2:
LPT3:
FUNES INTERFACE http

ENCRYPTRSA ( < cFileKey > , < cInfo > , [ lEncode64 ] ) --> cRet
Parmetros
Argumento
Tipo
Descrio
Representa o nome do arquivo, que contm a chave para
Caracter
criptografar a informao, o arquivo deve ser do tipo .pem
Representa a informao que desejamos ser criptografada
Caracter
usando RSA.
Caso desejamos que a sada dos dados venha encodado em
Lgico
base 64 informamos true, caso contrrio false.
cFileKey
cInfo
lEncode64
Retorno
Tipo
Caracter
Descrio
Retorna as informaes passadas atravs do argumento, criptografadas em
RSA.
Descrio
A funo EncryptRSA tem como objetivo realizar a criptografia de dados, para isso usa
um tipo de criptografia denominada RSA.
O RSA um algoritmo de Criptografia Assimtrica, isto significa que possumos uma
chave pblica e privada, RSA o mais usado algoritmo de chave pblica, pois prov
confidencialidade e assinatura digital.
A chave pblica a que serve para cifrar a mensagem (Confidencialidade) e decifrar a
mensagem (Autenticidade). Todos que desejarem lhe enviar uma mensagem devem
conhec-la.
Chave privada, que serve para decifrar a mensagem (Confidencialidade) e cifrar a
mensagem (Autenticidade). Somente uma pessoa deve conhec-la.
Em nossa funo informamos o local onde se encontra a chave que ser usada, em
seguida passamos como string os dados que queremos criptografar, podemos ainda
informar se desejamos o retorno em base 64 ou nao.
Sintaxe
GETWEBJOB ( ) --> cJobName
Retorno
Tipo
Caracter
Descrio
cJobName corresponde o nome do job que configura a working Thread
atual em uso. Caso a chamada da funo seja realizada a partir de uma
thread que no seja uma Working Thread ( como por exemplo , uma
thread iniciada a partir de um ApxRemote ) , a funo GetWebJob()
retornar uma string vazia ("").
Descrio
Atravs desta funo , possvel recuperar o nome da configurao de Working
Threads ( Job ) que est sendo utilizada pela Working Thread atual.
Observao : Esta funo est disponvel a partir dos Build's Ap6 gerados a partir
de 05/09/2002.
Sintaxe
GetEnvHost ( ) --> cHost
Retorno
Tipo
Caracter
Descrio
Quando em ambiente web retorna o host que foi utilizado para chamar a
funo.
Descrio
Retorna quando em ambiente web, por qual host a pgina foi chamada.
Exemplo:
web function retHost
return getenvhost() // Retorna o nome do host que chamou essa funcao ( Ex:
www.microsiga.com.br )
Sintaxe
HTTPCACHE ( < cCacheControl > ) --> cLastCache
Parmetros
Argumento
Tipo
cCacheControl
Descrio
Define o novo contedo da etiqueta do Header de Retorno
Caracter
HTTP Cache-Control.
Retorno
Tipo
Caracter
Descrio
Esta funo retorna a definio atualmente utilizada para a etiqueta CacheControl do Header HTTP.
Descrio
Atravs desta funo , podemos redefinir a etiqueta CACHE-CONTROL do Header de
Resposta de requisio HTTP , sobrepondo definio defaut de retorno CACHECONTROL , opcionalmente definida na configurao do HOST HTTP no Arquivo de
configurao do Protheus Server.
Tabela A - Definies CACHE-CONTROL

Contedo Aplicao
Nenhuma informao deve ser guardada em Cache pelo servidor e/ou
no-store
proxie(s).
Observao : A definio de um novo contedo para o CACHE-CONTROL do
Header HTTP apenas ser possvel caso esta funo Advpl seja executada
antes de qualquer envio parcial de html ao browser , realizado pela
funo HttpSend().
Sintaxe
HTTPCOUNTSESSION ( ) --> nCount
Retorno
Tipo
Numrico
Descrio
nCount corresponde ao nmero de usurios que possuem variveis de
session em uso no Server PRotheus.
Descrio
Esta funo retorna o nmero de Sessions de usurios que esto atualmente em uso na
memria.
** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **
OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um Build de Protheus Server com data igual ou superior a

22/04/2002.
Sintaxe
HTTPCTDISP ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de prover informaes sobre como apresentar uma mensagen
ou como parte de um pacote.
Quando uma parte de um pacote Http para ser tratada como um arquivo atachado, a
funo ir setar essa parte do cabealho http(Content-Disposition) como um nome de
arquivo sugerido de acordo com o parmetro.
Obs.: Caso ocorra a necessidade de verificar os tipos de parmetros usados pelo
protocolo Http das opes possveis para Content-Disposition:
http://http://www.ietf.org/rfc/rfc2183.txt
Obs.: A funo fuciona somente em Links APW
Exemplos
Neste exemplo criamos uma funo STATIC getFile(). Para usarmos a funo devemos
apenas informar o endereo fisico em disco de um aquivo.
Criamos um pequeno buffer, para ir mandando o pacote ao browser, em seguida
abrimos o arquivo com a funo FOpen() e pegamos o tamanho do arquivo com a
funo FSeek().
Definimos com a funo HttpCTType o tipode arquivo que iremos carregar, em nosso
exemplo apenas arquivos texto. Usamos a HttpCTDisp informando ao browser que
estamos carregando um attachment, no caso est linha ir fazer aparecer a tela de
download de um aquivo do seu Browser default e informamos o local do arquivo.
Em seguida informamos ao browser qual o tamanho desse arquivo, retornado da funo
FSeek(), e comeamos a enviar o arquivo em pequenos pedaos de 1024bytes.
static Function GetFile( cFile )
Local cHtml
Local cBuffer
:= ''
:= space(1024)
Local hArq
Local nTam
If !file(cFile)
cHtml += '
Arquivo '+cFile+' no encontrado.
'
ElseIf (hArq := FOpen(cFile)) < 0
cHtml += '
Falha na Abertura do Arquivo '+cFile+' ( FERROR '+str(ferror(),4)+' )
'
Else
// Le o arquivo e manda p/ o browse
nTam := FSeek(hArq, 0, 2)
FSeek(hArq, 0, 0 )
HttpSetPart(.T.)
HttpCTType("text/plain")
HttpCTDisp('attachment; filename="'+cFile+'"')
HttpCTLen(nTam)
While FRead(hArq, @cBuffer, 1024)>0
HttpSend(cBuffer)
EndDo
FClose(hArq)
Endif
Return cHtml
Sintaxe
HTTPEXITPROC ( < cFunction > ) --> Nil
Parmetros
Argumento
Tipo
Descrio
String que indica o nome da funo a ser chamada quando
Caracter
a Session for finalizada por time-out.
cFunction
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A httpExitProc tem o objetivo de setar uma funo que ser chamada quando uma
Session for Finalizada por Time-Out.
A funo que ser chamada para tratamento da session finalizada, deve estar compilada
no repositrio de dados corrente.
Muito til quando se deseja encaminhar todas 'quedas' de Session para uma nica
funo de tratamento.
Sintaxe
HTTPFREESESSION ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL
Descrio
Atravs da funo HttpFreeSession , eliminamos da memria do Servidor Protheus
todas as variveis de Session do usurio atual. Normalmente utilizamos esta funo em
operaes de LOGOFF , onde necessitamos limpar todas os conteudos relacionados
Session deste usurio.
Extended ) **
necessrio adquirir um Build do Servidor Protheus Server com data igual ou superior a
22/04/2002.
Sintaxe
HTTPGET ( < cUrl > , [ cGETParms ] , [ nTimeOut ] ) --> cHttp
Parmetros
Argumento
cUrl
cGETParms
nTimeOut
Tipo
Descrio
cUrl corresponde ao endereo http , juntamente com a
Caracter
pasta e o documento solicitados.
cGETParms corresponde StringList de parmetros a
Caracter serem enviados ao servidor http atravs da URl . Caso no
especificado , este parmetro considerado vazio ("")
Em nTimeOut especificamos o tempo em segundos
mximo de inatividade permitido durante a recepo do
Numrico
documento . Caso no especificado , o valor default
assumido 120 segundos ( 2 minutos).
Retorno
Tipo
Caracter
Descrio
String Html correspondendo ao documento solicitado.
Descrio
A funo HttpGet() permite a emulao de um Client HTTP atravs de uma funo
Advpl, acessando um determinado documento html publicado em um servidor Web,
utiliando o mtodo GET , permitindo a passagem de parmetros via URL, aguardando
por um tempo determinado (time-out) pela resposta do servidor solicitado.
Observaes :
--- Na passagem de parmtros GET , devemos atentar ao formato da string a ser passada
como parmetros , pois a mesma segue o formato URI (Uniform Resource Identifiers) :
Query Component.
--- Caso nao seja retornado o documento antes do trmino do Time-out especificado na
chamada da funo; ou caso no seja possvel localizar o servidor ; seja por falha de
resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a funo retornar
Nulo (NIL).
--- Caso nao seja possvel o acesso ao documento , como por exemplo o documento no
exista , ser retornado uma string html com a mensagem de erro html enviada pelo
servidor correspondente.
OBSERVACAO : Esta funco est disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002
Sintaxe
HTTPGETPART ( ) --> bPartEnabled
Retorno
Tipo
Lgico
Descrio
Retorna .t. se o envio parcial do contedo HTML est habilitado.
Descrio
Esta funo retorna se o envio parcial de contedo ao browser est ou no habilitado.
Sintaxe
HTTPGETSTATUS ( ) --> nStatus
Retorno
Tipo
Numrico
Descrio
Retorna o status da conexo HTTP atual requerida
Descrio
A funo tem o objetivo de retornar qual o status da conexo HTTP requisitada.
Para tal tarefa a funo retorna valores de acordo com o protocolo HTTP, entre eles os
mais comuns e importantes so:
Error codes
500 501 502 403;14 -
'Internal Server Error'

'Not Implemented'
'Bad Gateway'
'Forbidden - Directory Listing Denied'
200
'Sucess Connection'
Exemplos
Neste exemplo usamos a funo HttpGetStatus para termos certeza de que no temos
uma conexo HTTP vlida, para isto verificamos o cdigo retornado pela funo.
Estando tudo correto, realizamos uma emulao de post para a funo no inicio do fonte
- ExHTTPPost() - retornando uma simples tabela com os dados postados.
Em seguida ainda verificamos a conexo aps o Post.
#INCLUDE "XMLXFUN.CH"
Web Function ExHTTPPost()
Local cHtml := ""
if (HttpPost->login != Nil .AND. HttpPost->pass != Nil)
conout("Post com Sucesso\nlogin: "+HttpPost->login +
"\nPass: "+ HttpPost->pass)
cHtml
cHtml
cHtml
>login+"</td></tr>"
cHtml
>pass+"</td></tr>"
cHtml
endif
:= "<h3>HttpPost</h3><br><br>"
+= "<table width=200 border=1>"
+= "<tr><td>Login</td><td>"+HttpPost+= "<tr><td>Senha</td><td>"+HttpPost+= "</table>"
Return cHtml
web Function loginMK()

Local cHtml := ""
if HttpGetStatus() == 0
cHtml := HTTPPOST( "http://ricardo/w_ExHTTPPost.apw", "",
"login=Teste&pass=123", 120 , NIL )
conout( HttpGetStatus() )
if HttpIsConnected()
conout("isConnected")
endif
endif
Return cHtml
Sintaxe
HTTPLEAVESESSION ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
A funo HttpLeaveSession() sempre retorna NIL
Descrio
Esta funo , uma vez executada , libera o processamento de requisio de atualizo
de contedos de variveis tipo HttpSession para requisies de consulta e/ou
atualizaes simultneas para o usurio atual.
Extended ) **
necessrio adquirir um build de Server PRotheus com data igual ou superior a
22/04/2002.
Sintaxe
HTTPLOGONUSER ( ) --> cLogonUser
Retorno
Tipo
Caracter
Descrio
String contendo o login do usurio, no formato DOMINIO\login. Caso a
funo no seja executada em uma thread iniciada em uma interface http ,
ou o acesso annimo o site no IIS esteja habilitado , a funo retornar
uma string em branco ("").
Descrio
Atravs da Funo HttpLogonUser() , quando utilizamos o AP Server ISAPI (
AdvplIsapi.dll) , em conjunto com o Microsoft IIS (Internet Information Services ) ,
obtemos o login do usurio atual.
Observao : Para que o usurio seja obrigado a informar um login individual ,
deve ser desabilitado no IIS a configurao que permite acesso annimo ao site.
Caso esta configurao no seja alterada , todos os usurios sero identificados
como "annimos" pelo IIS, e a funo retornar uma String em branco.
Sintaxe
HTTPOTHERCONTENT ( ) --> cContent
Retorno
Tipo
Caracter
Descrio
cContent a string correspondendo ao contedo do corpo do pacote
HTML postado no Server.
Descrio
A funo HttpOtherContent() , quando utilizada em uma thread montada e/ou
inicializada para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do
pacote html proveniente de uma operao de POSTagem de dados, se e somente se a
operaco de POSTagem especificou no HEader HTTP um content-disposition ou
content-type no tratados automaticamente pelo Server PRotheus.
Caso a requisio no tenha sido realizada por um client HTTP atravs do mtodo de
postagem , ou a postagem j possua tratamento nativo no Server Protheus , ou a funo
seja chamada em um ambiente que no esteja atendendo uma requisio Http ( como
um JOB , por exemplo) , a funo retornar uma string em branco ("").
Sintaxe
HTTPPOST ( < cUrl > , [ cGETParms ] , [ cPOSTParms ] , [ nTimeOut ] , [ aHeadStr ]
) --> cHtml
Parmetros
Argumento
Tipo
Descrio
cUrl corresponde ao endereo http , juntamente com a
Caracter
pasta e o documento solicitados.
cGETParms corresponde StringList de parmetros a
Caracter serem enviados ao servidor http atravs da URl . Caso no
especificado , este parmetro considerado vazio ("")
cPostParms corresponde StringList de parmetros a
serem enviados ao servidor http atravs do pacote HTTP .
Caracter
Caso no especificado , este parmetro considerado
vazio ("")
Em nTimeOut especificamos o tempo em segundos
mximo de inatividade permitido durante a recepo do
Numrico
documento . Caso no especificado , o valor default
assumido 120 segundos ( 2 minutos).
Atravs deste parametro , podemos especificar um array
Array
com strings a serem acrescentadas ao Header da
requisio HTTP a ser realizada.
cUrl
cGETParms
cPOSTParms
nTimeOut
aHeadStr
Retorno
Tipo
Caracter
Descrio
Atravs de cHtml ser retornada a String Html correspondendo ao
documento solicitado.
Descrio
A funo HttpPost() permite a emulao de um Client HTTP atravs de uma funo
Advpl, postando um bloco de informaes para um determinado documento publicado
em um servidor Web, utiliando o mtodo POST , permitindo a passagem de parmetros
adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta
do servidor solicitado.
Observaes :
Na passagem de parmtros GET e POST , devemos atentar ao formato da string

a ser passada como parmetros , pois a mesma segue o formato URI (Uniform
Resource Identifiers) : Query Component.
Caso nao seja retornado o documento antes do trmino do Time-out especificado
na chamada da funo; ou caso no seja possvel localizar o servidor ; seja por
falha de resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a
funo retornar Nulo (NIL).
Caso nao seja possvel o acesso ao documento , como por exemplo o documento
no exista ,ser retornado uma string html com a mensagem de erro html
enviada pelo servidor correspondente.
Quando utilizamos a funo HttpPost() , podemos especificar um Content-Type
diferenciado para o contedo postado. Caso no seja especificado um ContentType , alguns servidores tratam a informao postada como sendo um dado do
tipo 'application/x-www-form-url' , seria o equivalente a um formulrio HTML
postado via Browser, outros servidores podero no reconhecer tal informao

postada dessa forma. Para especificar que o contedo postado deve ser tratado
como um POST de formulrio HTTP , devemos passar no parmetro aHeadStr ,
um elemento contendo 'Content-Type: application/x-www-form-url'.
ATENO
1. Esta funco est disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002 .
2. O parametro aHeadStr apenas est disponvel em Build's Ap6 e posteriores
gerados apos 01/10/2002.
Exemplos
Neste exemplo usamos a funo HttpGetStatus para termos certeza de que no temos
uma conexo HTTP vlida, para isto verificamos o cdigo retornado pela funo.
Estando tudo correto, realizamos uma emulao de post para a funo no inicio do fonte
- ExHTTPPost() - retornando uma simples tabela com os dados postados.
Em seguida ainda verificamos a conexo aps o Post.
Web Function ExHTTPPost()
Local cHtml := ""
if (HttpPost->login != Nil .AND. HttpPost->pass != Nil)
conout("Post com Sucesso\nlogin: "+HttpPost->login +
"\nPass: "+ HttpPost->pass)
cHtml
cHtml
cHtml
>login+"</td></tr>"
cHtml
>pass+"</td></tr>"
cHtml
endif
:= "<h3>HttpPost</h3><br><br>"
+= "<table width=200 border=1>"
+= "<tr><td>Login</td><td>"+HttpPost+= "<tr><td>Senha</td><td>"+HttpPost+= "</table>"
Return cHtml
web Function loginMK()

Local cHtml := ""
if HttpGetStatus() == 0
cHtml := HTTPPOST( "http://ricardo/w_ExHTTPPost.apw", "",
"login=Teste&pass=123", 120 , NIL )
conout( HttpGetStatus() )
if HttpIsConnected()
conout("isConnected")
endif
endif
Return cHtml
Sintaxe
HTTPPOSTXML ( < cURL > , [ cParam ] , < cFile > , < nTimeOut > ) --> lRet
Parmetros
Argumento
cURL
cParam
cFile
nTimeOut
Tipo
Descrio
Caracter Indica o endereo para qual ser feito o POST dos dados.
bloco de informaes, que utiliando o mtodo POST ser
Caracter
feita a passagem de parmetros adicionais.
Caracter Indica um path de um arquivo local armazenado em disco.
Representa o tempo(timeout) de inatividade em que a
Numrico
requisio ir aguardar em segundos.
Retorno
Tipo
Lgico
Descrio
Retorna se foi possvel realizar o PostXml. Caso seja realizado retorna
true, caso contrrio false.
Descrio
A funo HttpPostXml() permite a emulao de um Client HTTP atravs de uma funo
Advpl.
Postando um bloco de informaes e um documento XML indicado por uma
string path, para um determinado documento publicado em um servidor Web, utiliando
o mtodo POST , permitindo a passagem de parmetros adicionais e aguardando por um
tempo determinado (time-out) pela resposta do servidor solicitado.
Sintaxe
HTTPPRAGMA ( < cPragma > ) --> cOldPragma
Parmetros
Argumento
Tipo
Descrio
cPragma corresponde ao conteudo do PRAGMA a ser
Caracter definido no Header de retorno HTTP. Veja tabela "A" de
definies PRAGMA.
cPragma
Retorno
Tipo
Caracter
Descrio
A funo HttpPragma retornar a definio anterior de PRAGMA
utilizada.
Descrio
Atravs desta funo , podemos redefinir a etiqueta PRAGMA do Header de Resposta
de requisio HTTP , sobrepondo definio defaiut de retorno PRAGMA ,
opcionalmente definida na configurao do HOST HTTP no Arquivo de configurao
do Protheus Server.
Tabela A - Definies Pragma

Contedo Aplicao
Informa ao Client HTTP ( Browser ) que a pgina retornada no deve ser
no-cache
colocada em Cache, independente da configurao de Cache do Browser.
Observao : A definio de um novo contedo para o PRAGMA do Header
HTTP apenas ser possvel caso esta funo Advpl seja executada antes
de quaqlquer envio parcial de html ao browser , realizado pela funo
HttpSend().
Sintaxe
HTTPRCTDISP ( ) --> cCtDisp
Retorno
Tipo
Caracter
Descrio
cCtDisp corresponde o conteudo do identificador Content-disposition ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.
Descrio
A funo HttpRCtDisp() , quando utilzada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-disposition do Header HTTP .
Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no

esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo
retornar uma String em branco ("").
Sintaxe
HTTPRCTLEN ( ) --> nCtLen
Retorno
Tipo
Numrico
Descrio
nCtLen corresponde o conteudo do identificador Content-length ,
servidor.
Descrio
A funo HttpRCtLen() , quando utilizada em uma thread montada e/ou inicializada
Content-length do Header HTTP , como um dado numrico .
retornar 0 ( Zero ) .
Sintaxe
HTTPRCTTYPE ( ) --> cCtType
Retorno
Tipo
Caracter
Descrio
cCtType corresponde o conteudo do identificador Content-type , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo HttpRCtType() , quando utilzada em uma thread montada e/ou inicializada
Content-type do Header HTTP .
Sintaxe
HTTPRCTTYPE ( ) --> cCtType
Retorno
Tipo
Caracter
Descrio
cCtType corresponde o conteudo do identificador Content-type , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo HttpRCtType() , quando utilzada em uma thread montada e/ou inicializada
Content-type do Header HTTP .
Sintaxe
HTTPSEND ( < cHtmlStr > ) --> cHtmlNoSend
Parmetros
Argumento
Tipo
Descrio
cHtmlStr corresponde string a ser enviada ao Browser
Caracter
solicitante de um processamento .
cHtmlStr
Retorno
Tipo
Descrio
Caso a funo obtenha sucesso em enviar a String cHtmlStr para o Browse
solicitante , o retorno ser uma string vazia ("").
Caracter
Caso no seja possvel o envio da string , devido o recurso de envio

simultneo estar desabilitado ; ou ocorra uma falha de comunicao, ou a
funo HttpSend() seja executada a partir de uam thread que no uma
Working Thread , a funo ir retornar a string passada como parmetro.
Descrio
Atravs desta funo, possivel retornar uma string Html um browser durante o
processamento de uma requisio realizada atravs de um link .APW , utilizando
Working Threads , durante o processamento da mesma.

Observao : Este recurso no funciona em requisies de procesamento
realizadas a partir de um link .apl . necessrio que a requisio seja para um
link .apw , atendida por uma Working Thread.
Sintaxe
HTTPSETPART ( < lHttpSend > ) --> NIL
Parmetros
Argumento
Tipo
Descrio
lHttpSend um valor booleano que habilita o envio parcial
Lgico
( caso .T. ) ou desabilita o envio parcial de HTML ( .F. )
lHttpSend
Retorno
Tipo
(NULO)
Descrio
Descrio
Essa funo permite desabilitar o envio parcial do HTML, esse um recurso disponivel
para os programas escritos para APW ( Utilizando Working Thread ).
Esse recurso util para comearmos a mandar contedo ao browser antes de
terminarmos de processar totalmente a pgina, ele pode aumentar em muito o
desempenho do transmisso da pgina em caso de pginas grandes.
A Funo HTTPSend utilizada para esse envio temporrio.
Sintaxe
HTTPSETPASS ( < cUser > , < cPass > ) --> Nil
Parmetros
Argumento
cUser
cPass
Tipo
Descrio
Cadeia de caracteres que representa o usurio a ser setado
Caracter
uma senha.
Indica a senha informada para autenticao de acordo com
Caracter
o usurio informado.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Em alguns momentos trabalhamos com protocolo Http autenticado, isso nos indica que
para nos conectar a determinada URL devemos informar um usurio e senha que
tenham permiso para conexo com a URL.
A funo HttpSetPass() tem o objetivo de setar uma senha para um determinado
usurio, quando uma requisio HTTP necessita de autenticao.
Informando atravs de parametro o usurio e a senha que dever ser usada para
autenticao do usurio infromado.
Sintaxe
HttpCountSession ( ) --> nQtde
Retorno
Tipo
Numrico
Descrio
Quantidade de usurios com sesses web extended ativas
Descrio
Esta funo retorno o nmero de sesses de usurios ativas no servidor, util para saber
quantos usurios de Web esto utilizando os servidores neste momento.
Sintaxe
HttpFreeSession ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Libera a sesso do usurio corrente, todos os dados armazenado nas sesses deste
usurio ser perdida.
Funo utilizada para efetuar o log off do usurio do site.
Sintaxe
HttpIsAPW ( ) --> bIsAPW
Retorno
Tipo
Lgico
Descrio
Retorna .T. no caso do ambiente em execuo ser um APW, .F. em todas
as outras situaes.
Descrio
Informa se o ambiente web em execuo um APW, caso no seja retorna .F.
Essa funo util na criao de funes genricas ou na consistncia da configurao
do ambiente.
Sintaxe
HttpIsConnected ( ) --> bConnected
Retorno
Tipo
Lgico
Descrio
Retorna .t. se o browser ainda est conectado aguardando a resposta.
Descrio
Informa se o browser est conectado ainda esperando a resposta do Protheus!
Funcionalidade no disponvel quando utilizado o ISAPI para integrao com IIS
Sintaxe
ISSECURE ( ) --> lRet
Retorno
Tipo
Descrio
(NULO)
true caso a conexo uma conexo SSL, false caso contrrio.
Descrio
A funo IsSecure() tem como objetivo retornar um valor booleano informando se a
conexo HTTP corrente, uma conexo segura, ou no.
Uma conexo HTTP segura, uma conexo que usa criptografia SSL, podemos
observar esse tipo de conexo quando a URL modifica-se de HTTP para HTTPS em um
browser.
Sintaxe
SOAPRACTION ( ) --> cSoapAction
Retorno
Tipo
Caracter
Descrio
cSoapAction corresponde o conteudo do identificador soapaction ,
servidor.
Descrio
A funo SoapRAction() , quando utilizada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo string do
identificador soapaction do Header HTTP .
retornar uma string em branco ("").
FUNO DE DISCO E ARQUIVO

Sintaxe
ADIR ( [ ] , [ ] , [ ] , [ ] , [ ] , [ ] ) --> nArquivos
Parmetros
Argumento
<cEspecArq>
Tipo
Descrio
Caracter <cEspecArq> a especificaao dos arquivos a serem
<aNomesArq>
Array
<aTamanhos>
Array
<aDatas>
Array
<aHoras>
Array
<aAtributos>
Array
incluidos na pesquisa do diretrio padrao. uma

especificaao de arquivo padrao que pode incluir os
caracteres coringa do tipo * e ?, bem como referncia a
diretrio e path. Caso nao seja especificado, o padrao
assumido *.*.
<aNomesArq> o vetor a ser preenchido com os nomes de
arquivo que correspondem a <cEspecArq>. Cada elemento
contm o nome do arquivo e extensao na forma de uma
cadeia de caracteres em letras maisculas.
<aTamanhos> o vetor a ser preenchido com os tamanhos
dos arquivos correspondentes no vetor <aNomesArq>.
Cada elemento numrico.
<aDatas> o vetor a ser preenchido com as datas dos
arquivos correspondentes no vetor <aNomesArq>. Cada
elemento uma data.
<aHoras> o vetor a ser preenchido com as horas dos
arquivos correspondentes no vetor <aNomesArq>. Cada
elemento preenchido contm uma cadeia de caracteres da
forma: hh:mm:ss.
<aAtributos> o vetor a ser preenchido com os atributos
dos arquivos correspondentes no vetor <aFilenames>.
Cada elemento uma cadeia de caracteres. Caso
<aAtributos> seja especificado, os arquivos de diretrio,
sistema, e escondidos sao incluidos, assim como os
arquivos normais. Se <aAtributos> nao for especificado,
somente os arquivos normais sao incluidos.
Retorno
Tipo
Numrico
Descrio
ADIR() retorna a quantidade de arquivos que correspondem ao esqueleto
de diretrio especificado.
Descrio
ADIR() uma funao de tratamento de vetor que executa duas operaoes bsicas.
Primeiro, ele retorna a quantidade de arquivos que correspondem especificaao de
arquivo. Segundo, preenche uma srie de vetores com nomes de arquivos, tamanhos,
datas, horas e atributos.
ADIR() uma funao de compatibilidade e portanto desaconselhada. Ele est superado
pela funao DIRECTORY(), que retorna todas as informaoes de arquivo em um vetor
multi-dimensional.
OBSERVAO
Diretrios: Caso o argumento <aAtributos> seja especificado e <cEspecArq> seja
especificado como *.*, os diretrios serao incluidos em <aNomesArq>. No vetor
<aAtributos>, os diretrios sao indicados com um valor atributo de "D." Se ADIR() for
executado dentro de um subdiretrio, as duas primeiras entradas do vetor
<aNomesArq> sao "." e "..", os "alias" dos diretrios corrente e raiz. A data e hora da
ltima atualizaao sao informadas para diretrios, mas o tamanho de um diretrio
sempre zero.
Exemplos
Este exemplo cria um vetor que conter os nomes de todos os arquivos (.txt) no
diretrio DEFAULT corrente, e os relaciona no console utilizando a funao AEVAL() :
LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| conout(element) })
Sintaxe
CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento
Tipo
Descrio
Nome(s) dos arquivos a serem copiados, aceita apenas
Caracter arquivos
no servidor, WildCards ( * e ? ) so aceitos normalmente.
Caracter Diretrio com o destino dos arquivos no Client ( Remote )
Indica se a cpia deve ser feita compactando o arquivo
Lgico
antes do envio.
cOrigem
cDestino
lCompacta
Retorno
Tipo
Lgico
Descrio
lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em
caso de falha na cpia.
Descrio
Copia um arquivo, do servidor para o cliente ( Remote ). .Caso a compactao seja
habilitada (lCompacta ), os dados sero transmitidos de maneira compactada e
descompactados antes do uso.
Exemplo :
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. ) // Copia arquivos do
servidor para o remote local, compactando antes de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. ) // Copia arquivos do

servidor para o remote local, sem compactar antes de transmitir
Sintaxe
CPYT2S ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento
Tipo
Descrio
Nomes dos arquivos a serem copiados, aceita apenas
Caracter arquivos locais ( Cliente ), WildCards ( * e ? ) so aceitos
normalmente.
Caracter Diretrio com o destino dos arquivos no Servidor
lCompacta indica se o(s) arquivo(s) deve(m) ser enviados
Lgico
em formato compactado.
cOrigem
cDestino
lCompacta
Retorno
Tipo
Lgico
Descrio
lSucess indica , caso verdadeiro , que a cpia foi realizada com sucesso.
Caso retorne .F. , houve erro na copia do arquivo.
Descrio
Copia um arquivo, do cliente ( Remote ) para o servidor,. Caso a compactao seja
habilitada ( lCompacta ), os dados sero transmitidos de maneira compacta e
descompactados antes do uso.
Exemplo
CpyT2S( "C:\TEMP\MANUAL.DOC","\BKP", .T. ) // Copia arquivos do
cliente( remote ) para o Servidor compactando antes de transmitir
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" ) // Copia arquivos do cliente(
remote ) para o Servidor sem compactar.
Sintaxe
CURDIR ( [ cNovoPath ] ) --> cPathAtual
Parmetros
Argumento
cNovoPath
Tipo
Descrio
Caracter Caminho relativo , com o novo diretrio que ser ajustado
como corrente.
Retorno
Tipo
Caracter
Descrio
Diretrio corrente, sem a primeira barra.
Descrio
Retorna o diretrio corrente do servidor. O caminho retornado sempre relativo o
RootPath definido na configurao do Environment no .INI do Protheus Server.
Inicialmente , o diretrio atual da aplicao o constante na chave StartPath , tambm
definido na configurao do Environment no .INI do Protheus Server.
Caso seja passado o parmetro cNovoPath , este path assumido como sendo o Path
atual. Caso o path recebido como parmetro no exista , seja invlido , ou seja um path
absoluto ( iniciado com uma letra de drive ou caimnho de rede ) , a funo no ir setar
o novo path , mantendo o atual .
No exemplo abaixo , conferimos o path atual e tentamos setar um novo path atual ,
verificando se a operao foi realizada com sucesso.
cOldDir := curdir()
cNewDir := '\webadv\xis'
curdir(cNewDir) // Troca o path
If cNewDir <> '\'+curdir() // E verifica se trocou mesmo
conout('Falha ao Trocar de Path de '+cOldDir + ' para '+cNewDir)
Else
conout('Path de '+cOldDir + ' trocado para '+cNewDir+' com
sucesso.')
Endif
Sintaxe
DIRECTORY ( < cDirSpec > , [ ] ) --> aDiretorio
Parmetros
Argumento
cDirSpec
Tipo
Descrio
<cDirSpec> especifica o drive, diretrio e arquivo para a
pesquisa no diretrio. Caracteres do tipo coringa sao
permitidos na especificaao de arquivos. Caso <cDirSpec>
Caracter
seja omitido, o valor padrao *.*.
O caminho especificado pode estar na estao (remote) ,
ou no servidor , obedecendo s definices de Path
Absoluto / Relativo de acesso

<cAtributos> especifica que arquivos com atributos
especiais devem ser incluidos na informaao retornada.
Caracter <cAtributos> consiste em uma cadeia de caracteres que
contm um ou mais dos seguintes caracteres, contidos na
tabela adicional A , especificada abaixo:
<cAtributos>
Retorno
Tipo
Array
Descrio
DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor
contm informaoes sobre cada arquivo que atenda a <cDirSpec>.Veja
maiores detalhes na Tabela B, abaixo discriminada.
Descrio
DIRECTORY() uma funao de tratamento de ambiente que retorna informaoes a
respeito dos arquivos no diretrio corrente ou especificado. semelhante a ADIR(),
porm retorna um nico vetor ao invs de adicionar valores a uma srie de vetores
existentes passados por referncia.
DIRECTORY() pode ser utilizada para realizar operaoes em conjuntos de arquivos.
Em combinaao com AEVAL(), voc pode definir um bloco que pode ser aplicado a
todos os arquivos que atendam a <cDirSpec> especificada.
Para tornar as referncias aos vrios elementos de cada sub-vetor de arquivo mais
legveis, fornecido o arquivo header Directry.ch, que contm os #defines para os
subarray subscripts.
TABELA A: Atributos de DIRECTORY()

Atributo Significado
H
Incluir arquivos ocultos
S
Incluir arquivos de sistema
D
Incluir diretrios
V
Procura pelo volume DOS e exclui outros arquivos
Arquivos normais sao sempre incluidos na pesquisa, a nao ser que V seja especificado.
TABELA B: Estrutura dos Subvetores de DIRECTORY()

Posiao Metasmbolo Directry.ch
1
cNome
F_NAME
2
cTamanho F_SIZE
3
dData
F_DATE
4
cHora
F_TIME
5
cAtributos F_ATT
Exemplos
Atravs do exemplo abaixo , obtemos no array aDirectory todos os diretrios no
ambiente do servidor a partir do path atual.
#INCLUDE "Directry.ch"
aDirectory := DIRECTORY("*.*","D")
AEVAL( aDirectory, {|aFile| CONOUT(aFile[F_NAME])} )
Sintaxe
DIRREMOVE ( < cDiretorio > ) --> lSucesso
Parmetros
Argumento
cDiretorio
Tipo
Descrio
Caracter Nome do diretrio a ser removido.
Retorno
Tipo
Lgico
Descrio
lSucesso ser .T. caso o diretrio tenha sido eliminado , ou .F. caso no
seja possvel excluir o diretrio. Quando a funo DirRemove retornar .F.
, possvel obter mais detalhes da ocorrncia recuperando o cdigo do
Erro atravs da funo FError().
Descrio
DIRREMOVE() elimina um diretrio especifico. Caso especifiquemos um path sem a
unidade de disco , ele ser considerado no ambiente do Servidor , a partir do RootPath
do ambiente ( caso o path comee com \ ) , ou a partir do diretrio corrente ( caso o path
no seja iniciado com \ ) . E , quando especificado um path absoluto ( com unidade de
disco preenchida ) , a funo ser executada na estao onde est sendo executado o
Protheus Remote. Quando executamos a funo DirRemove() em JOB ( processo
isolado no Server , sem interface ) , no possvel especificar um Path absoluto de
disco. Caso isto seja realizado , a funo retornar .F. e FError() retornar -1 ( Syntax
Error ) .
Note que necessrio ter direitos suficientes para remover um diretrio, e o
diretrio a ser eliminado precisa estar vazio, sem subdiretrios ou arquivos dentro
do mesmo.
Exemplos
No exemplo abaixo , executado a partir do Protheus Remoite , tentamos excluir a pasta
c:\TmpFiles , verificando se houve sucesso nesta operao.
cDelPath := 'c:\TmpFiles'
lRemoveOk := DIRREMOVE(cDelPath)
IF !lRemoveOk
MsgStop('Falha ao remover a pasta '+cDelPath+' ( File Error
'+str(Fewrror(),4)+' ) ')
Else
MsgStop('Pasta '+cDelPath+' removida com sucesso.')
Endif
Sintaxe
DISKSPACE ( [ nDrive ] ) --> nBytesFree
Parmetros
Argumento
nDrive
Tipo
Descrio
Nmero do drive, onde 0 o espao na unidade de disco
Numrico corrente, e 1 o drive A: do cliente, 2 o drive B: do
cliente, etc.
Retorno
Tipo
Numrico
Descrio
Nmero de bytes disponveis no disco informado como parmetro.
Descrio
DISKSPACE() uma funo de ambiente que determina quantos bytes esto
disponveis em uma determinada uinidade de disco. Esta funo obtm a informao
sempre relativa estao onde est sendo executado o Protheus Remote. Atravs do
parmetro nDRive , selecionamos qual a unidade de disco que desejamos obter a
informao do espao livre , onde:
0 : Unidade de disco atual da estao (DEFAULT).
1 : Drive A: da estao remota.
2 : Drive B: da estao remota.
3 : Drive C: da estao remota.
4 : Drive D: da estao remota ... e assim por diante.
Caso a funo DiskSpace seja executada atravs de um Job ( processo isolado no
Servidor , sem interface Remota ) , ou seja passado um argumento de unidade de
disco inexistente ou indisponvel , a funo DISKSPACE() retornar -1
Exemplo da funo DISKSPACE

Reviso: 01/05/2003
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
No exemplo abaixo , obtemos os espaos em disco da unidade de disco da estao local

e do drive A: da estao local, verificando se houve sucesso na operao.
nBytesLocal := DISKSPACE( ) // Retorna o espao disponivel na unidade
de disco local ( remote ).
IF nBytesLocal < 1048576
MsgStop('Unidade de Disco local possui menos de 1 Mb livre.')
Else
MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes
livres.')
Endif
nBytes_A := DISKSPACE( 1 ) // Retorna o espao disponivel no drive A:
local ( remote ).
If nBytes_A == -1
MsgStop('Unidade A: no est disponvel ou no h disco no Drive')
ElseIf nBytes_A < 8192
MsgStop('No h espao disponvel no disco. Substitua o disco na
Unidade A:')
Else
MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes
livres.')
Endif
Sintaxe
FCLOSE ( < nHandle > ) --> lError
Parmetros
Argumento
nHandle
Tipo
Descrio
<nHandle> o handle do arquivo obtido previamente
Numrico
atravs de FOPEN() ou FCREATE().
Retorno
Tipo
Lgico
Descrio
FCLOSE() retorna falso (.F.) se ocorre um erro enquanto os buffers estao
sendo escritos; do contrrio, retorna verdadeiro (.T.).
Descrio
FCLOSE() uma funao de tratamento de arquivos de baixo nvel utilizada para fechar
arquivos binrios e forar que os respectivos buffers do DOS sejam escritos no disco.
Caso a operaao falhe, FCLOSE() retorna falso (.F.). FERROR() pode entao ser usado
para determinar a razao exata da falha. Por exemplo, ao tentar-se usar FCLOSE() com
um handle (tratamento dado ao arquivo pelo sistema operacional) invlido retorna falso
(.F.) e FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para
obter uma lista completa dos cdigos de erro.
Aviso
Esta funao permite acesso de baixo nvel aos arquivos e dispositivos do DOS. Ela deve
ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional
utilizado.
Exemplos
O exemplo a seguir utiliza FCLOSE() para fechar um arquivo binrio recm criado e
exibe uma mensagem de erro caso o fechamento falhe:
#include "Fileio.ch"
nHandle := FCREATE("Testfile", FC_NORMAL)
If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf
Sintaxe
FCREATE ( < cArquivo > , [ nAtributo ] ) --> nHandle
Parmetros
Argumento
cArquivo
nAtributo
Tipo
Descrio
Nome do arquivo a ser criado , podendo ser especificado
um path absoluto ou relativo , para criar arquivos no
Caracter
ambiente local ( Remote ) ou no Servidor ,
respectivamente .
Atributos do arquivo a ser criado (Vide Tabela de
Numrico atributos abaixo). Caso no especificado , o DEFAULT
FC_NORMAL.
Retorno
Tipo
Numrico
Descrio
A funo retornar o Handle do arquivo para ser usado nas demais funes
de manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no
seja possvel criar o arquivo , a funo retornar o handle -1 , e ser
possvel obter maiores detalhes da ocorrencia atravs da funo FERror()
Descrio
FCREATE() uma funo de baixo-nvel que permite a manipulao direta dos
arquivos textos como binrios. Ao ser executada FCREATE() cria um arquivo ou
elimina o seu contedo, e retorna o handle (manipulador) do arquivo, para ser usado nas
demais funes de manuteno de arquivo. Aps ser utilizado , o Arquivo deve ser
fechado atravs da funo FCLOSE().
Na tabela abaixo , esto descritos os atributos para criao do arquivo , definidos no
arquivo header fileio.ch
Constante
Valor Descrio
FC_NORMAL 0
Criao normal do Arquivo (default/padro).
FC_READONLY 1
Cria o arquivo protegido para gravao.
FC_HIDDEN
2
Cria o arquivo como oculto.
FC_SYSTEM
4
Cria o arquivo como sistema.
Caso desejemos especificar mais de um atributo , basta som-los . Por exemplo , para
criar um arquivo protegiro contra gravao e escondido , passamos como atributo
FC_READONLY + FC_HIDDEN .
ATENO : Caso o arquivo j exista , o contedo do mesmo ser ELIMINADO ,
e seu tamanho ser truncado para 0 ( ZERO ) bytes.
Sintaxe
FERASE ( < cArquivo > ) --> nStatus
Parmetros
Argumento
Tipo
Descrio
Nome do arquivo a ser apagado . Pode ser especificado um
Caracter path absoluto ou relativo , para apagar arquivos na estao
local ( Remote ) ou no Servidor , respctivamente .
cArquivo
Retorno
Tipo
Numrico
Descrio
A funo retornar 0 caso o arquivop seja apagado com sucesso , e -1 caso
no seja possvel apagar o arquivo. Caso a funo retorne -1 , possvel
obter mauires detalhes da ocorrncia atravs da funo fError()
Descrio
Atravs da funo Ferase , possvel apagar um arquivo no disco . O Arquivo pode

estar no Servidor ou na estao local (Remote).
O Arquivo para ser apagado deve estar fechado. No permitido a utilizao de
caracteres coringa (wildcards).
Exemplos
// Este exemplo apaga todos os arquivos .BAK do diretrio corrente no Servidor
#include 'DIRECTRY.CH'
aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })
// Este exemplo apaga um arquivo no cliente ( Remote ) , informando o status da

operao
IF FERASE("C:\ListaTXT.tmp") == -1
MsgStop('Falha na deleo do Arquivo ( FError'+str(ferror(),4)+
')')
Else
MsgStop('Arquivo deletado com sucesso.')
ENDIF
Sintaxe
FILE ( < cArquivo > ) --> lExiste
Parmetros
Argumento
Tipo
Descrio
Nome do arquivo , podendo ser especificado um path
(caminho ) . Caminhos locais (Remote) ou caminhos de
Caracter
servidor so aceitos , bem como wildcards ( Caracteres * e
?)
cArquivo
Retorno
Tipo
Lgico
Descrio
O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no
exista no path especificado , a funo retorna .F.
Descrio
Verifica se existe um arquivo ou um padro de arquivos, no diretrio. Pordemos
especificar caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( A partir
do RootPath do Protheus Server) . Os caracteres * e ? ( wildcards). so aceitos.
Exemplos
FILE("teste.dbf") // Verifica no diretrio corrente do servidor se

existe o arquivo teste.dbf
FILE("\SIGAADV\TESTE.dbf") // Verifica no diretrio Sigaadv do
servidor se existe o arquivo teste.dbf
FILE("C:\TEMP\TESTE.dbf") // // Verifica no diretrio Temp do cliente
(Remote) se existe o arquivo teste.dbf
Observao : Caso a funo File() seja executada em Job ( programa sem interface
remota ) , sendo passado um caminho absoluto de arquivo ( exemplo c:\teste.txt) , a
funo retornar .F. e FERROR() retornar -1 )
Sintaxe
FOPEN ( < cArq > , [ nModo ] ) --> nRet
Parmetros
Argumento
cArq
nModo
Tipo
Descrio
Nome do arquivo a ser aberto que inclui o path caso haja
Caracter
um.
Modo de acesso DOS solicitado que indica como o
arquivo aberto deve ser acessado. O acesso de uma das
categorias relacionadas na tabela A e as restries de
compartilhamento relacionada na Tabela B. O modo
Numrico
padrao zero, somente para leitura, com
compartilhamento por Compatibilidade. Ao definirmos o
modo de acesso , devemos somar um elemento da Tabela
A com um elemento da Tabela B.
Retorno
Tipo
Numrico
Descrio
FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535.
Caso ocorra um erro, FOPEN() retorna -1.
Descrio
Abre um arquivo binrio.
FOPEN() uma funao de tratamento de arquivo de baixo nvel que abre um arquivo
binrio existente para que este possa ser lido e escrito, dependendo do argumento
<nModo>. Toda vez que houver um erro na abertura do arquivo, FERROR() pode ser
usado para retornar o cdigo de erro do Sistema Operacional. Por exemplo, caso o
arquivo nao exista, FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o
arquivo nao foi encontrado. Veja FERROR() para uma lista completa dos cdigos de
erro.
Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do

Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de
banco de dados, e ele exigido para identificar o arquivo aberto para as outras funoes
de tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi
retornado a uma varivel para uso posterior, como mostra o exemplo desta funo.
Aviso
Esta funao permite acesso de baixo nvel a arquivos e dispositivos. Ela deve ser
utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional
utilizado.
Notas
FOPEN procura o arquivo no diretrio corrente e nos diretrios configurados na

varivel de pesquisa do Sistema Operacional, a nao ser que um path seja
declarado explicitamente como parte do argumento <cArq>.
Por serem executadas em um ambiente cliente-servidor, as funes de
tratamento de arquivos podem trabalhar em arquivos localizados no cliente
(estao) ou no servidor. O ADVPL identifica o local onde o arquivo ser
manipulado atravs da existncia ou no da letra do drive no nome do arquivo
passado em <cArq>. Ou seja, se o arquivo for especificado com a letra do drive,
ser aberto na estao. Caso contrrio, ser aberto no servidor com o diretrio
configurado como rootpath sendo o diretrio raz para localizao do arquivo.
Tabela A: Modos de Acesso a Arquivos Binrios

Modo Constante (fileio.ch) Operao
0
FO_READ
Aberto para leitura (padro assumido)
1
FO_WRITE
Aberto para gravao
2
FO_READWRITE Aberto para leitura e gravao
Tabela B: Modos de Acesso de Compartilhamento a Arquivos Binrios

Modo
0
16
32
48
Constante
Operao
(fileio.ch)
FO_COMPAT
Modo de Compatibilidade (Default)
FO_EXCLUSIVE Acesso total exclusivo
Acesso bloqueando a gravao de outros processos ao
FO_DENYWRITE
arquivo.
FO_DENYREAD Acesso bloqueando a leitura de outros processos ao arquivo.
64
FO_DENYNONE
64
FO_SHARED
Acesso compartilhado. Permite a leitura e gravao por

outros processos ao arquivo..
Igual FO_DENYNONE
No exemplo abaixo , tentamos abrir o arquivo error.log para escrita e gravao

compartilhada.
#include 'fileio.ch'
...
nH := fopen('\sigaadv\error.log' , FO_READWRITE + FO_SHARED )
If nH == -1
MsgStop('Erro de abertura : FERROR '+str(ferror(),4))
Else
MsgStop('Arquivo aberto com sucesso.')
...
fclose(nH)
Endif
...
Sintaxe
FREAD ( < nHanvle > , < cBuffer > , < nQtdBytes > ) --> nBytesLidos
Parmetros
Argumento
nHanvle
cBuffer
nQtdBytes
Tipo
Descrio
o manipulador (Handle) retornado pelas funes
FOPEN(),
Numrico
FCREATE(), FOPENPORT(), que faz referncia ao
arquivo a ser lido.
o nome de uma varivel do tipo String , a ser utilizada
como buffer de leitura , onde os dados lidos
devero ser armazenados. O tamanho desta varivel deve
ser maior ou igual ao tamanho informado em nQtdBytes.
Caracter
Esta varivel deve ser sempre passada por referncia. ( @
antes do nome da varivel ), caso contrrio os dados lidos
no sero retornados.
Define a quantidade de Bytes que devem ser lidas do
Numrico
arquivo a partor posicionamento do ponteiro atual.
Retorno
Tipo
Numrico
Descrio
Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada,
isto indica erro de leitura ou final de arquivo, Verifique a funo
FERROR() para maiores detalhes.
Descrio
FREAD() l os dados a partir um arquivo aberto, atravs de FOPEN(), FCREATE()
e/ou FOPENPORT(), e armazena os dados lidos por referncia no buffer informado.
FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum
erro ou o arquivo chegue ao final, FREAD() retornar um nmero menor que o
especificado em nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128,
ASC 0, etc.).
A varivel String a ser utiilzada como buffer de leitura deve ser sempre pr-alocado e
passado como referncia. Caso contrrio, os dados no podero ser retornados.
FREAD() l a partir da posio atual do ponteiro atual do arquivo , que pode ser
ajustado ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().
Sintaxe
FREADSTR ( < nHandle > , < nQtdBytes > ) --> cLidos
Parmetros
Argumento
nHandle
nQtdBytes
Tipo
Descrio
o manipulador retornado pelas funes FOPEN(),
Numrico
FCREATE(), FOPENPORT().
Numrico Nmero mximo de bytes que devem ser lidos.
Retorno
Tipo
Caracter
Descrio
Retorna uma string contendo os caracteres
lidos.
Descrio
L caracteres de um arquivo binrio.
FREADSTR() l de um arquivo aberto, atravs de FOPEN(), FCREATE(),
FOPENPORT().
FREADSTR() ler at o nmero de bytes informado em nQtdBytes ou at encontrar um
CHR(0). Caso acontea algum erro ou o arquivo chegue ao final, FREADSTR()
retornar uma string menor do que nQdBytes e colocar o erro em FERROR().
FREADSTR() l a partir da posio atual do ponteiro, que pode ser ajustado pelo
FSEEK(), FWRITE( ) ou FREAD().
Sintaxe
FRENAME ( < cOldFile > , < cNewFile > ) --> nStatus
Parmetros
Argumento
Tipo
Descrio
Nome do arquivo ser renomeado, aceita caminhos do
servidor e caminhos do cliente. Caso no seja especificado
Caracter
nenhuma unidade de disco e path, considerado o path
atual no servidor.
Novo nome do arquivo, aceita tambm caminho do
Caracter
servidor, e caminho do cliente.
cOldFile
cNewFile
Retorno
Tipo
Numrico
Descrio
Se o status retornado for -1 , ocorreu algum erro na mudana de nome :
Verifique se os dois caminhos esto no mesmo ambiente, verifique a
existncia do arquivo de origem, se ele no est em uso no momento por
outro processo , e verifique se o nome do arquivo de destino j no existe
no path de destino especificado.
Descrio
Atravs da funo FRENAME() possvel renomear um arquivo para outro nome, tanto
no servidor como na estao. Ao renomear um arquivo no esquea que esta arquivo
dever
estar fechado ( isto , no pode estar em uso por nenhum outro processo ou estao).
Caso o arquivo esteja aberto por outro processo , a operao de renomear o arquivo no
possvel. A funo fRename() no aceita wildcards ( * e/ou ? ).
Vale lembrar que no possvel renomear um arquivo especificando nos parmetros
simultaneamente um caminho de servidor e um de estao remota, bem como
especificar dois arquivos remotos e executar a funo fername() atravs de um JOB.
Caso isto ocorra, a funo retornar -1 , e fError() retornar tambm -1.
Importante : Quando especificamos um path diferente nos arquivos de origem e
destino , a funo fRename() realiza a funcionalidade de MOVER o arquivo para o
Path especificado.
Exemplos
// Renomeando um arquivo no Client de origem.txt para destino.txt , na
pasta c:\Temp
nStatus1 := frename('c:\Temp\Origem.txt' , 'c:\Temp\Destino.txt' )
IF nStatus1 == -1
MsgStop('Falha na operao 1 : FError '+str(ferror(),4))
Endif
// Renomeando um arquivo no Server, na pasta sigaadv , de error.log

para error.old
nStatus2 := frename('\sigaadv\error.log' , '\sigaadv\error.old' )
IF nStatus2 == -1
Endif
// Movendo um arquivo no client , da pasta Raiz para a pasta c:\Temp ,
alterando tambm o nome do arquivo.
nStatus3 := frename('c:\Lista.txt','c:\Temp\OldLista.txt')
IF nStatus3 == -1
Endif
Sintaxe
FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) --> nPos
Parmetros
Argumento
nHandle
nOffSet
nOrigem
Tipo
Descrio
Manipulador obtido atravs das funes
Numrico
FCREATE,FOPEN.
nOffSet corresponde ao nmero de bytes no ponteiro de
posicionamento do arquivo a ser movido. Pode ser um
Numrico
numero positivo , zero ou negativo, a ser considerado a
partir do parmetro passado em nOrigem.
Indica a partir de qual posio do arquivo, o nOffset ser
Numrico
considerado.
Retorno
Tipo
Numrico
Descrio
FSEEK() retorna a nova posiao do ponteiro de arquivo com relaao ao
incio do arquivo (posiao 0) na forma de um valor numrico inteiro. Este
valor nao leva em conta a posiao original do ponteiro de arquivos antes
da execuo da funo FSEEK().
Descrio
FSEEK() posiciona o ponteiro do arquivo para as prximas operaes de leitura ou
gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os
seguintes valores, definidos em fileio.ch:
Tabela A: Origem a ser considerada para a movimentao do ponteiro de
posicionamento do Arquivo.
Origem Constante
Operao
0
FS_SET
Ajusta a partir do inicio do arquivo. (Default)
1
FS_RELATIVE Ajuste relativo a posio atual do arquivo.
FS_END
Ajuste a partir do final do arquivo.
Sintaxe
FT_FEOF ( ) --> lRet
Retorno
Tipo
Lgico
Descrio
Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso
contrrio.
Descrio
Indica se o ponteiro esta posicionado no fim do arquivo texto.
A funo FT_FEof() retorna verdadeiro (.t.) se o arquivo texto aberto pela FT_FUSE
estiver posicionado no final do arquivo, similar funo Eof (), usada em tabelas de
dados.
Exemplos
O exemplo abaixo realiza a leitura de um arquvio texto, utilizando-se das funes
FT_F*
FT_FUse('teste.txt') // Abre o arquivo
conout("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha
["+FT_FReadln()+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo
Sintaxe
FT_FGOTO ( < nPos > ) --> NIL
Parmetros
Argumento
nPos
Tipo
Descrio
Indica a posio que ser colocado o ponteiro para leitura
Numrico
dos dados no arquivo.
Retorno
Tipo
(NULO)
Descrio
Descrio
A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto,
para a posio absoluta especificada pelo argumento <nPos>.
Sintaxe
FT_FGOTOP ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Descrio
A funo FT_FGoTop tem como objetivo posicionar o arquivo texto aberto pela
FT_FUse na
posio inicial do arquivo.
Entende-se como posio inicial do arquivo, o primeiro caracter da primeira linha do
arquivo texto.
Sintaxe
FT_FLASTREC ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo
esteja vazio, ou no exista arquivo aberto, a funo retornar 0 (zero)
Descrio
A funo tem o objetivo de retornar o nmero de linhas existentes do arquivo texto.
A funo FT_FLastRec retorna o nmero total de linhas do arquivo texto aberto pela
FT_FUse. As linhas so delimitadas pela sequncia de caracteres CRLF ou LF (*).
(*) Verifique maiores informaes sobre formato do arquivo e tamanho mximo da
linha de texto na funo FT_FREADLN()
Exemplos
O exemplo abaixo realiza a leitura de um arquvio texto, utilizando-se das funes
FT_F*
FT_FUse('teste.txt') // Abre o arquivo
conout("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha
["+FT_FReadln()+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo
Sintaxe
FT_FREADLN ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
Retorna a linha inteira na qual est posicionado o ponteiro para leitura de
dados.
Descrio
A funo tem como objetivo ler uma linha do arquivo texto.
A funo FT_FREADLN() retorna uma linha de texto do arquivo aberto pela FT_FUse.
As linhas so delimitadas pela sequncia de caracteres CRLF ( chr(13) + chr(10) ) , ou
apenas LF ( chr(10 ), e o tamanho mximo de cada linha 1022 bytes
Observaes
A utilizao desta funo no altera a posio do ponteiro para leitura dos

dados, o ponteiro do arquivo no movido. A movimentao do ponteiro
realizada atravs da funo FT_FSKIP()
O limite de 1022 bytes por linha inclui os caracteres delimitadores de final de
linha. Deste modo, quando utilizados os separadores CRLF, isto nos deixa 1020
bytes de texto, e utilizando LF, 1021 bytes. A tentativa de leitura de arquivos
com linhas de texto maiores do que os valores especificados acima resultar na
leiitura dos 1023 primeiros bytes da linha, e incorreta identificao das quebras
de linha posteriores.
As funes FT_F* foram projetadas para ler arquivos com contedo texto
apenas. A utilizao das mesmas em arquivos binrios pode gerar
comportamentos inesperados na movimentao do ponteiro de leitura do
arquivo, e incorretas identificaes nos separadores de final de linha.
Release
Quando utilizado um Protheus Server, com build superior a 7.00.050713P, a funo
FT_FREADLN() tambm capaz de ler arquivos texto / ASCII, que utilizam tambm o
caractere LF ( chr(10) ) como separador de linha.
Exemplos
Sintaxe
FT_FRECNO ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
Retorna a posio corrente do ponteiro do arquivo texto.
Descrio
A funo tem o objetivo de retornar a posio do ponteiro do arquivo texto.
A funo FT_FRecno retorna a posio corrente do ponteiro do arquivo texto aberto
pela FT_FUse.
Sintaxe
FT_FSKIP ( [ nLinhas ] ) --> NIL
Parmetros
Argumento
Tipo
Descrio
nLinhas
Numrico
nLinhas corresponde ao nmero de linhas do arquivo

TXT ref. movimentao do ponteiro de leitura do arquivo.
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL.
Descrio
Move o ponteiro do arquivo texto para uma nova posio.
A funo FT_FSkip move o ponteiro do arquivo texto aberto pela FT_FUse para a
prxima linha, similar ao DbSkip usado para tabelas de dados.
Sintaxe
FT_FUSE ( [ cTXTFile ] ) --> nHnd
Parmetros
Argumento
Tipo
Descrio
Corresponde o nome do arquivo TXT a ser aberto. Caso o
Caracter nome no seja passado, e j exisa um arquivo aberto. o
mesmo fechado.
cTXTFile
Retorno
Tipo
Numrico
Descrio
A funo retorna o Handle de controle do arquivo. Em caso de falha de
abertura, a funo retornar -1
Descrio
Abre ou fecha um arquivo texto para uso das funcoes FT_F*
As funes FT_F* so usadas para para ler arquivos texto, onde as linhas so
delimitadas pela sequncia de caracteres CRLF ou LF (*) e o tamanho mximo de cada
linha 1022 bytes.. O arquivo aberto em uma rea de trabalho, similar usada pelas
tabelas de dados.
(*) Maiores detalhes sobre a especificao do arquivo na funo FT_FREADLN()
Sintaxe
FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) --> nBytesEscritos
Parmetros
Argumento
nHandle
cBuffer
nQtdBytes
Tipo
Descrio
o manipulador de arquivo ou device retornado pelas
Numrico
funes FOPEN(), FCREATE(), ou FOPENPORT().
<cBuffer> a cadeia de caracteres a ser escrita no arquivo
especificado. O tamanho desta varivel deve ser maior ou
Caracter
igual ao tamanho informado em nQtdBytes (caso
seja informado o tamanho).
<nQtdBytes> indica a quantidade de bytes a serem
escritos a partir da posiao corrente do ponteiro de
Numrico
arquivos. Caso seja omitido, todo o contedo de
<cBuffer> escrito.
Retorno
Tipo
Numrico
Descrio
FWRITE() retorna a quantidade de bytes escritos na forma de um valor
numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
operaao foi bem sucedida. Caso o valor de retorno seja menor que
<nBytes> ou zero, ou o disco est cheio ou ocorreu outro erro. Neste caso
, utilize a funo FERROR() para obter maiores detalhes da ocorrncia.
Descrio
Voc pode escrever todo ou parte do contedo do buffer , limitando a quantidade de
Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da posio corrente do
ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes escritos.
Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou
criar um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou
enviados os dados do buffer informado. Por tratar-se de uma funo de manipulao de
contedo binrio , so suportados na String cBuffer todos os caracteres da tabela ASCII
, inclusive caracteres de controle ( ASC 0 , ASC 12 , ASC 128 , etc... ).
Caso acontea alguma falha na gravao , a funo retornar um nmero menor que o
nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro
especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do
ponteiro , que pode ser ajustado atravs das funes FSEEK() , FREAD() ou
FREADSTR().
Exemplo da funo FWRITE

Reviso: 27/05/2003
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Este exemplo realiza uma cpia de um arquivo Texto chamado ORIGEM.TXT , para
um arquivo chamado DESTINO.TXT , no ambiente do Protheus Server.
#INCLUDE "FILEIO.CH"
#DEFINE F_BLOCK 1024
/ gravados por vez
// Define o bloco de Bytes a serem lidos
User Function TestCopy()

Local cBuffer := SPACE(F_BLOCK)
Local nHOrigem , nHDestino
Local nBytesLidos , nBytesFalta , nTamArquivo
Local nBytesLer , nBytesSalvo
Local lCopiaOk := .T.
// Abre o arquivo de Origem
nHOrigem := FOPEN("ORIGEM.TXT", FO_READ)
// Testa a abertura do Arquivo
If nHOrigem == -1
MsgStop('Erro ao abrir origem. Ferror =
'+str(ferror(),4),'Erro')
Return .F.
Endif
// Determina o tamanho do arquivo de origem
nTamArquivo := Fseek(nHOrigem,0,2)
// Move o ponteiro do arquivo de origem para o inicio do arquivo
Fseek(nHOrigem,0)
// Cria o arquivo de destino
nHDestino := FCREATE("DESTINO.TXT", FC_NORMAL)
// Testa a criao do arquivo de destino
If nHDestino == -1
MsgStop('Erro ao criar destino. Ferror =
'+str(ferror(),4),'Erro')
FCLOSE(nHOrigem)
// Fecha o arquivo de Origem
Return .F.
Endif
// Define que a quantidade que falta copiar o prprio tamanho do
Arquivo
nBytesFalta := nTamArquivo
// Enquanto houver dados a serem copiados
While nBytesFalta > 0
// Determina quantidade de dados a serem lidos
nBytesLer
:= Min(nBytesFalta , F_BLOCK )
// l os dados do Arquivo
nBytesLidos := FREAD(nHOrigem, @cBuffer, nBytesLer )
// Determina se no houve falha na leitura

If nBytesLidos < nBytesLer
MsgStop(
"Erro de Leitura da Origem. "+;
Str(nBytesLer,8,2)+" bytes a
LER."+;
Str(nBytesLidos,8,2)+" bytes
Lidos."+;
"Ferror =
"+str(ferror(),4),'Erro')
lCopiaOk := .F.
Exit
Endif
// Salva os dados lidos no arquivo de destino
nBytesSalvo := FWRITE(nHDestino, cBuffer,nBytesLer)
// Determina se no houve falha na gravao
If nBytesSalvo < nBytesLer
MsgStop("Erro de gravao do Destino. "+;
Str(nBytesLer,8,2)+" bytes a
SALVAR."+;
Str(nBytesSalvo,8,2)+" bytes
gravados."+;
"Ferror =
"+str(ferror(),4),'Erro')
lCopiaOk := .F.
EXIT
Endif
// Elimina do Total do Arquivo a quantidade de bytes copiados
nBytesFalta -= nBytesLer
Enddo
// Fecha os arquivos de origem e destino
FCLOSE(nHOrigem)
FCLOSE(nHDestino)
If lCopiaOk
MsgStop('Cpia de Arquivos finalizada com sucesso. '+;
str(nTamArquivo,12,0)+' bytes
copiados.','Final')
Else
MsgStop( 'Falha na Cpia. Arquivo de Destino incompleto. '+;
'Do total de '+str(nTamArquivo,12,0)+'
bytes, faltaram '+str(nBytesFalta,12,0)+' bytes.','Final')
Endif
Return
Sintaxe
GETCLIENTDIR ( ) --> cPath
Retorno
Tipo
Caracter
Descrio
Retona o path onde est instalado o Protheus Remote.
Descrio
Retorna o diretrio completo onde o Remote est instalado, informando inclusive a
unidade de disco.
Observao : Esta funo apenas retornar um resultdo vlido caso seja
executada em um programa atravs do Protheus Remote . Caso esta funo seja
chamada em JOB , a mesma ocasionar um erro de execuo ( Error to
comunicate with Remote ) .
Exemplos
No exemplo abaixo , obtemos o drive e diretrio onde esto instalados o Remote .
MsgStop('Protheus Remote instalado em '+ GetClientDir())
Sintaxe
GETREMOTEININAME ( ) --> cArqConf
Retorno
Tipo
Caracter
Descrio
Path e nome do arquivo de configurao
Descrio
Retorna o nome do arquivo de configurao do AP Remote.
Exemplo das funes IsSrvUnix e

GetRemoteIniName
Reviso: 12/06/2003
Abrangncia
Verso 6.09
Verso 7.10
Verso 8.11
Atravs do exemplo abaixo, podemos obter o path de execuo do AP Remote.
#include "protheus.ch"
Function TstRmtPath()
Local cIniName:= GETREMOTEININAME()
Local lUnix:= IsSrvUnix()
Local nPos:= Rat( IIf(lUnix,"/","\"),cIniName )
Local cPathRmt
if nPos!=0
cPathRmt:= Substr( cIniName,1,nPos-1 )
else
cPathRmt:=""
endif
QOut( cPathRmt )
Return
Sintaxe
GETSRVPROFSTRING ( < cChave > , < cDefault > ) --> cConteudo
Parmetros
Argumento
cChave
Tipo
Descrio
Caracter Chave do INI do environment a ser lida,
cDefault o conteudo da chave a ser retornado caso a
Caracter
chave no seja encontrada no .ini
cDefault
Retorno
Tipo
Caracter
Descrio
Conteudo da chave especificada
Descrio
Atravs da funo GetSrvProfString , podemos obter o contedo de uma chave de
configurao do environment atual em uso no arquivo de Inicializao do Server
Protheus ( APxSrv.ini ) .
Sintaxe
MAKEDIR ( < cNovoDir > ) --> nResultado
Parmetros
Argumento
cNovoDir
Tipo
Descrio
Nome do diretrio a ser criado, incluindo opcionalmente o
Caracter
caminho (path).
Retorno
Tipo
Numrico
Descrio
Retorno zero ( 0 ),o diretrio foi criado com sucesso. Caso contrrio,
houve erro na criao do diretrio.
Descrio
Cria um diretrio na estao ou no servidor APx.
Caso o diretrio comece com um drive ( Ex: C:, X: ) o diretrio ser criado na estao,
caso contrrio ser criado no servidor.
MAKEDIR("c:\teste\um") // Cria um diretrio na estacao
nResult := MAKEDIR("\teste\um") // Cria o diretorio no servidor
Advanced protheus
IF nResult != 0
Conout( "Impossivel Criar o diretrio no servidor Protheus", nResult
)
ENDIF
MAKEDIR( "teste" ) // Exemplo tambm vlido ( Criando o diretrio no
servidor ) dentro do diretrio corrente
Sintaxe
MSCOMPRESS ( < cArq | aArquivos > , [ cDestino ] , [ cSenha ] ) --> cFileName
Parmetros
Argumento
Tipo
Descrio
Arquivo(s) a ser(em) compactado(s). Pode ser do tipo
String , para especificar um nico arquivo , ou do tipo
cArq | aArquivos (Qualquer)
Array , contendo um ou mais arquivo(s) a ser(em)
compatado(s).
Nome do Arquivo destino, caso a extenso seja omitida
ser assumido .MZP, se no for informado assumir o
cDestino
Caracter
mesmo nome do cArq com extenso .MZP ou o nome do
1. Arquivo no Array <aArquivos>.
Senha a ser utilizada para criptografar o arquivo
cSenha
Caracter
compactado.
Retorno
Tipo
Caracter
Descrio
Caso a compactao seja executada com sucesso , a funo retornar uma
sring contendo o nome do arquivo gerado . Caso no seja possvel a
compactao , por falta de espao em disco ou erro de acesso a algum dos
arquivos a ser(em) compactado(s), a funo retornar uma string em
branco ("").
Descrio
Compacta um ou vrios arquivos em um nico arquivo com extenso .MZP.
MSCOMPRESS() compacta os arquivos informados em um nico arquivo com
extenso default .MZP. O formato proprietrio e multiplataforma.
Caso a senha seja informada apenas com a senha poderemos descompactar os arquivos.
Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
Exemplos
// Exemplo 1 Compacta apenas um arquivo
lRes := MSCOMPRESS( "AP6SRV.EXE", "AP6SRV.MZP" )
// Exemplo 2 Compacta um diretrio com senha

aNome := {}
ADIR( "*.DBF", aNome )
lRes := MSCOMPRESS( aNome, "ArqComp.MZP", "SENHA" )
Sintaxe
MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess
Parmetros
Argumento
cArq
Tipo
Descrio
Caracter Nome do Arquivo no formato MZP a ser descompactado.
Path de destino onde sero gravados o(s) arquivo(s)
Caracter descompactado(s). Note que podem ser includos
caminhos do servidor como caminhos locais.
Caso o arquivo tenha sido compactado com senha , esta
Caracter deve ser especificada este parmetro para ser poss;ivel a
descompactao do arquivo.
cPathDestino
cSenha
Retorno
Tipo
Lgico
Descrio
Caso a descompactao foi executada com sucesso, a funo retornar .T.
, Em caso de erro durante a descompactao, a funo retrornar .F.
Verifique o espao disponvel na unidade de disco para descompactar o(s)
arquivo(s) e/ou se existe amgum arquivo a ser descompactado no pacote
que j exista na unidade de disco , atribudo como "REad-Only".
Descrio
MSDECOMP() descompacta o arquivo informado em um diretrio. O Formato

proprietrio, e multi-plataforma, suporta apenas arquivos compactados pela funo
MSCOMPRESS().
Caso o arquivo seja protegido por senha, apenas com a senha poderemos descompactlo.
Sintaxe
MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess
Parmetros
Argumento
cArq
Tipo
Descrio
Caracter Nome do Arquivo no formato MZP a ser descompactado.
Path de destino onde sero gravados o(s) arquivo(s)
Caracter descompactado(s). Note que podem ser includos
caminhos do servidor como caminhos locais.
Caso o arquivo tenha sido compactado com senha , esta
Caracter deve ser especificada este parmetro para ser poss;ivel a
descompactao do arquivo.
cPathDestino
cSenha
Retorno
Tipo
Lgico
Descrio
Caso a descompactao foi executada com sucesso, a funo retornar .T.
, Em caso de erro durante a descompactao, a funo retrornar .F.
Verifique o espao disponvel na unidade de disco para descompactar o(s)
arquivo(s) e/ou se existe amgum arquivo a ser descompactado no pacote
que j exista na unidade de disco , atribudo como "REad-Only".
Descrio
MSDECOMP() descompacta o arquivo informado em um diretrio. O Formato
proprietrio, e multi-plataforma, suporta apenas arquivos compactados pela funo
MSCOMPRESS().
Caso o arquivo seja protegido por senha, apenas com a senha poderemos descompactlo.
Sintaxe
SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) -->
NIL
Parmetros
Argumento
Tipo
Descrio
Nome do Arquivo a ser quebrado. Opcionalmente, pode
Caracter
incluir caminho e drive.
Nome do Drive. Exemplo ( C: ). Caso o Arquivo
Caracter informado no possua drive ou o caminho refira-se ao
servidor, o retorno ser uma string em branco.
Nome do Caminho. Caso o Arquivo informado no possua
Caracter
caminho, ser uma string em branco.
Nome do Arquivo sem a extenso. Caso em cArq no seja
Caracter especificado um nome do Arquivo, ser retornada uma
string em branco.
Extenso do arquivo informado em cArq , prefizada com
Caracter um ponto ".". Caso a extenso em cArq no seja
especificada , o retorno ser uma string em branco.
cArq
cDrive
cCaminho
cNome
cExt
Retorno
Tipo
Caracter
Descrio
Esta funo sempre retorna NIL.
Descrio
A funo SplitPath() divide um caminho completo em todas as suas subpartes ( Drive ,
Caminho , Nome e Extenso ) .
Tanto arquivos locais ( Remote ) quanto arquivos no servidor, podem ser informados.
O caminho, caso informado, incluir uma barra como ltimo caracter. A extenso ,
quando retornada , inclui sempre o ponto ( . ) antes da extenso.
Todos os parmetros , a partir do segundo , quando passados devem ser por referncia.
Observao : Vale lembrar que a funo SplitPath no valida a sintaxe do caminho
e/ou arquivo digitados , nem a existncia do mesmo . Esta funo utilizada para
determinar em uma string os elementos que compe um caminho para a
localizao de um arquivo.
Exemplos
No exemplo abaixo , exemplificamos o funcionamento da funo SplitPath , usando
combinaes de nomes de arquivos com ou sem drive , caminho , nome de arquivo e/ou
extenso.
User Function TSTSplit()
Local aArq := {} , cDrive, cDir, cNome, cExt
aadd(aArq,'c:\path\arquivo.ext')
aadd(aArq,'c:\path\arquivo')
aadd(aArq,'c:\path\')
aadd(aArq,'c:\arquivo')
aadd(aArq,'\path\arquivo.ext')
aadd(aArq,'path\arquivo')
aadd(aArq,'\\servidor\pasta\')
aadd(aArq,'\\servidor\pasta\arquivo.ext')
aadd(aArq,'')
For nI := 1 to len(aArq)
SplitPath( aArq[nI], @cDrive, @cDir, @cNome, @cExt )
conout( aArq[nI] + ' ['+cDrive+'] ['+ cDir +'] ['+ cNome +'] ['+
cExt + ']')
Next
Aps executado o programa acima, deve ser exibido no console do Protheus Server o
texto abaixo :
c:\path\arquivo.ext [c:] [\path\] [arquivo] [.ext]
c:\path\arquivo [c:] [\path\] [arquivo] []
c:\path\ [c:] [\path\] [] []
c:\arquivo [c:] [\] [arquivo] []
\path\arquivo.ext [] [\path\] [arquivo] [.ext]
path\arquivo [] [path\] [arquivo] []
\\servidor\pasta\ [] [\\servidor\pasta\] [] []
\\servidor\pasta\arquivo.ext [] [\\servidor\pasta\] [arquivo] [.ext]
[] [] [] []
Sintaxe
WRITEPPROSTRING ( < cSecao > , < cChave > , < cConteudo > , < cArqIni > ) -->
lSucess
Parmetros
Argumento
cSecao
cChave
cConteudo
cArqIni
Tipo
Descrio
cSecao corresponde o nome da seo do ni a ser
Caracter
utilizada. Caso a seo no exista , a mesma ser criada.
Chave da seo do ini a ter seu conteco alterado . Caso a
Caracter chave no esxista na seo especificada, a mesma ser
criada.
cConteudo corresponde o contedo da chave a ser
Caracter
atualizado.
cArqIni corresponde ao nome do arquivo de inicializao a
ser alterado. Caso o arquivo no exista , ele ser criado .
Caso o path do arquivo no seja informado , o mesmo ser
Caracter criado/atualizado no diretrio onde est instalado o
Protheus Server, no servidor. Caso especificado um path
absoluto , com unidade de disco , o arquivo .ini ser criado
e/ou atualizado na estao remota , no path informado.
Retorno
Tipo
Lgico
Descrio
Caso a chave seja incluida e/ou alterada com sucesso , a funo retornat
.T. (true) , e caso ocorra alguma falha ou impossibilidade de acesso ao
arquivo .ini , a funo retornar .F. (false). Dentre as causas mais comuns
de falha , podemos citar erro de sintaxe no nome do arquivo e/ou path
inexistente ou inacessvel.
Descrio
Atravs da funcao WritePProString() , possvel criar e/ou alterar uma seo / chave de
configurao em um arquivo .ini . Caso o arquivo no exista , o mesmo ser criado . No
nome do arquivo , podemos opcionalmente definir um path absoluto , com unidade de
disco , de modo que o arquivo .ini ser atualizado na estao remota ( onde est sendo
executado o Protheus Remote ) . Caso no seja especificado nenhum path ou caminho
do arquivo .ini , o caminho de disco considerado ser o path no Servidor onde est
instalado o Protheus Server .
FUNO DE TRATAMENTO DE CARACTERES

Sintaxe
ALLTRIM ( < cString > ) --> cTrimString
Parmetros
Argumento
Tipo
Descrio
<cString> a expressao caractere cujos espaos em branco
Caracter
serao eliminados.
cString
Retorno
Tipo
Caracter
Descrio
ALLTRIM() retorna uma cadeia de caracteres cujos espaos em branco
direita e esquerda foram removidos.
Descrio
ALLTRIM() uma funo de tratamento de dados do tipo caractere que remove os
espaos em branco direita e esquerda de uma cadeia de caracteres. relacionada a
LTRIM() e RTRIM(), que removem espaos em branco esquerda e direita de uma
cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM()
sao as funoes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou
alinham esquerda cadeias de caracteres atravs da insero de caracteres de
preenchimento.
Sintaxe
DESCEND ( < cString > ) --> cDescend
Parmetros
Argumento
Tipo
Descrio
<cString> corresponde sequncia de caracteres a ser
Caracter
analisada.
cString
Retorno
Tipo
Caracter
Descrio
DESCEND() retorna a string especificada como parmetro de uma forma
complementada. Um DESCEND() de CHR(0) sempre retorna CHR(0).
Descrio
DESCEND() uma funo de converso que retorna a forma complementada da
expresso string especificada. Esta funo normalmente utilizada para a criao de
indexadores em Ordem Decrescente.
Exemplos
Este exemplo utiliza DESCEND() em uma expressao INDEX para criar um ndice de
datas de ordem descendente:
USE Sales NEW
INDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate
Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice
descendente:
DbSEEK(DESCEND(DTOS(dFindDate)))
Observao : Faz-se necessria a converso da Data para String m atravs da

funo DTOS(), pois a funo DESCEND apenas trabalha com Strings.
Sintaxe
LTRIM ( < cString > ) --> cStringResult
Parmetros
Argumento
Tipo
Descrio
<cString> a cadeia de caracteres a ser copiada sem os
Caracter
espaos em branco esquerda.
cString
Retorno
Tipo
Caracter
Descrio
LTRIM() retorna uma cpia de <cString>, sendo que os espaos em
branco esquerda foram removidos. Caso <cString> seja uma cadeia de
caracteres nula ("") ou toda composta de espaos em branco, LTRIM()
retorna uma cadeia de caracteres nula ("").
Descrio
LTRIM() uma funao de tratamento de caracteres utilizada para Formatar cadeias de
caracteres que possuam espaos em branco esquerda. Pode ser o caso de, por exemplo,
nmeros convertidos para cadeias de caracteres atravs da funao STR().
LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a
ALLTRIM(), que remove espaos tanto esquerda quanto direita. O contrrio de
ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres,
atravs da inserao de caracteres de preenchimento.
Sintaxe
PADL / PADR / PADC ( < exp > , < nTamanho > , [ cCaracPreench ] ) -->
cStringPreench
Parmetros
Argumento
Tipo
exp
nTamanho
cCaracPreench
Descrio
<exp> um valor caractere, data, ou numrico no qual
Caracter
serao inseridos caracteres de preenchimento.
<nTamanho> o tamanho da cadeia de caracteres a ser
Numrico
retornada.
<cCaracPreench> o caractere a ser inserido em <exp>.
Caracter Caso nao seja especificado, o padrao o espao em
branco.
Retorno
Tipo
Descrio
Caracter
PADC(), PADL(), e PADR() retornam o resultado de <exp> na forma de

uma cadeia de caracteres preenchida com <cCaracPreench>, para totalizar
o tamanho especificado por <nTamanho>.
Descrio
PADC(), PADL(), e PADR() sao funoes de tratamento de caracteres que inserem
caracteres de preenchimento em valores caractere, data ou numricos a fim de criar uma
nova cadeia de caracteres de tamanho especificado. PADC() centraliza <exp>,
adicionando caracteres de preenchimento direita e esquerda; PADL() adiciona
caracteres de preenchimento esquerda; e PADR() adiciona caracteres de
preenchimento direita. Caso o tamanho de <exp> exceda o argumento <nTamanho>,
todas as funoes PAD() truncam cStringPreench ao <nTamanho> especificado.
PADC(), PADL(), e PADR() sao utilizadas para exibir cadeias de caracteres de tamanho
varivel em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para
assegurar o alinhamento com comandos ?? consecutivos. Outra utilizaao exibir textos
em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi
completamente sobreescrito.
PADC(), PADL(), e PADR() sao o contrrio das funoes ALLTRIM(), LTRIM(), e
LTRIM(), as quais eliminam espaoes em branco esquerda e direita de cadeias de
caracteres.
Sintaxe
RTRIM ( < cString > ) --> cTrimString
Parmetros
Argumento
Tipo
Descrio
<cString> a cadeia de caracteres a ser copiada sem os
Caracter
espaos em branco direita.
cString
Retorno
Tipo
Caracter
Descrio
RTRIM() retorna uma cpia de <cString>, sendo que os espaos em
branco direita foram removidos. Caso <cString> seja uma cadeia de
caracteres nula ("") ou totalmente composta por espaos, RTRIM() retorna
uma cadeia de caracteres nula ("").
Descrio
RTRIM() uma funao de tratamento de caracteres utilizada para Formatar cadeias de
caracteres que contenham espaos em branco direita. Ela til quando voc deseja
eliminar espaos em branco direita ao se concatenar cadeias de caracteres. o caso

tpico com campos de banco de dados que sao armazenados em formato de tamanho
fixo. Por exemplo, voc pode usar RTRIM() para concatenar o primeiro e o ltimo
campos de nome para formar uma cadeia de caracteres de nome.
LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a
ALLTRIM(), que remove espaos em branco direita e esquerda. O contrrio de
ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres,
inserindo caracteres de preenchimento.
Sintaxe
CDOW ( < dExp > ) --> cNomeDia
Parmetros
Argumento
dExp
Tipo Descrio
Data <dExp> o valor data a ser convertido.
Retorno
Tipo
Caracter
Descrio
CDOW() retorna o nome do dia da semana na forma de uma cadeia de
caracteres. A primeira letra ser maiscula e o resto dos caracteres vir em
minsculas. Para um valor de data nulo ou invlido, CDOW() retorna uma
cadeia de caracteres vazia ("").
Descrio
CDOW() uma funo utilizada para obter, a partir de uma data, a cadeia de caracteres
contendo o dia da semana correspondente.
Exemplos
Os exemplos a seguir ilustram o funcionamento da funao CDOW():
conout( DATE() )
conout( CDOW(DATE()) )
conout( CDOW(DATE() + 7) )
conout( CDOW(CTOD("12/06/90")) )
// Resulta: 08/04/02
// Resulta: Sunday
// Resulta: Sunday
// Resulta: Thursday
Sintaxe
CMONTH ( < dData > ) --> cMs
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> a data a converter.
Retorno
Tipo
Caracter
Descrio
CMONTH() retorna o nome do ms a partir de uma data como sendo uma
cadeia de caracteres com a primeira letra maiscula e o restante da string
em letras minsculas. Para uma data nula, CMONTH() retornar uma
string nula ("").
Descrio
CMONTH() uma funo de converso de datas que , a partir de uma data , retorna
uma cadeia de caracteres correspondendo ao nome do ms correspondente.
Exemplos
Os exemplos seguintes ilustram a utilizaao da funao CMONTH():
conout( CMONTH(DATE()) )
Resulta: August
conout( CMONTH(DATE() + 45) )
Resulta: September
conout( SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE()),3))
Resulta: Aug 4
//
//
//
Sintaxe
DATE ( ) --> dSistema
Retorno
Tipo
Data
Descrio
DATE() retorna a data do sistema como sendo um valor do tipo data.
Descrio
Retorna a data do sistema.
DATE() a funo que retorna a data do atual sistema. O formato de
sada controlado pelo comando SET DATE. O formato padro mm/dd/yy.
Exemplos
conout(
conout(
conout(
dDate =
conout(
DATE() )
DATE() + 30 )
DATE() - 30 )
DATE()
CMONTH(dDate) )
// Resulta: 08/04/02
// Resulta: 09/03/02
// Resulta: 07/05/02
// Resulta: August
Sintaxe
DAY ( < dData > ) --> nDia
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> a data a converter.
Retorno
Tipo
Numrico
Descrio
DAY() retorna um nmero na faixa de 0 at 31, sendo este um valor
numrico inteiro. Caso o ms seja Fevereiro, os anos bissextos sao
considerados. Se o argumento de data 29 de Fevereiro e o ano nao
bissexto, DAY() retornar zero. Se o argumento de data vazio, DAY()
tambm retornar zero.
Descrio
Retorna o dia do ms como valor numrico. DAY() uma funao de conversao de datas
utilizada para converter um valor do tipo data para o dia do ms correspondente. Esta
funo usada em conjunto com CMONTH() e YEAR() para formatar datas. Alm
disso, geralmente usada em clculos que envolvam datas.
Exemplos
Os exemplos seguintes mostram a funao DAY() sendo utilizada
de diversas maneiras:
conout(
conout(
conout(
conout(
DATE() )
DAY(DATE()) )
DAY(DATE()) + 1)
DAY(CTOD("")) )
// Resulta: 09/01/90
// Resulta: 1
// Resulta: 2
// Resulta: 0
Este exemplo utiliza DAY() em conjunto com CMONTH() e YEAR()

para formatar um valor do tipo data:
conout( CMONTH(DATE()) + STR(DAY(DATE())) +;
"," + STR(YEAR(DATE())) )
// Resulta: June 15, 1990
Sintaxe
DOW ( < dData > ) --> nDia
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data que ser convertido.
Retorno
Tipo
Numrico
Descrio
DOW() retorna o dia da semana na forma de um nmero entre zero e sete.
O primeiro dia da semana um (Domingo) e o ltimo sete (Sbado). Se
<dData> estiver vazio, DOW() retorna zero.
Descrio
DOW() uma funao de conversao de datas que converte um valor data para um
nmero que identifica o dia da semana. Ela til quando voc deseja clculos de data
em uma base semanal. DOW() semelhante a CDOW(), a qual retorna o dia da semana
na forma de uma cadeia de caracteres ao invs de um nmero.
Exemplos
Os exemplos a seguir ilustram CDOW() e seu relacionamento com DOW():
conout(
conout(
conout(
conout(
conout(
DATE() )
DOW(DATE()) )
CDOW(DATE()) )
DOW(DATE() - 2) )
CDOW(DATE() - 2) )
//
//
//
//
//
Resulta:
Resulta:
Resulta:
Resulta:
Resulta:
09/01/89
3
Terca-feira
1
Domingo
A seguir est uma funao definida por usurio que utiliza DOW() para calcular a data da
ltima segunda-feira a partir de qualquer outra data:
USER FUNCTION LastMonday(dData)
Return (dData - DOW(dData) + 2)
Sintaxe
DTOC ( < dData > ) --> cData

Parmetros
Argumento
dData
Tipo Descrio
Retorno
Tipo
Caracter
Descrio
DTOC() retorna uma cadeia de caracteres que representa uma data. O
valor de retorno formatado de acordo com o formato de datas corrente. O
formato padrao mm/dd/aa. Uma data nula retorna uma cadeia de
caracteres em branco igual em tamanho ao formato de data corrente.
Descrio
DTOC() uma funao de conversao de datas utilizada por motivos de Formataao
quando voc deseja exibir a data no formato SET DATE e necessria uma expressao
caractere. Caso voc precise de um formato de data especfico, voc pode utilizar
TRANSFORM() ou uma expressao customizada.
Se voc estiver INDEXando uma data juntamente com uma cadeia de caracteres, use
DTOS() ao invs de DTOC() para converter o valor data para uma cadeia de caracteres.
Exemplos
Os exemplos a seguir demonstram utilizaoes gerais de DTOC():
conout( DATE() )
conout( DTOC(DATE()) )
conout( "Hoje e " + DTOC(DATE()) )
// Resulta: 09/01/90
// Resulta: 09/01/90
// Resulta: Hoje e 09/01/90
Sintaxe
DTOS ( < dData > ) --> cData
Parmetros
Argumento
dData
Tipo Descrio
Retorno
Tipo
Descrio
Caracter
DTOS() retorna uma cadeia com oito caracteres no formato, aaaammdd.

Quando <dData> for uma data nula (CTOD("")), DTOS() retorna uma
cadeia de oito caracteres em branco. O valor de retorno nao afetado pelo
Formato de data corrente.
Descrio
DTOS() uma funao de conversao de datas utilizada para criar expressoes de ndice
que consistem em um valor data e uma expressao caractere. DTOS() converte um valor
data para uma cadeia de caracteres que pode ser concatenada a qualquer outra expressao
caractere. O valor de retorno estruturado para preservar a ordem de data (ano, ms, e
dia).
Exemplos
Os exemplos a seguir ilustram DTOS() em conjunto com vrias outras funoes:
conout( DATE() )
conout( DTOS(DATE()) )
conout( LEN(DTOS(CTOD(""))) )
// Resulta: 09/01/90
// Resulta: 19900901
// Resulta: 8
Este exemplo demonstra como criar um ndice com uma data

composta e chave de caractere utilizando DTOS():
USE Vendas NEW
INDEX ON DTOS(Data) + Vendedor TO DataVend
Sintaxe
ELAPTIME ( < cHoraInicial > , < cHoraFinal > ) --> cIntervalo
Parmetros
Argumento
Tipo
Descrio
Informe a hora inicial no formato hh:mm:ss, onde hh a
Caracter
hora ( 1 a 24 ), mm os minutos e ss os segundos
Informe a hora final no formato hh:mm:ss, onde hh a
Caracter
hora ( 1 a 24 ), mm os minutos e ss os segundos.
cHoraInicial
cHoraFinal
Retorno
Tipo
Caracter
Descrio
A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),
mm os minutos e ss os segundos
Descrio
ElapTime() retorna uma cadeia de caracteres contendo a diferena de
tempo entre cHoraFinal - cHoraInicial , no formato hh:mm:ss.
Os dois parmetros , cHoraInicial e cHoraFinal , devem ser especificados no formato
hh:mm:ss , com tamanho de 8 bytes . Caso um dos parmetros tenha tamanho diferente
de 8 Bytes, gerada uma ocorrncia de Erro Fatal "invalid len". Qualquer caracter
invalido nas posices referentes hora (hh) , minuto (mm) e segundo (ss) , sero
ignorados na composio de numeros para o clculo. Caso o horrio inicial seja maior
que o horrio final , retornada a diferena entre os horrios acrescidos de 24h. Para
maiores detalhes , consulte o exemplo da funo ElapTime()
Exemplos
Este exemplo utiliza a funo ElapTime() para calcular o tempo necessrio para um
determinado processamento.
cHoraInicio := TIME() // Armazena hora de inicio do processamento
.
. <instrucoes>
.
cElapsed := ELAPTIME(TIME(),cHoraInicio) // Calcula a diferena de
tempo
Sintaxe
MONTH ( < dData > ) --> nMs
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data a ser convertido.
Retorno
Tipo
Numrico
Descrio
MONTH() retorna um valor numrico inteiro na faixa de 0 (zero) a 12.
Uma data nula (CTOD("")) retorna zero.
Descrio
MONTH() uma funao de conversao de datas que til quando voc precisa de um
valor de ms numrico durante clculos para, por exemplo, relatrios peridicos.
MONTH() faz parte de um grupo de funoes que retornam componentes de um valor
data na forma de valores numricos. O grupo inclui DAY() e YEAR(), que retornam os
valores de dia e ano na Forma de nmericos. CMONTH() uma funao relacionada,

que permite a voc retornar o nome do ms a partir de um valor data.
Exemplos
Estes exemplos ilustram o retorno do ms da data do sistema:
conout( DATE() )
conout( MONTH(DATE()) )
conout( MONTH(DATE()) + 1 )
// Resulta: 09/01/90
// Resulta: 9
// Resulta: 10
Este exemplo demonstra a funao MONTH() atuando em uma data nula:

conout( MONTH(CTOD("")) )
// Resulta: 0
Sintaxe
SECONDS ( ) --> nSegundos
Retorno
Tipo
Numrico
Descrio
SECONDS() retorna a hora do sistema como um valor numrico na forma
segundos.centsimos. O valor numrico retornado a quantidade de
segundos decorridos desde a meia-noite, e tem base em um relgio de
vinte e quatro horas em uma faixa de zero a 86399.
Descrio
SECONDS() uma funao de horas utilizada para fornecer um mtodo simples de
calcular o tempo decorrido, com base no relgio do sistema, durante a execuao do
programa. relacionado funao TIME(), a qual retorna a hora do sistema como uma
cadeia de caracteres na forma hh:mm:ss.
Exemplos
Este exemplo compara o valor de TIME() com o de SECONDS():
conout( TIME() )
conout( SECONDS() )
// Resulta: 10:00:00
// Resulta: 36000.00
Este exemplo demonstra como utilizar SECONDS() para informar o tempo decorrido
em segundos:
LOCAL nStart, nElapsed
nStart = SECONDS()
.
. <processamentos...etc....>
.
nElapsed = SECONDS() - nStart
conout( "Decorridos: " + LTRIM(STR(nElapsed)) + " segundos" )
Sintaxe
TIME ( ) --> cStringHora
Retorno
Tipo
Caracter
Descrio
TIME() retorna a hora do sistema como uma cadeia de caracteres na forma
hh:mm:ss. hh indica a hora no formato de 24 horas, mm indica os minutos,
e ss indica os segundos. Horas, minutos e segundos sao separadas por dois
pontos.
Descrio
TIME() uma funao de tratamento de tempo, utilizada para exibir ou imprimir a hora
do sistema em um relatrio ou na tela. TIME() est relacionada a SECONDS(), que
retorna a quantidade de segundos decorridos desde a meia-noite. SECONDS()
geralmente utilizada em lugar de TIME() para clculos sobre o tempo.
Exemplos
Estes exemplos mostram a funo TIME() utilizada em conjunto com SUBSTR()
para extrair a hora, os minutos e os segundos:
cTime := TIME() // Resultado: 10:37:17
cHora := SUBSTR(cTime, 1, 2) // Resultado: 10
cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37
cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17
Sintaxe
YEAR ( < dData > ) --> nAno
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data a ser convertido.
Retorno
Tipo
Numrico
Descrio
YEAR() retorna o ano do valor data especificado, inclusive dgitos
indicativos de sculo, na forma de um valor numrico de quatro dgitos. O
valor retornado nao influenciado pelo formato de DATE ou CENTURY
corrente. A especificaao de uma data nula (CTOD("")) retorna zero.
Descrio
YEAR() uma funao de conversao de datas utilizada para converter um valor data para
um valor numrico indicativo do ano. Pode ser utilizada em clculos de, por exemplo,
relatrios peridicos, ou para Formataao de exibioes de data.
YEAR() membro de um grupo de funoes que retornam componentes de um valor
data na forma de valores numricos. Este grupo inclui DAY() e MONTH(), que
retornam valores de dia e ms na forma de valores numricos.
Exemplos
Os exemplos a seguir ilustram YEAR() usando a data do
sistema:
conout( DATE() )
conout( YEAR(DATE()) )
conout( YEAR(DATE()) + 11 )
// Resulta: 09/01/90
// Resulta: 1990
// Resulta: 2001
Este exemplo cria uma funao definida pelo usurio usando

YEAR() para formatar um valor data na forma : ms dia, ano:
conout( U_Mdy(DATE()) )
1990
// Resulta: September 20,
USER FUNCTION Mdy( dDate )

Return CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate)));
+ "," + STR(YEAR(dDate))
FUNES DE TRATAMENTO DE MATRIZ

Sintaxe
AADD ( < aDestino > , [ expValor ] ) --> Valor
Parmetros
Argumento
aDestino
expValor
Tipo
Array
Descrio
o array ao qual o novo elemento ser adicionado.
uma expresso vlida que ser o valor do
(Qualquer)
novo elemento.
Retorno
Tipo
(Qualquer)
Descrio
Avalia expValor e retorna seu Valor. Se expValor no for especificado,
AADD() retorna NIL.
Descrio
AADD() uma funo de tratamento de vetor que adiciona um elemento ao vetor. Ao
elemento de vetor recm criado atribuido o valor especificado por <expValor>.
AADD() utilizado para aumentar o tamanho de um vetor dinamicamente. til na
construo de filas ou listas dinmicas.
AADD() semelhante funo ASIZE(), mas adiciona apenas um elemento por vez;
ASIZE() pode aumentar ou diminuir um vetor a um tamanho especificado. AADD(),
porm, possui a vantagem de poder atribuir um valor ao novo elemento, enquanto que
ASIZE() nao pode. AADD() pode tambm parecer ser igual a AINS(), mas isso nao
verdade: AINS() move elementos dentro de um vetor, mas nao modifica o tamanho do
vetor.
OBSERVAO : Caso <expValor> seja um outro vetor, o novo elemento no vetor
destino conter uma referncia ao vetor especificado por <expValor>.
Os exemplos a seguir demonstram os efeitos de chamadas mltiplas da funo AADD()

para um vetor:
aArray := {}
AADD(aArray, 5)
AADD(aArray, 10)
AADD(aArray, { 12, 10 })
}
//
//
//
//
Resulta:
Resulta:
Resulta:
Resulta:
aArray
aArray
aArray
aArray
e
e
e
e
um vetor vazio
{ 5 }
{ 5, 10 }
{ 5, 10, { 12, 10 }
Sintaxe
ACLONE ( < aFonte > ) --> aDuplica
Parmetros
Argumento
Tipo Descrio
Array <aFonte> o vetor a ser duplicado.
aFonte
Retorno
Tipo
Array
Descrio
Array idntico ao aFonte , porem sem nenhuma referncia ao mesmo.
Descrio
ACLONE() uma funao de vetor que cria uma duplicata completa do vetor de
<aFonte>. Caso <aFonte> contenha sub-vetores, ACLONE() cria sub-vetores
correspondentes e os preenche com cpias dos valores contidos nos sub-vetores de
<aFonte>.
Ao igualarmos dois arrays, eles ficam associados por referncia, utilizando
aClone() no existe referncia. ACLONE() semelhante a ACOPY(), porm ACOPY()
nao duplica vetores aninhados.
Sintaxe
ACOPY ( < aFonte > , < aDestino > , [ nInicio ] , [ nCont ] , [ nPosDestino ] ) -->
aDestino
Parmetros
Argumento
aFonte
aDestino
nInicio
nCont
nPosDestino
Tipo
Array
Descrio
<aFonte> o vetor de onde serao copiados os elementos.
<aDestino> o vetor para onde serao copiados os
Array
elementos.
<nInicio> a posiao do elemento inicial no vetor
Numrico <aFonte>. Se nao for especificado, o valor assumido um
(01).
<nCont> a quantidade de elementos a serem copiados
do vetor <aFonte> a partir da posiao <nInicio>. Caso
Numrico <nCont> nao seja especificado, todos os elementos em
<aFonte> que comeam com o elemento inicial sao
copiados.
<nPosDestino> a posiao do elemento inicial no vetor
Numrico <aDestino> que receber os elementos de <aFonte>. Se
nao for especificado, o valor padrao um (01).
Retorno
Tipo
Array
Descrio
ACOPY() retorna uma referncia ao vetor destino, <aDestino>.
Descrio
ACOPY() uma funao de tratamento de vetor que copia elementos do vetor <aFonte>
para o vetor <aDestino>. O vetor <aDestino> j deve existir e ser grande o suficiente
para conter os elementos copiados. Caso o vetor <aFonte> tenha mais elementos, alguns
elementos nao serao copiados.
ACOPY() copia valores de todos os tipos de dados, inclusive NIL e blocos de cdigo.
Se um elemento do vetor <aFonte> for um sub-vetor, o elemento correspondente no
vetor <aDestino> conter uma referncia ao sub-vetor. Consequentemente, ACOPY()
nao cria duplicatas completas de vetores multi-dimensionais. Para fazer isto, use a
funao ACLONE().
Exemplos
Este exemplo cria dois vetores, cada um deles preenchido com um valor. Os dois
primeiros elementos do vetor fonte sao entao copiados para o vetor destino:
LOCAL nCount := 2, nStart := 1, aOne, aTwo
aOne := { 1, 1, 1 }
aTwo := { 2, 2, 2 }
ACOPY(aOne, aTwo, nStart, aCont)
// Resulta: aTwo e agora { 1, 1, 2
}
Sintaxe
ADEL ( < aFonte > , < nPosicao > ) --> aFonte
Parmetros
Argumento
aFonte
nPosicao
Tipo
Descrio
<aFonte> o vetor que contm um elemento a ser
Array
eliminado.
<nPosiao> a posiao do elemento de vetor , a partir do
Numrico
primeiro , que ser eliminado.
Retorno
Tipo
Array
Descrio
ADEL() retorna uma referncia ao vetor destino, <aFonte>.
Descrio
ADEL() uma funao de tratamento de vetor que elimina um elemento de um vetor. O

contedo do elemento de vetor especificado perdido, e todos os elementos a partir
daquela posiao at o final do elemento sobem uma posiao. O ltimo elemento no
vetor torna-se NIL.
AVISO : Em Advpl, vetores multi-dimensionais sao implementados atravs do
aninhamento de vetores dentro de outros vetores. Caso o vetor <aFonte> seja um vetor
multi-dimensional, ADEL() eliminar todo o sub-vetor especificado por <nPosiao>,
forando <aFonte> a nao mais ter dimensoes regulares.
Este exemplo cria um vetor constante de trs elementos, e depois
elimina o segundo elemento. O terceiro elemento sobe uma posiao, e ao
novo terceiro elemento atribuido NIL:
LOCAL aArray
aArray := { 1, 2, 3 }
ADEL(aArray, 2)
}
// Resulta: aArray e agora { 1, 2, 3 }

// Resulta: aArray e agora { 1, 3, NIL
Sintaxe
AEVAL ( < aVetor > , < bBloco > , [ nInicio ] , [ nCont ] ) --> aVetor
Parmetros
Argumento
aVetor
bBloco
nInicio
nCont
Tipo
Array
Descrio
<aVetor> o vetor a ser varrido.
<bBloco> um bloco de cdigo a ser executado para
Code-Block
cada elemento encontrado.
<nInicio> o elemento inicial. Caso nao seja
Numrico
especificado, o padrao assumido o elemento um.
<nCont> a quantidade de elementos a serem
Numrico processados a partir de <nIncio>. Se nao for
especificado, o padrao todos os elementos no vetor.
Retorno
Tipo
Array
Descrio
AEVAL() retorna uma referncia a <aVetor>.
Descrio
AEVAL() uma funao de tratamento de vetor que avalia um bloco de cdigo uma vez
para cada elemento de um vetor, passando o valor do elemento como um parmetro de
bloco. O valor de retorno do bloco ignorado. Todos os elementos no <aVetor> sao
processados a nao ser que o argumento <nInicio> ou <nCont> seja especificado.
AEVAL() nao faz suposioes sobre o contedo dos elementos de vetor que ele est
passando para o bloco. assumido que o bloco sabe qual o tipo de dados haver em
cada elemento.
AEVAL() semelhante a DBEVAL(), que aplica um bloco para cada registro de um
arquivo de banco de dados. Da mesma forma que DBEVAL(), AEVAL() pode ser
utilizado como base para a construao de comandos de interaao tanto para estruturas de
vetor complexas como simples.
Consulte a seao Blocos de Cdigo no na seo A Linguagem Advpl para maiores
informaes sobre Code-Blocks.
Exemplos
Local aArray := { "Teste" , 123 }
Local bBlock := { |x,y| conout(valtype(x)) , conout(y) }
aEval(aArray,bBlock)
No exemplo acima , criamos um array com 2 elementos : O primeiro um Caracter , e o

segundo um nmero ; e criamos um code-block que receber em x ( primeiro
parametro fornecido pela funo aEval) cada elemento do array , e y ( segundo
parametro fornecido pela aEval ) o nmero do elemento do array que est sendo
processado nesta execuo.
O resultado de tela no console do Protheus Server dever ser :
Teste // Conteudo do primeiro elemento
C // Tipo do conteudo
1 // Numero do elemento processado
123 // Conteudo do segundo elemento
N // Tipo do Segundo Elemento
2 // Numero do elemento processado
Caso o array passado como parmetro seja um array multi-Dimensional , sero passados
como parmetros os arrays de primeiro nivel para o code-BLock.
Vejamos uma aplicao mais complexa : Um array multi-dimensional temos 2colunas ,
uma de cdigo (string) e uma de valor ( numrica ) , e seja necessrio realizar um
clculo de totalizao da coluna numrica :
aItens := {}
aadd(aItens,{"Branco",10})
aadd(aItens,{"Preto",15})
aadd(aItens,{"Cinza",12})
// Podemos realizar a totalizao pelo metodo tradicional :

nTotal := 0
For nI := 1 to len(aItens)
nTotal := nTotal + aItens[nI][2]
Next
conout(nTotal) // 37
// Ou utilizando a Funco aEval :

nTotal := 0
aeval(aItens , {|x| nTotal += x[2] } )
conout(nTotal)
Sintaxe
AFILL ( < aDestino > , < ValorExp > , [ nInicio ] , [ nCont ] ) --> aDestino
Parmetros
Argumento
aDestino
ValorExp
nInicio
nCont
Tipo
Array
Descrio
<aDestino> o vetor a ser preenchido.
<ValorExp> o valor a ser alocado em cada elemento de
(Qualquer) vetor. Pode ser uma expressao de qualquer tipo de dados
vlido.
<nInicio> a posiao do primeiro elemento a ser
Numrico preenchido. Caso este argumento seja omitido, o valor
padrao um.
<nCont> a quantidade de elementos a serem
preenchidos iniciando com o elemento <nInicio>. Se este
Numrico
argumento for omitido, os elementos sao preenchidos a
partir da posiao do elemento inicial at o final do vetor.
Retorno
Tipo
Array
Descrio
AFILL() retorna uma referncia ao <aDestino>.
Descrio
AFILL() uma funao de vetor que preenche um vetor especificado com um nico
valor de qualquer tipo de dados (inclusive vetores, blocos de cdigo ou NIL) atribuindo
<ValorExp> a cada elemento de vetor na faixa especificada.
ATENO : AFILL() nao pode ser utilizado para preencher vetores multidimensionais. Este tipo de vetores em Clipper sao implementados aninhando-se vetores
dentro de outros vetores. A utilizaao de AFILL() com vetores multi-dimensionais
sobre-escrever vetores para as outras dimensoes do vetor.
Exemplos
Neste exemplo, criado um vetor com trs elementos. O vetor depois preenchido com
falso (.F.). Ao final, aos elementos nas posioes dois e trs atribuido o novo valos de
verdadeiro (.T.):
LOCAL aLogic[3]
AFILL(aLogic, .F.)
AFILL(aLogic, .T., 2, 2)
// Resulta: aLogic e { NIL, NIL, NIL }

// Resulta: aLogic e { .F., .F., .F. }
// Resulta: aLogic e { .F., .T., .T. }
Sintaxe
AINS ( < aDestino > , < @nPos > ) --> aDestino
Parmetros
Argumento
aDestino
nPos
Tipo
Array
Descrio
o array de onde ser inserido um item NIL.
a posio, a partir da 1, na qual ser inserido um
Numrico
elemento NIL
Retorno
Tipo
Array
Descrio
Retorna uma referncia ao vetor aDestino
Descrio
AINS() uma funo de vetor que insere um novo elemento em um vetor especificado.
O elemento recm inserido NIL at que um novo valor seja atribuido a ele. Aps a
insero, o ltimo elemento no vetor descartado, e todos os elementos depois do novo
elemento descem uma posio.
AVISO : AINS() deve ser utilizado com cuidado quando se tratar de vetores multidimensionais. Vetores multi-dimensionais em Advpl sao implementados atravs do
aninhamento de vetores dentro de outros vetores. Utilizar AINS() com um vetor multidimensional descarta o ltimo sub-vetor no vetor destino especificado, o que causa a
perda de uma ou mais dimensoes. Para inserir uma nova dimensao em um vetor,
primeiramente adicione um novo elemento ao final do vetor utilizando AADD() ou

ASIZE() antes de usar AINS().
Exemplos
Este exemplo demonstra o efeito da utilizao de AINS() em um vetor:
LOCAL aArray
aArray := { 1, 2, 3 }
AINS(aArray, 2)
}
// Resulta: aArray e agora { 1, 2, 3 }

// Resulta: aArray e agora { 1, NIL, 2
Sintaxe
ARRAY ( < nElementos,... > ) --> aVetor
Parmetros
Argumento
Tipo
nElementos,...
Descrio
<nElementos> a quantidade de elementos na dimensao
Numrico especificada.Os vetores em Advpl podem ter um nmero
ilimitado de dimensoes.
Retorno
Tipo
Array
Descrio
ARRAY() retorna um vetor de dimensoes especificadas.
Descrio
ARRAY() uma funao de tratamento de vetor que retorna um vetor nao inicializado
com a quantidade especificada de elementos e dimensoes. Se for especificado mais de
um argumento <nElementos>, criado um vetor multi-dimensional ou aninhado, sendo
que a quantidade de dimensoes igual quantidade de argumentos <nElementos>
especificada.
No Advpl, h vrias formas de se criar um vetor. Voc pode declarar um vetor
utilizando LOCAL ou STATIC; voc pode criar um vetor utilizando PRIVATE ou
PUBLIC; voc pode atribuir um vetor literal a uma varivel existente; ou voc pode
usar a funao ARRAY(). ARRAY() tem a vantagem de possibilitar a voc a criaao de
vetores dentro de expressoes ou blocos de cdigo.
Exemplos
Este exemplo cria um vetor unidimensional de cinco elementos utilizando a funao
ARRAY(), e depois exibe a aao equivalente atribuindo um vetor literal de valores NIL:
aArray := ARRAY(5)
aArray := { NIL, NIL, NIL, NIL, NIL }
Este exemplo ilustra trs declaraoes diferentes que criam o mesmo vetor multidimensional:
aArray := ARRAY(3, 2)
aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} }
aArray := { ARRAY(2), ARRAY(2), ARRAY(2) }
Sintaxe
ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm
Parmetros
Argumento
aDestino
ProcuraExp
nInicio
nCont
Tipo
Array
Descrio
<aDestino> o vetor a ser varrido.
<ProcuraExp> pode ser um valor simples a ser
procurado, ou um bloco de cdigo. Caso <ProcuraExp>
(Qualquer)
seja um valor simples, este poder ser do tipo numrico,
lgico, data, ou caractere.
<nInicio> o elemento a partir do qual ter incio a
Numrico pesquisa. Se este argumento nao for especificado, a
posiao inicial padrao um.
<nCont> a quantidade de elementos que serao varridos
a partir da posiao inicial. Caso este argumento nao seja
Numrico
especificado, todos os elementos, desde o elemento
inicial at o final do vetor, serao varridos.
Retorno
Tipo
Numrico
Descrio
ASCAN() retorna um valor numrico que representa a posiao ocupada no
vetor pelo ltimo elemento varrido. Se <ProcuraExp> for um valor
simples, ASCAN() retorna a posiao do primeiro elemento que
corresponder ao valor procurado, ou zero caso nao haja correspondncia.
Se <ProcuraExp> for um bloco de cdigo, ASCAN() retorna a posiao do
elemento onde o bloco retornou verdadeiro (.T.).
Descrio
ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor
especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor
simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea
com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai
para o prximo elemento no vetor.
Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente
igual ao resultado de <ProcuraExp> para que haja correspondncia.
Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor
<aDestino> executando o bloco para cada elemento acessado. medida em que cada
elemento encontrado, ASCAN() passa o valor do elemento como um argumento para
o bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra
quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo
elemento no vetor.
Exemplos
O exemplo a seguir demonstra a pesquisa em um vetor de trs elementos utilizando
valores simples e um bloco de cdigo como critrios de pesquisa. Os critrios do bloco
de cdigo ilustram como executar uma pesquisa que nao faz diferenciaao entre
maisculas e minsculas:
aArray := { "Tom", "Mary", "Sue" }
? ASCAN(aArray, "Mary")
? ASCAN(aArray, "mary")
? ASCAN(aArray, { |x| UPPER(x) == "MARY" })
// Resulta: 2
// Resulta: 0
// Resulta: 2
O Exemplo abaixo demonstra como continuar a pesquisa dos mltiplos tipos de um

argumento de pesquisa aps ter sido encontrada uma correspondncia:
LOCAL aArray := { "Tom", "Mary", "Sue", "Mary" }, nStart := 1
// Pegar ultima posicao de elemento de vetor
nAtEnd := LEN(myVetor)
While (nPos := ASCAN(aArray, "Mary", nStart)) > 0
? nPos, aArray[nPos]
// Pegar nova posicao inicial e testar condicao de limite
If (nStart := ++nPos) > nAtEnd
EXIT
EndIf
EndDo
Sintaxe
ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm
Parmetros
Argumento
aDestino
ProcuraExp
nInicio
nCont
Tipo
Array
Descrio
<aDestino> o vetor a ser varrido.
<ProcuraExp> pode ser um valor simples a ser
procurado, ou um bloco de cdigo. Caso <ProcuraExp>
(Qualquer)
seja um valor simples, este poder ser do tipo numrico,
lgico, data, ou caractere.
<nInicio> o elemento a partir do qual ter incio a
Numrico pesquisa. Se este argumento nao for especificado, a
posiao inicial padrao um.
<nCont> a quantidade de elementos que serao varridos
a partir da posiao inicial. Caso este argumento nao seja
Numrico
especificado, todos os elementos, desde o elemento
inicial at o final do vetor, serao varridos.
Retorno
Tipo
Numrico
Descrio
ASCAN() retorna um valor numrico que representa a posiao ocupada no
vetor pelo ltimo elemento varrido. Se <ProcuraExp> for um valor
simples, ASCAN() retorna a posiao do primeiro elemento que
corresponder ao valor procurado, ou zero caso nao haja correspondncia.
Se <ProcuraExp> for um bloco de cdigo, ASCAN() retorna a posiao do
elemento onde o bloco retornou verdadeiro (.T.).
Descrio
ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor
especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor
simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea
com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai
para o prximo elemento no vetor.
Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente
igual ao resultado de <ProcuraExp> para que haja correspondncia.
Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor
<aDestino> executando o bloco para cada elemento acessado. medida em que cada
elemento encontrado, ASCAN() passa o valor do elemento como um argumento para
o bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra
quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo
elemento no vetor.
Exemplos
O exemplo a seguir demonstra a pesquisa em um vetor de trs elementos utilizando

valores simples e um bloco de cdigo como critrios de pesquisa. Os critrios do bloco
de cdigo ilustram como executar uma pesquisa que nao faz diferenciaao entre
maisculas e minsculas:
aArray := { "Tom", "Mary", "Sue" }
? ASCAN(aArray, "Mary")
? ASCAN(aArray, "mary")
? ASCAN(aArray, { |x| UPPER(x) == "MARY" })
// Resulta: 2
// Resulta: 0
// Resulta: 2
O Exemplo abaixo demonstra como continuar a pesquisa dos mltiplos tipos de um

argumento de pesquisa aps ter sido encontrada uma correspondncia:
LOCAL aArray := { "Tom", "Mary", "Sue", "Mary" }, nStart := 1
// Pegar ultima posicao de elemento de vetor
nAtEnd := LEN(myVetor)
While (nPos := ASCAN(aArray, "Mary", nStart)) > 0
? nPos, aArray[nPos]
// Pegar nova posicao inicial e testar condicao de limite
If (nStart := ++nPos) > nAtEnd
EXIT
EndIf
EndDo
Parmetros
Argumento
destino
procura
nInicio
nCont
Tipo
Descrio
Representa o objeto a ser varrido pela funo, pode ser
(Qualquer)
atribuido ao parametro um array um Objeto.
Representa o valor que ser pesquisado, podendo ser um
(Qualquer)
bloco de cdigo.
Representa o elemento a partir do qual ter inicio a
Numrico pesquisa, quando este argumento nao for informado o
valor default ser 1.
Representa a quantidade de elementos que sero
pesquisados a partir da posio inicial, quando este
Numrico
argumento nao for informado todos elementos do array
sero pesquisados
Retorno
Tipo
Numrico
Descrio
Retorna o valor numrico(indice) que representa a posio ocupada no
vetor pelo ultimo elemento pesquisado, no caso quando a o elemnto foi
encontrado.
Descrio
A funo ASCANX() uma funao de tratamento de vetor. ASCANX tem como
objetivo varrer um vetor
procurando um valor especificado e opera de forma parecida com a funo ASCAN.
A diferena fundamental da funao ASCANX que a funo recebe um segundo
parametro em seu codeblock representando o indice do array.
Exemplo.:
nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y<=100})
Nesta linha de exemplo, note a incluso no codeblock do Y, onde a funo ir terminar
sua execuo em 3 condioes:
1) At encontrar o elemento no ARRAY com a ocorrncia cNome, retornando a
posio desse elemento.
2) Essa novidade, ASCANX ir verificar o Array at a posio 100.
3)O elemento cNome nao foi encontrado no ARRAY e a condio de Y at 100 nao
satizfaz, pois o array menor do que 100 posioes!
Obs.: Como ASCAN() que utiliza o operador (=) para comparaoes, a funao
ASCANX() tambm case sensitive, no caso os elementos procurados devem ser
exatamente igual.
Sintaxe
ASIZE ( < aDestino > , < @nTamanho > ) --> ASIZE()
Parmetros
Argumento
aDestino
nTamanho
Tipo
Descrio
Array
<aDestino> o vetor a ser aumentado ou diminuido.
Numrico <nTamanho> o novo tamanho do vetor.
Retorno
Tipo
Array
Descrio
Retorna uma referncia ao array aDestino.
Descrio
ASIZE() uma funo de tratamento de vetor que muda o valor real do vetor
<aDestino>. O vetor diminuido ou aumentado para corresponder ao tamanho
especificado. Caso o vetor seja diminuido, os elementos no final do vetor sao perdidos.
Se o vetor for aumentado, novos elementos sao adicionados ao final do vetor e a eles
atribuido NIL.
ASIZE() semelhante a AADD(), o qual adiciona somente um novo elemento ao final
de um vetor e opcionalmente atribui um novo valor ao mesmo tempo. Observe que
ASIZE() diferente de AINS() e ADEL(), os quais na realidade nao modificam o
tamanho do vetor.
Exemplos
Estes exemplos demonstram a adio de novos elementos e a eliminao de elementos
existentes:
aArray := { 1 }
ASIZE(aArray, 3)
ASIZE(aArray, 1)
// Resulta: aArray e { 1 }
// Resulta: aArray e { 1, NIL, NIL }
// Resulta: aArray e { 1 }
Sintaxe
ASORT ( < aDestino > , [ nInicio ] , [ nCont ] , [ bOrdem ] ) --> aDestino
Parmetros
Argumento
aDestino
nInicio
nCont
bOrdem
Tipo
Descrio
<aDestino> o vetor cujos elementos serao colocados
Array
em ordem.
<nInicio> o primeiro dos elementos que serao
Numrico colocados em ordem. Caso nao seja especificada, a
posiao inicial assumida um.
<nCont> a quantidade de elementos que serao
colocados em ordem. Se nao for especificada, todos os
Numrico
elementos no vetor que comeam com o elemento inicial
sao ordenados.
<bOrdem> um bloco de cdigo opcional utilizado para
determinar qual a ordem que ser seguida. Caso nao seja
especificada, a ordem padrao ascendente. *** Ateno
Code-Block
: Caso utilizada a funo aSort para um array aninhado
(milti-dimensional), o parmetro bOrdem deve ser
passado ; caso contrrio o array no ser ordenado.
Retorno
Tipo
Array
Descrio
ASORT() retorna uma referncia ao vetor <aDestino>.
Descrio
ASORT() uma funao de vetor que coloca em ordem todo ou parte de um vetor que
contm elementos de um nico tipo de dados. Os tipos de dados que podem ser
ordenados incluem caractere, data, lgico e numrico.
Se o argumento <bOrdem> nao for especificado, a ordem padrao ascendente.
Elementos com valores baixos sao colocados no incio do vetor (primeiro elemento),
enquanto elementos com valores altos sao colocados no final do vetor (ltimo
elemento).
Caso o argumento de bloco <bOrdem> seja especificado, ele utilizado para determinar
a ordem em que os elementos serao colocados. Cada vez que o bloco avaliado, dois
elementos do vetor destino sao passados como parmetros de bloco. O bloco deve
retornar verdadeiro (.T.) se os elementos estiverem ordenados. Isto pode ser usado para
criar uma ordem descendente ou de dicionrio. Veja os exemplos abaixo.
Quando ordenadas, as cadeias de caracteres sao colocadas na sequncia ASCII; valores
lgicos sao ordenados com falso (.F.) sendo considerado o valor menor; valores data sao
ordenados cronologicamente; e numricos sao ordenados por magnitude.
OBSERVAO : Sendo os vetores multi-dimensionais em Clipper implementados
atravs do aninhamento de sub-vetores dentro de outros vetores, ASORT() nao ordena
diretamente vetores deste tipo. Para ordenar um vetor aninhado, voc deve fornecer um
bloco de cdigo que dar o tratamento adequado aos sub-vetores.
Exemplos
No Exemplo abaixo , ordenamos um array em ordem crescenter , depois em ordem
decrescente atravs de um code-block .
Local aArray := { 3, 5, 1, 2, 4 }
ASORT(aArray) // Resultado: { 1, 2, 3, 4, 5 }
ASORT(aArray,,,{ |x, y| x > y }) // Resultado: { 5, 4, 3, 2, 1 }
No Exemplo abaixo , utilizamos na expresso de ordenao a funo upper() , para

ordenar o array em ordem alfabrica independentemente da informao estar em letras
maisculas e/ou minusculas.
aArray := { "Fred", Kate", "ALVIN", "friend" }
ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) })
No exemplo abaixo , montamos um code-block para ordenao de um array multidimensional , para ordenar o array em ordem crescente do segundo elemento da
dimenso.
aKids := { {"Mary", 14}, {"Joe", 23},{"Art", 16} }
aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })

// Resultado : { {"Mary", 14}, {"Art", 16}, {"Joe",23} }
Sintaxe
ATAIL ( < aArray > ) --> Ret
Parmetros
Argumento
aArray
Tipo Descrio
Array Representa o array a ser informado para a funo.
Retorno
Tipo
(Qualquer)
Descrio
Retorna ltima ocorrencia ou o ltimo elemento do array.
Descrio
A funo tem o objetivo de retornar a ltima ocorrncia do array informado pelo
argumento <aArray>, caso o argumento Array passado esteja vazio a funo ir retornar
NIL.
Se for informado um argumento que no for um Array para a funo, isto ir causar um
um erro ADVPL.
Ex:
user function tstArray()
Local aArray := {'ola', 'ops', 'oq', 'aff', 'oljha'}
Local cRet
cRet := atail(aArray) //retorna oljha
return cRet
FUNES TRATAMENTO XML
Sintaxe
XmlChildCount ( < oParent > ) --> nChild

Parmetros
Argumento
Tipo
Descrio
Indica o node XML no qual ele ir fazer a contagem dos
Objeto
filhos.
oParent
Retorno
Tipo
Numrico
Descrio
Retorna o numero de elementos encontrados.
Descrio
A funo tem o objetivo de retornar a quantidade de ns existentes, a partir de um nodo
pai informado como argumento.
A funo no faz essa contagem recursivamente pela estrutura, ou seja, ela nao varre a
estrutura entrando em todos subNodos a partir do elemento passado como raiz para a
contagem e sim apenas os filhos de primeiro nvel.
Essa funo util para manipularmos os objetos XML diretamente, sem
necessariamente conhecermos o contedo do objeto.
Sintaxe
XmlChildEx ( < OParent > , < cProcura > ) --> retorno
Parmetros
Argumento
Tipo
Descrio
Nodo usado para indicar o inicio da procura do elemento
Objeto
requerido.
Caracter Representa o nome do elemento que desejamos encontrar.
OParent
cProcura
Retorno
Tipo
(Qualquer)
Descrio
Quando a funao encontrar apenas um elemento ser retornado o objeto
node, caso possua mais de um elemento do mesmo nome ir retornar um
array dos nodes, caso contrrio retorna NIL.
Descrio
A funo tem o objetivo de retornar um ou mais filhos da estrutura, de acordo com o

nome do elemento procurado.
Especificando um elemento qualquer do objeto para a funo, na qual ser usado como
base para busca apenas em seu primeiro sub-nvel a funo ir retornar todos os
nodos filhos que encontar.
til quando quando queremos buscar por um elemento filho e exista mais de um
elemento do mesmo tipo.
Sintaxe
XmlCloneNode ( < oParent > , < cNewName > ) --> Nil
Parmetros
Argumento
oParent
cNewName
Tipo
Descrio
Objeto Representa o objeto node XML no qual ser colando
Caracter Indica o nome no qual ser atribuido o node clonado
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de criar um clone, do n informado pelo parametro,
especificando um novo nome para o elemento, de forma que a funo clona apenas o
node, as propriedades no.
Quando o nodo clonado esta com o mesmo nome de um existente, ento criado um
array automaticamente com os nodos.
Ela pode ser utilizada para acrescentarmos dados em um modelo de xml j existente.
Sintaxe
XmlDelNode ( < oParent > , < cNode > ) --> Nil
Parmetros
Argumento
oParent
Tipo
Descrio
Objeto Representa o Node pai do elemento que ser removido.
cNode
Caracter
Representa o Real name do elemento node que ser

removido.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de deletar um nodo de um objeto xml.
Para isto informamos passando por parametro um elemento do objeto que contm a
estrutura do xml(um nodo qualquer), este nao precisa ser obrigatriamente o root da
estrutura.
Em seguida informamos o nome do nodo que desejamos deletar, pois a funo ir
procurar recursivamente a partir do nodo informado, o elemento que possu o nome do
nodo a ser deletado dentro da estrutura.
A xmlDelNode ir deletar todos nodos que contenham o nome igual ao do nodo
informado para ser deletado a partir do nodo informado para pesquisa.
A funo retorna true caso consiga encontrar um elemento e deleta-lo, false caso
contrrio.
Exemplos
Neste exemplo, criamos uma string contendo o xml, em seguida parseamos ele, e agora
vamos deletar um nodo do objeto retornado pela xmlParser, note que no exemplo passei
o nodo '<itens>' como raiz da estrutura a ser pesquisada e queremos deletar o nodo
'<item>', que elemento de '<itens>'.
A funo xmlDelNode tem como objetivo deletar todos os elementos '<item>' que
encontrar dentro da estrutura passada para inicio da pesquisa.
User Function getObjXML()
Local cError
:= ""
Local cWarning := ""
Local oXml := NIL
//Gera o Objeto XML
oXml := XmlParser( GeraXML(), "_", @cError, @cWarning )
if !XmlDelNode( oScript:_PEDIDO:_ITENS, "_ITEM" )

conout("Nao foi possivel excluir")
EndIf
// Tranforma o Objeto XML em arquivo ou string

// Grava o arquivo em um diretrio \xml a partir do rootPath
SAVE oXml XMLFILE "\xml\teste.xml"
Return oXml
// funo para gerar uma string contendo um xml
Static Function GeraXML()
Local cScript := '<?xml version="1.0" encoding="UTF-8"?>'
cScript += "<pedido>"
cScript += " <Nome Cliente>Microsiga Software S/A</Nome
Cliente>"
cScript += " <Endereco>Av. Braz Leme</Endereco>"
cScript += " <Numero>1361</Numero>"
cScript += " <Data>22-03-2005</Data>"
cScript += " <Itens>"
cScript += "
<Item>"
cScript += "
<Produto>Prothues</Produto>"
cScript += "
<Quantidade>1</Quantidade>"
cScript += "
<Preco>100.00</Preco>"
cScript += "
</Item>"
cScript += "
<Item>"
cScript += "
<Produto>ERP<Produto>"
cScript += "
cScript += "
<Preco>0</Preco>"
cScript += "
</Item>"
cScript += " </Itens>"
cScript += "</pedido>"
Return cScript
Sintaxe
XmlGetChild ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de retornar um elemento filho da estrutura.
Especificando um elemento qualquer do objeto para a funo, na qual ir usar como
base para retornar o nodo filho de nmero indicado pelo segundo parametro passado
para a funo.
til quando queremos mudar o posicionamento do objeto, para algum nodo filho
do atual na estrutura do objeto XML.
No Exemplo seguinte usamos a funo para nos posicionar no nodo <itens>, em seguida
apagamos todos os nodos filhos com a xmlDelNode.
Usando o comando SAVE criamos um arquivo teste.xml ao final da execuo do
programa.
User Function ExeXML()
Local cError
:= ""
Local oScript
Local cFile := ""
//a partir do rootpath do ambiente
cFile := "\xml\pedido.xml"
//Gera o Objeto XML ref. ao script
oScript := XmlParser( GeraXML(), "_", @cError, @cWarning )
oScript := XmlGetchild( oScript:_PEDIDO , XmlChildCount(
oScript:_PEDIDO ))
// Agora vou apagar um node
if !XmlDelNode( oScript , "_ITEM" )
conout("Nao foi possivel apagar o nodo")
EndIf
// Tranforma o Objeto XML em arquivo
SAVE oScript XMLFILE "\xml\teste.xml"
Return oScript
// Script XML a gerar objeto
Cliente>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript += "
cScript += "
</Item>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript
cScript
cScript
cScript
+=
+=
+=
+=
"
<Preco>0</Preco>"
"
</Item>"
" </Itens>"
"</pedido>"
Return cScript
Sintaxe
XmlGetParent ( < oNode > ) --> oParent
Parmetros
Argumento
Tipo
Descrio
representa o node no qual ser usado como referncia para
Objeto
o retorno do node pai.
oNode
Retorno
Tipo
Objeto
Descrio
Um objeto posicionado no node de acordo com o argumento passado.
Descrio
A funo tem o objetivo de retornar um nodo que representa o nodo 'pai'
do elemento especificado por parametro.
til quando queremos 'subir' na estrutura do objeto XML
Sintaxe
XmlNewNode ( < oParent > , < cElementName > , < cRealName > , < cType > ) --> Nil
Parmetros
Argumento
oParent
cElementName
cRealName
cType
Tipo
Descrio
Objeto Indica o local onde ser inserido o novo node XML.
Caracter o nome do elemento Node no XML
Caracter o nome Real do Node XML
Caracter Representa o tipo de node XML que ser criado
Retorno
Tipo
Objeto
Descrio
Nil
Descrio
A funo tem o objetivo de criar um novo nodo a partir de um ponto qualquer no xml.
Para isto necessrio informar em qual ponto do objeto xml(o xml parseado) que
desejamos adicionar um novo elemento.
O novo nodo ser adicionado como filho do nodo passado por parametro, onde sero
informados tambm os dados em relao a ele:
-REALNAME
-ELEMENTNAME
-TYPE
(para entender melhor o funcionamento da funo veja o exemplo)
Exemplos
Neste exemplo criamos o xml atravs da funo GeraXML, parseamos ele atravs da
xmlParser retornando o objeto xml.
Em seguida visualizamos o objeto retornado e usamos a funao xmlChildCount
retornando a quantidade de elementos no objeto contendo o xml. No Nosso exemplo a
funo ir retornar 5 elementos.
Agora usaremos a xmlNewNode, especificando que o novo nodo ser adicionado como
filho de '<pedido>', logo depois acessamos o nodo e acrecentamos um texto para ele.
obs: o resultado disso no xml ser <exemplo1>Exemplo Microsiga</exemplo1>
Aps a criao do nodo, a xmlChildCount ir retornar 6 indicando que o nodo foi
inserido.
Local cError
:= ""
Local cXML := ""
Local oXml := NIL
//Gera o Objeto XML
//verifica quantos elementos possuo
conout( XmlChildCount( oScript:_PEDIDO ) )
// Criando um node
XmlNewNode(oScript:_PEDIDO, "Exemplo1", "Exemplo1", "NOD" )
//setando o CONTEUDO do meu nodo ""
oXml:_PEDIDO:Exemplo1:Text := "Exemplo Microsiga"
//verifica quantos elementos possuo depois da insero
conout( XmlChildCount( oScript:_PEDIDO ) )
// Tranforma o Objeto XML em string

SAVE oXml XMLSTRING cXML
Return oXml
Cliente>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript += "
cScript += "
</Item>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript += "
<Preco>0</Preco>"
cScript += "
</Item>"
Return cScript
Sintaxe
XmlNode2Arr ( < oRoot > , < cNode2Array > ) --> lRet
Parmetros
Argumento
Tipo
oRoot
cNode2Array
Descrio
Elemento Node no qual ser usado como root para inicio
Objeto
da busca do elemento a ser tranformado em array.
Representa o elemento procurado para ser transformado
Caracter
em array na estrutura.
Retorno
Tipo
Lgico
Descrio
Retorna true caso consiga transformar em array, false caso contrrio.
Descrio
A funo tem o objetivo de transformar em array, um objeto(node) da estrutura do xml.
Informando um elemento(node) da estrutura XML atravs de parametro como raiz, a

funo ir procurar pelo nome do nodo no qual se deseja transformar em array.
Exemplos
No exemplo seguinte demonstrado o simples uso da funo XmlNode2Arr, em que
pegamos o objetoXml e o tranformamos em um array.
Em seguida gravamos esse objeto em arquivo .xml propriamente dito.
User Function ExeXML()
Local cError
:= ""
Local oScript
//Gera o Objeto XML ref. ao script
oScript := XmlParser( GeraXML(), "_", @cError, @cWarning )
// Transforma node em uma array, no caso tranforma a estrutura
para array
XmlNode2Arr( oScript:_PEDIDO, "_PEDIDO" )
// Tranforma o Objeto XML em arquivo
// Grava o arquivo em um diretrio \xml a partir do rootPath
SAVE oScript XMLFILE "\xml\teste.xml"
Return .T.

Cliente>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript += "
cScript += "
</Item>"
cScript += "
<Item>"
cScript += "
cScript += "
cScript += "
<Preco>0</Preco>"
cScript += "
</Item>"
Return cScript
Sintaxe
XmlParser ( < cXml > , < cReplace > , < @cError > , < @cWarning > ) --> oXML
Parmetros
Argumento
cXml
Tipo
Descrio
Caracter a cadeia de caracteres que contm o cdigo XML.
Representa o valor a ser atribuido para os caracteres de
Caracter
espao encontrados na especificao dos nodes XML.
Caso ocorra algum erro durante execuo da funo, a
Caracter
varivel ser preenchida com a descrio do erro ocorrido.
Caso ocorra algum alerta de 'warning' durante execuo da
Caracter funo, a varivel ser preenchida com a descrio do
'warning' ocorrido.
cReplace
cError
cWarning
Retorno
Tipo
Objeto
Descrio
Representa um objeto com a estrutura de acordo com o XML.
Descrio
A funo tem o objetivo de retornar um objeto que possu uma estrutura referente
ao xml, passado pelo parametro na funo.
A estrutura retornada:
<ObjXML>
<NodeXML>
-<ArrayNodes>
-REALNAME
-TEXT
-TYPE
Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem.
A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do
mesmo tipo. (demonstrado no exemplo)
Exemplos
Neste exemplo criamos uma funo geraXml que retorna uma string contento um
XML.
Quando passamos essa string para a XmlParser, a funo ir montar o objeto analisando
se a sintaxe e a ordem das tags est bem formada, caso isso nao ocorra a funo ir
retonar um warning ou at um possvel erro, nos parametros informados por referncia.
A estrutura:
oXml:
pedido:
-realName
-type
-text
nome_cliente:
-realName
-type
-text
endereo:
-realName
-type
-text
numero:
-realName
-type
-text
data:
-realName
-type
-text
itens:
-item <- (array)
-item[1]:
-realName
-type
-text
produto:
quantidade:
preco:
-item[2]
-realName
-type
-text
produto:
quantidade:
preco:
-realName
-type
-text
Caso isso nao ocorra a funo ir retornar o objeto contendo uma estrutura em forma de
arvore, no caso a mesma estrutura do xml.
Local cError
:= ""
Local cXML := ""
Local oXml := NIL
//Gera o Objeto XML
//acessando o CONTEUDO do meu nodo ""
oXml:_PEDIDO:_NOME_CLIENTE:Text := "Microsiga"
// Tranforma o Objeto XML em string
//SAVE oXml XMLSTRING cXML
Return oXml
Local cScript := '
Sintaxe
XmlParserFile ( < cFile > , < cReplace > , < @cError > , < @cWarning > ) --> oXML
Parmetros
Argumento
Tipo
Descrio
Representa o path de um arquivo .xml, indicando o local
Caracter
onde se encontra o arquivo no disco.
Representa o valor a ser atribuido para os caracteres de
Caracter
espao encontrados na especificao dos nodes XML.
cError Caracter Caso ocorra algum erro durante execuo
Caracter da funo, a varivel ser preenchida com a descrio do
erro ocorrido.
cWarning Array Caso ocorra algum alerta de 'warning'
Caracter durante execuo da funo, a varivel ser preenchida
com a descrio do 'warning' ocorrido.
cFile
cReplace
cError
cWarning
Retorno
Tipo
Objeto
Descrio
Retorna um objeto q contm uma estrutura de acordo com o XML.
Descrio
A funo tem o objetivo de retornar um objeto que possu uma estrutura referente ao
arquivo .xml, passado pelo parametro na funo.
A estrutura retornada:
<ObjXML>
<NodeXML>
-<ArrayNodes>
-REALNAME
-TEXT
-TYPE
Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem.
A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do
mesmo tipo. (demonstrado no exemplo)
Exemplos
Neste exemplo vamos usar a funo que tem o mesmo objetivo da XmlParser, a
diferena que esta l um arquivo do disco com a extenso .xml.
Quando passamos a string informando o path do arquivo em disco, devemos lembrar
que a procura do arquivo ser feita atravs do rootpath do Protheus.
logo aps a leitura do arquivo a funo ir montar o objeto analisando se a sintaxe e a
ordem das tags est bem formada, caso isso no ocorra a funo ir retonar um warning
ou at um possvel erro, nos parametros informados por referncia.
Caso isso nao ocorra a funo ir retornar o objeto contendo uma estrutura em forma de
arvore, no caso a mesma estrutura do xml.
Local cError
:= ""
Local oXml := NIL
Local cFile := ""
//a partir do rootpath do ambiente
cFile := "\xml\pedido.xml"
//Gera o Objeto XML
oXml := XmlParserFile( cFile, "_", @cError, @cWarning )
//acessando o CONTEUDO do meu nodo ""
oXml:_PEDIDO:_NOME_CLIENTE:Text := "Microsiga"
Return oXml
INFORMAES ADICIONAIS
ARREDONDAMENTO
No Protheus, pode haver diferena de arredondamento em algumas operaes
numricas. Isso ocorre devido a diferenas no armazenamento de variveis numricas
nos diversos processadores. Diferena esta, inclusive, presente no Advpl, mesmo antes
do surgimento do Protheus.
Para evitar esses problemas de arredondamento, utilize a funo 'Round', principalmente
antes de realizar uma comparao, e antes de utilizar a funo 'Int'. Desse
modo, assegura-se que o resultado ser correto independentemente do processador /
plataforma.
Exemplos:
1. If (Valor/30) = 50
// pode ser falso ou invlido
If Round(Valor/30, 0) = 50 // correto
2. M->EE8_QTDEM1:= Int (M->EE8_SLDINI/M->EE8_QE)
falso ou invlido
correto
// pode ser
M->EE8_QTDEM1:= Int (Round(M->EE8_SLDINI/M->EE8_QE, 10)) //
CRIAO DE CLASSES
Podemos criar Classes prprias em Advpl ; bastando para tal nos utilizarmos dos
comandos de declarao de Classes , Mtodos e Propriedades do Protheus. Veja abaixo
um modelo simples que exemplifica a utilizao e declarao de uma Classe de
Exemplo utilizando Advpl:
// Crio uma funo para teste da Classe Exemplo
Function u_teste()
Local oSoma1 := Exemplo():New() // Crio um novo objeto de exemplo (
objeto 1 )
Local oSoma2 := Exemplo():New() // Crio outro objeto de exemplo (
objeto 2 )
// Realizo 3 chamadas ao mtodo Soma, com o objeto 1
oSoma1:Soma(10)
oSoma1:Soma(20)
oSoma1:Soma(30)
// Realizo 2 chamadas ao mtodo Soma, com o objeto 2
oSoma2:Soma(30)
oSoma2:Soma(30)
// Imprimo no console o acumulador das somas do obj 1 ( 60 )
conout(oSoma1:nAcumulador)
// Imprimo no console o acumulador das chamadas soma com o objeto 1

( 3 )
conout(oSoma1:nChamadas)
// Imprimo no console o acumulador das somas do obj 2 ( 60 )
conout(oSoma2:nAcumulador)
// Imprimo no console o acumulador das chamadas soma com o objeto 2
(2)
conout(oSoma2:nChamadas)
Return
// ------------------------------------------------------------------------------// Declaracao da Classe Exemplo
// ------------------------------------------------------------------------------CLASS Exemplo
// Declaracao das propriedades da Classe
DATA nAcumuladorDATA nChamadas
// Declarao dos Mtodos da Classe
METHOD New() CONSTRUCTORMETHOD Soma( nNum )
ENDCLASS
// Criao do construtor, onde atribuimos os valores default
// para as propriedades e retornamos Self
METHOD New() Class Exemplo
::nAcumulador := 0
::nChamadas := 0
Return Self
// Criao do Mtodo de Soma , que recebe um nmero e o soma
// ao acumulador, retornando o conteudo do acumululador aps
// a soma , e incrementa em 1 o contador de chamadas do mtodo
METHOD Soma( nNum ) Class Exemplo
::nAcumulador += nNum
::nChamadas++
Return ::nAcumulador
Podemos utilizar os outros tipos de variveis Advpl nas Classes , como variveis Locais
, Private , Static , etc... Para acessarmos uma propriedade da classe atual , devemos
prefix-la com :: ( dois sinais de 2 pontos )
Ao declarar um objeto utilizando o construtor da classe , utilizamos a sintaxe : oObjeto
:= NomeDaClasse():Metodo_Contrutor(). Para acessar uma propriedade deste objeto ,
utilizamos oObjeto:Propriedade , e para acessar um mtodo da classe aplicvel a este
objeto , utilizamos oObjeto:Metodo( parametros,... )
PALAVRAS RESERVADAS
Lista de Palavras Reservadas

AADD
ABS
ASC
AT
BOF
BREAK
ENDIF
LTRIM
SPACE
CTOD
FILE
PCOUNT
TRANSFORM
DOW
IIF
DTOS
ELSE
ELSEIF
EMPTY
ENDCASE
ENDDO
LOWER
SETPOS
COL
FIELDNAME
PCOL
TIME
DEVPOS
IF
RECNO
INKEY
INT
LASTREC
LEN
LOCK
LOG
SELECT
CMONTH
FCOUNT
MONTH
SUBSTR
DELETED
FUNCTION
RECCOUNT
UPPER
REPLICATE
RLOCK
ROUND
ROW
RTRIM
SECONDS
CHR
EXP
MIN
STR
DAY
FOUND
PROW
TYPE
VAL
VALTYPE
WHILE
WORD
YEAR
CDOW
EOF
MAX
SQRT
DATE
FLOCK
PROCEDURE
TRIM
DTOC
Novas Palavras Reservadas

A partir das verses Protheus Ap5 - Build 7.00.030702 , Ap6 - Build
7.00.030702 e Ap7 - Build 7.00.030702 , as palavras abaixo passaram a ser
reservadas:
TRY
AS
CATCH
THROW
Notas:
Palavras reservadas no podem ser utilizadas para variveis, procedimentos, ou

funes.
Funes reservadas so pertencentes ao compilador e portanto no podem ser
redefinidas por uma aplicao.
Abreviaes de quatro letras de palavras reservadas e funes tambm so
reseravdas.
Todos os identifadores que comearem com um ou mais caracters de sublinhado
(_) so utilizados como identificadores internos e portanto so tambm
reservados.
TABELAS DE PICTURES DE FORMATAO
Comando SAY/PSAY
Funes
Conteudo Funcionalidade
C
Exibe CR depois de nmeros positivos
E
Exibe numricos com o ponto e a vrgula invertidos (formato Europeu)
R
Insere caracteres diferentes dos caracteres de template
X
Exibe DB depois de nmeros negativos
Z
Exibe zeros como brancos
(
Envolve nmeros negativos entre parnteses
!
Converte todos os carecteres alfabticos para maisculo
Templates
X
Exibe dgitos para qualquer tipo de dado
9
#
!
Converte caracteres alfabticos para maisculo
*
Exibe asterisco no lugar de espaos em branco inicias em nmeros
.
Exibe a posio do ponto decimal
,
Exibe a posio do milhar
Comando GET
Funes
A
Permite apenas caracteres alfabticos
C
Exibe CR depois de nmeros positivos
E
Exibe numricos com o ponto e vrgula invertidos (formato Europeu)
Insere caracteres diferentes dos caracteres de template na exibio mas no
R
insere-os na varivel do GET
Permite rolamento horizontal do texto dentro do GET, <n> um nmero
S<n>
inteiro que identifica o tamanho da regio
X
Exibe DB depois de nmeros negativos
Z
Exibe zeros como brancos
(
Exibe nmeros negativos entre parnteses com os espaos em branco iniciais
)
Exibe nmeros negativos entre parnteses sem os espaos em branco iniciais
!
Templates
X
Permite qualquer caractere
Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
9
numricos
#
Permite dgitos, sinais e espaos em branco para qualquer tipo de dado
!
*
Exibe um asterisco no lugar dos espaos em branco iniciais em nmeros
.
Exibe o ponto decimal
,
Exibe a posio do milhar
TCNICAS DE PROGRAMAO EFICIENTE

Para o desenvolvimento de sistemas e a programao de rotinas, sempre esperado que
qualquer cdigo escrito seja:
de correto funcionamento
eficiente
legvel
reutilizvel
extensvel
portvel
Aps anos de experincia na utilizao de linguagens padro xBase e do

desenvolvimento da linguagem AdvPl, algumas tcnicas para uma programao
otimizada e eficiente foram reconhecidas. A utilizao das tcnicas a seguir, visa buscar
o mximo aproveitamento dos recursos da linguagem com o objetivo de criar programas
com estas caractersticas.
Criao de Funes Segundo a Necessidade

Observe o cdigo de exemplo:
User Function GetAnswer(lDefault)
Local lOk
lOk := GetOk(lDefault)
If lOk
Return .T.
Else
Return .F.
Endif
Return nil
Utilizando-se apenas o critrio "a funo funciona corretamente?", a funo GetAnswer

perfeita. Recebe um parmetro lgico com a resposta padro e retorna um valor lgico
dependente da opo escolhida pelo usurio em uma funo de dilogo "sim/no"
designada para isso. Pode entretanto ser melhorada, particularmente se eficincia for
considerada como um critrio para um cdigo melhor. Eficincia tipicamente involve a
utilizao de poucos recursos de mquina, poucos chamadas de funes ou tornar mais
rpido um processo.
Segundo esse raciocnio, poderia se produzir o seguinte cdigo:
Return If( GetOk(lDefault), .T., .F.)
Ou melhor:
Return GetOk(lDefault)
Com a otimizao do cdigo da funo GetAnswer, pode facilmente verificar que a

mesma no realiza nada adicional chamada de GetOk, podendo ser substituda por
uma chamada direta desta, continuando a funcionar corretamente.
Codificao Auto-Documentvel
Nenhum comentrio substitui um cdigo claramente escrito, e este no um um
acidente. Considere o exemplo:
cVar := "
" // 11 espaos
O tamanho da varivel cVar no evidente por si s e no facilmente verificado. Estes

mesmos 10 espaos estariam mais bvios e ainda assim garantidos se a instruo fosse
escrita como:
cVar := Space(11)
O mesmo princpio pode ser aplicado para qualquer string longa de caracteres repetidos.
A funo Replicate pode ser utilizada como a seguir:
cVar := Replicate( "*", 80 )
Este tipo de programao deixa o cdigo fcil de digitar, fcil de ler e mais flexvel.
Utilizao de Solues Simples

Simplicidade na criao de instrues torna a programao e at mesmo a execuo
mais rpida. Considere a linha de cdigo:
If nVar > 0 .Or. nVar < 0
Se o valor da varivel nVar for igual a zero (0) no momento da execuo desta linha de
cdigo, ambas as comparaes separadas pelo operador lgico .Or. sero efetuadas:
Aps ser avaliada, a primeria comparao ir falhar. A segunda comparao ser ento
avaliada e falhar tambm. Como resultado, o cdigo existente dentro da estrutura de
fluxo If no ser executado. Tal cdigo somente ser executado quando o valor desta
varivel for maior OU menor do que zero. Ou seja, sempre que for DIFERENTE de
zero, o que torna a linha a seguir mais eficiente:
If nVar != 0
Este tipo de alterao torna o cdigo mais legvel e o processamento mais rpido,
evitando a avaliao de instrues desnecessariamente.
Existem outras situaes onde a simplificao pode ser utilizada. A expresso de
avaliao a seguir:
If cVar == "A" .Or. cVar == "B" .Or ;
cVar == "C" .Or. cVar == "D"
Pode ser substitudo pelo operador de conteno:

If cVar $ "ABCD"
Opo por Flexibilidade
A melhor soluo aquela que envolve o problema imediato e previne problemas no

futuro. Considere o exemplo:
@nRow,nCol PSAY cVar Picture "!!!!!!!!!!!!!!!!!!!!"
Exceto contando-se os caracteres, no existe maneira de saber se o nmero de caracteres

de exclamao o esperado. Enquanto isto um problema, existem algo mais grave. A
expresso de picture esttica. Se no futuro for necessrio ajustar o tamanho da varivel
cVar, ser necessrio localizar todos os lugares no cdigo onde esta mscara de picture
est sendo utilizada para ajuste manual. Existe uma opo dsoluo de de auto-ajuste
disponvel que fcil de digitar e tem a garantia de executar a tarefa igualmente (tornar
todos os caracteres maisculos):
@nRow,nCol PSAY cVar Picture "@!"
Opo da Praticidade ao Drama

Se a soluo parece complexa, provavelmente porque o caminho escolhido est
levando a isso. Deve-se sempre se perguntar porque algum desenvolveria uma
linguagem que requisite tantos comandos complicados para fazer algo simples. Na
grande maioria dos casos, existe uma soluo mais simples. O exemplo abaixo deixa
isso bem claro:
@ 10,25 Say Substr(cCep,1,5) + "-" + Substr(cCep,6,3) Picture
"!!!!!!!!!"
Que pode ficar mais simples assim:

@ 10,25 Say cCep Picture "@R 99999-999"
Utilizao de Operadores de Incremento/Decremento

Utilizados devidamente, os operadores de incremento e decremento tornam o cdigo
mais fcil de ler e possivelmente um pouco mais rpidos. Ao contrrio de escrever
adies simples como:
nVar := nVar + 1
nVar := nVar -1
Pode-se escrev-las assim:

++nVar
--nVar
Deve-se apenas tomar cuidado com a precedncia destes operadores, pois o "++" ou o "-" podem aparecer antes ou depois de uma varivel, e em alguns casos quando a
varivel for utilizada dentro de uma expresso, a prefixao ou sufixao destes
operadores afetar o resultado. Para maiores detalhes, consulte a documentao de
operadores da linguagem AdvPl.
Evitar Passos Desnecessrios

Existe uma diferena entre um bom hbito e perda de tempo. Algumas vezes estes
conceitos podem estar muito prximos, mas um modo de diferenci-los balancear os
benefcios de realizar alguma ao contra o problema que resultaria se no fosse
executada. Observe o exemplo:
Local nCnt := 0
For nCnt := 1 To 10
<cdigo>
Next nCnt
Inicializar a varivel no momento da declarao no um problema. Se o 0 fosse

necessrio no exemplo, teria sido til a inicializao na declarao. Mas neste caso a
estrutura de repetio For... Next atribui o seu valor imediatamente com 1, portanto no
houve ganho em atribuir a varivel com 0 no comeo.
Neste exemplo no h nenhum ponto negativo e nada errado ocorrer se a varivel no
for inicializada, portanto aconselhvel evitar este tipo de inicializao, pois no torna
o cdigo mais seguro e tambm no expressa a inteno do cdigo mais claramente.
Porm note este exemplo, onde a varivel no inicializada:
Local nCnt
While ( nCnt++ < 10 )
<cdigo>
EndDo
Em AdvPl, variveis no inicializadas sempre tem seu valor contendo nulo (nil) a
princpio, o que far com que uma exceo em tempo de execuo acontea quando a
instruo de repetio while for executada.
Diferentemente do primeiro exemplo, onde a inicializao da varivel no fazia
diferena alguma, neste segundo exemplo a inicializao absolutamente necessria.
Deve-se procurar inicializar variveis numricas com zero (0) e variveis caracter com
string nula ("") apenas quando realmente necessrio.
Utilizao de Alternativas
Quando se est trabalhando em uma simples rotina, deve-se tomar algum tempo para
explorar duas ou trs diferentes abordagens. Quando se est trabalhando em algo mais
complexo, deve-se planejar prototipar algumas a mais. Considere o seguinte cdigo:
If cHair = "A"
Replace hair With "Loira"
Else
If cHair = "B"
Replace hair With "Morena"
Else
If cHair = "C"
Replace hair With "Ruiva"
Else
If cHair = "D"
Replace hair With "Grisalho"
Else
Replace hair With "Preto"
Endif
Endif
Endif
Endif
Um cdigo de uma nica letra, (A at E), foi informado para indicar a

cor de cabelo. Este cdigo foi ento convertido e armazenado como uma
string. Pode-se notar que a cor "Preto" ser atribuda se nenhuma
outra opo for verdadeira.
Uma alternativa que reduz o nvel de identao torna o cdigo mais
fcil de ler enquanto reduz o nmero de comandos replace:
Do Case
Case cHair == "A"
cColor := "Loira"
Case cHair == "B"
cColor := "Morena"
Case cHair == "C"
cColor := "Ruiva"
Case cHair == "D"
cColor := "Grisalho"
OtherWise
cColor := "Preto"
EndCase
Replace hair With cColor
Utilizao de Arquivos de Cabealho

Quando Necessrio
Se um arquivo de cdigo criado se referencia a comandos para
interpretao e tratamento de arquivos XML, este deve se incluir o
arquivo de cabealho prprio para tais comandos (XMLXFUN.CH no
exemplo). Porm no deve-se incluir arquivos de cabealho apenas por
segurana. Se no se est referenciando nenhuma das constantes ou
utilizando nenhum dos comandos contidos em um destes arquivos, a
incluso apenas tornar a compilao mais demorada.
Constantes em Maisculo
Isto uma conveno que faz sentido. Em AdvPl, como em C por exemplo,
a regra utilizar todos os caracteres de uma constante em maisculo,
a fim de que possam ser claramente reconhecidos como constantes no
cdigo, e que no seja necessrios lembrar onde foram declarados.
Utilizao de Identao
Este um hbito que todo programador deve desenvolver. No consome
muito esforo para manter o cdigo alinhado durante o trabalho, porm
quando necessrio pode-se utilizar AP6 IDE para a reidentao de
cdigo.
Considere o exemplo:
While !SB1->(Eof())
If mv_par01 = SB1->B1_COD
dbSkip()
Loop
Endif
Do Case
Case SB1->B1_LOCAL == "01" .Or. SB1->B1_LOCAL == "02"
TrataLocal(SB1->B1_COD,SB1->B1_LOCAL)
Case SB1->B1_LOCAL == "03"
TrataDefeito(SB1->B1_COD)
OtherWise
TrataCompra(SB1->B1_COD,SB1->B1_LOCAL)
EndCase
dbSkip()
EndDo
A utilizao da identao seguindo as estruturas de controle de fluxo

(while, if, case, etc) torna a compreenso do cdigo muito mais fcil:
While !SB1->(Eof())
If mv_par01 = SB1->B1_COD
dbSkip()
Loop
Endif
Do Case
Case SB1->B1_LOCAL == "01" .Or. SB1->B1_LOCAL == "02"
TrataLocal(SB1->B1_COD,SB1->B1_LOCAL)
Case SB1->B1_LOCAL == "03"
TrataDefeito(SB1->B1_COD)
OtherWise
TrataCompra(SB1->B1_COD,SB1->B1_LOCAL)
EndCase
dbSkip()
EndDo
Utilizao de Espaos em Branco

Espaos em branco extras tornam o cdigo mais fcil para a leitura.
No necessrio imensas reas em branco, mas agrupar pedaos de
cdigo atravs da utilizao de espaos em branco funciona muito bem.
Costuma-se separar parmetros com espaos em branco.
Quebra de Linhas Muito Longas

Com o objetivo de tornar o cdigo mais fcil de ler e imprimir, as
linhas do cdigo no devem estender o limite da tela ou do papel.
Podem ser "quebradas" em mais de uma linha de texto utilizando o
ponto-e-vrgula (;).
Capitulao de Palavras-Chave
Uma conveno amplamente utilizada a de capitular as palavras
chaves, funes, variveis e campos utilizando uma combinao de
caracteres em maisculo e minsculo, visando facilitar a leitura do
cdigo fonte. O cdigo a seguir:
local ncnt
while ( ncnt++ < 10 )
ntotal += ncnt * 2
enddo
Ficaria melhor com as palavras chaves e variveis capituladas:
Local nCnt
While ( nCnt++ < 10 )
nTotal += nCnt * 2
EndDo
Utilizao da Notao Hngara

A Notao Hngara muito comum entre programadores xBase e de outras
linguagens. A documentao do AdvPl utiliza esta notao para a
descrio das funes e comandos e aconselhvel sua utilizao na
criao de rotinas, pois ajuda a evitar pequenos erros e facilita a
leitura do cdigo. Para maiores detalhes, consulte a documentao
sobre a Notao Hngara disponvel na documentao da linguagem AdvPl.
Utilizao de Nomes Significantes para

Variveis
A principal vantagem da liberdade na criao dos nomes de variveis
a facilidade de identificao da sua utilidade. Portanto deve-se
utilizar essa facilidade o mximo possvel. Nomes sem sentido apenas
tornaro difcil a identificao da utilidade de uma determinada
varivel, assim como nomes extremamente curtos. Nem sempre a
utilizao de uma varivel chamada i a melhor sada. Claro, no
convm criar uma varivel com um nome muito longo que ser utilizada
como um contador, e referenciada muitas vezes no cdigo. O bom senso
deve ser utilizado.
Criar variveis como nNumero ou dData tambm no ajudam na
identificao. A Notao Hngara j est sendo utilizada para isso e o
objetivo do nome da varivel deveria ser identificar sua utilizao,
no o tipo de dado utilizado. Deve-se procurar substituir tais
variveis por algo como nTotal ou dCompra.
O mesmo vlido para nomes de funes, que devem descrever um pouco
sobre o que a funo faz. Novamente nomes extremamente curtos no so
aconselhveis.
Utilizao de Comentrios
Comentrios so muito teis na documentao de programas criados e
para facilitar a identificao de processos importantes no futuro.
Devem sempre ser utilizados.
Sempre que possvel, funes criadas devem ter uma breve descrio do
seu objetivo, parmetros e retorno. Alm de servir como documentao,
os comentrios embelezam o cdigo ao separar as funes umas das
outras.
Os comentrios devem ser utilizados com bom senso, pois reescrever a
sintaxe AdvPl em portugus torna-se apenas perda de tempo:
#EX
If nLastKey == 27 // Se o nLastKey for igual a 27

#EX
Criao de Mensagens Sistmicas

Significantes e Consistentes
Seja oferecendo assistncia, exibindo mensagens de aviso ou mantendo o
usurio informado do estado de algum processo, as mensagens devem
refletir o tom geral e a importncia da aplicao. Em termos gerais,
deve-se evitar ser muito informal e ao mesmo tempo muito tcnico.
#EX
"Aguarde. Reindexando (B1_FILIAL+B1_COD+B1_LOCAL) do arquivo:
\DADOSADV\SB1990.DBF"
#/EX
Esse tipo de mensagem pode dar informaes demais para o usurio e
deix-lo sentindo-se desconfortvel se no souber o que significa
"reindexando", etc. E de fato, o usurio no devia ser incomodado com
tais detalhes. Apenas a frase "Aguarde, indexando." funcionaria
corretamente, assim como palavras "processando" ou "reorganizando".
Outra boa idia evitar a referencia a um item corrente de uma tabela
como um "registro":
#EX
"Deletar este registro?"
#/EX
Se a operao estiver sendo efetuada em um arquivo de clientes, o
usurio deve ser questionado sobre a remoo do cliente corrente, se
possvel informando valores de identificao como o cdigo ou o nome.
Evitar Abreviao de Comandos em 4

letras
Apesar do AdvPl suportar a abreviao de comandos em quatro letras
(por exemplo, repl no lugar de replace) no h necessidade de utilizar
tal funcionalidade. Isto apenas torna o cdigo mais difcil de ler e
no torna a compilao mais rpida ou simples.
Evitar "Disfarces" no Cdigo

No deve-se criar constantes para expresses complexas. Isto tornar o
cdigo muito difcil de compreender e poder causar erros primrios,
pois pode-se imaginar que uma atribuio efetuada a uma varivel
quando na verdade h toda uma expresso disfarada:
#define NUMLINES aPrintDefs[1]

#define NUMPAGES aPrintDefs[2]
#define ISDISK
aReturn[5]
If ISDISK == 1
NUMLINES := 55
Endif
NUMPAGES += 1
A impresso
esto sendo
utilizadas.
substitudo
que se tem aps uma leitura deste cdigo de que valores

atribuidos s variveis ou que constantes esto sendo
Se o objetivo flexibilidade, o cdigo anterior deve ser
por:
#define NUMLINES 1
#define NUMPAGES 2
#define ISDISK
5
If aReturn[ISDISK] == 1
aPrintDefs[ NUMLINES ] := 55
Endif
aPrintDefs[ NUMPAGES ] += 1
Evitar Cdigo de Segurana

Desnecessrio
Dada sua natureza binria, tudo pode ou no acontecer dentro de um
computador. Adicionar pedaos de cdigo apenas para "garantir a
segurana" freqentemente utilizado como uma desculpa para evitar
corrigir o problema real. Isto pode incluir a checagem para validar
intervalos de datas ou para tipos de dados corretos, o que comumente
utilizando em funes:
Static Function MultMalor( nVal )

If ValType( nVal ) != "N"
nVal := 0
Endif
Return ( nVal * nVal )
O ganho irrisrio na checagem do tipo de dado do parmetro j que

nenhum programa corretamente escrito em execuo poderia enviar uma
string ou uma data para a funo. De fato, este tipo de "captura" o
que torna a depurao difcil, j que o retorno ser sempre um valor
vlido (mesmo que o parmetro recebido seja de tipo de dado
incorreto). Se esta captura no tiver sido efetuada quando um
possvel erro de tipo de dado invlido ocorrer, o cdigo pode ser
corrigido para que este erro no mais acontea.
Isolamento de Strings de Texto

No caso de mensagens e strings de texto, a centralizao um bom
negcio. Pode-se colocar mensagens, caminhos para arquivos, e mesmo
outros valores em um local especfico. Isto os torna acessveis de

qualquer lugar no programa e fceis de gerenciar.
Por exemplo, se existe uma mensagem comum como "Imprimindo, por favor
aguarde..." em muitas partes do cdigo, corre-se o risco de no seguir
um padro para uma das mensagens em algum lugar do cdigo. E mant-las
em um nico lugar, como um arquivo de cabealho, torna fcil a
produo de documentao e a internacionalizao em outros idiomas.
SINTAXE DE LINGUAGEM
Criaco de um Programa
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Um programa de computador nada mais do que um grupo de comandos logicamente

dispostos com o objetivo de executar determinada tarefa. Esses comandos so gravados
em um arquivo texto que transformado em uma linguagem executvel por um
computador atravs de um processo chamado compilao. A compilao substitui os
comandos de alto nvel (que os humanos compreendem) por instrues de baixo nvel
(compreendida pelo sistema operacional em execuo no computador). No caso do
AdvPl, no o sistema operacional de um computador que ir executar o cdigo
compilado, mas sim o AP6 Server.
Dentro de um programa, os comandos e funes utilizados devem seguir regras de
sintaxe da linguagem utilizada, pois caso contrrio o programa ser interrompido por
erros. Os erros podem ser de compilao ou de execuo.
Erros de compilao so aqueles encontrados na sintaxe que no permitem que o

arquivo de cdigo do programa seja compilado. Podem ser comandos
especificados de forma errnea, utilizao invlida de operadores, etc.
Erros de execuo so aqueles que acontecem depois da compilao, quando o
programa est sendo executado. Podem ocorrer por inmeras razes, mas
geralmente se referem a funes no existentes, ou variveis no criadas ou
inicializadas, etc.
Linhas de Programa
As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser

linhas de comando, linhas de comentrio ou linhas mistas.
Linhas de Comando
Linhas de comando possuem os comandos ou instrues que sero executadas. Por
exemplo:
Local nCnt
Local nSoma := 0
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Linhas de Comentrio
Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem
apenas para documentao e para tornar mais fcil o entendimento do programa.
Existem trs formas de se comentar linhas de texto. A primeira delas utilizar o sinal de
* (asterisco) no comeo da linha:
* Programa para clculo do total
* Autor: Microsiga Software S.A.
* Data: 2 de outubro de 2001
Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio.

Pode-se utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para
realizar a funo do sinal de asterisco. Porm todas estas formas de comentrio de
linhas so obsoletas e existem apenas para compatibilizao com o padro xBase. A
melhor maneira de comentar linhas em AdvPl utilizar duas barras transversais:
// Programa para clculo do total
// Autor: Microsiga Software S.A.
// Data: 2 de outubro de 2001
Outra forma de documentar textos utilizar as barras transversais juntamente com o

asterisco, podendo-se comentar todo um bloco de texto sem precisar comentar linha a
linha:
/*
Programa para clculo do total
Autor: Microsiga Software S.A.
Data: 2 de outubro de 2001

*/
Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento
(indicada pelos caracteres */) considerado como comentrio.
Linhas Mistas
O AdvPl tambm permite que existam linhas de comando com comentrio. Isto
possvel inclundo-se as duas barras transversais (//) ao final da linha de comando e
adicionando-se o texto do comentrio:
Local nCnt
Local nSoma := 0 // Inicializa a varivel com zero para a soma
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Tamanho da Linha
Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser
digitado no editor de textos utilizado, existe uma linha considerada linha lgica. A linha
lgica, aquela considerada para a compilao como uma nica linha de comando.
A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento
da tecla <Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm algumas
vezes, por limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha
lgica em mais de uma linha fsica no arquivo texto. Isto efetuado utilizando-se o sinal
de ponto-e-vrgula (;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter>
!Empty(cTel) .And. !Empty(cFax) .And. ; <enter>
!Empty(cEmail)
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas.
Como a linha torna-se muito grande, pode-se divid-la em mais de uma linha fsica
utilizando o sinal de ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas
duas primeiras linhas, durante a execuo do programa ocorrer um erro, pois a segunda
linha fsica ser considerada como uma segunda linha de comando na compilao. E
durante a execuo esta linha no ter sentido.
Estrutura de um Programa
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Apesar de no ser uma linguagem de padres rgidos com relao estrutura do

programa, importante identificar algumas de suas partes. Considere o programa de
exemplo abaixo:
/*
+===========================================+
| Programa: Clculo do Fatorial
|
| Autor
: Microsiga Software S.A.
|
| Data
: 02 de outubro de 2001
|
+===========================================+
*/
Local nCnt
Local nResultado := 1 // Resultado do fatorial
Local nFator
:= 5 // Nmero para o clculo
// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
// Exibe o resultado na tela, atravs da funo alert
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))
// Termina o programa
Return
Pode-se classificar um programa em AdvPl em quatro partes bsicas:
rea de Identificao
rea de Ajustes Iniciais
Corpo do Programa
rea de Encerramento
A rea de Identificao
Esta uma rea que no obrigatria e dedicada a documentao do programa.
Quando existente, contm apenas comentrios explicando a sua finalidade, data de

criao, autor, etc, e aparece no comeo do programa, antes de qualquer linha de
comando.
O formato para esta rea no definido. Pode-se colocar qualquer tipo de informao
desejada e escolher a formatao apropriada.
/*
+==========================================+
| Programa: Clculo do Fatorial
|
| Autor
: Microsiga Software S.A.
|
| Data
: 02 de outubro de 2001
|
+==========================================+
*/
Opcionalmente pode-se incluir definies de constantes utilizadas no programa ou

incluso de arquivos de cabealho nesta rea.
A rea de Ajustes Iniciais

Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto
funcionamento do programa. Entre os ajustes se encontram declaraes de variveis,
inicializaes, abertura de arquivos, etc. Apesar do AdvPl no ser uma linguagem rgida
e as variveis poderem ser declaradas em qualquer lugar do programa, aconselhvel
faz-lo nesta rea visando tornar o cdigo mais legvel e facilitar a identificao de
variveis no utilizadas.
Local nCnt
Local nResultado := 0 // Resultado do fatorial
Local nFator
:= 10 // Nmero para o clculo
O Corpo do Programa
nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a
tarefa necessria atravs da organizao lgica destas linhas de comando. Espera-se que
as linhas de comando estejam organizadas de tal modo que no final desta rea o
resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variveis de
memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela.
// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
A rea de Encerramento
nesta rea onde as finalizaes so efetuadas. onde os arquivos abertos so
fechados, e o resultado da execuo do programa utilizado. Pode-se exibir o resultado
armazenado em uma varivel ou em um arquivo ou simplesmente finalizar, caso a tarefa
j tenha sido toda completada no corpo do programa. nesta rea que se encontra o
encerramento do programa. Todo programa em AdvPl deve sempre terminar com a
palavra chave return.
// Exibe o resultado na tela, atravs da funo alert
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))
// Termina o programa
Return
Controlando o Fluxo
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
O AdvPl suporta vrias estruturas de controle que permitem mudar a seqncia de fluxo
de execuo de um programa. Estas estruturas permitem a execuo de cdigo baseado
em condies lgica e a repetio da execuo de pedaos de cdigo qualquer nmero
de vezes.
Em AdvPl, todas as estruturas de controle podem ser "aninhadas" dentro de todas as
demais estruturas contanto que estejam aninhadas propriamente. Estruturas de controle
tm um identificador de incio e um de fim, e qualquer estrutura aninhada deve se
encontrar entre estes identificadores.
Tambm existem estruturas de controle para determinar que elementos, comandos, etc
em um programa sero compilados. Estas so as diretivas do pr-processador
#ifdef...#endif e #ifndef...#endif. Consulte a documentao sobre o pr-processador para
maiores detalhes.
As estruturas de controle em AdvPl esto divididas em :
Estruturas de Repetio
Estruturas de Deciso.
Desviando a Execuco
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Estruturas de desvio so deseginadas para executar uma seo de cdigo se determinada

condio lgica resultar em verdadeiro (.T.). Em AdvPl existem dois comandos para
execuo de sees de cdigo de acordo com avaliaes lgicas. O comando
IF...ENDIF e o comando DO CASE...ENDCASE.
O Comando DO CASE...ENDCASE
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em

verdadeiro (.T.).
Sintaxe
DO CASE
CASE lExpressao1
Commandos
[CASE lExpressao2
Commandos
...
CASE lExpressaoN
Commandos]
[OTHERWISE
Commandos]
ENDCASE
Parmetros
CASE
lExpressao1
Comandos...
OTHERWISE
Commandos
Quando a primeira expresso CASE resultante em verdadeiro (.T.) for

encontrada, o conjunto de comandos seguinte executado. A
execuo do conjunto de comandos continua at que a prxima
clusula CASE, OTHERWISE ou ENDCASE seja encontrada. Ao
terminar de executar esse conjunto de comandos, a execuo continua
com o primeiro comando seguinte ao ENDCASE.
Se uma expresso CASE resultar em falso (.F.), o conjunto de
comandos seguinte a esta at a prxima clusula ignorado.
Apenas um conjunto de comandos executado. Estes so os
primeiros comandos cuja expresso CASE avaliada como
verdadeiro (.T.). Aps a execuo, qualquer outra expresso CASE
posterior ignorada (mesmo que sua avaliao resultasse em
verdadeiro).
Se todas as expresses CASE forem avaliadas como falso (.F.), a
clusula OTHERWISE determina se um conjunto adicional de
comandos deve ser executado. Se essa clusula for incluida, os
comandos seguintes sero executados e ento o programa continuar
com o primeiro comando seguinte ao ENDCASE. Se a clusula
OTHERWISE for omitida, a execuo continuar normalmente aps
a clusula ENDCASE.
Comentrios
O Comando DO CASE...ENDCASE utilizado no lugar do comando IF...ENDIF
quando um nmero maior do que uma expresso deve ser avaliada, substituindo a
necessidade de mais de um comando IF...ENDIF aninhados.
Exemplo
Local nMes
:= Month(Date())
Local cPeriodo := ""
DO CASE
CASE nMes <= 3
cPeriodo := "Primeiro Trimestre"
CASE nMes >= 4 .And. nMes <= 6
cPeriodo := "Segundo Trimestre"
CASE nMes >= 7 .And. nMes <= 9
cPeriodo := "Terceiro Trimestre"
OTHERWISE
cPeriodo := "Quarto Trimestre"
ENDCASE
Return
O Comando IF...ENDIF
Reviso: 20/09/2004
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Executa um conjunto de comandos baseado no valor de uma expresso lgica.
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
Parmetros
Especifica uma expresso lgica que avaliada. Se lExpressao resultar em
verdadeiro (.T.), qualquer comando seguinte ao IF e antecedente ao ELSE
ou ENDIF (o que ocorrer primeiro) ser executado.Se lExpressao resultar
em falso (.F.) e a clusula ELSE for definida, qualquer comando aps essa
lExpressao
clusula e anterior ao ENDIF ser executada. Se a clusula ELSE no for
definida, todos os comandos entre o IF e o ENDIF so ignorados. Neste
caso, a execuo do programa continua com o primeiro comando seguinte
ao ENDIF.
Conjunto de comandos AdvPl que sero executados dependendo da
Comandos
avaliao da expresso lgica em lExpressao.
Comentrios
Pode-se aninhar um bloco de comando IF...ENDIF dentro de outro bloco de comando
IF...ENDIF. Porm, para a avaliao de mais de uma expresso lgica, deve-se utilizar o
comando DO CASE...ENDCASE.
Exemplo
Local dVencto := CTOD("31/12/01")

If Date() > dVencto
Alert("Vencimento ultrapassado!")
Endif
Return
IF no Protheus
Nas verses do ERP Siga Advanced 2.07 /4.07 e anteriores, caso o comando IF
recebesse um argumento nulo ( NIL ) , a aplicao era abortada com a ocorrncia
"Error BASE/1066 Argument error: conditional".
A partir das verses Protheus 507 e posteriores, a aplicao no abortada, e o
comando IF comporta-se como se tivesse recebido o valor booleano .F. ( falso ) .
O Comando FOR...NEXT
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
A estrutura de controle FOR...NEXT, ou simplesmente o loop FOR, repete uma seo

de cdigo em um nmero determinado de vezes.
Sintaxe
FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento]

Comandos...
[EXIT]
[LOOP]
NEXT
Parmetros
Especifica uma varivel ou um elemento de uma matriz para atuar

como um contador. A varivel ou o elemento da matriz no precisa ter
Variavel
sido declarado antes da execuo do comando FOR...NEXT. Se a
varivel no existir, ser criada como uma varivel privada.
nValorInicial o valor inicial para o contador; nValorFinal o valor
nValorInicial final para o contador. Pode-se utilizar valores numricos literais,
TO nValorFinal variveis ou expresses, contanto que o resultado seja do tipo de dado
numrico.
nIncremento a quandidade que ser incrementada ou decrementada
no contador aps cada execuo da seo de comandos. Se o valor de
STEP
nIncremento for negativo, o contador ser decrementado. Se a clusula
nIncremento
STEP for omitida, o contador ser incrementado em 1. Pode-se utilizar
valores numricos literais, variveis ou expresses, contanto que o
resultado seja do tipo de dado numrico.
Especifica um ou mais instrues de comando AdvPl que sero
Comandos
executadas.
Transfere o controle de dentro do comando FOR...NEXT para o
comando imediatamente seguinte ao NEXT, ou seja, finaliza a
EXIT
repetio da seo de comandos imediatamente. Pode-se colocar o
comando EXIT em qualquer lugar entre o FOR e o NEXT.
Retorna o controle diretamente para a clusula FOR sem executar o
restante dos comandos entre o LOOP e o NEXT. O contador
LOOP
incrementadou ou decrementado normalmente, como se o NEXT
tivesse sido alcanado. Pode-se colocar o comando LOOP em qualquer
lugar entre o FOR e o NEXT.
Comentrios
Uma varivel ou um elemento de uma matriz utilizado como um contador para
especificar quantas vezes os comandos AdvPl dentro da estrutura FOR...NEXT so
executados. Os comandos AdvPl depois do FOR so executados at que o NEXT seja
alcanado. O contador (Variavel) ento incrementado ou decremantado com o valor
em nIncremento (se a clusula STEP for omitida, o contador incrementado em 1).
Ento, o contador comparado com o valor em nValorFinal. Se for menor ou igual ao
valor em nValorFinal, os comandos seguintes ao FOR so executados novamente. Se o
valor for maior que o contido em nValorFinal, a estrutura FOR...NEXT terminada e o
programa continua a execuo no primeiro comando aps o NEXT.
Os valores de nValorInicial, nValorFinal e nIncremento so apenas considerados
inicialmente. Entretanto, mudar o valor da varivel utilizada como contador dentro da
estrutura afetar o nmero de vezes que a repetio ser executada. Se o valor de
nIncremento negativo e o valor de nValorInicial maior que o de nValorFinal, o
contador ser decrementado a cada repetio.
Exemplo
Local nCnt
Local nSomaPar := 0
For nCnt := 0 To 100 Step 2
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros nmeros pares : " + ;
cValToChar(nSomaPar) )
Return
Este exemplo imprime a soma dos 100 primerios nmeros pares. A soma obitida
atravs da repetio do clculo utilizando a prpria varivel de contador. Como a
clusula STEP est sendo utilizada, a varivel nCnt ser sempre incrementada em 2. E
como o contador comea com 0, seu valor sempre ser um nmero par.
O Comando WHILE...ENDDO
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma

seo de cdigo enquanto uma determinada expresso resultar em verdadeiro (.T.).
Sintaxe
WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO
Parmetros
Especifica uma expresso lgica cujo valor determina quando os comandos

entre o WHILE e o ENDDO so executados. Enquanto o resultado de
lExpressao
lExpressao for avaliado como verdadeiro (.T.), o conjunto de comandos so
executados.
Especifica um ou mais instrues de comando AdvPl que sero executadas
Comandos
enquanto lExpressao for avaliado como verdadeiro (.T.).
Transfere o controle de dentro do comando WHILE...ENDDO para o
comando imediatamente seguinte ao ENDDO, ou seja, finaliza a repetio
EXIT
da seo de comandos imediatamente. Pode-se colocar o comando EXIT em
qualquer lugar entre o WHILE e o ENDO.
Retorna o controle diretamente para a clusula WHILE sem executar o
restante dos comandos entre o LOOP e o ENDDO. A expresso em
LOOP
lExpressao reavaliada para a deciso se os comandos continuaro sendo
executados.
Comentrios
Os comandos entre o WHILE e o ENDDO so executados enquanto o resultado da
avaliao da expresso em lExpressao permanecer verdadeiro (.T.). Cada palavra chave
WHILE deve ter uma palavra chave ENDDO correspondente.
Exemplo
Local nNumber := 0
Local nSomaPar := 0
While nNumber <= 100
nSomaPar += nNumber
nNumber += 2
Enddo
Alert( "A soma dos 100 primeiros nmeros pares : " +
cValToChar(nSomaPar) )
Return
Repetico de Comandos
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Estruturas de repetio so deseginadas para executar uma seo de cdigo mais de uma
vez. Por exemplo, imagiando-se a existncia de uma funo para imprimir um relatrio,
pode-se desejar imprimi-lo quatro vezes. Claro, pode-se simplesmente chamar a funo
de impresso quatro vezes em seqncia, mas isto se tornaria pouco profissional e no
resolveria o problema se o nmero de relatrios fosse varivel.
Em AdvPl existem dois comandos para a repetio de sees de cdigo. O comando
FOR...NEXT e o comando WHILE...ENDDO.
Macro Substituico
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
O operador de macro substituio, simbolizado pelo "e" comercial (&), utilizado para
a avaliao de expresses em tempo de execuo. Funciona como se uma expresso
armazenada fosse compilada em tempo de execuo, antes de ser de fato executada.
01 X := 10
02 Y := "X + 1"
03 B := &Y // O contedo de B ser 11
A varivel X atribuda com o valor 10, enquanto a varivel Y atribuda com a string
de caracteres contendo "X + 1".
A terceira linha utiliza o operador de macro. Esta linha faz com que o nmero 11 seja
atribudo varivel B. Pode-se perceber que esse o valor resultante da expresso em
formato de caractere contida na varivel Y.
Utilizando-se uma tcnica matemtica elementar, a substituio, temos que na segunda
linha, Y definido como "X + 1", ento pode-se substituir Y na terceira linha:
03 B := &"X + 1"
O operador de macro cancela as aspas:

03 B := X + 1
Pode-se perceber que o operador de macro remove as aspas, o que deixa um pedao de
cdigo para ser executado. Deve-se ter em mente que tudo isso acontece em tempo de
eecuo, o que torna tudo muito dinmico. Uma utilizao interessante criar um tipo
de calculadora, ou avaliador de frmulas, que determina o resultado de algo que o
usurio digita.
O operador de macro tem uma limitao: variveis referenciadas dentro da string de
caracteres (X nos exemplos anteriores) no podem ser locais.
Operadores Comuns
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Na documentao sobre variveis h uma breve demonstrao de como atribuir valores

a uma varivel da forma mais simples. O AdvPl amplia significativamente a utilizao
de variveis atravs do uso de expresses e funes. Uma expresso um conjunto de
operadores e operandos cujo resultado pode ser atribudo a uma varivel ou ento
analisado para a tomada de decises. Por exemplo:
Local nSalario := 1000, nDesconto := 0.10
Local nAumento, nSalLiquido
nAumento := nSalario * 1.20
nSalLiquido := nAumento * (1-nDesconto)
Neste exemplo so utilizadas algumas expresses para calcular o salrio lquido aps
um aumento. Os operandos de uma expresso podem ser uma varivel, uma constante,
um campo de arquivo ou uma funo.
Operadores Matemticos
Os operadores utilizados em AdvPl para clculos matemticos so:

+
Adio
Subtrao
*
Multiplicao
/
Diviso
** ou ^ Exponenciao
%
Mdulo (Resto da Diviso)
Operadores de String
Os operadores utilizados em AdvPl para tratamento de caracteres so:
+ Concatenao de strings (unio)
- Concatenao de strings com eliminao dos brancos finais das strings intermedirias
$ Comparao de Substrings (contido em)
Operadores Relacionais
Os operadores utilizados em AdvPl para operaes e avaliaes relacionais so:
<
Comparao Menor
>
Comparao Maior
=
Comparao Igual
==
Comparao Exatamente Igual (para caracteres)
<=
Comparao Menor ou Igual
>=
Comparao Maior ou Igual
<> ou # ou != Comparao Diferente
Operadores Lgicos
Os operadores utilizados em AdvPl para operaes e avaliaes lgicas so:
.And.
E lgico
.Or.
OU lgico
.Not. ou ! NO lgico
Operadores Especiais
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Alm dos operadores comuns, o AdvPl possui alguns outros operadores ou

identificadores. Estas so suas finalidades:
() Agrupamento ou Funo
[] Elemento de Matriz
{} Definio de Matriz, Constante ou Bloco de Cdigo
-> Identificador de Apelido
& Macrosubstituio
@ Passagem de parmetro por referncia
Os parnteses so utilizados para agrupar elementos em uma expresso mudando a

ordem de precedncia da avaliao da expresso (segundo as regras matemticas por
exemplo). Tambm servem para envolver os argumentos de uma funo. Veja a
documentao sobre precedncia de operadores para maiores detalhes.
Os colchetes so utilizados para especificar um elemento especfico de uma matriz. Por
exemplo, A[3,2], refere-se ao elemento da matriz A na linha 3, coluna 2.
As chaves so utilizadas para a especificao de matrizes literais ou blocos de cdigo.
Por exemplo, A:={10,20,30} cria uma matriz chamada A com trs elementos.
O smbolo -> identifica um campo de um arquivo diferenciando-o de uma varivel. Por
exemplo, FUNC->nome refere-se ao campo nome do arquivo FUNC. Mesmo que exista
uma varivel chamada nome, o campo nome que ser acessado.
O smbolo & identifica uma avaliao de expresso atravs de macro e visto em
detalhes na documentao sobre macrossubstituio.
O smbolo @ utilizado para indicar que durante a passagem de uma varivel para uma
funo ou procedimento ela seja tomada como uma referncia e no como valor.
Operadores de Atribuico
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Os operadores utilizados em AdvPl para atribuio de valores a variveis de memria

so:
=
Atribuio Simples
:=
Atribuio em Linha
+=
Adio e Atribuio em Linha
-=
Subtrao e Atribuio em Linha
*=
Multiplicao e Atribuio em Linha
/=
Diviso e Atribuio em Linha
**= ou ^= Exponenciao e Atribuio em Linha
%=
Mdulo (resto da diviso) e Atribuio em Linha
Atribuio Simples
O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.
nVariavel = 10
Atribuio em Linha
O operador de atribuio em linha caracterizado por dois pontos e o sinal de
igualdade. Tem a mesma funo do sinal de igualdade sozinho, porm aplia a atribuio
s variveis. Com ele pode-se atribuir mais de uma varivel ao mesmo tempo.
nVar1 := nVar2 := nVar3 := 0
Quando diversas variveis so inicializadas em uma mesma linha, a atribuio comea

da direita para a esquerda, ou seja, nVar3 recebe o valro zero inicialmente, nVar2
recebe o contedo de nVar3 e nVar1 recebe o contedo de nVar2 por final.
Com o operador de atribuio em linha, pode-se substituir as inicializaes individuais
de cada varivel por uma inicializao apenas:
Local nVar1 := 0, nVar2 := 0, nVar3 := 0
por
Local nVar1 := nVar2 := nVar3 := 0
O operador de atribuio em linha tambm pode ser utilizado para substituir valores de
campos em um banco de dados.
Atribuio Composta
Os operadores de atribuio composta so uma facilidade da linguagem AdvPl para
expresses de clculo e atribuio. Com eles pode-se economizar digitao:
Operador Exemplo Equivalente a
+=
X += Y X = X + Y
-=
X -= Y X = X - Y
*=
X *= Y X = X * Y
/=
X /= Y X = X / Y
**= ou ^= X **= Y X = X ** Y
%=
X %= Y X = X % Y
Operadores de Incremento/Decremento
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
A linguagem AdvPl possui operadores para realizar incremento ou decremento de

variveis. Entende-se por incremento aumentar o valor de uma varivel numrica em 1 e
entende-se por decremento diminuir o valor da varivel em 1. Os operadores so:
++ Incremento Ps ou Pr-fixado
-- Decremento Ps ou Pr-fixado
Os operadores de decremento/incremento podem ser colocados tanto antes (pr-fixado)

como depois (ps-fixado) do nome da varivel. Dentro de uma expresso, a ordem do
operador muito importante, podendo alterar o resultado da expresso. Os operadores
incrementais so executados da esquerda para a direita dentro de uma expresso.
Local nA := 10
Local nB := nA++
nA
O valor da varivel nB resulta em 21, pois a primeira referncia a nA (antes do ++)

continha o valor 10 que foi considerado e imediatamente aumentado em 1. Na segunda
referncia a nA, este j possua o valor 11. O que foi efetuado foi a soma de 10 mais 11,
igual a 21. O resultado final aps a execuo destas duas linhas a varivel nB
contendo 21 e a varivel nA contendo 11.
No entanto:
Local nA := 10
Local nB := ++nA
nA
Resulta em 22, pois o operador incremental aumentou o valor da primeira nA antes que
seu valor fosse considerado.
Ordem de Precedencia dos Operadores

Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Dependendo do tipo de operador, existe uma ordem de precedncia para a avaliao dos
operandos. Em princpio, todas as operaes com os operadores so realizadas da
esquerda para a direita se eles tiverem o mesmo nvel de prioridade.
A ordem de precedncia, ou nvel de prioridade de execuo, dos operadores em AdvPl
:
1. Operadores de Incremento/Decremento pr-fixado

2. Operadores de String
3. Operadores Matemticos
4. Operadores Relacionais
5. Operadores Lgicos
6. Operadores de Atribuio
7. Operadores de Incremento/Decremento ps-fixado
Em expresses complexas com diferentes tipos de operadores, a avaliao seguir essa

sequncia. Caso exista mais de um operador do mesmo tipo (ou seja, de mesmo nvel), a
avaliao se d da esquerda para direita. Para os operadores matemticos entretanto h
uma precedncia a seguir:
1. Exponenciao
2. Multiplicao e Diviso
3. Adio e Subtrao
Local nResultado := 2+10/2+5*3+2^3
O resultado desta expresso 30, pois primeiramente calculada a exponenciao

2^3(=8), ento so calculadas as multiplicaes e divises 10/2(=5) e 5*3(=15), e
finalmente as adies resultando em 2+5+15+8(=30).
Alterao da Precedncia
A utilizao de parnteses dentro de uma expresso altera a ordem de precedncia dos
operadores. Operandos entre parnteses so analisados antes dos que se encontram fora
dos parnteses. Se existirem mais de um conjunto de parnteses no-aninhados, o grupo
mais a esquerda ser avaliado primeiro e assim sucessivamente.
Local nResultado := (2+10)/(2+5)*3+2^3
No exemplo acima primeiro ser calculada a exponenciao 2^3(=8). Em seguida

2+10(=12) ser calculado, 2+5(=7) calculado, e finalmente a diviso e a multiplicao
sero efetuadas, o que resulta em 12/7*3+8(=13.14).
Se existirem vrios parnteses aninhados, ou seja, colocados um dentro do outro, a
avaliao ocorrer do parnteses mais intero em direo ao mais externo.
Blocos de Codigo
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Blocos de cdigo so um conceito existente h muito tempo em linguagens xBase. No

como algo que apareceu da noite para o dia, e sim uma evoluo progressiva utilizando
a combinao de muitos conceitos da linguagem para a sua implementao.
Um Primeiro Lembrete
O AdvPl uma linguagem baseada em funes. Funes tm um valor de retorno.
Assim como o operador de atribuio :=.
Assim, ao invs de escrever:
x := 10 // Atribui o valor 10 varivel chamada X
Alert("Valor de x: " + cValToChar(x))
Pode-se escrever:
// Atribui e ento exibe o valor da varivel X
Alert("Valor de x: " + cValtoChar(X := 10))
A expresso x:=10 avaliada primeiro, e ento seu resultado (o valor de X, que agora
10) passada para a funo cvaltochar para a converso para caracter, e em seguida
para a funo alert para a exibio. Por causa desta regra de precedncia possvel
atribuir um valor a mais de uma varavel ao mesmo tempo:
Z := Y := X := 0
Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:
Z := ( Y := (X := 0) )
Apesar do AdvPl avaliar expresses da esquerda para a direita, no caso de atribuies

isso acontece ao contrrio, da direita para a esquerda. O valor atribudo varivel X,
que retorna o valor para ser atribudo varivel Y e assim sucessivamente. Pode-se
dizer que o zero foi "propagado atravs da expresso".
Outro Lembrete
Em AdvPl pode-se juntar diversas linhas de cdigo em uma nica linha fscia do
arquivo. Por exemplo, o cdigo:
If lAchou
Alert("Cliente encontrado!")
Endif
pode ser escrito assim:

If lAchou ; Alert("Cliente encontrado!") ; Endif
O ponto-e-vrgula indica ao AdvPl que a nova linha de cdigo est para comear. Podese ento colocar diversas linhas lgicas de cdigo na mesma linha fsica atravs do
editor de texto utilizado.
Apesar da possibilidade de se escrever todo o programa assim, em uma nica linha
fsica, isto no recomendado pois dificulta a legibilidade do programa e,
conseqentemente, a manuteno.
Lista de Expresses
A evoluo dos blocos de cdigo comea com as listas de expresses. Nos exemplos a
seguir, o smbolo ==> indicar o retorno da expresso aps sua avaliao (seja para
atribuir em uma varivel, exibir para o usurio ou imprimir em um relatrio), que ser
impresso em um relatrio por exemplo.
Duas Linhas de Cdigo
@00,00 PSAY x := 10
@00,00 PSAY y := 20
==>
==>
10
20
Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento
impresso.
Duas Linha de Cdigo em Uma , Utilizando Ponto-e-Vrgula

Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:
Alert( cValToChar( x := 10 ; y := 20 ) )
==>
10
Apesar desse cdigo se encontrar em uma nica linha fsica, existem duas linhas lgicas
separadas pelo ponto e vrgula. Ou seja, esse cdigo equivalente a:
Alert( cValToChar( x := 10 ) )
y := 20
Portanto apenas o valor 10 da varivel x ser passado para as funes cvaltochar e alert
para ser exibido. E o valor 20 apenas ser atribudo varivel y.
Convertendo para uma Lista de Expresses

Quando parnteses so colocados ao redor do cdigo e o sinal de ponto-e-vrgula
substitudo por uma vrgula apenas, o cdigo torna-se uma lista de expresses:
Alert( cValToChar ( ( X := 10 , Y := 20 ) ) )
==>
20
O valor de retorno resultante de uma lista de expresses o valor resultante da ltima

expresso ou elemento da lista. Funciona como se fosse um pequeno programa ou
funo, que retorna o resultado de sua ltima avaliao (efetuadas da esquerda para a
direita).
Neste exemplo, a expresso x := 10 avaliada, e ento a expresso y := 20, cujo valor
resultante passado para a funo alert e cvaltochar, e ento exibido. Depois que essa
linha de cdigo executada, o valor de X igual a 10 e o de y igual a 20, e 20 ser
exibido.
Teoricamente, no h limitao para o nmero de expresses que podem ser
combinadas em uma lista de expresses. Na prtica, o nmero mximo por volta de
500 smbolos.
Debugar listas de expresses difcil oprque as expresses no esto divididas em
linhas de cdigo fonte, o que torna todas as expresses associadas a uma mesma linha
de cdigo. Isto pode tornar muito difcil determinar onde um erro ocorreu.
Onde Pode-se Utilizar uma Lista de Expresses?

O propsito principal de uma lista de expresses agrup-las em uma nica unidade.
Em qualquer lugar do cdigo AdvPl que uma expresso simples pode ser utilizada,
pode-se utilizar uma lista de expresses. E ainda, pode-se fazer com que vrias coisas
aconteam onde normalmente apenas uma aconteceria.
X := 10 ; Y := 20
If X > Y
Alert("X")
Z := 1
Else
Alert("Y")
Z := -1
Endif
Aqui temos o mesmo conceito, escrito utilizando listas de expresses na funo iif:
X := 10 ; Y := 20
iif( X > Y , ;
( Alert("X"), Z := 1 ) , ;
( Alert("Y"), Z := -1 )
)
De Listas de Expresses para Blocos de Cdigo

Considere a seguinte lista de expresses:
Alert( cValToChar( ( x := 10, y := 20 ) ) )
==>
20
O AdvPl permite criar funes, que so pequenos pedaos de cdigo, como se fosse um
pequeno programa, utilizados para diminuir partes de tarefas mais complexas e
reaproveitar cdigo em mais de um lugar num programa. Para maiores detalhes consulte
a documentao sobre a criao de funes em AdvPl. Porm, a idia neste momento
que a lista de expresses utilizada na linha anterior pode ser criada como uma funo:
Function Lista()
X := 10
Y := 20
Return Y
E a linha de exemplo com a lista de expresses pode ser substituda, tendo o mesmo
resultado, por:
Alert( cValToChar( Lista() ) )
==>
20
Como mencionado anteriormente, uma lista de expresses como um pequeno

programa ou funo. Com poucas mudanas, uma lista de expresses pode se tornar um
bloco de cdigo:
( X := 10 , Y := 20 )
// Lista de Expresses
{|| X := 10 , Y := 20 } // Bloco de Cdigo
Note as chaves {} utilizadas no bloco de cdigo. Ou seja, um bloco de cdigo uma

matriz. Porm na verdade, no uma lista de dados, e sim uma lista de comandos, uma
lista de cdigo.
// Isto uma matriz de dados
A := {10, 20, 30}
// Isto um bloco de cdigo, porm funciona como
// se fosse uma matriz de comandos
B := {|| x := 10, y := 20}
Executando um Bloco de Cdigo

Diferentemente de uma matriz, no se pode acessar elementos de um bloco de cdigo
atravs de um ndice numrico. Porm blocos de cdigo so semelhantes a uma lista de
expresses, e a uma pequena funo. Ou seja, podem ser executados. Para a execuo,
ou avaliao, de um bloco de cdigo, deve-se utilizar a funo eval:
nRes := Eval(B)
==>
20
Essa funo recebe como parmero um bloco de cdigo e avalias todas as expresses
contidas neste bloco de cdigo, retornando o resultado da ltima expresso avaliada.
Passando Parmetros
J que blocos de cdigo so como pequenas funes, tambm possvel a passagem de
parmetros para um bloco de cdigo. Os parmetros devem ser informados entre as
barras verticais (||) separados por vrgulas, assim como em uma funo.
B := {| N | X := 10, Y := 20 + N}
Porm deve-se notar que j que o bloco de cdigo recebe um parmetro, um valor deve
ser passado quando o bloco de cdigo for avaliado.
C := Eval(B, 1)
==>
21
Utilizando Blocos de Cdigo

Blocos de cdigo podem ser utilizados em diversas situaes. Geralmente so utilizados
para executar tarefas quando eventos de objetos so acionados ou para modificar o
comportamento padro de algumas funes.
Por exemplo, considere a matriz abaixo:
A := {"GARY HALL", "FRED SMITH", "TIM JONES"}
Esta matriz pode ser ordenada pelo primeiro nome, utilizando-se a chamada da funo
asort(A), resultado na matriz com os elementos ordenados dessa forma:
{"FRED SMITH", "GARY HALL", "TIM JONES"}
A ordem padro para a funo asort ascendente. Este comportamento pode ser
modificado atravs da informao de um bloco de cdigo que ordena a matriz de forma

descendente:
B := { |X, Y| X > Y }
aSort(A, B)
O bloco de cdigo (de acordo com a documentao da funo asort) deve ser escrito
para aceitar dois parmetros que so os dois elementos da matriz para comparao. Note
que o bloco de cdigo no conhece que elementos est comparando - a funo asort
seleciona os elementos (talvez utilizando o algortmo QuickSort) e passa-os para o
bloco de cdigo. O bloco de cdigo compara-os e retorna verdadeiro (.T.) se se
encontram na ordem correta, ou falso (.F.) se no. Se o valor de retorno for falso, a
funo asort ir ento trocar os valores de lugar e seguir comparando o prximo par de
valores.
Ento, no bloco de cdigo anterior, a comparao X > Y verdadeira se os elementos
esto em ordem descendente, o que significa que o primeiro valor maior que o
segundo.
Para ordenar a mesma matriz pelo ltimo nome, tambm em ordem descendente, podese utilizar o seguinte bloco de cdigo:
B := { |X, Y| Substr(X,At(" ",X)+1) > Substr(Y,At(" ",Y)+1) }
Note que este bloco de cdigo procura e compara as partes dos caracteres
imediatamente seguinte a um espao em branco. Depois de utilizar esse bloco de cdigo
para a funo asort, a matriz conter:
{"GARY HALL", "TIM JONES", "FRED SMITH"}
Finalmente, para ordenar um sub-elemento (coluna) de uma matriz por exemplo, podese utilizar o seguinte bloco de cdigo:
B := { |X, Y| X[1] > Y[1] }
Criaco e Atribuico de Variaveis

Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Variveis de memria so um dos recursos mais importantes de uma linguagem. So

reas de memria criadas para armazenar informaes utilizadas por um programa para
a execuo de tarefas. Por exemplo, quando o usurio digita uma informao qualquer,
como o nome de um produto, em uma tela de um programa esta informao
armazenada em uma varivel de memria para posteriormente ser gravada ou impressa.
A partir do momento que uma varivel criada, no necessrio mais se referenciar ao
seu contedo, e sim ao seu nome. O nome de uma varivel um identificador nico que
segue duas regras regras:
Mximo de 10 caracteres. O AdvPl no impede a criao de uma varivel de memria
cujo nome contenha mais de 10 caracteres, porm apenas os 10 primeiros sero
considerados para a localizao do contedo armazenado. Portanto se forem criadas
duas variveis cujos 10 primeiros caracteres forem iguais, como nTotalGeralAnual e
nTotalGeralMensal, as referncias a qualquer uma delas no programa resultaro o
mesmo. Ou seja, sero a mesma varivel:
nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))
Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300.

Isso acontece porque no momento que esse valor foi atribuido varivel
nTotalGeralAnual, o AdvPl considerou apenas os 10 primeiros caracteres (assim como
o faz quando deve exibir o valor da varivel nTotalGeralMensal), ou seja, considerou-as
como a mesma varivel. Assim o valor original de 100 foi substituido pelo de 300.
Limitao de caracteres no nome. Os nomes das variveis devem sempre comear por
uma letra ou o caracter de sublinhado ( _ ). No restante, pode conter letras, nmeros e o
caracter de sublinhado. Qualquer outro caracter, incluindo espaos em branco, no so
permitidos.
O AdvPl permite a criao ilimitada de variveis, dependendo apenas da memria
disponvel. A seguir esto alguns nomes vlidos para variveis:
TOT01
cNumero
VAR_QUALQUER
M_CARGO
A11
E alguns invlidos:
1CODIGO (Inicia por um nmero)
M CARGO (contm um espao em branco)
LOCAL
(palavra reservada do AdvPl)
O AdvPl no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio

informar o tipo de dados que determinada varivel ir conter no momento de sua
declarao, e o seu valor pode mudar durante a execuo do programa. Tambm no h
necessidade de declarar variveis em uma seo especfica do seu cdigo fonte, embora
seja aconselhvel declarar todas as variveis necessrias no comeo, tornando a
manuteno mais fcil e evitando a declarao de variveis desnecessrias.
Para declarar uma varivel deve-se utilizar um identificador de escopo, seguido de uma
lista de variveis separadas por vrgula (,). Um identificador de escopo uma palavra
chave que indica a que contexto do programa a varivel declarada pertence. O contexto
de variveis pode ser local (visualizadas apenas dentro do programa atual), pblico
(visualizadas por qualquer outro programa), entre outros. Os diferentes tipos de
contexto de variveis so explicados na documentao sobre escopo de variveis.
Considere as linhas de cdigo de exemplo:
nResultado := 250 * (1 + (nPercentual / 100))
Se esta linha for executada em um programa AdvPl, ocorrer um erro de execuo com
a mensagem "variable does not exist: nPercentual", pois esta varivel est sendo
utilizada em uma expresso de clculo sem ter sido declarada. Para solucionar este erro,
deve-se declarar a varivel previamente:
Local nPercentual, nResultado
Neste exemplo, as variveis so declaradas previamente utilizando o identificador de

escopo local. Quando a linha de clculo for executada, o erro de varivel no existente
no mais ocorrer. Porm variveis no inicializadas tm sempre o valor default nulo
(Nil) e este valor no pode ser utilizado em um clculo pois tambm gerar erros de
execuo (nulo no pode ser dividido por 100). A resoluo deste problema efetuada
inicializando-se a varivel atravs de uma das formas:
Local nPercentual,nResultado
Store 10 To nPercentual
ou
Local nPercentual, nResultado
nPercentual := 10
ou
Local nPercentual := 10, nResultado
A diferena entre o ltimo exemplo e os dois anteriores que a varivel inicializada

no momento da declarao. Nos dois primeiros exemplos, a varivel primeiro
declarada e ento inicializada em uma outra linha de cdigo. O comando store existe
apenas por compatibilidade com verses anteriores e outras linguagens xBase, mas
obsoleto. Deve-se utilizar o operador de atribuio (:= ou somente =). aconselhvel
optar pelo operador de atribuio composto de dois pontos e sinal de igual, pois o
operador de atribuio utilizando somente o sinal de igual pode ser facilmente
confundido com o operador relacional (para comparao) durante a criao do
programa.
Uma vez que um valor lhe seja atribudo, o tipo de dado de uma varivel igual ao tipo
de dado do valor atribudo. Ou seja, uma varivel passa a ser numrica se um nmero
lhe atribudo, passa a ser caracter se uma string de texto lhe for atribuda, etc. Porm
mesmo que uma varivel seja de determinado tipo de dado, pode-se mudar o tipo da
varivel atribuindo outro tipo a ela:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
Local xVariavel // Declara a varivel inicialmente com valor nulo

xVariavel := "Agora a varivel caracter..."
Alert("Valor do Texto: " + xVariavel)
xVariavel := 22 // Agora a varivel numrica
Alert(cValToChar(xVariavel))
xVariavel := .T. // Agora a varivel lgica
If xVariavel
Alert("A varivel tem valor verdadeiro...")
Else
Alert("A varivel tem valor falso...")
Endif
xVariavel := Date() // Agora a varivel data
17
18
19
20
21
22
Alert("Hoje : " + DtoC(xVariavel))

xVariavel := nil // Nulo novamente
Alert("Valor nulo: " + xVariavel)
Return
No programa de exemplo anterior, a varivel xVariavel utilizada para armazenar

diversos tipos de dados. A letra "x" em minsculo no comeo do nome utilizada para
indicar uma varivel que pode conter diversos tipos de dados, segundo a Notao
Hngara (consulte documentao especfica para detalhes). Este programa troca os
valores da varivel e exibe seu contedo para o usurio atravs da funo alert. Essa
funo recebe um parmetro que deve ser do tipo string de caracter, por isso
dependendo do tipo de dado da varivel xVariavel necessrio fazer uma converso
antes.
Apesar dessa flexibilidade de utilizao de variveis, deve-se tomar cuidados na
passagem de parmetros para funes ou comandos, e na concatenao (ou soma) de
valores. Note a linha 20 do programa de exemplo. Quando esta linha executada, a
varivel xVariavel contem o valor nulo. A tentativa de soma de tipos de dados
diferentes gera erro de execuo do programa. Nesta linha do exemplo, ocorrer um
erro com a mensagem "type mismatch on +". Excetuando-se o caso do valor nulo, para
os demais deve-se sempre utilizar funes de converso quando necessita-se concatenar
tipos de dados diferentes (por exemplo, nas linhas 07 e 17.
Note tambm que quando uma varivel do tipo de dado lgico, ela pode ser utilizada
diretamente para checagem (linha 10):
If xVariavel
o mesmo que
If xVariavel = .T.
A declarao de variveis para os demais tipos de dados, matrizes e blocos de cdigo,

exatamente igual ao descrito at agora. Apenas existem algumas diferenas quanto a
inicializao, que podem ser consultadas na documentao de inicializao de matrizes
e blocos de cdigo.
Diferenciaco entre variaveis e nomes de

campos
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Muitas vezes uma varivel pode ter o mesmo nome que um campo de um arquivo ou
tabela aberto no momento. Neste caso, o AdvPl privilegiar o campo. Assim uma
referncia a um nome que identifique tanto uma varivel como um campo, resultar no
contedo do campo.
Para especificar qual deve ser o elemento referenciado, deve-se utilizar o operador de
identificao de apelido (->) e um dos dois identificadores de referncia, MEMVAR ou
FIELD.
cRes := MEMVAR->NOME
Esta linha de comando identifica que o valor atribudo varivel cRes deve ser o valor
da varivel de memria chamada NOME.
cRes := FIELD->NOME
Neste caso, o valor atribudo varivel cRes ser o valor do campo NOME existente no
arquivo ou tabela aberto na rea atual.
O identificador FIELD pode ser substitudo pelo apelido de um arquivo ou tabela
aberto, para evitar a necessidade de selecionar a rea antes de acessar o contedo de
terminado campo.
cRes := CLIENTES->NOME
Para maiores detalhes sobre abertura de arquivos com atribuio de apelidos, consulte a
documentao sobre acesso a banco de dados ou a documentao da funo dbUseArea.
Inicializando Matrizes
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Algumas vezes o tamanho da matriz conhecido previamente. Outras vezes o tamanho

da matriz s ser conhecido em tempo de execuo.
Se o tamanho da matriz conhecido
Se o tamanho da matriz conhecido no momento que o programa escrito, h diversas
maneiras de implementar o cdigo.
01
02
03
04
05
06
07
08
Local
Local
Local
Local
nCnt
aX[10]
aY := Array(10)
aZ := {0,0,0,0,0,0,0,0,0,0}
For nCnt := 1 To 10
aX[nCnt] := nCnt * nCnt
Next nCnt
Este cdigo preenche a matriz com uma tabela de quadrados. Os valores sero 1, 4, 9,
16 ... 81, 100. Note que a linha 07 se refere varivel aX, mas poderia tambm
trabalhar com aY ou aZ. O objetivo deste exemplo demonstrar trs modos de criar
uma matriz de tamanho conhecido no momento da criao do cdigo.
Na linha 02 a matriz criada usando aX[10]. Isto indica ao AdvPl para alocar espao
para 10 elementos na matriz. Os colchetes [ e ] so utilizados para indicar o tamanho
necessrio.
Na linha 03 utilizada a funo array com o parmetro 10 para criar a matriz, e o
retorno desta funo atribudo varivel aY.
Na linha 03 efetuado o que se chama "desenhar a imagen da matriz". Como pode-se
notar, existem dez 0s na lista encerrada entre chaves ({}). Claramente, este mtodo no
o utilizado para criar uma matriz de 1000 elementos. O terceiro mtodo difere dos
anteriores porque inicializa a matriz com os valores definitivos. Nos dois primeiros
mtodos, cada posio da matriz contm um valor nulo (Nil) e deve ser inicializado
posteriormente.
A linha 07 demonstra como um valor pode ser atribudo para uma posio existente em
uma matriz especificando o ndice entre colchetes.
Se o tamanho da matriz no conhecido

Se o tamanho da matriz no conhecido at o momento da execuo do programa, h
algumas maneiras de criar uma matriz e adicionar elementos a ela. O exemplo a seguir
ilustra a idia de criao de uma matriz vazia (sem nenhum elemento) e adio de
elementos dinamicamente.
01
02
03
04
05
06
07
08
Local
Local
Local
Local
nCnt
aX[0]
aY := Array(0)
aZ := {}
For nCnt := 1 To nSize

aAdd(aX,nCnt*nCnt)
Next nCnt
A linha 02 utiliza os colchetes para criar uma matriz vazia. Apesar de no ter nenhum
elemento, seu tipo de dado matriz.
Na linha 03 a chamada da funo array cria uma matriz sem nenhum elemento.
Na linha 04 est declarada a representao de uma matriz vazia em AdvPl. Mais uma
vez, esto sendo utilizadas as chaves para indicar que o tipo de dados da varivel
matriz. Note que {} uma matriz vazia (tem o tamanho 0), enquanto {Nil} uma
matriz com um nico elemento nulo (tem tamanho 1).
Porque cada uma destas matrizes no contem elementos, a linha 07 utiliza a funo aadd
para adicionar elementos sucessivamente at o tamanho necessrio (especificado por
exemplo na varivel nSize).
Matrizes
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Matrizes, ou arrays, so colees de valores. Ou, de uma maneira mais fcil de

entender, uma lista. Uma matriz pode ser criada atravs de diferentes maneiras.
Consulte a documentao sobre Inicializao de Matrizes para maiores detalhes.
Cada item em uma matriz referenciado pela indicao de sua posio numrica na
lista, iniciando pelo nmero 1. O exemplo a seguir declara uma varivel, atribui uma
matriz de trs elementos a ela, e ento exibe um dos elementos e o tamanho da matriz:
Local aLetras
// Declarao da varivel
aLetras := {"A", "B", "C"} // Atribuio da matriz varivel
Alert(aLetras[2])
// Exibe o segundo elemento da matriz
Alert(cValToChar(Len(aLetras)))
// Exibe o tamanho da matriz
O AdvPl permite a manipulao de matrizes facilmente. Enquanto que em outras

linguagens como C ou Pascal necessrio alocar memria para cada elemento de uma
matriz (o que tornaria a utilizao de "pointeiros" necessria), o AdvPl se encarrega de
gerenciar a memria e torna simples adicionar elementos a uma matriz, utilizando a
funo aAdd:
aAdd(aLetras,"D")
Alert(aLetras[4])
Alert(aLetras[5])
// Adiciona o quarto elemento ao final da matriz

// Exibe o quarto elemento
// Erro! No h um quinto elemento na matriz
Matrizes como Estruturas

Uma caracterstica interessante do AdvPl que uma matriz pode conter qualquer coisa:
nmeros, datas, lgicos, caracteres, objetos, etc. E ao mesmo tempo. Em outras
palavras, os elementos de uma matriz no precisam ser necessariamente do mesmo tipo
de dado, em contraste com outras linguagens como C e Pascal.
aFunct1 := {"Pedro",32,.T.}
Esta matriz contem uma string, um nmero e um valor lgico. Em outras linguagens
como C ou Pascal, este "pacote" de informaes pode ser chamado como um "struct"
(estrutura em C, por exemplo) ou um "record" (registro em Pascal, por exemplo). Como
se fosse na verdade um registro de um banco de dados, um pacote de informaes
construdo com diversos campos. Cada campo tendo um pedao diferente de dado.
Suponha que no exemplo anterior, o array aFunct1 contenha informaes sobre o nome
de uma pessoa, sua idade e sua situao matrimonial. Os seguintes #defines podem ser
criados para indicar cada posio dos valores dentro da matriz:
#define FUNCT_NOME
1
#define FUNCT_IDADE 2
#define FUNCT_CASADO 3
E considere mais algumas matrizes para representar mais pessoas:
aFunct2 := {"Maria" , 22, .T.}

aFunct3 := {"Antnio", 42, .F.}
Os nomes podem ser impressos assim:

Alert(aFunct1[FUNCT_NOME])
Agora, ao invs de trabalhar com variveis individuais, pode-se agrup-las em uma

outra matriz, do mesmo modo que muitos registros so agrupados em uma tabela de
banco de dados:
aFuncts := {aFunct1, aFunct2, aFunct3}
Que equivalente a isso:

aFuncts := { {"Pedro" , 32, .T.}, ;
{"Maria" , 22, .T.}, ;
{"Antnio", 42, .F.} }
aFuncts uma matriz com 3 linhas por 3 colunas. Uma vez que as variveis separadas
foram combinadas em uma matriz, os nomes podem ser exibidos assim:
Local nCount
For nCount := 1 To Len(aFuncts)
Alert(aFuncts[nCount,FUNCT_NOME])
// O acesso a elementos de uma matriz multidimensional
// pode ser realizado tambm desta forma:
// aFuncts[nCount][FUNCT_NOME]
Next nCount
A varivel nCount seleciona que funcionrio (ou que linha) de interesse. Ento a
constante FUNCT_NOME seleciona a primeira coluna daquela linha.
Cuidados com Matrizes

Matrizes so listas de elementos, portanto memria necessria para armazenar estas
informaes. Como as matrizes podem ser multidimensionais, a memria necessria

ser a multiplicao do nmero de itens em cada dimenso da matriz, considerando-se o
tamanho do contedo de cada elemento contido nesta. Portanto o tamanho de uma
matriz pode variar muito.
A facilidade da utilizao de matrizes, mesmo que para armazenar informaes em
pacotes como descrito anteriormente, no compensada pela utilizao em memria
quando o nmero de itens em um array for muito grande. Quando o nmero de
elementos for muito grande deve-se procurar outras solues, como a utilizao de um
arquivo de banco de dados temporrio.
No h limitao para o nmero de dimenses que uma matriz pode ter, mas o nmero
de elementos mximo (independentes das dimenses onde se encontram) de 100000.
Tipos de Dados
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
O AdvPl no uma linguagem de tipos rgidos (strongly typed), o que significa que
variveis de memria podem diferentes tipos de dados durante a execuo do programa.
Variveis podem tambm conter objetos, mas os tipos primrios da linguagem so:
Numrico
Lgico
Caracter
Data
Matriz (Array)
Bloco de Cdigo
Numrico
O AdvPl no diferencia valores inteiros de valores com ponto flutuante, portanto podese criar variveis numricas com qualquer valor dentro do intervalo permitido. Os
seguintes elementos so do tipo de dado numrico:
2
43.53
0.5
0.00001
1000000
Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos
incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E308 at
1.7976931348623158 E+308.
Lgico
Valores lgicos em AdvPl so identificados atravs de .T. ou .Y. para verdadeiro e .F.
ou .N. para falso (independentemente se os caracteres estiverem em maisculo ou
minsculo).
Caracter
Strings ou cadeias de caracteres so identificadas em AdvPl por blocos de texto entre
aspas duplas (") ou aspas simples ('):
"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"
Uma varivel do tipo caracter pode conter strings com no mximo 1 Mb, ou seja,
1048576 caracteres.
Data
O AdvPl tem um tipo de dados especfico para datas. Internamente as variveis deste
tipo de dado so armazenadas como um nmero correspondente a data Juliana.
Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs da
utilizao de funes especficas como por exemplo ctod que converte uma string para
data.
Matriz (Array)
Matrizes so um tipo de dado especial. a disposio de outros elementos em colunas e
linhas. O AdvPl suporta matrizes uni ou multidimensionais. Os elementos de uma
matriz so acessados atravs de ndices numricos iniciados em 1, identificando a linha
e coluna para quantas dimenes existirem.
Uma matriz pode conter no mximo 100000 elementos, independentemente do nmero
de dimenses.
Matrizes devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir
a memria do servidor.
Bloco de Cdigo
O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues
escritas em AdvPl que podero ser executadas posteriormente.
ESCOPO DE VRIAVEIS
O Contexto de Variaveis dentro de um

Programa
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
As variveis declaradas em um programa ou funo, so visveis de acordo com o

escopo onde so definidas. Como tambm do escopo depende o tempo de existncia das
variveis. A definio do escopo de uma varivel efetuada no momento de sua
declarao.
Local nNumero := 10
Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence
seu escopo local.
Os identifadores de escopo so:
LOCAL
STATIC
PRIVATE
PUBLIC
O AdvPl no rgido em relao declarao de variveis no comeo do programa. A

incluso de um identificador de escopo no necessrio para a declarao de uma
varivel, contanto que um valor lhe seja atribudo.
nNumero2 := 15
Quando um valor atribudo uma varivel em um programa ou funo, o AdvPl criar

a varivel caso ela no tenha sido declarada anteriormente. A varivel ento criada
como se tivesse sido declarada como Private.
Devido a essa caracterstica, quando pretende-se fazer uma atribuio a uma varivel
declarada previamente mas escreve-se o nome da varivel de forma incorreta, o AdvPl
no gerar nenhum erro de compilao ou de execuo. Pois compreender o nome da
varivel escrito de forma incorreta como se fosse a criao de uma nova varivel. Isto
alterar a lgica do programa, e um erro muitas vezes difcil de identificar.
Variaveis Estaticas
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Variveis estticas funcionam basicamente como as variveis locais, mas mantm seu
valor atravs da execuo. Variveis estticas devem ser declaradas explicitamente no
cdigo com o identificador STATIC.
O escopo das variveis estticas depende de onde so declaradas. Se forem declaradas
dentro do corpo de uma funo ou procedimento, seu escopo ser limitado quela
rotina. Se forem declaradas fora do corpo de qualquer rotina, seu escopo todo o
arquivo de programa.
Neste exemplo, a varivel nVar declarada como esttica e inicializada com o valor 10:
Function Pai()
Static nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada.
Diferente de variveis declaras como LOCAL ou PRIVATE, nVar continua a existir e

mantem seu valor atual quando a execuo da funo Pai termina. Entretanto, somente
pode ser acessada por execues subseqntes da funo Pai.
Variaveis Locais
Reviso: 02/12/2004
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Variveis locais so pertencentes apenas ao escopo da funo onde foram declaradas.

Devem ser explicitamente declaradas com o identificador LOCAL, como no exemplo:
Function Pai()
Local nVar := 10, aMatriz := {0,1,2,3}
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10.
Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada.
Quando a execuo da funo Pai terminar, a varivel nVar destruda. Qualquer
varivel com o mesmo nome no programa que chamou a funo Pai no afetada.
Variveis locais so criadas automaticamente cada vez que a funo onde forem
declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da
ativao da funo (ou seja, at que a funo retorne o controle para o cdigo que a
executou). Se uma funo chamada recursivamente (por exemplo, chama a si mesma),
cada chamada em recurso cria um novo conjunto de variveis locais.
A visibilidade de variveis locais idntica ao escopo de sua declarao. Ou seja, a
varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se uma
funo chamada recursivamente, apenas as variveis locais criadas na mais recente
ativao so visveis.
A declarao de variveis locais dentro de uma funo deve preceder qualquer

comando interno ou declarao de outros tipos de variveis (Private ou Public) da
funo caso contrrio ser gerado um erro de compilao.
Exemplo:
Function A( )
Private x:= 0
Local b:=0 <<<<< ERRADO, ERRO DE COMPILAO
...
Return
Verso correta:
Function A( )
Local b:=0 // correto
Private x:=0
....
Return
Variaveis Privadas
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
A declarao opcional para variveis privadas. Mas podem ser declaradas

explicitamente com o identificador PRIVATE.
Adicionalmente, a atribuio de valor a uma varivel no criada anteriormente
automaticamente cria a varivel como privada. Uma vez criada, uma varivel privada
continua a existir e mantem seu valor at que o programa ou funo onde foi criada
termine (ou seja, at que a funo onde foi criada retorne para o cdigo que a executou).
Neste momento, automaticamente destruda.

possvel criar uma nova varivel privada com o mesmo nome de uma varivel j
existente. Entretanto, a nova (duplicada) varivel pode apenas ser criada em um nvel de
ativao inferior ao nvel onde a varivel foi declarada pela primeira vez (ou seja,
apenas em uma funo chamada pela funo onde a varivel j havia sido criada). A
nova varivel privada ir esconder qualquer outra varivel privada ou pblica (veja a
documentao sobre variveis pblicas) com o mesmo nome enquanto existir.
Uma vez criada, uma varivel privada visvel em todo o programa enquanto no for
destruda automaticamente quando a rotina que a criou terminar ou uma outra varivel
privada com o mesmo nome for criada em uma subfuno chamada (neste caso, a
varivel existente torna-se inacessvel at que a nova varivel privada seja destruda).
Em termos mais simples, uma varivel privada visvel dentro da funo de criao e
todas as funes chamadas por esta, a menos que uma funo chamada crie sua prpria
varivel privada com o mesmo nome.
Por exemplo:
Function Pai()
Private nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Neste exemplo, a varivel nVar criada como privada e inicializada com o valor 10.
Quando a funo Filha executada, nVar ainda existe e, diferente de uma varivel local,
pode ser acessada pela funo Filha. Quando a funo Pai terminar, nVar ser destruda
e qualquer declarao de nVar anterior se tornar acessvel novamente.
Variaveis Publicas
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Pode-se criar variveis pblicas dinamicamente no cdigo com o identificador PUBLIC.

As variveis pblicas continuam a existir e mantm seu valor at o fim da execuo.
possvel criar uma varivel privada com o mesmo nome de uma varivel pblica
existente. Entretanto, no permitido criar uma varivel pblica com o mesmo nome de
uma varivel privada existente.
Uma vez criada, uma varivel pblica visvel em todo o programa onde foi declarada
at que seja escondida por uma varivel privada criada com o mesmo nome. A nova
varivel privada criada esconde a varivel pblica existente, e esta se tornar inacessvel
at que a nova varivel privada seja destruda. Por exemplo:
Function Pai()
Public nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Neste exemplo, nVar criada como pblica e inicializada com o valor 10. Quando a
funo Filha executada, nVar ainda existe e pode ser acessada. Diferente de variveis
locais ou privadas, nVar ainda existe aps o trmino da a execuo da funo Pai.
Diferentemente dos outros identificadores de escopo, quando uma varivel declarada
como pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).

Apostila Com Comandos para Server, Remote, HTTP, Objetos

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Apostila Com Comandos para Server, Remote, HTTP, Objetos

Загружено:

Авторское право:

Доступные форматы

CLASSES VISUAIS

PDF Creator - PDF4Free v2.0

Executado quando objeto ganha foco.

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Objeto, opcional. Janela me da janela a ser criada,

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Numrico, opcional. Largura do controle em pixels.

Muda o item selecionado no combobox.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

PDF Creator - PDF4Free v2.0

Mtodo construtor do controle.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Bloco de cdigo, opcional. Executado quando o

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

@ 10,10 MSGET oGet1 VAR cGet1 SIZE 100,10 OF oGroup PIXEL

Mtodo construtor da classe.

PDF Creator - PDF4Free v2.0

Numrico, opcional. Largura do controle em pixels.

Fora a seleo de um item.

Parmetros Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Numrico, opcional. Posio do item a ser selecionado.

Insere ou adiciona novo item.

Parmetro Tipo / Descrio

Modifica o texto de um item.

Parmetro Tipo / Descrio

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE Teste

PDF Creator - PDF4Free v2.0

Numrico. Nmero total de passos at o preenchimento da rgua de

Mtodo construtor da classe.

Parmetro Tipo / Descrio

PDF Creator - PDF4Free v2.0

Atualiza a posio da rgua de processamento.

Parmetro Tipo / Descrio

STATIC Function RunMeter(oMeter)

PDF Creator - PDF4Free v2.0

nCurrent+=10 // atualiza rgua

Mtodo construtor da classe.

PDF Creator - PDF4Free v2.0