Você está na página 1de 252

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
pixels ou caracteres.
Numrico, opcional. Coordenada horizontal direita em
anRight
pixels ou caracteres.
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Descrio
Sintaxe

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels ou
anRow
carateres.
Numrico, opcional. Coordenada horizontal em pixels
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
Bloco de cdigo, opcional. Executado quando o
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.
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.
Retorno

O objeto construdo.

Exemplo
#include protheus.ch
User Function Teste()
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.)
ACTIVATE MSDIALOG oDlg CENTERED
If lCheck
MsgStop( Funcionou! )
Endif
Return NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels ou
anRow
caracteres.
Numrico, opcional. Coordenada horizontal em pixels
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}.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

anWidth
anHeight

Numrico, opcional. Largura do controle em pixels.


Numrico, opcional. Altura do controle em pixels.
Objeto, opcional. Janela ou controle onde o controle
aoWnd
ser criado.
nPar8
Reservado.
Bloco de cdigo, opcional. Executado quando o
abChange
controle modifica o item selecionado.
Bloco de cdigo, opcional. Executado quando o
contedo do controle deve ser validado, deve retornar
abValid
.T. se o contedo for vlido e .F. quando o contedo
for invlido.
anClrBack Numrico, opcional. Cor de fundo do controle.
anClrText Numrico, opcional. Cor do texto do controle.
Lgico, opcional. Se .T. as coordenadas informadas
alPixel
so em pixels, se .F. so em caracteres.
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

Parmetro Tipo / Descrio


anItem
Numrico, opcional. Posio do item a ser selecionado.

Retorno

NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
@ 40,10 BUTTON oButton PROMPT Fechar OF oDlg PIXEL ACTION oDlg:End()
ACTIVATE MSDIALOG oDlg CENTERED
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Retorno

O objeto criado.

Exemplo
#INCLUDE "PROTHEUS.CH"
User Function Teste()
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.
ACTIVATE MSDIALOG oDlg CENTERED
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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])

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels
anRow
ou caracteres.
Numrico, opcional. Coordenada horizontal em pixels
anCol
ou caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no
formato {|u| if( Pcount( )>0, <var>:= u, <var> ) } que
abSetGet
o controle utiliza para atualizar a varivel <var>.
<var> deve ser tipo caracter, numrico ou data.
Objeto, opcional. Janela ou controle onde o controle
aoWnd
ser criado.
anWidth
Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
Caractere, opcional. Mscara de formatao do
acPict
contedo a ser exibido.
Bloco de cdigo, opcional. Executado quando o
contedo do controle deve ser validado, deve retornar
abValid
.T. se o contedo for vlido e .F. quando o contedo
for invlido.
Parmetros
anClrFore Numrico, opcional. Cor de fundo do controle.
anClrBack Numrico, opcional. Cor do texto do controle.
Objeto, opcional. Objeto tipo tFont utilizado para
aoFont
definir as caractersticas da fonte utilizada para exibir
o contedo do controle.
lPar12
Reservado.
oPar13
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas
alPixel
so em pixels, se .F. so em caracteres.
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.
lPar19
Reservado.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Bloco de cdigo, opcional. Executado quando o


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
#include protheus.ch
User Function TesteGet()
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
*/
// Boto para fechar a janela
@ 40,10 BUTTON oButton PROMPT Fechar OF oDlg PIXEL ACTION oDlg:End()
ACTIVATE MSDIALOG oDlg CENTERED
MsgStop( O valor +Transform(nGet1,@E 999,999.00) )
Return NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

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
anBottom
pixels ou caracteres.
Numrico, opcional. Coordenada horizontal direita em
anRight
pixels ou caracteres.
Parmetros
acCaption Caractere, opcional. Ttulo do grupo.
Objeto, opcional. Janela ou controle onde o controle
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
#include protheus.ch
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.)

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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


@ 30,10 MSGET oGet2 VAR cGet2 SIZE 100,10 OF oGroup PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
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

Mtodo construtor da classe.


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

PDF Creator - PDF4Free v2.0

Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels
ou caracteres.
Numrico, opcional. Coordenada horizontal em
pixels 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>. <var> deve ser tipo caracter ou numrica.
Array de items caracteres, opcional. Lista de items
selecionveis.

http://www.pdf4free.com

anWidth
anHeight

Numrico, opcional. Largura do controle em pixels.


Numrico, opcional. Altura do controle em pixels.
Bloco de cdigo, opcional. Executado quando o
abChange
item selecionado alterado.
Objeto, opcional. Janela ou controle onde o
aoWnd
controle ser criado.
Bloco de cdigo, opcional. Executado quando o
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.
Lgico, opcional. Se .T. as coordenadas informadas
alPixel
so em pixels, se .F. so em caracteres.
lPar13
Reservado.
Bloco de cdigo, opcional. Executado quando
abLDBLClick acionado duplo click do boto esquerdo do mouse
sobre o controle.
Objeto, opcional. Objeto tipo tFont utilizado para
aoFont
definir as caractersticas da fonte utilizada para
exibir o contedo do controle.
cPar16
Reservado.
lPar17
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.
aPar19
Reservado.
bPar20
Reservado.
lPar21
Reservado.
lPar22
Reservado.
Bloco de cdigo, opcional. Executado quando
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

nItem
Retorno

Numrico, opcional. Posio do item a ser selecionado.

NIL

Add
Descrio
Sintaxe

Insere ou adiciona novo item.


Add( cText, nPos )

Parmetro Tipo / Descrio


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 )

Parmetro Tipo / Descrio


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 )

Parmetro Tipo / Descrio


Parmetros
Numrico, obrigatrio. Posio a ser excluida, deve ser
nPos
maior que 0 e menor ou igual que o nmero de itens.
Retorno

NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
#include protheus.ch
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.)
ACTIVATE MSDIALOG oDlg CENTERED
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels ou
anRow
caracteres.
Numrico, opcional. Coordenada horizontal em pixels
anCol
ou caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato
{|u| if( Pcount( )>0, <var>:= u, <var> ) } que o controle
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.
Objeto, opcional. Janela ou controle onde o controle
aoWnd
sera criado.
anWidth Numrico, opcional. Largura do controle em pixels.
Parmetros
anHeight Numrico, opcional. Altura do controle em pixels.
lPar8
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas so
alPixel
em pixels, se .F. so em caracteres.
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Set
Descrio
Sintaxe

Atualiza a posio da rgua de processamento.


Set( [nVal] )

Parmetro Tipo / Descrio


Parmetros
Numrico, opcional. Novo valor da posio da rgua de
nVal
processamento.
Retorno

NIL

Exemplo
#include protheus.ch
STATIC lRunning:=.F., lStop:=.F.
User Function Teste()
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.
ACTIVATE MSDIALOG oDlg CENTERED
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

PDF Creator - PDF4Free v2.0

Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels
ou caracteres.
Numrico, opcional. Coordenada horizontal em
pixels 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>.
<var> deve ser tipo caracter.

http://www.pdf4free.com

Objeto, opcional. Janela ou controle onde o controle


ser criado.
anWidth
Numrico, opcional. Largura do controle em pixels.
anHeight
Numrico, opcional. Altura do controle em pixels.
Objeto, opcional. Objeto tipo tFont utilizado para
aoFont
definir as caractersticas da fonte utilizada para exibir
o contedo do controle.
Lgico, opcional. Se .T., habilita barra de rolagem
alHScroll
horizontal.
anClrFore Numrico, opcional. Cor de fundo do controle.
anClrBack Numrico, opcional. Cor do texto do controle.
oPar11
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas
alPixel
so em pixels, se .F. so em caracteres.
cPar13
Reservado.
lPar14
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.
lPar16
Reservado.
lPar17
Reservado.
Lgico, opcional. Se .T. o controle so permitira
alReadOnly
leitura.
Bloco de cdigo, opcional. Executado quando o
contedo do controle deve ser validado, deve retornar
abValid
.T. se o contedo for vlido e .F. quando o contedo
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

Parmetro Tipo / Descrio


lEnable Lgico, obrigatrio. Se .T. habilita se .F. desabilita a

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

barra de rolagem.
Retorno

NIL

EnableHScroll
Descrio
Sintaxe

Habilita a barra de rolagem horizontal.


EnableHScroll( lEnable )

Parmetros

Parmetro Tipo / Descrio


Lgico, obrigatrio. Se .T. habilita se .F. desabilita a
lEnable
barra de rolagem.

Retorno

NIL

Exemplo
#include protheus.ch
User Function Teste()
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()
ACTIVATE MSDIALOG oDlg CENTERED
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

PDF Creator - PDF4Free v2.0

Mtodo construtor da classe.

http://www.pdf4free.com

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.
anWidth Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
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
#include protheus.ch
User Function Teste()
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
ACTIVATE MSDIALOG oDlg CENTERED
Return

Descrio
PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels ou
anRow
caracteres.
Numrico, opcional. Coordenada horizontal em pixels
anCol
ou caracteres.
aacItems Array de caracteres, opcional. Lista de opes.
Bloco de cdigo, opcional. Bloco de cdigo no formato
{|u| if( Pcount( )>0, <var>:= u, <var> ) } que o controle
abSetGet
utiliza para atualizar a varivel <var>. <var> deve ser
tipo numrico.
Objeto, opcional. Janela ou controle onde o controle
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.
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. para que o controle permanea habilitado, ou .F. se
no.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

anWidth Numrico, opcional. Largura do controle em pixels.


anHeight Numrico, opcional. Altura do controle em pixels.
Bloco de cdigo, opcional. Executado quando o
abValid contedo do controle deva ser validado, retornando .T.
se o contedo for vlido, e .F. quando invlido.
lPar16
Reservado.
Lpar17 Reservado.
Lgico, opcional. Se .T. as coordenadas informadas so
alPixel
em pixels, se .F. so em caracteres.
Retorno

O objeto criado.

EnableItem
Descrio
Sintaxe

Habilita ou desabilita item.


EnableItem( [nItem], [lEnable])

Parmetro Tipo / Descrio


nItem
Numrico, opcional. Item selecionado.
Parmetros
Lgico, opcional. Se .T. habilita o item se .F. desabilita
lEnable
o item.
Retorno

NIL

Exemplo
#include protheus.ch
User Function Teste()
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.)
@ 40,10 BUTTON oButton PROMPT Fechar OF oDlg PIXEL ACTION oDlg:End()
ACTIVATE MSDIALOG oDlg CENTERED
MsgStop(Escolheu +aOptions[nRadio] )
Return NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

Mtodo construtor da classe.


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

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical em pixels ou
anRow
caracteres.
Numrico, opcional. Coordenada horizontal em pixels
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

anClrBack Numrico, opcional. Cor do fundo do controle.


anWidth Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
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] )

Parmetro Tipo / Descrio


Parmetros
Caracter / Numrico / Data, Opcional. Valor a ser
xVal
exibido.
Retorno

NIL

Exemplo
#include protheus.ch
User Function Teste()
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)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

Descrio
Utilize a classe tScrollbox para criar um painel com scroll deslizantes nas laterais do
controle.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Mtodos

New
Descrio
Sintaxe

Mtodo construtor da classe.


New([aoWnd], [anTop], [anLeft], [anHeight], [anWidth],
[alVertical], [alHorizontal], [alBorder])
Parmetro

Tipo / Descrio
Objeto, opcional. Janela ou controle onde o controle
aoWnd
ser criado.
anTop
Numrico, opcional. Coordenada vertical em pixels.
Numrico, opcional. Coordenada horizontal em
anLeft
pixels.
Numrico, opcional. Altura do controle em pixels.
Parmetros anHeight
anWidth
Numrico, opcional. Largura do controle em pixels.
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
#include protheus.ch
User Function Teste()
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
@ 50,10 MSGET oGet2 VAR cGet2 SIZE 100,10 OF oScr PIXEL
@ 150,100 MSGET oGet3 VAR cGet3 SIZE 100,10 OF oScr PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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] );

Parmetro Tipo / Descrio


Numrico, opcional. Coordenada vertical superior em
nTop
pixels ou caracteres.
Numrico, opcional. Coordenada horizontal esquerda
nLeft
em pixels ou caracteres.
Numrico, opcional. Coordenada vertical inferior em
nBottom
pixels ou caracteres.
Numrico, opcional. Coordenada horizontal inferior em
nRight
pixels ou caracteres.
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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] ).

Parmetro Tipo / Descrio


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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
#INCLUDE "PROTHEUS.CH"
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
PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

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

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

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

http://www.pdf4free.com

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]:nNumMsgNaoLidas
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.
cNome: O respectivo nome da 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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

O mtodo GetSMTPTimeOut() da classe tMailManager


tem como objetivo retornar o tempo em segundos que
est estabelecido com o servidor SMTP para que seja
finalizada a conexo por time-out.

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

O mtodo imapStore() da classe tMailManager tem como


objetivo armazenar uma determinada mensagem em algum
folder do servidor IMAP.

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Antes da utilizao das funes e/ou propriedades da classe


de email necessario criarmos uma instancia da classe
atravs do contrutor New().
Mtodo POPCONNECT

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

A pasta Inbox por exemplo, sempre assinada por default.


Mtodo SETMSGFLAG usado apenas para conexo

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
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.
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
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
Mtodo COPYMSG usado apenas para conexo IMAP.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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)
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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][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

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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]:nNumMsgNaoLidas
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.
cNome: O respectivo nome da 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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Retorno
Tipo
Lgico

Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
finalizada a conexo por time-out.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
qual desejamos transferir a mensagem.

Retorno
Tipo
Lgico

Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
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
determinada mensagem da pasta corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor.
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)
Sintaxe
tMailManager():NEW ( ) --> oObjtMailManager
Retorno
Tipo
Objeto

Descrio
Retorna uma nova instncia do Objeto da Classe tMailManager.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Tipo

Descrio

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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() )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
Finaliza a conexo TCP genrica (socket ) do objeto corrente.

Sintaxe
oObj:CloseConnection ( ) --> Nil
Retorno
Tipo
(NULO)

Descrio
Nil

Descrio
Finaliza a conexo TCP genrica (socket ) do objeto corrente.

Abrangncia
Verso 6.09

Verso 7.10

Verso 8.11

Sintaxe

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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)

PDF Creator - PDF4Free v2.0

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

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

-1 // Job, Web ou Working Thread ( Sem remote )


1 // Remote em ambiente Windows
2 // Remote em ambiente Unix/Linux

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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))

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 .

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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)

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
** 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 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).

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 "PROTHEUS.CH"
#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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
** 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 Server PRotheus com data igual ou superior a
22/04/2002.

Sintaxe
HTTPLOGONUSER ( ) --> cLogonUser
Retorno

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#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() )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.

Descrio
A funo HttpRCtLen() , quando utilizada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-length do Header HTTP , como um dado numrico .
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 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
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-type 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 ("").

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-type 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
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
Esta funo sempre retorna NIL

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

PDF Creator - PDF4Free v2.0

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.

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

(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 ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
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 .
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 ("").

FUNO DE DISCO E ARQUIVO


Sintaxe
ADIR ( [ ] , [ ] , [ ] , [ ] , [ ] , [ ] ) --> nArquivos
Parmetros
Argumento
<cEspecArq>

PDF Creator - PDF4Free v2.0

Tipo
Descrio
Caracter <cEspecArq> a especificaao dos arquivos a serem

http://www.pdf4free.com

<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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

<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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Tipo
Descrio
Caracter Caminho relativo , com o novo diretrio que ser ajustado

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

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

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.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()

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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().

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

// 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
MsgStop('Falha na operao 2 : FError '+str(ferror(),4))
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
MsgStop('Falha na operao 3 : FError '+str(ferror(),4))
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Parmetros
Argumento
nPos

Tipo

Descrio
Indica a posio que ser colocado o ponteiro para leitura
Numrico
dos dados no arquivo.

Retorno
Tipo
(NULO)

Descrio
Esta funo sempre retorna NIL

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
Esta funo sempre retorna NIL

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)

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Descrio

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

// 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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

#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

PDF Creator - PDF4Free v2.0

Tipo

Descrio
Nome do diretrio a ser criado, incluindo opcionalmente o
Caracter
caminho (path).

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
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.
Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
Sintaxe
SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) -->
NIL

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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')

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

DTOC ( < dData > ) --> cData


Parmetros
Argumento
dData

Tipo Descrio
Data <dData> o valor data que ser convertido.

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
Data <dData> o valor data que ser convertido.

Retorno
Tipo

Descrio

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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() )

PDF Creator - PDF4Free v2.0

// Resulta: 10:00:00
// Resulta: 36000.00

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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})

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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,

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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} }

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Tipo
Descrio
Objeto Representa o Node pai do elemento que ser removido.

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
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")

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 += "
<Quantidade>0</Quantidade>"
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
User Function ExeXML()
Local cError
:= ""
Local cWarning := ""
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
Static Function GeraXML()
// Script XML a gerar objeto
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 += "
<Quantidade>0</Quantidade>"

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
User Function getObjXML()
Local cError
:= ""
Local cWarning := ""
Local cXML := ""
Local oXml := NIL
//Gera o Objeto XML
oXml := XmlParser( GeraXML(), "_", @cError, @cWarning )
//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 ) )

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

// Tranforma o Objeto XML em string


SAVE oXml XMLSTRING cXML
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 += "
<Quantidade>0</Quantidade>"
cScript += "
<Preco>0</Preco>"
cScript += "
</Item>"
cScript += " </Itens>"
cScript += "</pedido>"
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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
User Function ExeXML()
Local cError
:= ""
Local cWarning := ""
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.

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 += "
<Quantidade>0</Quantidade>"
cScript += "
<Preco>0</Preco>"
cScript += "
</Item>"
cScript += " </Itens>"
cScript += "</pedido>"
Return cScript

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
User Function getObjXML()

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Local cError
:= ""
Local cWarning := ""
Local cXML := ""
Local oXml := NIL
//Gera o Objeto XML
oXml := XmlParser( GeraXML(), "_", @cError, @cWarning )
//acessando o CONTEUDO do meu nodo ""
oXml:_PEDIDO:_NOME_CLIENTE:Text := "Microsiga"
// Tranforma o Objeto XML em string
//SAVE oXml XMLSTRING cXML
Return oXml
// funo para gerar uma string contendo um xml
Static Function GeraXML()

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "XMLXFUN.CH"
User Function getObjXML()
Local cError
:= ""
Local cWarning := ""
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:
#INCLUDE "PROTHEUS.CH"
// 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)

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

// 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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
Conteudo Funcionalidade
X
Exibe dgitos para qualquer tipo de dado
9
Exibe dgitos para qualquer tipo de dado
#
Exibe dgitos para qualquer tipo de dado
!
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
Conteudo Funcionalidade
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
!
Converte caracteres alfabticos para maisculo

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Templates
Conteudo Funcionalidade
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
!
Converte caracteres alfabticos para maisculo
*
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:
User Function GetAnswer(lDefault)
Return If( GetOk(lDefault), .T., .F.)

Ou melhor:
User Function GetAnswer(lDefault)
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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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"

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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]

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.
Considere o exemplo:
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"

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Verso 5.08

Verso 6.09

Verso 7.10

Verso 8.11

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Verso 5.08

Verso 6.09

Verso 7.10

Verso 8.11

http://www.pdf4free.com

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

Considere o exemplo:
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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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 ) ) )

PDF Creator - PDF4Free v2.0

==>

20

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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
nResultado := 250 * (1 + (nPercentual / 100))

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

Store 10 To nPercentual
nResultado := 250 * (1 + (nPercentual / 100))

ou
Local nPercentual, nResultado
nPercentual := 10
nResultado := 250 * (1 + (nPercentual / 100))

ou
Local nPercentual := 10, nResultado
nResultado := 250 * (1 + (nPercentual / 100))

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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:

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

aFunct2 := {"Maria" , 22, .T.}


aFunct3 := {"Antnio", 42, .F.}

Os nomes podem ser impressos assim:


Alert(aFunct1[FUNCT_NOME])
Alert(aFunct2[FUNCT_NOME])
Alert(aFunct3[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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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.

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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).

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com

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

PDF Creator - PDF4Free v2.0

Verso 5.08

Verso 6.09

Verso 7.10

Verso 8.11

http://www.pdf4free.com

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).

PDF Creator - PDF4Free v2.0

http://www.pdf4free.com