ADVPL

ADVPL
GUIA DE REFERNCIA
Escola conveniada
Verso 1.0 06/2008 Todos direitos reservados
ADVPL
GUIA DE REFERNCIA
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Tel: 11 50114895 / 50116082 / 98081988
E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
NDICE
Converso entre tipos de dados.................................................................................................................8
CTOD().............................................................................................................................................................8
CVALTOCHAR()..............................................................................................................................................8
DTOC().............................................................................................................................................................8
DTOS()..............................................................................................................................................................9
STOD()..............................................................................................................................................................9
STR()...............................................................................................................................................................10
STRZERO()....................................................................................................................................................10
VAL()...............................................................................................................................................................11
Matemticas..............................................................................................................................................11
ACOS()............................................................................................................................................................11
CEILING()......................................................................................................................................................12
COS()..............................................................................................................................................................12
LOG10()..........................................................................................................................................................13
SIN()................................................................................................................................................................13
SQRT()............................................................................................................................................................13
TAN()..............................................................................................................................................................14
Anlise de variveis..................................................................................................................................14
TYPE()............................................................................................................................................................14
VALTYPE().....................................................................................................................................................15
Manipulao de arrays............................................................................................................................16
AADD()...........................................................................................................................................................16
ACLONE()......................................................................................................................................................17
ACOPY().........................................................................................................................................................17
ADEL()............................................................................................................................................................18
ADIR()............................................................................................................................................................18
AFILL()...........................................................................................................................................................19
AINS().............................................................................................................................................................20
ARRAY().........................................................................................................................................................20
ASCAN().........................................................................................................................................................21
ASCANX()......................................................................................................................................................22
ASIZE()...........................................................................................................................................................22
ASORT().........................................................................................................................................................23
ATAIL()...........................................................................................................................................................24
Manipulao de blocos de cdigo............................................................................................................25

EVAL()............................................................................................................................................................25
DBEVAL()......................................................................................................................................................25
AEVAL().........................................................................................................................................................26
Manipulao de strings............................................................................................................................27
ALLTRIM().....................................................................................................................................................27
ASC()..............................................................................................................................................................28
AT().................................................................................................................................................................28
BITON()..........................................................................................................................................................29
CAPITAL()......................................................................................................................................................29
CHR()..............................................................................................................................................................30
DESCEND()....................................................................................................................................................30
GETDTOVAL()...............................................................................................................................................31
ISALPHA().....................................................................................................................................................31
ISDIGIT()........................................................................................................................................................31
ISLOWER()....................................................................................................................................................32
Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
ISUPPER()......................................................................................................................................................32
LEN()..............................................................................................................................................................33
LOWER()........................................................................................................................................................33
LTRIM()..........................................................................................................................................................33
MATHC()........................................................................................................................................................34
OEMTOANSI()...............................................................................................................................................34
PADL() / PADR() / PADC()............................................................................................................................35
RAT()...............................................................................................................................................................35
REPLICATE().................................................................................................................................................36
RTRIM()..........................................................................................................................................................36
SPACE()..........................................................................................................................................................36
STRTOKARR()...............................................................................................................................................37
STRTRAN()....................................................................................................................................................37
STUFF()..........................................................................................................................................................38
SUBSTR().......................................................................................................................................................38
TRANSFORM()..............................................................................................................................................39
UPPER()..........................................................................................................................................................39
Manipulao de data / hora.....................................................................................................................40

CDOW()..........................................................................................................................................................40
CMONTH().....................................................................................................................................................40
DATE()............................................................................................................................................................41
DAY()..............................................................................................................................................................41
DOW().............................................................................................................................................................42
DTOC()...........................................................................................................................................................42
DTOS()............................................................................................................................................................43
ELAPTIME()..................................................................................................................................................43
MONTH()........................................................................................................................................................44
SECONDS()....................................................................................................................................................44
TIME()............................................................................................................................................................45
YEAR()...........................................................................................................................................................45
Manipulao de variveis numricas......................................................................................................46

ABS()..............................................................................................................................................................46
ALEATORIO()................................................................................................................................................46
INT()................................................................................................................................................................47
NOROUND()..................................................................................................................................................47
RANDOMIZE()..............................................................................................................................................48
ROUND()........................................................................................................................................................48
Manipulao de arquivos.........................................................................................................................49
ADIR()............................................................................................................................................................49
CGETFILE()...................................................................................................................................................49
Funo Principal: SELFILE().........................................................................................................................51
Funo auxiliar: PARBOXFILE()...................................................................................................................52
Funo auxiliar: MARKFILE().......................................................................................................................53
Funo auxiliar: TROCA()..............................................................................................................................54
Funo auxiliar: MARCAOK().......................................................................................................................54
CPYS2T()........................................................................................................................................................55
CPYT2S()........................................................................................................................................................55
CURDIR().......................................................................................................................................................56
DIRECTORY()................................................................................................................................................57
DIRREMOVE()..............................................................................................................................................58
DISKSPACE().................................................................................................................................................58
EXISTDIR()....................................................................................................................................................59
FCLOSE().......................................................................................................................................................60
FCREATE().....................................................................................................................................................61
FERASE().......................................................................................................................................................61
FILE()..............................................................................................................................................................62
FILENOEXT()................................................................................................................................................63
Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
FOPEN()..........................................................................................................................................................63
FREAD().........................................................................................................................................................65
FREADSTR ().................................................................................................................................................65
FRENAME()...................................................................................................................................................66
FSEEK()..........................................................................................................................................................66
FT_FEOF()......................................................................................................................................................67
FT_FGOTO()..................................................................................................................................................67
FT_FGOTOP()................................................................................................................................................68
FT_FLASTREC()............................................................................................................................................68
FT_FREADLN().............................................................................................................................................69
FT_FRECNO()................................................................................................................................................69
FT_FSKIP().....................................................................................................................................................70
FT_FUSE()......................................................................................................................................................70
FWRITE().......................................................................................................................................................70
MSCOPYFILE().............................................................................................................................................73
MSCOPYTO()................................................................................................................................................73
MSCREATE().................................................................................................................................................74
MSERASE()....................................................................................................................................................75
MSRENAME()................................................................................................................................................75
RETFILENAME()..........................................................................................................................................76
Manipulao de arquivos e ndices temporrios....................................................................................76

CRIATRAB()..................................................................................................................................................76
Manipulao de bases de dados...............................................................................................................77

ALIAS()..........................................................................................................................................................77
BOF() / EOF().................................................................................................................................................78
COPY()............................................................................................................................................................79
COPY STRUCTURE()...................................................................................................................................81
DBAPPEND().................................................................................................................................................82
DBCLEARALLFILTER()...............................................................................................................................82
DBCLEARFILTER()......................................................................................................................................83
DBCLEARINDEX().......................................................................................................................................83
DBCLOSEALL()............................................................................................................................................84
DBCLOSEAREA().........................................................................................................................................84
DBCOMMIT()................................................................................................................................................85
DBCOMMITALL().........................................................................................................................................85
DBCREATE()..................................................................................................................................................86
DBCREATEINDEX().....................................................................................................................................87
DBDELETE()..................................................................................................................................................88
DBF()..............................................................................................................................................................89
DBFIELDINFO()............................................................................................................................................89
DBFILTER()...................................................................................................................................................90
DBGOTO()......................................................................................................................................................90
DBGOTOP()...................................................................................................................................................91
DBGOBOTTON()...........................................................................................................................................91
DBINFO().......................................................................................................................................................92
DBNICKINDEXKEY()..................................................................................................................................93
DBORDERINFO()..........................................................................................................................................93
DBORDERNICKNAME()..............................................................................................................................94
DBPACK()......................................................................................................................................................94
DBRECALL().................................................................................................................................................95
DBRECORDINFO().......................................................................................................................................95
DBREINDEX()...............................................................................................................................................96
DBRLOCK()...................................................................................................................................................97
DBRLOCKLIST()...........................................................................................................................................97
DBRUNLOCK().............................................................................................................................................98
DBSETDRIVER()...........................................................................................................................................98
DBSETINDEX().............................................................................................................................................99
Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DBSETNICKNAME()....................................................................................................................................99
DBSELECTAREA().....................................................................................................................................100
DBSETORDER()..........................................................................................................................................101
DBORDERNICKNAME()............................................................................................................................101
DBSEEK() E MSSEEK()..............................................................................................................................101
DBSKIP()......................................................................................................................................................103
DBSETFILTER()..........................................................................................................................................103
DBSTRUCT()...............................................................................................................................................104
DBUNLOCK()..............................................................................................................................................105
DBUNLOCKALL()......................................................................................................................................105
DBUSEAREA()............................................................................................................................................105
DELETED()..................................................................................................................................................106
FCOUNT()....................................................................................................................................................107
FOUND()......................................................................................................................................................107
INDEXKEY()................................................................................................................................................108
INDEXORD()...............................................................................................................................................108
LUPDATE()..................................................................................................................................................109
MSAPPEND()...............................................................................................................................................109
MSUNLOCK()..............................................................................................................................................109
ORDBAGEXT()............................................................................................................................................110
ORDKEY()....................................................................................................................................................111
RECLOCK()..................................................................................................................................................111
RECNO().......................................................................................................................................................112
SELECT()......................................................................................................................................................113
SET FILTER TO............................................................................................................................................113
SOFTLOCK()................................................................................................................................................114
USED()..........................................................................................................................................................115
Controle de numerao seqencial........................................................................................................115

GETSXENUM()............................................................................................................................................115
CONFIRMSXE()...........................................................................................................................................116
ROLLBACKSXE().......................................................................................................................................116
Validao.................................................................................................................................................116
ALLWAYSFALSE()......................................................................................................................................116
ALLWAYSTRUE().......................................................................................................................................116
EXISTCHAV()..............................................................................................................................................117
EXISTCPO().................................................................................................................................................117
LETTERORNUM().......................................................................................................................................117
NAOVAZIO()................................................................................................................................................118
NEGATIVO()................................................................................................................................................118
PERTENCE()................................................................................................................................................118
POSITIVO()..................................................................................................................................................118
TEXTO().......................................................................................................................................................119
VAZIO()........................................................................................................................................................119
Manipulao de parmetros do sistema................................................................................................119

GETMV()......................................................................................................................................................119
GETNEWPAR()............................................................................................................................................119
PUTMV()......................................................................................................................................................120
SUPERGETMV()..........................................................................................................................................120
Controle de impresso............................................................................................................................121
AVALIMP()...................................................................................................................................................121
CABEC().......................................................................................................................................................122
IMPCADAST().............................................................................................................................................125
MS_FLUSH()................................................................................................................................................125
OURSPOOL()...............................................................................................................................................127
RODA().........................................................................................................................................................128
SETDEFAULT()............................................................................................................................................130
Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
SETPRC()......................................................................................................................................................131
SETPRINT()..................................................................................................................................................131
Controle de processamentos..................................................................................................................133
ABREEXCL()...............................................................................................................................................133
CLOSEOPEN().............................................................................................................................................133
CLOSESFILE().............................................................................................................................................133
CHKFILE()...................................................................................................................................................134
CONOUT()....................................................................................................................................................134
CRIAVAR()...................................................................................................................................................135
DISARMTRANSACTION()........................................................................................................................135
EXECBLOCK()............................................................................................................................................136
EXISTBLOCK()...........................................................................................................................................137
ERRORBLOCK().........................................................................................................................................138
FINAL()........................................................................................................................................................139
FINDFUNCTION().......................................................................................................................................140
FUNDESC()..................................................................................................................................................140
FUNNAME()................................................................................................................................................140
GETAREA()..................................................................................................................................................141
GETCOUNTRYLIST().................................................................................................................................141
ISINCALLSTACK().....................................................................................................................................141
REGTOMEMORY().....................................................................................................................................142
RESTAREA()................................................................................................................................................142
USEREXCEPTION()....................................................................................................................................143
Utilizao de recursos do ambiente ERP..............................................................................................143

AJUSTASX1()...............................................................................................................................................143
ALLUSERS()................................................................................................................................................145
ALLGROUPS().............................................................................................................................................147
CGC()............................................................................................................................................................148
CONPAD1()..................................................................................................................................................148
DATAVALIDA()............................................................................................................................................148
EXISTINI()...................................................................................................................................................149
EXTENSO()..................................................................................................................................................149
FORMULA().................................................................................................................................................150
GETADVFVAL()..........................................................................................................................................150
HELP()..........................................................................................................................................................150
MESEXTENSO()..........................................................................................................................................151
OBRIGATORIO().........................................................................................................................................152
OPENFILE().................................................................................................................................................155
PERGUNTE()...............................................................................................................................................155
PESQPICT()..................................................................................................................................................155
PESQPICTQT()............................................................................................................................................156
POSICIONE()...............................................................................................................................................156
PUTSX1()......................................................................................................................................................157
RETINDEX()................................................................................................................................................158
SIXDESCRICAO().......................................................................................................................................158
TABELA().....................................................................................................................................................159
TAMSX3().....................................................................................................................................................159
TM()..............................................................................................................................................................159
X1DEF01()....................................................................................................................................................160
X1PERGUNT().............................................................................................................................................161
X2NOME()....................................................................................................................................................161
X3CBOX()....................................................................................................................................................162
X3DESCRIC()..............................................................................................................................................162
X3PICTURE()...............................................................................................................................................163
X3TITULO().................................................................................................................................................164
X3USO().......................................................................................................................................................164
X5DESCRI().................................................................................................................................................165
Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
X6CONTEUD()............................................................................................................................................165
X6DESCRIC()..............................................................................................................................................166
XADESCRIC()..............................................................................................................................................167
XBDESCRI()................................................................................................................................................168
XFILIAL().....................................................................................................................................................168
Componentes da interface visual...........................................................................................................169

MSDIALOG()...............................................................................................................................................169
MSGET().......................................................................................................................................................169
SAY().............................................................................................................................................................170
BUTTON()....................................................................................................................................................170
SBUTTON()..................................................................................................................................................171
CHECKBOX()..............................................................................................................................................172
COMBOBOX().............................................................................................................................................173
FOLDER().....................................................................................................................................................173
RADIO()........................................................................................................................................................174
Interfaces de cadastro............................................................................................................................175
AXCADASTRO().........................................................................................................................................175
MBROWSE()................................................................................................................................................175
AXPESQUI()................................................................................................................................................175
AXVISUAL()................................................................................................................................................176
AXINCLUI().................................................................................................................................................176
AXALTERA()...............................................................................................................................................177
AXDELETA()...............................................................................................................................................178
Interfaces visuais para aplicaes.........................................................................................................178

ALERT()........................................................................................................................................................178
AVISO()........................................................................................................................................................179
FORMBACTH()...........................................................................................................................................179
MSGFUNCTIONS().....................................................................................................................................180
Recursos das interfaces visuais..............................................................................................................181

GDFIELDGET()...........................................................................................................................................181
GDFIELDPOS()............................................................................................................................................181
GDFIELDPUT()............................................................................................................................................182
GETMARK()................................................................................................................................................182
MARKBREFRESH()....................................................................................................................................183
READVAR().................................................................................................................................................184

Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Converso entre tipos de dados

CTOD()
Realiza a converso de uma informao do tipo caracter no formato DD/MM/AAAA para uma
varivel do tipo data.
Sintaxe: CTOD(cData)
Parmetros
cData
Caracter no formato DD/MM/AAAA
Exemplo:
LOCAL cData := 31/12/2006
LOCAL dData := CTOD(cData)
IF dDataBase >= dData
MSGALERT(Data do sistema fora da competncia)
ELSE
MSGINFO(Data do sistema dentro da competncia)
ENDIF
CVALTOCHAR()
Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de
espaos a informao.
Sintaxe: CVALTOCHAR(nValor)
Parmetros
nValor
Valor numrico que ser convertido para caractere.
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CVALTOCHAR(nPercorridos))
NEXT nPercorridos
DTOC()
Realiza a converso de uma informao do tipo data para em caracter, sendo o resultado no
formato DD/MM/AAAA.
Sintaxe: DTOC(dData)
Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
dData
Varivel com contedo data
Exemplo:
MSGINFO(Database do sistema: +DTOC(dData))
DTOS()
Realiza a converso de uma informao do tipo data em um caracter, sendo o resultado no
formato AAAAMMDD.
Sintaxe: DTOS(dData)
Parmetros
dData
Varivel com contedo data
Exemplo:
cQuery := SELECT A1_COD, A1_LOJA, A1_NREDUZ FROM SA1010 WHERE
cQuery += A1_DULTCOM >=+DTOS(dDataIni)+
STOD()
Realiza a converso de uma informao do tipo string com contedo no formato AAAAMMDD
em data, no formato DD/MM/AAAA.
Sintaxe: STOD(sData)
Parmetros
sData
String no formato AAAAMMDD
Exemplo:
LOCAL sData := 20080601
LOCAL dData := STOD(sData)
MSGINFO(dData)

Tel: 11 50114895 / 50116082 / 98081988
SP
ADVPL
GUIA DE REFERNCIA
Escola conveniada
STR()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos
direita.
Sintaxe: STR(nValor)
Parmetros
nValor
Exemplo:
LOCAL nPassos := 6
MSGINFO(Passos percorridos: +STR(nPassos)
STRZERO()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando zeros
esquerda do nmero convertido, de forma que a string gerada tenha o tamanho especificado
no parmetro.
Sintaxe: STRZERO(nValor, nTamanho)

Parmetros
nValor
nTamanho
Tamanho total desejado para a string retornada.
Exemplo:
LOCAL nPassos := 6
MSGINFO(Passos percorridos: +STRZERO(nPassos,6))

Tel: 11 50114895 / 50116082 / 98081988
SP
10
ADVPL
GUIA DE REFERNCIA
Escola conveniada
VAL()
Realiza a converso de uma informao do tipo caracter em numrica.
Sintaxe: VAL(cValor)
Parmetros
cValor
String que ser convertida para numrico.
Exemplo:
LOCAL cValor := 12345
LOCAL nValor := VAL( cValor ) + 1
MSGINFO( nValor )
Matemticas
ACOS()
Funo utilizada para calcular o valor do arco co-seno.
Sintaxe: ACOS(nValor)
Parmetros:
nValor
Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
11
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Numrico
Range de 0 a radianos.
Se o valor informado no parmetro for menor que 1 ou maior que 1, acos
retorna um valor indefinido por default [+ , -]
CEILING()
Funo utilizada para calcular o valor mais prximo possvel de um valor nMax informado como
parmetro para a funo.
Sintaxe: CELLING(nMax)
Parmetros
nMax
Valor limite para anlise da funo, no formato floating-point.
Retorno:
Numrico
Valor do tipo double, representando o menor inteiro que maior ou igual ao
valor de nX. No h retorno de erro na funo.
COS()
Funo utilizada para calcular o valor do co-seno ou co-seno hiperblico.
Sintaxe: COS(nAngulo)
Parmetros:
nAngulo
Retorno:
Numrico
Valor que representa o ngulo em radianos.
Valor que representa o co-seno ou co-seno hiperblico do ngulo informado.
Situaes invlidas:
Entrada
QNAN,IND
(cosf, cos)
x 7.104760e+002 (cosh, coshf)
Exceo apresentada
None
INVALID
INEXACT+OVERFLOW
Significado da Exceo
Sem Domnio
Sem Domnio
OVERFLOW
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na

chamada da funo COS().

Tel: 11 50114895 / 50116082 / 98081988
SP
12
ADVPL
GUIA DE REFERNCIA
Escola conveniada
LOG10()
Funo utilizada para calcular o logaritmo natural de um valor numrico, em base 10.
LOG10() uma funo numrica que calcula o logaritmo natural de um nmero. O logaritmo
natural tem como base o valor 10. Devido ao arredondamento matemtico, os valores
retornados por LOG() podem no coincidir exatamente.
Sintaxe: LOG10(nNatural)
Parmetros:
nNatural
Valor cujo o logaritmo deve ser encontrado.
Retorno:
Numrico
A funo retorna o logaritmo de nNatural se bem sucedidas. Se nNatural for

negativo, estas funes retornam um indefinido, pelo defeito. Se nNatural for
0, retornam INF(infinito).
SIN()
Funo utilizada para calcular o valor do seno ou seno hiperblico. Devemos informar como
parmetro para a funo um valor que representa o angulo em radianos.
Sintaxe: SIN(nAngulo)
Parmetros:
nAngulo
Retorno:
Numrico
Valor do ngulo em radianos.
Retorna o valor do seno do ngulo especificado.
Situaes invlidas:
Entrada
QNAN,IND
(senf, sen)
x 7.104760e+002 (senh, senhf)
Exceo apresentada
None
INVALID
INEXACT+OVERFLOW
Sem Domnio
Sem Domnio
OVERFLOW
Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da

funo SIN().
SQRT()
Funo utilizada para calcular a raiz quadrada de um nmero positivo.
Sintaxe: SQRT(nValor)
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
13
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nValor
Um nmero positivo do qual ser calculada a raiz quadrada.
Retorno:
Numrico
Retorna um valor numrico calculado com preciso dupla. A quantidade de

casas decimais exibidas determinada apenas por SET DECIMALS, sem
importar a configurao de SET FIXED. Um nmero negativo <nValor>
retorna zero.
TAN()
Funo utilizada para calcular o valor da tangente ou tangente hiperblica.
Sintaxe: TAN(nAngulo)
Parmetros:
nAngulo
Valor do ngulo em radianos.
Retorno:
Numrico
Retorna o valor da tangente do ngulo especificado.
Situaes invlidas:
Entrada
QNAN,IND
Exceo apresentada
None
INVALID
Sem Domnio
Sem Domnio
Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da

funo cos.
Anlise de variveis
TYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.
Sintaxe: TYPE(cVariavel)
Parmetros
cVariavel
Nome da varivel que se deseja avaliar, entre aspas ().
Exemplo:
IF TYPE(dDataBase) == D
Tel: 11 50114895 / 50116082 / 98081988
SP
14
ADVPL
GUIA DE REFERNCIA
Escola conveniada
ELSE
ENDIF
MSGINFO(Database do sistema: +DTOC(dDataBase))

MSGINFO(Varivel indefinida no momento)
VALTYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.
Sintaxe: VALTYPE(cVariavel)
Parmetros
cVariavel
Nome da varivel que se deseja avaliar.
Exemplo:
STATIC FUNCTION GETTEXTO(nTamanho, cTitulo, cSay)
LOCAL cTexto
:=
LOCAL nColF, nLargGet
:= 0
PRIVATE oDlg
Default cTitulo
:= "Tela para informar texto"
Default cSay
:= "Informe o texto:"
Default nTamanho := 1
nTamanho
cTexto
nColf
:= IIF(ValType(nTamanho) != N,1,nTamanho) // Se o parmetro foi passado

:= Space(nTamanho);nLargGet := Round(nTamanho * 2.5,0);
:= Round(195 + (nLargGet * 1.75) ,0)
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 120,nColF PIXEL

@ 005,005 TO 060, Round(nColF/2,0) OF oDlg PIXEL
@ 010,010 SAY cSay SIZE 55, 7 OF oDlg PIXEL
@ 010,065 MSGET cTexto SIZE nLargGet, 11 OF oDlg PIXEL ;
Picture "@!" VALID !Empty(cTexto)
DEFINE SBUTTON FROM 030, 010 TYPE 1 ACTION (nOpca := 1,oDlg:End()) ENABLE OF oDlg
DEFINE SBUTTON FROM 030, 040 TYPE 2 ACTION (nOpca := 0,oDlg:End()) ENABLE OF oDlg
ACTIVATE MSDIALOG oDlg CENTERED
cTexto := IIF(nOpca==1,cTexto,"")
RETURN cTexto

Tel: 11 50114895 / 50116082 / 98081988
SP
15
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Manipulao de arrays
AADD()
A funo AADD() permite a insero de um item em um array j existente, sendo que este
item podem ser um elemento simples, um objeto ou outro array.
Sintaxe: AADD(aArray, xItem)

Parmetros
aArray
Array pr-existente no qual ser adicionado o item definido em xItem
xItem
Item que ser adicionado ao array.
Exemplo:
aDados := {} // Define que a varivel aDados um array, sem especificar suas dimenses.
aItem := {} // Define que a varivel aItem um array, sem especificar suas dimenses.
AADD(aItem, cVariavel1) // Adiciona um elemento no array aItem de acordo com o cVariavel1
//
//
//
//
Neste ponto o array a Item possui 03 elementos os quais podem ser acessados com:
aItem[1] -> corresponde ao contedo de cVariavel1
AADD(aDados,aItem) // Adiciona no array aDados o contedo do array aItem

//
//
//
//
//
Neste ponto, o array a aDados possui apenas um elemento, que tambm um array
contendo 03 elementos:
aDados [1][1] -> corresponde ao contedo de cVariavel1
AADD(aDados, aItem)
AADD(aDados, aItem)
// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros
// 03 elementos, sendo:
// aDados [1][1] -> corresponde ao contedo de cVariavel1
Tel: 11 50114895 / 50116082 / 98081988
SP
16
ADVPL
GUIA DE REFERNCIA
Escola conveniada

// Desta forma, o array aDados montando com uma estrutura de 03 linhas e 03 colunas, com
// o contedo definido por variveis externas, mas com a mesma forma obtida com o uso do
// comando: aDados := ARRAY(3,3).
ACLONE()
A funo ACLONE() realiza a cpia dos elementos de um array para outro array integralmente.
Sintaxe: ACLONE(aArray)
Parmetros
aArray
Array pr-existente que ter seu contedo copiado para o array especificado.
Exemplo:
Utilizando o array aDados utilizado no exemplo da funo AADD()
Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array
aDados
aItens := ACLONE(aDados)
Por ser uma estrutura de memria, um array no pode ser simplesmente

copiado para outro array atravs de uma atribuio simples (:=).
Para mais informaes sobre a necessidade de utilizar o comando ACLONE()
verifique o tpico 6.1.3 Cpia de Arrays.
ACOPY()
Funo de array que copia elementos do array aOrigem para array aDestino. O array destino
aDestino j deve ter sido declarado e grande o bastante para conter os elementos que sero
copiados. Se o array aOrigem contiver mais elementos, alguns dos elementos no sero
copiados. ACOPY() copia os valores de todos os dados, incluindo valores nulos (NIL) e cdigos
de bloco.
Se um elemento for um subarray, o elemento correspondente no array aDestino, conter o
mesmo subarray. Portanto, ACOPY() no produzir uma cpia completa de array
multidimensionais.
Sintaxe: ACOPY( aOrigem, aDestino , [ nInicio ], [ nQtde ], [ nPosDestino ])

Parmetros:
aOrigem
o array que contm os elementos a serem copiados.
aDestino
o array que receber a cpia dos elementos.
nInicio
indica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se

Tel: 11 50114895 / 50116082 / 98081988
SP
17
ADVPL
GUIA DE REFERNCIA
Escola conveniada
no for especificado, o valor assumido ser 01.

nQtde
nPosDestino
indica a quantidade de elementos a serem copiados a partir do array

aOrigem. iniciando-se a contagem a partir da posio nInicio. Se nQtde no
for especificado, todos os elementos do array aOrigem sero copiados,
iniciando-se a partir da posio nInicio.
a posio do elemento inicial no array aDestino que receber os
elementos de aOrigem. Se no especificado, ser assumido 01.
Retorno:
aDestino
referncia ao array aDestino.
Exemplo:
LOCAL nCount := 2, nStart := 1, aOne, aTwo
aOne := { 1, 1, 1 }
aTwo := { 2, 2, 2 }
ACOPY(aOne, aTwo, nStart, nCount)
// Result: aTwo is now { 1, 1, 2 }
ADEL()
A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a excluso de um
elemento, todos os demais so reorganizados de forma que a ultima posio do array passar
a ser nula.
Sintaxe: ADEL(aArray, nPosio)

Parmetros
aArray
Array do qual deseja-se remover uma determinada posio
nPosio
Posio do array que ser removida
Exemplo:
// Utilizando o array aItens do exemplo da funo ACLONE() temos:
ADEL(aItens,1) // Ser removido o primeiro elemento do array aItens.
//
//
//
//
Neste ponto, o array aItens continua com 03 elementos, aonde:

aItens[1] -> antigo aItens[2], o qual foi reordenado como efeito da excluso do item 1.
aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito da excluso do item 1.
aItens[3] -> contedo nulo, por se tratar do item excludo.
ADIR()
Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da
mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados.
Importante: ADir uma funo obsoleta, utilize sempre Directory().
Tel: 11 50114895 / 50116082 / 98081988
SP
18
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora],

[ aAtributo ])
Parmetros:
cArqEspec
aNomeArq
aTamanho
aData
aHora
aAtributos
Caminho dos arquivos a serem includos na busca de informaes. Segue o

padro para especificao de arquivos, aceitando arquivos no servidor
Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso
seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ).
Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
Array Numrico. So os tamanhos dos arquivos encontrados na busca.
Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
Array de Caracteres. So os atributos dos arquivos, caso esse array seja
passado como parmetros, sero includos os arquivos com atributos de
sistema e ocultos.
Retorno:
nArquivos
Quantidade de arquivos encontrados.
Exemplo:
LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })
AFILL()
Funo de manipulao de arrays, que preenche os elementos do array com qualquer tipo de
dado. Incluindo code-block. Esta funo no deve ser usada para preencher um array com
outro array.
Sintaxe: AFILL( aDestino , xExpValor, [ nInicio ], [ nQuantidade ])

Parmetros
aDestino
o onde os dados sero preenchidos.
xExpValor
o dado que ser preenchido em todas as posies informadas, no

permitida a utilizao de arrays.
a posio inicial de onde os dados sero preenchidos, o valor padro 1.
nInicio
nCount
Quantidade de elementos a partir de [nInicio] que sero preenchidos com

<expValor>, caso no seja informado o valor ser a quantidade de
elementos at o final do array.
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
19
ADVPL
GUIA DE REFERNCIA
Escola conveniada
aDestino
Retorna uma referncia para aDestino.
Exemplo:
LOCAL aLogic[3]
// Resultado: aLogic { NIL, NIL, NIL }
AFILL(aLogic, .F.)
// Resultado: aLogic { .F., .F., .F. }
AFILL(aLogic, .T., 2, 2)
// Resultado: aLogic { .F., .T., .T. }
AINS()
A funo AINS() permite a insero de um elemento no array especificado em qualquer ponto
da estrutura do mesmo, diferindo desta forma da funo AADD() a qual sempre insere um
novo elemento ao final da estrutura j existente.
Sintaxe: AINS(aArray, nPosicao)

Parmetros
aArray
Array pr-existente no qual desejasse inserir um novo elemento.
nPosicao
Posio na qual o novo elemento ser inserido.
Exemplo:
aAlunos := {Edson, Robson, Renato, Tatiana}
AINS(aAlunos,3)
// Neste ponto o array aAlunos ter o seguinte contedo:
// {Edson, Robson, nulo, Renato, Tatiana}
Similar ao efeito da funo ADEL(), o elemento inserido no array pela funo

AINS() ter um contedo nulo, sendo necessrio trata-lo aps a realizao
deste comando.
ARRAY()
A funo Array() utilizada na definio de variveis de tipo array, como uma opo a sintaxe
utilizando chaves ({}).
Sintaxe: Array(nLinhas, nColunas)

Parmetros
nLinhas
Determina o nmero de linhas com as quais o array ser criado
nColunas
Determina o nmero de colunas com as quais o array ser criado

Tel: 11 50114895 / 50116082 / 98081988
SP
20
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.
O array definido pelo comando Array() apesar de j possuir a estrutura

solicitada, no possui contedo em nenhum de seus elementos, ou seja:
aDados[1] -> array de trs posies
aDados[1][1] -> posio vlida, mas de contedo nulo.
ASCAN()
A funo ASCAN() permite que seja identificada a posio do array que contm uma
determinada informao, atravs da anlise de uma expresso descrita em um bloco de
cdigo.
Sintaxe: ASCAN(aArray, bSeek)

Parmetros
aArray
bSeek
Array pr-existente no qual desejasse identificar a posio que contm a

informao pesquisada.
Bloco de cdigo que configura os parmetros da busca a ser realizada.
Exemplo:
aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}
bSeek := {|x| x == Denis}
nPosAluno := aScan(aAlunos,bSeek) // retorno esperado 2
Durante a execuo da funo aScan, a varivel x receber o contedo o

item que est posicionado no momento, no caso aAlunos[x]. Como aAlunos[x]
uma posio do array que contm o nome do aluno, x poderia ser
renomeada para cNome, e a definio do bloco bSeek poderia ser re-escrita
como:
bSeek := {|cNome| cNome == Denis}
Na definio dos programas sempre recomendvel utilizar variveis com

nomes significativos, desta forma os blocos de cdigo no so exceo.
Sempre opte por analisar como o bloco de cdigo ser utilizado e ao invs de
x, y e similares, defina os parmetros com nomes que representem seu
contedo. Ser mais simples o seu entendimento e o entendimento de outros
que forem analisar o cdigo escrito.

Tel: 11 50114895 / 50116082 / 98081988
SP
21
ADVPL
GUIA DE REFERNCIA
Escola conveniada
ASCANX()
Funo utilizada para varrer um vetor procurando um valor especificado, operando de forma
similar a funo ASCAN.
A diferena fundamental da funo ASCANX que esta funo recebe um segundo parmetro
em seu code-block representando o ndice do array.
Sintaxe: ASCANX ( < xDestino > , < bSeek > , [ nInicio ] , [ nCont ] )
Parmetros:
xDestino
bSeek
nInicio
nCont
Representa o objeto a ser varrido pela funo, pode ser atribudo ao

parmetro 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 no for informado o valor default ser 1.
Representa a quantidade de elementos que sero pesquisados a partir da
posio inicial, quando este argumento no for informado todos elementos
do array sero pesquisados.
Exemplo:
nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y<=100})
No cdigo demonstrado acima, note a incluso no code-block do Y, onde a
funo ir terminar sua execuo em 3 condies:
1) At encontrar o elemento no ARRAY com a ocorrncia cNome, retornando a
posio desse elemento.
2) Essa novidade, ASCANX ir verificar o Array at a posio 100.
3) O elemento cNome no foi encontrado no ARRAY e a condio de Y at 100
no satisfaz, pois o array menor do que 100 posies!
Como ASCAN() que utiliza o operador (=) para comparaes, a funo

ASCANX() tambm case sensitive, no caso os elementos procurados devem
ser exatamente igual.
ASIZE()
A funo ASIZE permite a redefinio da estrutura de um array pr-existente, adicionando ou
removendo itens do mesmo.

Tel: 11 50114895 / 50116082 / 98081988
SP
22
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: ASIZE(aArray, nTamanho)

Parmetros
aArray
Array pr-existente que ter sua estrutura redimensionada.
nTamanho
Tamanho com o qual deseja-se redefinir o array. Se o tamanho for menor do

que o atual, sero removidos os elementos do final do array, j se o tamanho
for maior do que o atual sero inseridos itens nulos ao final do array.
Exemplo:
// Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo ADEL()
ASIZE(aItens,Len(aItens-1))
// Neste ponto o array aItens possui 02 elementos, ambos com contedos vlidos.
Utilizar a funo ASIZE() aps o uso da funo ADEL() uma prtica

recomendada e evita que seja acessada uma posio do array com um
contedo invlido para a aplicao em uso.
ASORT()
A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio
pr-estabelecido.
Sintaxe: ASORT(aArray, nInicio, nItens, bOrdem)

Parmetros
aArray
nInicio
nItens
bOrdem
Array pr-existente que ter seu contedo ordenado atravs de um critrio

estabelecido.
Posio inicial do array para incio da ordenao. Caso no seja informado, o
array ser ordenado a partir de seu primeiro elemento.
Quantos itens, a partir da posio inicial devero ser ordenados. Caso no
seja informado, sero ordenados todos os elementos do array.
Bloco de cdigo que permite a definio do critrio de ordenao do array.
Caso bOrdem no seja informado, ser utilizado o critrio ascendente.
Um bloco de cdigo basicamente uma funo escrita em linha. Desta forma

sua estrutura deve suportar todos os requisitos de uma funo, os quais so
atravs da anlise e interpretao de parmetros recebidos, executar um
processamento e fornecer um retorno.
Com base nesse requisito, pode-se definir um bloco de cdigo com a estrutura
abaixo:
bBloco := { |xPar1, xPar2, ... xParZ| Ao1, Ao2, AoZ } , aonde:
|| -> define o intervalo onde esto compreendidos os parmetros
Ao Z-> expresso que ser executadas pelo bloco de cdigo
Tel: 11 50114895 / 50116082 / 98081988
SP
23
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Ao1... AoZ -> intervalo de expresses que sero executadas pelo bloco
de cdigo, no formato de lista de expresses.
Retorno -> resultado da ultima ao executada pelo bloco de cdigo, no caso
AoZ.
Para maiores detalhes sobre a estrutura e utilizao de blocos de cdigo
consulte o tpico 6.2 Listas de Expresses e Blocos de cdigo.
Exemplo 1:
Ordenao ascendente
aAlunos := { Mauren, Soraia, Andria}
aSort(aAlunos)
// Neste ponto, os elementos do array aAlunos sero {Andria, Mauren, Soraia}
Exemplo 2 :
Ordenao descendente
aAlunos := { Mauren, Soraia, Andria}
bOrdem := {|x,y| x > y }
//
//
//
//
//
//
Durante a execuo da funo aSort(), a varivel x receber o contedo do item que est
posicionado. Como o item que est posicionado a posio aAlunos[x] e aAlunos[x] ->
string contendo o nome de um aluno, pode-se substituir x por cNomeAtu.
A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma
analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de cdigo
bOrdem pode ser re-escrito como:
bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}

aSort(aAlunos,,bOrdem)
// Neste ponto, os elementos do array aAlunos sero {Soraia , Mauren, Andria}
ATAIL()
ATAIL() uma funo de manipulao de array que retorna o ltimo elemento de um array. Ela
deve ser usada em substituio da seguinte construo: aArray [LEN( aArray )]
Sintaxe: ATAIL( aArray )

Parmetros:
aArray
o array de onde ser retornado o ltimo elemento.
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
24
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nUltimo
Nmero do ltimo elemento do array.
Exemplo:
aArray := {"a", "b", "c", "d"}
ATAIL(aArray) // Resultado: d
Manipulao de blocos de cdigo

EVAL()
A funo EVAL() utilizada para avaliao direta de um bloco de cdigo, utilizando as
informaes disponveis no mesmo de sua execuo. Esta funo permite a definio e
passagem de diversos parmetros que sero considerados na interpretao do bloco de cdigo.
Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)

Parmetros
bBloco
Bloco de cdigo que ser interpretado.
xParamZ
Parmetros que sero passados ao bloco de cdigo. A partir da passagem do

bloco, todos os demais parmetros da funo sero convertidos em
parmetros para a interpretao do cdigo.
Exemplo:
nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
nValor := EVAL(bBloco, nInt)
// O retorno ser dado pela avaliao da ultima ao da lista de expresses, no caso z.
// Cada uma das variveis definidas em uma das aes da lista de expresses fica disponvel
// para a prxima ao.
// Desta forma temos:
// N recebe nInt como parmetro (10)
// X tem atribudo o valor 10 (10)
// Y resultado da multiplicao de X por N (100)
// Z resultado a diviso de Y pela multiplicao de X por N ( 100 / 100) 1
DBEVAL()
A funo DBEval() permite que todos os registro de uma determinada tabela sejam analisados
e para cada registro ser executado o bloco de cdigo definido.
Sintaxe: Array(bBloco, bFor, bWhile)

Parmetros
bBloco
Bloco de cdigo principal, contendo as expresses que sero avaliadas para

cada registro do alias ativo.

Tel: 11 50114895 / 50116082 / 98081988
SP
25
ADVPL
GUIA DE REFERNCIA
Escola conveniada
bFor
Condio para continuao da anlise dos registros, com o efeito de uma

estrutura For ... Next.
bWhile
Condio para continuao da anlise dos registros, com o efeito de uma

estrutura While ... End
Exemplo 1:
// Considerando o trecho de cdigo abaixo:
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA <= mv_par02
nCnt++
dbSkip()
End
// O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5") .And. X5_TABELA<=mv_par02})
Exemplo 2:
// Considerando o trecho de cdigo abaixo:
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
While !Eof() .And. X5_TABELA == cTabela
AADD(aTabela,{X5_CHAVE, Capital(X5_DESCRI)})
dbSkip()
End
// O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval({|| AADD(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{|| X5_TABELA==cTabela})
Na utilizao da funo DBEVAL() deve ser informado apenas um dos dois

parmetros: bFor ou bWhile.
AEVAL()
A funo AEVAL() permite que todos os elementos de um determinada array sejam analisados
e para cada elemento ser executado o bloco de cdigo definido.
Sintaxe: AEVAL(aArray, bBloco, nInicio, nFim)

Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
26
ADVPL
GUIA DE REFERNCIA
Escola conveniada
aArray
Array que ser avaliado na execuo da funo.
bBloco
Bloco de cdigo principal, contendo as expresses que sero avaliadas para

cada elemento do array informado.
nInicio
Elemento inicial do array, a partir do qual sero avaliados os blocos de

cdigo.
Elemento final do array, at o qual sero avaliados os blocos de cdigo.
nFim
Exemplo 1:
Considerando o trecho de cdigo abaixo:
AADD(aCampos,A1_FILIAL)
AADD(aCampos,A1_COD)
SX3->(dbSetOrder(2))
For nX:=1 To Len(aCampos)
SX3->(dbSeek(aCampos[nX]))
AADD(aTitulos,AllTrim(SX3->X3_TITULO))
Next nX
O mesmo pode ser re-escrito com o uso da funo AEVAL():
aEval(aCampos,{|x| SX3->(dbSeek(x)),IIF(Found(), AADD(aTitulos,;
AllTrim(SX3->X3_TITULO)))})
Manipulao de strings
ALLTRIM()
Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado
como parmetro.
A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left
trim).
Sintaxe: ALLTRIM(cString)
Parmetros
cString
String que ser avaliada para remoo dos espaos a direita e a esquerda.
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))
ASC()
Tel: 11 50114895 / 50116082 / 98081988
SP
27
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Converte uma informao caractere em seu valor de acordo com a tabela ASCII.
Sintaxe: ASC(cCaractere)
Parmetros
cCaractere
Caracter que ser consultado na tabela ASCII.
Exemplo:
USER FUNCTION NoAcento(Arg1)
Local nConta := 0
Local cLetra := ""
Local cRet := ""
Arg1 := Upper(Arg1)
For nConta:= 1 To Len(Arg1)
cLetra := SubStr(Arg1, nConta, 1)
Do Case
Case (Asc(cLetra) > 191 .and. Asc(cLetra) < 198) .or.;
(Asc(cLetra) > 223 .and. Asc(cLetra) < 230)
cLetra := "A"
cLetra := "E"
Exemplo (continuao):
cLetra := "I"
(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) < 247)
cLetra := "O"
cLetra := "U"
Case Asc(cLetra) == 199 .or. Asc(cLetra) == 231
cLetra := "C"
EndCase
cRet := cRet+cLetra
Next
Return UPPER(cRet)
AT()
Tel: 11 50114895 / 50116082 / 98081988
SP
28
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorna a primeira posio de um caracter ou string dentro de outra string especificada.
Sintaxe: AT(cCaractere, cString )

Parmetros
cCaractere
Caractere ou string que se deseja verificar
cString
String na qual ser verificada a existncia do contedo de cCaractere.
Exemplo:
STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)
LOCAL cNoMascara
LOCAL nX := 0
:= ""
IF !Empty(cMascara) .AND. AT(cMascara,cString) > 0

FOR nX := 1 TO Len(cString)
IF !(SUBSTR(cString,nX,1) $ cMascara)
cNoMascara += SUBSTR(cString,nX,1)
ENDIF
NEXT nX
cNoMascara := PADR(ALLTRIM(cNoMascara),nTamanho)
ELSE
cNoMascara := PADR(ALLTRIM(cString),nTamanho)
ENDIF
RETURN cNoMascara
BITON()
Funo utilizada para ligar determinados bits de uma String passada por parmetro para a
funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico
que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem
alterados(ligados) e o tamanho da string passada.
Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )
Parmetros
cValue
String no qual desejamos ligar os bits.
nBitIni
Indica a partir de qual bit, comear a ser ligados os bits na String
nBitEnd
Indica a quantidade de bits que sero ligados a partir do inicio.
nStrLen
Representa o tamanho da String passada para a funo.
CAPITAL()
Funo que avalia a string passada como parmetro alterando a primeira letra de cada palavra
para maiscula e as demais letras como minsculas.
Sintaxe: CAPITAL(cFrase)

Tel: 11 50114895 / 50116082 / 98081988
SP
29
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
cFrase
String a ser avaliada
Retorno:
String
Contedo da string original com as modificaes necessrias para atender a

condio da funo.
CHR()
Converte um valor nmero referente a uma informao da tabela ASCII no caractere que esta
informao representa.
Sintaxe: CHR(nASCII)
Parmetros
nASCII
Cdigo ASCII do caractere
Exemplo:
#DEFINE CRLF CHR(13)+CHR(10) // FINAL DE LINHA
DESCEND()
Funo de converso que retorna a forma complementada da expresso string especificada.
Esta funo normalmente utilizada para a criao de indexadores em ordem decrescente
Sintaxe: DESCEND ( < cString > )

Parmetros:
cString
Corresponde seqncia de caracteres a ser analisada.
Retorno:
Caracter
String complementada da string analisada.
Exemplo:
// Este exemplo utiliza DESCEND() em uma expresso 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:
Tel: 11 50114895 / 50116082 / 98081988
SP
30
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DbSEEK(DESCEND(DTOS(dFindDate)))
GETDTOVAL()
Funo utilizada para retornar um numero formatado, de acordo com o valor passado por
parmetro, sendo que ir apenas manter os valores numricos contidos na string passada por
parmetro, verificando se existe algum caractere '.' retornando um numero fracionrio, na
ordem dos nmeros contidos na string.
A funo muito til quando desejamos utilizar o valor numrico de uma data que est
contida em uma string.
Sintaxe: GETDTOVAL ( < cDtoVal > )
Parmetros:
cDtoVal
Representa uma string contendo um valor numrico no qual ser convertido.
Retorno:
Numrico
Retorna um dado numrico de acordo com o valor informado em <cDtoVal>.
Exemplo:
GetDtoVal('123456')
//retorno 123456.0000
GetDtoVal('1/2/3/4/5/6') //retorno 123456.0000
GetDtoVal('fim.123456') //retorno 0.123456
GetDtoVal('teste')
//retorno 0.0
ISALPHA()
Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres alfabtico, permitindo avaliar se o string especificado comea com um caractere
alfabtico. Um caractere alfabtico consiste em qualquer letra maiscula ou minscula de A
a Z.
Sintaxe: ISALPHA ( < cString > )
Parmetros:
cString
Cadeia de caracteres a ser examinada.
Retorno:
Lgico
Retorna verdadeiro (.T.) se o primeiro caractere em <cString> for alfabtico,

caso contrrio, retorna falso (.F.).
ISDIGIT()

Tel: 11 50114895 / 50116082 / 98081988
SP
31
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de

caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um dgito
numrico entre zero e nove.
Sintaxe: ISDIGIT ( < cString > )
Parmetros:
cString
Retorno:
Lgico
Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito

entre zero e nove; caso contrrio, retorna falso (.F.).
ISLOWER()
Funo utilizada para determinar se o caractere mais esquerda uma letra minscula,
permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio
de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula.
ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.
Sintaxe: ISLOWER( < cString > )
Parmetros:
cString
Retorno:
Lgico
Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo ,

ISUPPER()
Funo utilizada para determinar se o caractere mais esquerda uma letra maiscula,
permitindo avaliar se o primeiro caractere de um string uma letra maiscula. o contrrio
de ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula.
ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.
Sintaxe: ISUPPER( < cString > )
Parmetros:
cString
Retorno:
Lgico
Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo ,


Tel: 11 50114895 / 50116082 / 98081988
SP
32
ADVPL
GUIA DE REFERNCIA
Escola conveniada
LEN()
Retorna o tamanho da string especificada no parmetro.
Sintaxe: LEN(cString)
Parmetros
cString
String que ser avaliada
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))
LOWER()
Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.
Sintaxe: LOWER(cString)
Parmetros
cString
String que ser convertida para caracteres minsculos.
Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
LTRIM()
Funo para 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 funo 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() so as funes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs
da insero de caracteres de preenchimento.
Sintaxe: LTRIM ( < cString > )

Parmetros:
cString
<cString> a cadeia de caracteres a ser copiada sem os espaos em branco

Tel: 11 50114895 / 50116082 / 98081988
SP
33
ADVPL
GUIA DE REFERNCIA
Escola conveniada
esquerda.
Retorno:
Caracter
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 ("").
MATHC()
Funo utilizada para realizar operaes matemticas com strings que contm um valor
numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao, Diviso,
Multiplicao e Exponenciao.
A funo ir retornar uma string contendo o resultado da operao matemtica, com uma
especificao de at 18 casas de preciso no numero.
Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )
Parmetros:
cNum1
cOperacao
cNum2
String contendo um valor numrico, representando o numero no qual

desejamos realizar uma operao.
Representa a string que indica a operao que desejamos realizar. Olhar na
tabela para verificar quais valores devem ser informados aqui.
String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.
Retorno:
Caracter
Retorna uma nova string contendo o resultado matemtico da operao.
OEMTOANSI()
Funo que transforma uma string no Formato OEM / MS-DOS Text para uma string ANSI
Text ( formato do Windows ).
Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de dados , os
acentos e caracteres especiais so gravados como texto OEM . Para tornar possvel a correta
visualizao destes dados em uma interface Windows , utilizamos a funo OemToAnsi() para
realizar a converso.
Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados , o texto
capturado no formato ANSI Text . Caso este texto seja utilizado para alimentar uma base de
dados a ser acessada atravs de um programa MS-DOS , devemos converter o dado para OEM
antes de grav-lo , atravs da funo AnsiToOem().
Sintaxe: OemToAnsi ( < cStringOEM > )

Parmetros:
cStringOEM
String em formato OEM - MsDos a ser convertida.

Tel: 11 50114895 / 50116082 / 98081988
SP
34
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Caracter
String convertida para ser exibida no Windows ( Formato ANSI ).
PADL() / PADR() / PADC()

Funes de tratamento de strings que inserem caracteres de preenchimento para completar
um tamanho previamente especificado em vrios formatos como data ou numricos.
PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e

esquerda.
PADL() adiciona caracteres de preenchimento esquerda.
PADR() adiciona caracteres de preenchimento direita.
Caso o tamanho de <cExp> exceda o argumento <nTamanho>, todas as funes PAD()

truncam string preenchida ao <nTamanho> especificado.
PADC(), PADL(), e PADR() so 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 utilizao exibir textos em uma tela de
tamanho fixo, para certificar-se de que o texto anterior foi completamente sobrescrito.
PADC(), PADL(), e PADR() so o contrrio das funes ALLTRIM(), LTRIM(), e LTRIM(), as quais
eliminam espaos em branco esquerda e direita de cadeias de caracteres.
Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench ] )
Parmetros
cExp
Caractere, data, ou numrico no qual sero inseridos caracteres de

preenchimento.
Tamanho da cadeia de caracteres a ser retornada.
nTamanho
cCaracPreench
Caractere a ser inserido em cExp. Caso no seja especificado, o padro

o espao em branco.
Retorno:
Caracter
Retornam o resultado de <cExp> na forma de uma cadeia de caracteres

preenchida com <cCaracPreench>, para totalizar o tamanho especificado
por <nTamanho>.
RAT()
Retorna a ltima posio de um caracter ou string dentro de outra string especificada.
Sintaxe: RAT(cCaractere, cString)

Parmetros
cCaractere
Caractere ou string que se deseja verificar
cString
String na qual ser verificada a existncia do contedo de cCaractere.

Tel: 11 50114895 / 50116082 / 98081988
SP
35
ADVPL
GUIA DE REFERNCIA
Escola conveniada
REPLICATE()
A funo Replicate() utilizada para gerar uma cadeira de caracteres repetidos a partir de um
caracter base informado, podendo a string gerada conter at 64KB. Caso seja especificado no
parmetro de itens a repetir o nmero zero, ser retornada uma string vazia.
Sintaxe: REPLICATE(cString, nCount)
Parmetros:
cString
Caracter que ser repetido
nCount
Quantidade de ocorrncias do caracter base que sero geradas na string de

destino.
Retorno:
cReplicated
String contendo as ocorrncias de repeticao geradas para o caracter

informado.
RTRIM()
Funo para 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 so 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() so as funes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres, inserindo
caracteres de preenchimento.
Sintaxe: RTRIM ( < cString > ) --> cTrimString
Parmetros:
cString
<cString> a cadeia de caracteres a ser copiada sem os espaos em branco

direita.
Retorno:
Caracter
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 ("").
SPACE()

Tel: 11 50114895 / 50116082 / 98081988
SP
36
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Funo de tratamento de caracteres utilizada para retornar uma quantidade especificada de

espaos. A utilizao desta funo tem o mesmo efeito que REPLICATE(' ', <nCont>), e
normalmente utilizada para inicializar uma varivel do tipo caractere, antes que a mesma seja
associada a um GET.
Sintaxe: SPACE ( < nCont > )
Parmetros:
nCont
A quantidade de espaos a serem retornados, sendo que o nmero mximo

65.535 (64K).
Retorno:
Caracter
Retorna uma cadeia de caracteres. Se <nCont> for zero, SPACE()retorna

uma cadeia de caracteres nula ("").
STRTOKARR()
Funo utilizada para retornar um array, de acordo com os dados passados como parmetro
para a funo. Esta funo recebe uma string <cValue> e um caracter <cToken> que
representa um separador, e para toda ocorrncia deste separador em <cValue> adicionado
um item no array.
Sintaxe: STRTOKARR ( < cValue > , < cToken > )
Parmetros:
cValue
cToken
Representa a cadeia de caracteres no qual desejamos separar de acordo com

<cToken>.
Representa o caracter que indica o separador em <cValue>.
Retorno:
Array
Array de caracteres que representa a string passada como parmetro.
Exemplo:
STRTOKARR('1;2;3;4;5', ';')
//retorna {'1','2','3','4','5'}
STRTRAN()
Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.
Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] ,
[ nCount ] )
Parmetros:
cString
Seqncia de caracteres ou campo memo a ser pesquisado.

Tel: 11 50114895 / 50116082 / 98081988
SP
37
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cSearch
Seqncia de caracteres a ser procurada em cString.
cReplace
Seqncia de caracteres que deve substituir a string cSearch. Caso no

seja especificado, as ocorrncias de cSearch em cString sero substitudas
por uma string nula ("").
nStart corresponde ao nmero seqencial da primeira ocorrncia de
cSEarch em cString a ser substituda por cReplace. Se este argumento for
omitido , o default 1 ( um ) . Caso seja passado um numero menor que
1, a funo retornar uma string em branco ("").
nCount corresponde ao nmero mximo de trocas que dever ser realizada
pela funo . Caso este argumento no seja especificado , o default
substituir todas as ocorrncias encontradas.
nStart
nCount
Retorno:
Code-Block
A funo STRTRAN retorna uma nova string, com as ocorrncias

especificadas
de
cSearch
trocadas
para
cReplace,
conforme
parametrizao.
STUFF()
Funo que permite substituir um contedo caractere em uma string j existente,
especificando a posio inicial para esta adio e o nmero de caracteres que sero
substitudos.
Sintaxe: STUFF(cString, nPosInicial, nExcluir, cAdicao)
Parmetros:
cString
nExcluir
A cadeia de caracteres destino na qual sero eliminados e inseridos

caracteres.
A posio inicial na cadeia de caracteres destino onde ocorre a
insero/eliminao.
A quantidade de caracteres a serem eliminados.
cAdicao
A cadeia de caracteres a ser inserida.
nPosInicial
Retorno:
Caracter
Retorna a nova string gerada pela funo com as modificaes.
Exemplo:
cLin := Space(100)+cEOL // Cria a string base
cCpo := PADR(SA1->A1_FILIAL,02) // Informao que ser armazenada na string
cLin := Stuff(cLin,01,02,cCpo) // Substitui o contedo de cCpo na string base
SUBSTR()
Retorna parte do contedo de uma string especificada, de acordo com a posio inicial deste
contedo na string e a quantidade de caracteres que dever ser retornada a partir daquele
ponto (inclusive).
Tel: 11 50114895 / 50116082 / 98081988
SP
38
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: SUBSTR(cString, nPosInicial, nCaracteres)

Parmetros
cString
String que se deseja verificar
nPosInicial
Posio inicial da informao que ser extrada da string
nCaracteres
Quantidade de caracteres que dever ser retornada a partir daquele ponto

(inclusive).
Exemplo:
cCampo := A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_
TRANSFORM()
Funo de converso que formata valores caractere, data, lgicos e numricos conforme um
string de mscara especificado, a qual inclui uma combinao de strings de template e funes
de picture. Ela faz o mesmo que a clusula PICTURE do comando @...SAY, sendo normalmente
utilizada para formatar dados a serem enviados tela ou impressora.
Sintaxe: TRANSFORM ( < cExp > , < cSayPicture > )
Parmetros:
cExp
cSayPictur
e
O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
Uma string de caracteres de mscara e template usado para descrever o
formato da cadeia de caracteres a ser retornada.
Retorno:
Retorna a converso de <cExp> para uma cadeia de caracteres formatada

conforme a definio em <cSayPicture>.
UPPER()
Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.
Sintaxe: UPPER(cString)
Parmetros
cString
String que ser convertida para caracteres maisculos.
Exemplo:

Tel: 11 50114895 / 50116082 / 98081988
SP
39
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
Manipulao de data / hora

CDOW()
Funo que converte uma data para uma cadeia de caracteres.
Sintaxe: CDOW( dExp )

Parmetros:
dExp
Data que ser convertida.
Retorno:
cDayWeek
Nome do dia da semana como uma cadeia de caracteres. A primeira letra

maiscula e as demais minsculas.
Exemplo:
dData := DATE() // Resultado: 09/01/90
cDiaDaSemana := CDOW(DATE()) // Resultado: Friday
cDiaDaSemana := CDOW(DATE() + 7) // Resultado: Friday
cDiaDaSemana := CDOW(CTOD("06/12/90")) // Resultado: Tuesday
A funo FG_CDOW(dExp) retorna o nome do dia da semana de acordo com

o idioma em uso pelo ERP.
CMONTH()
Funo de converso de datas que retorna uma cadeia de caracteres com o nome do ms em
ingls.
Sintaxe: CMONTH( dData )

Parmetros:
dData
Retorno:
cMonth
Retorna o nome do ms em uma cadeia de caracteres. A primeira letra do

retorno em maiscula e o restante do nome, em minsculas.
Exemplo:

Tel: 11 50114895 / 50116082 / 98081988
SP
40
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cMes
cMes
cMes
cMes
:=
:=
:=
:=
CMONTH(DATE()) // Resultado: September

CMONTH(DATE() + 45) // Resultado: October
CMONTH(CTOD("12/01/94")) // Resultado: December
SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE())) // Resultado: Sep 1
DATE()
Funo que retorna a data do atual sistema. O formato de sada controlado pelo comando
SET DATE, sendo que o formato padro mm/dd/yy.
Sintaxe: DATE()
Parmetros:
Nenhum
Retorno:
dData
Data do sistema.
Exemplo:
dData := DATE() + 30 // Resultado: 10/01/01
dData := DATE() - 30 // Resultado: 08/02/90
dData := DATE()
cMes := CMONTH(dData) // Resultado: September
DAY()
Funo de converso de datas usada para converter o valor data em um nmero inteiro que
representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR()
para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas.
Sintaxe: DAY( dData )

Parmetros:
dData
Retorno:
nDias
Se o ms do argumento dData for fevereiro, anos bissextos so

considerados. Se a data do argumento dData for 29 de fevereiro e o ano no
for bissexto, ou se o argumento dData for vazio.
Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
nDia := DAY(DATE()) // Resultado: 1
nDia := DAY(DATE()) + 1 // Resultado: 2
Tel: 11 50114895 / 50116082 / 98081988
SP
41
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nDia := DAY(CTOD("12/01/94")) // Resultado: 1

// Este exemplo mostra a funo DAY() usada em conjunto com CMONTH() e
YEAR() para formatar o valor da data:
dData := Date()
cData := CMONTH(dData) + STR(DAY(dData)) + "," + STR(YEAR(dData)) // Resultado: June
15, 2001
DOW()
Funo que converte uma data para o valor numrico que representa o dia da semana. til
quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o dia da
semana como uma cadeia de caracteres.
Sintaxe: DOW( dData )

Parmetros:
dData
Retorno:
nDia
Retorna um nmero entre zero e sete, representando o dia da semana. O

primeiro dia da semana 1 (Domingo) e o ltimo 7 (Sbado). Se a data for
vazia ou invlida, DOW() retorna zero.
Exemplo:
nDiaDaSemana := DOW(DATE()) // Resultado: 3
cDiaDaSemana := CDOW(DATE()) // Resultado: Tuesday
nDiaDaSemana := DOW(DATE() - 2) // Resultado: 1
cDiaDaSemana := CDOW(DATE() - 2) // Resultado: Sunday
DTOC()
Funo para converso de uma data para uma cadeia de caracteres formatada segundo o
padro corrente, definido pelo comando SET DATE. Se for necessria a utilizao de
formatao especial, use a funo TRANSFORM().
Em expresses de ndices de arquivo, use DTOS() no lugar de DTOC() para converter datas
para cadeia de caracteres.
Sintaxe: DTOC( dData )

Parmetros:
dData
Retorno:
cData
uma cadeia de caracteres representando o valor da data. O retorno

formatado utilizando-se o formato corrente definido pelo comando SET DATE
FORMAT. O formato padro mm/dd/yy. Para uma data nula ou invlida, o

Tel: 11 50114895 / 50116082 / 98081988
SP
42
ADVPL
GUIA DE REFERNCIA
Escola conveniada
retorno ser uma cadeia de caracteres com espaos e tamanho igual ao

formato atual.
Exemplo:
cData := DATE() // Resultado: 09/01/90
cData := DTOC(DATE()) // Resultado: 09/01/90
cData := "Today is " + DTOC(DATE()) // Resultado: Today is 09/01/90
DTOS()
Funo para converso de uma data que pode ser usada para criar expresses de ndice. O
resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia).
Sintaxe: DTOS( dData )

Parmetros:
dData
Retorno:
sData
Retorna uma cadeia de caracteres com oito byte de tamanho no formato

yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia
de caracteres com oito espaos. O valor retornado no afetado pela
formato da data corrente.
Exemplo:
cData := DATE() // Resultado: 09/01/90
cData := DTOS(DATE()) // Resultado: 19900901
nLen := LEN(DTOS(CTOD(""))) // Resultado: 8
ELAPTIME()
Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no formato
hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.
Sintaxe: ElapTime( cHoraInicial , cHoraFinal )

Parmetros:
cHoraInicial
CHoraFinal
Informe a hora inicial no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),

mm os minutos e ss os segundos
Informe a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm
os minutos e ss os segundos.
Retorno:
Caracter
A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),

mm os minutos e ss os segundos.

Tel: 11 50114895 / 50116082 / 98081988
SP
43
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
cHoraInicio := TIME() // Resultado: 10:00:00
...
<instrues>
...
cElapsed := ELAPTIME(TIME(), cHoraInicio)
MONTH()
Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que
retorna o nome do ms a partir do valor de dData.
Sintaxe: MONTH( dData )

Parmetros:
dData
Retorno:
Numrico
>=0 e <=12 Para uma data vlida.

0 Se a data for nula ou invlida
Exemplo:
nMes := MONTH(DATE()) // Resultado: 9
nMes := MONTH(DATE()) + 1 // Resultado: 10
SECONDS()
Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a hora do
sistema. Est relacionada funo TIME() que retorna a hora do sistema como uma cadeia de
caracteres no formato hh:mm:ss.
Sintaxe: SECONDS()
Parmetros:
Nenhum
Retorno:
Numrico
>=0 e <=86399 Retorna a hora do sistema em segundos. O valor

numrico representa o nmero de segundos decorridos desde a meia-noite,
baseado no relgio de 24 horas e varia de 0 a 86399.
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
44
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cHora := TIME() // Resultado: 10:00:00

cSegundos := SECONDS() // Resultado: 36000.00
//Este exemplo usa a funo SECONDS() para cronometrar o tempo decorrido:
LOCAL nStart, nElapsed
nStart:= SECONDS()
TIME()
Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada
com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a
meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos.
Sintaxe: TIME()
Parmetros:
Nenhum
Retorno:
Caracter
A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss

onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.
Exemplo:
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
YEAR()
YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR()
membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui
DAY() e MONTH() que retornam o dia e o ms como valores numricos.
Sintaxe: YEAR( dData )

Parmetros:
dData
Retorno:
Numrico
Valor numrico do ano da data especificada em dData incluindo os dgitos do

sculo. O valor retornado no afetado pelos valores especificados pelos
comandos SET DATE ou SET CENTURY.
Para uma data invlida ou nula ser retornado o valor 0.

Tel: 11 50114895 / 50116082 / 98081988
SP
45
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo 1:
dAno := YEAR(dData) // Resultado: 2001
dAno := YEAR(dData) + 11 // Resultado: 2012
Exemplo 2:
// Este exemplo cria uma funo de usurio que usa a funo YEAR() para formatar o valor da
// data:
cData := Mdy(DATE()) // Result: September 20, 1990
FUNCTION Mdy( dDate )
RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))) + "," + STR(YEAR(dDate))
Manipulao de variveis numricas

ABS()
Retorna um valor absoluto (independente do sinal) com base no valor especificado no
parmetro.
Sintaxe: ABS(nValor)
Parmetros
nValor
Valor que ser avaliado
Exemplo:
nPessoas := 20
nLugares := 18
IF nPessoas < nLugares
MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando)
ENDIF
ALEATORIO()
Gera um nmero aleatrio de acordo com a semente passada. Esta funo retorna um nmero
aleatrio menor ou igual ao primeiro parmetro informado, usando como semente o segundo
parmetro. recomendado que esta semente seja sempre o ltimo nmero aleatrio gerado
por esta funo.
Sintaxe: Aleatorio(nMax,nSeed)
Parmetros
nMax
Nmero mximo para a gerao do nmero aleatrio

Tel: 11 50114895 / 50116082 / 98081988
SP
46
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nSeed
Semente para a gerao do nmero aleatrio
Exemplo:
Funo ALEATORIO()
nSeed := 0
For i := 1 to 100
nSeed := Aleatorio(100,nSeed)
? Str(i,3)+ numero aleatorio gerado: +Str(nSeed,3)
Next i
inkey(0)
Return
INT()
Retorna a parte inteira de um valor especificado no parmetro.
Sintaxe: INT(nValor)
Parmetros
nValor
Exemplo:
STATIC FUNCTION COMPRAR(nQuantidade)
LOCAL nDinheiro := 0.30
LOCAL nPrcUnit := 0.25
IF nDinheiro >= (nQuantidade*nPrcUnit)
RETURN nQuantidade
ELSEIF nDinheiro > nPrcUnit
nQuantidade := INT(nDinheiro / nPrcUnit)
ELSE
nQuantidade := 0
ENDIF
RETURN nQuantidade
NOROUND()
Retorna um valor, truncando a parte decimal do valor especificado no parmetro de acordo
com a quantidade de casas decimais solicitadas.
Sintaxe: NOROUND(nValor, nCasas)

Parmetros
nValor

Tel: 11 50114895 / 50116082 / 98081988
SP
47
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nCasas
Nmero de casas decimais vlidas. A partir da casa decimal especificada os

valores sero desconsiderados.
Exemplo:
Funo NOROUND()
nBase := 2.985
nValor := NOROUND(nBase,2) 2.98
RANDOMIZE()
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: RANDOMIZE ( < nMinimo > , < nMaximo > )
Parmetros
nMinimo
Corresponde ao menor numero a ser gerado pela funo.
nMaximo
Corresponde ao maior nmero ( menos um ) a ser gerado pela funo.
Retorno:
Numrico
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 .
ROUND()
Retorna um valor, arredondando a parte decimal do valor especificado no parmetro de acordo
com a quantidades de casas decimais solicitadas, utilizando o critrio matemtico.
Sintaxe: ROUND(nValor, nCasas)

Parmetros
nValor
nCasas
Nmero de casas decimais vlidas. As demais casas decimais sofrero o

arredondamento matemtico, aonde:
Se nX <= 4 0, seno +1 para a casa decimal superior.

Tel: 11 50114895 / 50116082 / 98081988
SP
48
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
nBase := 2.985
nValor := ROUND(nBase,2) 2.99
Manipulao de arquivos
ADIR()
Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da
mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados.
Importante: ADir uma funo obsoleta, utilize sempre Directory().
Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora],

[ aAtributo ])
Parmetros:
cArqEspec
aNomeArq
aTamanho
aData
aHora
aAtributos
Caminho dos arquivos a serem includos na busca de informaes. Segue o

padro para especificao de arquivos, aceitando arquivos no servidor
Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso
seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ).
Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
Array Numrico. So os tamanhos dos arquivos encontrados na busca.
Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
Array de Caracteres. So os atributos dos arquivos, caso esse array seja
passado como parmetros, sero includos os arquivos com atributos de
sistema e ocultos.
Retorno:
nArquivos
Quantidade de arquivos encontrados.
Exemplo:
LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })
CGETFILE()
Funo utilizada para seleo de um arquivo ou diretrio, disponibilizando uma interface
grfica para amigvel para o usurio. Esta funo est normalmente associada ao recurso de
Tel: 11 50114895 / 50116082 / 98081988
SP
49
ADVPL
GUIA DE REFERNCIA
Escola conveniada
abrir ou salvar arquivos, permitindo para esta ltima a digitao opcional do nome do arquivo
que ser gravado.
Sintaxe: cGetFile ( ExpC1, ExpC2, ExpN1, ExpC3, ExpL1, ExpN2,ExpL2 )
Parmetros:
ExpC1
Mascara para filtro (Ex: 'Informes Protheus (*.##R) | *.##R')
ExpC2
Titilo da Janela
ExpN1
Numero da mascara default ( Ex: 1 p/ *.exe )
ExpC3
Diretrio inicial se necessrio
Expl1
.T. para mostrar boto como 'Salvar' e .F. para boto 'Abrir'
ExpN2
Mascara de bits para escolher as opes de visualizao do Objeto.
ExpL2
.T. para exibir diretrio [Servidor] e .F. para no exibir
Mscaras de bits para opes:
GETF_OVERWRITEPROMPT
Solicita confirmao para sobrescrever
GETF_MULTISELECT
Permite selecionar mltiplos arquivos
GETF_NOCHANGEDIR
No permite mudar o diretrio inicial
GETF_LOCALFLOPPY
Exibe o(s) Drive(s) de disquete da maquina local
GETF_LOCALHARD
Exibe o(s) HardDisk(s) Local(is)
GETF_NETWORKDRIVE
Exibe os drives da rede ( Mapeamentos )
GETF_SHAREWARE
No implementado
GETF_RETDIRECTORY
Retorna um diretrio
Exemplo:
cGetFile ( '*.PRW|*.CH'
GETF_LOCALFLOPPY)
'Fontes',
1,
'C:\VER507',
.F.,
GETF_LOCALHARD
Aparncia:

Tel: 11 50114895 / 50116082 / 98081988
SP
50
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Para permitir a seleo de diversos arquivos contidos em um diretrio

necessrio combinar as funes CGETFILE(), DIRECTORY() e o objeto
LISTBOX() conforme abaixo:
CGETFILE: exibe os diretrios disponveis e retorna o nome do item

selecionado.
DIRECTORY: efetua a leitura dos arquivos contidos no diretrio
retornado pela CGETFILE.
LISTBOX: Exibe uma tela de seleo de com a opo de marcao,
para que sejam selecionados os arquivos que sero processados.
Exemplo: Seleo de mltiplos arquivos com CGETFILE, DIRECTORY() e LISTBOX()
Funo Principal: SELFILE()
#include "protheus.ch"
//+--------------------------------------------------------------------+
//| Rotina | SELFILE | Autor |
| Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo para seleo de mltiplos arquivos.
|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
Tel: 11 50114895 / 50116082 / 98081988
SP
51
ADVPL
GUIA DE REFERNCIA
Escola conveniada
USER FUNCTION SELFILE()

LOCAL cDirectory := ""
LOCAL aArquivos
:= {}
LOCAL nArq
:= 0
PRIVATE aParamFile:= ARRAY(1)
IF !PARBOXFILE()
RETURN
ENDIF
// Exibe a estrutura de diretrio e permite a seleo dos arquivos que sero
processados
cDirectory := ALLTRIM(cGetFile("Arquivos de Dados|'"+aParamFile[1]+"'|",
'Importao de lanamentos', 0,'', .T., GETF_OVERWRITEPROMPT + GETF_NETWORKDRIVE
+ GETF_RETDIRECTORY,.T.))
aArquivos
:= Directory(cDirectory+"*.*")
aArquivos
:= MARKFILE(aArquivos,cDirectory,aParamFile[1],@lSelecao)
FOR nArq TO Len(aArquivos)
IF !aArquivos[nArq][1]
LOOP
ENDIF
<...processamento...>
NEXT nArq
RETURN
Funo auxiliar: PARBOXFILE()
//+--------------------------------------------------------------------+
//| Rotina | PARBOXFILE | Autor |
| Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo de uso da PARAMBOX em conjunto com CGETFILE|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION PARBOXFILE()
Local
Local
Local
Local
Local
Local
Local
Local
aParamBox := {}
cTitulo
:= "Filtros Adicionais"
aRet := {}
bOk
:= {|| .T.}
aButtons
:= {}
lCentered
:= .T.
nPosx
nPosy

Tel: 11 50114895 / 50116082 / 98081988
SP
52
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Local
Local
Local
Local
Local
cLoad := ""
lCanSave
:= .F.
lUserSave := .F.
nX
:= 0
lRet := .T.
AADD(aParamBox,{2,"Tipo de arquivo" ,2,

{"*.dbf","*.dtc"},100,"AllwaysTrue()",.T.})
lRet := ParamBox(aParamBox, cTitulo, aRet, bOk, aButtons, lCentered, nPosx,
nPosy,, cLoad, lCanSave, lUserSave)
IF ValType(aRet) == "A" .AND. Len(aRet) == Len(aParamBox)
For nX := 1 to Len(aParamBox)
If aParamBox[nX][1] == 1
aParam102[nX] := aRet[nX]
ElseIf aParamBox[nX][1] == 2 .AND. ValType(aRet[nX]) == "C"
aParam102[nX] := aRet[nX] // Tipo do arquivo
ElseIf aParamBox[nX][1] == 2 .AND. ValType(aRet[nX]) == "N"
aParam102[nX] := aParamBox[nX][4][aRet[nX]] // Tipo do arquivo
Endif
Next nX
ENDIF
RETURN lRet
Funo auxiliar: MARKFILE()

//+--------------------------------------------------------------------+
//| Rotina | MARKFILE | Autor |
| Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo para marcao de mltiplos arquivos.
|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION MARKFILE(aArquivos,cDiretorio,cDriver,lSelecao)
Local aChaveArq
:= {}
Local cTitulo
:= "Arquivos para importao: "
Local bCondicao
:= {|| .T.}
// Variveis utilizadas na seleo de categorias
Local oChkQual,lQual,oQual,cVarQ
// Carrega bitmaps
Local oOk
:= LoadBitmap( GetResources(), "LBOK")
Local oNo
:= LoadBitmap( GetResources(), "LBNO")
// Variveis utilizadas para lista de filiais
Local nx
:= 0
Local nAchou
:= 0
//+--------------------------------------------------------------------+
//| Carrega os arquivos do diretrio no array da ListBox
|
//+--------------------------------------------------------------------+
For nX := 1 to Len(aArquivos)
//+--------------------------------------------------------------------+
//| aChaveArq - Contem os arquivos que sero exibidos para seleo
|
Tel: 11 50114895 / 50116082 / 98081988
SP
53
ADVPL
GUIA DE REFERNCIA
Escola conveniada
//+--------------------------------------------------------------------+
AADD(aChaveArq,{.F.,aArquivos[nX][1],cDiretorio})
Next nX
//+--------------------------------------------------------------------+
//| Monta tela para seleo dos arquivos contidos no diretrio
|
//+--------------------------------------------------------------------+
DEFINE MSDIALOG oDlg TITLE cTitulo STYLE DS_MODALFRAME From 145,0 To 445,628;
OF oMainWnd PIXEL
oDlg:lEscClose := .F.
@ 05,15 TO 125,300 LABEL UPPER(cDriver) OF oDlg PIXEL
@ 15,20 CHECKBOX oChkQual VAR lQual PROMPT "Inverte Seleo" SIZE 50, 10;
OF oDlg PIXEL;
ON CLICK (AEval(aChaveArq, {|z| z[1] := If(z[1]==.T.,.F.,.T.)}),;
oQual:Refresh(.F.))
@ 30,20 LISTBOX oQual VAR cVarQ Fields HEADER "","Cdigo","Descrio" SIZE;
273,090 ON DBLCLICK (aChaveArq:=Troca(oQual:nAt,aChaveArq),oQual:Refresh());
NoScroll OF oDlg PIXEL
oQual:SetArray(aChaveArq)
oQual:bLine := { || {If(aChaveArq[oQual:nAt,1],oOk,oNo),;
aChaveArq[oQual:nAt,2],aChaveArq[oQual:nAt,3]}}
DEFINE SBUTTON FROM 134,240 TYPE 1 ACTION IIF(MarcaOk(aChaveArq),;
(lSelecao := .T., oDlg:End(),.T.),.F.) ENABLE OF oDlg
DEFINE SBUTTON FROM 134,270 TYPE 2 ACTION (lSelecao := .F., oDlg:End());
ENABLE OF oDlg
RETURN aChaveArq
Funo auxiliar: TROCA()

//+--------------------------------------------------------------------+
//| Rotina | TROCA
| Autor |
| Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION Troca(nIt,aArray)
aArray[nIt,1] := !aArray[nIt,1]
Return aArray
Funo auxiliar: MARCAOK()
//+--------------------------------------------------------------------+
//| Rotina | MARCAOK | Autor |
| Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION MarcaOk(aArray)
Local lRet:=.F.
Local nx:=0

Tel: 11 50114895 / 50116082 / 98081988
SP
54
ADVPL
GUIA DE REFERNCIA
Escola conveniada
// Checa marcaes efetuadas

For nx:=1 To Len(aArray)
If aArray[nx,1]
lRet:=.T.
EndIf
Next nx
// Checa se existe algum item marcado na confirmao
If !lRet
HELP("SELFILE",1,"HELP","SEL. FILE","No existem itens marcados",1,0)
EndIf
Return lRet
CPYS2T()
Funo utilizada para copiar um arquivo do servidor para o cliente (Remote), sendo que os
caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada
(lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do
uso.
Sintaxe: CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] )
Parmetros:
cOrigem
cDestino
Nome(s) dos arquivos a serem copiados, aceita apenas arquivos no servidor,

WildCards ( * e ? ) so aceitos normalmente.
Diretrio com o destino dos arquivos no Client ( Remote ).
lCompacta
Indica se a cpia deve ser feita compactando o arquivo antes do envio.
Retorno:
Lgico
lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em caso
de falha na cpia.
Exemplo:
// Copia arquivos do servidor para o remote local, compactando antes de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. )
// Copia arquivos do servidor para o remote local, sem compactar antes de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. )
CPYT2S()
Funo utilizada para copiar um arquivo do cliente (Remote) para o servidor, sendo que os
caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada
(lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do
uso.
Sintaxe: CpyT2S( cOrigem, cDestino, [ lCompacta ])
Parmetros:
cOrigem
Nomes dos arquivos a serem copiados, aceita apenas arquivos locais

( Cliente ), WildCards so aceitos normalmente.

Tel: 11 50114895 / 50116082 / 98081988
SP
55
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cDestino
Diretrio com o destino dos arquivos no remote ( Cliente ).
lCompacta
Indica se a cpia deve ser feita compactando o arquivo antes.
Retorno:
Lgico
Indica se o arquivo foi copiado para o cliente com sucesso.
Exemplo:
// Copia arquivos do cliente( remote ) para o Servidor compactando antes de transmitir
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP", .T. )
// Copia arquivos do cliente( remote ) para o Servidor sem compactar.
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" )
CURDIR()
Funo que retorna o diretrio corrente do servidor. O caminho retornado sempre relativo ao
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 caminho de rede), a funo no ir setar o novo path,
mantendo o atual .
Sintaxe: CURDIR ( [ cNovoPath ] )
Parmetros:
cNovoPath
Caminho relativo , com o novo diretrio que ser ajustado como corrente.
Retorno:
Caracter
Diretrio corrente, sem a primeira barra.
Exemplo:
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
DIRECTORY()
Tel: 11 50114895 / 50116082 / 98081988
SP
56
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Funo de tratamento de ambiente que retorna informaes a respeito dos arquivos no

diretrio corrente ou especificado. semelhante a ADIR(), porm retorna um nico vetor ao
invs de adicionar valores a uma srie de vetores existentes passados por referncia.
DIRECTORY() pode ser utilizada para realizar operaes em conjuntos de arquivos. Em
combinao com AEVAL(), voc pode definir um bloco que pode ser aplicado a todos os
arquivos que atendam a <cDirSpec> especificada.
Para tornar as referncias aos vrios elementos de cada sub-vetor de arquivo mais legveis,
fornecido o arquivo header Directry.ch, que contm os #defines para os subarray subscripts.
TABELA A: Atributos de DIRECTORY()

Atributo
Significado
Incluir arquivos ocultos
Incluir arquivos de sistema
Incluir diretrios
Procura pelo volume DOS e exclui outros arquivos
Nota: Arquivos normais so sempre includos na pesquisa, a no ser que V seja especificado.
TABELA B: Estrutura dos Subvetores de DIRECTORY()

Posio
Metasmbolo
Directry.ch
cNome
F_NAME
cTamanho
F_SIZE
dData
F_DATE
cHora
F_TIME
cAtributos
F_ATT
Sintaxe: DIRECTORY ( < cDirSpec > , [ ] )
Parmetros:
cDirSpec
cAtributos>
<cDirSpec> especifica o drive, diretrio e arquivo para a pesquisa no

diretrio. Caracteres do tipo coringa so permitidos na especificao de
arquivos. Caso <cDirSpec> seja omitido, o valor padro *.*.
O caminho especificado pode estar na estao (remote) , ou no servidor,
obedecendo s definies de Path Absoluto / Relativo de acesso.
<cAtributos> especifica que arquivos com atributos especiais devem ser
includos na informao retornada. <cAtributos> consiste em uma cadeia de
caracteres que contm um ou mais dos seguintes caracteres, contidos na
tabela adicional A , especificada anteriormente.
Retorno:
Array
DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor

contm informaes sobre cada arquivo que atenda a <cDirSpec>.Veja
maiores detalhes na Tabela B, discriminada anteriormente.

Tel: 11 50114895 / 50116082 / 98081988
SP
57
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
#INCLUDE "Directry.ch"
aDirectory := DIRECTORY("*.*","D")
AEVAL( aDirectory, {|aFile| CONOUT(aFile[F_NAME])} )
DIRREMOVE()
Funo que 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 comece com \ ), ou a partir do diretrio corrente (caso o path no seja iniciado com \ ).
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.
Sintaxe: DIRREMOVE ( < cDiretorio > )
Parmetros:
cDiretorio
Nome do diretrio a ser removido.
Retorno:
Lgico
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().
Exemplo:
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
DISKSPACE()
Funo de ambiente que determina quantos bytes esto disponveis em uma determinada
unidade de disco. Esta funo obtm a informao sempre relativa estao onde est sendo
Tel: 11 50114895 / 50116082 / 98081988
SP
58
ADVPL
GUIA DE REFERNCIA
Escola conveniada
executado o Protheus Remote. Atravs do parmetro nDrive , selecionamos qual a unidade de

disco que desejamos obter a informao do espao livre , onde:
0
1
2
3
4
:
:
:
:
:
Unidade de disco atual da estao (DEFAULT).

Drive A: da estao remota.
Drive B: da estao remota.
Drive C: da estao remota.
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
Sintaxe: DISKSPACE ( [ nDrive ] )
Parmetros:
nDrive
Nmero do drive, onde 0 o espao na unidade de disco corrente, e 1 o

drive A: do cliente, 2 o drive B: do cliente, etc.
Retorno:
Numrico
Nmero de bytes disponveis no disco informado como parmetro.
Exemplo:
nBytesLocal := DISKSPACE( ) // Retorna o espao disponvel na unidade de disco local
IF nBytesLocal < 1048576
MsgStop('Unidade de Disco local possui menos de 1 MB livre.')
Else
MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes livres.')
Endif
nBytes_A := DISKSPACE( 1 ) // Retorna o espao disponvel no drive A: local ( remote ).
If nBytes_A == -1
MsgStop('Unidade A: no est disponvel ou no h disco no Drive')
ElseIf nBytes_A < 8192
MsgStop('No h espao disponvel no disco. Substitua o disco na Unidade A:')
Else
MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes livres.')
Endif
EXISTDIR()
Funo utilizada para determinar se um path de diretrio existe e valido.
Sintaxe: EXISTDIR (< cPath >)
Parmetros:
cPath
String contendo o diretrio que ser verificado, caso seja feita uma

Tel: 11 50114895 / 50116082 / 98081988
SP
59
ADVPL
GUIA DE REFERNCIA
Escola conveniada
verificao a partir do server, devemos informar a partir do rootPath do

Protheus, caso contrrio devemos passar o path completo do diretrio.
Retorno:
Lgico
Retorna se verdadeiro(.T.) caso o diretrio solicitado exista, falso(.F.) caso

contrrio.
Exemplo 1: No server a partir do rootPath

lRet := ExistDir('\teste')
Exemplo 2: No client, passando o FullPath
lRet := ExistDir('c:\APO')
FCLOSE()
Funo 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 operao falhe,
FCLOSE() retorna falso (.F.). FERROR() pode ento ser usado para determinar a razo 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.
Nota: Esta funo 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.
Sintaxe: FCLOSE ( < nHandle > )
Parmetros:
nHandle
Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().
Retorno:
Lgico
Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo

escritos; do contrrio, retorna verdadeiro (.T.).
Exemplo:
#include "Fileio.ch"
nHandle := FCREATE("Testfile", FC_NORMAL)
If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf

Tel: 11 50114895 / 50116082 / 98081988
SP
60
ADVPL
GUIA DE REFERNCIA
Escola conveniada
FCREATE()
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
Atributos definidos no include FileIO.ch

Constante
Valor
Descrio
FC_NORMAL
Criao normal do Arquivo (default/padro).
FC_READONLY
Cria o arquivo protegido para gravao.
FC_HIDDEN
Cria o arquivo como oculto.
FC_SYSTEM
Cria o arquivo como sistema.
Caso desejemos especificar mais de um atributo , basta som-los . Por exemplo , para criar
um arquivo protegido contra gravao e escondido , passamos como atributo FC_READONLY +
FC_HIDDEN.
.
Nota: Caso o arquivo j exista , o contedo do mesmo ser ELIMINADO , e seu tamanho ser
truncado para 0 ( ZERO ) bytes.
Sintaxe: FCREATE ( < cArquivo > , [ nAtributo ] )
Parmetros:
cArquivo
nAtributo
Nome do arquivo a ser criado , podendo ser especificado um path absoluto

ou relativo , para criar arquivos no ambiente local ( Remote ) ou no Servidor,
respectivamente .
Atributos do arquivo a ser criado (Vide Tabela de atributos abaixo). Caso no
especificado, o DEFAULT FC_NORMAL.
Retorno:
Numrico
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 ocorrncia atravs da funo FERROR() .
FERASE()
Funo utilizada para 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 sendo permitido a
utilizao de caracteres coringa (wildcards).
Sintaxe: FERASE ( < cArquivo > )
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
61
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cArquivo
Nome do arquivo a ser apagado . Pode ser especificado um path absoluto ou

relativo , para apagar arquivos na estao local ( Remote ) ou no Servidor,
respectivamente.
Retorno:
Numrico
A funo retornar 0 caso o arquivo seja apagado com sucesso , e -1 caso

no seja possvel apagar o arquivo. Caso a funo retorne -1, possvel
obter maiores detalhes da ocorrncia atravs da funo FERROR().
Exemplo:
#include 'DIRECTRY.CH'
aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })
// Este exemplo apaga um arquivo no cliente ( Remote ) , informando o status da operao
IF FERASE("C:\ListaTXT.tmp") == -1
MsgStop('Falha na deleo do Arquivo ( FError'+str(ferror(),4)+ ')')
Else
MsgStop('Arquivo deletado com sucesso.')
ENDIF
FILE()
Funo que verifica se existe um arquivo ou um padro de arquivos, no diretrio. Podem ser
especificados caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( a partir do
RootPath do Protheus Server) , sendo os caracteres * e ? ( wildcards) aceitos.
Sintaxe: FILE ( < cArquivo > )
Parmetros:
cArquivo
Nome do arquivo , podendo ser especificado um path (caminho) . Caminhos

locais (Remote) ou caminhos de servidor so aceitos , bem como wildcards
(Caracteres * e ? ).
Retorno:
Lgico
O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no

exista no path especificado , a funo retorna .F.
Exemplo:
//Verifica no diretrio corrente do servidor se existe o arquivo teste.dbf
FILE("teste.dbf")
// Verifica no diretrio Sigaadv do servidor se existe o arquivo teste.dbf
FILE("\SIGAADV\TESTE.dbf")
// Verifica no diretrio Temp do cliente (Remote) se existe o arquivo teste.dbf
Tel: 11 50114895 / 50116082 / 98081988
SP
62
ADVPL
GUIA DE REFERNCIA
Escola conveniada
FILE("C:\TEMP\TESTE.dbf")
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 ).
FILENOEXT()
Funo que retorna o nome de um arquivo contido em uma string, ignorando a extenso.
Sintaxe: FileNoExt( cString )
Parmetros
cString
String contendo o nome do arquivo.
Exemplo:
Local cString := '\SIGAADV\ARQZZZ.DBF'
cString := FileNoExt( cString )
// Retorno \SIGAADV\ARQZZZ
FOPEN()
Funo 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 no exista, FOPEN() retorna -1 e FERROR()
retorna 2 para indicar que o arquivo no 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 funes 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.
Nota: Esta funo 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.
FOPEN procura o arquivo no diretrio corrente e nos diretrios configurados
na varivel de pesquisa do Sistema Operacional, a no ser que um path seja
declarado explicitamente como parte do argumento <cArq>.
Por serem executadas em um ambiente cliente-servidor, as funes de
tratamento de arquivos podem trabalhar em arquivos localizados no cliente
(estao) ou no servidor. O ADVPL identifica o local onde o arquivo ser
manipulado atravs da existncia ou no da letra do drive no nome do
arquivo passado em <cArq>. Ou seja, se o arquivo for especificado com a
Tel: 11 50114895 / 50116082 / 98081988
SP
63
ADVPL
GUIA DE REFERNCIA
Escola conveniada
letra do drive, ser aberto na estao. Caso contrrio, ser aberto no

servidor com o diretrio configurado como rootpath sendo o diretrio raiz
para localizao do arquivo.
Sintaxe: FOPEN ( < cArq > , [ nModo ] )
Parmetros:
cArq
Nome do arquivo a ser aberto que inclui o path caso haja um.
nModo
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 padro
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:
Numrico
FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso

ocorra um erro, FOPEN() retorna -1.
Exemplo:
#include 'fileio.ch'
...
nH := fopen('\sigaadv\error.log' , FO_READWRITE + FO_SHARED )
If nH == -1
MsgStop('Erro de abertura : FERROR '+str(ferror(),4))
Else
MsgStop('Arquivo aberto com sucesso.')
...
fclose(nH)
Endif
...
Tabela A: Modos de acesso a arquivos binrios
Modo
Constate(fileio.ch)
Operao
FO_READ
Aberto para leitura (padro assumido)
FO_WRITE
Aberto para gravao
FO_READWRITE
Aberto para leitura e gravao
Tabela B: Modos de acesso de compartilhamento a arquivos binrios
Modo
0
Constate(fileio.ch)
Operao
FO_COMPAT
Modo de Compatibilidade (Default)
16
FO_EXCLUSIVE
Acesso total exclusivo
32
FO_DENYWRITE
Acesso bloqueando a gravao de outros

Tel: 11 50114895 / 50116082 / 98081988
SP
64
ADVPL
GUIA DE REFERNCIA
Escola conveniada
processos ao arquivo.
48
FO_DENYREAD
64
FO_DENYNONE
Acesso bloqueando a leitura de outros

processos ao arquivo.
Acesso compartilhado. Permite a leitura e
gravao por outros.
FREAD()
Funo que realiza a leitura dos 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.) e l a partir
da posio atual do ponteiro atual do arquivo , que pode ser ajustado ou modificado pelas
funes FSEEK() , FWRITE() ou FREADSTR().
A varivel String a ser utilizada como buffer de leitura deve ser sempre pr-alocado e passado
como referncia. Caso contrrio, os dados no podero ser retornados.
Sintaxe: FREAD ( < nHandle > , < cBuffer > , < nQtdBytes > )
Parmetros:
nHandle
cBuffer
nQtdBytes
o manipulador (Handle) retornado pelas funes FOPEN(),

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.
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 arquivo a partir
posicionamento do ponteiro atual.
Retorno:
Numrico
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.
FREADSTR ()
Funo que realiza a leitura de 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: FREADSTR ( < nHandle > , < nQtdBytes > )
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
65
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nHandle
o manipulador retornado pelas funes FOPEN(),

FCREATE(), FOPENPORT().
Nmero mximo de bytes que devem ser lidos.
nQtdBytes
Retorno:
Caracter
Retorna uma string contendo os caracteres

lidos.
FRENAME()
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 fRename() atravs de um JOB. Caso isto ocorra, a
funo retornar -1 , e fError() retornar tambm -1.
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.
Sintaxe: FRENAME ( < cOldFile > , < cNewFile > )
Parmetros:
cOldFile
cNewFile
Nome do arquivo ser renomeado, aceita caminhos do servidor e caminhos

do cliente. Caso no seja especificado nenhuma unidade de disco e path,
considerado o path atual no servidor.
Novo nome do arquivo, aceita tambm caminho do servidor, e caminho do
cliente.
Retorno:
Numrico
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.
FSEEK()
Funo que 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.

Tel: 11 50114895 / 50116082 / 98081988
SP
66
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Origem
Constate(fileio.ch)
Operao
FS_SET
Ajusta a partir do inicio do arquivo. (Default)
FS_RELATIVE
Ajuste relativo a posio atual do arquivo.
FS_END
Ajuste a partir do final do arquivo.
Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] )
Parmetros:
nHandle
Manipulador obtido atravs das funes FCREATE,FOPEN.
nOffSet
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 partir do parmetro passado em nOrigem.
Indica a partir de qual posio do arquivo, o nOffset ser considerado.
nOrigem
Retorno:
Numrico
FSEEK() retorna a nova posio do ponteiro de arquivo com relao ao incio

do arquivo (posio 0) na forma de um valor numrico inteiro. Este valor no
leva em conta a posio original do ponteiro de arquivos antes da execuo
da funo FSEEK().
FT_FEOF()
Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE() estiver
posicionado no final do arquivo, similar funo EOF() utilizada para arquivos de dados.
Sintaxe: FT_FEOF( )
Parmetros:
Nenhum
Retorno:
Lgico
Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso
contrrio.
FT_FGOTO()
Funo utilizada para mover o ponteiro, que indica a leitura do arquivo texto, para a posio
absoluta especificada pelo argumento <nPos>.
Sintaxe: FT_FGOTO ( < nPos > )
Parmetros:
nPos
Indica a posio que ser colocado o ponteiro para leitura dos dados no

Tel: 11 50114895 / 50116082 / 98081988
SP
67
ADVPL
GUIA DE REFERNCIA
Escola conveniada
arquivo.
Retorno:
Nenhum
FT_FGOTOP()
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_FGOTO ( < nPos > )
Parmetros:
nPos
Indica a posio que ser colocado o ponteiro para leitura dos dados no
arquivo.
Retorno:
Nenhum
FT_FLASTREC()
Funo que retorna o nmero total de linhas do arquivo texto aberto pela FT_FUse. As linhas
so delimitadas pela seqncia de caracteres CRLF o LF.
Verifique maiores informaes sobre formato do arquivo e tamanho
mximo da linha de texto na funo FT_FREADLN().
Sintaxe: FT_FLASTREC( )
Parmetros:
Nenhum
Retorno:
Numrico
Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja

vazio, ou no exista arquivo aberto, a funo retornar 0 (zero).
Exemplo:
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
Tel: 11 50114895 / 50116082 / 98081988
SP
68
ADVPL
GUIA DE REFERNCIA
Escola conveniada
FT_FUse() // Fecha o arquivo

FT_FREADLN()
Funo que retorna uma linha de texto do arquivo aberto pela FT_FUse. As linhas so
delimitadas pela seqncia de caracteres CRLF ( chr(13) + chr(10) ) , ou apenas LF ( chr(10 ),
e o tamanho mximo de cada linha 1022 bytes.
A utilizao desta funo no altera a posio do ponteiro para leitura dos
dados, o ponteiro do arquivo no movido. A movimentao do ponteiro
realizada atravs da funo FT_FSKIP()
O limite de 1022 bytes por linha inclui os caracteres delimitadores de final de
linha. Deste modo, quando utilizados os separadores CRLF, isto nos deixa
1020 bytes de texto, e utilizando LF, 1021 bytes. A tentativa de leitura de
arquivos com linhas de texto maiores do que os valores especificados acima
resultar na leitura dos 1023 primeiros bytes da linha, e incorreta
identificao das quebras de linha posteriores.
As funes FT_F* foram projetadas para ler arquivos com contedo texto
apenas. A utilizao das mesmas em arquivos binrios pode gerar
comportamentos inesperados na movimentao do ponteiro de leitura do
arquivo, e incorretas identificaes nos separadores de final de linha.
Release: Quando utilizado um Protheus Server, com build superior a

7.00.050713P, a funo FT_FREADLN() tambm capaz de ler arquivos texto
/ ASCII, que utilizam tambm o caractere LF ( chr(10) ) como separador de
linha.
Sintaxe: FT_FREADLN( )
Parmetros:
Nenhum
Retorno:
Caracter
Retorna a linha inteira na qual est posicionado o ponteiro para leitura de

dados.
FT_FRECNO()
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_FRECNO ( )
Parmetros:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
69
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Caracter
Retorna a posio corrente do ponteiro do arquivo texto.
FT_FSKIP()
Funo que move o ponteiro do arquivo texto aberto pela FT_FUSE() para a prxima linha,
similar ao DBSKIP() usado para arquivos de dados.
Sintaxe: FT_FSKIP ( [ nLinhas ] )

Parmetros:
nLinhas
nLinhas corresponde ao nmero de linhas do arquivo TXT ref. movimentao

do ponteiro de leitura do arquivo.
Retorno
Nenhum
FT_FUSE()
Funo que abre ou fecha um arquivo texto para uso das funes FT_F*. As funes FT_F* so
usadas para ler arquivos texto, onde as linhas so delimitadas pela seqncia 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.
Verifique maiores informaes sobre formato do arquivo e tamanho
mximo da linha de texto na funo FT_FREADLN().
Sintaxe: FT_FUSE ( [ cTXTFile ] )

Parmetros:
cTXTFile
Corresponde ao nome do arquivo TXT a ser aberto. Caso o nome no seja

passado, e j exista um arquivo aberto. o mesmo fechado.
Retorno:
Numrico
A funo retorna o Handle de controle do arquivo. Em caso de falha de

abertura, a funo retornar -1
FWRITE()
Funo que permite a escrita em todo ou em parte do contedo do buffer , limitando a
quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da posio
corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes
escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou criar
um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou enviados os
dados do buffer informado. Por tratar-se de uma funo de manipulao de contedo binrio ,
so suportados na String cBuffer todos os caracteres da tabela ASCII , inclusive caracteres de
controle ( ASC 0 , ASC 12 , ASC 128 , etc.).
Tel: 11 50114895 / 50116082 / 98081988
SP
70
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Caso acontea alguma falha na gravao , a funo retornar um nmero menor que o
nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro
especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do ponteiro ,
que pode ser ajustado atravs das funes FSEEK() , FREAD() ou FREADSTR().
Sintaxe: FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] )
Parmetros:
nHandle
cBuffer
nQtdBytes
o manipulador de arquivo ou device retornado pelas funes FOPEN(),

FCREATE(), ou FOPENPORT().
<cBuffer> a cadeia de caracteres a ser escrita no arquivo especificado. O
tamanho desta varivel deve ser maior ou igual ao tamanho informado em
nQtdBytes (caso seja informado o tamanho).
<nQtdBytes> indica a quantidade de bytes a serem escritos a partir da
posio corrente do ponteiro de arquivos. Caso seja omitido, todo o contedo
de <cBuffer> escrito.
Retorno:
Numrico
FWRITE() retorna a quantidade de bytes escritos na forma de um valor

numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
operao 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.
Exemplo:
#INCLUDE "FILEIO.CH"
#DEFINE F_BLOCK 1024 // Define o bloco de Bytes a serem lidos / gravados por vez
User Function TestCopy()
Local cBuffer := SPACE(F_BLOCK)
Local nHOrigem , nHDestino
Local nBytesLidos , nBytesFalta , nTamArquivo
Local nBytesLer , nBytesSalvo
Local lCopiaOk := .T.
// Abre o arquivo de Origem
nHOrigem := FOPEN("ORIGEM.TXT", FO_READ)
// Testa a abertura do Arquivo
If nHOrigem == -1
MsgStop('Erro ao abrir origem. Ferror = '+str(ferror(),4),'Erro')
Return .F.
Endif
// Determina o tamanho do arquivo de origem
nTamArquivo := Fseek(nHOrigem,0,2)
Tel: 11 50114895 / 50116082 / 98081988
SP
71
ADVPL
GUIA DE REFERNCIA
Escola conveniada
// Move o ponteiro do arquivo de origem para o inicio do arquivo

Fseek(nHOrigem,0)
// Cria o arquivo de destino
nHDestino := FCREATE("DESTINO.TXT", FC_NORMAL)
// Testa a criao do arquivo de destino
If nHDestino == -1
MsgStop('Erro ao criar destino. Ferror = '+str(ferror(),4),'Erro')
FCLOSE(nHOrigem) // Fecha o arquivo de Origem
Return .F.
Endif
// Define que a quantidade que falta copiar o prprio tamanho do Arquivo
nBytesFalta := nTamArquivo
// Enquanto houver dados a serem copiados
While nBytesFalta > 0
// Determina quantidade de dados a serem lidos
nBytesLer
:= Min(nBytesFalta , F_BLOCK )
// l os dados do Arquivo
nBytesLidos := FREAD(nHOrigem, @cBuffer, nBytesLer )
// Determina se no houve falha na leitura
If nBytesLidos < nBytesLer
MsgStop(
"Erro de Leitura da Origem. "+;
Str(nBytesLer,8,2)+" bytes a LER."+;
Str(nBytesLidos,8,2)+" bytes Lidos."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
Exit
Endif
// Salva os dados lidos no arquivo de destino
nBytesSalvo := FWRITE(nHDestino, cBuffer,nBytesLer)
// Determina se no houve falha na gravao
If nBytesSalvo < nBytesLer
MsgStop("Erro de gravao do Destino. "+;
Str(nBytesLer,8,2)+" bytes a SALVAR."+;
Str(nBytesSalvo,8,2)+" bytes gravados."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
EXIT
Endif
// Elimina do Total do Arquivo a quantidade de bytes copiados
nBytesFalta -= nBytesLer
Enddo
// Fecha os arquivos de origem e destino
FCLOSE(nHOrigem)
FCLOSE(nHDestino)
Tel: 11 50114895 / 50116082 / 98081988
SP
72
ADVPL
GUIA DE REFERNCIA
Escola conveniada
If lCopiaOk
MsgStop('Cpia de Arquivos finalizada com sucesso. '+;
str(nTamArquivo,12,0)+' bytes copiados.','Final')
Else
MsgStop( 'Falha na Cpia. Arquivo de Destino incompleto. '+;
'Do total de '+str(nTamArquivo,12,0)+' bytes, faltaram
'+str(nBytesFalta,12,0)+' bytes.','Final')
Endif
Return
MSCOPYFILE()
Funo que executa a cpia binria de um arquivo para o destino especificado.
Sintaxe: MSCOPYFILE( cArqOrig, cArqDest )
Parmetros:
cArqOrig
Nome do arquivo origem e a extenso.
cArqDest
Nome do arquivo destino e a extenso.
Retorno:
Lgico
Se a copia for realizada com sucesso a funo retornar verdadeiro (.T.).
Exemplo:
Local cArqOrig := 'ARQ00001.DBF'
Local cArqDest := 'ARQ00002.XXX'
If MsCopyFile( cArqOrig, cArqDest )
APMsgInfo('Copia realizada com sucesso!')
EndIf
MSCOPYTO()
Funo que realiza a cpia dos registros de uma base de dados para outra, criando o arquivo
destino de acordo com a estrutura da base de dados origem.
Sintaxe: MSCOPYTO( [cArqOrig], cArqDest )
Parmetros:
cArqOrig
cArqDest
Nome do arquivo origem e a extenso se o ambiente for Top o parmetro

passar a ser obrigatrio.
Nome do arquivo destino e a extenso.
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
73
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Lgico
Se a copia for realizada com sucesso a funo retornar verdadeiro (.T.).
Exemplo:
Local cArqDest := 'SX2ZZZ.DBF'
DbSelectArea('SX2')
If MsCopyTo( , cArqDest )
APMsgInfo('Copia realizada com sucesso!')
Else
APMsgInfo('Problemas ao copiar o arquivo SX2!')
EndIf
MSCREATE()
Funo que cria um arquivo (tabela) de acordo com a estrutura informada no parmetro
aStruct. Se o parmetro cDriver no for informado o RDD corrente ser assumido como
padro. Para criao de tabelas no TopConnect necessrio estar conectado ao banco e o
environment do protheus ser TOP.
aStruct: array contendo a estrutura da tabela aonde:
1 - caracter, nome do campo;
2 - caracter, tipo do campo;
3 - numrico, tamanho do campo;
4 - numrico, decimais.
Sintaxe: MsCreate( cArquivo, aStru ,[cDriver] )
Parmetros:
cArquivo
Nome do arquivo.
aStruct
Estrutura do arquivo.
cDriver
RDD do arquivo.
Retorno:
Lgico
Indica se a operao foi executada com sucesso.
Exemplo:
Local cTarget := '\sigaadv\'
Local aStrut
aStrut := { { 'Campo', 'C', 40, 0 } }
If MsCreate( cTarget+'ARQ1001', aStrut )
APMsgInfo('Criado com sucesso!')
Else
APMsgInfo('Problemas ao criar o arquivo!')
EndIf

Tel: 11 50114895 / 50116082 / 98081988
SP
74
ADVPL
GUIA DE REFERNCIA
Escola conveniada
MSERASE()
Funo utilizada para deletar fisicamente o arquivo especificado.
Sintaxe: MsErase( cArquivo, [cIndice], [cDriver] )
Parmetros:
cArquivo
Nome do arquivo e a extenso.
cIndice
Nome do arquivo de ndice e a extenso.
cDriver
RDD do arquivo, se no for informado assumir o RDD corrente.
Retorno:
Lgico
Indica se a operao foi executada com sucesso.
Exemplo:
Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If MsErase( cArquivo, cIndice )
APMsgInfo( 'Arquivo deletado com sucesso!' )
Else
APMsgInfo( 'Problemas ao deletar arquivo!' )
EndIf
MSRENAME()
Funo que verifica a existncia do arquivo especificado.
Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] )
Parmetros:
cArquivo
Nome do arquivo e a extenso.
cIndice
Nome do arquivo de ndice e a extenso.
cDriver
RDD do arquivo, se no for informado assumir o RDD corrente.
Retorno:
Lgico
Indica se o arquivo especificado existe.
Exemplo:
Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If !MsFile ( cArquivo, cIndice )
Tel: 11 50114895 / 50116082 / 98081988
SP
75
ADVPL
GUIA DE REFERNCIA
Escola conveniada
EndIf
APMsgInfo( 'Arquivo no encontrado!' )
RETFILENAME()
Funo que retorna o nome de um arquivo contido em uma string, ignorando o caminho e a
extenso.
Sintaxe: RetFileName( cArquivo )
Parmetros:
cArquivo
String contendo o nome do arquivo
Retorno:
Caracter
Nome do arquivo contido na string cArquivo sem o caminho e a extenso.
Exemplo:
Local cArquivo := '\SIGAADV\ARQZZZ.DBF'
cArquivo := RetFileName( cArquivo )
// retorno ARQZZZ
Manipulao de arquivos e ndices temporrios

CRIATRAB()
Funo que cria um arquivo de trabalho com uma estrutura especificada, sendo que:
Caso o parmetro lDbf seja definido como .T., a funo criar um arquivo DBF com este
nome e a estrutura definida em aArray.
Caso o parmetro lDbf seja definido como .F., a funo no criar arquivo de nenhum
tipo, apenas fornecer um nome vlido.
Sintaxe: CriaTrab(aArray,lDbf)
Parmetros:
aArray
lDbf
Array multidimensional contendo a estrutura de campos da tabela que ser

criada no formato: {Nome, Tipo, Tamanho, Decimal}
Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )
Retorno:
Caracter
Nome do Arquivo gerado pela funo.
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
76
ADVPL
GUIA DE REFERNCIA
Escola conveniada
// Com lDbf = .F.

cArq := CriaTrab(NIL, .F.)
cIndice := C9_AGREG++IndexKey()
Index on &cIndice To &cArq
// Com lDbf = .T.
aStru := {}
AADD(aStru,{ MARK , C, 1, 0})
AADD(aStru,{ AGLUT , C, 10, 0})
AADD(aStru,{ NUMOP , C, 10, 0})
AADD(aStru,{ PRODUTO, C, 15, 0})
AADD(aStru,{ QUANT , N, 16, 4})
AADD(aStru,{ ENTREGA, D, 8, 0})
AADD(aStru,{ ENTRAJU, D, 8, 0})
AADD(aStru,{ ORDEM , N, 4, 0})
AADD(aStru,{ GERADO , C, 1, 0})
cArqTrab := CriaTrab(aStru, .T.)
USE &cArqTrab ALIAS TRB NEW
Na criao de ndices de trabalho temporrios utilizada a sintaxe:

CriaTrab(Nil, .F.)
Manipulao de bases de dados

ALIAS()
Funo de banco de dados utilizada para determinar o alias da rea de trabalho especificada.
Alias o nome atribuido a uma rea de trabalho quando um arquivo de banco de dados est
em uso. O nome real atribuido o nome do arquivo de banco de dados, ou um nome que foi
explicitamente
atribuido
atravs
da
clusula
ALIAS
do
comando
USE.
A funo ALIAS() o inverso da funao SELECT() pois retorna o alias atravs do nmero da
rea de trabalho, enquanto SELECT() retorna o nmero da rea de trabalho atravs do alias.
Sintaxe: ALIAS ( [ nAreaTrabalho ] )
Parmetros:
nAreaTrabalho
<nAreaTrabalho> o nmero da rea de trabalho a ser verificada.
Retorno:
Caracter
Retorna o alias da rea de trabalho especificada na forma de uma cadeia

de caracteres, em letra maiscula. Caso <nAreaTrabalho> nao seja
especificada, retornado o alias da rea de trabalho corrente. Se nao
houver nenhum arquivo de banco de dados em USo na rea de trabalho
especificada, ALIAS() retorna uma cadeia de caracteres nula ("").

Tel: 11 50114895 / 50116082 / 98081988
SP
77
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
cAlias := alias()
IF empty(cAlias)
alert('No h Area em uso')
Else
alert(Area em uso atual : '+cAlias)
Endif
BOF() / EOF()
As funes BOF() e EOF() so utilizadas para determinar se o ponteiro de leitura do arquivo
encontra-se no comeo ou no final do mesmo conforme abaixo:
BOF() uma funo de tratamento de banco de dados utilizada para

condio de limite de inicial do arquivo quando o ponteiro de registros est
para trs em um arquivo de banco de dados.
EOF() uma funo de tratamento de banco de dados utilizada para
condio de limite de final de arquivo quando o ponteiro de registros est
para frente em um arquivo de banco de dados.
testar uma
se movendo
testar uma
se movendo
Normalmente utilizada a condio EOF() como parte do argumento <lCondicao> de

uma construao DO WHILE que processa registros sequencialmente em um arquivo de
banco de dados. Neste caso <lCondicao> incluiria um teste para .NOT. EOF(), forando
o lao DO WHILE a terminar quando EOF() retornar verdadeiro (.T.)
Sintaxe: BOF() / EOF()
Parmetros:
Nenhum
Retorno:
Lgico
Lgico
Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de

registros para alm do primeiro registro lgico em um arquivo de banco de
dados, do contrrio, ela retorna falso (.F.).
Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de
registros para alm do ltimo registro lgico em um arquivo de banco de
dados, do contrrio, ela retorna falso (.F.). Caso nao haja nenhum arquivo de
banco de dados aberto na rea de trabalho corrente, EOF() retorna falso
(.F.). Se o arquivo de banco de dados corrente no possui registros, EOF()
retorna verdadeiro (.T.).

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

Tel: 11 50114895 / 50116082 / 98081988
SP
79
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED

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

delimitada diferenciada, obtida atravs do comando COPY TO (...) DELIMITED
WITH BLANK . No Protheus este formato no suportado. Caso utilize-se este
comando com a sintaxe acima, o arquivo ASCII gerado ser delimitado,
utilizando-se a sequncia de caracteres 'BLANK' como delimitadora de campos
Caractere.
Sintaxe:
COPY [ FIELDS <campo,...> ] TO cFile [cEscopo] [ WHILE <lCondicao> ]

[ FOR <lCondicao> ] [ SDF | DELIMITED [WITH <cDelimiter>] ]
[ VIA <cDriver> ]
Parmetros:
FIELDS <campo,...>
TO cFile
cEscopo
FIELDS <campo,...> especifica um ou mais campos, separados por

vrgula, a serem copiados para a tabela de destino. Caso no especificado
este parmetro, sero copiados todos os campos da tabela de origem.
TO <cFile> especifica o nome do arquivo de destino. O nome do arquivo
de destimno pode ser especificado de forma literal direta, ou como uma
expresso Advpl, entre parnteses.
Caso sejam especificadas as clusulas SDF ou DELIMITED, gerado um
arquivo ASCII, com extenso .txt por default.
<cEscopo> define a poro de dados da tabela atual a ser coipiada. Por
default, so copiados todos os registros (ALL). Os escopos possveis de
uso so:
ALL - Copia todos os registros.
REST - Copia, a partir do registro atualmente posicionado, at o final da
tabela.
NEXT <n> - Copia apenas <n> registros, iniciando a partir do registro
atualmente posicionado.

Tel: 11 50114895 / 50116082 / 98081988
SP
80
ADVPL
GUIA DE REFERNCIA
Escola conveniada
WHILE <lCondicao>
FOR <lCondicao>
[SDF|DELIMITED]
OBSERVAO : Vale a pena lembrar que o escopo sensvel tambm s

demais condies de filtro ( WHILE / FOR ).
WHILE <lCondicao> permite especificar uma condio para realizao da
cpia, a partir do registro atual, executada antes de inserir cada registro
na tabela de destino, sendo realizada a operao de cpia enquanto esta
condio for verdadeira.
FOR <lCondicao> especifica uma condio para cpia de registros,
executada antes de inserir um registro na tabela de destino, sendo a
operao realizada apenas se lCondicao ser verdadeira ( .T. )
[ SDF | DELIMITED [WITH <xcDelimiter>] ]
SDF especifica que o tipo de arquivo de destino gerado um arquivo no
formato "System Data Format" ASCII, onde registros e campos possuiem
tamanho fixo no arquivo de destino.
DELIMITED especifica que o arquivo ASCII de destino ser no formato
delimitado, onde os campos do tipo Caractere so delimitados entre aspas
duplas ( delimitador Default ). Registros e campos tm tamanho varivel
no arquivo ASCII.
DELIMITED WITH <xcDelimiter> permite especificar um novo caractere,
ou sequncia de caracteres, a ser utilizada como delimitador, ao invs do
default ( aspas duplas ). O caractere delimitador pode ser escrito de
forma literal, ou como uma expresso entre parnteses.
VIA <cDriver>
Nas Tabelas complementares A e B, na documentao do comando, so

detalhadas as especificaes dos formatos SDF e DELIMITED.
VIA <xcDriver> permite especificar o driver utilizado para criar a tabela
de destino dos dados a serem copiados.
O Driver deve ser especificado como uma expresso caractere. Caso
especificado como um valor literal direto, o mesmo deve estar entre
aspas.
Retorno:
Nenhum
COPY STRUCTURE()
O comando COPY STRUCTURE 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 ).
A Linguagem Advpl, antes do Protheus, suportava a parametrizao de uma
lista de campos da tabela atual, para compor a estrutura da tabela de destino,
atravs da clusula FIELDS <campo,...>. Esta opo no suportada no
Protheus. Caso seja utilizada, o programa ser abortado com a ocorrncia de
erro fatal : 'DBCopyStruct - Parameter <Fields> not supported in
Protheus'
Sintaxe:
COPY STRUCTURE TO <xcDataBase>

Tel: 11 50114895 / 50116082 / 98081988
SP
81
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
TO <xcDataBase>
Deve ser especificado em xcDatabase o nome da tabela a ser

criada.
Retorno:
Nenhum
DBAPPEND()
A funo DBAPPEND() acrescenta mais um registro em branco no final da tabela corrente. Se
no houver erro da RDD, o registro acrescentado e bloqueado.
Sintaxe: DBAPPEND ( [ lLiberaBloqueios ] )
Parmetros:
lLiberaBloqueios
Se o valor for .T., libera todos os registros bloqueados anteriormente

(locks). Se for .F., todos os bloqueios anteriores so mantidos. Valor
default: .T.
Retorno:
Nenhum
Exemplo:
USE Clientes NEW
FOR i:=1 to 5
DBAPPEND(.F.)
NOME := "XXX"
END : ="YYY"
NEXT
// Os 5 registros includos permanecem bloqueados
DBAPPEND()
// Todos os bloqueios anteriores so liberados
DBCLEARALLFILTER()
A funo DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as
tabelas e depois limpa as condies de filtro de todas as tabelas.
Sintaxe: DBCLEARALLFILTER()
Parmetros:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
82
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Nenhum
Exemplo:
USE Clientes NEW
DBSETFILTER( {|| Idade < 40}, 'Idade < 40') // Seta a expresso de filtro
...
DBCLEARALLFILTER()
// Limpa a expresso de filtro de todas as ordens
DBCLEARFILTER()
A funo DBCLEARFILTER() salva as atualizaes realizadas e pendentes na tabela corrente e
depois limpa todas as condies de filtro da ordem ativa no momento. Seu funcionamento
oposto ao comando SET FILTER.
Sintaxe: DBCLEARFILTER()
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo:
USE Clientes NEW
DBSETFILTER( {|| Idade < 40}, "Idade < 40" ) // Seta a expresso de filtro
...
DBCLEARFILTER()
// Limpa a expresso de filtro
DBCLEARINDEX()
A funo DBCLEARINDEX() salva as atualizaes pendentes na tabela corrente e fecha todos
os arquivos de ndice da rea de trabalho. Por conseqncia, limpa todas as ordens da lista.
Seu funcionamento oposto ao comando SET INDEX.
Sintaxe: DBCLEARINDEX()
Parmetros:
Nenhum
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
83
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Nenhum
Exemplo:
USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
...
DBCLEARINDEX()
// Fecha todos os arquivos de ndices
DBCLOSEALL()
A funo DBCLOSEALL() salva as atualizaes pendentes,
bloqueados e fecha todas as tabelas abertas (reas
chamasse DBCLOSEAREA para cada rea de trabalho.
Sintaxe: DBCLOSEALL()
Parmetros:
Nenhum
libera todos os registros

de trabalho) como se
Retorno:
Nenhum
Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCLOSEALL para fechar a rea de
trabalho atual.
USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
USE Fornecedores NEW
DBSETINDEX("Idade") // Abre o arquivo de ndice "Idade"
...
DBCLOSEALL() //Fecha todas as reas de trabalho, todos os indices e ordens
DBCLOSEAREA()
A funo DBCLOSEAREA() permite que um alias presente na conexo seja fechado, o que
viabiliza seu reuso em outro operao. Este comando tem efeito apenas no alias ativo na
conexo, sendo necessria sua utilizao em conjunto com o comando DbSelectArea().
Sintaxe: DBCLOSEAREA()
Parmetros:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
84
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Nenhum
Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
DBCOMMIT()
A funo DBCOMMIT() salva em disco todas as atualizaes pendentes na rea de
trabalho corrente.
Sintaxe: DBCOMMIT()
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo:
USE Clientes NEW
DBGOTO(100)
Nome := "Jose"
DBGOTO(168)
Nome := "Joao"
DBCOMMIT() // Salva em disco apenas as alteraes realizadas na tabela Fornecedores
DBCOMMITALL()
A funo DBCOMMITALL() salva em disco todas as atualizaes pendentes em todas
as reas de trabalho.
Sintaxe: DBCOMMITALL()
Parmetros:
Nenhum
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
85
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Nenhum
Exemplo:
USE Clientes NEW
DBGOTO(100)
Nome := "Jose"
DBGOTO(168)
Nome := "Joao"
DBCOMMITALL()
// Salva em disco as alteraes realizadas nas tabelas Clientes e Fornecedores
DBCREATE()
A funo DBCREATE() utilizada para criar um novo arquivo de tabela cujo nome
est especificado atravs do primeiro parmetro (cNome) e estrutura atravs do segundo
(aEstrutura). A estrutura especificada atravs de um array com todos os campos,
onde cada campo expresso atravs de um array contendo {Nome, Tipo, Tamanho,
Decimais}.
Sintaxe: DBCREATE ( < cNOME > , < aESTRUTURA > , [ cDRIVER ] )
Parmetros:
cNOME
aESTRUTURA
cDRIVER
Nome do arquivo a ser criado. Se contm pasta, ela se localiza abaixo do

"RootPath". Se no, criado por padro no caminho formado por
"RootPath"+"StartPath"
Lista com as informaes dos campos para ser criada a tabela.
Nome da RDD a ser utilizado para a criao da tabela. Se for omitido ser
criada com a corrente.
Retorno:
Nenhum
Exemplo:
// Este exemplo mostra como se pode criar novo arquivo atravs da funo DBCREATE:
LOCAL aEstrutura :={{Cod,N,3,0},
{Nome,C,10,0},
{Idade,N,3,0},
{Nasc,D,8,0},
{Pagto,N,7,2}}
// Cria a tabela com o RDD corrente
DBCREATE('\teste\cliente.dbf', aEstrutura)
USE '\teste\cliente.dbf' VIA 'DBFCDX' NEW

Tel: 11 50114895 / 50116082 / 98081988
SP
86
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Erros mais comuns:

1.
DBCreate - Data base files can only be created on the server: O nome
do arquivo a ser criado no pode conter 'driver', pois, por conveno, ele
seria criado na mquina onde o Remote est rodando.
2.
DBCreate - Invalid empty filename: Nome do arquivo no foi
especificado
3.
DBCreate - Field's name cannot be 'DATA': Algumas RDD's no
suportam este nome de campo. uma palavra reservada.
4.
DBCreate - The length of Field's name must be at most 10: Nome do
campo no pode ter mais que 10 caracteres.
5.
DBCreate - Field's name must be defined: Nome do campo no foi
definido.
6.
DBCreate - Field's type is not defined: Tipo do campo no foi definido.
7.
DBCreate - invalid Field's type: Tipo do campo diferente de 'C', 'N',
'D', 'M' ou 'L'.
8.
DBCreate - Invalid numeric field format: Considerando 'len' o tamanho
total do campo numrico e 'dec' o nmero de decimais, ocorre este erro se:
(len = 1) .and. (dec <> 0): Se o tamanho total 1, o campo no pode

ter decimais
(len>1) .and. (len< dec + 2): Se o tamanho total maior que 1, ele
deve ser maior que o nmero de decimais mais 2, para comportar o
separador de decimais e ter pelo menos um algarismo na parte inteira.
Exemplo: O nmero 12.45 poderia ser o valor de um campo com
len=5 e dec=2 (no mnimo).
Erros mais comuns:

Podem ocorrer tambm erros decorrentes de permisso e direitos na pasta
onde se est tentando criar o arquivo ou por algum problema no banco de
dados. Verifique as mensagens do servidor Protheus e do banco de dados.
DBCREATEINDEX()
A funo DBCREATEINDEX() utilizada para criar um novo arquivo de ndice com o nome
especificado atravs do primeiro parmetro, sendo que se o mesmo existir deletado e criado
o novo. Para tanto so executados os passos a seguir:
Salva fisicamente as alteraes ocorridas na tabela corrente;

Fecha todos os arquivos de ndice abertos;
Cria o novo ndice;
Seta o novo ndice como a ordem corrente;
Posiciona a tabela corrente no primeiro registro do ndice.
Com exceo do RDD CTREE, a tabela corrente no precisa estar aberta em modo exclusivo
para a criao de ndice, pois na criao de ndices no Ctree alterada a estrutura da tabela,
precisando para isto a tabela estar aberta em modo exclusivo.
Tel: 11 50114895 / 50116082 / 98081988
SP
87
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe:
[lUNICO])
Parmetros:
DBCREATEINDEX(<cNOME>,
<cEXPCHAVE>,
[bEXPCHAVE],
cNOME
Nome do arquivo de ndice a ser criado.
cEXPCHAVE
Expresso das chaves do ndice a ser criado na forma de string.
bEXPCHAVE
Expresso das chaves do ndice a ser criado na forma executvel.
lUNICO
Cria ndice como nico (o padro .F.).
Retorno:
Nenhum
Exemplo:
// Este exemplo mostra como se pode criar novo arquivo de ndice criando a ordem sobre os
// campos Nome e End e no aceitar duplicao:
USE Cliente VIA "DBFCDX" NEW
DBCREATEINDEX("\teste\ind2.cdx","Nome+End",{ || Nome+End },.T.)
DBDELETE()
A funo DBDELETE() marca o registro corrente como apagado logicamente(), sendo
necessria sua utilizao em conjunto com as funes RecLock() e MsUnLock().
Para filtrar os registro marcados do alias corrente pode-se utilizar o comando SET DELETED e
para apag-los fisicamente pode-se utilizar a funo __DBPACK().
Sintaxe: DBDELETE ( )
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found()
RecLock(SA1,.F.) // Define que ser realizada uma alterao no registro posicionado
DbDelete() // Efetua a excluso lgica do registro posicionado.
Tel: 11 50114895 / 50116082 / 98081988
SP
88
ADVPL
GUIA DE REFERNCIA
Escola conveniada
MsUnLock() // Confirma e finaliza a operao

ENDIF
DBF()
A funo DBF() verifica qual o Alias da rea de trabalho corrente. O Alias definido
quando a tabela aberta atravs do parmetro correspondente (DBUSEAREA()). Esta funo
o inverso da funo SELECT(), pois nesta retornado o nmero da rea de trabalho do Alias
correspondente.
Sintaxe: DBF()
Parmetros:
Nenhum
Retorno:
Caracter
Retorna o Alias corrente. Caso no exista Alias corrente retorna "" (String
vazia).
Exemplo:
dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
MessageBox("O Alias corrente : "+DBF(),"Alias", 0) //Resultado: "O Alias corrente : SSS"
DBFIELDINFO()
A funo DBFIELDINFO() utilizada para obter informaes sobre determinado campo da
tabela corrente. O tipo de informao (primeiro argumento) escolhido de acordo com as
constantes abaixo:
Tabela A : Constantes utilizadas na parametrizao da funo

Constante
Descrio
Retorno
DBS_NAME
Nome do campo.
Caracter
DBS_DEC
Nmero de casas decimais.
Numrico
DBS_LEN
Tamanho.
Numrico
DBS_TYPE
Tipo.
Caracter
A posio do campo no leva em considerao os campos internos do Protheus (Recno e

Deleted).
Sintaxe: DBFIELDINFO ( < nINFOTIPO > , < nCAMPO > )
Parmetros:
nINFOTIPO
Tipo de informao a ser verificada (DBS_NAME, DBS_DEC, DBS_LEN e

DBS_TYPE).

Tel: 11 50114895 / 50116082 / 98081988
SP
89
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nCAMPO
Posio do campo a ser verificado.

Tel: 11 50114895 / 50116082 / 98081988
SP
90
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Indefinido
Retorna NIL se no h tabela corrente ou a posio do campo

especificado est invlida.
Informao do campo Informao requisitada pelo usurio (pode ser de tipo
numrico se for tamanho ou casas decimais, tipo caracter se for nome ou
tipo).
Exemplo:
USE Clientes NEW
DBFIELDINFO(DBS_NAME,1) // Retorno: Nome
DBFIELDINFO(DBS_TYPE,1) // Retorno: C
DBFIELDINFO(DBS_LEN,1) // Retorno: 10
DBFIELDINFO(DBS_DEC,1) // Retorno: 0
DBFILTER()
A funo DBFILTER() utilizada para verificar a expresso de filtro ativo na rea de trabalho
corrente.
Sintaxe: DBFILTER()
Parmetros:
Nenhum
Retorno:
Caracter
Retorna a expresso do filtro ativo na rea de trabalho atual. Caso no exista

filtro ativo retorna "" (String vazia).
Exemplo:
USE Cliente INDEX Ind1 NEW
SET FILTER TO Nome > "Jose"
DBFILTER() // retorna: Nome > "Jose"
SET FILTER TO Num < 1000
DBFILTER() // retorna: Num < 1000
DBGOTO()
Move o cursor da rea de trabalho ativa para o record number (recno) especificado, realizando
um posicionamento direto, sem a necessidade uma busca (seek) prvio.
Sintaxe: DbGoto(nRecno)
Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
91
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nRecno
Record number do registro a ser posicionado.
Exemplo:
DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro 100
IF !EOF() // Se a rea de trabalho no estiver em final de arquivo
MsgInfo(Voc est no cliente:+A1_NOME)
ENDIF
DBGOTOP()
Move o cursor da rea de trabalho ativa para o primeiro registro lgico.
Sintaxe: DbGoTop()
Parmetros
Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo
DbSelectArea(SA1)
DbGoTop()
While !BOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(-1)
End
MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).
// Retorno esperado :000001, pois o DbGoTop posiciona no primeiro registro.
DBGOBOTTON()
Move o cursor da rea de trabalho ativa para o ltimo registro lgico.
Sintaxe: DbGoBotton()
Parmetros
Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo
DbSelectArea(SA1)
Tel: 11 50114895 / 50116082 / 98081988
SP
92
ADVPL
GUIA DE REFERNCIA
Escola conveniada

DbGoBotton()
While !EOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(1)
End
MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).
// Retorno esperado :000001, pois o DbGoBotton posiciona no ltimo registro.
DBINFO()
DBINFO() utilizada para obter informaes sobre a tabela corrente. O tipo de informao
(primeiro argumento) escolhido de acordo com as constantes abaixo:

Constante
Descrio
Retorno
DBI_GETRECSIZE
Tamanho do registro em nmero de bytes

similar a RECSIZE.
Numrico
DBI_TABLEEXT
Extenso do arquivo da tabela corrente.
Caracter
DBI_FULLPATH
Nome da tabela corrente com caminho

completo.
Caracter
DBI_BOF
Se est posicionada no incio da tabela

similar a BOF
Lgico
DBI_EOF
Se est posicionada no final da tabela

similar a EOF
Lgico
DBI_FOUND
Se a tabela est posicionada aps uma

pesquisa similar a FOUND
Lgico
DBI_FCOUNT
Nmero de campos na estrutura

tabela corrente similar a FCOUNT
Numrico
DBI_ALIAS
Nome do Alias da rea de trabalho

corrente similar a ALIAS
Caracter
DBI_LASTUPDATE
Data da ltima modificao similar a

LUPDATE
Data
Sintaxe: DBINFO(<nINFOTIPO>)
Parmetros:
nINFOTIPO
da
Tipo de informao a ser verificada.
Retorno:
Indefinido
Informao da Tabela Informao requisitada pelo usurio (o tipo depende

da informao requisitada). Se no houver tabela corrente retorna NIL.

Tel: 11 50114895 / 50116082 / 98081988
SP
93
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
USE Clientes NEW
DBINFO(DBI_FULLPATH) // Retorno: C:\Teste\Clientes.dbf
DBINFO(DBI_FCOUNT) // Retorno: 12
DBGOTOP()
DBINFO(DBI_BOF) // Retorno: .F.
DBSKIP(-1)
DBINFO(DBI_BOF) // Retorno: .T.
DBNICKINDEXKEY()
Funo que retorna o IndexKey,ou seja, a expresso de ndice da ordem especificada pelo
NickName. Se no existe ndice com o nickname, retorna uma string vazia.
Sintaxe: DBNICKINDEXKEY(<cNick>)
Parmetros:
cNick
Indica o "NickName" da ordem de ndice.
Retorno:
Caracter
Expresso do ndice identificado pelo "NickName".
DBORDERINFO()
A funo DBORDERINFO() utilizada para obter informaes sobre determinada ordem. A
especificao da ordem pode ser realizada atravs de seu nome ou sua
posio dentro da lista de ordens, mas se ela no for especificada sero
obtidas informaes da ordem corrente.O tipo de informao (primeiro argumento) escolhido
de acordo com as constantes abaixo:

Constante
Descrio
Retorno
DBOI_BAGNAME
Nome do arquivo de ndice ao qual a

ordem pertence.
Caracter
DBOI_FULLPATH
do arquivo de ndice (com seu diretrio)

ao qual a ordem pertence.
Caracter
DBOI_ORDERCOUNT
Nmero de ordens existentes no arquivo

de ndice especificado.
Caracter
Sintaxe: DBORDERINFO(<nINFOTIPO>)
Parmetros:
nINFOTIPO
Nome do arquivo de ndice.

Tel: 11 50114895 / 50116082 / 98081988
SP
94
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Caracter
Retorna a informao da Ordem requisitada pelo usurio (pode ser de tipo

numrico se for nmero de ordens no ndice, tipo caracter se for nome do
arquivo de ndice). Caso no exista ordem corrente ou a posio da ordem
especificada est invlida retorna NIL.
Exemplo:
DBORDERINFO(DBOI_BAGNAME) // retorna: Ind
DBORDERINFO(DBOI_FULLPATH) // retorna: C:\AP6\Teste\Ind.cdx
DBORDERNICKNAME()
A funo DBORDERNICKNAME() utilizada para selecionar a ordem ativa atravs de seu
apelido. Esta ordem a responsvel pela seqncia lgica dos registros da tabela corrente.
Sintaxe: DBORDERNICKNAME(<cAPELIDO>)
Parmetros:
cAPELIDO
Nome do apelido da ordem a ser setada.
Retorno:
Lgico
Retorna Falso se no conseguiu tornar a ordem ativa. Principais erros: No

existe tabela ativa ou no foi encontrada a ordem com o apelido.
Retorna Verdadeiro se a ordem foi setada com sucesso.
Exemplo:
USE Cliente NEW
SET INDEX TO Nome, Idade
IF !DBORDERNICKNAME("IndNome")
Messagebox("Registro no encontrado","Erro", 0)
ENDIF
DBPACK()
A funo DBPACK() remove fisicamente todos os registros com marca de excludo da tabela.
Sintaxe: __DBPACK()
Parmetros:
Nenhum
Retorno:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
95
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
USE Clientes NEW
DBGOTO(100)
DBDELETE()
DBGOTO(105)
DBDELETE()
DBGOTO(110)
DBDELETE()
// Se a excluso for confirmada:
__DBPACK()
DBRECALL()
A funo DBRECALL() utilizada para retirar a marca de registro deletado do registro atual.
Para ser executada o registro atual deve estar bloqueado ou a tabela deve estar aberta em
modo exclusivo. Se o registro atual no estiver deletado, esta funo no faz nada. Ela o
oposto da funo DBDELETE() que marca o registro atual como deletado.
Sintaxe: DBRECALL()
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo 01:
Desfazendo a deleo do registro posicionado do alias corrente
USE Cliente
DBGOTO(100)
DBDELETE()
DELETED() // Retorna: .T.
DBRECALL()
DELETED() // Retorna: .F.
Exemplo 02:
Desfazendo as delees do alias corrente
USE Cliente
DBGOTOP()
WHILE !EOF()
DBRECALL()
DBSKIP()
ENDDO

Tel: 11 50114895 / 50116082 / 98081988
SP
96
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DBRECORDINFO()
A funo DBRECORDINFO() utilizada para obter informaes sobre o registro especificado
pelo segundo argumento (recno) da tabela corrente, se esta informao for omitida ser
verificado o registro corrente. O tipo de informao (primeiro argumento) escolhido de
acordo com as constantes abaixo:

Constante
Descrio
Retorno
DBRI_DELETED
Estado de deletado similar a DELETED
Lgico
DBRI_RECSIZE
Tamanho do registro similar a RECSIZE
Numrico
DBRI_UPDATED
Verifica se o registro foi alterado e ainda

no foi atualizado fisicamente similar a
UPDATED
Lgico
Sintaxe: DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO
Parmetros:
nINFOTIPO
Tipo de informao a ser verificada.
nREGISTRO
Nmero do registro a ser verificado.
Retorno:
Indefinido
No h tabela corrente ou registro invlido. Informao do Registro.

Informao requisitada pelo usurio (o tipo depende da informao
requisitada).
Exemplo:
USE Clientes NEW
DBGOTO(100)
DBRECORDINFO(DBRI_DELETED) // Retorno: .F.
DBDELETE()
DBRECORDINFO(DBRI_DELETED) // Retorno: .F.
DBRECALL()
DBRECORDINFO(DBRI_RECSIZE) // Retorno: 230
NOME := "JOAO"
DBGOTO(200)
DBRECORDINFO(DBRI_UPDATED) // Retorno: .F.
DBRECORDINFO(DBRI_UPDATED,100) // Retorno: .T.
DBREINDEX()
A funo DBREINDEX() reconstri todos os ndices da rea de trabalho corrente e posiciona as
tabelas no primeiro registro lgico.
Sintaxe: DBREINDEX()

Tel: 11 50114895 / 50116082 / 98081988
SP
97
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo:
USE Clientes NEW
DBSETINDEX("IndNome")
DBREINDEX()
DBRLOCK()
A funo DBRLOCK() utilizada quando se tem uma tabela aberta e compartilhada e se deseja
bloquear
um
registro
para
que
outros
usurios
no
possam
alter-lo.
Se a tabela j est aberta em modo exclusivo, a funo no altera seu estado.
O usurio pode escolher o registro a ser bloqueado atravs do parmetro
(recno), mas se este for omitido ser bloqueado o registro corrente como na funo RLOCK().
Esta funo o oposto DBRUNLOCK, que libera registros bloqueados.
Sintaxe: DBRLOCK([nREGISTRO])
Parmetros:
nREGISTRO
Nmero do registro a ser bloqueado.
Retorno:
Lgico
Retorna Falso se no conseguiu bloquear o registro. Principal motivo: o

registro j foi bloqueado por outro usurio.
Retorna Verdadeiro se o registro foi bloqueado com sucesso.
Exemplo:
DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
DBGOTO(100)
DBRLOCK() // Bloqueia o registro atual (100)
DBRLOCK(110) // Bloqueia o registro de nmero 110
DBRLOCKLIST()
A funo DBRLOCKLIST() utilizada para verificar quais registros esto locados na tabela
corrente. Para tanto, retornada uma tabela unidimensional com os nmeros dos registros.
Sintaxe: DBRLOCKLIST()

Tel: 11 50114895 / 50116082 / 98081988
SP
98
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
Nenhum
Retorno:
Array
Retorna NIL se no existe tabela corrente ou no existe nenhum

registro locado. Retorna a lista com os recnos dos registros locados na tabela
corrente.
Exemplo:
DBGOTOP()
DBRLOCK() // Bloqueia o primeiro registro
DBRLOCKLIST() // Retorna: {1,100,110}
DBRUNLOCK()
A funo DBRUNLOCK() utilizada para liberar determinado registro bloqueado. O usurio
pode escolher o registro a ser desbloqueado atravs do parmetro (Recno), mas se este for
omitido ser desbloqueado o registro corrente como na funo DBUNLOCK(). Esta funo o
oposto DBRLOCK, que bloquea os registros.
Sintaxe: DBRUNLOCK([nREGISTRO])
Parmetros:
nREGISTRO
Nmero do registro a ser desbloqueado.
Retorno:
Nenhum
Exemplo:
DBGOTO(100)
DBRUNLOCK() //Desbloqueia o registro atual (100)
DBRUNLOCK(110) // Desbloqueia o registro de nmero 110
DBSETDRIVER()
A funo DBSETDRIVER() pode ser utilizada apenas para verificar qual o RDD que est definido
como padro quando for omitido seu parmetro. Ela tambm pode ser utilizada para
especificar outro RDD como padro, especificando-o atravs do parmetro.
Tel: 11 50114895 / 50116082 / 98081988
SP
99
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: DBSETDRIVER([cNOVORDD])
Parmetros:
cNOVORDD
Novo nome do RDD a ser definido como padro.
Retorno:
Caracter
Nome do RDD padro corrente.
Exemplo:
DBSETDRIVER("CTREECDX") // Retorna: DBFCDX
DBSETDRIVER() // Retorna: CTREECDX
Note que ao utilizar a funo DBSETDRIVER para redefinir o driver corrente, o

retorno da funo no ser o driver definido nos parmetros, mas o driver que
estava em uso antes da atualizao.
DBSETINDEX()
A funo DBSETINDEX() utilizada para acrescentar uma ou mais ordens de determinado
ndice na lista de ordens ativas da rea de trabalho. Quando o arquivo de ndice possui apenas
uma ordem, a mesma acrescentada lista e torna-se ativa. Quando o ndice possui mais de
uma ordem, todas so acrescentadas lista e a primeira torna-se ativa.
Para utilizar os arquivos de extenso padro do RDD este dado deve ser
especificado.
Sintaxe: DBSETINDEX(<@cARQINDICE>)
Parmetros:
cARQINDICE
Nome do arquivo de ndice, com ou sem diretrio.
Retorno:
Nenhum
Exemplo:
USE Cliente NEW
DBSETINDEX("Ind1")
DBSETINDEX("\teste\Ind2.cdx")
DBSETNICKNAME()

Tel: 11 50114895 / 50116082 / 98081988
SP
100
ADVPL
GUIA DE REFERNCIA
Escola conveniada
A funo DBSETNICKNAME() utilizada para colocar um apelido em determinada ordem

especificada pelo primeiro parmetro. Caso seja omitido o nome do apelido a ser dado, a
funo apenas verifica o apelido corrente.
Sintaxe: DBSETNICKNAME(<cINDICE>, [cAPELIDO])
Parmetros:
cINDICE
Nome da ordem que deve receber o apelido.
cAPELIDO
Nome do apelido da ordem a ser setada.
Retorno:
Caracter
Retorna "" (String vazia) se no conseguiu encontrar a ordem especificada,

no conseguiu setar o apelido ou no havia apelido. Retorna o apelido
corrente.
Exemplo:
USE Cliente NEW
DBSETNICKNAME("IndNome") // retorna: ""
DBSETNICKNAME("IndNome","NOME") // retorna: ""
DBSETNICKNAME("IndNome") // retorna: "NOME"
DBSELECTAREA()
Define a rea de trabalho especificada com sendo a rea ativa. Todas as operaes
subseqentes que fizerem referncia a uma rea de trabalho a utilizao, a menos que a rea
desejada seja informada explicitamente.
Sintaxe: DbSelectArea(nArea | cArea)

Parmetros
nArea
Valor numrico que representa a rea desejada, em funo de todas as reas

j abertas pela aplicao, que pode ser utilizado ao invs do nome da rea.
cArea
Nome de referncia da rea de trabalho a ser selecionada.
Exemplo 01:
DbselectArea(nArea)
nArea := Select(SA1) // 10 (proposto)
DbSelectArea(nArea) // De acordo com o retorno do comando Select()
ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias selecionado, os comandos
// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME

Tel: 11 50114895 / 50116082 / 98081988
SP
101
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo 02:
DbselectArea(cArea)
DbSelectArea(SA1) // Especificao direta do alias que deseja-se selecionar
ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias selecionado, os comandos
// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME
DBSETORDER()
Define qual ndice ser utilizada pela rea de trabalho ativa, ou seja, pela rea previamente
selecionada atravs do comando DbSelectArea(). As ordens disponveis no ambiente Protheus
so aquelas definidas no SINDEX /SIX, ou as ordens disponibilizadas por meio de ndices
temporrios.
Sintaxe: DbSetOrder(nOrdem)
Parmetros
nOrdem
Nmero de referncia da ordem que deseja ser definida como ordem ativa
para a rea de trabalho.
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // De acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DBORDERNICKNAME()
Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os seus prprios
ndices e no momento da incluso deve criar o NICKNAME para o mesmo.
Sintaxe: DbOrderNickName(NickName)
Parmetros
NickName
NickName atribudo ao ndice criado pelo usurio
Exemplo:
DbSelectArea(SA1)
DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO
NickName: Tipo
DBSEEK() E MSSEEK()

Tel: 11 50114895 / 50116082 / 98081988
SP
102
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DbSeek(): Permite posicionar o cursor da rea de trabalho ativo no registro com as

informaes especificadas na chave de busca, fornecendo um retorno lgico indicando se o
posicionamento foi efetuado com sucesso, ou seja, se a informao especificada na chave de
busca foi localizada na rea de trabalho.
Sintaxe: DbSeek(cChave, lSoftSeek, lLast)

Parmetros
cChave
lSoftSeek
lLast
Dados do registro que deseja-se localizar, de acordo com a ordem de busca

previamente especificada pelo comando DbSetOrder(), ou seja, de acordo
com o ndice ativo no momento para a rea de trabalho.
Define se o cursor ficar posicionado no prximo registro vlido, em relao
a chave de busca especificada, ou em final de arquivo, caso no seja
encontrada exatamente a informao da chave. Padro .F.
Define se o cursor ser posicionado no primeiro ou no ltimo registro de um
intervalo com as mesmas informaes especificadas na chave. Padro .F.
Exemplo 01:
Busca exata
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001, Loja: 02
MsgInfo(Cliente localizado, Consulta por cliente)
Else
MsgAlert(Cliente no encontrado, Consulta por cliente)
Endif
Exemplo 02:
Busca aproximada
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DbSeek(01 + 000001 + 02, .T. ) // Filial: 01, Cdigo: 000001, Loja: 02
// Exibe os dados do cliente localizado, o qual pode no ser o especificado na chave:
MsgInfo(Dados do cliente localizado: +CRLF +;
Filial:
+ A1_FILIAL + CRLF +;
Cdigo: + A1_COD
+ CRLF +;
Loja:
+ A1_LOJA + CRLF +;
Nome:
+ A1_NOME + CRLF, Consulta por cliente)
MsSeek(): Funo desenvolvida pela rea de Tecnologia da Microsiga, a qual possui as
mesmas funcionalidades bsicas da funo DbSeek(), com a vantagem de no necessitar

Tel: 11 50114895 / 50116082 / 98081988
SP
103
ADVPL
GUIA DE REFERNCIA
Escola conveniada
acessar novamente a base de dados para localizar uma informao j utilizada pela thread
(conexo) ativa.
Desta forma, a thread mantm em memria os dados necessrios para reposicionar os
registros j localizados atravs do comando DbSeek (no caso o Recno()) de forma que a
aplicao pode simplesmente efetuar o posicionamento sem executar novamente a busca.
A diferena entre o DbSeek() e o MsSeek() notada em aplicaes com grande volume de
posicionamentos, como relatrios, que necessitam referenciar diversas vezes o mesmo registro
durante uma execuo.
DBSKIP()
Move o cursor do registro posicionado para o prximo (ou anterior dependendo do parmetro),
em funo da ordem ativa para a rea de trabalho.
Sintaxe: DbSkip(nRegistros)
Parmetros
Define em quantos registros o cursor ser deslocado. Padro 1
nRegistros
Exemplo 01:
Avanando registros
DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGotop() // Posiciona o cursor no incio da rea de trabalho ativa
While !EOF() // Enquanto o cursor da rea de trabalho ativa no indicar fim de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip()
End
Exemplo 02:
Retrocedendo registros
DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGoBotton() // Posiciona o cursor no final da rea de trabalho ativa
While !BOF() // Enquanto o cursor da rea de trabalho ativa no indicar incio de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip(-1)
End
DBSETFILTER()
Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de um bloco
de cdigo ou atravs de uma expresso simples.
104
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo - SP
Tel:
11 50114895 / 50116082 / 98081988

ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: DbSetFilter(bCondicao, cCondicao)

Parmetros
bCondicao
Bloco de expressa a condio de filtro em forma executvel
cCondicao
Expresso de filtro simples na forma de string
Exemplo 01:
Filtro com bloco de cdigo
bCondicao := {|| A1_COD >= 000001 .AND. A1_COD <= 001000}
DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(bCondicao)
DbGoBotton()
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
Exemplo 02:
Filtro com expresso simples
cCondicao := A1_COD >= 000001 .AND. A1_COD <= 001000
DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(,cCondicao)
DbGoBotton()
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
DBSTRUCT()
Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura ser um
array bidimensional conforme abaixo:
ID*
Nome campo
Tipo campo
Tamanho
Decimais
ndice do array

Tel: 11 50114895 / 50116082 / 98081988
SP
105
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: DbStruct()
Parmetros
Nenhum
Exemplo:
cCampos :=
DbSelectArea(SA1)
aStructSA1 := DbStruct()
FOR nX := 1 to Len(aStructSA1)
cCampos += aStructSA1[nX][1] + /
NEXT nX
ALERT(cCampos)
DBUNLOCK()
A funo DBUNCLOK() retira os bloqueios dos registros e do arquivo da tabela corrente.
Sintaxe: DBUNLOCK()
Parmetros:
Nenhum
Retorno:
Nenhum
DBUNLOCKALL()
A funo DBUNLOCKALL() Retira os bloqueios de todos os registros e dos arquivos de todas as
tabelas abertas. Esta funo utilizada para liberar todos os registros bloqueados e
equivalente a executar DBUNLOCK para todas as tabelas da rea de trabalho.
Sintaxe: DBUNLOCKALL()
Parmetros:
Nenhum
Retorno:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
106
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DBUSEAREA()
Define um arquivo de base de dados como uma rea de trabalho disponvel na aplicao.
Sintaxe: DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)
Parmetros
cAlias
Parmetro opcional que permite que se caso o cAlias especificado j

esteja em uso, ele seja fechado antes da abertura do arquivo da base de
dados.
Driver que permita a aplicao manipular o arquivo de base de dados
especificado. A aplicao ERP possui a varivel __LOCALDRIVER definida
a partir das configuraes do .ini do server da aplicao.
Algumas chaves vlidas: DBFCDX, CTREECDX, DBFCDXAX,
TOPCONN.
Nome do arquivo de base de dados que ser aberto com o alias
especificado.
Alias para referncia do arquivos de base de dados pela aplicao.
lComparilhado
Se o arquivo poder ser utilizado por outras conexes.
lSoLeitura
Se o arquivo poder ser alterado pela conexo ativa.
lNovo
cDriver
cArquivo
Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
DELETED()
A funo DELETED() Verifica se o registro est com marca de excludo. Quando o registro
excludo, permanece fisicamente na tabela, mas fica marcado como excludo. Esta funo
verifica este estado. Se nenhuma rea est selecionada, retorna .F.. Quando executada a
funo DBPACK() todos os registros marcados como deletados so apagados fisicamente. A
funo DBRECALL() retira todas as marcas.
Sintaxe: DELETED()
Parmetros:
Nenhum
Retorno:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
107
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
USE "\DADOSADV\AA1990.DBF" SHARED NEW
DBGOTO(100)
IF DELETED()
Messagebox("O registro atual foi deletado","Erro", 0)
ENDIF
FCOUNT()
A funo FCOUNT() avalia a quantidade de campos existentes na estrutura do arquivo ativo
como rea de trabalho.
Sintaxe: FCOUNT()
Parmetros:
Nenhum
Retorno:
Numrico
Quantidade de campos existentes na estrutura da rea de trabalho ativa.
Exemplo:
DbSelectArea(SA1)
nFields := FCOUNT()
IF nFields > 0
MSGINFO(A estrutura da tabela contm :+CvalToChar(nFields)+campos.)
ENDIF
FOUND()
A funo FOUND() recupera o resultado de sucesso referente a ltima operao de busca
efetuada pelo processamento corrente.
Sintaxe: FOUND()
Parmetros:
Nenhum
Retorno:
Lgico
Indica se a ltima operao de busca realizada pelo processamento corrente

obteve sucesso (.T.) ou no (.F.).
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
108
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Pergunte(cPerg,.T.)
DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(xFilial(SA1)+MVPAR01)
IF Found()
MSGINFO(Cliente encontrado)
ELSE
MSGALERT(Dados no encontrados)
ENDIF
INDEXKEY()
A funo INDEXKEY() determina a expresso da chave de um ndice especificado na rea de
trabalho corrente, e o retorna na forma de uma cadeia de caracteres, sendo normalmente
utilizada na rea de trabalho correntemente selecionada.
Sintaxe: INDEXKEY()
Parmetros:
nOrdem
Ordem do ndice na lista de ndices abertos pelo comando USE...INDEX ou

SET INDEX TO na rea de trabalho corrente. O valor default zero especifica o
ndice corrente, independentemente de sua posio real na lista.
Retorno:
Caracter
Expresso da chave do ndice especificado na forma de uma cadeia de

caracteres. Caso no haja um ndice correspondente, INDEXKEY() retorna
uma cadeia de caracteres vazia ("").
Exemplo:
cExpressao := SA1->(IndexKey())
INDEXORD()
A funo INDEXORD() verifica a posio do ndice corrente na lista de ndices do respectivo
alias.
Sintaxe: INDEXORD()
Parmetros:
Nenhum
Retorno:
Numrico
Posio do ndice corrente na lista de ndices da tabela. Retorna 0 se no

existe ndice aberto na tabela corrente.

Tel: 11 50114895 / 50116082 / 98081988
SP
109
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
USE Cliente NEW
SET INDEX TO Nome, End, Cep
nOrd:=INDEXORD() // Return: 1 - o primeiro ndice da lista
LUPDATE()
A funo LUPDATE() verifica qual a data da ltima modificao e fechamento da tabela
corrente, sendo que caso no exista tabela corrente retornada uma data em branco.
Sintaxe: LUPDATE()
Parmetros:
Nenhum
Retorno:
Data
Retorna um valor do tipo Data , indicando a data da ultima modificao e

fechamento da Tabela. Caso no haja tabela selecionada na rea de trabalho
atual , a funo retornar uma data vazia (ctod("")) .
Exemplo:
// Mostra a data da ltima modificao da tabela corrente,
dModificacao := LUpdate()
IF (EMPTY(dModificacao))
CONOUT("No h tabela corrente")
ELSE
CONOUT(("Data da ultima modificacao : " + DTOS(dModificacao)))
ENDIF
MSAPPEND()
A funo MsAppend() adiciona registros de um arquivo para outro, respeitando a estrutura das
tabelas.
Sintaxe: MSAPPEND( [cArqDest], cArqOrig )
Parmetros:
cArqDest
cArqOrig
Se o RDD corrente for DBFCDX os registros sero adicionados na rea

selecionada, caso contrrio o arquivo destino ter que ser informado.
Nome do arquivo origem contendo os registros a serem adicionados.
Retorno:
Lgico
Se a operao for realizada com sucesso o funo retornar verdadeiro (.T.).

Tel: 11 50114895 / 50116082 / 98081988
SP
110
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
dbSelectArea(XXX)
MsAppend(,ARQ00001)
MSUNLOCK()
Libera o travamento (lock) do registro posicionado confirmando as atualizaes efetuadas
neste registro.
Sintaxe: MsUnLock()
Parmetros
Nenhum
Exemplo:
DbSelectArea(SA1)
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
ENDIF
ORDBAGEXT()
A funo ORDBAGEXT utilizada no gerenciamento de indices para os arquivos de dados do
sistema, permitindo avaliar qual a extenso deste ndices atualmente em uso, de acordo com a
RDD ativa.
Sintaxe: ORDBAGEXT()
Parmetros:
Nenhum
Retorno:
cBagExt
Extenso do arquivo dos arquivos de ndices em uso pelo sistema,

determinado pela RDD ativa.
Exemplo:
cArqTRB := CriaTrab(aStruTRB,.T.)
Tel: 11 50114895 / 50116082 / 98081988
SP
111
ADVPL
GUIA DE REFERNCIA
Escola conveniada
// RDD UTILIZADA: DBFCDXADS

DbUseArea(.T., DBFCDXADS, cArqTRB, "TRBSA1", .F., .F.)
DbSelectArea("TRBSA1")
cArqInd := CriaTrab(Nil,.F.)
IndRegua("TRBSA1",cArqInd,cChaveInd,,"","Selecionando registros ...")
#IFNDEF TOP
DbSetIndex(cArqInd+OrdBagExt())
// RETORNO: .CDX
#ENDIF
DbSetOrder(1)
ORDKEY()
A funo ORDKEY() verifica qual a expresso de chave de determinada ordem. Caso no
sejam especificados os parmetros de identificao da ordem, verificada a ordem corrente.
Para evitar conflito, no caso de haver mais de uma ordem com o mesmo nome, pode-se passar
o parmetro com o nome do ndice ao qual a ordem pertence.
A ordem passada no primeiro parmetro pode ser especificada atravs da sua posio na lista
de ordens ativas (atravs do ORDLISTADD) ou atravs do nome dado ordem. A funo
verifica automaticamente se o parmetro numrico ou caracter.
Sintaxe: ORDKEY([cOrdem | nPosicao] , [cArqIndice])
Parmetros:
cOrdem
nPosicao
cArqIndice
H duas opes para o primeiro parmetro:

cNome: tipo caracter, contm nome do ndice.
nPosicao: tipo numrico, indica ordem do ndice.
Nome do arquivo de ndice.
Retorno:
Caracter
Expresso de chave da ordem ativa ou especificada pelos parmetros.

Cadeia vazia indica que no existe ordem corrente.
Exemplo:
USE Cliente NEW
INDEX ON Nome+Cod TO Ind1 FOR Nome+Cod > 'AZZZZZZZ'
ORDKEY('Ind1')
// Retorna: Nome+Cod
RECLOCK()
Efetua o travamento do registro posicionado na rea de trabalho ativa, permitindo a incluso
ou alterao das informaes do mesmo.
Sintaxe: RecLock(cAlias,lInclui)
Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
112
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cAlias
Alias que identifica a rea de trabalho que ser manipulada.
lInclui
Define se a operao ser uma incluso (.T.) ou uma alterao (.F.)
Exemplo 01:
Incluso
DbSelectArea(SA1)
RecLock(SA1,.T.)
SA1->A1_FILIAL := xFilial(SA1) // Retorna a filial de acordo com as configuraes do ERP
SA1->A1_COD := 900001
SA1->A1_LOJA := 01
Exemplo 02
Alterao
DbSelectArea(SA1)
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
ENDIF
A linguagem ADVPL possui variaes da funo RecLock(), as quais so:
RLOCK()
DBRLOCK()
A sintaxe e a descrio destas funes esto disponveis no Guia de Referncia

Rpido ao final deste material.
A linguagem ADVPL possui variaes da funo MsUnlock(), as quais so:
UNLOCK()
DBUNLOCK()
DBUNLOCKALL()
A sintaxe e a descrio destas funes esto disponveis no Guia de Referncia

Rpido ao final deste material.
Tel: 11 50114895 / 50116082 / 98081988
SP
113
ADVPL
GUIA DE REFERNCIA
Escola conveniada
RECNO()
A funo RECNO() retorna o nmero do registro atualmente posiconado na rea de trabalho
ativa.
Sintaxe: RECNO()
Parmetros:
Nenhum
Retorno:
nRecno
Identificador numrico do registro atualmente posicionando na rea de

trabalho ativa.
Exemplo:
DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro de recno 100.
MSGINFO(Registro posicionado:+cValToChar(RECNO()))
SELECT()
A funo SELECT() determina o nmero da rea de trabalho de um alias. O nmero retornado
pode variar de zero a 250. Se <cAlias> no for especificado, retornado o nmero da rea de
trabalho corrente. Caso <cAlias> seja especificado e o alias nao existir, SELECT() retorna zero.
Sintaxe: SELECT([cAlias])
Parmetros:
cAlias
Nome da rea de trabalho a ser verificada.
Retorno:
Numrico
rea de trabalho do alias especificado na forma de um valor numrico inteiro.
Exemplo:
nArea := Select(SA1)
ALERT(Referncia do alias SA1: +STRZERO(nArea,3)) // 10 (proposto)
SET FILTER TO

Tel: 11 50114895 / 50116082 / 98081988
SP
114
ADVPL
GUIA DE REFERNCIA
Escola conveniada
O comando SET FILTER TO define uma condio de filtro que ser aplicada a rea de trabalho
ativa.
Recomenda-se o uso da funo DbSetFilter() em substituio ao comando SET

FILTER TO
Sintaxe: SET FILTER TO cCondicao
Parmetros:
cCondicao
Expresso que ser avaliada pela SET FILTER, definindo os registros que
ficaro disponveis na rea de trabalho ativa.
Esta expresso obrigatoriamente deve ter um retorno lgico.
Retorno:
Nenhum
O uso da sintaxe SET FILTER TO desativa o filtro na rea de trabalho corrente.
Exemplo:
USE Employee INDEX Name NEW
SET FILTER TO Age > 50
LIST LastName, FirstName, Age, Phone
SET FILTER TO
SOFTLOCK()
Permite a reserva do registro posicionado na rea de trabalho ativa de forma que outras
operaes, com exceo da atual, no possam atualizar este registro. Difere da funo
RecLock() pois no gera uma obrigao de atualizao, e pode ser sucedido por ele.
Na aplicao ERP Protheus, o SoftLock() utilizado nos browses, antes da confirmao da
operao de alterao e excluso, pois neste momento a mesma ainda no foi efetivada, mas
outras conexes no podem acessar aquele registro pois o mesmo est em manuteno, o que
implementa da integridade da informao.
Sintaxe: SoftLock(cAlias)
Parmetros
cAlias
Alias de referncia da rea de trabalho ativa, para o qual o registro

posicionado ser travado.

Tel: 11 50114895 / 50116082 / 98081988
SP
115
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exemplo:
cChave := GetCliente() // Funo ilustrativa que retorna os dados de busca de um cliente
DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(cChave)
IF Found()
SoftLock() // Reserva o registro localizado
lConfirma := AlteraSA1() // Funo ilustrativa que exibe os dados do registro
// posicionado e pemite a alterao dos mesmos.
IF lConfirma
RecLock(SA1,.F.)
GravaSA1() // Funo ilustrativa que altera os dados conforme a AlertaSA1()
MsUnLock() // Liberado o RecLock() e o SoftLock() do registro.
Endif
Endif
USED()
A funo USED() utilizada para determinar se h um arquivo de banco de dados em uso em
uma rea de trabalho especfica. O padro que USED() opere na rea de trabalho
correntemente selecionada.
Sintaxe: USED()
Parmetros:
Nenhum
Retorno:
Lgico
Verdadeiro (.T.) caso haja um arquivo de banco de dados em uso; caso

contrrio, retorna falso (.F.).
Exemplo:
USE Customer NEW
CONOUT(USED()) // Resulta: .T.
CLOSE
CONOUT (USED()) // Resulta: .F.
Controle de numerao seqencial

GETSXENUM()
Tel: 11 50114895 / 50116082 / 98081988
SP
116
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Obtm o nmero seqncia do alias especificado no parmetro, atravs da referncia aos

arquivos de sistema SXE/SXF ou ao servidor de numerao, quando esta configurao est
habilitada no ambiente Protheus.
Sintaxe: GETSXENUM(cAlias, cCampo, cAliasSXE, nOrdem)

Parmetros
cAlias
cCampo
cAliasSXE
nOrdem
Alias de referncia da tabela para a qual ser efetuado o controle da

numerao seqencial.
Nome do campo no qual est implementado o controle da numerao.
Parmetro opcional, quando o nome do alias nos arquivos de controle de
numerao no o nome convencional do alias para o sistema ERP.
Nmero do ndice para verificar qual a prxima ocorrncia do nmero.
CONFIRMSXE()
Confirma o nmero alocado atravs do ltimo comando GETSXENUM().
Sintaxe: CONFIRMSXE(lVerifica)
Parmetros
lVerifica
Verifica se o nmero confirmado no foi alterado, e por conseqncia j

existe na base de dados.
ROLLBACKSXE()
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao
disponvel para outras conexes.
Sintaxe: ROLLBACKSXE()
Parmetros
Nenhum
Validao
ALLWAYSFALSE()
A funo AllwaysFalse() foi criada com o objetivo de compatibilidade, sendo que sempre ir
retornar um valor lgico falso, facilitando a especificao desta situao nas parametrizaes
de validaes de modelos de interface pr-definidos no sistema.
Sintaxe: ALLWAYSFALSE()
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
117
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Nenhum
Retorno:
Lgico
Retorna um valor lgico sempre falso.
ALLWAYSTRUE()
A funo AllwaysTrue() foi criada com o objetivo de compatibilidade, sendo que sempre ir
retornar um valor lgico verdadeiro, facilitando a especificao desta situao nas
parametrizaes de validaes de modelos de interface pr-definidos no sistema.
Sintaxe: ALLWAYSTRUE()
Parmetros:
Nenhum
Retorno:
Lgico
Retorna um valor lgico sempre verdadeiro.
EXISTCHAV()
Retorna .T. ou .F. se o contedo especificado existe no alias especificado. Caso exista ser
exibido um help de sistema com um aviso informando da ocorrncia.
Funo utilizada normalmente para verificar se um determinado cdigo de cadastro j existe
na tabela na qual a informao ser inserida, como por exemplo o CNPJ no cadastro de
clientes ou fornecedores.
Sintaxe: ExistChav(cAlias, cConteudo, nIndice)

Parmetros
cAlias
Alias de referncia para a validao da informao.
cConteudo
Chave a ser pesquisada, sem a filial.
nIndice
ndice de busca para consulta da chave.
EXISTCPO()
Retorna .T. ou .F. se o contedo especificado no existe no alias especificado. Caso no exista
ser exibido um help de sistema com um aviso informando da ocorrncia.
Funo utilizada normalmente para verificar se a informao digitada em um campo, a qual
depende de outra tabela, realmente existe nesta outra tabela, como por exemplo o cdigo de
um cliente em um pedido de venda.
Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)

Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
118
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cAlias
Alias de referncia para a validao da informao.
cConteudo
Chave a ser pesquisada, sem a filial.
nIndice
ndice de busca para consulta da chave.
LETTERORNUM()
A funo LETTERORNUM() avalia se um determinado contedo composto apenas de letras e
nmeros (alfanumrico).
Sintaxe: LETTERORNUM(cString)
Parmetros:
cString
String que ter seu contedo avaliado.
Retorno:
Lgico
Indica que se a string avaliada contm apenas letras e nmero, ou seja,

alfanumrico.
NAOVAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio.
Sintaxe: NaoVazio()
Parmetros
Nenhum
NEGATIVO()
Retorna .T. ou .F. se o contedo digitado para o campo negativo.
Sintaxe: Negativo()
Parmetros
Nenhum
PERTENCE()
Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida como
parmetro da funo. Normalmente utilizada em campos com a opo de combo, pois caso
contrrio seria utilizada a funo ExistCpo().
Sintaxe: Pertence(cString)

Tel: 11 50114895 / 50116082 / 98081988
SP
119
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros
cString
String contendo as informaes vlidas que podem ser digitadas para um

campo.
POSITIVO()
Retorna .T. ou .F. se o contedo digitado para o campo positivo.
Sintaxe: Positivo()
Parmetros
Nenhum
TEXTO()
Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou
alfanumricos.
Sintaxe: Texto()
Parmetros
Nenhum
VAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.
Sintaxe: Vazio()
Parmetros
Nenhum
Manipulao de parmetros do sistema

GETMV()
Retorna o contedo do parmetro especificado no arquivo SX6, considerando a filial
parametrizada na conexo. Caso o parmetro no exista ser exibido um help do sistema
informando a ocorrncia.
Sintaxe: GETMV(cParametro)
Parmetros

Tel: 11 50114895 / 50116082 / 98081988
SP
120
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da filial de

sistema.
GETNEWPAR()
Difere do SuperGetMV() pois considera que o parmetro pode no existir na verso atual do
sistema, e por conseqncia no ser exibida a mensagem de help.
Sintaxe: GETNEWPAR(cParametro, cPadrao, cFilial)
Parmetros
cParametro

sistema.
cPadrao
Contedo padro que ser utilizado caso o parmetro no exista no SX6.
cFilial
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
PUTMV()
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.
Sintaxe: PUTMV(cParametro, cConteudo)

Parmetros
cParametro

sistema.
cConteudo
Contedo que ser atribudo ao parmetro no SX6.
SUPERGETMV()
Difere do GetMv() pois os parmetros consultados so adicionados em uma rea de memria,
que permite que em uma nova consulta no seja necessrio acessar e pesquisar o parmetro
na base de dados.
Sintaxe: SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)

Tel: 11 50114895 / 50116082 / 98081988
SP
121
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros
cParametro

sistema.
lHelp
Se ser exibida a mensagem de Help caso o parmetro no seja encontrado

no SX6.
cPadrao
Contedo padro que ser utilizado caso o parmetro no exista no SX6.
cFilial
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
Controle de impresso
AVALIMP()
A funo AVALIMP() utilzada em relatrios especficos em substituio da funo CABEC(),
configurando a impressora de acordo com o driver escolhido e os parmetros de impresso
disponveis no array aReturn, respeitando o formato utilizado pela funo SETPRINT().
Sintaxe: AVALIMP(nLimite)
Parmetros:
nLimite
Tamanho do relatrio em colunas, podendo assumir os valores 80,132 ou

220 colunas, respectivamente para os formatos P, M ou G de
impresso.
Retorno:
Caracter
String com caracteres de controle, dependente das configuraes escolhidas

pelo usurio e do arquivo de driver especificado.
Exemplo:
/*/
+----------------------------------------------------------------------------| Funo
| XAVALIMP
| Autor |
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo AXCADASTRO()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
USER FUNCTION XAVALIMP()
LOCAL cTitulo
:= PADC(AVALIMP,74)

Tel: 11 50114895 / 50116082 / 98081988
SP
122
ADVPL
GUIA DE REFERNCIA
Escola conveniada
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
cDesc1
cDesc2
cDesc3
cTamanho
cLimite
cNatureza
aReturn
cNomeProg
cPerg
nLastKey
cString
:= PADC(Demonstrao do uso da funo AVALIMP(),74)

:=
:= PADC(CURSO DE ADVPL,74)
:= G
:= 220
:=
:= {Especial, 1,Administrao, 1, 2, 2,,1}
:= RAVALIMP
:= PADR(RAVALIMP,10) // Compatibilizao com MP10
:= 0
:=SF2"
Pergunte(cPerg,.F.) // Pergunta no SX1

wnrel:= SetPrint(cString,wnrel,cPerg,cTitulo,cDesc1,cDesc2,cDesc3,.T.)
SetDefault(aReturn,cString)
If nLastKey == 27
Return
Endif
RptStatus({|| RunReport(cString)},cTitulo)
Return
/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor |
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela XAVALIMP()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
Static Function RunReport(cString)
SetPrc(0,0)
//+-------------------------------------------------------------------------+
//| Chamada da funo AVALIMP()
|
//+-------------------------------------------------------------------------+
@ 00,00 PSAY AvalImp(220)
dbSelectArea(cString)
dbSeek(xFilial()+mv_par01+mv_par03,.T.)
...
Return
CABEC()
A funo CABEC() determina as configuraes de impresso do relatrio e imprime o cabealho
do mesmo.
Sintaxe: Cabec(cTitulo, cCabec1, cCabec2, cNomeProg, nTamanho, nCompress,

aCustomText, lPerg, cLogo)

Tel: 11 50114895 / 50116082 / 98081988
SP
123
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
cTitulo
Ttulo do relatrio
cCabec1
String contendo as informaes da primeira linha do cabealho
cCabec2
String contendo as informaes da segunda linha do cabealho
cNomeProg
Nome do programa de impresso do relatrio.
nTamanho
Tamanho do relatrio em colunas (80, 132 ou 220)
nCompress
Indica se impresso ser comprimida (15) ou normal (18).

Texto especfico para o cabealho, substituindo a estrutura padro do
sistema.
Permite a supresso da impresso das perguntas do relatrio, mesmo que
o parmetro MV_IMPSX1 esteja definido como S
aCustomText
lPerg
Parmetros (continuao):
Redefine o bitmap que ser impresso no relatrio, no necessitando que
ele esteja no formato padro da Microsiga:
"LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"
cLogo
Retorno:
Nenhum
Exemplo:
#INCLUDE "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MPTR001
| Autor |
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao das funes de impresso CABEC()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
User Function MPTR001()
Local
Local
Local
Local
Local
cDesc1
cDesc2
cDesc3
cTitulo
lImprime
:=
:=
:=
:=
:=
"Este programa tem como objetivo imprimir relatorio "

"de acordo com os parametros informados pelo usuario."
"Listagem de clientes"
"Listagem de clientes"
.T.
// Parametros da SetPrint()
Local cString
:= "SA1"
Local cPerg
:= ""
Local lDic
:= .T. // Habilita a visalizacao do dicionario
Local aOrd
:= RetSixOrd(cString)
Local lCompres
:= .T. // .F. - Normal / .T. - Comprimido
Local lFilter
:= .T. // Habilita o filtro para o usuario
Local cNomeProg
:= "MPTR002"
Tel: 11 50114895 / 50116082 / 98081988
SP
124
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Local cTamanho
Local nTipo
Local nLimite
:= "M"
:= 18
:= 132
Default lCriaTrab := .T.

Private lEnd
:= .F.
Private lAbortPrint
:= .F.
Private aReturn
:= { "Zebrado", 1, "Administracao", 2, 2, 1, "", 1}
//aReturn[4] 1- Retrato, 2- Paisagem
//aReturn[5] 1- Em Disco, 2- Via Spool, 3- Direto na Porta, 4- Email
Private nLastKey
Private m_pag
Private wnrel
:= 0
:= 01
:= "MPTR002"
dbSelectArea("SA1")
dbSetOrder(1)
//
// Monta a interface padrao com o usuario...
//
wnrel :=
SetPrint(cString,cNomeProg,cPerg,@cTitulo,cDesc1,cDesc2,cDesc3,lDic,aOrd,lCompre
s,cTamanho,,lFilter)
If nLastKey == 27
Return
Endif
SetDefault(aReturn,cString,,,cTamanho,aReturn[4]) // nFormato: 1- Retrato, 2Paisagem
If nLastKey == 27
Return
Endif
nTipo := IIF(aReturn[4]==1,15,18)
//
// Processamento. RPTSTATUS monta janela com a regua de processamento.
//
RptStatus({||
RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)},cTitulo)
Return
/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor | -------------------- | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/

Tel: 11 50114895 / 50116082 / 98081988
SP
125
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)

Local
Local
Local
Local
nLin
cCabec1
cCabec2
cArqInd
cCabec1
cCabec1
cCabec1
cCabec2
:=
+=
+=
:=
:= 80
:= ""
:= ""
"CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME REDUZIDO"+Space(9)
"RAZAO SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
"CEP"
"ESTADO"+Space(2)+"MUNICIPIO"+Space(8)+"ENDERECO"
dbSelectArea("TRBSA1")
dbGoTop()
SetRegua(RecCount())
While !EOF()
If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
Exit
Endif
If nLin > 55 // Salto de Pgina. Neste caso o formulario tem 55 linhas...
Cabec(cTitulo,cCabec1,cCabec2,cNomeProg,cTamanho,nTipo)
nLin := 9
Endif
...
IMPCADAST()
A funo IMPCADAST() cria uma interface simples que permite a impresso dos cadastros do
sistema com parametrizao DE/ATE.
Sintaxe: IMPCADAST(cCab1, cCab2, cCab3, cNomeProg, cTam, nLimite, cAlias)
Parmetros:
cCab1
Primeira linha do cabealho
cCab2
Segunda linha do cabealho
cCab3
Terceira linha do cabealho
cNomeProg
Nome do programa
cTam
Tamanho do relatrio nos formatos P, M e G.
nLimite
Nmero de colunas do relatrio, seguindo o formato especificado no

tamanho, aonde:
P- 80 colunas
M- 132 colunas
G- 220 colunas
Alias do arquivo de cadastro que ser impresso
cAlias

Tel: 11 50114895 / 50116082 / 98081988
SP
126
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Nenhum
MS_FLUSH()
A funo MS_FLUSH() envia o spool de impresso para o dispositivo previamente especificado
com a utilizao das funes AVALIMP() ou SETPRINT().
Sintaxe: MS_FLUSH()
Parmetros:
Nenhum
Retorno:
Nenhum
Exemplo:
/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor |
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------| Observao| Continuao do exemplo da funo CABEC()
|
|+---------------------------------------------------------------------------/*/
Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)
Local
Local
Local
Local
nLin
cCabec1
cCabec2
cArqInd
cCabec1
cCabec1
cCabec1
cCabec2
:=
+=
+=
:=
:= 80
:= ""
:= ""
"CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME REDUZIDO"+Space(9)
"RAZAO SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
"CEP"
"ESTADO"+Space(2)+"MUNICIPIO"+Space(8)+"ENDERECO"
dbSelectArea("TRBSA1")
dbGoTop()
SetRegua(RecCount())
While !EOF()
If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
Tel: 11 50114895 / 50116082 / 98081988
SP
127
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Exit
Endif
If nLin > 55 // Salto de Pgina. Neste caso o formulario tem 55 linhas...
Cabec(cTitulo,cCabec1,cCabec2,cNomeProg,cTamanho,nTipo)
nLin := 9
Endif
// Primeira linha de detalhe:
@nLin,000 PSAY TRBSA1->A1_COD
@nLin,008 PSAY TRBSA1->A1_LOJA
@nLin,014 PSAY TRBSA1->A1_NREDUZ
@nLin,036 PSAY TRBSA1->A1_NOME
@nLin,078 PSAY TRBSA1->A1_CGC
@nLin,100 PSAY TRBSA1->A1_INSCR
@nLin,122 PSAY TRBSA1->A1_CEP
nLin++
// Segunda linha de detalhe
@nLin,000 PSAY TRBSA1->A1_EST
@nLin,008 PSAY TRBSA1->A1_MUN
@nLin,025 PSAY TRBSA1->A1_END
nLin++
//Linha separadora de detalhes
@nLin,000 PSAY Replicate("-",nLimite)
nLin++
dbSkip() // Avanca o ponteiro do registro no arquivo
EndDo
SET DEVICE TO SCREEN
If aReturn[5]==1
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif
MS_FLUSH()
RETURN
OURSPOOL()
A funo OURSPOOL() executa o gerenciador de impresso da aplicao Protheus, permitindo
a visualizao do arquivo de impresso gerado pelo relatrio no formato PostScrip com
extenso ##R.
Sintaxe: OURSPOOL(cArquivo)
Parmetros:
cArquivo
Nome do relatrio a ser visualizado.

Tel: 11 50114895 / 50116082 / 98081988
SP
128
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Exemplo:
If aReturn[5]==1 // Indica impresso em disco.
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif
RODA()
A funo RODA() imprime o rodap da pgina do relatrio, o que pode ser feito a cada pgina,
ou somente ao final da impresso.
Pode ser utilizado o ponto de entrada "RodaEsp" para tratamento de
uma impresso especfica.
Sintaxe: Roda(uPar01, uPar02, cSize)
Parmetros:
uPar01
No mais utilizado
uPar02
No mais utilizado
cSize
Tamanho do relatrio (P,M,G)
Retorno:
Nenhum
Exemplo:
/*/
+----------------------------------------------------------------------------| Funo
| TESTIMPR
| Autor |
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo RODA() em conjunto com a CABEC.|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
#include "protheus.ch"
User Function TestImpr()
Local wnrel
Local cString := "SA1"
Local titulo
:= "Teste Impresso de Relatorios"
Tel: 11 50114895 / 50116082 / 98081988
SP
129
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Local NomeProg := "XXX"

Local Tamanho := "M"
PRIVATE aReturn := { "Zebrado", 1,"Administracao", 1, 2, 1, "",1 }
wnrel:=SetPrint(cString,NomeProg,"",@titulo,"", "", "",.F.,.F.,.F.,Tamanho,,.F.)
SetDefault(aReturn,cString)
RptStatus({|lEnd| TestRel(@lEnd,wnRel,cString,Tamanho,NomeProg)},titulo)
Return
/*/
+----------------------------------------------------------------------------| Funo
| TESTREL
| Autor |
| Data |
|
+----------------------------------------------------------------------------| Descrio | Funo interna de impresso da TestImpr().
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
User Function TestRel(lEnd,WnRel,cString,Tamanho,NomeProg)
LOCAL
LOCAL
Local
Local
cabec1,cabec2
cRodaTxt := oemtoansi("Rodap")
nCntImpr
nTipo
nCntImpr := 0
li := 80
m_pag := 1
nTipo := 15
titulo:= oemtoansi("Lista de Clientes")
cabec1:= oemtoansi("COD LOJA NOME"+Space(27)+ "NOME FANTASIA")
cabec2:=""
dbSelectArea("SA1")
dbGoTop()
SetRegua(LastRec())
While !Eof()
IncRegua()
If Li > 60
cabec(titulo,cabec1,cabec2,nomeprog,tamanho,15)
@ Li,0 PSAY __PrtThinLine()
Endif
nCntImpr++
Li++
@ Li,01 PSAY A1_COD
@ Li,05 PSAY A1_LOJA
@ Li,10 PSAY A1_NOME
@ Li,51 PSAY A1_NREDUZ
If Li > 60
Li:=66
Endif
dbSkip()
EndDO
Tel: 11 50114895 / 50116082 / 98081988
SP
130
ADVPL
GUIA DE REFERNCIA
Escola conveniada
If li != 80
Roda(nCntImpr,cRodaTxt,Tamanho)
EndIf
Set Device to Screen
If aReturn[5] = 1
Set Printer To
dbCommitAll()
OurSpool(wnrel)
Endif
MS_FLUSH()
Return
SETDEFAULT()
A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes
configuradas no array aReturn, obtidas atravs da funo SetPrint().
Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] , [cSize] ,
[ nFormat ] )
Parmetros:
aReturn
Configuraes de impresso.
cAlias
Alias do arquivo a ser impresso.
uParm3
Parmetro reservado.
uParm4
Parmetro reservado.
cSize
Tamanho da pgina "P","M" ou "G"
nFormat
Formato da pgina, 1 retrato e 2 paisagem.
Retorno:
Nenhum
Estrutura aReturn:
aReturn[1]
Caracter, tipo do formulrio
aReturn[2]
Numrico, opo de margem
aReturn[3]
Caracter, destinatrio
aReturn[4]
Numrico, formato da impresso
aReturn[5]
Numrico, dispositivo de impresso
aReturn[6]
Caracter, driver do dispositivo de impresso
aReturn[7]
Caracter, filtro definido pelo usurio
aReturn[8]
Numrico, ordem
aReturn[x]
A partir a posio [9] devem ser informados os nomes dos campos que
devem ser considerados no processamento, definidos pelo uso da opo
Dicionrio da SetPrint().

Tel: 11 50114895 / 50116082 / 98081988
SP
131
ADVPL
GUIA DE REFERNCIA
Escola conveniada

Tel: 11 50114895 / 50116082 / 98081988
SP
132
ADVPL
GUIA DE REFERNCIA
Escola conveniada
SETPRC()
A funo SETPRC() utilizada para posicionar o dispositivo de impresso ativo, previamente
definido pelo uso das funes AVALIMP() ou SETPRINT() , em uma linha/coluna especificada.
Sintaxe: SETPRC(nLinha, nColuna)
Parmetros:
nLinha
Linha na qual dever ser posicionado o dispositivo de impresso.
nColuna
Coluna na qual dever ser posicionado o dispositivo de impresso.
Retorno:
Nenhum
Exemplo:
aReturn := { "", 1, "" , 2, 3, cPorta , "",IndexOrd() }
SetPrint(Alias(),"","","",,,,.F.,,,,,,,'EPSON.DRV',.T.,,cPorta)
if nLastKey == 27
Return (.F.)
Endif
SetDefault(aReturn,Alias())
SetPrc(0,0)
SETPRINT()
A funo SetPrint() cria uma interface padro onde as opes de impresso de um relatrio
podem ser configuradas. Basicamente duas variveis m_pag e aReturn precisam ser
declaradas como privadas (private) antes de executar a SetPrint(), sendo que:
m_pag: controla o nmero de pginas.

aReturn: vetor contendo as opes de impresso, sendo sua estrutura bsica
composta de 8 (oito) elementos.
Aps confirmada, os dados so armazenados no vetor aReturn que ser passado como
parmetro para funo SetDefault().
Sintaxe: SetPrint ( < cAlias > , < cProgram > , [ cPergunte ] , [ cTitle ] ,
[ cDesc1 ] , [ cDesc2 ] , [ cDesc3 ] , [ lDic ] , [ aOrd ] , [ lCompres ] , [ cSize ] ,
[ uParm12 ] , [ lFilter ] , [ lCrystal ] , [ cNameDrv ] , [ uParm16 ] , [ lServer ] ,
[ cPortPrint ] ) --> cReturn
Parmetros:
cAlias
Alias do arquivo a ser impresso.
cProgram
Nome do arquivo a ser gerado em disco.
cPergunte
Grupo de perguntas cadastrado no dicionrio SX1.

Tel: 11 50114895 / 50116082 / 98081988
SP
133
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cTitle
Ttulo do relatrio.
Parmetros (continuao):
cDesc1
Descrio do relatrio.
cDesc2
Continuao da descrio do relatrio.
cDesc3
Continuao da descrio do relatrio.

Utilizado na impresso de cadastro genrico permite a escolha dos campos a
serem impressos. Se o parametro cAlias no for informado o valor padro
assumido ser .F.
Ordem(s) de impresso.
Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro
assumido ser .T.
Tamanho do relatrio "P","M" ou "G".
lDic
aOrd
lCompres
cSize
uParm12
cNameDrv
Parmetro reservado
Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro
assumido ser .T.
Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro
assumido ser .F.
Nome de um driver de impresso.
uParm16
Parmetro reservado.
lServer
Se verdadeiro (.T.) fora impresso no servidor.
cPortPrint
Define uma porta de impresso padro.
lFilter
lCrystal
Retorno:
Caracter
Nome do Relatrio
Estrutura aReturn:
aReturn[1]
Caracter, tipo do formulrio
aReturn[2]
Numrico, opo de margem
aReturn[3]
Caracter, destinatrio
aReturn[4]
Numrico, formato da impresso
aReturn[5]
Numrico, dispositivo de impresso
aReturn[6]
Caracter, driver do dispositivo de impresso
aReturn[7]
Caracter, filtro definido pelo usurio
aReturn[8]
Numrico, ordem
aReturn[x]
A partir a posio [9] devem ser informados os nomes dos campos que
devem ser considerados no processamento, definidos pelo uso da opo
Dicionrio da SetPrint().

Tel: 11 50114895 / 50116082 / 98081988
SP
134
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Controle de processamentos
ABREEXCL()
A funo ABREEXCL() fecha o arquivo cujo alias est expresso em <cAlias> e o reabre em
modo exclusivo para proceder operaes em que isto necessrio, como por exemplo, PACK.
Se outra estao estiver usando o arquivo, o retorno ser .F..
Sintaxe: ABREEXCL(cAlias)
Parmetros:
cAlias
Alias do arquivo que ser re-aberto em modo exclusivo.
Retorno:
Lgico
Indica se foi possvel abrir o arquivo em modo exclusivo.
CLOSEOPEN()
A funo CLOSEOPEN() utilizada para fechar e re-abrir uma lista de arquivos especificada.
Sintaxe: CLOSEOPEN(aClose, aOpen)
Parmetros:
aClose
Array contendo os Aliases dos arquivos que devero ser fechados.
aOpen
Array contendo os Aliases dos arquivos que devero ser abertos.
Retorno:
Lgico
Indica se todos os arquivos especificados em aOpen foram abertos com

sucesso.
CLOSESFILE()
A funo CLOSESFILE() fecha todos os arquivos em uso pela conexo, com exceo dos SXs
(inclusive SIX), SM2 e SM4.
Sintaxe: CLOSESFILE(cAlias)
Parmetros:
cAlias
String contendo os nomes dos demais Aliases que no devero ser fechados,
separando os itens com /.
Retorno:

Tel: 11 50114895 / 50116082 / 98081988
SP
135
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Lgico
Indica se todos os arquivos foram fechados com sucesso.
CHKFILE()
A funo CHKFILE() retorna verdadeiro (.T.) se o arquivo j estiver aberto ou se o Alias no for
informado. Sempre que desejar mudar o modo de acesso do arquivo (de compartilhado para
exclusivo ou vice-versa), feche-o antes de cham-la.
Sintaxe: ChkFile(cAlias,lExcl,cNewAlias)
Parmetros:
cAlias
Alias do arquivo a ser re-aberto.
lExcl
Se for informado verdadeiro (.T.), o arquivo ser aberto em modo

exclusivo, caso contrrio, o arquivo ser aberto em modo compartilhado.
Se este parmetro no for informado, ser assumido falso (.F.).
Novo Alias para re-abertura do arquivo.
cNewAlias
Retorno:
Lgico
Indica se o arquivo foi re-aberto com sucesso.
Exemplo:
dbSelectArea(SA1)
dbCloseArea()
lOk := .T.
While .T.
IF !ChkFile(SA1,.T.)
nResp := Alert(Outro usurio usando! Tenta de novo?,{Sim,Nao})
If nResp == 2
lOk := .F.
Exit
Endif
Endif
EndDo
If lOk
// Faz o processamento com o arquivo...
Endif
// Finaliza
If Select(SA1)
dbCloseArea()
Endif
ChkFile(SA1,.F.)
Return
CONOUT()

Tel: 11 50114895 / 50116082 / 98081988
SP
136
ADVPL
GUIA DE REFERNCIA
Escola conveniada
A funo CONOUT() permite a exibio de uma mensagem de texto no console do Server do

Protheus. Caso o Protheus esteja configurado como servio a mensagem ser gravada no
arquivo de log.
Sintaxe: CONOUT(cMensagem)
Parmetros:
cMensagem
String contendo a mensagem que dever ser exibida no console do

Protheus.
Retorno:
Nenhum
CRIAVAR()
A funo CRIAVAR() cria uma varivel, retornando o valor do campo, de acordo com o
dicionrio de dados, inclusive avaliando o inicializador padro, permitindo um retorno de
acordo com o tipo de dado definido no dicionrio.
Sintaxe: CriaVar(cCampo,lIniPad,cLado)
Parmetros:
cCampo
Nome do campo
lIniPad
Indica se considera (.T.) ou no (.F.) o inicializador
cLado
Se a varivel for caracter, cLado pode ser: C - centralizado, L

- esquerdo ou R direito.
Retorno:
Indefinido
Tipo de dado de acordo com o dicionrio de dados, considerando inicializador

padro
Exemplo:
// Exemplo do uso da funo CriaVar:
cNumNota := CriaVar(F2_DOC) // Retorna o contedo do
// inicializador padro,
// se existir, ou espaos em branco
Alert(cNumNota)
Return
DISARMTRANSACTION()
A funo DISARMTRANSATCION() utilizada para realizar um RollBack de uma transao
aberta com o comando BEGIN TRANSACTION e delimitada com o comando END
TRANSACTION.

Tel: 11 50114895 / 50116082 / 98081988
SP
137
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Ao utilizar esta funo, todas as alteraes realizadas no intervalo delimitado pela transao
so desfeitas, restaurando a situao da base de dados ao ponto imediatamente anterior ao
incio do processamento.
O uso da funo DISARMTRANSACTION() no finaliza a conexo ou o
processamento corrente.
Caso seja necessrio alm de desfazer as alteraes,
processamento, dever ser utilizada a funo USEREXCEPTION().
Sintaxe: DISARMTRANSACTION()
Parmetros:
Nenhum
finalizar
Retorno:
Nenhum
Exemplo:
lMsErroAuto := .F.
MSExecAuto({|x,y| MATA240(x,y)}, aCampos, 3)
If lMsErroAuto
aAutoErro := GETAUTOGRLOG()
DisarmTransaction()
MostraErro()
EndIf
EXECBLOCK()
A funo EXECBLOCK() executa uma funo de usurio que esteja compilada no repositrio.
Esta funo normalmente utilizada pelas rotinas padres da aplicao Protheus para executar
pontos de entrada durante seu processamento.
A funo de usurio executada atravs da EXECBLOCK() no recebe
parmetros diretamente, sendo que estes estaro disponveis em uma varivel
private denominada PARAMIXB.
A varivel PARAMIXB o reflexo do parmetro xParam, definido na execuo

da funo EXECBLOCK(). Caso seja necessria a passagem de vrias
informaes, as mesmas devero ser definidas na forma de um array,
tornando PARAMIXB um array tambm, a ser tratado na funo de usurio
que ser executada.
Tel: 11 50114895 / 50116082 / 98081988
SP
138
ADVPL
GUIA DE REFERNCIA
Escola conveniada
EXISTBLOCK()
A funo EXISTBLOCK() verifica a existncia de uma funo de usurio compilada no
repositrio de objetos da aplicao Protheus. Esta funo normalmente utilizada nas rotinas
padres da apliao Protheus para determinar a existncia de um ponto de entrada e permitir
sua posterior execuo.
Sintaxe: EXISTBLOCK(cFuno)
Parmetros:
cFuno
Nome da funo que ser avaliada.
Retorno:
Lgico
Indica se a funo de usurio existe compilada no repositrio de objetos

corrente.
Exemplo:
IF EXISTBLOCK(MT100GRV)
EXECBLOCK(MT100GRV,.F.,.F.,aParam)
ENDIF
Sintaxe: EXECBLOCK(cFuno, lReserv1, lReserv2, xParam)
Parmetros:
cFuno
Nome da funo de usurio que ser executada.
lReserv1
Parmetro de uso reservado da aplicao. Definir como .F.
lReserv2
Parmetro de uso reservado da aplicao. Definir como .F.
xParam
Contedo que ficar disponvel na funo de usurio executada, na forma da

varivel private PARAMIXB.
Retorno:
Indefinido
O retorno da EXECBLOCK() definido pela funo que ser executada.
Exemplo:
aParam := {cNota, cSerie, cFornece, cLoja)
IF EXISTBLOCK(MT100GRV)
lGravou := EXECBLOCK(MT100GRV,.F.,.F.,aParam)
ENDIF
USER FUNCTION MT100GRV()
Tel: 11 50114895 / 50116082 / 98081988
SP
139
ADVPL
GUIA DE REFERNCIA
Escola conveniada
LOCAL
LOCAL
LOCAL
LOCAL
cNota := PARAMIXB[1]
cSerie:= PARAMIXB[1]
cFornece:= PARAMIXB[1]
cLoja:= PARAMIXB[1]
RETURN .T.
ERRORBLOCK()
A funo ERRORBLOCK() efetua o tratamento de erros e define a atuao de um handler de
erros sempre que ocorrer um erro em tempo de execuao. O manipulador de erros
especificado como um bloco de cdigo da seguinte forma:
{ |<objError>| <lista de expressoes>, ... }, onde:
<objError> um error object que contm informaoes sobre o erro.Dentro do bloco de cdigo,
podem ser enviadas mensagens ao error object para obter informaoes sobre o erro. Se o
bloco de tratamento de erros retornar verdadeiro (.T.), a operaao que falhou repetida, e se
retornar falso (.F.), o processamento recomea.
Se nao foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer um erro
em tempo de execuao, o bloco de tratamento ao de erros padrao avaliado. Este
manipulador de erros exibe uma mensagem descritiva na tela, ajusta a funao ERRORLEVEL()
para 1, e depois sai do programa (QUIT).
Como ERRORBLOCK() retorna o bloco de tratamento ao de erros corrente, possvel
especificar um bloco de tratamento de erros para uma operaao gravando-se o bloco de
manipulaao de erros corrente e depois recuperando-o aps o final da operaao. Alm disso,
uma importante consequncia do fato de os blocos de tratamento de erros serem especificados
como blocos de cdigo, que eles podem ser passados pararotinas e funoes definidas por
usurio e depois retornadas como valores.
Sintaxe: ERRORBLOCK ( < bErrorHandler > )

Parmetros:
bErrorHandler
O bloco de cdigo a ser executado toda vez que

ocorrer um erro em tempo de execuao.
Quando avaliado, o <bErrorHandler> passado na forma de um objeto
erro como um argumento pelo sistema.
Retorno:
Code-block
Retorna o bloco de cdigo corrente que tratar o erro. Caso nao tenha sido
enviado nenhum bloco de tratamento de erro desde que o programa foi
invocado, ERRORBLOCK() retorna o bloco de tratamento de erro padrao.
Exemplo:
Function CA010Form()
LOCAL xResult
LOCAL cForm:= Upper(&(ReadVar()))
LOCAL bBlock:= ErrorBlock( { |e| ChecErro(e) } )
LOCAL cOutMod
Tel: 11 50114895 / 50116082 / 98081988
SP
140
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Local lOptimize := GetNewPar("MV_OPTNFE",.F.) .Or. GetNewPar("MV_OPTNFS",.F.)

PRIVATE lRet:=.T.
cVarOutMod := If(Type("cVarOutMod") = "U", "", cVarOutMod)
cOutMod
:= cVarOutMod + If(Right(cVarOutMod, 1) = ",", "", ",")
While ! Empty(cOutMod)
If Left(cOutMod, At(",", cOutMod) - 1) $ Upper(cForm)
// no modulo
Help( " ",1,"ERR_FORM,,"Variavel nao disponivel para este modulo"
Return .F.
Endif
cOutMod := Subs(cOutMod, At(",", cOutMod) + 1)
EndDo
If ("LERSTR"$cForm .or. "LERVAL"$cForm .or. "LERDATA"$cForm) .And. M->I5_CODIGO >
"499"
Help( " ",1,"CA010TXT")
ErrorBlock(bBlock)
Return .F.
Endif
BEGIN SEQUENCE
If !"EXECBLOCK"$cForm .and. !"LERSTR"$cForm .And.; // nao executa execblock
!"LERVAL"$cForm .And.;
// nem funcao de leitura
!"LERDATA"$cForm .And.;
// de texto no cadastramento
IIf(!lOptimize,.T.,!"CTBANFS"$cForm .And. !"CTBANFE"$cForm)
xResult := &cForm
Endif
END SEQUENCE
ErrorBlock(bBlock)
Return lRet
FINAL()
A funo FINAL() executa as operaes bsicas que garantem a integridade dos dados ao
finalizar o sistema desmontando as transaes (se houver), desbloqueando os semforos e
fechando as tabelas abertas, finalizando-o em seguinda.
Sintaxe: Final( [cMensagem1], [cMensagem2] )
Parmetros:
cMensagem1
Primeira mensagem
cMensagem2
Segunda mensagem
Retorno:
Nenhum
Exemplo:
User Function ValidUser( cUsuario, cSenha )
Tel: 11 50114895 / 50116082 / 98081988
SP
141
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Local cMensag1 := Usurio invalido!

Local cMensag2 := Opo disponvel para usurios Adminstradores!
If !PswAdmin( cUsuario, cSenha )
Final( cMensag1, cMensag2 )
EndIf
Return
FINDFUNCTION()
A funo FINDFUNCTION() tem como objetivo verificar se uma determinada funo se
encontra no repositrio de objetos e at mesmo do binrio do Protheus, sendo uma funo
bsica da linguagem.
Sintaxe: FINDFUNCTION(cFuno)
Parmetros:
cFuno
Nome da funo que ser avaliada no repositrio de objetos corrente.
Retorno:
Lgico
Indica se a funo existe compilada no repositrio de objetos corrente.
FUNDESC()
A funo FunDesc() retornar a descrio de uma opo selecionada no menu da aplicao.
Sintaxe: FUNDESC()
Parmetros:
Nenhum
Retorno:
Caracter
Descrio da opo selecionada no menu da aplicao.
FUNNAME()
A funo FunName() retornar o nome de uma funo executada a partir de um menu da
aplicao.
Sintaxe: FUNNAME()
Parmetros:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
142
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Caracter
Nome da funo executada a partir do menu da aplicao.
GETAREA()
Funo utilizada para proteger o ambiente ativo no momento de algum processamento
especfico. Para salvar uma outra rea de trabalho (alias) que no o ativo, a funo GetArea()
deve ser executada dentro do alias: ALIAS->(GetArea()).
Sintaxe: GETAREA()
Retorno: Array contendo {Alias(),IndexOrd(),Recno()}
Parmetros
Nenhum
GETCOUNTRYLIST()
A funo GETCOUNTRYLIST() retorna um array de duas dimenses contendo informaes dos
pases localizados.
Sintaxe: GetCountryList()
Parmetros:
Nenhum
Retorno:
Array
Array de duas dimenses, sendo uma linha para cada pas localizado,
contendo em cada posio a sigla dos pases, o nome do pas e a
identificao do pas com dois dgitos.
Exemplo:
Local aArray := GetCountryList()
Local cSigla := GetMv( MV_PAISLOC )
Local nPos
nPos := Ascan( aArray, {|d| d[1] == Upper(cSigla) } )
If nPos > 0
APMsgInfo( Pas de localizao + aArray[nPos,2] )
EndIf
ISINCALLSTACK()

Tel: 11 50114895 / 50116082 / 98081988
SP
143
ADVPL
GUIA DE REFERNCIA
Escola conveniada
A funo ISINCALLSTACK() verifica se uma determinada funo est existe dentro da pilha de
chamadas do processamento corrente.
Sintaxe: IsInCallStack( cIsInCallStack , cStackExit )
Parmetros:
cIsInCallStack
Nome da funo que desejasse pesquisar na pilha.
cStackExit
String que identifica o ponto em que desejasse finalizar a busca. Caso

no seja informada, ser utilizada como padro a expresso
"STACK_EXIT".
Retorno:
Lgico
Indica se a funo especificada encontrasse na pilha de chamadas do

processsamento corrente, at o ponto de sada especificado.
REGTOMEMORY()
Inicializa as variveis de memria identificadas pelo uso do alias M-> de acordo com a
estrutura e/ou informaes contidas no arquivo definido como referncia.
Sintaxe: REGTOMEMORY(cAlias, lInclui)
Parmetros:
cAlias
lInclui
Alias do arquivo que ser utilizado como referncia para inicializao das
variveis de memria.
Identifica se as variveis devero ser inicializadas com contedos padres,
ou contendo as informaes do registro posicionado do alias especificado.
Retorno:
Nenhum
RESTAREA()
Funo utilizada para devolver a situao do ambiente salva atravs do comando GETAREA().
Deve-se observar que a ltima rea restaurada a rea que ficar ativa para a aplicao.
Sintaxe: RESTAREA(aArea)
Parmetros
aArea
Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo

uso da funo GetArea().
Exemplo:
// ALIAS ATIVO ANTES DA EXECUO DA ROTINA SN3
User Function XATF001()
Tel: 11 50114895 / 50116082 / 98081988
SP
144
ADVPL
GUIA DE REFERNCIA
Escola conveniada
LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.
cVar := &(ReadVar())
dbSelectArea("SX5")
IF !dbSeek(xFilial()+"Z1"+cVar)
cSTR0001 := "REAV - Tipo de Reavaliacao"
cSTR0002 := "Informe um tipo de reavalicao valido"
cSTR0003 := "Continuar"
Aviso(cSTR0001,cSTR0002,{cSTR0003},2)
lRet := .F.
ENDIF
RestArea(aArea)
Return( lRet )
USEREXCEPTION()
A funo USEREXCEPTION() tem o objetivo de forar um erro em ADVPL de forma que
possamos tratar de alguma forma. USEREXCEPTION() recebe uma string contendo uma
descrio do erro, essa descrio ser exibida de acordo com o ambiente que se est
executando, caso um ambiente ERP, ser exibida uma tela de erro.
Sintaxe: USEREXCEPTION(cMensagem)
Parmetros:
cMensagem
Mensagem que ser exibida no cabealho do erro, contendo a explicao da

exceo.
Retorno:
Nenhum
Utilizao de recursos do ambiente ERP

AJUSTASX1()
A funo AJUSTASX1() permite a incluso simultnea de vrios itens de perguntas para um
grupo de perguntas no SX1 da empresa ativa.
Sintaxe: AJUSTASX1(cPerg, aPergs)
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
145
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cPerg
Grupo de perguntas do SX1 (X1_GRUPO)
aPergs
Array contendo a estrutura dos campos que sero gravados no SX1.
Retorno:
Nenhum
Estrutura Item do array aPerg:

Posio
01
02
03
04
Campo
X1_PERGUNT
X1_PERSPA
X1_PERENG
X1_VARIAVL
Tipo
Caractere
Caractere
Caractere
Caractere
05
06
07
X1_TIPO
X1_TAMANHO
X1_DECIMAL
Caractere
Numrico
Numrico
08
X1_PRESEL
Numrico
09
X1_GSC
Caractere
10
11
X1_VALID
X1_VAR01
Caractere
Caractere
12
X1_DEF01
Caractere
13
14
15
X1_DEFSPA1
X1_DEFENG1
X1_CNT01
Caractere
Caractere
Caractere
16
17
X1_VAR02
X1_DEF02
Caractere
Caractere
18
19
20
21
22
X1_DEFSPA2
X1_DEFENG2
X1_CNT02
X1_VAR03
X1_DEF03
Caractere
Caractere
Caractere
Caractere
Caractere
Descrio
Descrio da pergunta em portugus
Descrio da pergunta em espanhol
Descrio da pergunta em ingls
Nome da varivel de controle auxiliar
(mv_ch)
Tipo do parmetro
Tamanho do contedo do parmetro
Nmero de decimais para contedos
numricos
Define qual opo do combo a padro para
o parmetro.
Define se a pergunta ser do tipo G Get ou
C Choice (combo)
Expresso de validao do parmetro
Nome da varivel MV_PAR+Ordem do
parmetro
Descrio da opo 1 do combo em
portugus
Descrio da opo 1 do combo em espanhol
Descrio da opo 1 do combo em ingls
Contedo padro ou ultimo contedo
definido como respostas para a pergunta.
No informado
Descrio da opo X do combo em
portugus
Descrio da opo X do combo em espanhol
Descrio da opo X do combo em ingls
No informado
No informado
portugus
Estrutura Item do array aPerg (continuao):

23
24
25
26
27
X1_DEFSPA3
X1_DEFENG3
X1_CNT03
X1_VAR04
X1_DEF04
Caractere
Caractere
Caractere
Caractere
Caractere
28
29
30
X1_DEFSPA4
X1_DEFENG4
X1_CNT04
Caractere
Caractere
Caractere
Descrio da opo
Descrio da opo
No informado
No informado
Descrio da opo
portugus
Descrio da opo
Descrio da opo
No informado
X do combo em espanhol
X do combo em ingls
X do combo em
X do combo em espanhol
X do combo em ingls

Tel: 11 50114895 / 50116082 / 98081988
SP
146
ADVPL
GUIA DE REFERNCIA
Escola conveniada
31
32
X1_VAR05
X1_DEF05
Caractere
Caractere
33
34
35
36
X1_DEFSPA5
X1_DEFENG5
X1_CNT05
X1_F3
Caractere
Caractere
Caractere
Caractere
37
X1_GRPSXG
Caractere
38
X1_PYME
Caractere
39
40
X1_HELP
X1_PICTURE
Caractere
Caractere
41
aHelpPor
Array
42
aHelpEng
Array
43
aHelpSpa
Array
No informado
portugus
No informado
Cdigo da consulta F3 vinculada ao
parmetro
Cdigo do grupo de campos SXG para
atualizao automtica, quando o grupo for
alterado.
Se a pergunta estar disponvel no ambiente
Pyme
Contedo do campo X1_HELP
Picture de formatao do contedo do
campo.
Vetor simples contendo as linhas de help em
portugus para o parmetro. Trabalhar com
linhas de at 40 caracteres.
ingls para o parmetro. Trabalhar com
espanhol para o parmetro. Trabalhar com
ALLUSERS()
A funo ALLUSERS() retorna um array multidimensional contendo as informaes dos
usurios do sistema.
Sintaxe: ALLUSERS()
Parmetros:
Nenhum
Retorno:
Array
Array multidimensional contendo as informaes dos usurios do sistema,

aonde para cada usurio sero demonstradas as seguintes informaes:
aArray[x][1] Configuraes gerais de acesso
aArray[x][2] Configuraes de impresso
aArray[x][3] Condiguraes de acesso aos mdulos
Array de informaes dos usurios: Configuraes gerais de acesso

Elemento
1
1
Descrio
Tipo
ID
Qtd.
6

Tel: 11 50114895 / 50116082 / 98081988
SP
147
ADVPL
GUIA DE REFERNCIA
Escola conveniada
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
C
C
C
A
D
N
L
L
A
C
C
C
C
N
D
L
N
L
C
15
6
30
-8
4
1
1
-6
30
30
130
4
8
1
1
1
4
Array de informaes dos usurios: Configuraes de impresso

Elemento
2
1
2
3
4
5
6
7
8
9
10
11
12
13
Nome
Senha
Nome Completo
Vetor com n ltimas senhas
Data de validade
Quantas vezes para expirar
Autorizado a alterar a senha
Alterar a senha no prximo logon
Vetor com os grupos
ID do superior
Departamento
Cargo
E-Mail
Nmero de acessos simultneos
Data da ltima alterao
Usurio bloqueado
Nmero de dgitos para o ano
Listner de ligaes
Ramal
Descrio
Tipo
Qtd.
Vetor com horrios de acesso

Idioma
Diretrio
Impressora
Acessos
Vetor com empresas
Ponto de entrada
Tipo de impresso
Formato
Ambiente
Prioridade p/ config. do grupo
Opo de impresso
Acesso a outros dir de
impresso
A
N
C
C
C
A
C
N
N
N
L
C
L
-1
100
-512
-10
1
1
1
1
50
1
Array de informaes dos usurios: Configuraes de acesso aos mdulos

Elemento
3
1
Descrio
Tipo
Mdulo+nvel+menu
Qtd.

Tel: 11 50114895 / 50116082 / 98081988
SP
148
ADVPL
GUIA DE REFERNCIA
Escola conveniada
ALLGROUPS()
A funo ALLGROUPS() retorna um array multidimensional contendo as informaes dos
grupos de usurios do sistema.
Sintaxe: ALLGROUPS()
Parmetros:
Nenhum
Retorno:
Array
Array multidimensional contendo as informaes dos grupos de usurios do

sistema, aonde para cada grupo sero demonstradas as seguintes
informaes:
aArray[x][1] Configuraes gerais de acesso
aArray[x][2] Configuraes de acesso aos mdulos
Array de informaes dos grupos: Configuraes gerais de acesso

Elemento
1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Descrio
Tipo
Qtd.
ID
Nome
Vetor com horrios de acesso
Data de validade
Quantas vezes para expirar
Autorizado a alterar a senha
Idioma
Diretrio
Impressora
Acessos
Vetor com empresas
Data da ltima alterao
Tipo de impresso
Formato
Ambiente
Opo de impresso
Acesso a outros Dir de impresso
C
C
A
D
N
L
N
C
C
C
A
D
N
N
N
L
L
6
20
8
4
1
1
100
512
8
1
1
1
1
1
Array de informaes dos grupos: Configuraes de acesso aos mdulos

Elemento
2
1
Descrio
Tipo
Modulo+nvel+menu
Qtd.

Tel: 11 50114895 / 50116082 / 98081988
SP
149
ADVPL
GUIA DE REFERNCIA
Escola conveniada
CGC()
A funo CGC() valida o CGC digitado, utilizando o algoritmo nacional para verificao do dgito
de controle.
Sintaxe: CGC(cCGC)
Parmetros:
cCGC
String contendo o CGC a ser validado
Retorno:
Lgico
Indica se o CGC informado vlido.
CONPAD1()
A funo CONPAD1() exibe uma tela de consulta padro baseada no Dicionrio de Dados
(SXB).
Sintaxe: ConPad1 ( [uPar1] , [uPar2] , [uPar3] , cAlias , [cCampoRet]

[uPar4] , [lOnlyView] )
Parmetros:
uPar
Parmetro reservado.
uPar2
Parmetro reservado.
uPar3
Parmetro reservado.
cAlias
Consulta padro cadastrada no Dicionrio de Dados (SXB) a ser utilizada.
cCampoRet
Nome da varivel ou campo que receber o retorno da consulta padro.

Parmetro Reservado.
uPar4
lOnlyView
Indica se ser somente para visualizao.
Retorno:
Nenhum
DATAVALIDA()
A funo DATAVALIDA() retorna a primeira data vlida a partir de uma data especificada como
referncia, considerando inclusive a data informada para anlise.
Sintaxe: DATAVALIDA(dData)
Parmetros:
dData
Data a partir da qual ser avaliada a prxima data vlida, considerando-a

inclusive como uma possibilidade.

Tel: 11 50114895 / 50116082 / 98081988
SP
150
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
Data
Prxima data vlida, desconsiderando sbados, domingos e os feriados

cadastrados no sistema.
EXISTINI()
A funo EXISTINI() verifica se o campo possui inicializador padro.
Sintaxe: EXISTINI(cCampo)
Parmetros:
cCampo
Nome do campo para verificao.
Retorno:
Lgico
Indica se o campo possui um inicializador padro.
Exemplo:
// Exemplo de uso da funcao ExistIni:
// Se existir inicializador no campo B1_COD:
If ExistIni(B1_COD)
// Executa o inicializador:
cCod := CriaVar(B1_COD)
Endif
Return
EXTENSO()
A funo EXTENSO() retorna uma string referente a descrio por extenso de um valor
numrico, sendo comumente utilizada para impresso de cheques, valor de duplicatas, etc.
Sintaxe: Extenso(nValor, lQtd, nMoeda)
Parmetros:
nValor
Valor para gerao do extenso.
lQtd
Indica se o valor representa uma quantidade (.T.) ou dinheiro (.F.)
nMoeda
Para qual moeda do sistema deve ser o extenso.
Retorno:
String
Descrio do valor por extenso.
FORMULA()
Tel: 11 50114895 / 50116082 / 98081988
SP
151
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Interpreta uma frmula cadastrada. Esta funo interpreta uma frmula, previa-mente
cadastrada no Arquivo SM4 atravs do Mdulo Configurador, e retorna o resultado com tipo de
dado de acordo com a prpria frmula.
Sintaxe: Formula(cFormula)
Parmetros:
cFormula
Cdigo da frmula a ser avaliada e cadastrada no SM4 Cadastro de

Frmulas.
Retorno:
Indefinido
Resultado da interpretao da frmula cadastrada no SM4.
GETADVFVAL()
A funo GETADVFVAL() executa uma pesquisa em um arquivo pela chave de busca e na
ordem especificadas, possibilitando o retorno de um ou mais campos.
Sintaxe: GetAdvFVal(cAlias,uCpo,uChave,nOrder,uDef)
Parmetros:
cAlias
Alias do arquivo
uCpo
uChave
Nome de um campo ou array contendo os nomes dos campos

desejados
Chave para a pesquisa
nOrder
Ordem do ndice para a pesquisa
uDef
Valor ou array default para ser retornado caso a chave no seja encontrada
Retorno:
Indefinido
Retorna o contedo de um campo ou array com o contedo de vrios campos
A funo GETADVFVAL() difere da funo POSICIONE() apenas por permitir o

retorno de vrios campos em uma nica consulta.
As duas funes devem ser protegidas por GETAREA() / RESTAREA()
dependendo da aplicao.
HELP()
Esta funo exibe a ajuda especificada para o campo e permite sua edio. Se for
um help novo, escreve-se o texto em tempo de execuo.

Tel: 11 50114895 / 50116082 / 98081988
SP
152
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: Help(cHelp,nLinha, cTitulo, uPar4,cMensagem,nLinMen,nColMen)
Parmetros:
cHelp
Nome da Rotina chamadora do help. (sempre branco)
nLinha
Nmero da linha da rotina chamadora. (sempre 1)
cTitulo
Ttulo do help
uPar4
Sempre NIL
cMensagem
Mensagem a ser exibida para o Help.
nLinMen
Nmero de linhas da Mensagem. (relativa janela)
nColMen
Nmero de colunas da Mensagem. (relativa janela)
Retorno:
Nenhum
A funo HELP() tratada na execuo das rotinas com o recurso de

MSEXECAUTO(), permitindo a captura e exibio da mensagem no log de
processamento.
Por esta razo, em rotinas que podem ser chamadas atravs da funo
MSEXECAUTO() deve-se sempre utilizar avisos utilizando esta funo, para
que este tipo de processamento no seja travado indevidamente.
Exemplo:
IF lAuto // Se for rotina automtica
Help("ESPECIFICO",1,"HELP","PROCESSAMENTO","Parmetros do JOB Invlidos",1,0)
ELSE
MsgAlert(Parmetros do JOB Invlidos, PROCESSAMENTO)
ENDIF
MESEXTENSO()
A funo MESEXTENSO() retorna o nome de um ms por extenso.
Sintaxe: MESEXTENSO(nMes)
Parmetros:
nMes
Indica o nmero do ms a ter seu nome escrito por extenso.
Este parmetro pode ser definido tambm como caracter ou como data.

Tel: 11 50114895 / 50116082 / 98081988
SP
153
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Retorno:
String
Nome do ms indicado por extenso.
OBRIGATORIO()
A funo OBRIGATORIO() avalia se todos os campos obrigatrios de uma Enchoice() foram
digitados.
Sintaxe: OBRIGATORIO(aGets, aTela, aTitulos)
Parmetros:
aGets
aTela
aTitulos
Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no

fonte.
Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no
fonte.
Array contendo os ttulos dos campos exibidos na Enchoice().
Retorno:
Lgico
Indica se todos os campos obrigatrios foram preenchidos.
Exemplo:
#INCLUDE "protheus.ch"
/*/
+----------------------------------------------------------------------------| Programa | ATFA010A | Autor |
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Cadastro de dados complementares do bem Ativo Fixo
|
+---------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
User Function ATFA010A()
Private cCadastro := "Atualizacao de dados do bem"
Private aRotina := { {"Pesquisar" ,"AxPesqui"
{"Visualizar"
,"AxVisual"
{"Atualizar"
,"U_A010AATU"
,0,1} ,;
,0,2} ,;
,0,4}}
Private cDelFunc := ".T."

Private cString := "SN1"
dbSelectArea("SN1")
dbSetOrder(1)
dbSelectArea(cString)
mBrowse( 6,1,22,75,cString)
Tel: 11 50114895 / 50116082 / 98081988
SP
154
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Return
/*/
+----------------------------------------------------------------------------| Programa | A010AATU | Autor |
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Atualizao de dados do bem Ativo Fixo
|
+----------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
User Function A010AATU(cAlias,nReg,nOpc)
Local aCpoEnch
Local aAlter
:= {}
:= {}
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
aButtons
cAliasE
aAlterEnch
aPos
nModelo
lF3
lMemoria
lColumn
caTela
lNoFolder
lProperty
{}
cAlias
{}
{015,000,400,600
.F.
.T.
.F.
""
.F.
.F.
Private
Private
Private
Private
Private
oDlg
oGetD
oEnch
aTELA[0][0]
aGETS[0]
// Variveis que sero atualizadas pela Enchoice()

// e utilizadas pela funo OBRIGATORIO()
DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
//+--------------------------------------------------------------------------+
//|Campos da enchoice
|
//+--------------------------------------------------------------------------+
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "A1_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.
X3Uso(SX3->X3_USADO)
AAdd(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
//+--------------------------------------------------------------------------+
//|Campos alterveis da enchoice
|
//+--------------------------------------------------------------------------+
AADD(aAlterEnch,"N1_TIPOADT")
// Controle de Adiantamentos
AADD(aAlterEnch,"N1_DESCRIC")
// Descrio
AADD(aAlterEnch,"N1_CHAPA")
// Numero da plaqueta
AADD(aAlterEnch,"N1_FORNEC") // Fornecedor
Tel: 11 50114895 / 50116082 / 98081988
SP
155
ADVPL
GUIA DE REFERNCIA
Escola conveniada
AADD(aAlterEnch,"N1_LOJA")
AADD(aAlterEnch,"N1_NSERIE")
AADD(aAlterEnch,"N1_NFISCAL")
AADD(aAlterEnch,"N1_NFITEM")
AADD(aAlterEnch,"N1_UM")
AADD(aAlterEnch,"N1_PRODUTO")
AADD(aAlterEnch,"N1_PEDIDO")
AADD(aAlterEnch,"N1_ITEMPED")
AADD(aAlterEnch,"N1_PRCIMP")
AADD(aAlterEnch,"N1_CODPAIS")
AADD(aAlterEnch,"N1_ORIGCPR")
AADD(aAlterEnch,"N1_CODSP")
AADD(aAlterEnch,"N1_CHASSIS")
// Loja do Fornecedor
Serie da Nota
Numero da Nota
Item da Nota
Unidade de Medida
Cdigo do Produto
Codigo do Pedido de Compras
Item do Pedido de Compras
Codigo do Processo de Importacao
Codigo do Pais
Origem de Compras
// Codigo da SP Interna
// Numero de serie
//
//
//
//
//
//
//
//
//
//
//+--------------------------------------------------------------------------+
//|Montagem do DIALOG
|
//+--------------------------------------------------------------------------+
DEFINE MSDIALOG oDlg TITLE cCadastro FROM 000,000 TO 400,600 PIXEL
RegToMemory("SN1", .F.)
oEnch :=
MsMGet():New(cAliasE, nReg, nOpc, /*aCRA*/, /*cLetra*/,;

/*cTexto*/, aCpoEnch,aPos,aAlterEnch, nModelo, /*nColMens*/,;
/*cMensagem*/, /*cTudoOk*/, oDlg, lF3, lMemoria, lColumn,;
caTela, lNoFolder, lProperty)
ACTIVATE MSDIALOG oDlg CENTERED;

ON INIT EnchoiceBar(oDlg,
{||IIF(A010AGRV(aCpoEnch,aAlterEnch,nOpc),;
oDlg:End(),.F.)},; // Boto OK
{||oDlg:End()},,aButtons) // Boto Cancelar
RETURN
/*/
+----------------------------------------------------------------------------| Programa | A010AGRV | Autor |
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Validao da enchoice e gravao dos dados do bem
|
+----------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
Static Function A010AGRV(aCpos,aAlter,nOpc)
Local aArea
Local nX
:= GetArea()
:= 0
IF !Obrigatorio(aGets,aTela) /*Valida o cabecalho*/

Return .F.
ENDIF
// Atualizacao dos campos passiveis de alteracao no SN1
RecLock("SN1",.F.)
For nX := 1 to Len(aAlter)
SN1->&(aAlter[nX]) := M->&(aAlter[nX])
Next nX
MsUnLock()
Tel: 11 50114895 / 50116082 / 98081988
SP
156
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Return .T.
OPENFILE()
A funo OPENFILE() exibe o diagnstico de arquivos, verificando a existncia dos arquivos de
dados e os ndices do sistema, criando caso no existam e abre os arquivos de acordo com o
mdulo onde executada ou de acordo com a parametrizao.
Sintaxe: OPENFILE(cEmp)
Parmetros:
cEmp
Empresa cujo os arquivos sero re-abertos.
Retorno:
Nenhum
PERGUNTE()
A funo PERGUNTE() inicializa as variveis de pergunta (mv_par01,...) baseada na pergunta
cadastrado no Dicionrio de Dados (SX1). Se o parmetro lAsk no for especificado ou for
verdadeiro ser exibida a tela para edio da pergunta e se o usurio cofirmar as variveis
sero atualizadas e a pergunta no SX1 tambm ser atualizada.
Sintaxe: Pergunte( cPergunta , [lAsk] , [cTitle] )
Parmetros:
cPergunta
Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada.
|Ask
Indica se exibir a tela para edio.
cTitle
Ttulo do dilogo.
Retorno:
Lgico
Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou

cancelada (.F.)
PESQPICT()
A funo PESQPICT() retorna a picture definida para um campo especificado no Dicionrio de
Dados (SX3).
Sintaxe: PesqPict(cAlias,cCampo,nTam)
Parmetros:
cAlias
Alias do arquivo

Tel: 11 50114895 / 50116082 / 98081988
SP
157
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cCampo
Nome do campo
nTam
Opcional, para campos numricos, ser usado como o tamanho do campo

para definio da picture. Se no informado, e usado o tamanho padro no
dicionrio de dados.
Retorno:
String
Picture do campo especificado.
PESQPICTQT()
A funo PESQPICTQT() retorna a picture de um campo numrico referente a uma quantidade,
de acordo com o Dicionrio de Dados (SX3). Esta funo geralmente utilizada quando h
pouco espao disponvel para impresso de valores em relatrios, quando o valor nEdio no
informado, ela tem o comportamento semelhante ao da funo X3Picture, pois busca o
tamanho do campo no dicionrio de dados.
Sintaxe: PesqPictQt(cCampo,nEdio)
Parmetros:
cCampo
Nome do campo a verificar a picture.
nEdio
Espao disponvel para edio.
Retorno:
String
Picture ideal para o espao definido por nEdio, sem a separao dos
milhares por vrgula.
POSICIONE()
A funo POSICIONE() permite o retorno do contedo de um campo de um registro de uma
tabela especificado atravs de uma chave de busca.
Sintaxe: Posicione(cAlias, nOrdem, cChave, cCampo)
Parmetros:
cAlias
Alias do arquivo
nOrdem
Ordem utilizada
cChave
Chave pesquisa
cCampo
Campo a ser retornado
Retorno:
Indefinido
Contedo do campo solicitado.

Tel: 11 50114895 / 50116082 / 98081988
SP
158
ADVPL
GUIA DE REFERNCIA
Escola conveniada
A utilizao da funo POSICIONE() deve ser protegida com GETAREA() /

RESTAREA() dependendo da aplicao.
PUTSX1()
A funo PUTSX1() permite a incluso de um nico item de pergunta em um grupo de definido
no Dicionrio de Dados (SX1). Todos os vetores contendo os textos explicativos da pergunta
devem conter at 40 caracteres por linha.
Sintaxe: PutSx1(cGrupo, cOrdem, cPergunt, cPerSpa, cPerEng, cVar, cTipo,

nTamanho, nDecimal, nPresel, cGSC, cValid, cF3, cGrpSxg ,cPyme, cVar01,
cDef01, cDefSpa1 , cDefEng1, cCnt01, cDef02, cDefSpa2, cDefEng2, cDef03,
cDefSpa3, cDefEng3, cDef04, cDefSpa4, cDefEng4, cDef05, cDefSpa5,
cDefEng5, aHelpPor, aHelpEng, aHelpSpa, cHelp)
Parmetros:
cGrupo
Grupo de perguntas do SX1 (X1_GRUPO)
cOrdem
Ordem do parmetro no grupo (X1_ORDEM)
cPergunt
Descrio da pergunta em portugus
cPerSpa
Descrio da pergunta em espanhol
cPerEng
Descrio da pergunta em ingls
cVar
Nome da varivel de controle auxiliar (X1_VARIAVL)
cTipo
Tipo do parmetro
nTamanho
Tamanho do contedo do parmetro
nDecimal
Nmero de decimais para contedos numricos
nPresel
Define qual opo do combo a padro para o parmetro.
cGSC
Define se a pergunta ser do tipo G Get ou C Choice (combo)
cValid
Expresso de validao do parmetro
cF3
cPyme
Cdigo da consulta F3 vinculada ao parmetro

Cdigo do grupo de campos SXG para atualizao automtica, quando o
grupo for alterado.
Se a pergunta estar disponvel no ambiente Pyme
cVar01
Nome da varivel MV_PAR+Ordem do parmetro.
cDef01
Descrio da opo 1 do combo em portugus
cDefSpa1
Descrio da opo 1 do combo em espanhol
cDefEng1
Descrio da opo 1 do combo em ingls
cCnt01
Contedo padro ou ultimo contedo definido como respostas para este item
cDef0x
Descrio da opo X do combo em portugus
cDefSpax
cDefEngx
aHelpPor
Vetor simples contendo as linhas de help em portugus para o parmetro.
aHelpEng
Vetor simples contendo as linhas de help em ingls para o parmetro.
cGrpSxg

Tel: 11 50114895 / 50116082 / 98081988
SP
159
ADVPL
GUIA DE REFERNCIA
Escola conveniada
aHelpSpa
Vetor simples contendo as linhas de help em espanhol para o parmetro.
cHelp
Contedo do campo X1_HELP
RETINDEX()
A funo RETINDEX()
Dados (SIX).
restaura os ndices padres de um alias definidos no Dicionrio de
Sintaxe: RETINDEX(cAlias)
Parmetros:
cAlias
Alias de um arquivo do sistema existente no Dicionrio de Dados.
Retorno:
Numrico
Indica quantos ndices padres o alias especificado possui no Dicionrio de

Dados.
A funo RETINDEX() quando utilizada em ambientes TOPCONNECT retorna -1
SIXDESCRICAO()
A funo SIXDESCRICAO() retorna a descrio da chave de ndice, de acordo com o registro
posicionado no SIX e idioma corrente.
Sintaxe: SIXDESCRICAO()
Parmetros:
Nenhum
Retorno:
String
Descrio do indice posicionado no SIX de acordo com o idioma corrente.
Exemplo:
User Function <nome-da-funo>( cChave, cOrdem )
Local cSixDesc :=
dbSelectArea(SIX)
dbSetOrder(1)
If dbSeek(cChave+cOrdem)
cSixDescr := SixDescricao()
Tel: 11 50114895 / 50116082 / 98081988
SP
160
ADVPL
GUIA DE REFERNCIA
Escola conveniada
EndIf
Return
TABELA()
A funo TABELA() retorna o contedo de uma tabela cadastrada no Arquivo de Tabelas (SX5)
de acordo com a chave especificada. Caso a tabela ou a chave especificada no existir ser
exibido um HELP() padro do sistema.
Sintaxe: Tabela(cTab,cChav,lPrint)
Parmetros:
cTab
Idenficao da tabela a pesquisar (deve ser informado como caracter).
cChav
Chave a pesquisar na tabela informada.
lPrint
Indica se deve (.T.) ou no (.F.) exibir o help ou a chave NOTAB se a tabela

no existir.
Retorno:
String
Contedo da tabela na chave especificada. Retorna nulo caso a tabela no

exista ou a chave no seja encontrada.
TAMSX3()
A funo TAMSX3() retorna o tamanho (total e parte decimal) de um campo especificado no
Dicionrio de Dados (SX3).
Sintaxe: TAMSX3(cCampo)
Parmetros:
cCampo
Nome do campo a ser consultado no Dicionrio de Dados (SX3).
Retorno:
Array
Array de duas posies contendo o tamanho total e o nmero de decimais do

campo especificado respectivamente.
TM()
A funo TM() retorna a picture de impresso para valores numricos dependendo do espao
disponvel.
Sintaxe: TM(nValor, nEdio, nDec)
Parmetros:
nValor
Valor a ser avaliado.

Tel: 11 50114895 / 50116082 / 98081988
SP
161
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nEdio
Espao disponvel para edio.
nDec
Nmero de casas decimais.
Retorno:
String
Picture ideal para edio do valor nValor
Esta rotina leva em considerao duas variveis:

MV_MILHAR Determina se deve haver separao de milhar;
MV_CENT Nmero de casas decimais padro da moeda corrente.
Para ajustar o valor passado (nValor) ao espao disponvel (nEdio) a funo
verifica se pode haver separao de milhar, neste caso, a rotina eliminar
tantos pontos decimais quantos sejam necessrios ao ajuste do tamanho.
Caso no seja possvel ajustar o valor ao espao dado, ser colocado na
picture o caracter de estouro de campo *.A funo tambm ajusta um valor
ao nmero de decimais (nDec), sempre imprimindo a quantidade de decimais
passados no parmetro.
X1DEF01()
A funo X1DEF01() retorna o contedo da primeira definio da pergunta posicionada no SX1
(caso seja combo) no idioma corrente.
Sintaxe: X1DEF01()
Parmetros:
Nenhum
Retorno:
String
Contedo da primeira definio da pergunta no idioma corrente.
Exemplo:
User Function <nome-da-funo>( cGrupo, cPerg )
Local cDef01
Local cDef02
Local cDef03
Local cDef04
Local cDef05
dbSelectArea(SX1)
dbSetOrder(1)
If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDef01 := X1Def01()
cDef02 := X1Def02()
Tel: 11 50114895 / 50116082 / 98081988
SP
162
ADVPL
GUIA DE REFERNCIA
Escola conveniada
EndIf
cDef03 := X1Def03()
cDef04 := X1Def04()
cDef05 := X1Def05()
Return
X1PERGUNT()
A funo X1PERGUNT() retorna a descrio da pergunta posicionada no Dicionrio de Dados
(SX1) para o idioma corrente.
Sintaxe: X1PERGUNT()
Parmetros:
Nenhum
Retorno:
String
Descrio da pergunta do Dicionrio de Dados (SX1) no idioma corrente.
Exemplo:
User Function <nome-da-funo>( cGrupo, cPerg )
Local cDescr
dbSelectArea(SX1)
dbSetOrder(1)
If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDescr := X1Pergunt()
EndIf
Return
X2NOME()
A funo X2NOME() retorna a descrio de uma tabela posicionada no Dicionrio de Dados
(SX2) no idioma corrente.
Sintaxe: X2NOME()
Parmetros:
Nenhum
Retorno:
String
Descrio da tabela posicionada no Dicionrio de Dados (SX2) no idioma

corrente.
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
163
ADVPL
GUIA DE REFERNCIA
Escola conveniada
User Function <nome-da-funo>( )

Local cTabela
dbSelectArea(SX2)
dbSetOrder(1)
If dbSeek( SA1 )
cTabela := X2Nome()
EndIf
Return
X3CBOX()
A funo X3CBOX() retorna o contedo de um campo tipo combo posicionado no Dicionrio de
Dados (SX3) no idioma corrente.
Sintaxe: X3CBOX()
Parmetros:
Nenhum
Retorno:
String
Contedo do campo do tipo combo posicionado no Dicionrio de Dados (SX3)

no idioma corrente.
Exemplo:
Local cTitulo
Local cDescri
Local cCombo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( cCampo )
cTitulo := X3Titulo()
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf
Return
X3DESCRIC()
A funo X3DESCRIC() retorna a descrio de um campo posicionado no Dicionrio de Dados
(SX3) no idioma corrente.
Sintaxe: X3DESCRIC()

Tel: 11 50114895 / 50116082 / 98081988
SP
164
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros:
Nenhum
Retorno:
String
Descrio do campo posicionado no Dicionrio de Dados (SX3) no idioma

corrente.
Exemplo:
Local cTitulo
Local cDescri
Local cCombo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( cCampo )
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf
Return
X3PICTURE()
A funo X3PICTURE() retorna a mscara de um campo contido no Dicionrio de Dados (SX3).
Sintaxe: X3PICTURE(cCampo)
Parmetros:
cCampo
Nome do campo contido no Dicionrio de Dados (SX3).
Retorno:
String
Picture do campo informado.
Exemplo:
User Function <nome-da-funo>( cCampo )
Local cPicture
cPicture := X3Picture( cCampo )
Return cPicture
Tel: 11 50114895 / 50116082 / 98081988
SP
165
ADVPL
GUIA DE REFERNCIA
Escola conveniada
X3TITULO()
A funo X3TITULO() retorna o ttulo de um campo posicionado no Dicionrio de Dados (SX3)
no idioma corrente.
Sintaxe: X3TITULO()
Parmetros:
Nenhum
Retorno:
String
Ttulo do campo posicionado no dicionrio de dados (SX3) no idioma

corrente.
Exemplo:
Local cTitulo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( A1_COD )
EndIf
Return
X3USO()
A funo X3USO() verifica se o campo atualmente posicionado no Dicionrio de Dados (SX3)
est disponvel para uso.
Sintaxe: X3USO( cUsado, [Modulo])
Parmetros:
cUsado
Contedo do campo X3_USADO a ser avaliado.
Modulo
Nmero do mdulo. Caso no seja informado ser assumido como padro o

nmero do mdulo corrente.
Retorno:
Lgico
Indica se o campo est configurado como usado no Dicionrio de Dados

(SX3).
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
166
ADVPL
GUIA DE REFERNCIA
Escola conveniada
User Function <nome-da-funo>()

Local lUsado := .F.
DbSelectArea(SX3)
DbSetOrder(2)
DbSeek(A1_COD)
If X3Uso( SX3->X3_USADO )
lUsado := .T.
EndIf
Return lUsado
X5DESCRI()
A funo X5DESCRI() retorna a descrio de um item de uma tabela posicionado no Arquivo de
Tabelas (SX5) no idioma corrente.
Sintaxe: X5DESCRI()
Parmetros:
Nenhum
Retorno:
String
Decrio do item do Arquivo de Tabelas (SX5) no idioma corrente.
Exemplo:
User Function <nome-da-funo>( cFilial, cTabela, cChave )
Local cDescr
dbSelectArea(SX5)
dbSetOrder(1)
If dbSeek( cFilial+cTabela+cChave )
cDescr := X5Descri()
EndIf
Return
X6CONTEUD()
A funo X6CONTEUD() retorna o contedo de um parmetro posicionado no Dicionrio de
Dados (SX6) para o idioma corrente.
Sintaxe: X6CONTEUD()
Parmetros:

Tel: 11 50114895 / 50116082 / 98081988
SP
167
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Nenhum
Retorno:
Indefinido
Contedo do parmetro posicionado no Dicionrio de Dados (SX6) para o

idioma corrente.
Utilizar preferncialmente as funes de manipulao de parmetros GETMV()

e suas variantes.
Exemplo:
User Function <nome-da-funo>( cFilial, cParam )
Local cDescr
Local cConteud
dbSelectArea(SX6)
dbSetOrder(1)
If dbSeek( cFilial+cParm )
cDescr := X6Descric()
cDescr += X6Desc1()
cDescr += X6Desc2()
cConteud := X6Conteud()
EndIf
Return
X6DESCRIC()
A funo X6DESCRI() retorna o contedo da descrio de um parmetro de acordo com o
registro posicionado no Dicionrio de Dados (SX6) no idioma corrente.
Sintaxe: X6DESCRIC()
Parmetros:
Nenhum
Retorno:
String
Descrio do parmetro posicionado no Dicionrio de Dados (SX6) no idioma

corrente.
Para avaliar os contedos dos primeiro e segundo complementos da descrio

do parmetro utilize as funes:
Tel: 11 50114895 / 50116082 / 98081988
SP
168
ADVPL
GUIA DE REFERNCIA
Escola conveniada
X6DESC01() retorna o primeiro complemento da descrio.

X6DESC02() retorna o segundo complemento da descrio.
As trs funes possuem a mesma sintaxe e forma de utilizao.
Exemplo:
User Function <nome-da-funo>( cFilial, cParam )
Local cDescr
Local cConteud
dbSelectArea(SX6)
dbSetOrder(1)
If dbSeek( cFilial+cParm )
cDescr := X6Descric()
cDescr += X6Desc1()
cDescr += X6Desc2()
cConteud := X6Conteud()
EndIf
Return
XADESCRIC()
A funo XADESCRI() retorna o contedo da descrio dos folders de acordo com o registro
posicionado no Dicionrio de Dados (SXA) no idioma corrente.
Sintaxe: XADESCRIC()
Parmetros:
Nenhum
Retorno:
String
Descrio do folder posicionado no Dicionrio de Dados (SXA) no idioma

corrente.
Exemplo:
User Function <nome-da-funo>( cFolder, cNumero )
Local cDescr
dbSelectArea(SXA)
dbSetOrder(1)
If dbSeek( cFolder+cNumero ) // alias do folder + numero do folder
cDescr := XADescric()
EndIf
Return
Tel: 11 50114895 / 50116082 / 98081988
SP
169
ADVPL
GUIA DE REFERNCIA
Escola conveniada
XBDESCRI()
A funo XBDESCRI() retorna o contedo da descrio de uma consulta de acordo com o
registro posicionado no Dicionrio de Dados (SXB) no idioma corrente.
Sintaxe: XBDESCRI()
Parmetros:
Nenhum
Retorno:
String
Descrio da consulta posicionada no Dicionrio de Dados (SXB) no idioma

corrente.
Exemplo:
User Function <nome-da-funo>( cAlias )
Local cDescr
dbSelectArea(SXB)
dbSetOrder(1)
If dbSeek( cAlias + 1 )
cDescr := XBDescri()
EndIf
Return
XFILIAL()
A funo XFILIAL() retorna a filial utilizada por determinado arquivo.
Esta funo utilizada para permitir que pesquisas e consultas em arquivos trabalhem
somente com os dados da filial corrente, dependendo claro se o arquivo est compartilhado
ou no (definio que feita atravs do mdulo Configurador Dicionrio de Dados (SX2)).
importante verificar que esta funo no tem por objetivo retornar apenas a filial corrente,
mas retorn-la caso o arquivo seja exclusivo. Se o arquivo estiver compartilhado, a funo
xFilial retornar dois espaos em branco.
Sintaxe: XFILIAL(cAlias)
Parmetros:
cAlias
Alias do arquivo desejado. Se no for especificado, o arquivo tratado ser o

da rea corrente.
Retorno:
Caracter
String contendo a filial do arquivo corrente.

Tel: 11 50114895 / 50116082 / 98081988
SP
170
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Componentes da interface visual

MSDIALOG()
Define o componente MSDIALOG(), o qual utilizado como base para os demais componentes
da interface visual, pois um componente MSDIALOG() uma janela da aplicao.
Sintaxe:
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO nLiFim,nColFim OF

oObjetoRef UNIDADE
Parmetros
oObjetoDLG
Posio do objeto Say em funo da janela em que ele ser definido.
cTitulo
Ttulo da janela de dilogo.
nLinIni, nColIni
Posio inicial em linha / coluna da janela.
nLiFim, nColFim
Posio final em linha / coluna da janela.
oObjetoRef
Objeto dialog no qual a janela ser definida.
UNIDADE
Unidade de medida das dimenses: PIXEL
Exemplo:
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL
MSGET()
Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis
na tela da interface.
Sintaxe:
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3

VALID VALID WHEN WHEN PICTURE cPicture
Parmetros
nLinha, nColuna
Posio do objeto MsGet em funo da janela em que ele ser definido.
VARIAVEL
Varivel da aplicao que ser vinculada ao objeto MsGet, que definir

suas caractersticas e na qual ser armezanado o que for informado no

Tel: 11 50114895 / 50116082 / 98081988
SP
171
ADVPL
GUIA DE REFERNCIA
Escola conveniada
campo.
nLargura,nAltura
Dimenses do objeto MsGet para exibio do texto.
UNIDADE
oObjetoRef
Objeto dialog no qual o componente ser definido.
cF3
String que define a consulta padro que ser vinculada ao campo.
VALID
Funo de validao para o campo.
WHEN
Condio para manipulao do campo, a qual pode ser diretamente .T.

ou .F., ou uma varivel ou uma chamada de funo.
cPicture
String contendo a definio da Picture de digitao do campo.
Exemplo:
@ 010,050 MSGET cCGC
VALID !Vazio()
SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
SAY()
Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de
interface.
Sintaxe:
@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef
Parmetros
nLinha, nColuna
Posio do objeto Say em funo da janela em que ele ser definido.
cTexto
Texto que ser exibido pelo objeto Say.
nLargura,nAltura
Dimenses do objeto Say para exibio do texto.
UNIDADE
oObjetoRef
Exemplo:
@ 010,010 SAY
cTexto SIZE 55, 07 OF oDlg PIXEL
BUTTON()
Define o componente visual Button, o qual permite a incluso de botes de operao na tela da
interface, os quais sero visualizados somente com um texto simples para sua identificao.
Tel: 11 50114895 / 50116082 / 98081988
SP
172
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Sintaxe: BUTTON()
@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef

ACTION AO
Parmetros
nLinha,nColuna
Posio do objeto Button em funo da janela em que ele ser definido.
cTexto
String contendo o texto que ser exibido no boto.
nLargura,nAltura
Dimenses do objeto Button para exibio do texto.
UNIDADE
oObjetoRef
AO
Funo ou lista de expresses que define o comportamento do boto

quando ele for utilizado.
Exemplo:
010, 120 BUTTON Confirmar SIZE 080, 047 PIXEL OF oDlg;
ACTION (nOpca := 1,oDlg:End())
SBUTTON()
Define o componente visual SButton, o qual permite a incluso de botes de operao na tela
da interface, os quais sero visualizados dependendo da interface do sistema ERP utilizada
somente com um texto simples para sua identificao, ou com uma imagem (BitMap) prdefinido.
Sintaxe: SBUTTON()
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF oObjetoRet
Parmetros
nLinha, nColuna
TYPE N
AO
Posio do objeto sButton em funo da janela em que ele ser

definido.
Nmero que indica o tipo do boto (imagem) pr-definida que ser
utilizada.
Funo ou lista de expresses que define o comportamento do boto
quando ele for utilizado.
STATUS
Propriedade de uso do boto: ENABLE ou DISABLE
oObjetoRet
Exemplo:
Tel: 11 50114895 / 50116082 / 98081988
SP
173
ADVPL
GUIA DE REFERNCIA
Escola conveniada
DEFINE SBUTTON FROM 020, 120 TYPE 2 ACTION (nOpca := 2,oDlg:End());

ENABLE OF oDlg
Visual dos diferentes tipos de botes disponveis
CHECKBOX()
Define o componente visual CheckBox, o qual permite a utilizao da uma marca para habilitar
ou no uma opo escolhida, sendo esta marca acompanhada de um texto explicativo. Difere
do RadioMenu pois cada elemento do check nico, mas o Radio permite a utilizao de uma
lista junto com um controle de seleo.
Sintaxe:
@ nLinha,nColuna CHECKBOX oCheckBox VAR VARIAVEL PROMPT cTexto WHEN WHEN

UNIDADE OF oObjetoRef SIZE nLargura,nAltura MESSAGE cMensagem
Parmetros:
nLinha,nColuna
Posio do objeto ComboBox em funo da janela em que ele ser

definido.
oCheckBox
Objeto do tipo CheckBox que ser criado.
VARIAVEL
Varivel do tipo lgico com o status do objeto (.T. marcado, .F.

desmarcado).
cTexto
Texto que ser exibido ao lado do get de marcao.
WHEN
Condio para manipulao do objeto, a qual pode ser diretamente .T.

ou .F., ou uma varivel ou uma chamada de funo.
UNIDADE
oObjetoRef
nLargura,nAltura
Dimenses do objeto CheckBox.

Tel: 11 50114895 / 50116082 / 98081988
SP
174
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cMensagem
Texto que ser exibido ao clicar no componente.
Exemplo:
@ 110,10 CHECKBOX oChk VAR lChk PROMPT "Marca/Desmarca" SIZE 60,007 PIXEL OF oDlg ;
ON CLICK(aEval(aVetor,{|x| x[1]:=lChk}),oLbx:Refresh())
COMBOBOX()
Define o componente visual ComboBox, o qual permite seleo de um item dentro de uma lista
de opes de textos simples no formato de um vetor.
Sintaxe:
@ nLinha,nColuna COMBOBOX VARIAVEL ITEMS AITENS SIZE nLargura,nAltura UNIDADE OF

oObjetoRef
Parmetros:
nLinha,nColuna
VARIAVEL
AITENS
Posio do objeto ComboBox em funo da janela em que ele ser

definido.
Varivel do tipo caracter que ir receber a descrio do item
selecionado no ComboBox.
Vetor simples contendo as strings que sero exibidas como opes do
ComboBox.
nLargura,nAltura
Dimenses do objeto ComboBox.
UNIDADE
oObjetoRef
Exemplo:
@ 40, 10 COMBOBOX oCombo VAR cCombo ITEMS aCombo SIZE 180,10 PIXEL OF
oFld:aDialogs[2]
FOLDER()
Define o componente visual Folder, o qual permite a incluso de diversos Dialogs dentro de
uma mesma interface visual. Um Folder pode ser entendido como um array de Dialogs, aonde
cada painel recebe seus componentes e tem seus atributos definidos independentemente dos
demais.
Sintaxe:
@ nLinha,nColuna FOLDER oFolder OF oObjetoRef PROMPT &cTexto1,,&cTextoX UNIDADE

SIZE nLargura,nAltura
Tel: 11 50114895 / 50116082 / 98081988
SP
175
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Parmetros
nLinha,nColuna
Posio do objeto Folder em funo da janela em que ele ser

definido.
oFolder
Objeto Folder que ser criado.
oObjetoRef
&cTexto1,,&cTextoX
Strings de ttulos de cada uma das abas do Folder, sempre

precedidas por &. Exemplo: &Pasta1,&PastaX.
UNIDADE
nLargura,nAltura
Dimenses do objeto Folder.
Exemplo:
@ 50,06 FOLDER oFld OF oDlg PROMPT "&Buscas", "&Consultas", "Check-&Up / Botes" PIXEL
SIZE 222,078
RADIO()
Define o componente visual Radio, tambm conhecido como RadioMenu, o qual seleo de
uma opo ou de mltiplas opes atravs de uma marca para os itens exibidos de uma lista.
Difere do componente CheckBox, pois cada elemento de check sempre nico, e o Radio pode
conter um ou mais elementos.
Sintaxe:
@ nLinha,nColuna RADIO oRadio VAR nRadio 3D SIZE nLargura,nAltura <ITEMS PROMPT>

cItem1,cItem2,...,cItemX OF oObjetoRef UNIDADE ON CHANGE CHANGE ON CLICK CLICK
Parmetros
nLinha,nColuna
Posio do objeto Radio em funo da janela em que ele ser

definido.
oRadio
Objeto do tipo Radio que ser criado.
nRadio
Item do objeto Radio que est selecionado.
3D
Item opcional que define se o RadioButton ter aspecto

simples ou 3D.
nLargura,nAltura
Dimenses do objeto Radio.
<ITEMS PROMPT>
Utilizar um dos dois identificadores para definir quais os

textos que sero vinculados a cada RadioButton.
cItem1,cItem2,...,cItem
X
Texto que ser vinculado a cada RadioButton.
oObjetoRef

Tel: 11 50114895 / 50116082 / 98081988
SP
176
ADVPL
GUIA DE REFERNCIA
Escola conveniada
UNIDADE

Funo ou lista de expresses que ser executada na
mudana de um item de um RadioButton para outro.
Funo ou lista de expresses que ser executada na seleo
de um item RadioButton.
CHANGE
CLICK
Exemplo:
aAdd( aRadio, "Disco" )
aAdd( aRadio, "Impressora" )
aAdd( aRadio, "Scanner" )
@ 30, 10 RADIO oRadio VAR nRadio ITEMS aRadio[1],aRadio[2],aRadio[3] SIZE 65,8 ;
PIXEL OF ;
oFld:aDialogs[3] ;
ON CHANGE ;
(Iif(nRadio==1,MsgInfo("Opco 1",cAtencao),;
Iif(nRadio==2,MsgInfo("Opo 2",cAtencao),MsgInfo("Opo 3",cAtencao))))
Interfaces de cadastro
AXCADASTRO()
Sintaxe
AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)
Descrio
O AxCadastro() uma funcionalidade de cadastro simples, com poucas

opes de customizao.
MBROWSE()
Sintaxe
MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias)
Descrio
A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de

recursos mais aprimorados na visualizao e manipulao das informaes
do sistema.
AXPESQUI()
Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o
browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado
na pesquisa e a digitao das informaes que compe a chave de busca.
Sintaxe: AXPESQUI()
Parmetros
Nenhum
AXVISUAL()
Tel: 11 50114895 / 50116082 / 98081988
SP
177
ADVPL
GUIA DE REFERNCIA
Escola conveniada
Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme

demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;

aButtons, lMaximized )
Parmetros
cAlias
Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada
nReg
Record number (recno) do registro posicionado no alias ativo.
nOpc
aAcho
Nmero da linha do aRotina que definir o tipo de edio (Incluso,

Alterao, Excluso, Visualizao).
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER".
nColMens
Parmetro no utilizado.
cMensagem
Parmetro no utilizado.
cFunc
aButtons
lMaximized
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
Botes adicionais para a EnchoiceBar, no formato:
aArray[n][1] -> Imagem do boto
aArray[n][2] -> bloco de cdigo contendo a ao do boto
aArray[n][3] -> ttulo do boto
Indica se a janela dever ser ou no maximizada
AXINCLUI()
Funo de incluso padro das informaes de um registro, no formato Enchoice, conforme
Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;

cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
cAlias
nReg
nOpc
aAcho
cFunc
aCpos

Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER".
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
Vetor com nome dos campos que podero ser editados

Tel: 11 50114895 / 50116082 / 98081988
SP
178
ADVPL
GUIA DE REFERNCIA
Escola conveniada
cTudoOk
Funo de validao de confirmao da tela. No deve ser passada

como Bloco de Cdigo, mas pode ser passada como uma lista de
expresses, desde que a ltima ao efetue um retorno lgico:
(Func1(), Func2(), ...,FuncX(), .T. )
lF3
Indica se a enchoice esta sendo criada em uma consulta F3 para utilizar

variveis de memria
cTransact
Funo que ser executada dentro da transao da AxFunction()
aButtons
aParam
aAuto
lVirtual
lMaximized

Funes para execuo em pontos pr-definidos da AxFunction(),
conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da exibio
da interface.
aParam[2] := Bloco de cdigo para processamento na validao da
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao
da AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da transao da
AxFunction().
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser
executada a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as
validaes do SX3
Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de
memria ou os campos da tabela na edio
AXALTERA()
Funo de alterao padro das informaes de um registro, no formato Enchoice, conforme
Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens, cMensagem,;

cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
Vide documentao de parmetros da funo AxInclui().

Tel: 11 50114895 / 50116082 / 98081988
SP
179
ADVPL
GUIA DE REFERNCIA
Escola conveniada
AXDELETA()
Funo de excluso padro das informaes de um registro, no formato Enchoice, conforme
Sintaxe: AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,;

aAuto, lMaximized)
Parmetros
cAlias
nReg
nOpc

cTransact
Funo que ser executada dentro da transao da AxFunction()
aCpos
Vetor com nome dos campos que podero ser editados
aButtons
aParam
aAuto
lMaximized

Funes para execuo em pontos pr-definidos da AxFunction(),
conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da exibio
da interface.
aParam[2] := Bloco de cdigo para processamento na validao da
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao
da AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da transao da
AxFunction().
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser
executada a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as
validaes do SX3
Interfaces visuais para aplicaes

ALERT()
Sintaxe: AVISO(cTexto)
Parmetros
cTexto
Texto a ser exibido

Tel: 11 50114895 / 50116082 / 98081988
SP
180
ADVPL
GUIA DE REFERNCIA
Escola conveniada
AVISO()
Sintaxe: AVISO(cTitulo, cTexto, aBotoes, nTamanho)

Retorno: numrico indicando o boto selecionado.
Parmetros
cTitulo
Ttulo da janela
cTexto
Texto do aviso
aBotoes
Array simples (vetor) com os botes de opo
nTamanho
Tamanho (1,2 ou 3)
FORMBACTH()
Sintaxe: FORMBATCH(cTitulo, aTexto, aBotoes, bValid, nAltura, nLargura )

Parmetros
cTitulo
aTexto
aBotoes
Ttulo da janela
Array simples (vetor) contendo cada uma das linhas de texto que sero
exibidas no corpo da tela.
Array com os botes do tipo SBUTTON(), com a seguinte estrutura:
{nTipo,lEnable,{|| Ao() }}
bValid
(opcional) Bloco de validao do janela
nAltura
(opcional) Altura em pixels da janela

Tel: 11 50114895 / 50116082 / 98081988
SP
181
ADVPL
GUIA DE REFERNCIA
Escola conveniada
nLargura
(opcional) Largura em pixels da janela
MSGFUNCTIONS()
Sintaxe:
Sintaxe:
Sintaxe:
Sintaxe:
Parmetros
MSGALERT(cTexto, cTitulo)
MSGINFO(cTexto, cTitulo)
MSGSTOP(cTexto, cTitulo)
MSGYESNO(cTexto, cTitulo)
cTexto
Texto a ser exibido como mensagem
cTitulo
Ttulo da janela de mensagem
MSGALERT
MSGINFO

Tel: 11 50114895 / 50116082 / 98081988
SP
182
ADVPL
GUIA DE REFERNCIA
Escola conveniada
MSGSTOP
MSGYESNO
Recursos das interfaces visuais

GDFIELDGET()
A funo GDFIELDGET() retorna o contedo de um campo especificado em uma grid formada
por um objeto do tipo MsNewGetDados() de acordo com a linha da grid desejada.
Sintaxe: GDFIELDGET(cCampo, nLinha)
Parmetros:
cCampo
Nome do campo para retorno do contedo.
nLinha
Linha da grid que dever ser avaliada.
Retorno:
Indefinido
Contedo do campo especificado de acordo com a linha da grid informada.
GDFIELDPOS()

Tel: 11 50114895 / 50116082 / 98081988
SP
183
ADVPL
GUIA DE REFERNCIA
Escola conveniada
A funo GDFIELDPOS() retorna a posio de um campo especificado em uma gria formada

por um objeto do tipo MsNewGetDados().
Sintaxe: GDFIELDPOS(cCampo)
Parmetros:
cCampo
Nome do campo a ser avaliado na grid.
Retorno:
Numrico
Posio que o campo ocupada na grid. Caso o mesmo no exista ser

retornado 0.
GDFIELDPUT()
A funo GDFIELDPUT() atualiza o contedo de uma grid formada por um objeto do tipo
MsNewGetDados() de acordo com o campo e linha da grid especificados.
Sintaxe: GDFIELDPUT(cCampo, xConteudo, nLinha)
Parmetros:
cCampo
Nome do campo a ser atualizado.
xConteudo
Contedo que ser atribudo a clula da grid.
nLinha
Linha da grid que ser atualizada.
Retorno:
Nenhum
GETMARK()
A funo GETMARK() utilizada em conjunto com a funo MarkBrow(), para retornar o
conjunto de caracteres que sero utilizados para identificar os registros marcados pelo browse.
Sintaxe: GETMARK( [lUpper] )
Parmetros:
lUpper
Se verdadeiro (.T.) retorna somente caracteres em maisculos.
Retorno:
String
Conjunto de caracteres que definem a marca que dever ser utilizada pela
MarkBrowse durante o processamento corrente.

Tel: 11 50114895 / 50116082 / 98081988
SP
184
ADVPL
GUIA DE REFERNCIA
Escola conveniada
O retorno da funo GETMARK() depende do contedo atual do parmetro

MV_MARCA.
altamente recomendvel limpar o contedo do campo marcado pela

MarkBrowse() ao trmino do processamento, para se evitar problemas com a
reutilizao da marca aps a exausto das possibilidades de combinao de
dois caracteres, o qual o tamanho padro do campos utilizados para
marcao de registros pela MarkBrowse(), que neste caso somam 1891
possibilidades de 00 a zz.
Exemplo:
Function <nome-da-funo>( )
Local aCampos := {{'CB_OK' ,,''},;
{'CB_USERLIB' ,,'Usurio'},;
{'CB_TABHORA' ,,'Hora'},;
{'CB_DTTAB' ,,'Data'}}
Private cMarca := GetMark()
Private cCadastro := 'Cadastro de Contrato'
Private aRotina := { { 'Pesquisar' , 'AxPesqui' , 0, 1 }}
MarkBrow( 'SCB', 'CB_OK','!CB_USERLIB',aCampos,, cMarca,'MarkAll()',,,,'Mark()' )
Return
MARKBREFRESH()
A funo MARKBREFRESH() atualiza a exibio da marca no MarkBrowse(), sendo utilizada
quando algum processamento paralelo atualiza o contedo do campo definido como controle
de marca para os registros em exibio pelo browse.
Este tipo de processamento comum, e normalmente est associonada a clique de inverter
seleo, ou a opes de marcar e desmarcar todas.
A MarkBrowse() atualiza automaticamente a exibio da marca de registros
quando utilizado o browse.
Sintaxe: MARKBREFRESH()
Parmetros:
Nenhum
Retorno:
Nenhum

Tel: 11 50114895 / 50116082 / 98081988
SP
185
ADVPL
GUIA DE REFERNCIA
Escola conveniada
READVAR()
A funo READVAR() retorna o nome da varivel ou campo associoado ao objeto do tipo GET()
atualmente selecionado ou em edio.
Sintaxe: READVAR()
Parmetros:
Nenhum
Retorno:
String
Nome da varivel ou campo associado ao objeto do tipo GET.

Tel: 11 50114895 / 50116082 / 98081988
SP
186

ADVPL - Guia de Referência

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

ADVPL - Guia de Referência

Enviado por

Direitos autorais:

Formatos disponíveis

Verso 1.0 06/2008 Todos direitos reservados

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Manipulao de blocos de cdigo............................................................................................................25

Verso 1.0 06/2008 Todos direitos reservados

Manipulao de data / hora.....................................................................................................................40

Manipulao de variveis numricas......................................................................................................46

Verso 1.0 06/2008 Todos direitos reservados

Manipulao de arquivos e ndices temporrios....................................................................................76

Manipulao de bases de dados...............................................................................................................77

Verso 1.0 06/2008 Todos direitos reservados

Controle de numerao seqencial........................................................................................................115

Manipulao de parmetros do sistema................................................................................................119

Verso 1.0 06/2008 Todos direitos reservados

Utilizao de recursos do ambiente ERP..............................................................................................143

Verso 1.0 06/2008 Todos direitos reservados

Componentes da interface visual...........................................................................................................169

Interfaces visuais para aplicaes.........................................................................................................178

Recursos das interfaces visuais..............................................................................................................181

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Converso entre tipos de dados

Caracter no formato DD/MM/AAAA

Valor numrico que ser convertido para caractere.

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Varivel com contedo data

Varivel com contedo data

String no formato AAAAMMDD

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Valor numrico que ser convertido para caractere.

Sintaxe: STRZERO(nValor, nTamanho)

Valor numrico que ser convertido para caractere.

Tamanho total desejado para a string retornada.

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

String que ser convertida para numrico.

Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Valor limite para anlise da funo, no formato floating-point.

Valor que representa o ngulo em radianos.

Valor que representa o co-seno ou co-seno hiperblico do ngulo informado.

Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Valor cujo o logaritmo deve ser encontrado.

A funo retorna o logaritmo de nNatural se bem sucedidas. Se nNatural for

Valor do ngulo em radianos.

Retorna o valor do seno do ngulo especificado.

Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da

Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo

Verso 1.0 06/2008 Todos direitos reservados

Um nmero positivo do qual ser calculada a raiz quadrada.

Retorna um valor numrico calculado com preciso dupla. A quantidade de

Valor do ngulo em radianos.

Retorna o valor da tangente do ngulo especificado.

Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da

Nome da varivel que se deseja avaliar, entre aspas ().

Verso 1.0 06/2008 Todos direitos reservados

MSGINFO(Database do sistema: +DTOC(dDataBase))