AdvPL 0 - Guia de Referencia

ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados

Escola Parceira
Certificao

A v . L e o n a r d o d a V i n c i , n 6 0 8 M e t r C o n c e i o - S o P a u l o - S P
T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
1

ADVPL

GUIA DE REFERNCIA

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
2

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() ............................................................................................................................................................... 29
BITON() ......................................................................................................................................................... 29
CAPITAL() .................................................................................................................................................... 29
CHR() ............................................................................................................................................................. 30
DESCEND() .................................................................................................................................................. 30
GETDTOVAL() ............................................................................................................................................. 31
ISALPHA() .................................................................................................................................................... 31
ISDIGIT() ...................................................................................................................................................... 32
ISLOWER() ................................................................................................................................................... 32

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
3

ISUPPER() ..................................................................................................................................................... 32
LEN() ............................................................................................................................................................. 33
LOWER() ....................................................................................................................................................... 33
LTRIM() ........................................................................................................................................................ 33
MATHC() ...................................................................................................................................................... 34
OEMTOANSI() ............................................................................................................................................. 34
PADL() / PADR() / PADC() .......................................................................................................................... 35
RAT() ............................................................................................................................................................. 35
REPLICATE() ............................................................................................................................................... 36
RTRIM() ........................................................................................................................................................ 36
SPACE() ........................................................................................................................................................ 37
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() .................................................................................................................................................. 50
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() ............................................................................................................................................... 59
EXISTDIR() ................................................................................................................................................... 59
FCLOSE() ...................................................................................................................................................... 60
FCREATE() ................................................................................................................................................... 61
FERASE() ...................................................................................................................................................... 61
FILE() ............................................................................................................................................................ 62

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
4

FILENOEXT() ............................................................................................................................................... 63
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() .................................................................................................................................................. 91
DBGOTO() .................................................................................................................................................... 91
DBGOTOP() .................................................................................................................................................. 92
DBGOBOTTON() ......................................................................................................................................... 92
DBINFO() ...................................................................................................................................................... 93
DBNICKINDEXKEY() ................................................................................................................................. 94
DBORDERINFO()......................................................................................................................................... 94
DBORDERNICKNAME() ............................................................................................................................ 95
DBPACK() ..................................................................................................................................................... 95
DBRECALL() ................................................................................................................................................ 96
DBRECORDINFO() ...................................................................................................................................... 96
DBREINDEX() .............................................................................................................................................. 97
DBRLOCK() .................................................................................................................................................. 98
DBRLOCKLIST() ......................................................................................................................................... 98
DBRUNLOCK() ............................................................................................................................................ 99
DBSETDRIVER() ......................................................................................................................................... 99

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
5

DBSETINDEX() .......................................................................................................................................... 100
DBSETNICKNAME() ................................................................................................................................. 100
DBSELECTAREA() .................................................................................................................................... 101
DBSETORDER() ......................................................................................................................................... 102
DBORDERNICKNAME() .......................................................................................................................... 102
DBSEEK() E MSSEEK() ............................................................................................................................. 102
DBSKIP() ..................................................................................................................................................... 104
DBSETFILTER() ......................................................................................................................................... 104
DBSTRUCT() .............................................................................................................................................. 105
DBUNLOCK() ............................................................................................................................................. 106
DBUNLOCKALL() ..................................................................................................................................... 106
DBUSEAREA() ........................................................................................................................................... 107
DELETED() ................................................................................................................................................. 107
FCOUNT() ................................................................................................................................................... 108
FOUND() ..................................................................................................................................................... 108
INDEXKEY() .............................................................................................................................................. 109
INDEXORD() .............................................................................................................................................. 109
LUPDATE() ................................................................................................................................................. 110
MSAPPEND() .............................................................................................................................................. 110
MSUNLOCK() ............................................................................................................................................ 111
ORDBAGEXT() .......................................................................................................................................... 111
ORDKEY() .................................................................................................................................................. 112
RECLOCK() ................................................................................................................................................ 112
RECNO() ..................................................................................................................................................... 114
SELECT() .................................................................................................................................................... 114
SET FILTER TO .......................................................................................................................................... 115
SOFTLOCK() .............................................................................................................................................. 115
USED() ........................................................................................................................................................ 116
Controle de numerao seqencial ........................................................................................................ 116
GETSXENUM() .......................................................................................................................................... 117
CONFIRMSXE() ......................................................................................................................................... 117
ROLLBACKSXE() ...................................................................................................................................... 117
Validao .................................................................................................................................................. 117
ALLWAYSFALSE() ................................................................................................................................... 117
ALLWAYSTRUE() ..................................................................................................................................... 118
EXISTCHAV() ............................................................................................................................................ 118
EXISTCPO() ................................................................................................................................................ 118
LETTERORNUM() ..................................................................................................................................... 119
NAOVAZIO() .............................................................................................................................................. 119
NEGATIVO() .............................................................................................................................................. 119
PERTENCE() ............................................................................................................................................... 119
POSITIVO() ................................................................................................................................................. 120
TEXTO() ...................................................................................................................................................... 120
VAZIO() ...................................................................................................................................................... 120
Manipulao de parmetros do sistema ................................................................................................ 120
GETMV() ..................................................................................................................................................... 120
GETNEWPAR() .......................................................................................................................................... 121
PUTMV() ..................................................................................................................................................... 121
SUPERGETMV() ........................................................................................................................................ 121
Controle de impresso ............................................................................................................................. 122
AVALIMP() ................................................................................................................................................. 122
CABEC()...................................................................................................................................................... 123
IMPCADAST() ............................................................................................................................................ 126
MS_FLUSH() .............................................................................................................................................. 127
OURSPOOL() .............................................................................................................................................. 128
RODA() ....................................................................................................................................................... 129

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
6

SETDEFAULT() .......................................................................................................................................... 131
SETPRC() .................................................................................................................................................... 133
SETPRINT() ................................................................................................................................................ 133
Controle de processamentos ................................................................................................................... 135
ABREEXCL() .............................................................................................................................................. 135
CLOSEOPEN() ............................................................................................................................................ 135
CLOSESFILE() ............................................................................................................................................ 135
CHKFILE() .................................................................................................................................................. 136
CONOUT() .................................................................................................................................................. 136
CRIAVAR() ................................................................................................................................................. 137
DISARMTRANSACTION() ....................................................................................................................... 137
EXECBLOCK() ........................................................................................................................................... 138
EXISTBLOCK() .......................................................................................................................................... 139
ERRORBLOCK() ........................................................................................................................................ 140
FINAL() ....................................................................................................................................................... 141
FINDFUNCTION() ..................................................................................................................................... 142
FUNDESC() ................................................................................................................................................. 142
FUNNAME() ............................................................................................................................................... 142
GETAREA() ................................................................................................................................................ 143
GETCOUNTRYLIST() ............................................................................................................................... 143
ISINCALLSTACK() .................................................................................................................................... 144
REGTOMEMORY() .................................................................................................................................... 144
RESTAREA() .............................................................................................................................................. 144
USEREXCEPTION()................................................................................................................................... 145
Utilizao de recursos do ambiente ERP ............................................................................................... 145
AJUSTASX1() ............................................................................................................................................. 145
ALLUSERS() ............................................................................................................................................... 147
ALLGROUPS() ........................................................................................................................................... 149
CGC() ........................................................................................................................................................... 150
CONPAD1() ................................................................................................................................................ 150
DATAVALIDA()......................................................................................................................................... 150
EXISTINI() .................................................................................................................................................. 151
EXTENSO() ................................................................................................................................................. 151
FORMULA() ............................................................................................................................................... 152
GETADVFVAL() ........................................................................................................................................ 152
HELP() ......................................................................................................................................................... 153
MESEXTENSO()......................................................................................................................................... 153
OBRIGATORIO() ....................................................................................................................................... 154
OPENFILE() ................................................................................................................................................ 157
PERGUNTE() .............................................................................................................................................. 157
PESQPICT() ................................................................................................................................................ 157
PESQPICTQT() ........................................................................................................................................... 158
POSICIONE() .............................................................................................................................................. 158
PUTSX1() .................................................................................................................................................... 159
RETINDEX() ............................................................................................................................................... 160
SIXDESCRICAO() ...................................................................................................................................... 160
TABELA() ................................................................................................................................................... 161
TAMSX3() ................................................................................................................................................... 161
TM() ............................................................................................................................................................. 161
X1DEF01() .................................................................................................................................................. 162
X1PERGUNT() ............................................................................................................................................ 163
X2NOME() .................................................................................................................................................. 163
X3CBOX() ................................................................................................................................................... 164
X3DESCRIC() ............................................................................................................................................. 165
X3PICTURE() ............................................................................................................................................. 165
X3TITULO() ................................................................................................................................................ 166
X3USO() ...................................................................................................................................................... 166

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
7

X5DESCRI() ................................................................................................................................................ 167
X6CONTEUD() ........................................................................................................................................... 168
X6DESCRIC() ............................................................................................................................................. 168
XADESCRIC() ............................................................................................................................................ 169
XBDESCRI() ............................................................................................................................................... 170
XFILIAL() ................................................................................................................................................... 170
Componentes da interface visual............................................................................................................ 171
MSDIALOG() .............................................................................................................................................. 171
MSGET() ..................................................................................................................................................... 171
SAY() ........................................................................................................................................................... 172
BUTTON() ................................................................................................................................................... 173
SBUTTON() ................................................................................................................................................ 173
CHECKBOX() ............................................................................................................................................. 174
COMBOBOX() ............................................................................................................................................ 175
FOLDER() ................................................................................................................................................... 176
RADIO() ...................................................................................................................................................... 176
Interfaces de cadastro ............................................................................................................................. 177
AXCADASTRO() ........................................................................................................................................ 177
MBROWSE() ............................................................................................................................................... 177
AXPESQUI() ............................................................................................................................................... 178
AXVISUAL() .............................................................................................................................................. 178
AXINCLUI() ................................................................................................................................................ 178
AXALTERA() ............................................................................................................................................. 179
AXDELETA() .............................................................................................................................................. 181
Interfaces visuais para aplicaes .......................................................................................................... 181
ALERT() ...................................................................................................................................................... 181
AVISO() ....................................................................................................................................................... 182
FORMBACTH() .......................................................................................................................................... 182
MSGFUNCTIONS() .................................................................................................................................... 183
Recursos das interfaces visuais ............................................................................................................... 184
GDFIELDGET() .......................................................................................................................................... 184
GDFIELDPOS() .......................................................................................................................................... 184
GDFIELDPUT() .......................................................................................................................................... 185
GETMARK() ............................................................................................................................................... 185
MARKBREFRESH() ................................................................................................................................... 186
READVAR() ................................................................................................................................................ 187

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
8

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
9

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
10

STR()

Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos
direita.

Sintaxe: STR(nValor)
Parmetros


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

nTamanho Tamanho total desejado para a string retornada.

Exemplo:

LOCAL nPassos := 6
MSGINFO(Passos percorridos: +STRZERO(nPassos,6))

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
11

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
12

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 Valor que representa o ngulo em radianos.

Retorno:

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

Situaes invlidas:

Entrada Exceo apresentada Significado da Exceo
QNAN,IND None Sem Domnio
(cosf, cos) INVALID Sem Domnio
x 7.104760e+002 (cosh, coshf) INEXACT+OVERFLOW OVERFLOW

Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na
chamada da funo COS().

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
13

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 Valor do ngulo em radianos.

Retorno:

Numrico Retorna o valor do seno do ngulo especificado.

Situaes invlidas:

(senf, sen) INVALID Sem Domnio
x 7.104760e+002 (senh, senhf) INEXACT+OVERFLOW 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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
14

Parmetros:

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:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
15

IF TYPE(dDataBase) == D
MSGINFO(Database do sistema: +DTOC(dDataBase))
ELSE
MSGINFO(Varivel indefinida no momento)
ENDIF

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 := IIF(ValType(nTamanho) != N,1,nTamanho) // Se o parmetro foi passado
cTexto := Space(nTamanho);nLargGet := Round(nTamanho * 2.5,0);
nColf := 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
16

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:




ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
17


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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
18

nInicio indica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se
no for especificado, o valor assumido ser 01.
nQtde 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.
nPosDestino 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
19

Importante: ADir uma funo obsoleta, utilize sempre Directory().

Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora],
[ aAtributo ])

Parmetros:

cArqEspec 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 ( *.* ).
aNomeArq Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
aTamanho Array Numrico. So os tamanhos dos arquivos encontrados na busca.
aData Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
aHora Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
aAtributos 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.
nInicio a posio inicial de onde os dados sero preenchidos, o valor padro 1.
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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
20

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
21

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 Array pr-existente no qual desejasse identificar a posio que contm a
informao pesquisada.
bSeek 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
22

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 Representa o objeto a ser varrido pela funo, pode ser atribudo ao
parmetro um array um Objeto.
bSeek Representa o valor que ser pesquisado, podendo ser um bloco de cdigo.
nInicio Representa o elemento a partir do qual ter inicio a pesquisa, quando este
argumento no for informado o valor default ser 1.
nCont 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
23

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 Array pr-existente que ter seu contedo ordenado atravs de um critrio
estabelecido.
nInicio Posio inicial do array para incio da ordenao. Caso no seja informado, o
array ser ordenado a partir de seu primeiro elemento.
nItens Quantos itens, a partir da posio inicial devero ser ordenados. Caso no
seja informado, sero ordenados todos os elementos do array.
bOrdem 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
24

Ao Z-> expresso que ser executadas pelo bloco de cdigo
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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
25

Retorno:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
26

bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada registro do alias ativo.

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
27

Parmetros

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.
nFim Elemento final do array, at o qual sero avaliados os blocos de cdigo.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
28

ASC()

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
29

AT()

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
30

Sintaxe: CAPITAL(cFrase)

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
31

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

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,

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
32

caso contrrio, retorna falso (.F.).

ISDIGIT()

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:


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:


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:


ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
33

Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo ,

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
34

Sintaxe: LTRIM ( < cString > )
Parmetros:

cString <cString> a cadeia de caracteres a ser copiada sem os espaos em branco
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 String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.
cOperacao Representa a string que indica a operao que desejamos realizar. Olhar na
tabela para verificar quais valores devem ser informados aqui.
cNum2 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 > )

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
35

Parmetros:

cStringOEM String em formato OEM - MsDos a ser convertida.

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.
nTamanho Tamanho da cadeia de caracteres a ser retornada.
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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
36

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

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
37

SPACE()

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 Representa a cadeia de caracteres no qual desejamos separar de acordo com
<cToken>.
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 ] )

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
38

Parmetros:

cString Seqncia de caracteres ou campo memo a ser pesquisado.
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 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 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.

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 A cadeia de caracteres destino na qual sero eliminados e inseridos
caracteres.
nPosInicial A posio inicial na cadeia de caracteres destino onde ocorre a
insero/eliminao.
nExcluir A quantidade de caracteres a serem eliminados.
cAdicao A cadeia de caracteres a ser inserida.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
39

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

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 O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
cSayPicture 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
40

Exemplo:

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 Data que ser convertida.

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
41

Exemplo:

cMes := CMONTH(DATE()) // Resultado: September
cMes := CMONTH(DATE() + 45) // Resultado: October
cMes := CMONTH(CTOD("12/01/94")) // Resultado: December
cMes := 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:


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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
42

// Estes exemplos mostram a funo DAY() de diversas maneiras:
nDia := DAY(DATE()) // Resultado: 1
nDia := DAY(DATE()) + 1 // Resultado: 2
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:


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:


ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
43

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


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 Informe a hora inicial no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),
mm os minutos e ss os segundos
CHoraFinal Informe a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm
os minutos e ss os segundos.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
44

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.

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:


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,

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
45

baseado no relgio de 24 horas e varia de 0 a 86399.

Exemplo:

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:


Retorno:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
46

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.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
47

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


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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
48

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

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
49

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.

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 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 ( *.* ).
aNomeArq Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
aTamanho Array Numrico. So os tamanhos dos arquivos encontrados na busca.
aData Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
aHora Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
aAtributos 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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
50

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
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' , 'Fontes', 1, 'C:\VER507', .F., GETF_LOCALHARD +
GETF_LOCALFLOPPY)

Aparncia:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
51

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
52

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

STATIC FUNCTION PARBOXFILE()

Local aParamBox := {}
Local cTitulo := "Filtros Adicionais"
Local aRet := {}
Local bOk := {|| .T.}
Local aButtons := {}
Local lCentered := .T.
Local nPosx

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
53

Local nPosy
Local cLoad := ""
Local lCanSave := .F.
Local lUserSave := .F.
Local nX := 0
Local 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. |
//+--------------------------------------------------------------------+
//+--------------------------------------------------------------------+

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
54

//+--------------------------------------------------------------------+
//| aChaveArq - Contem os arquivos que sero exibidos para seleo |
//+--------------------------------------------------------------------+
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 |
//+--------------------------------------------------------------------+
//+--------------------------------------------------------------------+

STATIC FUNCTION Troca(nIt,aArray)
aArray[nIt,1] := !aArray[nIt,1]
Return aArray

Funo auxiliar: MARCAOK()

//+--------------------------------------------------------------------+
//| Rotina | MARCAOK | Autor | | Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//+--------------------------------------------------------------------+

STATIC FUNCTION MarcaOk(aArray)
Local lRet:=.F.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
55

Local nx:=0

// 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 Nome(s) dos arquivos a serem copiados, aceita apenas arquivos no servidor,
WildCards ( * e ? ) so aceitos normalmente.
cDestino 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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
56

cOrigem Nomes dos arquivos a serem copiados, aceita apenas arquivos locais (
Cliente ), WildCards so aceitos normalmente.
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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
57

DIRECTORY()

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

Sintaxe: DIRECTORY ( < cDirSpec > , [ ] )

Parmetros:

cDirSpec

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
58

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.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
59

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
executado o Protheus Remote. Atravs do parmetro nDrive , selecionamos qual a unidade de
disco que desejamos obter a informao do espao livre , onde:

0 : Unidade de disco atual da estao (DEFAULT).
1 : Drive A: da estao remota.
2 : Drive B: da estao remota.
3 : Drive C: da estao remota.
4 : Drive D: da estao remota ... e assim por diante.

Caso a funo DiskSpace seja executada atravs de um Job ( processo isolado no Servidor ,
sem interface Remota ) , ou seja passado um argumento de unidade de disco inexistente ou
indisponvel , a funo DISKSPACE() retornar -1

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
60

Parmetros:

cPath String contendo o diretrio que ser verificado, caso seja feita uma
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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
61

If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf

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 0 Criao normal do Arquivo (default/padro).
FC_READONLY 1 Cria o arquivo protegido para gravao.
FC_HIDDEN 2 Cria o arquivo como oculto.
FC_SYSTEM 4 Cria o arquivo como sistema.

Caso desejemos especificar mais de um atributo , basta som-los . Por exemplo , para criar
um arquivo 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 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 .
nAtributo 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()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
62

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:

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
63

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
64

declarado explicitamente como parte do argumento <cArq>.

Por serem executadas em um ambiente cliente-servidor, as funes de
tratamento de arquivos podem trabalhar em arquivos localizados no cliente
(estao) ou no servidor. O ADVPL identifica o local onde o arquivo ser
manipulado atravs da existncia ou no da letra do drive no nome do
arquivo passado em <cArq>. Ou seja, se o arquivo for especificado com a
letra do drive, ser aberto na estao. Caso contrrio, ser aberto no
servidor com o diretrio configurado como rootpath sendo o diretrio 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
0 FO_READ Aberto para leitura (padro assumido)
1 FO_WRITE Aberto para gravao
2 FO_READWRITE Aberto para leitura e gravao

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
65

Tabela B: Modos de acesso de compartilhamento a arquivos binrios

Modo Constate(fileio.ch) Operao
0 FO_COMPAT Modo de Compatibilidade (Default)
16 FO_EXCLUSIVE Acesso total exclusivo
32 FO_DENYWRITE Acesso bloqueando a gravao de outros
processos ao arquivo.
48 FO_DENYREAD Acesso bloqueando a leitura de outros
processos ao arquivo.
64 FO_DENYNONE 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 o manipulador (Handle) retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT(), que faz referncia ao arquivo a ser lido.
cBuffer 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.
nQtdBytes 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
66

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:

nHandle o manipulador retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT().
nQtdBytes Nmero mximo de bytes que devem ser lidos.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
67

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.

Origem Constate(fileio.ch) Operao
0 FS_SET Ajusta a partir do inicio do arquivo. (Default)
1 FS_RELATIVE Ajuste relativo a posio atual do arquivo.
2 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.
nOrigem Indica a partir de qual posio do arquivo, o nOffset ser considerado.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
68

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
69

FT_FUse('teste.txt') // Abre o arquivo
CONOUT("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln()+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
70

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 .

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
71

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

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 o manipulador de arquivo ou device retornado pelas funes FOPEN(),
FCREATE(), ou FOPENPORT().
cBuffer <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 <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)


ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
72

// Testa a abertura do Arquivo
If nHOrigem == -1
MsgStop('Erro ao abrir origem. Ferror = '+str(ferror(),4),'Erro')
Return .F.
Endif

// Determina o tamanho do arquivo de origem
nTamArquivo := Fseek(nHOrigem,0,2)

// Move o ponteiro do arquivo de origem para o inicio do arquivo
Fseek(nHOrigem,0)

// Cria o arquivo de destino
nHDestino := FCREATE("DESTINO.TXT", FC_NORMAL)

// Testa a criao do arquivo de destino
If nHDestino == -1
MsgStop('Erro ao criar destino. Ferror = '+str(ferror(),4),'Erro')
FCLOSE(nHOrigem) // Fecha o arquivo de Origem
Return .F.
Endif

// Define que a quantidade que falta copiar o prprio tamanho do Arquivo
nBytesFalta := nTamArquivo

// Enquanto houver dados a serem copiados
While nBytesFalta > 0

// Determina quantidade de dados a serem lidos
nBytesLer := Min(nBytesFalta , F_BLOCK )

// l os dados do Arquivo
nBytesLidos := FREAD(nHOrigem, @cBuffer, nBytesLer )

// Determina se no houve falha na leitura
If nBytesLidos < nBytesLer
MsgStop( "Erro de Leitura da Origem. "+;
Str(nBytesLer,8,2)+" bytes a LER."+;
Str(nBytesLidos,8,2)+" bytes Lidos."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
Exit
Endif

// Salva os dados lidos no arquivo de destino
nBytesSalvo := FWRITE(nHDestino, cBuffer,nBytesLer)

// Determina se no houve falha na gravao
If nBytesSalvo < nBytesLer
MsgStop("Erro de gravao do Destino. "+;
Str(nBytesLer,8,2)+" bytes a SALVAR."+;
Str(nBytesSalvo,8,2)+" bytes gravados."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
EXIT
Endif

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
73


// Elimina do Total do Arquivo a quantidade de bytes copiados
nBytesFalta -= nBytesLer

Enddo

// Fecha os arquivos de origem e destino
FCLOSE(nHOrigem)
FCLOSE(nHDestino)

If lCopiaOk
MsgStop('Cpia de Arquivos finalizada com sucesso. '+;
str(nTamArquivo,12,0)+' bytes copiados.','Final')
Else
MsgStop( 'Falha na Cpia. Arquivo de Destino incompleto. '+;
'Do total de '+str(nTamArquivo,12,0)+' bytes, faltaram
'+str(nBytesFalta,12,0)+' bytes.','Final')
Endif

Return

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 )

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
74

Parmetros:

cArqOrig
Nome do arquivo origem e a extenso se o ambiente for Top o parmetro
passar a ser obrigatrio.
cArqDest Nome do arquivo destino e a extenso.

Retorno:

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
75

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

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
76

Lgico Indica se o arquivo especificado existe.

Exemplo:

Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If !MsFile ( cArquivo, cIndice )
APMsgInfo( 'Arquivo no encontrado!' )
EndIf

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 Array multidimensional contendo a estrutura de campos da tabela que ser

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
77

criada no formato: {Nome, Tipo, Tamanho, Decimal}
lDbf Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )

Retorno:

Caracter Nome do Arquivo gerado pela funo.

Exemplo:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
78

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

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 testar uma
condio de limite de inicial do arquivo quando o ponteiro de registros est se movendo
para trs em um arquivo de banco de dados.
EOF() uma funo de tratamento de banco de dados utilizada para testar uma
condio de limite de final de arquivo quando o ponteiro de registros est se movendo
para frente em um arquivo de banco de dados.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
79

(.F.). Se o arquivo de banco de dados corrente no possui registros, EOF()
retorna verdadeiro (.T.).

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
80

Separador de Registros CRLF ( ASCII 13 + ASCII 10 )
Marca de final de arquivo (EOF) Nenhum

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
81

OBSERVAO : Vale a pena lembrar que o escopo sensvel tambm s
demais condies de filtro ( WHILE / FOR ).
WHILE <lCondicao> 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> 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] [ 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.

Nas Tabelas complementares A e B, na documentao do comando, so
detalhadas as especificaes dos formatos SDF e DELIMITED.
VIA <cDriver> 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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
82

COPY STRUCTURE TO <xcDataBase>

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
83

Nenhum .

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
84

Nenhum .

Retorno:

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, libera todos os registros
bloqueados e fecha todas as tabelas abertas (reas de trabalho) como se
chamasse DBCLOSEAREA para cada rea de trabalho.

Sintaxe: DBCLOSEALL()

Parmetros:

Nenhum .

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
85

Parmetros:

Nenhum .

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
86

Nenhum .

Retorno:

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 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"
aESTRUTURA Lista com as informaes dos campos para ser criada a tabela.
cDRIVER 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
87

DBCREATE('\teste\cliente.dbf', aEstrutura)
USE '\teste\cliente.dbf' VIA 'DBFCDX' NEW

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
88

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.

Sintaxe: DBCREATEINDEX(<cNOME>, <cEXPCHAVE>, [bEXPCHAVE],
[lUNICO])

Parmetros:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
89

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
90

nINFOTIPO Tipo de informao a ser verificada (DBS_NAME, DBS_DEC, DBS_LEN e
DBS_TYPE).
nCAMPO Posio do campo a ser verificado.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
91

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
92

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
93

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:


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

Exemplo:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
94

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:


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.

Retorno:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
95

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 .

Exemplo:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
96

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

DBRECORDINFO()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
97

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:


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

Parmetros:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
98

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
99

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
100

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
101

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
102

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
103

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
104

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

nRegistros Define em quantos registros o cursor ser deslocado. Padro 1

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
105

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.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
106

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 .

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
107

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

lNovo
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.
cDriver
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.
cArquivo
Nome do arquivo de base de dados que ser aberto com o alias
especificado.
cAlias 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.

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 .

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
108

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
109

Exemplo:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
110

existe ndice aberto na tabela corrente.

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 Se o RDD corrente for DBFCDX os registros sero adicionados na rea
selecionada, caso contrrio o arquivo destino ter que ser informado.
cArqOrig Nome do arquivo origem contendo os registros a serem adicionados.

Retorno:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
111

Lgico Se a operao for realizada com sucesso o funo retornar verdadeiro (.T.).

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
112

Exemplo:

cArqTRB := CriaTrab(aStruTRB,.T.)
// 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 H duas opes para o primeiro parmetro:
cNome: tipo caracter, contm nome do ndice.
nPosicao: tipo numrico, indica ordem do ndice.
nPosicao
cArqIndice 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
113

Sintaxe: RecLock(cAlias,lInclui)
Parmetros

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
114

A sintaxe e a descrio destas funes esto disponveis no Guia de
Referncia Rpido ao final deste material.

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
115

SET FILTER TO

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
116

cAlias
Alias de referncia da rea de trabalho ativa, para o qual o registro
posicionado ser travado.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
117

GETSXENUM()

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
Alias de referncia da tabela para a qual ser efetuado o controle da
numerao seqencial.
cCampo Nome do campo no qual est implementado o controle da numerao.
cAliasSXE
Parmetro opcional, quando o nome do alias nos arquivos de controle de
numerao no o nome convencional do alias para o sistema ERP.
nOrdem 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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
118

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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
119

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.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
120

Sintaxe: Pertence(cString)
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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
121

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
122

Sintaxe: SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)
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()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
123

LOCAL cTitulo := PADC(AVALIMP,74)
LOCAL cDesc1 := PADC(Demonstrao do uso da funo AVALIMP(),74)
LOCAL cDesc2 :=
LOCAL cDesc3 := PADC(CURSO DE ADVPL,74)
LOCAL cTamanho := G
LOCAL cLimite := 220
LOCAL cNatureza :=
LOCAL aReturn := {Especial, 1,Administrao, 1, 2, 2,,1}
LOCAL cNomeProg := RAVALIMP
LOCAL cPerg := PADR(RAVALIMP,10) // Compatibilizao com MP10
LOCAL nLastKey := 0
LOCAL cString :=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() |
|+----------------------------------------------------------------------------
|+----------------------------------------------------------------------------
/*/

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
124

Sintaxe: Cabec(cTitulo, cCabec1, cCabec2, cNomeProg, nTamanho, nCompress,
aCustomText, lPerg, cLogo)

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).
aCustomText
Texto especfico para o cabealho, substituindo a estrutura padro do
sistema.
lPerg
Permite a supresso da impresso das perguntas do relatrio, mesmo que
o parmetro MV_IMPSX1 esteja definido como S

Parmetros (continuao):

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

Retorno:

Nenhum .

Exemplo:

#INCLUDE "protheus.ch"

/*/
+-----------------------------------------------------------------------------
| Funo | MPTR001 | Autor | | Data | 01.01.2007 |
+-----------------------------------------------------------------------------
| Descrio | Exemplo de utilizao das funes de impresso CABEC() |
|+----------------------------------------------------------------------------
|+----------------------------------------------------------------------------
/*/

User Function MPTR001()

Local cDesc1 := "Este programa tem como objetivo imprimir relatorio "
Local cDesc2 := "de acordo com os parametros informados pelo usuario."
Local cDesc3 := "Listagem de clientes"
Local cTitulo := "Listagem de clientes"
Local lImprime := .T.

// Parametros da SetPrint()
Local cString := "SA1"
Local cPerg := ""
Local lDic := .T. // Habilita a visalizacao do dicionario

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
125

Local aOrd := RetSixOrd(cString)
Local lCompres := .T. // .F. - Normal / .T. - Comprimido
Local lFilter := .T. // Habilita o filtro para o usuario
Local cNomeProg := "MPTR002"
Local cTamanho := "M"
Local nTipo := 18
Local nLimite := 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 := 0
Private m_pag := 01
Private wnrel := "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, 2-
Paisagem

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
126

|+----------------------------------------------------------------------------
/*/

Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)

Local nLin := 80
Local cCabec1 := ""
Local cCabec2 := ""
Local cArqInd

cCabec1 := "CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME REDUZIDO"+Space(9)
cCabec1 += "RAZAO SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
cCabec1 += "CEP"
cCabec2 := "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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
127

M- 132 colunas
G- 220 colunas
cAlias Alias do arquivo de cadastro que ser impresso

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() |
|+----------------------------------------------------------------------------
|+----------------------------------------------------------------------------
| Observao| Continuao do exemplo da funo CABEC() |
|+----------------------------------------------------------------------------
/*/

Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)

Local nLin := 80
Local cCabec1 := ""
Local cCabec2 := ""
Local cArqInd

cCabec1 := "CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME REDUZIDO"+Space(9)
cCabec1 += "RAZAO SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
cCabec1 += "CEP"
cCabec2 := "ESTADO"+Space(2)+"MUNICIPIO"+Space(8)+"ENDERECO"

dbSelectArea("TRBSA1")
dbGoTop()

SetRegua(RecCount())

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
128

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

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
129

Parmetros:

cArquivo Nome do relatrio a ser visualizado.

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.|
|+----------------------------------------------------------------------------
|+----------------------------------------------------------------------------
/*/

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
130

#include "protheus.ch"

User Function TestImpr()
Local wnrel
Local cString := "SA1"
Local titulo := "Teste Impresso de Relatorios"
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(). |
|+----------------------------------------------------------------------------
|+----------------------------------------------------------------------------
/*/
User Function TestRel(lEnd,WnRel,cString,Tamanho,NomeProg)

LOCAL cabec1,cabec2
LOCAL cRodaTxt := oemtoansi("Rodap")
Local nCntImpr
Local 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
131

@ Li,51 PSAY A1_NREDUZ
If Li > 60
Li:=66
Endif
dbSkip()
EndDO

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
132

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
133

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
134

cTitle Ttulo do relatrio.

Parmetros (continuao):

cDesc1 Descrio do relatrio.
cDesc2 Continuao da descrio do relatrio.
cDesc3 Continuao da descrio do relatrio.
lDic
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.
aOrd Ordem(s) de impresso.
lCompres
Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro
assumido ser .T.
cSize Tamanho do relatrio "P","M" ou "G".
uParm12 Parmetro reservado
lFilter
Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro
assumido ser .T.
lCrystal
Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro
assumido ser .F.
cNameDrv Nome de um driver de impresso.
lServer Se verdadeiro (.T.) fora impresso no servidor.
cPortPrint Define uma porta de impresso padro.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
135

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
136

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.).
cNewAlias Novo Alias para re-abertura do arquivo.

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
137

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
138

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, finalizar o
processamento, dever ser utilizada a funo USEREXCEPTION().

Sintaxe: DISARMTRANSACTION()

Parmetros:

Nenhum .

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
139

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
140

LOCAL cNota := PARAMIXB[1]
LOCAL cSerie:= PARAMIXB[1]
LOCAL cFornece:= PARAMIXB[1]
LOCAL 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) } )

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
141

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
142

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
143

Nenhum .

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
144

ISINCALLSTACK()

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 Alias do arquivo que ser utilizado como referncia para inicializao das
variveis de memria.
lInclui 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
145

User Function XATF001()

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
146

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

Estrutura Item do array aPerg (continuao):

portugus

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
147

portugus
36 X1_F3 Caractere Cdigo da consulta F3 vinculada ao
parmetro
37 X1_GRPSXG Caractere Cdigo do grupo de campos SXG para
atualizao automtica, quando o grupo for
alterado.
38 X1_PYME Caractere Se a pergunta estar disponvel no ambiente
Pyme
39 X1_HELP Caractere Contedo do campo X1_HELP
40 X1_PICTURE Caractere Picture de formatao do contedo do
campo.
41 aHelpPor Array Vetor simples contendo as linhas de help em
portugus para o parmetro. Trabalhar com
linhas de at 40 caracteres.
42 aHelpEng Array Vetor simples contendo as linhas de help em
ingls para o parmetro. Trabalhar com
43 aHelpSpa Array Vetor simples contendo as linhas de help em
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 Descrio Tipo Qtd.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
148

1
1 ID C 6
2 Nome C 15
3 Senha C 6
4 Nome Completo C 30
5 Vetor com n ltimas senhas A --
6 Data de validade D 8
7 Quantas vezes para expirar N 4
8 Autorizado a alterar a senha L 1
9 Alterar a senha no prximo logon L 1
10 Vetor com os grupos A --
11 ID do superior C 6
12 Departamento C 30
13 Cargo C 30
14 E-Mail C 130
15 Nmero de acessos simultneos N 4
16 Data da ltima alterao D 8
17 Usurio bloqueado L 1
18 Nmero de dgitos para o ano N 1
19 Listner de ligaes L 1
20 Ramal C 4

Array de informaes dos usurios: Configuraes de impresso

2
1 Vetor com horrios de acesso A --
2 Idioma N 1
3 Diretrio C 100
4 Impressora C --
5 Acessos C 512
6 Vetor com empresas A --
7 Ponto de entrada C 10
8 Tipo de impresso N 1
9 Formato N 1
10 Ambiente N 1
11 Prioridade p/ config. do grupo L 1
12 Opo de impresso C 50
13 Acesso a outros dir de
impresso
L 1

Array de informaes dos usurios: Configuraes de acesso aos mdulos

3

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
149

1 Mdulo+nvel+menu C

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

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

Array de informaes dos grupos: Configuraes de acesso aos mdulos

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
150

2
1 Modulo+nvel+menu C

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.
uPar4
Parmetro Reservado.

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
151

Sintaxe: DATAVALIDA(dData)

Parmetros:

dData Data a partir da qual ser avaliada a prxima data vlida, considerando-a
inclusive como uma possibilidade.

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
152

Retorno:

String Descrio do valor por extenso.

FORMULA()

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 Nome de um campo ou array contendo os nomes dos campos
desejados
uChave 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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
153

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.

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
154

nMes Indica o nmero do ms a ter seu nome escrito por extenso.

Este parmetro pode ser definido tambm como caracter ou como data.

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 Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no
fonte.
aTela Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no
fonte.
aTitulos 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" ,0,1} ,;
{"Visualizar" ,"AxVisual" ,0,2} ,;
{"Atualizar" ,"U_A010AATU" ,0,4}}

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
155

Private cDelFunc := ".T."
Private cString := "SN1"

dbSelectArea("SN1")
dbSetOrder(1)
dbSelectArea(cString)
mBrowse( 6,1,22,75,cString)

Return

/*/
+-----------------------------------------------------------------------------
| Programa | A010AATU | Autor | | Data | |
+-----------------------------------------------------------------------------
| Desc. | Atualizao de dados do bem Ativo Fixo |
+-----------------------------------------------------------------------------
+-----------------------------------------------------------------------------
/*/

User Function A010AATU(cAlias,nReg,nOpc)

Local aCpoEnch := {}
Local aAlter := {}

Local aButtons := {}
Local cAliasE := cAlias
Local aAlterEnch := {}
Local aPos := {015,000,400,600
Local nModelo :=
Local lF3 := .F.
Local lMemoria := .T.
Local lColumn := .F.
Local caTela := ""
Local lNoFolder := .F.
Local lProperty := .F.


Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0] // Variveis que sero atualizadas pela Enchoice()
Private aGETS[0] // 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()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
156

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
AADD(aAlterEnch,"N1_LOJA") // Loja do Fornecedor
AADD(aAlterEnch,"N1_NSERIE") // Serie da Nota
AADD(aAlterEnch,"N1_NFISCAL") // Numero da Nota
AADD(aAlterEnch,"N1_NFITEM") // Item da Nota
AADD(aAlterEnch,"N1_UM") // Unidade de Medida
AADD(aAlterEnch,"N1_PRODUTO") // Cdigo do Produto
AADD(aAlterEnch,"N1_PEDIDO") // Codigo do Pedido de Compras
AADD(aAlterEnch,"N1_ITEMPED") // Item do Pedido de Compras
AADD(aAlterEnch,"N1_PRCIMP") // Codigo do Processo de Importacao
AADD(aAlterEnch,"N1_CODPAIS") // Codigo do Pais
AADD(aAlterEnch,"N1_ORIGCPR") // Origem de Compras
AADD(aAlterEnch,"N1_CODSP") // Codigo da SP Interna
AADD(aAlterEnch,"N1_CHASSIS") // 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 |
+-----------------------------------------------------------------------------
+-----------------------------------------------------------------------------
/*/
Static Function A010AGRV(aCpos,aAlter,nOpc)

Local aArea := GetArea()
Local nX := 0

IF !Obrigatorio(aGets,aTela) /*Valida o cabecalho*/
Return .F.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
157

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

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
158

A funo PESQPICT() retorna a picture definida para um campo especificado no Dicionrio de
Dados (SX3).

Sintaxe: PesqPict(cAlias,cCampo,nTam)

Parmetros:

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:

nOrdem Ordem utilizada
cChave Chave pesquisa

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
159

cCampo Campo a ser retornado

Retorno:

Indefinido Contedo do campo solicitado.

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 Cdigo da consulta F3 vinculada ao parmetro
cGrpSxg
Cdigo do grupo de campos SXG para atualizao automtica, quando o
grupo for alterado.
cPyme 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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
160

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 Descrio da opo X do combo em espanhol
cDefEngx Descrio da opo X do combo em ingls
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.
aHelpSpa Vetor simples contendo as linhas de help em espanhol para o parmetro.
cHelp Contedo do campo X1_HELP

RETINDEX()

A funo RETINDEX() restaura os ndices padres de um alias definidos no Dicionrio de
Dados (SIX).

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
161

Exemplo:

User Function <nome-da-funo>( cChave, cOrdem )
Local cSixDesc :=

dbSelectArea(SIX)
dbSetOrder(1)

If dbSeek(cChave+cOrdem)
cSixDescr := SixDescricao()
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()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
162

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
163

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()
cDef03 := X1Def03()
cDef04 := X1Def04()
cDef05 := X1Def05()
EndIf

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
164

Nenhum .

Retorno:

String Descrio da tabela posicionada no Dicionrio de Dados (SX2) no idioma
corrente.

Exemplo:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
165

Return

X3DESCRIC()

A funo X3DESCRIC() retorna a descrio de um campo posicionado no Dicionrio de Dados
(SX3) no idioma corrente.

Sintaxe: X3DESCRIC()

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
166

String Picture do campo informado.

Exemplo:

User Function <nome-da-funo>( cCampo )

Local cPicture

cPicture := X3Picture( cCampo )
Return cPicture

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
167

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:

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
168

Return

X6CONTEUD()

A funo X6CONTEUD() retorna o contedo de um parmetro posicionado no Dicionrio de
Dados (SX6) para o idioma corrente.

Sintaxe: X6CONTEUD()

Parmetros:

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
169

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:

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
170

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

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
171

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.

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
172

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
campo.
nLargura,nAltura Dimenses do objeto MsGet para exibio do texto.
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 SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
173


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.

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

Sintaxe: SBUTTON()

DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF oObjetoRet

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
174

Parmetros

nLinha, nColuna
Posio do objeto sButton em funo da janela em que ele ser
definido.
TYPE N
Nmero que indica o tipo do boto (imagem) pr-definida que ser
utilizada.
AO
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 Objeto dialog no qual o componente ser definido.

Exemplo:

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:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
175

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.
nLargura,nAltura Dimenses do objeto CheckBox.
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
Posio do objeto ComboBox em funo da janela em que ele ser
definido.
VARIAVEL
Varivel do tipo caracter que ir receber a descrio do item
selecionado no ComboBox.
AITENS
Vetor simples contendo as strings que sero exibidas como opes do
ComboBox.
nLargura,nAltura Dimenses do objeto ComboBox.

Exemplo:

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
176

@ 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

Parmetros

nLinha,nColuna
Posio do objeto Folder em funo da janela em que ele ser
definido.
oFolder Objeto Folder que ser criado.
&cTexto1,,&cTextoX
Strings de ttulos de cada uma das abas do Folder, sempre
precedidas por &. Exemplo: &Pasta1,&PastaX.
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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
177

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,...,cItemX Texto que ser vinculado a cada RadioButton.
CHANGE
Funo ou lista de expresses que ser executada na
mudana de um item de um RadioButton para outro.
CLICK
Funo ou lista de expresses que ser executada na
seleo de um item RadioButton.

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
178

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

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
Nmero da linha do aRotina que definir o tipo de edio (Incluso,
Alterao, Excluso, Visualizao).
aAcho
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
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.
aButtons
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
lMaximized 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)

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
179

Parmetros

nOpc
aAcho
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".
cFunc
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.
aCpos Vetor com nome dos campos que podero ser editados
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
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().
aAuto
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
lVirtual
Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de
memria ou os campos da tabela na edio

AXALTERA()

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
180

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
181

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

nOpc
cTransact Funo que ser executada dentro da transao da AxFunction()
aCpos Vetor com nome dos campos que podero ser editados
aButtons
aParam
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().
aAuto
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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
182

cTexto Texto a ser exibido

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 Ttulo da janela
aTexto
Array simples (vetor) contendo cada uma das linhas de texto que sero
exibidas no corpo da tela.
aBotoes
Array com os botes do tipo SBUTTON(), com a seguinte estrutura:

{nTipo,lEnable,{|| Ao() }}

bValid (opcional) Bloco de validao do janela

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
183

nAltura (opcional) Altura em pixels da janela
nLargura (opcional) Largura em pixels da janela

MSGFUNCTIONS()

Sintaxe: MSGALERT(cTexto, cTitulo)
Sintaxe: MSGINFO(cTexto, cTitulo)
Sintaxe: MSGSTOP(cTexto, cTitulo)
Sintaxe: MSGYESNO(cTexto, cTitulo)

Parmetros

cTexto Texto a ser exibido como mensagem
cTitulo Ttulo da janela de mensagem
MSGALERT

MSGINFO

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
184

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

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
185

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.

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
186

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 .

ADVPL
GUIA DE REFERNCIA

Escola Parceira
Certificao

T e l : 1 1 5 0 1 1 4 8 9 5 / 5 0 1 1 6 0 8 2 / 9 8 0 8 1 9 8 8
187

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.

AdvPL 0 - Guia de Referencia

Enviado por

Dados do documento

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 0 - Guia de Referencia

Enviado por

Direitos autorais:

Formatos disponíveis

ADVPL

Você também pode gostar