CLASSES VISUAIS TSRCOBJECT Caractersticas

Classe abstrata inicial de todas as classes de interface do Advpl. No deve ser instanciada diretamente.

Propriedades
Propriedade nLeft nTop nWidth nHeight cCaption cTooltip Tipo Numrico. Numrico. Numrico. Numrico. Caractere. Caractere. 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. Executado quando objeto ganha foco.

lShowHint Lgico. cMsg nClrText nClrPane bWhen bValid blClicked Caractere. Numrico. Numrico. Bloco de cdigo. Bloco de cdigo.

Bloco de cdigo. Bloco de brClicked cdigo. Bloco de blDblClick cdigo. oWnd Objeto. lVisible Booleano. Objeto ou Cargo varivel. Bloco de bLostFocus cdigo. bGotFocus Bloco de

cdigo.

Mtodos

SetFocus
Sintaxe SetFocus( ) Descrio Fora o foco de entrada de dados mudar para o objeto. Retorno NIL

Hide
Sintaxe Hide( ) Descrio Torna objeto invisvel. Retorno NIL

Show
Sintaxe Show( ) Descrio Torna objeto visvel. Retorno NIL

Enable
Sintaxe Enable( ) Descrio Habilita o objeto. Retorno NIL

Disable
Sintaxe Disable( ) Descrio Desabilita o objeto. Retorno NIL

Refresh
Sintaxe Refresh( ) Fora atualizao (sincronia) de propriedades entre o programa e o Descrio Protheus Remote.

Caractersticas
MSDialog deve ser utilizada como padro de janela para entrada de dados. MSDialog um tipo de janela dilogo modal, isto , no permite que outra janela ativa receba dados enquanto esta estiver ativa.

Propriedades
Vide classes ancestrais.

Mtodos

New
Descrio Mtodo construtor da classe. New([anTop], [anLeft], [anBottom], [anRight], [acCaption], [cPar6], Sintaxe [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 em anLeft pixels ou caracteres. Numrico, opcional. Coordenada vertical inferior em anBotom pixels ou caracteres. Numrico, opcional. Coordenada horizontal direita em anRight pixels ou caracteres. acCaption Caractere, opcional. Ttulo da janela. cPar6 Reservado. nPar7 Reservado. lPar8 Reservado. Parmetros nPar9 Reservado. anClrText Numrico,opcional. Cor do texto. anClrBack Numrico,opcional. Cor de fundo. oPar12 Reservado. Objeto, opcional. Janela me da janela a ser criada, aoWnd padro a janela principal do programa. Lgico, opcional. Se .T. considera as coordenadas alPixel passadas em pixels, se .F. considera caracteres. oPar15 Reservado. oPar16 Reservado. nPar17 Reservado.

Retorno

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

Descrio
Utilize a classe tButton para criar um controle visual do tipo boto.

Propriedades
Nome Tipo / Descrio lProcessing Lgico. Se .T. indica o boto est efetuando uma ao. bAction Bloco de cdigo. Executado quando o boto pressionado.

Mtodos

New
Descrio Mtodo construtor da classe. New([anRow], [anCol], [acCaption], [aoWnd], [abAction], Sintaxe [anWidth], [anHeight], [nPar8], [aoFont], [lPar10], [alPixel],[lPar12], [cPar13], [lPar14], [abWhen], [bPar16], [lPar17]) Parmetros Parmetro Tipo / Descrio Numrico, opcional. Coordenada vertical em pixels ou anRow carateres. Numrico, opcional. Coordenada horizontal em pixels ou anCol caracteres. acCaption Caractere, opcional. Titulo do boto. Objeto, opcional. Janela ou controle onde o boto dever aoWnd 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 aoFont lPar10 alPixel lPar12 cPar13 lPar14 abWhen bPar16 lPar17

Reservado. Objeto, opcional. Objeto tipo tFont com propriedades da fonte utilizada para o ttulo do boto. Reservado. Lgico, opcional. Se .T. considera as coordenadas passadas em pixels, se .F. (padro) considera em caracteres. Reservado. Reservado. Reservado. Bloco de cdigo, opcional. Executado quando mudana de foco de entrada de dados est sendo efetuada na janela onde o controle foi criado. O bloco deve retornar .T. se o controle deve permanecer habilitado ou .F. se no. Reservado. Reservado.

Exemplo
#include protheus.ch User Function TesteGet() Local oDlg, oButton, oCombo, cCombo, aItems:= {item1,item2,item3} cCombo:= aItems[2] DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE Meu Combo oCombo:= tComboBox():New(10,10,{|u|if(PCount()>0,cCombo:=u,cCombo)},; aItems,100,20,oDlg,,{||MsgStop(Mudou item)},,,,.T.,,,,,,,,,cCombo) // Boto para fechar a janela oButton:=tButton():New(30,10,fechar,oDlg,{|| oDlg:End()},100,20,,,,.T.) ACTIVATE MSDIALOG oDlg CENTERED MsgStop( O valor +cCombo ) Return NIL

Descrio

Utilize a classe tCheckbox quando desejar criar um controle que possua dois estados .T. ou .F..

Mtodos

New
Descrio Mtodo construtor da classe. New([anRow], [anCol], [acCaption], [abSetGet], [aoWnd], [anWidth], [anHeight], [nPar8], [abClick], [aoFont], [abValid], Sintaxe [anClrFore], [anClrBack], [lPar14], [alPixel], [cPar16], [lPar17], [abWhen]) Parmetros 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 {|u| if( Pcount( )>0, <var>:= u, <var> ) } que o controle abSetGet utiliza para atualizar a varivel <var>. <var> deve ser tipo lgico, se <var> = .T. ento o controle aparecer checado. Objeto, opcional. Janela ou controle onde o controle aoWnd dever ser criado. anWidth Numrico, opcional. Largura do controle em pixels. anHeight Numrico, opcional. Altura do controle em pixels. nPar8 Reservado. Bloco de cdigo, opcional. Executado quando o controle abClick click do boto esquerdo do mouse acionado sobre o controle. Objeto, opcional. Objeto tipo tFont com propriedades da aoFont fonte utilizada para o texto do controle. Bloco de cdigo, opcional. Executado quando o contedo do controle deve ser validado, deve retornar .T. abValid 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 so alPixel em pixels, se .F. so em caracteres. cPar16 Reservado. lPar17 Reservado. abWhen Bloco de cdigo, opcional. Executado quando mudana

Retorno

de foco de entrada de dados est sendo efetuada na janela onde o controle foi criado. O bloco deve retornar .T. se o controle deve permanecer habilitado ou .F. se no. 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

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 formatos: aItems 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 Mtodo construtor da classe. New([anRow], [anCol], [abSetGet], [anItems], [anWidth], [anHeight], [aoWnd], [nPar8], [abChange], [abValid], [anClrText], Sintaxe [anClrBack], [alPixel], [aoFont], [cPar15], [lPar16], [abWhen], [lPar18], [aPar19], [bPar20], [cPar21], [acReadVar]) Parmetros 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>. <var> deve ser abSetGet 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) Seqencial, anItems exemplo: {item1,item2,...,itemN} ou b) Indexada, exemplo: {a=item1,b=item2, ..., n=itemN}. anWidth Numrico, opcional. Largura do controle em pixels. anHeight 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 controle abChange 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 so alPixel em pixels, se .F. so em caracteres. Objeto, opcional. Objeto tipo tFont utilizado para definir aoFont as caractersticas da fonte utilizada para exibir o contedo do controle. cPar15 Reservado. lPar16 Reservado. abWhen Bloco de cdigo, opcional. Executado quando mudana de foco de entrada de dados est sendo efetuada na

Retorno

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( ). O objeto criado.

Select
Descrio Sintaxe Muda o item selecionado no combobox. Select( [anItem] ) Parmetro Tipo / Descrio Parmetros anItem Numrico, opcional. Posio do item a ser selecionado. Retorno NIL

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 objeto Align 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. hParent Numrico. Handle (identificador) do objeto sobre o qual o controle foi criado. Bloco de cdigo. Executado quando o estado ou contedo do controle bChange modificado pela ao sobre o controle.

Mtodos

SetFocus
Descrio Fora mudana do foco de entrada de dados para o controle. Sintaxe SetFocus( ) REtorno NIL

Descrio
Utilize objeto tFont para modificar a fonte padro de controles visuais.

Propriedades
Vide classes ancestrais.

Mtodos

New
Descrio Mtodo construtor da classe. New([acName], [nPar2], [anHeight], [lPar4], [alBold], [nPar6], Sintaxe [lPar7], [nPar8], [alItalic], [alUnderline]) Parmetro Tipo / Descrio acName Caractere, opcional. Nome da fonte, o padro Arial. nPar2 Reservado. anHeight Numrico, opcional. Tamanho da fonte. O padro -11. lPar4 Reservado. alBold Lgico, opcional. Se .T. o estilo da fonte ser negrito. Reservado. Parmetros nPar6 lPar7 Reservado. nPar8 Reservado. alItalic Lgico, opcional. Se .T. o estilo da fonte ser itlico. Lgico, opcional. Se .T. o estilo da fonte ser alUnderline sublinhado.

Retorno

O objeto criado.

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

New
Descrio Mtodo construtor do controle. New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth], [anHeight], [acPict], [abValid], [anClrFore], [anClrBack], [aoFont], [lPar12], Sintaxe [oPar13], [alPixel], [cPar15], [lPar16], [abWhen], [lPar18], [lPar19], [abChange], [alReadOnly], [alPassword], [cPar23], [acReadVar], [cPar25], [lPar26], [nPar27], [lPar28]) Parmetros 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 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 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. Objeto, opcional. Objeto tipo tFont utilizado para aoFont definir as caractersticas da fonte utilizada para exibir o contedo do controle.

Retorno

Reservado. Reservado. Lgico, opcional. Se .T. as coordenadas informadas so alPixel 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 efetuada na abWhen 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. Bloco de cdigo, opcional. Executado quando o abChange 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. O controle construdo.

lPar12 oPar13

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

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 Mtodo construtor da classe. New([anTop], [anLeft], [anBottom], [anRight], [acCaption], Sintaxe [aoWnd], [anClrText], [anClrPane], [alPixel], [lPar10]) Parmetro Tipo / Descrio Numrico, opcional. Coordenada vertical superior em anTop pixels ou caracteres. Numrico, opcional. Coordenada horizontal esquerda em anLeft 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 ser aoWnd 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.) @ 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 Mtodo construtor da classe. New([anRow], [anCol], [abSetGet], [aaItems], [anWidth], [anHeigth], [abChange], [aoWnd], [abValid], [anClrFore], Sintaxe [anClrBack], [alPixel], [lPar13], [abLDBLClick], [aoFont], [cPar16], [lPar17], [abWhen], [aPar19], [bPar20], [lPar21], [lPar22], [abRightClick] ) Parmetros Parmetro Tipo / Descrio Numrico, opcional. Coordenada vertical em pixels anRow ou caracteres. Numrico, opcional. Coordenada horizontal em anCol pixels ou caracteres. abSetGet Bloco de cdigo, opcional. Bloco de cdigo no

Retorno

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 aaItems selecionveis. anWidth Numrico, opcional. Largura do controle em pixels. anHeight Numrico, opcional. Altura do controle em pixels. Bloco de cdigo, opcional. Executado quando o item abChange selecionado alterado. Objeto, opcional. Janela ou controle onde o controle aoWnd 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. O objeto criado.

Select
Descrio Fora a seleo de um item. Sintaxe Select( [anItem] ) Parmetros Parmetro Tipo / Descrio

Retorno

nItem NIL

Numrico, opcional. Posio do item a ser selecionado.

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

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 nTotal lPercentage nClrBar Tipo / Descrio Numrico. Nmero total de passos at o preenchimento da rgua de processo. Lgico. Se .T. considera o passo de movimentao em porcentagem. Numrico. Cor da barra de andamento.

Mtodos

New
Descrio Mtodo construtor da classe. New([anRow], [anCol], [abSetGet], [anTotal], [aoWnd], [anWidth], Sintaxe [anHeight], [lPar8], [alPixel], [oPar10], [cPar11], [alNoPerc], [anClrPane], [nPar14], [anClrBar], [nPar16], [lPar17]) Parmetros Parmetro Tipo / Descrio

Retorno

Numrico, opcional. Coordenada vertical em pixels ou caracteres. Numrico, opcional. Coordenada horizontal em pixels ou anCol 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 sera aoWnd criado. anWidth Numrico, opcional. Largura do controle em pixels. 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. O objeto criado. anRow

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 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 Mtodo construtor da classe. New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth], [anHeight], [aoFont], [alHScroll], [anClrFore], [anClrBack], [oPar11], [alPixel], Sintaxe [cPar13], [lPar14], [abWhen], [lPar16], [lPar17], [alReadOnly], [abValid], [bPar20], [lPar21], [alNoBorder], [alNoVScroll]) Parmetros 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 abSetGet o controle utiliza para atualizar a varivel <var>. <var> deve ser tipo caracter. 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. 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.

Retorno

alReadOnly Lgico, opcional. Se .T. o controle so permitira leitura. 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. bPar20 Reservado. lPar21 Reservado. alNoBorder Lgico, opcional. Se .T. cria controle sem borda. Lgico, opcional. Se .T., habilita barra de rolagem alNoVScroll vertical. O objeto criado.

EnableVScroll
Descrio Sintaxe Habilita a barra de rolagem vertical. EnableVScroll( lEnable ) Parmetro Tipo / Descrio Parmetros Lgico, obrigatrio. Se .T. habilita se .F. desabilita a lEnable barra de rolagem. Retorno NIL

EnableHScroll
Descrio Sintaxe Habilita a barra de rolagem horizontal. EnableHScroll( lEnable ) Parmetro Tipo / Descrio Parmetros 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 Mtodo construtor da classe. New([anRow], [anCol], [acText], [aoWnd], [aoFont], [alCentered], Sintaxe [lPar6], [anClrText], [anClrBack], [anWidth], [anHeight], [alLowered], [alRaised]) Parmetro Tipo / Descrio anRow Numrico, opcional. Coordenada vertical em pixels. anCol Numrico, opcional. Coordenada horizontal em pixels. acText 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 centro alCentered do controle. Parmetros lPar6 Reservado. 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
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 Mtodo construtor da classe. New([anRow], [anCol], [aacItems], [abSetGet], [aoWnd], [aPar6], Sintaxe [abChange], [anClrText], [anClrPan], [cPar10], [lPar11], [abWhen], [anWidth], [anHeight], [abValid], [lPar16], [lPar17], [alPixel]) Parmetros Parmetro Tipo / Descrio Numrico, opcional. Coordenada vertical em pixels ou anRow caracteres. Numrico, opcional. Coordenada horizontal em pixels ou anCol 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 ser aoWnd criado.

Retorno

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 janela abWhen onde o controle foi criado. O bloco deve retornar .T. para que o controle permanea habilitado, ou .F. se no. anWidth Numrico, opcional. Largura do controle em pixels. anHeight Numrico, opcional. Altura do controle em pixels. Bloco de cdigo, opcional. Executado quando o contedo abValid 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. O objeto criado.

aPar6

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

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 Mtodo construtor da classe. New([anRow], [anCol], [abText], [aoWnd], [acPicture], [aoFont], [lPar7], [lPar8], [lPar9], [alPixels], [anClrText], [anClrBack], Sintaxe [anWidth], [anHeight], [lPar15], [lPar16], [lPar17], [lPar18], [lPar19]) Parmetros 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 ser aoWnd criado. Caractere, opcional. Picture de formatao do contedo a acPicture ser exibido. Objeto, opcional. Objeto tipo tFont para configurao do aoFont tipo de fonte que ser utilizado para exibir o contedo. lPar7 Reservado. lPar8 Reservado.

Retorno

Reservado. Lgico, opcional. Se .T. considera coordenadas passadas alPixels em pixels se .F., padro, considera as coordenadas passadas em caracteres. anClrText Numrico, opcional. Cor do contedo do controle. anClrBack Numrico, opcional. Cor do fundo do controle. 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. O objeto criado.

lPar9

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.

Mtodos

New
Descrio Mtodo construtor da classe. New([aoWnd], [anTop], [anLeft], [anHeight], [anWidth], Sintaxe [alVertical], [alHorizontal], [alBorder]) Parmetro Tipo / Descrio Objeto, opcional. Janela ou controle onde o controle aoWnd ser criado. anTop Numrico, opcional. Coordenada vertical em pixels. anLeft Numrico, opcional. Coordenada horizontal em pixels. anHeight Numrico, opcional. Altura do controle em pixels. Parmetros 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

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 Mtodo construtor da janela. New( [anTop], [anLeft],[anBottom], [anRight], [acTitle], [nPar6], [oPar7] ,[oPar8],[oPar9], [aoParent], [lPar11], [lPar12], [anClrFore], Sintaxe [anClrBack], [oPar15], [cPar16], [lPar17], [lPar18], [lPar19], [lPar20], [alPixel] ); Parmetros Parmetro Tipo / Descrio Numrico, opcional. Coordenada vertical superior em nTop pixels ou caracteres. Numrico, opcional. Coordenada horizontal esquerda em nLeft pixels ou caracteres. Numrico, opcional. Coordenada vertical inferior em nBottom pixels ou caracteres. Numrico, opcional. Coordenada horizontal inferior em nRight pixels ou caracteres. cTitle Caractere, opcional. Ttulo da janela. nPar6 Reservado. oPar7 Reservado. oPar8 Reservado. oPar9 Reservado. oParent Objeto, opcional. Janela me da janela corrente. lPar11 Reservado. lPar12 Reservado. nClrFore Numrico, opcional. Cor de fundo da janela. nClrText Numrico, opcional. Cor do texto da janela. oPar15 Reservado.

Retorno

Reservado. Reservado. Reservado. Reservado. Reservado. Lgico, opcional. Se .T. (padro) considera coordenadas lPixel passadas em pixels, se .F. considera caracteres. Objeto. A janela construda.

cPar16 lPar17 lPar18 lPar19 lPar20

Activate
Descrio Ativa (exibe) a janela. Chamar esse mtodo apenas uma vez. Activate([acShow], [bPar2], [bPar3], [bPar4], [bPar5], [bPar6], Sintaxe [ 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 da abValid janela for vlido, ou .F. se no. Se o bloco retornar .F. a janela no fechar. bPar17 Reservado. bPar18 Reservado. Retorno NIL

End
Descrio Solicita encerramento da janela. Sintaxe End( ) Retorno Lgico. .T. se encerrou a janela e .F. se no.

Center
Descrio Centraliza a janela. Sintaxe Center( ) Retorno NIL

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

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

COPYMSG

Para se criar uma pasta no diretrio root do servidor IMAP basta apenas passar o nome da pasta que desejamos, sem path algum de um device. Para se criar uma subpasta, devemos informar a hierarquia de pastas e o nome da pasta. Para se criar uma subpasta de Inbox, basta chamar a funo create folder informando 'Inbox\Teste' e assim por diante. Mtodo DELETEFOLDER usado apenas para conexo IMAP.

DELETEFOLDER

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 O mtodo DeleteMsg() da classe tMailManager tem como

DELETEMSG

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 O mtodo GetErrorString da classe TMailManager, tem como objetivo retornar um erro em forma de string, trazendo sua descrio de acordo com algum erro que tenha ocorrido durante alguma outra funo da classe com SendMail(), algum connect e assim por diante. O valor informado por parametro representa erros definidos por padro do protocolo de conexo SMTP. Mtodo GETFOLDER usado apenas para conexo IMAP. 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.

GETERRORSTRING

GETFOLDER

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. O mtodo GetMsgBody() da classe de tMailManager tem como objetivo obter o conteudo da mensagem indicada de acordo com o parametro que representa o numero da mensagem para a funo. O valor informado por parametro o numero da mensagem na pasta do servidor. O mtodo ir procurar pela mensagem no folder que estiver posicionado no server IMAP. Mtodo GETMSGHEADER usado apenas para conexo IMAP. O mtodo GetMsgHeader() da classe tMailManager tem como objetivo se comunicar com o server de email IMAP e obter o cabealho da mensagem requerida de acordo com o parametro informando. 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.

GETMSGBODY

GETMSGHEADER

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

GETPOPTIMEOUT

GETSMTPTIMEOUT

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

IMAPCONNECT

IMAP. O mtodo IMAPConnect() da classe TMailManager tem como objetivo realizar a conexo em um IMAP e-mail server e sincroniza o mailbox folders. A conexo atravs de IMAP trata-se de um mtodo de acesso a mensagens eletrnicas armazenadas em um servidor local ou remoto. O mtodo ir se conectar de acordo com os dados informados atravs do mtodo init(). Obs.:Uma caracterstica importante do IMAP permitir que a manipulao de mensagens e pastas seja feita como se estivessem no computador local. Sempre que for estabelecida uma conexo com servidor IMAP atravs da funo imapConnect() importante finalizar a conexo utilizando a imapDisconnect(). 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. 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. 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

IMAPDISCONNECT

IMAPSTORE

INIT

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

MOVEMSG

Antes da utilizao das funes e/ou propriedades da classe de email necessario criarmos uma instancia da classe atravs do contrutor New(). Mtodo POPCONNECT O mtodo PopConnect() da classe TmailManager se conecta com o servidor de email, atravs dos parametros que foram informados atravs do mtodo INIT(). Com esse mtodo realizamos a conexo no servidor POP, ou seja, apenas realizaremos o recebimento das mensagens existentes na caixa postal do usuario informado. Mtodo POPDISCONNECT 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

POPCONNECT

POPDISCONNECT

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

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. 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. Mtodo SETMSGFLAG usado apenas para conexo IMAP. A funo SetMsgFlag() da classe tMailManager tem como objetivo indicar o status para uma determinada mensagem indicada de acordo com o parametro informado para a funo. Os estados possiveis para setar na mensagem so: A = ANSWERED, F = FLAGGED, D = DELETED, S = SEEN, R =
DRAFT, C = RECENT, P = SPECIAL

SENDMAIL

SETFOLDERSUBSCRIBE

SETMSGFLAG

SETPOPTIMEOUT

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. Mtodo 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 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 O mtodo SMTPDisconnect() da classe TMailManager ir realizar o fim da conexo com o servidor SMTP, se desconectando apenas com o servidor SMTP. Ao solicitar a finalizao da conexo com o servidor SMTP, a funo ir retornar o status da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso contrrio. Mtodo SETUSEREALID usado apenas para conexo IMAP. A funo SetUseRealID() da classe tMailManager tem como objetivo definir qual id ser usado para busca das mensagens. Uma mensagem de email possui dois modos de se identificada no servidor IMAP: -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

SETSMTPTIMEOUT

SMTPCONNECT

SMTPDISCONNECT

SETUSEREALID

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 todos os cabealhos(headers) de todas as mensagens de uma determinada pasta.

STARTGETALLMSGHEADER

A funo ir avisar ao servidor IMAP que um processo de obteno das mensagens vai ocorrer, definindo qual a pasta(folder) deve se iniciar o processo e qual as infomao no header da mensagem deve ser retornada. obs.: a funo apenas inicia o processo, para pegar os cabealhos das mensagens da pasta use a funo EndGetAllMsgHeader().

Este exemplo tem como objetivo principal documentar a classe tMailManager, com foco nas funoes que so usadas apenas por conexo IMAP. Este exemplo ir fazer basicamente manipulao dos folders de uma conta de email, atravs de uma conexo com o servidor IMAP. Ex: imap.microsiga.com.br
#include "Protheus.ch" STATIC oMailManager := Nil User Function tstIMAP()

Local aStPastas := {} Local sFolder := "TSTIMAP" Local 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 TSTIMAP //pego os folders(pastas) existentes no servidor, incluido o GetFolderList( @aStPastas ) varinfo("PASTAS", aStPastas) //Verificamos o folder corrente em uso GetFolder( @sFolder ) conout("Folder Corrente" + sFolder)

If !oMailManager:DeleteFolder( ConvFdlName( sFolder, .F. ) ) conout("nao foi possivel deletar a pasta" + sFolder) Return .F. EndIf myDisconnect() return .T. function myConnect( sSrvIMAP, sSrvSMTP, sLogin, sPass, sErro ) Local nErro := 0 //obtenho uma nova instancia da classe de email. oMailManager := TMailManager():New() //uso a funo init para setar os dados. If (nErro := oMailManager:Init( sSrvIMAP, sSrvSMTP, sLogin, sPass )) != 0 sErro := oMailManager:GetErrorString( nErro ) Conout( sErro ) Return .F. EndIf //realizo uma CONEXAO IMAP If (nErro := oMailManager:IMAPConnect()) != 0 sErro := oMailManager:GetErrorString( nErro ) Conout( sErro ) Return .F. EndIf //informo o server que iremos trabalhar com ID real da mensagem oMailManager:SetUseRealID( .T. ) Return .T.

function myDisconnect() oMailManager:IMAPDisconnect() Return .T. function GetFolderList( aStPastas ) Local nI := 0, nTam := 0 Local aTemp := {} Local aFolder aTemp := oMailManager:GetFolderList() nTam := Len( aTemp ) For nI := 1 To nTam //crio um array temp {nome, nTotalMensagens, nMensagensNaoLidas, lAssinada} aFolder := {} aAdd(aFolder, ConvFdlName( aTemp[ nI ][1], .T. )) aAdd(aFolder, aTemp[ nI ][3]) aAdd(aFolder, aTemp[ nI ][5]) aAdd(aFolder, .T.) //adiciono no array de referencia do parametro aAdd( aStPastas, aFolder ) aFolder := NIL

Next Return .T.

// Retorna a pasta que esta em uso, sFolder referencia function GetFolder( sFolder ) sFolder := ConvFdlName( oMailManager:GetFolder(), .F. ) Return .T. Function CreateFolder( sFolder ) sFolder := ConvFdlName( sFolder, .F. ) //tento criar o folder no server IMAP If ! oMailManager:CreateFolder( sFolder ) Return .F. EndIf //set o folder como assinado, para aparecer If ! oMailManager:SetFolderSubscribe( sFolder, .T. ) Return .F. EndIf Return .T.

Sintaxe oObj:CHANGEFOLDER ( < sFolder > ) --> lRet

Parmetros Argumento sFolder Retorno Tipo Lgico 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. Descrio Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP, false caso contrario. Tipo Descrio Representa o nome da pasta na qual desejamos nos Caracter mudar(conectar) no servidor IMAP.

oObj:COPYMSG ( < nMsg > , < sFolder > ) --> lRet Parmetros Argumento nMsg sFolder Retorno Tipo Lgico 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(). Descrio Retorna true caso tenha sido possivel encontrar a mensagem requirida e Copiar para a pasta informada, false caso contrrio. 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 qual Caracter desejamos transferir a mensagem.

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 Retorno Tipo Lgico 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) Sintaxe oObj:DELETEFOLDER ( < cFolder > ) --> lRet Parmetros Argumento cFolder Tipo Descrio Representa o nome da pasta na qual desejamos deletar no Caracter servidor IMAP. Descrio Retorna true caso tenha sido possivel encontrar a mensagem requirida e Copiar para a pasta informada, false caso contrrio. 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 qual Caracter desejamos transferir a mensagem.

Retorno Tipo Lgico 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 Retorno Tipo (NULO) 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 aHeaders Tipo Descrio Array Array usado como referncia para o retorno dos headers das Descrio Retorna true, caso tenha sido possivel deletar a mensagem. Caso contrrio retorna false. Tipo Descrio Numrico Numero da mensagem a ser deletada. Descrio Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP, false caso contrario.

mensagens. Retorno Tipo Lgico 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. Descrio Retorna true quando o servidor IMAP terminou de mandar todos os headers das mensagens, false caso contrrio.

Sintaxe oObj:GETALLFOLDERLIST ( ) --> aRet Retorno Tipo 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 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.

: :

: :

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 Retorno Tipo Caracter 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 Descrio Retorna uma string contendo o nome do folder em uso pela aplicao. Descrio Retorna uma cadeia de caracteres com a descrio, de acordo com o valor do erro passado. Tipo Descrio Representa um valor numrico a ser passado de algum erro Numrico de acordo como SMTP.

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 Mtodo GETFOLDERLIST usado apenas para conexo IMAP. O mtodo GetFolderList() da classe TMailManager, tem como objetivo obter todas as pastas de determinada conta de email, que esto no servidor email IMAP. O mtodo retorna todas as pastas assinadas(so as pastas abilitadas ou Subscribe), esse retorno vem em forma de array, do seguinte modo: array[1] array[1][1]:cNome array[1][1]:nNumMsgNaoLidas array[1][1]:nNumMsg array[1][1]:cStatus : : 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.

: :

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 Descrio

(NULO) Descrio

Retorno nulo.

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 Retorno Tipo Lgico 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. Descrio Retorna true caso tenha sido possivel encontrar a mensagem requirida e retornar seu cabealho, false caso contrrio. Tipo Descrio Numrico Valor numerico da mensagem no servidor de email IMAP.

Sintaxe

oObj:GETNUMMSGS ( < nNumMsg > ) --> nRet Parmetros Argumento nNumMsg Retorno Tipo Numrico Descrio Mtodo GETNUMMSGS O mtodo GetNumMsgs() da classe TMailManager tem como objetivo retornar o numero de mensagens que existem no servidor. Devemos informar um numrico no parametro da funo como referncia, indicando o total de mensagens aps a execuo da funo, o valor retornado pela funo apenas o status de funcionou ou no. Obs.: A funo retorna o numero de mensagens total da conta de usurio informada e nao apenas por pasta como inbox, sent itens, etc.. Descrio 0 = Lista recebida com sucesso Tipo Descrio Parametro passado por referencia, retorna nele o numero de Numrico mensagens que esto no servidor.

Sintaxe oObj:GETPOPTIMEOUT ( ) --> nRet Retorno Tipo Numrico 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). Descrio Retorna o tempo em segundos para a finalizao por time out da conexao POP.

Sintaxe oObj:GETSMTPTIMEOUT ( ) --> nRet Retorno Tipo Numrico 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. Obs.: caso nao tenha sido estabelecido nenhum tempo de time-out pela funo SETSMTPTIMEOUT, ser retornado 0(zero). Descrio Retorna um tempo em segundos, que representa o tempo para a finalizao da conexo com o servidor SMTP.

Sintaxe oObj:GETUSER ( ) --> sRet Retorno Tipo Caracter 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 @. Descrio Retorna uma String contento o nome do usuario da conta de email que estamos conectados.

Sintaxe oObj:IMAPCONNECT ( ) --> lRet

Retorno Tipo Lgico Descrio Mtodo IMAPCONNECT usado apenas para conexo IMAP. O mtodo IMAPConnect() da classe TMailManager tem como objetivo realizar a conexo em um IMAP e-mail server e sincroniza o mailbox folders. A conexo atravs de IMAP trata-se de um mtodo de acesso a mensagens eletrnicas armazenadas em um servidor local ou remoto. O mtodo ir se conectar de acordo com os dados informados atravs do mtodo init(). Obs.:Uma caracterstica importante do IMAP permitir que a manipulao de mensagens e pastas seja feita como se estivessem no computador local. Sempre que for estabelecida uma conexo com servidor IMAP atravs da funo imapConnect() importante finalizar a conexo utilizando a imapDisconnect(). Descrio Retorna true caso tenha sido possvel realizar a conexo no servidor Imap, false caso contrrio.

Sintaxe oObj:IMAPDISCONNECT ( ) --> lRet Retorno Tipo Lgico 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. Descrio Retorna true caso tenha sido possvel realizar a finalizao da conexo no servidor Imap, false caso contrrio.

Sintaxe oObj:IMAPSTORE ( < cFolder > , < oMsg > ) --> nRet

Parmetros Argumento cFolder oMsg Retorno Tipo Numrico 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 Retorno Tipo (NULO) Descrio Descrio Retorno nulo. Tipo Caracter Caracter Caracter Caracter Numrico Numrico Descrio Endereo do servidor POP ou IMAP, no caso de conexo SMTP passe esse como ""(branco). Endereo do servidor SMTP, no caso de conexo POP passe esse como ""(branco) Login no servidor. Senha no servidor. Time out para a conexo. Porta para se conectar. Descrio Retorna um inteiro informando o status da operao, caso retornado 1 ocorreu erro durante a funo, caso contrario retorna outros valores de informao. Tipo Descrio Representa uma String que contm o nome da pasta(folder) Caracter no qual desejamos armazenar a mensagem. Indica um objeto tMailMessage que contem as informaoes Objeto da mensagem que desejamos armazenar.

Mtodo INIT Atravs desse mtodo da classe tMailManager, iniciamos uma nova conexo com um servidor de emails POP ou SMTP. Quando informamos por argumento o servidor pop (Ex.: pop3.microsiga.com.br) que siginifica o protocolo usado na internet para a recebimento de mensagens ao usurio final e o servidor smtp (Ex.: smtp.microsiga.com.br) que siginifica o protocolo usado na internet para a envio de mensagens ao usurio final, devemos tambm informar um usuario que esteja devidamente cadastrado no servidor e sua senha. Podemos ainda informar o tempo de timeout para queda da conexo e ainda o numero de porta, caso a porta do servidor desejado no seja a default de um smtp Sintaxe oObj:MOVEMSG ( < nNumMsg > , < sFolder > ) --> lRet Parmetros Argumento nNumMsg sFolder Retorno Tipo Lgico 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) Descrio Retorna true caso tenha sido possivel encontrar a mensagem requirida e mover para a pasta informada, false caso contrrio. Tipo Descrio Numrico Valor numerico da mensagem no servidor de email IMAP. Indica o nome da pasta no servidor de email IMAP, no qual Caracter desejamos transferir a mensagem.

Sintaxe tMailManager():NEW ( ) --> oObjtMailManager Retorno Tipo Objeto 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(). Descrio Retorna uma nova instncia do Objeto da Classe tMailManager.

Sintaxe oObj:POPCONNECT ( ) --> NIL Retorno Tipo (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 Descrio Retorna 0 quando for Disconectado, outro valor caso contrrio. Descrio Retorno nulo.

Mtodo POPDISCONNECT O mtodo POPDisconnect() da classe TMailManager ir realizar o fim da conexo com o servidor POP, se desconectando apenas com o servidor POP. Ao solicitar a finalizao da conexo com o servidor POP, a funo ir retornar o status da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso contrrio. Sintaxe oObj:PURGE ( ) --> NIL Retorno Tipo (NULO) Descrio Mtodo PURGE usado apenas para conexo IMAP O metodo purge() da classe tMailManager Descrio Retorno nulo.

Sintaxe oObj:RENAMEFOLDER ( < sOldFolder > , < sNewFolder > ) --> lRet Parmetros Argumento sOldFolder sNewFolder Retorno Tipo (NULO) Descrio Mtodo RENAMEFOLDER usado apenas para conexo IMAP. Descrio Retorna true caso tenha sido possvel realizar a mudana de nome das pastas, false caso contrrio. 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. Caracter Indica o novo nome no qual desejamos atribuir para a pasta.

A funo RenameFolder() da classe tMailManger tem como objetivo realizar a mudana entre os nomes da pastas no servidor de e-mails IMAP. Sintaxe oObj:SENDMAIL ( < sFrom > , < sTo > , < sSubject > , < sBody > , [ sCC ] , [ cBCC ] , [ aAttach ] , [ nNumAttach ] ) --> nRet Parmetros Argumento sFrom sTo sSubject sBody sCC cBCC aAttach Tipo Caracter Caracter Caracter Caracter Caracter Caracter Array Descrio Indica uma conta de email no qual ser usada para representar de quem foi mandado o email. Ex: Deusuario@microsiga.com.br Indica a conta de email no qual ser usada para enviar o respectivo email. Ex: Parausuario@microsiga.com.br Representa o assunto do email ou mensagem, que ser enviado para a conta de email indicada. Representa o conteudo da mensagem que ser enviada. Opcional. Parametro para adicionar endereos ao qual ser enviado na seo Com Cpia(CC). Opicional. Parametro para adicionar endereos de email no qual ser enviado na seo Com Cpia Oculta(BCC) Opcional. Parametro no qual podemos informar um 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 quandidade de arquivos que sero atachados no email, no caso a quantidade de elementos do array.

nNumAttach

Numrico

Retorno Tipo (NULO) 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 Descrio Retrona 0, quando o E-mail for enviado com sucesso, outro valor qualquer caso contrario.

Sintaxe oObj:SETFOLDERSUBSCRIBE ( < cFolder > , < lAssinado > ) --> lRet Parmetros Argumento cFolder lAssinado Retorno Tipo Lgico 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. Descrio Retorna true caso a operao tenha sido realizada com sucesso, falso caso contrrio. 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 assinado(subscribe), Lgico falso caso contrrio.

Sintaxe oObj:SETMSGFLAG ( < nNumMsg > , < sFlag > ) --> lRet Parmetros Argumento nNumMsg sFlag Retorno Tipo Lgico Descrio Retorna true caso a mensagem tenha sido setada corretamente, caso contrrio false. Tipo Descrio Indica o numero da mensagem que desejamos alterar seu Array status(flag). Array Informa o novo status que desejamos para a mensagem.

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

Sintaxe oObj:SETPOPTIMEOUT ( < nTimeOut > ) --> nRet Parmetros Argumento nTimeOut Retorno Tipo Numrico 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. Descrio 0 = Time out setado Tipo Descrio Numrico Tempo para que a conexo seja fechada por Time-Out.

Sintaxe oObj:SETSMTPTIMEOUT ( < nTime > ) --> nRet Parmetros Argumento nTime Tipo Descrio Numrico Tempo para que a conexo seja fechada por Time-Out.

Retorno Tipo Numrico 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. Descrio 0 - Time out configurado

Sintaxe oObj:SETUSEREALID ( < lOpt > ) --> NIL Parmetros Argumento lOpt Retorno Tipo (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. Descrio Retorno nulo. 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.

Sintaxe oObj:SMTPCONNECT ( ) --> nRet Retorno Tipo Numrico 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(). Descrio 0 - Conectado

Sintaxe oObj:SMTPDISCONNECT ( ) --> nRet Retorno Tipo (NULO) 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 Descrio 0 = Disconectado

Argumento sFOlder aHeader Retorno Tipo Lgico Descrio

Tipo

Descrio Indica qual o folder no servidor que desejamos obter os Caracter cabealhos das mensagens. Array que representa as informaoes que desejamos serem Array retornadas nos cabealhos das mensagens.

Descrio Retorna true caso tenha sido possivel iniciar o processo de obteno de cabealho das mensagens, false caso contrario.

Mtodo STARTGETALLMSGHEADER usado apenas para conexo IMAP. A funo StartGetAllMsgHeader() da classe tMailManager tem como objetivo dar inicio ao processo de obteno de todos os cabealhos(headers) de todas as mensagens de uma determinada pasta. A funo ir avisar ao servidor IMAP que um processo de obteno das mensagens vai ocorrer, definindo qual a pasta(folder) deve se iniciar o processo e qual as infomao no header da mensagem deve ser retornada. obs.: a funo apenas inicia o processo, para pegar os cabealhos das mensagens da pasta use a funo EndGetAllMsgHeader().

Tmailmessage
Este exemplo tem como objetivo principal mostrar o uso dos mtodos da classe tMailMessage. Para isto usamos a classe tMailManager(responsavel por estabelecer a conexo de fato). A classe tMailMessage possu uma dependencia direta com a classe tMailManager, devemos imaginar a classe tMailMessage como a mensagem que ser enviada de fato e tendo atravs dos mtodos e propriedades a forma que iremos preencher os dados necessrios para um email como: Assunto, Corpo da Mensagem, 'Com Cpia', etc.. Assim atravs da classe podemos customizar tambm a mensagem que queremos enviar. Acompanhe o exemplo abaixo.
#include "Protheus.ch" user Function EMail() Local oServer Local oMessage Local nNumMsg := 0

Local nTam Local nI

:= 0 := 0

//Crio a conexo com o server STMP ( Envio de e-mail ) oServer := TMailManager():New() oServer:Init( "", "smtp.microsiga.com.br", "ricardo.reis", "rica4758", 0, 25 ) //seto um tempo de time out com servidor de 1min If oServer:SetSmtpTimeOut( 60 ) != 0 Conout( "Falha ao setar o time out" ) Return .F. EndIf //realizo a conexo SMTP If oServer:SmtpConnect() != 0 Conout( "Falha ao conectar" ) Return .F. EndIf //Apos a conexo, crio o objeto da mensagem oMessage := TMailMessage():New() //Limpo o objeto oMessage:Clear() //Populo com os dados de envio oMessage:cFrom := "Microsiga " oMessage:cTo := "microsiga@microsiga.com.br;microsiga@microsiga.com.br" oMessage:cCc := "microsiga@microsiga.com.br" oMessage:cBcc := "microsiga@microsiga.com.br" oMessage:cSubject := "Teste de Email" oMessage:cBody := "Conteudo do e-mail" //Adiciono um attach If oMessage:AttachFile( "arquivo.txt" ) < 0 Conout( "Erro ao atachar o arquivo" ) Return .F. Else //adiciono uma tag informando que um attach e o nome do arq oMessage:AddAtthTag( 'Content-Disposition: attachment; filename=arquivo.txt') EndIf //Envio o e-mail If oMessage:Send( oServer ) != 0 Conout( "Erro ao enviar o e-mail" ) Return .F. EndIf //Disconecto do servidor If oServer:SmtpDisconnect() != 0 Conout( "Erro ao disconectar do servidor SMTP" ) Return .F. EndIf //Crio uma nova conexo, agora de POP oServer := TMailManager():New() oServer:Init( "pop3.microsiga.com.br", "", "SeunomeAntesDo@", "senhaDoEmail", 0, 110 )

If oServer:SetPopTimeOut( 60 ) != 0 Conout( "Falha ao setar o time out" ) Return .F. EndIf If oServer:PopConnect() != 0 Conout( "Falha ao conectar" ) Return .F. EndIf //Recebo o nmero de mensagens do servidor oServer:GetNumMsgs( @nNumMsg ) nTam := nNumMsg For nI := 1 To nTam //Limpo o objeto da mensagem oMessage:Clear() //Recebo a mensagem do servidor oMessage:Receive( oServer, nI ) //Escrevo no server os dados do e-mail recebido Conout( oMessage:cFrom ) Conout( oMessage:cTo ) Conout( oMessage:cCc ) Conout( oMessage:cSubject ) Conout( oMessage:cBody ) Next //Deleto todas as mensagens do servidor For nI := 1 To nTam oServer:DeleteMsg( nI ) Next //Diconecto do servidor POP oServer:POPDisconnect() Return .T.

Sintaxe oObj:ADDATTHTAG ( < cTag > ) --> NIL Parmetros Argumento cTag Retorno Tipo (NULO) Descrio Descrio Retorno nulo. Tipo Descrio Representa os dados que desejamos informa no caso de um Caracter arquivo atachado.

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 Retorno Tipo (NULO) Descrio Mtodo ATTACHFILE O mtodo AttachFile() da classe tMailMessage tem como objetivo adicionar um arquivo ao objeto de e-mail, 'um Attach'. Descrio Retorno nulo. Tipo Descrio Caracter Indica o nome do arquivo a ser adicionado no e-mail.

Sintaxe oObj:CLEAR ( ) --> NIL Retorno Tipo (NULO) Descrio Mtodo CLEAR Descrio Retorno nulo.

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 Retorno Tipo Caracter 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. Descrio Retorno uma String(cadeia de caracteres) contendo o conteudo do arquivo atachado na mensagem. Tipo Descrio Representa o Id(numero da mensagem) que desejamos Numrico obter informaes.

Sintaxe oObj:GETATTACHCOUNT ( ) --> nRet Retorno Tipo Numrico Descrio Mtodo GETATTACHCOUNT O mtodo getAttachCount() da classe tMailMessage tem como objetivo informar qual a quantidade de arquivos anexados a mensagem. Descrio Retorna o numero de anexos a mensagem.

Sintaxe oObj:GETATTACHINFO ( < nMsg > ) --> NIL Parmetros Argumento nMsg Retorno Tipo (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 Descrio Retorno nulo. Tipo Descrio Numrico Indica o numero da mensagem que desejamos verificar.

Sintaxe tMailMessage():NEW ( ) --> oObjtMailMessage Retorno Tipo Objeto Descrio Contrutor da Classe tMailMessage. Descrio Retorna uma nova instncia do Objeto da Classe tMailMessage.

Retorna uma nova instncia do Objeto da Classe tMailMessage, representa uma mensagem

Sintaxe oObj:RECEIVE ( < oServer > , < nMsg > ) --> nRet Parmetros Argumento oServer nMsg Retorno Tipo Numrico Descrio Mtodo RECEIVE O mtodo receive() da classe tMailMessage, tem como objetivo receber uma nova mensagem do servidor populando o objeto da mensagem. Descrio Retorna 0(zero) quando o E-mail foi recebido com sucesso, outro valor caso contrrio. Tipo Descrio Indica o Objeto do servidor POP, criado atraves no obejeto Memo TMailManager. Indica o Nmero da mensagem a ser criada, recebido Numrico atraves do metodo TMailManager:GetNumMsgs.

Sintaxe oObj:SAVE ( < cNumMsg > ) --> NIL Parmetros Argumento cNumMsg Retorno Tipo (NULO) Descrio Mtodo SAVE Descrio Retorno nulo. Tipo Descrio Array Representa o numero da mensagem que desejamos salvar.

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 oServer Retorno Tipo (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 Retorno nulo. Tipo Descrio Indica o objeto da classe tMailManager para o envio da Objeto mensagem.

Descrio Esta classe permite estabelecer uma conexo cliente de socket do tipo TCP genrica. Enviar e receber dados atravs de uma socket genrico e tambm pode ser usada como base para implementao de protocolos no suportados pelo protheus. Mtodos Mtodo Descrio

CloseConnection Connect IsConnected New Receive Reset Send

Finaliza a conexo TCP genrica (socket ) do objeto corrente. Estabelece um conexo TCP genrica (socket ). Verifica se existe conexo valida no objeto corrente. Cria o objeto tSocketClient, sem conexo ativa. Recebe os dados pela conexo ativa do objeto, qualquer tipo de dado pode ser recebido. Finaliza anormalmente a conexo, no avisa o outro lado que a conexo ser finalizada. Deve ser utilizado apenas em casos extremos. Transmite o buffer pela conexo TCP Genrica ativa.

O Exemplo abaixo exemplifica a utilizao de um cliente socket, note que para o programa funcionar corretamente, deve-se alterar os parametros da conexo.
user function MySocket Local oObj := tSocketClient():New() nResp := oObj:Connect( 999, "172.255.255.255", 1000 ) if(nResp == 0 ) Conout( "Conexo OK!" ) else Conout( "Erro na Conexo OK! ", nResp ) return endif cSend = "Ola!!!! Estou transmitindo um dado!" nResp := oObj:Send( cSend ) if( nResp != len( cSend ) ) conout( "Erro! Dado nao transmitido" ) else conout( "Dado Enviado" ) endif cBuffer := "" nQtd = oObj:Receive( cBuffer, 10000 ) if( nQtd >= 0 ) conout( "Dados Recebidos " + Str( nQtd, 4, 0 ), cBuffer ) else conout( "Nao recebi nada" ) endif cSend = "Dados que ser transmitido!!!" nResp := oObj:Send( cSend ) if( nResp != len( cSend ) ) conout( "Erro! Dado nao transmitido" ) else conout( "Dado Enviado" ) endif if( oObj:IsConnected() ) conout( "OK! Estou conectado" ) else conout( "Ops! Nao estou conectado" ) endif oObj:CloseConnection() if( !oObj:IsConnected() ) conout( "Desconectei" ) else conout( "Ainda estou conectado, erro na desconexao" )

endif return

Sintaxe oObj:CloseConnection ( ) --> Nil Retorno Tipo (NULO) Descrio Finaliza a conexo TCP genrica (socket ) do objeto corrente. Descrio Nil

Sintaxe oObj:CloseConnection ( ) --> Nil Retorno Tipo (NULO) Descrio Finaliza a conexo TCP genrica (socket ) do objeto corrente. Descrio Nil

Abrangncia Verso 6.09 Sintaxe oObj:IsConnected ( ) --> lLogico Retorno Tipo Lgico Descrio Retorna True se a conexo esta ativa e false caso esteja invlida/desconectado. Verso 7.10 Verso 8.11

Descrio Verifica se existe conexo valida no objeto corrente. Sintaxe tSocketClient():New ( ) --> oSocket Retorno Tipo Objeto Descrio Cria o objeto tSocketClient, sem conexo ativa. Sintaxe oObj:Receive ( < @cBuffer > , < nTimeout > ) --> nQtdRecebida Parmetros Argumento cBuffer nTimeout Retorno Tipo Numrico Descrio Recebe os dados pela conexo ativa do objeto, qualquer tipo de dado pode ser recebido. Descrio Qtde de bytes recebidos, se houver algum erro nQtdRecebida ser menor que zero. 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. Descrio Retorna um Objeto do tipo tSocketClient

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 Retorno Tipo Numrico Descrio Transmite o buffer pela conexo TCP Genrica ativa. Descrio Numero de bytes transmitidos, caso o numero seja diferente do tamanho de cBuffer, algum erro aconteceu. Tipo Descrio Caracter Buffer com os dados a serem transmitidos pela conexo.

BANCO DE DADOS Copy

Sintaxe COPY [ FIELDS <campo,...> ] TO xcFile [ escopo ] [ WHILE <lCondicao> ] [ FOR <lCondicao> ] [ SDF | DELIMITED [WITH <xcDelimiter>] ] [ VIA <xcDriver> ] Parmetros Argumento FIELDS <campo,...> TO xcFile Tipo Descrio FIELDS <campo,...> especifica um ou mais campos, separados por vrgula, a serem copiados para a tabela de Caracter destino. Caso no especificado este parmetro, sero copiados todos os campos da tabela de origem. Caracter 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.

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

escopo

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, executada WHILE Lgico antes de inserir cada registro na tabela de destino, sendo <lCondicao> 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 de FOR <lCondicao> Lgico destino, sendo a operao realizada apenas se lCondicao ser verdadeira ( .T. ) [ 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. 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 Caracter arquivo ASCII. DELIMITED WITH <xcDelimiter> permite especificar um novo caractere, ou sequncia de caracteres, a ser utilizada como delimitador, ao invs do default ( aspas duplas ). O caractere delimitador pode ser escrito de forma literal, ou como uma expresso entre parnteses. Nas Tabelas complementares A e B, na documentao do comando, so detalhadas as especificaes dos formatos SDF e DELIMITED. Caracter VIA <xcDriver> permite especificar o driver utilizado para criar a tabela de destino dos dados a serem copiados.

[ SDF | DELIMITED [WITH <xcDelimiter>] ]

VIA <xcDriver>

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

Marca de final de arquivo Nenhum (EOF) Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED WITH <xcDelimiter> ) Elemento do Arquivo Campos 'C' Caractere Campos 'D' Data Campos 'L' lgicos Formato Delimitados, ignorando espaos direita Formato aaaammdd ( ano, ms, dia ) T ou F

Campos 'M' Memo Campos 'N' Numricos Delimitador de Campos Separador de Registros

(campo ignorado) sem espaos em branco. Vrgula CRLF ( ASCII 13 + ASCII 10 )

Marca de final de arquivo Nenhum (EOF) 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 Sintaxe COPY STRUCTURE TO <xcDataBase> Parmetros Argumento Descrio Deve ser especificado em xcDatabase o nome da tabela a ser TO <xcDataBase> Caracter criada. Descrio COPY STRUCTURE um comando de banco de dados, que cria uma nova tabela, vazia, com a estrutura da tabela ativa na rea de trabalho atual. Se a tabela a ser criada j exista, a mesma sobrescrita. A tabela de destino criada utiliza o mesmo RDD da tabela de origem ( tabela ativa na rea de trabalho atual ). Observaes

Verso 5.08

Verso 6.09

Verso 7.10

Verso 8.11

Tipo

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

Sintaxe FTPVERSION ( ) --> cRet Retorno Tipo Caracter Descrio A funo FtpVersion tem como objetivo determinar qual a verso do Protocolo de Transferncia de Arquivos. Descrio Retorna uma String contendo o valor da verso de FTP.

Sintaxe

GETCOMPUTERNAME ( ) --> Nome da mquina Retorno Tipo Caracter Descrio Retorna o nome da mquina (HOSTNAME) que est executando o Protheus Remote Descrio Nome da mquina

Sintaxe GETENV ( < cVariavel > ) --> cRet Parmetros Argumento cVariavel Retorno Tipo Caracter Descrio A funo GetEnv() tm como objetivo determinar o valor de uma varivel do environment da plataforma(Sistema Operacional) em uso, no ambiente do Protheus Server. O valor de retorno da funo ser NIL se o parametro varname informado no for encontrado na tabela das variveis de ambiente do Sistema Operacional. Exemplo: cSysPath := GetEnv('PATH') Descrio Retorna o contedo da varivavel de ambiente, se encontrada na tabela de variaveis de sistema. Caso contrrio, retorna NIL. Tipo Descrio Nome da variavel de ambiente do sistema que desejamos Caracter obter.

Sintaxe GETENVSERVER ( ) --> cRet Retorno

Tipo Caracter Descrio

Descrio String contendo o nome do environment em execuo.

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 Atravs da funo GetRemoteType(), possvel identificar sob qual interface o programa atual est em execuo. Esta funo est disponvel a partir do Protheus 8, Build 7.00.040308a Pode-se utilizar as constantes abaixo, para avaliar o retorno da funo. NO_REMOTE REMOTE_QT_WIN32 REMOTE_QT_LINUX -1 // Job, Web ou Working Thread ( Sem remote ) 1 // Remote em ambiente Windows 2 // Remote em ambiente Unix/Linux Descrio nRmtType corresponde o nmero correspondente interface utilizada.

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 cSemaforo Retorno Tipo Numrico 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. Descrio A funo retorna um inteiro indicando oo numero de Threads LIVRES de acordo com o semaforo indicado por parametro. Tipo Descrio Indica o local ou Semafora em que as Threads foram Caracter iniciados.

Sintaxe IPCGo ( < cSemaforo > ) --> Nil Parmetros Argumento cSemaforo Retorno Tipo (NULO) Descrio Nil Tipo Descrio Indica o local ou Semaforo em que as Threads foram Caracter iniciados.

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 Retorno Tipo Lgico Descrio A funo IPCWait() tem como objetivo colocar em modo de espera uma Thread que acabou de ser carregada e fica aguardando oo chamado de uma IPCGo(). A funo recebe um parametro numrico que indica o timeOut em milissegundos de tempo para que a Thread seja derrubada. A IPCWait() recebe mais 15 parametros opcionais - que indica os parametros passados pela IPCGo() Retorna true caso tenha chegado um chamado da IPCGo(), false no recebeu nenhum IPCGo ou saiu por timeOut. obs: note que nao foi indicado um valor de semaforo para a funo, pois est implicito o programa que iniciou a Thread. Descrio Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao recebeu nehuma chamada ou saiu por timeOut. Tipo Descrio Numerico que Indica um tempo de timeOut em Numrico milissegundos, para a thread sair do ar.

Sintaxe

IPCWaitEx ( < cSemaforo > , < nTimeOut > ) --> nRet Parmetros Argumento cSemaforo nTimeOut Retorno Tipo Lgico 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. Descrio Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao recebeu nehuma chamada ou saiu por timeOut. 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.

Sintaxe ISSRVUNIX ( ) --> lisUnix Retorno Tipo Lgico Descrio Informa se o servidor Advanced Protheus est sendo executado em ambiente UNIX ou Linux. 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)

Exemplo das funes IsSrvUnix e GetRemoteIniName

Reviso: 12/06/2003 Abrangncia Verso 6.09 Verso 7.10 Verso 8.11

Atravs do exemplo abaixo, podemos obter o path de execuo do AP Remote.

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

Sintaxe KILLAPP ( [ lKill ] ) --> lRet Parmetros Argumento lKill Retorno Tipo Lgico Descrio Descrio retorna se thread corrente j recebeu algum aviso para ser finalizada(true), caso contrrio retorna false. Tipo Descrio Parametro opcional indicando se Thread corrente deve ser Lgico finalizada.

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 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. Descrio Nil

Sintaxe MSCRC32 ( < cString > ) --> nCRC

Parmetros Argumento cString 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.

Retorno Tipo Numrico 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))

Descrio Um nmero inteiro , com at 10 (dez) dgitos , correspondente ao CRC da string informada como parmetro.

Sintaxe MSCRC32STR ( < cString > ) --> cCRC32 Parmetros Argumento cString Tipo Descrio String a partir da qual ser calculado o CRC32. garantido que para a mesma string sempre ser obtido um mesmo Caracter CRC , mas no garantido que para strings diferentes os CRCs sejam sempre diferentes.

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 Muitas vezes desenvolvemos rotinas de durao longa que quando chamadas atravs de uma ao no Protheus Remote (Exemplo: Opo acionada no menu) provocam um 'congelamento' temporrio nas telas do Protheus Remote. Para minimizar esse efeito, podemos utilizar a funo PROCESSMESSAGES( ) para que o Protheus Remote possa renovar a pintura de suas janelas ou reagir a ao do mouse durante um processamento longo sendo executado no Protheus Server. Como o exemplo a seguir : while nRecs<1000 ProcessMessages( ) // Processo Longo DoSomethingLongTime( ) nRec-enddo Descrio Nil

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 Retorno Tipo Numrico 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 . 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 . Tipo Descrio Numrico Corresponde ao menor numero a ser gerado pela funo. Corresponde ao maior nmero ( menos um ) a ser gerado Numrico pela funo.

Sintaxe SENDTOFORE ( ) --> Nil

Retorno Tipo (NULO) 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. Descrio Esta funo no retorna valor

Sintaxe SOCKETCONN ( < cIP > , < nPort > , < cReq > , < nTimeOut > ) --> Nil Parmetros Argumento cIP nPort cReq nTimeOut Retorno Tipo (NULO) 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. Descrio Nil Tipo Caracter Numrico Caracter Numrico Descrio Representa uma String com o endereo IP ou nome da mquina do destino desejado. Indica o nmero da porta pelo qual ser realizada a conexo. Representa a requisio que ser feita para a maquina desejada, assim que a conexo for estabelecida. Indica o valor de tempo em segundos no qual a conexo ser encerrada por tempo de inatividade(time out).

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 A funcao XmlError() retorna um status da execuo da ultima rotina de criao de Objeto XML realizada pelo comando CREATE oXML. Podemos utilizar-nos das constantes definidas no arquivo #INCLUDE "XmlxFun.CH" para realizar o tratamento de erro. Vide tabelas de constantes abaixo : ---------------------------------------Constante Valor ---------------------------------------XERROR_ONLYFIRSTNODE -1 XERROR_SUCCESS 0 XERROR_FILE_NOT_FOUND 1 XERROR_OPEN_ERROR 2 XERROR_INVALID_XML 3 ---------------------------------------Descrio Retorna o status da ultima operao de Criao de Objeto XML realizado pelo comando CREATE oXml ...

#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 Retorno Tipo Lgico Descrio Compacta um buffer recebido, atravs do algoritmo proprietrio. Na maioria dos casos o buffer recebido ser menor do que o buffer original, em casos onde o buffer original muito pequeno, menos de 128 bytes, o buffer de sada poder ser maior do que o o buffer original. Essa funo aceita e retorna caracteres binrios de vrios tipos, incluindo o zero binrio. O Resultado dessa funo no dever ser gravado em banco de dados, especialmente TopConnect. Descrio Retorna .T., caso o buffer foi compactado com sucesso. Retorna .F., caso no seja possvel compactar o buffer. Tipo Descrio Retorna o buffer compactado, a varivel dever ser do tipo Caracter 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.

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 nLengthOut cBufferIn nLengthIn Retorno Tipo Lgico 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. Descrio Retorna .t., caso o buffer foi descompacto com sucesso. Retorna .F., caso no seja possvel descompactar o buffer. Tipo Caracter Numrico Caracter Numrico Descrio Buffer descompactado, exatamente o buffer que foi passado pela funo compress. Tamanho do buffer descompactado Buffer compactado pela funo compress. Tamanho do buffer compacto, informao fundamental para a correta descompactao do buffer.

FUNES DE IMPRESSO

Sintaxe GETIMPWINDOWS ( < lServer > ) --> aPrinters Parmetros Argumento lServer Retorno Tipo Array Descrio GETIMPWINDOWS( ) retorna uma lista de impressoras disponveis no spool do Server ou Remote. Se o Server est em ambiente Unix, a GETIMPWINDOWS() retornar a lista com os nomes de impressoras cadastradas na chave PRINTERSNAME do arquivo de configurao do Protheus Server. Caso no seja encontrada nenhuma impressora , retornado um array com 1 elemento , contendo a String "Nenhuma Impressora Disponivel". Observao : Caso a funo seja passada com o argumento .F. ( buscar impressoras da estao Remote ) , porm a funo seja executada a partir de um JOB ( programa sem a interface Remota ) , o array retornado ter apenas 1 elemento , contendo a String "Nenhuma Impressora Disponivel". Exemplos No exemplo abaixo , determinamos as impressoras disponveis na estao Remote e no Server , respectivamente. E , mostramos no Console do Server a(s) impressora(s) encontrada(s).
aImpRemote := GetImpWindows(.F.) conout('Impressoras na estao remota') aeval(aImpRemote , { |x| conout(x) }) aImpServer := GetImpWindows(.T.) conout('Impressoras no Servidor') aeval(aImpServer , { |x| conout(x) })

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.

Descrio Array com nome das impressoras disponveis. Vale lembrar que esta funo no verifica o status atual da(s) impressora(s) encontrada(s).

Sintaxe

GETPORTACTIVE ( < lServer > ) --> aPortImp Parmetros Argumento lServer Retorno Tipo Array Descrio Retorna lista de portas de impresso disponveis. A funo GETPORTACTIVE( ) retorna uma lista de portas de impresso disponveis do Protheus Server ou Remote. Se o Protheus Server est em ambiente Unix, a GETPORTACTIVE() retornar uma lista com os nomes de devices possveis para impresso. Caso no sejam encontradas portas para impresso , retornado um array com apenas um elemento , contendo a string "Nao existem portas disponiveis". Observao : Caso a funo seja chamada com o parmetro .F. , para obter as portas de impresso da estao remota , porm a funo seja chamada atravs de um JOB ( programa sem a interface Remote ) , a mesma retornar um array com um elemento , contendo a string "Nao existem portas disponiveis". [RELEASE] Builds superiores a 7.00.041130p Ao verificar os devices de impresso disponveis no SERVER, os devices especificados na configurao de bloqueio de portas de impresso ( DisableDevicePort ) no server no so listados por esta funo. Quando executada em ambiente Linux, os devices de impresso disponveis no SERVER, a funo deixa de retornar os devices como /dev/lp0 e /dev/ttys0 ... e passa a retorn-los a nomenclatura LPT1:...COM1:... , limitando o retorno em no mximo 4 portas paralelas e 4 portas seriais. Exemplos No exemplo abaixo, determinamos as portas de impresso disponveis na estao Remote e no Server, respectivamente. E mostramos no Console do Server a(s) porta(s) encontrada(s).
aPortRemote := GetPortActive(.F.) conout('Impressoras na estao remota') aeval(aPortRemote , { |x| conout(x) }) aPortServer := GetPortActive(.T.)

Tipo

Descrio CAso especificado .T. , a lista de impressoras ser obtida do Lgico Server, caso .F. a lista ser obtida da estao (Remote).

Descrio Array com as portas de impresso disponveis.

conout('Impressoras no Servidor') aeval(aPortServer , { |x| conout(x) })

Veja abaixo um exemplo do que foi mostrado no console do Protheus Server, apos a execuo da rotina.
Impressoras na estao remota COM1: COM2: COM3: COM4: FILE: LPT1: LPT2: LPT3: \\prnserver\prx-lp1 Impressoras no Servidor COM1: COM2: COM3: COM4: FILE: LPT1: LPT2: LPT3:

FUNES INTERFACE http

ENCRYPTRSA ( < cFileKey > , < cInfo > , [ lEncode64 ] ) --> cRet Parmetros Argumento cFileKey cInfo lEncode64 Retorno Tipo Caracter Descrio Descrio Retorna as informaes passadas atravs do argumento, criptografadas em RSA. 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.

A funo EncryptRSA tem como objetivo realizar a criptografia de dados, para isso usa um tipo de criptografia denominada RSA. O RSA um algoritmo de Criptografia Assimtrica, isto significa que possumos uma chave pblica e privada, RSA o mais usado algoritmo de chave pblica, pois prov confidencialidade e assinatura digital. A chave pblica a que serve para cifrar a mensagem (Confidencialidade) e decifrar a mensagem (Autenticidade). Todos que desejarem lhe enviar uma mensagem devem conhec-la. Chave privada, que serve para decifrar a mensagem (Confidencialidade) e cifrar a mensagem (Autenticidade). Somente uma pessoa deve conhec-la. Em nossa funo informamos o local onde se encontra a chave que ser usada, em seguida passamos como string os dados que queremos criptografar, podemos ainda informar se desejamos o retorno em base 64 ou nao.

Sintaxe GETWEBJOB ( ) --> cJobName Retorno Tipo Caracter Descrio cJobName corresponde o nome do job que configura a working Thread atual em uso. Caso a chamada da funo seja realizada a partir de uma thread que no seja uma Working Thread ( como por exemplo , uma thread iniciada a partir de um ApxRemote ) , a funo GetWebJob() retornar uma string vazia ("").

Descrio Atravs desta funo , possvel recuperar o nome da configurao de Working Threads ( Job ) que est sendo utilizada pela Working Thread atual. Observao : Esta funo est disponvel a partir dos Build's Ap6 gerados a partir de 05/09/2002.

Sintaxe GetEnvHost ( ) --> cHost Retorno

Tipo Caracter Descrio

Descrio Quando em ambiente web retorna o host que foi utilizado para chamar a funo.

Retorna quando em ambiente web, por qual host a pgina foi chamada. Exemplo: web function retHost return getenvhost() // Retorna o nome do host que chamou essa funcao ( Ex: www.microsiga.com.br )

Sintaxe HTTPCACHE ( < cCacheControl > ) --> cLastCache Parmetros Argumento cCacheControl Retorno Tipo Caracter 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. Descrio Esta funo retorna a definio atualmente utilizada para a etiqueta CacheControl do Header HTTP. Tipo Descrio Define o novo contedo da etiqueta do Header de Retorno Caracter HTTP Cache-Control.

Tabela A - Definies CACHE-CONTROL

Contedo Aplicao no-store Nenhuma informao deve ser guardada em Cache pelo servidor e/ou 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 Esta funo retorna o nmero de Sessions de usurios que esto atualmente em uso na memria. ** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web Extended ) ** OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo necessrio adquirir um Build de Protheus Server com data igual ou superior a 22/04/2002. Descrio nCount corresponde ao nmero de usurios que possuem variveis de session em uso no Server PRotheus.

Sintaxe HTTPCTDISP ( ) --> Nil Retorno Tipo (NULO) 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 Descrio Nil

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 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 := '' := space(1024)

Sintaxe HTTPEXITPROC ( < cFunction > ) --> Nil Parmetros

Argumento cFunction Retorno Tipo (NULO) Descrio

Tipo

Descrio String que indica o nome da funo a ser chamada quando a Caracter Session for finalizada por time-out.

Descrio Nil

A httpExitProc tem o objetivo de setar uma funo que ser chamada quando uma Session for Finalizada por Time-Out. A funo que ser chamada para tratamento da session finalizada, deve estar compilada no repositrio de dados corrente. Muito til quando se deseja encaminhar todas 'quedas' de Session para uma nica funo de tratamento. Sintaxe HTTPFREESESSION ( ) --> NIL Retorno Tipo (NULO) Descrio 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. Descrio Esta funo sempre retorna NIL

Sintaxe HTTPGET ( < cUrl > , [ cGETParms ] , [ nTimeOut ] ) --> cHttp

Parmetros Argumento cUrl cGETParms Tipo Descrio cUrl corresponde ao endereo http , juntamente com a pasta Caracter 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).

nTimeOut

Retorno Tipo Caracter 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 Descrio String Html correspondendo ao documento solicitado.

Sintaxe HTTPGETPART ( ) --> bPartEnabled Retorno Tipo Descrio

Lgico Descrio

Retorna .t. se o envio parcial do contedo HTML est habilitado.

Esta funo retorna se o envio parcial de contedo ao browser est ou no habilitado.

Sintaxe HTTPGETSTATUS ( ) --> nStatus Retorno Tipo Numrico 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' Descrio Retorna o status da conexo HTTP atual requerida

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 Return cHtml web Function loginMK() Local cHtml := "" if HttpGetStatus() == 0 cHtml := HTTPPOST( "http://ricardo/w_ExHTTPPost.apw", "", "login=Teste&pass=123", 120 , NIL ) conout( HttpGetStatus() ) if HttpIsConnected() conout("isConnected") endif endif Return cHtml := "<h3>HttpPost</h3><br><br>" += "<table width=200 border=1>" += "<tr><td>Login</td><td>"+HttpPost+= "<tr><td>Senha</td><td>"+HttpPost+= "</table>"

Sintaxe HTTPLEAVESESSION ( ) --> NIL Retorno Tipo (NULO) 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 Descrio A funo HttpLeaveSession() sempre retorna NIL

necessrio adquirir um build de Server PRotheus com data igual ou superior a 22/04/2002.

Sintaxe HTTPLOGONUSER ( ) --> cLogonUser Retorno Tipo Caracter Descrio String contendo o login do usurio, no formato DOMINIO\login. Caso a funo no seja executada em uma thread iniciada em uma interface http , ou o acesso annimo o site no IIS esteja habilitado , a funo retornar uma string em branco ("").

Descrio Atravs da Funo HttpLogonUser() , quando utilizamos o AP Server ISAPI ( AdvplIsapi.dll) , em conjunto com o Microsoft IIS (Internet Information Services ) , obtemos o login do usurio atual. Observao : Para que o usurio seja obrigado a informar um login individual , deve ser desabilitado no IIS a configurao que permite acesso annimo ao site. Caso esta configurao no seja alterada , todos os usurios sero identificados como "annimos" pelo IIS, e a funo retornar uma String em branco. Sintaxe HTTPOTHERCONTENT ( ) --> cContent Retorno Tipo Caracter Descrio 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 Descrio cContent a string correspondendo ao contedo do corpo do pacote HTML postado no Server.

seja chamada em um ambiente que no esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar uma string em branco ("").

Sintaxe HTTPPOST ( < cUrl > , [ cGETParms ] , [ cPOSTParms ] , [ nTimeOut ] , [ aHeadStr ] ) --> cHtml Parmetros Argumento cUrl cGETParms cPOSTParms Tipo Caracter Caracter Caracter Descrio cUrl corresponde ao endereo http , juntamente com a pasta e o documento solicitados. cGETParms corresponde StringList de parmetros a 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 . Caso no especificado , este parmetro considerado vazio ("") Em nTimeOut especificamos o tempo em segundos mximo de inatividade permitido durante a recepo do documento . Caso no especificado , o valor default assumido 120 segundos ( 2 minutos). Atravs deste parametro , podemos especificar um array com strings a serem acrescentadas ao Header da requisio HTTP a ser realizada.

nTimeOut

Numrico

aHeadStr Retorno Tipo Caracter Descrio

Array

Descrio Atravs de cHtml ser retornada a String Html correspondendo ao documento solicitado.

A funo HttpPost() permite a emulao de um Client HTTP atravs de uma funo Advpl, postando um bloco de informaes para um determinado documento publicado em um servidor Web, utiliando o mtodo POST , permitindo a passagem de parmetros adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta do servidor solicitado. Observaes :

Na passagem de parmtros GET e POST , devemos atentar ao formato da string a ser passada como parmetros , pois a mesma segue o formato URI (Uniform Resource Identifiers) : Query Component.

Caso nao seja retornado o documento antes do trmino do Time-out especificado na chamada da funo; ou caso no seja possvel localizar o servidor ; seja por falha de resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a funo retornar Nulo (NIL). Caso nao seja possvel o acesso ao documento , como por exemplo o documento no exista ,ser retornado uma string html com a mensagem de erro html enviada pelo servidor correspondente. Quando utilizamos a funo HttpPost() , podemos especificar um Content-Type diferenciado para o contedo postado. Caso no seja especificado um ContentType , alguns servidores tratam a informao postada como sendo um dado do tipo 'application/x-www-form-url' , seria o equivalente a um formulrio HTML postado via Browser, outros servidores podero no reconhecer tal informao postada dessa forma. Para especificar que o contedo postado deve ser tratado como um POST de formulrio HTTP , devemos passar no parmetro aHeadStr , um elemento contendo 'Content-Type: application/x-www-form-url'. ATENO

1. Esta funco est disponivel apenas em Builds Ap6 gerados a partir de 10/07/2002 . 2. O parametro aHeadStr apenas est disponvel em Build's Ap6 e posteriores gerados apos 01/10/2002.

Exemplos Neste exemplo usamos a funo HttpGetStatus para termos certeza de que no temos uma conexo HTTP vlida, para isto verificamos o cdigo retornado pela funo. Estando tudo correto, realizamos uma emulao de post para a funo no inicio do fonte ExHTTPPost() - retornando uma simples tabela com os dados postados. Em seguida ainda verificamos a conexo aps o Post.
#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 := "<h3>HttpPost</h3><br><br>" += "<table width=200 border=1>" += "<tr><td>Login</td><td>"+HttpPost+= "<tr><td>Senha</td><td>"+HttpPost+= "</table>"

endif Return cHtml web Function loginMK() Local cHtml := "" if HttpGetStatus() == 0 cHtml := HTTPPOST( "http://ricardo/w_ExHTTPPost.apw", "", "login=Teste&pass=123", 120 , NIL ) conout( HttpGetStatus() ) if HttpIsConnected() conout("isConnected") endif endif Return cHtml

Sintaxe HTTPPOSTXML ( < cURL > , [ cParam ] , < cFile > , < nTimeOut > ) --> lRet Parmetros Argumento cURL cParam cFile nTimeOut Retorno Tipo Lgico 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 Descrio Retorna se foi possvel realizar o PostXml. Caso seja realizado retorna true, caso contrrio false. 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.

mtodo POST , permitindo a passagem de parmetros adicionais e aguardando por um tempo determinado (time-out) pela resposta do servidor solicitado.

Sintaxe HTTPPRAGMA ( < cPragma > ) --> cOldPragma Parmetros Argumento cPragma Retorno Tipo Caracter 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. Descrio A funo HttpPragma retornar a definio anterior de PRAGMA utilizada. Tipo Descrio cPragma corresponde ao conteudo do PRAGMA a ser Caracter definido no Header de retorno HTTP. Veja tabela "A" de definies PRAGMA.

Tabela A - Definies Pragma

Contedo Aplicao Informa ao Client HTTP ( Browser ) que a pgina retornada no deve ser no-cache colocada em Cache, independente da configurao de Cache do Browser.
Observao : A definio de um novo contedo para o PRAGMA do Header HTTP apenas ser possvel caso esta funo Advpl seja executada antes de quaqlquer envio parcial de html ao browser , realizado pela funo HttpSend().

Sintaxe HTTPRCTDISP ( ) --> cCtDisp Retorno Tipo Caracter Descrio cCtDisp corresponde o conteudo do identificador Content-disposition , recebido quando um Web Browser realiza uma requisio via HTTP ao

servidor. Descrio A funo HttpRCtDisp() , quando utilzada em uma thread montada e/ou inicializada para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador Content-disposition do Header HTTP . Caso a requisio tenha sido realizada por um client HTTP que no enviou este identificador no Header HTTP , ou a funo seja chamada em um ambiente que no esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar uma String em branco (""). Sintaxe HTTPRCTLEN ( ) --> nCtLen Retorno Tipo Numrico Descrio 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 ) . Descrio nCtLen corresponde o conteudo do identificador Content-length , recebido quando um Web Browser realiza uma requisio via HTTP ao servidor.

Sintaxe HTTPRCTTYPE ( ) --> cCtType Retorno Tipo Caracter Descrio Descrio cCtType corresponde o conteudo do identificador Content-type , recebido quando um Web Browser realiza uma requisio via HTTP ao servidor.

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 HTTPRCTTYPE ( ) --> cCtType Retorno Tipo Caracter 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 (""). Descrio cCtType corresponde o conteudo do identificador Content-type , recebido quando um Web Browser realiza uma requisio via HTTP ao servidor.

Sintaxe HTTPSEND ( < cHtmlStr > ) --> cHtmlNoSend Parmetros Argumento cHtmlStr Retorno Tipo Caracter Descrio Caso a funo obtenha sucesso em enviar a String cHtmlStr para o Browse solicitante , o retorno ser uma string vazia (""). Caso no seja possvel o envio da string , devido o recurso de envio Tipo Descrio cHtmlStr corresponde string a ser enviada ao Browser Caracter solicitante de um processamento .

simultneo estar desabilitado ; ou ocorra uma falha de comunicao, ou a funo HttpSend() seja executada a partir de uam thread que no uma Working Thread , a funo ir retornar a string passada como parmetro. Descrio Atravs desta funo, possivel retornar uma string Html um browser durante o processamento de uma requisio realizada atravs de um link .APW , utilizando Working Threads , durante o processamento da mesma. Observao : Este recurso no funciona em requisies de procesamento realizadas a partir de um link .apl . necessrio que a requisio seja para um link .apw , atendida por uma Working Thread.

Sintaxe HTTPSETPART ( < lHttpSend > ) --> NIL Parmetros Argumento lHttpSend Retorno Tipo (NULO) 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. Descrio Esta funo sempre retorna NIL Tipo Descrio lHttpSend um valor booleano que habilita o envio parcial Lgico ( caso .T. ) ou desabilita o envio parcial de HTML ( .F. )

Sintaxe HTTPSETPASS ( < cUser > , < cPass > ) --> Nil Parmetros

Argumento cUser cPass Retorno Tipo (NULO) Descrio

Tipo

Descrio Cadeia de caracteres que representa o usurio a ser setado Caracter uma senha. Indica a senha informada para autenticao de acordo com o Caracter usurio informado.

Descrio Nil

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 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 Descrio Nil Descrio Quantidade de usurios com sesses web extended ativas

Libera a sesso do usurio corrente, todos os dados armazenado nas sesses deste usurio ser perdida. Funo utilizada para efetuar o log off do usurio do site.

Sintaxe HttpIsAPW ( ) --> bIsAPW Retorno Tipo Lgico Descrio 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. Descrio Retorna .T. no caso do ambiente em execuo ser um APW, .F. em todas as outras situaes.

Sintaxe HttpIsConnected ( ) --> bConnected Retorno Tipo Lgico Descrio Informa se o browser est conectado ainda esperando a resposta do Protheus! Funcionalidade no disponvel quando utilizado o ISAPI para integrao com IIS Descrio Retorna .t. se o browser ainda est conectado aguardando a resposta.

Sintaxe ISSECURE ( ) --> lRet

Retorno Tipo (NULO) 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. Descrio true caso a conexo uma conexo SSL, false caso contrrio.

Sintaxe SOAPRACTION ( ) --> cSoapAction Retorno Tipo Caracter 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 (""). Descrio cSoapAction corresponde o conteudo do identificador soapaction , recebido quando um Web Browser realiza uma requisio via HTTP ao servidor.

FUNO DE DISCO E ARQUIVO

Sintaxe ADIR ( [ ] , [ ] , [ ] , [ ] , [ ] , [ ] ) --> nArquivos Parmetros Argumento <cEspecArq> Tipo Descrio Caracter <cEspecArq> a especificaao dos arquivos a serem

<aNomesArq>

Array

<aTamanhos> <aDatas>

Array 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() uma funao de tratamento de vetor que executa duas operaoes bsicas. Primeiro, ele retorna a quantidade de arquivos que correspondem especificaao de arquivo. Segundo, preenche uma srie de vetores com nomes de arquivos, tamanhos, datas, horas e atributos. ADIR() uma funao de compatibilidade e portanto desaconselhada. Ele est superado pela funao DIRECTORY(), que retorna todas as informaoes de arquivo em um vetor multi-dimensional. OBSERVAO Diretrios: Caso o argumento <aAtributos> seja especificado e <cEspecArq> seja especificado como *.*, os diretrios serao incluidos em <aNomesArq>. No vetor <aAtributos>, os diretrios sao indicados com um valor atributo de "D." Se ADIR() for Descrio ADIR() retorna a quantidade de arquivos que correspondem ao esqueleto de diretrio especificado.

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 cOrigem cDestino lCompacta Retorno Tipo Lgico Descrio Copia um arquivo, do servidor para o cliente ( Remote ). .Caso a compactao seja habilitada (lCompacta ), os dados sero transmitidos de maneira compactada e descompactados antes do uso. Exemplo :
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. ) // Copia arquivos do servidor para o remote local, compactando antes de transmitir CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. ) // Copia arquivos do servidor para o remote local, sem compactar antes de transmitir

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 antes Lgico do envio.

Descrio lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em caso de falha na cpia.

Sintaxe CPYT2S ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess Parmetros Argumento cOrigem cDestino lCompacta Retorno Tipo Lgico 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.

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.

Descrio lSucess indica , caso verdadeiro , que a cpia foi realizada com sucesso. Caso retorne .F. , houve erro na copia do arquivo.

Sintaxe CURDIR ( [ cNovoPath ] ) --> cPathAtual Parmetros Argumento cNovoPath Retorno Tipo Descrio Caminho relativo , com o novo diretrio que ser ajustado Caracter como corrente.

Tipo Caracter Descrio

Descrio Diretrio corrente, sem a primeira barra.

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 Tipo Descrio <cDirSpec> especifica o drive, diretrio e arquivo para a pesquisa no diretrio. Caracteres do tipo coringa sao permitidos na especificaao de arquivos. Caso <cDirSpec> Caracter seja omitido, o valor padrao *.*. O caminho especificado pode estar na estao (remote) , ou no servidor , obedecendo s definices de Path Absoluto / Relativo de acesso Caracter <cAtributos> especifica que arquivos com atributos especiais devem ser incluidos na informaao retornada. <cAtributos> consiste em uma cadeia de caracteres que contm um ou mais dos seguintes caracteres, contidos na

cDirSpec

<cAtributos>

tabela adicional A , especificada abaixo: Retorno Tipo Array 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. 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.

TABELA A: Atributos de DIRECTORY()

Atributo H S D V Significado Incluir arquivos ocultos Incluir arquivos de sistema Incluir diretrios 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 1 2 3 4 5 Metasmbolo cNome cTamanho dData cHora cAtributos Directry.ch F_NAME F_SIZE F_DATE F_TIME F_ATT

Exemplos Atravs do exemplo abaixo , obtemos no array aDirectory todos os diretrios no ambiente do servidor a partir do path atual.

#INCLUDE "Directry.ch" aDirectory := DIRECTORY("*.*","D") AEVAL( aDirectory, {|aFile| CONOUT(aFile[F_NAME])} )

Sintaxe DIRREMOVE ( < cDiretorio > ) --> lSucesso Parmetros Argumento cDiretorio 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(). Tipo Descrio Caracter Nome do diretrio a ser removido.

Descrio DIRREMOVE() elimina um diretrio especifico. Caso especifiquemos um path sem a unidade de disco , ele ser considerado no ambiente do Servidor , a partir do RootPath do ambiente ( caso o path comee com \ ) , ou a partir do diretrio corrente ( caso o path no seja iniciado com \ ) . E , quando especificado um path absoluto ( com unidade de disco preenchida ) , a funo ser executada na estao onde est sendo executado o Protheus Remote. Quando executamos a funo DirRemove() em JOB ( processo isolado no Server , sem interface ) , no possvel especificar um Path absoluto de disco. Caso isto seja realizado , a funo retornar .F. e FError() retornar -1 ( Syntax Error ) . Note que necessrio ter direitos suficientes para remover um diretrio, e o diretrio a ser eliminado precisa estar vazio, sem subdiretrios ou arquivos dentro do mesmo. Exemplos No exemplo abaixo , executado a partir do Protheus Remoite , tentamos excluir a pasta c:\TmpFiles , verificando se houve sucesso nesta operao.
cDelPath := 'c:\TmpFiles' lRemoveOk := DIRREMOVE(cDelPath) IF !lRemoveOk MsgStop('Falha ao remover a pasta '+cDelPath+' ( File Error '+str(Fewrror(),4)+' ) ') Else MsgStop('Pasta '+cDelPath+' removida com sucesso.') Endif

Sintaxe DISKSPACE ( [ nDrive ] ) --> nBytesFree Parmetros Argumento nDrive Retorno Tipo Numrico 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 Descrio Nmero de bytes disponveis no disco informado como parmetro. 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.

Exemplo da funo DISKSPACE

Reviso: 01/05/2003 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

No exemplo abaixo , obtemos os espaos em disco da unidade de disco da estao local e do drive A: da estao local, verificando se houve sucesso na operao.

nBytesLocal := DISKSPACE( ) // Retorna o espao disponivel na unidade de disco local ( remote ). IF nBytesLocal < 1048576 MsgStop('Unidade de Disco local possui menos de 1 Mb livre.') Else MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes livres.') Endif nBytes_A := DISKSPACE( 1 ) // Retorna o espao disponivel no drive A: local ( remote ). If nBytes_A == -1 MsgStop('Unidade A: no est disponvel ou no h disco no Drive') ElseIf nBytes_A < 8192 MsgStop('No h espao disponvel no disco. Substitua o disco na Unidade A:') Else MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes livres.') Endif

Sintaxe FCLOSE ( < nHandle > ) --> lError Parmetros Argumento nHandle Retorno Tipo Lgico Descrio FCLOSE() uma funao de tratamento de arquivos de baixo nvel utilizada para fechar arquivos binrios e forar que os respectivos buffers do DOS sejam escritos no disco. Caso a operaao falhe, FCLOSE() retorna falso (.F.). FERROR() pode entao ser usado para determinar a razao exata da falha. Por exemplo, ao tentar-se usar FCLOSE() com um handle (tratamento dado ao arquivo pelo sistema operacional) invlido retorna falso (.F.) e FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para obter uma lista completa dos cdigos de erro. Aviso Esta funao permite acesso de baixo nvel aos arquivos e dispositivos do DOS. Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional utilizado. Descrio FCLOSE() retorna falso (.F.) se ocorre um erro enquanto os buffers estao sendo escritos; do contrrio, retorna verdadeiro (.T.). Tipo Descrio <nHandle> o handle do arquivo obtido previamente Numrico atravs de FOPEN() ou FCREATE().

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 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 atributos Numrico abaixo). Caso no especificado , o DEFAULT FC_NORMAL.

nAtributo Retorno Tipo Numrico

Descrio A funo retornar o Handle do arquivo para ser usado nas demais funes de manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no seja possvel criar o arquivo , a funo retornar o handle -1 , e ser possvel obter maiores detalhes da ocorrencia atravs da funo FERror()

Descrio FCREATE() uma funo de baixo-nvel que permite a manipulao direta dos arquivos textos como binrios. Ao ser executada FCREATE() cria um arquivo ou elimina o seu contedo, e retorna o handle (manipulador) do arquivo, para ser usado nas demais funes de manuteno de arquivo. Aps ser utilizado , o Arquivo deve ser fechado atravs da funo FCLOSE(). Na tabela abaixo , esto descritos os atributos para criao do arquivo , definidos no arquivo header fileio.ch Constante Valor Descrio

FC_NORMAL FC_READONLY FC_HIDDEN FC_SYSTEM

0 1 2 4

Criao normal do Arquivo (default/padro). Cria o arquivo protegido para gravao. Cria o arquivo como oculto. 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 cArquivo Retorno Tipo Numrico Descrio Atravs da funo Ferase , possvel apagar um arquivo no disco . O Arquivo pode estar no Servidor ou na estao local (Remote). O Arquivo para ser apagado deve estar fechado. No permitido a utilizao de caracteres coringa (wildcards). Exemplos // Este exemplo apaga todos os arquivos .BAK do diretrio corrente no Servidor
#include 'DIRECTRY.CH' aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })

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 .

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

// 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 cArquivo 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 ? )

Retorno Tipo Lgico Descrio Verifica se existe um arquivo ou um padro de arquivos, no diretrio. Pordemos especificar caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( A partir do RootPath do Protheus Server) . Os caracteres * e ? ( wildcards). so aceitos. Exemplos
FILE("teste.dbf") // Verifica no diretrio corrente do servidor se existe o arquivo teste.dbf FILE("\SIGAADV\TESTE.dbf") // Verifica no diretrio Sigaadv do servidor se existe o arquivo teste.dbf FILE("C:\TEMP\TESTE.dbf") // // Verifica no diretrio Temp do cliente (Remote) se existe o arquivo teste.dbf

Descrio O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no exista no path especificado , a funo retorna .F.

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 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 padrao Numrico 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.

nModo

Retorno Tipo Numrico Descrio Abre um arquivo binrio. FOPEN() uma funao de tratamento de arquivo de baixo nvel que abre um arquivo binrio existente para que este possa ser lido e escrito, dependendo do argumento <nModo>. Toda vez que houver um erro na abertura do arquivo, FERROR() pode ser usado para retornar o cdigo de erro do Sistema Operacional. Por exemplo, caso o arquivo nao exista, FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o arquivo nao foi encontrado. Veja FERROR() para uma lista completa dos cdigos de erro. Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de banco de dados, e ele exigido para identificar o arquivo aberto para as outras funoes de tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi retornado a uma varivel para uso posterior, como mostra o exemplo desta funo. Aviso Esta funao permite acesso de baixo nvel a arquivos e dispositivos. Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional utilizado. Notas Descrio FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso ocorra um erro, FOPEN() retorna -1.

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 0 1 2 Constante (fileio.ch) FO_READ FO_WRITE FO_READWRITE Operao Aberto para leitura (padro assumido) Aberto para gravao Aberto para leitura e gravao

Tabela B: Modos de Acesso de Compartilhamento a Arquivos Binrios Modo 0 16 32 48 64 64 Constante (fileio.ch) Operao FO_COMPAT Modo de Compatibilidade (Default) FO_EXCLUSIVE Acesso total exclusivo FO_DENYWRITE Acesso bloqueando a gravao de outros processos ao arquivo. FO_DENYREAD Acesso bloqueando a leitura de outros processos ao arquivo. Acesso compartilhado. Permite a leitura e gravao por outros FO_DENYNONE processos ao arquivo.. FO_SHARED 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 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.

cBuffer

nQtdBytes Retorno Tipo Numrico Descrio

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.

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 Retorno Tipo Caracter Descrio L caracteres de um arquivo binrio. FREADSTR() l de um arquivo aberto, atravs de FOPEN(), FCREATE(), FOPENPORT(). FREADSTR() ler at o nmero de bytes informado em nQtdBytes ou at encontrar um CHR(0). Caso acontea algum erro ou o arquivo chegue ao final, FREADSTR() retornar uma string menor do que nQdBytes e colocar o erro em FERROR(). FREADSTR() l a partir da posio atual do ponteiro, que pode ser ajustado pelo FSEEK(), FWRITE( ) ou FREAD(). Sintaxe FRENAME ( < cOldFile > , < cNewFile > ) --> nStatus Parmetros Argumento 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. 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 servidor, Caracter e caminho do cliente. Descrio Retorna uma string contendo os caracteres lidos. Tipo Descrio o manipulador retornado pelas funes FOPEN(), Numrico FCREATE(), FOPENPORT(). Numrico Nmero mximo de bytes que devem ser lidos.

Descrio Atravs da funo FRENAME() possvel renomear um arquivo para outro nome, tanto no servidor como na estao. Ao renomear um arquivo no esquea que esta arquivo dever estar fechado ( isto , no pode estar em uso por nenhum outro processo ou estao). Caso o arquivo esteja aberto por outro processo , a operao de renomear o arquivo no possvel. A funo fRename() no aceita wildcards ( * e/ou ? ). Vale lembrar que no possvel renomear um arquivo especificando nos parmetros simultaneamente um caminho de servidor e um de estao remota, bem como especificar dois arquivos remotos e executar a funo fername() atravs de um JOB. Caso isto ocorra, a funo retornar -1 , e fError() retornar tambm -1. Importante : Quando especificamos um path diferente nos arquivos de origem e destino , a funo fRename() realiza a funcionalidade de MOVER o arquivo para o Path especificado. Exemplos
// Renomeando um arquivo no Client de origem.txt para destino.txt , na pasta c:\Temp nStatus1 := frename('c:\Temp\Origem.txt' , 'c:\Temp\Destino.txt' ) IF nStatus1 == -1 MsgStop('Falha na operao 1 : FError '+str(ferror(),4)) Endif // Renomeando um arquivo no Server, na pasta sigaadv , de error.log para error.old nStatus2 := frename('\sigaadv\error.log' , '\sigaadv\error.old' ) IF nStatus2 == -1 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 Tipo Descrio Manipulador obtido atravs das funes Numrico FCREATE,FOPEN. Numrico nOffSet corresponde ao nmero de bytes no ponteiro de posicionamento do arquivo a ser movido. Pode ser um numero positivo , zero ou negativo, a ser considerado a

nOrigem Retorno Tipo Numrico

partir do parmetro passado em nOrigem. Indica a partir de qual posio do arquivo, o nOffset ser Numrico considerado.

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 0 1 2 Constante FS_SET FS_RELATIVE FS_END Operao Ajusta a partir do inicio do arquivo. (Default) Ajuste relativo a posio atual do arquivo. Ajuste a partir do final do arquivo.

Sintaxe FT_FEOF ( ) --> lRet Retorno Tipo Lgico 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. Descrio Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso contrrio.

Exemplos O exemplo abaixo realiza a leitura de um arquvio texto, utilizando-se das funes FT_F*
FT_FUse('teste.txt') // Abre o arquivo conout("Linhas no arquivo ["+str(ft_flastrec(),6)+"]") FT_FGOTOP() While !FT_FEof() conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln() +"]") FT_FSkip() Enddo FT_FUse() // Fecha o arquivo

Sintaxe FT_FGOTO ( < nPos > ) --> NIL Parmetros Argumento nPos Retorno Tipo (NULO) Descrio A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto, para a posio absoluta especificada pelo argumento <nPos>. Descrio Esta funo sempre retorna NIL Tipo Descrio Indica a posio que ser colocado o ponteiro para leitura Numrico dos dados no arquivo.

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

Descrio Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja vazio, ou no exista arquivo aberto, a funo retornar 0 (zero)

Sintaxe

FT_FREADLN ( ) --> cRet Retorno Tipo Caracter 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

Descrio Retorna a linha inteira na qual est posicionado o ponteiro para leitura de dados.

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 nLinhas Retorno Tipo (NULO) 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. Descrio Esta funo sempre retorna NIL. Tipo Descrio nLinhas corresponde ao nmero de linhas do arquivo TXT Numrico ref. movimentao do ponteiro de leitura do arquivo.

Sintaxe FT_FUSE ( [ cTXTFile ] ) --> nHnd Parmetros Argumento cTXTFile Retorno Tipo Numrico Descrio A funo retorna o Handle de controle do arquivo. Em caso de falha de abertura, a funo retornar -1 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.

Descrio Abre ou fecha um arquivo texto para uso das funcoes FT_F* As funes FT_F* so usadas para para ler arquivos texto, onde as linhas so delimitadas pela sequncia de caracteres CRLF ou LF (*) e o tamanho mximo de cada linha 1022 bytes.. O arquivo aberto em uma rea de trabalho, similar usada pelas tabelas de dados. (*) Maiores detalhes sobre a especificao do arquivo na funo FT_FREADLN()

Sintaxe FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) --> nBytesEscritos Parmetros Argumento nHandle cBuffer 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 Numrico a partir da posiao corrente do ponteiro de arquivos. Caso seja omitido, todo o contedo de <cBuffer> escrito.

nQtdBytes Retorno Tipo Numrico

Descrio FWRITE() retorna a quantidade de bytes escritos na forma de um valor numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a operaao foi bem sucedida. Caso o valor de retorno seja menor que <nBytes> ou zero, ou o disco est cheio ou ocorreu outro erro. Neste caso , utilize a funo FERROR() para obter maiores detalhes da ocorrncia.

Descrio Voc pode escrever todo ou parte do contedo do buffer , limitando a quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da posio corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou criar um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou enviados os dados do buffer informado. Por tratar-se de uma funo de manipulao de contedo binrio , so suportados na String cBuffer todos os caracteres da tabela ASCII , inclusive

caracteres de controle ( ASC 0 , ASC 12 , ASC 128 , etc... ). Caso acontea alguma falha na gravao , a funo retornar um nmero menor que o nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do ponteiro , que pode ser ajustado atravs das funes FSEEK() , FREAD() ou FREADSTR().

Exemplo da funo FWRITE

Reviso: 27/05/2003 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Este exemplo realiza uma cpia de um arquivo Texto chamado ORIGEM.TXT , para um arquivo chamado DESTINO.TXT , no ambiente do Protheus Server.
#INCLUDE "FILEIO.CH" #DEFINE F_BLOCK 1024 / gravados por vez // Define o bloco de Bytes a serem lidos

User Function TestCopy() Local cBuffer := SPACE(F_BLOCK) Local nHOrigem , nHDestino Local nBytesLidos , nBytesFalta , nTamArquivo Local nBytesLer , nBytesSalvo Local lCopiaOk := .T. // Abre o arquivo de Origem nHOrigem := FOPEN("ORIGEM.TXT", FO_READ) // Testa a abertura do Arquivo If nHOrigem == -1 MsgStop('Erro ao abrir origem. Ferror = '+str(ferror(),4),'Erro') Return .F. Endif // Determina o tamanho do arquivo de origem nTamArquivo := Fseek(nHOrigem,0,2) // Move o ponteiro do arquivo de origem para o inicio do arquivo Fseek(nHOrigem,0) // Cria o arquivo de destino nHDestino := FCREATE("DESTINO.TXT", FC_NORMAL) // Testa a criao do arquivo de destino If nHDestino == -1 MsgStop('Erro ao criar destino. Ferror = '+str(ferror(),4),'Erro') FCLOSE(nHOrigem) // Fecha o arquivo de Origem

Return .F. Endif // Define que a quantidade que falta copiar o prprio tamanho do Arquivo nBytesFalta := nTamArquivo // Enquanto houver dados a serem copiados While nBytesFalta > 0 // Determina quantidade de dados a serem lidos nBytesLer := Min(nBytesFalta , F_BLOCK ) // l os dados do Arquivo nBytesLidos := FREAD(nHOrigem, @cBuffer, nBytesLer ) // Determina se no houve falha na leitura If nBytesLidos < nBytesLer MsgStop( "Erro de Leitura da Origem. "+; Str(nBytesLer,8,2)+" bytes a Str(nBytesLidos,8,2)+" bytes "Ferror =

LER."+;

Lidos."+; "+str(ferror(),4),'Erro') lCopiaOk := .F. Exit Endif

// Salva os dados lidos no arquivo de destino nBytesSalvo := FWRITE(nHDestino, cBuffer,nBytesLer) // Determina se no houve falha na gravao If nBytesSalvo < nBytesLer MsgStop("Erro de gravao do Destino. "+; Str(nBytesLer,8,2)+" bytes a SALVAR."+; Str(nBytesSalvo,8,2)+" bytes gravados."+; "Ferror = "+str(ferror(),4),'Erro') lCopiaOk := .F. EXIT Endif // Elimina do Total do Arquivo a quantidade de bytes copiados nBytesFalta -= nBytesLer Enddo // Fecha os arquivos de origem e destino FCLOSE(nHOrigem) FCLOSE(nHDestino) If lCopiaOk MsgStop('Cpia de Arquivos finalizada com sucesso. '+; str(nTamArquivo,12,0)+' bytes copiados.','Final') Else MsgStop( 'Falha na Cpia. Arquivo de Destino incompleto. '+; 'Do total de '+str(nTamArquivo,12,0)+'

bytes, faltaram '+str(nBytesFalta,12,0)+' bytes.','Final') Endif Return

Sintaxe GETCLIENTDIR ( ) --> cPath Retorno Tipo Caracter Descrio 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())

Descrio Retona o path onde est instalado o Protheus Remote.

Sintaxe GETREMOTEININAME ( ) --> cArqConf Retorno Tipo Caracter Descrio Retorna o nome do arquivo de configurao do AP Remote. Descrio Path e nome do arquivo de configurao

Exemplo das funes IsSrvUnix e GetRemoteIniName

Reviso: 12/06/2003 Abrangncia Verso 6.09 Verso 7.10 Verso 8.11

Atravs do exemplo abaixo, podemos obter o path de execuo do AP Remote.

#include "protheus.ch" Function TstRmtPath() Local cIniName:= GETREMOTEININAME() Local lUnix:= IsSrvUnix() Local nPos:= Rat( IIf(lUnix,"/","\"),cIniName ) Local cPathRmt if nPos!=0 cPathRmt:= Substr( cIniName,1,nPos-1 ) else cPathRmt:="" endif QOut( cPathRmt ) Return

Sintaxe GETSRVPROFSTRING ( < cChave > , < cDefault > ) --> cConteudo Parmetros Argumento cChave cDefault Retorno Tipo Caracter Descrio Descrio Conteudo da chave especificada Tipo Descrio Caracter Chave do INI do environment a ser lida, cDefault o conteudo da chave a ser retornado caso a chave Caracter no seja encontrada no .ini

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 Retorno Tipo Numrico 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

Tipo

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

Descrio Retorno zero ( 0 ),o diretrio foi criado com sucesso. Caso contrrio, houve erro na criao do diretrio.

Sintaxe MSCOMPRESS ( < cArq | aArquivos > , [ cDestino ] , [ cSenha ] ) --> cFileName Parmetros Argumento 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). cDestino Caracter Nome do Arquivo destino, caso a extenso seja omitida Tipo

cSenha Retorno Tipo Caracter

Caracter

ser assumido .MZP, se no for informado assumir o mesmo nome do cArq com extenso .MZP ou o nome do 1. Arquivo no Array <aArquivos>. Senha a ser utilizada para criptografar o arquivo compactado.

Descrio Caso a compactao seja executada com sucesso , a funo retornar uma sring contendo o nome do arquivo gerado . Caso no seja possvel a compactao , por falta de espao em disco ou erro de acesso a algum dos arquivos a ser(em) compactado(s), a funo retornar uma string em branco ("").

Descrio Compacta um ou vrios arquivos em um nico arquivo com extenso .MZP. MSCOMPRESS() compacta os arquivos informados em um nico arquivo com extenso default .MZP. O formato proprietrio e multiplataforma. Caso a senha seja informada apenas com a senha poderemos descompactar os arquivos. Tanto arquivos no local ( Remote ) como no Servidor so aceitos. Exemplos
// Exemplo 1 Compacta apenas um arquivo lRes := MSCOMPRESS( "AP6SRV.EXE", "AP6SRV.MZP" ) // Exemplo 2 Compacta um diretrio com senha aNome := {} ADIR( "*.DBF", aNome ) lRes := MSCOMPRESS( aNome, "ArqComp.MZP", "SENHA" )

Sintaxe MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess Parmetros Argumento cArq cPathDestino cSenha 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.

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 descompact-lo. Tanto arquivos no local ( Remote ) como no Servidor so aceitos. Sintaxe MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess Parmetros Argumento cArq 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". 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.

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 descompact-lo. Tanto arquivos no local ( Remote ) como no Servidor so aceitos. Sintaxe SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) --> NIL Parmetros Argumento cArq cDrive cCaminho cNome cExt Retorno Tipo Caracter 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 Descrio Esta funo sempre retorna NIL. Tipo Caracter Caracter Caracter Caracter Caracter Descrio Nome do Arquivo a ser quebrado. Opcionalmente, pode incluir caminho e drive. Nome do Drive. Exemplo ( C: ). Caso o Arquivo 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 caminho, ser uma string em branco. Nome do Arquivo sem a extenso. Caso em cArq no seja especificado um nome do Arquivo, ser retornada uma string em branco. Extenso do arquivo informado em cArq , prefizada com um ponto ".". Caso a extenso em cArq no seja especificada , o retorno ser uma string em branco.

No exemplo abaixo , exemplificamos o funcionamento da funo SplitPath , usando combinaes de nomes de arquivos com ou sem drive , caminho , nome de arquivo e/ou extenso.
User Function TSTSplit() Local aArq := {} , cDrive, cDir, cNome, cExt aadd(aArq,'c:\path\arquivo.ext') aadd(aArq,'c:\path\arquivo') aadd(aArq,'c:\path\') aadd(aArq,'c:\arquivo') aadd(aArq,'\path\arquivo.ext') aadd(aArq,'path\arquivo') aadd(aArq,'\\servidor\pasta\') aadd(aArq,'\\servidor\pasta\arquivo.ext') aadd(aArq,'') For nI := 1 to len(aArq) SplitPath( aArq[nI], @cDrive, @cDir, @cNome, @cExt ) conout( aArq[nI] + ' ['+cDrive+'] ['+ cDir +'] ['+ cNome +'] ['+ cExt + ']') Next

Aps executado o programa acima, deve ser exibido no console do Protheus Server o texto abaixo :
c:\path\arquivo.ext [c:] [\path\] [arquivo] [.ext] c:\path\arquivo [c:] [\path\] [arquivo] [] c:\path\ [c:] [\path\] [] [] c:\arquivo [c:] [\] [arquivo] [] \path\arquivo.ext [] [\path\] [arquivo] [.ext] path\arquivo [] [path\] [arquivo] [] \\servidor\pasta\ [] [\\servidor\pasta\] [] [] \\servidor\pasta\arquivo.ext [] [\\servidor\pasta\] [arquivo] [.ext] [] [] [] []

Sintaxe WRITEPPROSTRING ( < cSecao > , < cChave > , < cConteudo > , < cArqIni > ) --> lSucess Parmetros Argumento cSecao cChave cConteudo Tipo Descrio cSecao corresponde o nome da seo do ni a ser utilizada. Caracter 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. Caracter cConteudo corresponde o contedo da chave a ser

cArqIni

atualizado. cArqIni corresponde ao nome do arquivo de inicializao a ser alterado. Caso o arquivo no exista , ele ser criado . Caso o path do arquivo no seja informado , o mesmo ser Caracter criado/atualizado no diretrio onde est instalado o Protheus Server, no servidor. Caso especificado um path absoluto , com unidade de disco , o arquivo .ini ser criado e/ou atualizado na estao remota , no path informado.

Retorno Tipo Lgico Descrio Caso a chave seja incluida e/ou alterada com sucesso , a funo retornat .T. (true) , e caso ocorra alguma falha ou impossibilidade de acesso ao arquivo .ini , a funo retornar .F. (false). Dentre as causas mais comuns de falha , podemos citar erro de sintaxe no nome do arquivo e/ou path inexistente ou inacessvel.

Descrio Atravs da funcao WritePProString() , possvel criar e/ou alterar uma seo / chave de configurao em um arquivo .ini . Caso o arquivo no exista , o mesmo ser criado . No nome do arquivo , podemos opcionalmente definir um path absoluto , com unidade de disco , de modo que o arquivo .ini ser atualizado na estao remota ( onde est sendo executado o Protheus Remote ) . Caso no seja especificado nenhum path ou caminho do arquivo .ini , o caminho de disco considerado ser o path no Servidor onde est instalado o Protheus Server .

FUNO DE TRATAMENTO DE CARACTERES

Sintaxe ALLTRIM ( < cString > ) --> cTrimString Parmetros Argumento cString Retorno Tipo Caracter Descrio ALLTRIM() retorna uma cadeia de caracteres cujos espaos em branco direita e esquerda foram removidos. Tipo Descrio <cString> a expressao caractere cujos espaos em branco Caracter serao eliminados.

Descrio ALLTRIM() uma funo de tratamento de dados do tipo caractere que remove os espaos em branco direita e esquerda de uma cadeia de caracteres. relacionada a LTRIM() e RTRIM(), que removem espaos em branco esquerda e direita de uma cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres atravs da insero de caracteres de preenchimento. Sintaxe DESCEND ( < cString > ) --> cDescend Parmetros Argumento cString Retorno Tipo Caracter 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 Descrio DESCEND() retorna a string especificada como parmetro de uma forma complementada. Um DESCEND() de CHR(0) sempre retorna CHR(0). Tipo Descrio <cString> corresponde sequncia de caracteres a ser Caracter analisada.

Este exemplo utiliza DESCEND() em uma expressao INDEX para criar um ndice de datas de ordem descendente:
USE Sales NEW INDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate

Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice descendente:
DbSEEK(DESCEND(DTOS(dFindDate)))

Observao : Faz-se necessria a converso da Data para String m atravs da funo DTOS(), pois a funo DESCEND apenas trabalha com Strings. Sintaxe LTRIM ( < cString > ) --> cStringResult Parmetros Argumento 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 (""). Tipo Descrio <cString> a cadeia de caracteres a ser copiada sem os Caracter espaos em branco esquerda.

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 exp nTamanho Tipo 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 Retorno Tipo Caracter Descrio

Caracter

<cCaracPreench> o caractere a ser inserido em <exp>. Caso nao seja especificado, o padrao o espao em branco.

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

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 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 (""). Tipo Descrio <cString> a cadeia de caracteres a ser copiada sem os Caracter espaos em branco direita.

Descrio RTRIM() uma funao de tratamento de caracteres utilizada para Formatar cadeias de caracteres que contenham espaos em branco direita. Ela til quando voc deseja eliminar espaos em branco direita ao se concatenar cadeias de caracteres. o caso tpico com campos de banco de dados que sao armazenados em formato de tamanho fixo. Por exemplo, voc pode usar RTRIM() para concatenar o primeiro e o ltimo campos de nome para formar uma cadeia de caracteres de nome. LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a ALLTRIM(), que remove espaos em branco direita e esquerda. O contrrio de ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres, inserindo caracteres de preenchimento.

Sintaxe CDOW ( < dExp > ) --> cNomeDia Parmetros Argumento dExp 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 (""). Tipo Descrio Data <dExp> o valor data a ser convertido.

Descrio CDOW() uma funo utilizada para obter, a partir de uma data, a cadeia de caracteres contendo o dia da semana correspondente. Exemplos Os exemplos a seguir ilustram o funcionamento da funao CDOW():
conout( DATE() ) conout( CDOW(DATE()) ) conout( CDOW(DATE() + 7) ) conout( CDOW(CTOD("12/06/90")) ) // Resulta: 08/04/02 // Resulta: Sunday // Resulta: Sunday // Resulta: Thursday

Sintaxe CMONTH ( < dData > ) --> cMs Parmetros Argumento dData 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 (""). Tipo Descrio Data <dData> a data a converter.

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 Descrio DATE() retorna a data do sistema como sendo um valor do tipo data.

Retorna a data do sistema. DATE() a funo que retorna a data do atual sistema. O formato de sada controlado pelo comando SET DATE. O formato padro mm/dd/yy. Exemplos
conout( conout( conout( dDate = conout( DATE() ) DATE() + 30 ) DATE() - 30 ) DATE() CMONTH(dDate) ) // Resulta: 08/04/02 // Resulta: 09/03/02 // Resulta: 07/05/02 // Resulta: August

Sintaxe DAY ( < dData > ) --> nDia Parmetros Argumento dData 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. Tipo Descrio Data <dData> a data a converter.

Descrio Retorna o dia do ms como valor numrico. DAY() uma funao de conversao de datas utilizada para converter um valor do tipo data para o dia do ms correspondente. Esta funo usada em conjunto com CMONTH() e YEAR() para formatar datas. Alm disso, geralmente usada em clculos que envolvam datas. Exemplos Os exemplos seguintes mostram a funao DAY() sendo utilizada de diversas maneiras:
conout( conout( conout( conout( DATE() ) DAY(DATE()) ) DAY(DATE()) + 1) DAY(CTOD("")) ) // Resulta: 09/01/90 // Resulta: 1 // Resulta: 2 // Resulta: 0

Este exemplo utiliza DAY() em conjunto com CMONTH() e YEAR() para formatar um valor do tipo data:
conout( CMONTH(DATE()) + STR(DAY(DATE())) +; "," + STR(YEAR(DATE())) ) // Resulta: June 15, 1990

Sintaxe DOW ( < dData > ) --> nDia Parmetros Argumento dData Retorno Tipo Numrico 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

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

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.

A seguir est uma funao definida por usurio que utiliza DOW() para calcular a data da ltima segunda-feira a partir de qualquer outra data:
USER FUNCTION LastMonday(dData) Return (dData - DOW(dData) + 2)

Sintaxe DTOC ( < dData > ) --> cData Parmetros Argumento dData 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. Tipo Descrio Data <dData> o valor data que ser convertido.

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 Caracter Descrio 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 cHoraInicial cHoraFinal Retorno Tipo Descrio 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 hora Caracter ( 1 a 24 ), mm os minutos e ss os segundos.

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

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 Retorno Tipo Numrico 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 Descrio MONTH() retorna um valor numrico inteiro na faixa de 0 (zero) a 12. Uma data nula (CTOD("")) retorna zero. Tipo Descrio Data <dData> o valor data a ser convertido.

na forma de valores numricos. O grupo inclui DAY() e YEAR(), que retornam os valores de dia e ano na Forma de nmericos. CMONTH() uma funao relacionada, que permite a voc retornar o nome do ms a partir de um valor data. Exemplos Estes exemplos ilustram o retorno do ms da data do sistema:
conout( DATE() ) conout( MONTH(DATE()) ) conout( MONTH(DATE()) + 1 ) // Resulta: 09/01/90 // Resulta: 9 // Resulta: 10

Este exemplo demonstra a funao MONTH() atuando em uma data nula:

conout( MONTH(CTOD("")) ) // Resulta: 0

Sintaxe SECONDS ( ) --> nSegundos Retorno Tipo Numrico Descrio SECONDS() retorna a hora do sistema como um valor numrico na forma segundos.centsimos. O valor numrico retornado a quantidade de segundos decorridos desde a meia-noite, e tem base em um relgio de vinte e quatro horas em uma faixa de zero a 86399.

Descrio SECONDS() uma funao de horas utilizada para fornecer um mtodo simples de calcular o tempo decorrido, com base no relgio do sistema, durante a execuao do programa. relacionado funao TIME(), a qual retorna a hora do sistema como uma cadeia de caracteres na forma hh:mm:ss. Exemplos Este exemplo compara o valor de TIME() com o de SECONDS():
conout( TIME() ) conout( SECONDS() ) // Resulta: 10:00:00 // Resulta: 36000.00

Este exemplo demonstra como utilizar SECONDS() para informar o tempo decorrido em segundos:
LOCAL nStart, nElapsed nStart = SECONDS() . . <processamentos...etc....> . nElapsed = SECONDS() - nStart conout( "Decorridos: " + LTRIM(STR(nElapsed)) + " segundos" )

Sintaxe TIME ( ) --> cStringHora Retorno Tipo Caracter Descrio TIME() retorna a hora do sistema como uma cadeia de caracteres na forma hh:mm:ss. hh indica a hora no formato de 24 horas, mm indica os minutos, e ss indica os segundos. Horas, minutos e segundos sao separadas por dois pontos.

Descrio TIME() uma funao de tratamento de tempo, utilizada para exibir ou imprimir a hora do sistema em um relatrio ou na tela. TIME() est relacionada a SECONDS(), que retorna a quantidade de segundos decorridos desde a meia-noite. SECONDS() geralmente utilizada em lugar de TIME() para clculos sobre o tempo. Exemplos Estes exemplos mostram a funo TIME() utilizada em conjunto com SUBSTR() para extrair a hora, os minutos e os segundos:
cTime := TIME() // Resultado: 10:37:17 cHora := SUBSTR(cTime, 1, 2) // Resultado: 10 cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37 cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17

Sintaxe YEAR ( < dData > ) --> nAno Parmetros

Argumento dData Retorno Tipo Numrico

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

Descrio YEAR() retorna o ano do valor data especificado, inclusive dgitos indicativos de sculo, na forma de um valor numrico de quatro dgitos. O valor retornado nao influenciado pelo formato de DATE ou CENTURY corrente. A especificaao de uma data nula (CTOD("")) retorna zero.

Descrio YEAR() uma funao de conversao de datas utilizada para converter um valor data para um valor numrico indicativo do ano. Pode ser utilizada em clculos de, por exemplo, relatrios peridicos, ou para Formataao de exibioes de data. YEAR() membro de um grupo de funoes que retornam componentes de um valor data na forma de valores numricos. Este grupo inclui DAY() e MONTH(), que retornam valores de dia e ms na forma de valores numricos. Exemplos Os exemplos a seguir ilustram YEAR() usando a data do sistema:
conout( DATE() ) conout( YEAR(DATE()) ) conout( YEAR(DATE()) + 11 ) // Resulta: 09/01/90 // Resulta: 1990 // Resulta: 2001

Este exemplo cria uma funao definida pelo usurio usando YEAR() para formatar um valor data na forma : ms dia, ano:
conout( U_Mdy(DATE()) ) 1990 // Resulta: September 20,

USER FUNCTION Mdy( dDate ) Return CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))); + "," + STR(YEAR(dDate))

FUNES DE TRATAMENTO DE MATRIZ

Sintaxe AADD ( < aDestino > , [ expValor ] ) --> Valor

Parmetros Argumento aDestino expValor Retorno Tipo (Qualquer) 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>. Descrio Avalia expValor e retorna seu Valor. Se expValor no for especificado, AADD() retorna NIL. Tipo Array Descrio o array ao qual o novo elemento ser adicionado. uma expresso vlida que ser o valor do (Qualquer) novo elemento.

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 }) 10 } } // // // // Resulta: Resulta: Resulta: Resulta: aArray aArray aArray aArray e e e e um vetor vazio { 5 } { 5, 10 } { 5, 10, { 12,

Sintaxe ACLONE ( < aFonte > ) --> aDuplica Parmetros

Argumento aFonte Retorno Tipo Array Descrio

Tipo Descrio Array <aFonte> o vetor a ser duplicado.

Descrio Array idntico ao aFonte , porem sem nenhuma referncia ao mesmo.

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

nCont

nPosDestino Retorno Tipo Array

Descrio ACOPY() retorna uma referncia ao vetor destino, <aDestino>.

Descrio ACOPY() uma funao de tratamento de vetor que copia elementos do vetor <aFonte> para o vetor <aDestino>. O vetor <aDestino> j deve existir e ser grande o suficiente para conter os elementos copiados. Caso o vetor <aFonte> tenha mais elementos, alguns elementos nao serao copiados. ACOPY() copia valores de todos os tipos de dados, inclusive NIL e blocos de cdigo. Se um elemento do vetor <aFonte> for um sub-vetor, o elemento correspondente no vetor <aDestino> conter uma referncia ao sub-vetor. Consequentemente, ACOPY() nao cria duplicatas completas de vetores multi-dimensionais. Para fazer isto, use a funao ACLONE(). Exemplos Este exemplo cria dois vetores, cada um deles preenchido com um valor. Os dois primeiros elementos do vetor fonte sao entao copiados para o vetor destino:
LOCAL nCount := 2, nStart := 1, aOne, aTwo aOne := { 1, 1, 1 } aTwo := { 2, 2, 2 } ACOPY(aOne, aTwo, nStart, aCont) // Resulta: aTwo e agora { 1, 1, 2 }

Sintaxe ADEL ( < aFonte > , < nPosicao > ) --> aFonte Parmetros Argumento aFonte nPosicao Retorno Tipo Array Descrio ADEL() uma funao de tratamento de vetor que elimina um elemento de um vetor. O contedo do elemento de vetor especificado perdido, e todos os elementos a partir daquela posiao at o final do elemento sobem uma posiao. O ltimo elemento no vetor torna-se NIL. Descrio ADEL() retorna uma referncia ao vetor destino, <aFonte>. 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.

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

// Resulta: aArray e agora { 1, 2, 3 } // Resulta: aArray e agora { 1, 3,

Sintaxe AEVAL ( < aVetor > , < bBloco > , [ nInicio ] , [ nCont ] ) --> aVetor Parmetros Argumento aVetor bBloco nInicio nCont Retorno Tipo Array Descrio AEVAL() uma funao de tratamento de vetor que avalia um bloco de cdigo uma vez para cada elemento de um vetor, passando o valor do elemento como um parmetro de bloco. O valor de retorno do bloco ignorado. Todos os elementos no <aVetor> sao processados a nao ser que o argumento <nInicio> ou <nCont> seja especificado. AEVAL() nao faz suposioes sobre o contedo dos elementos de vetor que ele est Descrio AEVAL() retorna uma referncia a <aVetor>. Tipo Array Descrio <aVetor> o vetor a ser varrido. <bBloco> um bloco de cdigo a ser executado para cada Code-Block elemento encontrado. <nInicio> o elemento inicial. Caso nao seja especificado, Numrico o padrao assumido o elemento um. <nCont> a quantidade de elementos a serem processados Numrico a partir de <nIncio>. Se nao for especificado, o padrao todos os elementos no vetor.

passando para o bloco. assumido que o bloco sabe qual o tipo de dados haver em cada elemento. AEVAL() semelhante a DBEVAL(), que aplica um bloco para cada registro de um arquivo de banco de dados. Da mesma forma que DBEVAL(), AEVAL() pode ser utilizado como base para a construao de comandos de interaao tanto para estruturas de vetor complexas como simples. Consulte a seao Blocos de Cdigo no na seo A Linguagem Advpl para maiores informaes sobre Code-Blocks. Exemplos
Local aArray := { "Teste" , 123 } Local bBlock := { |x,y| conout(valtype(x)) , conout(y) } aEval(aArray,bBlock)

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

// Podemos realizar a totalizao pelo metodo tradicional :

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

// Ou utilizando a Funco aEval :

nTotal := 0 aeval(aItens , {|x| nTotal += x[2] } ) conout(nTotal)

Sintaxe AFILL ( < aDestino > , < ValorExp > , [ nInicio ] , [ nCont ] ) --> aDestino Parmetros Argumento aDestino ValorExp nInicio 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 argumento for Numrico omitido, os elementos sao preenchidos a partir da posiao do elemento inicial at o final do vetor.

nCont

Retorno Tipo Array Descrio AFILL() uma funao de vetor que preenche um vetor especificado com um nico valor de qualquer tipo de dados (inclusive vetores, blocos de cdigo ou NIL) atribuindo <ValorExp> a cada elemento de vetor na faixa especificada. ATENO : AFILL() nao pode ser utilizado para preencher vetores multi-dimensionais. Este tipo de vetores em Clipper sao implementados aninhando-se vetores dentro de outros Descrio AFILL() retorna uma referncia ao <aDestino>.

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 Retorno Tipo Array Descrio AINS() uma funo de vetor que insere um novo elemento em um vetor especificado. O elemento recm inserido NIL at que um novo valor seja atribuido a ele. Aps a insero, o ltimo elemento no vetor descartado, e todos os elementos depois do novo elemento descem uma posio. AVISO : AINS() deve ser utilizado com cuidado quando se tratar de vetores multidimensionais. Vetores multi-dimensionais em Advpl sao implementados atravs do aninhamento de vetores dentro de outros vetores. Utilizar AINS() com um vetor multidimensional descarta o ltimo sub-vetor no vetor destino especificado, o que causa a perda de uma ou mais dimensoes. Para inserir uma nova dimensao em um vetor, primeiramente adicione um novo elemento ao final do vetor utilizando AADD() ou ASIZE() antes de usar AINS(). Exemplos Este exemplo demonstra o efeito da utilizao de AINS() em um vetor: Descrio Retorna uma referncia ao vetor aDestino 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

LOCAL aArray aArray := { 1, 2, 3 } AINS(aArray, 2) 2 }

// Resulta: aArray e agora { 1, 2, 3 } // Resulta: aArray e agora { 1, NIL,

Sintaxe ARRAY ( < nElementos,... > ) --> aVetor Parmetros Argumento nElementos,... Retorno Tipo Array Descrio ARRAY() uma funao de tratamento de vetor que retorna um vetor nao inicializado com a quantidade especificada de elementos e dimensoes. Se for especificado mais de um argumento <nElementos>, criado um vetor multi-dimensional ou aninhado, sendo que a quantidade de dimensoes igual quantidade de argumentos <nElementos> especificada. No Advpl, h vrias formas de se criar um vetor. Voc pode declarar um vetor utilizando LOCAL ou STATIC; voc pode criar um vetor utilizando PRIVATE ou PUBLIC; voc pode atribuir um vetor literal a uma varivel existente; ou voc pode usar a funao ARRAY(). ARRAY() tem a vantagem de possibilitar a voc a criaao de vetores dentro de expressoes ou blocos de cdigo. Exemplos Este exemplo cria um vetor unidimensional de cinco elementos utilizando a funao ARRAY(), e depois exibe a aao equivalente atribuindo um vetor literal de valores NIL:
aArray := ARRAY(5) aArray := { NIL, NIL, NIL, NIL, NIL }

Tipo

Descrio <nElementos> a quantidade de elementos na dimensao Numrico especificada.Os vetores em Advpl podem ter um nmero ilimitado de dimensoes.

Descrio ARRAY() retorna um vetor de dimensoes especificadas.

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 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> seja um valor (Qualquer) 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.

nInicio

nCont

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

Numrico

Descrio ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai para o prximo elemento no vetor. Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente igual ao resultado de <ProcuraExp> para que haja correspondncia.

Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor <aDestino> executando o bloco para cada elemento acessado. medida em que cada elemento encontrado, ASCAN() passa o valor do elemento como um argumento para o bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo elemento no vetor. Exemplos O exemplo a seguir demonstra a pesquisa em um vetor de trs elementos utilizando valores simples e um bloco de cdigo como critrios de pesquisa. Os critrios do bloco de cdigo ilustram como executar uma pesquisa que nao faz diferenciaao entre maisculas e minsculas:
aArray := { "Tom", "Mary", "Sue" } ? ASCAN(aArray, "Mary") ? ASCAN(aArray, "mary") ? ASCAN(aArray, { |x| UPPER(x) == "MARY" })

// Resulta: 2 // Resulta: 0 // Resulta: 2

O Exemplo abaixo demonstra como continuar a pesquisa dos mltiplos tipos de um argumento de pesquisa aps ter sido encontrada uma correspondncia:
LOCAL aArray := { "Tom", "Mary", "Sue", "Mary" }, nStart := 1 // Pegar ultima posicao de elemento de vetor nAtEnd := LEN(myVetor) While (nPos := ASCAN(aArray, "Mary", nStart)) > 0 ? nPos, aArray[nPos] // Pegar nova posicao inicial e testar condicao de limite If (nStart := ++nPos) > nAtEnd EXIT EndIf EndDo

Sintaxe ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm Parmetros Argumento aDestino ProcuraExp nInicio 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> seja um valor (Qualquer) simples, este poder ser do tipo numrico, lgico, data, ou caractere. Numrico <nInicio> o elemento a partir do qual ter incio a pesquisa. Se este argumento nao for especificado, a posiao

nCont

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

Numrico

Descrio ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai para o prximo elemento no vetor. Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente igual ao resultado de <ProcuraExp> para que haja correspondncia. Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor <aDestino> executando o bloco para cada elemento acessado. medida em que cada elemento encontrado, ASCAN() passa o valor do elemento como um argumento para o bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo elemento no vetor. Exemplos O exemplo a seguir demonstra a pesquisa em um vetor de trs elementos utilizando valores simples e um bloco de cdigo como critrios de pesquisa. Os critrios do bloco de cdigo ilustram como executar uma pesquisa que nao faz diferenciaao entre maisculas e minsculas:
aArray := { "Tom", "Mary", "Sue" } ? ASCAN(aArray, "Mary") ? ASCAN(aArray, "mary") ? ASCAN(aArray, { |x| UPPER(x) == "MARY" })

// Resulta: 2 // Resulta: 0 // Resulta: 2

O Exemplo abaixo demonstra como continuar a pesquisa dos mltiplos tipos de um argumento de pesquisa aps ter sido encontrada uma correspondncia:
LOCAL aArray := { "Tom", "Mary", "Sue", "Mary" }, nStart := 1 // Pegar ultima posicao de elemento de vetor nAtEnd := LEN(myVetor) While (nPos := ASCAN(aArray, "Mary", nStart)) > 0 ? nPos, aArray[nPos] // Pegar nova posicao inicial e testar condicao de limite If (nStart := ++nPos) > nAtEnd EXIT EndIf EndDo

Parmetros Argumento destino procura nInicio Tipo (Qualquer) (Qualquer) Numrico Descrio Representa o objeto a ser varrido pela funo, pode ser atribuido ao parametro um array um Objeto. Representa o valor que ser pesquisado, podendo ser um bloco de cdigo. Representa o elemento a partir do qual ter inicio a 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 argumento nao for informado todos elementos do array sero pesquisados

nCont

Numrico

Retorno Tipo Numrico 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}) 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.

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 Retorno Tipo Array Descrio ASIZE() uma funo de tratamento de vetor que muda o valor real do vetor <aDestino>. O vetor diminuido ou aumentado para corresponder ao tamanho especificado. Caso o vetor seja diminuido, os elementos no final do vetor sao perdidos. Se o vetor for aumentado, novos elementos sao adicionados ao final do vetor e a eles atribuido NIL. ASIZE() semelhante a AADD(), o qual adiciona somente um novo elemento ao final de um vetor e opcionalmente atribui um novo valor ao mesmo tempo. Observe que ASIZE() diferente de AINS() e ADEL(), os quais na realidade nao modificam o tamanho do vetor. Exemplos Estes exemplos demonstram a adio de novos elementos e a eliminao de elementos existentes:
aArray := { 1 } // Resulta: aArray e { 1 }

Tipo Descrio Array <aDestino> o vetor a ser aumentado ou diminuido. Numrico <nTamanho> o novo tamanho do vetor.

Descrio Retorna uma referncia ao array aDestino.

ASIZE(aArray, 3) ASIZE(aArray, 1)

// Resulta: aArray e { 1, NIL, NIL } // Resulta: aArray e { 1 }

Sintaxe ASORT ( < aDestino > , [ nInicio ] , [ nCont ] , [ bOrdem ] ) --> aDestino Parmetros Argumento aDestino nInicio nCont Tipo Descrio <aDestino> o vetor cujos elementos serao colocados em Array ordem. <nInicio> o primeiro dos elementos que serao colocados Numrico em ordem. Caso nao seja especificada, a posiao inicial assumida um. <nCont> a quantidade de elementos que serao colocados Numrico em ordem. Se nao for especificada, todos os 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.

bOrdem

Retorno Tipo Array Descrio ASORT() uma funao de vetor que coloca em ordem todo ou parte de um vetor que contm elementos de um nico tipo de dados. Os tipos de dados que podem ser ordenados incluem caractere, data, lgico e numrico. Se o argumento <bOrdem> nao for especificado, a ordem padrao ascendente. Elementos com valores baixos sao colocados no incio do vetor (primeiro elemento), enquanto elementos com valores altos sao colocados no final do vetor (ltimo elemento). Caso o argumento de bloco <bOrdem> seja especificado, ele utilizado para determinar a ordem em que os elementos serao colocados. Cada vez que o bloco avaliado, dois elementos do vetor destino sao passados como parmetros de bloco. O bloco deve retornar verdadeiro (.T.) se os elementos estiverem ordenados. Isto pode ser usado para criar uma ordem descendente ou de dicionrio. Veja os exemplos abaixo. Quando ordenadas, as cadeias de caracteres sao colocadas na sequncia ASCII; valores lgicos sao ordenados com falso (.F.) sendo considerado o valor menor; valores data sao ordenados cronologicamente; e numricos sao ordenados por magnitude. Descrio ASORT() retorna uma referncia ao vetor <aDestino>.

OBSERVAO : Sendo os vetores multi-dimensionais em Clipper implementados atravs do aninhamento de sub-vetores dentro de outros vetores, ASORT() nao ordena diretamente vetores deste tipo. Para ordenar um vetor aninhado, voc deve fornecer um bloco de cdigo que dar o tratamento adequado aos sub-vetores. Exemplos No Exemplo abaixo , ordenamos um array em ordem crescenter , depois em ordem decrescente atravs de um code-block .
Local aArray := { 3, 5, 1, 2, 4 } ASORT(aArray) // Resultado: { 1, 2, 3, 4, 5 } ASORT(aArray,,,{ |x, y| x > y }) // Resultado: { 5, 4, 3, 2, 1 }

No Exemplo abaixo , utilizamos na expresso de ordenao a funo upper() , para ordenar o array em ordem alfabrica independentemente da informao estar em letras maisculas e/ou minusculas.
aArray := { "Fred", Kate", "ALVIN", "friend" } ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) })

No exemplo abaixo , montamos um code-block para ordenao de um array multidimensional , para ordenar o array em ordem crescente do segundo elemento da dimenso.
aKids := { {"Mary", 14}, {"Joe", 23},{"Art", 16} } aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] }) // Resultado : { {"Mary", 14}, {"Art", 16}, {"Joe",23} }

Sintaxe ATAIL ( < aArray > ) --> Ret Parmetros Argumento aArray Retorno Tipo (Qualquer) Descrio Retorna ltima ocorrencia ou o ltimo elemento do array. Tipo Descrio Array Representa o array a ser informado para a funo.

Descrio A funo tem o objetivo de retornar a ltima ocorrncia do array informado pelo argumento <aArray>, caso o argumento Array passado esteja vazio a funo ir retornar NIL. Se for informado um argumento que no for um Array para a funo, isto ir causar um um erro ADVPL.

Ex: user function tstArray() Local aArray := {'ola', 'ops', 'oq', 'aff', 'oljha'} Local cRet cRet := atail(aArray) //retorna oljha return cRet

FUNES TRATAMENTO XML

Sintaxe XmlChildCount ( < oParent > ) --> nChild Parmetros Argumento oParent Retorno Tipo Numrico Descrio A funo tem o objetivo de retornar a quantidade de ns existentes, a partir de um nodo pai informado como argumento. Descrio Retorna o numero de elementos encontrados. Tipo Descrio Indica o node XML no qual ele ir fazer a contagem dos Objeto filhos.

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 OParent cProcura Retorno Tipo (Qualquer) Descrio A funo tem o objetivo de retornar um ou mais filhos da estrutura, de acordo com o nome do elemento procurado. Especificando um elemento qualquer do objeto para a funo, na qual ser usado como base para busca apenas em seu primeiro sub-nvel a funo ir retornar todos os nodos filhos que encontar. til quando quando queremos buscar por um elemento filho e exista mais de um elemento do mesmo tipo. 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. Tipo Descrio Nodo usado para indicar o inicio da procura do elemento Objeto requerido. Caracter Representa o nome do elemento que desejamos encontrar.

Sintaxe XmlCloneNode ( < oParent > , < cNewName > ) --> Nil Parmetros Argumento oParent Tipo Descrio Objeto Representa o objeto node XML no qual ser colando

cNewName Retorno Tipo (NULO) Descrio

Caracter Indica o nome no qual ser atribuido o node clonado

Descrio Nil

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 cNode Retorno Tipo (NULO) 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. Descrio Nil Tipo Descrio Objeto Representa o Node pai do elemento que ser removido. Representa o Real name do elemento node que ser Caracter removido.

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") 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 cScript cScript cScript cScript cScript Return cScript

+= += += += += +=

" <Produto>ERP<Produto>" " <Quantidade>0</Quantidade>" " <Preco>0</Preco>" " </Item>" " </Itens>" "</pedido>"

Sintaxe XmlGetChild ( ) --> Nil Retorno Tipo (NULO) Descrio A funo tem o objetivo de retornar um elemento filho da estrutura. Especificando um elemento qualquer do objeto para a funo, na qual ir usar como base para retornar o nodo filho de nmero indicado pelo segundo parametro passado para a funo. til quando queremos mudar o posicionamento do objeto, para algum nodo filho do atual na estrutura do objeto XML. No Exemplo seguinte usamos a funo para nos posicionar no nodo <itens>, em seguida apagamos todos os nodos filhos com a xmlDelNode. Usando o comando SAVE criamos um arquivo teste.xml ao final da execuo do programa.
#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 )

Descrio Nil

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

Sintaxe XmlGetParent ( < oNode > ) --> oParent Parmetros Argumento oNode Retorno Tipo Objeto Descrio Um objeto posicionado no node de acordo com o argumento passado. Tipo Descrio representa o node no qual ser usado como referncia para o Objeto retorno do node pai.

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 Retorno Tipo Objeto Descrio A funo tem o objetivo de criar um novo nodo a partir de um ponto qualquer no xml. Para isto necessrio informar em qual ponto do objeto xml(o xml parseado) que desejamos adicionar um novo elemento. O novo nodo ser adicionado como filho do nodo passado por parametro, onde sero informados tambm os dados em relao a ele: -REALNAME -ELEMENTNAME -TYPE (para entender melhor o funcionamento da funo veja o exemplo) Exemplos Neste exemplo criamos o xml atravs da funo GeraXML, parseamos ele atravs da xmlParser retornando o objeto xml. Em seguida visualizamos o objeto retornado e usamos a funao xmlChildCount retornando a quantidade de elementos no objeto contendo o xml. No Nosso exemplo a funo ir retornar 5 elementos. Descrio Nil Tipo Objeto Caracter Caracter Caracter Descrio Indica o local onde ser inserido o novo node XML. o nome do elemento Node no XML o nome Real do Node XML Representa o tipo de node XML que ser criado

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 ) ) // 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 oRoot cNode2Array Retorno Tipo Lgico Descrio A funo tem o objetivo de transformar em array, um objeto(node) da estrutura do xml. Informando um elemento(node) da estrutura XML atravs de parametro como raiz, a funo ir procurar pelo nome do nodo no qual se deseja transformar em array. Exemplos No exemplo seguinte demonstrado o simples uso da funo XmlNode2Arr, em que pegamos o objetoXml e o tranformamos em um array. Em seguida gravamos esse objeto em arquivo .xml propriamente dito.
#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" )

Tipo

Descrio Elemento Node no qual ser usado como root para inicio da Objeto busca do elemento a ser tranformado em array. Representa o elemento procurado para ser transformado em Caracter array na estrutura.

Descrio Retorna true caso consiga transformar em array, false caso contrrio.

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

Sintaxe XmlParser ( < cXml > , < cReplace > , < @cError > , < @cWarning > ) --> oXML Parmetros Argumento cXml cReplace cError cWarning Retorno Tipo Objeto Descrio Representa um objeto com a estrutura de acordo com o XML. 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.

Descrio A funo tem o objetivo de retornar um objeto que possu uma estrutura referente ao xml, passado pelo parametro na funo. A estrutura retornada: <ObjXML> <NodeXML> -<ArrayNodes> -REALNAME -TEXT -TYPE Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem. A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do mesmo tipo. (demonstrado no exemplo) Exemplos Neste exemplo criamos uma funo geraXml que retorna uma string contento um XML. Quando passamos essa string para a XmlParser, a funo ir montar o objeto analisando se a sintaxe e a ordem das tags est bem formada, caso isso nao ocorra a funo ir retonar um warning ou at um possvel erro, nos parametros informados por referncia. A estrutura: oXml: pedido: -realName -type -text nome_cliente: -realName -type -text endereo: -realName -type -text numero: -realName -type -text data: -realName -type -text itens:

-item <- (array) -item[1]: -realName -type -text produto: quantidade: preco: -item[2] -realName -type -text produto: quantidade: preco: -realName -type -text

Caso isso nao ocorra a funo ir retornar o objeto contendo uma estrutura em forma de arvore, no caso a mesma estrutura do xml.
#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 ) //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 cFile cReplace cError cWarning Retorno Tipo Objeto Descrio A funo tem o objetivo de retornar um objeto que possu uma estrutura referente ao arquivo .xml, passado pelo parametro na funo. A estrutura retornada: <ObjXML> <NodeXML> -<ArrayNodes> -REALNAME -TEXT -TYPE Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem. A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do mesmo tipo. (demonstrado no exemplo) Exemplos Neste exemplo vamos usar a funo que tem o mesmo objetivo da XmlParser, a diferena que esta l um arquivo do disco com a extenso .xml. Quando passamos a string informando o path do arquivo em disco, devemos lembrar que a procura do arquivo ser feita atravs do rootpath do Protheus. logo aps a leitura do arquivo a funo ir montar o objeto analisando se a sintaxe e a ordem das tags est bem formada, caso isso no ocorra a funo ir retonar um warning ou at um possvel erro, nos parametros informados por referncia. Descrio Retorna um objeto q contm uma estrutura de acordo com o XML. Tipo Caracter Caracter Caracter Caracter Descrio Representa o path de um arquivo .xml, indicando o local onde se encontra o arquivo no disco. Representa o valor a ser atribuido para os caracteres de espao encontrados na especificao dos nodes XML. cError Caracter Caso ocorra algum erro durante execuo da funo, a varivel ser preenchida com a descrio do erro ocorrido. cWarning Array Caso ocorra algum alerta de 'warning' durante execuo da funo, a varivel ser preenchida com a descrio do 'warning' ocorrido.

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 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) ou invlido correto // pode ser falso

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) // 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 prefixla com :: ( dois sinais de 2 pontos ) Ao declarar um objeto utilizando o construtor da classe , utilizamos a sintaxe : oObjeto := NomeDaClasse():Metodo_Contrutor(). Para acessar uma propriedade deste objeto , utilizamos oObjeto:Propriedade , e para acessar um mtodo da classe aplicvel a este objeto , utilizamos oObjeto:Metodo( parametros,... )

PALAVRAS RESERVADAS

Lista de Palavras Reservadas

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

Novas Palavras Reservadas

A partir das verses Protheus Ap5 - Build 7.00.030702 , Ap6 - Build 7.00.030702 e Ap7 - Build 7.00.030702 , as palavras abaixo passaram a ser reservadas:

TRY

AS

CATCH

THROW

Notas:

Palavras reservadas no podem ser utilizadas para variveis, procedimentos, ou funes. Funes reservadas so pertencentes ao compilador e portanto no podem ser redefinidas por uma aplicao. Abreviaes de quatro letras de palavras reservadas e funes tambm so reseravdas. Todos os identifadores que comearem com um ou mais caracters de sublinhado (_) so utilizados como identificadores internos e portanto so tambm reservados.

TABELAS DE PICTURES DE FORMATAO

Comando SAY/PSAY
Funes
Conteudo C E R X Z ( ! Funcionalidade Exibe CR depois de nmeros positivos Exibe numricos com o ponto e a vrgula invertidos (formato Europeu) Insere caracteres diferentes dos caracteres de template Exibe DB depois de nmeros negativos Exibe zeros como brancos Envolve nmeros negativos entre parnteses Converte todos os carecteres alfabticos para maisculo

Templates
Conteudo X 9 # ! * . Funcionalidade Exibe dgitos para qualquer tipo de dado 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 A C E R S<n> X Z ( ) ! Funcionalidade Permite apenas caracteres alfabticos Exibe CR depois de nmeros positivos Exibe numricos com o ponto e vrgula invertidos (formato Europeu) Insere caracteres diferentes dos caracteres de template na exibio mas no insere-os na varivel do GET Permite rolamento horizontal do texto dentro do GET, <n> um nmero inteiro que identifica o tamanho da regio Exibe DB depois de nmeros negativos 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

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

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:
cVar := Replicate( "*", 80 )

Este tipo de programao deixa o cdigo fcil de digitar, fcil de ler e mais flexvel.

Utilizao de Solues Simples

Simplicidade na criao de instrues torna a programao e at mesmo a execuo mais rpida. Considere a linha de cdigo:
If nVar > 0 .Or. nVar < 0

Se o valor da varivel nVar for igual a zero (0) no momento da execuo desta linha de cdigo, ambas as comparaes separadas pelo operador lgico .Or. sero efetuadas: Aps ser avaliada, a primeria comparao ir falhar. A segunda comparao ser ento avaliada e falhar tambm. Como resultado, o cdigo existente dentro da estrutura de fluxo If no ser executado. Tal cdigo somente ser executado quando o valor desta varivel for maior OU menor do que zero. Ou seja, sempre que for DIFERENTE de zero, o que torna a linha a seguir mais eficiente:
If nVar != 0

Este tipo de alterao torna o cdigo mais legvel e o processamento mais rpido, evitando a avaliao de instrues desnecessariamente. Existem outras situaes onde a simplificao pode ser utilizada. A expresso de avaliao a seguir:
If cVar == "A" .Or. cVar == "B" .Or ; cVar == "C" .Or. cVar == "D"

Pode ser substitudo pelo operador de conteno:

If cVar $ "ABCD"

Opo por Flexibilidade

A melhor soluo aquela que envolve o problema imediato e previne problemas no futuro. Considere o exemplo:
@nRow,nCol PSAY cVar Picture "!!!!!!!!!!!!!!!!!!!!"

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

Opo da Praticidade ao Drama

Se a soluo parece complexa, provavelmente porque o caminho escolhido est levando a isso. Deve-se sempre se perguntar porque algum desenvolveria uma linguagem que requisite tantos comandos complicados para fazer algo simples. Na grande maioria dos casos, existe uma soluo mais simples. O exemplo abaixo deixa isso bem claro:

@ 10,25 Say Substr(cCep,1,5) + "-" + Substr(cCep,6,3) Picture "!!!!!!!!!"

Que pode ficar mais simples assim:

@ 10,25 Say cCep Picture "@R 99999-999"

Utilizao de Operadores de Incremento/Decremento

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

Pode-se escrev-las assim:

++nVar --nVar

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

Evitar Passos Desnecessrios

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

<cdigo> Next nCnt

Inicializar a varivel no momento da declarao no um problema. Se o 0 fosse necessrio no exemplo, teria sido til a inicializao na declarao. Mas neste caso a estrutura de repetio For... Next atribui o seu valor imediatamente com 1, portanto no houve ganho em atribuir a varivel com 0 no comeo. Neste exemplo no h nenhum ponto negativo e nada errado ocorrer se a varivel no for inicializada, portanto aconselhvel evitar este tipo de inicializao, pois no torna o cdigo mais seguro e tambm no expressa a inteno do cdigo mais claramente. Porm note este exemplo, onde a varivel no inicializada:
Local nCnt While ( nCnt++ < 10 ) <cdigo> EndDo

Em AdvPl, variveis no inicializadas sempre tem seu valor contendo nulo (nil) a princpio, o que far com que uma exceo em tempo de execuo acontea quando a instruo de repetio while for executada. Diferentemente do primeiro exemplo, onde a inicializao da varivel no fazia diferena alguma, neste segundo exemplo a inicializao absolutamente necessria. Deve-se procurar inicializar variveis numricas com zero (0) e variveis caracter com string nula ("") apenas quando realmente necessrio. Utilizao de Alternativas Quando se est trabalhando em uma simples rotina, deve-se tomar algum tempo para explorar duas ou trs diferentes abordagens. Quando se est trabalhando em algo mais complexo, deve-se planejar prototipar algumas a mais. Considere o seguinte cdigo:

If cHair = "A" Replace hair With "Loira" Else If cHair = "B" Replace hair With "Morena" Else If cHair = "C" Replace hair With "Ruiva" Else If cHair = "D" Replace hair With "Grisalho" Else Replace hair With "Preto" Endif Endif

Endif Endif Um cdigo de uma nica letra, (A at E), foi informado para indicar a cor de cabelo. Este cdigo foi ento convertido e armazenado como uma string. Pode-se notar que a cor "Preto" ser atribuda se nenhuma outra opo for verdadeira. Uma alternativa que reduz o nvel de identao torna o cdigo mais fcil de ler enquanto reduz o nmero de comandos replace:

Do Case Case cHair == "A" cColor := "Loira" Case cHair == "B" cColor := "Morena" Case cHair == "C" cColor := "Ruiva" Case cHair == "D" cColor := "Grisalho" OtherWise cColor := "Preto" EndCase Replace hair With cColor

Utilizao de Arquivos de Cabealho Quando Necessrio

Se um arquivo de cdigo criado se referencia a comandos para interpretao e tratamento de arquivos XML, este deve se incluir o arquivo de cabealho prprio para tais comandos (XMLXFUN.CH no exemplo). Porm no deve-se incluir arquivos de cabealho apenas por segurana. Se no se est referenciando nenhuma das constantes ou utilizando nenhum dos comandos contidos em um destes arquivos, a incluso apenas tornar a compilao mais demorada.

Constantes em Maisculo
Isto uma conveno que faz sentido. Em AdvPl, como em C por exemplo, a regra utilizar todos os caracteres de uma constante em maisculo, a fim de que possam ser claramente reconhecidos como constantes no cdigo, e que no seja necessrios lembrar onde foram declarados.

Utilizao de Identao
Este um hbito que todo programador deve desenvolver. No consome muito esforo para manter o cdigo alinhado durante o trabalho, porm

quando necessrio pode-se utilizar AP6 IDE para a reidentao de cdigo. Considere o exemplo: While !SB1->(Eof()) If mv_par01 = SB1->B1_COD dbSkip() Loop Endif Do Case Case SB1->B1_LOCAL == "01" .Or. SB1->B1_LOCAL == "02" TrataLocal(SB1->B1_COD,SB1->B1_LOCAL) Case SB1->B1_LOCAL == "03" TrataDefeito(SB1->B1_COD) OtherWise TrataCompra(SB1->B1_COD,SB1->B1_LOCAL) EndCase dbSkip() EndDo

A utilizao da identao seguindo as estruturas de controle de fluxo (while, if, case, etc) torna a compreenso do cdigo muito mais fcil: While !SB1->(Eof()) If mv_par01 = SB1->B1_COD dbSkip() Loop Endif Do Case Case SB1->B1_LOCAL == "01" .Or. SB1->B1_LOCAL == "02" TrataLocal(SB1->B1_COD,SB1->B1_LOCAL) Case SB1->B1_LOCAL == "03" TrataDefeito(SB1->B1_COD) OtherWise TrataCompra(SB1->B1_COD,SB1->B1_LOCAL) EndCase dbSkip() EndDo

Utilizao de Espaos em Branco

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

Quebra de Linhas Muito Longas

Com o objetivo de tornar o cdigo mais fcil de ler e imprimir, as

linhas do cdigo no devem estender o limite da tela ou do papel. Podem ser "quebradas" em mais de uma linha de texto utilizando o ponto-e-vrgula (;).

Capitulao de Palavras-Chave
Uma conveno amplamente utilizada a de capitular as palavras chaves, funes, variveis e campos utilizando uma combinao de caracteres em maisculo e minsculo, visando facilitar a leitura do cdigo fonte. O cdigo a seguir: local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo

Ficaria melhor com as palavras chaves e variveis capituladas: Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo

Utilizao da Notao Hngara

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

Utilizao de Nomes Significantes para Variveis

A principal vantagem da liberdade na criao dos nomes de variveis a facilidade de identificao da sua utilidade. Portanto deve-se utilizar essa facilidade o mximo possvel. Nomes sem sentido apenas tornaro difcil a identificao da utilidade de uma determinada varivel, assim como nomes extremamente curtos. Nem sempre a utilizao de uma varivel chamada i a melhor sada. Claro, no convm criar uma varivel com um nome muito longo que ser utilizada como um contador, e referenciada muitas vezes no cdigo. O bom senso deve ser utilizado. Criar variveis como nNumero ou dData tambm no ajudam na identificao. A Notao Hngara j est sendo utilizada para isso e o objetivo do nome da varivel deveria ser identificar sua utilizao,

no o tipo de dado utilizado. Deve-se procurar substituir tais variveis por algo como nTotal ou dCompra. O mesmo vlido para nomes de funes, que devem descrever um pouco sobre o que a funo faz. Novamente nomes extremamente curtos no so aconselhveis.

Utilizao de Comentrios
Comentrios so muito teis na documentao de programas criados e para facilitar a identificao de processos importantes no futuro. Devem sempre ser utilizados. Sempre que possvel, funes criadas devem ter uma breve descrio do seu objetivo, parmetros e retorno. Alm de servir como documentao, os comentrios embelezam o cdigo ao separar as funes umas das outras. Os comentrios devem ser utilizados com bom senso, pois reescrever a sintaxe AdvPl em portugus torna-se apenas perda de tempo: #EX If nLastKey == 27 // Se o nLastKey for igual a 27 #EX

Criao de Mensagens Sistmicas Significantes e Consistentes

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

Evitar Abreviao de Comandos em 4 letras

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

Evitar "Disfarces" no Cdigo

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

A impresso esto sendo utilizadas. substitudo

que se tem aps uma leitura deste cdigo de que valores atribuidos s variveis ou que constantes esto sendo Se o objetivo flexibilidade, o cdigo anterior deve ser por:

#define NUMLINES 1 #define NUMPAGES 2 #define ISDISK 5 If aReturn[ISDISK] == 1 aPrintDefs[ NUMLINES ] := 55 Endif aPrintDefs[ NUMPAGES ] += 1

Evitar Cdigo de Segurana Desnecessrio

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

Static Function MultMalor( nVal ) If ValType( nVal ) != "N" nVal := 0 Endif Return ( nVal * nVal )

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

Isolamento de Strings de Texto

No caso de mensagens e strings de texto, a centralizao um bom negcio. Pode-se colocar mensagens, caminhos para arquivos, e mesmo outros valores em um local especfico. Isto os torna acessveis de qualquer lugar no programa e fceis de gerenciar. Por exemplo, se existe uma mensagem comum como "Imprimindo, por favor aguarde..." em muitas partes do cdigo, corre-se o risco de no seguir um padro para uma das mensagens em algum lugar do cdigo. E mant-las em um nico lugar, como um arquivo de cabealho, torna fcil a produo de documentao e a internacionalizao em outros idiomas.

SINTAXE DE LINGUAGEM

Criaco de um Programa
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Um programa de computador nada mais do que um grupo de comandos logicamente dispostos com o objetivo de executar determinada tarefa. Esses comandos so gravados em um arquivo texto que transformado em uma linguagem executvel por um computador atravs de um processo chamado compilao. A compilao substitui os comandos de alto nvel (que os humanos compreendem) por instrues de baixo nvel (compreendida pelo sistema operacional em execuo no computador). No caso do AdvPl, no o sistema operacional de um computador que ir executar o cdigo compilado, mas sim o AP6 Server.

Dentro de um programa, os comandos e funes utilizados devem seguir regras de sintaxe da linguagem utilizada, pois caso contrrio o programa ser interrompido por erros. Os erros podem ser de compilao ou de execuo.

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

Linhas de Programa
As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser linhas de comando, linhas de comentrio ou linhas mistas.

Linhas de Comando
Linhas de comando possuem os comandos ou instrues que sero executadas. Por exemplo:
Local nCnt Local nSoma := 0 For nCnt := 1 To 10 nSoma += nCnt Next nCnt

Linhas de Comentrio
Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem apenas para documentao e para tornar mais fcil o entendimento do programa. Existem trs formas de se comentar linhas de texto. A primeira delas utilizar o sinal de * (asterisco) no comeo da linha:
* Programa para clculo do total * Autor: Microsiga Software S.A. * Data: 2 de outubro de 2001

Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio. Pode-se utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para

realizar a funo do sinal de asterisco. Porm todas estas formas de comentrio de linhas so obsoletas e existem apenas para compatibilizao com o padro xBase. A melhor maneira de comentar linhas em AdvPl utilizar duas barras transversais:
// Programa para clculo do total // Autor: Microsiga Software S.A. // Data: 2 de outubro de 2001

Outra forma de documentar textos utilizar as barras transversais juntamente com o asterisco, podendo-se comentar todo um bloco de texto sem precisar comentar linha a linha:
/* Programa para clculo do total Autor: Microsiga Software S.A. Data: 2 de outubro de 2001 */

Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento (indicada pelos caracteres */) considerado como comentrio.

Linhas Mistas
O AdvPl tambm permite que existam linhas de comando com comentrio. Isto possvel inclundo-se as duas barras transversais (//) ao final da linha de comando e adicionando-se o texto do comentrio:
Local nCnt Local nSoma := 0 // Inicializa a varivel com zero para a soma For nCnt := 1 To 10 nSoma += nCnt Next nCnt

Tamanho da Linha
Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser digitado no editor de textos utilizado, existe uma linha considerada linha lgica. A linha lgica, aquela considerada para a compilao como uma nica linha de comando. A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento da tecla <Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm algumas vezes, por limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha lgica em

mais de uma linha fsica no arquivo texto. Isto efetuado utilizando-se o sinal de ponto-evrgula (;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter> !Empty(cTel) .And. !Empty(cFax) .And. ; <enter> !Empty(cEmail) GravaDados(cNome,cEnd,cTel,cFax,cEmail) Endif

Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas. Como a linha torna-se muito grande, pode-se divid-la em mais de uma linha fsica utilizando o sinal de ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas duas primeiras linhas, durante a execuo do programa ocorrer um erro, pois a segunda linha fsica ser considerada como uma segunda linha de comando na compilao. E durante a execuo esta linha no ter sentido.

Estrutura de um Programa
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Apesar de no ser uma linguagem de padres rgidos com relao estrutura do programa, importante identificar algumas de suas partes. Considere o programa de exemplo abaixo:
/* +===========================================+ | Programa: Clculo do Fatorial | | Autor : Microsiga Software S.A. | | Data : 02 de outubro de 2001 | +===========================================+ */ Local nCnt Local nResultado := 1 // Resultado do fatorial Local nFator := 5 // Nmero para o clculo // Clculo do fatorial For nCnt := nFator To 1 Step -1 nResultado *= nCnt Next nCnt // Exibe o resultado na tela, atravs da funo alert

Alert("O fatorial de " + cValToChar(nFator) + ; " " + cValToChar(nResultado)) // Termina o programa Return

Pode-se classificar um programa em AdvPl em quatro partes bsicas:

rea de Identificao rea de Ajustes Iniciais Corpo do Programa rea de Encerramento

A rea de Identificao
Esta uma rea que no obrigatria e dedicada a documentao do programa. Quando existente, contm apenas comentrios explicando a sua finalidade, data de criao, autor, etc, e aparece no comeo do programa, antes de qualquer linha de comando. O formato para esta rea no definido. Pode-se colocar qualquer tipo de informao desejada e escolher a formatao apropriada.
/* +==========================================+ | Programa: Clculo do Fatorial | | Autor : Microsiga Software S.A. | | Data : 02 de outubro de 2001 | +==========================================+ */

Opcionalmente pode-se incluir definies de constantes utilizadas no programa ou incluso de arquivos de cabealho nesta rea.

A rea de Ajustes Iniciais

Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto funcionamento do programa. Entre os ajustes se encontram declaraes de variveis, inicializaes, abertura de arquivos, etc. Apesar do AdvPl no ser uma linguagem rgida e as variveis poderem ser declaradas em qualquer lugar do programa, aconselhvel fazlo nesta rea visando tornar o cdigo mais legvel e facilitar a identificao de variveis no utilizadas.
Local nCnt Local nResultado := 0 // Resultado do fatorial Local nFator := 10 // Nmero para o clculo

O Corpo do Programa
nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a tarefa necessria atravs da organizao lgica destas linhas de comando. Espera-se que as linhas de comando estejam organizadas de tal modo que no final desta rea o resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variveis de memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela.
// Clculo do fatorial For nCnt := nFator To 1 Step -1 nResultado *= nCnt Next nCnt

A rea de Encerramento
nesta rea onde as finalizaes so efetuadas. onde os arquivos abertos so fechados, e o resultado da execuo do programa utilizado. Pode-se exibir o resultado armazenado em uma varivel ou em um arquivo ou simplesmente finalizar, caso a tarefa j tenha sido toda completada no corpo do programa. nesta rea que se encontra o encerramento do programa. Todo programa em AdvPl deve sempre terminar com a palavra chave return.
// Exibe o resultado na tela, atravs da funo alert Alert("O fatorial de " + cValToChar(nFator) + ; " " + cValToChar(nResultado)) // Termina o programa Return

Controlando o Fluxo
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

O AdvPl suporta vrias estruturas de controle que permitem mudar a seqncia de fluxo de execuo de um programa. Estas estruturas permitem a execuo de cdigo baseado em condies lgica e a repetio da execuo de pedaos de cdigo qualquer nmero de vezes.

Em AdvPl, todas as estruturas de controle podem ser "aninhadas" dentro de todas as demais estruturas contanto que estejam aninhadas propriamente. Estruturas de controle tm um identificador de incio e um de fim, e qualquer estrutura aninhada deve se encontrar entre estes identificadores. Tambm existem estruturas de controle para determinar que elementos, comandos, etc em um programa sero compilados. Estas so as diretivas do pr-processador #ifdef...#endif e #ifndef...#endif. Consulte a documentao sobre o pr-processador para maiores detalhes. As estruturas de controle em AdvPl esto divididas em :

Estruturas de Repetio Estruturas de Deciso.

Desviando a Execuco
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Estruturas de desvio so deseginadas para executar uma seo de cdigo se determinada condio lgica resultar em verdadeiro (.T.). Em AdvPl existem dois comandos para execuo de sees de cdigo de acordo com avaliaes lgicas. O comando IF...ENDIF e o comando DO CASE...ENDCASE.

O Comando DO CASE...ENDCASE
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro (.T.).

Sintaxe

DO CASE CASE lExpressao1

Commandos [CASE lExpressao2 Commandos ... CASE lExpressaoN Commandos] [OTHERWISE Commandos] ENDCASE

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

CASE lExpressao1 Comandos...

OTHERWISE Commandos

Comentrios
O Comando DO CASE...ENDCASE utilizado no lugar do comando IF...ENDIF quando um nmero maior do que uma expresso deve ser avaliada, substituindo a necessidade de mais de um comando IF...ENDIF aninhados.

Exemplo

Local nMes := Month(Date()) Local cPeriodo := "" DO CASE CASE nMes <= 3 cPeriodo := "Primeiro Trimestre"

CASE nMes >= 4 .And. nMes <= 6 cPeriodo := "Segundo Trimestre" CASE nMes >= 7 .And. nMes <= 9 cPeriodo := "Terceiro Trimestre" OTHERWISE cPeriodo := "Quarto Trimestre" ENDCASE Return

O Comando IF...ENDIF
Reviso: 20/09/2004 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Executa um conjunto de comandos baseado no valor de uma expresso lgica.

Sintaxe

IF lExpressao Comandos [ELSE Comandos...] ENDIF

Parmetros
Especifica uma expresso lgica que avaliada. Se lExpressao resultar em verdadeiro (.T.), qualquer comando seguinte ao IF e antecedente ao ELSE ou ENDIF (o que ocorrer primeiro) ser executado.Se lExpressao resultar em falso (.F.) e a clusula ELSE for definida, qualquer comando aps essa lExpressao clusula e anterior ao ENDIF ser executada. Se a clusula ELSE no for definida, todos os comandos entre o IF e o ENDIF so ignorados. Neste caso, a execuo do programa continua com o primeiro comando seguinte ao ENDIF. Conjunto de comandos AdvPl que sero executados dependendo da avaliao Comandos da expresso lgica em lExpressao.

Comentrios
Pode-se aninhar um bloco de comando IF...ENDIF dentro de outro bloco de comando IF...ENDIF. Porm, para a avaliao de mais de uma expresso lgica, deve-se utilizar o comando DO CASE...ENDCASE.

Exemplo

Local dVencto := CTOD("31/12/01") If Date() > dVencto Alert("Vencimento ultrapassado!") Endif Return

IF no Protheus Nas verses do ERP Siga Advanced 2.07 /4.07 e anteriores, caso o comando IF recebesse um argumento nulo ( NIL ) , a aplicao era abortada com a ocorrncia "Error BASE/1066 Argument error: conditional". A partir das verses Protheus 507 e posteriores, a aplicao no abortada, e o comando IF comporta-se como se tivesse recebido o valor booleano .F. ( falso ) .

O Comando FOR...NEXT
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

A estrutura de controle FOR...NEXT, ou simplesmente o loop FOR, repete uma seo de cdigo em um nmero determinado de vezes.

Sintaxe

FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento] Comandos...

[EXIT] [LOOP] NEXT

Parmetros
Especifica uma varivel ou um elemento de uma matriz para atuar como um contador. A varivel ou o elemento da matriz no precisa ter sido Variavel 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 repetio EXIT da seo de comandos imediatamente. Pode-se colocar o comando EXIT em qualquer lugar entre o FOR e o NEXT. Retorna o controle diretamente para a clusula FOR sem executar o restante dos comandos entre o LOOP e o NEXT. O contador LOOP incrementadou ou decrementado normalmente, como se o NEXT tivesse sido alcanado. Pode-se colocar o comando LOOP em qualquer lugar entre o FOR e o NEXT.

Comentrios
Uma varivel ou um elemento de uma matriz utilizado como um contador para especificar quantas vezes os comandos AdvPl dentro da estrutura FOR...NEXT so executados. Os comandos AdvPl depois do FOR so executados at que o NEXT seja alcanado. O contador (Variavel) ento incrementado ou decremantado com o valor em nIncremento (se a clusula STEP for omitida, o contador incrementado em 1). Ento, o contador comparado com o valor em nValorFinal. Se for menor ou igual ao valor em nValorFinal, os comandos seguintes ao FOR so executados novamente. Se o valor for maior que o contido em nValorFinal, a estrutura FOR...NEXT terminada e o programa continua a execuo no primeiro comando aps o NEXT.

Os valores de nValorInicial, nValorFinal e nIncremento so apenas considerados inicialmente. Entretanto, mudar o valor da varivel utilizada como contador dentro da estrutura afetar o nmero de vezes que a repetio ser executada. Se o valor de nIncremento negativo e o valor de nValorInicial maior que o de nValorFinal, o contador ser decrementado a cada repetio. Exemplo
Local nCnt Local nSomaPar := 0 For nCnt := 0 To 100 Step 2 nSomaPar += nCnt Next Alert( "A soma dos 100 primeiros nmeros pares : " + ; cValToChar(nSomaPar) ) Return

Este exemplo imprime a soma dos 100 primerios nmeros pares. A soma obitida atravs da repetio do clculo utilizando a prpria varivel de contador. Como a clusula STEP est sendo utilizada, a varivel nCnt ser sempre incrementada em 2. E como o contador comea com 0, seu valor sempre ser um nmero par.

O Comando WHILE...ENDDO
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma seo de cdigo enquanto uma determinada expresso resultar em verdadeiro (.T.).

Sintaxe

WHILE lExpressao Comandos... [EXIT]

[LOOP] ENDDO

Parmetros
Especifica uma expresso lgica cujo valor determina quando os comandos entre o WHILE e o ENDDO so executados. Enquanto o resultado de lExpressao lExpressao for avaliado como verdadeiro (.T.), o conjunto de comandos so executados. Especifica um ou mais instrues de comando AdvPl que sero executadas Comandos enquanto lExpressao for avaliado como verdadeiro (.T.). Transfere o controle de dentro do comando WHILE...ENDDO para o comando imediatamente seguinte ao ENDDO, ou seja, finaliza a repetio da EXIT seo de comandos imediatamente. Pode-se colocar o comando EXIT em qualquer lugar entre o WHILE e o ENDO. Retorna o controle diretamente para a clusula WHILE sem executar o restante dos comandos entre o LOOP e o ENDDO. A expresso em LOOP lExpressao reavaliada para a deciso se os comandos continuaro sendo executados.

Comentrios
Os comandos entre o WHILE e o ENDDO so executados enquanto o resultado da avaliao da expresso em lExpressao permanecer verdadeiro (.T.). Cada palavra chave WHILE deve ter uma palavra chave ENDDO correspondente.

Exemplo

Local nNumber := 0 Local nSomaPar := 0 While nNumber <= 100 nSomaPar += nNumber nNumber += 2 Enddo Alert( "A soma dos 100 primeiros nmeros pares : " + cValToChar(nSomaPar) ) Return

Repetico de Comandos
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Estruturas de repetio so deseginadas para executar uma seo de cdigo mais de uma vez. Por exemplo, imagiando-se a existncia de uma funo para imprimir um relatrio, pode-se desejar imprimi-lo quatro vezes. Claro, pode-se simplesmente chamar a funo de impresso quatro vezes em seqncia, mas isto se tornaria pouco profissional e no resolveria o problema se o nmero de relatrios fosse varivel. Em AdvPl existem dois comandos para a repetio de sees de cdigo. O comando FOR...NEXT e o comando WHILE...ENDDO.

Macro Substituico
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

O operador de macro substituio, simbolizado pelo "e" comercial (&), utilizado para a avaliao de expresses em tempo de execuo. Funciona como se uma expresso armazenada fosse compilada em tempo de execuo, antes de ser de fato executada. 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"

O operador de macro cancela as aspas:

03 B := X + 1

Pode-se perceber que o operador de macro remove as aspas, o que deixa um pedao de cdigo para ser executado. Deve-se ter em mente que tudo isso acontece em tempo de eecuo, o que torna tudo muito dinmico. Uma utilizao interessante criar um tipo de calculadora, ou avaliador de frmulas, que determina o resultado de algo que o usurio digita. O operador de macro tem uma limitao: variveis referenciadas dentro da string de caracteres (X nos exemplos anteriores) no podem ser locais.

Operadores Comuns
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Na documentao sobre variveis h uma breve demonstrao de como atribuir valores a uma varivel da forma mais simples. O AdvPl amplia significativamente a utilizao de variveis atravs do uso de expresses e funes. Uma expresso um conjunto de operadores e operandos cujo resultado pode ser atribudo a uma varivel ou ento analisado para a tomada de decises. Por exemplo:
Local nSalario := 1000, nDesconto := 0.10 Local nAumento, nSalLiquido nAumento := nSalario * 1.20 nSalLiquido := nAumento * (1-nDesconto)

Neste exemplo so utilizadas algumas expresses para calcular o salrio lquido aps um aumento. Os operandos de uma expresso podem ser uma varivel, uma constante, um campo de arquivo ou uma funo.

Operadores Matemticos
Os operadores utilizados em AdvPl para clculos matemticos so: + * / ** ou ^ % Adio Subtrao Multiplicao Diviso 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: < > = == <= >= <> ou # ou != Comparao Menor Comparao Maior Comparao Igual Comparao Exatamente Igual (para caracteres) Comparao Menor ou Igual Comparao Maior ou Igual Comparao Diferente

Operadores Lgicos
Os operadores utilizados em AdvPl para operaes e avaliaes lgicas so: .And. E lgico

.Or. OU lgico .Not. ou ! NO lgico

Operadores Especiais
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Alm dos operadores comuns, o AdvPl possui alguns outros operadores ou identificadores. Estas so suas finalidades: () [] {} -> & @ Agrupamento ou Funo Elemento de Matriz Definio de Matriz, Constante ou Bloco de Cdigo Identificador de Apelido Macrosubstituio Passagem de parmetro por referncia

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

Operadores de Atribuico
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Os operadores utilizados em AdvPl para atribuio de valores a variveis de memria so: = := += -= *= /= **= ou ^= %= 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 Exponenciao e Atribuio em Linha Mdulo (resto da diviso) e Atribuio em Linha

Atribuio Simples
O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.
nVariavel = 10

Atribuio em Linha
O operador de atribuio em linha caracterizado por dois pontos e o sinal de igualdade. Tem a mesma funo do sinal de igualdade sozinho, porm aplia a atribuio s variveis. Com ele pode-se atribuir mais de uma varivel ao mesmo tempo.
nVar1 := nVar2 := nVar3 := 0

Quando diversas variveis so inicializadas em uma mesma linha, a atribuio comea da

direita para a esquerda, ou seja, nVar3 recebe o valro zero inicialmente, nVar2 recebe o contedo de nVar3 e nVar1 recebe o contedo de nVar2 por final. Com o operador de atribuio em linha, pode-se substituir as inicializaes individuais de cada varivel por uma inicializao apenas:
Local nVar1 := 0, nVar2 := 0, nVar3 := 0

por
Local nVar1 := nVar2 := nVar3 := 0

O operador de atribuio em linha tambm pode ser utilizado para substituir valores de campos em um banco de dados.

Atribuio Composta
Os operadores de atribuio composta so uma facilidade da linguagem AdvPl para expresses de clculo e atribuio. Com eles pode-se economizar digitao: Operador += -= *= /= **= ou ^= %= Exemplo X += Y X -= Y X *= Y X /= Y X **= Y X %= Y Equivalente a X=X+Y X=X-Y X=X*Y X=X/Y X = X ** Y X=X%Y

Operadores de Incremento/Decremento
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

A linguagem AdvPl possui operadores para realizar incremento ou decremento de variveis. Entende-se por incremento aumentar o valor de uma varivel numrica em 1 e entende-se por decremento diminuir o valor da varivel em 1. Os operadores so: ++ Incremento Ps ou Pr-fixado -- Decremento Ps ou Pr-fixado

Os operadores de decremento/incremento podem ser colocados tanto antes (pr-fixado) como depois (ps-fixado) do nome da varivel. Dentro de uma expresso, a ordem do operador muito importante, podendo alterar o resultado da expresso. Os operadores incrementais so executados da esquerda para a direita dentro de uma expresso.
Local nA := 10 Local nB := nA++

nA

O valor da varivel nB resulta em 21, pois a primeira referncia a nA (antes do ++) continha o valor 10 que foi considerado e imediatamente aumentado em 1. Na segunda referncia a nA, este j possua o valor 11. O que foi efetuado foi a soma de 10 mais 11, igual a 21. O resultado final aps a execuo destas duas linhas a varivel nB contendo 21 e a varivel nA contendo 11. No entanto:
Local nA := 10 Local nB := ++nA

nA

Resulta em 22, pois o operador incremental aumentou o valor da primeira nA antes que seu valor fosse considerado.

Ordem de Precedencia dos Operadores

Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Dependendo do tipo de operador, existe uma ordem de precedncia para a avaliao dos operandos. Em princpio, todas as operaes com os operadores so realizadas da esquerda para a direita se eles tiverem o mesmo nvel de prioridade. A ordem de precedncia, ou nvel de prioridade de execuo, dos operadores em AdvPl :

1. Operadores de Incremento/Decremento pr-fixado 2. Operadores de String 3. Operadores Matemticos 4. Operadores Relacionais 5. Operadores Lgicos 6. Operadores de Atribuio 7. Operadores de Incremento/Decremento ps-fixado

Em expresses complexas com diferentes tipos de operadores, a avaliao seguir essa sequncia. Caso exista mais de um operador do mesmo tipo (ou seja, de mesmo nvel), a avaliao se d da esquerda para direita. Para os operadores matemticos entretanto h uma precedncia a seguir:

1. Exponenciao 2. Multiplicao e Diviso 3. Adio e Subtrao

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

No exemplo acima primeiro ser calculada a exponenciao 2^3(=8). Em seguida 2+10(=12) ser calculado, 2+5(=7) calculado, e finalmente a diviso e a multiplicao sero efetuadas, o que resulta em 12/7*3+8(=13.14). Se existirem vrios parnteses aninhados, ou seja, colocados um dentro do outro, a avaliao ocorrer do parnteses mais intero em direo ao mais externo.

Blocos de Codigo
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Blocos de cdigo so um conceito existente h muito tempo em linguagens xBase. No como algo que apareceu da noite para o dia, e sim uma evoluo progressiva utilizando a combinao de muitos conceitos da linguagem para a sua implementao.

Um Primeiro Lembrete
O AdvPl uma linguagem baseada em funes. Funes tm um valor de retorno. Assim como o operador de atribuio :=. Assim, ao invs de escrever:
x := 10 // Atribui o valor 10 varivel chamada X Alert("Valor de x: " + cValToChar(x))

Pode-se escrever:
// Atribui e ento exibe o valor da varivel X Alert("Valor de x: " + cValtoChar(X := 10))

A expresso x:=10 avaliada primeiro, e ento seu resultado (o valor de X, que agora 10) passada para a funo cvaltochar para a converso para caracter, e em seguida para a funo alert para a exibio. Por causa desta regra de precedncia possvel atribuir um valor a mais de uma varavel ao mesmo tempo:

Z := Y := X := 0

Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:
Z := ( Y := (X := 0) )

Apesar do AdvPl avaliar expresses da esquerda para a direita, no caso de atribuies isso acontece ao contrrio, da direita para a esquerda. O valor atribudo varivel X, que retorna o valor para ser atribudo varivel Y e assim sucessivamente. Pode-se dizer que o zero foi "propagado atravs da expresso".

Outro Lembrete
Em AdvPl pode-se juntar diversas linhas de cdigo em uma nica linha fscia do arquivo. Por exemplo, o cdigo:
If lAchou Alert("Cliente encontrado!") Endif

pode ser escrito assim:

If lAchou ; Alert("Cliente encontrado!") ; Endif

O ponto-e-vrgula indica ao AdvPl que a nova linha de cdigo est para comear. Pode-se ento colocar diversas linhas lgicas de cdigo na mesma linha fsica atravs do editor de texto utilizado. Apesar da possibilidade de se escrever todo o programa assim, em uma nica linha fsica, isto no recomendado pois dificulta a legibilidade do programa e, conseqentemente, a manuteno.

Lista de Expresses
A evoluo dos blocos de cdigo comea com as listas de expresses. Nos exemplos a seguir, o smbolo ==> indicar o retorno da expresso aps sua avaliao (seja para

atribuir em uma varivel, exibir para o usurio ou imprimir em um relatrio), que ser impresso em um relatrio por exemplo.

Duas Linhas de Cdigo

@00,00 PSAY x := 10 @00,00 PSAY y := 20

==> ==>

10 20

Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento impresso.

Duas Linha de Cdigo em Uma , Utilizando Ponto-e-Vrgula

Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:
Alert( cValToChar( x := 10 ; y := 20 ) ) ==> 10

Apesar desse cdigo se encontrar em uma nica linha fsica, existem duas linhas lgicas separadas pelo ponto e vrgula. Ou seja, esse cdigo equivalente a:
Alert( cValToChar( x := 10 ) ) y := 20

Portanto apenas o valor 10 da varivel x ser passado para as funes cvaltochar e alert para ser exibido. E o valor 20 apenas ser atribudo varivel y.

Convertendo para uma Lista de Expresses

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

O valor de retorno resultante de uma lista de expresses o valor resultante da ltima expresso ou elemento da lista. Funciona como se fosse um pequeno programa ou funo, que retorna o resultado de sua ltima avaliao (efetuadas da esquerda para a direita). Neste exemplo, a expresso x := 10 avaliada, e ento a expresso y := 20, cujo valor resultante passado para a funo alert e cvaltochar, e ento exibido. Depois que essa linha de cdigo executada, o valor de X igual a 10 e o de y igual a 20, e 20 ser

exibido. Teoricamente, no h limitao para o nmero de expresses que podem ser combinadas em uma lista de expresses. Na prtica, o nmero mximo por volta de 500 smbolos. Debugar listas de expresses difcil oprque as expresses no esto divididas em linhas de cdigo fonte, o que torna todas as expresses associadas a uma mesma linha de cdigo. Isto pode tornar muito difcil determinar onde um erro ocorreu.

Onde Pode-se Utilizar uma Lista de Expresses?

O propsito principal de uma lista de expresses agrup-las em uma nica unidade. Em qualquer lugar do cdigo AdvPl que uma expresso simples pode ser utilizada, pode-se utilizar uma lista de expresses. E ainda, pode-se fazer com que vrias coisas aconteam onde normalmente apenas uma aconteceria.
X := 10 ; Y := 20 If X > Y Alert("X") Z := 1 Else Alert("Y") Z := -1 Endif

Aqui temos o mesmo conceito, escrito utilizando listas de expresses na funo iif:
X := 10 ; Y := 20 iif( X > Y , ; ( Alert("X"), Z := 1 ) , ; ( Alert("Y"), Z := -1 ) )

De Listas de Expresses para Blocos de Cdigo

Considere a seguinte lista de expresses:
Alert( cValToChar( ( x := 10, y := 20 ) ) ) ==> 20

O AdvPl permite criar funes, que so pequenos pedaos de cdigo, como se fosse um pequeno programa, utilizados para diminuir partes de tarefas mais complexas e reaproveitar cdigo em mais de um lugar num programa. Para maiores detalhes consulte a

documentao sobre a criao de funes em AdvPl. Porm, a idia neste momento que a lista de expresses utilizada na linha anterior pode ser criada como uma funo:
Function Lista() X := 10 Y := 20 Return Y

E a linha de exemplo com a lista de expresses pode ser substituda, tendo o mesmo resultado, por:
Alert( cValToChar( Lista() ) ) ==> 20

Como mencionado anteriormente, uma lista de expresses como um pequeno programa ou funo. Com poucas mudanas, uma lista de expresses pode se tornar um bloco de cdigo:
( X := 10 , Y := 20 ) // Lista de Expresses {|| X := 10 , Y := 20 } // Bloco de Cdigo

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

Executando um Bloco de Cdigo

Diferentemente de uma matriz, no se pode acessar elementos de um bloco de cdigo atravs de um ndice numrico. Porm blocos de cdigo so semelhantes a uma lista de expresses, e a uma pequena funo. Ou seja, podem ser executados. Para a execuo, ou avaliao, de um bloco de cdigo, deve-se utilizar a funo eval:
nRes := Eval(B) ==> 20

Essa funo recebe como parmero um bloco de cdigo e avalias todas as expresses contidas neste bloco de cdigo, retornando o resultado da ltima expresso avaliada.

Passando Parmetros
J que blocos de cdigo so como pequenas funes, tambm possvel a passagem de parmetros para um bloco de cdigo. Os parmetros devem ser informados entre as barras verticais (||) separados por vrgulas, assim como em uma funo.
B := {| N | X := 10, Y := 20 + N}

Porm deve-se notar que j que o bloco de cdigo recebe um parmetro, um valor deve ser passado quando o bloco de cdigo for avaliado.
C := Eval(B, 1) ==> 21

Utilizando Blocos de Cdigo

Blocos de cdigo podem ser utilizados em diversas situaes. Geralmente so utilizados para executar tarefas quando eventos de objetos so acionados ou para modificar o comportamento padro de algumas funes. Por exemplo, considere a matriz abaixo:
A := {"GARY HALL", "FRED SMITH", "TIM JONES"}

Esta matriz pode ser ordenada pelo primeiro nome, utilizando-se a chamada da funo asort(A), resultado na matriz com os elementos ordenados dessa forma:
{"FRED SMITH", "GARY HALL", "TIM JONES"}

A ordem padro para a funo asort ascendente. Este comportamento pode ser modificado atravs da informao de um bloco de cdigo que ordena a matriz de forma descendente:
B := { |X, Y| X > Y } aSort(A, B)

O bloco de cdigo (de acordo com a documentao da funo asort) deve ser escrito para aceitar dois parmetros que so os dois elementos da matriz para comparao. Note que o bloco de cdigo no conhece que elementos est comparando - a funo asort seleciona os elementos (talvez utilizando o algortmo QuickSort) e passa-os para o bloco de cdigo. O bloco de cdigo compara-os e retorna verdadeiro (.T.) se se encontram na ordem correta, ou falso (.F.) se no. Se o valor de retorno for falso, a funo asort ir ento trocar os valores de lugar e seguir comparando o prximo par de valores. Ento, no bloco de cdigo anterior, a comparao X > Y verdadeira se os elementos esto em ordem descendente, o que significa que o primeiro valor maior que o segundo. Para ordenar a mesma matriz pelo ltimo nome, tambm em ordem descendente, pode-se 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, pode-se utilizar o seguinte bloco de cdigo:
B := { |X, Y| X[1] > Y[1] }

Criaco e Atribuico de Variaveis

Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Variveis de memria so um dos recursos mais importantes de uma linguagem. So reas de memria criadas para armazenar informaes utilizadas por um programa para a

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

Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300. Isso acontece porque no momento que esse valor foi atribuido varivel nTotalGeralAnual, o AdvPl considerou apenas os 10 primeiros caracteres (assim como o faz quando deve exibir o valor da varivel nTotalGeralMensal), ou seja, considerou-as como a mesma varivel. Assim o valor original de 100 foi substituido pelo de 300. Limitao de caracteres no nome. Os nomes das variveis devem sempre comear por uma letra ou o caracter de sublinhado ( _ ). No restante, pode conter letras, nmeros e o caracter de sublinhado. Qualquer outro caracter, incluindo espaos em branco, no so permitidos. O AdvPl permite a criao ilimitada de variveis, dependendo apenas da memria disponvel. A seguir esto alguns nomes vlidos para variveis:
TOT01 cNumero VAR_QUALQUER M_CARGO A11

E alguns invlidos:
1CODIGO (Inicia por um nmero) M CARGO (contm um espao em branco) LOCAL (palavra reservada do AdvPl)

O AdvPl no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio informar o tipo de dados que determinada varivel ir conter no momento de sua declarao, e o seu valor pode mudar durante a execuo do programa. Tambm no h necessidade de declarar variveis em uma seo especfica do seu cdigo fonte, embora seja aconselhvel declarar todas as variveis necessrias no comeo, tornando a manuteno mais fcil e evitando a declarao de variveis desnecessrias. Para declarar uma varivel deve-se utilizar um identificador de escopo, seguido de uma lista de variveis separadas por vrgula (,). Um identificador de escopo uma palavra chave que indica a que contexto do programa a varivel declarada pertence. O contexto de variveis pode ser local (visualizadas apenas dentro do programa atual), pblico (visualizadas por qualquer outro programa), entre outros. Os diferentes tipos de contexto de variveis so explicados na documentao sobre escopo de variveis. Considere as linhas de cdigo de exemplo:
nResultado := 250 * (1 + (nPercentual / 100))

Se esta linha for executada em um programa AdvPl, ocorrer um erro de execuo com a mensagem "variable does not exist: nPercentual", pois esta varivel est sendo utilizada em uma expresso de clculo sem ter sido declarada. Para solucionar este erro, deve-se declarar a varivel previamente:
Local nPercentual, nResultado 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 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. Devese 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 17 18 19 20 21 22 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 Alert("Hoje : " + DtoC(xVariavel)) xVariavel := nil // Nulo novamente Alert("Valor nulo: " + xVariavel) Return

No programa de exemplo anterior, a varivel xVariavel utilizada para armazenar

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

o mesmo que
If xVariavel = .T.

A declarao de variveis para os demais tipos de dados, matrizes e blocos de cdigo, exatamente igual ao descrito at agora. Apenas existem algumas diferenas quanto a inicializao, que podem ser consultadas na documentao de inicializao de matrizes e blocos de cdigo.

Diferenciaco entre variaveis e nomes de campos

Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Muitas vezes uma varivel pode ter o mesmo nome que um campo de um arquivo ou tabela aberto no momento. Neste caso, o AdvPl privilegiar o campo. Assim uma referncia a um nome que identifique tanto uma varivel como um campo, resultar no contedo do campo. Para especificar qual deve ser o elemento referenciado, deve-se utilizar o operador de identificao de apelido (->) e um dos dois identificadores de referncia, MEMVAR ou FIELD.
cRes := MEMVAR->NOME

Esta linha de comando identifica que o valor atribudo varivel cRes deve ser o valor da varivel de memria chamada NOME.
cRes := FIELD->NOME

Neste caso, o valor atribudo varivel cRes ser o valor do campo NOME existente no arquivo ou tabela aberto na rea atual. O identificador FIELD pode ser substitudo pelo apelido de um arquivo ou tabela aberto, para evitar a necessidade de selecionar a rea antes de acessar o contedo de terminado campo.
cRes := CLIENTES->NOME

Para maiores detalhes sobre abertura de arquivos com atribuio de apelidos, consulte a documentao sobre acesso a banco de dados ou a documentao da funo dbUseArea.

Inicializando Matrizes
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Algumas vezes o tamanho da matriz conhecido previamente. Outras vezes o tamanho da matriz s ser conhecido em tempo de execuo. Se o tamanho da matriz conhecido Se o tamanho da matriz conhecido no momento que o programa escrito, h diversas maneiras de implementar o cdigo.
01 02 03 04 05 06 07 08 Local Local Local Local nCnt aX[10] aY := Array(10) aZ := {0,0,0,0,0,0,0,0,0,0}

For nCnt := 1 To 10 aX[nCnt] := nCnt * nCnt Next nCnt

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

06 For nCnt := 1 To nSize 07 aAdd(aX,nCnt*nCnt) 08 Next nCnt

A linha 02 utiliza os colchetes para criar uma matriz vazia. Apesar de no ter nenhum elemento, seu tipo de dado matriz. Na linha 03 a chamada da funo array cria uma matriz sem nenhum elemento. Na linha 04 est declarada a representao de uma matriz vazia em AdvPl. Mais uma vez, esto sendo utilizadas as chaves para indicar que o tipo de dados da varivel matriz. Note que {} uma matriz vazia (tem o tamanho 0), enquanto {Nil} uma matriz com um nico elemento nulo (tem tamanho 1). Porque cada uma destas matrizes no contem elementos, a linha 07 utiliza a funo aadd para adicionar elementos sucessivamente at o tamanho necessrio (especificado por exemplo na varivel nSize).

Matrizes
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

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

O AdvPl permite a manipulao de matrizes facilmente. Enquanto que em outras linguagens como C ou Pascal necessrio alocar memria para cada elemento de uma matriz (o que tornaria a utilizao de "pointeiros" necessria), o AdvPl se encarrega de gerenciar a memria e torna simples adicionar elementos a uma matriz, utilizando a funo aAdd:

aAdd(aLetras,"D") Alert(aLetras[4]) Alert(aLetras[5])

// Adiciona o quarto elemento ao final da matriz // Exibe o quarto elemento // Erro! No h um quinto elemento na matriz

Matrizes como Estruturas

Uma caracterstica interessante do AdvPl que uma matriz pode conter qualquer coisa: nmeros, datas, lgicos, caracteres, objetos, etc. E ao mesmo tempo. Em outras palavras, os elementos de uma matriz no precisam ser necessariamente do mesmo tipo de dado, em contraste com outras linguagens como C e Pascal.
aFunct1 := {"Pedro",32,.T.}

Esta matriz contem uma string, um nmero e um valor lgico. Em outras linguagens como C ou Pascal, este "pacote" de informaes pode ser chamado como um "struct" (estrutura em C, por exemplo) ou um "record" (registro em Pascal, por exemplo). Como se fosse na verdade um registro de um banco de dados, um pacote de informaes construdo com diversos campos. Cada campo tendo um pedao diferente de dado. Suponha que no exemplo anterior, o array aFunct1 contenha informaes sobre o nome de uma pessoa, sua idade e sua situao matrimonial. Os seguintes #defines podem ser criados para indicar cada posio dos valores dentro da matriz:
#define FUNCT_NOME 1 #define FUNCT_IDADE 2 #define FUNCT_CASADO 3

E considere mais algumas matrizes para representar mais pessoas:

aFunct2 := {"Maria" , 22, .T.} aFunct3 := {"Antnio", 42, .F.}

Os nomes podem ser impressos assim:

Alert(aFunct1[FUNCT_NOME]) 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 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 pode-se criar variveis numricas com qualquer valor dentro do intervalo permitido. Os seguintes elementos so do tipo de dado numrico:
2 43.53 0.5 0.00001 1000000

Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E308 at 1.7976931348623158 E+308.

Lgico
Valores lgicos em AdvPl so identificados atravs de .T. ou .Y. para verdadeiro e .F. ou .N. para falso (independentemente se os caracteres estiverem em maisculo ou minsculo).

Caracter
Strings ou cadeias de caracteres so identificadas em AdvPl por blocos de texto entre aspas duplas (") ou aspas simples ('):
"Ol mundo!" 'Esta uma string' "Esta 'outra' string"

Uma varivel do tipo caracter pode conter strings com no mximo 1 Mb, ou seja, 1048576 caracteres.

Data
O AdvPl tem um tipo de dados especfico para datas. Internamente as variveis deste tipo de dado so armazenadas como um nmero correspondente a data Juliana. Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs da utilizao de funes especficas como por exemplo ctod que converte uma string para data.

Matriz (Array)
Matrizes so um tipo de dado especial. a disposio de outros elementos em colunas e linhas. O AdvPl suporta matrizes uni ou multidimensionais. Os elementos de uma matriz so acessados atravs de ndices numricos iniciados em 1, identificando a linha e coluna para quantas dimenes existirem. Uma matriz pode conter no mximo 100000 elementos, independentemente do nmero de dimenses. Matrizes devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a memria do servidor.

Bloco de Cdigo
O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues escritas em AdvPl que podero ser executadas posteriormente. ESCOPO DE VRIAVEIS

O Contexto de Variaveis dentro de um Programa

Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

As variveis declaradas em um programa ou funo, so visveis de acordo com o escopo onde so definidas. Como tambm do escopo depende o tempo de existncia das variveis. A definio do escopo de uma varivel efetuada no momento de sua declarao.
Local nNumero := 10

Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence seu escopo local. Os identifadores de escopo so:

LOCAL STATIC PRIVATE PUBLIC

O AdvPl no rgido em relao declarao de variveis no comeo do programa. A incluso de um identificador de escopo no necessrio para a declarao de uma varivel, contanto que um valor lhe seja atribudo.
nNumero2 := 15

Quando um valor atribudo uma varivel em um programa ou funo, o AdvPl criar a varivel caso ela no tenha sido declarada anteriormente. A varivel ento criada como se tivesse sido declarada como Private. Devido a essa caracterstica, quando pretende-se fazer uma atribuio a uma varivel declarada previamente mas escreve-se o nome da varivel de forma incorreta, o AdvPl no gerar nenhum erro de compilao ou de execuo. Pois compreender o nome da varivel escrito de forma incorreta como se fosse a criao de uma nova varivel. Isto alterar a lgica do programa, e um erro muitas vezes difcil de identificar.

Variaveis Estaticas
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Variveis estticas funcionam basicamente como as variveis locais, mas mantm seu valor atravs da execuo. Variveis estticas devem ser declaradas explicitamente no cdigo com o identificador STATIC. O escopo das variveis estticas depende de onde so declaradas. Se forem declaradas dentro do corpo de uma funo ou procedimento, seu escopo ser limitado quela rotina. Se forem declaradas fora do corpo de qualquer rotina, seu escopo todo o arquivo de programa. Neste exemplo, a varivel nVar declarada como esttica e inicializada com o valor 10:
Function Pai() Static nVar := 10 . <comandos> . Filha() . <mais comandos> . Return(.T.)

Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada. Diferente de variveis declaras como LOCAL ou PRIVATE, nVar continua a existir e mantem seu valor atual quando a execuo da funo Pai termina. Entretanto, somente pode ser acessada por execues subseqntes da funo Pai.

Variaveis Locais
Reviso: 02/12/2004 Abrangncia Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Verses Anteriores Variveis locais so pertencentes apenas ao escopo da funo onde foram declaradas. Devem ser explicitamente declaradas com o identificador LOCAL, como no exemplo:
Function Pai() Local nVar := 10, aMatriz := {0,1,2,3} . <comandos> . Filha() . <mais comandos> . Return(.T.)

Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10. Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada. Quando a execuo da funo Pai terminar, a varivel nVar destruda. Qualquer varivel com o mesmo nome no programa que chamou a funo Pai no afetada. Variveis locais so criadas automaticamente cada vez que a funo onde forem declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da ativao da funo (ou seja, at que a funo retorne o controle para o cdigo que a executou). Se uma funo chamada recursivamente (por exemplo, chama a si mesma), cada chamada em recurso cria um novo conjunto de variveis locais. A visibilidade de variveis locais idntica ao escopo de sua declarao. Ou seja, a varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se uma funo chamada recursivamente, apenas as variveis locais criadas na mais recente ativao so visveis. A declarao de variveis locais dentro de uma funo deve preceder qualquer comando interno ou declarao de outros tipos de variveis (Private ou Public) da funo caso contrrio ser gerado um erro de compilao. Exemplo: Function A( ) Private x:= 0 Local b:=0 <<<<< ERRADO, ERRO DE COMPILAO ... Return

Verso correta: Function A( ) Local b:=0 // correto Private x:=0 .... Return

Variaveis Privadas
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

A declarao opcional para variveis privadas. Mas podem ser declaradas explicitamente com o identificador PRIVATE. Adicionalmente, a atribuio de valor a uma varivel no criada anteriormente automaticamente cria a varivel como privada. Uma vez criada, uma varivel privada continua a existir e mantem seu valor at que o programa ou funo onde foi criada termine (ou seja, at que a funo onde foi criada retorne para o cdigo que a executou). Neste momento, automaticamente destruda. possvel criar uma nova varivel privada com o mesmo nome de uma varivel j existente. Entretanto, a nova (duplicada) varivel pode apenas ser criada em um nvel de ativao inferior ao nvel onde a varivel foi declarada pela primeira vez (ou seja, apenas em uma funo chamada pela funo onde a varivel j havia sido criada). A nova varivel privada ir esconder qualquer outra varivel privada ou pblica (veja a documentao sobre variveis pblicas) com o mesmo nome enquanto existir. Uma vez criada, uma varivel privada visvel em todo o programa enquanto no for destruda automaticamente quando a rotina que a criou terminar ou uma outra varivel privada com o mesmo nome for criada em uma subfuno chamada (neste caso, a varivel existente torna-se inacessvel at que a nova varivel privada seja destruda). Em termos mais simples, uma varivel privada visvel dentro da funo de criao e todas as funes chamadas por esta, a menos que uma funo chamada crie sua prpria varivel privada com o mesmo nome.

Por exemplo:
Function Pai() Private nVar := 10 . <comandos> . Filha() . <mais comandos> . Return(.T.)

Neste exemplo, a varivel nVar criada como privada e inicializada com o valor 10. Quando a funo Filha executada, nVar ainda existe e, diferente de uma varivel local, pode ser acessada pela funo Filha. Quando a funo Pai terminar, nVar ser destruda e qualquer declarao de nVar anterior se tornar acessvel novamente.

Variaveis Publicas
Reviso: 13/07/2002 Abrangncia Verso 5.07 Verses Anteriores Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Pode-se criar variveis pblicas dinamicamente no cdigo com o identificador PUBLIC. As variveis pblicas continuam a existir e mantm seu valor at o fim da execuo. possvel criar uma varivel privada com o mesmo nome de uma varivel pblica existente. Entretanto, no permitido criar uma varivel pblica com o mesmo nome de uma varivel privada existente. Uma vez criada, uma varivel pblica visvel em todo o programa onde foi declarada at que seja escondida por uma varivel privada criada com o mesmo nome. A nova varivel privada criada esconde a varivel pblica existente, e esta se tornar inacessvel at que a nova varivel privada seja destruda. Por exemplo:
Function Pai() Public nVar := 10 . <comandos>

. Filha() . <mais comandos> . Return(.T.)

Neste exemplo, nVar criada como pblica e inicializada com o valor 10. Quando a funo Filha executada, nVar ainda existe e pode ser acessada. Diferente de variveis locais ou privadas, nVar ainda existe aps o trmino da a execuo da funo Pai. Diferentemente dos outros identificadores de escopo, quando uma varivel declarada como pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).