Você está na página 1de 535

Educao Corporativa

ADVPL Avanado
(Capacitao Interna)

Matriz Av. Braz Leme, 1.717 02511-000 So Paulo SP Brasil.


Tel.: 55 (11) 3981-7001 www.totvs.com.br

ESTRUTURA DO TREINAMENTO
OBJETIVOS DO CURSO............................................................................................................................... 11
MDULO 05: Introduo orientao objetos ........................................................................................ 12
1.

Conceitos de orientao objetos..................................................................................................... 12


1.1.

Definies ................................................................................................................................. 12

1.2.

Conceitos Bsicos ..................................................................................................................... 15

1.3.
O
1.3.1.
1.3.2.
1.3.3.
1.3.4.
2.

3.

Modelo de Objetos (OMT) ...................................................................................................... 16


Objetos e Classes ..................................................................................................................... 16
Atributos ................................................................................................................................. 17
Operaes e Mtodos ................................................................................................................ 18
Sugestes de desenvolvimento................................................................................................... 19

Orientao a objetos em ADVPL ........................................................................................................ 20


2.1.

Sintaxe e operadores para orientao a objetos ....................................................................... 20

2.2.

Estrutura de uma classe de objetos em ADVPL ......................................................................... 23

2.3.

Implementao dos mtodos de uma classe em ADVPL ............................................................ 24

Regras adicionais da linguagem ADVPL............................................................................................. 28


3.1.

Palavras reservadas.................................................................................................................. 28

3.2.

Pictures de formatao disponveis .......................................................................................... 29

MDULO 07: ADVPL Orientado objetos II ............................................................................................... 30


4.

Componentes da interface visual do ADVPL ...................................................................................... 30


TSRVOBJECT().............................................................................................................................. 32
TFONT() ...................................................................................................................................... 35
MSDIALOG() ................................................................................................................................ 36
TDIALOG() ................................................................................................................................... 37
TWINDOW() ................................................................................................................................. 40
TCONTROL() ................................................................................................................................ 43
BRGETDDB() ................................................................................................................................ 44
MSCALEND() ................................................................................................................................ 47
MSCALENDGRID()......................................................................................................................... 49
MSSELBR() .................................................................................................................................. 51
MSWORKTIME()............................................................................................................................ 54
SBUTTON() .................................................................................................................................. 57
TBAR() ........................................................................................................................................ 59
TBITMAP() ................................................................................................................................... 61
TBROWSEBUTTON() ...................................................................................................................... 63
TBTNBMP() .................................................................................................................................. 65
TBTNBMP2()................................................................................................................................. 67
TBUTTON() .................................................................................................................................. 69
TCBROWSE()................................................................................................................................ 71
TCHECKBOX() .............................................................................................................................. 75
TCOLORTRIANGLE() ...................................................................................................................... 77
TCOMBOBOX() ............................................................................................................................. 79
TFOLDER() ................................................................................................................................... 82
TGET() ........................................................................................................................................ 84
TGROUP() .................................................................................................................................... 86
THBUTTON() ................................................................................................................................ 88
TIBROWSER() .............................................................................................................................. 89
TLISTBOX().................................................................................................................................. 91
TMENU()...................................................................................................................................... 95
TMENUBAR() ................................................................................................................................ 96
TMETER() .................................................................................................................................... 97
TMSGRAPHIC() ........................................................................................................................... 100
TMSGBAR() ................................................................................................................................ 106
TMSGITEM()............................................................................................................................... 108
TMULTIBTN() ............................................................................................................................. 109
TMULTIGET().............................................................................................................................. 112
TOLECONTAINER()...................................................................................................................... 114

-2ADVPL Avanado

TPAGEVIEW() ............................................................................................................................. 116


TPANEL() ................................................................................................................................... 118
TRADMENU() .............................................................................................................................. 119
TSBROWSE().............................................................................................................................. 123
TSAY() ...................................................................................................................................... 127
TSCROLLBOX() ........................................................................................................................... 129
TSIMPLEEDITOR()....................................................................................................................... 130
TSLIDER().................................................................................................................................. 135
TSPLITTER()............................................................................................................................... 138
TTABS()..................................................................................................................................... 142
TTOOLBOX() .............................................................................................................................. 144
TWBROWSE() ............................................................................................................................. 147
VCBROWSE() ............................................................................................................................. 151
4.1.
Particularidades dos componentes visuais.............................................................................. 157
4.1.1. Configurando as cores para os componentes .............................................................................. 157
5.

Aplicaes com a interface visual do ADVPL.................................................................................... 159


5.1.
Captura de informaes simples (Multi-Gets) ......................................................................... 159
5.1.1. Enchoice() ............................................................................................................................. 160
5.1.2. MsMGet()............................................................................................................................... 162
5.2.
Captura de mltiplas informaes (Multi-Lines) ..................................................................... 164
5.2.1. MsGetDB() ............................................................................................................................. 165
5.2.2. MsGetDados() ........................................................................................................................ 169
5.2.3. MsNewGetDados() .................................................................................................................. 173
5.2.3.1.
Definindo cores personalizadas para o objeto MsNewGetDados() .......................................... 178
5.3.
Barras de botes..................................................................................................................... 183
5.3.1. EnchoiceBar()......................................................................................................................... 183
5.3.2. TBar() ................................................................................................................................... 185
5.3.3. ButtonBar .............................................................................................................................. 186
5.3.4. Imagens pr-definidas para as barras de botes ......................................................................... 189

6.

Outras aplicaes da interface visual do ADVPL .............................................................................. 190


6.1.
MaWndBrowse() ..................................................................................................................... 190
6.1.1. Enchoice para Arquivos Temporrios ......................................................................................... 193

7.

6.2.

DbTree() ................................................................................................................................. 203

6.3.

MsSelect() .............................................................................................................................. 208

Introduo relatrios grficos ...................................................................................................... 211


7.1.
TReport()................................................................................................................................ 211
7.1.1. Introduo ............................................................................................................................. 211
Finalidade .................................................................................................................................. 211
Descrio................................................................................................................................... 212
Pr-Requisitos ............................................................................................................................ 212
7.1.2. Impresso do relatrio personalizvel........................................................................................ 213
7.1.2.1.
Parmetros de impresso ................................................................................................ 213
Impresso.................................................................................................................................. 213
Arquivo...................................................................................................................................... 213
Spool ........................................................................................................................................ 214
E-mail ....................................................................................................................................... 214
Papel......................................................................................................................................... 215
Tamanho do papel ...................................................................................................................... 215
Formato da impresso ................................................................................................................. 215
Configuraes............................................................................................................................. 215
Ttulo ........................................................................................................................................ 215
Ordem....................................................................................................................................... 215
Layout ....................................................................................................................................... 215
Preview ..................................................................................................................................... 215
Executar em segundo plano ......................................................................................................... 216
7.1.3. Personalizao........................................................................................................................ 216
7.1.3.1.
Editando o layout do relatrio .......................................................................................... 216
Nova estrutura do relatrio TReport: ............................................................................................. 217
7.1.4. Definindo a Funo ReportDef()................................................................................................ 217
DEFINE REPORT.......................................................................................................................... 218
DEFINE SECTION ........................................................................................................................ 218
DEFINE CELL .............................................................................................................................. 218

-3ADVPL Avanado

MDULO 08: Aplicaes ADVPL para o ERP ............................................................................................. 219


8.

Protheus e o TOPCONNECT / TOTVS DbAccess ................................................................................ 219


8.1.

Caractersticas tcnicas com o uso do TOTVS DbAccess ......................................................... 220


Comportamento de Queries Colunas Calculadas ........................................................................... 220
Comportamento diferenciado com Bandos de Dados PostGres .......................................................... 222
Conceito de ndices Permanentes e Diferenas das RDDs ................................................................. 223
Funcionamento Interno................................................................................................................ 223
Quebra de Compatibilidade com CodeBase/DBF .............................................................................. 224
Lista dos cdigos de erro do TOPConnect / DbAccess....................................................................... 225

8.2.

Funes ADVPL para TOPCONNECT / TOTVS DbAccess ........................................................... 226


Lista das funes de interao com a aplicao TopConnect / DbAccess:............................................ 226
Lista das funes acessrias utilizadas nos fontes como facilitadoras:................................................ 226
Funes de interao com o TopConnect / DbAccess ....................................................................... 227
TCCANOPEN () ........................................................................................................................... 227
TCCONTYPE() ............................................................................................................................. 227
TCDELFILE()............................................................................................................................... 228
TCGENQRY() .............................................................................................................................. 229
TCGETDB() ................................................................................................................................ 229
TCLINK() ................................................................................................................................... 230
TCQUERY() ................................................................................................................................ 232
TCQUIT() ................................................................................................................................... 233
TCSETCONN() ............................................................................................................................ 233
TCSETFIELD() ............................................................................................................................ 234
TCSPEXEC() ............................................................................................................................... 236
TCSPEXIST() .............................................................................................................................. 238
TCSQLERROR()........................................................................................................................... 238
TCSQLEXEC() ............................................................................................................................. 239
TCSRVTYPE() ............................................................................................................................. 239
TCUNLINK() ............................................................................................................................... 240
TCCHKOBJ()............................................................................................................................... 241
TCEXEERROR() ........................................................................................................................... 241
TCPGMEXE() .............................................................................................................................. 242
TCSYSEXE() ............................................................................................................................... 242
Funes acessrias para uso em fontes com interao com o TOTVS DbAccess................................... 243
CHANGEQUERY() ........................................................................................................................ 243
RETFULLNAME().......................................................................................................................... 244
RETSQLCOND() .......................................................................................................................... 245
RETSQLNAME()........................................................................................................................... 245
RETSQLTABLE() .......................................................................................................................... 246
SQLCOPY()................................................................................................................................. 246
SQLORDER() .............................................................................................................................. 247
SQLTOTRB()............................................................................................................................... 248

8.3.
Aplicaes com controle de comunio com o Banco de Dados ............................................... 249
8.3.1. MaWndBrowse com Alias Temporrio gerado por Query............................................................... 249
Exemplo: MaWndBrowse com Alias Temporrio gerado por Query..................................................... 250
8.3.2. Banco de dados de interface .................................................................................................... 261
Consideraes relevantes sobre as funes TCLink() e TCSetConn().................................................. 261
Consideraes complementares sobre o conceito de Banco de Dados de Interface .............................. 263
8.4.

9.

Embedded SQL Facilitador de Querys .................................................................................. 264


Disponibilidade do Recurso........................................................................................................... 264
Caractersticas operacionais - Sintaxe............................................................................................ 265
Limitao:.................................................................................................................................. 265
Erros de Compilao.................................................................................................................... 266
Erros de Execuo....................................................................................................................... 266
Caractersticas operacionais - depurao........................................................................................ 267
Funo auxiliar - GETLastQuery().................................................................................................. 267

Funcionalidade MsExecAuto ............................................................................................................ 269


Sobre a MsExecAuto e Rotinas Automticas.................................................................................... 269
Quando utilizar a funcionalidade MsExecAuto ? ............................................................................... 270
Processos da aplicao ERP com tratamentos para execuo por MsExecAuto..................................... 270
Quando no utilizar a funcionalidade MsExecAuto ........................................................................... 271
9.1.

Desenvolvendo aplicaes com MsExecAuto ........................................................................... 272


Estrutura de uma rotina com execuo de MsExecAuto .................................................................... 272
Variveis de controle ................................................................................................................... 272
Montagem dos arrays de parmetros............................................................................................. 272
Definio dos parmetros especficos da rotina que ser executada................................................... 276
-4ADVPL Avanado

Controle de transao ................................................................................................................. 277


Tratamento de mensagens de erro................................................................................................ 279
Aplicao completa de importao utilizando MsExecAuto: Carga de imobilizado ................................. 282
10.

Recursos de envio de e-mail ....................................................................................................... 295


Funes para manipulao de e-mails ........................................................................................... 295
Detalhamento das funes de manipulao de e-mails..................................................................... 295
CALLPROC() ............................................................................................................................... 295
MAILSMTPON() ........................................................................................................................... 296
MAILPOPON() ............................................................................................................................. 296
MAILSMTPOFF().......................................................................................................................... 297
MAILPOPOFF() ............................................................................................................................ 297
MAILRECEIVE()........................................................................................................................... 298
MAILAUTH() ............................................................................................................................... 299
POPMSGCOUNT() ........................................................................................................................ 300
MAILSEND() ............................................................................................................................... 300
MAILGETERR()............................................................................................................................ 301
Exemplos de utilizao das funcionalidades de envio e recebimento de e-mail .................................... 301
Envio de mensagens utilizando sintaxe clssica .............................................................................. 301
Envio de mensagens utilizando funes ......................................................................................... 304
Recebimento de mensagens utilizando funes ............................................................................... 307

11.

Integrao bsica com MsOffice.................................................................................................. 309

11.1.

Exportao para EXCEL ........................................................................................................... 309


DLGTOEXCEL() ........................................................................................................................... 309
Exemplo de exportao para o Microsoft Excel utilizando a funo DlgToExcel().................................. 310

APNDICES.............................................................................................................................................. 312
Relao de imagens para aplicaes visuais........................................................................................ 312
LISTAS DE EXERCCIOS ........................................................................................................................... 320
Projeto: Avaliao prtica do treinamento de ADVPL Avanado .......................................................... 325
REFERNCIAS BIBLIOGRFICAS.............................................................................................................. 326
GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL .................................................................. 328
Converso entre tipos de dados........................................................................................................... 328
CTOD()...................................................................................................................................... 328
CVALTOCHAR()........................................................................................................................... 328
DTOC()...................................................................................................................................... 329
DTOS()...................................................................................................................................... 329
STOD()...................................................................................................................................... 329
STR() ........................................................................................................................................ 330
STRZERO() ................................................................................................................................ 330
VAL() ........................................................................................................................................ 331
Matemticas ........................................................................................................................................ 332
ACOS()...................................................................................................................................... 332
CEILING() .................................................................................................................................. 332
COS()........................................................................................................................................ 332
LOG10() .................................................................................................................................... 333
SIN()......................................................................................................................................... 333
SQRT() ...................................................................................................................................... 334
TAN() ........................................................................................................................................ 334
Anlise de variveis............................................................................................................................. 335
TYPE() ....................................................................................................................................... 335
VALTYPE().................................................................................................................................. 335
Manipulao de arrays......................................................................................................................... 336
AADD()...................................................................................................................................... 336
ACLONE() .................................................................................................................................. 337
ACOPY() .................................................................................................................................... 337
ADEL() ...................................................................................................................................... 338
ADIR()....................................................................................................................................... 339
AFILL() ...................................................................................................................................... 340
AINS()....................................................................................................................................... 340
ARRAY() .................................................................................................................................... 341
ASCAN() .................................................................................................................................... 341
ASCANX() .................................................................................................................................. 342
ASIZE() ..................................................................................................................................... 343
-5ADVPL Avanado

ASORT() .................................................................................................................................... 344


ATAIL() ..................................................................................................................................... 345
Manipulao de blocos de cdigo......................................................................................................... 346
EVAL()....................................................................................................................................... 346
DBEVAL()................................................................................................................................... 346
AEVAL()..................................................................................................................................... 348
Manipulao de strings........................................................................................................................ 349
ALLTRIM().................................................................................................................................. 349
ASC() ........................................................................................................................................ 349
AT() .......................................................................................................................................... 350
BITON()..................................................................................................................................... 351
CAPITAL() .................................................................................................................................. 351
CHR()........................................................................................................................................ 351
DESCEND() ................................................................................................................................ 352
GETDTOVAL()............................................................................................................................. 352
ISALPHA().................................................................................................................................. 353
ISDIGIT() .................................................................................................................................. 353
ISLOWER() ................................................................................................................................ 354
ISUPPER().................................................................................................................................. 354
LEN() ........................................................................................................................................ 354
LOWER().................................................................................................................................... 355
LTRIM() ..................................................................................................................................... 355
MATHC().................................................................................................................................... 356
OEMTOANSI() ............................................................................................................................ 356
PADL() / PADR() / PADC()............................................................................................................ 357
RAT() ........................................................................................................................................ 357
REPLICATE() .............................................................................................................................. 358
RETASC()................................................................................................................................... 358
RTRIM()..................................................................................................................................... 359
SPACE()..................................................................................................................................... 359
STRTOKARR()............................................................................................................................. 360
STRTRAN()................................................................................................................................. 360
STUFF() ..................................................................................................................................... 361
SUBSTR() .................................................................................................................................. 361
TRANSFORM() ............................................................................................................................ 362
UPPER()..................................................................................................................................... 362
Manipulao de data / hora................................................................................................................. 363
CDOW()..................................................................................................................................... 363
CMONTH() ................................................................................................................................. 363
DATE() ...................................................................................................................................... 364
DAY() ........................................................................................................................................ 364
DOW()....................................................................................................................................... 365
DTOC()...................................................................................................................................... 365
DTOS()...................................................................................................................................... 366
ELAPTIME() ................................................................................................................................ 366
MONTH() ................................................................................................................................... 367
SECONDS() ................................................................................................................................ 367
TIME()....................................................................................................................................... 368
YEAR() ...................................................................................................................................... 368
Manipulao de variveis numricas ................................................................................................... 369
ABS() ........................................................................................................................................ 369
ALEATORIO() ............................................................................................................................. 369
INT()......................................................................................................................................... 370
NOROUND() ............................................................................................................................... 370
RANDOMIZE() ............................................................................................................................ 371
ROUND() ................................................................................................................................... 371
Manipulao de arquivos ..................................................................................................................... 372
ADIR()....................................................................................................................................... 372
CGETFILE() ................................................................................................................................ 373
CPYS2T() ................................................................................................................................... 379
CPYT2S() ................................................................................................................................... 379
CURDIR()................................................................................................................................... 380
DIRECTORY() ............................................................................................................................. 381
DIRREMOVE()............................................................................................................................. 382
DISKSPACE() ............................................................................................................................. 383
EXISTDIR() ................................................................................................................................ 384
FCLOSE()................................................................................................................................... 384
-6ADVPL Avanado

FCREATE() ................................................................................................................................. 385


FERASE() ................................................................................................................................... 386
FILE()........................................................................................................................................ 386
FILENOEXT() .............................................................................................................................. 387
FOPEN() .................................................................................................................................... 388
FREAD() .................................................................................................................................... 390
FREADSTR () .............................................................................................................................. 390
FRENAME() ................................................................................................................................ 391
FSEEK()..................................................................................................................................... 392
FT_FEOF() ................................................................................................................................. 392
FT_FGOTO()............................................................................................................................... 393
FT_FGOTOP() ............................................................................................................................. 393
FT_FLASTREC() .......................................................................................................................... 393
FT_FREADLN()............................................................................................................................ 394
FT_FRECNO() ............................................................................................................................. 395
FT_FSKIP() ................................................................................................................................ 395
FT_FUSE() ................................................................................................................................. 395
FWRITE() ................................................................................................................................... 396
MSCOPYFILE() ............................................................................................................................ 398
MSCOPYTO() .............................................................................................................................. 399
MSCREATE() .............................................................................................................................. 399
MSERASE() ................................................................................................................................ 400
MSRENAME().............................................................................................................................. 401
RETFILENAME() .......................................................................................................................... 401
Manipulao de arquivos e ndices temporrios .................................................................................. 402
CRIATRAB() ............................................................................................................................... 402
Manipulao de bases de dados........................................................................................................... 403
ALIAS() ..................................................................................................................................... 403
BOF() / EOF()............................................................................................................................. 403
COPY() ...................................................................................................................................... 404
COPY STRUCTURE() .................................................................................................................... 407
DBAPPEND() .............................................................................................................................. 407
DBCLEARALLFILTER() .................................................................................................................. 408
DBCLEARFILTER() ....................................................................................................................... 409
DBCLEARINDEX()........................................................................................................................ 409
DBCLOSEALL() ........................................................................................................................... 410
DBCLOSEAREA() ......................................................................................................................... 410
DBCOMMIT() .............................................................................................................................. 411
DBCOMMITALL() ......................................................................................................................... 411
DBCREATE()............................................................................................................................... 412
DBCREATEINDEX()...................................................................................................................... 413
DBDELETE() ............................................................................................................................... 414
DBF() ........................................................................................................................................ 415
DBFIELDINFO() .......................................................................................................................... 415
DBFILTER() ................................................................................................................................ 416
DBGOTO() ................................................................................................................................. 417
DBGOTOP()................................................................................................................................ 417
DBGOBOTTON().......................................................................................................................... 418
DBINFO()................................................................................................................................... 418
DBNICKINDEXKEY() .................................................................................................................... 419
DBORDERINFO()......................................................................................................................... 420
DBORDERNICKNAME()................................................................................................................. 421
DBPACK() .................................................................................................................................. 421
DBRECALL() ............................................................................................................................... 422
DBRECORDINFO()....................................................................................................................... 422
DBREINDEX() ............................................................................................................................. 423
DBRLOCK() ................................................................................................................................ 424
DBRLOCKLIST().......................................................................................................................... 424
DBRUNLOCK() ............................................................................................................................ 425
DBSETDRIVER() ......................................................................................................................... 425
DBSETINDEX() ........................................................................................................................... 426
DBSETNICKNAME() ..................................................................................................................... 427
DBSELECTAREA()........................................................................................................................ 427
DBSETORDER() .......................................................................................................................... 428
DBSEEK() E MSSEEK()................................................................................................................. 429
DBSKIP() ................................................................................................................................... 430
DBSETFILTER()........................................................................................................................... 431
DBSTRUCT() .............................................................................................................................. 432
DBUNLOCK() .............................................................................................................................. 432
-7ADVPL Avanado

DBUNLOCKALL() ......................................................................................................................... 433


DBUSEAREA() ............................................................................................................................ 433
DELETED() ................................................................................................................................. 434
FCOUNT() .................................................................................................................................. 434
FOUND().................................................................................................................................... 435
INDEXKEY() ............................................................................................................................... 435
INDEXORD() .............................................................................................................................. 436
LUPDATE() ................................................................................................................................. 436
MSAPPEND() .............................................................................................................................. 437
MSUNLOCK().............................................................................................................................. 437
ORDBAGEXT() ............................................................................................................................ 438
ORDKEY() .................................................................................................................................. 438
RECLOCK() ................................................................................................................................ 439
RECNO().................................................................................................................................... 440
SELECT() ................................................................................................................................... 440
SET FILTER TO ........................................................................................................................... 441
SOFTLOCK()............................................................................................................................... 442
USED() ...................................................................................................................................... 443
ZAP........................................................................................................................................... 443
Controle de numerao seqencial ...................................................................................................... 444
GETSXENUM() ............................................................................................................................ 444
CONFIRMSXE() ........................................................................................................................... 444
ROLLBACKSXE() ......................................................................................................................... 444
Validao............................................................................................................................................. 445
ALLWAYSFALSE()........................................................................................................................ 445
ALLWAYSTRUE() ......................................................................................................................... 445
EXISTCHAV() ............................................................................................................................. 445
EXISTCPO() ............................................................................................................................... 446
LETTERORNUM()......................................................................................................................... 446
NAOVAZIO() .............................................................................................................................. 446
NEGATIVO() ............................................................................................................................... 446
PERTENCE() ............................................................................................................................... 447
POSITIVO() ................................................................................................................................ 447
TEXTO() .................................................................................................................................... 447
VAZIO()..................................................................................................................................... 447
Manipulao de parmetros do sistema............................................................................................... 448
GETMV() .................................................................................................................................... 448
GETNEWPAR() ............................................................................................................................ 448
PUTMV() .................................................................................................................................... 449
SUPERGETMV()........................................................................................................................... 449
Controle de impresso......................................................................................................................... 450
AVALIMP() ................................................................................................................................. 450
CABEC() .................................................................................................................................... 451
IMPCADAST() ............................................................................................................................. 454
MS_FLUSH()............................................................................................................................... 454
OURSPOOL() .............................................................................................................................. 456
RODA()...................................................................................................................................... 457
SETDEFAULT()............................................................................................................................ 459
SETPRC() ................................................................................................................................... 460
SETPRINT()................................................................................................................................ 460
Controle de processamentos ............................................................................................................... 462
ABREEXCL() ............................................................................................................................... 462
CLOSEOPEN()............................................................................................................................. 462
CLOSESFILE() ............................................................................................................................ 462
CHKFILE().................................................................................................................................. 463
CONOUT().................................................................................................................................. 464
CRIAVAR() ................................................................................................................................. 464
DISARMTRANSACTION() .............................................................................................................. 465
EXECBLOCK() ............................................................................................................................. 466
EXISTBLOCK()............................................................................................................................ 466
ERRORBLOCK() .......................................................................................................................... 467
FINAL() ..................................................................................................................................... 469
FINDFUNCTION() ........................................................................................................................ 469
FUNDESC() ................................................................................................................................ 470
FUNNAME() ................................................................................................................................ 470
GETAREA()................................................................................................................................. 470
GETCOUNTRYLIST() .................................................................................................................... 471
-8ADVPL Avanado

ISINCALLSTACK() ....................................................................................................................... 471


REGTOMEMORY()........................................................................................................................ 472
RESTAREA() ............................................................................................................................... 473
USEREXCEPTION() ...................................................................................................................... 473
Utilizao de recursos do ambiente ERP .............................................................................................. 475
AJUSTASX1() ............................................................................................................................. 475
ALLUSERS() ............................................................................................................................... 477
ALLGROUPS() ............................................................................................................................. 479
CGC()........................................................................................................................................ 480
CONPAD1() ................................................................................................................................ 480
DATAVALIDA()............................................................................................................................ 481
EXISTINI() ................................................................................................................................. 481
EXTENSO() ................................................................................................................................ 482
FORMULA() ................................................................................................................................ 482
GETADVFVAL() ........................................................................................................................... 482
HELP()....................................................................................................................................... 483
MESEXTENSO() .......................................................................................................................... 484
OBRIGATORIO() ......................................................................................................................... 484
OPENFILE() ................................................................................................................................ 487
PERGUNTE()............................................................................................................................... 488
PESQPICT()................................................................................................................................ 488
PESQPICTQT() ............................................................................................................................ 489
POSICIONE().............................................................................................................................. 489
PUTSX1()................................................................................................................................... 490
RETINDEX() ............................................................................................................................... 491
SIXDESCRICAO() ........................................................................................................................ 491
TABELA() ................................................................................................................................... 492
TAMSX3() .................................................................................................................................. 492
TM().......................................................................................................................................... 493
X1DEF01() ................................................................................................................................. 494
X1PERGUNT()............................................................................................................................. 495
X2NOME().................................................................................................................................. 495
X3CBOX() .................................................................................................................................. 496
X3DESCRIC() ............................................................................................................................. 496
X3PICTURE() .............................................................................................................................. 497
X3TITULO()................................................................................................................................ 498
X3USO() .................................................................................................................................... 498
X5DESCRI() ............................................................................................................................... 499
X6CONTEUD() ............................................................................................................................ 500
X6DESCRIC() ............................................................................................................................. 501
XADESCRIC() ............................................................................................................................. 502
XBDESCRI() ............................................................................................................................... 502
XFILIAL() ................................................................................................................................... 503
Interfaces de cadastro ........................................................................................................................ 504
AXCADASTRO() .......................................................................................................................... 504
AXPESQUI() ............................................................................................................................... 506
AXVISUAL() ............................................................................................................................... 506
AXINCLUI() ................................................................................................................................ 507
AXALTERA() ............................................................................................................................... 508
AXDELETA() ............................................................................................................................... 508
BRWLEGENDA().......................................................................................................................... 509
ENDFILBRW() ............................................................................................................................. 509
FILBROWSE() ............................................................................................................................. 510
PESQBRW()................................................................................................................................ 510
MARKBROW() ............................................................................................................................. 511
MBROWSE() ............................................................................................................................... 515
MODELO2()................................................................................................................................ 523
MODELO3()................................................................................................................................ 526
Interfaces visuais para aplicaes....................................................................................................... 529
ALERT() ..................................................................................................................................... 529
AVISO()..................................................................................................................................... 530
FORMBACTH() ............................................................................................................................ 530
MSGFUNCTIONS()....................................................................................................................... 531
Recursos das interfaces visuais........................................................................................................... 532
GDFIELDGET()............................................................................................................................ 532
GDFIELDPOS() ........................................................................................................................... 532
GDFIELDPUT()............................................................................................................................ 532

-9ADVPL Avanado

GETMARK() ................................................................................................................................ 533


ISMARK()................................................................................................................................... 534
MARKBREFRESH()....................................................................................................................... 534
READVAR() ................................................................................................................................ 535
THISINV().................................................................................................................................. 535
THISMARK()............................................................................................................................... 535

- 10 ADVPL Avanado

OBJETIVOS DO CURSO
Objetivos especficos do curso:
Ao final do curso o treinando dever ter desenvolvido os seguintes conceitos, habilidades e
atitudes:
a) Conceitos a serem aprendidos




estruturas para implementao aplicaes orientadas a objetos


introduo as tcnicas de programao de desenvolvimento de relatrios
grficos
introduo aos conceitos de ADVPL ASP e WebServices

b) Habilidades e tcnicas a serem aprendidas






desenvolvimento de aplicaes voltadas ao ERP Protheus


anlise de fontes de mdia complexidade
desenvolvimento de com orientao a objetos

c) Atitudes a serem desenvolvidas






adquirir conhecimentos atravs da anlise dos funcionalidades disponveis no


ERP Protheus;
estudar a implementao de fontes com estruturas orientadas a objetos em
ADVPL;
embasar a realizao de outros cursos relativos a linguagem ADVPL

- 11 ADVPL Avanado

MDULO 05: Introduo orientao objetos


1. Conceitos de orientao objetos
O termo orientao a objetos pressupe uma organizao de software em termos de coleo
de objetos discretos incorporando estrutura e comportamento prprios. Esta abordagem de
organizao essencialmente diferente do desenvolvimento tradicional de software, onde
estruturas de dados e rotinas so desenvolvidas de forma apenas fracamente acopladas.
Neste tpico sero os conceitos de programao orientada a objetos listados abaixo. Esta
breve viso geral do paradigma permitir entender melhor os conceitos associados
programao orientada a objetos e, em particular, s construes implementadas atravs da
linguagem ADVPL.
 Objetos
 Herana
 Atributos
 Mtodos
 Classes
 Abstrao
 Generalizao
 Encapsulamento
 Polimorfismo

1.1. Definies
Objeto
Um objeto uma entidade do mundo real que tem uma identidade. Objetos podem
representar entidades concretas (um arquivo no meu computador, uma bicicleta) ou entidades
conceituais (uma estratgia de jogo, uma poltica de escalonamento em um sistema
operacional). Cada objeto ter sua identidade significa que dois objetos so distintos mesmo
que eles apresentem exatamente as mesmas caractersticas.
Embora objetos tenham existncia prpria no mundo real, em termos de linguagem de
programao um objeto necessita um mecanismo de identificao. Esta identificao de objeto
deve ser nica, uniforme e independente do contedo do objeto. Este um dos mecanismos
que permite a criao de colees de objetos, as quais so tambm objetos em si.
A estrutura de um objeto representada em termos de atributos. O comportamento de um
objeto representado pelo conjunto de operaes que podem ser executadas sobre o objeto.

- 12 ADVPL Avanado

Classe
Objetos com a mesma estrutura e o mesmo comportamento so agrupados em classes. Uma
classe uma abstrao que descreve propriedades importantes para uma aplicao e
simplesmente ignora o resto.
Cada classe descreve um conjunto (possivelmente infinito) de objetos individuais. Cada objeto
dito ser uma instncia de uma classe. Assim, cada instncia de uma classe tem seus prprios
valores para cada atributo, mas dividem os nomes dos atributos e mtodos com as outras
instncias da classe. Implicitamente, cada objeto contm uma referncia para sua prpria
classe, em outras palavras, ele sabe o que ele .

Figura: Representao de uma classe de objetos

Figura: Representao de um objeto instanciado de uma classe

- 13 ADVPL Avanado

Polimorfismo
Polimorfismo significa que a mesma operao pode se comportar de forma diferente em
classes diferentes. Por exemplo, a operao move quando aplicada a uma janela de um
sistema de interfaces tem um comportamento distinto do que quando aplicada a uma pea de
um jogo de xadrez. Um mtodo uma implementao especfica de uma operao para uma
certa classe.
Polimorfismo tambm implica que uma operao de uma mesma classe pode ser
implementada por mais de um mtodo. O usurio no precisa saber quantas implementaes
existem para uma operao, ou explicitar qual mtodo deve ser utilizado: a linguagem de
programao deve ser capaz de selecionar o mtodo correto a partir do nome da operao,
classe do objeto e argumentos para a operao. Desta forma, novas classes podem ser
adicionadas sem necessidade de modificao de cdigo j existente, pois cada classe apenas
define os seus mtodos e atributos.
No mundo real, alguns objetos e classes podem ser descritos como casos especiais, ou
especializaes, de outros objetos e classes. Por exemplo, a classe de computadores pessoais
com processador da linha 80x86 uma especializao de computadores pessoais, que por sua
vez uma especializao de computadores. No desejvel que tudo que j foi descrito para
computadores tenha de ser repetido para computadores pessoais ou para computadores
pessoais com processador da linha 80x86.
Herana
Herana o mecanismo do paradigma de orientao a objetos que permite compartilhar
atributos e operaes entre classes baseada em um relacionamento hierrquico. Uma classe
pode ser definida de forma genrica e depois refinada sucessivamente em termos de
subclasses ou classes derivadas. Cada subclasse incorpora, or herda, todas as propriedades de
sua superclasse (ou classe base) e adiciona suas propriedades nicas e particulares. As
propriedades da classe base no precisam ser repetidas em cada classe derivada. Esta
capacidade de fatorar as propriedades comuns de diversas classes em uma superclasse pode
reduzir dramaticamente a repetio de cdigo em um projeto ou programa, sendo uma das
principais vantagens da abordagem de orientao a objetos.

- 14 ADVPL Avanado

1.2. Conceitos Bsicos


A abordagem de orientao a objetos favorece a aplicao de diversos conceitos considerados
fundamentais para o desenvolvimento de bons programas, tais como abstrao e
encapsulamento.
Tais conceitos no so exclusivos desta abordagem, mas so suportados de forma melhor no
desenvolvimento orientado a objetos do que em outras metodologias.
Abstrao
Abstrao consiste de focalizar nos aspectos essenciais inerentes a uma entidade e ignorar
propriedades acidentais. Em termos de desenvolvimento de sistemas, isto significa
concentrar-se no que um objeto e faz antes de se decidir como ele ser implementado. O
uso de abstrao preserva a liberdade para tomar decises de desenvolvimento ou de
implementao apenas quando h um melhor entendimento do problema a ser resolvido.
Muitas linguagens de programao modernas suportam o conceito de abstrao de dados;
porm, o uso de abstrao juntamente com polimorfismo e herana, como suportado em
orientao a objetos, um mecanismo muito mais poderoso.
O uso apropriado de abstrao permite que um mesmo modelo conceitual (orientao a
objetos) seja utilizado para todas as fases de desenvolvimento de um sistema, desde sua
anlise at sua documentao.
Encapsulamento
Encapsulamento, tambm referido como esconder informao, consiste em separar os
aspectos externos de um objeto, os quais so acessveis a outros objetos, dos detalhes
internos de implementao do objeto, os quais permanecem escondidos dos outros objetos. O
uso de encapsulamento evita que um programa torne-se to interdependente que uma
pequena mudana tenha grandes efeitos colaterais.
O uso de encapsulamento permite que a implementao de um objeto possa ser modificada
sem afetar as aplicaes que usam este objeto. Motivos para modificar a implementao de
um objeto podem ser, por exemplo, melhoria de desempenho, correo de erros e mudana de
plataforma de execuo.
Assim como abstrao, o conceito de Encapsulamento no exclusivo da abordagem de
orientao a objetos. Entretanto, a habilidade de se combinar estrutura de dados e
comportamento em uma nica entidade torna a Encapsulamento mais elegante e mais
poderosa do que em linguagens convencionais que separam estruturas de dados e
comportamento.
Compartilhamento
Tcnicas de orientao a objetos promovem compartilhamento em diversos nveis distintos.
Herana de estrutura de dados e comportamento permite que estruturas comuns sejam
compartilhadas entre diversas classes derivadas similares sem redundncia. O
compartilhamento de cdigo usando herana uma das grandes vantagens da orientao a
objetos. Ainda mais importante que a economia de cdigo a clareza conceitual de reconhecer
que operaes diferentes so na verdade a mesma coisa, o que reduz o nmero de casos
distintos que devem ser entendidos e analisados.

- 15 ADVPL Avanado

O desenvolvimento orientado a objetos no apenas permite que a informao dentro de um


projeto seja compartilhada como tambm oferece a possibilidade de reaproveitar projetos e
cdigo em projetos futuros. As ferramentas para alcanar este compartilhamento, tais como
abstrao, Encapsulamento e herana, esto presentes na metodologia; uma estratgia de
reuso entre projetos a definio de bibliotecas de elementos reusveis. Entretanto,
orientao a objetos no uma frmula mgica para alcanar reusabilidade; para tanto,
preciso planejamento e disciplina para pensar em termos genricos, no voltados
simplesmente para a aplicao corrente.

1.3. O Modelo de Objetos (OMT)


Um modelo de objetos busca capturar a estrutura esttica de um sistema mostrando os
objetos existentes, seus relacionamentos, e atributos e operaes que caracterizam cada
classe de objetos. atravs do uso deste modelo que se enfatiza o desenvolvimento em
termos de objetos ao invs de mecanismos tradicionais de desenvolvimento baseado em
funcionalidades, permitindo uma representao mais prxima do mundo real.
Uma vez que as principais definies e conceitos da abordagem de orientao a objetos esto
definidos, possvel introduzir o modelo de objetos que ser adotado ao longo deste texto. O
modelo apresentado um subconjunto do modelo OMT (Object Modeling Technique), proposto
por Rumbaugh entre outros. Este modelo tambm introduz uma representao diagramtica
para este modelo, a qual ser tambm apresentada aqui.

1.3.1. Objetos e Classes


Objeto definido neste modelo como um conceito, abstrao ou coisa com limites e
significados bem definidos para a aplicao em questo. Objetos tm dois propsitos:
promover o entendimento do mundo real e suportar uma base prtica para uma
implementao computacional. No existe uma maneira correta de decompor um problema
em objetos; esta decomposio depende do julgamento do projetista e da natureza do
problema. Todos os objetos tm identidade prpria e so distinguveis.
Uma classe de objetos descreve um grupo de objetos com propriedades (atributos) similares,
comportamentos (operaes) similares, relacionamentos comuns com outros objetos e uma
semntica comum. Por exemplo, Pessoa e Companhia so classes de objetos. Cada pessoa
tem um nome e uma idade; estes seriam os atributos comuns da classe. Companhias tambm
podem ter os mesmos atributos nome e idade definidos. Entretanto, devido distino
semntica elas provavelmente estariam agrupados em outra classe que no Pessoa. Como se
pode observar, o agrupamento em classes no leva em conta apenas o compartilhamento de
propriedades.
Todo objeto sabe a que classe ele pertence, ou seja, a classe de um objeto um atributo
implcito do objeto. Este conceito suportado na maior parte das linguagens de programao
orientada a objetos, inclusive em ADVPL.
OMT define dois tipos de diagramas de objetos, diagramas de classes e diagramas de
instncias. Um diagrama de classe um esquema, ou seja, um padro ou gabarito que
descreve as muitas possveis instncias de dados. Um diagrama de instncias descreve como
um conjunto particular de objetos est relacionado. Diagramas de instncias so teis para
apresentar exemplos e documentar casos de testes; diagramas de classes tm uso mais
amplos. A Figura abaixo apresenta a notao adotada para estes diagramas.

- 16 ADVPL Avanado

Figura: Representao diagramtica de OMT para classes e objetos

O agrupamento de objetos em classes um poderoso mecanismo de abstrao. Desta forma,


possvel generalizar definies comuns para uma classe de objetos, ao invs de repet-las
para cada objeto em particular. Esta uma das formas de reutilizao e economia que a
abordagem de orientao a objetos suporta.

1.3.2. Atributos
Um atributo um valor de dado assumido pelos objetos de uma classe. Nome, idade e peso
so exemplos de atributos de objetos Pessoa. Cor, peso e modelo so possveis atributos de
objetos Carro. Cada atributo tem um valor para cada instncia de objeto. Por exemplo, o
atributo idade tem valor ``29'' no objeto Pedro Y. Em outras palavras, Pedro Y tem 29 anos de
idade. Diferentes instncias de objetos podem ter o mesmo valor para um dado atributo.
Cada nome de atributo nico para uma dada classe, mas no necessariamente nico entre
todas as classes. Por exemplo, ambos Pessoa e Companhia podem ter um atributo chamado
endereo.
No diagrama de classes, atributos so listados no segundo segmento da caixa que representa
a classe. O nome do atributo pode ser seguido por detalhes opcionais, tais como o tipo de
dado assumido e valor default. A Figura abaixo mostra esta representao.

Figura: Representao diagramtica de OMT para classes e objetos com atributos


No se deve confundir identificadores internos de objetos com atributos do mundo real.
Identificadores de objetos so uma convenincia de implementao, e no tm nenhum
significado para o domnio da aplicao. Por exemplo, CIC e RG no so identificadores de
objetos, mas sim verdadeiros atributos do mundo real.

- 17 ADVPL Avanado

1.3.3. Operaes e Mtodos


Uma operao uma funo ou transformao que pode ser aplicada a ou por objetos em uma
classe. Por exemplo, abrir, salvar e imprimir so operaes que podem ser aplicadas a objetos
da classe Arquivo. Todos os objetos em uma classe compartilham as mesmas operaes.
Toda operao tem um objeto-alvo como um argumento implcito. O comportamento de uma
operao depende da classe de seu alvo. Como um objeto sabe qual sua classe, possvel
escolher a implementao correta da operao. Alm disto, outros argumentos (parmetros)
podem ser necessrios para uma operao.
Uma mesma operao pode se aplicar a diversas classes diferentes. Uma operao como esta
dita ser polimrfica, ou seja, ela pode assumir distintas formas em classes diferentes.
Um mtodo a implementao de uma operao para uma classe. Por exemplo, a operao
imprimir pode ser implementada de forma distinta, dependendo se o arquivo a ser impresso
contm apenas texto ASCII, um arquivo de um processador de texto ou binrio. Todos estes
mtodos executam a mesma operao: imprimir o arquivo; porm, cada mtodo ser
implementado por um diferente cdigo.
A assinatura de um mtodo dada pelo nmero e tipos de argumentos do mtodo, assim
como por seu valor de retorno. Uma estratgia de desenvolvimento recomendvel manter
assinaturas coerentes para mtodos implementando uma dada operao, assim como um
comportamento consistente entre as implementaes.
Em termos de diagramas OMT, operaes so listadas na terceira parte da caixa de uma
classe. Cada nome de operao pode ser seguida por detalhes opcionais, tais como lista de
argumentos e tipo de retorno. A lista de argumentos apresentada entre parnteses aps o
nome da operao. Uma lista de argumentos vazia indica que a operao no tem
argumentos; da ausncia da lista de argumentos no se pode concluir nada. O tipo de
resultado vem aps a lista de argumentos, sendo precedido por dois pontos (:). Caso a
operao retorne resultado, este no deve ser omitido, pois esta a forma de distingui-la de
operaes que no retornam resultado. Exemplos de representao de operaes em OMT so
apresentados na Figura abaixo:

Figura: Representao diagramtica de OMT para classes com atributos e operaes

- 18 ADVPL Avanado

1.3.4. Sugestes de desenvolvimento


Na construo de um modelo para uma aplicao, as seguintes sugestes devem ser
observadas a fim de se obter resultados claros e consistentes:
 No comece a construir um modelo de objetos simplesmente definindo classes,
associaes e heranas. A primeira coisa a se fazer entender o problema a ser
resolvido.
 Tente manter seu modelo simples. Evite complicaes desnecessrias.
 Escolha nomes cuidadosamente. Nomes so importantes e carregam conotaes
poderosas. Nomes devem ser descritivos, claros e no deixar ambigidades. A escolha
de bons nomes um dos aspectos mais difceis da modelagem.
 No enterre apontadores ou outras referncias a objetos dentro de objetos como
atributos. Ao invs disto, modele estas referncias como associaes. Isto torna o
modelo mais claro e independente da implementao.
 Tente evitar associaes que envolvam trs ou mais classes de objetos. Muitas vezes,
estes tipos de associaes podem ser decompostos em termos de associaes binrias,
tornando o modelo mais claro.
 No transfira os atributos de ligao para dentro de uma das classes.
 Tente evitar hierarquias de generalizao muito profundas.
 No se surpreenda se o seu modelo necessitar vrias revises; isto o normal.
 Sempre documente seus modelos de objetos. O diagrama pode especificar a estrutura
do modelo, mas nem sempre suficiente para descrever as razes por trs da definio
do modelo. Uma explicao escrita pode clarificar pontos tais como significado de
nomes e explicar a razo para cada classe e relacionamento.
 Nem sempre todas as construes OMT so necessrias para descrever uma aplicao.
Use apenas aquelas que forem adequadas para o problema analisado.

- 19 ADVPL Avanado

2. Orientao a objetos em ADVPL


Neste tpico ser detalhada a forma com a qual a linguagem ADVPL implementa os conceitos
de orientao a objetos e a sintaxe utilizada no desenvolvimento de aplicaes.

2.1. Sintaxe e operadores para orientao a objetos


Palavras reservadas

 CLASS
 CLASSDATA
 CONSTRUCTOR
 DATA
 ENDCLASS
 EXPORT
 FROM
 HIDDEN
 METHOD
 PROTECTED
 SELF
CLASS
Descrio

Utilizada na declarao de uma classe de objetos para identificar a qual


classe um determinado mtodo est relacionado.

Sintaxe 1

CLASS <nome_da_classe>

Sintaxe 2

METHOD <nome_do_mtodo> CLASS <nome_da_classe>

CLASSDATA
Descrio

Utilizada na declarao de um atributo da classe de objetos com a finalidade


de definir um tipo e um contedo padro para este atributo.

Sintaxe 1

CLASSDATA <nome_da_varivel> AS <tipo> <atributo> INIT <contedo>

CONSTRUCTOR

Descrio

Utilizada na especificao de um mtodo especial, definido como construtor,


o qual tem a funo de retornar um novo objeto com os atributos e mtodos
definidos na classe.

Sintaxe

METHOD <nome_do_mtodo()> CONSTRUCTOR

- 20 ADVPL Avanado

DATA
Descrio

Utilizada na declarao de um atributo da classe de objetos.

Sintaxe

DATA <nome_do_atributo>

ENDCLASS
Descrio

Utilizada na finalizao da declarao da classe.

Sintaxe

ENDCLASS

EXPORT

Descrio

Operador utilizado para definir o modo de acesso de um atributo especificado


na classe de objetos. O uso deste operador indica que o atributo ser visvel
e altervel sem a necessidade de utilizao dos mtodos do prprio objeto.
Seu uso na linguagem ADVPL opcional.

Simular

EXPORT ou [PUBLIC]

Sintaxe 1

DATA cNome

Sintaxe 2

EXPORT DATA cNome

FROM

Descrio

Utilizada na declarao de uma classe, a qual ser uma instncia de uma


superclasse, recebendo os atributos e mtodos nela definidos,
implementando a herana entre classes.

Sintaxe

CLASS <nome_da_classe> FROM <nome_da_superclasse>

HIDDEN

Descrio

Operador utilizado para definir o modo de acesso de um atributo especificado


na classe de objetos. O uso deste operador indica que o atributo no ser
visvel para chamadas diretas do objeto, sendo necessria a utilizao de
mtodos para sua manipulao.

Simular

HIDDEN ou [LOCAL]

Sintaxe

HIDDEN DATA cNome

METHOD
Descrio

Utilizada na declarao do prottipo do mtodo de uma classe de objetos, e


na declarao do mtodo efetivamente desenvolvido.

Sintaxe 1

METHOD <nome_do_mtodo()>

Sintaxe 2

METHOD <nome_do_mtodo(<parmetros>)> CLASS <nome_da_classe>

- 21 ADVPL Avanado

PROTECTED

Descrio

Operador utilizado para definir o modo de acesso de um atributo especificado


na classe de objetos. O uso deste operador indica que o atributo ser visvel
mas no ser editvel para chamadas diretas do objeto, sendo necessria a
utilizao de mtodos para sua manipulao.

Simular

PROTECTED ou [READONLY]

Sintaxe

PROTECTED DATA cNome

SELF
Descrio

Utilizada principalmente pelo mtodo construtor para retornar o objeto


criado para a aplicao.

Sintaxe

Return SELF

Operadores especficos

Utilizado para referenciar um mtodo ou um atributo de um objeto j


instanciado.

Exemplo 1

cNome := oAluno:sNome

Exemplo 2

cNota := oAluno:GetNota(cCurso)

::

Utilizado pelos mtodos de uma classe para referenciar os atributos


disponveis para o objeto.
METHOD GetNota(cCurso) CLASS ALUNO
Local nPosCurso := 0
Local nNota := 0
nPosCurso := aScan(::aCursos,{|aCurso| aCurso[1] == cCurso})

Exemplo

IF nPosCurso > 0
nNota := ::aCursos[nPosCurso][2]
ENDIF
Return nNota

- 22 ADVPL Avanado

2.2. Estrutura de uma classe de objetos em ADVPL


Declarao da classe
A declarao de uma classe da linguagem ADVPL realizada de forma similar a declarao de
uma funo, com a diferena de que uma classe no possui diferenciao quanto a sua
procedncia, como uma Function() e uma User Function(), e no possui visibilidade limitada
como uma Static Function().
Exemplo:
#include protheus.ch
CLASS Pessoa()

Definio dos atributos


Seguindo o mesmo princpio de variveis no tipadas, os atributos das classes em ADVPL no
precisam ter seu tipo especificado, sendo necessrio apenas determinar seus nomes.
Desta forma recomendado o uso da notao Hngara tambm para a definio dos atributos
de forma a facilitar a anlise, interpretao e utilizao da classe e seus objetos instanciados.
Exemplo:
#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade

Prototipao dos mtodos


A prototipao dos mtodos uma regra utilizada pelas linguagens orientadas a objetos,
atravs da qual so especificadas as operaes que podem ser realizadas pelo objeto,
diferenciando os mtodos de outras funes internas de uso da classe, e para especificar quais
so os mtodos construtores.
Em linguagens tipadas, na prototipao dos mtodos necessrio definir quais so os
parmetros recebidos e seus respectivos tipos, alm de definir o tipo do retorno que ser
fornecido. Em ADVPL necessrio apenas descrever a chamada do mtodo e caso necessrio
se o mesmo um construtor.

- 23 ADVPL Avanado

Exemplo:
#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade
METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()
ENDCLASS

2.3. Implementao dos mtodos de uma classe em ADVPL


Mtodo Construtor
O mtodo construtor possui a caracterstica de retornar um objeto com o tipo da classe da qual
o mesmo foi instanciado. Por esta razo diz-se que o tipo do objeto instanciado a classe
daquele objeto.
Para produzir este efeito, o mtodo construtor utiliza a palavra reservada SELF, a qual
utilizada pela linguagem ADVPL para referncia a prpria classe daquele objeto.
Exemplo:
#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade
METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()
ENDCLASS
METHOD Create(cNome, nIdade) CLASS Pessoa
::cNome := cNome
::nIdade := nIdade
Return SELF

- 24 ADVPL Avanado

Manipulao de atributos
Os atributos definidos para uma classe com a utilizao da palavra reservada DATA em sua
declarao podem ser manipulados por seus mtodos utilizando o operador ::.
A utilizao deste operador permite ao interpretador ADVPL diferenciar variveis comuns
criadas pelas funes e mtodos que utilizam este objeto dos atributos propriamente ditos.
Exemplo:
#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade
METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()
ENDCLASS
METHOD Create(cNome, nIdade) CLASS Pessoa
::cNome := cNome
::nIdade := nIdade
Return SELF

Utilizao de funes em uma classe de objetos


Conforme mencionado anteriormente, a utilizao da palavra reservada METHOD permite ao
interpretador ADVPL diferenciar os mtodos que podem ser utilizados atravs da referncia do
objeto de funes internas descritas internamente na classe.
Isto permite a utilizao de funes tradicionais da linguagem ADVPL, como as Static
Functions() as quais sero visveis apenas a classe, e no podero ser referenciadas
diretamente pelo objeto.
Exemplo parte 01: Funo CadPessoa (usuria da classe Pessoa)
#include protheus.ch
USER FUNCTION CadPessoa()
Local
Local
Local
Local

oPessoa
cNome :=
dNascimento:= CTOD()
aDados := {}

aDados := GetDados()
oPessoa := Pessoa():Create(cNome,dNascimento)
Return

- 25 ADVPL Avanado

Exemplo parte 02: Classe Pessoa


#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade
DATA dNascimento
METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()
ENDCLASS
METHOD Create(cNome, dNascimento) CLASS Pessoa
::cNome := cNome
::dNascimento := dNascimento
::nIdade := CalcIdade(dNascimento)
Return SELF
STATIC FUNCTION CalcIdade(dNascimento)
Local nIdade
nIdade := dDataBase - dNascimento
RETURN nIdade

Herana entre classes


Seguindo o principio da orientao a objetos, a linguagem ADVPL permite que uma classe
receba por herana os mtodos e atributos definidos em uma outra classe, a qual tornasse a
superclasse desta instncia.
Para utilizar este recurso deve ser utilizada a palavra reservada FROM na declarao da
classe, especificando a superclasse que ser referenciada.
Em ADVPL o exemplo prtico desta situao a superclasse TSrvObject, a qual utilizada pela
maioria das classes e componentes da interface visual, como demonstrado no mdulo 06.

Exemplo parte 01: Declarao da classe Pessoa


#include protheus.ch
CLASS Pessoa()
DATA cNome
DATA nIdade
DATA dNascimento
METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()
ENDCLASS

- 26 ADVPL Avanado

Exemplo parte 02: Declarao da classe Aluno


#include protheus.ch
CLASS Aluno() FROM Pessoa
DATA nID
DATA aCursos
METHOD
METHOD
METHOD
METHOD
METHOD

Create() CONSTRUCTOR
Inscrever()
Avaliar()
GetNota()
GetStatus()

ENDCLASS
// Os objetos da classe Aluno, possuem todos os mtodos e atributos da classe
Pessoa, alm
// dos mtodos e atributos declarados na prpria classe.

Construtor para classes com herana


Quanto utilizado o recurso de herana entre classes, o construtor da classe instanciada deve
receber um tratamento adicional, para que o objeto instanciado seja criado com os atributos e
mtodos definidos na superclasse.
Nestes casos, logo aps a definio do mtodo construtor da classe, dever ser executado o
mtodo construtor da superclasse.
Exemplo parte 03: Mtodo Construtor da classe Aluno
METHOD Create(cNome,dNascimento,nID)
:Create(cNome,dNascimento) // Chamada do mtodo construtor da classe Pessoa.
::nID := ID
Return SELF

- 27 ADVPL Avanado

3. Regras adicionais da linguagem ADVPL


3.1. Palavras reservadas
AADD
ABS
ASC
AT
BOF
BREAK
ENDIF
LTRIM
SPACE
CTOD
FILE
PCOUNT
TRANSFORM
DOW
IIF
CATCH

DTOS
ELSE
ELSEIF
EMPTY
ENDCASE
ENDDO
LOWER
SETPOS
COL
FIELDNAME
PCOL
TIME
DEVPOS
IF
RECNO
THROW

INKEY
INT
LASTREC
LEN
LOCK
LOG
SELECT
CMONTH
FCOUNT
MONTH
SUBSTR
DELETED
FUNCTION
RECCOUNT
UPPER

 Palavras reservadas no
procedimentos ou funes;

REPLICATE
RLOCK
ROUND
ROW
RTRIM
SECONDS
CHR
EXP
MIN
STR
DAY
FOUND
PROW
TYPE
TRY

podem

ser

VAL
VALTYPE
WHILE
WORD
YEAR
CDOW
EOF
MAX
SQRT
DATE
FLOCK
PROCEDURE
TRIM
DTOC
AS

utilizadas

para

variveis,

 Funes reservadas so pertencentes ao compilador e no podem ser


redefinidas por uma aplicao;
 Todos os identificadores que comearem com dois ou mais caracteres
_ so utilizados como identificadores internos e so reservados.
 Identificadores de escopo PRIVATE ou PUBLIC utilizados em aplicaes
especficas desenvolvida por ou para clientes devem ter sua
identificao iniciada por um caractere _.

- 28 ADVPL Avanado

3.2. Pictures de formatao disponveis


Com base na documentao disponvel no DEM Documentao Eletrnica Microsiga, a
linguagem ADVPL e a aplicao ERP Protheus admitem as seguintes pictures:
Dicionrio de Dados (SX3) e GET
Funes
Contedo
A
C
E
R
S<n>
X
Z
(
)
!

Funcionalidade
Permite apenas caracteres alfabticos.
Exibe CR depois de nmeros positivos.
Exibe numrico com o ponto e vrgula invertidos (formato Europeu).
Insere caracteres diferentes dos caracteres de template na exibio, mas no os
insere na varivel do GET.
Permite rolamento horizontal do texto dentro do GET, <n> um nmero inteiro
que identifica o tamanho da regio.
Exibe DB depois de nmeros negativos.
Exibe zeros como brancos.
Exibe nmeros negativos entre parnteses com os espaos em branco iniciais.
Exibe nmeros negativos entre parnteses sem os espaos em branco iniciais.
Converte caracteres alfabticos para maisculo.

Templates
Contedo Funcionalidade
X
Permite qualquer caractere.
9
Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos.
#
Permite dgitos, sinais e espaos em branco para qualquer tipo de dado.
!
Converte caracteres alfabticos para maisculo.
*
Exibe um asterisco no lugar dos espaos em branco iniciais em nmeros.
.
Exibe o ponto decimal.
,
Exibe a posio do milhar.
Exemplo 01 Picture campo numrico
CT2_VALOR Numrico 17,2
Picture: @E 99,999,999,999,999.99

Exemplo 02 Picture campo texto, com digitao apenas em caixa alta


A1_NOME Caracter - 40
Picture: @!

- 29 ADVPL Avanado

MDULO 07: ADVPL Orientado objetos II


Neste mdulo sero tratados os componentes e objetos da interface visual da linguagem
ADVPL, permitindo o desenvolvimento de aplicaes com interfaces grficas com sintaxe
orientada a objetos.

4. Componentes da interface visual do ADVPL


A linguagem ADVPL possui diversos componentes visuais e auxiliares, os quais podem ser
representados utilizando a estrutura abaixo:

Classes da Interface Visual


Tsrvobject

Classes Auxiliares
Tfont

Classes de Janelas
Msdialog
Tdialog
Twindow

Classes de Componentes
Tcontrol

- 30 ADVPL Avanado

Classes de Componentes
Visuais
Brgetddb
Mscalend
Mscalendgrid
Msselbr
Msworktime
Sbutton
Tbar
Tbitmap
Tbrowsebutton
Tbtnbmp
Tbtnbmp2
Tbutton
Tcbrowse
Tcheckbox
Tcolortriangle
Tcombobox
Tfolder
Tfont
Tget
Tgroup
Thbutton
Tibrowser
Tlistbox
Tmenu
Tmenubar
Tmeter
Tmsgraphic
Tmsgbar
Tmultibtn
Tmultiget
Tolecontainer
Tpageview
Tpanel
Tradmenu
Tsbrowse
Tsay
Tscrollbox
Tsimpleeditor

Tslider

Classes de Componentes
Visuais
Tsplitter
Ttabs
Ttoolbox
Twbrowse
Vcbrowse

Atributos comuns as classes de componentes visuais


cCaption
cF3
cMsg
cName
cTooltip
cVariable
lPassword
lReadOnly
lShowHint
lVisibleControl
nHeight
nLeft
nTop
nWidth
Picture

Ttulo ou contedo do objeto.


Consulta F3 ao qual o objeto est vinculado, quando o
mesmo do tipo get.
Mensagem exibida na barra de status da janela principal
quando o objeto ganha foco.
Nome do objeto
Mensagem exibida quando objeto exibe seu tooltip.
Varivel que receber o contedo selecionado ou digitado no
objeto, quando o mesmo for to tipo get ou similar.
Indica se o texto digitado no objeto ser exibido no formato
de password, quando o mesmo do tipo get.
Flag que indica se o objeto pode ou no ser editado.
Flag que ativa .T. ou desativa .F. a exibio do tooltip do
objeto.
Se .T. o objeto visvel, se .F. o objeto invisvel.
Altura em pixels.
Coordenada horizontal em pixels.
Coordenada vertical em pixels.
Largura em pixels.
Picture de digitao do objeto, quando o mesmo do tipo
get.

Eventos comuns as classes de componentes visuais


bAction
bChange
bF3
bGotFocus
blClicked
blDblClick
bLostFocus
brClicked
bValid
bWhen

Bloco de cdigo executado quando o objeto utilizado,


quando o mesmo do tipo boto ou similar.
Bloco de cdigo executado quando ocorre uma mundana na
seleo de itens que compe o objeto, como por exemplo
em listas ou grids.
Bloco de cdigo executado quando utilizado o recurso de
consulta F3 vinculado ao objeto.
Executado quando objeto ganha foco.
Executado quando acionado click do boto esquerdo do
mouse sobre o objeto.
Executado quando acionado duplo click do boto esquerdo
do mouse sobre o objeto.
Executado quando objeto perde foco.
Executado quando acionado click do boto direito do mouse
sobre o objeto.
Executado quando o contedo do objeto modificado e
dever ser validado. Deve retornar .T. se o contedo
vlido e .F. se contedo invlido.
Executado quando h movimentao de foco na janela.Se
retornar .T. o objeto continua habilitado, se retornar .F. o
- 31 ADVPL Avanado

objeto ser desabilitado.

Classes da interface visual


TSRVOBJECT()


Descrio: Classe abstrata inicial de todas as classes de interface do ADVPL. No deve


ser instanciada diretamente.

Propriedades:
nLeft
nTop
nWidth
nHeight
cCaption
cTooltip
lShowHint
cMsg
nClrText
nClrPane
bWhen

bValid
blClicked
brClicked
blDblClick
oWnd
lVisible
Cargo
bLostFocus
bGotFocus

Coordenada horizontal em pixels.


Coordenada vertical em pixels.
Largura em pixels.
Altura em pixels.
Ttulo ou contedo do objeto.
Mensagem exibida quando objeto exibe seu tooltip.
Flag que ativa .T. ou desativa .F. a exibio do tooltip do
objeto.
Mensagem exibida na barra de status da janela principal
quando o objeto ganha foco.
Cor do texto do objeto.
Cor do fundo do objeto.
Executado quando h movimentao de foco na janela.Se
retornar .T. o objeto continua habilitado, se retornar .F. o
objeto ser desabilitado.
Executado quando o contedo do objeto modificado e
dever ser validado. Deve retornar .T. se o contedo
vlido e .F. se contedo invlido.
Executado quando acionado click do boto esquerdo do
mouse sobre o objeto.
Executado quando acionado click do boto direito do mouse
sobre o objeto.
Executado quando acionado duplo click do boto esquerdo
do mouse sobre o objeto.
Janela onde o objeto foi criado.
Se .T. o objeto visvel, se .F. o objeto invisvel.
Contedo associado ao objeto.
Executado quando objeto perde foco.
Executado quando objeto ganha foco.

Construtor: No pode ser instanciada.

Parmetros:
Nenhum

- 32 ADVPL Avanado

Mtodos auxiliares:
SetFocus
 Descrio: Fora mudana do foco de entrada de dados para o controle.
 Sintaxe: SetFocus( )
 Parmetros:
Nenhum

 Retorno:
Nil
Hide
 Descrio: Torna objeto invisvel.
 Sintaxe: Hide( )
 Parmetros:
Nenhum

 Retorno:
Nil
Show
 Descrio: Torna objeto visvel.
 Sintaxe: Show( )
 Parmetros:
Nenhum

 Retorno:
Nil
Enable
 Descrio: Habilita o objeto.
 Sintaxe: Enable( )
 Parmetros:
Nenhum

 Retorno:
Nil

- 33 ADVPL Avanado

Disable
 Descrio: Desabilita o objeto.
 Sintaxe: Disable( )
 Parmetros:
Nenhum

 Retorno:
Nil
Refresh
 Descrio: Fora atualizao (sincronia) de propriedades entre o programa e o
Protheus Remote.
 Sintaxe: Refresh( )
 Parmetros:
Nenhum

 Retorno:
Nil

Exemplo:

CLASS TCONTROL FROM TSRVOBJECT

- 34 ADVPL Avanado

Classes auxiliares
TFONT()


Descrio: Classe de objetos que define a fonte do texto utilizado nos controles
visuais.

Propriedades:
-

Herdadas as classes superiores

Construtor: New([acName], [nPar2], [anHeight], [lPar4], [alBold], [nPar6],


[lPar7], [nPar8], [alItalic], [alUnderline])

Parmetros:
acName
nPar2
anHeight
lPar4
alBold
nPar6
lPar7
nPar8
alItalic
alUnderline

Caractere, opcional. Nome da fonte, o padro Arial.


Reservado.
Numrico, opcional. Tamanho da fonte. O padro -11.
Reservado.
Lgico, opcional. Se .T. o estilo da fonte ser negrito.
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. o estilo da fonte ser itlico.
Lgico, opcional. Se .T. o estilo da fonte ser sublinhado.

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg, oSay
DEFINE MSDIALOG oDlg FROM 0,0 TO 200,200 TITLE 'My dialog' PIXEL
// Cria font para uso
oFont:= TFont():New('Courier New',,-14,.T.)
// Apresenta o tSay com a fonte Courier New
oSay := TSay():New( 10, 10, {|| 'Mensagem'},oDlg,, oFont,,,, .T.,
CLR_WHITE,CLR_RED )
oSay:lTransparent:= .F.
ACTIVATE MSDIALOG oDlg CENTERED
Return

- 35 ADVPL Avanado

Classes de janelas
MSDIALOG()


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

Propriedades:
-

Herdadas as classes superiores

Construtor: New([anTop], [anLeft], [anBottom], [anRight], [acCaption],


[cPar6], [nPar7], [lPar8], [nPar9], [anClrText], [anClrBack], [oPar12],
[aoWnd], [alPixel], [oPar15], [oPar16], [lPar17])

Parmetros:
anTop
anLeft
anBotom
anRight
acCaption
cPar6
nPar7
lPar8
nPar9
anClrText
anClrBack
oPar12
aoWnd
alPixel
oPar15
oPar16
nPar17

Numrico, opcional. Coordenada vertical superior em pixels


ou caracteres.
Numrico, opcional. Coordenada horizontal esquerda em
pixels ou caracteres.
Numrico, opcional. Coordenada vertical inferior em pixels
ou caracteres.
Numrico, opcional. Coordenada horizontal direita em pixels
ou caracteres.
Caractere, opcional. Ttulo da janela.
Reservado.
Reservado.
Reservado.
Reservado.
Numrico,opcional. Cor do texto.
Numrico,opcional. Cor de fundo.
Reservado.
Objeto, opcional. Janela me da janela a ser criada, padro
a janela principal do programa.
Lgico, opcional. Se .T. considera as coordenadas passadas
em pixels, se .F. considera caracteres.
Reservado.
Reservado.
Reservado.

- 36 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
// cria dilogo
Local oDlg := MSDialog():New(10,10,300,300,'Meu
dialogo',,,,,CLR_BLACK,CLR_WHITE,,,.T.)
// ativa dilogo centralizado
oDlg:Activate(,,,.T.,{||msgstop('validou!'),.T.},,{||msgstop('iniciando'
)} )
Return

TDIALOG()


Descrio: Classe de objetos do tipo dilogo de entrada de dados, sendo seu


uso reservado. Recomenda-se utilizar a classe MSDialog que
herdada desta classe.

Propriedades:
-

Herdadas as classes superiores

Construtor: New([anTop], [anLeft], [anBottom], [anRight], [acCaption],


[cPar6], [nPar7], [lPar8], [nPar9], [anClrText], [anClrBack], [oPar12],
[aoWnd], [alPixel], [oPar15], [oPar16], [nPar17], [anWidth],
[anHeight])

Parmetros:
anTop
anLeft
anBotom
anRight

Numrico, opcional. Coordenada


ou caracteres.
Numrico, opcional. Coordenada
pixels ou caracteres.
Numrico, opcional. Coordenada
ou caracteres.
Numrico, opcional. Coordenada
- 37 ADVPL Avanado

vertical superior em pixels


horizontal esquerda em
vertical inferior em pixels
horizontal direita em pixels

ou caracteres.
Caractere, opcional. Ttulo da janela.
Reservado.
Reservado.
Reservado.
Reservado.
Numrico,opcional. Cor do texto.
Numrico,opcional. Cor de fundo.
Reservado.
Objeto, opcional. Janela me da janela a ser criada, padro
a janela principal do programa.
Lgico, opcional. Se .T. considera as coordenadas passadas
em pixels, se .F. considera caracteres.
Reservado.
Reservado.
Reservado.
Numrico, opcional. Largura da janela em pixels.
Numrico, opcional. Altura da janela em pixels.

acCaption
cPar6
nPar7
lPar8
nPar9
anClrText
anClrBack
oPar12
aoWnd
alPixel
oPar15
oPar16
nPar17
anWidth
anHeight

Mtodos auxiliares:
Activate
 Descrio: Ativa (exibe) o dilogo. Chamar somente uma vez este
mtodo.
 Sintaxe: Activate([bPar1], [bPar2], [bPar3], [alCentered], [abValid],
[lPar6], [abInit], [bPar8], [bPar9] )
 Parmetros:
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. exibe a janela centralizada, .F.
padro.
Bloco de cdigo, opcional. Deve retornar .T. se contedo
do dilogo vlido, se retornar .F. o dilogo no fechar
quando solicitada de encerrar.
Reservado.
Bloco de cdigo, opcional. Executado quando o dilogo
inicia exibio.
Reservado.
Reservado.

bPar1
bPar2
bPar3
alCentered
abValid
lPar6
abInit
bPar8
bPar9
 Retorno:
Nenhum

- 38 ADVPL Avanado

End
 Descrio: Encerra (fecha) o dilogo.
 Sintaxe: End( )
 Parmetros:
Nenhum

 Retorno: Lgico .T. se o dilogo foi encerrado.


Lgico

Indica se o dilogo foi encerrado.

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
// cria dilogo
oDlg := MSDialog():New(10,10,300,300,'Meu
dialogo',,,,,CLR_BLACK,CLR_WHITE,,,.T.)
// ativa dilogo centralizado
oDlg:Activate(,,,.T.,{||msgstop('validou!'),.T.},,{||msgstop('iniciando..
.')} )
/* os comandos abaixo proporcionam o mesmo resultado
// cria dilogo
DEFINE DIALOG oDlg TITLE 'Meu dialogo' FROM 10,10 TO 300,300 COLOR
CLR_BLACK,CLR_WHITE PIXEL
// ativa dilogo centralizado
ACTIVATE DIALOG oDlg CENTER ON INIT (msgstop('iniciando...')) VALID
(msgstop('validou!'),.T.)
*/
Return Nil

- 39 ADVPL Avanado

TWINDOW()


Descrio: Classe de objetos do tipo dilogo principal de programa. Dever


existir apenas uma instncia deste objeto na execuo do programa.

Propriedades:
-

Herdadas das classes superiores

Construtor: New( [anTop], [anLeft],[anBottom], [anRight], [acTitle], [nPar6],


[oPar7] ,[oPar8],[oPar9], [aoParent], [lPar11], [lPar12], [anClrFore],
[anClrBack], [oPar15], [cPar16], [lPar17], [lPar18], [lPar19],
[lPar20], [alPixel] );

Parmetros:
nTop
nLeft
nBottom
nRight
cTitle
nPar6
oPar7
oPar8
oPar9
oParent
lPar11
lPar12
nClrFore
nClrText
oPar15
cPar16
lPar17
lPar18
lPar19
lPar20
lPixel

Numrico, opcional. Coordenada vertical superior em pixels


ou caracteres.
Numrico, opcional. Coordenada horizontal esquerda em
pixels ou caracteres.
Numrico, opcional. Coordenada vertical inferior em pixels
ou caracteres.
Numrico, opcional. Coordenada horizontal inferior em pixels
ou caracteres.
Caractere, opcional. Ttulo da janela.
Reservado.
Reservado.
Reservado.
Reservado.
Objeto, opcional. Janela me da janela corrente.
Reservado.
Reservado.
Numrico, opcional. Cor de fundo da janela.
Numrico, opcional. Cor do texto da janela.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. (padro) considera coordenadas
passadas em pixels, se .F. considera caracteres.

- 40 ADVPL Avanado

Mtodos auxiliares:
Activate
 Descrio: Ativa (exibe) a janela. Chamar esse mtodo apenas uma vez.
 Sintaxe: Activate([acShow], [bPar2], [bPar3], [bPar4], [bPar5], [bPar6],
[ abInit ], [bPar8], [bPar9], [bPar10], [bPar11], [bPar12] ,[bPar13],
[bPar14], [bPar15], [abValid], [bPar17], [bPar18] ).
 Parmetros:
acShow
bPar2
bPar3
bPar4
bPar5
bPar6
abInit
bPar8
bPar9
bPar10
bPar11
bPar12
bPar13
bPar14
bPar15
abValid
bPar17
bPar18

Caracter, opcional. ICONIZED para janela iconizada ou


MAXIMIZED para janela maximizada.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Bloco de cdigo. Executado quando janela est sendo
exibida.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.
Bloco de cdigo. Executado quando a janela for solicitada
de fechar. Dever retornar .T. se o contedo da janela for
vlido, ou .F. se no. Se o bloco retornar .F. a janela no
fechar.
Reservado.
Reservado.

 Retorno:
Nenhum

End
 Descrio: Solicita encerramento da janela.
 Sintaxe: End( )
 Parmetros:
Nenhum

 Retorno: Lgico .T. se o dilogo foi encerrado.


Lgico

Indica se a janela foi encerrada.

- 41 ADVPL Avanado

Center
 Descrio: Centraliza a janela.
 Sintaxe: Center( )
 Parmetros:
Nenhum

 Retorno: Lgico .T. se o dilogo foi encerrado.


Nenhum


Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oWindow
Local abInit:= {||conout('ativando!')}
Local abValid:= {||conout('encerrando!'),.T.}
oWindow:= tWindow():New( 10, 10, 200, 200, 'Meu
programa',,,,,,,,CLR_WHITE,CLR_BLACK,,,,,,,.T. )
oWindow:Activate('MAXIMIZED',,,,,,abInit,,,,,,,,,abValid,,)
/* os comandos abaixo proporcionam o mesmo resultado
DEFINE WINDOW oWindow FROM 10, 10 TO 200,200 PIXEL TITLE 'Meu programa'
COLOR CLR_WHITE,CLR_BLACK
ACTIVATE WINDOW oWindow MAXIMIZED ON INIT abInit VALID abValid
*/
Return
.

- 42 ADVPL Avanado

Classes de componentes
TCONTROL()


Descrio: Classe abstrata comum entre todos os componentes visuais


editveis. No deve ser instanciada diretamente.

Propriedades:
Numrico. Alinhamento do controle no espao
disponibilizado pelo seu objeto parente. 0 = Nenhum
(padro), 1= no topo, 2 = no rodap, 3= a esquerda, 4 = a
direita e 5 = em todo o parente.
Lgico. Se .T. indica que o contedo da varivel associada
ao controle foi modificado.
Lgico. Se .T. o contedo da varivel associada ao controle
permanecer apenas para leitura.
Numrico. Handle (identificador) do objeto sobre o qual o
controle foi criado.
Bloco de cdigo. Executado quando o estado ou contedo do
controle modificado pela ao sobre o controle.

Align

lModified
lReadOnly
hParent
bChange


Construtor: No pode ser instanciada.

Parmetros:
-

Nenhum


Mtodos auxiliares:
SetFocus
 Descrio: Fora mudana do foco de entrada de dados para o controle.
 Sintaxe: SetFocus( )
 Parmetros:
Nenhum

 Retorno:
Nil

Exemplo:

CLASS TSay FROM Tcontrol

- 43 ADVPL Avanado

Classes de componentes visuais


BRGETDDB()


Descrio: Classe de objetos visuais do tipo Grid.

Propriedades:
+
nAt
nLen

Herdadas da classe superior


Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

Construtor: New([nRow], [nCol], [nWidth], [nHeigth], [bFields], [aHeaders],


[aColSizes], [oDlg], [cField], [uValue1], [uValue2], [uChange],
[uLDblClick], [uRClick], [oFont], [oCursor], [nClrFore], [nClrBack],
[cMsg], [lUpdate], [cAlias], [lPixel], [bWhen], [lDesign], [bValid],
[aAlter], [oMother])

Parmetros:
nRow
nCol
nWidth
nHeight
bFields
aHeaders
aColSizes
oDlg
cField
uValue1
uValue2
bChange
bLDblClick
bRClick
oFont
oCursor
nClrFore
nClrBack
cMsg
lUpdate
cAlias
lPixel

bWhen
lDesign

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, Lista de Campos
Vetor, Descrio dos campos para no cabealho
Vetor, Largura das colunas
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Caracter, opcional. Campos necessrios ao filtro
Indefinido, opcional. Inicio do intervalo para o filtro
Indefinido, opcional. Fim do intervalo para o filtro
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
No utilizado
Objeto, opcional. Fonte
Objeto, opcional. Tipo do Cursor
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Caracter, opcional se objeto utilizado com Vetor, obrigatorio
se utilizado com Tabela
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
No Utilizado

- 44 ADVPL Avanado

Bloco de cdigo, opcional. Executado quando o contedo do


controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
No Utilizado
No Utilizado

bValid
aAlter
oMother


Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:

- 45 ADVPL Avanado

Nil
RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil

Aparncia:

- 46 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 302,402 PIXEL TITLE 'Exemplo'
DbSelectArea('SA1')
oBrowse := BrGetDDB():New(
1,1,200,150,,,,oDlg,,,,,,,,,,,,.F.,'SA1',.T.,,.F.,,, )
oBrowse:AddColumn(TCColumn():New('Codigo',{||SA1->A1_COD
},,,,'LEFT',,.F.,.F.,,,,.F.,))
oBrowse:AddColumn(TCColumn():New('Loja' ,{||SA1>A1_LOJA},,,,'LEFT',,.F.,.F.,,,,.F.,))
oBrowse:AddColumn(TCColumn():New('Nome' ,{||SA1>A1_NOME},,,,'LEFT',,.F.,.F.,,,,.F.,))
// Principais commandos
TButton():New(160,001,'GoUp()',oDlg,{|| oBrowse:GoUp()
},40,10,,,,.T.)
TButton():New(170,001,'GoDown()',oDlg,{|| oBrowse:GoDown()
},40,10,,,,.T.)
TButton():New(180,001,'GoTop()',oDlg,{|| oBrowse:GoTop()
},40,10,,,,.T.)
TButton():New(190,001,'GoBottom()' , oDlg,{|| oBrowse:GoBottom()
},40,10,,,,.T.)
TButton():New(160,060,'nAt (Linha selecionada)',oDlg,;
{|| Alert (oBrowse:nAt)},80,10,,,,.T.)
TButton():New(170,060,'nRowCount (Nr de linhas visiveis)',oDlg,;
{|| Alert(oBrowse:nRowCount()) },80,10,,,,.T.)
TButton():New(180,060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oBrowse:nLen) },80,10,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
MSCALEND()


Descrio: Classe de objetos visuais do tipo Calendrio.

Propriedades:
+
bChange
bChangeMes
dDiaAtu

Herdadas da classe superior


Bloco de cdigo executado na mudana de seleo de um
dia.
Bloco de cdigo executado na mundaa de seleo de um
ms.
Dia atualmente selecionado

Construtor: New([nRow], [nCol], [oDlg], [lCanMultSel])

- 47 ADVPL Avanado

Parmetros:
nRow
nCol
oDlg
lCanMultSel

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Logico, opcional. Permite seleo de multiplos dias

Aparncia:

Exemplo:
#include 'protheus.ch'
user function Calend_Ex()
DEFINE MSDIALOG oDlg FROM 0,0 TO 1000,1000 PIXEL TITLE 'Exemplo de
MsCalend'
// Cria objeto
oCalend:=MsCalend():New(01,01,oDlg,.T.)
// Code-Block para mudana de Dia
oCalend:bChange := {|| Alert('Dia Selecionado: ' +
dtoc(oCalend:dDiaAtu)) }
// Code-Block para mudana de mes
oCalend:bChangeMes := {|| alert('Mes alterado') }
ACTIVATE MSDIALOG oDlg CENTERED
Return

- 48 ADVPL Avanado

MSCALENDGRID()


Descrio: Classe de objetos visuais do tipo Grade de Perodos.

Propriedades:
bAction
bRClick

Bloco de cdigo. Executado quando o boto esquerdo do


mouse pressionado.
Bloco de cdigo. Executado quando o boto direito do mouse
pressionado.

Construtor: New([aoWnd],
[anRow],
[anCol],
[anHeight],
[anWidth],
[dDateIni], [nResolution], [abWhen], [abAction], [nDefColor],
[bRClick], [lFillAll])

Parmetros:
aoWnd

anRow
anCol
anHeight
anWidth
dDateIni
nResolution
abWhen

abAction
nDefColor
bRClick
lFillAll


Objeto, opcional. Janela ou controle onde o boto dever ser


criado.
Numrico, opcional.
carateres.
Numrico, opcional.
caracteres.
Numrico, opcional.
Numrico, opcional.

Coordenada vertical em pixels ou


Coordenada horizontal em pixels ou
Altura do boto em pixels.
Largura do boto em pixels.

Data, Data inicial do Calendrio


Numrico, Resoluo a ser aplicada na grid do Calendrio
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Numrico, opcional. Cor do Fundo da Grid.
Bloco de cdigo, opcional. Executado quando acionado o
boto direito do mouse sobre o controle.
Lgico, opcional. Preenche todo o periodo

Mtodos auxiliares:
Add
 Descrio: Adiciona periodo na Grid.
 Sintaxe: Add(cCaption, nLin, nInitial, nFinal, nColor, cDescri )
 Parmetros:
cCaption
nLin
nInitial
nFinal

Caracter. Descrio a ser inserida a esquerda da Grid


Numerico. Numero da linha a ser inserido o item
Numerico. Dia inicial
Numerico. Dia Final
- 49 ADVPL Avanado

nColor
cDescri

Numerico. Cor que destacara o item


Caracter, Opicional. Descrio do tipo tooltip(hint) do item

 Retorno:
Nil


Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
nResolution := 1
oMsCalendGrid := MsCalendGrid():New( oDlg, 01, 01, 500,300,;
date(), nResolution, ,{|x,y| Alert(x) },;
RGB(255,255,196), {|x,y|Alert(x,y)}, .T.
)
oMsCalendGrid:Add('caption 01', 1, 10, 20, RGB(255,000,0),
'Descricao 01')
oMsCalendGrid:Add('caption 02', 2, 20, 30, RGB(255,255,0),
'Descricao 02')
oMsCalendGrid:Add('caption 03', 3, 01, 05, RGB(255,0,255),
'Descricao 03')
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 50 ADVPL Avanado

MSSELBR()


Descrio: Classe de objetos visuais do tipo controle - Grid

Propriedades:
+
nAt
nLen

Herdadas da classe superior


Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

Construtor: New([nRow], [nCol], [nWidth], [nHeigth], [bFields], [aHeaders],


[aColSizes], [oDlg], [cField], [uValue1], [uValue2], [uChange],
[uLDblClick], [uRClick], [oFont], [oCursor], [nClrFore], [nClrBack],
[cMsg], [lUpdate], [cAlias], [lPixel], [bWhen], [lDesign], [bValid])

Parmetros:
nRow
nCol
nWidth
nHeight
bFields
aHeaders
aColSizes
oDlg
cField
uValue1
uValue2
bChange
bLDblClick
bRClick
oFont
oCursor
nClrFore
nClrBack
cMsg
lUpdate
cAlias
lPixel

bWhen
lDesign
bValid

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, Lista de Campos
Vetor, Descrio dos campos para no cabealho
Vetor, Largura das colunas
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Caracter, opcional. Campos necessrios ao filtro
Indefinido, opcional. Inicio do intervalo para o filtro
Indefinido, opcional. Fim do intervalo para o filtro
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
No utilizado
Objeto, opcional. Fonte
Objeto, opcional. Tipo do Cursor
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Caracter, opcional se objeto utilizado com Vetor, obrigatorio
se utilizado com Tabela
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
No Utilizado
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.

- 51 ADVPL Avanado

Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:
Nil

- 52 ADVPL Avanado

RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil


Aparncia:

- 53 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 302,402 PIXEL TITLE 'Exemplo'
DbSelectArea('SA1')
oBrowse := MsSelBr():New(
1,1,200,150,,,,oDlg,,,,,,,,,,,,.F.,'SA1',.T.,,.F.,,, )
oBrowse:AddColumn(TCColumn():New('Codigo',{||SA1->A1_COD
},,,,'LEFT',,.F.,.F.,,,,.F.,))
oBrowse:AddColumn(TCColumn():New('Loja' ,{||SA1>A1_LOJA},,,,'LEFT',,.F.,.F.,,,,.F.,))
oBrowse:AddColumn(TCColumn():New('Nome' ,{||SA1>A1_NOME},,,,'LEFT',,.F.,.F.,,,,.F.,))
// Principais commandos
TButton():New(160,001,'GoUp()',oDlg,{|| oBrowse:GoUp()
},40,10,,,,.T.)
TButton():New(170,001,'GoDown()',oDlg,{|| oBrowse:GoDown()
},40,10,,,,.T.)
TButton():New(180,001,'GoTop()',oDlg,{|| oBrowse:GoTop()
},40,10,,,,.T.)
TButton():New(190,001,'GoBottom()' , oDlg,{|| oBrowse:GoBottom()
},40,10,,,,.T.)
TButton():New(160,060,'nAt (Linha selecionada)',oDlg,{||
Alert(oBrowse:nAt)},80,10,,,,.T.)
TButton():New(170,060,'nRowCount (Nr de linhas visiveis)',oDlg,;
{|| Alert(oBrowse:nRowCount()) },80,10,,,,.T.)
TButton():New(180,060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oBrowse:nLen) },80,10,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
.
MSWORKTIME()


Descrio: Classe de objetos visuais do tipo controle - Barra de Perodo.

Propriedades:
bChange

Bloco de cdigo. Executado ao disparar qualquer ao sobre


o objeto.

Construtor: New([aoWnd],
[anRow],
[anCol],
[anHeight],
[nResolution], [cValue], [abWhen], [abChange])

Parmetros:
aoWnd
anRow

[anWidth],

Objeto, opcional. Janela ou controle onde o boto dever ser


criado.
Numrico, opcional. Coordenada vertical em pixels ou
carateres.

- 54 ADVPL Avanado

Numrico, opcional. Coordenada horizontal em pixels ou


caracteres.
Numrico, opcional. Altura do boto em pixels.
Numrico, opcional. Largura do boto em pixels.
Numrico, Resoluo a ser aplicada na grid do Calendrio
Caracter, opcional. Descritivo
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.

anCol
anHeight
anWidth
nResolution
cValue
abWhen

abChange


Mtodos auxiliares:
GetValue
 Descrio: Retorna os item selecionados no formato XX X XX.
 Sintaxe: GetValue()
 Parmetros:
Nenhum

 Retorno:
Caracter

Retorna os item selecionados no formato XX X XX.

GetInterTime
 Descrio: Retorna periodo selecionado.
 Sintaxe: GetInterTime()
 Parmetros:
Nenhum

 Retorno:
Caracter

Retorna o perodo selecionada no formato HH:MM:SS

SetResol
 Descrio: Define a resoluo da demonstrao da barra de perodos.
 Sintaxe: SetResol (nResolution)
 Parmetros:
nResolution

Resoluo

 Retorno:
Nil

- 55 ADVPL Avanado

SetValue
 Descrio: Atribui um determindo contedo para um objeto ou atributo
de um objeto.
 Sintaxe: SetValue(xValue, cPicture)
 Parmetros:
xValue
cPicture

Valor que ser atribudo ao objeto ou atributo do objeto.


Picture de formao opcional para o contedo atribudo.

 Retorno:
Nenhum

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oMsWorkTime := MsWorkTime():New(oDlg,04,04,280,133,0,'',{||.T.},;
{|oWorkTime|Alert('GetValue():
'+oWorkTime:GetValue()+chr(13)+;
'GetInterTime():
'+oWorkTime:GetInterTime())} )
oMsWorkTime:SetValue('X X XX X')
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 56 ADVPL Avanado

SBUTTON()


Descrio: Classe de objetos visuais do tipo boto que 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.

Propriedades:
Bloco de cdigo. Executado ao precionar o boto esquerdo
do mouse.

bAction


Construtor: New([nTop], [nLeft],


[cMsg], [bWhen])

Parmetros:

[bAction],

[oWnd],

[lEnable],

Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels ou
carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Numrico. Tipo do Boto
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Logico, opcional. Habilita/Desabilita boto
Caracter, Opicional. Descrio do tipo tooltip(hint) do item
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

Parmetro
nTop
nLeft
nType
bAction
oWnd
lEnable
cMsg
abWhen

[nType],

Mtodos auxiliares:
Create
 Descrio: Retorna Mtodo construtor opcional da classe.
 Sintaxe: Create()
 Parmetros:
Nenhum

 Retorno:
Objeto

Objeto da classe Sbutton com todos os atributos com


contedos padres.

- 57 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oSButton1 := SButton():New( 01,01,1,{||Alert('SButton
01')},oDlg,.T.,,)
oSButton2 := SButton():New( 21,01,2,{||Alert('SButton
02')},oDlg,.T.,,)
oSButton3 := SButton():New( 41,01,3,{||Alert('SButton
03')},oDlg,.T.,,)
oSButton4 := SButton():New( 61,01,4,{||Alert('SButton
04')},oDlg,.T.,,)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 58 ADVPL Avanado

TBAR()


Descrio: Classe de objetos visuais que permite a implementao de um


componente do tipo barra de botes para a parte superior de uma
janela previamente definida.

Propriedades:
-

Construtor:

Parmetros:
oWnd

Objeto, opcional. Janela ou controle onde o boto dever ser


criado.

nBtnWidth

Numrico, opcional. Largura do boto contido na barra

nBtnHeight

Numrico, opcional. Altura do boto contido na barra

l3D

Lgico, opcional. Define tipo da barra

cMode

No utilizado.

oCursor
cResource
lNoAutoAdjust


Herdados das classes superiores.

Objeto, opcional. Define Cursor ao posicionar o mouse sobre a


barra.
Caracter, opcional. Imagem do recurso a ser inserido como
fundo da barra.
Lgico.

Aparncia:

- 59 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
/*/
+-----------------------------------------------------------------------| Funo
| TSTBAR
| Autor | MICROSIGA
|Data |
|
+-----------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto TBar()
|
+-----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+-----------------------------------------------------------------------/*/
User Function TstTBar()
Local oDlg
oDlg

:= MSDIALOG():New(000,000,305,505, 'Exemplo - TBAR',,,,,,,,,.T.)

Exemplo (continuao):
oTBar := TBar():New( oDlg,25,32,.T.,,,,.F. )
oTBtnBmp2_1 := TBtnBmp2():New( 00, 00, 35, 25, 'copyuser' ,,,,;
{||Alert('TBtnBmp2_1')}, oTBar,'msGetEx',,.F.,.F. )
oTBtnBmp2_2 := TBtnBmp2():New( 00, 00, 35, 25, 'critica'
{||},oTBar,'Critica',,.F.,.F. )

,,,,;

oTBtnBmp2_3 := TBtnBmp2():New( 00, 00, 35, 25, 'bmpcpo'


{||},oTBar,'PCO',,.F.,.F. )

,,,,;

oTBtnBmp2_4 := TBtnBmp2():New( 00, 00, 35, 25, 'preco'


{||},oTBar,'Preo' ,,.F.,.F. )

,,,,;

oDlg:lCentered := .T.
oDlg:Activate()
Return

- 60 ADVPL Avanado

TBITMAP()


Descrio: Classe de objetos visuais que permite a exibio de uma imagem.

Propriedades:
cResName
cBmpFile
lStretch
lAutoSize
lTransparent

Caractere, Nome do resource


Caractere, Nome do arquivo
Lgico, opcional. Strech da imagem
Lgico, opcional. Tamanho automtico
Lgico, opcional. Transparente

Construtor: New([anTop], [anLeft], [anWidth], [anHeight], [acResName],


[acBmpFile], [alNoBorder], [aoWnd], [abLClicked], [abRClicked],
[alScroll], [alStretch], [aoCursor], [acMsg], [alUpdate], [abWhen],
[alPixel], [abValid], [alDesign], [alIsIcon], [alIsJpeg] )

Parmetros:
anTop
anLeft
anWidth
anHeight
acResName
acBmpFile
alNoBorder
aoWnd
abLClicked
abRClicked
alScroll
alStretch
aoCursor
acMsg
alUpdate
abWhen
alPixel
abValid
alDesign
alIsIcon
alIsJpeg

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Numrico, opcional. Largura em pixels.
Numrico, opcional. Altura em pixels.
Caractere, Nome do resource.
Caractere, Nome do arquivo.
Lgico, opcional. Exibe borda
Objeto, opcional. Janela ou controle onde a imagem dever
ser criada.
Bloco de cdigo, opcional. Bloco que dever ser acionado
boto esquerdo do mouse for pressionado.
Bloco de cdigo, opcional. Bloco que dever ser acionado
boto direito do mouse for pressionado.
Lgico, opcional. Ativa o scroll
Lgico, opcional. Strech da imagem
Objeto, opcional. Cursor a ser exibido
No utilizado
No utilizado
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Lgico, opcional. Utiliza coordenadas em pixel
Bloco de cdigo, opcional. Bloco que dever ser acionado na
validao.
No utilizado
Lgico, opcional. cone. No utilizado a partir da verso
Protheus 8
Lgico, opcional. Jpeg. No utilizado a partir da verso
Protheus 8

- 61 ADVPL Avanado

Mtodos auxiliares:
Create
 Descrio: Retorna Mtodo construtor opcional da classe.
 Sintaxe: Create()
 Parmetros:
Nenhum

 Retorno:
Objeto

Objeto da classe TBar com todos os atributos com


contedos padres.

SetBmp
 Descrio: Mtodo para carregar uma imagem do repositrio.
 Sintaxe: SetBmp( acResName )
 Parmetros:
acResName

Caractere, Nome do resource

 Retorno:
-

Nenhum
Load

 Descrio: Mtodo para carregar uma imagem do repositrio ou local.


 Sintaxe: Load( acResName, acBmpFile )
 Parmetros:
acResName
acBmpFile

Caractere, Nome do resource.


Caractere, Nome do arquivo.

 Retorno:
Nenhum


Aparncia:

- 62 ADVPL Avanado

Exemplo:

#include protheus.ch
User Function tBitmapTst()
Local oDlg
Local oBmp
DEFINE MSDIALOG oDlg TITLE '' FROM 0,0 TO 280,330 PIXEL
@ 10, 10 BITMAP oBmp RESOURCE 'totvs.bmp' SIZE 150,150 OF oDlg PIXEL
oBmp:lAutoSize := .T.
ACTIVATE MSDIALOG oDlg CENTERED
Return
.
TBROWSEBUTTON()


Descrio: Classe de objetos visuais do tipo boto no formato padro utilizado


em browses da aplicao.

Propriedades:
bAction

Bloco de cdigo. Executado ao precionar o boto esquerdo


do mouse.

Construtor: New([nRow], [nCol], [cCaption], [oWnd], [bAction], [nWidth],


[nHeight], [nHelpId], [oFont], [lDefault], [lPixel], [lDesign], [cMsg],
[lUpdate], [bWhen], [bValid], [lCancel])

Parmetros:
nRow
nCol
cCaption
oWnd
bAction
nWidth
nHeight
nHelpId
oFont
lDefault
lPixel

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Caractere, opcional. Titulo do boto.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Numrico, opcional. Largura do boto em pixels
Numrico, opcional. Altura do boto em pixels.
Reservado
Objeto, opcional. Objeto tipo tFont com propriedades da
fonte utilizada para o ttulo do boto.
Reservado
Lgico, opcional. Se .T. considera as coordenadas passadas
em pixels, se .F. (padro) considera em caracteres.
- 63 ADVPL Avanado

lDesign
cMsg
lUpdate
bWhen
bValid
lCancel


Reservado
Reservado
Reservado
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Reservado
Reservado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oTBrowseButton := TBrowseButton():New( 01,01,'TBrowseButton',oDlg,;
{||Alert('TBrowseButton')},40,10,,,.F.,.T.,.F.,,.F.,,,)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 64 ADVPL Avanado

TBTNBMP()


Descrio: Classe de objetos visuais do tipo boto, o qual permite que seja
vinculada uma imagem ao controle.

Propriedades:
bAction

Bloco de cdigo. Executado ao precionar o boto esquerdo


do mouse.

Construtor: NewBar([cResName1], [cResName2], [cBmpFile1], [cBmpFile2],


[cMsg], [bAction], [lGroup], [oWnd], [lAdjust], [bWhen], [cToolTip],
[lPressed],
[bDrop],
[cAction],
[nPos],
[cPrompt],
[oFont],
[cResName3], [cBmpFile3], [lBorder])

Parmetros:
cResName1
cResName2
cBmpFile1
cBmpFile2
cMsg
bAction
lGroup
oWnd
lAdjust
bWhen
cToolTip
lPressed
bDrop
cAction
nPos
cPrompt
oFont
cResName3
cBmpFile3
lBorder

Caractere, Nome do resource


Caractere, Nome do resource
Caractere, NO UTILIZADO
Caractere, NO UTILIZADO
Caractere, Mensagem de Hint
Bloco de cdigo. Ao executada
Lgico. Define grupo
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Lgico, NO UTILIZADO
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Mensagem exibida quando objeto exibe seu tooltip.
No utilizado
No utilizado
No utilizado
No utilizado
Caracter, opcional. Caption do boto.
Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada para exibir o contedo do
controle.
No utilizado
No utilizado
No utilizado

- 65 ADVPL Avanado

Mtodos auxiliares:
LoadBitmaps
 Descrio: Atribui ao boto os bitmaps ou recursos para exibio.
 Sintaxe:
LoadBitmaps([cResName1],
[cResName2],
[cBmpFile1],
[cBmpFile2], [cResName3], [cBmpFile3])
 Parmetros:
cResName1
cResName2
cBmpFile1
cBmpFile2
cResName3
cBmpFile3

Caractere,
Caractere,
Caractere,
Caractere,
Caractere,
Caractere,

Nome
Nome
Nome
Nome
Nome
Nome

do
do
do
do
do
do

resource
resource
arquivo BMP
arquivo BMP
resource
resource

 Retorno:
Nenhum

SetPopUpMenu
 Descrio: Seta o objeto do tipo TMenu referente ao boto.
 Sintaxe: SetPopupMenu(oMenu)
 Parmetros:
Nenhum

 Retorno:
Nenhum


Aparncia:

- 66 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oTBar := TBar():New( oDlg,25,32,.T.,,,,.F. ) // Orig: 25,45
oTBtnBmp1 := TBtnBmp() :NewBar('RPMNEW',,,,'Msg 01',;
{||Alert('TBtnBmp
01')},.F.,oTBar,.T.,{||.T.},,.F.,,,1,,,,,.T. )
oTBtnBmp2 := TBtnBmp() :NewBar('copyuser',,,,'Msg 02',;
{||Alert('TBtnBmp
02')},.F.,oTBar,.T.,{||.T.},,.F.,,,1,,,,,.T. )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

TBTNBMP2()


Descrio: Classe de objetos visuais do tipo boto, o qual permite a exibio de


uma imagem ou de um popup.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([anTop], [anLeft], [anWidth], [anHeight], [acResName1],


[acResName2], [acBmpFile1], [acBmpFile2],[abAction], [aoWnd],
[acMsg], [abWhen], [lAdjuste], [lUpdate])

Parmetros:
anTop
anLeft
anWidth
anHeight
acResName1
acResName2
acBmpFile1
acBmpFile2
abAction
aoWnd
acMsg
abWhen
lAdjust
lUpdate

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Numrico, opcional. Largura em pixels.
Numrico, opcional. Altura em pixels.
Caractere, Nome do resource
Caractere, NO UTILIZADO
Caractere, NO UTILIZADO
Caractere, NO UTILIZADO
Bloco de cdigo. Ao executada
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Caractere, Mensagem de Hint
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Lgico, NO UTILIZADO
Lgico, NO UTILIZADO

Mtodos auxiliares:
- 67 ADVPL Avanado

LoadBitmaps
 Descrio: Atribui ao boto os bitmaps ou recursos para exibio.
 Sintaxe:
LoadBitmaps([cResName1],
[cResName2],
[cBmpFile1],
[cBmpFile2], [cResName3], [cBmpFile3])
 Parmetros:
cResName1
cResName2
cBmpFile1
cBmpFile2
cResName3
cBmpFile3

Caractere,
Caractere,
Caractere,
Caractere,
Caractere,
Caractere,

Nome
Nome
Nome
Nome
Nome
Nome

do
do
do
do
do
do

resource
resource
arquivo BMP
arquivo BMP
resource
resource

 Retorno:
Nenhum
SetPopUpMenu
 Descrio: Seta o objeto do tipo TMenu referente ao boto.
 Sintaxe: SetPopupMenu(oMenu)
 Parmetros:
Nenhum

 Retorno:
Nenhum


Aparncia:

- 68 ADVPL Avanado

Exemplo:
Local oBtn := TBtnBmp2():New( 10, 10, 25, 25, 'printer_r2' , , , , , oDlg,
, , )
Exemplo 2 (Popup)
#INCLUDE 'PROTHEUS.CH'
User Function BtnBmpPopUp
Local oDlg
Local oBtn
DEFINE MSDIALOG oDlg TITLE '' FROM 0,0 TO 100,200 PIXEL
oBtn := TBtnBmp2():New( 10, 10, 13, 13, 'IBF-MENU.BMP' , 'IBF-MENU.BMP' ,
, , , oDlg, , , .T.)
oBtn:SetPopupmenu(TShowMenu())
ACTIVATE MSDIALOG oDlg CENTERED
Return
/**************************/
Static Function TShowMenu()
Local oMenu
oMenu := TMenu():New(0,0,0,0,.T.)
oMenu:Add(TMenuItem():New(,'Detalhes', 'Detalhes',,, ,,,,,,,,,.T.))
oMenu:Add(TMenuItem():New(,'Add Info', 'Add Info',,, ,,,,,,,,,.T.))
Return oMenu
TBUTTON()


Descrio: Classe de objetos visuais do tipo boto, o qual permite a utilizao


de texto para sua identificao.

Propriedades:
lProcessing
bAction

Lgico. Se .T. indica o boto est efetuando uma ao.


Bloco de cdigo. Executado quando o boto pressionado.

Construtor: New([anRow], [anCol], [acCaption], [aoWnd], [abAction],


[anWidth],
[anHeight],
[nPar8],
[aoFont],
[lPar10],
[alPixel],[lPar12],[cPar13], [lPar14], [abWhen], [bPar16], [lPar17])

Parmetros:
Parmetro
anRow
anCol
acCaption
aoWnd
abAction
anWidth
anHeight
nPar8
aoFont

Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels ou
carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Caractere, opcional. Titulo do boto.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Numrico, opcional. Largura do boto em pixels.
Numrico, opcional. Altura do boto em pixels.
Reservado.
Objeto, opcional. Objeto tipo tFont com propriedades da
fonte utilizada para o ttulo do boto.
- 69 ADVPL Avanado

lPar10
alPixel
lPar12
cPar13
lPar14
abWhen
bPar16
lPar17


Reservado.
Lgico, opcional. Se .T. considera as coordenadas passadas
em pixels, se .F. (padro) considera em caracteres.
Reservado.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Reservado.
Reservado.

Aparncia:

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

- 70 ADVPL Avanado

TCBROWSE()


Descrio: Classe de objetos visuais do tipo Grid.

Propriedades:
+
nAt
nLen

Herdadas da classe superior


Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

Construtor: New([nRow], [nCol], [nWidth], [nHeigth],[bFields], [aHeaders],


[aColSizes],
[oDlg],
[cField],
[uValue1],
[uValue2],
[uChange],[{|nRow,nCol,nFlags|[uLDblClick]}],
[{|nRow,nCol,nFlags|[uRClick]}], [oFont], [oCursor], [nClrFore],
[nClrBack], [cMsg], [lUpdate], [cAlias], [lPixel], [{uWhen}],
[lDesign], [bValid], [lHScroll], [lVScroll])

Parmetros:
nRow
nCol
nWidth
nHeight
bFields
aHeaders
aColSizes
oDlg
cField
uValue1
uValue2
bChange
bLDblClick
bRClick
oFont
oCursor
nClrFore
nClrBack
cMsg
lUpdate
cAlias
lPixel

bWhen
lDesign
bValid

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, Lista de Campos
Vetor, Descrio dos campos para no cabealho
Vetor, Largura das colunas
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Caracter, opcional. Campos necessrios ao filtro
Indefinido, opcional. Inicio do intervalo para o filtro
Indefinido, opcional. Fim do intervalo para o filtro
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
No utilizado
Objeto, opcional. Fonte
Objeto, opcional. Tipo do Cursor
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Caracter, opcional se objeto utilizado com Vetor, obrigatorio
se utilizado com Tabela
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
No Utilizado
Bloco de cdigo, opcional. Executado quando o contedo do

- 71 ADVPL Avanado

controle deve ser validado, deve retornar .T. se o contedo


for vlido e .F. quando o contedo for invlido.
Lgico, opcional. Se .T., habilita barra de rolagem
horizontal.
Lgico, opcional. Se .T., habilita barra de rolagem vertical.

lHScroll
lVScroll


Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:

- 72 ADVPL Avanado

Nil
RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil


Aparncia:

- 73 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
user function TcBrowse_EX()
Local oOK
:= LoadBitmap(GetResources(),'br_verde')
Local oNO
:= LoadBitmap(GetResources(),'br_vermelho')
Local aList := {} // Vetor com elementos do Browse
Local nX
// Cria Vetor para teste
for nX := 1 to 100
aListAux := {.T., strzero(nX,10), 'Descrio do Produto '+;
strzero(nX,3), 1000.22+nX}
aadd(aList, aListAux)
next
DEFINE MSDIALOG oDlg FROM 0,0 TO 520,600 PIXEL TITLE 'Exemplo da TCBrowse'
// Cria objeto de fonte que sera usado na Browse
Define Font oFont Name 'Courier New' Size 0, -12
// Cria Browse
oList := TCBrowse():New( 01 , 01, 300, 200,,;
'','Codigo','Descrio','Valor'},{20,50,50,50},;
oDlg,,,,,{||},,oFont,,,,,.F.,,.T.,,.F.,,, )
// Seta o vetor a ser utilizado
oList:SetArray(aList)
// Monta a linha a ser exibina no Browse
oList:bLine := {||{ If(aList[oList:nAt,01],oOK,oNO),;
aList[oList:nAt,02],;
aList[oList:nAt,03],;
Transform(aList[oList:nAT,04],'@E 99,999,999,999.99') } }
// Evento de DuploClick (troca o valor do primeiro elemento do Vetor)
oList:bLDblClick := {|| aList[oList:nAt][1] :=;
!aList[oList:nAt][1],oList:DrawSelect() }
// Principais commandos
oBtn := TButton():New( 210, 001,'GoUp()' , oDlg,{||oList:GoUp()},;
40, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 220, 001,'GoDown()', oDlg,{||oList:GoDown()},;
40, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 230, 001,'GoTop()' , oDlg,{||oList:GoTop()}, ;
40, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 240, 001,'GoBottom()', oDlg,{||oList:GoBottom()},;
40, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 210, 060, 'nAt (Linha selecionada)'
,;
oDlg,{|| Alert(oList:nAt)},;
90, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 220, 060, 'nRowCount (Nr de linhas visiveis)',
oDlg,;{|| Alert(oList:nRowCount()) }, 90, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 230, 060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oList:nLen) }, 90, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 240, 060, 'lEditCell (Edita a celula)', oDlg,;
{|| lEditCell(@aList,oList,'@!',3) }, 90, 010,,,.F.,.T.,.F.,,.F.,,,.F. )
ACTIVATE MSDIALOG oDlg CENTERED
return

- 74 ADVPL Avanado

TCHECKBOX()


Descrio: Classe de objetos visuais do tipo controle - CheckBox.

Propriedades:
bLClicked
bSetGet
bWhen
bValid

Bloco de cdigo disparado ao clique do mouse no objeto


Bloco de cdigo disparado na mudana de item selecionado,
responsavel pela mudana de valor da variavel numerica
que indica o item selecionado.
Bloco de cdigo recebe um lgico e de True permite
alterao, se False no permite.
Bloco de cdigo executado na saida do objeto.

Construtor: New([nRow], [nCol], [cCaption], [bSetGet], [oDlg], [nWidth],


[nHeight], [aHelpIds], [bLClicked], [oFont], [bValid], [nClrText],
[nClrPane], [lDesign], [lPixel], [cMsg], [lUpdate], [bWhen])

Parmetros:
nRow
nCol
cCaption
bSetGet
oDlg
nWidth
nHeight
aHelpIds
bLClicked
oFont
bValid
nClrText
nClrPane
lDesign
lPixel
cMsg
lUpdate
bWhen

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Caracter, Texto descritivo
Code-block, opcional, Responsvel pela setagem de valor
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
No utilizado
Bloco de cdigo, opcional. Executado ao clique do mouse.
Objeto, opcional. Fonte
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
No utilizado
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

- 75 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
user function TCheckBox()
DEFINE MSDIALOG oDlg FROM 0,0 TO 270,400 PIXEL TITLE 'Exemplo da
TCBrowse'
lCheck1 := .T.
oCheck1 := TCheckBox():New(01,01,'CheckBox 001',,oDlg,
100,210,,,,,,,,.T.,,,)
oCheck2 := TCheckBox():New(11,01,'CheckBox 002',,oDlg,
100,210,,,,,,,,.T.,,,)
oCheck3 := TCheckBox():New(21,01,'CheckBox 003',,oDlg,
100,210,,,,,,,,.T.,,,)
oCheck4 :=TCheckBox():New(31,01,'CheckBox 004',,oDlg,
100,210,,,,,,,,.T.,,,)
oCheck5 := TCheckBox():New(41,01,'CheckBox
005',,oDlg,100,210,,,,,,,,.T.,,,)
// Seta Eventos do primeiro Check
oCheck1:bSetGet
:= {|| lCheck1 }
oCheck1:bLClicked := {|| lCheck1:=!lCheck1 }
oCheck1:bWhen
:= {|| .T. }
oCheck1:bValid
:= {|| Alert('bValid') }
// Principais comandos
oBtn := TButton():New( 060, 001, 'Retorna estado do CheckBox
001',;
oDlg,{|| Alert(lCheck1) }, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
ACTIVATE MSDIALOG oDlg CENTERED
return

- 76 ADVPL Avanado

TCOLORTRIANGLE()


Descrio: Classe de objetos visuais do tipo Paleta de Cores.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([anRow], [anCol], [aoWnd], [anWidth], [anHeight] )

Parmetros:
Numrico, opcional. Coordenada vertical em pixels ou
carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Objeto, opcional. Janela ou controle onde a paleta dever
ser criada.
Numrico, opcional. Largura da paleta em pixels.
Numrico, opcional. Altura da paleta em pixels.

anRow
anCol
aoWnd
anWidth
anHeight


Mtodos auxiliares:
Create
 Descrio: Mtodo construtor opcional da classe.
 Sintaxe: Create(aoWnd)
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde a paleta dever


ser criada.

 Retorno:
Objeto

Objeto do tipo TColorTriangule com os atributos definidos


com contedo padro.

RetColor
 Descrio: Retorna o RGB da cor selecionada
 Sintaxe: RetColor ( )
 Parmetros:
Nenhum

 Retorno:
Numrico

Valor que representa do RGB da cor.

- 77 ADVPL Avanado

SetColorIni
 Descrio: Define a cor inicial selecionada para o controle.
 Sintaxe: SetColorIni (nColor )
 Parmetros:
nColor

Valor da cor inicial no padro RGB.

 Retorno:
Nenhum

SetColor
 Descrio: Define a cor corrente.
 Sintaxe: SetColor (nColor )
 Parmetros:
nColor

Valor da cor inicial no padro RGB.

 Retorno:
Nenhum

SetSizeTriangule
 Descrio: Define o tamanho do tringulo de configurao das cores.
 Sintaxe: SetSizeTriangule (nWidh, nHeight)
 Parmetros:
nWidth
nHeight

Numrico. Largura
Numrico.Altura

 Retorno:
Nenhum


Aparncia:

- 78 ADVPL Avanado

Exemplo:
#include protheus.ch
User Function tColor()
Local oDlg, oColorT
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Cores
// Usando o mtodo create
oColorT := tColorTriangle():Create( oDlg )
oColorT:SetColorIni( nColorIni )
ACTIVATE MSDIALOG oDlg CENTERED
Return Nil
TCOMBOBOX()


Descrio: Classe de objetos visuais do tipo tComboBox, a qual cria uma


entrada de dados com mltipla escolha com item definido em uma
lista vertical, acionada por F4 ou pelo boto esquerdo localizado na
parte direita do controle. A varivel associada ao controle ter o
valor de um dos itens selecionados ou no caso de uma lista
indexada, o valor de seu ndice.

Propriedades:

aItems
nAt

Array. Lista de itens, caracteres, a serem exibidos. Pode ter


os seguintes formatos: a) Seqencial, exemplo:
{item1,item2,...,itemN} ou b) Indexada, exemplo:
{a=item1,b=item2, ..., n=itemN}.
Numrico. Posio do item selecionado.

Construtor: New([anRow], [anCol], [abSetGet], [anItems], [anWidth],


[anHeight], [aoWnd], [nPar8], [abChange], [abValid], [anClrText],
[anClrBack], [alPixel], [aoFont], [cPar15], [lPar16], [abWhen],
[lPar18], [aPar19], [bPar20], [cPar21], [acReadVar])

Parmetros:
Parmetro
anRow
anCol

abSetGet

anItems
anWidth

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato {|u|
if( Pcount( )>0, <var>:= u, <var> ) } que o controle utiliza
para atualizar a varivel <var>. <var> deve ser tipo
caracter. Se a lista for seqencial, o controle atualizar
<var> com o contedo do item selecionado, se a lista for
indexada, <var> ser atualizada com o valor do ndice do
item selecionado.
Array, opcional. Lista de items, caracteres, a serem exibidos.
Pode ter os seguintes formatos: a) Seqencial, exemplo:
{item1,item2,...,itemN} ou b) Indexada, exemplo:
{a=item1,b=item2, ..., n=itemN}.
Numrico, opcional. Largura do controle em pixels.
- 79 ADVPL Avanado

Numrico, opcional. Altura do controle em pixels.


Objeto, opcional. Janela ou controle onde o controle ser
criado.
Reservado.
Bloco de cdigo, opcional. Executado quando o controle
modifica o item selecionado.
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Numrico, opcional. Cor de fundo do controle.
Numrico, opcional. Cor do texto do controle.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada para exibir o contedo do
controle.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Reservado.
Reservado.
Reservado.
Reservado.
Caractere, opcional. Nome da varivel que o controle dever
manipular, dever ser a mesma varivel informada no
parmetro abSetGet, e ser o retorno da funo ReadVar( ).

anHeight
aoWnd
nPar8
abChange
abValid
anClrBack
anClrText
alPixel
aoFont
cPar15
lPar16
abWhen
lPar18
aPar19
bPar20
cPar21
acReadVar

Mtodos auxiliares:
Select
 Descrio: Muda o item selecionado no combobox.
 Sintaxe: Select( [anItem] )
 Parmetros:
anItem

Numrico, opcional. Posio do item a ser selecionado.

 Retorno:
Nenhum

- 80 ADVPL Avanado

Aparncia:

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

- 81 ADVPL Avanado

TFOLDER()


Descrio: Classe de objetos visuais do tipo controle - Folder.

Propriedades:
Array, Titulo dos folders
Array, Nome dos dilogos
Numrico, Folder selecionado
Bloco de cdigo, Executado na seleo do folder

aPrompts
aDialogs
nOption
bSetOption


Construtor: New([anTop], [anLeft], [aPrompts], [aDialogs], [aoWnd],


[anOption], [anClrFore], [anClrBack], [alPixel], [alDesign], [anWidth],
[anHeight], [acMsg], [alAllWidth])

Parmetros:
Numrico, opcional. Coordenada vertical em pixels ou
carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Array, Titulo dos folders
Array, Nome dos dilogos
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Numrico, opcional. Folder selecionado
Numrico, opcional. Cor de frente
Numrico, opcional. Cor de fundo
Lgico, opcional. Utiliza coordenadas em pixel
Lgico, opcional. NO USADO
Numrico, opcional. Largura em pixels.
Numrico, opcional. Altura em pixels.
Caractere, Mensagem de Hint
Lgico, opcional. NO USADO

anTop
anLeft
aPrompts
aDialogs
aoWnd
anOption
anClrFore
anClrBack
alPixel
alDesign
anWidth
anHeight
acMsg
alAllWidth


Mtodos auxiliares:
SetOption
 Descrio: Seleciona folder desejado
 Sintaxe: SetOption( nOption )
 Parmetros:
nOption

Numrico. Folder a ser selecionado

 Retorno:
Nenhum

- 82 ADVPL Avanado

AddItem
 Descrio: Insere um folder
 Sintaxe: AddItem ( cItem, lVisible )
 Parmetros:
cItem
lVisible

Caractere. Ttulo do Folder


Lgico. Visvel

 Retorno:
Nenhum

aEnable
 Descrio: Habilita/Desabilita um folder
 Sintaxe: aEnable( nItem, lEnable )
 Parmetros:
nItem
lEnable

Numrico. Folder para habilitar/desabilitar


Lgico. Habilita/Desabilita

 Retorno:
Nenhum


Aparncia:

- 83 ADVPL Avanado

Exemplo:
Local oFolder
Local aFolder := { 'Folder 1', 'Folder 2', 'Folder 3' }
oFolder := TFolder():New( 0, 0, aFolder, aFolder, oDlg,,,, .T., , 200,;
200 )

TGET()


Descrio: Classe de objetos visuais do tipo controle tGet, a qual cria um


controle que armazena ou altera o contedo de uma varivel atravs
de digitao. O contedo da varivel s modificado quando o
controle perde o foco de edio para outro controle.

Propriedades:

lPassword
Picture

Lgico. Se .T. o controle se comporta como entrada de


dados de senha, exibindo asteriscos * para esconder o
contedo digitado.
Caractere. Mscara de formatao do contedo a ser
exibido.

Construtor: New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth],


[anHeight], [acPict], [abValid], [anClrFore], [anClrBack], [aoFont],
[lPar12], [oPar13], [alPixel], [cPar15], [lPar16], [abWhen], [lPar18],
[lPar19],
[abChange],
[alReadOnly],
[alPassword],
[cPar23],
[acReadVar], [cPar25], [lPar26], [nPar27], [lPar28])

Parmetros:
anRow
anCol

abSetGet

aoWnd
anWidth
anHeight
acPict
abValid
anClrFore
anClrBack
aoFont

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato {|u|
if( Pcount( )>0, <var>:= u, <var> ) } que o controle utiliza
para atualizar a varivel <var>. <var> deve ser tipo
caracter, numrico ou data.
Objeto, opcional. Janela ou controle onde o controle ser
criado.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Caractere, opcional. Mscara de formatao do contedo a
ser exibido.
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Numrico, opcional. Cor de fundo do controle.
Numrico, opcional. Cor do texto do controle.
Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada para exibir o contedo do
- 84 ADVPL Avanado

lPar12
oPar13
alPixel
cPar15
lPar16
abWhen
lPar18
lPar19
abChange
alReadOnly
alPassword
cPar23
acReadVar
cPar25
lPar26
nPar27
lPar28


controle.
Reservado.
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando o controle
modifica o valor da varivel associada.
Lgico, opcional. Se .T. o controle no poder ser editado.
Lgico, opcional. Se .T. o controle exibir asteriscos * no
lugar dos caracteres exibidos pelo controle para simular
entrada de senha.
Reservado.
Caractere, opcional. Nome da varivel que o controle dever
manipular, dever ser a mesma varivel informada no
parmetro abSetGet, e ser o retorno da funo ReadVar( ).
Reservado.
Reservado.
Reservado.
Reservado.

Aparncia:

- 85 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function TesteGet()
Local oDlg, oButton, oCombo, cCombo, nGet1:=0
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE 'Meu Get'
oGet1:= TGet():New(10,10,{|u| if(PCount()>0,nGet1:=u,nGet1)}, oDlg,;
100,20,'@E 999,999.99',;
{|o|nGet1>1000.00},,,,,,.T.,,,,,,,,,,'nGet1')
// Boto para fechar a janela
oButton:=tButton():New(30,10,'fechar',oDlg,{||oDlg:End()},100,20,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
MsgStop( 'O valor '+Transform(nGet1,'@E 999,999.00') )
Return NIL
TGROUP()


Descrio: Classe de objetos visuais do tipo painel tGroup, a qual cria um


painel onde controles visuais podem ser agrupados ou classificados.
Neste painel criada uma borda com ttulo em volta dos controles
agrupados.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([anTop], [anLeft], [anBottom], [anRight],


[aoWnd], [anClrText], [anClrPane], [alPixel], [lPar10])

Parmetros:
anTop
anLeft
anBottom
anRight
acCaption
aoWnd
anClrText
anClrPane
alPixel
lPar10

[acCaption],

Numrico, opcional. Coordenada vertical superior em pixels


ou caracteres.
Numrico, opcional. Coordenada horizontal esquerda em
pixels ou caracteres.
Numrico, opcional. Coordenada vertical inferior em pixels
ou caracteres.
Numrico, opcional. Coordenada horizontal direita em pixels
ou caracteres.
Caractere, opcional. Ttulo do grupo.
Objeto, opcional. Janela ou controle onde o controle ser
criado.
Numrico, opcional. Cor do texto.
Numrico, opcional. Cor do fundo.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Reservado.

- 86 ADVPL Avanado

Aparncia:

Exemplo:

#include 'protheus.ch'
User Function Teste()
Local oDlg, oButton, oCombo, cCombo, cGet1:='Teste'
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE 'Meu test'
oGroup:= tGroup():New(10,10,130,130,'grupo de gets',oDlg,,,.T.)
@ 18,16 MSGET oGet1 VAR cGet1 SIZE 100,10 OF oGroup PIXEL
@ 38,16 MSGET oGet2 VAR cGet1 SIZE 100,10 OF oGroup PIXEL
ACTIVATE MSDIALOG oDlg CENTERED

- 87 ADVPL Avanado

THBUTTON()


Descrio: Classe de objetos visuais do tipo boto com hiperlink.

Propriedades:
bAction

Bloco de cdigo. Executado quando o boto pressionado.

Construtor: New([anRow], [anCol], [acCaption],


[anWidth], [anHeight], [aoFont], [abWhen])

Parmetros:
Parmetro
anRow
anCol
acCaption
aoWnd
abAction
anWidth
anHeight
aoFont

abWhen

[aoWnd],

[abAction],

Tipo / Descrio
Numrico, opcional. Coordenada vertical em pixels ou
carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Caractere, opcional. Titulo do boto.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Numrico, opcional. Largura do boto em pixels.
Numrico, opcional. Altura do boto em pixels.
Objeto, opcional. Objeto tipo tFont com propriedades da
fonte utilizada para o ttulo do boto.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

Mtodos auxiliares:
Create
 Descrio: Mtodo construtor opcional da classe.
 Sintaxe: Create(aoWnd)
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde a paleta dever


ser criada.

 Retorno:
Objeto

Objeto do tipo THButton com os atributos definidos com


contedo padro.

- 88 ADVPL Avanado

Aparncia:

Exemplo:
#include protheus.ch
#include hbutton.ch
User Function MyhBtn()
Local oDlg, ohBtn
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Meu hButton
// Usando o mtodo create
ohBtn:= tHButton():Create( oDlg )
ohBtn:nTop
:= 100
ohBtn:nLeft
:= 10
ohBtn:nWidth
:= 100
ohBtn:nHeight
:= 30
ohBtn:cCaption := 'hButton'
ohBtn:blClicked := { || MsgStop( 'Cliquei' ) }
// Usando o command
@ 200,100 HBUTTON ohBtn PROMPT 'Exemplo hButton' SIZE 100,30 ACTION
MsgStop('Cliquei') OF oDlg MESSAGE 'hButton'
ACTIVATE MSDIALOG oDlg CENTERED
Return Nil

TIBROWSER()


Descrio: Classe de objetos visuais do tipo Pgina de Internet, sendo


necessrio incluir a clausula BrowserEnabled=1 no Config do
Remote.INI

Propriedades:
-

Herdadas da classe superior

Construtor: New([nRow], [nCol], [nWidth], [nHeight], [cPager], [oWnd])

Parmetros:
nRow
nCol
nWidth
nHeigth
cPage
oWnd

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres
Numrico, opcional. Largura em pixels
Numrico, opcional. Altura em pixels.
Caracter. Enredeo URL da pgina de Internet
Objeto, opcional. Janela ou controle onde a boto dever ser
criado

Aparncia:
- 89 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
// Habilitar no Remote(Config) -> BrowserEnabled=1
oTIBrowser:=
TIBrowser():New(0,0,306,134,'http://www.microsiga.com.br',oDlg )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 90 ADVPL Avanado

TLISTBOX()


Descrio: Classe de objetos visuais do tipo controle tListbox, a qual cria uma
janela com itens selecionveis e barra de rolagem. Ao selecionar um
item, uma varivel atualizada com o contedo do item selecionado.

Propriedades:
nAt
aItems

Numrico. Posio do item selecionado.


Array de items caracteres. Lista do itens selecionveis.

Construtor:
New([anRow], [anCol], [abSetGet], [aaItems], [anWidth],
[anHeigth],
[abChange],
[aoWnd],
[abValid],
[anClrFore],
[anClrBack], [alPixel], [lPar13], [abLDBLClick], [aoFont], [cPar16],
[lPar17], [abWhen], [aPar19], [bPar20], [lPar21], [lPar22],
[abRightClick] )

Parmetros:
anRow
anCol

abSetGet

aaItems
anWidth
anHeight
abChange
aoWnd
abValid
anClrFore
anClrBack
alPixel
lPar13
abLDBLClick
aoFont
cPar16
lPar17
abWhen

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato {|u|
if( Pcount( )>0, <var>:= u, <var> )} que o controle utiliza
para atualizar a varivel <var>. <var> deve ser tipo
caracter ou numrica.
Array de items caracteres, opcional. Lista de items
selecionveis.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Objeto, opcional. Janela ou controle onde o controle ser
criado.
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Numrico, opcional. Cor de fundo do controle.
Numrico, opcional. Cor do texto do controle.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Reservado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada para exibir o contedo do
controle.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
- 91 ADVPL Avanado

Reservado.
Reservado.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando acionado click
do boto direito do mouse sobre o controle.

aPar19
bPar20
lPar21
lPar22
abRightClick


Mtodos auxiliares:
Select
 Descrio: Fora a seleo de um item.
 Sintaxe: Select( [anItem] )
 Parmetros:
nItem

Numrico, opcional. Posio do item a ser selecionado.

 Retorno:
Nenhum

Add
 Descrio: Adiciona novo item.
 Sintaxe: Add( cText, nPos )
 Parmetros:
cText
nPos

Caractere, obrigatrio. Texto do item.


Numrico, obrigatrio. Se 0 ou maior que o nmero de
itens, insere o item no final da lista. Se valor entre 1 e
nmero de itens, insere o item na posio informada,
empurrando o item anterior para baixo.

 Retorno:
Nenhum

Modify
 Descrio: Modifica o texto de um item.
 Sintaxe: Modify( cText, nPos )
 Parmetros:
cText
nPos

Caractere, obrigatrio. Novo texto do item.


Numrico, obrigatrio. Posio a ser modificada deve ser
maior que 0 e menor ou igual que o nmero de itens.

 Retorno:
Nenhum

- 92 ADVPL Avanado

Del
 Descrio: Remove um item.
 Sintaxe: Del( nPos )
 Parmetros:
nPos

Numrico, obrigatrio. Posio a ser excluida, deve ser


maior que 0 e menor ou igual que o nmero de itens.

 Retorno:
Nenhum

Len
 Descrio: Retorna o nmero de itens.
 Sintaxe: Len( )
 Parmetros:
Nenhum

 Retorno:
Numrico

Nmero de itens.

Reset
 Descrio: Apaga todos os itens.
 Sintaxe: Reset( )
 Parmetros:
Nenhum

 Retorno:
Nenhum

- 93 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg, oList, nList:= 1
Local aItems:={}
Aadd(aItems,'Item 1')
Aadd(aItems,'Item 2')
Aadd(aItems,'Item 3')
Aadd(aItems,'Item 4')
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE 'Teste'
oList:= tListBox():New(10,10,{|u|if(Pcount()>0,nList:=u,nList)};
,aItems,100,100,,oDlg,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 94 ADVPL Avanado

TMENU()


Descrio: Classe de objetos visuais do tipo controle - Menu.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New ([nTop], [nLeft], [nHeight], [nWidth], [lPopUp], [cBmpName],


[oWnd],
[nClrNoSelect],
[nClrSelect],
[cArrowUpNoSel],
[cArrowUpSel], [cArrowDownNoSel], [cArrowDownSel])

Parmetros:
nTop
nLeft
nHeight
nWidth
lPopUp
cBmpName
oWnd
nClrNoSelect
nClrSelect
cArrowUpNoSel
cArrowUpSel
cArrowDownNoSel
cArrowDownSel

Numrico, opcional. Coordenada vertical em pixels.


Numrico, opcional. Coordenada horizontal em pixels.
Numrico, opcional. Altura do controle em pixels.
Numrico, opcional. Largura do controle em pixels.
Lgico. Define se o objeto ser um PoPup
Caracter opcional. Figura do Menu
Objeto, opcional. Janela ou controle onde a boto dever
ser criado
Numerico opcional. Cor quando no selecionado
Numerico opcional. Cor quando selecionado
Caracter opcional, Define a figura da seta para cima
quando no selecionado o item.
Caracter opcional, Define a figura da seta para cima
quando selecionado o item.
Caracter opcional, Define a figura da seta para baixo
quando no selecionado o item.
Caracter opcional, Define a figura da seta para baixo
quando selecionado o item.

Aparncia:

- 95 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oMenu := TMenu():New( 0,0,0,0,.F.,'',oDlg,CLR_WHITE,CLR_BLACK)
// Adiciona Item ao Menu Principal
oMenuItem1 := TMenuItem():New2( oMenu:Owner(),'Item 001','Item
001',,,)
oMenu:Add( oMenuItem1 )
// Adiciona sub-Itens
oMenuItem2 := TMenuItem():New2( oMenu:Owner(),'Sub-Item
001',,,{||Alert('TMenuItem')})
oMenuItem3 := TMenuItem():New2( oMenu:Owner(),'Sub-Item
002',,,{||Alert('TMenuItem')})
oMenuItem1:Add( oMenuItem2 )
oMenuItem1:Add( oMenuItem3 )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

TMENUBAR()


Descrio: Classe de objetos visuais do tipo controle - Barra de Menu.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([oWnd])

Parmetros:
oWnd

Objeto, opcional. Janela ou controle onde o boto dever ser


criado.

Aparncia:

- 96 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
// Monta um Menu Suspenso
TMenuBar := TMenuBar():New(oDlg)
TMenuBar:nClrPane := RGB(183,208,248) // Cor de fundo do Menu
oTMenu1 := TMenu():New(0,0,0,0,.T.,,oDlg)
oTMenu2 := TMenu():New(0,0,0,0,.T.,,oDlg)
TMenuBar:AddItem('Arquivo' , oTMenu1, .T.)
TMenuBar:AddItem('Relatorio', oTMenu2, .T.)
// Cria Itens do Menu
oTMenuItem := TMenuItem():New(oDlg,'TMenuItem 01',,,,;
{||Alert('TMenuItem 01')},,'AVGLBPAR1',,,,,,,.T.)
oTMenu1:Add(oTMenuItem)
oTMenu2:Add(oTMenuItem)
oTMenuItem := TMenuItem():New(oDlg,'TMenuItem 02',,,,;
{||Alert('TMenuItem 02')},,,,,,,,,.T.)
oTMenu1:Add(oTMenuItem)
oTMenu2:Add(oTMenuItem)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
TMETER()


Descrio: Classe de objetos visuais do tipo controle tMeter, a qual exibe uma
rgua (gauge) de processamento, descrevendo o andamento de um
processo atravs da exibio de uma barra horizontal.

Propriedades:
nTotal
lPercentage
nClrBar

Numrico. Nmero total de passos at o preenchimento da


rgua de processo.
Lgico. Se .T. considera o passo de movimentao em
porcentagem.
Numrico. Cor da barra de andamento.

Construtor: New([anRow], [anCol], [abSetGet], [anTotal], [aoWnd], [anWidth],


[anHeight], [lPar8], [alPixel], [oPar10], [cPar11], [alNoPerc],
[anClrPane], [nPar14], [anClrBar], [nPar16], [lPar17])

Parmetros:
anRow
anCol

abSetGet

anTotal

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato {|u|
if( Pcount( )>0, <var>:= u, <var> ) } que o controle utiliza
para atualizar a varivel <var>. <var> deve ser tipo
numrico.
Numrico, opcional. Numero total de passos at o
preenchimento da rgua de processo.
- 97 ADVPL Avanado

Objeto, opcional. Janela ou controle onde o controle sera


criado.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Reservado.
Reservado.
Lgico, opcional. Se .T. (padro) no considera os passos de
atualizao em porcentagem.
Numrico, opcional. Cor de fundo do controle.
Reservado.
Numrico, opcional. Cor da barra de andamento.
Reservado.
Reservado.

aoWnd
anWidth
anHeight
lPar8
alPixel
oPar10
cPar11
alNoPerc
anClrPane
nPar14
anClrBar
nPar16
lPar17


Mtodos auxiliares:
Set
 Descrio: Atualiza a posio da rgua de processamento.
 Sintaxe: Set( [nVal] )
 Parmetros:
nVal

Numrico, opcional. Novo valor da posio da rgua de


processamento.

 Retorno:
Nenhum

Aparncia:

- 98 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
STATIC lRunning:=.F., lStop:=.F.
User Function Teste()
Local oDlg, oMeter, nMeter:=0, oBtn1, oBtn2
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 TITLE 'Teste' Pixel
oMeter:= tMeter():New(10,10,{|u|if(Pcount()>0,nMeter:=u,nMeter)};
,100,oDlg,100,16,,.T.) // cria a rgua
// boto para ativar andamento da rgua
@ 30,10 BUTTON oBtn1 PROMPT 'Run ' OF oDlg PIXEL ACTION RunMeter(oMeter)
@ 50,10 BUTTON oBtn2 PROMPT 'Stop' OF oDlg PIXEL ACTION lStop:=.T.
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
STATIC Function RunMeter(oMeter)
If lRunning
Return
Endif
lRunning:= .T.
oMeter:Set(0)
// inicia a rgua
While .T. .and. !lStop
Sleep(1000) // pra 1 segundo
ProcessMessages() // atualiza a pintura da janela, processa mensagens do
windows
nCurrent:= Eval(oMeter:bSetGet) // pega valor corrente da rgua
nCurrent+=10 // atualiza rgua
oMeter:Set(nCurrent)
if nCurrent==oMeter:nTotal
Return
endif
Enddo
lRunning:= .F.
lStop:= .F.
Return

- 99 ADVPL Avanado

TMSGRAPHIC()


Descrio: Classe de objetos visuais do tipo controle - Grfico.

Propriedades:
l3D
lAxisVisib

Lgico, opcional Grfico em 3D


Lgico, opcional Mostra eixos do grfico

Construtor:
New([anRow],
[anCol],
[aoWnd],
[anClrBack], [anWidth], [anHeight])

Parmetros:
anRow
anCol
aoWnd
aoFont
anClrText
anClrBack
anWidth
anHeight

[aoFont],

[anClrText],

Numrico, opcional. Coordenada vertical em pixels.


Numrico, opcional. Coordenada horizontal em pixels.
Objeto, opcional. Janela ou controle onde a imagem dever
ser criada.
Objeto, opcional. Fonte utilizada no grfico.
Caractere, Nome do resource.
Caractere, Nome do arquivo.
Lgico, opcional. Exibe borda
Objeto, opcional. Janela ou controle onde a imagem dever
ser criada.

Mtodos auxiliares:
CreateSerie
 Descrio: Mtodo para criao de uma serie para o grfico.
 Sintaxe:
CreateSerie(
[nSerieType],
[cLegend],
[nDecimals],
[lShowValues] )
 Parmetros:

nSerieType

cLegend
nDecimals
lShowValues

Numrico. Indica o tipo do grfico


GRP_LINE
1
GRP_AREA
2
GRP_POINT
3
GRP_BAR
4
GRP_PIE
10
Caractere, opcional. Legenda da srie.
Numrico, opcional. Numero de casas decimais dos
valores.
Lgico, opcional. Mostra valores

 Retorno:
Numrico

Numero da srie criada.

- 100 ADVPL Avanado

Add
 Descrio: Mtodo para adicionar um item ao grfico.
 Sintaxe: Add(nSerie, nVal, cLegend, nColor )
 Parmetros:
nSerie
nVal
cLegend
nColor

Numrico. Serie a ser inserido o item.


Numrico. Valor do item.
Caractere. Legenda do item.
Numrico, Cor do item.

 Retorno:
Nenhum

SetGradiente
 Descrio: Mtodo para setar o fundo do grfico com uma cor gradiente
em determinada direo.
 Sintaxe: SetGradient(nDirection, StartColor, EndColor )
 Parmetros:

nDirection

StartColor
EndColor

Numrico. Indica direo do gradiente.


GDTOPBOTTOM 1
GDBOTTOMTOP 2
GDLEFTRIGHT 3
GDRIGHTLEFT 4
Numrico. Cor inicial.
Numrico. Cor final.

 Retorno:
Nenhum

SetTitle
 Descrio: Define o titulo do grfico.
 Sintaxe: SetTitle(cTitle, cTitle2, Color, Aligment, lFoot)
 Parmetros:
cTitle
cTitle2
Color
Aligment
lFoot

Caractere. Primeiro titulo.


Caractere. Segundo titulo.
Numrico. Cor do titulo.
Numrico. Alinhamento do titulo.
A_LEFTJUST 1
A_RIGHTJUS 2
A_CENTER 3
Lgico. Indica titulo no rodap do grfico.

 Retorno:
Nenhum

- 101 ADVPL Avanado

SetLegenProp
 Descrio: Mtodo para setar propriedades da legenda.
 Sintaxe: SetLegenProp(Align, Color, Style, Visible )
 Parmetros:

Align

Color

Style

Visible

Numerico. Alinhamento da legenda.


GRP_SCRTOP 1
GRP_SCRLEFT 2
GRP_SCRBOTTOM 3
GRP_SCRRIGHT 4
Numrico. Cor da legenda.
Numrico. Estilo da legenda.
GRP_AUTO 1
GRP_SERIES 2
GRP_VALUES 3
GRPLASTVAL 4
Lgico. Indica de o titulo ser visvel.

 Retorno:
Nenhum

SetMargins
 Descrio: Mtodo para setar as margens superior, inferior e laterais do
grfico.
 Sintaxe: SetMargins(nTop, nLeft, nBottom, nRight )
 Parmetros:
nTop
nLeft
nBottom
nRight

Numrico.
Numrico.
Numrico.
Numrico.

Posio
Posio
Posio
Posio

em
em
em
em

relao
relao
relao
relao

ao topo do grfico.
a esquerda.
ao rodap.
a direita.

 Retorno:
Nenhum

SetRangeY
 Descrio: Define a escala dos valores do eixo Y
 Sintaxe: SetRangeY (min, max, delta).
 Parmetros:
Min
Max
delta

valor inicial
valor final
intervalo entre os valores [ opcional, calculado
automaticamente ]

 Retorno:
Nenhum

- 102 ADVPL Avanado

SaveToBMP
 Descrio: Mtodo para salvar o grfico atual em um bitmap no
server(Obsoleto, ver SaveToImage).
 Sintaxe: SaveToBMP(BmpName, PathToWrite )
 Parmetros:
BmpName
PathToWrite

Caractere, Nome do da figura a ser salva.


Caractere. Path no Server onde ser salva a figura.

 Retorno:
Lgico

Indica se a imagem foi salva corretamente.

SaveToImage
 Descrio: Mtodo para salvar o grfico atual em um formato de prdeterminado no server.
 Sintaxe: SaveToImage(BmpName, PathToWrite, TypeImage)
 Parmetros:
BmpName
PathToWrite

Caractere, Nome do da figura a ser salva.


Caractere. Path no Server onde ser salva a figura.
Caractere. Tipo da Figura (Default 'JPEG')
Tipos suportados: JPEG, PNG, BMP

TypeImage
 Retorno:
Lgico

Indica se a imagem foi salva corretamente.

DelSerie
 Descrio: Mtodo para deletar uma srie do grafico.
 Sintaxe: DelSerie ( nSerie )
 Parmetros:
nSerie

Numrico. Serie a ser deletada.

 Retorno:
Lgico

Indica se a sria foi removida do grfico

ZoomIn
 Descrio: Mtodo para efetuar zoom interno ( + ).
 Sintaxe: ZoomIn()
 Parmetros:
Nenhum

 Retorno:
Nenhum

- 103 ADVPL Avanado

ZoomOut
 Descrio: Mtodo para efetuar zoom externo ( - ).
 Sintaxe: ZoomOut()
 Parmetros:
Nenhum

 Retorno:
Nenhum


Aparncia:

- 104 ADVPL Avanado

Exemplo:
#include 'MSGRAPHI.CH'
User Function tMsGraphicTst()
DEFINE MSDIALOG oDlg TITLE '' FROM 0,0 TO 250,330 PIXEL
@ 001, 001 MSGRAPHIC oGraphic SIZE 120,120 OF oDlg
oGraphic:SetTitle('Titulo do Grafico', DTOC(Date()), CLR_BLACK,
A_LEFTJUST, GRP_TITLE )
oGraphic:SetMargins(2,6,6,6)
oGraphic:SetGradient(GDBOTTOMTOP, CLR_HGRAY, CLR_WHITE)
oGraphic:SetLegenProp(GRP_SCRRIGHT, CLR_HGRAY, GRP_AUTO,.T.)
nSerie
:=
oGraphic:CreateSerie( 10 )
oGraphic:l3D := .T. // Grafico em 3D
oGraphic:lAxisVisib
:= .T.
// Mostra os eixos
// Itens do Grafico
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,
oGraphic:Add(nSerie,

200,
180,
210,
110,
100,
080,
110,

'Item01',
'Item02',
'Item03',
'Item04',
'Item05',
'Item06',
'Item07',

CLR_BLUE
CLR_RED
CLR_BLUE
CLR_BLUE
CLR_BLUE
CLR_BLUE
CLR_BLUE

@ 001, 124 BUTTON 'Salva Grafico' SIZE


oGraphic:SaveToBMP('Exemplo.bmp','\web\')
@ 020, 124 BUTTON 'Zoom IN'
SIZE
oGraphic:ZoomIn()
@ 040, 124 BUTTON 'Zoom OUT'
SIZE
oGraphic:ZoomOut()
@ 060, 124 BUTTON 'Deleta Serie' SIZE
oGraphic:DelSerie(nSerie)
ACTIVATE MSDIALOG oDlg CENTERED
Return

- 105 ADVPL Avanado

)
)
)
)
)
)
)

40,14 OF oDlg PIXEL ACTION


40,14 OF oDlg PIXEL ACTION
40,14 OF oDlg PIXEL ACTION
40,14 OF oDlg PIXEL ACTION

TMSGBAR()


Descrio: Classe de objetos visuais do tipo controle - Rodap.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New ([oWnd], [cPrompt,], [lCentered], [lClock], [lDate], [lKbd],


[nClrFore], [nClrBack], [oFont], [lInset], [imageName])

Parmetros:
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Caracter. Descrio na Barra
Logico. Define centralizao do texto
Nao utilizado
Nao utilizado
Nao utilizado
Numerico, opcional. Define cor da fonte da barra
Numerico, opcional. Define cor do fundo da barra
Objeto, opcional. Objeto tipo tFont com propriedades da
fonte utilizada para o ttulo do boto.
Nao utilizado
Caracter, opcional. Insere figura lateral esquerda

oWnd
cPrompt
lCentered
lClock
lDate
lKbd
nClrFore
nClrBack
oFont
lInset
imageName


Mtodos auxiliares:
AddItem
 Descrio: Mtodo insere um subitem no rodap
 Sintaxe: AddItem( oTMsgItem )
 Parmetros:
Objeto do tipo TMsgItem que ser inserido como subitem
do rodap.

oTMsgItem
 Retorno:
Nenhum

- 106 ADVPL Avanado

SetMsg
 Descrio: Define a descrio da barra de rodap
 Sintaxe: SetMsg(cTexto )
 Parmetros:
cTexto

Texto a ser inserido na barra

 Retorno:
Nenhum


Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oTMsgBar := TMsgBar():New(oDlg, 'MP10 | Totvs/Software',
.F.,.F.,.F.,.F., RGB(116,116,116),,,.F.)
oTMsgItem1 := TMsgItem():New( oTMsgBar,'oTMsgItem1', 204,,,, .T.,
{||})
oTMsgItem2 := TMsgItem():New( oTMsgBar,'oTMsgItem2', 040,,,, .T.,
{||Alert('Item da Barra Acionado')} )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 107 ADVPL Avanado

TMSGITEM()


Descrio: Classe de objetos visuais do tipo controle utilizado para adicionar


mensagens em outros objetos, como barras e menus.

Propriedades:
-

Herdadas das classes superiores

Construtor: New( <oMsgBar>, <cMsg>, <nSize>, <oFont>, <nClrFore>,


<nClrBack>, lEnable , [<{bAction}>], cImagem )

Parmetros:
oMsgBar
cMsg
nSize
oFont
nClrFore
nClrBack
lEnable
bAction
cImagem

Objeto do tipo barra ou menu no qual ser adicionado o item


de mensagem.
Mensagem que ser exibida pelo objeto
Tamanho da fonte do texto
Fonte do texto
Cor da fonte do texto
Cor do fundo do objeto
Indica se o objeto est habilitado.
Bloco de cdigo executado quando o objeto ativado
Imagem a ser vinculada no objeto.

Aparncia:

- 108 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oTMsgBar := TMsgBar():New(oDlg, 'MP10 | Totvs/Software',
.F.,.F.,.F.,.F., RGB(116,116,116),,,.F.)
oTMsgItem1 := TMsgItem():New( oTMsgBar,'oTMsgItem1', 204,,,, .T.,
{||})
oTMsgItem2 := TMsgItem():New( oTMsgBar,'oTMsgItem2', 040,,,, .T.,
{||Alert('Item da Barra Acionado')} )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
.

TMULTIBTN()


Descrio: Classe de objetos visuais do tipo controle - Mltiplos botes.

Propriedades:
bAction

Bloco de cdigo. Executado ao precionar o boto esquerdo


do mouse.

Construtor: New([nRow], [nCol], [cTitle], [oWnd], [bAction],


[nHeight], [imgName], [ori], [cMsg], [btnPerLine])

Parmetros:
nRow
nCol
oWnd
bAction
nWidth
nHeigth
imgName
ori
cMsg
btnPerLine

[nWidth],

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for pressionado.
Numrico, opcional. Largura em pixels
Numrico, opcional. Altura em pixels.
Caracter. Imagem a ser inserida ao lado esquerdo do
componente
Numerico, opcional. Orientao dos botes.
Caracter, Opicional. Descrio do tipo tooltip(hint) do item
Numerico, opcional. Quantidade de botes por linha

- 109 ADVPL Avanado

Mtodos auxiliares:
LoadImage
 Descrio: Muda a figura a esquerda do componente
 Sintaxe: LoadImage(cImagem)
 Parmetros:
cImagem

Nome da imagem que ser carregada pelo objeto

 Retorno:
Nenhum

AddButton
 Descrio: Insere um boto
 Sintaxe: AddButton(cTexto)
 Parmetros:
cTexto

Texto para exibio no boto inserido.

 Retorno:
Nenhum

SetTitle
 Descrio: Muda o titulo e o numero de botes por linha
 Sintaxe: SetTitle(cTexto, nBotoes)
 Parmetros:
cTexto
nBotoes

Texto que ser atribudo aos botes


Nmero de botes por linha

 Retorno:
Nenhum

SetFonts
 Descrio: Muda a font do titulo e dos botes
 Sintaxe: SetTitle(cFontTit, nSizeTit, nFontBut, nSizeBut)
 Parmetros:
cFontTit
nSizeTit
nFontBut
nSizeBut

Nome da fonte que ser atribuda ao ttulo


Tamanho da fonte do ttulo
Nome da fonte que ser atribuda aos botes
Tamanho da fonte dos botes

 Retorno:
Nenhum

- 110 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
otMultiBtn := tMultiBtn():New( 01,01,'cTitle1',oDlg,;
{|x|Alert(Str(x)) },200,150,'afastamento',0,'cTitle',3
)
otMultiBtn:SetFonts('Tahoma',16,'Tahoma',10)
otMultiBtn:AddButton('btn01')
otMultiBtn:AddButton('btn02')
otMultiBtn:AddButton('btn04')
otMultiBtn:AddButton('btn05')
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
.

- 111 ADVPL Avanado

TMULTIGET()


Descrio: Classe de objetos visuais do tipo controle - edio de texto de


mltiplas linhas.

Propriedades:
lWordWrap

Lgico. Se .T., faz quebra automtica de linhas.

Construtor: New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth],


[anHeight], [aoFont], [alHScroll], [anClrFore], [anClrBack], [oPar11],
[alPixel],
[cPar13],
[lPar14],
[abWhen],
[lPar16],
[lPar17],
[alReadOnly],
[abValid],
[bPar20],
[lPar21],
[alNoBorder],
[alNoVScroll])

Parmetros:
Parmetro
anRow
anCol

abSetGet

aoWnd
anWidth
anHeight
aoFont
alHScroll
anClrFore
anClrBack
oPar11
alPixel
cPar13
lPar14
abWhen
lPar16
lPar17
alReadOnly
abValid
bPar20
lPar21

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Bloco de cdigo, opcional. Bloco de cdigo no formato {|u|
if( Pcount( )>0, <var>:= u, <var> ) } que o controle utiliza
para atualizar a varivel <var>. <var> deve ser tipo
caracter.
Objeto, opcional. Janela ou controle onde o controle ser
criado.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada para exibir o contedo do
controle.
Lgico, opcional. Se .T., habilita barra de rolagem
horizontal.
Numrico, opcional. Cor de fundo do controle.
Numrico, opcional. Cor do texto do controle.
Reservado.
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Reservado.
Reservado.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
Reservado.
Reservado.
Lgico, opcional. Se .T. o controle so permitira leitura.
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Reservado.
Reservado.
- 112 ADVPL Avanado

alNoBorder
alNoVScroll


Lgico, opcional. Se .T. cria controle sem borda.


Lgico, opcional. Se .T., habilita barra de rolagem vertical.

Mtodos auxiliares:
EnableVScroll
 Descrio: Habilita a barra de rolagem vertical.
 Sintaxe: EnableVScroll( lEnable )
 Parmetros:
Lgico, obrigatrio. Se .T. habilita se .F. desabilita a barra
de rolagem.

lEnable
 Retorno:
Nenhum

EnableHScroll
 Descrio: Habilita a barra de rolagem horizontal.
 Sintaxe: EnableHScroll( lEnable )
 Parmetros:
Lgico, obrigatrio. Se .T. habilita se .F. desabilita a barra
de rolagem.

lEnable
 Retorno:
Nenhum

Aparncia:

- 113 ADVPL Avanado

Exemplo:
#include protheus.ch
User Function Teste()
Local oDlg, oMemo, cMemo:= space(50)
DEFINE MSDIALOG oDlg FROM 0,0 TO 400,400 PIXEL TITLE My test
oMemo:= tMultiget():New(10,10,{|u|if(Pcount()>0,cMemo:=u,cMemo)};
,oDlg,100,100,,,,,,.T.)
@ 200,10 BUTTON oBtn PROMPT Fecha OF oDlg PIXEL ACTION oDlg:End()
ACTIVATE MSDIALOG oDlg CENTERED
MsgStop(cMemo)
Return NIL

TOLECONTAINER()


Descrio: Classe de objetos visuais do tipo controle, a qual permite a criao


de um boto vinculado a um objeto OLE.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([nRow], [nCol], [nWidth], [nHeight], [oWnd], [lAutoActivate],


[cFileName])

Parmetros:
nRow
nCol
nWidth
nHeight
oWnd
lAutoActivate
cFileName

Numrico, opcional.
carateres.
Numrico, opcional.
caracteres.
Numrico, opcional.
Numrico, opcional.

Coordenada vertical em pixels ou


Coordenada horizontal em pixels ou
Largura do boto em pixels
Altura do boto em pixels.

Objeto, opcional. Janela ou controle onde o boto dever ser


criado.
Nao utilizado
Caracter. Endereo do arquivo Ole a ser aberto

- 114 ADVPL Avanado

Mtodos auxiliares:
OpenFromFile
 Descrio: Abre arquivo do tipo OLE.
 Sintaxe: New([cFileName, [lAsIcon], [allowInPlace])
 Parmetros:
cFileName
lAsIcon
allowInPlace

Caracter. Endereo do arquivo Ole a ser aberto


Logico. Define objeto Ole como Icone
Logico opcional. Permite abertura de arquivo local

 Retorno:
Nenhum

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
// TOleContainer
oTOleContainer := TOleContainer():New(
05,05,306,134,oDlg,.T.,'C:\Lixo\TesteRemote.doc' )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 115 ADVPL Avanado

TPAGEVIEW()


Descrio: Classe de objetos visuais do tipo controle, que permite a


visualizao de arquivos no formato gerado pelo spool de impresso
do Protheus.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([nCol], [nRow], [nWidth], [nHeight], [oPrinter], [oWnd],


[nPageWidth], [nPageHeight])

Parmetros:
Numrico, opcional.
carateres.
Numrico, opcional.
caracteres
Numrico, opcional.
Numrico, opcional.

nCol
nRow
nWidth
nHeigth
oPrinter

Coordenada horizontal em pixels ou


Largura em pixels
Altura em pixels.

Objeto do tipo TMsPrinter()


Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Numrico, opcional. Largura em pixels da pagina
Numrico, opcional. Altura em pixels da pagina

oWnd
nPageWidth
nPageHeight


Coordenada vertical em pixels ou

Mtodos auxiliares:
PageSize
 Descrio: Define o tamanho da pagina.
 Sintaxe: AddItem(nLargura, nAltura)
 Parmetros:
nLargura
nAltura

Lagura da pgina
Altura da pgina

 Retorno:
Nenhum

PrintPage
 Descrio: Imprime uma determinada pgina.
 Sintaxe: PrintPage(nNrPagina)
 Parmetros:
nNrPagina

Pgina que ser impressa

 Retorno:
Nenhum

- 116 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
// TPageView
__RelDir := WSPLRelDir()
oPrinter := TMsPrinter():New()
oPrinter:SetFile(__RELDIR + 'matr020.prt',.F.)
oTPageView := TPageView():New(
0,0,500,300,oPrinter,oTFolder2:aDialogs[07],550,350 )
oTPageView:Reset(400,400)
oTPageView:PrintPage(1)
oTPageView:Show()
oTPageView:nZoom := 150
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 117 ADVPL Avanado

TPANEL()


Descrio: Classe de objetos visuais do tipo controle tPanel, a qual permite


criar um painel esttico, onde podem ser criados outros controles
com o objetivo de organizar ou agrupar componentes visuais.

Propriedades:
-

Herdadas das classes superiores

Construtor: New([anRow], [anCol], [acText], [aoWnd], [aoFont], [alCentered],


[lPar6], [anClrText], [anClrBack], [anWidth], [anHeight], [alLowered],
[alRaised])

Parmetros:
anRow
anCol
acText
aoWnd
alCentered
lPar6
anClrText
anClrBack
anWidth
anHeight
alLowered
alRaised

Numrico, opcional. Coordenada vertical em pixels.


Numrico, opcional. Coordenada horizontal em pixels.
Caractere, opcional. Texto a ser exibido ao fundo.
Objeto, opcional. Janela ou controle onde ser criado o
objeto.
Lgico, opcional. Se .T. exibe o texto de ttulo ao centro do
controle.
Reservado.
Numrico, opcional. Cor do texto do controle.
Numrico, opcional. Cor do fundo do controle.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Lgico, opcional. Se .T. exibe o painel rebaixado em relao
ao controle de fundo.
Lgico, opcional. Se .T. exibe a borda do controle rebaixada
em relao ao controle de fundo.

Aparncia:

- 118 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg, oButton, oCombo, cCombo, cGet1:='Teste'
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE 'Meu test'
oPanel:= tPanel():New(10,10,,oDlg,,,,,CLR_BLUE,100,100) // cria o
painel
@ 10,10 BUTTON oBtn1 PROMPT 'hide' OF oPanel ACTION oPanel:Hide() // cria
boto sobre o painel
@ 200,10 BUTTON oBtn2 PROMPT 'show' OF oDlg ACTION oPanel:Show() // cria
boto fora o painel
ACTIVATE MSDIALOG oDlg CENTERED
Return

TRADMENU()


Descrio: Classe de objetos visuais do tipo controle TRadMenu, a qual


permite criar um controle visual no formato Radio Button.

Propriedades:
bChange
bSetGet
bWhen
bValid

Bloco de cdigo disparado na mudana de item selecionado


Bloco de cdigo disparado na mudana de item selecionado,
responsavel pela mudana de valor da variavel numerica
que indica o item selecionado.
Bloco de cdigo que permite ou no a alterao do objeto
Bloco de cdigo executado na saida do objeto.

Construtor: New([nRow], [nCol], [aItems], [bSetGet], [oDlg], [aHelpIds],


[bChange], [nClrText], [nClrPane], [cMsg], [lUpdate], [bWhen],
[nWidth], [nHeight], [bValid], [lDesign], [l3d], [lPixel])

Parmetros:

nRow
nCol
aItems
bSetGet
oDlg
aHelpIds
bChange
nClrText
nClrPane
cMsg
lUpdate
bWhen

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Vetor, elementos do Radio
Code-block, Responsvel pela setagem de valor
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
No utilizado
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o

- 119 ADVPL Avanado

controle deve permanecer habilitado ou .F. se no.


Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
No utilizado
No utilizado
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.

nWidth
nHeight
bValid
lDesign
l3d
lPixel

Mtodos auxiliares:
SetOption
 Descrio: Seleciona um item.
 Sintaxe: SetOption(nItem)
 Parmetros:
Item que ser selecionado

nItem
 Retorno:
Nenhum

EnableItem
 Descrio: Habilita/Desabilita um Item
 Sintaxe: EnableItem(nItem, lStatus)
 Parmetros:
Item que ser modificado
Status que ser atribudo ( .T. Enable , .F. Disable)

nItem
lStatus
 Retorno:
Nenhum

Enable
 Descrio: Habilita um item.
 Sintaxe: Enable(nItem)
 Parmetros:
Item que ser habilitado

nItem
 Retorno:
Nenhum

- 120 ADVPL Avanado

Disable
 Descrio: Desabilita um item
 Sintaxe: Disable(nItem)
 Parmetros:
Item que ser desabilitado

nItem
 Retorno:
Nenhum


Aparncia:

- 121 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
user function TRadMenu()
DEFINE MSDIALOG oDlg FROM 0,0 TO 270,400 PIXEL TITLE 'Exemplo da
TCBrowse'
// Variavel numerica que guarda o item selecionado do Radio
nRadio := 1
// Cria o Objeto
oRadio := TRadMenu():New
(01,01,{'Item01','Item02','Item03','Item04','Item05'},;
,oDlg,,,,,,,,200,200,,,,.T.)
// Seta Eventos
oRadio:bchange
:= {|| Alert('bChange') }
oRadio:bSetGet
:= {|u|Iif (PCount()==0,nRadio,nRadio:=u)}
oRadio:bWhen
:= {|| .T. }
oRadio:bValid
:= {|| Alert('bValid') }
// Principais comandos
oBtn := TButton():New( 060, 001, 'Retorna item selecionado',;
oDlg,{|| Alert(nRadio)
}, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 070, 001, 'SetOption(2) (Seta um
item)',;
oDlg,{|| oRadio:SetOption(2)
}, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 080, 001, 'EnableItem(2,.T.) (Habilita
item)',;
oDlg,{|| oRadio:EnableItem(2,.T.) }, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 090, 001, 'EnableItem(2,.F.)
(Desabilita item)',;
oDlg,{|| oRadio:EnableItem(2,.F.) }, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 100, 001, 'Enable(3) (Habilita
item)',;
oDlg,{|| oRadio:Enable(3)
}, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
oBtn := TButton():New( 110, 001, 'Disable(3) (Desabilita
item)',;
oDlg,{|| oRadio:Disable(3)
}, 120,
010,,,.F.,.T.,.F.,,.F.,,,.F. )
ACTIVATE MSDIALOG oDlg CENTERED
Return

- 122 ADVPL Avanado

TSBROWSE()


Descrio: Classe de objetos visuais do tipo controle TSBrowse, a qual


permite criar um controle visual do tipo Grid.

Propriedades:
Herdadas da classe superior
Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

+
nAt
nLen


Construtor: New([nRow], [nCol], [nWidth], [nHeight], [oWnd], [bChange],


[nHWidth], [oFont], [nLines])

Parmetros:
nRow
nCol
nWidth
nHeight

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Bloco de cdigo, na mudana de linha
No utilizado
Objeto, opcional. Fonte
Nmerico. Nr de linhas por clula

oWnd
bChange
nHWidth
oFont
nLines


Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil

- 123 ADVPL Avanado

GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:
Nil
RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil

LEditCell
 Descrio: Edita o valor de uma coluna.
 Sintaxe: lEditCell( aList, oList, cPicture, nCol )
 Parmetros:
aList
oList
cPicture
nCol

Vetor da Browse onde esto os valores da mesma


Objeto, Browse a ser editado
Caracter, picture necessria para edio do campo
Numrico, coluna a ser editada.

 Retorno:
Nil

- 124 ADVPL Avanado

Aparncia:

- 125 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 302,402 PIXEL TITLE 'Exemplo'
aBrowse
001'},;

:= {{'CLIENTE 001','RUA CLIENTE 001','BAIRRO CLIENTE


{'CLIENTE 001','RUA CLIENTE 001','BAIRRO CLIENTE

001'},;
{'CLIENTE 001','RUA CLIENTE 001','BAIRRO CLIENTE 001'}
}
oBrowse := TSBrowse():New(01,01,245,150,oDlg,,16,,5)
nForeCor := CLR_GRAY
nBackCor := CLR_WHITE
oBrowse:AddColumn( TcColumn():New('Nome',,,{|| nForeCor },{||
nBackCor }) )
oBrowse:AddColumn( TcColumn():New('Endereo',,,{|| nForeCor },{||
nBackCor }) )
oBrowse:AddColumn( TcColumn():New('Bairro',,,{|| nForeCor },{||
nBackCor }) )
oBrowse:SetArray(aBrowse)
// Principais commandos
TButton():New(160,001,'GoUp()',oDlg,{|| oBrowse:GoUp()
},40,10,,,,.T.)
TButton():New(170,001,'GoDown()',oDlg,{|| oBrowse:GoDown()
},40,10,,,,.T.)
TButton():New(180,001,'GoTop()',oDlg,{|| oBrowse:GoTop()
},40,10,,,,.T.)
TButton():New(190,001,'GoBottom()' , oDlg,{|| oBrowse:GoBottom()
},40,10,,,,.T.)
TButton():New(160,060,'nAt (Linha selecionada)',oDlg,;
{|| Alert (oBrowse:nAt)},80,10,,,,.T.)
TButton():New(170,060,'nRowCount (Nr de linhas visiveis)',oDlg,;
{|| Alert(oBrowse:nRowCount()) },80,10,,,,.T.)
TButton():New(180,060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oBrowse:nLen) },80,10,,,,.T.)
TButton():New( 190, 060, 'lEditCell (Edita a celula)', oDlg,;
{|| lEditCell(@aBrowse,oBrowse,'@!',3)
},40,10,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL
.

- 126 ADVPL Avanado

TSAY()


Descrio: Classe de objetos visuais do tipo controle tSay, a qual exibe o


contedo de texto esttico sobre uma janela ou controle
previamente definidos.

Propriedades:

lWordWrap

lTransparent

Lgico. Se .T. quebra o texto em vrias linhas de maneira a


enquadrar o contedo na rea determinada para o controle,
sendo o padro .F.
Lgico. Se .T. a cor de fundo do controle ignorada
assumindo o contedo ou cor do controle ou janela ao
fundo, sendo o padro .T.

Construtor: New([anRow], [anCol], [abText], [aoWnd], [acPicture], [aoFont],


[lPar7], [lPar8], [lPar9], [alPixels], [anClrText], [anClrBack],
[anWidth], [anHeight], [lPar15], [lPar16], [lPar17], [lPar18], [lPar19])

Parmetros:
anRow
anCol
abText
aoWnd
acPicture
aoFont
lPar7
lPar8
lPar9
alPixels
anClrText
anClrBack
anWidth
anHeight
lPar15
lPar16
lPar17
lPar18
lPar19

Numrico, opcional. Coordenada vertical em pixels ou


caracteres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Codeblock, opcional. Quando executado deve retornar uma
cadeia de caracteres a ser exibida.
Objeto, opcional. Janela ou dilogo onde o controle ser
criado.
Caractere, opcional. Picture de formatao do contedo a
ser exibido.
Objeto, opcional. Objeto tipo tFont para configurao do tipo
de fonte que ser utilizado para exibir o contedo.
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. considera coordenadas passadas em
pixels se .F., padro, considera as coordenadas passadas em
caracteres.
Numrico, opcional. Cor do contedo do controle.
Numrico, opcional. Cor do fundo do controle.
Numrico, opcional. Largura do controle em pixels.
Numrico, opcional. Altura do controle em pixels.
Reservado.
Reservado.
Reservado.
Reservado.
Reservado.

- 127 ADVPL Avanado

Aparncia:

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg, oButton, oCombo, cCombo, cGet1:='Teste'
DEFINE MSDIALOG oDlg FROM 0,0 TO 300,300 PIXEL TITLE 'Meu test'
oSay:= tSay():New(01,01,{||'para exibir'},oDlg,,,,;
,,.T.,CLR_RED,CLR_WHITE,100,20)
ACTIVATE MSDIALOG oDlg CENTERED
Return

- 128 ADVPL Avanado

TSCROLLBOX()


Descrio: Classe de objetos visuais do tipo controle tScrollbox, a qual


permite criar um painel com scroll deslizantes nas laterais
(horizontais e verticais) do controle.

Propriedades:
-

Herdadas das classes superiores

Construtor: New([aoWnd],
[anTop], [anLeft],
[alVertical], [alHorizontal], [alBorder])

Parmetros:
aoWnd
anTop
anLeft
anHeight
anWidth
alVertical
alHorizontal
alBorder

[anHeight],

[anWidth],

Objeto, opcional. Janela ou controle onde o controle ser


criado.
Numrico, opcional. Coordenada vertical em pixels.
Numrico, opcional. Coordenada horizontal em pixels.
Numrico, opcional. Altura do controle em pixels.
Numrico, opcional. Largura do controle em pixels.
Lgico, opcional. Se .T. exibe a barra de scroll vertical.
Lgico, opcional. Se .T. exibe a barra de scroll horizontal.
Lgico, opcional. Se .T. exibe a borda do controle.

Aparncia:

- 129 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg, oScr, oGet1, oGet2, oGet3
Local cGet1, cGet2, cGet3
cGet1:= Space(10)
cGet2:= Space(10)
cGet3:= Space(10)
DEFINE MSDIALOG oDlg FROM 0,0 TO 220,220 PIXEL TITLE 'Meu test'
oScr:= TScrollBox():New(oDlg,10,10,100,100,.T.,.T.,.T.) // cria controles
dentro do scrollbox
@ 10,10 MSGET oGet1 VAR cGet1 SIZE 100,10 OF oScr PIXEL
@ 50,10 MSGET oGet2 VAR cGet2 SIZE 100,10 OF oScr PIXEL
@ 150,100 MSGET oGet3 VAR cGet3 SIZE 100,10 OF oScr PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
Return

TSIMPLEEDITOR()


Descrio: Classe de objetos visuais do tipo controle tSimpleEditor, a qual


permite criar um controle visual para edio de textos com recursos
simples, como o NotePad

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([anRow], [anCol], [aoWnd], [anWidth], [anHeight],[ acText],


[alReadOnly])

Parmetros:
anRow
anCol
aoWnd
anWidth
anHeight
acText
alReadOnly

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Janela ou controle onde o editor dever ser criado.
Numrico, opcional. Largura do editor em pixels.
Numrico, opcional. Altura do editor em pixels.
Texto, opcional. Inserido na inicializao do objeto.
Lgico, opcional. Permite ou no a edio do texto

Mtodos auxiliares:
Create
 Descrio: Mtodo construtor opcional da classe.
 Sintaxe: Create( aoWnd )
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde o editor dever


ser criado.

- 130 ADVPL Avanado

 Retorno:
Objeto

Objeto do tipo TsimpleEditor.

Load
 Descrio: Carrega um texto para o editor.
 Sintaxe: Load( acTexto )
 Parmetros:
acTexto

Texto. Texto que inicializar o editor.

 Retorno:
Nenhum

TextBold
 Descrio: Texto em Negrito.
 Sintaxe: TextBold( alBold )
 Parmetros:
alBold

Lgico. Habilita ou Desabilita a sesso do texto como


Negrito.

 Retorno:
Nenhum

TextUnderline
 Descrio: Texto Sublinhado.
 Sintaxe: TextUnderline( alUnderline )
 Parmetros:
alUnderline

Lgico. Habilita ou Desabilita a sesso do texto


Sublinhado.

 Retorno:
Nenhum

TextItalic
 Descrio: Texto Itlico.
 Sintaxe: TextItalic( alItalic )
 Parmetros:
alItalic

Lgico. Habilita ou Desabilita a sesso do texto Itlico.

 Retorno:
Nenhum

- 131 ADVPL Avanado

TextFamily
 Descrio: Famlia de fontes.
 Sintaxe: TextFamily( acFamily )
 Parmetros:
acFamily

Texto. Nome da famlia da fonte a ser usada na sesso do


texto.

 Retorno:
Nenhum

TextSize
 Descrio: Tamanho da fonte.
 Sintaxe: TextSize( anSize )
 Parmetros:
anSize

Numrico. Tamanho da fonte utilizada na sesso do texto.

 Retorno:
Nenhum

TextStyle
 Descrio: Estilo do pargrafo.
 Sintaxe: TextStyle( anStyle )
 Parmetros:
Numrico. Estilo do pargrafo a ser utilizada na sesso do
texto.

anStyle

1
2
3
4
5
6
7

Normal
Disco (Bullet)
Circulo (Bullet)
Quadrado (Bullet)
Ordem decimal
Ordem alfanumrica minsculo
Ordem alfanumrica maisculo

 Retorno:
Nenhum

- 132 ADVPL Avanado

TextAlign
 Descrio: Alinhamento do texto.
 Sintaxe: TextAlign( anAlign )
 Parmetros:

anAlign

Numrico. Tipo do alinhamento do pargrafo.


1 Esquerda
2 Direita
3 Centralizado
4 Justificado

 Retorno:
Nenhum

TextFormat
 Descrio: Formato do texto.
 Sintaxe: TextFormat( anFormat )
 Parmetros:

anFormat

Numrico. Formato do texto


1 Html
2 Plain Text

 Retorno:
Nenhum

RetText
 Descrio: Retorna o texto em formato string.
 Sintaxe: RetText( void )
 Parmetros:
void

Retorna uma string com o contedo do editor

 Retorno:
Nenhum

RetTextSel
 Descrio: Retorna o texto selecionado em formato string..
 Sintaxe: RetText()
 Parmetros:
Nenhum

 Retorno:
String

Texto selecionado.

- 133 ADVPL Avanado

TextStatus
 Descrio: Retorna um array com as propriedades do texto posicionado.
 Sintaxe: TextStatus()
 Parmetros:
Nenhum

 Retorno:
Retorna um array com as seguintes propriedades

Array

1
2
3
4
5
6

Lgico Negrito
Lgico Itlico
Lgico Sublinhado
Caracter RGB da cor
Caracter Tamanho da fonte
Caracter Fonte

Aparncia:

- 134 ADVPL Avanado

Exemplo:
#include protheus.ch
User Function MyEditor()
Local oDlg, oEditor
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Meu Editor
// Usando o mtodo create
oEdit := tSimpleEditor():Create( oDlg )
oEdit:nTop
:= 10
oEdit:nLeft
:= 10
oEdit:nWidth
:= 600
oEdit:nHeight
:= 500
// Usando o mtodo new
oEdit := tSimpEdit():New( 0, 0, oDlg, 500, 600 )
ACTIVATE MSDIALOG oDlg CENTERED
Return Nil

TSLIDER()


Descrio: Classe de objetos visuais do tipo controle tSlider, a qual permite


criar um controle visual do tipo boto deslizante.

Propriedades:
bChange

Bloco de cdigo. Executado toda vez que o valor alterado


retornando o novo valor.

Construtor: New([anRow], [anCol], [aoWnd],


[anHeight], [acMsg], [abWhen])

Parmetros:
anRow
anCol
aoWnd
abChange
anWidth
anHeight
acMsg
abWhen

[abChange],

[anWidth],

Numrico, opcional. Coordenada vertical em pixels


Numrico, opcional. Coordenada horizontal em pixels
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Bloco de cdigo, opcional. Bloco que dever ser acionado
quando o boto for movimentado.
Numrico, opcional. Largura do boto em pixels.
Numrico, opcional. Altura do boto em pixels.
Caracter, opcional. Mensagem de hint do boto
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

Mtodos auxiliares:

- 135 ADVPL Avanado

Create
 Descrio: Mtodo construtor da classe.
 Sintaxe: Create( aoWnd )
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde o boto dever


ser criado.

 Retorno:
Objeto

Objeto do tipo TSlide criado.

setRange
 Descrio: Especifica a faixa de valores.
 Sintaxe: setRange( min, max )
 Parmetros:
Min
Max

Nmrico. Valor mnimo do boto.


Nmrico. Valor mximo do boto.

 Retorno:
Nenhum

setMarks
 Descrio: Especifica o tipo de marcao do boto.
 Sintaxe: setMarks( nTipo )
 Parmetros:
nTipo

Max

Nmrico. Tipo de marcao do boto.


1Nmrico. Valor mximo do boto.
0 Sem marcao
1 Acima (esquerda se vertical)
2 Abaixo (direita se vertical)
3 Ambos os lados

 Retorno:
Nenhum

- 136 ADVPL Avanado

setInterval
 Descrio: Especifica a distncia entre um marcador e outro.
 Sintaxe: setInterval( nInterval )
 Parmetros:
nInterval

Nmrico. Valor entre os marcadores

 Retorno:
Nenhum

setValue
 Descrio: Especifica um valor para o boto.
 Sintaxe: setValue( nVal )
 Parmetros:
nVal

Nmrico. Valor do boto

 Retorno:
Nenhum

setStep
 Descrio: Especifica o valor dos passos do boto.
 Sintaxe: setStep( nStep )
 Parmetros:
nStep

Nmrico. Valor do passo do boto

 Retorno:
Nenhum

setOrient
 Descrio: Especifica a orientao do boto, horizontal ou vertical.
 Sintaxe: setOrient( nOrient )
 Parmetros:

nOrient

Nmrico. Orientao do boto


0 Horizontal
1 Vertical

 Retorno:
Nenhum

- 137 ADVPL Avanado

Aparncia:

Exemplo:
#include protheus.ch
#include hbutton.ch
User Function MytSlider()
Local oDlg, oSlider
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Meu tSlider
// Usando o mtodo create
oSlider:= tSlider():Create( oDlg )
oSlider:nTop
:= 100
oSlider:nLeft
:= 10
oSlider:nWidth
:= 100
oSlider:nHeight
:= 30
// Usando o command
@ 100, 10 SLIDER oSlider SIZE 30, 100 OF oDlg MESSAGE 'tSlider'
ACTIVATE MSDIALOG oDlg CENTERED
Return Nil

TSPLITTER()


Descrio: Classe de objetos visuais do tipo controle tSplitter, a qual permite


criar um controle visual do tipo divisor.

Propriedades:
-

Herdadas as classes superiores.

Construtor: New( [anRow],


[anOrientation] )

Parmetros:
anRow
anCol
aoWnd
anWidth
anHeight
anOrientation

[anCol],

[aoWnd],

[anWidth],

[anHeight],

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Numrico, opcional. Sentido no qual devero ser criado os
divisores.
0 Horizontal
1 Vertical

- 138 ADVPL Avanado

Mtodos auxiliares:
Create
 Descrio: Mtodo construtor da classe.
 Sintaxe: Create( aoWnd )
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde o divisor dever


ser criado.

 Retorno:
Objeto

Objeto do tipo Tsplitter gerado.

setOrient
 Descrio: Especifica a orientao do divisor, horizontal ou vertical.
 Sintaxe: setOrient( nOrient )
 Parmetros:

nOrient

Nmrico. Orientao do boto


0 Horizontal
1 Vertical

 Retorno:
Nenhum

setChildCollapse
 Descrio: Especifica se os elementos podem ser collapsibles.
 Sintaxe: setChildCollpse( lColl )
 Parmetros:
lColl

Lgico. Ativa / Desativa

 Retorno:
Nenhum

- 139 ADVPL Avanado

setCollapse
 Descrio: Especifica o objeto que pode ser collapsible.
 Sintaxe: setCollapse( oObj, lColl )
 Parmetros:
oObj
lColl

Objeto. Controle a ser collapsed


Lgico. Ativa / Desativa

 Retorno:
Nenhum

movToLast
 Descrio: Coloca o objeto como ultimo das divises.
 Sintaxe: movToLast( oObj )
 Parmetros:
oObj

Objeto. Controle a posicionado

 Retorno:
Nenhum

movToFirst
 Descrio: Coloca o objeto como primeiro das divises.
 Sintaxe: movToFirst( oObj )
 Parmetros:
oObj

Objeto. Controle a ser posicionado

 Retorno:
Nenhum

setOpaqueResize
 Descrio: Especifica se o resize deve ser opaco.
 Sintaxe: setOpaqueResize( lOpaq )
 Parmetros:
lOpaq

Lgico. Ativa / Desativa

 Retorno:
Nenhum

- 140 ADVPL Avanado

setResizeMode
 Descrio: Especifica o mode de resize do objeto..
 Sintaxe: setResizeMode ( oObj, nMode )
 Parmetros:
oObj

nMode

Objeto. Controle a ser resized


Numrico. Modo do resize
0 Stretch
1- KeepSize
2 FollowSizeHint
3 Auto

 Retorno:
Nenhum

Aparncia:

- 141 ADVPL Avanado

Exemplo:
#include protheus.ch
#include hbutton.ch
User Function MytSplitter()
Local oDlg, oSplitter, oPanel1, oPanel2, oPanel3
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Meu tSplitter
// Usando o mtodo create
oSplitter := tSplitter():Create( oDlg )
@ 1, 1 MSPANEL oPanel1 OF oSplitter
@ 1, 2 MSPANEL oPanel2 OF oSplitter
@ 1, 3 MSPANEL oPanel3 OF oSplitter
// Usando o command
@ 1, 1 SPLITTER oSplitter
@ 1, 1 MSPANEL oPanel1 OF
@ 1, 2 MSPANEL oPanel2 OF
@ 1, 3 MSPANEL oPanel3 OF

SIZE 100, 100 OF oDlg


oSplitter
oSplitter
oSplitter

ACTIVATE MSDIALOG oDlg CENTERED


Return Nil

TTABS()


Descrio: Classe de objetos visuais do tipo controle TTabs, a qual permite


criar um controle visual do tipo pasta.

Propriedades:
-

Herdadas das classes superiores.

Construtor: New([anTop], [anLeft], [aPrompts], [bAction], [oWnd], [nOption],


[nClrFore], [nClrBack], [lPixel], [lDesign], [nWidth], [nHeigth],
[cMsg])

Parmetros:
anTop
anLeft
aPrompts
bAction
oWnd
nOption
nClrFore
nClrBack

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres
Array, Titulo dos folders
Bloco de codigo, Disparado na troca da aba.
Objeto, opcional. Janela ou controle onde a boto dever ser
criado
Numrico, opcional. Folder selecionado
Numrico, opcional. Cor de frente
Numrico, opcional. Cor de fundo

- 142 ADVPL Avanado

lPixel
lDesign
nWidth
nHeigth
cMsg

Lgico, opcional. Utiliza coordenadas em pixel


Lgico, opcional. NO USADO
Numrico, opcional. Largura em pixels
Numrico, opcional. Altura em pixels.
Caractere, Mensagem de Hint

Mtodos auxiliares:
AddItem
 Descrio: Adiciona uma aba na pasta
 Sintaxe: AddItem(cTtulo)
 Parmetros:
cTtulo

Ttulo da aba que ser adicionada

 Retorno:
Nenhum

SetOption
 Descrio: Seleciona a Aba
 Sintaxe: SetOption( nNrAba )
 Parmetros:
nNrAba

Nmero que identifica a posio da aba que ser


selecionada.

 Retorno:
Nenhum

Aparncia:

- 143 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
DEFINE MSDIALOG oDlg FROM 0,0 TO 304,504 PIXEL TITLE 'Exemplo'
oTTabs := TTabs():New(01,01,{'Aba01','Aba02','Aba03'},;
{||oPanel01:LVISIBLECONTROL:=(oTTabs:nOption==1)},;
oDlg,,RGB(255,0,0),RGB(255,255,0),.T.,,120,120,)
oPanel01 := TPanel():New( 000, 000,'',oTTabs,,,,,,100,100,,.T. )
oPanel01:lVisibleControl := .T.
oBtn01 := TButton():New( 01,01,'TButton01',oPanel01,;
{||oTTabs:SetOption(2)}, 037,
012,,,.F.,.T.,.F.,,.F.,,,.F. )
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

TTOOLBOX()


Descrio: Classe de objetos visuais do tipo controle tToolbox, a qual permite


criar um controle visual para agrupar diferentes objetos.

Propriedades:
bChangeGrp

Bloco de cdigo. Executado na troca entre os grupos


existentes.

Construtor: New([anRow], [anCol], [aoWnd], [anWidth], [anHeight], [aoFont],


[acMsg]], [abWhen])

Parmetros:
anRow
anCol
aoWnd
anWidth
anHeight
aoFont
acMsg
abWhen

Numrico, opcional. Coordenada vertical em pixels ou


carateres.
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Numrico, opcional. Largura do boto em pixels.
Numrico, opcional. Altura do boto em pixels.
Objeto, opcional. Objeto tipo tFont com propriedades da
fonte utilizada para o ttulo do boto.
Mensagem, opcional. Tooltip/Hint do componente.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

- 144 ADVPL Avanado

Mtodos auxiliares:
Create
 Descrio: Mtodo construtor opcional da classe.
 Sintaxe: Create( aoWnd )
 Parmetros:
aoWnd

Objeto, opcional. Janela ou controle onde o boto dever


ser criado.

 Retorno:
Objeto

Objeto do tipo TtoolBox gerado.

addGroup
 Descrio: Adiciona um grupo
 Sintaxe: addGroup( aoObj, acName, aoIcon )
 Parmetros:
aoObj
acName
aoIcon

Objeto. Objeto Pai que vai ser inserido no grupo.


Caractere. Descrio do grupo
Objeto, opcional. cone para o grupo

 Retorno:
Nenhum

removeGroup
 Descrio: Remove um grupo
 Sintaxe: removeGroup( aoObj )
 Parmetros:
aoObj

Objeto. Objeto Pai que vai ser removido do grupo.

 Retorno:
Nenhum

setCurrentGroup
 Descrio: Define o grupo corrente
 Sintaxe: setCurrentGroup( aoObj )
 Parmetros:
aoObj

Objeto. Objeto Pai que ser definido como grupo corrente.

 Retorno:
Nenhum

- 145 ADVPL Avanado

Aparncia:

Exemplo:
#include protheus.ch
User Function MytToolbox()
Local oDlg, oTb
DEFINE MSDIALOG oDlg FROM 0,0 TO 500,600 PIXEL TITLE Meu Toolbox
// Usando o mtodo create
oTb:= tToolbox():Create( oDlg )
oTb:nTop
:= 100
oTb:nLeft
:= 10
oTb:nWidth
:= 100
oTb:nHeight
:= 30
oTb:Add( oPanel, Opo 1, oIcone)
// Usando o command
@ 200,100 TOOLBOX oTb SIZE 100,30 OF oDlg
TOOLBOX oTb ADDGROUP TITLE Opo 1 OBJECT oPanel ICON oIcone
ACTIVATE MSDIALOG oDlg CENTERED
Return Nil

- 146 ADVPL Avanado

TWBROWSE()


Descrio: Classe de objetos visuais do tipo controle TWBrowse, a qual


permite criar um controle visual do tipo Grid.

Propriedades:
+
nAt
nLen

Herdadas da classe superior


Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

Construtor: New([nRow], [nCol], [nWidth], [nHeigth],[bFields], [aHeaders],


[aColSizes],
[oDlg],
[cField],
[uValue1],
[uValue2],
[uChange],[{|nRow,nCol,nFlags|[uLDblClick]}],
[{|nRow,nCol,nFlags|[uRClick]}], [oFont], [oCursor], [nClrFore],
[nClrBack], [cMsg], [lUpdate], [cAlias], [lPixel], [{uWhen}],
[lDesign], [bValid], [lHScroll], [lVScroll])

Parmetros:
nRow
nCol
nWidth
nHeight
bFields
aHeaders
aColSizes
oDlg
cField
uValue1
uValue2
bChange
bLDblClick
bRClick
oFont
oCursor
nClrFore
nClrBack
cMsg
lUpdate
cAlias
lPixel

bWhen
lDesign

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, Lista de Campos
Vetor, Descrio dos campos para no cabealho
Vetor, Largura das colunas
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Caracter, opcional. Campos necessrios ao filtro
Indefinido, opcional. Inicio do intervalo para o filtro
Indefinido, opcional. Fim do intervalo para o filtro
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
No utilizado
Objeto, opcional. Fonte
Objeto, opcional. Tipo do Cursor
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Caracter, opcional se objeto utilizado com Vetor, obrigatorio
se utilizado com Tabela
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.
No Utilizado

- 147 ADVPL Avanado

Bloco de cdigo, opcional. Executado quando o contedo do


controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Lgico, opcional. Se .T., habilita barra de rolagem
horizontal.
Lgico, opcional. Se .T., habilita barra de rolagem vertical.

bValid
lHScroll
lVScroll


Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil

GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:
- 148 ADVPL Avanado

Nil
RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil

LEditCell
 Descrio: Edita o valor de uma coluna.
 Sintaxe: lEditCell( aList, oList, cPicture, nCol )
 Parmetros:
aList
oList
cPicture
nCol

Vetor da Browse onde esto os valores da mesma


Objeto, Browse a ser editado
Caracter, picture necessria para edio do campo
Numrico, coluna a ser editada.

 Retorno:
Nil


Aparncia:

- 149 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
Local oOK := LoadBitmap(GetResources(),'br_verde')
Local oNO := LoadBitmap(GetResources(),'br_vermelho')
DEFINE MSDIALOG oDlg FROM 0,0 TO 402,402 PIXEL TITLE 'Exemplo'
oBrowse := TWBrowse():New( 01 , 01, 245, 150,,;
{'','Codigo','Descrio'},{20,30,30}, oDlg, ,,,,;
{||},,,,,,,.F.,,.T.,,.F.,,, )
aBrowse
:= {{.T.,'CLIENTE 001','RUA CLIENTE 001','BAIRRO CLIENTE
001'},;
{.F.,'CLIENTE 002','RUA CLIENTE 002','BAIRRO CLIENTE
002'},;
{.T.,'CLIENTE 003','RUA CLIENTE 003','BAIRRO CLIENTE
003'} }
oBrowse:SetArray(aBrowse)
oBrowse:bLine := {||{;
If(aBrowse[oBrowse:nAt,01],oOK,oNO),;
aBrowse[oBrowse:nAt,02],;
aBrowse[oBrowse:nAt,03],;
aBrowse[oBrowse:nAt,04] } }
oBrowse:bLDblClick := ;
{|| aBrowse[oBrowse:nAt][1] :=
!aBrowse[oBrowse:nAt][1],oBrowse:DrawSelect()}
// Principais commandos
TButton():New(160,001,'GoUp()',oDlg,{|| oBrowse:GoUp()
},40,10,,,,.T.)
TButton():New(170,001,'GoDown()',oDlg,{|| oBrowse:GoDown()
},40,10,,,,.T.)
TButton():New(180,001,'GoTop()',oDlg,{|| oBrowse:GoTop()
},40,10,,,,.T.)
TButton():New(190,001,'GoBottom()' , oDlg,{|| oBrowse:GoBottom()
},40,10,,,,.T.)
TButton():New(160,060,'nAt (Linha selecionada)',oDlg,;
{|| Alert (oBrowse:nAt)},80,10,,,,.T.)
TButton():New(170,060,'nRowCount (Nr de linhas visiveis)',oDlg,;
{|| Alert(oBrowse:nRowCount()) },80,10,,,,.T.)
TButton():New(180,060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oBrowse:nLen) },80,10,,,,.T.)
TButton():New(190,060, 'lEditCell (Edita a celula)', oDlg,;
{|| lEditCell(@aBrowse,oBrowse,'@!',3)
},80,10,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 150 ADVPL Avanado

VCBROWSE()


Descrio: Classe de objetos visuais do tipo controle VCBrowse, a qual


permite criar um controle visual do tipo Grid.

Propriedades:
+
nAt
nLen

Herdadas da classe superior


Linha atualmente selecionada / posicionada no objeto
Nmero total de linhas do objeto

Construtor: New([nRow], [nCol], [nWidth], [nHeigth],[bFields], [aHeaders],


[aColSizes],
[oDlg],
[cField],
[uValue1],
[uValue2],
[uChange],[{|nRow,nCol,nFlags|[uLDblClick]}],
[{|nRow,nCol,nFlags|[uRClick]}], [oFont], [oCursor], [nClrFore],
[nClrBack], [cMsg], [lUpdate], [cAlias], [lPixel], [{uWhen}],
[lDesign], [bValid], [lHScroll], [lVScroll])

Parmetros:
nRow
nCol
nWidth
nHeight
bFields
aHeaders
aColSizes
oDlg
cField
uValue1
uValue2
bChange
bLDblClick
bRClick
oFont
oCursor
nClrFore
nClrBack
cMsg
lUpdate
cAlias
lPixel

bWhen

Numrico, opcional. Coordenada vertical


Numrico, opcional. Coordenada horizontal
Numrico, opcional. Largura do objeto
Numrico, opcional. Altura do objeto
Bloco de cdigo, Lista de Campos
Vetor, Descrio dos campos para no cabealho
Vetor, Largura das colunas
Objeto, opcional. Janela ou controle onde o divisor dever
ser criado.
Caracter, opcional. Campos necessrios ao filtro
Indefinido, opcional. Inicio do intervalo para o filtro
Indefinido, opcional. Fim do intervalo para o filtro
Bloco de cdigo, opcional. Executado quando o item
selecionado alterado.
Bloco de cdigo, opcional. Executado quando acionado duplo
click do boto esquerdo do mouse sobre o controle.
No utilizado
Objeto, opcional. Fonte
Objeto, opcional. Tipo do Cursor
Numrico, opcional. Cor do texto da janela.
Numrico, opcional. Cor de fundo da janela.
Caracter, opcional. Mesamge ao posicionar o mouse sobre o
objeto
No utilizado
Caracter, opcional se objeto utilizado com Vetor, obrigatorio
se utilizado com Tabela
Lgico, opcional. Se .T. as coordenadas informadas so em
pixels, se .F. so em caracteres.
Bloco de cdigo, opcional. Executado quando mudana de
foco de entrada de dados est sendo efetuada na janela
onde o controle foi criado. O bloco deve retornar .T. se o
controle deve permanecer habilitado ou .F. se no.

- 151 ADVPL Avanado

lDesign

No Utilizado
Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar .T. se o contedo
for vlido e .F. quando o contedo for invlido.
Lgico, opcional. Se .T., habilita barra de rolagem
horizontal.
Lgico, opcional. Se .T., habilita barra de rolagem vertical.

bValid
lHScroll
lVScroll


Mtodos auxiliares:
GoUp
 Descrio: Salta uma linha para cima.
 Sintaxe: GoUp( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoDown
 Descrio: Salta uma linha para baixo.
 Sintaxe: GoDown( )
 Parmetros:
Nenhum

 Retorno:
Nil
GoTop
 Descrio: Salta para primeira linha.
 Sintaxe: GoTop( )
 Parmetros:
Nenhum

 Retorno:
Nil

- 152 ADVPL Avanado

GoBottom
 Descrio: Salta para ultima linha.
 Sintaxe: GoBottom( )
 Parmetros:
Nenhum

 Retorno:
Nil
RowCount
 Descrio: Retorna numero de linhas visiveis.
 Sintaxe: RowCount( )
 Parmetros:
Nenhum

 Retorno:
Nil

LEditCell
 Descrio: Edita o valor de uma coluna.
 Sintaxe: lEditCell( aList, oList, cPicture, nCol )
 Parmetros:
aList
oList
cPicture
nCol

Vetor da Browse onde esto os valores da mesma


Objeto, Browse a ser editado
Caracter, picture necessria para edio do campo
Numrico, coluna a ser editada.

 Retorno:
Nil

- 153 ADVPL Avanado

Aparncia:

- 154 ADVPL Avanado

Exemplo:
#include 'protheus.ch'
User Function Teste()
Local oDlg
Local oOK := LoadBitmap(GetResources(),'br_verde')
Local oNO := LoadBitmap(GetResources(),'br_vermelho')
DEFINE MSDIALOG oDlg FROM 0,0 TO 402,402 PIXEL TITLE 'Exemplo'
oBrowse := VCBrowse():New( 01 , 01, 245, 150,,;
{'','Codigo','Descrio'},{20,30,30}, oDlg, ,,,,;
{||},,,,,,,.F.,,.T.,,.F.,,, )
aBrowse
:= {{.T.,'CLIENTE 001','RUA CLIENTE 001','BAIRRO CLIENTE
001'},;
{.F.,'CLIENTE 002','RUA CLIENTE 002','BAIRRO CLIENTE
002'},;
{.T.,'CLIENTE 003','RUA CLIENTE 003','BAIRRO CLIENTE
003'} }
oBrowse:SetArray(aBrowse)
oBrowse:bLine := {||{;
If(aBrowse[oBrowse:nAt,01],oOK,oNO),;
aBrowse[oBrowse:nAt,02],;
aBrowse[oBrowse:nAt,03],;
aBrowse[oBrowse:nAt,04] } }
oBrowse:bLDblClick :=;
{|| aBrowse[oBrowse:nAt][1] :=
!aBrowse[oBrowse:nAt][1],oBrowse:DrawSelect()}
// Principais commandos
TButton():New(160,001,'GoUp()',oDlg,{|| oBrowse:GoUp()
},40,10,,,,.T.)
TButton():New(170,001,'GoDown()',oDlg,{|| oBrowse:GoDown()
},40,10,,,,.T.)
TButton():New(180,001,'GoTop()',oDlg,{|| oBrowse:GoTop()
},40,10,,,,.T.)
TButton():New(190,001,'GoBottom()' , oDlg,{|| oBrowse:GoBottom()
},40,10,,,,.T.)
TButton():New(160,060,'nAt (Linha selecionada)',oDlg,;
{|| Alert (oBrowse:nAt)},80,10,,,,.T.)
TButton():New(170,060,'nRowCount (Nr de linhas visiveis)',oDlg,;
{|| Alert(oBrowse:nRowCount()) },80,10,,,,.T.)
TButton():New(180,060, 'nLen (Numero total de linhas)', oDlg,;
{|| Alert(oBrowse:nLen) },80,10,,,,.T.)
TButton():New(190,060, 'lEditCell (Edita a celula)', oDlg,;
{|| lEditCell(@aBrowse,oBrowse,'@!',3)
},40,10,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED
Return NIL

- 155 ADVPL Avanado

Documentao dos componentes da interface visual


Os componentes da interface visual da linguagem ADVPL utilizados neste treinamento esto
documentados na seo Guia de Referncia, ao final deste material.
Para visualizar a documentao completa de todos os componentes mencionados neste
captulo deve ser acesso o site DEM Documentao Eletrnica Microsiga
(dem.microsiga.com.br) conforme abaixo:

- 156 ADVPL Avanado

4.1. Particularidades dos componentes visuais


4.1.1. Configurando as cores para os componentes
Os componentes visuais da linguagem ADVPL utilizam o padro de cores RGB.
As cores deste padro so definidas pela seguinte frmula, a qual deve ser avaliada tendo
como base a paleta de cores no formato RGB:

nCor := nVermelho + (nVerde * 256) + (nAzul * 65536)

Figura: Paleta de cores no formato RGB


Com base nesta paleta, podemos definir os valores das seguintes cores bsicas:
Cor
Preto
Azul
Verde
Ciano
Vermelho
Rosa
Amarelo
Branco

R
0
0
0
0
255
255
255
255

G
0
0
255
255
0
0
255
255

- 157 ADVPL Avanado

B
0
255
0
255
0
255
0
255

Valor
0
16711680
65280
16776960
255
16711935
65535
16777215

Para atribuir as cores aos objetos visuais devem ser observados os atributos utilizados para
estes fins em cada objeto, como por exemplo:
MSDIALOG()
nClrPane

Cor de fundo do painel

nClrText

Cor da fonte das letras do painel

TSAY()
nClrPane

Cor de fundo do painel

nClrText

Cor da fonte das letras do painel

Funo RGB()
A linguagem ADVPL possui a funo RGB() a qual retorna o valor da cor a ser definido, de
acordo com a parametrizao de cada um dos elementos da paleta RGB.

RGB(nRed, nGreen, nBlue)


nRed

Valor de 0-255 para o elemento vermelho da paleta RGB

nGreen

Valor de 0-255 para o elemento verde da paleta RGB

nBlue

Valor de 0-255 para o elemento azul da paleta RGB

Retorno

Valor a ser definido para o atributo cor do componente

- 158 ADVPL Avanado

5. Aplicaes com a interface visual do ADVPL


A linguagem ADVPL possui interfaces visuais pr-definidas que auxiliam no desenvolvimento
de aplicaes mais completas, combinando estas interfaces com os componentes visuais
demonstrados anteriormente.
Didaticamente as interfaces visuais pr-definidas da linguagem ADVPL podem ser divididas em
trs grupos:
 Captura de informaes simples ou Multi-Gets;
 Captura de mltiplas informaes ou Multi-Lines;
 Barras de botes

5.1. Captura de informaes simples (Multi-Gets)


Em ADVPL, as telas de captura de informaes compostas por mltiplos campos digitveis
acompanhados de seus respectivos textos explicativos so comumente chamados de
Enchoices.
Um Enchoice pode ser facilmente entendida como diversos conjuntos de objetos TSay e TGet
alinhados de forma a visualizar ou capturar informaes, normalmente vinculadas a arquivos
de cadastros ou movimentaes simples.
Abaixo temos a visualizao de uma Enchoice para o arquivo padro do ERP Protheus de
Cadastro de Clientes (SA1):

Figura: Enchoice do Cadastro de Clientes do ERP Protheus

- 159 ADVPL Avanado

A linguagem ADVPL permite a implementao da Enchoice de duas formas similares:


 Funo Enchoice: Sintaxe tradicionalmente utilizada em ADVPL, a qual no retorna
um objeto para a aplicao chamadora;
 Classe MsMGet: Classe do objeto Enchoice, a qual permite a instanciao direta de um
objeto, tornando-o disponvel na aplicao chamadora.
A utilizao de um ou outro objeto depende unicamente da escolha do desenvolvedor j que os
parmetros para a funo Enchoice e para o mtodo New() da classe MsMGet so os mesmos,
lembrando que para manter a coerncia com uma aplicao escrita em orientao a objetos
dever ser utilizada a classe MsMGet().

5.1.1. Enchoice()


Sintaxe: Enchoice( cAlias, nReg, nOpc, aCRA, cLetra, cTexto, aAcho, aPos,
aCpos, nModelo, nColMens, cMensagem, cTudoOk, oWnd, lF3,
lMemoria, lColumn, caTela, lNoFolder, lProperty)




Retorno: Nil
Parmetros:
cAlias
nReg
nOpc
aCRA
cLetra
cTexto
aAcho

aPos
aCpos
nModelo
nColMens
cMensagem
cTudoOk
oWnd
lF3
lMemoria
lColumn
caTela
lNoFolder
lProperty

Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser


editada
Parmetro no utilizado
Nmero da linha do aRotina que definir o tipo de edio
(Incluso, Alterao, Excluso, Visualizao)
Parmetro no utilizado
Parmetro no utilizado
Parmetro no utilizado
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"
Vetor com coordenadas para criao da enchoice no formato
{<top>, <left>, <bottom>, <right>}
Vetor com nome dos campos que podero ser editados
Se for diferente de 1 desabilita execuo de gatilhos
estrangeiros
Parmetro no utilizado
Parmetro no utilizado
Expresso para validao da Enchoice
Objeto (janela, painel, etc.) onde a enchoice ser criada.
Indica se a enchoice esta sendo criada em uma consulta F3
para utilizar variveis de memria
Indica se a enchoice utilizar variveis de memria ou os
campos da tabela na edio
Indica se a apresentao dos campos ser em forma de
coluna
Nome da varivel tipo "private" que a enchoice utilizar no
lugar da propriedade aTela
Indica se a enchoice no ir utilizar as Pastas de Cadastro
(SXA)
Indica se a enchoice no utilizar as variveis aTela e aGets,
somente suas propriedades com os mesmos nomes
- 160 ADVPL Avanado

Exemplo: Utilizao da funo Enchoice()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MBRWENCH
| Autor | ARNALDO RAYMUNDO JR.|Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao da funo Enchoice()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function MrbwEnch()
Private cCadastro := " Cadastro de Clientes"
Private aRotina
:=
{{"Pesquisar"
, "axPesqui"
{"Visualizar"
, "U_ModEnc"
DbSelectArea("SA1")
DbSetOrder(1)
MBrowse(6,1,22,75,"SA1")
Return
User Function ModEnc(cAlias,nReg,nOpc)
Local aCpoEnch
Local aAlter

:= {}
:= {}

Local cAliasE
:=
Local aAlterEnch :=
Local aPos
:=
Local nModelo
:=
Local lF3
:=
Local lMemoria
:=
Local lColumn
:=
Local caTela
:=
Local lNoFolder
:=
Local lProperty
:=
Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

cAlias
{}
{000,000,400,600}
3
.F.
.T.
.F.
""
.F.
.F.

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)

- 161 ADVPL Avanado

, 0, 1},;
, 0, 2}}

Exemplo (continuao):
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "A1_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.;
X3Uso(SX3->X3_USADO)
AADD(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
aAlterEnch := aClone(aCpoEnch)
DEFINE MSDIALOG oDlg TITLE cCadastro FROM 000,000 TO 400,600 PIXEL
RegToMemory("SA1", If(nOpc==3,.T.,.F.))
Enchoice(cAliasE, nReg, nOpc, /*aCRA*/, /*cLetra*/, /*cTexto*/, ;
aCpoEnch, aPos, aAlterEnch, nModelo, /*nColMens*/,;
/*cMensagem*/,/*cTudoOk*/, oDlg, lF3, lMemoria, lColumn,;
caTela, lNoFolder, lProperty)
ACTIVATE MSDIALOG oDlg CENTERED
Return

5.1.2. MsMGet()


Sintaxe: MsMGet():New( cAlias, nReg, nOpc, aCRA, cLetra, cTexto, aAcho,


aPos, aCpos, nModelo, nColMens, cMensagem, cTudoOk, oWnd, lF3,
lMemoria, lColumn, caTela, lNoFolder, lProperty)




Retorno: oMsMGet  objeto do tipo MsMGet()


Parmetros:
cAlias
nReg
nOpc
aCRA
cLetra
cTexto
aAcho

aPos
aCpos
nModelo
nColMens
cMensagem
cTudoOk
oWnd
lF3

Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser


editada
Parmetro no utilizado
Nmero da linha do aRotina que definir o tipo de edio
(Incluso, Alterao, Excluso, Visualizao)
Parmetro no utilizado
Parmetro no utilizado
Parmetro no utilizado
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"
Vetor com coordenadas para criao da enchoice no formato
{<top>, <left>, <bottom>, <right>}
Vetor com nome dos campos que podero ser editados
Se for diferente de 1 desabilita execuo de gatilhos
estrangeiros
Parmetro no utilizado
Parmetro no utilizado
Expresso para validao da Enchoice
Objeto (janela, painel, etc.) onde a enchoice ser criada.
Indica se a enchoice esta sendo criada em uma consulta F3
para utilizar variveis de memria

- 162 ADVPL Avanado

Indica se a enchoice utilizar variveis de memria ou os


campos da tabela na edio
Indica se a apresentao dos campos ser em forma de
coluna
Nome da varivel tipo "private" que a enchoice utilizar no
lugar da propriedade aTela
Indica se a enchoice no ir utilizar as Pastas de Cadastro
(SXA)
Indica se a enchoice no utilizar as variveis aTela e aGets,
somente suas propriedades com os mesmos nomes

lMemoria
lColumn
caTela
lNoFolder
lProperty

Exemplo: Utilizao do objeto MsMGet()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MBRWMSGET | Autor | ARNALDO RAYMUNDO JR. |Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto MsMget()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function MrbwMsGet()
Private cCadastro := " Cadastro de Clientes"
Private aRotina
:=
{{"Pesquisar"
, "axPesqui"
{"Visualizar"
, "U_ModEnc"
DbSelectArea("SA1")
DbSetOrder(1)
MBrowse(6,1,22,75,"SA1")
Return
User Function ModEnc(cAlias,nReg,nOpc)
Local aCpoEnch
:= {}
Local aAlter
:= {}
Local cAliasE
Local aAlterEnch :=
Local aPos
:=
Local nModelo
:=
Local lF3
:=
Local lMemoria
:=
Local lColumn
Local caTela
Local lNoFolder
:=
Local lProperty
:=
Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

:= cAlias
{}
{000,000,400,600}
3
.F.
.T.
:= .F.
:= ""
.F.
.F.

- 163 ADVPL Avanado

, 0, 1},;
, 0, 2}}

Exemplo (continuao):
DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "A1_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.
X3Uso(SX3->X3_USADO)
AADD(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
aAlterEnch := aClone(aCpoEnch)
oDlg

:= MSDIALOG():New(000,000,400,600,cCadastro,,,,,,,,,.T.)

RegToMemory(cAliasE, If(nOpc==3,.T.,.F.))
oEnch := MsMGet():New(cAliasE, nReg, nOpc, /*aCRA*/, /*cLetra*/,;
/*cTexto*/, aCpoEnch, aPos, aAlterEnch, nModelo, /*nColMens*/,;
/*cMensagem*/, /*cTudoOk*/,oDlg,lF3,lMemoria,lColumn, caTela,;
lNoFolder, lProperty)
oDlg:lCentered := .T.
oDlg:Activate()
Return

5.2. Captura de mltiplas informaes (Multi-Lines)


A linguagem ADVPL permite a utilizao de basicamente dois tipos de objetos do tipo grid, ou
como tambm so conhecidos: multi-line:
 Grids digitveis: permitem a visualizao e captura de informaes, comumente
utilizados em interfaces de cadastro e manuteno, tais como:

 MSGETDB()
 MSGETDADOS()
 MSNEWGETDADOS()
 Grids no digitveis: permitem somente a visualizao de informaes, comumente
utilizados como browses do ERP Protheus, tais como:

 TWBROWSE()
 MAWNDBROWSE()
 MBROWSE()
Neste tpico sero tratadas as grids digitveis disponveis na linguagem ADVPL para o
desenvolvimento de interfaces de cadastros e manuteno de informaes.

- 164 ADVPL Avanado

5.2.1. MsGetDB()
A classe de objetos visuais MsGetDB() permite a criao de um grid digitvel com uma ou mais
colunas, baseado em uma tabela temporria.


Sintaxe:

MsGetDB():New(nTop, nLeft, nBottom, nRight, nOpc, cLinhaOk,


cTudoOk, cIniCpos, lDelete, aAlter, nFreeze, lEmpty, uPar1, cTRB,
cFieldOk, lCondicional, lAppend, oWnd, lDisparos, uPar2, cDelOk,
cSuperDel)

Retorno: oMsGetDB
 objeto do tipo MsGetDB()

Parmetros:
nTop
nLeft
nBottom
nRight
nOpc
cLinhaOk
cTudoOk
cIniCpos

lDelete
aAlter
nFreeze
lEmpty
uPar1
cFieldOk
cTRB
lCondicional
lAppend
cDelOk
lDisparos
uPar2
cSuperDel
oWnd

Distancia entre a MsGetDB e o extremidade superior do


objeto que a contm.
Distancia entre a MsGetDB e o extremidade esquerda do
objeto que a contm.
Distancia entre a MsGetDB e o extremidade inferior do objeto
que a contm.
Distancia entre a MsGetDB e o extremidade direita do objeto
que a contm.
Posio do elemento do vetor aRotina que a MsGetDB usar
como referncia.
Funo executada para validar o contexto da linha atual do
aCols.
Funo executada para validar o contexto geral da MsGetDB
(todo aCols).
Nome dos campos do tipo caracter que utilizaro incremento
automtico. Este parmetro deve ser no formato +<nome
do primeiro campo>+<nome do segundo campo>+....
Habilita a opo de excluir linhas do aCols. Valor padro
falso.
Vetor com os campos que podero ser alterados.
Indica qual coluna no ficara congelada na exibio.
Habilita validao da primeira coluna do aCols para esta no
poder estar vazia. Valor padro falso.
Parmetro reservado.
Funo executada na validao do campo.
Alias da tabela temporria.
Reservado
Indica se a MsGetDB ira criar uma linha em branco
automaticamente quando for incluso.
Funo executada para validar a excluso de uma linha do
aCols.
Indica se ser utilizado o Dicionrio de Dados para consulta
padro, inicializao padro e gatilhos.
Parmetro reservado.
-Funo
executada
quando
pressionada
as
teclas
<Ctrl>+<Delete>.
Objeto no qual a MsGetDB ser criada.

- 165 ADVPL Avanado

Aparncia:

Variveis private:
aRotina

Vetor com as rotinas que sero executadas na MBrowse e


que definira o tipo de operao que esta sendo executada
(incluso, alterao, excluso, visualizao, pesquisa, ...) no
formato:
{cTitulo, cRotina, nOpo, nAcesso}, aonde:
nOpo segue o padro do ERP Protheus para:
12345-

aHeader

Pesquisar
Visualizar
Incluir
Alterar
Excluir

Vetor com informaes das colunas no formato:


{cTitulo, cCampo, cPicture, nTamanho, nDecimais,;
cValidao, cReservado, cTipo, xReservado1, xReservado2}
A tabela temporria utilizada pela MsGetDB dever ser criada
com base no aHeader mais um ltimo campo tipo lgico que
determina se a linha foi excluda.

lRefresh

Varivel tipo lgica para uso reservado.

- 166 ADVPL Avanado

Variveis pblicas:
nBrLin

Funes de validao:
cLinhaOk
cTudoOk

Indica qual a linha posicionada do aCols.

Funo de validao na mudana das linhas da grid. No


pode ser definida como Static Function.
Funo de validao da confirmao da operao com o grid.
No pode ser definida como Static Function.

Mtodos adicionais:
ForceRefresh()

Atualiza a MsGetDB com a tabela e posiciona na primeira


linha.

Exemplo: Utilizao do objeto MsGetDB()

#include protheus.ch
/*/
+----------------------------------------------------------------------------| Funo
| GETDBSA1
| Autor | MICROSIGA
|Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto MsGetDB()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function GetDbSA1()
Local
Local
Local
Local
Local

nI
oDlg
oGetDB
nUsado := 0
aStruct := {}

Private
Private
Private
Private

lRefresh := .T.
aHeader := {}
aCols := {}
aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluir", "AxDeleta", 0, 5}}

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")

- 167 ADVPL Avanado

Exemplo (continuao):
While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
AADD(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
AADD(aStruct,{SX3->X3_CAMPO,SX3->X3_TIPO,SX3->X3_TAMANHO,;
SX3->X3_DECIMAL})
EndIf
DbSkip()
End
AADD(aStruct,{"FLAG","L",1,0})
cCriaTrab := CriaTrab(aStruct,.T.)
DbUseArea(.T.,__LocalDriver,cCriaTrab,,.T.,.F.)
oDlg

:= MSDIALOG():New(000,000,300,400, MsGetDB SA1,,,,,,,,,.T.)

oGetDB := MsGetDB():New(05,05,145,195,3,"U_LINHAOK", "U_TUDOOK", "+A1_COD", ;


.T.,{"A1_NOME"},1,.F.,,cCriaTrab,"U_FIELDOK",,.T.,oDlg, .T., ,"U_DELOK",;
"U_SUPERDEL")
oDlg:lCentered := .T.
oDlg:Activate()
DbSelectArea(cCriaTrab)
DbCloseArea()
Return
User Function LINHAOK()
ApMsgStop("LINHAOK")
Return .T.
User Function TUDOOK()
ApMsgStop("LINHAOK")
Return .T.
User Function DELOK()
ApMsgStop("DELOK")
Return .T.
User Function SUPERDEL()
ApMsgStop("SUPERDEL")
Return .T.
User Function FIELDOK()
ApMsgStop("FIELDOK")
Return .T.

- 168 ADVPL Avanado

5.2.2. MsGetDados()
A classe de objetos visuais MsGetDados() permite a criao de um grid digitvel com uma ou
mais colunas, baseado em um array.


Sintaxe: MsGetDados():New( nTop, nLeft, nBottom, nRight, nOpc, cLinhaOk,


cTudoOk, cIniCpos, lDelete, aAlter, uPar1, lEmpty, nMax, cFieldOk,
cSuperDel, uPar2, cDelOk, oWnd)

Retorno: oMsGetDados  objeto do tipo MsGetDados()

Parmetros:
nTop
nLeft
nBottom
nRight
nOpc
cLinhaOk
cTudoOk
cIniCpos

lDelete
aAlter
uPar1
lEmpty
nMax
cFieldOk
cSuperDel
uPar2
cDelOk
oWnd

Distancia entre a MsGetDados e o extremidade superior do


objeto que a contm.
Distancia entre a MsGetDados e o extremidade esquerda do
objeto que a contm.
Distancia entre a MsGetDados e o extremidade inferior do
objeto que a contm.
Distancia entre a MsGetDados e o extremidade direita do
objeto que a contm.
Posio do elemento do vetor aRotina que a MsGetDados
usar como referencia.
Funo executada para validar o contexto da linha atual do
aCols.
Funo executada para validar o contexto geral da
MsGetDados (todo aCols).
Nome dos campos do tipo caracter que utilizaro incremento
automtico. Este parmetro deve ser no formato +<nome
do primeiro campo>+<nome do segundo campo>+....
Habilita excluir linhas do aCols. Valor padro falso.
Vetor com os campos que podero ser alterados.
Parmetro reservado.
Habilita validao da primeira coluna do aCols para esta no
poder estar vazia. Valor padro falso.
Nmero mximo de linhas permitidas. Valor padro 99.
Funo executada na validao do campo.
Funo
executada
quando
pressionada
as
teclas
<Ctrl>+<Delete>.
Parmetro reservado.
Funo executada para validar a excluso de uma linha do
aCols.
Objeto no qual a MsGetDados ser criada.

- 169 ADVPL Avanado

Aparncia:

Variveis private:
aRotina

Vetor com as rotinas que sero executadas na MBrowse e


que definira o tipo de operao que esta sendo executada
(incluso, alterao, excluso, visualizao, pesquisa, ...) no
formato:
{cTitulo, cRotina, nOpo, nAcesso}, aonde:
nOpo segue o padro do ERP Protheus para:
6- Pesquisar
7- Visualizar
8- Incluir
9- Alterar
10- Excluir

aHeader

Vetor com informaes das colunas no formato:


{cTitulo, cCampo, cPicture, nTamanho, nDecimais,;
cValidao, cReservado, cTipo, xReservado1, xReservado2}
A tabela temporria utilizada pela MsGetDB dever ser criada
com base no aHeader mais um ltimo campo tipo lgico que
determina se a linha foi excluda.

lRefresh

Varivel tipo lgica para uso reservado.

- 170 ADVPL Avanado

Variveis pblicas:
N

Funes de validao:
cLinhaOk
cTudoOk

Indica qual a linha posicionada do aCols.

Funo de validao na mudana das linhas da grid. No


pode ser definida como Static Function.
Funo de validao da confirmao da operao com o grid.
No pode ser definida como Static Function.

Mtodos adicionais:
ForceRefresh()
Hide()
Show()

Atualiza a MsGetDados com a tabela e posiciona na primeira


linha.
Oculta a MsGetDados.
Mostra a MsGetDados.

Exemplo: Utilizao do objeto MsGetDados()

#include protheus.ch
/*/
+----------------------------------------------------------------------------| Funo
| GETDADOSA1 | Autor | MICROSIGA
|Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto MSGETADOS()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function GetDadoSA1()
Local nI
Local oDlg
Local oGetDados
Local nUsado := 0
Private lRefresh := .T.
Private aHeader := {}
Private aCols := {}
Private aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluir", "AxDeleta", 0, 5}}
DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")

- 171 ADVPL Avanado

Exemplo (continuao):
While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
AADD(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
EndIf
DbSkip()
End
AADD(aCols,Array(nUsado+1))
For nI := 1 To nUsado
aCols[1][nI] := CriaVar(aHeader[nI][2])
Next
aCols[1][nUsado+1] := .F.
oDlg

:= MSDIALOG():New(000,000,300,400, MsGetDados SA1,,,,,,,,,.T.)

oGetDados := MsGetDados():New(05, 05, 145, 195, 4, "U_LINHAOK", "U_TUDOOK",;


"+A1_COD", .T., {"A1_NOME"}, , .F., 200, "U_FIELDOK", "U_SUPERDEL",,;
"U_DELOK", oDlg)
oDlg:lCentered := .T.
oDlg:Activate()
Return
User Function LINHAOK()
ApMsgStop("LINHAOK")
Return .T.
User Function TUDOOK()
ApMsgStop("LINHAOK")
Return .T.
User Function DELOK()
ApMsgStop("DELOK")
Return .T.
User Function SUPERDEL()
ApMsgStop("SUPERDEL")
Return .T.
User Function FIELDOK()
ApMsgStop("FIELDOK")
Return .T.

- 172 ADVPL Avanado

5.2.3. MsNewGetDados()
A classe de objetos visuais MsNewGetDados() permite a criao de um grid digitvel com uma
ou mais colunas, baseado em um array.


Sintaxe: MsNewGetDados():New(nSuperior, nEsquerda ,nInferior, nDireita,


nOpc, cLinOk, cTudoOk, cIniCpos, aAlterGDa, nFreeze, nMax,
cFieldOk, cSuperDel, cDelOk, oDLG, aHeader, aCols)

Retorno: oMsGetDados  objeto do tipo MsNewGetDados()

Parmetros:
nSuperior
nEsquerda
nInferior
nDireita
nOpc
cLinOk
cTudoOk
cIniCpos
aAlterGDa
nFreeze

Distancia entre a MsNewGetDados e o extremidade superior


do objeto que a contem
Distancia entre a MsNewGetDados e o extremidade esquerda
do objeto que a contem
Distancia entre a MsNewGetDados e o extremidade inferior do
objeto que a contem
Distancia entre a MsNewGetDados e o extremidade direita do
objeto que a contem
Operao em execuo: 2- Visualizar, 3- Incluir, 4- Alterar, 5Excluir
Funo executada para validar o contexto da linha atual do
aCols
Funo executada para validar o contexto geral da
MsNewGetDados (todo aCols)
Nome dos campos do tipo caracter que utilizaro incremento
automtico.
Campos alterveis da GetDados
Campos estticos na GetDados, partindo sempre da posio
inicial da getdados aonde:
1- Primeiro campo congelado
2- Primeiro e segundo campos congelados...

nMax
cFieldOk
cSuperDel
cDelOk
oDLG
aHeader
aCols

Nmero mximo de linhas permitidas. Valor padro 99


Funo executada na validao do campo
Funo executada quando pressionada as teclas
<Ctrl>+<Delete>
Funo executada para validar a excluso de uma linha do
aCols
Objeto no qual a MsNewGetDados ser criada
Array a ser tratado internamente na MsNewGetDados como
aHeader
Array a ser tratado internamente na MsNewGetDados como
aCols

- 173 ADVPL Avanado

Aparncia:

Variveis private:
aRotina

Vetor com as rotinas que sero executadas na MBrowse e


que definira o tipo de operao que esta sendo executada
(incluso, alterao, excluso, visualizao, pesquisa, ...) no
formato:
{cTitulo, cRotina, nOpo, nAcesso}, aonde:
nOpo segue o padro do ERP Protheus para:
12345-

aHeader

Pesquisar
Visualizar
Incluir
Alterar
Excluir

Vetor com informaes das colunas no formato:


{cTitulo, cCampo, cPicture, nTamanho, nDecimais,;
cValidao, cReservado, cTipo, xReservado1, xReservado2}
A tabela temporria utilizada pela MsGetDB dever ser criada
com base no aHeader mais um ltimo campo tipo lgico que
determina se a linha foi excluda.

lRefresh

Varivel tipo lgica para uso reservado.


- 174 ADVPL Avanado

Variveis pblicas:

Indica qual a linha posicionada do aCols.

Funes de validao:

Funo de validao na mudana das linhas da grid. No


pode ser definida como Static Function.
Funo de validao da confirmao da operao com o grid.
No pode ser definida como Static Function.

cLinhaOk
cTudoOk

Mtodos adicionais:

Atualiza a MsNewGetDados com a tabela e posiciona na


primeira linha.
Oculta a MsNewGetDados.
Mostra a MsNewGetDados.

ForceRefresh()
Hide()
Show()

Exemplo: Utilizao dos objetos MsNewGetDados() e MsMGet()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MBRWGETD
| Autor | ARNALDO RAYMUNDO JR. |Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao dos objetos
|
|
| MsNewGetDados() e MsMGet() combinados
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function MrbwGetD()
Private cCadastro := "Pedidos de Venda"
Private aRotina
:=
{{"Pesquisar"
{"Visualizar"
{"Incluir"

, "axPesqui"
, "U_ModGtd"
, "U_ModGtd"

DbSelectArea("SC5")
DbSetOrder(1)
MBrowse(6,1,22,75,"SC5")
Return
User Function ModGtd(cAlias,nReg,nOpc)
Local
Local
Local
Local
Local
Local

nX
nUsado
aButtons
aCpoEnch
cAliasE
aAlterEnch

:=
:=
:=
:=
:=
:=

0
0
{}
{}
cAlias
{}

- 175 ADVPL Avanado

, 0, 1},;
, 0, 2},;
, 0, 3}}

Exemplo (continuao):
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aPos
nModelo
lF3
lMemoria
lColumn
caTela
lNoFolder
lProperty
aCpoGDa
cAliasGD
nSuperior
nEsquerda
nInferior
nDireita
cLinOk
cTudoOk
cIniCpos
nFreeze
nMax
cFieldOk
cSuperDel
cDelOk
aHeader
aCols
aAlterGDa

Private
Private
Private
Private
Private

:=
:=
:=
:=
:=
:=
:=

:=

{000,000,080,400}
3
.F.
.T.
:= .F.
:= ""
.F.
.F.
:= {}
"SC6"
:= 081
:= 000
:= 250
:= 400
:= "AllwaysTrue"
:= "AllwaysTrue"
:= "C6_ITEM"
:= 000
:= 999
:= "AllwaysTrue"
:= ""
:= "AllwaysFalse"
:= {}
:= {}
{}

oDlg
oGetD
oEnch
aTELA[0][0]
aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "C5_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.;
X3Uso(SX3->X3_USADO)
AADD(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
aAlterEnch := aClone(aCpoEnch)
DbSelectArea("SX3")
DbSetOrder(1)
MsSeek(cAliasGD)
While !Eof() .And. SX3->X3_ARQUIVO == cAliasGD
If
!(AllTrim(SX3->X3_CAMPO) $ "C6_FILIAL") .And.;
cNivel >= SX3->X3_NIVEL .And. X3Uso(SX3->X3_USADO)
AADD(aCpoGDa,SX3->X3_CAMPO)
EndIf
DbSkip()
End
- 176 ADVPL Avanado

Exemplo (continuao):
aAlterGDa := aClone(aCpoGDa)
nUsado:=0
dbSelectArea("SX3")
dbSeek("SC6")
aHeader:={}
While !Eof().And.(x3_arquivo=="SC6")
If X3USO(x3_usado).And.cNivel>=x3_nivel
nUsado:=nUsado+1
AADD(aHeader,{ TRIM(x3_titulo), x3_campo, x3_picture,x3_tamanho,;
x3_decimal,"AllwaysTrue()",x3_usado, x3_tipo, x3_arquivo, x3_context } )
Endif
dbSkip()
End
If nOpc==3 // Incluir
aCols:={Array(nUsado+1)}
aCols[1,nUsado+1]:=.F.
For nX:=1 to nUsado
IF aHeader[nX,2] == "C6_ITEM"
aCols[1,nX]:= "0001"
ELSE
aCols[1,nX]:=CriaVar(aHeader[nX,2])
ENDIF
Next
Else
aCols:={}
dbSelectArea("SC6")
dbSetOrder(1)
dbSeek(xFilial()+M->C5_NUM)
While !eof().and.C6_NUM==M->C5_NUM
AADD(aCols,Array(nUsado+1))
For nX:=1 to nUsado
aCols[Len(aCols),nX]:=FieldGet(FieldPos(aHeader[nX,2]))
Next
aCols[Len(aCols),nUsado+1]:=.F.
dbSkip()
End
Endif
oDlg

:= MSDIALOG():New(000,000,400,600, cCadastro,,,,,,,,,.T.)
RegToMemory("SC5", If(nOpc==3,.T.,.F.))

oEnch := MsMGet():New(cAliasE,nReg,nOpc,/*aCRA*/,/*cLetra*/,/*cTexto*/,;
aCpoEnch,aPos,aAlterEnch, nModelo, /*nColMens*/, /*cMensagem*/,;
/*cTudoOk*/, oDlg,lF3, lMemoria,lColumn,caTela,lNoFolder,;
lProperty)
oGetD:= MsNewGetDados():New(nSuperior, nEsquerda, nInferior, nDireita,;
nOpc,cLinOk,cTudoOk, cIniCpos, aAlterGDa, nFreeze, nMax,cFieldOk,;
cSuperDel,cDelOk, oDLG, aHeader, aCols)
oDlg:bInit := {|| EnchoiceBar(oDlg, {||oDlg:End()},{||oDlg:End()},,aButtons)}
oDlg:lCentered := .T.
oDlg:Activate()
Return

- 177 ADVPL Avanado

5.2.3.1.

Definindo cores personalizadas para o objeto MsNewGetDados()

Conforme visto no tpico sobre definio das propriedades de cores para os componentes
visuais, cada objeto possui caractersticas que devem ser respeitadas para correta utilizao
deste recurso.


Atributos adicionais:
lUseDefaultColors

Mtodos adicionais:
SetBlkBackColor

Atributo que dever ser definido como .F. para que as


alteraes nas cores sejam permitidas.

Mtodo que define a cor que ser utilizada para cada linha do
grid. No necessrio utilizar o mtodo Refresh() aps a
definio da cor por este mtodo.

Aparncia:

- 178 ADVPL Avanado

Exemplo: Definindo cores personalizadas para o objeto MsNewGetDados()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MRBWGTCL
| Autor | ARNALDO RAYMUNDO JR. |Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao dos objetos
|
|
| MsNewGetDados() e MsMGet() combinados e tratamento de cores
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function MrbwGtCl()
Private cCadastro := "Pedidos de Venda"
Private aRotina
:=
{{"Pesquisar"
{"Visualizar"
{"Incluir"

, "axPesqui"
, "U_ModGtd"
, "U_ModGtd"

DbSelectArea("SC5")
DbSetOrder(1)
MBrowse(6,1,22,75,"SC5")
Return
User Function ModGtd(cAlias,nReg,nOpc)
Local nX
:= 0
Local nUsado
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aButtons
aCpoEnch
cAliasE
aAlterEnch
aPos
nModelo
lF3
lMemoria
lColumn
caTela
lNoFolder
lProperty
aCpoGDa
cAliasGD
nSuperior
nEsquerda
nInferior
nDireita
cLinOk
cTudoOk
cIniCpos
nFreeze
nMax

:= 0
:= {}
:= {}
:= cAlias
{}
{000,000,080,400}
3
.F.
.T.
:= .F.
:= ""
:= .F.
:= .F.
:= {}
:= "SC6"
:= 081
:= 000
:= 250
:= 400
:= "AllwaysTrue"
:= "AllwaysTrue"
:= "C6_ITEM"
:= 000
:= 999

:=
:=
:=
:=
:=

- 179 ADVPL Avanado

, 0, 1},;
, 0, 2},;
, 0, 3}}

Exemplo (continuao):
Local
Local
Local
Local
Local
Local

cFieldOk
cSuperDel
cDelOk
aHeader
aCols
aAlterGDa

Private
Private
Private
Private
Private

:=
:=
:=
:=
:=

"AllwaysTrue"
""
"AllwaysFalse"
{}
{}
:= {}

oDlg
oGetD
oEnch
aTELA[0][0]
aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "C5_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.;
X3Uso(SX3->X3_USADO)
AADD(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
aAlterEnch := aClone(aCpoEnch)
DbSelectArea("SX3")
DbSetOrder(1)
MsSeek(cAliasGD)
While !Eof() .And. SX3->X3_ARQUIVO == cAliasGD
If
!(AllTrim(SX3->X3_CAMPO) $ "C6_FILIAL") .And. cNivel >= SX3>X3_NIVEL .And. X3Uso(SX3->X3_USADO)
AADD(aCpoGDa,SX3->X3_CAMPO)
EndIf
DbSkip()
End
aAlterGDa := aClone(aCpoGDa)
nUsado:=0
dbSelectArea("SX3")
dbSeek("SC6")
aHeader:={}
While !Eof().And.(x3_arquivo=="SC6")
If X3USO(x3_usado).And.cNivel>=x3_nivel
nUsado:=nUsado+1
AADD(aHeader,{ TRIM(x3_titulo), x3_campo, x3_picture,;
x3_tamanho, x3_decimal,"AllwaysTrue()",;
x3_usado, x3_tipo, x3_arquivo, x3_context } )
Endif
dbSkip()
End

- 180 ADVPL Avanado

Exemplo (continuao):
If nOpc==3 // Incluir
aCols:={Array(nUsado+1)}
aCols[1,nUsado+1]:=.F.
For nX:=1 to nUsado
IF aHeader[nX,2] == "C6_ITEM"
aCols[1,nX]:= "0001"
ELSE
aCols[1,nX]:=CriaVar(aHeader[nX,2])
ENDIF
Next
Else
aCols:={}
dbSelectArea("SC6")
dbSetOrder(1)
dbSeek(xFilial()+M->C5_NUM)
While !eof().and.C6_NUM==M->C5_NUM
AADD(aCols,Array(nUsado+1))
For nX:=1 to nUsado
aCols[Len(aCols),nX]:=FieldGet(FieldPos(aHeader[nX,2]))
Next
aCols[Len(aCols),nUsado+1]:=.F.
dbSkip()
End
Endif
oDlg := MSDIALOG():New(000,000,400,600, cCadastro,,,,,,,,,.T.)
RegToMemory("SC5", If(nOpc==3,.T.,.F.))
oEnch := MsMGet():New(cAliasE,nReg,nOpc,/*aCRA*/,/*cLetra*/, /*cTexto*/,;
aCpoEnch,aPos, aAlterEnch, nModelo, /*nColMens*/, /*cMensagem*/,;
cTudoOk,oDlg,lF3, lMemoria,lColumn,caTela,lNoFolder,lProperty)
oGetD:= MsNewGetDados():New(nSuperior,nEsquerda,nInferior,nDireita, nOpc,;
cLinOk,cTudoOk,cIniCpos,aAlterGDa,nFreeze,nMax,cFieldOk, cSuperDel,;
cDelOk, oDLG, aHeader, aCols)
// Tratamento para definio de cores especficas,
// logo aps a declarao da MsNewGetDados
oGetD:oBrowse:lUseDefaultColors := .F.
oGetD:oBrowse:SetBlkBackColor({|| GETDCLR(oGetD:aCols,oGetD:nAt,aHeader)})
oDlg:bInit := {|| EnchoiceBar(oDlg, {||oDlg:End()}, {||oDlg:End()},,aButtons)}
oDlg:lCentered := .T.
oDlg:Activate()
Return

- 181 ADVPL Avanado

Exemplo (continuao):
// Funo para tratamento das regras de cores para a grid da MsNewGetDados
Static Function GETDCLR(aLinha,nLinha,aHeader)
Local
Local
Local
Local
Local

nCor2
nCor3
nPosProd
nUsado
nRet

:=
:=
:=
:=
:=

16776960 // Ciano - RGB(0,255,255)


16777215 // Branco - RGB(255,255,255)
aScan(aHeader,{|x| Alltrim(x[2]) == "C6_PRODUTO"})
Len(aHeader)+1
nCor3

If !Empty(aLinha[nLinha][nPosProd]) .AND. aLinha[nLinha][nUsado]


nRet := nCor2
ElseIf !Empty(aLinha[nLinha][nPosProd]) .AND. !aLinha[nLinha][nUsado]
nRet := nCor3
Endif
Return nRet

- 182 ADVPL Avanado

5.3. Barras de botes


A linguagem ADVPL permite a implementao de barras de botes utilizando funes prdefinidas desenvolvidas com o objetivo de facilitar sua utilizao, ou atravs da utilizao
direta dos componentes visuais disponveis. Dentre os recursos da linguagem que podem ser
utilizados com esta finalidade sero abordados:
 Funo EnchoiceBar: Sintaxe tradicionalmente utilizada em ADVPL, a qual no
retorna um objeto para a aplicao chamadora;
 Classe TBar: Classe do objeto TBar(), a qual permite a instanciao direta de um
objeto do tipo barra de botes superior, tornando-o disponvel na aplicao chamadora.
 Classe ButtonBar: Classe do objeto ButtonBar(), a qual permite a instanciao direta
de um objeto barra de botes genrico, o qual pode ser utilizado em qualquer posio
da tela, tornando-o disponvel na aplicao chamadora.

5.3.1. EnchoiceBar()
Funo que cria uma barra de botes no formato padro utilizado pelas interfaces de cadastro
da aplicao Protheus.
Esta barra possui os botes padres para confirmar ou cancelar a interface e ainda permite a
adio de botes adicionais com a utilizao do parmetro aButtons.

Sintaxe:

EnchoiceBar( oDlg, bOk, bCancel, lMsgDel, aButtons, nRecno, cAlias)

Parmetros:
oDlg
bOk
bCancel
lMsgDel
aButtons
nRecno
cAlias

Dialog onde ir criar a barra de botes


Bloco de cdigo a ser executado no boto Ok
Bloco de cdigo a ser executado no boto Cancelar
Exibe dialog para confirmar a excluso
Array contendo botes adicionais.
aArray[n][1] -> Imagem do boto
aArray[n][2] -> bloco de cdigo contendo a ao do boto
aArray[n][3] -> ttulo do boto
Registro a ser posicionado aps a execuo do boto Ok.
Alias do registro a ser posicionado aps a execuo do boto
Ok. Se o parmetro nRecno for informado, o cAlias passa ser
obrigatrio.

Aparncia:

- 183 ADVPL Avanado

Exemplo: Utilizao da funo EnchoiceBar()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| DENCHBAR
| Autor | ARNALDO RAYMUNDO JR. |Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao da funo
|
|
| EnchoiceBar()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function DEnchBar()
Local oDlg, oBtn
Local aButtons := {}
DEFINE MSDIALOG oDlg TITLE "Teste EnchoiceBar" FROM 000,000 TO 400,600 PIXEL OF;
oMainWnd
AADD( aButtons, {"HISTORIC", {|| TestHist()}, "Histrico...",;
"Histrico",{|| .T.}} )
@ -15,-15 BUTTON oBtn PROMPT "..." SIZE 1,1 PIXEL OF oDlg
ACTIVATE MSDIALOG oDlg ;
ON INIT (EnchoiceBar(oDlg,{||lOk:=.T.,oDlg:End()},{||oDlg:End()},,@aButtons))
Return

- 184 ADVPL Avanado

5.3.2. TBar()
Classe de objetos visuais que permite a implementao de um componente do tipo barra de
botes para a parte superior de uma janela previamente definida.


Sintaxe: New(oWnd, nBtnWidth, nBtnHeight, l3D, cMode, oCursor, cResource,


lNoAutoAdjust)

Retorno: oTBar  objeto do tipo TBar()

Parmetros:
oWnd

Objeto, opcional. Janela ou controle onde o boto dever ser


criado.

nBtnWidth

Numrico, opcional. Largura do boto contido na barra

nBtnHeight

Numrico, opcional. Altura do boto contido na barra

l3D

Lgico, opcional. Define tipo da barra

cMode

No utilizado.

oCursor
cResource
lNoAutoAdjust


Objeto, opcional. Define Cursor ao posicionar o mouse sobre a


barra.
Caracter, opcional. Imagem do recurso a ser inserido como
fundo da barra.
Lgico.

Aparncia:

Exemplo: Utilizao da funo EnchoiceBar()

#include 'protheus.ch'
/*/
+----------------------------------------------------------------------------| Funo
| TSTBAR
| Autor | MICROSIGA
|Data |
|
+----------------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto TBar()
|
+----------------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------------/*/
User Function TstTBar()
Local oDlg
oDlg

:= MSDIALOG():New(000,000,305,505, 'Exemplo - TBAR',,,,,,,,,.T.)


- 185 ADVPL Avanado

Exemplo (continuao):
oTBar := TBar():New( oDlg,25,32,.T.,,,,.F. )
oTBtnBmp2_1 := TBtnBmp2():New( 00, 00, 35, 25, 'copyuser' ,,,,;
{||Alert('TBtnBmp2_1')}, oTBar,'msGetEx',,.F.,.F. )
oTBtnBmp2_2 := TBtnBmp2():New( 00, 00, 35, 25, 'critica'
{||},oTBar,'Critica',,.F.,.F. )

,,,,;

oTBtnBmp2_3 := TBtnBmp2():New( 00, 00, 35, 25, 'bmpcpo'


{||},oTBar,'PCO',,.F.,.F. )

,,,,;

oTBtnBmp2_4 := TBtnBmp2():New( 00, 00, 35, 25, 'preco'


{||},oTBar,'Preo' ,,.F.,.F. )

,,,,;

oDlg:lCentered := .T.
oDlg:Activate()
Return

5.3.3. ButtonBar
A sintaxe ButtonBar a forma clssica utilizada na linguagem ADVPL para implementar um
objeto da classe TBar(), o qual possui as caractersticas mencionadas no tpico anterior.


Sintaxe:

DEFINE BUTTONBAR oBar SIZE nWidth, nHeight 3D MODE OF oDlg


CURSOR

Retorno: ().

Parmetros:
oBar
nWidth
nHeight
3D
oDlg
MODE

Objeto do tipo TBar() que ser criado com a utilizao da


sintaxe ButtonBar().
Numrico, opcional. Largura do boto contido na barra.
Numrico, opcional. Altura do boto contido na barra.
Se definido habilita a visualizao em 3D da barra de botes.
Objeto, opcional. Janela ou controle onde o boto dever ser
criado.
Define a forma de orientao do objeto ButtonBar utilizando
os seguintes termos pr-definidos:
TOP, BOTTOM, FLOAT

CURSOR

Objeto, opcional. Define Cursor ao posicionar o mouse sobre


a barra.

- 186 ADVPL Avanado

A sintaxe ButtonBar requer a adio dos botes como recursos adicionais da barra
previamente definida utilizando a sintaxe abaixo:


Botes: BUTTON RESOURCE

Sintaxe adicional:

DEFINE BUTTON RESOURCE cBitMap OF oBar ACTION cAcao TOOLTIP


cTexto

Parmetros:
cBitMap

Nome da imagem disponvel na aplicao.

oBar

Objeto do tipo TBar() no qual o boto ser adicionado.

cAcao

Funo ou lista de expresses que determina a ao que ser


realizada pelo boto.
Texto no estilo tooltip text que ser exibido quando o
cursor do mouse for posicionado sobre o boto na barra de
ferramentas.

cTexto

Aparncia:

Exemplo: Utilizao da sintaxe ButtonBar

#include 'protheus.ch'
/*/
+----------------------------------------------------------------------| Funo
| TstBBar
| Autor | MICROSIGA
|Data |
|
+----------------------------------------------------------------------| Descrio | Programa que demonstra a utilizao do objeto TBar()
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
User Function TstBBar()
Local oDlg
Local oBtn1
Local oBtn2
oDlg

:= MSDIALOG():New(000,000,305,505, 'Exemplo - BUTTONBAR',,,,,,,,,.T.)

DEFINE BUTTONBAR oBar SIZE 25,25 3D TOP OF oDlg


- 187 ADVPL Avanado

Exemplo (continuao):
DEFINE
DEFINE
DEFINE
DEFINE
ACTION

BUTTON RESOURCE "S4WB005N" OF oBar


BUTTON RESOURCE "S4WB006N" OF oBar
BUTTON RESOURCE "S4WB007N" OF oBar
BUTTON oBtn1 RESOURCE "S4WB008N" OF
Calculadora() TOOLTIP "Calculadora"

oBtn1:cTitle:="Calc"
DEFINE BUTTON RESOURCE "S4WB009N"
DEFINE BUTTON RESOURCE "S4WB010N"
DEFINE BUTTON RESOURCE "S4WB016N"
ACTION HelProg() TOOLTIP "Ajuda"

ACTION NaoDisp() TOOLTIP "Recortar"


ACTION NaoDisp() TOOLTIP "Copiar"
ACTION NaoDisp() TOOLTIP "Colar"
oBar GROUP;

OF oBar ACTION Agenda() TOOLTIP "Agenda"


OF oBar ACTION OurSpool() TOOLTIP "Spool"
OF oBar GROUP;

DEFINE BUTTON oBtn2 RESOURCE "PARAMETROS" OF oBar GROUP;


ACTION Sx1C020() TOOLTIP "Parmetros"
oBtn2:cTitle:="Param."
DEFINE
BUTTON oBtOk RESOURCE "FINAL" OF oBar GROUP;
ACTION oDlg:End()TOOLTIP "Sair"
oBar:bRClicked := {|| AllwaysTrue()}
oDlg:lCentered := .T.
oDlg:Activate()
Return

- 188 ADVPL Avanado

5.3.4. Imagens pr-definidas para as barras de botes


Conforme mencionado nos tpicos anteriores, os botes visuais do tipo barra de botes
permitem a definio de itens com aes e imagens vinculadas.
Dentre os objetos e funes mencionados, foi citada a EnchoiceBar(), a qual permite a adio
de botes adicionais atravs do parmetro aButton, sendo que os itens deste array devem
possuir o seguinte formato:
 Sintaxe: AADD(aButtons,{cBitMap, bAcao, cTexto})
 Estrutura:
cBitMap
bAcao
cTexto

Nome da imagem pr-definida existente na aplicao ERP que


ser vinculada ao boto.
Bloco de cdigo que define a ao que ser executada com a
utilizao do boto.
Texto no estilo tooltip text que ser exibido quando o cursor
do mouse for posicionado sobre o boto na barra de
ferramentas.

 Alguns BitMaps disponveis:


DESTINOS

DISCAGEM

EDIT

EDITABLE

EXCLUIR

FORM

GRAF2D

GRAF3D

LINE

NOTE

OBJETIVO

OK

PENDENTE

PRECO

PRODUTO

S4SB014N

S4WB001N

S4WB005N

S4WB006N

S4WB007N

S4WB008N

S4WB009N

S4WB010N

S4WB011N

S4WB013N

S4WB014A

S4WB016N

SIMULACA

VENDEDOR

USER

 Exemplo:
AADD(aButtons,{"USER",{||AllwaysTrue()},"Usurio"})

- 189 ADVPL Avanado

6. Outras aplicaes da interface visual do ADVPL


6.1. MaWndBrowse()


Descrio: Browse que permite a visualizao de registros para arquivos / tabelas que
no possuem estrutura definida no Dicionrio de Dados do sistema.

Sintaxe: MaWndBrowse (nLin1, nCol1, nLin2, nCol2, cTitle, cAlias, aCampos, aRotina,
cFunLeg, cTopFun, cBotFun, lCentered, aResource, nMod, aPesqui, cSeek,
lDic, lSavOrd)

Parmetros:
nLin1
nCol1
nLin2
nCol2
cTitle
cAlias
aCampos
aRotina
cFunLeg
cTopFun
cBotFun
lCentered
aResource

nModelo

aPesqui
cSeek
lDic
lSavOrd


Linha inicial do browse


Coluna inicial do browse
Linha final do browse
Coluna final do browse
Ttulo do browse (obrigatrio)
Alias da tabela corrente podendo ser um temporrio
Se lDic=.T. utilizar o SX3, do contrrio o aCampos
informado
Idntico ao aRotina para mBrowse
Funo que dever retornar um valor lgico e com isso ser
atribudo semafro na primeira coluna do browse
Mostrar os registros com a chave de
Mostrar os registros com a chave ate
Valor verdadeiro centraliza
aAdd(aResource,{"IMAGEM","Texto significativo"})
Posio do Menu:
1- Horizontal (superior)
2- Vertical (esquerda)
3- Horizontal (inferior)
aAdd(aPesqui{"Ttulo",nOrdem}), se no passado ser
utilizado o AxPesqui
Chave principal para a busca, exemplo: xFilial("???")
Parmetro em conjunto com aCampos
Estabelecer a ordem aps pesquisas.

Estrutura do array aCampos


aAdd(aCampo,{X3_CAMPO,X3_PICTURE,X3_TITULO,X3_TAMANHO})

- 190 ADVPL Avanado

Aparncia:

Exemplo: MaWndBrowse para arquivo temporrio

#include "protheus.ch"
/*/
+----------------------------------------------------------------------| Funo
| WndBrwTRB
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Demonstra a utilizao da MaWndBrowse com Temporrio
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
User Function WndBrwTRB()
// Variveis para o Arquivo Temporario
Local cChave
:= ""
Local cArqTrb
:= ""
Local aStruTRB := {}
// Variveis para o MaWndBrowse
Local cTitulo
:= "Cadastro Temporario"// Ttulo obrigatrio
Local cAlias
:= "TRB" // Alias da tabela corrente podendo ser TRB
Local cFunLeg
:= "" // Funo que dever retornar um valor lgico e com isso
ser atribudo semafro na primeira coluna do browse
Local cTopFun
:= "" // Mostrar os registros com a chave de
Local cBotFun
:= "" // Mostrar os registros com a chave ate
Local lCentered := .T. // Valor verdadeiro centraliza
Local aResource := {} // aAdd(aResource,{"IMAGEM","Texto significativo"})
Local nModelo
:= 1 // 1- Menu do aRotina
Local aPesqui
:= {} // aAdd(aPesqui{"Ttulo",nOrdem}), se no passado ser
utilizado o AxPesqui
Local cSeek
:= "" // Chave principal para a busca, exemplo: xFilial("???")
Local lDic
:= .F. // Parmetro em conjunto com aCampos
Local lSavOrd
:= .T. // Estabelecer a ordem aps pesquisas.
- 191 ADVPL Avanado

// Variaveis para a MsAdvSize


Local lEnchBar := .F. // Se a janela de dilogo possuir enchoicebar (.T.)
Local lPadrao
:= .F. // Se a janela deve respeitar as medidas padres do
//Protheus (.T.) ou usar o mximo disponvel (.F.)
Local nMinY
:= 400 // Altura mnima da janela
Local aSize

:= MsAdvSize(lEnchBar, lPadrao, nMinY)

Private cCadastro := " "


Private aCampos
:= {} // Se lDic=.T. utilizar o SX3, do contrrio o aCampos
//informado -> aAdd(aCampo,{X3_CAMPO,X3_PICTURE,X3_TITULO,X3_TAMANHO})
Private aRotina
:= {} // Idntico ao aRotina para mBrowse
aAdd(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
aAdd(aRotina,{"Visualizar","U_TVisual",0,2})
aAdd(aRotina,{"Incluir"
,"U_TInclui",0,3})
aAdd(aRotina,{"Alterar"
,"U_TAltera",0,4})
aAdd(aRotina,{"Excluir"
,"U_TExclui",0,5})
// Estrutura do Arquivo: Nome do campo / tipo, tamanho, decimais (SX3 para
//temporrio)
AADD(aStruTRB,{"TRB_FILIAL"
,"C",02,0}) // Nome_Campo , Tipo_Campo,
//Tamanho, Decimal
AADD(aStruTRB,{"TRB_ID"
,"C",14,0})
AADD(aStruTRB,{"TRB_NOME"
,"C",20,0})
AADD(aStruTRB,{"TRB_IDADE"
,"N",03,0})
AADD(aStruTRB,{"TRB_STATUS"
,"C",01,0})
// aCampos padro para a MaWndBrowse
//AADD(aCampos,{<Nome_Campo>,<Picture>,<Titulo>,<Tamanho>})
// aCampos melhorado para a WndBrwTRB
//AADD(aCampos,{<Nome_Campo>,<Picture>,<Titulo>,<Tamanho>,<Tipo>,<cWhen>,<lObrig
//atorio>})
// Nota: lObrigatorio deve ser sempre a ultima informacao do aCampos
AADD(aCampos,{"TRB_FILIAL"
AADD(aCampos,{"TRB_ID"
AADD(aCampos,{"TRB_NOME"
AADD(aCampos,{"TRB_IDADE"
AADD(aCampos,{"TRB_STATUS"

,"@!" ,"Filial"
,"@!" ,"Matricula"
,"@!" ,"Nome"
,"@E 999","Idade"
,"@!" ,"Status"

,02,"C",".F.",.T.})
,14,"C",".F.",.T.})
,20,"C",".T.",.F.})
,03,"N",".T.",.F.})
,01,"C",".T.",.T.})

If ( Select( "TRB" ) <> 0 )


dbSelectArea ( "TRB" )
dbCloseArea ()
Endif
//
// Crio arq. de trab. p/ gravar as inconsistencias.

//
cArqTrb
:= CriaTrab(aStruTRB,.t.)
dbUseArea(.T.,,cArqTrb,"TRB",.T.,.F.)
cChave
:= "TRB_FILIAL+TRB_ID"
IndRegua("TRB",cArqTrb,cChave,,,"Selecionando Registros...")

- 192 ADVPL Avanado

dbSelectArea( "TRB" )
MaWndBrowse(aSize[7],aSize[2],aSize[6],aSize[5],cTitulo,cAlias,aCampos,aRotina,,
cTopFun,cBotFun,lCentered,,nModelo,,cSeek,lDic,lSavOrd)
If ( Select( "TRB" ) <> 0 )
dbSelectArea ( "TRB" )
dbCloseArea ()
Endif
Return

6.1.1. Enchoice para Arquivos Temporrios


Para aproveitar inteiramente o recurso da MaWndBrowse utilizada com arquivos
temporrios, necessrio implementar uma funo do tipo Enchoice para realizar as
operaes de Visualizar, Incluir, Alterar e Excluir os registros deste arquivo / tabela.
Com foco nesta necessidade, foi desenvolvida para o curso de ADVPL a funo
TEnchoice.


Descrio: Funo para manipulao de registros de um arquivo temporrio simular a


Enchoice do ambiente Protheus.

Sintaxe: TEnchoice(oDlg, aCampos, nLeftE, nTopE, nHeightE, nWidthE, lEnchBar)

Parmetros:
oDlg
aCampos
nLeftE
nTopE
nHeightE
nWidthE
lEnchBar

Objeto Dialog no qual a TEnchoice ser vinculada


Estrutura de campos para exibio da tela da TEnchoice
Coordenada horizontal em pixels.
Coordenada vertical em pixels.
Altura em pixels
Largura em pixels.
Se a enchoice ser montada em conjunto com uma barra de
botes do tipo Enchoicebar()

Pr-requisitos da funo chamadora:


Para correta utilizao da funo TEnchoice so necessrios os seguintes tratamentos /
definies na funo chamadora:

 Tratamento 01: Montagem do array aCampos


O array aCampos utilizado pela TEnchoice possui basicamente o mesmo formato do
array utilizado pela funo Modelo2().
"<Variavel>"
{nLinha,nColuna}
"<Titulo>"
"<Picture>"
"<Validacao>"
"<F3>"

Nome da varivel Private que est vinculada ao campo


digitvel.
Posio em pixels do campo na Enchoice.
Ttulo do campo.
Picture de formatao do campo.
Validao do campo digitvel.
Consulta F3 vinculada ao campo.
- 193 ADVPL Avanado

"<lWhen>"
<Tamanho>

AADD(aCposEnch,

Se o campo est editvel.


Tamanho do campo para visualizao.

{"<Variavel>"
,{nLinha,nColuna} ,"<Titulo>",;
"<Picture>", "<Validacao>", "<F3>", "<lWhen>",;
<Tamanho>})

 Tratamento 02: Definio das dimenses da TEnchoice


Os parmetros de dimenso da TEnchoice no precisam se informados, pois ela ir se
ajustar ao tamanho do objeto Dialog ao qual for vinculado, caso o objetivo seja que a
TEnchoice ocupe toda a rea disponvel do objeto.
importante especificar se o Dialog ir conter uma EnchoiceBar() para que a
TEnchoice() seja posicionada adequadamente no objeto.


Aparncia:

Detalhamento da funo TEnchoice:


- 194 ADVPL Avanado

/*/
+----------------------------------------------------------------------| Funo
| TEnchoice
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
Static Function TEnchoice(oDlg, aCampos, nLeftE, nTopE, nHeightE, nWidthE,;
lEnchBar)
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aSays
aGets
cCaption
cPict
cValid
cF3
cWhen
cBlKSay
cBlkGet
cBlKVld
cBlKWhen
nLeft
nTop
nI

:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=

{}
{}
""
""
""
""
""
""
""
""
""
0
0
0

Default lEnchBar := .F.


Default
nLeftE
:= IIF(lEnchBar,(oDlg:nLeft)+16,2)
Default
nTopE
:= 2
Default
nHeightE
:= (oDlg:nHeight)-135
Default nWidthE
:= (oDlg:nWidth)-102
// Padrao Modelo2(), com lWhen -> cWhen
// AADD(aC,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
If Len(aCampos) > 0
oScroll := TScrollBox():New(oDlg, nLeftE, nTopE, nHeightE , nWidthE, .T.,;
.T., .T.)
For nI:=1 to Len(aCampos)
If Len(aCampos[nI])==8
cCampo
:= aCampos[nI,1]
nLeft := aCampos[nI,2,1]-13
nTop := aCampos[nI,2,2]
cCaption:= Iif(Empty(aCampos[nI,3]), " "
cPict := Iif(Empty(aCampos[nI,4]), Nil
cValid
:= Iif(Empty(aCampos[nI,5]),
cF3
:= Iif(Empty(aCampos[nI,6]),
cWhen := Iif(Empty(aCampos[nI,7]), ".T."
nWidthG

,aCampos[nI,3])
,aCampos[nI,4])
".t." ,aCampos[nI,5])
NIL
,aCampos[nI,6])
,aCampos[nI,7])

:= Iif(Empty(aCampos[nI,8]), 100,;
IiF(aCampos[nI,8]*3.5 > 100,100,nil))
- 195 ADVPL Avanado

cBlKSay := "{|| OemToAnsi('"+cCaption+"')}"


cBlkGet := "{ | u | If( PCount() == 0,;
"+cCampo+","+cCampo+":= u ) }"
cBlKVld := "{|| "+cValid+"}"
cBlKWhen := "{|| "+cWhen+"}"
AADD(aSays,Array(1))
aSays[nI] := TSay():New(nLeft+1, nTop, &(cBlkSay), oScroll,,,;
.F., .F., .F., .T.,,, 50, 8, .F., .F., .F., .F.,;
.F. )
AADD(aGets,Array(1))
aGets[nI] := TGet():New( nLeft, nTop+50, &(cBlKGet), oScroll,;
nWidthG, 11, cPict, &(cBlkVld),,,, .F.,, .T.,,;
.F., &(cBlkWhen), .F., .F.,, .F., .F. , cF3,;
(cCampo))
EndIf
Next
Endif
Return

- 196 ADVPL Avanado

Exemplo: Funo TVisual ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TVisual
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TVisual(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
:= {||oDlg:End()}
bCancel
:= {||oDlg:End()}
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}
For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".F.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
TEnchoice(oDlg, aCposEnch,,,,,.T.)
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN

- 197 ADVPL Avanado

Exemplo: Funo TInclui ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TInclui
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TInclui(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
aArea
:= GetArea()
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}
For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".T.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
Do Case
Case aCampos[nX][5] == "C"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "N"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "D"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "L"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "M"
&("_"+aCampos[nX][1])
EndCase

:= Space(aCampos[nX][4])
:= 0
:= CTOD("")
:= .F.
:= Space(aCampos[nX][4])

Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)

- 198 ADVPL Avanado

TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
(U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN
Exemplo: Funo TAltera ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TAltera
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TAltera(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
aArea
:= GetArea()
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}
For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",aCampos[nX][6],aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
- 199 ADVPL Avanado

TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
(U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN

Exemplo: Funo TExclui ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TExclui
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TExclui(cAlias, nReg, nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}
For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".F.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
- 200 ADVPL Avanado

TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
(U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN
Exemplo: Funo TValid ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TValid
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TValid(cAlias,nReg,nOpc,aCampos)
LOCAL lRet
LOCAL nX
LOCAL nPosObrig := Len(aCampos[1])
For nX := 1 to Len(aCampos)
IF aCampos[nX,nPosObrig] == .T.
IF !(lRet := !Empty(&("_"+aCampos[nX,1])))
Help("TEnchoice",1,"HELP","OBRIGATORIO","Existem campos
obrigatorios nao preenchidos",1,0)
RETURN lRet // EXIT
ENDIF
ENDIF
Next nX
IF nOpc == 3
IF !(lRet := !((cAlias)->(dbSeek(_TRB_FILIAL+_TRB_ID))))
Help("TEnchoice",1,"HELP","INCLUSAO","Ja existe um registro com esta
chave",1,0)
ENDIF
ELSE
IF !(lRet := (cAlias)->(dbSeek(_TRB_FILIAL+_TRB_ID)))
Help("TEnchoice",1,"HELP","ALTERACAO","Nao existe um registro com
esta chave",1,0)
ENDIF
ENDIF
RETURN lRet

- 201 ADVPL Avanado

Exemplo: Funo TGravar ( MaWndBrowse com TEnchoice)

/*/
+----------------------------------------------------------------------| Funo
| TGravar
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TGravar(cAlias,nReg,nOpc,aCampos)
LOCAL nX
RecLock(cAlias,nOpc==3)
IF nOpc == 5
DbDelete()
ELSE
For nX := 1 to Len(aCampos)
(cAlias)->&(aCampos[nX][1]) := &("_"+aCampos[nX][1])
Next nX
ENDIF
Msunlock()
RETURN

- 202 ADVPL Avanado

6.2. DbTree()


Descrio: Classe Advpl que permite a criao de um objeto visual do tipo Tree.

Propriedades:
bChange

Armazena o code-block executado quando da mudana de


foco entre elementos do Tree atual.

Mtodos principais:
New

Contrutor da Classe DbTree.


Retorna uma nova instncia do Objeto da Classe DbTree.
Atravs do mtodo AddTree, possvel acrescentar um 'n'
na rvore atual.

AddTree

Uma vez acrescentado o n, as prximas incluses de itens


na parvore sero realizadas neste n, at que o mesmo
seja fechado atravs do mtodo EndTree.

AddTreeItem

Atravs dele, podemos acrescentar itens na rvore atual ou


ltimo n acrescentado em aberto.

EndTree

Deve ser utilizado aps todos os elementos e itens serem


acrescentados a um n da rvore, aberto com o mtodo
AddTree().

Aparncia:

- 203 ADVPL Avanado

Mtodo: New()


Sintaxe: DbTree():New ( [ nTop ] , [ nLeft ] , [ nBottom ] , [ nRight ] , [oWnd] ,


[ bchange ] , [ bRClick ] , [ lCargo ] , [ lDisable ] )

Parmetros:
nTop
nLeft
nBottom
nRight
oWnd
bchange
bRClick

lCargo

lDisable

Coordenada vertical superior do Objeto.


Coordenada horizontal esquerda do Objeto.
Coordenada vertical inferior do Objeto.
Coordenada horizontal direita do Objeto.
Janela pai do Objeto Tree
Code-Block contendo a ao a ser edxecutada na mudana
de foco enrte os elementos da rvore.
Code-Block a ser executado quando pressionado o boto
direito do Mouse sobre um elemento da rvoew.
Se .T., indica que os elementos do Tree utilizaro a
propriedade CARGO, capaz de armazenar uma string
identificadora, fornecida na montagem para cada elemento
e item da rvore.
Se .T., cria o objeto do Tree desabilitado, no permitindo
foco e navegao no mesmo qneuando ele no seja
habilitado.

Retorno:
Objeto

Retorna uma nova instncia do Objeto da Classe DbTree.

Mtodo: AddTree()


Sintaxe: oObj:AddTree ( < cLabel > , [ lPar02 ] , [ cResOpen ] , [ cResClose ] ,


[ cBMPOpen ] , [ cBMPClose ] , [ cCargo ] )

Parmetros:
cLabel
lPar02
cResOpen
cResClose

cBMPOpen

Ttulo do "n" da rvore a ser acrescentado.


(reservado)
Resource do RPO a ser utilizado quando o n estiver
aberto.
Resource do RPO (bitmap) a ser utilizado quando o n
estiver fechado.
Path + Imagem bitmap a ser utilizada quando o n[o estiver
aberto.
A especificao de imagens a partir dos parametros
cBMPOpen e cBMPClose apenas ser considerada caso os
parmetros cResOpen e cResClose no forem
especificados.
Path + Imagem bitmap a ser utilizada quando o n estiver
fechado.

cBMPClose
A especificao de imagens a partir dos parametros
cBMPOpen e cBMPClose apenas ser considerada caso os
- 204 ADVPL Avanado

cCargo

parmetros cResOpen e cResClose no forem


especificados.
String com valor nico, fornecido para identificar o n
atual. Pode ser recuperado posteriormente durante a
navegao.

Retorno:
Nenhum

Mtodo: AddTreeItem()


Sintaxe: oObj:AddTreeItem ( <cLabel> , [cResource] , [cBitMap] , [cCargo] )

Parmetros:
cLabel
cResource

Ttulo do item da rvore.


Resource (BMP) do repositrio, a ser mostrado esquerda
do ttulo do item.
Arquivo de imagem (bitmap) a ser mostrado esquerda do
ttulo do item.

cBitMap

cCargo


Este parm,etro apenas ser considerado caso o parmetro


cResource no for informado.
atravs dele, podemos especificar uma string de
identificao para este item na rvore.

Retorno:
Nenhum

Mtodo: EndTree()


Sintaxe: oObj:EndTree ( )

Parmetros:
Nenhum

Retorno:
Nenhum

- 205 ADVPL Avanado

Exemplo:

#include "Protheus.ch"
/*/
+----------------------------------------------------------------------| Funo
| TDBTree
| Autor | MICROSIGA
| Data |
|
+----------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo DbTree
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
User Function TDBTree()
Local cBmp1 := "PMSEDT3"
Local cBmp2 := "PMSDOC"
Private cCadastro := "Meu Computador"
Private oDlg
Private oDBTree
DEFINE MSDIALOG oDlg TITLE cCadastro FROM 0,0 TO 240,500 PIXEL
oDBTree := dbTree():New(10,10,95,240,oDlg,{|| U_Proc(oDBTree:GetCargo())},;
,.T.)
oDBTree:AddTree("Pentium 4"+Space(24),.T.,cBmp1,cBmp1,,,"1.0")
oDBTree:AddTreeItem("Gabinete",cBmp2,,"1.1")
oDBTree:AddTreeItem("Monitor" ,cBmp2,,"1.2")
oDBTree:AddTreeItem("Teclado" ,cBmp2,,"1.3")
oDBTree:AddTreeItem("Mouse",cBmp2,,"1.4")
oDBTree:AddTreeItem("Som",cBmp2,,"1.5")
oDBTree:AddTree("Placa Me",.T.,cBmp1,cBmp1,,,"2.0")
oDBTree:AddTreeItem("Processador",cBmp2,,"2.1")
oDBTree:AddTreeItem("Memria" ,cBmp2,,"2.2")
oDBTree:AddTreeItem("Vdeo",cBmp2,,"2.3")
oDBTree:AddTreeItem("Fonte",cBmp2,,"2.4")
oDBTree:EndTree()
oDBTree:EndTree()
DEFINE SBUTTON FROM 107,213 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg
ACTIVATE MSDIALOG oDlg CENTER
Return

- 206 ADVPL Avanado

User Function Proc(cCargo)


Local cRet := ""
If
cCargo == "1.1"
MsgInfo("Gabinete Torre com 4 baias - Preto, com unidade de leitura e+;
gravao de CD/DVD",cCadastro)
Elseif cCargo == "1.2"
MsgInfo("Monitor LCD 17' - LG",cCadastro)
Elseif cCargo == "1.3"
MsgInfo("Teclado multimdia com funes de internet e e-mail",cCadastro)
Elseif cCargo == "1.4"
MsgInfo("Mouse Optico sem fio",cCadastro)
Elseif cCargo == "1.5"
MsgInfo("2 Caixas de Som - 50W RMS Cada",cCadastro)
Elseif cCargo == "2.1"
MsgInfo("Processador Pentium 4 - 3.8 Ghz",cCadastro)
Elseif cCargo == "2.2"
MsgInfo("1 Pente de Memria de 1Gb - DDR 500",cCadastro)
Elseif cCargo == "2.3"
MsgInfo("Placa de Vdeo GeoForce 5000 com 256Mb",cCadastro)
Elseif cCargo == "2.4"
MsgInfo("Fonte de Alimentao de 500W",cCadastro)
Endif
Return

- 207 ADVPL Avanado

6.3. MsSelect()


Descrio: A classe MsSelect cria um objeto browse (ou grid), com a primeira coluna
sendo do tipo marcao.

Propriedades:
oWnd
oBrowse

Mtodos principais:
New

Objeto pai da MsSelect (MSDIALOG, MSWINDOW,


MSPANEL)
Objeto browse (ou grid) da MsSelect, herdado da classe
TCBROWSE

Contrutor da Classe MsSelect.


Retorna uma nova instncia do Objeto da Classe MsSelect.

Aparncia:

- 208 ADVPL Avanado

Mtodo: New()


Sintaxe: MsSelect():NEW ( < cAlias > , [ cCampo ] , [ cCpo ] , [ aCampos ] , [


lInv ] , [ cMar ] , [ aCord ] , [ cTopFun ] , [ cBotFun ] , [ oWnd ] , [
reserved ] , [ aColors ] )
Parmetros:
cAlias
cCampo
cCpo

aCampos

lInv
cMar

aCord

cTopFun

cBotFun

oWnd
reserved

aColors

Tabela que ser utilizada pela MsSelect


Campo que ser utilizado na coluna de marcao
Campo da tabela informada pelo parametro cAlias ou
funo que ser executada na apresentao da coluna que
indica se a linha da MsSelect esta habilitada ou no
Vetor com informaes dos campos para criao das
colunas da MsSelect. Se no for informado, a MsSelect ir
criar as colunas baseado no Dicionrio de Campos (SX3) da
tabela informada no parametro cAlias.
Formato:
1 - campo ou bloc de cdigo com contedo que ser
apresentado na coluna pela MsSelect
2 - no utilizado
3 - cabealho
4 - mcara de apresentao (picture)
Indica se MsSelect ir utilizar marcao invertida
Marca que ser utilizada pela MsSelect para controle do
campo informado pelo parametro cCampo. Para utilizar o
parametro cMar, utilize a funo GetMark para retornar a
prxima marca.
Coordenadas para criao da MsSelect.
Formato:
1 - Linha inicial
2 - Coluna inicial
3 - Linha final
4 - Coluna final
Funo que retornar o contedo inicial que a MsSelect
utilizar para apresentar a primeira linha da tabela, como
um range, junto com o parametro cBotFun.
O contedo retornado ser utilizado para fazer o
posicionamento da tabela informada pelo parametro cAlias,
baseado na chave de ndice posicionada para a mesma.
Funo que retornar o contedo final que a MsSelect
utilizar para apresentar a ltima linha da tabela, como um
range, junto com o parametro cTopFun.
O contedo retornado ser utilizado para o posicionamento
final da tabela informada pelo parametro cAlias, baseado
na chave de ndice posicionada para a mesma
Objeto pai da MsSelect (MSDIALOG, MSWINDOW,
MSPANEL, etc.)
Parametro reservado
Vetor com regras para a apresentao da coluna de
legenda.
Formato:
1 - Expresso ADVPL com retorno lgico que indica se a
cor ser utilizada pela coluna
2 - cor da coluna:
- 209 ADVPL Avanado

BR_AMARELO
BR_AZUL
BR_BRANCO
BR_CINZA
BR_LARANJA
BR_MARROM
BR_PINK
BR_PRETO
BR_VERDE
BR_VERMELHO


Retorno:
Objeto

Retorna uma nova instncia do Objeto da Classe MsSelect.

Exemplo:

DEFINE MSDIALOG oDlg1 TITLE "Selecao para Transferencia" From 9,0 To 32,80;
OF oMainWnd
@1.4,.8 Say "Valor Total:"
@1.4, 7 Say oValor
VAR nValor Picture "@E 999,999,999,999.99"
@1.9,.8 Say "Quantidade:"
@1.9, 9 Say oQtda
VAR nQtdBem Picture "@E 99999" SIZE 50,10
@1.4,15 Say Iif(MVParBox01==1,;
"Somente grupos de ["+MVParBox02+"] ate ["+MVParBox03+"]","")
If cTipoDet == "D"
@12.4,01 Say "Qtde. a Detalhar"
@158,60 MSGET nQtde Picture "@E 999" SIZE 036, 10 OF oDlg PIXEL;
VALID nQtde > 0
ElseIf cTipoDet == "P"
@12.4,01 Say oLabel Var cLabel := "Tipo de Projeto"
oRad := TRadMenu():New(169,005,{"Industrial","Florestal"},;
bSetGet(nOpcRad),oDlg,,{|| AF250RAD(nOpcRad)},,,,,,100,12,,,,.T.)
@15.5,01 Say oLabel2 Var cLabel2 := "Detalhamento:"
oRad2 := TRadMenu():New(210,005,{"Manter","Alterar"},;
bSetGet(nOpcRad2),oDlg,,{|| AF250RAD2(nOpcRad2)},,,,,,;
100,12,,,,.T.)
@16.4,01 Say oLabel3 Var cLabel3 := "Percentual"
oGet := TGet():New(210,043,bSetGet(nPerc),oDlg,030,010,;
"@E 999.99",,,,,,,.T.)
@18.2,01 Say oLabel4 Var cLabel4 := "Qtde. Det."
oGet2 := TGet():New(235,040,bSetGet(nQtde),oDlg,030,010,;
"@E 999",,,,,,,.T.)
oGet:Hide()
oGet2:Hide()
oLabel3:Hide()
oLabel4:Hide()
EndIf
oMark := MsSelect():New("SN3","N3_OK","!N3_BAIXA",,@lInverte,;
@cMarca,{35,1,143,315})
oMark:bMark := {| | a250Display(cMarca,lInverte,oValor,oQtda)}
ACTIVATE MSDIALOG oDlg1
ON INIT EnchoiceBar(oDlg1,;
{|| nOpct:=1,iif(DeParaEnt(),oDlg1:End(),.f.)},{|| nOpct:=2,oDlg1:End()})

- 210 ADVPL Avanado

7. Introduo relatrios grficos


7.1. TReport()
7.1.1. Introduo
Finalidade

O Protheus oferece o recurso personalizao para alguns relatrios de cadastros e


movimentaes do sistema. Ele tem como principais funcionalidades a definio de cores,
estilos, tamanho, fontes, quebras, mscara das clulas para cada seo, criao de frmulas e
funes (Soma, Mdia, etc.), possibilidade de salvar as configuraes por usurio e criao de
grficos.
Com a funcionalidade de Relatrios Personalizveis, o usurio pode modificar os relatrios
padres, criando seu prprio layout.

Vale lembrar que nem todos os relatrios so personalizveis. Por exemplo, relatrios que
tenham layout pr-definidos por lei e formulrios (boletos, notas-fiscais, etc) no podero ser
alterados.
Os relatrios personalizados so gravados com extenso .PRT, diferenciando-se dos relatrios
padres que recebem a extenso .##R.

- 211 ADVPL Avanado

Descrio
O TReport uma classe de impresso que substitui as funes SetPrint, SetDefault,
RptStatus e Cabec.
A classe TReport permite que o usurio personalize as informaes que sero apresentadas no
relatrio, alterando fonte (tipo, tamanho, etc), cor, tipo de linhas, cabealho, rodap, etc.
Estrutura do componente TReport:
O relatrio (TReport) contm 1 ou mais sees (TRSection);
Uma seo (TRSection) pode conter 1 ou mais sees;
A seo (TRSection) contm clulas pr-definidas e clulas selecionadas pelo usurio;
A seo (TRSection) tambm contm as quebras (TRBreak) para impresso de
totalizadores (TRFunction);
Os totalizadores so includos pela seo que automaticamente inclui no relatrio
(TReport).

Pr-Requisitos
Para utilizar o TReport, verifique se o seu repositrio est com o Release 4 do Protheus-8, ou
verso superior.
A funo TRepInUse() verifica se a lib do TReport est liberada no repositrio em uso. O
retorno uma varivel lgica.
#include "protheus.ch"
User Function MyReport()
Local oReport
If TRepInUse()
//verifica se a opo relatrios personalizveis est
disponvel
Pergunte("MTR025",.F.)
oReport := ReportDef()
oReport:PrintDialog()
EndIf
Return
Verifique tambm o parmetro MV_TReport. Para utilizar os relatrios personalizveis, o
parmetro MV_TREPORT (tipo numrico) deve ser alterado no ambiente Configurador,
conforme uma das opes que seguem:
1 = utiliza relatrio no formato tradicional (antigo);
2 = utiliza relatrio personalizvel;
3 = pergunta qual relatrio ser utilizado: tradicional (antigo) ou personalizvel.

- 212 ADVPL Avanado

7.1.2. Impresso do relatrio personalizvel


Cada componente da tela de impresso do TReport, deve ser configurado no programa, para
que o usurio tenha acesso s personalizaes:

7.1.2.1.

Parmetros de impresso

A caixa de listagem apresentada deve ser utilizada conforme o meio de sada do relatrio. Veja
a seguir.

Impresso
Arquivo

O relatrio ser gravado em disco com o nome apresentado. Caso seja escolhida a opo
"Servidor" ele ser gravado no diretrio determinado na senha do usurio, atravs do
configurador, sendo este sempre no servidor (padro \SPOOL\). Na escolha da opo "Local"
ser aberta uma janela para que seja escolhido o local onde o relatrio ser gravado na
mquina do usurio.
O relatrio gerado a partir desta opo pode ser impresso ou enviado por e-mail aps ser
apresentado na tela.

- 213 ADVPL Avanado

Spool
Direciona o relatrio para impresso via configurao do Windows das impressoras
instaladas.
E-mail
Envia o relatrio por e-mail (Internet). Para isto, devem ser configurados os seguintes
parmetros no Ambiente Configurador:
 MV_RELACNT
Define a conta de e-mail para identificar
Exemplo: relprotheus@microsiga.com.br

provenincia

dos

relatrios.

do

relatrio.

 MV_RELPSW
Define a senha da conta de e-mail para envio dos relatrios.
 MV_RELSERV
Define
o
servidor
da
conta
Exemplo: smtp.microsiga.com.br

de

e-mail

para

envio

Quando selecionada esta opo, deve-se informar, no campo em destaque na figura abaixo, o
e-mail para o qual o relatrio deve ser remetido.

- 214 ADVPL Avanado

O Protheus Server pode tambm ser executado como um servidor Web, respondendo a
requisies HTTP. No momento destas requisies, pode executar rotinas escritas em ADVPL
como processos individuais, enviando o resultado das funes como retorno das requisies
para o cliente HTTP (como por exemplo, um Browser de Internet). Qualquer rotina escrita em
ADVPL que no contenha comandos de interface pode ser executada atravs de requisies
HTTP. O Protheus permite a compilao de arquivos HTML contendo cdigo ADVPL embutido.
So os chamados arquivos ADVPL ASP, para a criao de pginas dinmicas.


Programao TelNet

TelNet parte da gama de protocolos TCP/IP que permite a conexo a um computador remoto
atravs de uma aplicao cliente deste protocolo. O PROTHEUS Server pode emular um
terminal TelNet, atravs da execuo de rotinas escritas em ADVPL. Ou seja, pode-se escrever
rotinas ADVPL cuja interface final ser um terminal TelNet ou um coletor de dados mvel.

Papel
Tamanho do papel
Selecione o tamanho do papel em que o relatrio ser impresso.

As especificaes de tamanho do papel so as do padro do mercado,


conforme o formato escolhido, o Protheus ir ajustar a impresso.
Formato da impresso
Selecione o formato de impresso, clicando nos botes de opo Retrato ou Paisagem,
fazendo assim que o relatrio seja impresso na orientao vertical ou horizontal,
respectivamente.
Configuraes
Ttulo
Caso queira alterar a opo sugerida pelo sistema, digite o cabealho do relatrio.
Ordem
Escolha a ordem em que as informaes sero apresentadas no relatrio, clicando em uma das
chaves disponveis.
Layout
Permite selecionar o modelo de relatrio para impresso, medida que novos leiautes forem
gravados para um relatrio, seus nomes sero listados nessa caixa.
Preview
Faz a exibio do relatrio gerado na tela, possibilitando, na seqncia, o seu envio para
impressora ou a cancelamento da impresso.

- 215 ADVPL Avanado

Executar em segundo plano


Essa opo permite que o relatrio seja gerado e enviado para a fila de impresso, enquanto o
usurio pode executar outras tarefas no sistema.

7.1.3. Personalizao
possvel configurar-se as colunas do lay-out do relatrio, bem como os acumuladores,
cabealhos e linhas.
Esto disponveis para personalizao tambm a fonte, tamanho, cores, e etc.

7.1.3.1.

Editando o layout do relatrio

O primeiro passo entender a nova estrutura dos relatrios desenvolvidos com a ferramenta
TReport.
O Relatrio possui Sees e Clulas. chamada de Seo, cada um dos grupos de
informaes, e de Clula, cada um dos campos que sero impressos.

- 216 ADVPL Avanado

Nova estrutura do relatrio TReport:

O relatrio mais simples que se consegue emitir em TReport, uma listagem.

7.1.4. Definindo a Funo ReportDef()


A funo ReportDef() responsvel pela construo do lay-out do relatrio (oReport). ela
quem define as colunas, os campos e as informaes que sero impressas.
Os comandos que far essa construo so:

1. DEFINE REPORT
2. DEFINE SECTION
3. DEFINE CELL

- 217 ADVPL Avanado

DEFINE REPORT

A funo DEFINE REPORT responsvel pela criao do objeto Report, ou seja, o relatrio.
Internamente, o DEFINE REPORT ir executar o mtodo TReport():New().
Estrutura do componente TReport:

O relatrio (TReport) contm 1 ou mais sees (TRSection);


Uma seo (TRSection) pode conter 1 ou mais sees;
A seo (TRSection) contm clulas pr-definidas e clulas selecionadas pelo usurio;
A seo (TRSection) tambm contm as quebras (TRBreak) para impresso de
totalizadores (TRFunction);
Os totalizadores so includos pela seo que automaticamente inclui no relatrio
(TReport).

DEFINE SECTION

Ainda no ReportDef(), so definidas as sees (oSection) do relatrio.


As sees do relatrio representam os diferentes grupos de informaes exibidos.
H a seo principal e as especficas.
Internamente, o DEFINE SECTION ir executar o mtodo TRSection():New().
A classe TRSection pode ser entendida como um layout do relatrio, por conter clulas,
quebras e totalizadores que daro um formato para sua impresso.
Com a classe TRSection possvel definir uma query, filtro ou ndice com filtro (IndRegua) que
ser utilizada por ela para processamento do relatrio, atravs do mtodo Print e utilizando as
clulas de posicionamento (TRPosition).

DEFINE CELL

Para cada seo, devem ser definidas as clulas. Clula cada informao que dever ser
impressa. Pode ser um campo do cadastro, ou um resultado de uma operao. uma Clula
de impresso de uma seo (TRSection) de um relatrio que utiliza a classe TReport
Internamente, o DEFINE CELL ir executar o mtodo TRCell():New ().

- 218 ADVPL Avanado

MDULO 08: Aplicaes ADVPL para o ERP


8. Protheus e o TOPCONNECT / TOTVS DbAccess
O TOTVSDBAccess uma ferramenta de conectividade a bases de dados, permitindo que
aplicativos acessem uma ampla variedade de servidores de banco de dados sem a necessidade
de gerao de cdigos especficos para cada uma delas.
Os bancos de dados hoje suportados pelo TOTVSDBAccess so:
 Microsoft SQL7 ou superior
 Oracle 8 ou superior
 IBM Universal Database (DB2)
 Informix
 Sybase Adaptive Server
 Postgres 7.1.1 ou superior
 MySQL
O TOTVSDBAccess permite gerenciar as informaes pertinentes utilizao do banco de
dados, registrando e apresentado dados, como:
 Dados estatsticos de forma grfica com relao :
 Quantidade de usurios conectados
 Quantidade de tabelas em utilizao
 IOs por segundo
 Mximo de IOs por segundo
 Relao dos usurios conectados
 Checagem das querys geradas pelos usurios conectados
 Quebra de conexo do usurio
 Mensagens de utilizao do TOTVSDBAccess
 Configuraes Gerais quanto a:
 Banco de dados em utilizao
 Relao de usurios e senhas por banco de dados
 Logins de usurio
 Configurao de "Table Spaces" para determinados bancos de dados
 Definio dos parmetros de criao de tabelas para determinados bancos de dados
 Validao de conexo, checando os parmetros de conexo com o banco de dados
 Monitoramento de ndices gerados

- 219 ADVPL Avanado

8.1. Caractersticas tcnicas com o uso do TOTVS DbAccess


Comportamento de Queries Colunas Calculadas
Aps enviar ao Banco de Dados uma solicitao de abertura de Query, em caso de sucesso na
operao, o TOPConnect obtm do Banco de Dados a quantidade de colunas que sero
retornadas, e qual o tamanho e tipo e especificaes de cada uma das colunas, para retornar
ao Protheus uma estrutura definida de informaes, e o cursor aberto lido conforme so
solicitados os prximos registros ( DBSkip() no Advpl ), e a cada requisio, uma linha do
cursor retornada, at no haver mais linhas no cursor, atingindo o final do arquivo no Advpl (
EOF() ).
Quando especificamos uma coluna de retorno na Query, que corresponde a informaes lidas
diretamente de uma ou mais coluna(s) da tabela, cada coluna retornada pela Query contm
uma definio de tipo e tamanho correspondente ao campo de origem do dado de retorno.
Deste modo, se considerarmos, por exemplo, a Query : SELECT A1_FILIAL FROM SA1990 ,
onde o campo A1_FILIAL na tabela SA1990 um campo do tipo varchar, com 2 bytes de
tamanho, quando o cursor for aberto no Banco de Dados, o TOPConnect ir obter do banco
que o result-set gerado possui apenas uma coluna, e esta coluna do tipo varchar, com no
mximo 2 bytes de tamanho.
Os Bancos de Dados no apenas permitem recuperar retornos diretamente lidos de uma ou
mais tabelas, mas tambm possvel abrir um cursor onde uma ou mais colunas contenham
um resultado calculado, utilizando-se de expresses e/ou funes nativas do Banco de Dados.
Para estes tipos de retorno, cada banco de dados pode apresentar comportamentos
diferenciados ao descrever o tamanho de retorno da(s) coluna(s).
Este comportamento pode variar de acordo com o Banco de Dados, a expresso e/ou funes
utilizadas para gerar a coluna de retorno, e inclusive podem ter diferenas entre verses e
Builds do mesmo Banco de Dados e/ou parametrizaes especficas do Banco de Dados e/ou
da aplicao Client / ODBC / API utilizada para acesso ao Banco.
Para ilustrar melhor estas diferenas, vejamos abaixo os resultados obtidos com queries, em
bancos distintos, onde foi criada uma tabela com a mesma estrutura, e 10 linhas de dados, e
nela foram executadas algumas querys, onde temos como retorno uma coluna calculada. A
tabela possui os campos CPOC, tipo Caractere, tamanho 10 bytes, numerados de 0000000001
a 0000000010 e um campo numrico CPON, alimentado com valores positivos. Para cada
Query, mostramos o valor retornado ao Advpl, contendo o tipo de dado retornado e o tamanho
(len) da coluna, no formato . ( Tipo ( tamanho ) ).
Query: SELECT MIN(CPOC) CPOTESTE FROM TESTRET


Retorno: Todos os bancos retornaram uma coluna com tamanho de 10 bytes.

Bancos:
Database
MSSQL 2000
INFORMIX
ORACLE
MYSQL
DB2

Tipo
Caracter
Caracter
Caracter
Caracter
Caracter

Tamanho
10
10
10
10
10

- 220 ADVPL Avanado

Contedo
0000000001
0000000001
0000000001
0000000001
0000000001

Query: SELECT MIN(CPOC) CPOTESTE FROM TESTRET WHERE CPON < 0




Retorno: Todos os bancos retornaram uma coluna vazia.

Bancos:
Database
MSSQL 2000
POSTGRES
INFORMIX
ORACLE
MYSQL
DB2

Tipo
Caracter
Caracter
Caracter
Caracter
Caracter
Caracter

Tamanho
10
0
10
10
10
10

Contedo
Vazio
Vazio
Vazio
Vazio
Vazio
Vazio

Query: SELECT LEFT(CPOC,5) CPOTESTE FROM TESTRET




Retorno: Todos os bancos que suportam a funo LEFT() retornaram uma coluna
de informaes, onde os 5 primeiros bytes eram '00000'.

Observaes: Os bancos retornaram que a coluna tem 5 bytes de tamanho.


Porm, o BAnco DB2 informa que a coluna tm tamanho de 4000 Bytes.
Este mesmo retorno foi obtido no DB2 quando utilizadas funes
RIGHT(), REPLACE() e REPEAT(), no banco DB2, e para o BAnco
Postgres, foi retornado o tamanho de 2000 bytes para estas funes.

Bancos:
Database
MSSQL 2000
MYSQL
DB2

Tipo
Caracter
Caracter
Caracter

Tamanho
5
5
4000

Contedo
00000
00000
00000

Query: SELECT SUBSTRING(CPOC,2,4) CPOTESTE FROM TESTRET




Retorno: Todos os bancos retornaram uma coluna de tamanho 4 bytes, exceto o


POSTGRES, que retornou tamanho de 2000 bytes.

Bancos:
Database
MSSQL 2000
POSTGRES
INFORMIX
ORACLE
MYSQL
DB2

Tipo
Caracter
Caracter
Caracter
Caracter
Caracter
Caracter

Tamanho
4
2000
4
4
4
4

- 221 ADVPL Avanado

Contedo
0000
0000
0000
0000
0000
0000

Devido a estas diferenas de comportamento, devemos tomar alguns cuidados ao desenvolver


aplicaes que utilizam colunas calculadas em queries. Nestes casos, deve ser utilizada uma
funo do banco de dados, para assegurar que o banco de dados retorne o tamanho de coluna
adequado ao TOPConnect / TotvsDBAccess.
Por exemplo, vejamos a query abaixo :

SELECT REPLACE(CPOC,'0','_') AS CPOTESTE FROM TESTRET

Se j de conhecimento do programador que o campo da base de dados CPOC desta tabela


tem 10 bytes de tamanho, devemos fazer um cast deste retorno, para char ou varchar, com
tamanho de 10 bytes. Dessa forma, o banco retorna o tamanho esperado da coluna para o
TOPConnect quando da abertura da query. Isto evita que espaos desnecessrios trafeguem
pela rede para atender requisio, e que este valor excedente seja usado para alimentar
uma varivel do Advpl. Vejamos como usar este recurso na query acima descrita, utilizando
uma sintaxe aceita pela maioria dos Bancos de Dados homologados :

SELECT CAST( REPLACE(CPOC,'0','_') AS VARCHAR(10)) CPOTESTE FROM TESTRET

Vale a pena salientar que, cada banco de dados possui, com pequenas variaes, uma sintaxe
para permitir o CAST de um retorno. Para maiores detalhes, a documentao do banco deve
ser consultada.
Comportamento diferenciado com Bandos de Dados PostGres
O Banco de Dados Postgres possuem um comportamento diferenciado entre os Builds do
Server do Banco, e possui uma parametrizao na configurao do ODBC que pode interferir
na maneira como os atributos das colunas de retorno de uma query so retornados.
Em verses inferiores o Postgres 8.x, as diferenas de comportamento em relao os demais
Bancos de Dados possuem um diferencial muito significativo, em praticamente todas as
funes de retorno calculado. Para estes casos, em se tratando de Postgres verses inferiores
a 8.x, a preciso de retorno da coluna corresponde ao tamanho mximo de retorno do tipo
VarChar. ( Este tamanho mximo pode ser configurado na conexo ODBC do PostgreSql, e o
valor default 65536 bytes. )
Na funo Substring(), mesmo que esteja especificado no 3. parmetro da funo, a
quantidade final limitada de Bytes, o Banco de Dados descreve esta coluna de retorno como
sendo um VarChar() com a preciso do maior valor VARCHAR() a ser retornado pelo client. Na
funo Max(), quando especificado um campo da base do tipo Char ou Varchar, temos um
comportamento semelhante.
Quando foram homologados os Bancos Postgres para uso com o ERP Microsiga e TOPConnect
4, praticamente no eram utilizadas queries com colunas calculadas nas aplicaes Advpl, e
este comportamento diferenciado no foi percebido. Conforme as rotinas foram evoluindo,
buscando mais performance atravs do uso de Queries, tornou-se perceptvel estas diferenas
operacionais.

- 222 ADVPL Avanado

Algumas destas diferenas operacionais foram assimiladas pelas funes do ERP, por exemplo
a ChangeQuery, que em verso atualizada (** Protheus 8 e P10, fonte aplib070.prw com data
igual ou superior a 08/03/2008) , aplicam o CAST() automaticamente para SELECT
MAX(CAMPO), quando o banco Postgres, e o campo selecionado for um campo da base de
dados, presente no Dicionrio de Campos ( SX3 ).
Para todos os efeitos, para utilizao com as verses homologadas de Postgres inferiores a
8.x, necessrio alterar a configurao de ODBC do Postgres, para limitar o retorno do tipo
VarChar para 2000 Bytes, pois o retorno do valor default ( 65536 bytes ) no suportado pelo
TOPConnect / TOTVSDBAccess. Alteramos esta configurao no arquivo .odbc.ini no linux, e/ou
no arquivo de configurao do ODBC do Postgres utilizado, inserindo na seo da conexo /
identificao do banco a chave abaixo :

MaxLongVarcharSize=2000

Atualmente est em processo de homologao as verses mais recentes (8.x) do banco


Posgres. Quando homologado, a informao estar disponivel na DEM, em Principal -> Guia de
Referncia -> Guia de Plataformas Homologadas -> Bancos de Dados Relacional X S.O.
Conceito de ndices Permanentes e Diferenas das RDDs
Na RDD TOPCONN, no temos o conceito de criao de ndice temporrio, apenas ndice
permanente. Um ndice permanente criado fisicamente no Banco de Dados relacional
utilizado, atravs do TOPConnect / DbAccess, onde devemos especificar um ou mais campos
para compor a chave / expresso de ndice.
Quando utilizamos CodeBase/DBF, podemos especificar como campos de chave de ndice o
retorno de funes, como por exemplo STR(), DTOS(), SUBSTR(), entre outras suportadas de
modo nativo pela aplicao provedora de acesso, no caso ADS Local e/ou ADS Server.
Quando usamos um Banco Relacional SGDB atravs do TOPConnect / DbAccess, devemos
especificar uma expresso de chave que sempre retorne um valor Caractere, e as nicas
funes permitidas para adequaes de tipo de dado no Advpl para estas expresses de ndice
so : DTOS() e STR().
Funcionamento Interno
A expresso utilizada para a criao de um ndice permanente em Advpl, por exemplo : CPOC
+ DTOS(CPOD) + STR( CPON,10 ), quando utilizamos o RDD TOPCONN, ser ajustada para o
Banco de Dados relacional utilizado para uma expresso contendo apenas a lista de campos
desejada, na sequncia em que foi especificada, e as funes DTOS() e STR() nao so
passadas ao banco de dados, pois no existe a necessidade de converso de dados para o
Banco.
Um campo do tipo 'D' Data tratado pelo TOPConnect e gravado na tabela em questo como
um campo 'C' Caractere, de 10 bytes, no formato AAAAMMDD, e os nmeros so gravados em
um campo DOUBLE*.

- 223 ADVPL Avanado

Quebra de Compatibilidade com CodeBase/DBF


Os Bancos relacionais, em sua grande maioria, seno todos, suportam apenas a criao de
ndices onde sejam especificados campos fsicos da base de dados. No so suportadas
funes de converso ou transformao de dados na criao de ndices, como por exemplo
substring(), left(), entre outras. Embora alguns bancos permitam a criao de colunas
calculadas, as mesmas so 'virtuais', isto , no existem fisicamente na tabela, e tambm no
permitido o uso de colunas virtuais para a criao de ndices.
Entendemos que o RDD CodeBase / DBF, onde originalmente foi desenvolvido o ERP, nos dava
certa flexibilidade ao permitir operaes como estas, porm a um custo de processamento
mais alto, pois para cada insero ou alterao, o RDD tem que executar funes de conversao
e concatenao de strings para atualizao dos ndices que usam este recurso.
Manter o suporte a todos os indices permanentes, criados a partir de resultados de
expresses, nas verses anteriores do ERP, teramos um custo muito alto de complexidade,
performance e duplicidade de informaes nas tabelas. Seria necessrio criar colunas fsicas
nas tabelas, transparentes ao usuario, para manter copias em duplicidade de partes de colunas
agrupadas, com gatilhos do banco de dados disparados internamente em operaes de insert e
update, um mecanismo relativamente complexo de se manter, instvel para dar manuteno,
e custoso em performance para o Banco de Dados.
Partindo da premissa que, se uma determinada informao deve ser indexada para busca, ela
deve ser uma informao que ocupa exclusivamente um campo fsico da base de dados, so
evitadas as operaes constantes de concatenao e desmembramento de uma informao
agrupada, colocando cada parte da informao em seu devido espao ( campo )
definido, mesmo com o impacto gerado para alterar as aplicaes que usavam estes tipos
de ndices, os ganhos obtidos em organizao e performance foram muito significativos.

- 224 ADVPL Avanado

Lista dos cdigos de erro do TOPConnect / DbAccess


Quanto utilizado o TOPConnect / DbAccess para conexo e operaes com Bancos de Dados,
as ocorrncias de erro so reportadas ao Protheus informando em conjunto com o erro um
nmero menor que zero, correspondendo a um tipo de erro.
Para a maioria das ocorrncias, relacionadas ao Banco de Dados, deve-se olhar o log de erro
gravado pelo TOPConnect / DbAccess ( arquivo topconn.log ) para obter maiores detalhes
sobre a ocorrncia.
TC_NO_ERROR
NO_ROUTER_INSTALLED
NO_CONNECTION
NO_USER_SECURITY
PASSTHRU_FAILED
NO_MORE_CONNECTIONS
INVALID_TOP_KEY
INVALID_ENVIRONMENT
INVALID_FILE
UNKNOWN_FILE
EXCLUSIVE_REQUIRED
INVALID_OPERATION
INVALID_KEY_NUM
FILE_IN_USE
TOO_MANY_FILES
INVALID_NUMRECS
CALL_FAILED
COMMAND_FAILED
OVERRIDE_FAILED
QUERY_FAILED
CREATION_FAILED
OPEN_FAILED
NOT_OPENED
NO_RECORD_FOUND
END_OF_RECORDS
NO_WRITE_POSIBLE
NO_RECORD_EQUAL
UPDATE_FAILED
DELETE_FAILED
RECORD_LOCKED
FILE_LOCKED
NO_AUTORIZATION
TOO_MANY_USERS
NO_DB_CONNECTION
NO_CONN_ALLOWED
INTEGRITY_FAILURE
BUFFER_OVERFLOW
INVALID_PARAMETERS
NO_AUDIT_CONNECTION
COMM_DOSMEM_ERROR
COMM_PARTNER_ERROR
COMM_SNDSTAT_ERROR
COMM_RCVSTAT_ERROR

0
-1
-2
-4
-5
-6
-8
-9
-10
-11
-11
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
-31
-32
-33
-34
-35
-36
-37
-40
-41
-50
-58
-67
-76
-76

COMM_INITPGM_ERROR
COMM_PARAM_ERROR
COMM_PROGRAM_ERROR
COMM_INSMEM_ERROR
INVALID_BUILD
INVALID_TOPAPI

- 225 ADVPL Avanado

-81
-86
-88
-90
-99
-100

8.2. Funes ADVPL para TOPCONNECT / TOTVS DbAccess


Neste tpico sero descritas as funes da linguagem ADVPL que permitem a interao
com a aplicao TopConnect / DbAccess.
Lista das funes de interao com a aplicao TopConnect / DbAccess:

 TCCANOPEN
 TCCONTYPE
 TCDELFILE
 TCGENQRY
 TCGETDB
 TCLINK
 TCQUERY
 TCQUIT
 TCSETCONN
 TCSETFIELD
 TCSPEXEC
 TCSPEXIST
 TCSQLERROR
 TCSQLEXEC
 TCSRVTYPE
 TCUNLINK
 TCCHKOBJ
 TCEXEERROR
 TCPGMEXE
 TCSYSEXE
Lista das funes acessrias utilizadas nos fontes como facilitadoras:

 CHANGEQUERY
 RETFULLNAME
 RETSQLCOND
 RETSQLNAME
 RETSQLTABLE
 SQLCOPY
 SQLORDER
 SQLTOTRB

- 226 ADVPL Avanado

Funes de interao com o TopConnect / DbAccess


TCCANOPEN ()
Verifica a existncia de tabelas e ndices no servidor.


Sintaxe: TCCanOpen(cTable , cIndice)

Parmetros:
cTable
cIndice

Opcional, indica o nome completo do ndice referente a tabela especificada.

Retorno:
Lgico

Nome completo da tabela no banco de dados.

Indica a existncia da tabela e/ou do ndice especificado.

Exemplo:

//Verifica a existncia da tabela customer


IF !TCCanOpen("CUSTOMER")
dbCreate("CUSTOMER", aStru, "TOPCONN")
ENDIF
USE CUSTOMER SHARED NEW VIA "TOPCONN"
//Verifica a existncia do ndice
IF !TCCanOpen("CUSTOMER","CUSTCOD")
INDEX ON CODIGO TO CUSTCOD
ELSE
SET INDEX TO CUSTCOD
ENDIF

TCCONTYPE()
Especifica o protocolo de comunicao a ser utilizado pelo TOPConnect.


Sintaxe: TCConType(cType)

Parmetros:
cType

Tipo de protocolo de comunicao a ser utilizado pelo TopConnect, aonde:


TCPIP: Utiliza o protocolo TCP/IP.
NPIPE: Utiliza o protocolo Named Pipes.
APPC: Utiliza o protocolo APPC.
BRIDGE: Utiliza o utilitrio TOPBrigde para comunicao de estaes DOS
NPIPE com servidor AS/400 utilizando TCP/IP.

- 227 ADVPL Avanado

Retorno:
Nenhum

Exemplo:

#INCLUDE "TOPCONN.CH"
//Especifica conexo TCP/IP
TCConType("TCPIP")
//Conecta-se ao ambiente SIGAADV no Microsoft SQL-Server
TCLink("MSSQL/SIGAADV")

TCDELFILE()
Exclui uma tabela no servidor.


Sintaxe: TCDelFile(cTable)

Parmetros:
cTable

Retorno:
Nenhum

Nome completo da tabela a ser excluda.

Exemplo:

TCDelFile("CUSTOMER")

- 228 ADVPL Avanado

TCGENQRY()
Permite a execuo de uma query de seleo no banco de dados e retorna um recordset com o
resultado.


Sintaxe: TCGENQRY(xParam1,xParam2,cQuery)

Parmetros:

xParam1

Parmetro reservado.

xParam2

Parmetro reservado.

cQuery

Query de seleo com sintaxe no padro SQL ANSI a ser executada no banco
de dados.

Retorno:
RecordSet contendo o resultado da execuo da query de seleo.

RecordSet

Para que os dados contidos no RecordSet retornado pela funo TCGenQry()


sejam utilizados pela aplicao ADVPL necessrio disponibiliz-los em uma
WorkArea.
Desta forma a funo TCGenQry() dever ser utilizada em conjunto com a
funo DbUseArea(), para que a mesma disponibilize o RecordSet como uma
rea de trabalho do ADVPL.

Exemplo:

cQuery := "SELECT DISTINCT CV8_PROC FROM "+RETSQLNAME("CV8")


cQuery += " WHERE "
cQuery += "CV8_FILIAL = '"+MV_PAR01+"' AND "
cQuery += "D_E_L_E_T_ = '' "
cQuery += "ORDER BY CV8_PROC"
cQuery := ChangeQuery(cQuery)
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), "CV8QRY", .F., .T.)

TCGETDB()
Retorna o tipo de Banco de Dados corrente.


Sintaxe: TCGETDB()

Parmetros:
Nenhum

- 229 ADVPL Avanado

Retorno:
Caracter

Descrio referente ao tipo do banco de dados corrente, aonde:


ANYWHERE - Sybase SQL Anywhere
ANYSYBASE - Sybase SQL Anywhere (Emulando Sybase SQL-Server)
DB2 - IBM Universal Database
INFORMIX Informix
MSSQL - Microsoft SQL-Server 6.5
MSSQL7 - Microsoft SQL-Server 7.0 ou superior
ORACLE - Oracle
POSTGRES - PostGres
SYBASE - Sybase SQL-Server
Nota: O retorno da funo pode variar de acordo com a homologao de
novos databases para utilizao com a ferrramenta TopConnect / DbAccess.

Exemplo:

cDataBase := TCGETDB() // MSSQL7

TCLINK()
Abre uma conexo com o Servidor TOPConnect.


Sintaxe: TCLink(cConectString,cServer)

Parmetros:
cConectString

String composta conforme a regra:


Para TOPConnect NT : Nome do Banco de Dados / Nome do Ambiente
Para TOPConnect/400: Nome do Ambiente

cServer

Nome do servidor conforme a regra:


Para conexes NamedPipe, APPC e Brigde : O nome do servidor
TOPConnect.
Para conexes TCP/IP : O endereo IP do servidor TOPConnect

Observaes:
 Para o TOPConnect NT acessando Oracle, um ambiente o nome do Alias criado
com o utilitrio SQL-Net.
 Para o TOPConnect NT acessando os demais SGDB's um ambiente um System
DSN criado atravs do ODBC Data Source Administrator.
 Para o TOPConnect AS/400 um ambiente uma Library criada atravs do comando
CRTTOPENV do TOPConnect.

- 230 ADVPL Avanado

 Para informaes sobre a criao de ambientes consulte o manual de instalao do


TOPConnect.
 A lista dos tipos de bancos de dados suportados pela aplicao TopConnect /
DbAccess a mesma das possibilidades de retorno da funo TCGETDB conforme
abaixo:
ANYWHERE
ANYSYBASE
DB2
INFORMIX
MSSQL
MSSQL7
ORACLE
POSTGRES
SYBASE


- Sybase SQL Anywhere


- Sybase SQL Anywhere (Emulando Sybase SQL-Server)
- IBM Universal Database
Informix
- Microsoft SQL-Server 6.5
- Microsoft SQL-Server 7.0 ou superior
- Oracle
- PostGres
- Sybase SQL-Server

Retorno:
Numrico

A funo TCLink retorna ou o nmero da conexo ou um valor negativo


contendo o cdigo do erro.
A relaes dos cdigos de erros ocorridos durante uma tentativa de conexo
est disponvel no tpico 8.1. deste material.

Exemplo:

//Conecta-se ao Microsoft SQL-Server no ambiente SIGAADV


//Protocolo Named Pipes
TCConType("NPIPE")
nCon := TCLink("MSSQL/SIGAADV","TOPSRV")
if nCon < 0 //Conexes com retorno < 0 significam erro
Alert("Falha de conexo com o TOPConnect")
endif
//Protocolo TCP/IP
TCConType("TCPIP")
//Conecta-se ao Oracle no ambiente TESTES
nCon := TCLink("ORACLE/TESTES",172.16.1.2)
//Protocolo APPC
//Conecta-se ao AS/400 no ambiente PRODUCAO
nCon := TCLink("PRODUCAO","TOP400")

- 231 ADVPL Avanado

TCQUERY()
Executa uma Query no servidor e coloca seu retorno em uma WorkArea.

Durante o processo de compilao, a sintaxe TCQUERY() substituda pelas


expresso:
dbUseArea(.T.,"TOPCONN",TcGenQry(,,cQuery), ALIAS ,.T.,.F.)
Esta substituio realizada conforme as definies do include TOPCONN.CH.
Desta forma recomendvel a utilizao direta da sintaxe DbUseArea() +
TcGeQry().

Sintaxe: TCQUERY cSQLExpr ALIAS cAlias NEW VIA "TOPCONN"

Parmetros:
cSQLExpr

Expresso SQL a ser enviada ao servidor.

ALIAS cAlias

Especifica um nome para a Work Area a ser aberta.

NEW

Abre a tabela <cTable> na prxima Work Area disponvel. Se esta


clausula no for especificada, <cTable> ser na Work Area corrente.
Este parmetro indica ao ADVPL que esta Work Area ser gerenciada
pelo TOPconnect.

VIA "TOPCONN"

Observaes:
 A Work Area criada com o comando TCQUERY READ-ONLY, portanto no
permitido o uso de APPEND's ou REPLACE's.
 O TOPConnect tem apenas um cursor para a Query executada portando apenas os
seguintes comandos so suportados em uma Work Area criada com TCQUERY:
o
o
o
o
o

GO TOP - DbGoTop()
GO BOTTOM - DbGoBottom()
SKIP - DbSkip()
Eof()
Bof()

 Ao executar uma Query que retorne um ou mais valores calculados, o nome dos
campos da WorkArea sero COLUMN1, COLUMN2... COLUMNn.


Retorno:
Nenhum

- 232 ADVPL Avanado

Exemplo:

//Abre a tabela de Clientes em uma nova WorkArea


cQuery := "SELECT a.codigo, b.nome FROM CLIENTES a, CLIDATA b "
cQuery += "WHERE a.CODIGO = b.CODIGO ORDER BY CODIGO,NOME "
TCQUERY cQuery ALIAS CLIENTES NEW VIA "TOPCONN"
dbGoTop()
While !Eof()
ALERT(CODIGO+"|"+NOME)
dbSkip()
end
cQuery := 'SELECT SUM(VALOR),SUM(SALDO) FROM CUSTOMER'
TCQUERY cQuery NEW VIA "TOPCONN"
ALERT(CValToChar(COLUMN1)+"|"+CValToChar(COLUMN2))
// COLUMN1 - Somatoria dos valores
// COLUMN2 - Somatoria dos saldos

TCQUIT()
Encerra todas as conexes com o TOPConnect.


Sintaxe: TCQuit()

Parmetros:
Nenhum

Retorno:
Nenhum

TCSETCONN()
Seleciona a conexo ativa.


Sintaxe: TCSETCONN(nConn)

Parmetros:
nConn

Nmero da conexo

Retorno:
Nenhum

- 233 ADVPL Avanado

Exemplo:

// Abre conexo com o ambiente de Produo


nCon1 := TCLink("MSSQL/PRODUCAO")
if nCon1 < 0
Alert("Falha conectando ambiente de Produo")
QUIT
endif
// Abre conexo com o ambiente de Testes
nCon2 := TCLink("MSSQL/TESTES")
if nCon2 < 0 then
Alert("falha conectando ambiente de Testes")
QUIT
endif
TCSetConn(nCon1)
//Abre tabela de Clientes no ambiente de produo
USE CUSTOMER ALIAS PROD SHARED NEW VIA "TOPCONN"
TCSetConn(nCon2)
//Abre tabela de Clientes no ambiente de testes
USE CUSTOMER ALIAS TEST SHARED NEW VIA "TOPCONN"
...

TCSETFIELD()
Esta funo serve como apoio ao comando TCQUERY, na recuperao de campos tipo
NUMERIC, DATE e LOGICAL, pois os mesmos so gravados fisicamente no Banco de Dados
como caracteres, e no caso dos numricos como float.


Sintaxe: TCSetField(cAlias, cField ,cType, nTam, nDec )

Parmetros:

cAlias

Alias da WorkArea gerada pela execuo da query.

cField

Nome do campo a ser tratado

cType

Tipo desejado para o campo

nTam

Tamanho total desejado para o campo

nDec

Nmero de decimais desejado para o campo

Retorno:
Nenhum

- 234 ADVPL Avanado

Exemplo 01:

TCQUERY "SELECT NOME, DATA, MARRIED, VALOR FROM CUSTOMER" ALIAS QUERY VIA
"TOPCONN"
TCSetField("QUERY","DATA","D")
TCSetField("QUERY","VALOR","N",12,2)

Dentro de um programa ADVPL j podemos considerar como um campo data


no mais um campo caracter como o seu armazenamento.
O campo Data s retornado como um campo caracter por que estamos
utilizando a funo TCQUERY, se no o tratamento automtico.

A estrutura dos parmetros da funo TCSETFIELD() a mesma retornada


pela funo DbStruct() e que utilizada em diversas funes que manipulam
arquivos de dados.
Desta forma muito comum a montagem de queries em tabelas do sistema
partindo da estrutura de campos retornada pela funo DbStruct() sendo que
aps a execuo dos campos Tcquery() ou DbUseArea() normalmente
utilizado o campo TcSetField com base no contedo deste mesmo array de
estrutura.

Exemplo 02:

Local
Local
Local
Local
Local

cQuery
cCampos
aStruSA1
nX
nMax

:=
:=
:=
:=
:=

""
""
SA1->(DbStruct())
0
Len(aStruSA1)

// Monta a String cCampos de acordo com o contedo de aStruSA1


aEval(aStruSA1,{|aCampo| nX++, cCampos += aCampo[1] +;
IIF(nX == nMax,' ',', ')})
// Monta a query utilizando a String cCampos
cQuery := "SELECT "+cCampos+" FROM "+RetSqlName("SA1")
If Select("SA1SQL") <> 0
DbSelectArea("SA1SQL")
DbCloseArea()
Endif
dbUseArea(.T.,"TOPCONN",TcGenQry(,,cQuery),"SA1SQL",.T.,.F.)

- 235 ADVPL Avanado

Continuao:
For nX := 1 to Len(aStruSA1)
IF !( aStrutSA1[nX][2] $ "C/M")
TCSetField( cAlias,aStruSA1[nX][1],aStruSA1[nX][2],;
aStruSA1[nX][3],aStruSA1[nX][4])
ENDIF
Next nX

TCSPEXEC()
Executa uma Stored Procedure no Banco de Dados.

Devido a uma limitao em alguns dos Bancos de Dados suportados na


obteno dos tipos de parmetros (se so de INPUT e/ou OUTPUT) todos as
Stored Procedures a serem executadas atravs do TOPConnect devero
obedecer o seguinte padro de nomenclatura de seus parmetros :
Parmetros de INPUT devem comear com IN_... Ex. IN_VALOR.
Parmetros de OUTPUT devem comear com OUT_... Ex. OUT_CODIGO
Aps a execuo de uma Stored Procedure o TOPConnect retornar ao ADVPL
um array com 'n' elementos, onde n o nmero de parmetros de OUTPUT da
Stored Procedure.

Sintaxe: TCSPExec(cSPName,xParam1,xParam2...xParamN)

Parmetros:
cSPName

Nome completo da Stored Procedure no banco de dados.

xParamN

Parmetros de input da Stored Procedure.


As procedur es padres da aplicao ERP Protheus possuem concatenadas em
seus nomes o cdigo da empresa para a qual foram aplicadas.
Desta forma ao executar uma procedure padro do ERP atravs do comando
TCSPEXEC necessrio utilizar a funo xProcedures(), pois a mesma ir
concatenar ao nome da procedure que ser executada o cdigo da empresa.
Por exemplo: Procedure MAT001
 Se for executada com a sintaxe: TCSPExec(MAT001,...) ocorrer
um erro na aplicao pois esta procedure no existe.
 Utilizando a funo xProcedures() temos:
TCSPExec( xProcedures(MAT001), ...), onde caso a empresa em uso
seja a 01, ser executada a MAT001_01, a qual vlida.

- 236 ADVPL Avanado

Retorno:
Array com os parmetros de retorno da Stored Procedure e <cSPName> o
nome da Stored Procedure a ser executada e os demais parmetros variam
conforme a definio da Stored Procedure.

Array

Exemplo:

//Verifica se a Stored Procedure Teste existe no Servidor


If TCSPExist("TESTE")
//Executa a Stored Procedure Teste
aRet := TCSPExec("TESTE","JOSE",1000)
if aRet <> nil
cRetorno := ""
For i:= 1 to Len(aRet)
cRetorno += "|"+ IIF(ValType(aRet[i]) == "C", aRet[i],;
IIF(ValType(aRet[i]) == "N", CValToChar(aRet[i]), "U"))
Next
//Mostra os valores de retorno
ALERT(cRetorno)
Else
ALERT("Erro executando Stored Procedure"+CRLF+"Mensagem: "+TCSQLError())
Endif
EndIf

A funo TCSPExist() deve ser utilizada apenas para verificao da existncia


de Stored Procedures padres da aplicao ERP, ou que possuam concate
nadas no nome a informao da empresa para qual esto habilitadas.
Para verificao de procedures sem esta caracterstica deve ser utilizada a
funo ExistProc().

- 237 ADVPL Avanado

TCSPEXIST()
Verifica a existncia de uma determinada Stored Procedure no servidor.


Sintaxe: TCSPExist(cSPName)

Parmetros:
Nome da procedure a ser verificada no banco de dados.

CSPName


Retorno:
Indica se a Stored Procedure existe ou no e <cSPName> o nome da
Stored Procedure procurada.

Lgico

Exemplo:

If TCSPExist("MAT001_01")
TCSPExec("MAT001_01",...)
Endif

A funo TCSPExist() deve ser utilizada apenas para verificao da existncia


de Stored Procedures padres da aplicao ERP, ou que possuam concate
nadas no nome a informao da empresa para qual esto habilitadas.
Para verificao de procedures sem esta caracterstica deve ser utilizada a
funo ExistProc().

TCSQLERROR()
Retorna o ltimo erro registrado pelo TOPConnect durante a execuo de uma Query.


Sintaxe: TCSQLError()

Parmetros:
Nenhum

Retorno:
String

Mensagem de erro registrada no TopConnect para a ocorrncia.

Exemplo:

If

TCSQLExec("UPDATE CUSTOMER SET VALUE=0") < 0 then


ALERT(TCSQLError())
Endif

- 238 ADVPL Avanado

Esta a mesma mensagem que esta registrada no log de eventos do


TopConnect / TOTVS DbAccess Manager.

TCSQLEXEC()
Permite a execuo de comandos de atualizao no servidor de banco de dados.


Sintaxe: TCSQLExec(cCommand)

Parmetros:
cCommand

Retorno:
Numrico

Comando SQL a ser executado.

Retorna um valor negativo em caso de erros.

Exemplo:

nRet := TCSQLExec("UPDATE CUSTOMER SET VALUE=0)


TCSRVTYPE()
Retorna o tipo do servidor no qual TOPConnect / TOTVS DbAccess est em execuo.


Sintaxe: TCSrvType()

Parmetros:
Nenhum

Retorno:
String

Tipo do servidor, como por exemplo: "WinNT" ou "AS/400".

Exemplo:

TCLink("MSSQL/TESTE","TOPSRV")
ALERT(TCSrvtype())

- 239 ADVPL Avanado

Devido aos tratamentos especficos necessrios nas queries que sero


executadas em bancos de dados DB2 com sistemas operacionais AS/400
normal a seguinte verificao:
#IFDEF TOP
If TcSrvType() != "AS/400"
<Tratamento SQL convencional>
Else
#ENDIF
<Tratamento padro CODBASE>
#IFDEF TOP
Endif
#ENDIF

TCUNLINK()
Encerra uma conexo com o TOPConnect.


Sintaxe: TCUnlink(nConn)

Parmetros:
nConn

Retorno:
Nenhum

Nmero da conexo previamente retornado pela funo TCLink()

Exemplo:

TCConType("NPIPE")
nConn := TCLink("MSSQL/TOPCONN","TOPSRV")
TCUnLink(nConn)

- 240 ADVPL Avanado

TCCHKOBJ()
Verifica a existncia de um objeto no servidor AS/400


Sintaxe: TCChkObj(cObj,cLibrary,cType)

Parmetros:

cObj

Nome do objeto a ser verificado.

cLibrary

Nome da biblioteca que deve conter o objeto

cType

Tipo do de objeto AS/400, como por exemplo: *FILE ou *PGM.

Retorno:
0 quando o objeto existe ou o nmero do erro no AS/400.

Numrico

Exemplo:

nError := TCChkObj("CALCCUST","PRODUCAO","*PGM")

Funo para uso apenas com o TOPConnect em servidores AS/400.

TCEXEERROR()
Retorna uma string com a mensagem de erro retornada pela execuo das funes
TCPGMEXE() e TCSYSEXE().


Sintaxe: TCExeError()

Parmetros:
Nenhum

Retorno:
String

Mensagem de erro.

Exemplo:

If TCPGMEXE("CALCCUST") != 0
ALERT(TCExeError())
Endif

- 241 ADVPL Avanado

Funo para uso apenas com o TOPConnect em servidores AS/400.

TCPGMEXE()
Executa um programa no servidor AS/400.


Sintaxe: TCPGMEXE(cProgram)

Parmetros:
cProgram

Nome do programa a ser executado.

Retorno:
0 quando o objeto existe ou o nmero do erro no AS/400.

Numrico

Exemplo:

If TCPGMEXE("CALCCUST") != 0
ALERT(TCExeError())
Endif

Funo para uso apenas com o TOPConnect em servidores AS/400.

TCSYSEXE()
Permite a execuo de um comando utilizando a sintaxe e recursos nativos do DB2/400,
diretamente no servidor do banco de dados.


Sintaxe: TCSysExe(cCommand)

Parmetros:
cCommand

Comando a ser executado no servidor de banco de dados utilizando sintaxe


DB2/400.

Retorno:
Numrico

0 quando o objeto existe ou o nmero do erro no AS/400.

- 242 ADVPL Avanado

Exemplo:

cCommand
cCommand
cCommand
cCommand

:=
+=
+=
+=

"CRTCBLMOD MODULE("+cTDataBase+"/"+cName+"F"+cCrrEmp+") "


"SRCFILE("+cTDataBase+"/QSPSRC) "
"SRCMBR("+cName+"F"+cCrrEmp+") "
"REPLACE(*YES)"

If TCSysExe( cCommand )!= 0


ALERT(TCExeError())
Endif

Funo para uso apenas com o TOPConnect em servidores AS/400.

Funes acessrias para uso em fontes com interao com o TOTVS DbAccess
CHANGEQUERY()
Funo que efetua as adequaes necessrias a query para que a mesma possa ser executada
adequadamente no banco de dados em uso pela aplicao ERP atravs do TopConnect.
Esta funo necessria pois a aplicao ERP Protheus pode ser utilizada com diversos bancos
de dados, e cada banco possui particularidades em sua sintaxe, de forma que mesmo uma
query escrita respeitando o padro SQL ANSI pode necessitar de adequaes.


Sintaxe: ChangeQuery(cQuery)

Parmetros:
cQuery

String contendo a query escrita em sintaxe SQL ANSI.

Retorno:
String
Query adequada em funo do banco em uso pela conexo ativa com a
aplicao TopConnect.

Exemplo:

cQuery := "SELECT DISTINCT CV8_PROC FROM "+RETSQLNAME("CV8")


cQuery += " WHERE "
cQuery += "CV8_FILIAL = '"+MV_PAR01+"' AND "
cQuery += "D_E_L_E_T_ = '' "
cQuery += "ORDER BY CV8_PROC"
cQuery := ChangeQuery(cQuery)
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), "CV8QRY", .F., .T.)

- 243 ADVPL Avanado

A funo ChangeQuery() deve obrigatoriamente ser utilizada pelos fontes da


aplicao ERP, pois a mesma pode ser instalada em diversos ambientes,
utilizando os vrios bancos de dados homologados, mas para
desenvolvimentos especficos de clientes, o analista pode optar por no
utilizar a funo ChangeQuery().
A razo disto permitir ao analista, que tenha conhecimentos mais apurados
do banco de dados em uso pelo cliente, utilizar uma sintaxe focada em utilizar
melhor os recursos do banco, otimizando a performance da aplicao.

RETFULLNAME()
Retorna o nome real da tabela no banco de dados para utilizao desta na seleo da query.

A funo RetFullName() no exclusiva para uso em queries, sendo utilizada


pela aplicao ERP para verificar o nome da tabela para o alias, especificado
no SX2 da empresa indicada.

Sintaxe: RetFullName(cAlias, cEmp)

Parmetros:
cAlias
cEmp

Retorno:
String

Nome da rea de trabalho da aplicao para identificao da tabela no banco


de dados.
Cdigo da empresa a ser avaliada.

Nome completo / real da tabela no banco de dados.

Exemplo:

SA1->(DbSetOrder(1)) // A1_FILIAL+A1_COD+A1_LOJA
cOrder := SqlOrder(IndexKey())
cQuery := "SELECT * FROM "+RETSQLNAME("SA1")+ " WHERE "
cQuery += RetSqlCond("SA1")
cQuery += " ORDER BY "+cOrder
dbUseArea(.T.,"TOPCONN", TcGenQry(,,cQuery), "TRBSQL", .T., .F.)
cRealName := RetFullName("TRBSQL")

- 244 ADVPL Avanado

RETSQLCOND()
Retorna uma string com as condies padres de uso em uma query.


Sintaxe: RetSqlCond(cAlias)

Parmetros:
cAlias

Nome do alias para composio a string de condies.

Retorno:
String
Condies de seleo padres para o alias indicado.
As condies padres so:
ALIAS_FILIAL = xFilial(ALIAS) .AND.
ALIAS.D_E_L_E_T_ = .

Exemplo:

cQuery := "SELECT DISTINCT CV8_PROC FROM "+RETSQLNAME("CV8")


cQuery += " WHERE "
cQuery += RetSqlCond("CV8")
cQuery += "ORDER BY CV8_PROC"
cQuery := ChangeQuery(cQuery)
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), "CV8QRY", .F., .T.)

RETSQLNAME()
Retorna o nome padro da tabela para seleo no banco de dados atravs da query.


Sintaxe: RetSqlName(cAlias)

Parmetros:
cAlias

Retorno:
String

Alias para ser avaliado o nome padro da tabela.

Nome completo da tabela para seleo atravs da query.

Exemplo:

cQuery := "SELECT DISTINCT CV8_PROC FROM "+RETSQLNAME("CV8")


cQuery += " WHERE "
cQuery += RetSqlCond("CV8")
cQuery += "ORDER BY CV8_PROC"
cQuery := ChangeQuery(cQuery)
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), "CV8QRY", .F., .T.)

- 245 ADVPL Avanado

RETSQLTABLE()
Retorna o nome real da tabela para seleo no banco de dados atravs da query.


Sintaxe: RetSqlTable(cAlias)

Parmetros:
cAlias

Retorno:
String

Alias para ser avaliado o nome real da tabela.

Nome real da tabela no banco de dados.

Exemplo:

cQuery := "SELECT DISTINCT CV8_PROC FROM "+RETSQLTABLE("CV8")


cQuery += " WHERE "
cQuery += RetSqlCond("CV8")
cQuery += "ORDER BY CV8_PROC"
cQuery := ChangeQuery(cQuery)
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), "CV8QRY", .F., .T.)

SQLCOPY()
Cria um arquivo no formato especificado pela configurao LOCALFILES do ambiente com o
retorno da query.


Sintaxe: SqlCopy(cFile, cWhere, aStru, cAlias, aDates, lRecno)

Parmetros:
cFile

Nome do arquivo temporario destino a ser gerado

cWhere

Condicao "Where" da query

aStru

Array com os Campos a serem selecionados pela query

cAlias

Alias origem dos dados

aDates

Array com os nomes dos campos que devero ter o tratamento da funo
TCSetField() para o formato de data.
Se copia o contedo da coluna R_E_C_N_O_ para o arquivo gerado.

lRecno


Retorno:
Nenhum

- 246 ADVPL Avanado

SQLORDER()
Converte a sintaxe de um indce em formato ISAM (CODEBASE) para o formato SQL ANSI


Sintaxe: SqlOrdem(cOrder)

Parmetros:
cOrder

Retorno:
String

Sintaxe de ndice em formato ISAM.

ndice convertido para sintaxe SQL ANSI

Exemplo:

SA1->(DbSetOrder(1)) // A1_FILIAL+A1_COD+A1_LOJA
cOrder := SqlOrder(IndexKey())
cQuery := "SELECT * FROM "+RETSQLNAME("SA1")+ " WHERE "
cQuery += RetSqlCond("SA1")
cQuery += " ORDER BY "+cOrder
dbUseArea(.T.,"TOPCONN", TcGenQry(,,cQuery), "TRBSQL", .T., .F.)
cRealName := RetFullName("TRBSQL")

- 247 ADVPL Avanado

SQLTOTRB()
Preenche um arquivo temporrio com o contedo do retorno da query.


Sintaxe: SqlToTrb(cQuery, aStru, cAlias)

Parmetros:
cQuery

Query para seleo dos registros no banco de dados.

aStru

Array contendo a estrutura do arquivo temporrio a ser preenchido com os


dados de retorno da query.
Alias do arquivo temporrio a ser preenchido com os dados de retorno da
query.

cAlias

Para correta utilizao da funo SQLTOTRB() o arquivo temporrio deve estar


criado e com a rea de trabalho (ALIAS) definido.

Retorno:
Nenhum

Exemplo:

// Arquivo de trabalho que ser utilizado pela MaWndBrowse


cCampos:= ""
nX
:= 0
nMax
:= Len(aStruSQL)
aEval( aStruSQL,{|aCampo| nX++, cCampos += aCampo[1] +;
IIF(nX == nMax,' ',', ')})
cArqTrb := CriaTrab(aStruSQL,.T.)
dbUseArea(.T.,__LOCALDRIVER,cArqTrb,cAlias,.T.,.F.)
cQuery := "SELECT "+cCampos+" FROM "+RetSqlName("SA1")+" (NOLOCK) "
SqlToTrb(cQuery,aStruSQL,cAlias)
cArqInd := CriaTrab(Nil,.F.)
cChave
:= "A1_FILIAL+A1_COD+A1_LOJA"
IndRegua(cAlias,cArqInd,cChave,,,"Indexando Registros...")
dbSelectArea( cAlias )
dbGotop()

- 248 ADVPL Avanado

8.3. Aplicaes com controle de comunio com o Banco de Dados


Utilizando as funo de interao com a aplicao TopConnect / TOTVS DbAccess tm-se um
grande nmero de aplicaes que podem ser desenvolvidas, combinando-se recursos
previamente estudados nos mdulos Bsico, Intermedirio e utilizando os conceitos de
orientao objetos e as classes de objetos disponveis na linguagem ADVPL, tais como:
 Rotinas de processamento utilizando queries para seleo dos registros;
 Relatrios para seleo dos registros;
 Rotinas de atualizao para execuo dos comando de atualizao diretamente
no banco de dados.
Em resumo, qualquer aplicao do ambiente ERP pode ser escrita utilizando os recursos de
interao com a aplicao TopConnect / TOTVS DbAccess, para obter, manipular e atualizar os
dados do banco do banco de dados.
Neste tpico sero detalhadas duas aplicaes utilizando estas funes, cujo grau de
complexidade ilustra bem o potencial desta ferramenta.
 MaWndBrowse com Alias Temporrio gerado por Query
 Banco de dados de interface

8.3.1. MaWndBrowse com Alias Temporrio gerado por Query


Conforme descrito no tpico 6.1. MaWndBrowse, esta funo permite a montagem de
um browse cuja estrutura do arquivo no necessita estar definida no dicionrio de dados
da aplicao ERP.
Utilizando esta particularidade da MaWndBrowse possvel ento compor um alias
temporrio contendo o retorno de uma query e exibi-lo em um browse.
A vantagem deste BrowseSQL em relao ao browse de uma tabela normal a
possibilidade de combinar informaes de vrias tabelas atravs de uma query e exibilas em tela.
Algumas aplicaes interessantes para este recurso seriam:
 Consulta Kardex em tela, pois este relatrio combina dados das tabelas de
itens dos documentos de entrada (SD1), itens dos documentos de sada
(SD2) e movimentaes internas (SD3).
 Conciliao de contabilizaes, pois uma contabilizao composta por
uma origem, a qual pode ser praticamente de qualquer tabela de
movimentos da aplicao ERP, e de um ou mais lanamentos contbeis
(CT2) gerados por esta origem.
 Demonstrao em tela das depreciaes dos bens do imobilizado por
perodo, compondo dinamicamente as colunas de depreciao de acordo
com o intervalo de meses selecionados. Este recurso interessante pois
elimina a limitao de espao da impresso e pode ser combinado com a
funcionalidade de exportao de grids de dados para o Microsoft Excel.

- 249 ADVPL Avanado

Exemplo: MaWndBrowse com Alias Temporrio gerado por Query

Este exemplo de uso da MaWndBrowse com alias de temporrio utilizando


queries derivado do exemplo de utilizao da MaWndBrowse com arquivo
temporrio descrito no item 6.1. MaWndBrowse.

#include "protheus.ch"
/*/
+----------------------------------------------------------------------| Funo
| WndSQLTRB
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Demonstra a utilizao da MaWndBrowse com SQL
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
User Function WndSQLTRB()
// Variveis para o Arquivo Temporario
Local cChave
:= ""
Local cArqTrb
:= ""
Local aStruTRB := {}
Local aStruSQL := SA1->(DbStruct())
// Variveis para o MaWndBrowse
Local cTitulo
:= "Cadastro Temporario"// Ttulo obrigatrio
Local cAlias
:= "SA1" // Alias da tabela corrente podendo ser TRB
Local cFunLeg
:= "" // Funo que dever retornar um valor lgico e com isso
ser atribudo semafro na primeira coluna do browse
Local cTopFun
:= "" // Mostrar os registros com a chave de
Local cBotFun
:= "" // Mostrar os registros com a chave ate
Local lCentered := .T. // Valor verdadeiro centraliza
Local aResource := {} // aAdd(aResource,{"IMAGEM","Texto significativo"})
Local nModelo
:= 1 // 1- Menu do aRotina
Local aPesqui
:= {} // aAdd(aPesqui{"Ttulo",nOrdem}), se no passado ser
utilizado o AxPesqui
Local cSeek
:= "" // Chave principal para a busca, exemplo: xFilial("???")
Local lDic
:= .T. // Parmetro em conjunto com aCampos
Local lSavOrd
:= .T. // Estabelecer a ordem aps pesquisas.
// Variaveis para a MsAdvSize
Local lEnchBar := .F. // Se a janela de dilogo possuir enchoicebar (.T.)
Local lPadrao
:= .F. // Se a janela deve respeitar as medidas padres do
Protheus (.T.) ou usar o mximo disponvel (.F.)
Local nMinY
:= 400 // Altura mnima da janela
Local aSize

:= MsAdvSize(lEnchBar, lPadrao, nMinY)

Private cCadastro := " "


Private aCampos
:= {} // Se lDic=.T. utilizar o SX3, do contrrio o aCampos
informado -> aAdd(aCampo,{X3_CAMPO,X3_PICTURE,X3_TITULO,X3_TAMANHO})
Private aRotina
:= {} // Idntico ao aRotina para mBrowse

- 250 ADVPL Avanado

Continuao:
aAdd(aRotina,{"Visualizar","U_TcVisual",0,2}) // Desenvolver Enchoice para
campos de arquivo temporrio
aAdd(aRotina,{"Incluir"
,"U_TcInclui",0,3}) // Desenvolver Enchoice para
campos de arquivo temporrio
aAdd(aRotina,{"Alterar"
,"U_TcAltera",0,4}) // Desenvolver Enchoice para
campos de arquivo temporrio
aAdd(aRotina,{"Excluir"
,"U_TcExclui",0,5}) // Desenvolver Enchoice para
campos de arquivo temporrio
// Estrutura do Arquivo: Nome do campo / tipo, tamanho, decimais (SX3 para
temporrio)
/*
AADD(aStruTRB,{"TRB_FILIAL"
,"C",02,0})
// Nome_Campo , Tipo_Campo, Tamanho, Decimal
AADD(aStruTRB,{"TRB_ID"
,"C",14,0})
AADD(aStruTRB,{"TRB_NOME"
,"C",20,0})
AADD(aStruTRB,{"TRB_IDADE"
,"N",03,0})
AADD(aStruTRB,{"TRB_STATUS"
,"C",01,0})
*/
// aCampos padro para a MaWndBrowse
//AADD(aCampos,{<Nome_Campo>,<Picture>,<Titulo>,<Tamanho>})
// aCampos melhorado para a WndBrwTRB
//AADD(aCampos,{<Nome_Campo>,<Picture>,<Titulo>,<Tamanho>,<Tipo>,<cWhen>,;
//<lObrigatorio>})
// Nota: lObrigatorio deve ser sempre a ultima informacao do aCampos
/*
AADD(aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02,"C",".F.",.T.})
AADD(aCampos,{"TRB_ID"
,"@!" ,"Matricula"
,14,"C",".F.",.T.})
AADD(aCampos,{"TRB_NOME"
,"@!" ,"Nome"
,20,"C",".T.",.F.})
AADD(aCampos,{"TRB_IDADE"
,"@E 999","Idade"
,03,"N",".T.",.F.})
AADD(aCampos,{"TRB_STATUS"
,"@!" ,"Status"
,01,"C",".T.",.T.})
*/
If ( Select( cAlias ) <> 0 )
dbSelectArea ( cAlias )
dbCloseArea ()
Endif
// Arquivo de trabalho que ser utilizado pela MaWndBrowse
cCampos:= ""
nX
:= 0
nMax
:= Len(aStruSQL)
aEval( aStruSQL,{|aCampo| nX++, cCampos += aCampo[1] +;
IIF(nX == nMax,' ',', ')})
cArqTrb := CriaTrab(aStruSQL,.T.)
dbUseArea(.T.,__LOCALDRIVER,cArqTrb,cAlias,.T.,.F.)
cQuery := "SELECT "+cCampos+" FROM "+RetSqlName("SA1")+" (NOLOCK) "
SqlToTrb(cQuery,aStruSQL,cAlias)

- 251 ADVPL Avanado

Continuao:
cArqInd := CriaTrab(Nil,.F.)
cChave
:= "A1_FILIAL+A1_COD+A1_LOJA"
IndRegua(cAlias,cArqInd,cChave,,,"Indexando Registros...")
dbSelectArea( cAlias )
dbGotop()
MaWndBrowse(aSize[7],aSize[2],aSize[6],aSize[5],cTitulo,cAlias,/*aCampos*/,;
aRotina,,cTopFun,cBotFun,lCentered,,nModelo,,cSeek,lDic,lSavOrd)
If ( Select( cAlias ) <> 0 )
dbSelectArea ( cAlias )
dbCloseArea ()
Endif
If File(cArqInd+OrdBagExt())
FErase(cArqInd+OrdBagExt())
ENDIF
DbSelectArea("SA1")
DbSetOrder(1)
Return
/*/
+----------------------------------------------------------------------| Funo
| TcVisual
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcVisual(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
//
//
//
//

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
:= {||oDlg:End()}
bCancel
:= {||oDlg:End()}
nX

Padrao Modelo2(), com lWhen -> cWhen


AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}

Continuao:
- 252 ADVPL Avanado

For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".F.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
TEnchoice(oDlg, aCposEnch,,,,,.T.)
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN
/*/
+----------------------------------------------------------------------| Funo
| TcInclui
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcInclui(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
aArea
:= GetArea()
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}

Continuao:

- 253 ADVPL Avanado

For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".T.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
Do Case
Case aCampos[nX][5] == "C"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "N"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "D"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "L"
&("_"+aCampos[nX][1])
Case aCampos[nX][5] == "M"
&("_"+aCampos[nX][1])
EndCase

:= Space(aCampos[nX][4])
:= 0
:= CTOD("")
:= .F.
:= Space(aCampos[nX][4])

Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
( U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN

- 254 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| TcAltera
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcAltera(cAlias,nReg,nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
aArea
:= GetArea()
nX

// Padrao Modelo2(), com lWhen -> cWhen


// AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
// aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}
For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",aCampos[nX][6],aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
( U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN

- 255 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| TcExclui
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcExclui(cAlias, nReg, nOpc)
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
//
//
//
//

aCposEnch := {}
nLinha
:= 15
nColuna
:= 10
nOpcE
:= aRotina[nOpc][4] // Opcao de verdade
bOk
bCancel
:= {||oDlg:End()}
nX

Padrao Modelo2(), com lWhen -> cWhen


AADD(aCposEnch,{"<Variavel>"
,{nLinha,nColuna}
,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
aCampos,{"TRB_FILIAL"
,"@!" ,"Filial"
,02}

For nX := 1 to Len(aCampos)
If nX > 1
nLinha := IIF(nX%2 > 0 ,nLinha := nLinha +015,nLinha) // Impar
nColuna := IIF(nX%2 == 0,nColuna := nColuna+170,10)// Par
Endif
AADD(aCposEnch,{"_"+aCampos[nX][1],{nLinha,nColuna} ,;
aCampos[nX][3],aCampos[nX][2],"AllwaysTrue()",;
"",".F.",aCampos[nX][4]})
SetPrvt("_"+aCampos[nX][1])
&("_"+aCampos[nX][1]) := (cAlias)->&(aCampos[nX][1])
Next nX
oDlg := TDialog():New(000,000,400,650,cCadastro,,,,,,,,,.T.)
TEnchoice(oDlg, aCposEnch,,,,,.T.)
bOk := {|| IIF( U_TValid(cAlias,nReg,nOpcE,aCampos),;
(U_TGravar(cAlias,nReg,nOpcE,aCampos),oDlg:End()),)}
oDlg:bInit := {|| EnchoiceBar(oDlg, bOk, bCancel,.F.,{},nReg,cAlias)}
oDlg:lCentered := .T.
oDlg:Activate()
RETURN

Continuao:
- 256 ADVPL Avanado

/*/
+----------------------------------------------------------------------| Funo
| TcValid
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcValid(cAlias,nReg,nOpc,aCampos)
LOCAL lRet
LOCAL nX
LOCAL nPosObrig := Len(aCampos[1])
For nX := 1 to Len(aCampos)
IF aCampos[nX,nPosObrig] == .T.
IF !(lRet := !Empty(&("_"+aCampos[nX,1])))
Help("TEnchoice",1,"HELP","OBRIGATORIO","Existem campos
obrigatorios nao preenchidos",1,0)
RETURN lRet // EXIT
ENDIF
ENDIF
Next nX
IF nOpc == 3
IF !(lRet := !((cAlias)->(dbSeek(_TRB_FILIAL+_TRB_ID))))
Help("TEnchoice",1,"HELP","INCLUSAO","Ja existe um registro com esta
chave",1,0)
ENDIF
ELSE
IF !(lRet := (cAlias)->(dbSeek(_TRB_FILIAL+_TRB_ID)))
Help("TEnchoice",1,"HELP","ALTERACAO","Nao existe um registro com
esta chave",1,0)
ENDIF
ENDIF
RETURN lRet

- 257 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| TcGravar
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION TcGravar(cAlias,nReg,nOpc,aCampos)
LOCAL nX
RecLock(cAlias,nOpc==3)
IF nOpc == 5
DbDelete()
ELSE
For nX := 1 to Len(aCampos)
(cAlias)->&(aCampos[nX][1]) := &("_"+aCampos[nX][1])
Next nX
ENDIF
Msunlock()
RETURN

- 258 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| TEnchoice
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | Enchoice para arquivos temporarios
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
Static Function TEnchoice(oDlg, aCampos, nLeftE, nTopE, nHeightE, nWidthE,;
lEnchBar)
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aSays
aGets
cCaption
cPict
cValid
cF3
cWhen
cBlKSay
cBlkGet
cBlKVld
cBlKWhen
nLeft
nTop
nI

:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=

{}
{}
""
""
""
""
""
""
""
""
""
0
0
0

Default lEnchBar := .F.


Default
nLeftE
:= IIF(lEnchBar,(oDlg:nLeft)+16,2)
Default
nTopE
:= 2
Default
nHeightE
:= (oDlg:nHeight)-135
Default nWidthE
:= (oDlg:nWidth)-102
// Padrao Modelo2(), com lWhen -> cWhen
// AADD(aC,{"<Variavel>"
,{nLinha,nColuna}
//,"<Titulo>","<Picture>","<Validacao>","<F3>","<lWhen>",<Tamanho>})
If Len(aCampos) > 0
oScroll := TScrollBox():New(oDlg, nLeftE, nTopE, nHeightE , nWidthE, .T.,;
.T., .T.)
For nI:=1 to Len(aCampos)
If Len(aCampos[nI])==8
cCampo
:= aCampos[nI,1]
nLeft := aCampos[nI,2,1]-13
nTop := aCampos[nI,2,2]
cCaption:= Iif(Empty(aCampos[nI,3]), " "
cPict := Iif(Empty(aCampos[nI,4]), Nil
cValid
:= Iif(Empty(aCampos[nI,5]),
cF3
:= Iif(Empty(aCampos[nI,6]),

,aCampos[nI,3])
,aCampos[nI,4])
".t." ,aCampos[nI,5])
NIL
,aCampos[nI,6])

cWhen := Iif(Empty(aCampos[nI,7]), ".T." ,aCampos[nI,7])

- 259 ADVPL Avanado

Continuao:
nWidthG

:= Iif(Empty(aCampos[nI,8]), 100,;
IiF(aCampos[nI,8]*3.5 > 100,100,nil))

cBlKSay := "{|| OemToAnsi('"+cCaption+"')}"


cBlkGet := "{ | u | If( PCount() == 0,;
"+cCampo+","+cCampo+":= u ) }"
cBlKVld := "{|| "+cValid+"}"
cBlKWhen := "{|| "+cWhen+"}"
AADD(aSays,Array(1))
aSays[nI] := TSay():New(nLeft+1, nTop, &(cBlkSay), oScroll,,,;
.F., .F., .F., .T.,,, 50, 8, .F., .F., .F., .F.,;
.F. )
AADD(aGets,Array(1))
aGets[nI] := TGet():New( nLeft, nTop+50, &(cBlKGet), oScroll,;
nWidthG, 11, cPict, &(cBlkVld),,,, .F.,, .T.,,;
.F., &(cBlkWhen), .F., .F.,, .F., .F. , cF3,;
(cCampo))
EndIf
Next
Endif
Return

- 260 ADVPL Avanado

8.3.2. Banco de dados de interface


O termo Banco de dados de interface utilizado para classificar uma aplicao ADVPL escrita
com funes de interao com a aplicao TopConnect / TOTVS DbAccess para realizar a
integrao entre a aplicao ERP Protheus e outro sistema, utilizando como meio de
comunicao um banco de dados e no mais importao de arquivos em N formatos, tais
como .TXT, .DBF e similares.

Este tipo de integrao no visa substituir formatos de integraes padres j


existentes como o padro CNAB e o padro Web XML.
Sua aplicao integrao direta entre sistemas atravs de um banco de
dados com formato e padres comuns entre elas.

As vantagens da utilizao do conceito de Banco de Dados de Interface em comparao da


integrao por importao / exportao de arquivos so:
 Maior controle da integrao das informaes entre os sistemas, permitindo um
tratamento adequado de eventos de erros;
 Transparncia e rastreabilidade das informaes integradas, implementando
confiabilidade no processo;
 Possibilidade de utilizao de um tipo de banco de dados pela aplicao ERP
Protheus e de outro tipo de banco de dados para integrao entre os sistemas.
 Possibilidade de desenvolvimento de ferramentas para monitorar e gerenciar a
integrao entre os sistemas atravs do controle da rea de interface no banco
de dados, inclusive com a utilizao de Stored Procedures para aumentar a
performance da aplicao de interface.
Consideraes relevantes sobre as funes TCLink() e TCSetConn()
 A funo TCLink() permite a abertura de uma conexo com um banco de dados,
desde que haja o OBDC configurado no ambiente da aplicao e na aplicao
TOPConnect / TOTVS DBAccess;
 Cada abertura de conexo atravs da funo TcLink() consome uma licensa de
usurio do TOPConnect / TOTVS DBAccess. Aps a abertura de uma conexo a
mesma deve ser selecionada pela funo TcSetConn() para se tornar a conexo
ativa;
 Podem ser utilizadas diversas conexes em uma mesma aplicao ADVPL, e
podem ser utilizadas as informaes das tabelas j abertas e vinculadas a uma
rea de trabalho independente da conexo que est ativa. Somente deve ser
verificado que para abertura de uma tabela e vnculo desta com uma rea de
trabalho obrigatoriamente deve estar ativa a conexo com o banco de dados que
contm esta tabela.
 A conexo aberta entre o ERP Protheus e o TopConnect / DbAccess possu o
nmero de referncia 0. Desta forma, aps finalizar uma conexo aberta com o
comando TCLink() deve ser efetuado um TCSetConn(0) para restaurar como
conexo ativa a conexo padro do Protheus com o TopConnec.

- 261 ADVPL Avanado

A figura abaixo ilustra a estrutura tpica de uma aplicao utilizando o conceito de Banco de
Dados de Interface, com foco na aplicao ERP Protheus e seus recursos pr-disponveis:

Tarefa

Descrio

01

Exportao Protheus -> DbInterface

02

Importao DbInterface -> ERP X

03

Extrao ERP X -> DbInterface

04

Importao DbInterface -> Protheus

05

Efetivao Protheus -> Protheus

Detalhamento
Utilizao de queries ou stored
procedures para atualizao das
tabelas do banco DBInterface no
formato
necessrio
ao
ERP
X,
executadas a partir do ERP Protheus.
Ferramentas proprietrias do ERP X
para
leitura
do
DBInterface
e
tratamento das informaes para
atualizao do banco de dados desta
aplicao.
Pode ser uma ferramenta proprietria
da aplicao ERP X, ou pode ser um
conjunto
de
queries
e
stored
procedures
desenvolvidas
em
conjunto com a equipe do ERP X e a
equipe TOTVS, permitindo o controle
de execuo da extrao pelo ERP
Protheus.
Utilizao de queries ou stored
procedures
para
leitura
das
informaes
do
DBInterface
e
atualizao de tabelas intermedirias
no banco de dados do ERP Protheus,
executadas a partir do ERP Protheus.
Utilizao de funes prprias para
esta finalidade no ERP Protheus para
efetivao
das
informaes
importadas em informaes vlidas no
ERP. Estas funes normalmente so
compatveis com a execuo atravs
do recurso de MsExecAuto().

- 262 ADVPL Avanado

Consideraes complementares sobre o conceito de Banco de Dados de Interface


 A utilizao de tabelas intermedirias no banco de dados Protheus apesar de no
ser obrigatria recomendada para permitir um tratamento adequado das
ocorrncias de efetivao das informaes, principalmente quando utilizada a
funo MsExecAuto() para executao das rotinas de efetivao dos dados;
 Para extrao das informaes tanto do banco de dados Protheus para
exportao, quanto do banco de dados do sistema ERP X recomendvel o uso
de Stored Procedures para aumentar a performance do processo como um todo.
importante lembrar que se o sistema ERP X possuir procedures de exportao
as mesmas podero ser executadas diretamente pelo Protheus atravs da funo
TCSpExec();
 recomendvel que as funcionalidades de Exportao, Extrao, Importao e
Efetivao sejam tratadas tanto com interfaces de execuo direta quanto
atravs de execuo via Job.

- 263 ADVPL Avanado

8.4. Embedded SQL Facilitador de Querys


O objetivo do Embedded SQL facilitar a escrita e leitura de query's. Foi definida uma sintaxe
para que se possa escrever a query diretamente no cdigo ADVPL, sem a necessidade de ficar
concatenando pedaos de string para compor a string final.
Disponibilidade do Recurso
Este recurso est disponvel apenas no Protheus 8. A utilizao do Embedded SQL divide-se
em : compilao do fonte, e execuo do fonte. Para ser possvel compilar um fonte com o
cdigo escrito no formato Embedded, deve ser utilizado um Protheus, com Build igual ou
superior a 7.00.050721p, em um ambiente com repositrio para TopConnect ( RPODB=TOP ).
A utiliao deste recurso tambm depende da atualizao da LIB 811, superior a 'Lib
20050902 - 811'.
 Exemplo bsico - Fonte atual
cQuery : 'SELECT SE2.E2_PREFIXO,SE2.E2_NUM '
cQuery += 'FROM '+RetSqlTable('SE2')+' SE2,'+RetSqlTable('QEK')+' QEK '
cQuery += 'WHERE SE2.E2_FILIAL= '+xfilial('SE2')+' AND '
cQuery += 'SE2.E2_PREFIXO<> ''+cPrefixo+'' AND '
cQuery += 'SE2.D_E_L_E_T_ = ' ' '
cQuery += 'ORDER BY '+RetSqlOrder('SE2')
dbUseArea(.T.,'TOPCONN',TcGenQry(,,cQuery),'E2TEMP',.T.,.T.)
TCSetField('E2TEMP','E2_EMISSAO','D',8,0)

 Exemplo bsico - Utilizando Embedded SQL


BeginSql alias 'E2TEMP'
column E2_EMISSAO as Date
%noparser%
SELECT SE2.E2_PREFIXO,SE2.E2_NUM
FROM %table:SE2% SE2,%table:QEK% QEK
WHERE SE2.E2_FILIAL= %xfilial:SE2% AND
SE2.E2_PREFIXO<> %exp:cPrefixo% AND
SE2.%notDel%
ORDER BY %Order:SE2%
EndSql

- 264 ADVPL Avanado

Caractersticas operacionais - Sintaxe


O bloco onde ser escrito o Select deve sempre ser iniciado com 'BeginSql alias' e finalizado
com 'EndSql'.
Partes do cdigo que devem ser substitudas aparecem entre os sinais de %. Estas expresses
possuem tratamento especial em momento de execuo.
Qualquer instruo colocada entre BEGINSQL... ENDSQL, que no seja uma expresso %...% ,
ser inserida na query a ser enviada para o banco, de forma literal.
Variveis, expresses, funes aparecem iniciando com %exp: %.
Em column, especificar campos da query que so do tipo data, lgico ou numrico (DATE,
LOGIC, NUMBER). Esta linha trocada por chamadas funo TCSetField.
%noparser% indica que a query no deve passar pela funo 'ChangeQuery' antes de ser
enviada ao banco de dados. Caso no especificado, o default a string da query ser passada
automaticamente pela funo ChangeQuery.
%table:<alias>% substituda por RetSqlName(<alias>)
%notDel% substituda por D_E_L_E_T_= ' '
%Order:<alias>% substituda por SqlOrder(<alias>->(IndexKey()))
H 3 opes para o %Order:
1. %Order: <cAlias> %
traduzido para
SqlOrder(<cAlias>->(IndexKey()))
2. %Order: <cAlias>, <nIndice>% traduzido para
SqlOrder(<cAlias>->(IndexKey(<nIndice>)))
3. %Order: <cAlias>, <cNick>% traduzido para
SqlOrder(<alias>->(DBNickIndexKey(<cNick>)))
Limitao:
No permitido incluir funes no meio do cdigo 'embedded'. Se precisar, o valor deve ser
guardado em uma varivel antes do incio do BeginSql.

tam_cp := GetE2ValorSize()
BeginSql alias 'E2TEMP'
column E2_EMISSAO as Date, E2_VALOR as Numeric(tam_cp,2)
. . .
EndSql

- 265 ADVPL Avanado

Erros de Compilao
Caso seja utilizado algum argumento invlido para especificar as colunas, ou erros de sintaxe
nas expresses a serem transformadas para a montagem da query, a compilao do fonte
interrompida com a ocorrncia 'Syntax Error', informando a linha onde a primeira ocorrncia
foi encontrada.

ENDSQL (Error C2001

Syntax error:)

Caso a ocorrncia de compilao aponte diretamente para a linha do cdigo-fonte, onde est
escrita a instruo EndSql, verifique se existe algum espao em branco ou tabulao, a partir
do incio da linha, antes da instruo EndSql. A verso atual desde ambiente no suporta esta
declarao, exigindo que a instruo EndSql seja alinhada esquerda do fonte, sem espaos
ou tabulaes.

Erros de Execuo
 'Query Argument Error : Alias [XXX] already in use.'
Caso a instruo BeginSQL especifique um alias que j esteja aberto (em uso), a aplicao
abortada com a ocorrncia de erro fatal acima, informando em XXX o alias utilizado.

 'Query Argument Error : Invalid Value Type [X]'


Caso alguma expresso informada na Query, atravs da tag %exp: ... %, retorne um valor de
tipo diferente de 'C' Catacter, 'D' Data, 'N' Numrico, ou 'L' Lgico, a aplicao abortada com
a ocorrncia de erro acima, onde o tipo do argumento inesperado mostrado em [X].
 'Type Mismach on +'
Esta ocorrncia, se reproduzida, informar na pilha de chamadas o nmero da linha do cdigofonte correspondente instruo EndSQL. Ocorre caso alguma funo intermediria do engine
do Embedded SQL, excluindo-se as funes especificadas na query com a sintaxe %exp: ... %
, retornar um contedo no-caractere a ser acrescentado na Query. Esta ocorrncia de mais
difcil localizao, sendo til nestes casos a anlise do arquivo temporrio gerado pelo Protheus
IDE, no momento da compilao.
 Help NOFUNCW - Funo __EXECSQL
Caso um fonte com o Embedded SQL seja executado em um repositrio que no tenha sido
atualizado, OU que no seja um Repositrio para o ambiente TOPConnect ( RPODB=TOP), a
aplicao exibir a ocorrncia acima, indicando que a funo interna de execuo da Query
no est presente no ambiente. Verifique se a lib est atualizada, e se o RPO em uso de um
ambiente TOPConnect.

- 266 ADVPL Avanado

Caractersticas operacionais - depurao


Dada a montagem da Query, no possvel depurar o bloco do cdigo-fonte compreendido
entre as instrues BeginSql e EndSql, no sendo considerados pontos de parada de depurao
( BreakPoints ), caso colocados neste intervalo do cdigo. A colocao de pontos de parada
deve ser realizada antes ou depois deste bloco.

Funo auxiliar - GETLastQuery()


Aps a abertura do cursor, no alias especificado, a funo GetLastQuery() retorna um array,
com 5 elementos, onde esto disponveis as seguintes informaes sobre a Query executada :
[1]
[2]
[3]
[4]
[5]

cAlias - Alias usado para abrir o Cursor.


cQuery - Query executada.
aCampos - Array de campos com critrio de converso especificados.
lNoParser - Caso .T., no foi utilizada ChangeQuery() na String original.
nTimeSpend - Tempo, em segundos, utilizado para a abertura do Cursor.

 Exemplo mais completo: Cdigo ADVPL


BeginSql alias 'E2TEMP'
column E2_EMISSAO as Date, E2_VALOR as Numeric(tam_cp,2)
column QEK_SKLDOC As Logical
%noparser%
SELECT SE2.E2_PREFIXO,SE2.E2_NUM, SE2.E2_FORNECE, SE2.E2_LOJA,SE2.E2_VALOR,
SE2.D_E_L_E_T_ DEL1, QEK.D_E_L_E_T_ DEL2 , QEK.QEK_SKLDOC, SE2.R_E_C_N_O_
SE2RECNO
FROM %table:SE2% SE2,%table:qeK% QEK
WHERE SE2.E2_FILIAL= %xfilial:SE2% AND
qek.%notDel% and
SE2.E2_PREFIXO<> %exp:cPrefixo% AND
SE2.E2_NUM<> %exp:(cAlias)->M0_CODIGO% AND
SE2.E2_NUM<>45
AND
SE2.E2_FORNECE=%exp:Space(Len(SE2->E2_FORNECE))% AND
SE2.E2_EMISSAO<>%exp:MV_PAR06% AND
SE2.E2_LOJA<>%exp:MV_PAR05% AND
SE2.E2_VALOR<>%exp:MV_PAR04% AND
qek.QEK_SKLDOC<>%exp:MV_PAR03%
And
SE2.%notDel%
ORDER BY %Order:SE2,1%
EndSql

- 267 ADVPL Avanado

 Exemplo mais completo: Fonte gerado pelo pr-compilador (PPO)

__execSql(
'E2TEMP',
' SELECT SE2.E2_PREFIXO,SE2.E2_NUM, SE2.E2_FORNECE, SE2.E2_LOJA,SE2.E2_VALOR,
SE2.D_E_L_E_T_ DEL1, QEK.D_E_L_E_T_ DEL2 , QEK.QEK_SKLDOC, SE2.R_E_C_N_O_
SE2RECNO FROM

'+RetSqlName('SE2')+' SE2, '+RetSqlName('QEK')+' QEK WHERE

SE2.E2_FILIAL=
SE2.E2_PREFIXO<>

'' +xFilial('SE2')+''

AND qek.D_E_L_E_T_= ' ' AND

'+___SQLGetValue(CPREFIXO)+' AND SE2.E2_NUM <> '+

___SQLGetValue((CALIAS)->M0_CODIGO)+' AND SE2.E2_NUM<>45 AND SE2.E2_FORNECE= '+


___SQLGetValue(SPACE(LEN(SE2->E2_FORNECE)))+' AND SE2.E2_EMISSAO<> '+
___SQLGetValue(MV_PAR06)+' AND SE2.E2_LOJA<> '+___SQLGetValue(MV_PAR05) +' AND
SE2.E2_VALOR<> '+___SQLGetValue(MV_PAR04)+' AND qek.QEK_SKLDOC<> '+
___SQLGetValue(MV_PAR03)+' And SE2.D_E_L_E_T_= ' ' ORDER BY

'+

SqlOrder(SE2->(IndexKey(1))), {{'E2_EMISSAO','D',8,0}, {'E2_VALOR','N',tam_cp,2},


{'QEK_SKLDOC','L',1,0}},.T.)
)

- 268 ADVPL Avanado

9. Funcionalidade MsExecAuto
Sobre a MsExecAuto e Rotinas Automticas
A funcionalidade MsExecAuto, ou tambm conhecida como Rotina Automtica, permite a
execuo de rotinas do ambiente ERP Protheus por funes especficas, o que confere ao
desenvolvedor a possibilidade de efetuar tratamentos especficos antes da execuo da rotina
padro, e mais importante, no perder nenhuma funcionalidade que a rotina padro oferece.
Avaliando esta funcionalidade apenas pelo pargrafo acima, tem-se a impresso de ser um
recurso simples e at mesmo desnecessrio, pois um desenvolvedor experiente poderia
reproduzir todas as validaes e tratamentos existentes em sua rotina, ento porque ter de
tratar a rotina padro?
Para responder a esta pergunta devemos fazer as seguintes consideraes:
 A aplicao ERP est em constante evoluo:
No momento de desenvolvimento da rotina especfica era necessrio apenas o
tratamento de um conjunto isolado de informaes, mas com o aprimoramento do
ERP como um todo, agora so necessrios outros conjuntos de dados, os quais no
foram tratados pelo desenvolvedor naquele momento, mas que esto contemplados
na rotina padro do sistema.
Como o desenvolvedor optou por realizar todo o tratamento de forma especfica, em
uma atualizao do ERP este desenvolvimento precisar ser revisto ou at mesmo
refeito, o que implacar em custo para o cliente ou para o desenvolvedor.
Se o desenvolvedor tivesse optado por utilizar a rotina padro encapsulada em seu
desenvolvimento ele no teria problemas em adaptar sua rotina as novas
necessidades do sistema, pois a rotina padro j se preocupada com a
compatibilidade entre as verses, possibilitando que uma simples manuteno
atualize toda a rotina especfica, isto se esta manuteno for necessria, pois a
rotina padro poder tratar a novas informaes com contedos padres
dependendo da situao em que estas no forem informadas.
 A aplicao ERP pode ser personalidada atravs de pontos de entrada e
do dicionrio de dados:
A partir do momento que uma aplicao padro desenvolvida e disponibilizada a
mesma pode sofrer diversas personalizaes em campo, as quais podem ser
implementadas em paralelo ou aps o desenvolvimento da rotina especfica
disponibilizada pelo desenvolvedor.
Se esta situao no for prevista, a incluso de informaes utilizando a rotina
padro do sistema poder sofrer diversas validaes ou at mesmo efetuar a
gravao de informaes adicionais, as quais no esto visveis na rotina especfica,
gerando graves inconistncias na base de dados.
Avaliando estas consideraes percebesse o fator de sucesso que um desenvolvimento
especfico pode ter ao optar por refazer todos os tratamentos do sistema em detrimento de
utilizar a funcionalidade MsExecAuto, ou seja, qualquer modificao no ambiente,
independente do quo simples pode tornar a rotina especfica inadequada.

- 269 ADVPL Avanado

Quando utilizar a funcionalidade MsExecAuto ?


Tendo em vista este cenrio fica a pergunta: Quando utilizar a funcionalidade MsExecAuto ?
A resposta pode ser bvia e at conservadora, mas Sempre que a funcionalidade estiver
disponvel naquele processo.
Em resumo, qualquer funcionalidade de interface, seja ela de carga ou contnua, qualquer
funcionalidade de atualizao, ou seja, qualquer manuteno na base de dados do sistema,
sempre que possvel, deve utilizar a funcionalidade MsExecAuto.

Processos da aplicao ERP com tratamentos para execuo por MsExecAuto


Pode-se dizer que as principais rotinas de atualizao do ERP Protheus atualmente possuem o
tratamento necessrio para sua execuo por MsExecAuto, e com base nas necessidades de
desenvolvimento internas da TOTVS e nas melhorias solicitadas por clientes e analistas de
implantao as demais rotinas necessrias so atualizadas para contemplar este tratamento.
O quadro abaixo ilustra um dos ltimos cenrios de tratamento de MsExecAuto pelas rotinas
da aplicao ERP Protheus.
Rotina
ATFA010
ATFA030
ATFA035
CFGX016
CTBA015
CTBA016
CTBA020
CTBA102
CTBA270
FATA140
FATA220
FATA300
FATA310
FATA320
FINA010
FINA040
FINA050
FINA070
FINA080
FINA390
MATA040
MATA080
MATA103
MATA105
MATA110
MATA116A
MATA120
MATA125
MATA140
MATA145
MATA150

Parmetros
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, nOpc)
(xAutoCab, nOpc)
(xAutoCab, xAutoItens)
(nOpcAuto, aAuto)
(nOpcAuto, aAuto)
(aRotAuto, nOpcAuto, aRotItem)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(nOpcAuto, aAuto)
(nOpcAuto, aAutoCab)
(nOpcAuto, xAutoCab, xAutoAD2, xAutoAD3, xAutoAD4, xAutoAD9)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoVend, xAutoTask, xAutoCalend)
(aRotAuto, nOpcAuto)
(aRotAuto, nOpcAuto)
(aRotAuto, nOpcion, nOpcAuto)
(xAutoCab, nOpc)
(xAutoCab, nOpc)
(nPosArotina, xAutoCab, nOpcAuto)
(aAuto, nOpcAuto)
(aRotauto, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto, lWhenGet, xAutoImp)
(xReservCab, xReservItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, lInclui)
(nFuncao, xAutoCab, xAutoItens, nOpcAuto, )
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoIt, xAutoIt2, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
- 270 ADVPL Avanado

Rotina
MATA175
MATA185
MATA200
MATA230
MATA241
MATA242
MATA261
MATA265
MATA266
MATA267
MATA360
MATA410
MATA415
MATA416
MATA490
MATA685
MATA700
MATA920
TMKA061
TMKA062
TMKA271
TMSA040
TMSA050
TMSA170
TMSA360
TMSA430
TMSA440

Parmetros
(xRotAuto, xOpcAuto)
(xAutoSCP, xAutoSD3, nOpcAuto, xPerg)
(xAutoCab, xAutoItens, nOpcAuto)
(aAuto, nOpcAuto)
(xAutoCab, xAutoItens, nCallOpcx)
(xAutoCab, xAutoItens, nOpcAuto)
(aAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(aAutoItens)
(aAutoItens)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens)
(xAuto, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAuto, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)
(xAutoCab, xAutoItens, xItensPesM3, xItensEnder, nOpcAuto)
(xAutoCab, nOpcAuto)
(xAutoCab, xAutoItens, xAutoNFAva, nOpcAuto)
(cAlias, xAutoCab, xAutoVei, xAutoMot, nOpcAuto)
(xAutoCab, xAutoItens, nOpcAuto)

Quando no utilizar a funcionalidade MsExecAuto


Apesar de todas as orientaes dos tpicos anteriores existem situaes nas quais no
recomendado utilizar a funcionalidade MsExecAuto, no caso, em situaes para as quais
existem rotinas padres da aplicao ERP para processamentos de integraes e atualizaes
que possuem tratamento para execuo direta ou execuo via Job.
Para estes casos a rotina j est pr-disposta a execuo direta, no havendo a necessidade
de tratamento via MsExecAuto, ou o tratamento realizado pela rotina o mais adequado para
aquele volume de dados.
O exemplo clssico desta situao para importao de lanamentos ou saldos contbeis. A
aplicao ERP possui uma rotina de integrao denominada Contabilizao TXT (CTBA500)
mas a rotina de lanamentos contbeis (CTBA102)
pode ser executada atravs da
MsExecAuto.
Para importaes de saldos e lanamentos deve-se optar pela utilizao da rotina de
Contabilizao TXT, devido aos tratamentos que a mesma permite atravs das configuraes
da prpria rotina em conjunto com as parametrizaes do mdulo. O uso da CTBA102
Laamentos Contbeis via MsExecAuto recomendado para rotinas de manuteno ou
funcionalidades especficas / melhorias, com por exemplo o estorno de lanamentos contbeis
sem a necessidade de avaliar regras de contabilizao.

- 271 ADVPL Avanado

9.1.

Desenvolvendo aplicaes com MsExecAuto

Estrutura de uma rotina com execuo de MsExecAuto


 Definio das variveis de controle da MsExecAuto
 Montagem dos arrays de parmetros
 Definio dos parmetros especficos da rotina que ser executada
 Controle de transao
 Tratamento do sucesso ou no da operao
Variveis de controle
 Private lMsErroAuto
Indica de se houve erro no fatal durante a execuo.
 Private lMsHelpAuto
Habilita a captura das mensagens de erro.
 Private lAutoErrNoFile
Desabilita a gerao do arquivo de log padro do sistema.

Montagem dos arrays de parmetros


 Tipos de arrays de parmetros:
Basicamente uma MsExecAuto possui dois tipos de arrays de parmetros: Array de
Dados de Cabealho e Array de Dados de Itens.
Os exemplos a seguir visam ilustrar a utilizao de cada uma dos tipos de arrays:
 Cadastro de clientes (MATA030): Esta rotina atualiza apenas os dados da tabela
SA1 Cadastro de Clientes, portanto ser necessrio apenas um array de dados
contendo as informaes que devero ser gravadas na tabela SA1.
 Documentos de entrada (MATA103): Esta rotina atualiza basicamente os dados
das tabelas SF1 Cabealho do Documento de Entrada e SD1 Itens do
Documento de entrada, portanto sero necessrios dois arrays de dados
contendo as informaes do cabealho do documento de entrada e dos itens do
documento de entrada, sendo que este ltimo ter sua estrutura de contedo
repetida para cada item do documento.
 Aviso de Recebimento de Carga (MATA145): Esta rotina atualiza basicamente os
dados das tabelas DB1 Aviso de Recebimento de Carga, DB2 Cabealho do
documento recebido e DB3 Itens do documento recebido, portanto so
necessrios trs array de dados contendo as respectivas informaes para as
tabelas DB1, DB2 e DB3, sendo que as duas ltimas tero suas estruturas de
contedo repetidas para cada documento recebido.

- 272 ADVPL Avanado

 Estrutura dos arrays de parmetros:


 Array de dados do cabealho (xAutoCab):
O array contendo os dados do cabealho composto por: Campo, Contedo e
Validao.
Cada item deste array um dos campos da tabela de cabealho das informaes
que sero processadas pela MsExecAuto. Com base nos exemplos anteriores, a
MsExecAuto da MATA030 possui apenas um array de parmetros no formato
xAutoCab, sendo que a MATA103 utilizar o xAutoCab para a tabela SF1 e a
MATA145 para a tabela DB1.
Sintaxe:

AADD(xAutoCab,{Campo, xContedo, Validao})

Exemplo:

AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

,
,
,
,

Nil})
Nil})
Nil})
Nil})

MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)

 Array de dados dos itens (xAutoItens):


O array contendo os dados dos itens tambm composto por: Campo, Contedo
e Validao; sendo que a diferena est no fato de que para cada item a ser
tratado pela MsExecAuto dever ser repetida e preenchida a estrutura do array
com as informaes do mesmo.
Com base nos exemplos anteriores, a MsExecAuto da MATA030 no possui um
array de parmetros no formato xAutoItens, j a MATA103 utilizar o xAutoItens
para a tabela SD1 e a MATA145 utilizar dois xAutoItens, sendo o primeiro para
a tabela DB2 e o segundo para a tabela DB3.
Sintaxe:

<Estrutura de controle e repetio>


xAutoItem := {}
AADD(xAutoItem,{Campo, xContedo, Validao})
AADD(xAutoItens, xAutoItem)
</Estrutura>

- 273 ADVPL Avanado

Exemplo:

AADD(xAutoCab,{F1_FILIAL
AADD(xAutoCab,{F1_DOC
AADD(xAutoCab,{F1_SERIE
AADD(xAutoCab,{F1_FORNECE
AADD(xAutoCab,{F1_LOJA

,
,
,
,
,

xFilial(SF1)
000001
1
000001
01

,
,
,
,
,

Nil})
Nil})
Nil})
Nil})
Nil})

For nX := 1 to 2
xAutoItem := {}
AADD(xAutoItem,{D1_FILIAL
AADD(xAutoItem,{D1_DOC
AADD(xAutoItem,{D1_SERIE
AADD(xAutoItem,{D1_FORNECE
AADD(xAutoItem,{D1_LOJA
AADD(xAutoItem,{D1_ITEM
AADD(xAutoItem,{D1_COD
AADD(xAutoItem,{D1_QUANT
AADD(xAutoItem,{D1_VUNIT
AADD(xAutoItem,{D1_TOTAL
AADD(xAutoItem,{D1_TES

,
,
,
,
,
,
,
,
,
,
,

xFilial(SD1)
000001
1
000001
01
STRZERO(nx,04)
STRZERO(nx,15)
100*nX
5*nX
(100*nX)*(5*nX)
001

,
,
,
,
,
,
,
,
,
,
,

Nil})
Nil})
Nil})
Nil})
Nil})
Nil})
Nil})
Nil})
Nil})
Nil})
Nil})

AADD(xAutoItens, xAutoItem)
Next nX
MsExecAuto({|x,y,z| MATA103(x,y,z)}, xAutoCab, xAutoItens, 3)

 Mtodo de atribuio de contedo Direto:


O mtodo direto consiste em atribuir diretamente na montagem do array de parmetros
o contedo de cada campo que ser tratado pela MsExecAuto.
Este mtodo o mais comum de ser utilizado dado sua praticidade, e pela possibilidade
do desenvolvedor especificar somente os campos obrigatrios para a tabela e aqueles
que contero as informaes geradas por sua aplicao.
Exemplo:

AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)

- 274 ADVPL Avanado

,
,
,
,

Nil})
Nil})
Nil})
Nil})

 Mtodo de atribuio de contedo pela estrutura:


O mtodo de atribuio pela estrutura recomendvel em rotinas que efetuam a
importao das informaes atravs da leitura de arquivos de dados, sejam eles
CODEBASE ou via banco de dados.
Este mtodo consiste em comparar a estrutura do arquivo de origem (a ser importado)
contra a do arquivo de destino (tratado pela MsExecAuto). Desta forma os campos que
forem coincidentes entre o arquivo de origem e o arquivo de destino sero preenchidos
com as informaes do arquivo importado, caso contrrio os mesmos podero ser
desconsiderados ou serem preenchidos com um contedo padro.
Exemplo:

// Captura a estrutura da tabela padro do sistema


DbSelectArea("SN1")
DbSetOrder(1)
aStruSN1 := SN1->(DbStruct())
// Efetua a abertura do arquivo SN1 que ser importado
cArqSN1:= cDirArq+"SN1IMP"
IF File(cArqSN1+cFileExt)
dbUseArea(.T.,,cArqSN1+cFileExt,"SN1IMP",.F.,.F.)
IndRegua("SN1IMP",cArqSN1+OrdBagExt(),"N1_FILIAL+N1_CBASE+N1_ITEM",;
,,"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SN1IMP no existe."+;
CRLF+"Verifique caminho informado.",1,0)
RETURN
ENDIF
// Efetua a leitura do arquivo a ser importado
DbSelectArea("SN1IMP")
DbGotop()
WHILE SN1IMP->(!Eof())
// Efetua a montagem do xAutoCab com base nas estruturas dos
// arquivos
FOR nX := 1 TO LEN(aStruSN1)
IF SN1IMP->(FieldPos(aStruSN1[nX][1]))>0
DO CASE
CASE EMPTY(SN1IMP->&(aStruSN1[nX][1]))
AADD(xAutoCab,{aStruSN1[nX][1],;
CRIAVAR(aStruSN1[nX][1]), NIL})
CASE aStruSN1[nX][2] == "C"
AADD(xAutoCab,{aStruSN1[nX][1],;
SN1IMP->&(aStruSN1[nX][1]),;
"",aStruSN1[nX][3]), NIL})
CASE aStruSN1[nX][2] == "N"
AADD(xAutoCab,{aStruSN1[nX][1],;
ABS(SN1IMP->&(aStruSN1[nX][1])), NIL})

- 275 ADVPL Avanado

OTHERWISE
AADD(xAutoCab,{aStruSN1[nX][1],;
SN1IMP->&(aStruSN1[nX][1]), NIL})
ENDCASE
ELSE
AADD(xAutoCab,{aStruSN1[nX][1],;
CRIAVAR(aStruSN1[nX][1]), NIL})
ENDIF
NEXT nX
...
MsExecAuto({|x,y,z| ATFA010(x,y,z)}, xAutoCab, xAutoItens, 3)
END

Definio dos parmetros especficos da rotina que ser executada


Este ponto no qual o desenvolvedor inclui os tratamentos necessrios a correta execuo da
rotina, alm de seus tratamentos especficos, os quais justificaram o desenvolvimento.
Utilizando o mesmo exemplo anterior da ATFA010 Cadastro de Ativos podemos citar dois
tratamentos especficos necessrios para a correta execuo da MsExecAuto:
 Chamada das perguntas da ATFA010:
A execuo da funo Pergunte(ATFA010,.F.) permite que seja definidos os
contedos desejados para os parmetros da rotina de cadastro conforme a
necessidade da aplicao, como por exemplo permitir a incluso de uma chapa de
bem em branco ou no efetuar a contabilizao da incluso.
 Atualizao das variavis de memria do ALIAS M-> para o SN1:
A execuo da funo RegToMemory(SN1,.T.) necessria para a utilizao da
funo CRIAVAR() no mtodo de atribuio pela estrutura.

Muitas vezes uma estrutura que funciona para um MsExecAuto pode no


funcionar para outro do mesmo tipo, devido as caractersticas individuais de
cada rotina. Podemos citar os seguintes exemplos:
 MATA103 (Documento de Entrada): Para tratamento do ttulo
financeiro a ser gerado pela nota fiscal quando o parmetro de
atualizao de financeiro da TES est ativado, deve ser includo
o seguinte item no array xAutoCab:
{" E2_NATUREZ "

,"NAT01"

,NIL})

 MATA650 (Abertura de ordem de produo): Para que sejam


geradas as ordens de produo intermedirias na abertura de
uma ordem de produo principal deve ser includo o seguinte
item no array xAutoCab:
{"AUTEXPLODE"

,"S"

- 276 ADVPL Avanado

,NIL})

Controle de transao
A utilizao do controle de transao permite garantir a integridade das informaes gravadas
pelo processamento.
Para utilizao do controle de transao na aplicao podem ser utilizados os seguintes blocos
de controle:
 Begin Transaction ... DisarmTransaction() ... End Transaction
Um bloco de cdigo determinado pelos comandos Begin Transaction ... End Transaction
ter suas informaes atualizadas somente se antes do execuo do comando End
Transaction no for executada a funo DisarmTransaction().
Desta forma pode-se implementar um controle de transao por item processado, sendo
executado o DisarmTransaction() para aquele elemento em que houve algum problema
de processamento.
Seguindo este mesmo raciocnio, caso ocorra um erro fatal na aplicao, somente o item
que est em processamento ser desconsiderado, pois a aplicao ERP efetua um
DisarTransaction() automaticamente, fechamento as transaes pendentes e
restaurando as situaes anteriores, mas apenas para aqueles processamento protegidos
pelo bloco de controle de transao.

O comando END TRANSACTION no pode ter sua interpretao vinculada a


uma condio. Nestes casos ocorrer um erro de compilao indicando que o
bloco aberto pelo comando BEGIN TRANSACTION no foi corretamente
fechado.

Exemplo:

AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

BEGIN TRANSACTION
lMsErroAuto := .F.
MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)
IF lMsErroAuto
DisarmTransaction()
ENDIF
END TRANSACTION

- 277 ADVPL Avanado

,
,
,
,

Nil})
Nil})
Nil})
Nil})

 BeginTran() ... DisarmTransaction() ... EndTran()


As funes BeginTran() e EndTran() visam permitir que o trmino da transao seja
condicional, eliminando a limitao da estrutura BEGIN TRANSACTION ... END
TRANSACTION.
Exemplo:

AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

,
,
,
,

Nil})
Nil})
Nil})
Nil})

BeginTran()
lMsErroAuto := .F.
MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)
IF lMsErroAuto
DisarmTransaction()
ELSE
EndTran()
ENDIF
MsUnlockAll()

Neste modelo de controle de transao recomendvel a utilizao da funo


MsUnlockAll() para destravar todos os registros que estejam eventualmente
travados.

- 278 ADVPL Avanado

Tratamento de mensagens de erro


Com a utilizao da funcionalidade MsExecAuto a aplicao ERP disponibiliza diversos mtodos
para visualizao e tratamento das mensagens de erro ocorridas durante a execuo da rotina,
sendo estes:
 Visualizao do evento de erro;
 Gravao do evento de erro em arquivo texto;
 Personalizao da gravao do evento de erro.

 Visualizao do evento de erro


Para visualizao em tela do evento de erro ocorrido durante o processamento da
rotina via MsExecAuto deve-se utilizar a funo MostraErro(), conforme o exemplo:

Private lMsHelpAuto
:= .T.
Private lAutoErrNoFile := .F.
AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

,
,
,
,

Nil})
Nil})
Nil})
Nil})

BEGIN TRANSACTION
lMsErroAuto := .F.
MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)
IF lMsErroAuto
MostraErro()
DisarmTransaction()
ENDIF
END TRANSACTION

O contedo das variveis PRIVATE de controle da MsExecAuto deve ser


configurado conforme abaixo:
Private lMsHelpAuto
Private lAutoErrNoFile

:= .T.
:= .F.

- 279 ADVPL Avanado

 Gravao do evento de erro em arquivo texto


Para gravao em arquivo no formato texto do evento de erro ocorrido durante o
processamento da rotina via MsExecAuto deve-se utilizar a funo MostraErro(),
conforme o exemplo:

Private lMsHelpAuto
:= .T.
Private lAutoErrNoFile := .F.
AADD(xAutoCab,{A1_FILIAL
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

,
,
,
,

xFilial(SA1)
000001
01
TESTE-000001

,
,
,
,

Nil})
Nil})
Nil})
Nil})

BEGIN TRANSACTION
lMsErroAuto := .F.
MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)
IF lMsErroAuto
MostraErro(\system\)
DisarmTransaction()
ENDIF
END TRANSACTION

A funo MostraErro() possui o parmetro cPath o qual pode ser informado


de duas formas:
 Apenas o diretrio: Se for informado apenas o diretrio ser
gerado um arquivo com denominao no formato SCxxxxxx.log,
aonde xxxxxx ser um nmero sequencial gerado internamente
pelo sistema.
 Informando o diretrio e o nome do arquivo: A funo ir
respeitar o nome do arquivo informado, sobrescrendo o
contedo anterior.

Caso seja necessrio gerar um nico arquivo texto contendo todos os


eventos de erro gerados pelos sucessivos processamentos da MsExecAuto,
a funo MostraErro(cPath) dever ser chamada apenas uma vez, ao
trmino do processamento da rotina.
Isto ocorre pois a funo MostraErro() limpa o cache de eventos de erros
controlado pela MsExecAuto.

- 280 ADVPL Avanado

 Personalizao da gravao do evento de erro


Para processamentos mais volumosos, a gerao de diversos arquivos de textos ou
at mesmo a gerao de um nico arquivo texto contendo todos os eventos de erro
pode dificultar a anlise e correo dos problemas encontrados durante o
processamento.
Desta forma possvel personalizar a gravao do evento de erro, de forma que o
mesmo seja gerado em um arquivo no formato .DBF, permitindo o vnculo do registro
processado com a mensagem de erro gerada.

Private lMSHelpAuto
:= .F.
Private lAutoErrNoFile := .T.
AADD(xAutoCab,{A1_COD
AADD(xAutoCab,{A1_LOJA
AADD(xAutoCab,{A1_NOME

, 000001
, 01
, TESTE-000001

, Nil})
, Nil})
, Nil})

// Funo especfica que cria o arquivo no formato DBF que conter as


// mensagens de erro.
XDBFLOG()
BEGIN TRANSACTION
lMsErroAuto := .F.
MsExecAuto({|x,y| MATA030(x,y)}, xAutoCab, 3)
IF lMsErroAuto
// Funo que retorna o evento de erro na forma de um array
aAutoErro := GETAUTOGRLOG()
// Funo especifica que converte o array aAutoErro em texto
// contnuo, com a quantidade de caracteres desejada por linha
// Funo especfica que efetua a gravao do evento de erro no
// arquivo previamente crado.
XGRVLOG(XCONVERRLOG(aAutoErro))
DisarmTransaction()
ENDIF
END TRANSACTION

As funes especficas XDBFLOG(), XCONVERRLOG() e XGRVLOG() sero


detalhadas no exemplo completo de utilzao da funo MsExecAuto().

- 281 ADVPL Avanado

Aplicao completa de importao utilizando MsExecAuto: Carga de imobilizado


#INCLUDE "PROTHEUS.CH"
/*/
+----------------------------------------------------------------------| Funo
| IATF001
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | IMPORTACAO DO CADASTRO DE ATIVO IMOBILIZADO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION IATF001()
LOCAL oProcess
PRIVATE oMainWnd
//Perguntas para parametrizacao da rotina (PARAMBOX)
//MVParBox01 - Tipo de informao (.DBF/.TXT)
//MVParBox02 - LayOut do arquivo (Padro / Especifico)
//MVParBox03 - Arquivo de dados
(Consulta)
//MVParBox04 - Arquivo de layout (Consulta)
//MVParBox05 - Operacao
(Incluir, Alterar, Excluir)
//MVParBox06 - Diretorio de Log
(Consulta)
//MVParBox07 - Importa CIAP
(SIM/NAO)
PRIVATE
PRIVATE
PRIVATE
PRIVATE
PRIVATE
PRIVATE
PRIVATE
PRIVATE

aTiposFile
MvParBox01
MvParBox02
MvParBox03
MvParBox04
MvParBox05
MvParBox06
MVParBox07

PRIVATE _cDirectory

:=
:=
:=
:=
:=
:=
:=
:=

{".DBF",".DTC",".TXT"}
0
0
""
""
0
""
0
:= ""

RpcSetType(3)
RpcSetEnv("99", "01",,,,,
{"CT1","SF9","SN1","SN2","SN3","SN4","SN5","SNG","SM2"})
SET DATE FORMAT "dd/mm/yyyy"
oMainWnd := TWindow():New( 000, 000, 001, 001, "Importao: Fichas do
imobilizado",,,,,,,,,,,,,,,,.T.)
oMainWnd:bInit := {|| IIF(IC001PARBX(),(oProcess:= MsNewProcess():New({|lEnd|
PROCATIVO(.F.,oProcess)}),oProcess:Activate(),oMainWnd:End()),oMainWnd:End())}
oMainWnd:Activate("ICONIZED")
RpcClearEnv()
RETURN

- 282 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| PROCATIVO
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | PROCESSAMENTO DA IMPORTACAO DO CADASTRO DE IMOBILIZADO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION PROCATIVO(lEnd,oProcess)
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aArea
aDadosSN1
aDadosSN3
aDadosSF9
aDadosTN1
aDadosTN2
aDadosTN3
aItemSN3
cArqSN1
cArqSN2
cArqSN3
cArqSA2
aStruSN1
aStruSN2
aStruSN3
aStruSF9
nX
nTotRegs
nProcRegs
nPosDados
cCodFor
cLojaFor
cDescFor
cFilAtu
cDirArq
cHistorico
nX
cFileExt
lImpSF9
lImpSNG
cKeyImp
aAutoErro

:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=

GetArea()
{}
{}
{}
{}
{}
{}
{}
""
""
""
""
{}
{}
{}
{}
0
0
0
0
""
""
""
cFilAnt
Alltrim(MVParBox03)
""
0
aTiposFile[MvParBox01]
MvParBox07==1
.F. // Ainda nao implementado
""
{}

// Tratamentos adicionais - arquivos especificos do cliente


Local cArqCTA
:= ""
Local cArqSM2
:= ""
Local cIndSNG
Local nIndex
:= 0
Local cGrupo
:= ""
Local cContab
:= ""
Local aEntSNG
:= {}
Local cChapa
:= "000000"
Private lMsErroAuto
Private lMSHelpAuto

:= .F.
:= .F.
- 283 ADVPL Avanado

Continuao:
Private lAutoErrNoFile

:= .T.

// Garante a abertura dos arquivos padres do sistema


DbSelectArea("CT1")
DbSetOrder(2) // FILIAL + COD.REDUZIDO
DbSelectArea("SM2")
DbSetOrder(1)
DbSelectArea("SN1")
DbSetOrder(1)
aStruSN1 := SN1->(DbStruct())
DbSelectArea("SN2")
DbSetOrder(1)
aStruSN2 := SN2->(DbStruct())
DbSelectArea("SN3")
DbSetOrder(1)
aStruSN3 := SN3->(DbStruct())
DbSelectArea("SF9")
DbSetOrder(1)
aStruSF9 := SF9->(DbStruct())
// Prepara o arquivo no formato .DBF para gravao dos eventos de erro
XDBFLOG()
DbSelectArea("SNG")
cIndSNG := CRIATRAB(Nil,.F.)
IndRegua("SNG",cIndSNG,"NG_FILIAL+NG_CCONTAB",,,"Selecionando Registros...")
nIndex := RetIndex()
#IFNDEF TOP
DbSetIndex(cIndSNG+OrdBagExt())
#ENDIF
DbSetOrder(nIndex)
PERGUNTE("ATF010",.F.)
MV_PAR02 := 1 // Permite repetir chapa definido como sim
IF Select("SN1IMP") > 0
DbSelectArea("SN1IMP")
DbCloseArea()
ENDIF
IF Select("SN2IMP") > 0
DbSelectArea("SN2IMP")
DbCloseArea()
ENDIF
IF Select("SN3IMP") > 0
DbSelectArea("SN3IMP")
DbCloseArea()
ENDIF
IF Select("SF9IMP") > 0
DbSelectArea("SF9IMP")
DbCloseArea()
ENDIF

- 284 ADVPL Avanado

Continuao:
IF Select("CTAIMP") > 0
DbSelectArea("CTAIMP")
DbCloseArea()
ENDIF
cArqSN1:= cDirArq+"SN1IMP"
IF File(cArqSN1+cFileExt)
dbUseArea(.T.,,cArqSN1+cFileExt,"SN1IMP",.F.,.F.)
IndRegua("SN1IMP",cArqSN1+OrdBagExt(),"N1_FILIAL+N1_CBASE+N1_ITEM",,,;
"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SN1IMP no existe."+CRLF+;
"Verifique caminho informado.",1,0)
RETURN
ENDIF
cArqSN2:= cDirArq+"SN2IMP"
IF File(cArqSN2+cFileExt )
dbUseArea(.T.,,cArqSN2+cFileExt,"SN2IMP",.F.,.F.)
IndRegua("SN2IMP",cArqSN2+OrdBagExt(),;
"N2_FILIAL+N2_CBASE+N2_ITEM+N2_TIPO+N2_SEQ",,,"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SN2IMP no existe."+CRLF+;
"Verifique caminho informado.",1,0)
RETURN
ENDIF
cArqSN3:= cDirArq+"SN3IMP"
IF File(cArqSN3+cFileExt)
dbUseArea(.T.,,cArqSN3+cFileExt,"SN3IMP",.F.,.F.)
IndRegua("SN3IMP",cArqSN3+OrdBagExt(),"N3_FILIAL+N3_CBASE+N3_ITEM",,,;
"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SN3IMP no existe."+CRLF+;
"Verifique caminho informado.",1,0)
RETURN
ENDIF
IF lImpSF9
cArqSF9:= cDirArq+"SF9IMP"
IF File(cArqSF9+cFileExt )
dbUseArea(.T.,,cArqSF9+cFileExt,"SF9IMP",.F.,.F.)
IndRegua("SF9IMP",cArqSF9+OrdBagExt(),"F9_FILIAL+F9_CODIGO",,,;
"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SF9IMP no existe."+;
CRLF+"Verifique caminho informado.",1,0)
RETURN
ENDIF
ENDIF

- 285 ADVPL Avanado

Continuao:
cArqCTA:= cDirArq+"CTAIMP"
IF File(cArqCTA+cFileExt)
dbUseArea(.T.,,cArqCTA+cFileExt,"CTAIMP",.F.,.F.)
IndRegua("CTAIMP",cArqCTA+OrdBagExt(),"CODIGO_CON",,,;
"Selecionando Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO CTAIMP no existe."+CRLF+;
"Verifique caminho informado.",1,0)
RETURN
ENDIF
cArqSM2:= cDirArq+"SM2IMP"
IF File(cArqSM2+cFileExt)
dbUseArea(.T.,,cArqSM2+cFileExt,"SM2IMP",.F.,.F.)
IndRegua("SM2IMP",cArqSM2+OrdBagExt(),"DTOS(BTN_DATA)",,,"Selecionando
Registros...")
ELSE
HELP("IATF001",1,"HELP","NO_FILE","ARQUIVO SM2IMP no existe."+CRLF+;
"Verifique caminho informado.",1,0)
RETURN
ENDIF
lMSHelpAuto := .T.
DbSelectArea("SN1IMP")
DbGotop()
//
// Preparao para inicio do processamento

//
cKeyImp := DTOS(dDatabase)+StrZero(HoraToInt(Time()),6)
// Identidficador dos registros do log de erros
ConOut("Processando importao:")
ConOut("Inicio: "+Time())
ConOut("Registros SN1IMP: "+CValToChar(SN1IMP->(RecCount())))
ConOut("Registros SN2IMP: "+CValToChar(SN2IMP->(RecCount())))
ConOut("Registros SN3IMP: "+CValToChar(SN3IMP->(RecCount())))
dbEval( {|x| nTotRegs++ },,{||SN1IMP->(!EOF())})
oProcess:SetRegua1(nTotRegs+2)
oProcess:IncRegua1("Iniciando processamento...")
oProcess:SetRegua2(nTotRegs+1)
oProcess:IncRegua2("Ficha de Ativo:")
DbSelectArea("SN1IMP")
DbGotop()

- 286 ADVPL Avanado

Continuao:
While SN1IMP->(!Eof())
nProcRegs++
oProcess:IncRegua1("Processando item: "+CValToChar(nProcRegs)+" / "+;
CValToChar(nTotRegs))
oProcess:IncRegua2("Ficha de Ativo: ")
aDadosSN1 := {}
aDadosSN3 := {}
// Compatibilizao para utilizao do CRIAVAR()
REGTOMEMORY("SN1",.T.)
//Monstagem do array com dados sem tratamento e com as informao da IMP
FOR nX := 1 TO LEN(aStruSN1)
IF SN1IMP->(FieldPos(aStruSN1[nX][1]))>0
DO CASE
CASE EMPTY(SN1IMP->&(aStruSN1[nX][1]))
AADD(aDadosSN1,{aStruSN1[nX][1],;
CRIAVAR(aStruSN1[nX][1]), NIL})
CASE aStruSN1[nX][2] == "C"
AADD(aDadosSN1,{aStruSN1[nX][1],;
SN1IMP->&(aStruSN1[nX][1]),;
"",aStruSN1[nX][3]), NIL})
CASE aStruSN1[nX][2] == "N"
AADD(aDadosSN1,{aStruSN1[nX][1],;
ABS(SN1IMP->&(aStruSN1[nX][1])), NIL})
OTHERWISE
AADD(aDadosSN1,{aStruSN1[nX][1],;
SN1IMP->&(aStruSN1[nX][1]), NIL})
ENDCASE
ELSE
AADD(aDadosSN1,{aStruSN1[nX][1], CRIAVAR(aStruSN1[nX][1]),;
NIL})
ENDIF
NEXT nX
// Alterao das informaes do array de acordo com a necessidade
// AADD(aDadosTN1,{"CAMPO",CONTEUDO,"VALIDACAO"})
aDadosTN1
:= {}
// ALTERACAO DO ARRAY ADADOSSN1 COM AS INFORMACOES TRABALHADAS E
// ARMAZENADAS EM ADADOSTN1
// AADD(aDadosTN1,{"N1_XXXXXX"
,xConteudo
,Nil})
For nX := 1 TO LEN(aDadosTN1)
IF (nPosField := aScan(aDadosSN1,{|aDadoSN1| aDadosSN1[1] ==;
aDadosTN1[nX][1]})) > 0
aDadosSN1[nPosField][2] := aDadosTN1[nX][2]
aDadosSN1[nPosField][3] := aDadosTN1[nX][3]
ENDIF
Next nX

- 287 ADVPL Avanado

Continuao:
IF SN1->(DbSeek(aDadosSN1[1][2]+aDadosSN1[2][2]+aDadosSN1[3][2]))
ConOut("Registro j importado: "+;
aDadosSN1[1][2]+"/"+aDadosSN1[2][2]+"/"+aDadosSN1[3][2])
ConOut("Registros importados com sucesso: "+CValToChar(nProcRegs))
SN1IMP->(dbSkip())
Loop
ENDIF
SN3IMP->(DbSeek(SN1IMP->(N1_FILIAL+N1_CBASE+N1_ITEM)))
While SN3IMP->(!Eof()) .AND. SN3IMP->(N3_FILIAL+N3_CBASE+N3_ITEM) ==;
SN1IMP->(N1_FILIAL+N1_CBASE+N1_ITEM)
aItensSN3 := {}
// Monstagem do array com dados sem tratamento e com as informaes
FOR nX := 1 TO LEN(aStruSN3)
IF SN3IMP->(FieldPos(aStruSN3[nX][1]))>0
DO CASE
CASE EMPTY(SN3IMP->&(aStruSN3[nX][1]))
AADD(aItensSN3,{aStruSN3[nX][1],;
CRIAVAR(aStruSN3[nX][1]), NIL})
CASE aStruSN3[nX][2] == "C"
AADD(aItensSN3,{aStruSN3[nX][1],;
SN3IMP->&(aStruSN3[nX][1]),;
aStruSN3[nX][3]), NIL})
CASE aStruSN3[nX][2] == "N"
AADD(aItensSN3,{aStruSN3[nX][1],;
ABS(SN3IMP->&(aStruSN3[nX][1])),;
".T."})
OTHERWISE
AADD(aItensSN3,{aStruSN3[nX][1],;
SN3IMP->&(aStruSN3[nX][1]), NIL})
ENDCASE
ELSEIF aStruSN3[nX][2] == "N"
AADD(aItensSN3,{aStruSN3[nX][1],;
CRIAVAR(aStruSN3[nX][1]), ".T."})
ELSE
AADD(aItensSN3,{aStruSN3[nX][1],;
CRIAVAR(aStruSN3[nX][1]), NIL})
ENDIF
NEXT nX
// Alterao das informaes do array de acordo com a necessidade
// AADD(aDadosTN3,{"CAMPO"
,CONTEUDO,"VALIDACAO"})
aDadosTN3 := {}
// ALTERACAO DO ARRAY aItenSN3
// ARMAZENADAS EM aDadosTN3

COM AS INFORMACOES TRABALHADAS E

For nX := 1 TO LEN(aDadosTN3)
IF (nPosField := aScan(aItensSN3,{|aItenSN3| aItenSN3[1] ==;
aDadosTN3[nX][1]})) > 0
aItensSN3[nPosField][2] := aDadosTN3[nX][2]
aItensSN3[nPosField][3] := aDadosTN3[nX][3]
- 288 ADVPL Avanado

Continuao:
ENDIF
Next nX
AADD(aDadosSN3,aItensSN3)
SN3IMP->(DbSkip())
Enddo
IF

Len(aDadosSN1) > 0 .AND. Len(aDadosSN3) > 0


ConOut("Iniciando MsExecAuto - ATFA010: "+Time())
Begin Transaction
cFilAnt := SN1IMP->N1_FILIAL
lMsErroAuto := .F.
MSExecAuto({|x,y,z| Atfa010(x,y,z)},aDadosSN1,aDadosSN3,3)
// Cabealho, Itens e Opo
ConOut("Finalizada MsExecAuto - ATFA010: "+Time())
IF lMsErroAuto
aAutoErro := GETAUTOGRLOG()
XGRVLOG(cKeyImp,;
SN1IMP->(N1_FILIAL+N1_CBASE+N1_ITEM),;
SN1IMP->N1_DESCRIC, XCONVERRLOG(aAutoErro))
DisarmTransaction()
MostraErro(Alltrim(MVParBox06))
ELSE
// TRATAMENTO DA DESCRIO ESTENDIDA (SN2)
SN2IMP->(DbSeek(SN1IMP->(N1_FILIAL+N1_CBASE+N1_ITEM)))
cHistorico := ALLTRIM(SN2IMP->N2_HISTOR1) +;
ALLTRIM(SN2IMP->N2_HISTOR2)
For nX := 1 to Len(cHistorico) STEP 40
RECLOCK("SN2",.T.)
SN2->N2_FILIAL
:=
SN2->N2_CBASE
:=
SN2->N2_ITEM
:=
SN2->N2_TIPO
:=
SN2->N2_SEQ
:=
SN2->N2_SEQUENC
:=
SN2->N2_HISTOR
:=
MSUNLOCK()

SN1->N1_FILIAL
SN1->N1_CBASE
SN1->N1_ITEM
"01"
"001"
STRZERO(nX,2)
SUBSTR(cHistorico,nX,40)

NEXT nX
// TRATAMENTO DA CARGA DO CIAP
IF lImpSF9
IATFCIAP(aStruSF9,aDadosSF9)
ENDIF
ConOut("Registros importados com sucesso: "+;
CValToChar(nProcRegs))
ENDIF
End Transaction
- 289 ADVPL Avanado

Continuao:
ENDIF
SN1IMP->(DbSkip())
Enddo
oProcess:IncRegua1("Processamento finalizado")
DbSelectArea("SN1IMP")
DbCloseArea()
IF File(cArqSN1+OrdBagExt())
FErase(cArqSN1+OrdBagExt())
ENDIF
DbSelectArea("SN2IMP")
DbCloseArea()
IF File(cArqSN2+OrdBagExt())
FErase(cArqSN2+OrdBagExt())
ENDIF
DbSelectArea("SN3IMP")
DbCloseArea()
IF File(cArqSN3+OrdBagExt())
FErase(cArqSN3+OrdBagExt())
ENDIF
IF lImpSF9
DbSelectArea("SF9IMP")
DbCloseArea()
IF File(cArqSF9+OrdBagExt())
FErase(cArqSF9+OrdBagExt())
ENDIF
ENDIF
IF lImpSNG
DbSelectArea("SNGIMP")
DbCloseArea()
IF File(cIndSNG+OrdBagExt())
FErase(cIndSNG+OrdBagExt())
ENDIF
ENDIF
DbSelectArea("CTAIMP")
DbCloseArea()
IF File(cArqCTA+OrdBagExt())
FErase(cArqCTA+OrdBagExt())
ENDIF
DbSelectArea("SM2IMP")
DbCloseArea()
IF File(cArqSM2+OrdBagExt())
FErase(cArqSM2+OrdBagExt())
ENDIF

- 290 ADVPL Avanado

Continuao:
DbSelectArea("LOGIMP")
DbCloseArea()
ConOut("Total de registros importados: "+CValToChar(nProcRegs))
ConOut("Trmino da importao: "+Time())
cFilAnt := cFilAtu
RestArea(aArea)
RETURN
/*/
+----------------------------------------------------------------------| Funo
| CT001PARBX
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | TELA DE PARAMETROS ESPECIFICOS DA ROTINA CUSTOMIZADA
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION IC001PARBX()
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

aParamBox
cTitulo
aRet
bOk
aButtons
lCentered
nPosx
nPosy
cLoad
lCanSave
lUserSave
nX
lRet

:=
:=
:=
:=
:=
:=

{}
"Importacao de cadastros"
{}
{|| .T.}
{}
.T.

:=
:=
:=
:=
:=

""
.T.
.T.
0
.F.

AADD(aParamBox,{2,"Tipo de informao"
,1 ,aTiposFile ,060,;
"AllwaysTrue()", .T.})
AADD(aParamBox,{2,"LayOut do arquivo "
,1 ,;
{"Padro","Especifico"},060, "AllwaysTrue()", .T.})
AADD(aParamBox,{1,"Diretorio de dados"
,Space(60)
,;
"@!","AllwaysTrue()","HSSDIR" ,".T.",120,.T.})
AADD(aParamBox,{1,"Arquivo de layout "
,Space(60)
,;
"@!","AllwaysTrue()","" ,".T.",120,.F.})
AADD(aParamBox,{2,"Operacao
"
,1 ,;
{"Incluir","Alterar","Excluir"},060, "AllwaysTrue()", .T.})
AADD(aParamBox,{1,"Diretorio de Log "
,Space(60)
,;
"@!","AllwaysTrue()","HSSDIR" ,".T.",120,.F.})
AADD(aParamBox,{2,"Importa CIAP
"
,1 ,;
{"Sim","No"} ,060, "AllwaysTrue()", .T.})
lRet := ParamBox(aParamBox, cTitulo, aRet, bOk, aButtons, lCentered, nPosx,;
nPosy, /*oMainDlg*/ , cLoad, lCanSave, lUserSave)

- 291 ADVPL Avanado

Continuao:
IF ValType(aRet) == "A" .AND. Len(aRet) == Len(aParamBox)
For nX := 1 to Len(aParamBox)
If aParamBox[nX][1] == 1
&("MvParBox"+StrZero(nX,2)) := aRet[nX]
ElseIf aParamBox[nX][1] == 2 .AND. ValType(aRet[nX]) == "C"
&("MvParBox"+StrZero(nX,2)) := aScan(aParamBox[nX][4],;
{|x| Alltrim(x) == aRet[nX]})
ElseIf aParamBox[nX][1] == 2 .AND. ValType(aRet[nX]) == "N"
&("MvParBox"+StrZero(nX,2)) := aRet[nX]
Endif
Next nX
ENDIF
RETURN lRet
/*/
+----------------------------------------------------------------------| Funo
| IATFCIAP
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | IMPORTACAO DO LIVRO FISCAL CIAP
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION IATFCIAP(aStruSF9,aDadosSF9)
Local aDadosCIAP := {}
Local nX
:= 0
Local nPosSF9
:= 0
// Monta array com dados padres do SF9 de acordo com o SX3
FOR nX := 1 to Len(aStruSF9)
AADD(aDadosCIAP,{aStruSF9[nX][1],CRIAVAR(aStruSF9[nX][1]),NIL})
NEXT nX
// Atualiza dados do array com as informaes presentes no SN1
FOR nX := 1 to Len(aDadosSF9)
IF (nPosSF9 := aScan(aDadosCIAP,{|aLinhaCIAP| aLinhaCIAP[1] ==
aDadosSF9[nX][1]})) > 0
aDadosCIAP[nPosSF9][2] := aDadosSF9[nX][2]
ENDIF
NEXT nX
ConOut("Iniciando MsExecAuto - ATFCIAP: "+Time())
lMsErroAuto := .F.
MSExecAuto({|x,y| U_ATFCIAP(x,y)},aDadosCIAP,3) // Dados e Opo
ConOut("Finalizada MsExecAuto - ATFCIAP: "+Time())
RETURN lMsErroAuto

- 292 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| XDBFLOG
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | CRIACAO DO ARQUIVO DBF PARA TRATAMENTO DOS EVENTOS DE ERR|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION XDBFLOG()
LOCAL aCampos
:= {}
LOCAL cArqLog
:= MVParBox06+"LOGIMP"+GetDbExtension()
IF !File(cArqLog)
AADD(aCampos,{"CKEYIMP" ,"C",014,0})
AADD(aCampos,{"CKEYREG" ,"C",020,0})
AADD(aCampos,{"CDESCR" ,"C",040,0})
AADD(aCampos,{"CSEQMSG" ,"C",003,0})
AADD(aCampos,{"CMSGERR" ,"C",254,0})
dbCreate(cArqLog,aCampos,__LocalDriver)
ENDIF
dbUseArea(.T., __LocalDriver, cArqLog, "LOGIMP", .T., .F.)
RETURN
/*/
+----------------------------------------------------------------------| Funo
| XGRVLOG
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | GRAVACAO DA MENSAGEM DE ERRO NO ARQUIVO DBF DE CONTROLE |
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION XGRVLOG(cKeyImp, cKeyReg, cDescReg, cMsgErr)
LOCAL cSeqLog := "000"
FOR nX := 1 TO Len(cMsgErr) STEP 254
cSeqLog := SOMA1(cSeqLog)
RECLOCK("LOGIMP",.T.)
LOGIMP->CKEYIMP
:= cKeyImp
LOGIMP->CKEYREG
:= cKeyReg
LOGIMP->CDESCR
:= cDescReg
LOGIMP->CSEQMSG
:= cSeqLog
LOGIMP->CMSGERR
:= SUBSTR(cMsgErr,nX,254)
MSUNLOCK()
NEXT nX
RETURN

- 293 ADVPL Avanado

Continuao:
/*/
+----------------------------------------------------------------------| Funo
| XCONVERRLOG
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | CONVERTE O ARRAY AAUTOERRO EM TEXTO CONTINUO.
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
STATIC FUNCTION XCONVERRLOG(aAutoErro)
LOCAL cRet := ""
LOCAL nX := 1
FOR nX := 1 to Len(aAutoErro)
cRet += aAutoErro[nX]+CHR(13)+CHR(10)
NEXT nX
RETURN cRet

- 294 ADVPL Avanado

10.

Recursos de envio de e-mail

Neste tpico sero descritas as funes da linguagem ADVPL que permitem o envio e o
recebimento de mensagens atravs de e-mails.
Funes para manipulao de e-mails












CALLPROC
MAILSMTPON
MAILPOPON
MAILSMTPOFF
MAILPOPOFF
MAILRECEIVE
MAILAUTH
POPMSGCOUNT
MAILSEND
MAILGETERR

Detalhamento das funes de manipulao de e-mails


CALLPROC()
Mtodo do objeto oRpcSrv que permite a utilizao de todas as funes de envio e
recebimento de e-mail descritas neste tpico.


Sintaxe: CallProc(cFuncao, xParam1, ..., xParamN)

Parmetros:

cFuncao

Nome da funo ou mtodo do objeto oRpcSrv que ser executado.

xParamN

Parmetros da funo ou mtodo que ser executado.

Retorno:
Nenhum

- 295 ADVPL Avanado

MAILSMTPON()
Ativa uma conexo com o servio de SMTP para a thread ativa.


Sintaxe: MailSmtpOn( cServer, cUser, cPass, nTimeOut)

Sintaxe clssica:

CONNECT SMTP SERVER cServer ACCOUNT cUser PASSWORD cPass TIMEOUT nTimeOut IN
SERVER oRpcSrv RESULT lResult

Parmetros:
Cserver

Endereo do servidor para conexo

Cuser

Nome do usurio para autenticao no servidor.

CPass

Senha do usurio para autenticao no servidor.

NTimeOut

Tempo de espera para operao de autenticao.

Retorno:
Lgico

Indica se foi realizada com sucesso a conexo com o servidor indicado.

MAILPOPON()
Ativa uma conexo com o servio de POP para a thread ativa. -> lReturn


Sintaxe: MailPopOn( cServer, cUser, cPass, nTimeOut)

Sintaxe clssica:

CONNECT POP SERVER cServer ACCOUNT cUser PASSWORD cPass


SERVER oRpcSrv
RESULT lResult

TIMEOUT nTimeOut

Parmetros:
Cserver

Endereo do servidor para conexo

Cuser

Nome do usurio para autenticao no servidor.

CPass

Senha do usurio para autenticao no servidor.

NTimeOut

Tempo de espera para operao de autenticao.

Retorno:
Lgico

Indica se foi realizada com sucesso a conexo com o servidor indicado.

- 296 ADVPL Avanado

IN

MAILSMTPOFF()
Encerra a conexo com o servio de SMTP.


Sintaxe: MailSmtpOff()

Sintaxe clssica:

DISCONNECT SMTP SERVER

RESULT lResult

Parmetros:
Nenhum

IN SERVER oRpcSrv

Retorno:
Lgico

Indica se a operao foi realizada com sucesso.

MAILPOPOFF()
Encerra a conexo com o servio de POP


Sintaxe: MailPopOff()

Sintaxe clssica:

DISCONNECT POP SERVER

RESULT lResult

Parmetros:
Nenhum

IN SERVER oRpcSrv

Retorno:
Lgico

Indica se a operao foi realizada com sucesso.

- 297 ADVPL Avanado

MAILRECEIVE()
Efetua o recebimento de um e-mail, salvando-o no local definido.


Sintaxe: MailReceive(nNumber, @cFrom, @cTo, @cCc, @cBcc, @cSubject,


@cBody, @aFiles, cPath, lDelete)

Sintaxe clssica:

RECEIVE MAIL MESSAGE nNumber FROM cFrom TO


cTo CC cCc BCC cBcc SUBJECT
cSubject BODY cBody ATTACHMENT aFiles SAVE IN cPath DELETE IN SERVER oRpcSrv
RESULT lResult

Parmetros:

cFrom

Nmero da mensagem que dever ser recebida. Este nmero em funo da


quantidade de mensagens na caixa de e-mails.
Varivel local do fonte que ser atualizada com o remetente da mensagem.

cTo

Varivel local do fonte que ser atualizada com o destinatrio da mensagem.

cCc

cSubject

Varivel local do fonte que ser atualizada com a conta copiada na


mensagem.
Varivel local do fonte que ser atualizada com a conta copiada em cpia
oculta na mensagem.
Varivel local do fonte que ser atualizada com o assunto da mensagem.

cBody

Varivel local do fonte que ser atualizada com corpo da mensagem.

aFiles

Varivel local do fonte que ser atualizada os nomes dos anexos da


mensagem.
Diretrio no qual sero salvos os anexos da mensagem.

nNumber

cBcc

cPath
lDelete

Indica se a mensagem dever ser apagada do servidor de e-mails aps sua


recepo pela aplicao.

Retorno:
Lgico

Indica se a operao de recebimento de mensagens foi realizada com


sucesso.

- 298 ADVPL Avanado

MAILAUTH()
Funo que executa a autenticao do usurio no servio ativo.


Sintaxe: MailAuth(cUser, cPassword)

Parmetros:

cUser

Nome do usurio para validao da conexo com o servidor.

cPassword

Senha do usurio para validao da conexo com o servidor.

Retorno:
Lgico

Indica se foi realizada a autenticao do usurio com sucesso.

A funo MailAuth() dever ser utilizada obrigatoriamente aps a abertura da


conexo com o servidor, seja ele de envio ou recebimento de mensagens.

Para validao da conexo sempre efetue a verificao com o usurio contendo


o endereo completo do e-mail, e caso necessrio somente com o usurio,
eliminando o restante do endereo aps o caractere @.
lResult := MailAuth(Alltrim(cEmail), Alltrim(cPass))
// Se nao conseguiu fazer a Autenticacao usando o E-mail completo, tenta
// fazer a autenticacao usando apenas o nome de usuario do E-mail.
If !lResult
nA := At("@",cEmail)
cUser := If(nA>0,Subs(cEmail,1,nA-1),cEmail)
lResult := MailAuth(Alltrim(cUser), Alltrim(cPass))
Endif

- 299 ADVPL Avanado

POPMSGCOUNT()
Verifica quantas mensagens existem na caixa de entrada do servio POP ativo.


Sintaxe: PopMsgCount(@nMsgCount)

Sintaxe clssica:

POP MESSAGE COUNT nMsgCount

Parmetros:
nMsgCount

IN SERVER oRpcSrv RESULT lResult

Varivel local do fonte que ser atualizada com a quantidade de mensagens


disponveis para recebimento na caixa de e-mails.

Retorno:
Lgico

Indica se foi realizado o acesso a caixa de mensagens.

MAILSEND()
Envia um e-mail utilizando a servio de SMTP ativo.


Sintaxe: MailSend(cFrom, aTo, aCc, aBcc, cSubject, cBody, aFiles, lText)

Sintaxe clssica:

SEND MAIL FROM cFrom TO aTo,... CC aCc,... BCC aBcc,... SUBJECT cSubject BODY
cBody FORMAT TEXT ATTACHMENT aFiles,... IN SERVER oRpcSrv RESULT lResult

Parmetros:
cFrom

Endereo de e-mail do remente da mensagem.

aTo

Array contendo os endereos de e-mails dos destinatrios da mensagem.

aCc

Array contendo os endereos de e-mails dos copiados na mensagem.

aBcc
cSubject

Array contendo os endereos de e-mails dos copiados de forma oculta na


mensagem.
Texto de assunto do e-mail.

cBody

Texto da mensagem do e-mail.

aFiles

Array contendo os nomes dos arquivos que sero anexados a mensagem.

lText

Indica se o corpo do e-mail est em formato texto.

Retorno:
Lgico

Indica se a operao de envio de mensagens foi realizada com sucesso.

- 300 ADVPL Avanado

MAILGETERR()
Retorna o erro que ocorreu no envio do e-mail.


Sintaxe: MailGetErr()

Sintaxe clssica:

GET MAIL ERROR cErrorMsg IN SERVER oRpcSrv

Parmetros:

Nenhum

Retorno:

Caracter

Mensagem de erro ocorrida no processamento do envio ou recebimento dos


e-mails.

Exemplos de utilizao das funcionalidades de envio e recebimento de e-mail

Envio de mensagens utilizando sintaxe clssica

#include "protheus.ch"
#include "tbiconn.ch"
#include "AP5MAIL.CH"
/*/
+----------------------------------------------------------------------| Funo
| SENDMAIL
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | ENVIO DE E-MAIL GENERICO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION SendMail(_lJob)
Local lResulConn := .T.
Local lResulSend := .T.
Local cError := ""
Local
Local
Local
Local

cServer
cEmail
cPass
lRelauth

Local cDe
Local cPara

:=
:=
:=
:=

AllTrim(GetMV("MV_RELSERV"))
AllTrim(GetMV("MV_RELACNT"))
AllTrim(GetMV("MV_RELPSW"))
GetMv("MV_RELAUTH")

:= cEmail
:= "arnaldojr@microsiga.com.br"
- 301 ADVPL Avanado

Continuao:
Local
Local
Local
Local

cCc
cAssunto
cAnexo
cMsg

Default _lJob
cMsg
cMsg
cMsg
cMsg

:=
+=
+=
+=

:=
:=
:=
:=

""
"Teste de envio de e-mail: Curso ADVPL"
"\SYSTEM\lgrl99.bmp"
Space(200)
:= .T.

"--------------------------------------------------"
"CURSO DE ADVPL
"
"--------------------------------------------------"
"Voc est recebendo um e-mail do curso de ADVPL avanado"

CONNECT SMTP SERVER cServer ACCOUNT cEmail PASSWORD cPass RESULT lResulConn
If !lResulConn
GET MAIL ERROR cError
If _lJob
ConOut(Padc("Falha na conexao "+cError,80))
Else
MsgAlert("Falha na conexao "+cError)
Endif
Return(.F.)
Endif
// Sintaxe: SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
// Todos os e-mail tero: De, Para, Assunto e Mensagem, porm precisa analisar
se tem: Com Cpia e/ou Anexo
If lRelauth
lResult := MailAuth(Alltrim(cEmail), Alltrim(cPass))
//Se nao conseguiu fazer a Autenticacao usando o E-mail completo, tenta fazer
a autenticacao usando apenas o nome de usuario do E-mail
If !lResult
nA := At("@",cEmail)
cUser := If(nA>0,Subs(cEmail,1,nA-1),cEmail)
lResult := MailAuth(Alltrim(cUser), Alltrim(cPass))
Endif
Endif
If lResult
If Empty(cCc) .And. Empty(cAnexo)
SEND MAIL FROM cDe TO cPara SUBJECT cAssunto BODY cMsg RESULT
lResulSend
Else
If Empty(cCc) .And. !Empty(cAnexo)
SEND MAIL FROM cDe TO cPara SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
ElseIf !Empty(cCc) .And. !Empty(cAnexo)
SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
ElseIf Empty(cCc) .And. Empty(cAnexo)
SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
RESULT lResulSend
Endif
Endif
- 302 ADVPL Avanado

Continuao:
If !lResulSend
GET MAIL ERROR cError
If _lJob
ConOut(Padc("Falha no Envio do e-mail "+cError,80))
Else
MsgAlert("Falha no Envio do e-mail " + cError)
Endif
Endif
Else
If _lJob
ConOut(Padc("Falha na autenticao do e-mail: "+cError,80))
Else
MsgAlert("Falha na autenticao do e-mail:" + cError)
Endif
Endif
DISCONNECT SMTP SERVER
IF lResulSend
If _lJob
ConOut(Padc("E-mail enviado com sucesso",80))
Else
MsgInfo("E-mail enviado com sucesso" + cError)
Endif
ENDIF
RETURN lResulSend

- 303 ADVPL Avanado

Envio de mensagens utilizando funes

#include "protheus.ch"
#include 'tbiconn.ch'
#include "AP5MAIL.CH"
/*/
+----------------------------------------------------------------------| Funo
| SENDMAIL
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | ENVIO DE E-MAIL GENERICO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION FSendMail(_lJob)
Local
Local
Local
Local

lResulConn := .T.
lResulSend := .T.
lResult
:= .T.
cError := ""

Local
Local
Local
Local

cServer
cEmail
cPass
lRelauth

:=
:=
:=
:=

AllTrim(GetMV("MV_RELSERV"))
AllTrim(GetMV("MV_RELACNT"))
AllTrim(GetMV("MV_RELPSW"))
GetMv("MV_RELAUTH")

Local
Local
Local
Local
Local
Local
Local

cDe
cPara
cCc
cBcc
cAssunto
cAnexo
cMsg

:=
:=
:=
:=
:=
:=
:=

cEmail
"arnaldojr@microsiga.com.br"
""
""
"Teste de envio de e-mail: Curso ADVPL"
"\SYSTEM\lgrl99.bmp"
Space(200)

Default _lJob
cMsg
cMsg
cMsg
cMsg

:=
+=
+=
+=

:= .F.

"--------------------------------------------------"
"CURSO DE ADVPL
"
"--------------------------------------------------"
"Voc est recebendo um e-mail do curso de ADVPL avanado"

//CONNECT SMTP SERVER cServer ACCOUNT cEmail PASSWORD cPass RESULT lResulConn
lResulConn := MailSmtpOn( cServer, cEmail, cPass)
If !lResulConn
//GET MAIL ERROR cError
cError := MailGetErr()
If _lJob
ConOut(Padc("Falha na conexao "+cError,80))
Else
MsgAlert("Falha na conexao "+cError)
Endif
Return(.F.)
Endif

- 304 ADVPL Avanado

Continuao:
// Sintaxe: SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
// Todos os e-mail tero: De, Para, Assunto e Mensagem, porm precisa analisar
se tem: Com Cpia e/ou Anexo
If lRelauth
lResult := MailAuth(Alltrim(cEmail), Alltrim(cPass))
//Se nao conseguiu fazer a Autenticacao usando o E-mail completo, tenta fazer
a autenticacao usando apenas o nome de usuario do E-mail
If !lResult
nA := At("@",cEmail)
cUser := If(nA>0,Subs(cEmail,1,nA-1),cEmail)
lResult := MailAuth(Alltrim(cUser), Alltrim(cPass))
Endif
Endif
If lResult
/*
If Empty(cCc) .And. Empty(cAnexo)
SEND MAIL FROM cDe TO cPara SUBJECT cAssunto BODY cMsg RESULT
lResulSend
Else
If Empty(cCc) .And. !Empty(cAnexo)
SEND MAIL FROM cDe TO cPara SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
ElseIf !Empty(cCc) .And. !Empty(cAnexo)
SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
ATTACHMENT cAnexo RESULT lResulSend
ElseIf Empty(cCc) .And. Empty(cAnexo)
SEND MAIL FROM cDe TO cPara CC cCc SUBJECT cAssunto BODY cMsg
RESULT lResulSend
Endif
Endif
*/
lResulSend := MailSend(cDe,{cPara},{cCc},{cBcc},cAssunto,cMsg,{cAnexo},.T.)
If !lResulSend
//GET MAIL ERROR cError
cError := MailGetErr()
If _lJob
ConOut(Padc("Falha no Envio do e-mail "+cError,80))
Else
MsgAlert("Falha no Envio do e-mail " + cError)
Endif
Endif
Else
If _lJob
ConOut(Padc("Falha na autenticao do e-mail: "+cError,80))
Else
MsgAlert("Falha na autenticao do e-mail:" + cError)
Endif
Endif
Continuao:
- 305 ADVPL Avanado

//DISCONNECT SMTP SERVER


MailSmtpOff()
IF lResulSend
If _lJob
ConOut(Padc("E-mail enviado com sucesso",80))
Else
MsgInfo("E-mail enviado com sucesso" + cError)
Endif
ENDIF
RETURN lResulSend

- 306 ADVPL Avanado

Recebimento de mensagens utilizando funes

#include "protheus.ch"
#include "tbiconn.ch"
#include "AP5MAIL.CH"
/*/
+----------------------------------------------------------------------| Funo
| POPMAIL
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | RECEBIMENTO DE E-MAIL GENERICO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
USER FUNCTION FPopMail(_lJob)
Local
Local
Local
Local

lResulConn := .T.
lResulPop := .T.
lResult
:= .T.
cError := ""

Local
Local
Local
Local

cServer
cEmail
cPass
lRelauth

Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

cDe
:=
cPara
:=
cCc
:=
cBcc
:=
cAssunto :=
aAnexo
:=
cMsg
:=
cPath
:=
nMsgCount:=
nNumber :=

Default _lJob

:=
:=
:=
:=

AllTrim(GetMV("MV_RELSERV"))
AllTrim(GetMV("MV_RELACNT"))
AllTrim(GetMV("MV_RELPSW"))
GetMv("MV_RELAUTH")
""
""
""
""
""
{}
""
"\MailBox"
0
0
:= .F.

lResulConn := MailPopOn( cServer, cEmail, cPass,1000)


If !lResulConn
cError := MailGetErr()
If _lJob
ConOut(Padc("Falha na conexao "+cError,80))
Else
MsgAlert("Falha na conexao "+cError)
Endif
Return(.F.)
Endif

- 307 ADVPL Avanado

Continuao:
/*If lRelauth
lResult := MailAuth(Alltrim(cEmail), Alltrim(cPass))
// Se nao conseguiu fazer a Autenticacao usando o E-mail completo, tenta
// fazer a autenticacao usando apenas o nome de usuario do E-mail
If !lResult
nA := At("@",cEmail)
cUser := If(nA>0,Subs(cEmail,1,nA-1),cEmail)
lResult := MailAuth(Alltrim(cUser), Alltrim(cPass))
Endif
Endif*/
If lResult
PopMsgCount(@nMsgCount)
For nNumber := 1 to nMsgCount
lResulPop := MailReceive(nNumber, @cDe, @cPara, @cCc, @cBcc,;
@cAssunto, @cMsg, @aAnexo , cPath, .F.)
If !lResulPop
cError := MailGetErr()
If _lJob
ConOut(Padc("Falha no recebimento do e-mail "+cError,80))
Else
MsgAlert("Falha no recebimento do e-mail " + cError)
Endif
Else // Salvar mensagem de e-mail
cMessage
cMessage
cMessage
cMessage
cMessage
cMessage

:=
+=
+=
+=
+=
+=

"DE: "+cDe+CRLF
"PARA: "+cPara+CRLF
"CC: "+cCc+CRLF
"BCC: "+cBcc+CRLF
"ASSUNTO: "+cAssunto+CRLF
"MENSAGEM: "+cMsg+CRLF

MsgInfo(cMessage,"E-mail Recebido")
Endif
End-For // Next nNumber
Else
If _lJob
ConOut(Padc("Falha na autenticao do e-mail: "+cError,80))
Else
MsgAlert("Falha na autenticao do e-mail:" + cError)
Endif
Endif
MailPopOff()

- 308 ADVPL Avanado

Continuao:
IF lResulPop
If _lJob
ConOut(Padc("E-mails recebidos com sucesso",80))
Else
MsgInfo("E-mail recebidos com sucesso" + cError)
Endif
ENDIF
RETURN lResulPop

11.

Integrao bsica com MsOffice

11.1. Exportao para EXCEL


A funcionalidade bsica de exportao de informaes para o Microsoft Excel utiliza a funo
DlgToExcel(), a qual permite que as informaes em formatos de array sejam geradas em uma
planilha.
DLGTOEXCEL()
Realiza a exportao das informaes do ambiente Protheus em formato de arrays para uma
planilha do Microsoft Excel.


Sintaxe: DlgToExcel(cOrigem, cTitulo, aDadosCab, aDadosItens)

Parmetros:

cOrigem

Contedo fixo definido como: GETDADOS

cTitulo

Nome para exibio da planilha

aDadosCab

Array contendo os nomes dos campos que sero exibidos na planilha.

aDadosItens

Array contendo as informaes dos campos, de acordo com a ordem do


array de cabealho.

Retorno:
Nenhum

Na exportao das informaes para o Microsoft Excel deve-se atentar para as


colunas que possurem informaes alfanumricas mas que contm apenas
nmeros. Para que estas colunas sejam exibidas corretamente deve ser
acrescentado um caracter especial no incio da string de forma que o Microsoft
Excel as reconhea como texto e no como numricas.

- 309 ADVPL Avanado

Exemplo de exportao para o Microsoft Excel utilizando a funo DlgToExcel()

#include "protheus.ch"
/*/
+----------------------------------------------------------------------| Funo
| GExpExcel
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Descrio | EXPORTACAO PARA EXCEL GENERICO
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
User Function GExpExcel()
Local aCabExcel
:={}
Local aItensExcel

:={}

// AADD(aCabExcel, {"TITULO DO CAMPO", "TIPO", NTAMANHO, NDECIMAIS})


AADD(aCabExcel, {"A1_FILIAL"
,"C", 02, 0})
AADD(aCabExcel, {"A1_COD"
,"C", 06, 0})
AADD(aCabExcel, {"A1_LOJA"
,"C", 02, 0})
AADD(aCabExcel, {"A1_NOME"
,"C", 40, 0})
AADD(aCabExcel, {"A1_MCOMPRA"
,"N", 18, 2})
MsgRun("Favor Aguardar.....", "Selecionando os Registros",;
{|| GProcItens(aCabExcel, @aItensExcel)})
MsgRun("Favor Aguardar.....", "Exportando os Registros para o Excel",;
{||DlgToExcel({{"GETDADOS",;
"POSIO DE TTULOS DE VENDOR NO PERODO",;
aCabExcel,aItensExcel}})})
Return
/*/
+----------------------------------------------------------------------| Funo
| GProcItens
| Autor | Arnaldo R. Junior | Data |
|
+----------------------------------------------------------------------| Uso
| Curso ADVPL
|
+----------------------------------------------------------------------/*/
Static Function GProcItens(aHeader, aCols)
Local aItem
Local nX
DbSelectArea("SA1")
DbSetOrder(1)
DbGotop()

- 310 ADVPL Avanado

Continuao:
While SA1->(!EOF())
aItem := Array(Len(aHeader))
For nX := 1 to Len(aHeader)
IF aHeader[nX][2] == "C"
aItem[nX] := CHR(160)+SA1->&(aHeader[nX][1])
ELSE
aItem[nX] := SA1->&(aHeader[nX][1])
ENDIF
Next nX
AADD(aCols,aItem)
aItem := {}
SA1->(dbSkip())
End
Return

- 311 ADVPL Avanado

APNDICES
Relao de imagens para aplicaes visuais
AFASTAME

BPMSDOCI

COLTOT

AFASTAMENTO

BPMSEDT1

CONTAINR

ALT_CAD

BPMSEDT2

DBG05

AMARELO

BPMSEDT3

DBG06

ANALITICO

BPMSEDT4

DBG09

ANALITIC

BPMSRELA

DBG3

AGENDA

BPMSTASK1

DESTINOS

ALTERA

BPMSTASK2

DESTINOS2

AREA

BPMSTASK3

DISABLE

ASIENTOS

BPMSTASK4

DISCAGEM

AUTOM

BR_AMARELO

DOWN

BAIXATIT

BR_AZUL

E5

BAR

BR_AZUL_OCEAN

EDITABLE

BMPCALEN

BR_CINZA

EXCLUIR

BMPEMERG

BR_LARANJA

FILTRO

BMPGROUP

BR_MARROM

FINAL

BMPINCLUIR

BR_PRETO

FOLDER10

BMPPERG

BR_VERDE

FOLDER11

BMPPOST

BR_VERDE_OCEAN

FOLDER12

BMPTABLE

BR_VERMELHO

FOLDER14

BMPTRG

BR_VERMELHO_OCEAN

FOLDER5

BMPUSER

BUDGET

FOLDER6

BMPVISUAL

BUDGETY

FOLDER7

BONUS

CADEADO

GEOROTA

- 312 ADVPL Avanado

BOTTOM

CALCULADORA

GRAF2D

BPMSDOC

CANCEL

GRAF3D

BPMSDOCA

CHAVE2

HISTORIC

BPMSDOCE

CHECKED

INSTRUME

IMPRESSAO

PCO_ITALT

PMSSETATOP

LBNO

PCO_ITEXC

PMSSETAUP

LBOK

PCOCO

PMSTASK1

LBTIK

PCOCUBE

PMSTASK2

LEFT

PCOFXCANCEL

PMSTASK3

LINE

PCOFXOK

PMSTASK4

LIQCHECK

PENDENTE

PMSUSER

LJPRECO

PESQUISA

PMSZOOMIN

LOCALIZA

PGNEXT

PMSZOOMOUT

LUPA

PGPREV

POSCLI

MAQFOTO

PMSCOLOR

PRECO

MATERIAL

PMSEDT3

PREV

METAS_BAIXO_16

PMSEDT4

PRINT03

METAS_BAIXO_LEG

PMSEXCEL

PRODUTO

METAS_CIMA_16

PMSEXPALL

RECALC

METAS_CIMA_LEG

PMSEXPCMP

RECORTAR

MSGHIGH

PMSMAIS

RIGHT

MSVISIO

PMSMATE

RPMNEW

NEXT

PMSMENOS

RPMSAVE

NOTE

PMSPESQ

S4SB014N

NOVACELULA

PMSPRINT

S4WB001N

OBJETIVO

PMSRELA

S4WB005N

- 313 ADVPL Avanado

OK

PMSRRFSH

S4WB006N

ORDEM

PMSSETABOT

S4WB007N

PARAMETROS

PMSSETADIR

S4WB008N

PCO_COINC

PMSSETADOWN

S4WB009N

PCO_CONOR

PMSSETAESQ

S4WB010N

S4WB011N

WEB

CARAGANEW

S4WB014B

WFCHK

CARGASEQ

S4WB016N

WFUNCHK

CCTCALC

SALVAR

ADDCONTAINER

CHAT

SDUIMPORT

ADICIONAR_001

CHAT1

SDUPACK

ARMAZEM

CHAT2

SDUPROPR

ATALHO

CHAT3

SDUSETDEL

AVGARMAZEM

CHECK

SDUSOFTSEEK

AVGBOX1

CHECKOK

SHORTCUTDEL

AVGLBPAR1

CLOCK01

SHORTCUTEDIT

AVGOIC1

CLOCK02

SHORTCUTMINUS

AVIAO

CLOCK03

SHORTCUTNEW

AZUL

CLOCK04

SHORTCUTPLUS

BALANCA

DEVOLNF

SIMULACA

BGCOLOR

COBROWSR

SIMULACAO

BMPPARAM

COLFORM

SUGESTAO

BMPCONS

COMPTITL

SUMARIO

BMPCPO

COMSOM

SVM

BMPDEL

CRITICA

TK_VERTIT

BR_BRANCO

COPYUSER

UNCHECKED

BRANCO

CTBLANC

- 314 ADVPL Avanado

UP

BR_CANCEL

CTBREPLA

USER

BR_MARROM

DBG07

VCDOWN

BR_PINK

DELWEB

VCUP

BTCALC

COLOR

VENDEDOR

BTPESQ

DBG12

VERNOTA

CARGA

DBG10

DEPENDENTES

F7_VERM

F14_PINK

GEO

F8_NULL

F14_PRET

EDITWEB

F10_AMAR

F14_VERD

EMPILHADEIRA

F10_AZUL

F14_VERM

ENABLE

F10_CINZ

FRIAS

ESCALA

F10_LARA

FILTRO1

ESTOMOVI

F10_MARR

FOLDER8

F5_AZUL

F10_NULL

FOLDER13

F5_NULL

F10_PINK

FOLDER15

F5_VERD

F10_PRET

FORM

F5_VERM

F10_VERD

FRCOLOR

F6_NULL

F10_VERM

FRTOFFLINE

F5_AMAR

F11_NULL

FRTONLINE

F5_CINZ

F12_AMAR

GEO

F5_LARA

F12_AZUL

GEOEMAIL

F5_MARR

F12_CINZ

GEOTRECHO

F5_PINK

F12_LARA

GERPROJ

F5_PRET

F12_MARR

GLOBO

F7_AMAR

F12_PINK

IC_17

F7_AZUL

F12_PRET

INSTRUME

- 315 ADVPL Avanado

F7_CINZ

F12_VERD

LANDSCAPE

F7_LARA

F12_VERM

LIGHTBLU

F7_MARR

F14_AMAR

MDIHELP

F7_NULL

F14_AZUL

MDILOGOFF

F7_PINK

F14_CINZ

MDIRUN

F7_PRET

F14_LARA

MDISPOOL

F7_VERD

F14_MARR

MEDEXT

MENURUN

RPMCABEC

SDUFIELDS

MPWIZARD

RPMCPO

SDUFIND

NCO

RPMDES

SDUGOTO

NEWWEB

RPMFORM

SDUNEW

NOCONNECT

RPMFUNC

SDUOPEN

NOCHECKED

RPMGROUP

SDUOPENIDX

NOMEDICA

RPMIMP

SDUORDER

NORMAS

RPMIMPORT

SDURECALL

OPEN

RPMNEW2

SDUREPL

OPERACAO

RPMOPEN

SDUSEEK

OUTLOOK

RPMPERG

SDUSTRUCT

PAPEL_ESCRITO

RPMTABLE

SDUSUM

PEDIDO

S4WB004N

SDUZAP

PIN

S4WB013N

SEMSOM

PMSINFO

S4WB014A

SOLICITA

PREDIO

SALARIOS

SSFONTES

PRINT02

SAVECLOCK

TAB1

PROCESSA

SDUADDTBL

TABPRICE

PRODUT2

SDUAPPEND

TEXTBOLD

- 316 ADVPL Avanado

PROJETPMS

SDUCLOSE

TEXTCENTER

PRTETQ

SDUCLOSEIDX

XCLOSE

QMT_COND

SDUCOPYTO

TEXTITALIC

QMT_NO

SDUCOUNT

TEXTJUSTIFY

QMT_OK

SDUCREATEIDX

TEXTLEFT

RESPADEX

SDUDELETE

TEXTRIGHT

RESPONSA

SDUDRPTBL

TEXTUNDERLINE

ROSA

SDUERASE

TK_ALTFIN

TK_CLIFIN

BPMSEDT3A

GCT_NEW

TK_FIND

BPMSEDT3E

INVOICE1

TK_FONE

BPMSEDT3I

MSGGROUP

TK_HISTORY

BPMSEDT4A

MSGHIGH

TK_NOVO

BPMSEDT4E

PCO_COALT

TK_REFRESH

BPMSEDT4I

PCO_COEXC

TPOPAGTO1

BPMSREC

PCO_ITINC

UPDWARNING

BPMSRECA

PCOCOLA

UPDERROR

BPMSRECE

PCOCOPY

UPDINFORMATION

BPMSRECI

PCOEDIT

VERDE

BPMSRELAA

PCOFX

VERMELHO

BPMSRELAE

PCOLOCK

VERMESCURO

BPMSRELAI

PEDIDO2

WATCH

BPMSTSK1A

PEDIDO2_MDI

CLIENTE

BPMSTSK1E

PGRSAVE

ACAO

BPMSTSK1I

PMSAPONT

BOXBOM1

BPMSTSK2A

PMSCANC

BOXBOM2

BPMSTSK2E

PMSCOLUM

- 317 ADVPL Avanado

BOXBOM3

BPMSTSK2I

PMSCONS

BOXBOM4

BPMSTSK3A

PMSCUSTO

BOXBOM5

BPMSTSK3E

PMSDATE

BPMSEDT1A

BPMSTSK3I

PMSESTRU

BPMSEDT1E

BPMSTSK4A

PMSEXCEL

BPMSEDT1I

BPMSTSK4E

PMSEXEC

BPMSEDT2A

BPMSTSK4I

PMSEXPEXC

BPMSEDT2E

ENGRENAGEM2

PMSFILTER

BPMSEDT2I

GCT_EDIT

PMSGRAPH

PMSNEXT

MSGFORWD

UNSELECTALL

PMSOPCAO

MSGREPLY

BSTART

PMSPESQ

OMSDIVIDE

BTURNSHARPLEFT

PMSPREV

PMSUPDOWN

BTURNSHARPRIGHT

PMSPREVIO

SHAPE01

ENGRENAGEM

PMSPRINT

SHAPE02

PAGEDOWN

PMSPROG

SHAPE03

PAGEUP

PMSSUPALOC

SHAPE04

SELECT

PMSTOOLS

SHAPE05

SELECTALL

PMSUSERP

TRIDOWN

BBEARRIGHT

REFRESH

WORD

BEND

SHAPE06

ROTEIRO

BKEEPLEFT

TRILEFT

CLIPS_PQ

BKEEPRIGHT

TRIRIGHT

NEXT_PQ

BLEFT

VINCULA1

RELACIONAMENTO_DIREIRA_PQ

BRIGHT

BAHEAD

PREV_PQ

CANCEL

BBEARLEFT

UP.GIF

CONFIRM

- 318 ADVPL Avanado

DOWN

GOTOP

GOBOTTOM

- 319 ADVPL Avanado

INVERTSELECTION

LISTAS DE EXERCCIOS

01

02

03

Implementar a classe Aluno com os mtodos New(), Inscrever() e Avaliar().

Desenvolver um dilogo para interagir com a classe Aluno desenvolvida no


exerccio anterior.

Implementar uma Enchoice para o cadastro de produtos (SB1).

- 320 ADVPL Avanado

04

Converter o cadastro desenvolvido no exerccio anterior para que o mesmo


utilize o objeto MsMGet().

05

Desenvolver uma interface de cadastro que combine os objetos MsMGet e


MsNewGetDados causando o efeito de uma Modelo3().

06

Adicionar na interface de cadastro desenvolvida no exerccio anterior uma


EnchoiceBar() com um boto definido pelo usurio que exiba o AxCadastro de
um item utilizado na interface.

07

Converter o fonte DIALOG_OBJETOS.PRW para sintaxe orientada objetos.

- 321 ADVPL Avanado

08

Desenvolver uma MaWndBrowse utilizando um arquivo temporrio.

09

Implementar uma funcionalidade com mltiplos TwBrowses que permita


pesquisar clientes e visualizar os ttulos a receber dos mesmos.

10

Implementar um objeto TFolder para montar um rodap para uma interface


que contenha MsMGet() e MsNewGetDados().

11

Implementar a MsAdvSize() e MsObjSize() no fonte desenvolvido no exerccio


anterior.

- 322 ADVPL Avanado

12

Desenvolver uma MaWndBrowse utilizando um Alias gerado pela funo


TcGenQry().

13

Desenvolver uma MaWndBrowse utilizando um Alias gerado pela funo


TcGenQry() para um banco de dados externo a aplicao ERP.

14

Desenvolver uma aplicao que execute a Stored Procedure padro de


reprocessamento de saldos contbeis.

15

Implementar no fonte WndSqlConn desenvolvido anteriormente as funes


TcInclui(), TcAltera(), TcExclui() com o uso das funes TEnchoice() e
TcSqlExec().

- 323 ADVPL Avanado

16

Implementar uma funo que realize o envio de um texto simples para uma
conta de e-mail @totvs, que permita sua fcil identificao.

17

Implementar uma rotina que realize o recebimento do e-mail enviado


anteriormente para a conta de e-mail @totvs.

18

Implementar uma rotina automtica para gravar as informaes no cadastro


de clientes (MATA030).

- 324 ADVPL Avanado

Projeto: Avaliao prtica do treinamento de ADVPL Avanado


Objetivos do projeto
 Contemplar o contedo do curso e estimular a prtica da programao utilizando a linguagem
ADVPL;
 Acrescentar um grau de desafio ao treinamento;
Regras para entrega e apresentao
 Dever ser entregue na data estabelecida pelo instrutor, contendo os fontes e demais arquivos
necessrios. A avaliao do projeto ser realizada aps a entrega, no prazo estabelecido pelo
instrutor;
 Pode ser realizado em grupos de at 03 pessoas. Caso existam alunos sem grupos, estes podero
integrar equipes j formadas com o total de membros estabelecido, mediante aprovao do
instrutor;
Avaliao do projeto
 Mesmo peso da prova terica, podendo substitu-la integralmente.
 Sero considerados os quesitos:
 Funcionalidades
 Clareza da programao
 Apresentao
 Otimizao de tcnicas e recursos apresentados no treinamento
Funcionalidades que compe o projeto
Desenvolver uma aplicao utilizando a linguagem ADVPL que contemple as seguintes funcionalidades:

Projeto 01

Desenvolver uma aplicao de cadastro utilizando a classe Aluno e os mtodos


disponveis para a mesma.

Projeto 02

Converter os fontes do pacote de oficina de programao para orientao a


objetos.

Projeto 03

Implementar uma aplicao ADVPL que consulte e atualize dados em um


banco de interface externo ao Protheus.

- 325 ADVPL Avanado

REFERNCIAS BIBLIOGRFICAS
Referncias bibliogrficas
Gesto empresarial com ERP
Ernesto Haberkorn, 2006
Programao Orientada a Objetos com C ++
Ivan Luiz Marques Ricarte, 1996
Modelagem e Projetos baseados em objetos
James Rumbaugh, 1994 11. Edio
Programao orientada objetos no FiveWin
Gilmer FiveWin Brasil
Oficina de Programao
Robson Luiz Estefani Gonalves
Apostila de Treinamento - TReport
Tnia Bronzeri
Apostila de Treinamento - ADVPL
Educao corporativa
Apostila de Treinamento Boas Prticas de Programao
Inteligncia Protheus e Fbrica de Software
DEM Documentao Eletrnica Microsiga
Microsiga Software S.A.
Materiais diversos de colaboradores Microsiga
Colaboradores Microsiga

Colaboradores
Reviso 01
Arnaldo Raymundo Junior
Luis Akira Tamura
Mrcia Satiko Sasaki Tokura
Patricia Lopes Legas
Robson Luiz Estefani Gonalves
Srgio Sueo Fuzinaka

Data: 04.2008
CSA
Educao Corporativa
ACR-N1_FRAMEW1
Educao Corporativa
Fbrica de Software
Inteligncia Protheus

- 326 ADVPL Avanado

Educao Corporativa

Guia de Referncia Rpida


ADVPL Avanado

Matriz Av. Braz Leme, 1.717 02511-000 So Paulo SP Brasil.


Tel.: 55 (11) 3981-7001 www.microsiga.com.br

GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL


Neste guia de referncia rpida sero descritas as funes bsicas da linguagem ADVPL,
incluindo as funes herdadas da linguagem Clipper, necessrias ao desenvolvimento no
ambiente ERP.

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:
cData := 31/12/2006
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

- 328 Guia de Referncia Rpida


ADVPL Avanado

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
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 caracter com contedo no formato
AAAAMMDD em data.



Sintaxe: STOD(sData)
Parmetros
sData

String no formato AAAAMMDD

Exemplo:
sData := LERSTR(01,08) // Funo que realiza a leitura de uma string de um txt previamente
// aberto
dData := STOD(sData)

- 329 Guia de Referncia Rpida


ADVPL Avanado

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



Sintaxe: STR(nValor)
Parmetros
nValor

Valor numrico que ser convertido para caractere.

Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos

STRZERO()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando zeros
esquerda do nmero convertido, de forma que a string gerada tenha o tamanho especificado
no parmetro.



Sintaxe: STRZERO(nValor, nTamanho)


Parmetros
nValor

Valor numrico que ser convertido para caractere.

nTamanho

Tamanho total desejado para a string retornada.

Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos

- 330 Guia de Referncia Rpida


ADVPL Avanado

VAL()
Realiza a converso de uma informao do tipo caracter em numrica.



Sintaxe: VAL(cValor)
Parmetros
cValor

String que ser convertida para numrico.

Exemplo:
Static Function Modulo11(cData)
LOCAL L, D, P := 0
L := Len(cdata)
D := 0
P := 1
While L > 0
P := P + 1
D := D + (Val(SubStr(cData, L, 1)) * P)
If P = 9
P := 1
End
L := L - 1
End
D := 11 - (mod(D,11))
If (D == 0 .Or. D == 1 .Or. D == 10 .Or. D == 11)
D := 1
End
Return(D)

- 331 Guia de Referncia Rpida


ADVPL Avanado

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:

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



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.

- 332 Guia de Referncia Rpida


ADVPL Avanado

Situaes invlidas:

Entrada
QNAN,IND
(cosf, cos)
x 7.104760e+002 (cosh, coshf)

Exceo apresentada
None
INVALID
INEXACT+OVERFLOW

Significado da Exceo
Sem Domnio
Sem Domnio
OVERFLOW

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.
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo SIN().



Sintaxe: SIN(nAngulo)
Parmetros:
nAngulo

Retorno:
Numrico

Valor do ngulo em radianos.

Retorna o valor do seno do ngulo especificado.

Situaes invlidas:

Entrada
QNAN,IND
(senf, sen)
x 7.104760e+002 (senh, senhf)

Exceo apresentada
None
INVALID
INEXACT+OVERFLOW

- 333 Guia de Referncia Rpida


ADVPL Avanado

Significado da Exceo
Sem Domnio
Sem Domnio
OVERFLOW

SQRT()
Funo utilizada para calcular a raiz quadrada de um nmero positivo.
Sintaxe: SQRT(nValor)
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.
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo cos.



Sintaxe: TAN(nAngulo)
Parmetros:
nAngulo

Retorno:
Numrico

Valor do ngulo em radianos.

Retorna o valor da tangente do ngulo especificado.

Situaes invlidas:

Entrada
QNAN,IND

Exceo apresentada
None
INVALID

- 334 Guia de Referncia Rpida


ADVPL Avanado

Significado da Exceo
Sem Domnio
Sem Domnio

Anlise de variveis
TYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.



Sintaxe: TYPE(cVariavel)
Parmetros
cVariavel

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

Exemplo:
IF TYPE(dDataBase) == D
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
cTexto
nColf

:= IIF(ValType(nTamanho) != N,1,nTamanho) // Se o parmetro foi passado


:= Space(nTamanho);nLargGet := Round(nTamanho * 2.5,0);
:= Round(195 + (nLargGet * 1.75) ,0)

DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 120,nColF PIXEL


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

- 335 Guia de Referncia Rpida


ADVPL Avanado

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
AADD(aItem, cVariavel2) // Adiciona um elemento no array aItem de acordo com o cVariavel2
AADD(aItem, cVariavel3) // Adiciona um elemento no array aItem de acordo com o cVariavel3
//
//
//
//

Neste ponto o array a Item possui 03 elementos os quais podem ser acessados com:
aItem[1] -> corresponde ao contedo de cVariavel1
aItem[2] -> corresponde ao contedo de cVariavel2
aItem[3] -> corresponde ao contedo de cVariavel3

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
aDados [1][2] -> corresponde ao contedo de cVariavel2
aDados [1][3] -> corresponde ao contedo de cVariavel3

AADD(aDados, aItem)
AADD(aDados, aItem)
// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros
// 03 elementos, sendo:
// aDados [1][1] -> corresponde ao contedo de cVariavel1
// aDados [1][2] -> corresponde ao contedo de cVariavel2
// aDados [1][3] -> corresponde ao contedo de cVariavel3
// aDados [2][1] -> corresponde ao contedo de cVariavel1
// aDados [2][2] -> corresponde ao contedo de cVariavel2
// aDados [2][3] -> corresponde ao contedo de cVariavel3
// aDados [3][1] -> corresponde ao contedo de cVariavel1
// aDados [3][2] -> corresponde ao contedo de cVariavel2
// aDados [3][3] -> corresponde ao contedo de cVariavel3

- 336 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
// 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: AADD(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()
aItens := ACLONE(aDados)
// Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array
// aDados.

Por ser uma estrutura de memria, um array no pode ser simplesmente


copiado para outro array atravs de uma atribuio simples (:=).
Para mais informaes sobre a necessidade de utilizar o comando ACLONE()
verifique o tpico 6.1.3 Cpia de Arrays.

ACOPY()
Funo de array que copia elementos do array aOrigem para array aDestino. O array destino
aDestino j deve ter sido declarado e grande o bastante para conter os elementos que sero
copiados. Se o array aOrigem contiver mais elementos, alguns dos elementos no sero
copiados. ACOPY() copia os valores de todos os dados, incluindo valores nulos (NIL) e cdigos
de bloco.
Se um elemento for um subarray, o elemento correspondente no array aDestino, conter o
mesmo subarray. Portanto, ACOPY() no produzir uma cpia completa de array
multidimensionais.



Sintaxe: ACOPY( aOrigem, aDestino , [ nInicio ], [ nQtde ], [ nPosDestino ])


Parmetros:
aOrigem

o array que contm os elementos a serem copiados.

aDestino

o array que receber a cpia dos elementos.

nInicio

indica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se


no for especificado, o valor assumido ser 01.

- 337 Guia de Referncia Rpida


ADVPL Avanado

nQtde

nPosDestino

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


aOrigem. iniciando-se a contagem a partir da posio nInicio. Se nQtde
no for especificado, todos os elementos do array aOrigem sero copiados,
iniciando-se a partir da posio nInicio.
a posio do elemento inicial no array aDestino que receber os
elementos de aOrigem. Se no especificado, ser assumido 01.

Retorno:
aDestino

referncia ao array aDestino.

Exemplo:
LOCAL nCount := 2, nStart := 1, aOne, aTwo
aOne := { 1, 1, 1 }
aTwo := { 2, 2, 2 }
ACOPY(aOne, aTwo, nStart, nCount)
// Result: aTwo is now { 1, 1, 2 }

ADEL()
A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a excluso de um
elemento, todos os demais so reorganizados de forma que a ultima posio do array passar
a ser nula.



Sintaxe: ADEL(aArray, nPosio)


Parmetros
aArray

Array do qual deseja-se remover uma determinada posio

nPosio

Posio do array que ser removida

Exemplo:
// Utilizando o array aItens do exemplo da funo ACLONE() temos:
ADEL(aItens,1) // Ser removido o primeiro elemento do array aItens.
//
//
//
//

Neste ponto, o array aItens continua com 03 elementos, aonde:


aItens[1] -> antigo aItens[2], o qual foi reordenado como efeito da excluso do item 1.
aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito da excluso do item 1.
aItens[3] -> contedo nulo, por se tratar do item excludo.

- 338 Guia de Referncia Rpida


ADVPL Avanado

ADIR()
Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da
mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados.
Importante: ADir uma funo obsoleta, utilize sempre Directory().


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


[ aAtributo ])

Parmetros:
cArqEspec

aNomeArq
aTamanho
aData
aHora
aAtributos

Caminho dos arquivos a serem includos na busca de informaes. Segue o


padro para especificao de arquivos, aceitando arquivos no servidor
Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso
seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ).
Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
Array Numrico. So os tamanhos dos arquivos encontrados na busca.
Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
Array de Caracteres. So os atributos dos arquivos, caso esse array seja
passado como parmetros, sero includos os arquivos com atributos de
sistema e ocultos.

Retorno:
nArquivos

Quantidade de arquivos encontrados.

Exemplo:
LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })

- 339 Guia de Referncia Rpida


ADVPL Avanado

AFILL()
Funo de manipulao de arrays, que preenche os elementos do array com qualquer tipo de
dado. Incluindo code-block. Esta funo no deve ser usada para preencher um array com
outro array.



Sintaxe: AFILL( aDestino , xExpValor, [ nInicio ], [ nQuantidade ])


Parmetros
aDestino

o onde os dados sero preenchidos.

xExpValor

o dado que ser preenchido em todas as posies informadas, no


permitida a utilizao de arrays.
a posio inicial de onde os dados sero preenchidos, o valor padro 1.

nInicio
nCount

Quantidade de elementos a partir de [nInicio] que sero preenchidos com


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

Retorno:
aDestino

Retorna uma referncia para aDestino.

Exemplo:
LOCAL aLogic[3]
// Resultado: aLogic
AFILL(aLogic, .F.)
// Resultado: aLogic
AFILL(aLogic, .T., 2,
// Resultado: aLogic

{ NIL, NIL, NIL }


{ .F., .F., .F. }
2)
{ .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}

- 340 Guia de Referncia Rpida


ADVPL Avanado

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

Exemplo:
aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.

O array definido pelo comando Array() apesar de j possuir a estrutura


solicitada, no possui contedo em nenhum de seus elementos, ou seja:
aDados[1] -> array de trs posies
aDados[1][1] -> posio vlida, mas de contedo nulo.

ASCAN()
A funo ASCAN() permite que seja identificada a posio do array que contm uma
determinada informao, atravs da anlise de uma expresso descrita em um bloco de
cdigo.



Sintaxe: ASCAN(aArray, bSeek)


Parmetros
aArray
bSeek

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


informao pesquisada.
Bloco de cdigo que configura os parmetros da busca a ser realizada.

Exemplo:
aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}
bSeek := {|x| x == Denis}
nPosAluno := aScan(aAlunos,bSeek) // retorno esperado  2

- 341 Guia de Referncia Rpida


ADVPL Avanado

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.

ASCANX()
Funo utilizada para varrer um vetor procurando um valor especificado, operando de forma
similar a funo ASCAN.
A diferena fundamental da funo ASCANX que esta funo recebe um segundo parmetro
em seu code-block representando o ndice do array.


Sintaxe: ASCANX ( < xDestino > , < bSeek > , [ nInicio ] , [ nCont ] )

Parmetros:
xDestino
bSeek
nInicio
nCont

Representa o objeto a ser varrido pela funo, pode ser atribudo ao


parmetro um array um Objeto.
Representa o valor que ser pesquisado, podendo ser um bloco de cdigo.
Representa o elemento a partir do qual ter inicio a pesquisa, quando este
argumento no for informado o valor default ser 1.
Representa a quantidade de elementos que sero pesquisados a partir da
posio inicial, quando este argumento no for informado todos elementos
do array sero pesquisados.

Exemplo.:
nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y<=100})

- 342 Guia de Referncia Rpida


ADVPL Avanado

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.



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.

- 343 Guia de Referncia Rpida


ADVPL Avanado

ASORT()
A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio
pr-estabelecido.



Sintaxe: ASORT(aArray, nInicio, nItens, bOrdem)


Parmetros
aArray
nInicio
nItens
bOrdem

Array pr-existente que ter seu contedo ordenado atravs de um critrio


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

Um bloco de cdigo basicamente uma funo escrita em linha. Desta forma


sua estrutura deve suportar todos os requisitos de uma funo, os quais so
atravs da anlise e interpretao de parmetros recebidos, executar um
processamento e fornecer um retorno.
Com base nesse requisito, pode-se definir um bloco de cdigo com a estrutura
abaixo:
bBloco := { |xPar1, xPar2, ... xParZ| Ao1, Ao2, AoZ } , aonde:
|| -> define o intervalo onde esto compreendidos os parmetros
Ao Z-> expresso que ser executadas pelo bloco de cdigo
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 01 Ordenao ascendente


aAlunos := { Mauren, Soraia, Andria}
aSort(aAlunos)
// Neste ponto, os elementos do array aAlunos sero {Andria, Mauren, Soraia}

- 344 Guia de Referncia Rpida


ADVPL Avanado

Exemplo 02 Ordenao descendente


aAlunos := { Mauren, Soraia, Andria}
bOrdem := {|x,y| x > y }
//
//
//
//
//
//

Durante a execuo da funo aSort(), a varivel x receber o contedo do item que est
posicionado. Como o item que est posicionado a posio aAlunos[x] e aAlunos[x] ->
string contendo o nome de um aluno, pode-se substituir x por cNomeAtu.
A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma
analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de cdigo
bOrdem pode ser re-escrito como:

bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}


aSort(aAlunos,,bOrdem)
// Neste ponto, os elementos do array aAlunos sero {Soraia , Mauren, Andria}

ATAIL()
ATAIL() uma funo de manipulao de array que retorna o ltimo elemento de um array.
Ela deve ser usada em substituio da seguinte construo: aArray [LEN( aArray )]



Sintaxe: ATAIL( aArray )


Parmetros:
aArray

o array de onde ser retornado o ltimo elemento.

Retorno:
nUltimo

Nmero do ltimo elemento do array.

Exemplo:
aArray := {"a", "b", "c", "d"}
ATAIL(aArray) // Resultado: d

- 345 Guia de Referncia Rpida


ADVPL Avanado

Manipulao de blocos de cdigo


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



Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)


Parmetros
bBloco

Bloco de cdigo que ser interpretado.

xParamZ

Parmetros que sero passados ao bloco de cdigo. A partir da passagem do


bloco, todos os demais parmetros da funo sero convertidos em
parmetros para a interpretao do cdigo.

Exemplo:
nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
nValor := EVAL(bBloco, nInt)
// O retorno ser dado pela avaliao da ultima ao da lista de expresses, no caso z.
// Cada uma das variveis definidas em uma das aes da lista de expresses fica disponvel
// para a prxima ao.
// Desta forma temos:
// N  recebe nInt como parmetro (10)
// X  tem atribudo o valor 10 (10)
// Y  resultado da multiplicao de X por N (100)
// Z  resultado a diviso de Y pela multiplicao de X por N ( 100 / 100)  1

DBEVAL()
A funo DBEval() permite que todos os registro de uma determinada tabela sejam analisados
e para cada registro ser executado o bloco de cdigo definido.



Sintaxe: Array(bBloco, bFor, bWhile)


Parmetros
bBloco

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


cada registro do alias ativo.

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

- 346 Guia de Referncia Rpida


ADVPL Avanado

Exemplo 01:
// 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 02:
// 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.

- 347 Guia de Referncia Rpida


ADVPL Avanado

AEVAL()
A funo AEVAL() permite que todos os elementos de um determinada array sejam analisados
e para cada elemento ser executado o bloco de cdigo definido.



Sintaxe: AEVAL(aArray, bBloco, nInicio, nFim)


Parmetros
aArray

Array que ser avaliado na execuo da funo.

bBloco

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


cada elemento do array informado.

nInicio

Elemento inicial do array, a partir do qual sero avaliados os blocos de


cdigo.
Elemento final do array, at o qual sero avaliados os blocos de cdigo.

nFim
Exemplo 01:

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

- 348 Guia de Referncia Rpida


ADVPL Avanado

Manipulao de strings
ALLTRIM()
Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado
como parmetro.
A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left
trim).
Sintaxe: ALLTRIM(cString)
Parmetros




cString

String que ser avaliada para remoo dos espaos a direita e a esquerda.

Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))

ASC()
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"
Case (Asc(cLetra) > 199 .and. Asc(cLetra) < 204) .or.;
(Asc(cLetra) > 231 .and. Asc(cLetra) < 236)
cLetra := "E"

- 349 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
Case (Asc(cLetra) > 204 .and. Asc(cLetra) < 207) .or.;
(Asc(cLetra) > 235 .and. Asc(cLetra) < 240)
cLetra := "I"
Case (Asc(cLetra) > 209 .and. Asc(cLetra) < 215) .or.;
(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) < 247)
cLetra := "O"
Case (Asc(cLetra) > 216 .and. Asc(cLetra) < 221) .or.;
(Asc(cLetra) > 248 .and. Asc(cLetra) < 253)
cLetra := "U"
Case Asc(cLetra) == 199 .or. Asc(cLetra) == 231
cLetra := "C"
EndCase
cRet := cRet+cLetra
Next
Return UPPER(cRet)
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

- 350 Guia de Referncia Rpida


ADVPL Avanado

BITON()
Funo utilizada para ligar determinados bits de uma String passada por parmetro para a
funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico
que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem
alterados(ligados) e o tamanho da string passada.
Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )
Parmetros




cValue

String no qual desejamos ligar os bits.

nBitIni

Indica a partir de qual bit, comear a ser ligados os bits na String

nBitEnd

Indica a quantidade de bits que sero ligados a partir do inicio.

nStrLen

Representa o tamanho da String passada para a funo.

CAPITAL()
Funo que avalia a string passada como parmetro alterando a primeira letra de cada palavra
para maiscula e as demais letras como minsculas.


Sintaxe: CAPITAL(cFrase)

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

- 351 Guia de Referncia Rpida


ADVPL Avanado

DESCEND()
Funo de converso que retorna a forma complementada da expresso string especificada.
Esta funo normalmente utilizada para a criao de indexadores em ordem decrescente



Sintaxe: DESCEND ( < cString > )


Parmetros:
cString

Corresponde seqncia de caracteres a ser analisada.

Retorno:
Caracter

String complementada da string analisada.

Exemplo:

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

// Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice
// descendente:
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>.

- 352 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
GetDtoVal('123456')
//retorno 123456.0000
GetDtoVal('1/2/3/4/5/6') //retorno 123456.0000
GetDtoVal('fim.123456') //retorno 0.123456
GetDtoVal('teste')
//retorno 0.0

ISALPHA()
Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres alfabtico, permitindo avaliar se o string especificado comea com um caractere
alfabtico. Um caractere alfabtico consiste em qualquer letra maiscula ou minscula de A
a Z.


Sintaxe: ISALPHA ( < cString > )

Parmetros:
cString

Cadeia de caracteres a ser examinada.

Retorno:
Lgico

Retorna verdadeiro (.T.) se o primeiro caractere em <cString> for alfabtico,


caso contrrio, retorna falso (.F.).

ISDIGIT()
Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um dgito
numrico entre zero e nove.


Sintaxe: ISDIGIT ( < cString > )

Parmetros:
cString

Cadeia de caracteres a ser examinada.

Retorno:
Lgico

Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito


entre zero e nove; caso contrrio, retorna falso (.F.).

- 353 Guia de Referncia Rpida


ADVPL Avanado

ISLOWER()
Funo utilizada para determinar se o caractere mais esquerda uma letra minscula,
permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio
de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula.
ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.


Sintaxe: ISLOWER( < cString > )

Parmetros:
cString

Cadeia de caracteres a ser examinada.

Retorno:

Lgico

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


caso contrrio, retorna falso (.F.).

ISUPPER()
Funo utilizada para determinar se o caractere mais esquerda uma letra maiscula,
permitindo avaliar se o primeiro caractere de um string uma letra maiscula. o contrrio
de ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula.
ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.


Sintaxe: ISUPPER( < cString > )

Parmetros:
cString

Cadeia de caracteres a ser examinada.

Retorno:

Lgico

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


caso contrrio, retorna falso (.F.).

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

- 354 Guia de Referncia Rpida


ADVPL Avanado

LOWER()
Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.



Sintaxe: LOWER(cString)
Parmetros
cString

String que ser convertida para caracteres minsculos.

Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))

LTRIM()
Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
possuam espaos em branco esquerda. Pode ser o caso de, por exemplo, nmeros
convertidos para cadeias de caracteres atravs da funo STR().
LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a ALLTRIM(),
que remove espaos tanto esquerda quanto direita.
O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs
da insero de caracteres de preenchimento.



Sintaxe: LTRIM ( < cString > )


Parmetros:
cString

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


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

- 355 Guia de Referncia Rpida


ADVPL Avanado

MATHC()
Funo utilizada para realizar operaes matemticas com strings que contm um valor
numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao, Diviso,
Multiplicao e Exponenciao.
A funo ir retornar uma string contendo o resultado da operao matemtica, com uma
especificao de at 18 casas de preciso no numero.



Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )
Parmetros:
cNum1
cOperacao
cNum2

String contendo um valor numrico, representando o numero no qual


desejamos realizar uma operao.
Representa a string que indica a operao que desejamos realizar. Olhar na
tabela para verificar quais valores devem ser informados aqui.
String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.

Retorno:
Caracter

Retorna uma nova string contendo o resultado matemtico da operao.

OEMTOANSI()
Funo que transforma uma string no Formato OEM / MS-DOS Text para uma string ANSI
Text ( formato do Windows ).
Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de dados , os
acentos e caracteres especiais so gravados como texto OEM . Para tornar possvel a correta
visualizao destes dados em uma interface Windows , utilizamos a funo OemToAnsi() para
realizar a converso.
Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados , o texto
capturado no formato ANSI Text . Caso este texto seja utilizado para alimentar uma base de
dados a ser acessada atravs de um programa MS-DOS , devemos converter o dado para OEM
antes de grav-lo , atravs da funo AnsiToOem().



Sintaxe: OemToAnsi ( < cStringOEM > )


Parmetros:
cStringOEM

String em formato OEM - MsDos a ser convertida.

Retorno:
Caracter

String convertida para ser exibida no Windows ( Formato ANSI ).

- 356 Guia de Referncia Rpida


ADVPL Avanado

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




Caractere, data, ou numrico no qual sero inseridos caracteres de


preenchimento.
Tamanho da cadeia de caracteres a ser retornada.

cExp
nTamanho
cCaracPreench

Caractere a ser inserido em cExp. Caso no seja especificado, o padro


o espao em branco.

Retorno:

Caracter

Retornam o resultado de <cExp> na forma de uma cadeia de caracteres


preenchida com <cCaracPreench>, para totalizar o tamanho
especificado por <nTamanho>.

RAT()
Retorna a ltima posio de um caracter ou string dentro de outra string especificada.




Sintaxe: RAT(cCaractere, cString)


Parmetros
cCaractere

Caractere ou string que se deseja verificar

cString

String na qual ser verificada a existncia do contedo de cCaractere.

- 357 Guia de Referncia Rpida


ADVPL Avanado

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:
String contendo as ocorrncias de repeticao geradas para o caracter
informado.

cReplicated

RETASC()
A funo Replicate() utilizada para converter uma string numrica em uma informao
composta por letras e nmeros, devido a limitao no tamanho de campos ou variveis de
controle, como o caso do campo de sistema X3_ORDEM.


Sintaxe: RETASC(cString, nTamanho, lVolta)

Parmetros:

cString

String a ser convertida

nTamanho

Tamanho mximo da string de retorno

lVolta

Indica se ser gerada uma string composta por letras e nmeros a partir de
uma string apenas numrica (.T.) ou se ser gerada uma string numrica a
partir de uma string composta por letras e nmeros (.F.)

Retorno:
Caracter

String convertida conforme o parmetro lVolta.

Exemplo1 Converso de numrico para alfanumrico


cOrdem := 100
cX3Ordem := RETASC(cOrdem,2,.T.) <-- Ser retornado A0

Exemplo2 Converso de alfanumrico para numrico


cX3Ordem:= A0
cOrdem:= RETASC(cX3Ordem,3,.F.) <-- Ser retornado 100

- 358 Guia de Referncia Rpida


ADVPL Avanado

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


Sintaxe: RTRIM ( < cString > ) --> cTrimString

Parmetros:
cString

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


direita.

Retorno:
Caracter

RTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco


direita foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou totalmente composta por espaos, RTRIM() retorna uma cadeia
de caracteres nula ("").

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

- 359 Guia de Referncia Rpida


ADVPL Avanado

STRTOKARR()
Funo utilizada para retornar um array, de acordo com os dados passados como parmetro
para a funo. Esta funo recebe uma string <cValue> e um caracter <cToken> que
representa um separador, e para toda ocorrncia deste separador em <cValue> adicionado
um item no array.


Sintaxe: STRTOKARR ( < cValue > , < cToken > )

Parmetros:
cValue
cToken

Representa a cadeia de caracteres no qual desejamos separar de acordo com


<cToken>.
Representa o caracter que indica o separador em <cValue>.

Retorno:
Array

Array de caracteres que representa a string passada como parmetro.

Exemplo:
STRTOKARR('1;2;3;4;5', ';')

//retorna {'1','2','3','4','5'}

STRTRAN()
Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.


Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [
nCount ] )

Parmetros:
cString

Seqncia de caracteres ou campo memo a ser pesquisado.

cSearch

Seqncia de caracteres a ser procurada em cString.

cReplace

Seqncia de caracteres que deve substituir a string cSearch. Caso no


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

nStart

nCount

Retorno:
Code-Block

A funo STRTRAN retorna uma nova string, com as ocorrncias


especificadas
de
cSearch
trocadas
para
cReplace,
conforme
parametrizao.

- 360 Guia de Referncia Rpida


ADVPL Avanado

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:

nExcluir

A cadeia de caracteres destino na qual sero eliminados e inseridos


caracteres.
A posio inicial na cadeia de caracteres destino onde ocorre a
insero/eliminao.
A quantidade de caracteres a serem eliminados.

cAdicao

A cadeia de caracteres a ser inserida.

cString
nPosInicial

Retorno:
Caracter

Retorna a nova string gerada pela funo com as modificaes.

Exemplo:
cLin := Space(100)+cEOL // Cria a string base
cCpo := PADR(SA1->A1_FILIAL,02) // Informao que ser armazenada na string
cLin := Stuff(cLin,01,02,cCpo) // Substitui o contedo de cCpo na string base

SUBSTR()
Retorna parte do contedo de uma string especificada, de acordo com a posio inicial deste
contedo na string e a quantidade de caracteres que dever ser retornada a partir daquele
ponto (inclusive).



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_

- 361 Guia de Referncia Rpida


ADVPL Avanado

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
cSayPicture

O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
Uma string de caracteres de mscara e template usado para descrever o
formato da cadeia de caracteres a ser retornada.

Retorno:

Retorna a converso de <cExp> para uma cadeia de caracteres formatada


conforme a definio em <cSayPicture>.

UPPER()
Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.



Sintaxe: UPPER(cString)
Parmetros
cString

String que ser convertida para caracteres maisculos.

Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))

- 362 Guia de Referncia Rpida


ADVPL Avanado

Manipulao de data / hora


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




Data que ser convertida.

dExp
Retorno:

Nome do dia da semana como uma cadeia de caracteres. A primeira letra


maiscula e as demais minsculas.

cDayWeek

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.

Exemplo:
cMes
cMes
cMes
cMes

:=
:=
:=
:=

CMONTH(DATE()) // Resultado: September


CMONTH(DATE() + 45) // Resultado: October
CMONTH(CTOD("12/01/94")) // Resultado: December
SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE())) // Resultado: Sep 1

- 363 Guia de Referncia Rpida


ADVPL Avanado

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() // Resultado: 09/01/01
dData := DATE() + 30 // Resultado: 10/01/01
dData := DATE() - 30 // Resultado: 08/02/90
dData := DATE()
cMes := CMONTH(dData) // Resultado: September

DAY()
Funo de converso de datas usada para converter o valor data em um nmero inteiro que
representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR()
para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas.



Sintaxe: DAY( dData )


Parmetros:
dData

Data que ser convertida.

Retorno:
nDias

Se o ms do argumento dData for fevereiro, anos bissextos so


considerados. Se a data do argumento dData for 29 de fevereiro e o ano no
for bissexto, ou se o argumento dData for vazio.

Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
dData := DATE() // Resultado: 09/01/01
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

- 364 Guia de Referncia Rpida


ADVPL Avanado

DOW()
Funo que converte uma data para o valor numrico que representa o dia da semana. til
quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o dia da
semana como uma cadeia de caracteres.



Sintaxe: DOW( dData )


Parmetros:
dData

Data que ser convertida.

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:
dData := DATE() // Resultado: 09/01/01
nDiaDaSemana := DOW(DATE()) // Resultado: 3
cDiaDaSemana := CDOW(DATE()) // Resultado: Tuesday
nDiaDaSemana := DOW(DATE() - 2) // Resultado: 1
cDiaDaSemana := CDOW(DATE() - 2) // Resultado: Sunday

DTOC()
Funo para converso de uma data para uma cadeia de caracteres formatada segundo o
padro corrente, definido pelo comando SET DATE. Se for necessria a utilizao de
formatao especial, use a funo TRANSFORM().
Em expresses de ndices de arquivo, use DTOS() no lugar de DTOC() para converter datas
para cadeia de caracteres.



Sintaxe: DTOC( dData )


Parmetros:
dData

Data que ser convertida.

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

- 365 Guia de Referncia Rpida


ADVPL Avanado

DTOS()
Funo para converso de uma data que pode ser usada para criar expresses de ndice. O
resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia).



Sintaxe: DTOS( dData )


Parmetros:
dData

Data que ser convertida.

Retorno:
sData

Retorna uma cadeia de caracteres com oito byte de tamanho no formato


yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia
de caracteres com oito espaos. O valor retornado no afetado pela
formato da data corrente.

Exemplo:
cData := DATE() // Resultado: 09/01/90
cData := DTOS(DATE()) // Resultado: 19900901
nLen := LEN(DTOS(CTOD(""))) // Resultado: 8

ELAPTIME()
Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no formato
hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.



Sintaxe: ElapTime( cHoraInicial , cHoraFinal )


Parmetros:
cHoraInicial
CHoraFinal

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


mm os minutos e ss os segundos
Informe a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm
os minutos e ss os segundos.

Retorno:
Caracter

A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),


mm os minutos e ss os segundos.

Exemplo:
cHoraInicio := TIME() // Resultado: 10:00:00
...
<instrues>
...
cElapsed := ELAPTIME(TIME(), cHoraInicio)

- 366 Guia de Referncia Rpida


ADVPL Avanado

MONTH()
Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que
retorna o nome do ms a partir do valor de dData.



Sintaxe: MONTH( dData )


Parmetros:
dData

Data que ser convertida.

Retorno:
Numrico

>=0 e <=12  Para uma data vlida.


0  Se a data for nula ou invlida

Exemplo:
dData := DATE() // Resultado: 09/01/01
nMes := MONTH(DATE()) // Resultado: 9
nMes := MONTH(DATE()) + 1 // Resultado: 10

SECONDS()
Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a hora do
sistema. Est relacionada funo TIME() que retorna a hora do sistema como uma cadeia de
caracteres no formato hh:mm:ss.



Sintaxe: SECONDS()
Parmetros:
Nenhum

Retorno:
Numrico

>=0 e <=86399  Retorna a hora do sistema em segundos. O valor


numrico representa o nmero de segundos decorridos desde a meia-noite,
baseado no relgio de 24 horas e varia de 0 a 86399.

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

- 367 Guia de Referncia Rpida


ADVPL Avanado

TIME()
Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada
com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a
meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos.



Sintaxe: TIME()
Parmetros:
Nenhum

Retorno:
Caracter

A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss


onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

Exemplo:
cTime := TIME() // Resultado: 10:37:17
cHora := SUBSTR(cTime, 1, 2) // Resultado: 10
cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37
cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17

YEAR()
YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR()
membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui
DAY() e MONTH() que retornam o dia e o ms como valores numricos.



Sintaxe: YEAR( dData )


Parmetros:
dData

Data que ser convertida.

Retorno:
Numrico

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


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

Exemplo 01:
dData := DATE() // Resultado: 09/20/01
dAno := YEAR(dData) // Resultado: 2001
dAno := YEAR(dData) + 11 // Resultado: 2012

- 368 Guia de Referncia Rpida


ADVPL Avanado

Exemplo 02:
// Este exemplo cria uma funo de usurio que usa a funo YEAR() para formatar o valor da
// data:
cData := Mdy(DATE()) // Result: September 20, 1990
FUNCTION Mdy( dDate )
RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))) + "," + STR(YEAR(dDate))

Manipulao de variveis numricas


ABS()
Retorna um valor absoluto (independente do sinal) com base no valor especificado no
parmetro.



Sintaxe: ABS(nValor)
Parmetros
nValor

Valor que ser avaliado

Exemplo:
nPessoas := 20
nLugares := 18
IF nPessoas < nLugares
MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando)
ENDIF

ALEATORIO()
Gera um nmero aleatrio de acordo com a semente passada. Esta funo retorna um nmero
aleatrio menor ou igual ao primeiro parmetro informado, usando como semente o segundo
parmetro. recomendado que esta semente seja sempre o ltimo nmero aleatrio gerado
por esta funo.



Sintaxe: Aleatorio(nMax,nSeed)
Parmetros
nMax

Nmero mximo para a gerao do nmero aleatrio

nSeed

Semente para a gerao do nmero aleatrio

- 369 Guia de Referncia Rpida


ADVPL Avanado

Exemplo Funo ALEATORIO()


nSeed := 0
For i := 1 to 100
nSeed := Aleatorio(100,nSeed)
? Str(i,3)+ numero aleatorio gerado: +Str(nSeed,3)
Next i
inkey(0)
Return

INT()
Retorna a parte inteira de um valor especificado no parmetro.



Sintaxe: INT(nValor)
Parmetros
nValor

Valor que ser avaliado

Exemplo:
STATIC FUNCTION COMPRAR(nQuantidade)
LOCAL nDinheiro := 0.30
LOCAL nPrcUnit := 0.25
IF nDinheiro >= (nQuantidade*nPrcUnit)
RETURN nQuantidade
ELSEIF nDinheiro > nPrcUnit
nQuantidade := INT(nDinheiro / nPrcUnit)
ELSE
nQuantidade := 0
ENDIF
RETURN nQuantidade

NOROUND()
Retorna um valor, truncando a parte decimal do valor especificado no parmetro de acordo
com a quantidade de casas decimais solicitadas.



Sintaxe: NOROUND(nValor, nCasas)


Parmetros
nValor

Valor que ser avaliado

nCasas

Nmero de casas decimais vlidas. A partir da casa decimal especificada os


valores sero desconsiderados.

- 370 Guia de Referncia Rpida


ADVPL Avanado

Exemplo Funo NOROUND()


nBase := 2.985
nValor := NOROUND(nBase,2)  2.98

RANDOMIZE()
Atravs da funo RANDOMIZE() , geramos um numero inteiro aleatrio, compreendido entre
a faixa inferior e superior recebida atravs dos parmetros nMinimo e nMaximo,
respectivamente.
Observao :
 O limite inferior recebido atravs do parmetro nMinimo "maior ou igual a ", podendo
ser sorteado e fazer parte do retorno; porm o limite superior "menor que", de modo
a nunca ser atingido ou devolvido no resultado. Por exemplo , a chamada da funo
RANDOMIZE(1,2) sempre retornar 1 .


Sintaxe: RANDOMIZE ( < nMinimo > , < nMaximo > )

Parmetros

nMinimo

Corresponde ao menor numero a ser gerado pela funo.

nMaximo

Corresponde ao maior nmero ( menos um ) a ser gerado pela funo.

Retorno:
Numrico

Numero randmico , compreendido no intervalo entre (nMinimo) e


(nMaximo-1) : O numero gerado pode ser maior ou igual nMinimo e menor
ou igual a nMaximo-1 .

ROUND()
Retorna um valor, arredondando a parte decimal do valor especificado no parmetro de acordo
com a quantidades de casas decimais solicitadas, utilizando o critrio matemtico.



Sintaxe: ROUND(nValor, nCasas)


Parmetros
nValor

Valor que ser avaliado

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

- 371 Guia de Referncia Rpida


ADVPL Avanado

Manipulao de arquivos
ADIR()
Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da
mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados.
Importante: ADir uma funo obsoleta, utilize sempre Directory().


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


[ aAtributo ])

Parmetros:
cArqEspec

aNomeArq
aTamanho
aData
aHora
aAtributos

Caminho dos arquivos a serem includos na busca de informaes. Segue o


padro para especificao de arquivos, aceitando arquivos no servidor
Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso
seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ).
Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
Array Numrico. So os tamanhos dos arquivos encontrados na busca.
Array de Datas. So as datas de modificao dos arquivos encontrados na
busca.
Array de Caracteres. So os horrios de modificao dos arquivos
encontrados. Cada elemento contm horrio no formato: hh:mm:ss.
Array de Caracteres. So os atributos dos arquivos, caso esse array seja
passado como parmetros, sero includos os arquivos com atributos de
sistema e ocultos.

Retorno:
nArquivos

Quantidade de arquivos encontrados.

Exemplo:
LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })

- 372 Guia de Referncia Rpida


ADVPL Avanado

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

'Fontes',

1,

'C:\VER507',

- 373 Guia de Referncia Rpida


ADVPL Avanado

.F.,

GETF_LOCALHARD

Aparncia:

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.

- 374 Guia de Referncia Rpida


ADVPL Avanado

Exemplo: Seleo de mltiplos arquivos com CGETFILE, DIRECTORY() e LISTBOX()


Funo Principal: SELFILE()

#include "protheus.ch"
//+--------------------------------------------------------------------+
//| Rotina | SELFILE | Autor | ARNALDO R. JUNIOR | Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo para seleo de mltiplos arquivos.
|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
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

- 375 Guia de Referncia Rpida


ADVPL Avanado

Funo auxiliar: PARBOXFILE()

//+--------------------------------------------------------------------+
//| Rotina | PARBOXFILE | Autor | ARNALDO R. JUNIOR Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo de uso da PARAMBOX em conjunto com CGETFILE|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION PARBOXFILE()
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

aParamBox := {}
cTitulo
:= "Filtros Adicionais"
aRet := {}
bOk
:= {|| .T.}
aButtons
:= {}
lCentered
:= .T.
nPosx
nPosy
cLoad := ""
lCanSave
:= .F.
lUserSave := .F.
nX
:= 0
lRet := .T.

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

- 376 Guia de Referncia Rpida


ADVPL Avanado

Funo auxiliar: MARKFILE()

//+--------------------------------------------------------------------+
//| Rotina | MARKFILE | Autor | ARNALDO R. JUNIOR | Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Descr. | Funo exemplo para marcao de mltiplos arquivos.
|
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION MARKFILE(aArquivos,cDiretorio,cDriver,lSelecao)
Local aChaveArq
:= {}
Local cTitulo
:= "Arquivos para importao: "
Local bCondicao
:= {|| .T.}
// Variveis utilizadas na seleo de categorias
Local oChkQual,lQual,oQual,cVarQ
// Carrega bitmaps
Local oOk
:= LoadBitmap( GetResources(), "LBOK")
Local oNo
:= LoadBitmap( GetResources(), "LBNO")
// Variveis utilizadas para lista de filiais
Local nx
:= 0
Local nAchou
:= 0
//+--------------------------------------------------------------------+
//| Carrega os arquivos do diretrio no array da ListBox
|
//+--------------------------------------------------------------------+
For nX := 1 to Len(aArquivos)
//+--------------------------------------------------------------------+
//| aChaveArq - Contem os arquivos que sero exibidos para seleo
|
//+--------------------------------------------------------------------+
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
ACTIVATE MSDIALOG oDlg CENTERED
RETURN aChaveArq

- 377 Guia de Referncia Rpida


ADVPL Avanado

Funo auxiliar: TROCA()

//+--------------------------------------------------------------------+
//| Rotina | TROCA
| Autor | ARNALDO R. JUNIOR | Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION Troca(nIt,aArray)
aArray[nIt,1] := !aArray[nIt,1]
Return aArray

Funo auxiliar: MARCAOK()

//+--------------------------------------------------------------------+
//| Rotina | MARCAOK | Autor | ARNALDO R. JUNIOR | Data | 01.01.2007 |
//+--------------------------------------------------------------------+
//| Uso
| CURSO DE ADVPL
|
//+--------------------------------------------------------------------+
STATIC FUNCTION MarcaOk(aArray)
Local lRet:=.F.
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

- 378 Guia de Referncia Rpida


ADVPL Avanado

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:

cDestino

Nome(s) dos arquivos a serem copiados, aceita apenas arquivos no servidor,


WildCards ( * e ? ) so aceitos normalmente.
Diretrio com o destino dos arquivos no Client ( Remote ).

lCompacta

Indica se a cpia deve ser feita compactando o arquivo antes do envio.

cOrigem

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:

cDestino

Nomes dos arquivos a serem copiados, aceita apenas arquivos locais (


Cliente ), WildCards so aceitos normalmente.
Diretrio com o destino dos arquivos no remote ( Cliente ).

lCompacta

Indica se a cpia deve ser feita compactando o arquivo antes.

cOrigem

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

- 379 Guia de Referncia Rpida


ADVPL Avanado

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

- 380 Guia de Referncia Rpida


ADVPL Avanado

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

Incluir arquivos ocultos

Incluir arquivos de sistema

Incluir diretrios

Procura pelo volume DOS e exclui outros arquivos

Nota: Arquivos normais so sempre includos na pesquisa, a no ser que V seja especificado.


TABELA B: Estrutura dos Subvetores de DIRECTORY()


Posio

Metasmbolo

Directry.ch

cNome

F_NAME

cTamanho

F_SIZE

dData

F_DATE

cHora

F_TIME

cAtributos

F_ATT

Sintaxe: DIRECTORY ( < cDirSpec > , [ ] )

Parmetros:
cDirSpec

cAtributos>

<cDirSpec> especifica o drive, diretrio e arquivo para a pesquisa no


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

- 381 Guia de Referncia Rpida


ADVPL Avanado

Retorno:
Array

DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor


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

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

- 382 Guia de Referncia Rpida


ADVPL Avanado

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
1
2
3
4

:
:
:
:
:

Unidade de disco atual da estao (DEFAULT).


Drive A: da estao remota.
Drive B: da estao remota.
Drive C: da estao remota.
Drive D: da estao remota ... e assim por diante.

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


Sintaxe: DISKSPACE ( [ nDrive ] )

Parmetros:
nDrive

Nmero do drive, onde 0 o espao na unidade de disco corrente, e 1 o


drive A: do cliente, 2 o drive B: do cliente, etc.

Retorno:
Numrico

Nmero de bytes disponveis no disco informado como parmetro.

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

- 383 Guia de Referncia Rpida


ADVPL Avanado

EXISTDIR()
Funo utilizada para determinar se um path de diretrio existe e valido.


Sintaxe: EXISTDIR (< cPath >)

Parmetros:
cPath

String contendo o diretrio que ser verificado, caso seja feita uma
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 01: No server a partir do rootPath


lRet := ExistDir('\teste')

Exemplo 02: 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.).

- 384 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
#include "Fileio.ch"
nHandle := FCREATE("Testfile", FC_NORMAL)
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

Criao normal do Arquivo (default/padro).

FC_READONLY

Cria o arquivo protegido para gravao.

FC_HIDDEN

Cria o arquivo como oculto.

FC_SYSTEM

Cria o arquivo como sistema.

Caso desejemos especificar mais de um atributo , basta som-los . Por exemplo , para criar
um arquivo protegido contra gravao e escondido , passamos como atributo FC_READONLY +
FC_HIDDEN.
.
Nota: Caso o arquivo j exista , o contedo do mesmo ser ELIMINADO , e seu tamanho ser
truncado para 0 ( ZERO ) bytes.


Sintaxe: FCREATE ( < cArquivo > , [ nAtributo ] )

Parmetros:
cArquivo

nAtributo

Nome do arquivo a ser criado , podendo ser especificado um path absoluto


ou relativo , para criar arquivos no ambiente local ( Remote ) ou no Servidor,
respectivamente .
Atributos do arquivo a ser criado (Vide Tabela de atributos abaixo). Caso no
especificado, o DEFAULT FC_NORMAL.

Retorno:
Numrico

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

- 385 Guia de Referncia Rpida


ADVPL Avanado

FERASE()
Funo utilizada para apagar um arquivo no disco . O Arquivo pode estar no Servidor ou na
estao local (Remote). O arquivo para ser apagado deve estar fechado, no sendo permitido
a utilizao de caracteres coringa (wildcards).


Sintaxe: FERASE ( < cArquivo > )

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

- 386 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
//Verifica no diretrio corrente do servidor se existe o arquivo teste.dbf
FILE("teste.dbf")
// Verifica no diretrio Sigaadv do servidor se existe o arquivo teste.dbf
FILE("\SIGAADV\TESTE.dbf")
// Verifica no diretrio Temp do cliente (Remote) se existe o arquivo teste.dbf
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

- 387 Guia de Referncia Rpida


ADVPL Avanado

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

FOPEN procura o arquivo no diretrio corrente e nos diretrios


configurados na varivel de pesquisa do Sistema Operacional, a no
ser que um path seja declarado explicitamente como parte do
argumento <cArq>.

Por serem executadas em um ambiente cliente-servidor, as funes


de tratamento de arquivos podem trabalhar em arquivos localizados
no cliente (estao) ou no servidor. O ADVPL identifica o local onde o
arquivo ser manipulado atravs da existncia ou no da letra do
drive no nome do arquivo passado em <cArq>. Ou seja, se o arquivo
for especificado com a 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.

- 388 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
#include 'fileio.ch'
...
nH := fopen('\sigaadv\error.log' , FO_READWRITE + FO_SHARED )
If nH == -1
MsgStop('Erro de abertura : FERROR '+str(ferror(),4))
Else
MsgStop('Arquivo aberto com sucesso.')
...
fclose(nH)
Endif
...


Tabela A: Modos de acesso a arquivos binrios


Modo

Constate(fileio.ch)

Operao

FO_READ

Aberto para leitura (padro assumido)

FO_WRITE

Aberto para gravao

FO_READWRITE

Aberto para leitura e gravao

Tabela B: Modos de acesso de compartilhamento a arquivos binrios


Modo

Constate(fileio.ch)

Operao

FO_COMPAT

Modo de Compatibilidade (Default)

16

FO_EXCLUSIVE

Acesso total exclusivo

32

FO_DENYWRITE

48

FO_DENYREAD

64

FO_DENYNONE

Acesso bloqueando a gravao de outros


processos ao arquivo.
Acesso bloqueando a leitura de outros
processos ao arquivo.
Acesso compartilhado. Permite a leitura e
gravao por outros.

- 389 Guia de Referncia Rpida


ADVPL Avanado

FREAD()
Funo que realiza a leitura dos dados a partir um arquivo aberto, atravs de FOPEN(),
FCREATE() e/ou FOPENPORT(), e armazena os dados lidos por referncia no buffer informado.
FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum erro ou o
arquivo chegue ao final, FREAD() retornar um nmero menor que o especificado em
nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128, ASC 0, etc.) e l a partir
da posio atual do ponteiro atual do arquivo , que pode ser ajustado ou modificado pelas
funes FSEEK() , FWRITE() ou FREADSTR().
A varivel String a ser utilizada como buffer de leitura deve ser sempre pr-alocado e passado
como referncia. Caso contrrio, os dados no podero ser retornados.


Sintaxe: FREAD ( < nHandle > , < cBuffer > , < nQtdBytes > )

Parmetros:
nHandle
cBuffer

nQtdBytes

o manipulador (Handle) retornado pelas funes FOPEN(),


FCREATE(), FOPENPORT(), que faz referncia ao arquivo a ser lido.
o nome de uma varivel do tipo String , a ser utilizada como buffer de
leitura , onde os dados lidos devero ser armazenados. O tamanho desta
varivel deve ser maior ou igual ao tamanho informado em nQtdBytes.
Esta varivel deve ser sempre passada por referncia. ( @ antes do nome da
varivel ), caso contrrio os dados lidos no sero retornados.
Define a quantidade de Bytes que devem ser lidas do arquivo a partir
posicionamento do ponteiro atual.

Retorno:
Numrico

Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada,


isto indica erro de leitura ou final de arquivo, Verifique a funo FERROR()
para maiores detalhes.

FREADSTR ()
Funo que realiza a leitura de caracteres de um arquivo binrio. FREADSTR() l de um
arquivo aberto, atravs de FOPEN(), FCREATE(), FOPENPORT(). FREADSTR() ler at o nmero
de bytes informado em nQtdBytes ou at encontrar um CHR(0). Caso acontea algum erro ou
o arquivo chegue ao final, FREADSTR() retornar uma string menor do que nQdBytes e
colocar o erro em FERROR(). FREADSTR() l a partir da posio atual do ponteiro, que pode
ser ajustado pelo FSEEK(), FWRITE( ) ou FREAD().


Sintaxe: FREADSTR ( < nHandle > , < nQtdBytes > )

Parmetros:
nHandle
nQtdBytes

o manipulador retornado pelas funes FOPEN(),


FCREATE(), FOPENPORT().
Nmero mximo de bytes que devem ser lidos.

Retorno:
Caracter

Retorna uma string contendo os caracteres


lidos.
- 390 Guia de Referncia Rpida
ADVPL Avanado

FRENAME()
Atravs da funo FRENAME() possvel renomear um arquivo para outro nome, tanto no
servidor como na estao. Ao renomear um arquivo no esquea que esta arquivo dever
estar fechado ( isto , no pode estar em uso por nenhum outro processo ou estao). Caso o
arquivo esteja aberto por outro processo , a operao de renomear o arquivo no possvel. A
funo fRename() no aceita wildcards ( * e/ou ? ).
Vale lembrar que no possvel renomear um arquivo especificando nos parmetros
simultaneamente um caminho de servidor e um de estao remota, bem como especificar dois
arquivos remotos e executar a funo fRename() atravs de um JOB. Caso isto ocorra, a
funo retornar -1 , e fError() retornar tambm -1.

Quando especificamos um path diferente nos arquivos de origem e destino ,


a funo fRename() realiza a funcionalidade de MOVER o arquivo para o Path
especificado.

Sintaxe: FRENAME ( < cOldFile > , < cNewFile > )

Parmetros:
cOldFile

cNewFile

Nome do arquivo ser renomeado, aceita caminhos do servidor e caminhos


do cliente. Caso no seja especificado nenhuma unidade de disco e path,
considerado o path atual no servidor.
Novo nome do arquivo, aceita tambm caminho do servidor, e caminho do
cliente.

Retorno:
Numrico

Se o status retornado for -1 , ocorreu algum erro na mudana de nome :


Verifique se os dois caminhos esto no mesmo ambiente, verifique a
existncia do arquivo de origem, se ele no est em uso no momento por
outro processo , e verifique se o nome do arquivo de destino j no existe no
path de destino especificado.

- 391 Guia de Referncia Rpida


ADVPL Avanado

FSEEK()
Funo que posiciona o ponteiro do arquivo para as prximas operaes de leitura ou
gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os seguintes
valores, definidos em fileio.ch:


Tabela A: Origem a ser considerada para a movimentao do ponteiro de


posicionamento do Arquivo.
Origem

Constate(fileio.ch)

Operao

FS_SET

Ajusta a partir do inicio do arquivo. (Default)

FS_RELATIVE

Ajuste relativo a posio atual do arquivo.

FS_END

Ajuste a partir do final do arquivo.

Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] )

Parmetros:
nHandle

Manipulador obtido atravs das funes FCREATE,FOPEN.

nOffSet

nOffSet corresponde ao nmero de bytes no ponteiro de posicionamento do


arquivo a ser movido. Pode ser um numero positivo , zero ou negativo, a ser
considerado a partir do parmetro passado em nOrigem.
Indica a partir de qual posio do arquivo, o nOffset ser considerado.

nOrigem


Retorno:
Numrico

FSEEK() retorna a nova posio do ponteiro de arquivo com relao ao incio


do arquivo (posio 0) na forma de um valor numrico inteiro. Este valor no
leva em conta a posio original do ponteiro de arquivos antes da execuo
da funo FSEEK().

FT_FEOF()
Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE() estiver
posicionado no final do arquivo, similar funo EOF() utilizada para arquivos de dados.


Sintaxe: FT_FEOF( )

Parmetros:
Nenhum

Retorno:
Lgico

Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso
contrrio.

- 392 Guia de Referncia Rpida


ADVPL Avanado

FT_FGOTO()
Funo utilizada para mover o ponteiro, que indica a leitura do arquivo texto, para a posio
absoluta especificada pelo argumento <nPos>.


Sintaxe: FT_FGOTO ( < nPos > )

Parmetros:
nPos

Indica a posio que ser colocado o ponteiro para leitura dos dados no
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).
- 393 Guia de Referncia Rpida
ADVPL Avanado

Exemplo:
FT_FUse('teste.txt') // Abre o arquivo
CONOUT("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln()+"]")
FT_FSkip()
Enddo
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.

- 394 Guia de Referncia Rpida


ADVPL Avanado

FT_FRECNO()
A funo tem o objetivo de retornar a posio do ponteiro do arquivo texto.
A funo FT_FRecno retorna a posio corrente do ponteiro do arquivo texto aberto pela
FT_FUse.



Sintaxe: FT_FRECNO ( )
Parmetros:
Nenhum

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
- 395 Guia de Referncia Rpida
ADVPL Avanado

FWRITE()
Funo que permite a escrita em todo ou em parte do contedo do buffer , limitando a
quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da posio
corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes
escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou criar
um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou enviados os
dados do buffer informado. Por tratar-se de uma funo de manipulao de contedo binrio ,
so suportados na String cBuffer todos os caracteres da tabela ASCII , inclusive caracteres de
controle ( ASC 0 , ASC 12 , ASC 128 , etc.).
Caso acontea alguma falha na gravao , a funo retornar um nmero menor que o
nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro
especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do ponteiro ,
que pode ser ajustado atravs das funes FSEEK() , FREAD() ou FREADSTR().


Sintaxe: FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] )

Parmetros:
nHandle
cBuffer

nQtdBytes

o manipulador de arquivo ou device retornado pelas funes FOPEN(),


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

Retorno:
Numrico

FWRITE() retorna a quantidade de bytes escritos na forma de um valor


numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
operao foi bem sucedida. Caso o valor de retorno seja menor que
<nBytes> ou zero, ou o disco est cheio ou ocorreu outro erro. Neste caso ,
utilize a funo FERROR() para obter maiores detalhes da ocorrncia.

Exemplo:
#INCLUDE "FILEIO.CH"
#DEFINE F_BLOCK 1024 // Define o bloco de Bytes a serem lidos / gravados por vez
User Function TestCopy()
Local cBuffer := SPACE(F_BLOCK)
Local nHOrigem , nHDestino
Local nBytesLidos , nBytesFalta , nTamArquivo
Local nBytesLer , nBytesSalvo
Local lCopiaOk := .T.
// Abre o arquivo de Origem
nHOrigem := FOPEN("ORIGEM.TXT", FO_READ)

- 396 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
// 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

- 397 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
// 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

- 398 Guia de Referncia Rpida


ADVPL Avanado

MSCOPYTO()
Funo que realiza a cpia dos registros de uma base de dados para outra, criando o arquivo
destino de acordo com a estrutura da base de dados origem.


Sintaxe: MSCOPYTO( [cArqOrig], cArqDest )

Parmetros:

cArqOrig

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.

- 399 Guia de Referncia Rpida


ADVPL Avanado

Retorno:
Lgico

Indica se a operao foi executada com sucesso.

Exemplo:
Local cTarget := '\sigaadv\'
Local aStrut
aStrut := { { 'Campo', 'C', 40, 0 } }
If MsCreate( cTarget+'ARQ1001', aStrut )
APMsgInfo('Criado com sucesso!')
Else
APMsgInfo('Problemas ao criar o arquivo!')
EndIf

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

- 400 Guia de Referncia Rpida


ADVPL Avanado

MSRENAME()
Funo que verifica a existncia do arquivo especificado.


Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] )

Parmetros:

cArquivo

Nome do arquivo e a extenso.

cIndice

Nome do arquivo de ndice e a extenso.

cDriver

RDD do arquivo, se no for informado assumir o RDD corrente.

Retorno:
Lgico

Indica se o arquivo especificado existe.

Exemplo:
Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If !MsFile ( cArquivo, cIndice )
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

- 401 Guia de Referncia Rpida


ADVPL Avanado

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:
Array multidimensional contendo a estrutura de campos da tabela que ser
criada no formato: {Nome, Tipo, Tamanho, Decimal}
Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )

aArray
lDbf


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

- 402 Guia de Referncia Rpida


ADVPL Avanado

Manipulao de bases de dados


ALIAS()
Funo de banco de dados utilizada para determinar o alias da rea de trabalho especificada.
Alias o nome atribuido a uma rea de trabalho quando um arquivo de banco de dados est
em uso. O nome real atribuido o nome do arquivo de banco de dados, ou um nome que foi
explicitamente
atribuido
atravs
da
clusula
ALIAS
do
comando
USE.
A funo ALIAS() o inverso da funao SELECT() pois retorna o alias atravs do nmero da
rea de trabalho, enquanto SELECT() retorna o nmero da rea de trabalho atravs do alias.


Sintaxe: ALIAS ( [ nAreaTrabalho ] )

Parmetros:
nAreaTrabalho

<nAreaTrabalho> o nmero da rea de trabalho a ser verificada.

Retorno:
Caracter

Retorna o alias da rea de trabalho especificada na forma de uma cadeia


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

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

- 403 Guia de Referncia Rpida


ADVPL Avanado

Sintaxe: BOF() / EOF()

Parmetros:
Nenhum

Retorno:
Lgico

Lgico

Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de


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

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

- 404 Guia de Referncia Rpida


ADVPL Avanado

A tabela de destino dos dados copiados criada, e aberta em modo exclusivo, antes da
operao de cpia efetiva ser iniciada.


Tabela A : Especificao do formato SDF ( System Data Format )

Elemento do Arquivo

Formato

Campos 'C' Caractere

Tamanho fixo, ajustado com espaos em branco

Campos 'D' Data

Formato aaaammdd ( ano, ms, dia )

Campos 'L' lgicos

T ou F

Campos 'M' Memo

(campo ignorado)

Campos 'N' Numricos

Ajustados direita, com espaos em branco.

Delimitador de Campos

Nenhum

Separador de Registros

CRLF ( ASCII 13 + ASCII 10 )

Marca de final de arquivo (EOF)

Nenhum

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

- 405 Guia de Referncia Rpida


ADVPL Avanado

Parmetros:
FIELDS <campo,...>
TO cFile

FIELDS <campo,...> especifica um ou mais campos, separados por


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

cEscopo

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.

WHILE <lCondicao>

FOR <lCondicao>
[SDF|DELIMITED]

OBSERVAO : Vale a pena lembrar que o escopo sensvel tambm s


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

VIA <cDriver>

Nas Tabelas complementares A e B, na documentao do comando, so


detalhadas as especificaes dos formatos SDF e DELIMITED.
VIA <xcDriver> permite especificar o driver utilizado para criar a tabela
de destino dos dados a serem copiados.
O Driver deve ser especificado como uma expresso caractere. Caso
especificado como um valor literal direto, o mesmo deve estar entre
aspas.

Retorno:
Nenhum

- 406 Guia de Referncia Rpida


ADVPL Avanado

COPY STRUCTURE()
O comando COPY STRUCTURE cria uma nova tabela vazia, com a estrutura da tabela ativa na
rea de trabalho atual. Se a tabela a ser criada j exista, a mesma sobrescrita. A tabela de
destino criada utiliza o mesmo RDD da tabela de origem ( tabela ativa na rea de trabalho
atual ).
A Linguagem Advpl, antes do Protheus, suportava a parametrizao de uma
lista de campos da tabela atual, para compor a estrutura da tabela de destino,
atravs da clusula FIELDS <campo,...>. Esta opo no suportada no
Protheus. Caso seja utilizada, o programa ser abortado com a ocorrncia de
erro fatal : 'DBCopyStruct - Parameter <Fields> not supported in
Protheus'


Sintaxe:

COPY STRUCTURE TO <xcDataBase>

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

- 407 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
USE Clientes NEW
FOR i:=1 to 5
DBAPPEND(.F.)
NOME := "XXX"
END : ="YYY"
NEXT
// Os 5 registros includos permanecem bloqueados
DBAPPEND()
// Todos os bloqueios anteriores so liberados

DBCLEARALLFILTER()
A funo DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as
tabelas e depois limpa as condies de filtro de todas as tabelas.


Sintaxe: DBCLEARALLFILTER()

Parmetros:
Nenhum

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

- 408 Guia de Referncia Rpida


ADVPL Avanado

DBCLEARFILTER()
A funo DBCLEARFILTER() salva as atualizaes realizadas e pendentes na tabela corrente e
depois limpa todas as condies de filtro da ordem ativa no momento. Seu funcionamento
oposto ao comando SET FILTER.


Sintaxe: DBCLEARFILTER()

Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:

USE Clientes NEW


DBSETFILTER( {|| Idade < 40}, "Idade < 40" ) // Seta a expresso de filtro
...
DBCLEARFILTER()
// Limpa a expresso de filtro

DBCLEARINDEX()
A funo DBCLEARINDEX() salva as atualizaes pendentes na tabela corrente e fecha todos
os arquivos de ndice da rea de trabalho. Por conseqncia, limpa todas as ordens da lista.
Seu funcionamento oposto ao comando SET INDEX.


Sintaxe: DBCLEARINDEX()

Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:
USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
...
DBCLEARINDEX()
// Fecha todos os arquivos de ndices

- 409 Guia de Referncia Rpida


ADVPL Avanado

DBCLOSEALL()
A funo DBCLOSEALL() salva as atualizaes pendentes,
bloqueados e fecha todas as tabelas abertas (reas
chamasse DBCLOSEAREA para cada rea de trabalho.


Sintaxe: DBCLOSEALL()

Parmetros:
Nenhum

libera todos os registros


de trabalho) como se

Retorno:
Nenhum

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCLOSEALL para fechar a rea de
trabalho atual.
USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
USE Fornecedores NEW
DBSETINDEX("Idade") // Abre o arquivo de ndice "Idade"
...
DBCLOSEALL() //Fecha todas as reas de trabalho, todos os indices e ordens

DBCLOSEAREA()
A funo DBCLOSEAREA() permite que um alias presente na conexo seja fechado, o que
viabiliza seu reuso em outro operao. Este comando tem efeito apenas no alias ativo na
conexo, sendo necessria sua utilizao em conjunto com o comando DbSelectArea().


Sintaxe: DBCLOSEAREA()

Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()

- 410 Guia de Referncia Rpida


ADVPL Avanado

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"
USE Fornecedores NEW
DBGOTO(168)
Nome := "Joao"
DBCOMMIT() // Salva em disco apenas as alteraes realizadas na tabela Fornecedores

DBCOMMITALL()
A funo DBCOMMITALL() salva em disco todas as atualizaes pendentes em todas
as reas de trabalho.


Sintaxe: DBCOMMITALL()

Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:
USE Clientes NEW
DBGOTO(100)
Nome := "Jose"
USE Fornecedores NEW
DBGOTO(168)
Nome := "Joao"
DBCOMMITALL()
// Salva em disco as alteraes realizadas nas tabelas Clientes e Fornecedores

- 411 Guia de Referncia Rpida


ADVPL Avanado

DBCREATE()
A funo DBCREATE() utilizada para criar um novo arquivo de tabela cujo nome
est especificado atravs do primeiro parmetro (cNome) e estrutura atravs do segundo
(aEstrutura). A estrutura especificada atravs de um array com todos os campos,
onde cada campo expresso atravs de um array contendo {Nome, Tipo, Tamanho,
Decimais}.


Sintaxe: DBCREATE ( < cNOME > , < aESTRUTURA > , [ cDRIVER ] )

Parmetros:
cNOME

aESTRUTURA

Nome da RDD a ser utilizado para a criao da tabela. Se for omitido ser
criada com a corrente.

cDRIVER

Nome do arquivo a ser criado. Se contm pasta, ela se localiza abaixo do


"RootPath". Se no, criado por padro no caminho formado por
"RootPath"+"StartPath"
Lista com as informaes dos campos para ser criada a tabela.

Retorno:
Nenhum

Exemplo:
// Este exemplo mostra como se pode criar novo arquivo atravs da funo DBCREATE:
LOCAL aEstrutura :={{Cod,N,3,0},
{Nome,C,10,0},
{Idade,N,3,0},
{Nasc,D,8,0},
{Pagto,N,7,2}}
// Cria a tabela com o RDD corrente
DBCREATE('\teste\cliente.dbf', aEstrutura)
USE '\teste\cliente.dbf' VIA 'DBFCDX' NEW

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

- 412 Guia de Referncia Rpida


ADVPL Avanado

total do campo numrico e 'dec' o nmero de decimais, ocorre este erro se:

(len = 1) .and. (dec <> 0): Se o tamanho total 1, o campo no pode


ter decimais

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

Erros mais comuns:


Podem ocorrer tambm erros decorrentes de permisso e direitos na pasta
onde se est tentando criar o arquivo ou por algum problema no banco de
dados. Verifique as mensagens do servidor Protheus e do banco de dados.

DBCREATEINDEX()
A funo DBCREATEINDEX() utilizada para criar um novo arquivo de ndice com o nome
especificado atravs do primeiro parmetro, sendo que se o mesmo existir deletado e criado
o novo. Para tanto so executados os passos a seguir:






Salva fisicamente as alteraes ocorridas na tabela corrente;


Fecha todos os arquivos de ndice abertos;
Cria o novo ndice;
Seta o novo ndice como a ordem corrente;
Posiciona a tabela corrente no primeiro registro do ndice.

Com exceo do RDD CTREE, a tabela corrente no precisa estar aberta em modo exclusivo
para a criao de ndice, pois na criao de ndices no Ctree alterada a estrutura da tabela,
precisando para isto a tabela estar aberta em modo exclusivo.


Sintaxe:

Parmetros:

DBCREATEINDEX(<cNOME>,
[lUNICO])

<cEXPCHAVE>,

[bEXPCHAVE],

cNOME

Nome do arquivo de ndice a ser criado.

cEXPCHAVE

Expresso das chaves do ndice a ser criado na forma de string.

bEXPCHAVE

Expresso das chaves do ndice a ser criado na forma executvel.

lUNICO

Cria ndice como nico (o padro .F.).

Retorno:
Nenhum

- 413 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:

// Este exemplo mostra como se pode criar novo arquivo de ndice criando a ordem sobre os
// campos Nome e End e no aceitar duplicao:
USE Cliente VIA "DBFCDX" NEW
DBCREATEINDEX("\teste\ind2.cdx","Nome+End",{ || Nome+End },.T.)

DBDELETE()
A funo DBDELETE() marca o registro corrente como apagado logicamente(), sendo
necessria sua utilizao em conjunto com as funes RecLock() e MsUnLock().
Para filtrar os registro marcados do alias corrente pode-se utilizar o comando SET DELETED e
para apag-los fisicamente pode-se utilizar a funo __DBPACK().


Sintaxe: DBDELETE ( )

Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found()
RecLock(SA1,.F.) // Define que ser realizada uma alterao no registro posicionado
DbDelete() // Efetua a excluso lgica do registro posicionado.
MsUnLock() // Confirma e finaliza a operao
ENDIF

- 414 Guia de Referncia Rpida


ADVPL Avanado

DBF()
A funo DBF() verifica qual o Alias da rea de trabalho corrente. O Alias definido
quando a tabela aberta atravs do parmetro correspondente (DBUSEAREA()). Esta funo
o inverso da funo SELECT(), pois nesta retornado o nmero da rea de trabalho do Alias
correspondente.



Sintaxe: DBF()
Parmetros:
Nenhum

Retorno:
Caracter

Retorna o Alias corrente. Caso no exista Alias corrente retorna "" (String
vazia).

Exemplo:
dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
MessageBox("O Alias corrente : "+DBF(),"Alias", 0) //Resultado: "O Alias corrente : SSS"

DBFIELDINFO()
A funo DBFIELDINFO() utilizada para obter informaes sobre determinado campo da
tabela corrente. O tipo de informao (primeiro argumento) escolhido de acordo com as
constantes abaixo:


Tabela A : Constantes utilizadas na parametrizao da funo


Constante

Descrio

Retorno

DBS_NAME

Nome do campo.

Caracter

DBS_DEC

Nmero de casas decimais.

Numrico

DBS_LEN

Tamanho.

Numrico

DBS_TYPE

Tipo.

Caracter

A posio do campo no leva em considerao os campos internos do Protheus (Recno e


Deleted).


Sintaxe: DBFIELDINFO ( < nINFOTIPO > , < nCAMPO > )

Parmetros:
nINFOTIPO
nCAMPO

Tipo de informao a ser verificada (DBS_NAME, DBS_DEC, DBS_LEN e


DBS_TYPE).
Posio do campo a ser verificado.

- 415 Guia de Referncia Rpida


ADVPL Avanado

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

- 416 Guia de Referncia Rpida


ADVPL Avanado

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
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)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
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.

- 417 Guia de Referncia Rpida


ADVPL Avanado

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)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
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:


Tabela A : Constantes utilizadas na parametrizao da funo


Constante

Descrio

Retorno

DBI_GETRECSIZE

Tamanho do registro em nmero de bytes


similar a RECSIZE.

Numrico

DBI_TABLEEXT

Extenso do arquivo da tabela corrente.

Caracter

DBI_FULLPATH

Nome da tabela corrente com caminho


completo.

Caracter

DBI_BOF

Se est posicionada no incio da tabela


similar a BOF

Lgico

DBI_EOF

Se est posicionada no final da tabela


similar a EOF

Lgico

DBI_FOUND

Se a tabela est posicionada aps uma


pesquisa similar a FOUND

Lgico

DBI_FCOUNT

Nmero de campos na estrutura


tabela corrente similar a FCOUNT

Numrico

DBI_ALIAS

Nome do Alias da rea


corrente similar a ALIAS

DBI_LASTUPDATE

Data da ltima modificao similar a


LUPDATE

da

de trabalho

- 418 Guia de Referncia Rpida


ADVPL Avanado

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

- 419 Guia de Referncia Rpida


ADVPL Avanado

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:


Tabela A : Constantes utilizadas na parametrizao da funo


Constante

Descrio

Retorno

DBOI_BAGNAME

Nome do arquivo de ndice ao qual a


ordem pertence.

Caracter

DBOI_FULLPATH

do arquivo de ndice (com seu diretrio)


ao qual a ordem pertence.

Caracter

DBOI_ORDERCOUNT

Nmero de ordens existentes no arquivo


de ndice especificado.

Caracter

Sintaxe: DBORDERINFO(<nINFOTIPO>)

Parmetros:
nINFOTIPO

Nome do arquivo de ndice.

Retorno:
Caracter

Retorna a informao da Ordem requisitada pelo usurio (pode ser de tipo


numrico se for nmero de ordens no ndice, tipo caracter se for nome do
arquivo de ndice). Caso no exista ordem corrente ou a posio da ordem
especificada est invlida retorna NIL.

Exemplo:
DBORDERINFO(DBOI_BAGNAME) // retorna: Ind
DBORDERINFO(DBOI_FULLPATH) // retorna: C:\AP6\Teste\Ind.cdx

- 420 Guia de Referncia Rpida


ADVPL Avanado

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:
USE Clientes NEW
DBGOTO(100)
DBDELETE()
DBGOTO(105)
DBDELETE()
DBGOTO(110)
DBDELETE()
// Se a excluso for confirmada:
__DBPACK()

- 421 Guia de Referncia Rpida


ADVPL Avanado

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


Tabela A : Constantes utilizadas na parametrizao da funo


Constante

Descrio

Retorno

DBRI_DELETED

Estado de deletado similar a DELETED

Lgico

DBRI_RECSIZE

Tamanho do registro similar a RECSIZE

Numrico

Verifica se o registro foi alterado e ainda


no foi atualizado fisicamente similar a
UPDATED

Lgico

DBRI_UPDATED

- 422 Guia de Referncia Rpida


ADVPL Avanado

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

Retorno:
Nenhum

Exemplo:
USE Clientes NEW
DBSETINDEX("IndNome")
DBREINDEX()

- 423 Guia de Referncia Rpida


ADVPL Avanado

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

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.

- 424 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
DBGOTOP()
DBRLOCK() // Bloqueia o primeiro registro
DBRLOCK(110) // Bloqueia o registro de nmero 110
DBRLOCK(100) // Bloqueia o registro de nmero 100
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:
Nmero do registro a ser desbloqueado.

nREGISTRO


Retorno:
Nenhum

Exemplo:
DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
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.



Sintaxe: DBSETDRIVER([cNOVORDD])
Parmetros:
cNOVORDD

Novo nome do RDD a ser definido como padro.

Retorno:
Caracter

Nome do RDD padro corrente.

- 425 Guia de Referncia Rpida


ADVPL Avanado

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

- 426 Guia de Referncia Rpida


ADVPL Avanado

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

- 427 Guia de Referncia Rpida


ADVPL Avanado

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

- 428 Guia de Referncia Rpida


ADVPL Avanado

DBSEEK() E MSSEEK()
DbSeek(): Permite posicionar o cursor da rea de trabalho ativo no registro com as
informaes especificadas na chave de busca, fornecendo um retorno lgico indicando se o
posicionamento foi efetuado com sucesso, ou seja, se a informao especificada na chave de
busca foi localizada na rea de trabalho.
Sintaxe: DbSeek(cChave, lSoftSeek, lLast)
Parmetros




cChave

lSoftSeek
lLast

Dados do registro que deseja-se localizar, de acordo com a ordem de busca


previamente especificada pelo comando DbSetOrder(), ou seja, de acordo
com o ndice ativo no momento para a rea de trabalho.
Define se o cursor ficar posicionado no prximo registro vlido, em relao
a chave de busca especificada, ou em final de arquivo, caso no seja
encontrada exatamente a informao da chave. Padro  .F.
Define se o cursor ser posicionado no primeiro ou no ltimo registro de um
intervalo com as mesmas informaes especificadas na chave. Padro  .F.

Exemplo 01 Busca exata


DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001, Loja: 02
MsgInfo(Cliente localizado, Consulta por cliente)
Else
MsgAlert(Cliente no encontrado, Consulta por cliente)
Endif

Exemplo 02 Busca aproximada


DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DbSeek(01 + 000001 + 02, .T. ) // Filial: 01, Cdigo: 000001, Loja: 02
// Exibe os dados do cliente localizado, o qual pode no ser o especificado na chave:
MsgInfo(Dados do cliente localizado: +CRLF +;
Filial:
+ A1_FILIAL + CRLF +;
Cdigo: + A1_COD
+ CRLF +;
Loja:
+ A1_LOJA + CRLF +;
Nome:
+ A1_NOME + CRLF, Consulta por cliente)

- 429 Guia de Referncia Rpida


ADVPL Avanado

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

- 430 Guia de Referncia Rpida


ADVPL Avanado

DBSETFILTER()
Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de um bloco
de cdigo ou atravs de uma expresso simples.



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.

- 431 Guia de Referncia Rpida


ADVPL Avanado

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



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

- 432 Guia de Referncia Rpida


ADVPL Avanado

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

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

cDriver

cArquivo

Parmetro opcional que permite que se caso o cAlias especificado j


esteja em uso, ele seja fechado antes da abertura do arquivo da base de
dados.
Driver que permita a aplicao manipular o arquivo de base de dados
especificado. A aplicao ERP possui a varivel __LOCALDRIVER definida
a partir das configuraes do .ini do server da aplicao.
Algumas chaves vlidas: DBFCDX, CTREECDX, DBFCDXAX,
TOPCONN.
Nome do arquivo de base de dados que ser aberto com o alias
especificado.

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

- 433 Guia de Referncia Rpida


ADVPL Avanado

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

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

- 434 Guia de Referncia Rpida


ADVPL Avanado

FOUND()
A funo FOUND() recupera o resultado de sucesso referente a ltima operao de busca
efetuada pelo processamento corrente.


Sintaxe: FOUND()

Parmetros:
Nenhum

Retorno:
Lgico

Indica se a ltima operao de busca realizada pelo processamento corrente


obteve sucesso (.T.) ou no (.F.).

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

- 435 Guia de Referncia Rpida


ADVPL Avanado

INDEXORD()
A funo INDEXORD() verifica a posio do ndice corrente na lista de ndices do respectivo
alias.


Sintaxe: INDEXORD()

Parmetros:
Nenhum

Retorno:
Numrico

Posio do ndice corrente na lista de ndices da tabela. Retorna 0 se no


existe ndice aberto na tabela corrente.

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

- 436 Guia de Referncia Rpida


ADVPL Avanado

MSAPPEND()
A funo MsAppend() adiciona registros de um arquivo para outro, respeitando a estrutura das
tabelas.


Sintaxe: MSAPPEND( [cArqDest], cArqOrig )

Parmetros:
cArqDest
cArqOrig

Se o RDD corrente for DBFCDX os registros sero adicionados na rea


selecionada, caso contrrio o arquivo destino ter que ser informado.
Nome do arquivo origem contendo os registros a serem adicionados.

Retorno:
Lgico

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

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)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
ENDIF

- 437 Guia de Referncia Rpida


ADVPL Avanado

ORDBAGEXT()
A funo ORDBAGEXT utilizada no gerenciamento de indices para os arquivos de dados do
sistema, permitindo avaliar qual a extenso deste ndices atualmente em uso, de acordo com a
RDD ativa.


Sintaxe: ORDBAGEXT()

Parmetros:
Nenhum

Retorno:
cBagExt

Extenso do arquivo dos arquivos de ndices em uso pelo sistema,


determinado pela RDD ativa.

Exemplo:
cArqTRB := CriaTrab(aStruTRB,.T.)
// RDD UTILIZADA: DBFCDXADS
DbUseArea(.T., DBFCDXADS, cArqTRB, "TRBSA1", .F., .F.)
DbSelectArea("TRBSA1")
cArqInd := CriaTrab(Nil,.F.)
IndRegua("TRBSA1",cArqInd,cChaveInd,,"","Selecionando registros ...")
#IFNDEF TOP
DbSetIndex(cArqInd+OrdBagExt())
// RETORNO: .CDX
#ENDIF
DbSetOrder(1)

ORDKEY()
A funo ORDKEY() verifica qual a expresso de chave de determinada ordem. Caso no
sejam especificados os parmetros de identificao da ordem, verificada a ordem corrente.
Para evitar conflito, no caso de haver mais de uma ordem com o mesmo nome, pode-se
passar o parmetro com o nome do ndice ao qual a ordem pertence.
A ordem passada no primeiro parmetro pode ser especificada atravs da sua posio na lista
de ordens ativas (atravs do ORDLISTADD) ou atravs do nome dado ordem. A funo
verifica automaticamente se o parmetro numrico ou caracter.


Sintaxe: ORDKEY([cOrdem | nPosicao] , [cArqIndice])

Parmetros:
cOrdem
nPosicao
cArqIndice

H duas opes para o primeiro parmetro:


cNome: tipo caracter, contm nome do ndice.
nPosicao: tipo numrico, indica ordem do ndice.
Nome do arquivo de ndice.

- 438 Guia de Referncia Rpida


ADVPL Avanado

Retorno:
Caracter

Expresso de chave da ordem ativa ou especificada pelos parmetros.


Cadeia vazia indica que no existe ordem corrente.

Exemplo:
USE Cliente NEW
INDEX ON Nome+Cod TO Ind1 FOR Nome+Cod > 'AZZZZZZZ'
ORDKEY('Ind1')
// Retorna: Nome+Cod

RECLOCK()
Efetua o travamento do registro posicionado na rea de trabalho ativa, permitindo a incluso
ou alterao das informaes do mesmo.



Sintaxe: RecLock(cAlias,lInclui)
Parmetros
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
MsUnLock() // Confirma e finaliza a operao

Exemplo 02 - Alterao
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
ENDIF

A linguagem ADVPL possui variaes da funo RecLock(), as quais so:


 RLOCK()
 DBRLOCK()

- 439 Guia de Referncia Rpida


ADVPL Avanado

A sintaxe e a descrio destas funes esto disponveis no Guia de


Referncia Rpido ao final deste material.

A linguagem ADVPL possui variaes da funo MsUnlock(), as quais so:


 UNLOCK()
 DBUNLOCK()
 DBUNLOCKALL()
A sintaxe e a descrio destas funes esto disponveis no Guia de
Referncia Rpido ao final deste material.

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.

- 440 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
nArea := Select(SA1)
ALERT(Referncia do alias SA1: +STRZERO(nArea,3)) //  10 (proposto)

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

cCondicao

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

- 441 Guia de Referncia Rpida


ADVPL Avanado

SOFTLOCK()
Permite a reserva do registro posicionado na rea de trabalho ativa de forma que outras
operaes, com exceo da atual, no possam atualizar este registro. Difere da funo
RecLock() pois no gera uma obrigao de atualizao, e pode ser sucedido por ele.
Na aplicao ERP Protheus, o SoftLock() utilizado nos browses, antes da confirmao da
operao de alterao e excluso, pois neste momento a mesma ainda no foi efetivada, mas
outras conexes no podem acessar aquele registro pois o mesmo est em manuteno, o que
implementa da integridade da informao.


Sintaxe: SoftLock(cAlias)

Parmetros
cAlias

Alias de referncia da rea de trabalho ativa, para o qual o registro


posicionado ser travado.

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

- 442 Guia de Referncia Rpida


ADVPL Avanado

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.
ZAP
O comando ZAP remove fisicamente todos os registro da tabela corrente. necessrio que o
alias em questo seja aberto em modo exclusivo para esta operao ser realizada.



Sintaxe: ZAP
Parmetros:
Nenhum

Retorno:
Nenhum

Exemplo:
cTabela := RetSqlName("SA4")
cAlias := "TMP"
USE (cTabela) ALIAS (cAlias) EXCLUSIVE NEW VIA "TOPCONN"
IfNetErr()
MsgStop("Nao foi possivel abrir "+cTabela+" em modo EXCLUSIVO.")
Else
ZAP
USE
MsgStop("Registros da tabela "+cTabela+" eliminados com sucesso.")
Endif

- 443 Guia de Referncia Rpida


ADVPL Avanado

Controle de numerao seqencial


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

- 444 Guia de Referncia Rpida


ADVPL Avanado

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


- 445 Guia de Referncia Rpida
ADVPL Avanado

EXISTCPO()
Retorna .T. ou .F. se o contedo especificado no existe no alias especificado. Caso no exista
ser exibido um help de sistema com um aviso informando da ocorrncia.
Funo utilizada normalmente para verificar se a informao digitada em um campo, a qual
depende de outra tabela, realmente existe nesta outra tabela, como por exemplo o cdigo de
um cliente em um pedido de venda.



Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)


Parmetros

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

.
- 446 Guia de Referncia Rpida
ADVPL Avanado

PERTENCE()
Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida como
parmetro da funo. Normalmente utilizada em campos com a opo de combo, pois caso
contrrio seria utilizada a funo ExistCpo().



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

- 447 Guia de Referncia Rpida


ADVPL Avanado

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

cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de


sistema.

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

Nome do parmetro do sistema no SX6, sem a especificao da filial de


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.

- 448 Guia de Referncia Rpida


ADVPL Avanado

PUTMV()
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.



Sintaxe: PUTMV(cParametro, cConteudo)


Parmetros
cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de


sistema.

cConteudo

Contedo que ser atribudo ao parmetro no SX6.

SUPERGETMV()
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.
Difere do GetMv() pois os parmetros consultados so adicionados em uma rea de memria,
que permite que em uma nova consulta no seja necessrio acessar e pesquisar o parmetro
na base de dados.



Sintaxe: SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)


Parmetros

cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de


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.

- 449 Guia de Referncia Rpida


ADVPL Avanado

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 | ARNALDO RAYMUNDO JR. | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo AXCADASTRO()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
USER FUNCTION XAVALIMP()
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL
LOCAL

cTitulo
cDesc1
cDesc2
cDesc3
cTamanho
cLimite
cNatureza
aReturn
cNomeProg
cPerg
nLastKey
cString

:= PADC(AVALIMP,74)
:= PADC(Demonstrao do uso da funo AVALIMP(),74)
:=
:= PADC(CURSO DE ADVPL,74)
:= G
:= 220
:=
:= {Especial, 1,Administrao, 1, 2, 2,,1}
:= RAVALIMP
:= PADR(RAVALIMP,10) // Compatibilizao com MP10
:= 0
:=SF2"

Pergunte(cPerg,.F.) // Pergunta no SX1


wnrel:= SetPrint(cString,wnrel,cPerg,cTitulo,cDesc1,cDesc2,cDesc3,.T.)
SetDefault(aReturn,cString)

- 450 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
If nLastKey == 27
Return
Endif
RptStatus({|| RunReport(cString)},cTitulo)
Return
/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor | -------------------- | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela XAVALIMP()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
Static Function RunReport(cString)
SetPrc(0,0)
//+-------------------------------------------------------------------------+
//| Chamada da funo AVALIMP()
|
//+-------------------------------------------------------------------------+
@ 00,00 PSAY AvalImp(220)
dbSelectArea(cString)
dbSeek(xFilial()+mv_par01+mv_par03,.T.)
...
Return

CABEC()
A funo CABEC() determina as configuraes de impresso do relatrio e imprime o cabealho
do mesmo.

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


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
lPerg

Texto especfico para o cabealho, substituindo a estrutura padro do


sistema.
Permite a supresso da impresso das perguntas do relatrio, mesmo que
o parmetro MV_IMPSX1 esteja definido como S

- 451 Guia de Referncia Rpida


ADVPL Avanado

Parmetros (continuao):

Redefine o bitmap que ser impresso no relatrio, no necessitando que


ele esteja no formato padro da Microsiga:
"LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"

cLogo

Retorno:

Nenhum

Exemplo:
#INCLUDE "protheus.ch"
/*/
+----------------------------------------------------------------------------| Funo
| MPTR001
| Autor | ARNALDO RAYMUNDO JR. | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao das funes de impresso CABEC()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
User Function MPTR001()
Local
Local
Local
Local
Local

cDesc1
cDesc2
cDesc3
cTitulo
lImprime

:=
:=
:=
:=
:=

"Este programa tem como objetivo imprimir relatorio "


"de acordo com os parametros informados pelo usuario."
"Listagem de clientes"
"Listagem de clientes"
.T.

// Parametros da SetPrint()
Local cString
:= "SA1"
Local cPerg
:= ""
Local lDic
:= .T. // Habilita a visalizacao do dicionario
Local aOrd
:= RetSixOrd(cString)
Local lCompres
:= .T. // .F. - Normal / .T. - Comprimido
Local lFilter
:= .T. // Habilita o filtro para o usuario
Local cNomeProg
:= "MPTR002"
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
Private m_pag
Private wnrel

:= 0
:= 01
:= "MPTR002"

dbSelectArea("SA1")
dbSetOrder(1)

- 452 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
//
// Monta a interface padrao com o usuario...

//
wnrel :=
SetPrint(cString,cNomeProg,cPerg,@cTitulo,cDesc1,cDesc2,cDesc3,lDic,aOrd,lCompre
s,cTamanho,,lFilter)
If nLastKey == 27
Return
Endif
SetDefault(aReturn,cString,,,cTamanho,aReturn[4]) // nFormato: 1- Retrato, 2Paisagem
If nLastKey == 27
Return
Endif
nTipo := IIF(aReturn[4]==1,15,18)
//
// Processamento. RPTSTATUS monta janela com a regua de processamento.
//
RptStatus({||
RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)},cTitulo)
Return
/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor | -------------------- | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)
Local
Local
Local
Local

nLin
cCabec1
cCabec2
cArqInd

cCabec1
cCabec1
cCabec1
cCabec2

:=
+=
+=
:=

:= 80
:= ""
:= ""

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

dbSelectArea("TRBSA1")
dbGoTop()
SetRegua(RecCount())

- 453 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
While !EOF()
If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
Exit
Endif
If nLin > 55 // Salto de Pgina. Neste caso o formulario tem 55 linhas...
Cabec(cTitulo,cCabec1,cCabec2,cNomeProg,cTamanho,nTipo)
nLin := 9
Endif
...

IMPCADAST()
A funo IMPCADAST() cria uma interface simples que permite a impresso dos cadastros do
sistema com parametrizao DE/ATE.


Sintaxe: IMPCADAST(cCab1, cCab2, cCab3, cNomeProg, cTam, nLimite, cAlias)

Parmetros:
cCab1

Primeira linha do cabealho

cCab2

Segunda linha do cabealho

cCab3

Terceira linha do cabealho

cNomeProg

Nome do programa

cTam

Tamanho do relatrio nos formatos P, M e G.

nLimite

Nmero de colunas do relatrio, seguindo o formato especificado no


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

cAlias


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

- 454 Guia de Referncia Rpida


ADVPL Avanado

Retorno:

Nenhum
Exemplo:

/*/
+----------------------------------------------------------------------------| Funo
| RUNREPORT
| Autor | -------------------- | Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001()
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------| Observao| Continuao do exemplo da funo CABEC()
|
|+---------------------------------------------------------------------------/*/
Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)
Local
Local
Local
Local

nLin
cCabec1
cCabec2
cArqInd

cCabec1
cCabec1
cCabec1
cCabec2

:=
+=
+=
:=

:= 80
:= ""
:= ""

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

dbSelectArea("TRBSA1")
dbGoTop()
SetRegua(RecCount())
While !EOF()
If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
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++

- 455 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
// Segunda linha de detalhe
@nLin,000 PSAY TRBSA1->A1_EST
@nLin,008 PSAY TRBSA1->A1_MUN
@nLin,025 PSAY TRBSA1->A1_END
nLin++
//Linha separadora de detalhes
@nLin,000 PSAY Replicate("-",nLimite)
nLin++
dbSkip() // Avanca o ponteiro do registro no arquivo
EndDo
SET DEVICE TO SCREEN
If aReturn[5]==1
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif
MS_FLUSH()
RETURN
OURSPOOL()
A funo OURSPOOL() executa o gerenciador de impresso da aplicao Protheus, permitindo
a visualizao do arquivo de impresso gerado pelo relatrio no formato PostScrip com
extenso ##R.


Sintaxe: OURSPOOL(cArquivo)

Parmetros:
cArquivo

Nome do relatrio a ser visualizado.

Retorno:


.

Exemplo:
If aReturn[5]==1 // Indica impresso em disco.
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif

- 456 Guia de Referncia Rpida


ADVPL Avanado

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 | MICROSIGA
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo RODA() em conjunto com a CABEC.|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
#include "protheus.ch"
User Function TestImpr()
Local wnrel
Local cString := "SA1"
Local titulo
:= "Teste Impresso de Relatorios"
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

- 457 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
/*/
+----------------------------------------------------------------------------| Funo
| TESTREL
| Autor | MICROSIGA
| Data | 01.01.2007 |
+----------------------------------------------------------------------------| Descrio | Funo interna de impresso da TestImpr().
|
|+---------------------------------------------------------------------------| Uso
| Curso ADVPL
|
|+---------------------------------------------------------------------------/*/
User Function TestRel(lEnd,WnRel,cString,Tamanho,NomeProg)
LOCAL
LOCAL
Local
Local

cabec1,cabec2
cRodaTxt := oemtoansi("Rodap")
nCntImpr
nTipo

nCntImpr := 0
li := 80
m_pag := 1
nTipo := 15
titulo:= oemtoansi("Lista de Clientes")
cabec1:= oemtoansi("COD LOJA NOME"+Space(27)+ "NOME FANTASIA")
cabec2:=""
dbSelectArea("SA1")
dbGoTop()
SetRegua(LastRec())
While !Eof()
IncRegua()
If Li > 60
cabec(titulo,cabec1,cabec2,nomeprog,tamanho,15)
@ Li,0 PSAY __PrtThinLine()
Endif
nCntImpr++
Li++
@ Li,01 PSAY A1_COD
@ Li,05 PSAY A1_LOJA
@ Li,10 PSAY A1_NOME
@ Li,51 PSAY A1_NREDUZ
If Li > 60
Li:=66
Endif
dbSkip()
EndDO
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
- 458 Guia de Referncia Rpida
ADVPL Avanado

SETDEFAULT()
A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes
configuradas no array aReturn, obtidas atravs da funo SetPrint().


Sintaxe:

Parmetros:

aReturn

Configuraes de impresso.

cAlias

Alias do arquivo a ser impresso.

uParm3

Parmetro reservado.

uParm4

Parmetro reservado.

cSize

Tamanho da pgina "P","M" ou "G"

nFormat

Formato da pgina, 1 retrato e 2 paisagem.

Retorno:
Nenhum

SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] ,


[cSize] , [ nFormat ] )

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

- 459 Guia de Referncia Rpida


ADVPL Avanado

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.

cTitle

Ttulo do relatrio.

- 460 Guia de Referncia Rpida


ADVPL Avanado

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
lCrystal

cNameDrv

Nome de um driver de impresso.

uParm16

Parmetro reservado.

lServer

Se verdadeiro (.T.) fora impresso no servidor.

cPortPrint

Define uma porta de impresso padro.

Retorno:
Caracter

Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro


assumido ser .T.
Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro
assumido ser .F.

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

- 461 Guia de Referncia Rpida


ADVPL Avanado

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

Indica se todos os arquivos foram fechados com sucesso.

- 462 Guia de Referncia Rpida


ADVPL Avanado

CHKFILE()
A funo CHKFILE() retorna verdadeiro (.T.) se o arquivo j estiver aberto ou se o Alias no for
informado. Sempre que desejar mudar o modo de acesso do arquivo (de compartilhado para
exclusivo ou vice-versa), feche-o antes de cham-la.


Sintaxe: ChkFile(cAlias,lExcl,cNewAlias)

Parmetros:
cAlias

Alias do arquivo a ser re-aberto.

lExcl

Se for informado verdadeiro (.T.), o arquivo ser aberto em modo


exclusivo, caso contrrio, o arquivo ser aberto em modo compartilhado.
Se este parmetro no for informado, ser assumido falso (.F.).
Novo Alias para re-abertura do arquivo.

cNewAlias


Retorno:
Lgico

Indica se o arquivo foi re-aberto com sucesso.

Exemplo:
dbSelectArea(SA1)
dbCloseArea()
lOk := .T.
While .T.
IF !ChkFile(SA1,.T.)
nResp := Alert(Outro usurio usando! Tenta de novo?,{Sim,Nao})
If nResp == 2
lOk := .F.
Exit
Endif
Endif
EndDo
If lOk
// Faz o processamento com o arquivo...
Endif
// Finaliza
If Select(SA1)
dbCloseArea()
Endif
ChkFile(SA1,.F.)
Return

- 463 Guia de Referncia Rpida


ADVPL Avanado

CONOUT()
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:
String contendo a mensagem que dever ser exibida no console do
Protheus.

cMensagem

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

- 464 Guia de Referncia Rpida


ADVPL Avanado

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.
Ao utilizar esta funo, todas as alteraes realizadas no intervalo delimitado pela transao
so desfeitas, restaurando a situao da base de dados ao ponto imediatamente anterior ao
incio do processamento.

O uso da funo DISARMTRANSACTION() no finaliza a conexo ou o


processamento corrente.
Caso seja necessrio alm de desfazer as alteraes,
processamento, dever ser utilizada a funo USEREXCEPTION().

Sintaxe: DISARMTRANSACTION()

Parmetros:
Nenhum

Retorno:

Nenhum

Exemplo:
lMsErroAuto := .F.
MSExecAuto({|x,y| MATA240(x,y)}, aCampos, 3)
If lMsErroAuto
aAutoErro := GETAUTOGRLOG()
DisarmTransaction()
MostraErro()
EndIf

- 465 Guia de Referncia Rpida


ADVPL Avanado

finalizar

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.

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

- 466 Guia de Referncia Rpida


ADVPL Avanado

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

cNota := PARAMIXB[1]
cSerie:= PARAMIXB[1]
cFornece:= PARAMIXB[1]
cLoja:= PARAMIXB[1]

RETURN .T.

ERRORBLOCK()
A funo ERRORBLOCK() efetua o tratamento de erros e define a atuao de um handler de
erros sempre que ocorrer um erro em tempo de execuao. O manipulador de erros
especificado como um bloco de cdigo da seguinte forma:
 { |<objError>| <lista de expressoes>, ... }, onde:
<objError> um error object que contm informaoes sobre o erro.Dentro do bloco de cdigo,
podem ser enviadas mensagens ao error object para obter informaoes sobre o erro. Se o
bloco de tratamento de erros retornar verdadeiro (.T.), a operaao que falhou repetida, e se
retornar falso (.F.), o processamento recomea.
Se nao foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer um erro
em tempo de execuao, o bloco de tratamento ao de erros padrao avaliado. Este
manipulador de erros exibe uma mensagem descritiva na tela, ajusta a funao ERRORLEVEL()
para 1, e depois sai do programa (QUIT).
Como ERRORBLOCK() retorna o bloco de tratamento ao de erros corrente, possvel
especificar um bloco de tratamento de erros para uma operaao gravando-se o bloco de
manipulaao de erros corrente e depois recuperando-o aps o final da operaao. Alm disso,
- 467 Guia de Referncia Rpida
ADVPL Avanado

uma importante consequncia do fato de os blocos de tratamento de erros serem especificados


como blocos de cdigo, que eles podem ser passados pararotinas e funoes definidas por
usurio e depois retornadas como valores.



Sintaxe: ERRORBLOCK ( < bErrorHandler > )


Parmetros:
bErrorHandler

O bloco de cdigo a ser executado toda vez que


ocorrer um erro em tempo de execuao.
Quando avaliado, o <bErrorHandler> passado na forma de um objeto
erro como um argumento pelo sistema.

Retorno:
Code-block

Retorna o bloco de cdigo corrente que tratar o erro. Caso nao tenha sido
enviado nenhum bloco de tratamento de erro desde que o programa foi
invocado, ERRORBLOCK() retorna o bloco de tratamento de erro padrao.

Exemplo:
Function CA010Form()
LOCAL xResult
LOCAL cForm:= Upper(&(ReadVar()))
LOCAL bBlock:= ErrorBlock( { |e| ChecErro(e) } )
LOCAL cOutMod
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

- 468 Guia de Referncia Rpida


ADVPL Avanado

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

- 469 Guia de Referncia Rpida


ADVPL Avanado

FUNDESC()
A funo FunDesc() retornar a descrio de uma opo selecionada no menu da aplicao.


Sintaxe: FUNDESC()

Parmetros:
Nenhum

Retorno:
Caracter

Descrio da opo selecionada no menu da aplicao.

FUNNAME()
A funo FunName() retornar o nome de uma funo executada a partir de um menu da
aplicao.


Sintaxe: FUNNAME()

Parmetros:
Nenhum

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

- 470 Guia de Referncia Rpida


ADVPL Avanado

GETCOUNTRYLIST()
A funo GETCOUNTRYLIST() retorna um array de duas dimenses contendo informaes dos
pases localizados.


Sintaxe: GetCountryList()

Parmetros:
Nenhum

Retorno:
Array
Array de duas dimenses, sendo uma linha para cada pas localizado,
contendo em cada posio a sigla dos pases, o nome do pas e a
identificao do pas com dois dgitos.

Exemplo:
Local aArray := GetCountryList()
Local cSigla := GetMv( MV_PAISLOC )
Local nPos
nPos := Ascan( aArray, {|d| d[1] == Upper(cSigla) } )
If nPos > 0
APMsgInfo( Pas de localizao + aArray[nPos,2] )
EndIf

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

- 471 Guia de Referncia Rpida


ADVPL Avanado

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.

A funo REGTOMEMORY necessita que o ALIAS exista no SX3 para a


operao de incluso, mesmo que o parmetro lDic seja definido como falso.

Sintaxe: REGTOMEMORY(cAlias, lInclui, lDic, lInitPad)

Parmetros:
cAlias
lInclui
lDic
lInitPad

Alias do arquivo que ser utilizado como referncia para inicializao das
variveis de memria.
Identifica se as variveis devero ser inicializadas com contedos padres,
ou contendo as informaes do registro posicionado do alias especificado.
Define se ir utilizar o dicionrio de dados como base para inicializao das
variveis ou se ir utilizar o comando CRIAVAR().
Define se ir executar o inicializador padro do campo, contido no dicionrio
de dados. Parmetro utilizado pela CRIAVAR().

Retorno:
Nenhum

- 472 Guia de Referncia Rpida


ADVPL Avanado

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




Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo


uso da funo GetArea().

aArea
Exemplo:

// ALIAS ATIVO ANTES DA EXECUO DA ROTINA  SN3


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:
- 473 Guia de Referncia Rpida
ADVPL Avanado

Nenhum

- 474 Guia de Referncia Rpida


ADVPL Avanado

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:

cPerg

Grupo de perguntas do SX1 (X1_GRUPO)

aPergs

Array contendo a estrutura dos campos que sero gravados no SX1.

Retorno:
Nenhum

Estrutura Item do array aPerg:


Posio
01
02
03
04

Campo
X1_PERGUNT
X1_PERSPA
X1_PERENG
X1_VARIAVL

Tipo
Caractere
Caractere
Caractere
Caractere

05
06
07

X1_TIPO
X1_TAMANHO
X1_DECIMAL

Caractere
Numrico
Numrico

08

X1_PRESEL

Numrico

09

X1_GSC

Caractere

10
11

X1_VALID
X1_VAR01

Caractere
Caractere

12

X1_DEF01

Caractere

13
14
15

X1_DEFSPA1
X1_DEFENG1
X1_CNT01

Caractere
Caractere
Caractere

16
17

X1_VAR02
X1_DEF02

Caractere
Caractere

18
19
20
21
22

X1_DEFSPA2
X1_DEFENG2
X1_CNT02
X1_VAR03
X1_DEF03

Caractere
Caractere
Caractere
Caractere
Caractere

Descrio
Descrio da pergunta em portugus
Descrio da pergunta em espanhol
Descrio da pergunta em ingls
Nome da varivel de controle auxiliar
(mv_ch)
Tipo do parmetro
Tamanho do contedo do parmetro
Nmero de decimais para contedos
numricos
Define qual opo do combo a padro para
o parmetro.
Define se a pergunta ser do tipo G Get ou
C Choice (combo)
Expresso de validao do parmetro
Nome da varivel MV_PAR+Ordem do
parmetro
Descrio da opo 1 do combo em
portugus
Descrio da opo 1 do combo em espanhol
Descrio da opo 1 do combo em ingls
Contedo padro ou ultimo contedo
definido como respostas para a pergunta.
No informado
Descrio da opo X do combo em
portugus
Descrio da opo X do combo em espanhol
Descrio da opo X do combo em ingls
No informado
No informado
Descrio da opo X do combo em
portugus

- 475 Guia de Referncia Rpida


ADVPL Avanado

Estrutura Item do array aPerg (continuao):


23
24
25
26
27

X1_DEFSPA3
X1_DEFENG3
X1_CNT03
X1_VAR04
X1_DEF04

Caractere
Caractere
Caractere
Caractere
Caractere

28
29
30
31
32

X1_DEFSPA4
X1_DEFENG4
X1_CNT04
X1_VAR05
X1_DEF05

Caractere
Caractere
Caractere
Caractere
Caractere

33
34
35
36

X1_DEFSPA5
X1_DEFENG5
X1_CNT05
X1_F3

Caractere
Caractere
Caractere
Caractere

37

X1_GRPSXG

Caractere

38

X1_PYME

Caractere

39
40

X1_HELP
X1_PICTURE

Caractere
Caractere

41

aHelpPor

Array

42

aHelpEng

Array

43

aHelpSpa

Array

Descrio da opo X do combo em espanhol


Descrio da opo X do combo em ingls
No informado
No informado
Descrio da opo X do combo em
portugus
Descrio da opo X do combo em espanhol
Descrio da opo X do combo em ingls
No informado
No informado
Descrio da opo X do combo em
portugus
Descrio da opo X do combo em espanhol
Descrio da opo X do combo em ingls
No informado
Cdigo da consulta F3 vinculada ao
parmetro
Cdigo do grupo de campos SXG para
atualizao automtica, quando o grupo for
alterado.
Se a pergunta estar disponvel no ambiente
Pyme
Contedo do campo X1_HELP
Picture de formatao do contedo do
campo.
Vetor simples contendo as linhas de help em
portugus para o parmetro. Trabalhar com
linhas de at 40 caracteres.
Vetor simples contendo as linhas de help em
ingls para o parmetro. Trabalhar com
linhas de at 40 caracteres.
Vetor simples contendo as linhas de help em
espanhol para o parmetro. Trabalhar com
linhas de at 40 caracteres.

- 476 Guia de Referncia Rpida


ADVPL Avanado

ALLUSERS()
A funo ALLUSERS() retorna um array multidimensional contendo as informaes dos
usurios do sistema.


Sintaxe: ALLUSERS()

Parmetros:
.

Nenhum


Retorno:
Array multidimensional contendo as informaes dos usurios do sistema,
aonde para cada usurio sero demonstradas as seguintes informaes:

Array

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.

ID

Nome

15

Senha

Nome Completo

30

Vetor com n ltimas senhas

--

Data de validade

Quantas vezes para expirar

Autorizado a alterar a senha

Alterar a senha no prximo logon

10

Vetor com os grupos

--

11

ID do superior

12

Departamento

30

13

Cargo

30

14

E-Mail

130

15

Nmero de acessos simultneos

16

Data da ltima alterao

17

Usurio bloqueado

18

Nmero de dgitos para o ano

19

Listner de ligaes

20

Ramal

- 477 Guia de Referncia Rpida


ADVPL Avanado

Array de informaes dos usurios: Configuraes de impresso


Elemento

Descrio

Tipo

Qtd.

Vetor com horrios de acesso

--

Idioma

Diretrio

100

Impressora

--

Acessos

512

Vetor com empresas

--

Ponto de entrada

10

Tipo de impresso

Formato

10

Ambiente

11

Prioridade p/ config. do grupo

12

Opo de impresso

50

13

Acesso a outros dir de


impresso

Array de informaes dos usurios: Configuraes de acesso aos mdulos


Elemento

Descrio

Tipo

Mdulo+nvel+menu

3
1

- 478 Guia de Referncia Rpida


ADVPL Avanado

Qtd.

ALLGROUPS()
A funo ALLGROUPS() retorna um array multidimensional contendo as informaes dos
grupos de usurios do sistema.


Sintaxe: ALLGROUPS()

Parmetros:
.

Nenhum


Retorno:
Array multidimensional contendo as informaes dos grupos de usurios do
sistema, aonde para cada grupo sero demonstradas as seguintes
informaes:

Array

aArray[x][1]  Configuraes gerais de acesso


aArray[x][2]  Configuraes de acesso aos mdulos

Array de informaes dos grupos: Configuraes gerais de acesso


Elemento

Descrio

Tipo

Qtd.

ID

Nome

20

Vetor com horrios de acesso

Data de validade

Quantas vezes para expirar

Autorizado a alterar a senha

Idioma

Diretrio

100

Impressora

10

Acessos

11

Vetor com empresas

12

Data da ltima alterao

13

Tipo de impresso

14

Formato

15

Ambiente

16

Opo de impresso

17

Acesso a outros Dir de impresso

8
4

512

Array de informaes dos grupos: Configuraes de acesso aos mdulos


Elemento

Descrio

Tipo

Modulo+nvel+menu

2
1

- 479 Guia de Referncia Rpida


ADVPL Avanado

Qtd.

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
lOnlyView


Parmetro Reservado.
Indica se ser somente para visualizao.

Retorno:
Nenhum

- 480 Guia de Referncia Rpida


ADVPL Avanado

DATAVALIDA()
A funo DATAVALIDA() retorna a primeira data vlida a partir de uma data especificada como
referncia, considerando inclusive a data informada para anlise.


Sintaxe: DATAVALIDA(dData)

Parmetros:
dData

Data a partir da qual ser avaliada a prxima data vlida, considerando-a


inclusive como uma possibilidade.

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

- 481 Guia de Referncia Rpida


ADVPL Avanado

EXTENSO()
A funo EXTENSO() retorna uma string referente a descrio por extenso de um valor
numrico, sendo comumente utilizada para impresso de cheques, valor de duplicatas, etc.


Sintaxe: Extenso(nValor, lQtd, nMoeda)

Parmetros:

nValor

Valor para gerao do extenso.

lQtd

Indica se o valor representa uma quantidade (.T.) ou dinheiro (.F.)

nMoeda

Para qual moeda do sistema deve ser o extenso.

Retorno:
String

Descrio do valor por extenso.

FORMULA()
Interpreta uma frmula cadastrada. Esta funo interpreta uma frmula, previa-mente
cadastrada no Arquivo SM4 atravs do Mdulo Configurador, e retorna o resultado com tipo de
dado de acordo com a prpria frmula.


Sintaxe: Formula(cFormula)

Parmetros:
cFormula

Cdigo da frmula a ser avaliada e cadastrada no SM4 Cadastro de


Frmulas.

Retorno:
Indefinido

Resultado da interpretao da frmula cadastrada no SM4.

GETADVFVAL()
A funo GETADVFVAL() executa uma pesquisa em um arquivo pela chave de busca e na
ordem especificadas, possibilitando o retorno de um ou mais campos.


Sintaxe: GetAdvFVal(cAlias,uCpo,uChave,nOrder,uDef)

Parmetros:
cAlias

Alias do arquivo

uCpo
uChave

Nome de um campo ou array contendo os nomes dos campos


desejados
Chave para a pesquisa

nOrder

Ordem do ndice para a pesquisa

uDef

Valor ou array default para ser retornado caso a chave no seja encontrada

- 482 Guia de Referncia Rpida


ADVPL Avanado

Retorno:
Retorna o contedo de um campo ou array com o contedo de vrios
campos

Indefinido

A funo GETADVFVAL() difere da funo POSICIONE() apenas por permitir o


retorno de vrios campos em uma nica consulta.
As duas funes devem ser protegidas por GETAREA() / RESTAREA()
dependendo da aplicao.

HELP()
Esta funo exibe a ajuda especificada para o campo e permite sua edio. Se for
um help novo, escreve-se o texto em tempo de execuo.


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

- 483 Guia de Referncia Rpida


ADVPL Avanado

MESEXTENSO()
A funo MESEXTENSO() retorna o nome de um ms por extenso.


Sintaxe: MESEXTENSO(nMes)

Parmetros:
nMes

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

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

Retorno:
String

Nome do ms indicado por extenso.

OBRIGATORIO()
A funo OBRIGATORIO() avalia se todos os campos obrigatrios de uma Enchoice() foram
digitados.


Sintaxe: OBRIGATORIO(aGets, aTela, aTitulos)

Parmetros:
aGets
aTela
aTitulos

Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no


fonte.
Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no
fonte.
Array contendo os ttulos dos campos exibidos na Enchoice().

Retorno:
Lgico

Indica se todos os campos obrigatrios foram preenchidos.

- 484 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
#INCLUDE "protheus.ch"
/*/
+----------------------------------------------------------------------------| Programa | ATFA010A | Autor | ARNALDO R. JUNIOR
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Cadastro de dados complementares do bem Ativo Fixo
|
+---------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
User Function ATFA010A()
Private cCadastro := "Atualizacao de dados do bem"
Private aRotina := { {"Pesquisar" ,"AxPesqui"
{"Visualizar"
,"AxVisual"
{"Atualizar"
,"U_A010AATU"

,0,1} ,;
,0,2} ,;
,0,4}}

Private cDelFunc := ".T."


Private cString := "SN1"
dbSelectArea("SN1")
dbSetOrder(1)
dbSelectArea(cString)
mBrowse( 6,1,22,75,cString)
Return
/*/
+----------------------------------------------------------------------------| Programa | A010AATU | Autor | ARNALDO R. JUNIOR
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Atualizao de dados do bem Ativo Fixo
|
+----------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
User Function A010AATU(cAlias,nReg,nOpc)
Local aCpoEnch
Local aAlter

:= {}
:= {}

Local
Local
Local
Local
Local
Local
Local
Local
Local
Local
Local

:=
:=
:=
:=
:=
:=
:=
:=
:=
:=
:=

aButtons
cAliasE
aAlterEnch
aPos
nModelo
lF3
lMemoria
lColumn
caTela
lNoFolder
lProperty

{}
cAlias
{}
{015,000,400,600
.F.
.T.
.F.
""
.F.
.F.

- 485 Guia de Referncia Rpida


ADVPL Avanado

Exemplo (continuao):
Private
Private
Private
Private
Private

oDlg
oGetD
oEnch
aTELA[0][0]
aGETS[0]

// Variveis que sero atualizadas pela Enchoice()


// e utilizadas pela funo OBRIGATORIO()

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
//+--------------------------------------------------------------------------+
//|Campos da enchoice
|
//+--------------------------------------------------------------------------+
While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "A1_FILIAL") .And. cNivel >= SX3->X3_NIVEL .And.
X3Uso(SX3->X3_USADO)
AAdd(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
//+--------------------------------------------------------------------------+
//|Campos alterveis da enchoice
|
//+--------------------------------------------------------------------------+
AADD(aAlterEnch,"N1_TIPOADT")
// Controle de Adiantamentos
AADD(aAlterEnch,"N1_DESCRIC")
// Descrio
AADD(aAlterEnch,"N1_CHAPA")
// Numero da plaqueta
AADD(aAlterEnch,"N1_FORNEC") // Fornecedor
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
- 486 Guia de Referncia Rpida
ADVPL Avanado

Exemplo (continuao):
/*/
+----------------------------------------------------------------------------| Programa | A010AGRV | Autor | ARNALDO R. JUNIOR
| Data |
|
+----------------------------------------------------------------------------| Desc.
| Validao da enchoice e gravao dos dados do bem
|
+----------------------------------------------------------------------------| Uso
| Curso de ADVPL
|
+----------------------------------------------------------------------------/*/
Static Function A010AGRV(aCpos,aAlter,nOpc)
Local aArea
Local nX

:= GetArea()
:= 0

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


Return .F.
ENDIF
// Atualizacao dos campos passiveis de alteracao no SN1
RecLock("SN1",.F.)
For nX := 1 to Len(aAlter)
SN1->&(aAlter[nX]) := M->&(aAlter[nX])
Next nX
MsUnLock()
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

- 487 Guia de Referncia Rpida


ADVPL Avanado

PERGUNTE()
A funo PERGUNTE() inicializa as variveis de pergunta (mv_par01,...) baseada na pergunta
cadastrado no Dicionrio de Dados (SX1). Se o parmetro lAsk no for especificado ou for
verdadeiro ser exibida a tela para edio da pergunta e se o usurio cofirmar as variveis
sero atualizadas e a pergunta no SX1 tambm ser atualizada.


Sintaxe: Pergunte( cPergunta , [lAsk] , [cTitle] )

Parmetros:

cPergunta

Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada.

|Ask

Indica se exibir a tela para edio.

cTitle

Ttulo do dilogo.

Retorno:
Lgico

Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou


cancelada (.F.)

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


Sintaxe: PesqPict(cAlias,cCampo,nTam)

Parmetros:

cAlias

Alias do arquivo

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.

- 488 Guia de Referncia Rpida


ADVPL Avanado

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:
Picture ideal para o espao definido por nEdio, sem a separao dos
milhares por vrgula.

String

POSICIONE()
A funo POSICIONE() permite o retorno do contedo de um campo de um registro de uma
tabela especificado atravs de uma chave de busca.


Sintaxe: Posicione(cAlias, nOrdem, cChave, cCampo)

Parmetros:

cAlias

Alias do arquivo

nOrdem

Ordem utilizada

cChave

Chave pesquisa

cCampo

Campo a ser retornado

Retorno:
Indefinido

Contedo do campo solicitado.

A utilizao da funo POSICIONE() deve ser protegida com GETAREA() /


RESTAREA() dependendo da aplicao.

- 489 Guia de Referncia Rpida


ADVPL Avanado

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

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

- 490 Guia de Referncia Rpida


ADVPL Avanado

RETINDEX()
A funo RETINDEX()
Dados (SIX).

restaura os ndices padres de um alias definidos no Dicionrio de

Sintaxe: RETINDEX(cAlias)

Parmetros:
Alias de um arquivo do sistema existente no Dicionrio de Dados.

cAlias


Retorno:
Indica quantos ndices padres o alias especificado possui no Dicionrio de
Dados.

Numrico

A funo RETINDEX() quando utilizada em ambientes TOPCONNECT retorna -1

SIXDESCRICAO()
A funo SIXDESCRICAO() retorna a descrio da chave de ndice, de acordo com o registro
posicionado no SIX e idioma corrente.


Sintaxe: SIXDESCRICAO()

Parmetros:
Nenhum

Retorno:
String

Descrio do indice posicionado no SIX de acordo com o idioma corrente.

Exemplo:
User Function <nome-da-funo>( cChave, cOrdem )
Local cSixDesc :=
dbSelectArea(SIX)
dbSetOrder(1)
If dbSeek(cChave+cOrdem)
cSixDescr := SixDescricao()
EndIf
Return

- 491 Guia de Referncia Rpida


ADVPL Avanado

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.

- 492 Guia de Referncia Rpida


ADVPL Avanado

TM()
A funo TM() retorna a picture de impresso para valores numricos dependendo do espao
disponvel.


Sintaxe: TM(nValor, nEdio, nDec)

Parmetros:

nValor

Valor a ser avaliado.

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.

- 493 Guia de Referncia Rpida


ADVPL Avanado

X1DEF01()
A funo X1DEF01() retorna o contedo da primeira definio da pergunta posicionada no SX1
(caso seja combo) no idioma corrente.


Sintaxe: X1DEF01()

Parmetros:
Nenhum

Retorno:

String

Contedo da primeira definio da pergunta no idioma corrente.

Exemplo:
User Function <nome-da-funo>( cGrupo, cPerg )
Local cDef01
Local cDef02
Local cDef03
Local cDef04
Local cDef05
dbSelectArea(SX1)
dbSetOrder(1)
If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDef01 := X1Def01()
cDef02 := X1Def02()
cDef03 := X1Def03()
cDef04 := X1Def04()
cDef05 := X1Def05()
EndIf
Return

- 494 Guia de Referncia Rpida


ADVPL Avanado

X1PERGUNT()
A funo X1PERGUNT() retorna a descrio da pergunta posicionada no Dicionrio de Dados
(SX1) para o idioma corrente.


Sintaxe: X1PERGUNT()

Parmetros:
Nenhum

Retorno:
String

Descrio da pergunta do Dicionrio de Dados (SX1) no idioma corrente.

Exemplo:
User Function <nome-da-funo>( cGrupo, cPerg )
Local cDescr
dbSelectArea(SX1)
dbSetOrder(1)
If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDescr := X1Pergunt()
EndIf
Return

X2NOME()
A funo X2NOME() retorna a descrio de uma tabela posicionada no Dicionrio de Dados
(SX2) no idioma corrente.


Sintaxe: X2NOME()

Parmetros:
Nenhum

Retorno:
String

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


corrente.

Exemplo:
User Function <nome-da-funo>( )
Local cTabela
dbSelectArea(SX2)
dbSetOrder(1)
If dbSeek( SA1 )
cTabela := X2Nome()
EndIf
Return
- 495 Guia de Referncia Rpida
ADVPL Avanado

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:
User Function <nome-da-funo>( )
Local cTitulo
Local cDescri
Local cCombo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( cCampo )
cTitulo := X3Titulo()
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf
Return

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


Sintaxe: X3DESCRIC()

Parmetros:
Nenhum

Retorno:
String

Descrio do campo posicionado no Dicionrio de Dados (SX3) no idioma


corrente.

- 496 Guia de Referncia Rpida


ADVPL Avanado

Exemplo:
User Function <nome-da-funo>( )
Local cTitulo
Local cDescri
Local cCombo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( cCampo )
cTitulo := X3Titulo()
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf
Return

X3PICTURE()
A funo X3PICTURE() retorna a mscara de um campo contido no Dicionrio de Dados (SX3).


Sintaxe: X3PICTURE(cCampo)

Parmetros:
cCampo

Nome do campo contido no Dicionrio de Dados (SX3).

Retorno:
String

Picture do campo informado.

Exemplo:
User Function <nome-da-funo>( cCampo )
Local cPicture
cPicture := X3Picture( cCampo )
Return cPicture

- 497 Guia de Referncia Rpida


ADVPL Avanado

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:
User Function <nome-da-funo>( )
Local cTitulo
dbSelectArea(SX3)
dbSetOrder(2)
If dbSeek( A1_COD )
cTitulo := X3Titulo()
EndIf
Return

X3USO()
A funo X3USO() verifica se o campo atualmente posicionado no Dicionrio de Dados (SX3)
est disponvel para uso.


Sintaxe: X3USO( cUsado, [Modulo])

Parmetros:

cUsado

Contedo do campo X3_USADO a ser avaliado.

Modulo

Nmero do mdulo. Caso no seja informado ser assumido como padro o


nmero do mdulo corrente.

Retorno:
Lgico

Indica se o campo est configurado como usado no Dicionrio de Dados


(SX3).

- 498 Guia de Referncia Rpida


ADVPL Avanado

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
Return

- 499 Guia de Referncia Rpida


ADVPL Avanado

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

- 500 Guia de Referncia Rpida


ADVPL Avanado

X6DESCRIC()
A funo X6DESCRI() retorna o contedo da descrio de um parmetro de acordo com o
registro posicionado no Dicionrio de Dados (SX6) no idioma corrente.


Sintaxe: X6DESCRIC()

Parmetros:
.

Nenhum


Retorno:
String

Descrio do parmetro posicionado no Dicionrio de Dados (SX6) no idioma


corrente.

Para avaliar os co