Beruflich Dokumente
Kultur Dokumente
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.
lShowHint Lgico.
cMsg
Caractere.
nClrText
nClrPane
Numrico.
Numrico.
bWhen
Bloco de
cdigo.
bValid
Bloco de
cdigo.
Bloco de
cdigo.
Bloco de
brClicked
cdigo.
Bloco de
blDblClick
cdigo.
oWnd
Objeto.
lVisible
Booleano.
Objeto ou
Cargo
varivel.
Bloco de
bLostFocus
cdigo.
bGotFocus Bloco de
blClicked
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.
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
Retorno
O Dilogo criado.
Exemplo
#INCLUDE protheus.ch
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
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
Retorno
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
Retorno
Select
Descrio
Sintaxe
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
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
lPar12
oPar13
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.
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
*/
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
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
Retorno
Select
Descrio Fora a seleo de um item.
Sintaxe
Select( [anItem] )
Parmetros Parmetro Tipo / Descrio
Retorno
nItem
NIL
Add
Descrio
Sintaxe
Modify
Descrio
Sintaxe
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)
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
Retorno
Set
Descrio
Sintaxe
Exemplo
#include protheus.ch
STATIC lRunning:=.F., lStop:=.F.
User Function Teste()
Local oDlg, oMeter, nMeter:=0, oBtn1, oBtn2
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
Retorno
EnableVScroll
Descrio
Sintaxe
EnableHScroll
Descrio
Sintaxe
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
Exemplo
#include protheus.ch
User Function Teste()
Local oDlg, oPanel, oBtn1, oBtn2
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
aPar6
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.
EnableItem
Descrio
Sintaxe
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()
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
lPar9
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.
SetText
Descrio
Sintaxe
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
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
cPar16
lPar17
lPar18
lPar19
lPar20
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.
Activate
Descrio
End
Descrio Solicita encerramento da janela.
Sintaxe End( )
Retorno Lgico. .T. se encerrou a janela e .F. se no.
Center
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
COPYMSG
CREATEFOLDER
DELETEFOLDER
DELETEMSG
:
:
array[1][1]:cNome
array[1][2]:nNumMsg
array[1][3]:nNumMsgNaoLidas
array[1][4]:cStatus
:
:
GETERRORSTRING
GETFOLDER
:
:
array[1][1]:cNome
array[1][1]:nNumMsgNaoLidas
array[1][1]:nNumMsg
array[1][1]:cStatus
:
:
GETMSGBODY
GETMSGHEADER
GETPOPTIMEOUT
GETSMTPTIMEOUT
GETUSER
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.
IMAPDISCONNECT
IMAPSTORE
INIT
MOVEMSG
NEW
POPCONNECT
POPDISCONNECT
SENDMAIL
SETFOLDERSUBSCRIBE
SETMSGFLAG
SETPOPTIMEOUT
Mtodo SETPOPTIMEOUT
O mtodo SetPopTimeOut() da classe tMailmanager ir
configurar um tempo para que uma conexo
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
STARTGETALLMSGHEADER
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
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.)
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
Tipo
Descrio
Representa o nome da pasta na qual desejamos nos
Caracter
mudar(conectar) no servidor IMAP.
Retorno
Tipo
Lgico
Descrio
Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP,
false caso contrario.
Descrio
Mtodo CHANGEFOLDER usado apenas para conexo IMAP.
O mtodo ChangeFolder() da classe TMailManager tem como objetivo realizar a
mudana de pasta em que estamos conectados.
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
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
Copiar para a pasta informada, false caso contrrio.
Descrio
Mtodo COPYMSG usado apenas para conexo IMAP.
O mtodo CopyMsg() da classe tMailManager tem como objetivo Copiar uma
determinada mensagem da pasta corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor, ou at mesmo para a pasta corrente.
muito importante entendermos a localizao que estamos no server IMAP, isso quando
usamos funoes que lidam com o posicionamento no folder do servidor IMAP como
changeFolder(), createFolder() ou deleteFolder().
Para Copiar uma mensagem devemos informar qual mensagem queremos mover atravs
do primeiro parametro da funo e a pasta de acordo com o nome no servidor IMAP, a
funo ir procurar pelo ID da mensagem apenas na pasta em que estamos posicionados e
tentar mover para o folder informado(lembrando que o nome deve ser identico ao criado
no servidor)
oObj:COPYMSG ( < nMsg > , < sFolder > ) --> lRet
Parmetros
Argumento
nMsg
sFolder
Tipo
Descrio
Valor numerico da mensagem no servidor de email IMAP
Numrico
ou seu ID.
Indica o nome da pasta no servidor de email IMAP, no qual
Caracter
desejamos transferir a mensagem.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
Copiar para a pasta informada, false caso contrrio.
Descrio
Mtodo COPYMSG usado apenas para conexo IMAP.
O mtodo CopyMsg() da classe tMailManager tem como objetivo Copiar uma
determinada mensagem da pasta corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor, ou at mesmo para a pasta corrente.
muito importante entendermos a localizao que estamos no server IMAP, isso quando
usamos funoes que lidam com o posicionamento no folder do servidor IMAP como
changeFolder(), createFolder() ou deleteFolder().
Para Copiar uma mensagem devemos informar qual mensagem queremos mover atravs
do primeiro parametro da funo e a pasta de acordo com o nome no servidor IMAP, a
funo ir procurar pelo ID da mensagem apenas na pasta em que estamos posicionados e
tentar mover para o folder informado(lembrando que o nome deve ser identico ao criado
no servidor)
Sintaxe
oObj:DELETEFOLDER ( < cFolder > ) --> lRet
Parmetros
Argumento
cFolder
Tipo
Descrio
Representa o nome da pasta na qual desejamos deletar no
Caracter
servidor IMAP.
Retorno
Tipo
Lgico
Descrio
Retorna true, caso tenha sido possivel mudar de pasta no servidor IMAP,
false caso contrario.
Descrio
Mtodo DELETEFOLDER usado apenas para conexo IMAP.
O mtodo DeleteFolder() da classe tMailManager, tem como objetivo deletar uma pasta
do servidor de email IMAP.
Informando a pasta que ser deletada por parametro na funo, que deve conter o nome
passado idntico ao da pasta no sevidor (case sensitive).
Sintaxe
oObj:DELETEMSG ( < nMsg > ) --> lRet
Parmetros
Argumento
nMsg
Tipo
Descrio
Numrico Numero da mensagem a ser deletada.
Retorno
Tipo
(NULO)
Descrio
Retorna true, caso tenha sido possivel deletar a mensagem. Caso contrrio
retorna false.
Descrio
Mtodo DELETEMSG
O mtodo DeleteMsg() da classe tMailManager tem como objetivo deletar uma
determinada mensagem do servidor, de acordo com o numero da mensagem passada por
parametro para a funo.
A funo ir retornar true caso tenha sido encontrado a mensagem e deletada.
Sintaxe
oObj:ENDGETALLMSGHEADER ( < aHeaders > ) --> lRet
Parmetros
Argumento
aHeaders
Tipo Descrio
Array Array usado como referncia para o retorno dos headers das
mensagens.
Retorno
Tipo
Descrio
Retorna true quando o servidor IMAP terminou de mandar todos os headers
das mensagens, false caso contrrio.
Lgico
Descrio
Sintaxe
oObj:GETALLFOLDERLIST ( ) --> aRet
Retorno
Tipo
Descrio
Retorna um Array contendo todas as pastas (Assinadas/Nao Assinadas) e
informaoes sobre a respectiva pasta, como est status, o seu nome e numero
de mensagens existentes nela.
Array
Descrio
:
:
:
:
Sintaxe
oObj:GETERRORSTRING ( < nError > ) --> cRet
Parmetros
Argumento
nError
Tipo
Descrio
Representa um valor numrico a ser passado de algum erro
Numrico
de acordo como SMTP.
Retorno
Tipo
Caracter
Descrio
Retorna uma cadeia de caracteres com a descrio, de acordo com o valor do
erro passado.
Descrio
Mtodo GETERRORSTRING
O mtodo GetErrorString da classe TMailManager, tem como objetivo retornar um erro
em forma de string, trazendo sua descrio de acordo com algum erro que tenha ocorrido
durante alguma outra funo da classe com SendMail(), algum connect e assim por
diante.
O valor informado por parametro representa erros definidos por padro do protocolo de
conexo SMTP.
Sintaxe
oObj:GETFOLDER ( ) --> cFolder
Retorno
Tipo
Caracter
Descrio
Descrio
Retorna uma string contendo o nome do folder em uso pela aplicao.
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.
Array
Descrio
:
:
array[1][1]:cNome
array[1][1]:nNumMsgNaoLidas
array[1][1]:nNumMsg
array[1][1]:cStatus
:
:
Sintaxe
oObj:GETMSGBODY ( ) --> NIL
Retorno
Tipo
Descrio
(NULO)
Retorno nulo.
Descrio
Mtodo GETMSGBODY usado apenas para conexo IMAP.
O mtodo GetMsgBody() da classe de tMailManager tem como objetivo obter o conteudo
da mensagem indicada de acordo com o parametro que representa o numero da mensagem
para a funo.
O valor informado por parametro o numero da mensagem na pasta do servidor. O
mtodo ir procurar pela mensagem no folder que estiver posicionado no server IMAP.
Sintaxe
oObj:GETMSGHEADER ( < nMsg > ) --> lRet
Parmetros
Argumento
nMsg
Tipo
Descrio
Numrico Valor numerico da mensagem no servidor de email IMAP.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
retornar seu cabealho, false caso contrrio.
Descrio
Mtodo GETMSGHEADER usado apenas para conexo IMAP.
O mtodo GetMsgHeader() da classe tMailManager tem como objetivo se comunicar com
o server de email IMAP e obter o cabealho da mensagem requerida de acordo com o
parametro informando.
Esse cabealho da mensagem contem todos os dados relativos ao email como : From, To,
CC, BCC, etc...
O valor informado por parametro o numero da mensagem na pasta do servidor.
Obs.: o servidor IMAP ir procurar pela mensagem apenas na pasta corrente em uso, caso
a pasta em uso seja a 'Inbox' o mensagem ser procurada apenas na nesta pasta.
Sintaxe
Tipo
Descrio
Parametro passado por referencia, retorna nele o numero de
Numrico
mensagens que esto no servidor.
Retorno
Tipo
Numrico
Descrio
0 = Lista recebida com sucesso
Descrio
Mtodo GETNUMMSGS
O mtodo GetNumMsgs() da classe TMailManager tem como objetivo retornar o numero
de mensagens que existem no servidor.
Devemos informar um numrico no parametro da funo como referncia, indicando o
total de mensagens aps a execuo da funo, o valor retornado pela funo apenas o
status de funcionou ou no.
Obs.: A funo retorna o numero de mensagens total da conta de usurio informada e nao
apenas por pasta como inbox, sent itens, etc..
Sintaxe
oObj:GETPOPTIMEOUT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna o tempo em segundos para a finalizao por time out da conexao
POP.
Descrio
Mtodo GETPOPTIMEOUT
O mtodo GetPopTimeOut() da classe tMailManager tem como objetivo retornar o tempo
em segundos que est estabelecido com o servidor POP para que seja finalizada a
conexo por time-out.
Obs.: caso nao tenha sido estabelecido nenhum tempo de time-out pela funo
SETPOPTIMEOUT, ser retornado 0(zero).
Sintaxe
oObj:GETSMTPTIMEOUT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna um tempo em segundos, que representa o tempo para a finalizao
da conexo com o servidor SMTP.
Descrio
Mtodo GETSMTPTIMEOUT
O mtodo GetSMTPTimeOut() da classe tMailManager tem como objetivo retornar o
tempo em segundos que est estabelecido com o servidor SMTP para que seja finalizada
a conexo por time-out.
Obs.: caso nao tenha sido estabelecido nenhum tempo de time-out pela funo
SETSMTPTIMEOUT, ser retornado 0(zero).
Sintaxe
oObj:GETUSER ( ) --> sRet
Retorno
Tipo
Caracter
Descrio
Retorna uma String contento o nome do usuario da conta de email que
estamos conectados.
Descrio
Mtodo GETUSER
O mtodo usado apenas para conexo IMAP.
A funo GetUser() da classe de email tMailManager tem como objetivo obter o usuario
corrente em que estamos logados no momento.
A funo ir retornar uma string contendo o valor da conta de email do usuario antes do
@.
Sintaxe
oObj:IMAPCONNECT ( ) --> lRet
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possvel realizar a conexo no servidor Imap,
false caso contrrio.
Descrio
Mtodo IMAPCONNECT usado apenas para conexo IMAP.
O mtodo IMAPConnect() da classe TMailManager tem como objetivo realizar a conexo
em um IMAP e-mail server e sincroniza o mailbox folders.
A conexo atravs de IMAP trata-se de um mtodo de acesso a mensagens eletrnicas
armazenadas em um servidor local ou remoto.
O mtodo ir se conectar de acordo com os dados informados atravs do mtodo init().
Obs.:Uma caracterstica importante do IMAP permitir que a manipulao de
mensagens e pastas seja feita como se estivessem no computador local. Sempre que
for estabelecida uma conexo com servidor IMAP atravs da funo imapConnect()
importante finalizar a conexo utilizando a imapDisconnect().
Sintaxe
oObj:IMAPDISCONNECT ( ) --> lRet
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possvel realizar a finalizao da conexo no
servidor Imap, false caso contrrio.
Descrio
Mtodo IMAPDISCONNECT usado apenas para conexo IMAP.
O mtodo IMAPDisConnect() da classe TMailManager tem como objetivo realizar o fim
da conexo entre a aplicao e um IMAP e-mail server.
Obs.: sempre que for estabelecida uma conexo com servidor IMAP atravs da funo
imapConnect() importante finalizar a conexo utilizando a disconnect.
Sintaxe
oObj:IMAPSTORE ( < cFolder > , < oMsg > ) --> nRet
Parmetros
Argumento
cFolder
oMsg
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.
Retorno
Tipo
Numrico
Descrio
Retorna um inteiro informando o status da operao, caso retornado 1
ocorreu erro durante a funo, caso contrario retorna outros valores de
informao.
Descrio
Mtodo IMAPSTORE usado apenas para conexo IMAP
O mtodo imapStore() da classe tMailManager tem como objetivo armazenar uma
determinada mensagem em algum folder do servidor IMAP.
Obs.: A funo muito util quando por exemplo desejamos que ao enviar uma mensagem
ela seja salva em alguma pasta do server IMAP.
Sintaxe
oObj:INIT ( < cPopImap > , < cSmtp > , < cUser > , < cPass > , < nTimeOut > , < nPorta
> ) --> NIL
Parmetros
Argumento
Tipo
cPopImap
Caracter
cSmtp
Caracter
cUser
cPass
nTimeOut
nPorta
Caracter
Caracter
Numrico
Numrico
Retorno
Tipo
(NULO)
Descrio
Descrio
Retorno nulo.
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.
Mtodo INIT
Atravs desse mtodo da classe tMailManager, iniciamos uma nova conexo com um
servidor de emails POP ou SMTP.
Quando informamos por argumento o servidor pop (Ex.: pop3.microsiga.com.br) que
siginifica o protocolo usado na internet para a recebimento de mensagens ao usurio final
e o servidor smtp (Ex.: smtp.microsiga.com.br) que siginifica o protocolo usado na
internet para a envio de mensagens ao usurio final, devemos tambm informar um
usuario que esteja devidamente cadastrado no servidor e sua senha.
Podemos ainda informar o tempo de timeout para queda da conexo e ainda o numero de
porta, caso a porta do servidor desejado no seja a default de um smtp
Sintaxe
oObj:MOVEMSG ( < nNumMsg > , < sFolder > ) --> lRet
Parmetros
Argumento
nNumMsg
sFolder
Tipo
Descrio
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.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha sido possivel encontrar a mensagem requirida e
mover para a pasta informada, false caso contrrio.
Descrio
Mtodo MOVEMSG usada apenas para conexo IMAP.
A funo MoveMsg() da classe tMailManager tem como objetivo mover uma
determinada mensagem da pasta corrente em que estamos posicionados no servidor
IMAP para uma outra pasta no servidor.
muito importante entendermos a localizao que estamos no server IMAP, isso quando
usamos funoes que lidam com os folder como changeFolder(), createFolder() ou
deleteFolder().
Para mover uma mensagem devemos informar qual mensagem queremos mover atravs
do primeiro parametro da funo e a pasta de acordo com o nome no servidor IMAP, a
funo ir procurar pelo ID da mensagem apenas na pasta em que estamos posicionados e
tentar mover para o folder informado(lembrando que o nome deve ser identico ao criado
no servidor)
Sintaxe
tMailManager():NEW ( ) --> oObjtMailManager
Retorno
Tipo
Objeto
Descrio
Retorna uma nova instncia do Objeto da Classe tMailManager.
Descrio
Contrutor da Classe tMailManager.
Retorna uma nova instncia do Objeto da Classe tMailManager.
Antes da utilizao das funes e/ou propriedades da classe de email necessario
criarmos uma instancia da classe atravs do contrutor New().
Sintaxe
oObj:POPCONNECT ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo POPCONNECT
O mtodo PopConnect() da classe TmailManager se conecta com o servidor de email,
atravs dos parametros que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor POP, ou seja, apenas realizaremos o
recebimento das mensagens existentes na caixa postal do usuario informado.
Sintaxe
oObj:POPDISCONNECT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Descrio
Retorna 0 quando for Disconectado, outro valor caso contrrio.
Mtodo POPDISCONNECT
O mtodo POPDisconnect() da classe TMailManager ir realizar o fim da conexo com o
servidor POP, se desconectando apenas com o servidor POP.
Ao solicitar a finalizao da conexo com o servidor POP, a funo ir retornar o status
da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso
contrrio.
Sintaxe
oObj:PURGE ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo PURGE usado apenas para conexo IMAP
O metodo purge() da classe tMailManager
Sintaxe
oObj:RENAMEFOLDER ( < sOldFolder > , < sNewFolder > ) --> lRet
Parmetros
Argumento
sOldFolder
sNewFolder
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.
Retorno
Tipo
(NULO)
Descrio
Retorna true caso tenha sido possvel realizar a mudana de nome das
pastas, false caso contrrio.
Descrio
Mtodo RENAMEFOLDER usado apenas para conexo IMAP.
Tipo
sFrom
Caracter
sTo
Caracter
sSubject
Caracter
sBody
Caracter
sCC
Caracter
cBCC
Caracter
aAttach
Array
nNumAttach
Numrico
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.
Retorno
Tipo
(NULO)
Descrio
Retrona 0, quando o E-mail for enviado com sucesso, outro valor qualquer
caso contrario.
Descrio
Mtodo SENDMAIL
O mtodo SendMail() da classe TMailManager tem a funo de mandar um e-mail de
acordo com os dados passados por parametro para a funo.
Ao informar os parametros que representam os destinatarios pode-se informar mais de
uma conta de email, porm devidamente separada por ; Ex.: user1@server.com.br;
user2@server.com.br
Sintaxe
oObj:SETFOLDERSUBSCRIBE ( < cFolder > , < lAssinado > ) --> lRet
Parmetros
Argumento
cFolder
lAssinado
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.
Retorno
Tipo
Lgico
Descrio
Retorna true caso a operao tenha sido realizada com sucesso, falso caso
contrrio.
Descrio
Mtodo SETFOLDERSUBSCRIBE usado apenas para conexo IMAP.
A funo setFolderSubscribe da classe tMailManager tem como objetivo tornar uma pasta
do servidor de email IMAP assinada.
Tornar uma pasta assinada, tem um significado parecido como deixa-l visivel em nossa
caixa de email, as mensagens para esta pasta sero 'baixadas'.
A pasta Inbox por exemplo, sempre assinada por default.
Sintaxe
oObj:SETMSGFLAG ( < nNumMsg > , < sFlag > ) --> lRet
Parmetros
Argumento
nNumMsg
sFlag
Tipo Descrio
Indica o numero da mensagem que desejamos alterar seu
Array
status(flag).
Array Informa o novo status que desejamos para a mensagem.
Retorno
Tipo
Lgico
Descrio
Retorna true caso a mensagem tenha sido setada corretamente, caso
contrrio false.
Descrio
Mtodo SETMSGFLAG usado apenas para conexo IMAP.
A funo SetMsgFlag() da classe tMailManager tem como objetivo indicar o status para
uma determinada mensagem indicada de acordo com o parametro informado para a
funo.
Os estados possiveis para setar na mensagem so:
A = ANSWERED, F = FLAGGED, D = DELETED, S = SEEN, R = DRAFT, C = RECENT, P =
SPECIAL
Sintaxe
oObj:SETPOPTIMEOUT ( < nTimeOut > ) --> nRet
Parmetros
Argumento
nTimeOut
Tipo
Descrio
Numrico Tempo para que a conexo seja fechada por Time-Out.
Retorno
Tipo
Numrico
Descrio
0 = Time out setado
Descrio
Mtodo SETPOPTIMEOUT
O mtodo SetPopTimeOut() da classe tMailmanager ir configurar um tempo para que
uma conexo estabelecida com servidor POP seja finalizada por time-out.
Obs.: O tempo informado pelo mtodo deve ser em segundos.
Sintaxe
oObj:SETSMTPTIMEOUT ( < nTime > ) --> nRet
Parmetros
Argumento
nTime
Tipo
Descrio
Numrico Tempo para que a conexo seja fechada por Time-Out.
Retorno
Tipo
Numrico
Descrio
0 - Time out configurado
Descrio
Mtodo SETSMTPTIMEOUT
O mtodo SetSMTPTimeOut() da classe tMailmanager ir configurar um tempo para que
uma conexo estabelecida com servidor SMTP seja finalizada por time-out.
Obs.: O tempo informado pelo mtodo deve ser em segundos.
Sintaxe
oObj:SETUSEREALID ( < lOpt > ) --> NIL
Parmetros
Argumento
lOpt
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.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SETUSEREALID usado apenas para conexo IMAP.
A funo SetUseRealID() da classe tMailManager tem como objetivo definir qual id ser
usado para busca das mensagens.
Uma mensagem de email possui dois modos de se identificada no servidor IMAP:
-Atravs do seu nmero(o servidor mantm um 'contador' do numero de mensagens que
chegam para determinada conta e atribui esse numero a mensagem. Ex: Imagine uma
conta que acabou de ser criada, ao receber sua 1 msg, esta recebera um identificador de
numero 1 e assim por diante..).
-Atravs de um ID nico que o servidor atribui para a mensagem.
Por default as funoes usam o numero da mensagem, podemos usar a funo
SetUseRealID() para mudar isso, passando um parametro booleano para a funo.
Sintaxe
oObj:SMTPCONNECT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
0 - Conectado
Descrio
Mtodo SMTPCONNECT
O mtodo SMTPConnect() da classe TmailManager se conecta com o servidor de email,
atravs dos parametros que foram informados atravs do mtodo INIT().
Com esse mtodo realizamos a conexo no servidor SMTP, ou seja, apenas realizaremos
o envio de mensagens para uma determinada conta de usuario, informados anteriormente
pelo metodo INIT().
Sintaxe
oObj:SMTPDISCONNECT ( ) --> nRet
Retorno
Tipo
(NULO)
Descrio
0 = Disconectado
Descrio
Mtodo SMTPDISCONNECT
O mtodo SMTPDisconnect() da classe TMailManager ir realizar o fim da conexo com
o servidor SMTP, se desconectando apenas com o servidor SMTP.
Ao solicitar a finalizao da conexo com o servidor SMTP, a funo ir retornar o status
da operao, caso tenha sido bem sucedida retorna 0, outros valores de erro caso
contrrio.
Sintaxe
oObj:STARTGETALLMSGHEADER ( < sFOlder > , < aHeader > ) --> lRet
Parmetros
Argumento
Tipo
Descrio
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.
sFOlder
aHeader
Retorno
Tipo
Descrio
Retorna true caso tenha sido possivel iniciar o processo de obteno de
cabealho das mensagens, false caso contrario.
Lgico
Descrio
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
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
Tipo
Descrio
Representa os dados que desejamos informa no caso de um
Caracter
arquivo atachado.
Retorno
Tipo
(NULO)
Descrio
Descrio
Retorno nulo.
Mtodo ADDATTHTAG
O mtodo addAttTag() da classe tMailMessage tem como objetivo setar alguma
informao especial quando passado algum arquivo atachado para a mensagem que ser
enviada.
Ex: AddAtthTag( 'Content-Disposition: attachment; filename=arquivo.txt')
adiciono uma tag informando que um attach e o nome do arquivo.
Sintaxe
oObj:ATTACHFILE ( < cArq > ) --> NIL
Parmetros
Argumento
cArq
Tipo
Descrio
Caracter Indica o nome do arquivo a ser adicionado no e-mail.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo ATTACHFILE
O mtodo AttachFile() da classe tMailMessage tem como objetivo adicionar um arquivo
ao objeto de e-mail, 'um Attach'.
Sintaxe
oObj:CLEAR ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo CLEAR
O mtodo clear() da classe tMailMessage tem como objetivo limpar o conteudo do objeto,
assim podemos receber varias mensagem no mesmo objeto, apenas limpando o seu
conteudo antes.
Usando a funo clear, nao precisamos criar varias vezes o mesmo objeto, para receber
mais de uma mensagem.
Sintaxe
oObj:GETATTACH ( < cNumMsg > ) --> sRet
Parmetros
Argumento
cNumMsg
Tipo
Descrio
Representa o Id(numero da mensagem) que desejamos
Numrico
obter informaes.
Retorno
Tipo
Caracter
Descrio
Retorno uma String(cadeia de caracteres) contendo o conteudo do arquivo
atachado na mensagem.
Descrio
Mtodo GETATTACH
O mtodo getAttach da classe tMailMessage tem como objetivo obter o conteudo do
arquivo atachado e retornar esse conteudo atravs de uma String.
Devemos informar o numero da mensagem que desejamos obter o attach.
Sintaxe
oObj:GETATTACHCOUNT ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna o numero de anexos a mensagem.
Descrio
Mtodo GETATTACHCOUNT
O mtodo getAttachCount() da classe tMailMessage tem como objetivo informar qual a
quantidade de arquivos anexados a mensagem.
Sintaxe
oObj:GETATTACHINFO ( < nMsg > ) --> NIL
Parmetros
Argumento
nMsg
Tipo
Descrio
Numrico Indica o numero da mensagem que desejamos verificar.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo GETATTACHINFO
O mtodo getAttachInfo() da classe tMailMessage tem como objetivo trazer todas
informaoes sobre um attachment em alguma mensagem.
Devemos informar o numero da mensagem que desejamos trazer as informaoes sobre os
attachments, o mtodo ir retornar as seguintes informaes:
ShortName: O nome do attachment
Type: O tipo do attachment, podendo ser FILE e TEXT por exemplo.
Disposition: Tipo do arquivo
DispositionName: informa o nome do tipo de arquivo
Id: Identificao do attachment
Location: Local fisico do attachment
Sintaxe
tMailMessage():NEW ( ) --> oObjtMailMessage
Retorno
Tipo
Objeto
Descrio
Retorna uma nova instncia do Objeto da Classe tMailMessage.
Descrio
Contrutor da Classe tMailMessage.
Sintaxe
oObj:RECEIVE ( < oServer > , < nMsg > ) --> nRet
Parmetros
Argumento
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.
oServer
nMsg
Retorno
Tipo
Numrico
Descrio
Retorna 0(zero) quando o E-mail foi recebido com sucesso, outro valor caso
contrrio.
Descrio
Mtodo RECEIVE
O mtodo receive() da classe tMailMessage, tem como objetivo receber uma nova
mensagem do servidor populando o objeto da mensagem.
Sintaxe
oObj:SAVE ( < cNumMsg > ) --> NIL
Parmetros
Argumento
cNumMsg
Tipo Descrio
Array Representa o numero da mensagem que desejamos salvar.
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SAVE
O mtodo save() da classe tMailMessage tem como objetivo obter todo o conteudo de
uma determinada mensagem, que ser encontrada atravs do parametro informado, que
repesenta o Id(numero da mensagem) e salvar a mensagem.
Sintaxe
oObj:SEND ( < oServer > ) --> NIL
Parmetros
Argumento
Tipo
Descrio
Indica o objeto da classe tMailManager para o envio da
Objeto
mensagem.
oServer
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Mtodo SEND
O mtodo Send() da classe TMailMessage tem a funo de enviar um e-mail de acordo
com os dados passados pelo objeto da classe tMailManager por parametro para a funo.
Para que a funo seja usada corretamente preciso antes popular algumas das
propriedades da classe tMailMessage basicas para o envio como:
cFrom: Email de quem est mandando.
cTo: Email(s) para o qual desejamos enviar a mensagem.
cCc: Email(s) para o qual desejamos enviar a mensagem na seo "com cpia".
cBcc: Email(s) para o qual desejamos enviar a mensagem na seo "com cpia Oculta".
cSubject: Assunto da mensagem que ser enviada.
cBody: Conteudo da mensagem.
Descrio
Esta classe permite estabelecer uma conexo cliente de socket do tipo TCP genrica.
Enviar e receber dados atravs de uma socket genrico e tambm pode ser usada como
base para implementao de protocolos no suportados pelo protheus.
Mtodos
Mtodo
Descrio
CloseConnection
Connect
IsConnected
New
Receive
Reset
Send
endif
return
Sintaxe
oObj:CloseConnection ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Finaliza a conexo TCP genrica (socket ) do objeto corrente.
Sintaxe
oObj:CloseConnection ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Finaliza a conexo TCP genrica (socket ) do objeto corrente.
Abrangncia
Verso 6.09
Verso 7.10
Verso 8.11
Sintaxe
oObj:IsConnected ( ) --> lLogico
Retorno
Tipo
Lgico
Descrio
Retorna True se a conexo esta ativa e false caso esteja
invlida/desconectado.
Descrio
Verifica se existe conexo valida no objeto corrente.
Sintaxe
tSocketClient():New ( ) --> oSocket
Retorno
Tipo
Objeto
Descrio
Retorna um Objeto do tipo tSocketClient
Descrio
Cria o objeto tSocketClient, sem conexo ativa.
Sintaxe
oObj:Receive ( < @cBuffer > , < nTimeout > ) --> nQtdRecebida
Parmetros
Argumento
cBuffer
nTimeout
Tipo
Descrio
Caracter Buffer que conter os dados a serem recebidos.
tempo em milisegundos que a funo receive espera at
Numrico
receber algum dado pela conexo.
Retorno
Tipo
Numrico
Descrio
Qtde de bytes recebidos, se houver algum erro nQtdRecebida ser menor
que zero.
Descrio
Recebe os dados pela conexo ativa do objeto, qualquer tipo de dado pode ser recebido.
Sintaxe
oObj:Reset ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Retorno nulo.
Descrio
Finaliza anormalmente a conexo, no avisa o outro lado que a conexo ser finalizada.
Deve ser utilizado apenas em casos extremos.
Sintaxe
oObj:Send ( [ cBuffer ] ) --> nQtdTrasmitido
Parmetros
Argumento
cBuffer
Tipo
Descrio
Caracter Buffer com os dados a serem transmitidos pela conexo.
Retorno
Tipo
Numrico
Descrio
Numero de bytes transmitidos, caso o numero seja diferente do tamanho de
cBuffer, algum erro aconteceu.
Descrio
Transmite o buffer pela conexo TCP Genrica ativa.
BANCO DE DADOS
Copy
Sintaxe
COPY [ FIELDS <campo,...> ] TO xcFile [ escopo ] [ WHILE <lCondicao> ] [ FOR
<lCondicao> ] [ SDF | DELIMITED [WITH <xcDelimiter>] ] [ VIA <xcDriver> ]
Parmetros
Argumento
FIELDS
<campo,...>
TO xcFile
Tipo
Descrio
FIELDS <campo,...> especifica um ou mais campos,
separados por vrgula, a serem copiados para a tabela de
Caracter
destino. Caso no especificado este parmetro, sero
copiados todos os campos da tabela de origem.
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.
escopo
[ SDF |
DELIMITED
[WITH
<xcDelimiter>] ]
VIA <xcDriver>
Formato
T ou F
(campo ignorado)
Delimitador de Campos
Nenhum
Separador de Registros
Formato
T ou F
(campo ignorado)
Delimitador de Campos
Vrgula
Separador de Registros
COPY STRUCTURE
Abrangncia
Verso 5.07
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Sintaxe
COPY STRUCTURE TO <xcDataBase>
Parmetros
Argumento
Tipo
Descrio
Deve ser especificado em xcDatabase o nome da tabela a 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
FUNES GENRICAS
Sintaxe
EXISTDIR ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo ExistDir tem como objetivo determinar se um path de diretrio existe e valido.
Exemplo no server a partir do rootPath:
ExistDir('\teste')
Exemplo no client, passando o fullPath:
ExistDir('c:\APO')
Sintaxe
FTPVERSION ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
Retorna uma String contendo o valor da verso de FTP.
Descrio
A funo FtpVersion tem como objetivo determinar qual a verso do Protocolo de
Transferncia de Arquivos.
Sintaxe
Descrio
Nome da mquina
Descrio
Retorna o nome da mquina (HOSTNAME) que est executando o Protheus Remote
Sintaxe
GETENV ( < cVariavel > ) --> cRet
Parmetros
Argumento
cVariavel
Tipo
Descrio
Nome da variavel de ambiente do sistema que desejamos
Caracter
obter.
Retorno
Tipo
Caracter
Descrio
Retorna o contedo da varivavel de ambiente, se encontrada na tabela de
variaveis de sistema. Caso contrrio, retorna NIL.
Descrio
A funo GetEnv() tm como objetivo determinar o valor de uma
varivel do environment da plataforma(Sistema Operacional) em uso, no ambiente do
Protheus Server.
O valor de retorno da funo ser NIL se o parametro varname informado no for
encontrado na tabela das variveis de ambiente do Sistema Operacional.
Exemplo:
cSysPath := GetEnv('PATH')
Sintaxe
GETENVSERVER ( ) --> cRet
Retorno
Tipo
Caracter
Descrio
String contendo o nome do environment em execuo.
Descrio
A funo GetEnvServer() tem como objetivo retornar uma string que nos permite
determinar o nome do Environment que est rodando atualmente no Server Protheus.
Um exemplo interessante da funo quando desejamos rodar um programa e nao
sabemos em qual environment estaremos.
StartJob('Teste', GetEnvServer(), .T., '99', '01' )
Sintaxe
GETREMOTETYPE ( ) --> nRmtType
Retorno
Tipo
Numrico
Descrio
nRmtType corresponde o nmero correspondente interface utilizada.
Descrio
Atravs da funo GetRemoteType(), possvel identificar sob qual interface o
programa atual est em execuo.
Esta funo est disponvel a partir do Protheus 8, Build 7.00.040308a
Pode-se utilizar as constantes abaixo, para avaliar o retorno da funo.
NO_REMOTE
REMOTE_QT_WIN32
REMOTE_QT_LINUX
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
Tipo
Descrio
Indica o local ou Semafora em que as Threads foram
Caracter
iniciados.
Retorno
Tipo
Numrico
Descrio
A funo retorna um inteiro indicando oo numero de Threads LIVRES de
acordo com o semaforo indicado por parametro.
Descrio
A funo IPCCount tem como objetivo obter todas as Threads que esto no ar em um
determinado ambiente indicado pelo semaforo.
A funo ir retornar um inteiro indicando o total de threads livres que esto esperando
um IPCGo.
Sintaxe
IPCGo ( < cSemaforo > ) --> Nil
Parmetros
Argumento
cSemaforo
Tipo
Descrio
Indica o local ou Semaforo em que as Threads foram
Caracter
iniciados.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo IPCGo tem como objetivo mandar uma chamada para uma Thread, na qual nao
precisa ser necessariamente em mesmos ambientes, que esteja em wait.
A IPCGo devemos atravs de um primeiro argumento da funo, especificar o semaforo
que desejamos, a funo ir pegar a primeira Thread Livre que encontrar em IPCWait.
A funo recebe mais 15 argumentos opcionais para passagem de dados, porm este valor
no pode ser um Boolean ou um CodeBlock.
Sintaxe
IPCWait ( < nTimeOut > ) --> lRet
Parmetros
Argumento
nTimeOut
Tipo
Descrio
Numerico que Indica um tempo de timeOut em
Numrico
milissegundos, para a thread sair do ar.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao
recebeu nehuma chamada ou saiu por timeOut.
Descrio
A funo IPCWait() tem como objetivo colocar em modo de espera uma Thread que
acabou de ser carregada e fica aguardando oo chamado de uma IPCGo(). A funo recebe
um parametro numrico que indica o timeOut em milissegundos de tempo para que a
Thread seja derrubada.
A IPCWait() recebe mais 15 parametros opcionais - que indica os parametros passados
pela IPCGo() Retorna true caso tenha chegado um chamado da IPCGo(), false no recebeu nenhum
IPCGo ou saiu por timeOut.
obs: note que nao foi indicado um valor de semaforo para a funo, pois est
implicito o programa que iniciou a Thread.
Sintaxe
Tipo
Descrio
Caracter Indica o nome do Semaforo que estamos trabalhando.
Numerico que Indica um tempo de timeOut em
Numrico
milissegundos, para a thread sair do ar.
Retorno
Tipo
Lgico
Descrio
Retorna true caso tenha recebido uma chamada da IPCGo, false caso nao
recebeu nehuma chamada ou saiu por timeOut.
Descrio
A funo IPCWaitEx() tem como objetivo colocar em modo de espera uma Thread que
acabou de ser carregada e fica aguardando oo chamado de uma IPCGo(). Na IPCWaitEx()
devemos indicar o nome do semaforo que queremos.
A funo recebe como segundo parametro numrico que indica o timeOut em
milissegundos de tempo para que a Thread seja derrubada.
A IPCWaitEx() recebe mais 15 parametros opcionais - que indica os parametros passados
pela IPCGo() Retorna true caso tenha chegado um chamado da IPCGo(), false no recebeu nenhum
IPCGo ou saiu por timeOut.
Obs: note que na IPCWaitEx foi indicado um valor de semaforo para a funo.
Sintaxe
ISSRVUNIX ( ) --> lisUnix
Retorno
Tipo
Lgico
Descrio
Se .T. o servidor est sendo executado em ambiente Unix(r) ou Linux(r)
Se .F. o servidor est sendo executado em ambiente Windows(r)
Descrio
Informa se o servidor Advanced Protheus est sendo executado em ambiente UNIX ou
Linux.
Verso 7.10
Verso 8.11
Sintaxe
KILLAPP ( [ lKill ] ) --> lRet
Parmetros
Argumento
lKill
Tipo
Descrio
Parametro opcional indicando se Thread corrente deve ser
Lgico
finalizada.
Retorno
Tipo
Lgico
Descrio
Descrio
retorna se thread corrente j recebeu algum aviso para ser finalizada(true),
caso contrrio retorna false.
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. )
Descrio
Nil
Descrio
Se o Protheus Remote est sendo executado em background (abaixo de outras janelas de
outros programas no desktop do usurio), a funo MSAPPBRINGTOFRONT( ) pode ser
utilizada para avisar ao sistema operacional para que mude a disposio das janelas ativas
no desktop para que exiba a janela do Protheus Remote acima de todas as janelas das
outras aplicaes em execuo.
Nos sistemas operacionais Windows, se o sistema operacional no conseguir executar o
comando para movimentar as janelas, a barras de janelas do Windows ficar piscando
sobre a ocorrncia do Protheus Remote para avisar o usurio sobre a inteno do
programa (Protheus Remote) ser visualizado.
Sintaxe
MSCRC32 ( < cString > ) --> nCRC
Parmetros
Argumento
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
Um nmero inteiro , com at 10 (dez) dgitos , correspondente ao CRC da
string informada como parmetro.
Descrio
Calcula um CRC de uma string. A funo MSCRC32() calcula um CRC de uma string
informada e retorna um nmero com esse clculo.
Note que strings iguais retornam CRC iguais, porm, nem sempre strings diferentes
retornam CRC diferentes.
Atravs do exemplo abaixo , calculamos o CRC das strings informadas.
// Le o arquivo lista.txt no ambiente do servidor
// e calcula o CRC do mesmo.
cString := memoread('\lista.txt')
nCRC1 := MSCRC32(cString)
MsgStop('CRC = '+str(nCRC1,10))
Sintaxe
MSCRC32STR ( < cString > ) --> cCRC32
Parmetros
Argumento
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
Nil
Descrio
Muitas vezes desenvolvemos rotinas de durao longa que quando chamadas atravs de
uma ao no Protheus Remote (Exemplo: Opo acionada no menu) provocam um
'congelamento' temporrio nas telas do Protheus Remote.
Para minimizar esse efeito, podemos utilizar a funo PROCESSMESSAGES( ) para que
o Protheus Remote possa renovar a pintura de suas janelas ou reagir a ao do mouse
durante um processamento longo sendo executado no Protheus Server. Como o exemplo
a seguir :
while nRecs<1000
ProcessMessages( )
// Processo Longo
DoSomethingLongTime( )
nRec-enddo
Sintaxe
RANDOMIZE ( < nMinimo > , < nMaximo > ) --> nAleatorio
Parmetros
Argumento
nMinimo
Tipo
Descrio
Numrico Corresponde ao menor numero a ser gerado pela funo.
Corresponde ao maior nmero ( menos um ) a ser gerado
Numrico
pela funo.
nMaximo
Retorno
Tipo
Numrico
Descrio
Numero randmico , compreendido no intervalo entre (nMinimo) e
(nMaximo-1) : O numero gerado pode ser maior ou igual nMinimo e
menor ou igual a nMaximo-1 .
Descrio
Atravs da funo randomize() , geramos um numero inteiro aleatrio, compreendido
entre a faixa inferior e superior recebida atravs dos parmetros nMinimo e nMaximo,
respectivamente.
Observao :
O limite inferior recebido atravs do parmetro nMinimo "maior ou igual a ", podendo
ser sorteado e fazer parte do retorno; porm o limite superior "menor que", de modo a
nunca ser atingido ou devolvido no resultado. Por exemplo , a chamada da funo
randomize(1,2) sempre retornar 1 .
Sintaxe
SENDTOFORE ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Esta funo no retorna valor
Descrio
Esta funo torna a aplicao do Remote foreground na estao em que est sendo
executado.
Faz com que a janela ativa do Remote fique acima de todas as janelas de outras aplicaes
executadas na estao.
Extremamente dependente do sistema operacional em uso, as vezes pode falhar devido ao
sistema operacional no suportar o comando ou devido a carga excessiva do sistema, o
sistema operacional pode ignorar o comando.
Sintaxe
SOCKETCONN ( < cIP > , < nPort > , < cReq > , < nTimeOut > ) --> Nil
Parmetros
Argumento
Tipo
cIP
Caracter
nPort
Numrico
cReq
Caracter
nTimeOut
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).
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo SocketConn usada para criar uma conexo com um determinado destino,
atravs da conexo de um Socket Client.
Para Realizar esta conexo informamos o destino, no qual pode ser informado em forma
de IP ou atravs de um nome de mquina. Em seguida informamos o numero de porta na
qual ser realizado um bind atravs dessa porta.
Em seguida informamos atravs de string o tipo de requisio que iremos realizar, pois
quando a conexo ao socket destino completada com sucesso, a funo ir enviar e
receber dados de acordo com a requisio que fizemos.
Por ltimo informamos o total de tempo em segundos que a funo ir ficar esperando por
uma resposta do destino informado.
Sintaxe
XMLERROR ( ) --> nXmlStatus
Retorno
Tipo
Caracter
Descrio
Retorna o status da ultima operao de Criao de Objeto XML realizado
pelo comando CREATE oXml ...
Descrio
A funcao XmlError() retorna um status da execuo da ultima rotina de criao de Objeto
XML realizada pelo comando CREATE oXML. Podemos utilizar-nos das constantes
definidas no arquivo #INCLUDE "XmlxFun.CH" para realizar o tratamento de erro. Vide
tabelas de constantes abaixo :
---------------------------------------Constante Valor
---------------------------------------XERROR_ONLYFIRSTNODE -1
XERROR_SUCCESS 0
XERROR_FILE_NOT_FOUND 1
XERROR_OPEN_ERROR 2
XERROR_INVALID_XML 3
----------------------------------------
#INCLUDE "XmlXFun.xh"
Local oXml , nXmlStatus
CREATE oXML XMLFILE "\exemplo.xml"
nXmlStatus := XMLError()
If ( nXmlStatus != XERROR_SUCCESS )
Alert("Falha ("+str(nXmlStatus,3)+") na criao do XMLl")
Else
//processamento dop XML ....
Endif
Sintaxe
compress ( < @cBufferOut > , < @nLenghtOut > , < @cBufferIn > , < @nLengthIn > )
--> bOk
Parmetros
Argumento
cBufferOut
nLenghtOut
cBufferIn
nLengthIn
Tipo
Descrio
Retorna o buffer compactado, a varivel dever ser do 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.
Retorno
Tipo
Lgico
Descrio
Retorna .T., caso o buffer foi compactado com sucesso.
Retorna .F., caso no seja possvel compactar o buffer.
Descrio
Compacta um buffer recebido, atravs do algoritmo proprietrio.
Na maioria dos casos o buffer recebido ser menor do que o buffer original, em casos
onde o buffer original muito pequeno, menos de 128 bytes, o buffer de sada poder ser
maior do que o o buffer original.
Essa funo aceita e retorna caracteres binrios de vrios tipos, incluindo o zero binrio.
O Resultado dessa funo no dever ser gravado em banco de dados, especialmente
TopConnect.
Exemplos
user function TSTComp
Local cNaoComp := replicate( 'A', 1024 )
Local cComp := '', cResult := ''
Local nTamNaoComp := len( cNaoComp )
Local nTamComp := 0
Local bResp
bResp := compress( @cComp, @nTamComp, cNaoComp, nTamNaoComp )
If( bResp )
Alert( "Buffer Compactado - Tamanho Compactado" + str( nTamComp
) )
else
Alert( "Falha ao compactar o Buffer!" )
return
endif
bResp := uncompress( @cResult, @nTamNaoComp, cComp, nTamComp )
If( !bResp )
Alert( "Falha ao descompactar o Buffer!" )
return
endif
if( cResult != cNaoComp )
Alert( "Buffer descompactado diferente do buffer original" )
else
Alert( "Buffer descompactado igual ao buffer original" )
endif
return .t.
Sintaxe
uncompress ( < @cBufferOut > , < @nLengthOut > , < cBufferIn > , < @nLengthIn > )
--> bOK
Parmetros
Argumento
Tipo
cBufferOut
Caracter
nLengthOut
cBufferIn
Numrico
Caracter
nLengthIn
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.
Retorno
Tipo
Lgico
Descrio
Retorna .t., caso o buffer foi descompacto com sucesso.
Retorna .F., caso no seja possvel descompactar o buffer.
Descrio
Descompacta um buffer recebido, atravs do algoritmo proprietrio.
Este buffer devera ser gerado pela funo compress.
Essa funo aceita e retorna caracteres binrios de vrios tipos, incluindo o zero binrio.
FUNES DE IMPRESSO
Sintaxe
GETIMPWINDOWS ( < lServer > ) --> aPrinters
Parmetros
Argumento
lServer
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.
Retorno
Tipo
Array
Descrio
Array com nome das impressoras disponveis. Vale lembrar que esta funo
no verifica o status atual da(s) impressora(s) encontrada(s).
Descrio
GETIMPWINDOWS( ) retorna uma lista de impressoras disponveis no spool do Server
ou Remote. Se o Server est em ambiente Unix, a GETIMPWINDOWS() retornar a lista
com os nomes de impressoras cadastradas na chave PRINTERSNAME do arquivo de
configurao do Protheus Server.
Caso no seja encontrada nenhuma impressora , retornado um array com 1 elemento ,
contendo a String "Nenhuma Impressora Disponivel".
Observao : Caso a funo seja passada com o argumento .F. ( buscar impressoras
da estao Remote ) , porm a funo seja executada a partir de um JOB ( programa
sem a interface Remota ) , o array retornado ter apenas 1 elemento , contendo a
String "Nenhuma Impressora Disponivel".
Exemplos
No exemplo abaixo , determinamos as impressoras disponveis na estao Remote e no
Server , respectivamente. E , mostramos no Console do Server a(s) impressora(s)
encontrada(s).
aImpRemote := GetImpWindows(.F.)
conout('Impressoras na estao remota')
aeval(aImpRemote , { |x| conout(x) })
aImpServer := GetImpWindows(.T.)
conout('Impressoras no Servidor')
aeval(aImpServer , { |x| conout(x) })
Sintaxe
Tipo
Descrio
CAso especificado .T. , a lista de impressoras ser obtida do
Lgico
Server, caso .F. a lista ser obtida da estao (Remote).
Retorno
Tipo
Array
Descrio
Array com as portas de impresso disponveis.
Descrio
Retorna lista de portas de impresso disponveis. A funo GETPORTACTIVE( ) retorna
uma lista de portas de impresso disponveis do Protheus Server ou Remote. Se o
Protheus Server est em ambiente Unix, a GETPORTACTIVE() retornar uma lista com
os nomes de devices possveis para impresso.
Caso no sejam encontradas portas para impresso , retornado um array com apenas um
elemento , contendo a string "Nao existem portas disponiveis".
Observao : Caso a funo seja chamada com o parmetro .F. , para obter as
portas de impresso da estao remota , porm a funo seja chamada atravs de
um JOB ( programa sem a interface Remote ) , a mesma retornar um array com
um elemento , contendo a string "Nao existem portas disponiveis".
[RELEASE] Builds superiores a 7.00.041130p
Ao verificar os devices de impresso disponveis no SERVER, os devices especificados
na configurao de bloqueio de portas de impresso ( DisableDevicePort ) no server no
so listados por esta funo.
Quando executada em ambiente Linux, os devices de impresso disponveis no SERVER,
a funo deixa de retornar os devices como /dev/lp0 e /dev/ttys0 ... e passa a retorn-los a
nomenclatura LPT1:...COM1:... , limitando o retorno em no mximo 4 portas paralelas e
4 portas seriais.
Exemplos
No exemplo abaixo, determinamos as portas de impresso disponveis na estao Remote
e no Server, respectivamente. E mostramos no Console do Server a(s) porta(s)
encontrada(s).
aPortRemote := GetPortActive(.F.)
conout('Impressoras na estao remota')
aeval(aPortRemote , { |x| conout(x) })
aPortServer := GetPortActive(.T.)
conout('Impressoras no Servidor')
aeval(aPortServer , { |x| conout(x) })
Veja abaixo um exemplo do que foi mostrado no console do Protheus Server, apos a
execuo da rotina.
Impressoras na estao remota
COM1:
COM2:
COM3:
COM4:
FILE:
LPT1:
LPT2:
LPT3:
\\prnserver\prx-lp1
Impressoras no Servidor
COM1:
COM2:
COM3:
COM4:
FILE:
LPT1:
LPT2:
LPT3:
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.
Retorno
Tipo
Caracter
Descrio
Descrio
Retorna as informaes passadas atravs do argumento, criptografadas em
RSA.
A funo EncryptRSA tem como objetivo realizar a criptografia de dados, para isso usa
um tipo de criptografia denominada RSA.
O RSA um algoritmo de Criptografia Assimtrica, isto significa que possumos uma
chave pblica e privada, RSA o mais usado algoritmo de chave pblica, pois prov
confidencialidade e assinatura digital.
A chave pblica a que serve para cifrar a mensagem (Confidencialidade) e decifrar a
mensagem (Autenticidade). Todos que desejarem lhe enviar uma mensagem devem
conhec-la.
Chave privada, que serve para decifrar a mensagem (Confidencialidade) e cifrar a
mensagem (Autenticidade). Somente uma pessoa deve conhec-la.
Em nossa funo informamos o local onde se encontra a chave que ser usada, em
seguida passamos como string os dados que queremos criptografar, podemos ainda
informar se desejamos o retorno em base 64 ou nao.
Sintaxe
GETWEBJOB ( ) --> cJobName
Retorno
Tipo
Caracter
Descrio
cJobName corresponde o nome do job que configura a working Thread
atual em uso. Caso a chamada da funo seja realizada a partir de uma
thread que no seja uma Working Thread ( como por exemplo , uma thread
iniciada a partir de um ApxRemote ) , a funo GetWebJob() retornar uma
string vazia ("").
Descrio
Atravs desta funo , possvel recuperar o nome da configurao de Working Threads (
Job ) que est sendo utilizada pela Working Thread atual.
Observao : Esta funo est disponvel a partir dos Build's Ap6 gerados a partir
de 05/09/2002.
Sintaxe
GetEnvHost ( ) --> cHost
Retorno
Tipo
Caracter
Descrio
Quando em ambiente web retorna o host que foi utilizado para chamar a
funo.
Descrio
Retorna quando em ambiente web, por qual host a pgina foi chamada.
Exemplo:
web function retHost
return getenvhost() // Retorna o nome do host que chamou essa funcao ( Ex:
www.microsiga.com.br )
Sintaxe
HTTPCACHE ( < cCacheControl > ) --> cLastCache
Parmetros
Argumento
Tipo
cCacheControl
Descrio
Define o novo contedo da etiqueta do Header de Retorno
Caracter
HTTP Cache-Control.
Retorno
Tipo
Caracter
Descrio
Esta funo retorna a definio atualmente utilizada para a etiqueta CacheControl do Header HTTP.
Descrio
Atravs desta funo , podemos redefinir a etiqueta CACHE-CONTROL do Header de
Resposta de requisio HTTP , sobrepondo definio defaut de retorno CACHECONTROL , opcionalmente definida na configurao do HOST HTTP no Arquivo de
configurao do Protheus Server.
Sintaxe
HTTPCOUNTSESSION ( ) --> nCount
Retorno
Tipo
Numrico
Descrio
nCount corresponde ao nmero de usurios que possuem variveis de
session em uso no Server PRotheus.
Descrio
Esta funo retorna o nmero de Sessions de usurios que esto atualmente em uso na
memria.
** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **
OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um Build de Protheus Server com data igual ou superior a 22/04/2002.
Sintaxe
HTTPCTDISP ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de prover informaes sobre como apresentar uma mensagen ou
como parte de um pacote.
Quando uma parte de um pacote Http para ser tratada como um arquivo atachado, a
funo ir setar essa parte do cabealho http(Content-Disposition) como um nome de
arquivo sugerido de acordo com o parmetro.
Obs.: Caso ocorra a necessidade de verificar os tipos de parmetros usados pelo protocolo
Http das opes possveis para Content-Disposition:
http://http://www.ietf.org/rfc/rfc2183.txt
Obs.: A funo fuciona somente em Links APW
Exemplos
Neste exemplo criamos uma funo STATIC getFile(). Para usarmos a funo devemos
apenas informar o endereo fisico em disco de um aquivo.
Criamos um pequeno buffer, para ir mandando o pacote ao browser, em seguida abrimos
o arquivo com a funo FOpen() e pegamos o tamanho do arquivo com a funo FSeek().
Definimos com a funo HttpCTType o tipode arquivo que iremos carregar, em nosso
exemplo apenas arquivos texto. Usamos a HttpCTDisp informando ao browser que
estamos carregando um attachment, no caso est linha ir fazer aparecer a tela de
download de um aquivo do seu Browser default e informamos o local do arquivo.
Em seguida informamos ao browser qual o tamanho desse arquivo, retornado da funo
FSeek(), e comeamos a enviar o arquivo em pequenos pedaos de 1024bytes.
static Function GetFile( cFile )
Local cHtml
Local cBuffer
:= ''
:= space(1024)
Local hArq
Local nTam
If !file(cFile)
cHtml += '
Arquivo '+cFile+' no encontrado.
'
ElseIf (hArq := FOpen(cFile)) < 0
cHtml += '
Falha na Abertura do Arquivo '+cFile+' ( FERROR '+str(ferror(),4)+' )
'
Else
// Le o arquivo e manda p/ o browse
nTam := FSeek(hArq, 0, 2)
FSeek(hArq, 0, 0 )
HttpSetPart(.T.)
HttpCTType("text/plain")
HttpCTDisp('attachment; filename="'+cFile+'"')
HttpCTLen(nTam)
While FRead(hArq, @cBuffer, 1024)>0
HttpSend(cBuffer)
EndDo
FClose(hArq)
Endif
Return cHtml
Sintaxe
HTTPEXITPROC ( < cFunction > ) --> Nil
Parmetros
Argumento
cFunction
Tipo
Descrio
String que indica o nome da funo a ser chamada quando a
Caracter
Session for finalizada por time-out.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A httpExitProc tem o objetivo de setar uma funo que ser chamada quando uma
Session for Finalizada por Time-Out.
A funo que ser chamada para tratamento da session finalizada, deve estar compilada
no repositrio de dados corrente.
Muito til quando se deseja encaminhar todas 'quedas' de Session para uma nica funo
de tratamento.
Sintaxe
HTTPFREESESSION ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL
Descrio
Atravs da funo HttpFreeSession , eliminamos da memria do Servidor Protheus todas
as variveis de Session do usurio atual. Normalmente utilizamos esta funo em
operaes de LOGOFF , onde necessitamos limpar todas os conteudos relacionados
Session deste usurio.
** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **
OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um Build do Servidor Protheus Server com data igual ou superior a
22/04/2002.
Sintaxe
HTTPGET ( < cUrl > , [ cGETParms ] , [ nTimeOut ] ) --> cHttp
Parmetros
Argumento
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).
cUrl
cGETParms
nTimeOut
Retorno
Tipo
Caracter
Descrio
String Html correspondendo ao documento solicitado.
Descrio
A funo HttpGet() permite a emulao de um Client HTTP atravs de uma funo
Advpl, acessando um determinado documento html publicado em um servidor Web,
utiliando o mtodo GET , permitindo a passagem de parmetros via URL, aguardando por
um tempo determinado (time-out) pela resposta do servidor solicitado.
Observaes :
--- Na passagem de parmtros GET , devemos atentar ao formato da string a ser passada
como parmetros , pois a mesma segue o formato URI (Uniform Resource Identifiers) :
Query Component.
--- Caso nao seja retornado o documento antes do trmino do Time-out especificado na
chamada da funo; ou caso no seja possvel localizar o servidor ; seja por falha de
resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a funo retornar Nulo
(NIL).
--- Caso nao seja possvel o acesso ao documento , como por exemplo o documento no
exista , ser retornado uma string html com a mensagem de erro html enviada pelo
servidor correspondente.
OBSERVACAO : Esta funco est disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002
Sintaxe
HTTPGETPART ( ) --> bPartEnabled
Retorno
Tipo
Descrio
Lgico
Descrio
Esta funo retorna se o envio parcial de contedo ao browser est ou no habilitado.
Sintaxe
HTTPGETSTATUS ( ) --> nStatus
Retorno
Tipo
Numrico
Descrio
Retorna o status da conexo HTTP atual requerida
Descrio
A funo tem o objetivo de retornar qual o status da conexo HTTP requisitada.
Para tal tarefa a funo retorna valores de acordo com o protocolo HTTP, entre eles os
mais comuns e importantes so:
Error codes
500 501 502 403;14 -
:= "<h3>HttpPost</h3><br><br>"
+= "<table width=200 border=1>"
+= "<tr><td>Login</td><td>"+HttpPost+= "<tr><td>Senha</td><td>"+HttpPost+= "</table>"
Return cHtml
web Function loginMK()
Local cHtml := ""
if HttpGetStatus() == 0
cHtml := HTTPPOST( "http://ricardo/w_ExHTTPPost.apw", "",
"login=Teste&pass=123", 120 , NIL )
conout( HttpGetStatus() )
if HttpIsConnected()
conout("isConnected")
endif
endif
Return cHtml
Sintaxe
HTTPLEAVESESSION ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
A funo HttpLeaveSession() sempre retorna NIL
Descrio
Esta funo , uma vez executada , libera o processamento de requisio de atualizo de
contedos de variveis tipo HttpSession para requisies de consulta e/ou atualizaes
simultneas para o usurio atual.
** 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
Sintaxe
HTTPLOGONUSER ( ) --> cLogonUser
Retorno
Tipo
Caracter
Descrio
String contendo o login do usurio, no formato DOMINIO\login. Caso a
funo no seja executada em uma thread iniciada em uma interface http ,
ou o acesso annimo o site no IIS esteja habilitado , a funo retornar uma
string em branco ("").
Descrio
Atravs da Funo HttpLogonUser() , quando utilizamos o AP Server ISAPI
( AdvplIsapi.dll) , em conjunto com o Microsoft IIS (Internet Information Services ) ,
obtemos o login do usurio atual.
Observao : Para que o usurio seja obrigado a informar um login individual , deve
ser desabilitado no IIS a configurao que permite acesso annimo ao site. Caso esta
configurao no seja alterada , todos os usurios sero identificados como
"annimos" pelo IIS, e a funo retornar uma String em branco.
Sintaxe
HTTPOTHERCONTENT ( ) --> cContent
Retorno
Tipo
Caracter
Descrio
cContent a string correspondendo ao contedo do corpo do pacote HTML
postado no Server.
Descrio
A funo HttpOtherContent() , quando utilizada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do pacote html
proveniente de uma operao de POSTagem de dados, se e somente se a operaco de
POSTagem especificou no HEader HTTP um content-disposition ou content-type no
tratados automaticamente pelo Server PRotheus.
Caso a requisio no tenha sido realizada por um client HTTP atravs do mtodo de
postagem , ou a postagem j possua tratamento nativo no Server Protheus , ou a funo
seja chamada em um ambiente que no esteja atendendo uma requisio Http ( como
um JOB , por exemplo) , a funo retornar uma string em branco ("").
Sintaxe
HTTPPOST ( < cUrl > , [ cGETParms ] , [ cPOSTParms ] , [ nTimeOut ] , [ aHeadStr ] )
--> cHtml
Parmetros
Argumento
Tipo
cUrl
Caracter
cGETParms
Caracter
cPOSTParms
Caracter
nTimeOut
Numrico
aHeadStr
Array
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.
Retorno
Tipo
Caracter
Descrio
Atravs de cHtml ser retornada a String Html correspondendo ao
documento solicitado.
Descrio
A funo HttpPost() permite a emulao de um Client HTTP atravs de uma funo
Advpl, postando um bloco de informaes para um determinado documento publicado em
um servidor Web, utiliando o mtodo POST , permitindo a passagem de parmetros
adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta do
servidor solicitado.
Observaes :
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
Tipo
Descrio
Caracter Indica o endereo para qual ser feito o POST dos dados.
bloco de informaes, que utiliando o mtodo POST ser
Caracter
feita a passagem de parmetros adicionais.
Caracter Indica um path de um arquivo local armazenado em disco.
Representa o tempo(timeout) de inatividade em que a
Numrico
requisio ir aguardar em segundos.
Retorno
Tipo
Lgico
Descrio
Retorna se foi possvel realizar o PostXml. Caso seja realizado retorna true,
caso contrrio false.
Descrio
A funo HttpPostXml() permite a emulao de um Client HTTP atravs de uma funo
Advpl.
Postando um bloco de informaes e um documento XML indicado por uma
string path, para um determinado documento publicado em um servidor Web, utiliando o
Sintaxe
HTTPPRAGMA ( < cPragma > ) --> cOldPragma
Parmetros
Argumento
cPragma
Tipo
Descrio
cPragma corresponde ao conteudo do PRAGMA a ser
Caracter definido no Header de retorno HTTP. Veja tabela "A" de
definies PRAGMA.
Retorno
Tipo
Caracter
Descrio
A funo HttpPragma retornar a definio anterior de PRAGMA utilizada.
Descrio
Atravs desta funo , podemos redefinir a etiqueta PRAGMA do Header de Resposta de
requisio HTTP , sobrepondo definio defaiut de retorno PRAGMA , opcionalmente
definida na configurao do HOST HTTP no Arquivo de configurao do Protheus
Server.
Sintaxe
HTTPRCTDISP ( ) --> cCtDisp
Retorno
Tipo
Caracter
Descrio
cCtDisp corresponde o conteudo do identificador Content-disposition ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.
Descrio
A funo HttpRCtDisp() , quando utilzada em uma thread montada e/ou inicializada para
atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-disposition do Header HTTP .
Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no esteja
atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar uma
String em branco ("").
Sintaxe
HTTPRCTLEN ( ) --> nCtLen
Retorno
Tipo
Numrico
Descrio
nCtLen corresponde o conteudo do identificador Content-length , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo HttpRCtLen() , quando utilizada em uma thread montada e/ou inicializada para
atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-length do Header HTTP , como um dado numrico .
Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no esteja
atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar 0
( Zero ) .
Sintaxe
HTTPRCTTYPE ( ) --> cCtType
Retorno
Tipo
Caracter
Descrio
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
cCtType corresponde o conteudo do identificador Content-type , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo HttpRCtType() , quando utilzada em uma thread montada e/ou inicializada para
atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-type do Header HTTP .
Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no esteja
atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar uma
String em branco ("").
Sintaxe
HTTPSEND ( < cHtmlStr > ) --> cHtmlNoSend
Parmetros
Argumento
cHtmlStr
Tipo
Descrio
cHtmlStr corresponde string a ser enviada ao Browser
Caracter
solicitante de um processamento .
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
Sintaxe
HTTPSETPART ( < lHttpSend > ) --> NIL
Parmetros
Argumento
lHttpSend
Tipo
Descrio
lHttpSend um valor booleano que habilita o envio parcial
Lgico
( caso .T. ) ou desabilita o envio parcial de HTML ( .F. )
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL
Descrio
Essa funo permite desabilitar o envio parcial do HTML, esse um recurso disponivel
para os programas escritos para APW ( Utilizando Working Thread ).
Esse recurso util para comearmos a mandar contedo ao browser antes de terminarmos
de processar totalmente a pgina, ele pode aumentar em muito o desempenho do
transmisso da pgina em caso de pginas grandes.
A Funo HTTPSend utilizada para esse envio temporrio.
Sintaxe
HTTPSETPASS ( < cUser > , < cPass > ) --> Nil
Parmetros
Argumento
cUser
cPass
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.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
Em alguns momentos trabalhamos com protocolo Http autenticado, isso nos indica que
para nos conectar a determinada URL devemos informar um usurio e senha que tenham
permiso para conexo com a URL.
A funo HttpSetPass() tem o objetivo de setar uma senha para um determinado usurio,
quando uma requisio HTTP necessita de autenticao.
Informando atravs de parametro o usurio e a senha que dever ser usada para
autenticao do usurio infromado.
Sintaxe
HttpCountSession ( ) --> nQtde
Retorno
Tipo
Numrico
Descrio
Quantidade de usurios com sesses web extended ativas
Descrio
Esta funo retorno o nmero de sesses de usurios ativas no servidor, util para saber
quantos usurios de Web esto utilizando os servidores neste momento.
Sintaxe
HttpFreeSession ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Descrio
Nil
Libera a sesso do usurio corrente, todos os dados armazenado nas sesses deste usurio
ser perdida.
Funo utilizada para efetuar o log off do usurio do site.
Sintaxe
HttpIsAPW ( ) --> bIsAPW
Retorno
Tipo
Lgico
Descrio
Retorna .T. no caso do ambiente em execuo ser um APW, .F. em todas as
outras situaes.
Descrio
Informa se o ambiente web em execuo um APW, caso no seja retorna .F.
Essa funo util na criao de funes genricas ou na consistncia da configurao do
ambiente.
Sintaxe
HttpIsConnected ( ) --> bConnected
Retorno
Tipo
Lgico
Descrio
Retorna .t. se o browser ainda est conectado aguardando a resposta.
Descrio
Informa se o browser est conectado ainda esperando a resposta do Protheus!
Funcionalidade no disponvel quando utilizado o ISAPI para integrao com IIS
Sintaxe
ISSECURE ( ) --> lRet
Retorno
Tipo
(NULO)
Descrio
true caso a conexo uma conexo SSL, false caso contrrio.
Descrio
A funo IsSecure() tem como objetivo retornar um valor booleano informando se a
conexo HTTP corrente, uma conexo segura, ou no.
Uma conexo HTTP segura, uma conexo que usa criptografia SSL, podemos observar
esse tipo de conexo quando a URL modifica-se de HTTP para HTTPS em um browser.
Sintaxe
SOAPRACTION ( ) --> cSoapAction
Retorno
Tipo
Caracter
Descrio
cSoapAction corresponde o conteudo do identificador soapaction , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo SoapRAction() , quando utilizada em uma thread montada e/ou inicializada para
atender uma requisio Http ( .apl , .apw ) , retorna o contedo string do identificador
soapaction do Header HTTP .
Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no esteja
atendendo uma requisio Http ( como um JOB , por exemplo) , a funo retornar uma
string em branco ("").
Tipo
Descrio
Caracter <cEspecArq> a especificaao dos arquivos a serem
<aNomesArq>
Array
<aTamanhos>
Array
<aDatas>
Array
<aHoras>
Array
<aAtributos>
Array
Retorno
Tipo
Numrico
Descrio
ADIR() retorna a quantidade de arquivos que correspondem ao esqueleto de
diretrio especificado.
Descrio
ADIR() uma funao de tratamento de vetor que executa duas operaoes bsicas.
Primeiro, ele retorna a quantidade de arquivos que correspondem especificaao de
arquivo. Segundo, preenche uma srie de vetores com nomes de arquivos, tamanhos,
datas, horas e atributos.
ADIR() uma funao de compatibilidade e portanto desaconselhada. Ele est superado
pela funao DIRECTORY(), que retorna todas as informaoes de arquivo em um vetor
multi-dimensional.
OBSERVAO
Diretrios: Caso o argumento <aAtributos> seja especificado e <cEspecArq> seja
especificado como *.*, os diretrios serao incluidos em <aNomesArq>. No vetor
<aAtributos>, os diretrios sao indicados com um valor atributo de "D." Se ADIR() for
Sintaxe
CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento
cOrigem
cDestino
lCompacta
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.
Retorno
Tipo
Lgico
Descrio
lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em caso
de falha na cpia.
Descrio
Copia um arquivo, do servidor para o cliente ( Remote ). .Caso a compactao seja
habilitada (lCompacta ), os dados sero transmitidos de maneira compactada e
descompactados antes do uso.
Exemplo :
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. ) // Copia arquivos do
servidor para o remote local, compactando antes de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. ) // Copia arquivos do
servidor para o remote local, sem compactar antes de transmitir
Sintaxe
CPYT2S ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento
cOrigem
cDestino
lCompacta
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.
Retorno
Tipo
Lgico
Descrio
lSucess indica , caso verdadeiro , que a cpia foi realizada com sucesso.
Caso retorne .F. , houve erro na copia do arquivo.
Descrio
Copia um arquivo, do cliente ( Remote ) para o servidor,. Caso a compactao seja
habilitada ( lCompacta ), os dados sero transmitidos de maneira compacta e
descompactados antes do uso.
Exemplo
CpyT2S( "C:\TEMP\MANUAL.DOC","\BKP", .T. ) // Copia arquivos do
cliente( remote ) para o Servidor compactando antes de transmitir
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" ) // Copia arquivos do
cliente( remote ) para o Servidor sem compactar.
Sintaxe
CURDIR ( [ cNovoPath ] ) --> cPathAtual
Parmetros
Argumento
cNovoPath
Retorno
Tipo
Descrio
Caminho relativo , com o novo diretrio que ser ajustado
Caracter
como corrente.
Tipo
Caracter
Descrio
Diretrio corrente, sem a primeira barra.
Descrio
Retorna o diretrio corrente do servidor. O caminho retornado sempre relativo o
RootPath definido na configurao do Environment no .INI do Protheus Server.
Inicialmente , o diretrio atual da aplicao o constante na chave StartPath , tambm
definido na configurao do Environment no .INI do Protheus Server.
Caso seja passado o parmetro cNovoPath , este path assumido como sendo o Path
atual. Caso o path recebido como parmetro no exista , seja invlido , ou seja um path
absoluto ( iniciado com uma letra de drive ou caimnho de rede ) , a funo no ir setar o
novo path , mantendo o atual .
No exemplo abaixo , conferimos o path atual e tentamos setar um novo path atual ,
verificando se a operao foi realizada com sucesso.
cOldDir := curdir()
cNewDir := '\webadv\xis'
curdir(cNewDir) // Troca o path
If cNewDir <> '\'+curdir() // E verifica se trocou mesmo
conout('Falha ao Trocar de Path de '+cOldDir + ' para '+cNewDir)
Else
conout('Path de '+cOldDir + ' trocado para '+cNewDir+' com
sucesso.')
Endif
Sintaxe
DIRECTORY ( < cDirSpec > , [ ] ) --> aDiretorio
Parmetros
Argumento
cDirSpec
<cAtributos>
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
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.
Array
Descrio
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.
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
Tipo
Descrio
Caracter Nome do diretrio a ser removido.
Retorno
Tipo
Lgico
Descrio
lSucesso ser .T. caso o diretrio tenha sido eliminado , ou .F. caso no seja
possvel excluir o diretrio. Quando a funo DirRemove retornar .F. ,
possvel obter mais detalhes da ocorrncia recuperando o cdigo do Erro
atravs da funo FError().
Descrio
DIRREMOVE() elimina um diretrio especifico. Caso especifiquemos um path sem a
unidade de disco , ele ser considerado no ambiente do Servidor , a partir do RootPath do
ambiente ( caso o path comee com \ ) , ou a partir do diretrio corrente ( caso o path no
seja iniciado com \ ) . E , quando especificado um path absoluto ( com unidade de disco
preenchida ) , a funo ser executada na estao onde est sendo executado o Protheus
Remote. Quando executamos a funo DirRemove() em JOB ( processo isolado no Server
, sem interface ) , no possvel especificar um Path absoluto de disco. Caso isto seja
realizado , a funo retornar .F. e FError() retornar -1 ( Syntax Error ) .
Note que necessrio ter direitos suficientes para remover um diretrio, e o
diretrio a ser eliminado precisa estar vazio, sem subdiretrios ou arquivos dentro
do mesmo.
Exemplos
No exemplo abaixo , executado a partir do Protheus Remoite , tentamos excluir a pasta
c:\TmpFiles , verificando se houve sucesso nesta operao.
cDelPath := 'c:\TmpFiles'
lRemoveOk := DIRREMOVE(cDelPath)
IF !lRemoveOk
MsgStop('Falha ao remover a pasta '+cDelPath+' ( File Error
'+str(Fewrror(),4)+' ) ')
Else
MsgStop('Pasta '+cDelPath+' removida com sucesso.')
Endif
Sintaxe
DISKSPACE ( [ nDrive ] ) --> nBytesFree
Parmetros
Argumento
nDrive
Tipo
Descrio
Nmero do drive, onde 0 o espao na unidade de disco
Numrico corrente, e 1 o drive A: do cliente, 2 o drive B: do
cliente, etc.
Retorno
Tipo
Numrico
Descrio
Nmero de bytes disponveis no disco informado como parmetro.
Descrio
DISKSPACE() uma funo de ambiente que determina quantos bytes esto disponveis
em uma determinada uinidade de disco. Esta funo obtm a informao sempre relativa
estao onde est sendo executado o Protheus Remote. Atravs do parmetro nDRive ,
selecionamos qual a unidade de disco que desejamos obter a informao do espao livre ,
onde:
0 : Unidade de disco atual da estao (DEFAULT).
1 : Drive A: da estao remota.
2 : Drive B: da estao remota.
3 : Drive C: da estao remota.
4 : Drive D: da estao remota ... e assim por diante.
Caso a funo DiskSpace seja executada atravs de um Job ( processo isolado no
Servidor , sem interface Remota ) , ou seja passado um argumento de unidade de
disco inexistente ou indisponvel , a funo DISKSPACE() retornar -1
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Sintaxe
FCLOSE ( < nHandle > ) --> lError
Parmetros
Argumento
nHandle
Tipo
Descrio
<nHandle> o handle do arquivo obtido previamente
Numrico
atravs de FOPEN() ou FCREATE().
Retorno
Tipo
Lgico
Descrio
FCLOSE() retorna falso (.F.) se ocorre um erro enquanto os buffers estao
sendo escritos; do contrrio, retorna verdadeiro (.T.).
Descrio
FCLOSE() uma funao de tratamento de arquivos de baixo nvel utilizada para fechar
arquivos binrios e forar que os respectivos buffers do DOS sejam escritos no disco.
Caso a operaao falhe, FCLOSE() retorna falso (.F.). FERROR() pode entao ser usado
para determinar a razao exata da falha. Por exemplo, ao tentar-se usar FCLOSE() com um
handle (tratamento dado ao arquivo pelo sistema operacional) invlido retorna falso (.F.)
e FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para obter uma
lista completa dos cdigos de erro.
Aviso
Esta funao permite acesso de baixo nvel aos arquivos e dispositivos do DOS. Ela deve
ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional
utilizado.
Exemplos
O exemplo a seguir utiliza FCLOSE() para fechar um arquivo binrio recm criado e
exibe uma mensagem de erro caso o fechamento falhe:
#include "Fileio.ch"
nHandle := FCREATE("Testfile", FC_NORMAL)
If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf
Sintaxe
FCREATE ( < cArquivo > , [ nAtributo ] ) --> nHandle
Parmetros
Argumento
cArquivo
nAtributo
Tipo
Descrio
Nome do arquivo a ser criado , podendo ser especificado
um path absoluto ou relativo , para criar arquivos no
Caracter
ambiente local ( Remote ) ou no Servidor ,
respectivamente .
Atributos do arquivo a ser criado (Vide Tabela de atributos
Numrico abaixo). Caso no especificado , o DEFAULT
FC_NORMAL.
Retorno
Tipo
Numrico
Descrio
A funo retornar o Handle do arquivo para ser usado nas demais funes
de manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no
seja possvel criar o arquivo , a funo retornar o handle -1 , e ser possvel
obter maiores detalhes da ocorrencia atravs da funo FERror()
Descrio
FCREATE() uma funo de baixo-nvel que permite a manipulao direta dos arquivos
textos como binrios. Ao ser executada FCREATE() cria um arquivo ou elimina o seu
contedo, e retorna o handle (manipulador) do arquivo, para ser usado nas demais funes
de manuteno de arquivo. Aps ser utilizado , o Arquivo deve ser fechado atravs da
funo FCLOSE().
Na tabela abaixo , esto descritos os atributos para criao do arquivo , definidos no
arquivo header fileio.ch
Constante
Valor Descrio
FC_NORMAL
FC_READONLY
FC_HIDDEN
FC_SYSTEM
0
1
2
4
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
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 .
Retorno
Tipo
Numrico
Descrio
A funo retornar 0 caso o arquivop seja apagado com sucesso , e -1 caso
no seja possvel apagar o arquivo. Caso a funo retorne -1 , possvel
obter mauires detalhes da ocorrncia atravs da funo fError()
Descrio
Atravs da funo Ferase , possvel apagar um arquivo no disco . O Arquivo pode estar
no Servidor ou na estao local (Remote).
O Arquivo para ser apagado deve estar fechado. No permitido a utilizao de
caracteres coringa (wildcards).
Exemplos
// Este exemplo apaga todos os arquivos .BAK do diretrio corrente no Servidor
#include 'DIRECTRY.CH'
aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })
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
O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no
exista no path especificado , a funo retorna .F.
Descrio
Verifica se existe um arquivo ou um padro de arquivos, no diretrio. Pordemos
especificar caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( A partir do
RootPath do Protheus Server) . Os caracteres * e ? ( wildcards). so aceitos.
Exemplos
FILE("teste.dbf") // Verifica no diretrio corrente do servidor se
existe o arquivo teste.dbf
FILE("\SIGAADV\TESTE.dbf") // Verifica no diretrio Sigaadv do
servidor se existe o arquivo teste.dbf
FILE("C:\TEMP\TESTE.dbf") // // Verifica no diretrio Temp do cliente
(Remote) se existe o arquivo teste.dbf
Observao : Caso a funo File() seja executada em Job ( programa sem interface
remota ) , sendo passado um caminho absoluto de arquivo ( exemplo c:\teste.txt) , a
funo retornar .F. e FERROR() retornar -1 )
Sintaxe
FOPEN ( < cArq > , [ nModo ] ) --> nRet
Parmetros
Argumento
cArq
nModo
Tipo
Descrio
Nome do arquivo a ser aberto que inclui o path caso haja
Caracter
um.
Modo de acesso DOS solicitado que indica como o arquivo
aberto deve ser acessado. O acesso de uma das categorias
relacionadas na tabela A e as restries de
compartilhamento relacionada na Tabela B. O modo 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.
Retorno
Tipo
Numrico
Descrio
FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso
ocorra um erro, FOPEN() retorna -1.
Descrio
Abre um arquivo binrio.
FOPEN() uma funao de tratamento de arquivo de baixo nvel que abre um arquivo
binrio existente para que este possa ser lido e escrito, dependendo do argumento
<nModo>. Toda vez que houver um erro na abertura do arquivo, FERROR() pode ser
usado para retornar o cdigo de erro do Sistema Operacional. Por exemplo, caso o
arquivo nao exista, FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o arquivo
nao foi encontrado. Veja FERROR() para uma lista completa dos cdigos de erro.
Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do
Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de
banco de dados, e ele exigido para identificar o arquivo aberto para as outras funoes de
tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi retornado a
uma varivel para uso posterior, como mostra o exemplo desta funo.
Aviso
Esta funao permite acesso de baixo nvel a arquivos e dispositivos. Ela deve ser utilizada
com extremo cuidado e exige que se conhea a fundo o sistema operacional utilizado.
Notas
Constante (fileio.ch)
FO_READ
FO_WRITE
FO_READWRITE
Operao
Aberto para leitura (padro assumido)
Aberto para gravao
Aberto para leitura e gravao
Sintaxe
FREAD ( < nHanvle > , < cBuffer > , < nQtdBytes > ) --> nBytesLidos
Parmetros
Argumento
nHanvle
cBuffer
nQtdBytes
Tipo
Descrio
o manipulador (Handle) retornado pelas funes
FOPEN(),
Numrico
FCREATE(), FOPENPORT(), que faz referncia ao
arquivo a ser lido.
o nome de uma varivel do tipo String , a ser utilizada
como buffer de leitura , onde os dados lidos
devero ser armazenados. O tamanho desta varivel deve
ser maior ou igual ao tamanho informado em nQtdBytes.
Caracter
Esta varivel deve ser sempre passada por referncia. ( @
antes do nome da varivel ), caso contrrio os dados lidos
no sero retornados.
Define a quantidade de Bytes que devem ser lidas do
Numrico
arquivo a partor posicionamento do ponteiro atual.
Retorno
Tipo
Numrico
Descrio
Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada,
isto indica erro de leitura ou final de arquivo, Verifique a funo FERROR()
para maiores detalhes.
Descrio
FREAD() l os dados a partir um arquivo aberto, atravs de FOPEN(), FCREATE() e/ou
FOPENPORT(), e armazena os dados lidos por referncia no buffer informado.
FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum erro
ou o arquivo chegue ao final, FREAD() retornar um nmero menor que o especificado
em nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128, ASC 0, etc.).
A varivel String a ser utiilzada como buffer de leitura deve ser sempre pr-alocado e
passado como referncia. Caso contrrio, os dados no podero ser retornados.
FREAD() l a partir da posio atual do ponteiro atual do arquivo , que pode ser ajustado
ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().
Sintaxe
FREADSTR ( < nHandle > , < nQtdBytes > ) --> cLidos
Parmetros
Argumento
nHandle
nQtdBytes
Tipo
Descrio
o manipulador retornado pelas funes FOPEN(),
Numrico
FCREATE(), FOPENPORT().
Numrico Nmero mximo de bytes que devem ser lidos.
Retorno
Tipo
Caracter
Descrio
Retorna uma string contendo os caracteres
lidos.
Descrio
L caracteres de um arquivo binrio.
FREADSTR() l de um arquivo aberto, atravs de FOPEN(), FCREATE(),
FOPENPORT().
FREADSTR() ler at o nmero de bytes informado em nQtdBytes ou at encontrar um
CHR(0). Caso acontea algum erro ou o arquivo chegue ao final, FREADSTR() retornar
uma string menor do que nQdBytes e colocar o erro em FERROR().
FREADSTR() l a partir da posio atual do ponteiro, que pode ser ajustado pelo
FSEEK(), FWRITE( ) ou FREAD().
Sintaxe
FRENAME ( < cOldFile > , < cNewFile > ) --> nStatus
Parmetros
Argumento
cOldFile
cNewFile
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.
Retorno
Tipo
Numrico
Descrio
Se o status retornado for -1 , ocorreu algum erro na mudana de nome :
Verifique se os dois caminhos esto no mesmo ambiente, verifique a
existncia do arquivo de origem, se ele no est em uso no momento por
outro processo , e verifique se o nome do arquivo de destino j no existe no
path de destino especificado.
Descrio
Atravs da funo FRENAME() possvel renomear um arquivo para outro nome, tanto
no servidor como na estao. Ao renomear um arquivo no esquea que esta arquivo
dever
estar fechado ( isto , no pode estar em uso por nenhum outro processo ou estao).
Caso o arquivo esteja aberto por outro processo , a operao de renomear o arquivo no
possvel. A funo fRename() no aceita wildcards ( * e/ou ? ).
Vale lembrar que no possvel renomear um arquivo especificando nos parmetros
simultaneamente um caminho de servidor e um de estao remota, bem como especificar
dois arquivos remotos e executar a funo fername() atravs de um JOB. Caso isto ocorra,
a funo retornar -1 , e fError() retornar tambm -1.
Importante : Quando especificamos um path diferente nos arquivos de origem e
destino , a funo fRename() realiza a funcionalidade de MOVER o arquivo para o
Path especificado.
Exemplos
// Renomeando um arquivo no Client de origem.txt para destino.txt , na
pasta c:\Temp
nStatus1 := frename('c:\Temp\Origem.txt' , 'c:\Temp\Destino.txt' )
IF nStatus1 == -1
MsgStop('Falha na operao 1 : FError '+str(ferror(),4))
Endif
// Renomeando um arquivo no Server, na pasta sigaadv , de error.log
para error.old
nStatus2 := frename('\sigaadv\error.log' , '\sigaadv\error.old' )
IF nStatus2 == -1
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
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
Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso
contrrio.
Descrio
Indica se o ponteiro esta posicionado no fim do arquivo texto.
A funo FT_FEof() retorna verdadeiro (.t.) se o arquivo texto aberto pela FT_FUSE
estiver posicionado no final do arquivo, similar funo Eof (), usada em tabelas de
dados.
Exemplos
O exemplo abaixo realiza a leitura de um arquvio texto, utilizando-se das funes FT_F*
FT_FUse('teste.txt') // Abre o arquivo
conout("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln()
+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo
Sintaxe
FT_FGOTO ( < nPos > ) --> NIL
Parmetros
Argumento
nPos
Tipo
Descrio
Indica a posio que ser colocado o ponteiro para leitura
Numrico
dos dados no arquivo.
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL
Descrio
A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto, para
a posio absoluta especificada pelo argumento <nPos>.
Sintaxe
FT_FGOTOP ( ) --> NIL
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL
Descrio
A funo FT_FGoTop tem como objetivo posicionar o arquivo texto aberto pela
FT_FUse na
posio inicial do arquivo.
Entende-se como posio inicial do arquivo, o primeiro caracter da primeira linha do
arquivo texto.
Sintaxe
FT_FLASTREC ( ) --> nRet
Retorno
Tipo
Numrico
Descrio
Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja
vazio, ou no exista arquivo aberto, a funo retornar 0 (zero)
Descrio
A funo tem o objetivo de retornar o nmero de linhas existentes do arquivo texto.
A funo FT_FLastRec retorna o nmero total de linhas do arquivo texto aberto pela
FT_FUse. As linhas so delimitadas pela sequncia de caracteres CRLF ou LF (*).
(*) Verifique maiores informaes sobre formato do arquivo e tamanho mximo da linha
de texto na funo FT_FREADLN()
Exemplos
O exemplo abaixo realiza a leitura de um arquvio texto, utilizando-se das funes FT_F*
FT_FUse('teste.txt') // Abre o arquivo
conout("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln()
+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo
Sintaxe
Descrio
Retorna a linha inteira na qual est posicionado o ponteiro para leitura de
dados.
Descrio
A funo tem como objetivo ler uma linha do arquivo texto.
A funo FT_FREADLN() retorna uma linha de texto do arquivo aberto pela FT_FUse.
As linhas so delimitadas pela sequncia de caracteres CRLF ( chr(13) + chr(10) ) , ou
apenas LF ( chr(10 ), e o tamanho mximo de cada linha 1022 bytes
Observaes
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
Tipo
Descrio
nLinhas corresponde ao nmero de linhas do arquivo TXT
Numrico
ref. movimentao do ponteiro de leitura do arquivo.
Retorno
Tipo
(NULO)
Descrio
Esta funo sempre retorna NIL.
Descrio
Move o ponteiro do arquivo texto para uma nova posio.
A funo FT_FSkip move o ponteiro do arquivo texto aberto pela FT_FUse para a
prxima linha, similar ao DbSkip usado para tabelas de dados.
Sintaxe
FT_FUSE ( [ cTXTFile ] ) --> nHnd
Parmetros
Argumento
cTXTFile
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.
Retorno
Tipo
Numrico
Descrio
A funo retorna o Handle de controle do arquivo. Em caso de falha de
abertura, a funo retornar -1
Descrio
Abre ou fecha um arquivo texto para uso das funcoes FT_F*
As funes FT_F* so usadas para para ler arquivos texto, onde as linhas so delimitadas
pela sequncia de caracteres CRLF ou LF (*) e o tamanho mximo de cada linha 1022
bytes.. O arquivo aberto em uma rea de trabalho, similar usada pelas tabelas de
dados.
(*) Maiores detalhes sobre a especificao do arquivo na funo FT_FREADLN()
Sintaxe
FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) --> nBytesEscritos
Parmetros
Argumento
nHandle
cBuffer
nQtdBytes
Tipo
Descrio
o manipulador de arquivo ou device retornado pelas
Numrico
funes FOPEN(), FCREATE(), ou FOPENPORT().
<cBuffer> a cadeia de caracteres a ser escrita no arquivo
especificado. O tamanho desta varivel deve ser maior ou
Caracter
igual ao tamanho informado em nQtdBytes (caso
seja informado o tamanho).
<nQtdBytes> indica a quantidade de bytes a serem escritos
Numrico a partir da posiao corrente do ponteiro de arquivos. Caso
seja omitido, todo o contedo de <cBuffer> escrito.
Retorno
Tipo
Numrico
Descrio
FWRITE() retorna a quantidade de bytes escritos na forma de um valor
numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
operaao foi bem sucedida. Caso o valor de retorno seja menor que
<nBytes> ou zero, ou o disco est cheio ou ocorreu outro erro. Neste caso ,
utilize a funo FERROR() para obter maiores detalhes da ocorrncia.
Descrio
Voc pode escrever todo ou parte do contedo do buffer , limitando a quantidade de Bytes
atravs do parmetro nQtdBytes. A escrita comea a partir da posio corrente do
ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes escritos.
Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou criar
um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou enviados
os dados do buffer informado. Por tratar-se de uma funo de manipulao de contedo
binrio , so suportados na String cBuffer todos os caracteres da tabela ASCII , inclusive
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
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 )
LER."+;
Lidos."+;
"+str(ferror(),4),'Erro')
lCopiaOk := .F.
Exit
Endif
Str(nBytesLidos,8,2)+" bytes
"Ferror =
Sintaxe
GETCLIENTDIR ( ) --> cPath
Retorno
Tipo
Caracter
Descrio
Retona o path onde est instalado o Protheus Remote.
Descrio
Retorna o diretrio completo onde o Remote est instalado, informando inclusive a
unidade de disco.
Observao : Esta funo apenas retornar um resultdo vlido caso seja executada
em um programa atravs do Protheus Remote . Caso esta funo seja chamada em
JOB , a mesma ocasionar um erro de execuo ( Error to comunicate with
Remote ) .
Exemplos
No exemplo abaixo , obtemos o drive e diretrio onde esto instalados o Remote .
MsgStop('Protheus Remote instalado em '+ GetClientDir())
Sintaxe
GETREMOTEININAME ( ) --> cArqConf
Retorno
Tipo
Caracter
Descrio
Path e nome do arquivo de configurao
Descrio
Retorna o nome do arquivo de configurao do AP Remote.
Verso 7.10
Verso 8.11
Sintaxe
GETSRVPROFSTRING ( < cChave > , < cDefault > ) --> cConteudo
Parmetros
Argumento
cChave
cDefault
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
Retorno
Tipo
Caracter
Descrio
Descrio
Conteudo da chave especificada
Tipo
Descrio
Nome do diretrio a ser criado, incluindo opcionalmente o
Caracter
caminho (path).
Retorno
Tipo
Numrico
Descrio
Retorno zero ( 0 ),o diretrio foi criado com sucesso. Caso contrrio, houve
erro na criao do diretrio.
Descrio
Cria um diretrio na estao ou no servidor APx.
Caso o diretrio comece com um drive ( Ex: C:, X: ) o diretrio ser criado na estao,
caso contrrio ser criado no servidor.
MAKEDIR("c:\teste\um") // Cria um diretrio na estacao
nResult := MAKEDIR("\teste\um") // Cria o diretorio no servidor
Advanced protheus
IF nResult != 0
Conout( "Impossivel Criar o diretrio no servidor Protheus", nResult
)
ENDIF
MAKEDIR( "teste" ) // Exemplo tambm vlido ( Criando o diretrio no
servidor ) dentro do diretrio corrente
Sintaxe
MSCOMPRESS ( < cArq | aArquivos > , [ cDestino ] , [ cSenha ] ) --> cFileName
Parmetros
Argumento
Tipo
Descrio
Arquivo(s) a ser(em) compactado(s). Pode ser do tipo
String , para especificar um nico arquivo , ou do tipo
cArq | aArquivos (Qualquer)
Array , contendo um ou mais arquivo(s) a ser(em)
compatado(s).
cDestino
Caracter Nome do Arquivo destino, caso a extenso seja omitida
cSenha
Caracter
Retorno
Tipo
Caracter
Descrio
Caso a compactao seja executada com sucesso , a funo retornar uma
sring contendo o nome do arquivo gerado . Caso no seja possvel a
compactao , por falta de espao em disco ou erro de acesso a algum dos
arquivos a ser(em) compactado(s), a funo retornar uma string em branco
("").
Descrio
Compacta um ou vrios arquivos em um nico arquivo com extenso .MZP.
MSCOMPRESS() compacta os arquivos informados em um nico arquivo com extenso
default .MZP. O formato proprietrio e multiplataforma.
Caso a senha seja informada apenas com a senha poderemos descompactar os arquivos.
Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
Exemplos
// Exemplo 1 Compacta apenas um arquivo
lRes := MSCOMPRESS( "AP6SRV.EXE", "AP6SRV.MZP" )
// Exemplo 2 Compacta um diretrio com senha
aNome := {}
ADIR( "*.DBF", aNome )
lRes := MSCOMPRESS( aNome, "ArqComp.MZP", "SENHA" )
Sintaxe
MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess
Parmetros
Argumento
cArq
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
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
SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) -->
NIL
Parmetros
Argumento
Tipo
cArq
Caracter
cDrive
Caracter
cCaminho
Caracter
cNome
Caracter
cExt
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.
Retorno
Tipo
Caracter
Descrio
Esta funo sempre retorna NIL.
Descrio
A funo SplitPath() divide um caminho completo em todas as suas subpartes ( Drive ,
Caminho , Nome e Extenso ) .
Tanto arquivos locais ( Remote ) quanto arquivos no servidor, podem ser informados.
O caminho, caso informado, incluir uma barra como ltimo caracter. A extenso ,
quando retornada , inclui sempre o ponto ( . ) antes da extenso.
Todos os parmetros , a partir do segundo , quando passados devem ser por referncia.
Observao : Vale lembrar que a funo SplitPath no valida a sintaxe do caminho
e/ou arquivo digitados , nem a existncia do mesmo . Esta funo utilizada para
determinar em uma string os elementos que compe um caminho para a localizao
de um arquivo.
Exemplos
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 .
Tipo
Descrio
<cString> a expressao caractere cujos espaos em branco
Caracter
serao eliminados.
Retorno
Tipo
Caracter
Descrio
ALLTRIM() retorna uma cadeia de caracteres cujos espaos em branco
direita e esquerda foram removidos.
Descrio
ALLTRIM() uma funo de tratamento de dados do tipo caractere que remove os
espaos em branco direita e esquerda de uma cadeia de caracteres. relacionada a
LTRIM() e RTRIM(), que removem espaos em branco esquerda e direita de uma
cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM()
sao as funoes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou
alinham esquerda cadeias de caracteres atravs da insero de caracteres de
preenchimento.
Sintaxe
DESCEND ( < cString > ) --> cDescend
Parmetros
Argumento
cString
Tipo
Descrio
<cString> corresponde sequncia de caracteres a ser
Caracter
analisada.
Retorno
Tipo
Caracter
Descrio
DESCEND() retorna a string especificada como parmetro de uma forma
complementada. Um DESCEND() de CHR(0) sempre retorna CHR(0).
Descrio
DESCEND() uma funo de converso que retorna a forma complementada da
expresso string especificada. Esta funo normalmente utilizada para a criao de
indexadores em Ordem Decrescente.
Exemplos
Este exemplo utiliza DESCEND() em uma expressao INDEX para criar um ndice de
datas de ordem descendente:
USE Sales NEW
INDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate
Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice
descendente:
DbSEEK(DESCEND(DTOS(dFindDate)))
Tipo
Descrio
<cString> a cadeia de caracteres a ser copiada sem os
Caracter
espaos em branco esquerda.
Retorno
Tipo
Caracter
Descrio
LTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou toda composta de espaos em branco, LTRIM() retorna uma
cadeia de caracteres nula ("").
Descrio
LTRIM() uma funao de tratamento de caracteres utilizada para Formatar cadeias de
caracteres que possuam espaos em branco esquerda. Pode ser o caso de, por exemplo,
nmeros convertidos para cadeias de caracteres atravs da funao STR().
LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a
ALLTRIM(), que remove espaos tanto esquerda quanto direita. O contrrio de
ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as quais
centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs da
inserao de caracteres de preenchimento.
Sintaxe
PADL / PADR / PADC ( < exp > , < nTamanho > , [ cCaracPreench ] ) -->
cStringPreench
Parmetros
Argumento
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
Caracter
Retorno
Tipo
Caracter
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>.
Descrio
PADC(), PADL(), e PADR() sao funoes de tratamento de caracteres que inserem
caracteres de preenchimento em valores caractere, data ou numricos a fim de criar uma
nova cadeia de caracteres de tamanho especificado. PADC() centraliza <exp>,
adicionando caracteres de preenchimento direita e esquerda; PADL() adiciona
caracteres de preenchimento esquerda; e PADR() adiciona caracteres de preenchimento
direita. Caso o tamanho de <exp> exceda o argumento <nTamanho>, todas as funoes
PAD() truncam cStringPreench ao <nTamanho> especificado.
PADC(), PADL(), e PADR() sao utilizadas para exibir cadeias de caracteres de tamanho
varivel em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para
assegurar o alinhamento com comandos ?? consecutivos. Outra utilizaao exibir textos
em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi completamente
sobreescrito.
PADC(), PADL(), e PADR() sao o contrrio das funoes ALLTRIM(), LTRIM(), e
LTRIM(), as quais eliminam espaoes em branco esquerda e direita de cadeias de
caracteres.
Sintaxe
RTRIM ( < cString > ) --> cTrimString
Parmetros
Argumento
cString
Tipo
Descrio
<cString> a cadeia de caracteres a ser copiada sem os
Caracter
espaos em branco direita.
Retorno
Tipo
Caracter
Descrio
RTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
direita foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou totalmente composta por espaos, RTRIM() retorna uma cadeia
de caracteres nula ("").
Descrio
RTRIM() uma funao de tratamento de caracteres utilizada para Formatar cadeias de
caracteres que contenham espaos em branco direita. Ela til quando voc deseja
eliminar espaos em branco direita ao se concatenar cadeias de caracteres. o caso
tpico com campos de banco de dados que sao armazenados em formato de tamanho fixo.
Por exemplo, voc pode usar RTRIM() para concatenar o primeiro e o ltimo campos de
nome para formar uma cadeia de caracteres de nome.
LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a
ALLTRIM(), que remove espaos em branco direita e esquerda. O contrrio de
ALLTRIM(), LTRIM(), e RTRIM() sao as funoes PADC(), PADR(), e PADL(), as quais
centralizam, alinham direita, ou alinham esquerda cadeias de caracteres, inserindo
caracteres de preenchimento.
Sintaxe
CDOW ( < dExp > ) --> cNomeDia
Parmetros
Argumento
dExp
Tipo Descrio
Data <dExp> o valor data a ser convertido.
Retorno
Tipo
Caracter
Descrio
CDOW() retorna o nome do dia da semana na forma de uma cadeia de
caracteres. A primeira letra ser maiscula e o resto dos caracteres vir em
minsculas. Para um valor de data nulo ou invlido, CDOW() retorna uma
cadeia de caracteres vazia ("").
Descrio
CDOW() uma funo utilizada para obter, a partir de uma data, a cadeia de caracteres
contendo o dia da semana correspondente.
Exemplos
Os exemplos a seguir ilustram o funcionamento da funao CDOW():
conout( DATE() )
conout( CDOW(DATE()) )
conout( CDOW(DATE() + 7) )
conout( CDOW(CTOD("12/06/90")) )
// Resulta: 08/04/02
// Resulta: Sunday
// Resulta: Sunday
// Resulta: Thursday
Sintaxe
CMONTH ( < dData > ) --> cMs
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> a data a converter.
Retorno
Tipo
Caracter
Descrio
CMONTH() retorna o nome do ms a partir de uma data como sendo uma
cadeia de caracteres com a primeira letra maiscula e o restante da string em
letras minsculas. Para uma data nula, CMONTH() retornar uma string
nula ("").
Descrio
CMONTH() uma funo de converso de datas que , a partir de uma data , retorna uma
cadeia de caracteres correspondendo ao nome do ms correspondente.
Exemplos
Os exemplos seguintes ilustram a utilizaao da funao CMONTH():
conout( CMONTH(DATE()) )
Resulta: August
conout( CMONTH(DATE() + 45) )
Resulta: September
conout( SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE()),3))
Resulta: Aug 4
//
//
//
Sintaxe
DATE ( ) --> dSistema
Retorno
Tipo
Data
Descrio
Descrio
DATE() retorna a data do sistema como sendo um valor do tipo data.
DATE() )
DATE() + 30 )
DATE() - 30 )
DATE()
CMONTH(dDate) )
// Resulta: 08/04/02
// Resulta: 09/03/02
// Resulta: 07/05/02
// Resulta: August
Sintaxe
DAY ( < dData > ) --> nDia
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> a data a converter.
Retorno
Tipo
Numrico
Descrio
DAY() retorna um nmero na faixa de 0 at 31, sendo este um valor
numrico inteiro. Caso o ms seja Fevereiro, os anos bissextos sao
considerados. Se o argumento de data 29 de Fevereiro e o ano nao
bissexto, DAY() retornar zero. Se o argumento de data vazio, DAY()
tambm retornar zero.
Descrio
Retorna o dia do ms como valor numrico. DAY() uma funao de conversao de datas
utilizada para converter um valor do tipo data para o dia do ms correspondente. Esta
funo usada em conjunto com CMONTH() e YEAR() para formatar datas. Alm disso,
geralmente usada em clculos que envolvam datas.
Exemplos
Os exemplos seguintes mostram a funao DAY() sendo utilizada
de diversas maneiras:
conout(
conout(
conout(
conout(
DATE() )
DAY(DATE()) )
DAY(DATE()) + 1)
DAY(CTOD("")) )
// Resulta: 09/01/90
// Resulta: 1
// Resulta: 2
// Resulta: 0
Sintaxe
DOW ( < dData > ) --> nDia
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data que ser convertido.
Retorno
Tipo
Numrico
Descrio
DOW() retorna o dia da semana na forma de um nmero entre zero e sete. O
primeiro dia da semana um (Domingo) e o ltimo sete (Sbado). Se
<dData> estiver vazio, DOW() retorna zero.
Descrio
DOW() uma funao de conversao de datas que converte um valor data para um nmero
que identifica o dia da semana. Ela til quando voc deseja clculos de data em uma
base semanal. DOW() semelhante a CDOW(), a qual retorna o dia da semana na forma
de uma cadeia de caracteres ao invs de um nmero.
Exemplos
Os exemplos a seguir ilustram CDOW() e seu relacionamento com DOW():
conout(
conout(
conout(
conout(
conout(
DATE() )
DOW(DATE()) )
CDOW(DATE()) )
DOW(DATE() - 2) )
CDOW(DATE() - 2) )
//
//
//
//
//
Resulta:
Resulta:
Resulta:
Resulta:
Resulta:
09/01/89
3
Terca-feira
1
Domingo
A seguir est uma funao definida por usurio que utiliza DOW() para calcular a data da
ltima segunda-feira a partir de qualquer outra data:
USER FUNCTION LastMonday(dData)
Return (dData - DOW(dData) + 2)
Sintaxe
DTOC ( < dData > ) --> cData
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data que ser convertido.
Retorno
Tipo
Caracter
Descrio
DTOC() retorna uma cadeia de caracteres que representa uma data. O valor
de retorno formatado de acordo com o formato de datas corrente. O
formato padrao mm/dd/aa. Uma data nula retorna uma cadeia de caracteres
em branco igual em tamanho ao formato de data corrente.
Descrio
DTOC() uma funao de conversao de datas utilizada por motivos de Formataao quando
voc deseja exibir a data no formato SET DATE e necessria uma expressao caractere.
Caso voc precise de um formato de data especfico, voc pode utilizar TRANSFORM()
ou uma expressao customizada.
Se voc estiver INDEXando uma data juntamente com uma cadeia de caracteres, use
DTOS() ao invs de DTOC() para converter o valor data para uma cadeia de caracteres.
Exemplos
Os exemplos a seguir demonstram utilizaoes gerais de DTOC():
conout( DATE() )
conout( DTOC(DATE()) )
conout( "Hoje e " + DTOC(DATE()) )
// Resulta: 09/01/90
// Resulta: 09/01/90
// Resulta: Hoje e 09/01/90
Sintaxe
DTOS ( < dData > ) --> cData
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data que ser convertido.
Retorno
Tipo
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
Sintaxe
ELAPTIME ( < cHoraInicial > , < cHoraFinal > ) --> cIntervalo
Parmetros
Argumento
cHoraInicial
cHoraFinal
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.
Retorno
Tipo
Descrio
Caracter
Descrio
ElapTime() retorna uma cadeia de caracteres contendo a diferena de
tempo entre cHoraFinal - cHoraInicial , no formato hh:mm:ss.
Os dois parmetros , cHoraInicial e cHoraFinal , devem ser especificados no formato
hh:mm:ss , com tamanho de 8 bytes . Caso um dos parmetros tenha tamanho diferente de
8 Bytes, gerada uma ocorrncia de Erro Fatal "invalid len". Qualquer caracter invalido
nas posices referentes hora (hh) , minuto (mm) e segundo (ss) , sero ignorados na
composio de numeros para o clculo. Caso o horrio inicial seja maior que o horrio
final , retornada a diferena entre os horrios acrescidos de 24h. Para maiores detalhes ,
consulte o exemplo da funo ElapTime()
Exemplos
Este exemplo utiliza a funo ElapTime() para calcular o tempo necessrio para um
determinado processamento.
cHoraInicio := TIME() // Armazena hora de inicio do processamento
.
. <instrucoes>
.
cElapsed := ELAPTIME(TIME(),cHoraInicio) // Calcula a diferena de
tempo
Sintaxe
MONTH ( < dData > ) --> nMs
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data a ser convertido.
Retorno
Tipo
Numrico
Descrio
MONTH() retorna um valor numrico inteiro na faixa de 0 (zero) a 12. Uma
data nula (CTOD("")) retorna zero.
Descrio
MONTH() uma funao de conversao de datas que til quando voc precisa de um
valor de ms numrico durante clculos para, por exemplo, relatrios peridicos.
MONTH() faz parte de um grupo de funoes que retornam componentes de um valor data
// Resulta: 09/01/90
// Resulta: 9
// Resulta: 10
// Resulta: 0
Sintaxe
SECONDS ( ) --> nSegundos
Retorno
Tipo
Numrico
Descrio
SECONDS() retorna a hora do sistema como um valor numrico na forma
segundos.centsimos. O valor numrico retornado a quantidade de
segundos decorridos desde a meia-noite, e tem base em um relgio de vinte
e quatro horas em uma faixa de zero a 86399.
Descrio
SECONDS() uma funao de horas utilizada para fornecer um mtodo simples de
calcular o tempo decorrido, com base no relgio do sistema, durante a execuao do
programa. relacionado funao TIME(), a qual retorna a hora do sistema como uma
cadeia de caracteres na forma hh:mm:ss.
Exemplos
Este exemplo compara o valor de TIME() com o de SECONDS():
conout( TIME() )
conout( SECONDS() )
// Resulta: 10:00:00
// Resulta: 36000.00
Este exemplo demonstra como utilizar SECONDS() para informar o tempo decorrido em
segundos:
LOCAL nStart, nElapsed
nStart = SECONDS()
.
. <processamentos...etc....>
.
nElapsed = SECONDS() - nStart
conout( "Decorridos: " + LTRIM(STR(nElapsed)) + " segundos" )
Sintaxe
TIME ( ) --> cStringHora
Retorno
Tipo
Caracter
Descrio
TIME() retorna a hora do sistema como uma cadeia de caracteres na forma
hh:mm:ss. hh indica a hora no formato de 24 horas, mm indica os minutos, e
ss indica os segundos. Horas, minutos e segundos sao separadas por dois
pontos.
Descrio
TIME() uma funao de tratamento de tempo, utilizada para exibir ou imprimir a hora do
sistema em um relatrio ou na tela. TIME() est relacionada a SECONDS(), que retorna a
quantidade de segundos decorridos desde a meia-noite. SECONDS() geralmente
utilizada em lugar de TIME() para clculos sobre o tempo.
Exemplos
Estes exemplos mostram a funo TIME() utilizada em conjunto com SUBSTR()
para extrair a hora, os minutos e os segundos:
cTime := TIME() // Resultado: 10:37:17
cHora := SUBSTR(cTime, 1, 2) // Resultado: 10
cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37
cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17
Sintaxe
YEAR ( < dData > ) --> nAno
Parmetros
Argumento
dData
Tipo Descrio
Data <dData> o valor data a ser convertido.
Retorno
Tipo
Numrico
Descrio
YEAR() retorna o ano do valor data especificado, inclusive dgitos
indicativos de sculo, na forma de um valor numrico de quatro dgitos. O
valor retornado nao influenciado pelo formato de DATE ou CENTURY
corrente. A especificaao de uma data nula (CTOD("")) retorna zero.
Descrio
YEAR() uma funao de conversao de datas utilizada para converter um valor data para
um valor numrico indicativo do ano. Pode ser utilizada em clculos de, por exemplo,
relatrios peridicos, ou para Formataao de exibioes de data.
YEAR() membro de um grupo de funoes que retornam componentes de um valor data
na forma de valores numricos. Este grupo inclui DAY() e MONTH(), que retornam
valores de dia e ms na forma de valores numricos.
Exemplos
Os exemplos a seguir ilustram YEAR() usando a data do
sistema:
conout( DATE() )
conout( YEAR(DATE()) )
conout( YEAR(DATE()) + 11 )
// Resulta: 09/01/90
// Resulta: 1990
// Resulta: 2001
Parmetros
Argumento
aDestino
expValor
Tipo
Array
Descrio
o array ao qual o novo elemento ser adicionado.
uma expresso vlida que ser o valor do
(Qualquer)
novo elemento.
Retorno
Tipo
(Qualquer)
Descrio
Avalia expValor e retorna seu Valor. Se expValor no for especificado,
AADD() retorna NIL.
Descrio
AADD() uma funo de tratamento de vetor que adiciona um elemento ao vetor. Ao
elemento de vetor recm criado atribuido o valor especificado por <expValor>.
AADD() utilizado para aumentar o tamanho de um vetor dinamicamente. til na
construo de filas ou listas dinmicas.
AADD() semelhante funo ASIZE(), mas adiciona apenas um elemento por vez;
ASIZE() pode aumentar ou diminuir um vetor a um tamanho especificado. AADD(),
porm, possui a vantagem de poder atribuir um valor ao novo elemento, enquanto que
ASIZE() nao pode. AADD() pode tambm parecer ser igual a AINS(), mas isso nao
verdade: AINS() move elementos dentro de um vetor, mas nao modifica o tamanho do
vetor.
OBSERVAO : Caso <expValor> seja um outro vetor, o novo elemento no vetor
destino conter uma referncia ao vetor especificado por <expValor>.
//
//
//
//
Sintaxe
ACLONE ( < aFonte > ) --> aDuplica
Parmetros
Resulta:
Resulta:
Resulta:
Resulta:
aArray
aArray
aArray
aArray
e
e
e
e
um vetor vazio
{ 5 }
{ 5, 10 }
{ 5, 10, { 12,
Argumento
aFonte
Tipo Descrio
Array <aFonte> o vetor a ser duplicado.
Retorno
Tipo
Array
Descrio
Array idntico ao aFonte , porem sem nenhuma referncia ao mesmo.
Descrio
ACLONE() uma funao de vetor que cria uma duplicata completa do vetor de
<aFonte>. Caso <aFonte> contenha sub-vetores, ACLONE() cria sub-vetores
correspondentes e os preenche com cpias dos valores contidos nos sub-vetores de
<aFonte>.
Ao igualarmos dois arrays, eles ficam associados por referncia, utilizando
aClone() no existe referncia. ACLONE() semelhante a ACOPY(), porm ACOPY()
nao duplica vetores aninhados.
Sintaxe
ACOPY ( < aFonte > , < aDestino > , [ nInicio ] , [ nCont ] , [ nPosDestino ] ) -->
aDestino
Parmetros
Argumento
aFonte
aDestino
nInicio
nCont
nPosDestino
Tipo
Array
Descrio
<aFonte> o vetor de onde serao copiados os elementos.
<aDestino> o vetor para onde serao copiados os
Array
elementos.
<nInicio> a posiao do elemento inicial no vetor
Numrico <aFonte>. Se nao for especificado, o valor assumido um
(01).
<nCont> a quantidade de elementos a serem copiados do
vetor <aFonte> a partir da posiao <nInicio>. Caso
Numrico <nCont> nao seja especificado, todos os elementos em
<aFonte> que comeam com o elemento inicial sao
copiados.
<nPosDestino> a posiao do elemento inicial no vetor
Numrico <aDestino> que receber os elementos de <aFonte>. Se nao
for especificado, o valor padrao um (01).
Retorno
Tipo
Array
Descrio
ACOPY() retorna uma referncia ao vetor destino, <aDestino>.
Descrio
ACOPY() uma funao de tratamento de vetor que copia elementos do vetor <aFonte>
para o vetor <aDestino>. O vetor <aDestino> j deve existir e ser grande o suficiente para
conter os elementos copiados. Caso o vetor <aFonte> tenha mais elementos, alguns
elementos nao serao copiados.
ACOPY() copia valores de todos os tipos de dados, inclusive NIL e blocos de cdigo. Se
um elemento do vetor <aFonte> for um sub-vetor, o elemento correspondente no vetor
<aDestino> conter uma referncia ao sub-vetor. Consequentemente, ACOPY() nao cria
duplicatas completas de vetores multi-dimensionais. Para fazer isto, use a funao
ACLONE().
Exemplos
Este exemplo cria dois vetores, cada um deles preenchido com um valor. Os dois
primeiros elementos do vetor fonte sao entao copiados para o vetor destino:
LOCAL nCount := 2, nStart := 1, aOne, aTwo
aOne := { 1, 1, 1 }
aTwo := { 2, 2, 2 }
ACOPY(aOne, aTwo, nStart, aCont)
// Resulta: aTwo e agora { 1, 1,
2 }
Sintaxe
ADEL ( < aFonte > , < nPosicao > ) --> aFonte
Parmetros
Argumento
aFonte
nPosicao
Tipo
Descrio
<aFonte> o vetor que contm um elemento a ser
Array
eliminado.
<nPosiao> a posiao do elemento de vetor , a partir do
Numrico
primeiro , que ser eliminado.
Retorno
Tipo
Array
Descrio
ADEL() retorna uma referncia ao vetor destino, <aFonte>.
Descrio
ADEL() uma funao de tratamento de vetor que elimina um elemento de um vetor. O
contedo do elemento de vetor especificado perdido, e todos os elementos a partir
daquela posiao at o final do elemento sobem uma posiao. O ltimo elemento no vetor
torna-se NIL.
Sintaxe
AEVAL ( < aVetor > , < bBloco > , [ nInicio ] , [ nCont ] ) --> aVetor
Parmetros
Argumento
aVetor
bBloco
nInicio
nCont
Tipo
Array
Descrio
<aVetor> o vetor a ser varrido.
<bBloco> um bloco de cdigo a ser executado para 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.
Retorno
Tipo
Array
Descrio
AEVAL() retorna uma referncia a <aVetor>.
Descrio
AEVAL() uma funao de tratamento de vetor que avalia um bloco de cdigo uma vez
para cada elemento de um vetor, passando o valor do elemento como um parmetro de
bloco. O valor de retorno do bloco ignorado. Todos os elementos no <aVetor> sao
processados a nao ser que o argumento <nInicio> ou <nCont> seja especificado.
AEVAL() nao faz suposioes sobre o contedo dos elementos de vetor que ele est
passando para o bloco. assumido que o bloco sabe qual o tipo de dados haver em cada
elemento.
AEVAL() semelhante a DBEVAL(), que aplica um bloco para cada registro de um
arquivo de banco de dados. Da mesma forma que DBEVAL(), AEVAL() pode ser
utilizado como base para a construao de comandos de interaao tanto para estruturas de
vetor complexas como simples.
Consulte a seao Blocos de Cdigo no na seo A Linguagem Advpl para maiores
informaes sobre Code-Blocks.
Exemplos
Local aArray := { "Teste" , 123 }
Local bBlock := { |x,y| conout(valtype(x)) , conout(y) }
aEval(aArray,bBlock)
nTotal := 0
For nI := 1 to len(aItens)
nTotal := nTotal + aItens[nI][2]
Next
conout(nTotal) // 37
Sintaxe
AFILL ( < aDestino > , < ValorExp > , [ nInicio ] , [ nCont ] ) --> aDestino
Parmetros
Argumento
aDestino
ValorExp
nInicio
nCont
Tipo
Array
Descrio
<aDestino> o vetor a ser preenchido.
<ValorExp> o valor a ser alocado em cada elemento de
(Qualquer) vetor. Pode ser uma expressao de qualquer tipo de dados
vlido.
<nInicio> a posiao do primeiro elemento a ser
Numrico preenchido. Caso este argumento seja omitido, o valor
padrao um.
<nCont> a quantidade de elementos a serem preenchidos
iniciando com o elemento <nInicio>. Se este argumento for
Numrico
omitido, os elementos sao preenchidos a partir da posiao
do elemento inicial at o final do vetor.
Retorno
Tipo
Array
Descrio
AFILL() retorna uma referncia ao <aDestino>.
Descrio
AFILL() uma funao de vetor que preenche um vetor especificado com um nico valor
de qualquer tipo de dados (inclusive vetores, blocos de cdigo ou NIL) atribuindo
<ValorExp> a cada elemento de vetor na faixa especificada.
ATENO : AFILL() nao pode ser utilizado para preencher vetores multi-dimensionais.
Este tipo de vetores em Clipper sao implementados aninhando-se vetores dentro de outros
Sintaxe
AINS ( < aDestino > , < @nPos > ) --> aDestino
Parmetros
Argumento
aDestino
nPos
Tipo
Array
Descrio
o array de onde ser inserido um item NIL.
a posio, a partir da 1, na qual ser inserido um
Numrico
elemento NIL
Retorno
Tipo
Array
Descrio
Retorna uma referncia ao vetor aDestino
Descrio
AINS() uma funo de vetor que insere um novo elemento em um vetor especificado. O
elemento recm inserido NIL at que um novo valor seja atribuido a ele. Aps a
insero, o ltimo elemento no vetor descartado, e todos os elementos depois do novo
elemento descem uma posio.
AVISO : AINS() deve ser utilizado com cuidado quando se tratar de vetores multidimensionais. Vetores multi-dimensionais em Advpl sao implementados atravs do
aninhamento de vetores dentro de outros vetores. Utilizar AINS() com um vetor multidimensional descarta o ltimo sub-vetor no vetor destino especificado, o que causa a
perda de uma ou mais dimensoes. Para inserir uma nova dimensao em um vetor,
primeiramente adicione um novo elemento ao final do vetor utilizando AADD() ou
ASIZE() antes de usar AINS().
Exemplos
Este exemplo demonstra o efeito da utilizao de AINS() em um vetor:
LOCAL aArray
aArray := { 1, 2, 3 }
AINS(aArray, 2)
2 }
Sintaxe
ARRAY ( < nElementos,... > ) --> aVetor
Parmetros
Argumento
Tipo
nElementos,...
Descrio
<nElementos> a quantidade de elementos na dimensao
Numrico especificada.Os vetores em Advpl podem ter um nmero
ilimitado de dimensoes.
Retorno
Tipo
Array
Descrio
ARRAY() retorna um vetor de dimensoes especificadas.
Descrio
ARRAY() uma funao de tratamento de vetor que retorna um vetor nao inicializado
com a quantidade especificada de elementos e dimensoes. Se for especificado mais de um
argumento <nElementos>, criado um vetor multi-dimensional ou aninhado, sendo que a
quantidade de dimensoes igual quantidade de argumentos <nElementos> especificada.
No Advpl, h vrias formas de se criar um vetor. Voc pode declarar um vetor utilizando
LOCAL ou STATIC; voc pode criar um vetor utilizando PRIVATE ou PUBLIC; voc
pode atribuir um vetor literal a uma varivel existente; ou voc pode usar a funao
ARRAY(). ARRAY() tem a vantagem de possibilitar a voc a criaao de vetores dentro
de expressoes ou blocos de cdigo.
Exemplos
Este exemplo cria um vetor unidimensional de cinco elementos utilizando a funao
ARRAY(), e depois exibe a aao equivalente atribuindo um vetor literal de valores NIL:
aArray := ARRAY(5)
aArray := { NIL, NIL, NIL, NIL, NIL }
Este exemplo ilustra trs declaraoes diferentes que criam o mesmo vetor multidimensional:
aArray := ARRAY(3, 2)
aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} }
aArray := { ARRAY(2), ARRAY(2), ARRAY(2) }
Sintaxe
ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm
Parmetros
Argumento
aDestino
ProcuraExp
nInicio
nCont
Tipo
Array
Descrio
<aDestino> o vetor a ser varrido.
<ProcuraExp> pode ser um valor simples a ser procurado,
ou um bloco de cdigo. Caso <ProcuraExp> 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.
Retorno
Tipo
Numrico
Descrio
ASCAN() retorna um valor numrico que representa a posiao ocupada no
vetor pelo ltimo elemento varrido. Se <ProcuraExp> for um valor simples,
ASCAN() retorna a posiao do primeiro elemento que corresponder ao valor
procurado, ou zero caso nao haja correspondncia. Se <ProcuraExp> for um
bloco de cdigo, ASCAN() retorna a posiao do elemento onde o bloco
retornou verdadeiro (.T.).
Descrio
ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor
especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor
simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea
com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai para
o prximo elemento no vetor.
Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente igual
ao resultado de <ProcuraExp> para que haja correspondncia.
// Resulta: 2
// Resulta: 0
// Resulta: 2
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
Retorno
Tipo
Numrico
Descrio
ASCAN() retorna um valor numrico que representa a posiao ocupada no
vetor pelo ltimo elemento varrido. Se <ProcuraExp> for um valor simples,
ASCAN() retorna a posiao do primeiro elemento que corresponder ao valor
procurado, ou zero caso nao haja correspondncia. Se <ProcuraExp> for um
bloco de cdigo, ASCAN() retorna a posiao do elemento onde o bloco
retornou verdadeiro (.T.).
Descrio
ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor
especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor
simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea
com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai para
o prximo elemento no vetor.
Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente igual
ao resultado de <ProcuraExp> para que haja correspondncia.
Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor
<aDestino> executando o bloco para cada elemento acessado. medida em que cada
elemento encontrado, ASCAN() passa o valor do elemento como um argumento para o
bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra
quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo
elemento no vetor.
Exemplos
O exemplo a seguir demonstra a pesquisa em um vetor de trs elementos utilizando
valores simples e um bloco de cdigo como critrios de pesquisa. Os critrios do bloco de
cdigo ilustram como executar uma pesquisa que nao faz diferenciaao entre maisculas e
minsculas:
aArray := { "Tom", "Mary", "Sue" }
? ASCAN(aArray, "Mary")
? ASCAN(aArray, "mary")
? ASCAN(aArray, { |x| UPPER(x) == "MARY" })
// Resulta: 2
// Resulta: 0
// Resulta: 2
Parmetros
Argumento
Tipo
destino
(Qualquer)
procura
(Qualquer)
nInicio
Numrico
nCont
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
Retorno
Tipo
Numrico
Descrio
Retorna o valor numrico(indice) que representa a posio ocupada no vetor
pelo ultimo elemento pesquisado, no caso quando a o elemnto foi
encontrado.
Descrio
A funo ASCANX() uma funao de tratamento de vetor. ASCANX tem como
objetivo varrer um vetor
procurando um valor especificado e opera de forma parecida com a funo ASCAN.
A diferena fundamental da funao ASCANX que a funo recebe um segundo
parametro em seu codeblock representando o indice do array.
Exemplo.:
nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y<=100})
Sintaxe
ASIZE ( < aDestino > , < @nTamanho > ) --> ASIZE()
Parmetros
Argumento
aDestino
nTamanho
Tipo
Descrio
Array
<aDestino> o vetor a ser aumentado ou diminuido.
Numrico <nTamanho> o novo tamanho do vetor.
Retorno
Tipo
Array
Descrio
Retorna uma referncia ao array aDestino.
Descrio
ASIZE() uma funo de tratamento de vetor que muda o valor real do vetor <aDestino>.
O vetor diminuido ou aumentado para corresponder ao tamanho especificado. Caso o
vetor seja diminuido, os elementos no final do vetor sao perdidos. Se o vetor for
aumentado, novos elementos sao adicionados ao final do vetor e a eles atribuido NIL.
ASIZE() semelhante a AADD(), o qual adiciona somente um novo elemento ao final de
um vetor e opcionalmente atribui um novo valor ao mesmo tempo. Observe que ASIZE()
diferente de AINS() e ADEL(), os quais na realidade nao modificam o tamanho do
vetor.
Exemplos
Estes exemplos demonstram a adio de novos elementos e a eliminao de elementos
existentes:
aArray := { 1 }
// Resulta: aArray e { 1 }
ASIZE(aArray, 3)
ASIZE(aArray, 1)
Sintaxe
ASORT ( < aDestino > , [ nInicio ] , [ nCont ] , [ bOrdem ] ) --> aDestino
Parmetros
Argumento
aDestino
nInicio
nCont
bOrdem
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.
Retorno
Tipo
Array
Descrio
ASORT() retorna uma referncia ao vetor <aDestino>.
Descrio
ASORT() uma funao de vetor que coloca em ordem todo ou parte de um vetor que
contm elementos de um nico tipo de dados. Os tipos de dados que podem ser ordenados
incluem caractere, data, lgico e numrico.
Se o argumento <bOrdem> nao for especificado, a ordem padrao ascendente. Elementos
com valores baixos sao colocados no incio do vetor (primeiro elemento), enquanto
elementos com valores altos sao colocados no final do vetor (ltimo elemento).
Caso o argumento de bloco <bOrdem> seja especificado, ele utilizado para determinar a
ordem em que os elementos serao colocados. Cada vez que o bloco avaliado, dois
elementos do vetor destino sao passados como parmetros de bloco. O bloco deve
retornar verdadeiro (.T.) se os elementos estiverem ordenados. Isto pode ser usado para
criar uma ordem descendente ou de dicionrio. Veja os exemplos abaixo.
Quando ordenadas, as cadeias de caracteres sao colocadas na sequncia ASCII; valores
lgicos sao ordenados com falso (.F.) sendo considerado o valor menor; valores data sao
ordenados cronologicamente; e numricos sao ordenados por magnitude.
No exemplo abaixo , montamos um code-block para ordenao de um array multidimensional , para ordenar o array em ordem crescente do segundo elemento da
dimenso.
aKids := { {"Mary", 14}, {"Joe", 23},{"Art", 16} }
aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })
// Resultado : { {"Mary", 14}, {"Art", 16}, {"Joe",23} }
Sintaxe
ATAIL ( < aArray > ) --> Ret
Parmetros
Argumento
aArray
Tipo Descrio
Array Representa o array a ser informado para a funo.
Retorno
Tipo
(Qualquer)
Descrio
Retorna ltima ocorrencia ou o ltimo elemento do array.
Descrio
A funo tem o objetivo de retornar a ltima ocorrncia do array informado pelo
argumento <aArray>, caso o argumento Array passado esteja vazio a funo ir retornar
NIL.
Se for informado um argumento que no for um Array para a funo, isto ir causar um
um erro ADVPL.
Ex:
user function tstArray()
Local aArray := {'ola', 'ops', 'oq', 'aff', 'oljha'}
Local cRet
cRet := atail(aArray) //retorna oljha
return cRet
Sintaxe
XmlChildCount ( < oParent > ) --> nChild
Parmetros
Argumento
oParent
Tipo
Descrio
Indica o node XML no qual ele ir fazer a contagem dos
Objeto
filhos.
Retorno
Tipo
Numrico
Descrio
Retorna o numero de elementos encontrados.
Descrio
A funo tem o objetivo de retornar a quantidade de ns existentes, a partir de um nodo
pai informado como argumento.
A funo no faz essa contagem recursivamente pela estrutura, ou seja, ela nao varre a
estrutura entrando em todos subNodos a partir do elemento passado como raiz para a
contagem e sim apenas os filhos de primeiro nvel.
Essa funo util para manipularmos os objetos XML diretamente, sem necessariamente
conhecermos o contedo do objeto.
Sintaxe
XmlChildEx ( < OParent > , < cProcura > ) --> retorno
Parmetros
Argumento
OParent
cProcura
Tipo
Descrio
Nodo usado para indicar o inicio da procura do elemento
Objeto
requerido.
Caracter Representa o nome do elemento que desejamos encontrar.
Retorno
Tipo
(Qualquer)
Descrio
Quando a funao encontrar apenas um elemento ser retornado o objeto
node, caso possua mais de um elemento do mesmo nome ir retornar um
array dos nodes, caso contrrio retorna NIL.
Descrio
A funo tem o objetivo de retornar um ou mais filhos da estrutura, de acordo com o
nome do elemento procurado.
Especificando um elemento qualquer do objeto para a funo, na qual ser usado como
base para busca apenas em seu primeiro sub-nvel a funo ir retornar todos os
nodos filhos que encontar.
til quando quando queremos buscar por um elemento filho e exista mais de um
elemento do mesmo tipo.
Sintaxe
XmlCloneNode ( < oParent > , < cNewName > ) --> Nil
Parmetros
Argumento
oParent
Tipo
Descrio
Objeto Representa o objeto node XML no qual ser colando
cNewName
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de criar um clone, do n informado pelo parametro,
especificando um novo nome para o elemento, de forma que a funo clona apenas o
node, as propriedades no.
Quando o nodo clonado esta com o mesmo nome de um existente, ento criado um
array automaticamente com os nodos.
Ela pode ser utilizada para acrescentarmos dados em um modelo de xml j existente.
Sintaxe
XmlDelNode ( < oParent > , < cNode > ) --> Nil
Parmetros
Argumento
oParent
cNode
Tipo
Descrio
Objeto Representa o Node pai do elemento que ser removido.
Representa o Real name do elemento node que ser
Caracter
removido.
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de deletar um nodo de um objeto xml.
Para isto informamos passando por parametro um elemento do objeto que contm a
estrutura do xml(um nodo qualquer), este nao precisa ser obrigatriamente o root da
estrutura.
Em seguida informamos o nome do nodo que desejamos deletar, pois a funo ir
procurar recursivamente a partir do nodo informado, o elemento que possu o nome do
nodo a ser deletado dentro da estrutura.
cScript
cScript
cScript
cScript
cScript
cScript
+=
+=
+=
+=
+=
+=
"
<Produto>ERP<Produto>"
"
<Quantidade>0</Quantidade>"
"
<Preco>0</Preco>"
"
</Item>"
" </Itens>"
"</pedido>"
Return cScript
Sintaxe
XmlGetChild ( ) --> Nil
Retorno
Tipo
(NULO)
Descrio
Nil
Descrio
A funo tem o objetivo de retornar um elemento filho da estrutura.
Especificando um elemento qualquer do objeto para a funo, na qual ir usar como base
para retornar o nodo filho de nmero indicado pelo segundo parametro passado para a
funo.
til quando queremos mudar o posicionamento do objeto, para algum nodo filho
do atual na estrutura do objeto XML.
No Exemplo seguinte usamos a funo para nos posicionar no nodo <itens>, em seguida
apagamos todos os nodos filhos com a xmlDelNode.
Usando o comando SAVE criamos um arquivo teste.xml ao final da execuo do
programa.
#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 )
Sintaxe
XmlGetParent ( < oNode > ) --> oParent
Parmetros
Argumento
oNode
Tipo
Descrio
representa o node no qual ser usado como referncia para o
Objeto
retorno do node pai.
Retorno
Tipo
Objeto
Descrio
Um objeto posicionado no node de acordo com o argumento passado.
Descrio
A funo tem o objetivo de retornar um nodo que representa o nodo 'pai'
do elemento especificado por parametro.
til quando queremos 'subir' na estrutura do objeto XML
Sintaxe
XmlNewNode ( < oParent > , < cElementName > , < cRealName > , < cType > ) --> Nil
Parmetros
Argumento
oParent
cElementName
cRealName
cType
Tipo
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
Retorno
Tipo
Objeto
Descrio
Nil
Descrio
A funo tem o objetivo de criar um novo nodo a partir de um ponto qualquer no xml.
Para isto necessrio informar em qual ponto do objeto xml(o xml parseado) que
desejamos adicionar um novo elemento.
O novo nodo ser adicionado como filho do nodo passado por parametro, onde sero
informados tambm os dados em relao a ele:
-REALNAME
-ELEMENTNAME
-TYPE
(para entender melhor o funcionamento da funo veja o exemplo)
Exemplos
Neste exemplo criamos o xml atravs da funo GeraXML, parseamos ele atravs da
xmlParser retornando o objeto xml.
Em seguida visualizamos o objeto retornado e usamos a funao xmlChildCount
retornando a quantidade de elementos no objeto contendo o xml. No Nosso exemplo a
funo ir retornar 5 elementos.
Agora usaremos a xmlNewNode, especificando que o novo nodo ser adicionado como
filho de '<pedido>', logo depois acessamos o nodo e acrecentamos um texto para ele.
obs: o resultado disso no xml ser <exemplo1>Exemplo Microsiga</exemplo1>
Aps a criao do nodo, a xmlChildCount ir retornar 6 indicando que o nodo foi
inserido.
#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
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.
Retorno
Tipo
Lgico
Descrio
Retorna true caso consiga transformar em array, false caso contrrio.
Descrio
A funo tem o objetivo de transformar em array, um objeto(node) da estrutura do xml.
Informando um elemento(node) da estrutura XML atravs de parametro como raiz, a
funo ir procurar pelo nome do nodo no qual se deseja transformar em array.
Exemplos
No exemplo seguinte demonstrado o simples uso da funo XmlNode2Arr, em que
pegamos o objetoXml e o tranformamos em um array.
Em seguida gravamos esse objeto em arquivo .xml propriamente dito.
#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" )
Sintaxe
XmlParser ( < cXml > , < cReplace > , < @cError > , < @cWarning > ) --> oXML
Parmetros
Argumento
cXml
cReplace
cError
cWarning
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.
Retorno
Tipo
Objeto
Descrio
Representa um objeto com a estrutura de acordo com o XML.
Descrio
A funo tem o objetivo de retornar um objeto que possu uma estrutura referente ao xml,
passado pelo parametro na funo.
A estrutura retornada:
<ObjXML>
<NodeXML>
-<ArrayNodes>
-REALNAME
-TEXT
-TYPE
Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem.
A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do mesmo
tipo. (demonstrado no exemplo)
Exemplos
Neste exemplo criamos uma funo geraXml que retorna uma string contento um XML.
Quando passamos essa string para a XmlParser, a funo ir montar o objeto analisando
se a sintaxe e a ordem das tags est bem formada, caso isso nao ocorra a funo ir
retonar um warning ou at um possvel erro, nos parametros informados por referncia.
A estrutura:
oXml:
pedido:
-realName
-type
-text
nome_cliente:
-realName
-type
-text
endereo:
-realName
-type
-text
numero:
-realName
-type
-text
data:
-realName
-type
-text
itens:
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()
Parmetros
Argumento
Tipo
cFile
Caracter
cReplace
Caracter
cError
Caracter
cWarning
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.
Retorno
Tipo
Objeto
Descrio
Retorna um objeto q contm uma estrutura de acordo com o XML.
Descrio
A funo tem o objetivo de retornar um objeto que possu uma estrutura referente ao
arquivo .xml, passado pelo parametro na funo.
A estrutura retornada:
<ObjXML>
<NodeXML>
-<ArrayNodes>
-REALNAME
-TEXT
-TYPE
Onde REALNAME, TEXT e TYPE so propriedades que todos nodos possuem.
A propriedade ArrayNodes existir quando um nodo possuir mais de um filho, do mesmo
tipo. (demonstrado no exemplo)
Exemplos
Neste exemplo vamos usar a funo que tem o mesmo objetivo da XmlParser, a diferena
que esta l um arquivo do disco com a extenso .xml.
Quando passamos a string informando o path do arquivo em disco, devemos lembrar que
a procura do arquivo ser feita atravs do rootpath do Protheus.
logo aps a leitura do arquivo a funo ir montar o objeto analisando se a sintaxe e a
ordem das tags est bem formada, caso isso no ocorra a funo ir retonar um warning
ou at um possvel erro, nos parametros informados por referncia.
Caso isso nao ocorra a funo ir retornar o objeto contendo uma estrutura em forma de
arvore, no caso a mesma estrutura do xml.
#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
If Round(Valor/30, 0) = 50 // correto
2. M->EE8_QTDEM1:= Int (M->EE8_SLDINI/M->EE8_QE)
ou invlido
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
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
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
TRY
AS
CATCH
THROW
Notas:
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
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
de correto funcionamento
eficiente
legvel
reutilizvel
extensvel
portvel
Ou melhor:
User Function GetAnswer(lDefault)
Return GetOk(lDefault)
Codificao Auto-Documentvel
" // 11 espaos
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.
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"
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.
<cdigo>
Next nCnt
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
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
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
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
A impresso
esto sendo
utilizadas.
substitudo
#define NUMLINES 1
#define NUMPAGES 2
#define ISDISK
5
If aReturn[ISDISK] == 1
aPrintDefs[ NUMLINES ] := 55
Endif
aPrintDefs[ NUMPAGES ] += 1
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
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
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
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
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
|
+==========================================+
*/
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.
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
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
Sintaxe
DO CASE
CASE lExpressao1
Commandos
[CASE lExpressao2
Commandos
...
CASE lExpressaoN
Commandos]
[OTHERWISE
Commandos]
ENDCASE
Parmetros
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"
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
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
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
Sintaxe
[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.
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
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.
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
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
Agrupamento ou Funo
Elemento de Matriz
Definio de Matriz, Constante ou Bloco de Cdigo
Identificador de Apelido
Macrosubstituio
Passagem de parmetro por referncia
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
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
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
nA
nA
Resulta em 22, pois o operador incremental aumentou o valor da primeira nA antes que
seu valor fosse considerado.
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. Exponenciao
2. Multiplicao e Diviso
3. Adio e Subtrao
Considere o exemplo:
Local nResultado := 2+10/2+5*3+2^3
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
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
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
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.
@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.
==>
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.
==>
20
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.
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 )
)
==>
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
==>
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
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] }
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
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))
E alguns invlidos:
1CODIGO (Inicia por um nmero)
M CARGO (contm um espao em branco)
LOCAL
(palavra reservada do AdvPl)
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))
ou
Local nPercentual, nResultado
nPercentual := 10
nResultado := 250 * (1 + (nPercentual / 100))
ou
Local nPercentual := 10, nResultado
nResultado := 250 * (1 + (nPercentual / 100))
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.
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
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 := {}
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
aAdd(aLetras,"D")
Alert(aLetras[4])
Alert(aLetras[5])
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
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}
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.
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
Reviso: 13/07/2002
Abrangncia
Verso 5.07
Verses Anteriores
Verso 5.08
Verso 6.09
Verso 7.10
Verso 8.11
Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence seu
escopo local.
Os identifadores de escopo so:
LOCAL
STATIC
PRIVATE
PUBLIC
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
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
.
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).