Anda di halaman 1dari 430

Educao Corporativa

ADVPL II

Matriz Av. Braz Leme, 1.717 02511-000 So Paulo SP Brasil. Tel.: 55 (11) 3981-7001 www.microsiga.com.br

-2ADVPL II

ESTRUTURA DO TREINAMENTO
OBJETIVOS DO CURSO.................................................................................................................................................12 MDULO 04: Desenvolvendo aplicaes em ADVPL ....................................................................................................13 1. A linguagem ADVPL.....................................................................................................................................................13 2. Estrutura de um Programa ADVPL..............................................................................................................................15

2.1. reas de um Programa ADVPL.......................................................................................................17


3. Declarao e Atribuio de Variveis............................................................................................................................20

3.1. Tipo de Dados....................................................................................................................................20 3.2. Declarao de variveis.....................................................................................................................21 3.3. Escopo de variveis............................................................................................................................22 3.4. Entendendo a influncia do escopo das variveis............................................................................26
4. Regras adicionais da linguagem ADVPL......................................................................................................................27

4.1. Palavras reservadas ..........................................................................................................................27 4.2. Pictures de formatao disponveis..................................................................................................28


5. Programas de Atualizao.............................................................................................................................................29

5.1. Modelo1() ou AxCadastro()..............................................................................................................30 5.2. Mbrowse()..........................................................................................................................................33


5.2.1. AxFunctions().................................................................................................................................................38 5.2.2. FilBrowse().....................................................................................................................................................41 5.2.3. EndFilBrw()....................................................................................................................................................41 5.2.4. PesqBrw()........................................................................................................................................................42 5.2.5. BrwLegenda ()................................................................................................................................................42

5.3. MarkBrowse()....................................................................................................................................46
5.3.1. Funes de Apoio............................................................................................................................................47

5.4. Modelo2()...........................................................................................................................................50
5.4.1. Componentes de uma tela no formato Modelo 2............................................................................................50 5.4.2. Estrutura de um programa utilizando a Modelo2().........................................................................................59 5.4.3. Funo Modelo2()...........................................................................................................................................67

5.5. Modelo3()...........................................................................................................................................72
5.5.1. Estrutura de um programa utilizando a Modelo3().........................................................................................75 5.5.2. Funo Modelo3()...........................................................................................................................................84 6. Arquivos e ndices Temporrios....................................................................................................................................88

6.1. Utilizao de arquivos e ndices temporrios..................................................................................88 6.2. Funes para manipulao de arquivos e ndices temporrios......................................................88
6.2.1. CriaTrab()........................................................................................................................................................88 6.2.2. dbUseArea()....................................................................................................................................................89 6.2.3. IndRegua()......................................................................................................................................................89

6.3. Funes Auxiliares para Arquivos de Trabalho e Temporrios....................................................90


7. Relatrios no grficos..................................................................................................................................................94

7.1. Funes Utilizadas para Desenvolvimento de Relatrios...............................................................94


7.1.1. SetPrint().........................................................................................................................................................94 7.1.2. SetDefault().....................................................................................................................................................95
-3ADVPL II

7.1.3. RptStatus()......................................................................................................................................................96 7.1.3.1. SETREGUA().........................................................................................................................................96 7.1.3.2. INCREGUA()..........................................................................................................................................97 7.1.4. CABEC().........................................................................................................................................................97 7.1.5. RODA()...........................................................................................................................................................98 7.1.6. Pergunte()........................................................................................................................................................98 7.1.7. AjustaSX1()....................................................................................................................................................98 7.1.8. PutSX1()........................................................................................................................................................100

7.2. Estrutura de Relatrios Baseados na SetPrint()...........................................................................102


8. Manipulao de arquivos I..........................................................................................................................................112

8.1. Gerao e leitura de arquivos em formato texto...........................................................................112


8.1.1. 1 Famlia de funes de gravao e leitura de arquivos texto.....................................................................113 8.1.1.1. FCREATE()..........................................................................................................................................113 8.1.1.2. FWRITE().............................................................................................................................................114 8.1.1.3. FCLOSE().............................................................................................................................................114 8.1.1.4. FSEEK()................................................................................................................................................115 8.1.1.5. FOPEN()................................................................................................................................................115 8.1.1.6. FREAD()...............................................................................................................................................116 8.1.2. 2 Famlia de funes de gravao e leitura de arquivos texto.....................................................................123 8.1.2.1. FT_FUSE()............................................................................................................................................123 8.1.2.2. FT_FGOTOP()......................................................................................................................................123 8.1.2.3. FT_FLASTREC()..................................................................................................................................123 8.1.2.4. FT_FEOF()............................................................................................................................................124 8.1.2.5. FT_FREADLN()...................................................................................................................................124 8.1.2.6. FT_FSKIP()...........................................................................................................................................124 8.1.2.7. FT_FGOTO()........................................................................................................................................125 8.1.2.8. FT_FRECNO()......................................................................................................................................125 9. Oficina de programao I............................................................................................................................................128

9.1. Interfaces com sintaxe clssica.......................................................................................................128 9.2. Rguas de processamento................................................................................................................132


9.2.1. RptStatus()....................................................................................................................................................132 SETREGUA()...............................................................................................................................................134 INCREGUA()................................................................................................................................................135 9.2.2. Processa()......................................................................................................................................................136 SETPROC()...................................................................................................................................................138 INCPROC()...................................................................................................................................................138 9.2.3. MsNewProcess()...........................................................................................................................................139 9.2.4. MsAguarde().................................................................................................................................................141 9.2.5. MsgRun()......................................................................................................................................................143

9.3. ListBox() ..........................................................................................................................................145


9.3.1. ListBox simples ............................................................................................................................................145 9.3.2. ListBox mltiplas colunas ............................................................................................................................148

9.4. ScrollBox()........................................................................................................................................150 9.5. ParamBox()......................................................................................................................................155


MDULO 05: Introduo a orientao objetos .........................................................................................................160 10. Conceitos de orientao objetos..............................................................................................................................160

10.1. Definies ......................................................................................................................................160 10.2. Conceitos Bsicos ..........................................................................................................................163 10.3. O Modelo de Objetos (OMT)........................................................................................................164
10.3.1. Objetos e Classes .......................................................................................................................................164 10.3.2. Atributos .....................................................................................................................................................165
-4ADVPL II

10.3.3. Operaes e Mtodos .................................................................................................................................166 10.3.4. Sugestes de desenvolvimento ...................................................................................................................167 11. Orientao a objetos em ADVPL...............................................................................................................................168

11.1. Sintaxe e operadores para orientao a objetos..........................................................................168 11.2. Estrutura de uma classe de objetos em ADVPL..........................................................................171 11.3. Implementao dos mtodos de uma classe em ADVPL.............................................................172
MDULO 06: ADVPL Orientado objetos I ................................................................................................................176 12. Componentes da interface visual do ADVPL.............................................................................................................176

12.1. Particularidades dos componentes visuais...................................................................................183


12.1.1. Configurando as cores para os componentes..............................................................................................183 13. Aplicaes com a interface visual do ADVPL...........................................................................................................185

13.1. Captura de informaes simples (Multi-Gets).............................................................................185


13.1.1. Enchoice()...................................................................................................................................................186 13.1.2. MsMGet()....................................................................................................................................................188

13.2. Captura de mltiplas informaes (Multi-Lines)........................................................................191


13.2.1. MsGetDB()..................................................................................................................................................193 13.2.2. MsGetDados().............................................................................................................................................197 13.2.3. MsNewGetDados().....................................................................................................................................201 13.2.3.1. Definindo cores personalizadas para o objeto MsNewGetDados()....................................................206

13.3. Barras de botes............................................................................................................................211


13.3.1. EnchoiceBar().............................................................................................................................................211 13.3.2. TBar()..........................................................................................................................................................214 13.3.3. ButtonBar....................................................................................................................................................215 13.3.4. Imagens pr-definidas para as barras de botes..........................................................................................218 APNDICES...................................................................................................................................................................219 BOAS PRTICAS DE PROGRAMAO.....................................................................................................................219 14. Arredondamento.........................................................................................................................................................219 15. Utilizao de Identao .............................................................................................................................................219 16. Capitulao de Palavras-Chave ................................................................................................................................221

16.1. Palavras em maisculo .................................................................................................................221


17. Utilizao da Notao Hngara ................................................................................................................................222 18. Tcnicas de programao eficiente............................................................................................................................222 GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL............................................................................234

Converso entre tipos de dados............................................................................................................234


CTOD()..........................................................................................................................................................234 CVALTOCHAR().........................................................................................................................................234 DTOC()..........................................................................................................................................................235 DTOS()..........................................................................................................................................................235 STOD()..........................................................................................................................................................235 STR().............................................................................................................................................................236 STRZERO()...................................................................................................................................................236 VAL()............................................................................................................................................................237

Matemticas...........................................................................................................................................238
ACOS() ........................................................................................................................................................238 CEILING()....................................................................................................................................................238 COS().............................................................................................................................................................238 LOG10()........................................................................................................................................................239
-5ADVPL II

SIN()..............................................................................................................................................................239 SQRT()..........................................................................................................................................................240 TAN()............................................................................................................................................................240

Anlise de variveis...............................................................................................................................241
TYPE()..........................................................................................................................................................241 VALTYPE()..................................................................................................................................................241

Manipulao de arrays..........................................................................................................................242
AADD().........................................................................................................................................................242 ACLONE()....................................................................................................................................................243 ACOPY().......................................................................................................................................................243 ADEL()..........................................................................................................................................................244 ADIR()...........................................................................................................................................................245 AFILL() .......................................................................................................................................................246 AINS()...........................................................................................................................................................246 ARRAY()......................................................................................................................................................247 ASCAN().......................................................................................................................................................247 ASCANX() ..................................................................................................................................................248 ASIZE().........................................................................................................................................................249 ASORT().......................................................................................................................................................250 ATAIL()........................................................................................................................................................251

Manipulao de blocos de cdigo ........................................................................................................253


EVAL()..........................................................................................................................................................253 DBEVAL()....................................................................................................................................................253 AEVAL().......................................................................................................................................................255

Manipulao de strings.........................................................................................................................256
ALLTRIM()...................................................................................................................................................256 ASC().............................................................................................................................................................256 AT()...............................................................................................................................................................257 BITON() ......................................................................................................................................................258 CAPITAL()....................................................................................................................................................258 CHR()............................................................................................................................................................258 DESCEND() ................................................................................................................................................259 GETDTOVAL() ..........................................................................................................................................259 ISALPHA() ..................................................................................................................................................260 ISDIGIT() ....................................................................................................................................................260 ISLOWER() .................................................................................................................................................261 ISUPPER() ..................................................................................................................................................261 LEN().............................................................................................................................................................261 LOWER()......................................................................................................................................................262 LTRIM() ......................................................................................................................................................262 MATHC() ....................................................................................................................................................263 OEMTOANSI() ...........................................................................................................................................263 PADL() / PADR() / PADC().........................................................................................................................264 RAT()............................................................................................................................................................264 REPLICATE() .............................................................................................................................................265 RTRIM() ......................................................................................................................................................265 SPACE() ......................................................................................................................................................266 STRTOKARR() ...........................................................................................................................................266 STRTRAN() ................................................................................................................................................267 STUFF()........................................................................................................................................................267 SUBSTR().....................................................................................................................................................268 TRANSFORM() ..........................................................................................................................................268 UPPER()........................................................................................................................................................269

Manipulao de data / hora..................................................................................................................270


CDOW() ......................................................................................................................................................270 CMONTH() .................................................................................................................................................270
-6ADVPL II

DATE() ........................................................................................................................................................271 DAY() ..........................................................................................................................................................271 DOW() .........................................................................................................................................................272 DTOC() ........................................................................................................................................................272 DTOS() ........................................................................................................................................................273 ELAPTIME() ...............................................................................................................................................273 MONTH() ....................................................................................................................................................274 SECONDS() ................................................................................................................................................274 TIME() .........................................................................................................................................................275 YEAR() .......................................................................................................................................................275

Manipulao de variveis numricas...................................................................................................276


ABS().............................................................................................................................................................276 ALEATORIO()..............................................................................................................................................276 INT()..............................................................................................................................................................277 NOROUND()................................................................................................................................................277 RANDOMIZE()............................................................................................................................................278 ROUND()......................................................................................................................................................278

Manipulao de arquivos .....................................................................................................................279


ADIR()...........................................................................................................................................................279 CGETFILE() ...............................................................................................................................................281 CPYS2T()......................................................................................................................................................287 CPYT2S()......................................................................................................................................................287 CURDIR() ...................................................................................................................................................288 DIRECTORY() ...........................................................................................................................................289 DIRREMOVE().............................................................................................................................................290 DISKSPACE()...............................................................................................................................................291 EXISTDIR()..................................................................................................................................................292 FCLOSE().....................................................................................................................................................292 FCREATE() .................................................................................................................................................293 FERASE() ...................................................................................................................................................294 FILE() ..........................................................................................................................................................294 FILENOEXT()..............................................................................................................................................295 FOPEN()........................................................................................................................................................296 FREAD().......................................................................................................................................................298 FREADSTR ()...............................................................................................................................................298 FRENAME().................................................................................................................................................299 FSEEK()........................................................................................................................................................300 FT_FEOF()....................................................................................................................................................300 FT_FGOTO()................................................................................................................................................301 FT_FGOTOP()..............................................................................................................................................301 FT_FLASTREC()..........................................................................................................................................301 FT_FREADLN()...........................................................................................................................................302 FT_FRECNO()..............................................................................................................................................303 FT_FSKIP()...................................................................................................................................................303 FT_FUSE()....................................................................................................................................................303 FWRITE()......................................................................................................................................................304 MSCOPYFILE()...........................................................................................................................................306 MSCOPYTO()...............................................................................................................................................307 MSCREATE()...............................................................................................................................................307 MSERASE()..................................................................................................................................................308 MSRENAME()..............................................................................................................................................309 RETFILENAME().........................................................................................................................................309

Manipulao de arquivos e ndices temporrios ................................................................................310


CRIATRAB()................................................................................................................................................310

Manipulao de bases de dados ...........................................................................................................311


ALIAS().........................................................................................................................................................311
-7ADVPL II

BOF() / EOF() .............................................................................................................................................311 COPY()..........................................................................................................................................................312 COPY STRUCTURE() ................................................................................................................................315 DBAPPEND()...............................................................................................................................................315 DBCLEARALLFILTER() ..........................................................................................................................316 DBCLEARFILTER()....................................................................................................................................317 DBCLEARINDEX().....................................................................................................................................317 DBCLOSEALL()..........................................................................................................................................318 DBCLOSEAREA().......................................................................................................................................318 DBCOMMIT()..............................................................................................................................................319 DBCOMMITALL().......................................................................................................................................319 DBCREATE()...............................................................................................................................................320 DBCREATEINDEX()...................................................................................................................................321 DBDELETE()................................................................................................................................................322 DBF().............................................................................................................................................................323 DBFIELDINFO()..........................................................................................................................................323 DBFILTER().................................................................................................................................................324 DBGOTO()....................................................................................................................................................325 DBGOTOP().................................................................................................................................................325 DBGOBOTTON().........................................................................................................................................326 DBINFO().....................................................................................................................................................326 DBNICKINDEXKEY()................................................................................................................................327 DBORDERINFO()........................................................................................................................................329 DBORDERNICKNAME()............................................................................................................................330 DBPACK()....................................................................................................................................................330 DBRECALL()...............................................................................................................................................330 DBRECORDINFO().....................................................................................................................................331 DBREINDEX().............................................................................................................................................332 DBRLOCK().................................................................................................................................................333 DBRLOCKLIST().........................................................................................................................................333 DBRUNLOCK()...........................................................................................................................................334 DBSETDRIVER().........................................................................................................................................334 DBSETINDEX()...........................................................................................................................................335 DBSETNICKNAME()..................................................................................................................................336 DBSELECTAREA() ....................................................................................................................................336 DBSETORDER()..........................................................................................................................................337 DBSEEK() E MSSEEK()..............................................................................................................................338 DBSKIP()......................................................................................................................................................339 DBSETFILTER()..........................................................................................................................................340 DBSTRUCT()...............................................................................................................................................341 DBUNLOCK()..............................................................................................................................................341 DBUNLOCKALL()......................................................................................................................................342 DBUSEAREA()............................................................................................................................................342 DELETED()..................................................................................................................................................343 FCOUNT()....................................................................................................................................................343 FOUND().......................................................................................................................................................344 INDEXKEY()................................................................................................................................................344 INDEXORD()...............................................................................................................................................345 LUPDATE()..................................................................................................................................................345 MSAPPEND()...............................................................................................................................................346 MSUNLOCK()..............................................................................................................................................346 ORDBAGEXT()............................................................................................................................................347 ORDKEY()....................................................................................................................................................347 RECLOCK()..................................................................................................................................................348 RECNO().......................................................................................................................................................349 SELECT()......................................................................................................................................................349 SET FILTER TO...........................................................................................................................................350 SOFTLOCK()................................................................................................................................................351 USED()..........................................................................................................................................................352
-8ADVPL II

ZAP...............................................................................................................................................................352

Controle de numerao seqencial.......................................................................................................353


GETSXENUM()............................................................................................................................................353 CONFIRMSXE()...........................................................................................................................................353 ROLLBACKSXE().......................................................................................................................................353

Validao ...............................................................................................................................................354
ALLWAYSFALSE().....................................................................................................................................354 ALLWAYSTRUE()......................................................................................................................................354 EXISTCHAV()..............................................................................................................................................354 EXISTCPO().................................................................................................................................................355 LETTERORNUM().......................................................................................................................................355 NAOVAZIO()...............................................................................................................................................355 NEGATIVO()................................................................................................................................................355 PERTENCE()................................................................................................................................................356 POSITIVO()..................................................................................................................................................356 TEXTO().......................................................................................................................................................356 VAZIO()........................................................................................................................................................356

Manipulao de parmetros do sistema...............................................................................................357


GETMV()......................................................................................................................................................357 GETNEWPAR()............................................................................................................................................357 PUTMV()......................................................................................................................................................358 SUPERGETMV()..........................................................................................................................................358

Controle de impresso...........................................................................................................................359
AVALIMP()..................................................................................................................................................359 CABEC().......................................................................................................................................................360 IMPCADAST().............................................................................................................................................363 MS_FLUSH()................................................................................................................................................363 OURSPOOL()...............................................................................................................................................365 RODA().........................................................................................................................................................366 SETDEFAULT()...........................................................................................................................................368 SETPRC()......................................................................................................................................................369 SETPRINT()..................................................................................................................................................369

Controle de processamentos.................................................................................................................371
ABREEXCL()...............................................................................................................................................371 CLOSEOPEN().............................................................................................................................................371 CLOSESFILE().............................................................................................................................................371 CHKFILE()...................................................................................................................................................372 CONOUT()....................................................................................................................................................373 CRIAVAR()..................................................................................................................................................373 DISARMTRANSACTION().........................................................................................................................374 EXECBLOCK()............................................................................................................................................375 EXISTBLOCK()...........................................................................................................................................375 ERRORBLOCK() ........................................................................................................................................376 FINAL().........................................................................................................................................................378 FINDFUNCTION() .....................................................................................................................................378 FUNDESC()..................................................................................................................................................379 FUNNAME().................................................................................................................................................379 GETAREA()..................................................................................................................................................379 GETCOUNTRYLIST().................................................................................................................................380 ISINCALLSTACK().....................................................................................................................................380 REGTOMEMORY().....................................................................................................................................381 RESTAREA()................................................................................................................................................382 USEREXCEPTION()....................................................................................................................................382

Utilizao de recursos do ambiente ERP.............................................................................................384


AJUSTASX1()..............................................................................................................................................384
-9ADVPL II

ALLUSERS()................................................................................................................................................386 ALLGROUPS().............................................................................................................................................388 CGC()............................................................................................................................................................388 CONPAD1()..................................................................................................................................................389 DATAVALIDA()..........................................................................................................................................390 EXISTINI()....................................................................................................................................................390 EXTENSO()..................................................................................................................................................391 FORMULA().................................................................................................................................................391 GETADVFVAL().........................................................................................................................................391 HELP()..........................................................................................................................................................392 MESEXTENSO()..........................................................................................................................................393 OBRIGATORIO().........................................................................................................................................393 OPENFILE().................................................................................................................................................396 PERGUNTE()...............................................................................................................................................397 PESQPICT()..................................................................................................................................................397 PESQPICTQT().............................................................................................................................................398 POSICIONE()................................................................................................................................................398 PUTSX1()......................................................................................................................................................399 RETINDEX()................................................................................................................................................400 SIXDESCRICAO().......................................................................................................................................400 TABELA().....................................................................................................................................................401 TAMSX3()....................................................................................................................................................401 TM()..............................................................................................................................................................402 X1DEF01()....................................................................................................................................................403 X1PERGUNT().............................................................................................................................................404 X2NOME()....................................................................................................................................................404 X3CBOX()....................................................................................................................................................405 X3DESCRIC()...............................................................................................................................................405 X3PICTURE()...............................................................................................................................................406 X3TITULO().................................................................................................................................................407 X3USO().......................................................................................................................................................407 X5DESCRI().................................................................................................................................................408 X6CONTEUD()............................................................................................................................................409 X6DESCRIC()...............................................................................................................................................410 XADESCRIC()..............................................................................................................................................411 XBDESCRI().................................................................................................................................................411 XFILIAL().....................................................................................................................................................412

Componentes da interface visual..........................................................................................................413


MSDIALOG()...............................................................................................................................................413 MSGET().......................................................................................................................................................414 SAY()............................................................................................................................................................415 BUTTON()....................................................................................................................................................415 SBUTTON()..................................................................................................................................................416 CHECKBOX()..............................................................................................................................................416 COMBOBOX().............................................................................................................................................418 FOLDER().....................................................................................................................................................419 RADIO()........................................................................................................................................................420

Interfaces de cadastro...........................................................................................................................421
AXCADASTRO().........................................................................................................................................421 MBROWSE()................................................................................................................................................421 AXPESQUI().................................................................................................................................................421 AXVISUAL()................................................................................................................................................422 AXINCLUI().................................................................................................................................................422 AXALTERA()...............................................................................................................................................423 AXDELETA()...............................................................................................................................................424

Interfaces visuais para aplicaes........................................................................................................425


ALERT().......................................................................................................................................................425
- 10 ADVPL II

AVISO()........................................................................................................................................................425 FORMBACTH()...........................................................................................................................................426 MSGFUNCTIONS().....................................................................................................................................427

Recursos das interfaces visuais.............................................................................................................428


GDFIELDGET()...........................................................................................................................................428 GDFIELDPOS()............................................................................................................................................428 GDFIELDPUT()............................................................................................................................................428 GETMARK().................................................................................................................................................429 MARKBREFRESH()....................................................................................................................................430 READVAR() ...............................................................................................................................................430

- 11 ADVPL II

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 de relatrios e programas de atualizao estruturas para implementao de interfaces visuais princpios do desenvolvimento de aplicaes orientadas a objetos

b) Habilidades e tcnicas a serem aprendidas desenvolvimento de aplicaes voltadas ao ERP Protheus anlise de fontes de mdia complexidade desenvolvimento de aplicaes bsicas 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

- 12 ADVPL II

MDULO 04: Desenvolvendo aplicaes em ADVPL


1. A linguagem ADVPL
A Linguagem ADVPL teve seu incio em 1994, sendo na verdade uma evoluo na utilizao de linguagens no padro xBase pela Microsiga Software S.A. (Clipper, Visual Objects e depois FiveWin). Com a criao da tecnologia Protheus, era necessrio criar uma linguagem que suportasse o padro xBase para a manuteno de todo o cdigo existente do sistema de ERP Siga Advanced. Foi ento criada a linguagem chamada Advanced Protheus Language. O ADVPL uma extenso do padro xBase de comandos e funes, operadores, estruturas de controle de fluxo e palavras reservadas, contando tambm com funes e comandos disponibilizados pela Microsiga que a torna uma linguagem completa para a criao de aplicaes ERP prontas para a Internet. Tambm uma linguagem orientada a objetos e eventos, permitindo ao programador desenvolver aplicaes visuais e criar suas prprias classes de objetos. Quando compilados, todos os arquivos de cdigo tornam-se unidades de inteligncia bsicas, chamados APOs (de Advanced Protheus Objects). Tais APOs so mantidos em um repositrio e carregados dinamicamente pelo PROTHEUS Server para a execuo. Como no existe a linkedio, ou unio fsica do cdigo compilado a um determinado mdulo ou aplicao, funes criadas em ADVPL podem ser executadas em qualquer ponto do ambiente Advanced Protheus. O compilador e o interpretador da linguagem ADVPL o prprio servidor PROTHEUS (PROTHEUS Server), e existe um ambiente visual para desenvolvimento integrado (PROTHEUSIDE) onde o cdigo pode ser criado, compilado e depurado. Os programas em ADVPL podem conter comandos ou funes de interface com o usurio. De acordo com tal caracterstica, tais programas so subdivididos nas seguintes categorias: Programao Com Interface Prpria com o Usurio Nesta categoria entram os programas desenvolvidos para serem executados atravs do terminal remoto do Protheus, o Protheus Remote. O Protheus Remote a aplicao encarregada da interface e da interao com o usurio, sendo que todo o processamento do cdigo em ADVPL, o acesso ao banco de dados e o gerenciamento de conexes efetuado no Protheus Server. O Protheus Remote o principal meio de acesso a execuo de rotinas escritas em ADVPL no Protheus Server, e por isso permite executar qualquer tipo de cdigo, tenha ele interface com o usurio ou no. Porm nesta categoria so considerados apenas os programas que realizem algum tipo de interface remota utilizando o protocolo de comunicao do Protheus. Podem-se criar rotinas para a customizao do sistema ERP Microsiga Protheus, desde processos adicionais at mesmo relatrios. A grande vantagem aproveitar todo o ambiente montado pelos mdulos do ERP Microsiga Protheus. Porm, com o ADVPL possvel at mesmo criar toda uma aplicao, ou mdulo, do comeo. Todo o cdigo do sistema ERP Microsiga Protheus escrito em ADVPL.

- 13 ADVPL II

Programao Sem Interface Prpria com o Usurio As rotinas criadas sem interface so consideradas nesta categoria porque geralmente tm uma utilizao mais especfica do que um processo adicional ou um relatrio novo. Tais rotinas no tm interface com o usurio atravs do Protheus Remote, e qualquer tentativa nesse sentido (como a criao de uma janela padro) ocasionar uma exceo em tempo de execuo. Estas rotinas so apenas processos, ou Jobs, executados no Protheus Server. Algumas vezes, a interface destas rotinas fica a cargo de aplicaes externas, desenvolvidas em outras linguagens, que so responsveis por iniciar os processos no servidor Protheus atravs dos meios disponveis de integrao e conectividade no Protheus. De acordo com a utilizao e com o meio de conectividade utilizado, estas rotinas so subcategorizadas assim: Programao por Processos Rotinas escritas em ADVPL podem ser iniciadas como processos individuais (sem interface) no Protheus Server atravs de duas maneiras: Iniciadas por outra rotina ADVPL atravs da chamada de funes como StartJob() ou CallProc() ou iniciadas automaticamente na inicializao do Protheus Server (quando propriamente configurado). Programao de RPC Atravs de uma biblioteca de funes disponvel no Protheus (uma API de comunicao), podem-se executar rotinas escritas em ADVPL diretamente no Protheus Server, atravs de aplicaes externas escritas em outras linguagens. Isto o que se chama de RPC (de Remote Procedure Call, ou Chamada de Procedimentos Remota). O servidor Protheus tambm pode executar rotinas em ADVPL em outros servidores Protheus atravs de conexo TCP/IP direta utilizando o conceito de RPC. Do mesmo modo, aplicaes externas podem requisitar a execuo de rotinas escritas em ADVPL atravs de conexo TCP/IP direta. Programao Web 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.

- 14 ADVPL II

2. Estrutura de um Programa ADVPL


Um programa de computador nada mais do que um grupo de comandos logicamente dispostos com o objetivo de executar determinada tarefa. Esses comandos so gravados em um arquivo texto que transformado em uma linguagem executvel por um computador atravs de um processo chamado compilao. A compilao substitui os comandos de alto nvel (que os humanos compreendem) por instrues de baixo nvel (compreendida pelo sistema operacional em execuo no computador). No caso do ADVPL, no o sistema operacional de um computador que ir executar o cdigo compilado, mas sim o Protheus Server. Dentro de um programa, os comandos e funes utilizados devem seguir regras de sintaxe da linguagem utilizada, pois caso contrrio o programa ser interrompido por erros. Os erros podem ser de compilao ou de execuo. Erros de compilao so aqueles encontrados na sintaxe que no permitem que o arquivo de cdigo do programa seja compilado. Podem ser comandos especificados de forma errnea, utilizao invlida de operadores, etc. Erros de execuo so aqueles que acontecem depois da compilao, quando o programa est sendo executado. Podem ocorrer por inmeras razes, mas geralmente se referem as funes no existentes, ou variveis no criadas ou inicializadas, etc. Linhas de Programa As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser linhas de comando, linhas de comentrio ou linhas mistas. Linhas de Comando Linhas de comando possuem os comandos ou instrues que sero executadas. Por exemplo: Local nCnt Local nSoma := 0 For nCnt := 1 To 10 nSoma += nCnt Next nCnt Linhas de Comentrio Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem apenas para documentao e para tornar mais fcil o entendimento do programa. Existem trs formas de se comentar linhas de texto. A primeira delas utilizar o sinal de * (asterisco) no comeo da linha: * Programa para clculo do total * Autor: Microsiga Software S.A. * Data: 2 de outubro de 2001

- 15 ADVPL II

Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio. Podese utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para realizar a funo do sinal de asterisco. Porm todas estas formas de comentrio de linhas so obsoletas e existem apenas para compatibilizao com o padro xBase. A melhor maneira de comentar linhas em ADVPL utilizar duas barras transversais: // Programa para clculo do total // Autor: Microsiga Software S.A. // Data: 2 de outubro de 2001 Outra forma de documentar textos utilizar as barras transversais juntamente com o asterisco, podendo-se comentar todo um bloco de texto sem precisar comentar linha a linha: /* Programa para clculo do total Autor: Microsiga Software S.A. Data: 2 de outubro de 2001 */ Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento (indicada pelos caracteres */) considerado como comentrio. Linhas Mistas O ADVPL tambm permite que existam linhas de comando com comentrio. Isto possvel adicionando-se as duas barras transversais (//) ao final da linha de comando e adicionando-se o texto do comentrio: Local nCnt Local nSoma := 0 // Inicializa a varivel com zero para a soma For nCnt := 1 To 10 nSoma += nCnt Next nCnt Tamanho da Linha Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser digitado no editor de textos utilizado, existe uma linha considerada linha lgica. A linha lgica, aquela considerada para a compilao como uma nica linha de comando. A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento da tecla <Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm algumas vezes, por limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha lgica em mais de uma linha fsica no arquivo texto. Isto efetuado utilizando-se o sinal de ponto-e-vrgula (;). If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter> !Empty(cTel) .And. !Empty(cFax) .And. ; <enter> !Empty(cEmail) GravaDados(cNome,cEnd,cTel,cFax,cEmail) Endif Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas. Como a linha torna-se muito grande, pode-se dividi-la em mais de uma linha fsica utilizando o sinal de
- 16 ADVPL II

ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas duas primeiras linhas, durante a execuo do programa ocorrer um erro, pois a segunda linha fsica ser considerada como uma segunda linha de comando na compilao. E durante a execuo esta linha no ter sentido.

2.1.

reas de um Programa ADVPL

Apesar de no ser uma linguagem de padres rgidos com relao estrutura do programa, importante identificar algumas de suas partes. Considere o programa de exemplo abaixo: #include protheus.ch /* +===========================================+ | Programa: Clculo do Fatorial | | Autor : Microsiga Software S.A. | | Data : 02 de outubro de 2001 | +===========================================+ */ User Function CalcFator() Local nCnt Local nResultado := 1 // Resultado do fatorial Local nFator := 5 // Nmero para o clculo // Clculo do fatorial For nCnt := nFator To 1 Step -1 nResultado *= nCnt Next nCnt // Exibe o resultado na tela, atravs da funo alert Alert("O fatorial de " + cValToChar(nFator) + ; " " + cValToChar(nResultado)) // Termina o programa Return A estrutura de um programa ADVPL composta pelas seguintes reas: rea de Identificao Declarao dos includes Declarao da funo Identificao do programa rea de Ajustes Iniciais Declarao das variveis Corpo do Programa Preparao para o processamento Processamento rea de Encerramento

- 17 ADVPL II

rea de Identificao Esta uma rea que no obrigatria e dedicada a documentao do programa. Quando existente, contm apenas comentrios explicando a sua finalidade, data de criao, autor, etc., e aparece no comeo do programa, antes de qualquer linha de comando. O formato para esta rea no definido. Pode-se colocar qualquer tipo de informao desejada e escolher a formatao apropriada. #include protheus.ch /* +==========================================+ | Programa: Clculo do Fatorial | | Autor : Microsiga Software S.A. | | Data : 02 de outubro de 2001 | +==========================================+ */ User Function CalcFator() Opcionalmente podem-se incluir definies de constantes utilizadas no programa ou incluso de arquivos de cabealho nesta rea. rea de Ajustes Iniciais Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto funcionamento do programa. Entre os ajustes se encontram declaraes de variveis, inicializaes, abertura de arquivos, etc. Apesar do ADVPL no ser uma linguagem rgida e as variveis poderem ser declaradas em qualquer lugar do programa, aconselhvel faz-lo nesta rea visando tornar o cdigo mais legvel e facilitar a identificao de variveis no utilizadas. Local nCnt Local nResultado := 0 // Resultado do fatorial Local nFator := 10 // Nmero para o clculo Corpo do Programa nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a tarefa necessria atravs da organizao lgica destas linhas de comando. Espera-se que as linhas de comando estejam organizadas de tal modo que no final desta rea o resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variveis de memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela. // Clculo do fatorial For nCnt := nFator To 1 Step -1 nResultado *= nCnt Next nCnt

- 18 ADVPL II

A preparao para o processamento formada pelo conjunto de validaes e processamentos necessrios antes da realizao do processamento em si. Avaliando o processamento do clculo do fatorial descrito anteriormente, pode-se definir que a validao inicial a ser realizada o contedo da varivel nFator, pois a mesma determinar a correta execuo do cdigo.

// Clculo do fatorial nFator := GetFator() // GetFator funo ilustrativa na qual a varivel recebe a informao do usurio. If nFator <= 0 Alert(Informao invlida) Return Endif For nCnt := nFator To 1 Step -1 nResultado *= nCnt Next nCnt

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

- 19 ADVPL II

3. Declarao e Atribuio de Variveis 3.1. Tipo de Dados

O ADVPL no uma linguagem de tipos rgidos (strongly typed), o que significa que variveis de memria podem receber diferentes tipos de dados durante a execuo do programa. As variveis podem tambm conter objetos, mas os tipos primrios da linguagem so: Numrico O ADVPL no diferencia valores inteiros de valores com ponto flutuante, portanto podem-se criar variveis numricas com qualquer valor dentro do intervalo permitido. Os seguintes elementos so do tipo de dado numrico: 2 43.53 0.5 0.00001 1000000 Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E308 at 1.7976931348623158 E+308. Lgico Valores lgicos em ADVPL so identificados atravs de .T. ou .Y. para verdadeiro e .F. ou .N. para falso (independentemente se os caracteres estiverem em maisculo ou minsculo). Caractere Strings ou cadeias de caracteres so identificadas em ADVPL por blocos de texto entre aspas duplas (") ou aspas simples ('): "Ol mundo!" 'Esta uma string' "Esta 'outra' string" Uma varivel do tipo caractere pode conter strings com no mximo 1 MB, ou seja, 1048576 caracteres. Data O ADVPL tem um tipo de dados especfico para datas. Internamente as variveis deste tipo de dado so armazenadas como um nmero correspondente a data Juliana. Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs da utilizao de funes especficas como por exemplo CTOD() que converte uma string para data.

- 20 ADVPL II

Array O Array um tipo de dado especial. a disposio de outros elementos em colunas e linhas. O ADVPL suporta arrays unidimensionais (vetores) ou multidimensionais (matrizes). Os elementos de um array so acessados atravs de ndices numricos iniciados em 1, identificando a linha e coluna para quantas dimenses existirem. Arrays devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a memria do servidor. Bloco de Cdigo O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues escritas em ADVPL que podero ser executadas posteriormente.

3.2.

Declarao de variveis

Variveis de memria so um dos recursos mais importantes de uma linguagem. So reas de memria criadas para armazenar informaes utilizadas por um programa para a execuo de tarefas. Por exemplo, quando o usurio digita uma informao qualquer, como o nome de um produto, em uma tela de um programa esta informao armazenada em uma varivel de memria para posteriormente ser gravada ou impressa. A partir do momento que uma varivel criada, no necessrio mais se referenciar ao seu contedo, e sim ao seu nome. O nome de uma varivel um identificador nico o qual deve respeitar um mximo de 10 caracteres. O ADVPL no impede a criao de uma varivel de memria cujo nome contenha mais de 10 caracteres, porm apenas os 10 primeiros sero considerados para a localizao do contedo armazenado. Portanto se forem criadas duas variveis cujos 10 primeiros caracteres forem iguais, como nTotalGeralAnual e nTotalGeralMensal, as referncias a qualquer uma delas no programa resultaro o mesmo, ou seja, sero a mesma varivel: nTotalGeralMensal := 100 nTotalGeralAnual := 300 Alert("Valor mensal: " + cValToChar(nTotalGeralMensal)) Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300. Isso acontece porque no momento que esse valor foi atribudo varivel nTotalGeralAnual, o ADVPL considerou apenas os 10 primeiros caracteres (assim como o faz quando deve exibir o valor da varivel nTotalGeralMensal), ou seja, considerou-as como a mesma varivel. Assim o valor original de 100 foi substitudo pelo de 300.

- 21 ADVPL II

3.3.

Escopo de variveis

O ADVPL no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio informar o tipo de dados que determinada varivel ir conter no momento de sua declarao, e o seu valor pode mudar durante a execuo do programa. Tambm no h necessidade de declarar variveis em uma seo especfica do seu cdigo fonte, embora seja aconselhvel declarar todas as variveis necessrias no comeo, tornando a manuteno mais fcil e evitando a declarao de variveis desnecessrias. Para declarar uma varivel deve-se utilizar um identificador de escopo. Um identificador de escopo uma palavra chave que indica a que contexto do programa a varivel declarada pertence. O contexto de variveis pode ser local (visualizadas apenas dentro do programa atual), pblico (visualizadas por qualquer outro programa), entre outros. O Contexto de Variveis dentro de um Programa As variveis declaradas em um programa ou funo, so visveis de acordo com o escopo onde so definidas. Como tambm do escopo depende o tempo de existncia das variveis. A definio do escopo de uma varivel efetuada no momento de sua declarao. Local nNumero := 10 Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence seu escopo local. Os identificadores de escopo so: Local Static Private Public

O ADVPL no rgido em relao declarao de variveis no comeo do programa. A incluso de um identificador de escopo no necessrio para a declarao de uma varivel, contanto que um valor lhe seja atribudo. nNumero2 := 15 Quando um valor atribudo uma varivel em um programa ou funo, o ADVPL criar a varivel caso ela no tenha sido declarada anteriormente. A varivel ento criada como se tivesse sido declarada como Private. Devido a essa caracterstica, quando se pretende fazer uma atribuio a uma varivel declarada previamente mas escreve-se o nome da varivel de forma incorreta, o ADVPL no gerar nenhum erro de compilao ou de execuo. Pois compreender o nome da varivel escrito de forma incorreta como se fosse a criao de uma nova varivel. Isto alterar a lgica do programa, e um erro muitas vezes difcil de identificar.

- 22 ADVPL II

Variveis de escopo local Variveis de escopo local so pertencentes apenas ao escopo da funo onde foram declaradas e devem ser explicitamente declaradas com o identificador LOCAL, como no exemplo: Function Pai() Local nVar := 10, aMatriz := {0,1,2,3} . <comandos> . Filha() . <mais comandos> . Return(.T.) Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10. Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada. Quando a execuo da funo Pai terminar, a varivel nVar destruda. Qualquer varivel com o mesmo nome no programa que chamou a funo Pai no afetada. Variveis de escopo local so criadas automaticamente cada vez que a funo onde forem declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da ativao da funo (ou seja, at que a funo retorne o controle para o cdigo que a executou). Se uma funo chamada recursivamente (por exemplo, chama a si mesma), cada chamada em recurso cria um novo conjunto de variveis locais. A visibilidade de variveis de escopo locais idntica ao escopo de sua declarao, ou seja, a varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se uma funo chamada recursivamente, apenas as variveis de escopo local criadas na mais recente ativao so visveis. Variveis de escopo static Variveis de escopo static funcionam basicamente como as variveis de escopo local, mas mantm seu valor atravs da execuo e devem ser declaradas explicitamente no cdigo com o identificador STATIC. O escopo das variveis static depende de onde so declaradas. Se forem declaradas dentro do corpo de uma funo ou procedimento, seu escopo ser limitado quela rotina. Se forem declaradas fora do corpo de qualquer rotina, seu escopo afeta a todas as funes declaradas no fonte. Neste exemplo, a varivel nVar declarada como static e inicializada com o valor 10: Function Pai() Static nVar := 10 . <comandos> . Filha() . <mais comandos> . Return(.T.)

- 23 ADVPL II

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

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

Neste exemplo, a varivel nVar criada com escopo private e inicializada com o valor 10. Quando a funo Filha executada, nVar ainda existe e, diferente de uma varivel de escopo local, pode ser acessada pela funo Filha. Quando a funo Pai terminar, nVar ser destruda e qualquer declarao de nVar anterior se tornar acessvel novamente. No ambiente ERP Protheus, existe uma conveno adicional a qual deve ser respeitada que variveis em uso pela aplicao no sejam incorretamente manipuladas. Por esta conveno deve ser adicionado o caracter _ antes do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o tpico: Boas Prticas de Programao. Exemplo: Private _dData
- 24 ADVPL II

Variveis de escopo public Podem-se criar variveis de escopo public dinamicamente no cdigo com o identificador PUBLIC. As variveis deste escopo continuam a existir e mantm seu valor at o fim da execuo da thread (conexo). possvel criar uma varivel de escopo private com o mesmo nome de uma varivel de escopo public existente, entretanto, no permitido criar uma varivel de escopo public com o mesmo nome de uma varivel de escopo private existente. Uma vez criada, uma varivel de escopo public visvel em todo o programa onde foi declarada at que seja escondida por uma varivel de escopo private criada com o mesmo nome. A nova varivel de escopo private criada esconde a varivel de escopo public existente, e esta se tornar inacessvel at que a nova varivel private seja destruda. Por exemplo:

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

Neste exemplo, nVar criada como public e inicializada com o valor 10. Quando a funo Filha executada, nVar ainda existe e pode ser acessada. Diferente de variveis locais ou privates, nVar ainda existe aps o trmino da a execuo da funo Pai. Diferentemente dos outros identificadores de escopo, quando uma varivel declarada como pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil). No ambiente ERP Protheus, existe uma conveno adicional a qual deve ser respeitada que variveis em uso pela aplicao no sejam incorretamente manipuladas. Por esta conveno deve ser adicionado o caracter _ antes do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o tpico: Boas Prticas de Programao. Exemplo: Public _cRotina

- 25 ADVPL II

3.4.

Entendendo a influncia do escopo das variveis

Considere as linhas de cdigo de exemplo: nResultado := 250 * (1 + (nPercentual / 100))

Se esta linha for executada em um programa ADVPL, ocorrer um erro de execuo com a mensagem "variable does not exist: nPercentual", pois esta varivel est sendo utilizada em uma expresso de clculo sem ter sido declarada. Para solucionar este erro, deve-se declarar a varivel previamente:

Local nPercentual, nResultado nResultado := 250 * (1 + (nPercentual / 100))

Neste exemplo, as variveis so declaradas previamente utilizando o identificador de escopo local. Quando a linha de clculo for executada, o erro de varivel no existente, no mais ocorrer. Porm variveis no inicializadas tm sempre o valor default nulo (Nil) e este valor no pode ser utilizado em um clculo pois tambm gerar erros de execuo (nulo no pode ser dividido por 100). A resoluo deste problema efetuada inicializando-se a varivel atravs de uma das formas:

Local nPercentual, nResultado nPercentual := 10 nResultado := 250 * (1 + (nPercentual / 100)) ou Local nPercentual := 10, nResultado nResultado := 250 * (1 + (nPercentual / 100))

A diferena entre o ltimo exemplo e os dois anteriores que a varivel inicializada no momento da declarao. Em ambos os exemplos, a varivel primeiro declarada e ento inicializada em uma outra linha de cdigo. aconselhvel optar pelo operador de atribuio composto de dois pontos e sinal de igual, pois o operador de atribuio utilizando somente o sinal de igual pode ser facilmente confundido com o operador relacional (para comparao) durante a criao do programa.

- 26 ADVPL II

4. Regras adicionais da linguagem ADVPL 4.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 REPLICATE RLOCK ROUND ROW RTRIM SECONDS CHR EXP MIN STR DAY FOUND PROW TYPE TRY VAL VALTYPE WHILE WORD YEAR CDOW EOF MAX SQRT DATE FLOCK PROCEDURE TRIM DTOC AS

Palavras reservadas no procedimentos ou funes;

podem

ser

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

- 27 ADVPL II

4.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: @!

- 28 ADVPL II

5. Programas de Atualizao
Os programas de atualizao de cadastros e digitao de movimentos seguem um padro que se apia no Dicionrio de Dados. Basicamente so trs os modelos mais utilizados: Modelo 1 ou AxCadastro: Para cadastramentos em Exemplo: Cadastro de Cliente. tela cheia.

Modelo 2:

Cadastramentos envolvendo apenas uma tabela, mas com um cabealho e, opcionalmente, um rodap e um corpo com quantidade ilimitada de linhas. Ideal para casos em que h dados que se repetem por vrios itens e que, por isso, so colocados no cabealho. Exemplo: Pedido de Compra.

Modelo 3:

Cadastramentos envolvendo duas tabelas, um com dados de cabealho e outro digitado em linhas com os itens. Exemplo: Pedido de Vendas, Oramento etc.

Todos os modelos so genricos, ou seja, o programa independe da tabela a ser tratada, bastando praticamente que se informe apenas o seu Alias. O resto obtido do Dicionrio de Dados (SX3).

- 29 ADVPL II

5.1.

Modelo1() ou AxCadastro()
de cadastro simples, com poucas opes de

O AxCadastro() uma funcionalidade customizao, a qual composta de:

Browse padro para visualizao das informaes da base de dados, de acordo com as configuraes do SX3 Dicionrio de Dados (campo browse). Funes de pesquisa, visualizao, incluso, alterao e excluso padres para visualizao de registros simples, sem a opo de cabealho e itens.

Sintaxe: AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt) Parmetros: cAlias cTitulo cVldExc cVldAlt Alias padro do sistema para utilizao, o qual deve estar definido no dicionrio de dados SX3. Ttulo da Janela Validao para Excluso Validao para Alterao

Exemplo: Funo AxCadastro()

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | XCADSA2 | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Exemplo de utilizao da funo AXCADASTRO() | |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/ User Function XCadSA2() Local Local Local Local cAlias cTitulo cVldExc cVldAlt := := := := "SA2" "Cadastro de Fornecedores" ".T." ".T."

dbSelectArea(cAlias) dbSetOrder(1) AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt) Return Nil

- 30 ADVPL II

Exerccio Desenvolver um AxCadastro para a tabela padro do ERP SB1: Produtos Exemplo: Funo de validao da alterao

/*/ +----------------------------------------------------------------------------| Funo | VLDALT | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Funo de validao de alterao para a AXCADASTRO() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function VldAlt(cAlias,nReg,nOpc) Local lRet Local aArea Local nOpcao := .T. := GetArea() := 0

nOpcao := AxAltera(cAlias,nReg,nOpc) If nOpcao == 1 MsgInfo(Aterao concluda com sucesso!) Endif RestArea(aArea) Return lRet Exemplo: Funo de validao da excluso

/*/ +----------------------------------------------------------------------------| Funo | VLDEXC | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Funo de validao de excluso para a AXCADASTRO() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------- 31 ADVPL II

/*/ User Function VldExc(cAlias,nReg,nOpc) Local lRet Local aArea Local nOpcao := .T. := GetArea() := 0

nOpcao := AxExclui(cAlias,nReg,nOpc) If nOpcao == 1 MsgInfo(Excluso concluda com sucesso!) Endif RestArea(aArea) Return lRet

Exerccio Implementar no AxCadastro as validaes de alterao e excluso.

- 32 ADVPL II

5.2.

Mbrowse()

A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de recursos mais aprimorados na visualizao e manipulao das informaes do sistema, possuindo os seguintes componentes: Browse padro para visualizao das informaes da base de dados, de acordo com as configuraes do SX3 Dicionrio de Dados (campo browse). Parametrizao para funes especficas para as aes de visualizao, incluso, alterao e excluso de informaes, o que viabiliza a manuteno de informaes com estrutura de cabealhos e itens. Recursos adicionais como identificadores de status de registros, legendas e filtros para as informaes. Sintaxe: MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias, aFixe, cCpo, nPar08, cFun, nClickDef, aColors, cTopFun, cBotFun, nPar14, bInitBloc, lNoMnuFilter, lSeeAll, lChgAll) Parmetros: nLin1 nCol1 nLin2 nCol2 cAlias Nmero da Linha Inicial Nmero da Coluna Inicial Nmero da Linha Final Nmero da Coluna Final Alias do arquivo que ser visualizado no browse. Para utilizar a funo MBrowse com arquivos de trabalho, o alias do arquivo de trabalho deve ser obrigatoriamente 'TRB' e o parmetro aFixe torna-se obrigatrio. Array bi-dimensional contendo os nomes dos campos fixos prdefinidos, obrigando a exibio de uma ou mais colunas ou a definio das colunas quando a funo utilizada com arquivos de trabalho. A estrutura do array diferente para arquivos que fazem parte do dicionrio de dados e para arquivos de trabalho. Arquivos que fazem parte do dicionrios de dados aFixe [n][1]=>Descrio do campo [n][2]=>Nome do campo Arquivos de trabalho [n][1]=>Descrio do campo [n][2]=>Nome do campo [n][3]=>Tipo [n][4]=>Tamanho [n][5]=>Decimal [n][6]=>Picture

- 33 ADVPL II

Parmetros: Campo a ser validado se est vazio ou no para exibio do bitmap de status. Quando esse parmetro utilizado, a primeira coluna do browse ser um bitmap indicando o status do registro, conforme as condies configuradas nos parmetros cCpo, cFun e aColors. Parmetro reservado. Funo que retornar um valor lgico para exibio do bitmap de status. Quando esse parmetro utilizado, o parmetro cCpo automaticamente desconsiderado. Nmero da opo do aRotina que ser executada quando for efetuado um duplo clique em um registro do browse. O default executar a rotina de visualizao. Array bi-dimensional para possibilitar o uso de diferentes bitmaps de status. [n][1]=>Funo que retornar um valor lgico para a exibio do bitmap [n][2]=>Nome do bitmap que ser exibido quando a funo retornar .T. (True). O nome do bitmap deve ser um resource do repositrio e quando esse parmetro utilizado os parmetros cCpo e cFun so automaticamente desconsiderados. Funo que retorna o limite superior do filtro baseado na chave de ndice selecionada. Esse parmetro deve ser utilizado em conjunto com o parmetro cBotFun. Funo que retorna o limite inferior do filtro baseado na chave de ndice selecionada. Esse parmetro deve ser utilizado em conjunto com o parmetro cTopFun. Parmetro reservado. Bloco de cdigo que ser executado no ON INIT da janela do browse. O bloco de cdigo receber como parmetro o objeto da janela do browse. Valor lgico que define se a opo de filtro ser exibida no menu da MBrowse. .T. => No exibe a opo no menu .F. => (default) Exibe a opo no menu. A opo de filtro na MBrowse est disponvel apenas para TopConnect. Identifica se o Browse dever mostrar todas as filiais. O valor default .F. ( False ), no mostra todas as filiais. Caso os parmetros cTopFun ou cBotFun sejam informados esse parmetro ser configurado automaticamente para .F. ( False ) Parmetro vlido partir da verso 8.11. A funo SetBrwSeeAll muda o valor default desse parmetro. Identifica se o registro de outra filial est autorizado para alteraes. O valor default .F. ( False ), no permite alterar registros de outras filiais. Quando esse parmetro est configurado para .T. ( True ), o parmetro lSeeAll configurado automaticamente para .T. ( True ). Caso os parmetros cTopFun ou cBotFun sejam informados esse parmetro ser configurado automaticamente para .F. ( False ). Parmetro vlido partir da verso 8.11. A funo SetBrwChgAll muda o valor default desse parmetro.
- 34 ADVPL II

cCpo nPar08 cFun

nClickDef

aColors

cTopFun

cBotFun nPar14 bInitBloc

lNoMnuFilter

lSeeAll

lChgAll

Variveis private adicionais Array contendo as funes que sero executadas pela Mbrowse, nele ser definido o tipo de operao a ser executada (incluso, alterao, excluso, visualizao, pesquisa, etc. ), e sua estrutura composta de 5 (cinco) dimenses: [n][1] - Ttulo; [n][2] Rotina; [n][3] Reservado; [n][4] Operao (1 - pesquisa; 2 - visualizao; 3 - incluso; 4 alterao; 5 - excluso); Ele ainda pode ser parametrizado com as funes bsicas da AxCadastro conforme abaixo: AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" cCadastro ,"AxPesqui",0,1}) ,"AxVisual",0,2}) ,"AxInclui",0,3}) ,"AxAltera",0,4}) ,"AxDeleta",0,5})

aRotina

Ttulo do browse que ser exibido.

Informaes passadas para funes do aRotina: Ao definir as funes no array aRotina, se o nome da funo no for especificado com (), a Mbrowse passar como parmetros as seguintes variveis de controle: cAlias nReg nOpc Nome da rea de trabalho definida para a Mbrowse Recno do registro posicionado no Browse Posio da opo utilizada na Mbrowse de acordo com a ordem da funo no array a Rotina.

A posio das funes no array aRotina define o contedo de uma varivel de controle que ser repassada para as funes chamadas a partir da Mbrowse, convencionada como nOpc. Desta forma, para manter o padro da aplicao ERP a ordem a ser seguida na definio do aRotina : 1. 2. 3. 4. 5. 6. Pesquisar Visualizar Incluir Alterar Excluir Livre

- 35 ADVPL II

Exemplo: Funo Mbrowse() #include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | MBRWSA1 | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Exemplo de utilizao da funo MBROWSE() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function MBrwSA1() Local cAlias := "SA1" Private cCadastro := "Cadastro de Clientes" Private aRotina := {} AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" dbSelectArea(cAlias) dbSetOrder(1) mBrowse(6,1,22,75,cAlias) Return Nil ,"AxPesqui",0,1}) ,"AxVisual",0,2}) ,"AxInclui",0,3}) ,"AxAltera",0,4}) ,"AxDeleta",0,5})

Exemplo: Funo Inclui() substituindo a funo AxInclui() Chamada da Mbrowse()

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | MBRWSA1 | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Exemplo de utilizao da funo MBROWSE() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function MBrwSA1() Local cAlias := "SA1" Private cCadastro := "Cadastro de Clientes" Private aRotina := {} AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" ,"AxPesqui" ,0,1}) ,"AxVisual" ,0,2}) ,"U_Inclui" ,0,3})

- 36 ADVPL II

Exemplo (continuao): AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" dbSelectArea(cAlias) dbSetOrder(1) mBrowse(6,1,22,75,cAlias) Return Nil Exemplo: Funo Inclui() substituindo a funo AxInclui() Funo Inclui() ,"AxAltera" ,0,4}) ,"AxDeleta" ,0,5})

/*/ +----------------------------------------------------------------------------| Funo | INCLUI | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Funo de incluso especfica chamando a AXINCLUI() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function Inclui(cAlias, nReg, nOpc) Local cTudoOk := "(Alert('OK'),.T.)" Local nOpcao := 0 nOpcao := AxInclui(cAlias,nReg,nOpc,,,,cTudoOk) If nOpcao == 1 MsgInfo(Incluso concluda com sucesso!) ElseIf == 2 MsgInfo(Incluso cancelada!) Endif Return Nil

- 37 ADVPL II

Exemplo: Determinando a opo do aRotina pela informao recebida em nOpc #include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | EXCLUI | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Descrio| Funo de excluso especifica chamando a AxDeleta | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function Exclui(cAlias, nReg, nOpc) Local cTudoOk := "(Alert('OK'),.T.)" Local nOpcao := 0 nOpcao := AxDeleta(cAlias,nReg,aRotina[nOpc,4]) // Identifica corretamente a opo definida para o funo em aRotinas com mais // do que os 5 elementos padres. If nOpcao == 1 MsgInfo(Excluso realizada com sucesso!) ElseIf == 2 MsgInfo(Excluso cancelada!) Endif Return Nil

5.2.1.

AxFunctions()

Conforme mencionado nos tpicos sobre as interfaces padres AxCadastro() e Mbrowse(), existem funes padres da aplicao ERP que permitem a visualizao, incluso, alterao e excluso de dados em formato simples. Estas funes so padres na definio da interface AxCadastro() e podem ser utilizadas tambm da construo no array aRotina utilizado pela Mbrowse(), as quais esto listadas a seguir:

AXPESQUI() AXVISUAL() AXINCLUI() AXALTERA() AXDELETA()

- 38 ADVPL II

AXPESQUI() Sintaxe Descrio AXPESQUI() Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado na pesquisa e a digitao das informaes que compe a chave de busca.

AXVISUAL() Sintaxe Descrio AXINCLUI() Sintaxe Descrio AXALTERA() Sintaxe Descrio AxAltera(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized) Funo de alterao padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized) Funo de incluso padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,; aButtons, lMaximized ) Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro().

AXDELETA() Sintaxe Descrio AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,; aAuto, lMaximized) Funo de excluso padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro().

Exerccio Implementar uma MBrowse com as funes de cadastro padres para a tabela padro do ERP SB1: Produtos

- 39 ADVPL II

- 40 ADVPL II

5.2.2.

FilBrowse()

A FilBrowse() uma funcionalidade que permite a utilizao de filtros na MBrowse(). Sintaxe: FilBrowse(cAlias, aQuery, cFiltro, lShowProc) Parmetros: cAlias Alias ativo definido para a Mbrowse() Este parmetro dever ser inicializado sempre vazio e sua passagem obrigatoriamente por referncia, pois, seu retorno ser enviado para a funo EndFilBrw(). [1]=>Nome do Arquivo Fsico [2]=>Ordem correspondente ao Sindex cFiltro lShowProc Condio de filtro para a MBrowse() Habilita (.T.) ou desabilita (.F.) a apresentao da mensagem Selecionando registros ..., no processamento.

aQuery

5.2.3.

EndFilBrw()

A EndFilBrw() uma funcionalidade que permite eliminar o filtro e o arquivo temporrio criados pela FilBrowse(). Sintaxe: EndFilBrw(cAlias, aQuery) Parmetros: cAlias Alias ativo definido para a Mbrowse() Array de retorno passado por referncia para a FilBrowse(). aQuery [1]=>Nome do Arquivo Fsico [2]=>Ordem correspondente ao Sindex

- 41 ADVPL II

5.2.4.

PesqBrw()

A PesqBrw() uma funcionalidade que permite a pesquisa dentro da MBrowse(). Esta funo dever obrigatoriamente substituir a funo AxPesqui, no array do aRotina, sempre que for utilizada a funo FilBrowse(). Sintaxe: PesqBrw(cAlias , nReg, bBrwFilter) Parmetros: cAlias nReg bBrwFilter Alias ativo definido para a Mbrowse() Nmero do registro Bloco de Cdigo que contm a FilBrowse() Ex: bBrwFilter := { || FilBrowse(cAlias, aQuery, cFiltro, lShowProc) }

5.2.5.

BrwLegenda ()

A BrwLegenda() uma funcionalidade que permite a incluso de legendas na MBrowse(). Sintaxe: BrwLegenda(cCadastro , cTitulo, aLegenda) Parmetros: cCadastro cTitulo Mesma varivel utilizada para a MBrowse, que identifica o cadastro que est em uso no momento Ttulo (identificao) da Legenda Array contendo de definio da cor e do texto, explicativo sobre o que ela representa na MBrowse Ex: {{Cor,Texto}}

aLegenda

Lista de cores disponveis no Protheus BR_AMARELO BR_AZUL BR_BRANCO BR_CINZA BR_LARANJA BR_MARRON BR_VERDE BR_VERMELHO BR_PINK BR_PRETO

- 42 ADVPL II

Exemplo: Mbrowse() utilizando as funes acessrias

#Include "Protheus.ch" /*/ +----------------------------------------------------------------------------| Programa | MBrwSA2 | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Exemplo da MBrowse utilizando a tabela de Cadastro de | | | Fornecedores | +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ User Function MBrwSA2() Local cAlias := "SA2" Local aCores := {} Local cFiltra := "A2_FILIAL == '"+xFilial('SA2')+"' .And. A2_EST == 'SP'" Private Private Private Private cCadastro aRotina aIndexSA2 bFiltraBrw:= { := := := || "Cadastro de Fornecedores" {} {} FilBrowse(cAlias,@aIndexSA2,@cFiltra) } ,"PesqBrw" ,0,1}) ,"AxVisual" ,0,2}) ,"U_BInclui" ,0,3}) ,"U_BAltera" ,0,4}) ,"U_BDeleta" ,0,5}) ,"U_BLegenda" ,0,3})

AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" AADD(aRotina,{"Legenda"

/* -- CORES DISPONIVEIS PARA LEGENDA -BR_AMARELO BR_AZUL BR_BRANCO BR_CINZA BR_LARANJA BR_MARRON BR_VERDE BR_VERMELHO BR_PINK BR_PRETO */ AADD(aCores,{"A2_TIPO == 'F'" AADD(aCores,{"A2_TIPO == 'J'" AADD(aCores,{"A2_TIPO == 'X'" AADD(aCores,{"A2_TIPO == 'R'" AADD(aCores,{"Empty(A2_TIPO)" dbSelectArea(cAlias) dbSetOrder(1) ,"BR_VERDE" ,"BR_AMARELO" ,"BR_LARANJA" ,"BR_MARRON" ,"BR_PRETO" }) }) }) }) })

- 43 ADVPL II

Exemplo (continuao): //+-----------------------------------------------------------//| Cria o filtro na MBrowse utilizando a funo FilBrowse //+-----------------------------------------------------------Eval(bFiltraBrw) dbSelectArea(cAlias) dbGoTop() mBrowse(6,1,22,75,cAlias,,,,,,aCores) //+-----------------------------------------------//| Deleta o filtro utilizado na funo FilBrowse //+-----------------------------------------------EndFilBrw(cAlias,aIndexSA2) Return Nil //+--------------------------------------//|Funo: BInclui - Rotina de Incluso //+--------------------------------------User Function BInclui(cAlias,nReg,nOpc) Local nOpcao := 0 nOpcao := AxInclui(cAlias,nReg,nOpc) If nOpcao == 1 MsgInfo("Incluso efetuada com sucesso!") Else MsgInfo("Incluso cancelada!") Endif Return Nil //+----------------------------------------//|Funo: BAltera - Rotina de Alterao //+----------------------------------------User Function BAltera(cAlias,nReg,nOpc) Local nOpcao := 0 nOpcao := AxAltera(cAlias,nReg,nOpc) If nOpcao == 1 MsgInfo("Alterao efetuada com sucesso!") Else MsgInfo("Alterao cancelada!") Endif Return Nil

- 44 ADVPL II

Exemplo (continuao): //+----------------------------------------//|Funo: BDeleta - Rotina de Excluso //+----------------------------------------User Function BDeleta(cAlias,nReg,nOpc) Local nOpcao := 0 nOpcao := AxDeleta(cAlias,nReg,nOpc) If nOpcao == 1 MsgInfo("Excluso efetuada com sucesso!") Else MsgInfo("Excluso cancelada!") Endif Return Nil //+------------------------------------------//|Funo: BLegenda - Rotina de Legenda //+------------------------------------------User Function BLegenda() Local aLegenda := {} AADD(aLegenda,{"BR_VERDE" AADD(aLegenda,{"BR_AMARELO" AADD(aLegenda,{"BR_LARANJA" AADD(aLegenda,{"BR_MARRON" AADD(aLegenda,{"BR_PRETO" ,"Pessoa Fsica" }) ,"Pessoa Jurdica" ,"Exportao" ,"Fornecedor Rural" ,"No Classificado" }) }) }) })

BrwLegenda(cCadastro, "Legenda", aLegenda) Return Nil

Exerccio Implementar a legenda para a MBrowse da tabela padro do ERP SB1: Produtos

- 45 ADVPL II

5.3.

MarkBrowse()

A funo MarkBrow() permite que os elementos de um browse, sejam marcados ou desmarcados. Para utilizao da MarkBrow() necessrio declarar as variveis cCadastro e aRotina como Private, antes da chamada da funo. Sintaxe: MarkBrow (cAlias, cCampo, cCpo, aCampos, lInvert, cMarca, cCtrlM, uPar8, cExpIni, cExpFim, cAval, bParBloco) Parmetros: cAlias cCampo cCpo Alias ativo definido para a Mbrowse() Campo do arquivo onde ser feito o controle (gravao) da marca. Campo onde ser feita a validao para marcao e exibio do bitmap de status. Vetor de colunas a serem exibidas no browse, deve conter as seguintes dimenses: [n][1] [n][2] [n][3] [n][4] nome do campo; - Nulo (Nil); - Ttulo do campo; - Mscara (picture).

aCampos

lInvert cMarca cCtrlM uPar8 cExpIni cExpFim cAval bParBloco

Inverte a marcao. String a ser gravada no campo especificado para marcao. Funo a ser executada caso deseje marcar todos elementos. Parmetro reservado. Funo que retorna o contedo inicial do filtro baseada na chave de ndice selecionada. Funo que retorna o contedo final do filtro baseada na chave de ndice selecionada. Funo a ser executada no duplo clique em um elemento no browse. Bloco de cdigo a ser executado na inicializao da janela

Informaes passadas para funes do aRotina: Ao definir as funes no array aRotina, se o nome da funo no for especificado com (), a MarkBrowse passar como parmetros as seguintes variveis de controle: cAlias nReg nOpc cMarca lInverte Nome da rea de trabalho definida para a Mbrowse Recno do registro posicionado no Browse Posio da opo utilizada na Mbrowse de acordo com a ordem da funo no array a Rotina. Marca em uso pela MarkBrw() Indica se foi utilizada a inverso da seleo dos itens no browse.

- 46 ADVPL II

5.3.1.

Funes de Apoio

GetMark: define a marca atual. IsMark: avalia se um determinado contedo igual a marca atual. ThisMark: captura a marca em uso. ThisInv: indica se foi usado o recurso de selecionar todos (inverso). MarkBRefresh: atualiza exibio na marca do browse. Utilizada quando a marca colocada ou removida em blocos e no pelo clique. Exemplo: Funo MarkBrow() e acessrias

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Programa | MkBrwSA1 | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Desc. | MarkBrowse Genrico | +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ USER FUNCTION MkBrwSA1() Local Local Local Local aCpos aCampos nI cAlias := {} := {} := 0

:= "SA1"

Private aRotina := {} Private cCadastro := "Cadastro de Clientes" Private aRecSel := {} AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" AADD(aRotina,{"Visualizar Lote" AADD(aCpos,"A1_OK" AADD(aCpos,"A1_FILIAL" AADD(aCpos,"A1_COD" AADD(aCpos,"A1_LOJA" AADD(aCpos,"A1_NOME" AADD(aCpos,"A1_TIPO" ) ) ) ) ) ) ,"AxPesqui" ,0,1}) ,"AxVisual" ,0,2}) ,"AxInclui" ,0,3}) ,"AxAltera" ,0,4}) ,"AxDeleta" ,0,5}) ,"U_VisLote" ,0,5})

dbSelectArea("SX3") dbSetOrder(2) For nI := 1 To Len(aCpos) IF dbSeek(aCpos[nI])


- 47 ADVPL II

AADD(aCampos,{X3_CAMPO,"",IIF(nI==1,"",Trim(X3_TITULO)),; Trim(X3_PICTURE)}) Next ENDIF

DbSelectArea(cAlias) DbSetOrder(1) MarkBrow(cAlias,aCpos[1],"A1_TIPO == ' '",aCampos,.F.,GetMark(,"SA1","A1_OK")) Return Nil Exemplo: Funo VisLote() utilizao das funes acessrias da MarkBrow()

/*/ +----------------------------------------------------------------------------| Programa | VisLote() | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Desc. | Funo utilizada para demonstrar o uso do recurso da MarkBrowse| +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ USER FUNCTION VisLote() Local cMarca := ThisMark() Local nX := 0 Local lInvert := ThisInv() Local cTexto := "" Local cEOL := CHR(10)+CHR(13) Local oDlg Local oMemo DbSelectArea("SA1") DbGoTop() While SA1->(!EOF()) // IsMark("A1_OK", cMarca, lInverte) IF SA1->A1_OK == cMarca .AND. !lInvert AADD(aRecSel,{SA1->(Recno()),SA1->A1_COD, SA1->A1_LOJA, SA1->A1_NREDUZ}) ELSEIF SA1->A1_OK != cMarca .AND. lInvert AADD(aRecSel,{SA1->(Recno()),SA1->A1_COD,SA1->A1_LOJA, SA1->A1_NREDUZ}) ENDIF Enddo SA1->(dbSkip())

IF Len(aRecSel) > 0 cTexto := "Cdigo | Loja | Nome Reduzido "+cEol // "1234567890123456789012345678901234567890 // "CCCCCC | LL | NNNNNNNNNNNNNNNNNNNN +cEol For nX := 1 to Len(aRecSel) cTexto += aRecSel[nX][2]+Space(1)+ "|"+Space(2) + aRecSel[nX] [3]+Space(3)+"|" cTexto += Space(1)+SUBSTRING(aRecSel[nX][4],1,20)+Space(1) cTexto += cEOL

- 48 ADVPL II

Next nX DEFINE MSDIALOG oDlg TITLE "Clientes Selecionados" From 000,000 TO 350,400 PIXEL @ 005,005 GET oMemo VAR cTexto MEMO SIZE 150,150 OF oDlg PIXEL oMemo:bRClicked := {||AllwaysTrue()} DEFINE SBUTTON FROM 005,165 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg PIXEL ACTIVATE MSDIALOG oDlg CENTER LimpaMarca() ENDIF RETURN Exemplo: Funo LimpaMarca() utilizao das funes acessrias da MarkBrow()

/*/ +----------------------------------------------------------------------------| Programa | LimpaMarca | Autor | ARNALDO RAYMUNDO JR. | Data | | +----------------------------------------------------------------------------| Desc. | Funo utilizada para demonstrar o uso do recurso da MarkBrowse| +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ STATIC FUNCTION LimpaMarca() Local nX := 0 For nX := 1 to Len(aRecSel) SA1->(DbGoto(aRecSel[nX][1])) RecLock("SA1",.F.) SA1->A1_OK := SPACE(2) MsUnLock() Next nX RETURN

Exerccio Implementar uma MarkBrowse com as funes de cadastro padres para a tabela padro do ERP SB1: Produtos

Exerccio Implementar na MarkBrowse da tabela padro SB1, uma funo para excluso de mltiplos itens selecionados no Browse. ERP SB1: Produtos

- 49 ADVPL II

Exerccio Implementar uma MarkBrowse para a tabela SA1, para visualizao de dados de mltiplos clientes selecionados

5.4.

Modelo2()

O nome Modelo 2 foi conceituado pela Microsiga por se tratar de um prottipo de tela para entrada de dados. Inicialmente vamos desmistificar dois pontos: Funo Modelo2() Trata-se de uma funo pronta que contempla o prottipo Modelo 2, porm, este um assunto que no iremos tratar aqui, visto que uma funcionalidade simples que quando necessrio intervir em algo na rotina no h muito recurso para tal. Prottipo Modelo 2 Trata-se de uma tela, como a figura abaixo, onde seu objetivo efetuar a manuteno em vrios registros de uma s vez. Por exemplo: efetuar o movimento interno de vrios produtos do estoque em um nico lote.

5.4.1.

Componentes de uma tela no formato Modelo 2

Objeto MsDialog() Deve ser utilizada como janela padro para entrada de dados, um tipo de objeto modal, ou seja, no permite que outra janela ativa receba dados enquanto esta estiver ativa.

- 50 ADVPL II

Toda vez que utilizar este comando o ADVPL exige que seja declarado a diretiva Include no cabealho do programa o arquivo Protheus.ch, isto porque o compilador precisar porque este comando trata-se de um pseudo cdigo e sua traduo ser feita na compilao. Vale lembrar tambm que este s ser acionado depois que instanciado e ativado por outro comando.

DEFINE MSDIALOG oDlg TITLE "Prottipo Modelo 2" FROM 0,0 TO 280,552 OF; oMainWnd PIXEL ACTIVATE MSDIALOG oDlg CENTER

Reparem que o comando DEFINE MSDIALOG instanciou e o comando ACTIVATE MSDIALOG ativa todos os objetos, ou seja, todo ou qualquer outro objeto que precisar colocar nesta janela ser preciso informar em qual objeto, para este caso sempre ser utilizada a varivel de objeto exportvel oDlg. Funo EnchoiceBar() Funo que cria uma barra de botes padro de Ok e Cancelar, permitindo a implementao de botes adicionais.

Sintaxe: ENCHOICEBAR( oDlg, bOk, bCancelar, [ lMensApag ] , [ aBotoes ] ) Parmetros: oDlg bOk bCancelar lMensApag aBotes Objeto Objeto Objeto Lgico Vetor Janela onde a barra ser criada. Bloco de cdigo executado quando clicado boto Ok. Bloco de cdigo executado quando clicado. Indica se ao clicar no boto Ok aparecer uma tela de confirmao de excluso. Valor padro falso. Vetor com informaes para criao de botes adicionais na barra. Seu formato {bitmap, bloco de cdigo, mensagem}.
- 51 ADVPL II

Figura: Prottipo Modelo2 Enchoice Objeto TPanel() Repare que para facilitar o desenvolvimento foi utilizado o objeto TPanel para ajudar o alinhamento dos objetos TSay e TGet, ou seja, a utilizao deste recurso permite que o programador no se preocupe com coordenadas complexas para deixar a unio dos objetos simtricos. Utilize o objeto TPanel quando desejar criar um painel esttico, onde podem ser criados outros controles com o objetivo de organizar ou agrupar componentes visuais. Sintaxe: TPanel():New([anRow], [anCol], [acText], [aoWnd], [aoFont], [alCentered], [lPar6], [anClrText], [anClrBack], [anWidth], [anHeight], [alLowered], [alRaised])

Parmetros: nRow nCol cText Numrico vertical em pixel. Numrico horizontal em pixel. Texto a ser exibido ao fundo.

- 52 ADVPL II

oWnd oFont lCentered lPar6 nClrText nClrBack nWidth nHeight lLowered lRaised

Objeto da janela ou controle onde ser criado o objeto. Caractersticas da fonte do texto que aparecer ao fundo. Exibe o texto do ttulo centralizado. Reservado. Cor do texto de controle. Cor do fundo de controle. Largura do controle em pixel. Altura do controle em pixel. Exibe o painel rebaixado em relao ao controle de fundo. Exibe a borda do controle rebaixado em relao ao controle de fundo.

Comando SAY - Objeto: TSay() O comando SAY ou objeto TSay exibe o contedo de texto esttico sobre uma janela. Sintaxe SAY:

@ 4,6 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1

Sintaxe TSay(): TSay():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 Numrico, opcional. Coordenada vertical em pixels ou caracteres. Numrico, opcional. Coordenada horizontal em pixels ou caracteres. Code-Block, 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.

- 53 ADVPL II

lPar15 lPar16 lPar17 lPar18 lPar19

Reservado. Reservado. Reservado. Reservado. Reservado.

- 54 ADVPL II

Comando MSGET - Objeto: TGet() O comando MsGet ou o objeto TGet utilizado para criar um controle que armazene ou altere 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. Sintaxe MSGET:

@ 3,192 MSGET dData PICTURE "99/99/99" SIZE 40,7 PIXEL OF oTPanel1

Sintaxe

TGet():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 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 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.
- 55 ADVPL II

aoWnd anWidth anHeight acPict abValid anClrFore anClrBack aoFont lPar12 oPar13 alPixel cPar15 lPar16 abWhen

lPar18

lPar19 abChange alReadOnly alPassword cPar23 acReadVar cPar25 lPar26 nPar27 lPar18

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.

Objeto MsGetDados() Objeto tipo lista com uma ou mais colunas para cadastramento de dados baseado em um vetor. Sua utilizao exige que seja utilizado trs variveis com seu escopo Private, so elas: aRotina, aHeader e aCOLS. Observaes importantes: O vetor aHeader deve ser construdo com base no dicionrio de dados. O vetor aCOLS deve ser construdo com base no vetor aHeader, porm devese criar uma coluna adicional para o controle de excluso do registro, ou seja, quando o usurio teclar a tecla <DELETE> a linha ficar na cor cinza e esta coluna estar com o seu valor igual a verdadeiro (.T.). Quando instanciado este objeto possvel saber em que linha o usurio est porque o objeto trabalha com uma varivel de escopo Public denominada n, seu valor numrico e ter sempre no contedo a linha em que o usurio encontra-se com o cursor.

- 56 ADVPL II

Sintaxe: MSGETDADOS():NEW( nSuperior, nEsquerda, nInferior, nDireita, nOpc, [ cLinhaOk ], [ cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter], , [ uPar1 ], [ lVazio ], [ nMax], [ cCampoOk ], [ cSuperApagar ], [ uPar2 ], [ cApagaOk ], [ oWnd ] ) Parmetros: nSuperior nEsquerda nInferior nDireita nOpc cLinhaOk cTudoOk cIniCpos lApagar aAlter uPar1 lVazio nMax cCampoOk cSuperApagar uPar2 cApagaOk 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 deletar 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.

Varivel Private aRotina Array com as rotinas que sero executadas na MBrowse e que definir o tipo de operao que est sendo executada, por exemplo: Pesquisar, Visualizar, Incluir, Alterar, Excluir e outros. Este vetor precisa ser construdo no formato: Elemento 1 2 3 4 5 Contedo Ttulo da opo. Nome da rotina (Function). Reservado. Operao (1-Pesquisar;2-Visualizar;3-Incluir;4-Alterar;5-Excluso). Acesso relacionado a rotina, se est opo no for informada nenhum acesso ser validado.

- 57 ADVPL II

Varivel Private aHeader Array com informaes das colunas, ou seja, com as caractersticas dos campos que esto contidas no dicionrio de dados (SX3), este vetor precisa estar no formato abaixo: Elemento 1 2 3 4 5 6 7 8 9 10 Contedo Ttulo do campo Nome do campo Mscara do campo Tamanho do campo Decimal do campo Validao de usurio do campo Uso do campo Tipo do campo (caractere, numrico, data e etc.) Prefixo da tabela Contexto do campo (real ou virtual)

Varivel Private aCols Vetor com as linhas a serem editadas. As colunas devem ser construdas com base no vetor aHeader e mais uma ltima coluna com o valor lgico que determina se a linha foi excluda, inicialmente esta dever ter o seu contedo igual a falso (.F.).

- 58 ADVPL II

5.4.2.

Estrutura de um programa utilizando a Modelo2()

O exemplo abaixo demonstra a montagem de um programa para a utilizao do prottipo Modelo 2. Antes de iniciarmos o exemplo vamos estruturar o programa. Estrutura do programa
Linhas 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Programa Funo principal; Declarao e atribuio de variveis; Acesso a tabela principal e sua ordem; Chamada da funo MBrowse; Fim da funo principal. Funo de visualizao, alterao e excluso; Declarao e atribuio de variveis; Acesso ao primeiro registro da chave em que est posicionado na MBrowse; Montagem das variveis estticas em tela; Montagem do vetor aHeader por meio do dicionrio de dados; Montagem do vetor aCOLS de todos os registros referente a chave principal em que est posicionado na MBrowse; Instncia da MsDialog; Instncia dos objetos TSay e TGet; Instncia do objeto MsGetDados; Ativar o objeto principal que o objeto da janela; Se for operao diferente de visualizao e clicou no boto OK; A operao e de Alterao? Chamar a funo para alterar os dados; Caso contrrio Chamar a funo para excluir os dados; Fim da funo de visualizao, alterao e excluso. Funo de incluso; Declarao e atribuio de variveis; Montagem das variveis estticas em tela; Montagem do vetor aHeader por meio do dicionrio de dados; Montagem do vetor aCOLS com o seu contedo conforme o inicializador padro do campo ou vazio, pois trata-se de uma incluso; Instncia da MsDialog; Instncia dos objetos TSay e TGet; Instncia do objeto MsGetDados; Ativar o objeto principal que o objeto da janela; Se clicou no boto OK; Chamar a funo para incluir os dados; Fim da funo de incluso.

- 59 ADVPL II

Rotina principal

#include "protheus.ch" //+--------------------------------------------------------------------+ //| Rotina | xModelo2 | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Funo exemplo do prottipo Modelo2. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function xModelo2() Private cCadastro := "Prottipo Modelo 2" Private aRotina := {} AADD( AADD( AADD( AADD( AADD( aRotina, aRotina, aRotina, aRotina, aRotina, {"Pesquisar" {"Visualizar" {"Incluir" {"Alterar" {"Excluir" ,"AxPesqui" ,0,1}) ,'U_Mod2Mnt',0,2}) ,'U_Mod2Inc',0,3}) ,'U_Mod2Mnt',0,4}) ,'U_Mod2Mnt',0,5})

dbSelectArea("ZA3") dbSetOrder(1) dbGoTop() MBrowse(,,,,"ZA3") Return Rotina de incluso

//+--------------------------------------------------------------------+ //| Rotina | Mod2Inc | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para incluir dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod2Inc( cAlias, nReg, nOpc ) Local oDlg Local oGet Local oTPanel1 Local oTPAnel2 Local cCodigo := ZA3->ZA3_CODIGO Local cNome := ZA3->ZA3_NOME Local dData := dDataBase Private aHeader := {} Private aCOLS := {} Private aREG := {} dbSelectArea( cAlias ) dbSetOrder(1)

- 60 ADVPL II

Mod2aHeader( cAlias ) Mod2aCOLS( cAlias, nReg, nOpc ) DEFINE MSDIALOG oDlg TITLE cCadastro From 8,0 To 28,80 OF oMainWnd oTPanel1 := TPanel():New(0,0,"",oDlg,NIL,.T.,; .F.,NIL,NIL,0,16,.T.,.F.) oTPanel1:Align := CONTROL_ALIGN_TOP @ 4, 006 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1 @ 4, 062 SAY "Nome:" SIZE 70,7 PIXEL OF oTPanel1 @ 4, 166 SAY "Emissao:" SIZE 70,7 PIXEL OF oTPanel1 @ 3, 026 MSGET cCodigo F3 "SA3" PICTURE "@!" VALID; Mod2Vend(cCodigo, @cNome); SIZE 030,7 PIXEL OF oTPanel1 @ 3, 080 MSGET cNome When .F. SIZE 78,7 PIXEL OF oTPanel1 @ 3, 192 MSGET dData PICTURE "99/99/99" SIZE 40,7 PIXEL OF oTPanel1 oTPanel2 := TPanel():New(0,0,"",oDlg,NIL,.T.,; .F.,NIL,NIL,0,16,.T.,.F.) oTPanel2:Align := CONTROL_ALIGN_BOTTOM oGet := MSGetDados():New(0,0,0,0,nOpc,"U_Mod2LOk()",; ".T.","+ZA3_ITEM",.T.) oGet:oBrowse:Align := CONTROL_ALIGN_ALLCLIENT ACTIVATE MSDIALOG oDlg CENTER ON INIT ; EnchoiceBar(oDlg,{|| IIF(U_Mod2TOk(), Mod2GrvI(),; ( oDlg:End(), NIL ) )},{|| oDlg:End() }) Return Rotina de Visualizao, Alterao e Excluso

//+--------------------------------------------------------------------+ //| Rotina | Mod2Mnt | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para Visualizar, Alterar e Excluir dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod2Mnt( cAlias, nReg, nOpc ) Local Local Local Local oDlg oGet oTPanel1 oTPAnel2

Local cCodigo := Space(Len(Space(ZA3->ZA3_CODIGO))) Local cNome := Space(Len(Space(ZA3->ZA3_NOME))) Local dData := Ctod(Space(8))

- 61 ADVPL II

Private aHeader := {} Private aCOLS := {} Private aREG := {} dbSelectArea( cAlias ) dbGoTo( nReg ) cCodigo := ZA3->ZA3_CODIGO cNome := ZA3->ZA3_NOME cData := ZA3->ZA3_DATA Mod2aHeader( cAlias ) Mod2aCOLS( cAlias, nReg, nOpc ) DEFINE MSDIALOG oDlg TITLE cCadastro From 8,0 To 28,80 OF oMainWnd oTPane1 := TPanel():New(0,0,"",oDlg,NIL,.T.,; .F.,NIL,NIL,0,16,.T.,.F.) oTPane1:Align := CONTROL_ALIGN_TOP @ 4, 006 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1 @ 4, 062 SAY "Nome:" SIZE 70,7 PIXEL OF oTPanel1 @ 4, 166 SAY "Emissao:" SIZE 70,7 PIXEL OF oTPanel1 @ 3, 026 MSGET cCodigo When .F. SIZE 30,7 PIXEL OF oTPanel1 @ 3, 080 MSGET cNome When .F. SIZE 78,7 PIXEL OF oTPanel1 @ 3, 192 MSGET dData When .F. SIZE 40,7 PIXEL OF oTPanel1 oTPanel2 := TPanel():New(0,0,"",oDlg,NIL,.T.,; .F.,NIL,NIL,0,16,.T.,.F.) oTPanel2:Align := CONTROL_ALIGN_BOTTOM If nOpc == 4 oGet := MSGetDados():New(0,0,0,0,nOpc,"U_Mod2LOk()",; ".T.","+ZA3_ITEM",.T.) Else oGet := MSGetDados():New(0,0,0,0,nOpc) Endif oGet:oBrowse:Align := CONTROL_ALIGN_ALLCLIENT ACTIVATE MSDIALOG oDlg CENTER ON INIT ; EnchoiceBar(oDlg,{|| ( IIF( nOpc==4, Mod2GrvA(), ; IIF( nOpc==5, Mod2GrvE(), oDlg:End() ) ), oDlg:End() ) },; {|| oDlg:End() }) Return

- 62 ADVPL II

Montagem do array aHeader

//+--------------------------------------------------------------------+ //| Rotina | Mod2aHeader | Autor | Robson Luiz (rleg) |Data|01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para montar o vetor aHeader. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2aHeader( cAlias ) Local aArea := GetArea() dbSelectArea("SX3") dbSetOrder(1) dbSeek( cAlias ) While !EOF() .And. X3_ARQUIVO == cAlias If X3Uso(X3_USADO) .And. cNivel >= X3_NIVEL AADD( aHeader, { Trim( X3Titulo() ),; X3_CAMPO,; X3_PICTURE,; X3_TAMANHO,; X3_DECIMAL,; X3_VALID,; X3_USADO,; X3_TIPO,; X3_ARQUIVO,; X3_CONTEXT}) Endif dbSkip() End RestArea(aArea) Return Montagem do array aCols

//+--------------------------------------------------------------------+ //| Rotina | Mod2aCOLS | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para montar o vetor aCOLS. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2aCOLS( cAlias, nReg, nOpc ) Local aArea := GetArea() Local cChave := ZA3->ZA3_CODIGO Local nI := 0 If nOpc <> 3 dbSelectArea( cAlias ) dbSetOrder(1) dbSeek( xFilial( cAlias ) + cChave ) While !EOF() .And. ; ZA3->( ZA3_FILIAL + ZA3_CODIGO ) == xFilial( cAlias ) + cChave AADD( aREG, ZA3->( RecNo() ) )
- 63 ADVPL II

AADD( aCOLS, Array( Len( aHeader ) + 1 ) ) For nI := 1 To Len( aHeader ) If aHeader[nI,10] == "V" aCOLS[Len(aCOLS),nI] := CriaVar(aHeader[nI,2],.T.) Else aCOLS[Len(aCOLS),nI] := FieldGet(FieldPos(aHeader[nI,2])) Endif Next nI aCOLS[Len(aCOLS),Len(aHeader)+1] := .F. dbSkip() End Else AADD( aCOLS, Array( Len( aHeader ) + 1 ) ) For nI := 1 To Len( aHeader ) aCOLS[1, nI] := CriaVar( aHeader[nI, 2], .T. ) Next nI aCOLS[1, GdFieldPos("ZA3_ITEM")] := "01" aCOLS[1, Len( aHeader )+1 ] := .F. Endif Restarea( aArea ) Return Efetivao da incluso

//+--------------------------------------------------------------------+ //| Rotina | Mod2GrvI | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para gravar os dados na incluso. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2GrvI() Local aArea := GetArea() Local nI := 0 Local nX := 0 dbSelectArea("ZA3") dbSetOrder(1) For nI := 1 To Len( aCOLS ) If ! aCOLS[nI,Len(aHeader)+1] RecLock("ZA3",.T.) ZA3->ZA3_FILIAL := xFilial("ZA3") ZA3->ZA3_CODIGO := cCodigo ZA3->ZA3_DATA := dData For nX := 1 To Len( aHeader ) FieldPut( FieldPos( aHeader[nX, 2] ), aCOLS[nI, nX] ) Next nX MsUnLock() Endif Next nI RestArea(aArea) Return

- 64 ADVPL II

Efetivao da alterao

//+--------------------------------------------------------------------+ //| Rotina | Mod2GrvA | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para gravar os dados na alterao. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2GrvA() Local aArea := GetArea() Local nI := 0 Local nX := 0 dbSelectArea("ZA3") For nI := 1 To Len( aREG ) If nI <= Len( aREG ) dbGoTo( aREG[nI] ) RecLock("ZA3",.F.) If aCOLS[nI, Len(aHeader)+1] dbDelete() Endif Else RecLock("ZA3",.T.) Endif If !aCOLS[nI, Len(aHeader)+1] ZA3->ZA3_FILIAL := xFilial("ZA3") ZA3->ZA3_CODIGO := cCodigo ZA3->ZA3_DATA := dData For nX := 1 To Len( aHeader ) FieldPut( FieldPos( aHeader[nX, 2] ), aCOLS[nI, nX] ) Next nX Endif MsUnLock() Next nI RestArea( aArea ) Return

- 65 ADVPL II

Efetivao da excluso //+--------------------------------------------------------------------+ //| Rotina | Mod2GrvE | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para excluir os registros. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2GrvE() Local nI := 0 dbSelectArea("ZA3") For nI := 1 To Len( aCOLS ) dbGoTo(aREG[nI]) RecLock("ZA3",.F.) dbDelete() MsUnLock() Next nI Return Funo auxiliar: Validao do cdigo do vendedor //+--------------------------------------------------------------------+ //| Rotina | Mod2Vend | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para validar o cdigo do vendedor. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod2Vend( cCodigo, cNome ) If ExistCpo("SA3",cCodigo) .And. ExistChav("ZA3",cCodigo) cNome := Posicione("SA3",1,xFilial("SA3")+cCodigo,"A3_NOME") Endif Return(!Empty(cNome)) Funo auxiliar: Validao do cdigo do centro de custo na mudana de linha //+--------------------------------------------------------------------+ //| Rotina | Mod2LOk | Autor | Robson Luiz (rleg) | Data |01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para validar a linha de dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod2LOk() Local lRet := .T. Local cMensagem := "No ser permitido linhas sem o centro de custo." If !aCOLS[n, Len(aHeader)+1] If Empty(aCOLS[n,GdFieldPos("ZA3_CCUSTO")]) MsgAlert(cMensagem,cCadastro) lRet := .F. Endif Endif Return( lRet )

- 66 ADVPL II

Funo auxiliar: Validao do cdigo do centro de custo para todas as linhas

//+--------------------------------------------------------------------+ //| Rotina | Mod2TOk | Autor | Robson Luiz (rleg) | Data |01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para validar toda as linhas de dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod2TOk() Local lRet := .T. Local nI := 0 Local cMensagem := "No ser permitido linhas sem o centro de custo." For nI := 1 To Len( aCOLS ) If aCOLS[nI, Len(aHeader)+1] Loop Endif If !aCOLS[nI, Len(aHeader)+1] If Empty(aCOLS[n,GdFieldPos("ZA3_CCUSTO")]) MsgAlert(cMensagem,cCadastro) lRet := .F. Exit Endif Endif Next nI Return( lRet )

5.4.3.

Funo Modelo2()

A funo Modelo2() uma interface pr-definida pela Microsiga que implementa de forma padronizada os compontes necessrios a manipulao de estruturas de dados nas quais o cabealho e os itens da informao compartilham o mesmo registro fsico. Seu objetivo atuar como um facilitador de codificao, permitindo a utilizao dos recursos bsicos dos seguintes componentes visuais: MsDialog() TGet() TSay() MsNewGetDados() EnchoiceBar()

A funo Modelo2() no implementa as regras de visualizao, incluso, alterao e excluso, como uma AxCadastro() ou AxFunction(). A inicializao das variveis Private utilizada nos cabealhos e rodaps, bem como a inicializao e gravao do aCols devem ser realizadas pela rotina que suporta a execuo da Modelo2(). Da mesma forma, o Browse deve ser tratado por esta rotina, sendo comum a Modelo2() estar vinculada ao uso de uma MBrowse().
- 67 ADVPL II

Sintaxe: Modelo2([cTitulo], [aCab], [aRoda], [aGrid], [nOpc], [cLinhaOk], [cTudoOk]) Parmetros: cTitulo aCab Ttulo da janela Array contendo as informaes que sero exibidas no cabealho na forma de Enchoice() aCab[n][1] (Caractere) := Nome da varivel private que ser vinculada ao campo da Enchoice(). aCab[n][2] (Array) := Array com as coordenadas do campo na tela {Linha, Coluna} aCab[n][3] (Caractere) := Ttulo do campo na tela aCab[n][4] (Caractere) := Picture de formatao do get() do campo. aCab[n][5] (Caractere) := Funo de validao do get() do campo. aCab[n][6] (Caractere) := Nome da consulta padro que ser executada para o campo via tecla F3 aCab[n][7] (Lgico) := Se o campo estar livre para digitao. Array contendo as informaes que sero exibidas no cabealho na forma de Enchoice(), no mesmo formato que o aCab. Array contendo as coordenadas da GetDados() na tela. Padro := {44,5,118,315} Opo selecionada na MBrowse, ou que deseje ser passada para controle da Modelo2, aonde: 2 Visualizar 3 - Incluir 4 - Alterar 5 - Excluir Funo para validao da linha na GetDados() Funo para validao na confirmao da tela de interface da Modelo2().

aRoda aGrid nOpc

cLinhaOk cTudoOk Retorno: Lgico

Indica se a tela da interface Modelo2() foi confirmada ou cancelada pelo usurio.

- 68 ADVPL II

Exemplo: Utilizao da Modelo2() para visualizao do Cadastro de Tabelas (SX5)

#include "protheus.ch" //+--------------------------------------------------------------------+ //| Rotina | MBRW2SX5| Autor | ARNALDO RAYMUNDO JR. | Data |01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | UTILIZACAO DA MODELO2() PARA VISUALIZAO DO SX5. | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ USER FUNCTION MBrw2Sx5() Local cAlias := "SX5"

Private cCadastro := "Arquivo de Tabelas" Private aRotina := {} Private cDelFunc := ".T." // Validacao para a exclusao. Pode-se utilizar ExecBlock AADD(aRotina,{"Pesquisar" AADD(aRotina,{"Visualizar" AADD(aRotina,{"Incluir" AADD(aRotina,{"Alterar" AADD(aRotina,{"Excluir" dbSelectArea(cAlias) dbSetOrder(1) mBrowse( 6,1,22,75,cAlias) Return USER FUNCTION SX52INC(cAlias,nReg,nOpc) //Local nUsado := 0 Local cTitulo := "Inclusao de itens - Arquivo de Tabelas" Local aCab := {} // Array com descricao dos campos do Cabecalho do Modelo 2 Local aRoda := {} // Array com descricao dos campos do Rodape do Modelo 2 Local aGrid := {80,005,050,300} //Array com coordenadas da GetDados no modelo2 - Padrao: {44,5,118,315} // Linha Inicial - Coluna Inicial - +Qts Linhas - +Qts Colunas : {080,005,050,300} Local cLinhaOk := "AllwaysTrue()" // Validacoes na linha da GetDados da Modelo 2 Local cTudoOk := "AllwaysTrue()" // Validacao geral da GetDados da Modelo 2 Local lRetMod2 := .F. // Retorno da funo Modelo2 - .T. Confirmou / .F. Cancelou Local nColuna := 0 // Variaveis para GetDados() Private aCols := {} Private aHeader := {} ,"AxPesqui" ,0,1}) ,"U_SX52Vis" ,0,2}) ,"U_SX52Inc" ,0,3}) ,"U_SX52Alt" ,0,4}) ,"U_SX52Exc" ,0,5})

- 69 ADVPL II

Exemplo (continuao): // Variaveis para campos da Enchoice() Private cX5Filial := xFilial("SX5") Private cX5Tabela := SPACE(5) // Montagem do array de cabealho // AADD(aCab,{"Varivel" ,{L,C} ,"Ttulo","Picture","Valid","F3",lEnable}) AADD(aCab,{"cX5Filial" ,{015,010} ,"Filial","@!",,,.F.}) AADD(aCab,{"cX5Tabela" ,{015,080} ,"Tabela","@!",,,.T.}) // Montagem do aHeader AADD(aHeader,{"Chave" ,"X5_CHAVE","@!",5,0,"AllwaysTrue()",; "","C","","R"}) AADD(aHeader,{"Descricao" ,"X5_DESCRI","@!",40,0,"AllwaysTrue()",; "","C","","R"}) // Montagem do aCols aCols := Array(1,Len(aHeader)+1) // Inicializao do aCols For nColuna := 1 to Len(aHeader) If aHeader[nColuna][8] == "C" aCols[1][nColuna] := SPACE(aHeader[nColuna][4]) ElseIf aHeader[nColuna][8] == "N" aCols[1][nColuna] := 0 ElseIf aHeader[nColuna][8] == "D" aCols[1][nColuna] := CTOD("") ElseIf aHeader[nColuna][8] == "L" aCols[1][nColuna] := .F. ElseIf aHeader[nColuna][8] == "M" aCols[1][nColuna] := "" Endif Next nColuna aCols[1][Len(aHeader)+1] := .F. // Linha no deletada lRetMod2 := Modelo2(cTitulo,aCab,aRoda,aGrid,nOpc,cLinhaOk,cTudoOk) IF lRetMod2 //MsgInfo("Voc confirmou a operao","MBRW2SX5") For nLinha := 1 to len(aCols) // Campos de Cabealho Reclock("SX5",.T.) SX5->X5_FILIAL := cX5Filial SX5->X5_TABELA := cX5Tabela // Campos do aCols //SX5->X5_CHAVE := aCols[nLinha][1] //SX5->X5_DESCRI := aCols[nLinha][2] For nColuna := 1 to Len(aHeader) SX5->&(aHeader[nColuna][2]) := aCols[nLinha][nColuna] Next nColuna MsUnLock() Next nLinha ELSE MsgAlert("Voc cancelou a operao","MBRW2SX5") ENDIF Return
- 70 ADVPL II

Exerccio Implementar uma Modelo2() para a tabela padro do ERP SX5: Arquivo de Tabelas

Exerccio Implementar as funes de Visualizao, Alterao e Excluso para a Modelo2 desenvolvida para o SX5.

Exerccio Implementar uma Modelo2() para a tabela padro do ERP SB1: Tabela de Produtos

- 71 ADVPL II

5.5.

Modelo3()

O nome Modelo 3, assim como a Modelo 2 foi conceituado pela Microsiga por se tratar de um prottipo de tela para entrada de dados. Inicialmente vamos desmistifica dois pontos: Funo Modelo3() Trata-se de uma funo pronta que contempla o prottipo Modelo 3, porm, este um assunto que no iremos tratar aqui, visto que uma funcionalidade simples que quando necessrio intervir em algo na rotina no h muito recurso para tal. Prottipo Modelo 3 Trata-se de uma tela, como a figura abaixo, onde seu objetivo efetuar a manuteno em vrios registros de uma s vez relacionada a outro registro de outra tabela, ou seja, aqui teremos o relacionamento de registros pai e filho, ento preciso se preocupar com este relacionamento. Por exemplo: efetuar a manuteno em um pedido de vendas, onde ter um registro em uma tabela referente cabea do pedido e outra tabela com os registros referentes aos itens deste pedido de vendas. Para ganharmos tempo no ser apresentado aqui toda a explicao e montagens para a funo EnchoiceBar, comando MsDialog, Say e MsGet e para os vetores aHeader e aCOLS, entretanto todos estes estaro na codificao do cdigo fonte. A figura abaixo mostra exatamente o que a tela prottipo Modelo 3:

Figura: Prottipo Modelo 3

- 72 ADVPL II

Este prottipo constitudo de MsDialog, EnchoiceBar, Enchoice, MsGetDados, Say e Get. Diante dos expostos at o momento houve um novo nome para ns, ele a funo Enchoice, o que ? Funo Enchoice() Objeto MsMGet() A funo Enchoice ou o objeto MsMGet so recursos baseados no dicionrio de dados para verificar campos obrigatrios, validaes, gatilhos, consulta padro e etc. Assim tambm para criar pastas de cadastros. Estes podem ser usados tanto com variveis de memrias com o escopo Private como diretamente os campos da tabela que se refere. A diferena entre a funo Enchoice e o objeto MsMGet que a funo no retorna o nome da varivel de objeto exportvel criado. A estrutura para montar um programa com o prottipo modelo 3 semelhante ao prottipo modelo 2, porm a diferena real a utilizao da funo Enchoice ou o objeto MsMGet, para este documento iremos trabalhar com a funo. Sintaxe: Enchoice( cAlias, nReg, nOpc, aAc, cOpc, cTextExclui, aAcho, aPos, aCpos, nNum, nColMens, cMensagem, cTudOk, oObj, lVirtual) Parmetros: cAlias nReg uPar1 uPar2 uPar3 aAcho aPos Alias do dados a serem cadastrados. Nmero do registro da tabela a ser editado. Parmetro reservado. Parmetro reservado. Parmetro reservado. Vetor com os campos que sero apresentados pela MsMGet. Vetor com as coordenadas onde a MsMGet ser criada no formato {coord. superior, coord. esquerda, coord. direita, coord. inferior}.Funo executada para validar o contexto da linha atual do aCols. Vetor com os campos que podero ser alterados. Parmetro reservado. Nome dos campos do tipo caracter que utilizaro incremento automtico. Este parmetro deve ser no formato +<nome do primeiro campo>+<nome do segundo campo>+.... Parmetro reservado. Parmetro reservado. Parmetro reservado. Objeto no qual a MsMGet ser criada. Parmetro reservado. Indica se ser usado variveis de memria ou os campos da tabela para cadastramento dos dados. Valor padro falso. Indica se a MsMGet ser apresentada com um objeto por linha (uma coluna). Valor padro falso. Parmetro reservado. Parmetro reservado. Indica se no ser usado as Pastas de Cadastro na MsMGet. Funo executada para validar a excluso de uma linha do aCols.

aCpos uPar4

uPar5 uPar6 uPar7 oWnd uPar8 lMemoria lColuna uPar9 lSemPastas

- 73 ADVPL II

Vale lembrar que ns programadores reaproveitamos muito o que j existe, isto para simplesmente ganharmos tempo, e no caso da utilizao da funo Enchoice preciso criar as variveis de memrias que levam o mesmo nome dos campos da tabela em questo. Por exemplo o campo A2_NOME da tabela SA2 (cadastro de fornecedores) quando queremos referenciar o campo usa-se o prefixo da tabela e o campo em questo, desta forma: SA2->A2_NOME

Agora quando queremos referenciar a uma varivel que est com o contedo do mesmo campo criamos outro recurso, desta forma:

M->A2_NOME E para criar variveis com o nome do campo utilizamos um cdigo de bloco (code-block) e mais um lao de leitura para atribuir valores iniciais a cada uma dela. Ento fica assim o procedimento:

Private bCampo

:= { |nField| Field(nField) }

E em outro momento aproveitamos est varivel bCampo para facilitar a atribuio, veja o exemplo abaixo : For nX := 1 To FCount() M->&( Eval( bCampo, nX ) ) := Atribuio inicial ou atribuio de valor Next nX

Ou seja, fazer para todos os campos, e a cada campo criar a varivel com a atribuio inicial ou atribuio de valor.

- 74 ADVPL II

5.5.1.

Estrutura de um programa utilizando a Modelo3()

O exemplo abaixo demonstra a montagem de um programa para a utilizao do prottipo Modelo 3. Antes de iniciarmos o exemplo vamos estruturar o programa. Estrutura do programa
Linhas 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Programa Funo principal; Declarao e atribuio de variveis; Acesso a tabela principal e sua ordem; Chamada da funo MBrowse; Fim da funo principal. Funo de visualizao, alterao e excluso; Declarao e atribuio de variveis; Acesso ao primeiro registro da chave em que est posicionado na MBrowse; Construo das variveis de memria M->???; Montagem do vetor aHeader por meio do dicionrio de dados; Montagem do vetor aCOLS de todos os registros referente a chave principal em que est posicionado na MBrowse; Instncia da MsDialog; Execuo da funo Enchoice; Instncia do objeto MsGetDados; Ativar o objeto principal que o objeto da janela; Se for operao diferente de visualizao e clicou no boto OK; A operao e de Alterao? Chamar a funo para alterar os dados; Caso contrrio Chamar a funo para excluir os dados; Fim da funo de visualizao, alterao e excluso. Funo de incluso; Declarao e atribuio de variveis; Construo das variveis de memria M->???; Montagem do vetor aHeader por meio do dicionrio de dados; Montagem do vetor aCOLS com o seu contedo conforme o inicializador padro do campo ou vazio, pois trata-se de uma incluso; Instncia da MsDialog; Instncia dos objetos TSay e TGet; Instncia do objeto MsGetDados; Ativar o objeto principal que o objeto da janela; Se clicou no boto OK; Chamar a funo para incluir os dados; Fim da funo de incluso.

- 75 ADVPL II

Rotina principal

//+--------------------------------------------------------------------+ //| Rotina | xModelo3 | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Funo exemplo do prottipo Modelo3. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ #Include "Protheus.ch" User Function xModelo3() Private cCadastro := "Prottipo Modelo 3" Private aRotina := {} Private oCliente Private oTotal Private cCliente := "" Private nTotal := 0 Private bCampo := {|nField| FieldName(nField) } Private Private Private Private Private aSize := {} aInfo := {} aObj := {} aPObj := {} aPGet := {}

// Retorna a rea til das janelas Protheus aSize := MsAdvSize() // Ser utilizado trs reas na janela // 1 - Enchoice, sendo 80 pontos pixel // 2 - MsGetDados, o que sobrar em pontos pixel para este objeto // 3 - Rodap que a prpria janela, sendo 15 pontos pixel AADD( aObj, { 100, 080, .T., .F. }) AADD( aObj, { 100, 100, .T., .T. }) AADD( aObj, { 100, 015, .T., .F. }) // Clculo automtico da dimenses dos objetos (altura/largura) em pixel aInfo := { aSize[1], aSize[2], aSize[3], aSize[4], 3, 3 } aPObj := MsObjSize( aInfo, aObj ) // Clculo automtico de dimenses dos objetos MSGET aPGet := MsObjGetPos( (aSize[3] - aSize[1]), 315, { {004, 024, 240, 270} } ) AADD( AADD( AADD( AADD( AADD( aRotina, aRotina, aRotina, aRotina, aRotina, {"Pesquisar" {"Visualizar" {"Incluir" {"Alterar" {"Excluir" ,"AxPesqui" ,0,1}) ,'U_Mod3Mnt',0,2}) ,'U_Mod3Inc',0,3}) ,'U_Mod3Mnt',0,4}) ,'U_Mod3Mnt',0,5})

dbSelectArea("ZA1") dbSetOrder(1) dbGoTop() MBrowse(,,,,"ZA1") Return

- 76 ADVPL II

Funo de Incluso

//+--------------------------------------------------------------------+ //| Rotina | Mod3Inc | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para incluir dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod3Inc( cAlias, nReg, nOpc ) Local oDlg Local oGet Local nX := 0 Local nOpcA := 0 Private Private Private Private aHeader := {} aCOLS := {} aGets := {} aTela := {}

dbSelectArea( cAlias ) dbSetOrder(1) For nX := 1 To FCount() M->&( Eval( bCampo, nX ) ) := CriaVar( FieldName( nX ), .T. ) Next nX Mod3aHeader() Mod3aCOLS( nOpc ) DEFINE MSDIALOG oDlg TITLE cCadastro FROM ; aSize[7],aSize[1] TO aSize[6],aSize[5] OF oMainWnd PIXEL EnChoice( cAlias, nReg, nOpc, , , , , aPObj[1]) // Atualizao do nome do cliente @ aPObj[3,1],aPGet[1,1] SAY "Cliente: " SIZE 70,7 OF oDlg PIXEL @ aPObj[3,1],aPGet[1,2] SAY oCliente VAR cCliente SIZE 98,7 OF oDlg PIXEL // Atualizao do total @ aPObj[3,1],aPGet[1,3] SAY "Valor Total: " SIZE 70,7 OF oDlg PIXEL @ aPObj[3,1],aPGet[1,4] SAY oTotal VAR nTotal ; PICT "@E 9,999,999,999.99" SIZE 70,7 OF oDlg PIXEL oGet := MSGetDados():New(aPObj[2,1],aPObj[2,2],aPObj[2,3],aPObj[2,4],; nOpc,"U_Mod3LOk()",".T.","+ZA2_ITEM",.T.) ACTIVATE MSDIALOG oDlg ON INIT EnchoiceBar(oDlg,; {|| IIF( Mod3TOk().And.Obrigatorio( aGets, aTela ), ( nOpcA := 1, oDlg:End() ), NIL) },; {|| oDlg:End() }) If nOpcA == 1 .And. nOpc == 3 Mod3Grv( nOpc ) ConfirmSXE() Endif Return

- 77 ADVPL II

Funo de Visualizao, Alterao e Excluso

//+--------------------------------------------------------------------+ //| Rotina | Mod3Mnt | Autor | Robson Luiz (rleg) | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para Visualizar, Alterar e Excluir dados. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod3Mnt( cAlias, nReg, nOpc ) Local oDlg Local oGet Local nX := 0 Local nOpcA := 0 Private aHeader := {} Private aCOLS := {} Private aGets := {} Private aTela := {} Private aREG := {} dbSelectArea( cAlias ) dbSetOrder(1) For nX := 1 To FCount() M->&( Eval( bCampo, nX ) ) := FieldGet( nX ) Next nX Mod3aHeader() Mod3aCOLS( nOpc ) DEFINE MSDIALOG oDlg TITLE cCadastro FROM ; aSize[7],aSize[1] TO aSize[6],aSize[5] OF oMainWnd PIXEL EnChoice( cAlias, nReg, nOpc, , , , , aPObj[1]) // Atualizao do nome do cliente @ aPObj[3,1],aPGet[1,1] SAY "Cliente: " SIZE 70,7 OF oDlg PIXEL @ aPObj[3,1],aPGet[1,2] SAY oCliente VAR cCliente SIZE 98,7 OF oDlg PIXEL // Atualizao do total @ aPObj[3,1],aPGet[1,3] SAY "Valor Total: " SIZE 70,7 OF oDlg PIXEL @ aPObj[3,1],aPGet[1,4] SAY oTotal VAR nTotal PICTURE ; "@E 9,999,999,999.99" SIZE 70,7 OF oDlg PIXEL U_Mod3Cli() oGet := MSGetDados():New(aPObj[2,1],aPObj[2,2],aPObj[2,3],aPObj[2,4],; nOpc,"U_Mod3LOk()",".T.","+ZA2_ITEM",.T.) ACTIVATE MSDIALOG oDlg ON INIT EnchoiceBar(oDlg,; {|| IIF( Mod3TOk().And.Obrigatorio( aGets, aTela ), ( nOpcA := 1, oDlg:End() ), NIL ) },; {|| oDlg:End() }) If nOpcA == 1 .And. ( nOpc == 4 .Or. nOpc == 5 ) Mod3Grv( nOpc, aREG ) Endif Return

- 78 ADVPL II

Funo para montar o vetor aHeader

//+--------------------------------------------------------------------+ //| Rotina | Mod3aHeader | Autor | Robson Luiz (rleg) |Data|01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para montar o vetor aHeader. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod3aHeader() Local aArea := GetArea() dbSelectArea("SX3") dbSetOrder(1) dbSeek("ZA2") While !EOF() .And. X3_ARQUIVO == "ZA2" If X3Uso(X3_USADO) .And. cNivel >= X3_NIVEL AADD( aHeader, { Trim( X3Titulo() ),; X3_CAMPO,; X3_PICTURE,; X3_TAMANHO,; X3_DECIMAL,; X3_VALID,; X3_USADO,; X3_TIPO,; X3_ARQUIVO,; X3_CONTEXT}) Endif dbSkip() End RestArea(aArea) Return Funo para montar o vetor aCols

//+--------------------------------------------------------------------+ //| Rotina | Mod3aCOLS | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para montar o vetor aCOLS. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod3aCOLS( nOpc ) Local aArea := GetArea() Local cChave := "" Local cAlias := "ZA2" Local nI := 0 If nOpc <> 3 cChave := ZA1->ZA1_NUM dbSelectArea( cAlias ) dbSetOrder(1) dbSeek( xFilial( cAlias ) + cChave )
- 79 ADVPL II

Continuao: While !EOF() .And. ZA2->( ZA2_FILIAL + ZA2_NUM ) == xFilial( cAlias ) + cChave AADD( aREG, ZA2->( RecNo() ) ) AADD( aCOLS, Array( Len( aHeader ) + 1 ) ) For nI := 1 To Len( aHeader ) If aHeader[nI,10] == "V" aCOLS[Len(aCOLS),nI] := CriaVar(aHeader[nI,2],.T.) Else aCOLS[Len(aCOLS),nI] := FieldGet(FieldPos(aHeader[nI,2])) Endif Next nI aCOLS[Len(aCOLS),Len(aHeader)+1] := .F. dbSkip() End Else AADD( aCOLS, Array( Len( aHeader ) + 1 ) ) For nI := 1 To Len( aHeader ) aCOLS[1, nI] := CriaVar( aHeader[nI, 2], .T. ) Next nI aCOLS[1, GdFieldPos("ZA2_ITEM")] := "01" aCOLS[1, Len( aHeader )+1 ] := .F. Endif Restarea( aArea ) Return Funo para atribuir o nome do cliente a varivel

//+--------------------------------------------------------------------+ //| Rotina | Mod3Cli | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para atualizar a varivel com o nome do cliente. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod3Cli() cCliente := Posicione( "SA1", 1, xFilial("SA1") + M->(ZA1_CLIENT + ZA1_LOJA), "A1_NREDUZ" ) oCliente:Refresh() Return(.T.)

- 80 ADVPL II

Funo para validar a mudana de linha na MsGetDados() //+--------------------------------------------------------------------+ //| Rotina | Mod3LOk | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para atualizar a varivel com o total dos itens. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ User Function Mod3LOk() Local nI := 0 nTotal := 0 For nI := 1 To Len( aCOLS ) If aCOLS[nI,Len(aHeader)+1] Loop Endif nTotal+=Round(aCOLS[nI,GdFieldPos("ZA2_QTDVEN")]*; aCOLS[nI,GdFieldPos("ZA2_PRCVEN")],2) Next nI oTotal:Refresh() Return(.T.) Funo para validar se todas as linhas esto preenchidas //+--------------------------------------------------------------------+ //| Rotina | Mod3TOk | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para validar os itens se foram preenchidos. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod3TOk() Local nI := 0 Local lRet := .T. For nI := 1 To Len(aCOLS) If aCOLS[nI, Len(aHeader)+1] Loop Endif If Empty(aCOLS[nI,GdFieldPos("ZA2_PRODUT")]) .And. lRet MsgAlert("Campo PRODUTO preenchimento obrigatorio",cCadastro) lRet := .F. Endif If Empty(aCOLS[nI,GdFieldPos("ZA2_QTDVEN")]) .And. lRet MsgAlert("Campo QUANTIDADE preenchimento obrigatorio",cCadastro) lRet := .F. Endif If Empty(aCOLS[nI,GdFieldPos("ZA2_PRCVEN")]) .And. lRet MsgAlert("Campo PRECO UNITARIO preenchimento obrigatorio",cCadastro) lRet := .F. Endif If !lRet Exit Endif Next i Return( lRet )

- 81 ADVPL II

Funo para efetuar a gravao dos dados em ZA1 e ZA2 na incluso, alterao e excluso.

//+--------------------------------------------------------------------+ //| Rotina | Mod3Grv | Autor | Robson Luiz (rleg) |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Rotina para efetuar a gravao nas tabelas. | //+--------------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+--------------------------------------------------------------------+ Static Function Mod3Grv( nOpc, aAltera ) Local nX := 0 Local nI := 0 // Se for incluso If nOpc == 3 // Grava os itens dbSelectArea("ZA2") dbSetOrder(1) For nX := 1 To Len( aCOLS ) If !aCOLS[ nX, Len( aCOLS ) + 1 ] RecLock( "ZA2", .T. ) For nI := 1 To Len( aHeader ) FieldPut( FieldPos( Trim( aHeader[nI, 2] ) ), aCOLS[nX,nI] ) Next nI ZA2->ZA2_FILIAL := xFilial("ZA2") ZA2->ZA2_NUM := M->ZA1_NUM MsUnLock() Endif Next nX // Grava o Cabealho dbSelectArea( "ZA1" ) RecLock( "ZA1", .T. ) For nX := 1 To FCount() If "FILIAL" $ FieldName( nX ) FieldPut( nX, xFilial( "ZA1" ) ) Else FieldPut( nX, M->&( Eval( bCampo, nX ) ) ) Endif Next nX MsUnLock() Endif // Se for alterao If nOpc == 4 // Grava os itens conforme as alteraes dbSelectArea("ZA2") dbSetOrder(1) For nX := 1 To Len( aCOLS ) If nX <= Len( aREG ) dbGoto( aREG[nX] ) RecLock("ZA2",.F.) If aCOLS[ nX, Len( aHeader ) + 1 ] dbDelete() Endif Else

- 82 ADVPL II

Continuao: If !aCOLS[ nX, Len( aHeader ) + 1 ] RecLock( "ZA2", .T. ) Endif

Endif

If !aCOLS[ nX, Len(aHeader)+1 ] For nI := 1 To Len( aHeader ) FieldPut( FieldPos( Trim( aHeader[ nI, 2] ) ),; aCOLS[ nX, nI ] ) Next nI ZA2->ZA2_FILIAL := xFilial("ZA2") ZA2->ZA2_NUM := M->ZA1_NUM Endif MsUnLock() Next nX // Grava o Cabealho dbSelectArea("ZA1") RecLock( "ZA1", .F. ) For nX := 1 To FCount() If "FILIAL" $ FieldName( nX ) FieldPut( nX, xFilial("ZA1")) Else FieldPut( nX, M->&( Eval( bCampo, nX ) ) ) Endif Next MsUnLock()

Endif

// Se for excluso If nOpc == 5 // Deleta os Itens dbSelectArea("ZA2") dbSetOrder(1) dbSeek(xFilial("ZA2") + M->ZA1_NUM) While !EOF() .And. ZA2->(ZA2_FILIAL + ZA2_NUM) == xFilial("ZA2") +; M->ZA1_NUM RecLock("ZA2") dbDelete() MsUnLock() dbSkip() End // Deleta o Cabealho dbSelectArea("ZA1") RecLock("ZA1",.F.) dbDelete() MsUnLock() Endif Return

- 83 ADVPL II

5.5.2.

Funo Modelo3()

A funo Modelo3) uma interface pr-definida pela Microsiga que implementa de forma padronizada os compontes necessrios a manipulao de estruturas de dados nas quais o cabealho e os itens da informao esto em tabelas separadas. Seu objetivo atuar como um facilitador de codificao, permitindo a utilizao dos recursos bsicos dos seguintes componentes visuais: MsDialog() Enchoice() EnchoiceBar() MsNewGetDados()

A funo Modelo3() no implementa as regras de visualizao, incluso, alterao e excluso, como uma AxCadastro() ou AxFunction(). A inicializao dos campos utilizados na Enchoice() deve ser realizadas pela rotina que suporta a execuo da Modelo3(), normalmente atravs do uso da funo RegToMemory(). Da mesma forma, o Browse deve ser tratado por esta rotina, sendo comum a Modelo3() estar vinculada ao uso de uma MBrowse().

Sintaxe:

Modelo3 ([cTitulo], [cAliasE], [cAliasGetD], [cTudOk], [nOpcE], [nOpcG], [cFieldOk])

[aCposE],

[cLinOk],

Parmetros: cTitulo cAliasE cAliasGetD aCposE cLinhaOk cTudoOk Ttulo da janela Alias da tabela que ser utilizada na Enchoice Alias da tabela que ser utilizada na GetDados Nome dos campos, pertencentes ao Alias especificado o parmetro cAliasE, que devero ser exibidos na Enchoice: AADD(aCposE,{nome_campo}) Funo para validao da linha na GetDados() Funo para validao na confirmao da tela de interface da Modelo2(). Opo selecionada na MBrowse, ou que deseje ser passada para controle da Enchoice da Modelo3, aonde: 2 Visualizar 3 - Incluir 4 - Alterar 5 - Excluir Opo selecionada na MBrowse, ou que deseje ser passada para controle da GetDados da Modelo3, aonde: 2 Visualizar 3 - Incluir 4 - Alterar 5 - Excluir Validao dos campos da Enchoice()
- 84 ADVPL II

nOpcE

nOpcG

cFieldOk

Retorno: Lgico Indica se a tela da interface Modelo2() foi confirmada ou cancelada pelo usurio.

Exemplo: Utilizao da Modelo3() para Pedidos de Vendas (SC5,SC6)

#INCLUDE "protheus.ch" //+--------------------------------------------------------------------+ //| Rotina | MBRWMOD3| Autor | ARNALDO RAYMUNDO JR. |Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | EXEMPLO DE UTILIZACAO DA MODELO3(). | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ User Function MbrwMod3() Private cCadastro := "Pedidos de Venda" Private aRotina := {} Private cDelFunc := ".T." // Validacao para a exclusao. Pode-se utilizar ExecBlock Private cAlias := "SC5" AADD(aRotina,{ AADD(aRotina,{ AADD(aRotina,{ AADD(aRotina,{ AADD(aRotina,{ "Pesquisa","AxPesqui" ,0,1}) "Visual" ,"U_Mod3All" ,0,2}) "Inclui" ,"U_Mod3All" ,0,3}) "Altera" ,"U_Mod3All" ,0,4}) "Exclui" ,"U_Mod3All" ,0,5})

dbSelectArea(cAlias) dbSetOrder(1) mBrowse( 6,1,22,75,cAlias) Return User Function Mod3All(cAlias,nReg,nOpcx) Local Local Local Local Local Local Local Local cTitulo := cAliasE := cAliasG := cLinOk := cTudOk := cFieldOk:= aCposE := nUsado, nX "Cadastro de Pedidos de Venda" "SC5" "SC6" "AllwaysTrue()" "AllwaysTrue()" "AllwaysTrue()" {} := 0

- 85 ADVPL II

Exemplo (continuao): // // Opcoes de acesso para a Modelo 3 // Do Case Case nOpcx==3; nOpcE:=3 ; nOpcG:=3 // 3 - "INCLUIR" Case nOpcx==4; nOpcE:=3 ; nOpcG:=3 // 4 - "ALTERAR" Case nOpcx==2; nOpcE:=2 ; nOpcG:=2 // 2 - "VISUALIZAR" Case nOpcx==5; nOpcE:=2 ; nOpcG:=2 // 5 - "EXCLUIR" EndCase

// // Cria variaveis M->????? da Enchoice // RegToMemory("SC5",(nOpcx==3 .or. nOpcx==4 )) // Se for inclusao ou alteracao permite alterar o conteudo das variaveis de memoria // // Cria aHeader e aCols da GetDados // nUsado:=0 dbSelectArea("SX3") dbSeek("SC6") aHeader:={} While !Eof().And.(x3_arquivo=="SC6") If Alltrim(x3_campo)=="C6_ITEM" dbSkip() Loop Endif 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 nOpcx==3 // Incluir aCols:={Array(nUsado+1)} aCols[1,nUsado+1]:=.F. For nX:=1 to nUsado aCols[1,nX]:=CriaVar(aHeader[nX,2]) 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
- 86 ADVPL II

Exemplo (continuao): If Len(aCols)>0 // // Executa a Modelo 3 // aCposE := {"C5_CLIENTE"}

Endif

lRetMod3 := Modelo3(cTitulo, cAliasE, cAliasG, aCposE, cLinOk, cTudOk,; nOpcE, nOpcG,cFieldOk) // // Executar processamento // If lRetMod3 Aviso("Modelo3()","Confirmada operacao!",{"Ok"}) Endif

Return

Exerccio Implementar uma Modelo3() para as tabelas padres do ERP SF1: Cab. NFE e SD1: Itens NFE.

- 87 ADVPL II

6. Arquivos e ndices Temporrios 6.1. Utilizao de arquivos e ndices temporrios

Os arquivos e ndices temporrios ou de trabalho, so geralmente utilizados em ambiente CodeBase, pois, neste ambiente no h os recursos de Join e Order By, como existe nos bancos de dados relacionais. Por este motivo quando necessitar gerar uma informao ordenada e consolidada, ou seja, de vrias tabelas, deveremos recorrer ao uso dos arquivos e dos ndices temporrios.

6.2. 6.2.1.

Funes para manipulao de arquivos e ndices temporrios CriaTrab()

A CriaTrab() uma funcionalidade que permite criar um arquivo fsico ou gerar um nome aleatrio. Sintaxe: CriaTrab(aCampo, lCriar, cExt) Parmetros aCampo lCriar cExt Array com o nome, tipo, tamanho e decimal do campo a ser criado no arquivo Se verdadeiro (.T.) criar o arquivo, ou falso (.F.) somente retorna um nome aleatrio Qual extenso dever ser criado o arquivo de trabalho

Os arquivos criados com a funo CRIATRAB() sero gerados no diretrio especificado como StartPath, de acordo com o RootPath configurado no .ini da aplicao.

- 88 ADVPL II

6.2.2.

dbUseArea()

A dbUseArea() uma funcionalidade que permite definir um arquivo de base de dados, com uma rea de trabalho disponvel na aplicao. Sintaxe: dbUseArea(lNewArea, cDriver, cName, cAlias, lShared, lReadOnly) Parmetros lNewArea cDriver cName cAlias lShared lReadOnly Indica se e um novo alias no conjunto de alias aberto Drive (RddName()) do arquivo -> DBFCDX / TOPCONN / DBFNTX Nome fsico da tabela que ser usado Alias que ser usado enquanto estive aberto A tabela ter acesso exclusivo ou compartilhado Se verdadeiro a tabela ser somente leitura

6.2.3.

IndRegua()

A IndRegua() uma funcionalidade que permite criar ndices temporrios para o alias especificado, podendo ou no ter um filtro. Sintaxe: IndRegua(cAlias, cNIndex, cExpress, xOrdem, cFor, cMens, lShow) Parmetros cAlias cNIndex cExpress xOrdem cFor cMens lShow Alias da tabela onde ser efetuada o ndice/filtro temporrio Nome do arquivo de trabalho retornado pela funo CriaTrab() Expresso utilizada na chave do novo ndice Parmetro nulo Expresso utilizada para filtro Parmetro nulo Apresentar a tela de progresso do ndice/filtro temporrio

- 89 ADVPL II

6.3.

Funes Auxiliares para Arquivos de Trabalho e Temporrios

DbStruct() - Retorna um array com a estrutura de um Alias aberto no sistema: Exemplo: {campo,tipo,tamanho,decimal} RetIndex() - Retorna a quantidade de ndices ativa para um Alias aberto no sistema. DbSetIndex() - Agrega um arquivo de ndice a um Alias ativo no sistema. Caso seja um ndice temporrio gerado pela IndRegua, somente deve ser agregado se Database principal no for Top. OrdBagExt() - Retorna a extenso dos arquivos de ndices utilizados pelo sistema (.idx / .cdx / .ntx) Exemplo 01: Gerao de arquivo e ndice temporrios

#include protheus.ch /*/ +----------------------------------------------------------------------------| Programa | GeraTrab | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Desc. | Utilizao de arquivos e ndices temporrios | +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ User Function GeraTrab() Local Local Local Local Local AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD( aStru aArqTRB nI cIndTRB cNomArq aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru, { { { { { { { { { { { { { { { { { { { := := := := := {} {} 0 "" "" ,"B1_COD" ,"B1_DESC" ,"BM_GRUPO" ,"BM_DESC" ,"B1_TIPO" ,"B1_DESC" ,"CTT_CC" ,"CTT_DESC" ,"D2_SERIE" ,"D2_COD" ,"D2_TP" ,"D2_EMISSAO" ,"D2_CLIENTE" ,"D2_LOJA" ,"A1_NOME" ,"D2_QUANT" ,"D2_PRCVEN" ,"D2_TOTAL" ,"D2_PICM"
- 90 ADVPL II

"PRODUTO" "DESCRICAO" "GRUPO" "DESCGRUPO" "TIPO" "DESCTIPO" "CC" "DESC_CC" "SERIE" "DOCTO" "TIPONOTA" "EMISSAO" "CLIENTE" "LOJA" "NOME" "QTDE" "UNIT" "TOTAL" "ALIQICMS"

} } } } } } } } } } } } } } } } } } }

) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) )

AADD( AADD( AADD( AADD( AADD( AADD( AADD( AADD(

aStru, aStru, aStru, aStru, aStru, aStru, aStru, aStru,

{ { { { { { { {

"VALICMS" "ALIQIPI" "VALIPI" "VALMERC" "TOTSEMICMS" "VALPIS" "LIQUIDO" "CUSTO"

,"D2_VALICM" ,"D2_IPI" ,"D2_VALIPI" ,"D2_TOTAL" ,"D2_TOTAL" ,"D2_TOTAL" ,"D2_TOTAL" ,"D2_TOTAL"

} } } } } } } }

) ) ) ) ) ) ) )

dbSelectArea("SX3") dbSetOrder(2) For nI := 1 To Len( aStru ) dbSeek( aStru[nI,2] ) AADD( aArqTRB, { aStru[nI,1], X3_TIPO, X3_TAMANHO, X3_DECIMAL } ) Next nI // ndice que ser criado cIndTRB := "PRODUTO+DTOS(EMISSAO)" cNomArq := CriaTrab( aArqTRB, .T. ) dbUseArea( .T., "DBFCDX", cNomArq, "TRB", .T. ,.T. ) IndRegua( "TRB", cNomArq, cIndTRB ) dbSetOrder(1) // ( ... ) fazer o processamento necessrio dbSelectArea("TRB") dbCloseArea() If MsgYesNo("Apagar o arquivo gerado \system\"+cNomArq+".dbf ?",FunName()) Ferase(cNomArq+".dbf") Ferase(cNomArq+OrdBagExt()) Endif Return Nil Quando criamos um arquivo ou um ndice temporrio (trabalho), utilizando a funo Indregua, obrigatrio apag-los no final do rotina. A utilizao de arquivo ou ndice temporrio, dever ser bem analisada a fim de evitar lentido no processamentos da rotina. O array aStru foi criado com base nos campos existentes no sistema, ao invs de criarmos novas estruturas dos campos, utilizamos as j existentes no dicionrios de dados (SX3).

- 91 ADVPL II

Exemplo 02: Utilizando dois ndices temporrios com RDD DBFCDX

/*/ +----------------------------------------------------------------------------| Programa | IndTwoReg | Autor | MICHEL DANTAS | Data | | +----------------------------------------------------------------------------| Desc. | Utilizao de dois ndices temporrios com DBFCDX | +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ User Function IndTwoReg() LOCAL LOCAL LOCAL LOCAL LOCAL nOrder cArq1 cChave1 cArq2 cChave2 := := := := := 0 CriaTrab(NIL,.F.) "A1_FILIAL+A1_EST" CriaTrab(NIL,.F.) "A1_FILIAL+A1_NOME"

dbSelectArea("SA1") IndRegua("SA1",cArq1,cChave1,,,"Selecionando Regs...") IndRegua("SA1",cArq2,cChave2,,,"Selecionando Regs...") nOrder := RetIndex("SA1") dbSetIndex(cArq1+OrdBagExt()) dbSetIndex(cArq2+OrdBagExt()) Alert("Agora vai por estado") dbsetOrder(nOrder+1) dbGoTop() While !Eof() Alert("Estado : " + SA1->A1_EST +" dbSkip() End Alert("Agora vai por nome") dbSetOrder(nOrder+2) dbGoTop() While !Eof() Alert("Estado : " + SA1->A1_EST +" dbSkip() End RetIndex("SA1") Ferase(cArq1+OrdBagext()) Ferase(cArq2+OrdBagext()) Return

"+" Nome

: " + SA1->A1_NOME)

"+" Nome

: " + SA1->A1_NOME)

- 92 ADVPL II

Exerccio Implementar uma rotina que crie um arquivo de trabalho com uma estrutura similar ao SA1, e que receba as informaes desta tabela.

Exerccio Implementar uma rotina que crie um arquivo de trabalho com uma estrutura similar ao SB1, e que receba as informaes desta tabela.

- 93 ADVPL II

7. Relatrios no grficos
Os relatrios desenvolvidos em ADVPL possuem um padro de desenvolvimento que mais depende de layout e tipos de parmetros do que qualquer outro tipo de informao, visto que at o momento percebemos que a linguagem padro da Microsiga muito mais composta de funes genricas do que de comandos. Este tipo de relatrio caracterizado por um formato de impresso tipo PostScript, e permite a gerao de um arquivo em formato texto (.txt), com uma extenso prpria da aplicao ERP (.##R). A estrutura de um relatrio no grfico baseada no uso da funo SetPrint(), complementada pelo uso de outras funes acessrias, as quais esto detalhadas no Guia de Referncia Rpida que acompanha este material.

7.1. 7.1.1.

Funes Utilizadas para Desenvolvimento de Relatrios SetPrint()

A funo que cria a interface com as opes configurao para impresso de um relatrio no formato texto. Basicamente duas variveis m_pag e aReturn precisam ser declaradas como privadas (private) antes de executar a SetPrint(). 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 cProgram cPergunte cTitle cDesc1 cDesc2 cDesc3 lDic aOrd lCompres Alias do arquivo a ser impresso. Nome do arquivo a ser gerado em disco. Grupo de perguntas cadastrado no dicionrio SX1. Ttulo do relatrio. Descrio do relatrio. Continuao da descrio do relatrio. Continuao da descrio do relatrio. Utilizado na impresso de cadastro genrico permite a escolha dos campos a serem impressos. Se o parametro cAlias no for informado o valor padro assumido ser .F. Ordem(s) de impresso. Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro assumido ser .T.

- 94 ADVPL II

cSize uParm12 lFilter lCrystal cNameDrv uParm16 lServer cPortPrint Retorno: Caracter

Tamanho do relatrio "P","M" ou "G". Parmetro reservado Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro assumido ser .T. Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro assumido ser .F. Nome de um driver de impresso. Parmetro reservado. Se verdadeiro (.T.) fora impresso no servidor. Define uma porta de impresso padro.

Nome do Relatrio

Estrutura aReturn: aReturn[1] aReturn[2] aReturn[3] aReturn[4] aReturn[5] aReturn[6] aReturn[7] aReturn[8] aReturn[x] Caracter, tipo do formulrio Numrico, opo de margem Caracter, destinatrio Numrico, formato da impresso Numrico, dispositivo de impresso Caracter, driver do dispositivo de impresso Caracter, filtro definido pelo usurio Numrico, ordem 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().

7.1.2.

SetDefault()

A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes configuradas no array aReturn, obtidas atravs da funo SetPrint(). Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] , [cSize] , [ nFormat ] )

Parmetros: aReturn cAlias uParm3 uParm4 cSize nFormat Configuraes de impresso. Alias do arquivo a ser impresso. Parmetro reservado. Parmetro reservado. Tamanho da pgina "P","M" ou "G" Formato da pgina, 1 retrato e 2 paisagem.

- 95 ADVPL II

Estrutura aReturn: aReturn[1] aReturn[2] aReturn[3] aReturn[4] aReturn[5] aReturn[6] aReturn[7] aReturn[8] aReturn[x] Caracter, tipo do formulrio Numrico, opo de margem Caracter, destinatrio Numrico, formato da impresso Numrico, dispositivo de impresso Caracter, driver do dispositivo de impresso Caracter, filtro definido pelo usurio Numrico, ordem 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().

7.1.3.

RptStatus()

Rgua de processamento simples, com apenas um indicador de progresso, utilizada no processamento de relatrios do padro SetPrint(). Sintaxe: RptStatus(bAcao, cMensagem) Parmetros: bAcao cMensagem Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento. Mensagem que ser exibida na rgua de processamento durante a execuo.

7.1.3.1.

SETREGUA()

A funo SetRegua() utilizada para definir o valor mximo da rgua de progresso criada atravs da funo RptStatus(). Sintaxe: SetRegua(nMaxProc) Parmetros: nMaxProc Varivel que indica o valor mximo de processamento (passos) que sero indicados pela rgua.

- 96 ADVPL II

7.1.3.2.

INCREGUA()

A funo IncRegua() utilizada para incrementar valor na rgua de progresso criada atravs da funo RptStatus() Sintaxe: IncRegua(cMensagem) Parmetros: cMensagem Mensagem que ser exibida e atualizada na rgua de processamento a cada execuo da funo IncRegua(), sendo que a taxa de atualizao da interface controlada pelo Binrio.

7.1.4.

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 cCabec1 cCabec2 cNomeProg nTamanho nCompress aCustomText lPerg Ttulo do relatrio String contendo as informaes da primeira linha do cabealho String contendo as informaes da segunda linha do cabealho Nome do programa de impresso do relatrio. Tamanho do relatrio em colunas (80, 132 ou 220) Indica se impresso ser comprimida (15) ou normal (18). Texto especfico para o cabealho, substituindo a estrutura padro do sistema. Permite a supresso da impresso das perguntas do relatrio, mesmo que o parmetro MV_IMPSX1 esteja definido como S

Parmetros (continuao): cLogo Redefine o bitmap que ser impresso no relatrio, no necessitando que ele esteja no formato padro da Microsiga: "LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"

- 97 ADVPL II

7.1.5.

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. Sintaxe: Roda(uPar01, uPar02, cSize) Parmetros: uPar01 uPar02 cSize No mais utilizado No mais utilizado Tamanho do relatrio (P,M,G)

7.1.6.

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 |Ask cTitle Retorno: Lgico Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou cancelada (.F.) Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada. Indica se exibir a tela para edio. Ttulo do dilogo.

7.1.7.

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 aPergs Grupo de perguntas do SX1 (X1_GRUPO) Array contendo a estrutura dos campos que sero gravados no SX1.

Estrutura Item do array aPerg:


- 98 ADVPL II

Posio 01 02 03 04 05 06 07 08 09 10 11 12 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

Campo X1_PERGUNT X1_PERSPA X1_PERENG X1_VARIAVL X1_TIPO X1_TAMANHO X1_DECIMAL X1_PRESEL X1_GSC X1_VALID X1_VAR01 X1_DEF01 X1_DEFSPA1 X1_DEFENG1 X1_CNT01 X1_VAR02 X1_DEF02 X1_DEFSPA2 X1_DEFENG2 X1_CNT02 X1_VAR03 X1_DEF03 X1_DEFSPA3 X1_DEFENG3 X1_CNT03 X1_VAR04 X1_DEF04 X1_DEFSPA4 X1_DEFENG4 X1_CNT04 X1_VAR05 X1_DEF05 X1_DEFSPA5 X1_DEFENG5 X1_CNT05 X1_F3 X1_GRPSXG

Tipo Caractere Caractere Caractere Caractere Caractere Numrico Numrico Numrico Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere 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 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.

- 99 ADVPL II

38 39 40 41 42 43

X1_PYME X1_HELP X1_PICTURE aHelpPor aHelpEng aHelpSpa

Caractere Caractere Caractere Array Array Array

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.

7.1.8.

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 cOrdem cPergunt cPerSpa cPerEng cVar cTipo nTamanho nDecimal nPresel cGSC cValid cF3 cGrpSxg cPyme cVar01 cDef01 Grupo de perguntas do SX1 (X1_GRUPO) Ordem do parmetro no grupo (X1_ORDEM) Descrio da pergunta em portugus Descrio da pergunta em espanhol Descrio da pergunta em ingls Nome da varivel de controle auxiliar (X1_VARIAVL) 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 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 Nome da varivel MV_PAR+Ordem do parmetro. Descrio da opo 1 do combo em portugus
- 100 ADVPL II

cDefSpa1 cDefEng1 cCnt01 cDef0x cDefSpax cDefEngx aHelpPor aHelpEng aHelpSpa cHelp

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

- 101 ADVPL II

7.2.

Estrutura de Relatrios Baseados na SetPrint()

Neste tpico ser demonstrada a construo de relatrio no grfico baseado no uso da funo SetPrint() o qual atende os formatos de base de dados ISAM e Topconnect, porm no contemplando a tecnologia Protheus Embedded SQL. Estrutura do programa
Linhas 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 25 Programa Funo principal; Declarao e atribuio de variveis; Atualizao do arquivo de perguntas atravs da funo especfica CriaSX1(); Definio as perguntas atravs da funo Pergunte(); Definio das ordens disponveis para impresso do relatrio; Chamada da funo SetPrint; Atualizao das configuraes de impresso com a funo SetDefault(); Execuo da rotina de impresso atravs da funo RptStatus() Fim da funo principal. Funo de processamento e impresso do relatrio Declarao e atribuio de variveis; Definio dos filtros de impresso, avaliando o bando de dados em uso pela aplicao; Atualizao da rgua de processamento com a quantidade de registros que ser processada; Estrutura principal de repetio para impresso dos dados do relatrio; Controle da impresso do cabealho utilizando a funo Cabec(); Impresso dos totais do relatrio; Impresso do rodap da ltima pgina do relatrio utilizando a funo Roda(); Limpeza dos arquivos e ndices temporrios criados para o processamento(); Tratamento da visualizao do relatrio (impresso em disco) atravs da funo OurSpool() Tratamentos adicionais ao relatrio, de acordo com necessidades especficas; Liberao do buffer de impresso, seja para impressora, seja para limpeza do contedo visualizado em tela, utilizando a funo MS_FLUSH() Fim da funo de processamento e impresso do relatrio Funo de atualizao do arquivo de perguntas Declarao e atribuio de variveis; Opo 01: Adio individual de cada pergunta no SX1 utilizando a funo PUTSX1() Criao de um array individual no formato utilizado pela PUTSX1() contendo apenas as informaes da pergunta que ser adicionada no SX1. Opo 02: Adio de um grupo de perguntas no SX1 utilizando a funo AJUSTASX1() Criao de um array no formato utilizado pela AJUSTASX1() contendo todas as perguntas que sero atualizadas. Fim da funo de atualizao do arquivo de perguntas

26

Funo Principal

//+-----------------------------------------------------------------+ //| Rotina | Inform | Autor | Robson Luiz (rleg) | Data | 01.01.07 | //+-----------------------------------------------------------------+ //| Descr. | Rotina para gerar relatrio utilizando as funes | //| | SetPrint() e SetDefault(). | //+-----------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+-----------------------------------------------------------------+ User Function INFORM() //+------------------------//| Declaraes de variveis //+------------------------- 102 ADVPL II

Local cDesc1 conforme" Local cDesc2 Local cDesc3

:= "Este relatrio ir imprimir informaes do contas a pagar := "parmetros informado. Ser gerado um arquivo no diretrio " := "Spool - INFORM_????.XLS, onde ???? e o nome do usurio."

Private cString := "SE2" Private Tamanho := "M" Private aReturn := { "Zebrado",2,"Administrao",2,2,1,"",1 } Private wnrel := "INFORM" Private NomeProg := "INFORM" Private nLastKey := 0 Private Limite := 132 Private Titulo := "Ttulo a Pagar - Ordem de " Private cPerg := "INFORM" Private nTipo := 0 Private cbCont := 0 Private cbTxt := "registro(s) lido(s)" Private Li := 80 Private m_pag := 1 Private aOrd := {} Private Cabec1 := "PREFIXO TITULO PARCELA TIP EMISSAO VENCTO Private Cabec1 += "REAL VLR. ORIGINAL PAGO Private Cabec2 := "" /* +---------------------| Parmetros do aReturn +---------------------aReturn - Preenchido pelo SetPrint() aReturn[1] - Reservado para formulrio aReturn[2] - Reservado para numero de vias aReturn[3] - Destinatrio aReturn[4] - Formato 1=Paisagem 2=Retrato aReturn[5] - Mdia 1-Disco 2=Impressora aReturn[6] Porta ou arquivo 1-Lpt1... 4-Com1... aReturn[7] - Expresso do filtro aReturn[8] - Ordem a ser selecionada aReturn[9] [10] [n] - Campos a processar se houver */

VENCTO" SALDO "

Continuao: AADD( AADD( AADD( AADD( AADD( aOrd, aOrd, aOrd, aOrd, aOrd, "Fornecedor" "Titulo" "Emisso" "Vencimento" "Vencto. Real" ) ) ) ) )

//Parmetros de perguntas para o relatrio //+-------------------------------------------------------------+ //| mv_par01 - Fornecedor de ? 999999 | //| mv_par02 - Fornecedor ate ? 999999 | //| mv_par03 - Tipo de ? XXX | //| mv_par04 - Tipo ate ? XXX | //| mv_par05 - Vencimento de ? 99/99/99 | //| mv_par06 - Vencimento ate ? 99/99/99 | //| mv_par07 - Aglut.Fornecedor ? Sim/No |
- 103 ADVPL II

//+-------------------------------------------------------------+ CriaSx1() //+------------------------------------------------//| Disponibiliza para usurio digitar os parmetros //+------------------------------------------------Pergunte(cPerg,.F.) //cPerg -> Nome do grupo de perguntas, .T. mostra a tela,; // .F. somente carrega as variveis //+--------------------------------------------------//| Solicita ao usurio a parametrizao do relatrio. //+--------------------------------------------------wnrel := SetPrint(cString,wnrel,cPerg,@Titulo,cDesc1,cDesc2,cDesc3,.F.,aOrd,.F., ; Tamanho,.F.,.F.) //SetPrint(cAlias,cNome,cPerg,cDesc,cCnt1,cCnt2,cCnt3,lDic,aOrd,lCompres,; //cSize,aFilter,lFiltro,lCrystal,cNameDrv,lNoAsk,lServer,cPortToPrint) //+-------------------//| Se teclar ESC, sair //+-------------------If nLastKey == 27 Return Endif //+-----------------------------------------------------------------//| Estabelece os padres para impresso, conforme escolha do usurio //+-----------------------------------------------------------------SetDefault(aReturn,cString) //+------------------------------------//| Verificar se ser reduzido ou normal //+------------------------------------nTipo := IIF(aReturn[4] == 1, 15, 18) //+-------------------//| Se teclar ESC, sair //+-------------------If nLastKey == 27 Return Endif Continuao: //+----------------------------------//| Chama funo que processa os dados //+----------------------------------RptStatus({|lEnd| ImpRel(@lEnd) }, Titulo, "Processando e imprimindo dados,; aguarde...", .T. ) Return Funo de processamento e impresso

//+-----------------------------------------------------------------+ //| Rotina | ImpRel | Autor | Robson Luiz (rleg) | Data | 01.01.07 | //+-----------------------------------------------------------------+
- 104 ADVPL II

//| Descr. | Rotina de processamento e impresso. | //+-----------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+-----------------------------------------------------------------+ Static Function ImpRel(lEnd) Local Local Local Local Local Local Local Local Local Local Local Local Local Local Local nIndice := 0 cArq := "" cIndice := "" cFiltro := "" aCol := {} cFornec := "" nValor := 0 nPago := 0 nSaldo := 0 nT_Valor := 0 nT_Pago := 0 nT_Saldo := 0 cArqExcel := "" cAliasImp oExcelApp

Titulo += aOrd[aReturn[8]] #IFNDEF TOP cAliasImp := "SE2" cFiltro cFiltro cFiltro cFiltro cFiltro cFiltro cFiltro := += += += += += += "E2_FILIAL == '"+xFilial("SE2")+"' " ".And. E2_FORNECE >= '"+mv_par01+"' " ".And. E2_FORNECE <= '"+mv_par02+"' " ".And. E2_TIPO >= '"+mv_par03+"' " ".And. E2_TIPO <= '"+mv_par04+"' " ".And. Dtos(E2_VENCTO) >= '"+Dtos(mv_par05)+"' " ".And. Dtos(E2_VENCTO) <= '"+Dtos(mv_par06)+"' "

If aReturn[8] == 1 //Fornecedor cIndice := "E2_FORNECE+E2_LOJA+E2_NUM" Elseif aReturn[8] == 2 //Titulo cIndice := "E2_NUM+E2_FORNECE+E2_LOJA" Elseif aReturn[8] == 3 //Emissao Continuao: cIndice := "Dtos(E2_EMISSAO)+E2_FORNECE+E2_LOJA" Elseif aReturn[8] == 4 //Vencimento cIndice := "Dtos(E2_VENCTO)+E2_FORNECE+E2_LOJA" Elseif aReturn[8] == 5 //Vencimento Real cIndice := "Dtos(E2_VENCREA)+E2_FORNECE+E2_LOJA" Endif cArq := CriaTrab(NIL,.F.) dbSelectArea(cAliasImp) IndRegua(cAliasImp,cArq,cIndice,,cFiltro) nIndice := RetIndex() nIndice := nIndice + 1 dbSetIndex(cArq+OrdBagExt()) dbSetOrder(nIndice) #ELSE cAliasImp := GetNextAlias()
- 105 ADVPL II

cQuery := "SELECT " cQuery += "E2_PREFIXO, E2_NUM, E2_PARCELA, E2_TIPO, E2_FORNECE, E2_LOJA, E2_NOMFOR, " cQuery += "E2_EMISSAO, E2_VENCTO, E2_VENCREA, E2_VALOR, E2_SALDO " cQuery += "FROM "+RetSqlName("SE2")+" " cQuery += "WHERE E2_FILIAL = '"+xFilial("SE2")+"' " cQuery += "AND E2_FORNECE >= '"+mv_par01+"' " cQuery += "AND E2_FORNECE <= '"+mv_par02+"' " cQuery += "AND E2_TIPO >= '"+mv_par03+"' " cQuery += "AND E2_TIPO <= '"+mv_par04+"' " cQuery += "AND E2_VENCTO >= '"+Dtos(mv_par05)+"' " cQuery += "AND E2_VENCTO <= '"+Dtos(mv_par06)+"' " cQuery += "AND D_E_L_E_T_ <> '*' " cQuery += "ORDER BY " If aReturn[8] == 1 //Fornecedor cQuery += "E2_FORNECE,E2_LOJA,E2_NUM" Elseif aReturn[8] == 2 //Titulo cQuery += "E2_NUM,E2_FORNECE,E2_LOJA" Elseif aReturn[8] == 3 //Emissao cQuery += "E2_EMISSAO,E2_FORNECE,E2_LOJA" Elseif aReturn[8] == 4 //Vencimento cQuery += "E2_VENCTO,E2_FORNECE,E2_LOJA" Elseif aReturn[8] == 5 //Vencimento Real cQuery += "E2_VENCREA,E2_FORNECE,E2_LOJA" Endif dbUseArea( .T., "TOPCONN", TcGenQry(,,cQuery), cAliasImp, .T., .F. ) dbSelectArea(cAliasImp) /* Instruo SQL Embedded ---------------------If aReturn[8] == 1 //Fornecedor cOrder := "E2_FORNECE,E2_LOJA,E2_NUM" Elseif aReturn[8] == 2 //Titulo cOrder := "E2_NUM,E2_FORNECE,E2_LOJA" Elseif aReturn[8] == 3 //Emissao cOrder := "E2_EMISSAO,E2_FORNECE,E2_LOJA" Elseif aReturn[8] == 4 //Vencimento cOrder := "E2_VENCTO,E2_FORNECE,E2_LOJA" Continuao: Elseif aReturn[8] == 5 //Vencimento Real cOrder := "E2_VENCREA,E2_FORNECE,E2_LOJA" Endif BeginSQL Alias cAliasImp Column E2_EMISSAO As Column E2_VENCTO As Column E2_VENCREA As Column E2_VALOR As Column E2_SALDO As %NoParser% Date Date Date Numeric(12) Numeric(12)

SELECT E2_PREFIXO, E2_NUM, E2_PARCELA, E2_TIPO, E2_FORNECE, E2_LOJA, E2_NOMFOR, E2_EMISSAO, E2_VENCTO, E2_VENCREA, E2_VALOR, E2_SALDO
- 106 ADVPL II

FROM %Table:SE2 WHERE E2_FILIAL = %xFilial% AND E2_FORNECE BETWEEN %Exp:mv_par01% AND %Exp:mv_par02% AND E2_TIPO BETWEEN%Exp:mv_par03% AND %Exp:mv_par04% AND E2_VENCTO BETWEEN %Exp:mv_par05% AND %Exp:mv_par06% AND %NotDel% ORDER BY %Order:cOrder% EndSQL */ #ENDIF dbGoTop() SetRegua(0) //+-------------------//| Coluna de impresso //+-------------------AADD( aCol, 004 ) //Prefixo AADD( aCol, 012 ) //Titulo AADD( aCol, 024 ) //Parcela AADD( aCol, 031 ) //Tipo AADD( aCol, 036 ) //Emissao AADD( aCol, 046 ) //Vencimento AADD( aCol, 058 ) //Vencimento Real AADD( aCol, 070 ) //Valor Original AADD( aCol, 090 ) //Pago AADD( aCol, 110 ) //Saldo cFornec := (cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA While !Eof() .And. !lEnd If Li > 55 Cabec(Titulo,Cabec1,Cabec2,NomeProg,Tamanho,nTipo) Endif

Continuao: @ Li, aCol[1] PSay "Cod/Loj/Nome: "+(cAliasImp)->E2_FORNECE+; "-"+(cAliasImp)->E2_LOJA+" "+(cAliasImp)->E2_NOMFOR Li ++ While !Eof() .And. !lEnd .And.; (cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA == cFornec IncRegua() If Li > 55 Cabec(Titulo,Cabec1,Cabec2,NomeProg,Tamanho,nTipo) Endif If mv_par07 == 2 @ Li, aCol[1] PSay (cAliasImp)->E2_PREFIXO
- 107 ADVPL II

@ Li, aCol[2] PSay (cAliasImp)->E2_NUM @ Li, aCol[3] PSay (cAliasImp)->E2_PARCELA @ Li, aCol[4] PSay (cAliasImp)->E2_TIPO @ Li, aCol[5] PSay (cAliasImp)->E2_EMISSAO @ Li, aCol[6] PSay (cAliasImp)->E2_VENCTO @ Li, aCol[7] PSay (cAliasImp)->E2_VENCREA @ Li, aCol[8] PSay (cAliasImp)->E2_VALOR ; PICTURE "@E 99,999,999,999.99" @ Li, aCol[9] PSay (cAliasImp)->E2_VALOR -; (cAliasImp)->E2_SALDO ; PICTURE "@E 99,999,999,999.99" @ Li, aCol[10] PSay (cAliasImp)->E2_SALDO ; PICTURE "@E 99,999,999,999.99" Li ++ Endif nValor += (cAliasImp)->E2_VALOR nPago += ((cAliasImp)->E2_VALOR-(cAliasImp)->E2_SALDO) nSaldo += (cAliasImp)->E2_SALDO nT_Valor += (cAliasImp)->E2_VALOR nT_Pago += ((cAliasImp)->E2_VALOR-(cAliasImp)->E2_SALDO) nT_Saldo += (cAliasImp)->E2_SALDO End dbSkip() Replicate("-",Limite) PSay PSay PSay PSay "TOTAL....." nValor PICTURE "@E 99,999,999,999.99" nPago PICTURE "@E 99,999,999,999.99" nSaldo PICTURE "@E 99,999,999,999.99"

@ Li, 000 PSay Li ++ @ Li, aCol[1] @ Li, aCol[8] @ Li, aCol[9] @ Li, aCol[10] Li +=2 cFornec nValor nPago nSaldo End Continuao: := := := :=

(cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA 0 0 0

If lEnd @ Li, aCol[1] PSay cCancel Return Endif @ Li, Li ++ @ Li, @ Li, @ Li, @ Li, 000 PSay Replicate("=",Limite) aCol[1] aCol[8] aCol[9] aCol[10] PSay PSay PSay PSay "TOTAL GERAL....." nT_Valor PICTURE "@E 99,999,999,999.99" nT_Pago PICTURE "@E 99,999,999,999.99" nT_Saldo PICTURE "@E 99,999,999,999.99"

If Li <> 80 Roda(cbCont,cbTxt,Tamanho) Endif


- 108 ADVPL II

//+---------------------------------------------------------------------//| Gera arquivo do tipo .DBF com extenso .XLS p/ usurio abrir no Excel //+---------------------------------------------------------------------cArqExcel := __RELDIR+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS" Copy To &cArqExcel #IFNDEF TOP dbSelectArea(cAliasImp) RetIndex(cAliasImp) Set Filter To #ELSE dbSelectArea(cAliasImp) dbCloseArea() #ENDIF dbSetOrder(1) dbGoTop() If aReturn[5] == 1 Set Printer TO dbCommitAll() OurSpool(wnrel) EndIf //+-----------------------//| Abrir planilha MS-Excel //+-----------------------If mv_par08 == 1 __CopyFile(cArqExcel,"c:\"+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS") If ! ApOleClient("MsExcel") MsgAlert("MsExcel no instalado") Return Endif oExcelApp := MsExcel():New() oExcelApp:WorkBooks:Open( "c:\"+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS" ) oExcelApp:SetVisible(.T.) Endif Ms_Flush() Return Funo para gerar o grupo de parmetros no SX1

//+-----------------------------------------------------------------+ //| Rotina | CriaSX1 | Autor | Robson Luiz (rleg)| Data | 01.01.07 | //+-----------------------------------------------------------------+ //| Descr. | Rotina para criar o grupo de parmetros. | //+-----------------------------------------------------------------+ //| Uso | Para treinamento e capacitao. | //+-----------------------------------------------------------------+ Static Function CriaSx1() Local aP := {} Local i := 0 Local cSeq Local cMvCh Local cMvPar Local aHelp := {}
- 109 ADVPL II

/****** Parmetros da funo padro --------------------------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) Caracterstica do vetor p/ utilizao da funo SX1 --------------------------------------------------[n,1] --> texto da pergunta [n,2] --> tipo do dado [n,3] --> tamanho [n,4] --> decimal [n,5] --> objeto G=get ou C=choice [n,6] --> validao [n,7] --> F3 [n,8] --> definio 1 [n,9] --> definio 2 [n,10] -> definio 3 [n,11] -> definio 4 [n,12] -> definio 5 ***/ Continuao: AADD(aP,{"Fornecedor de","C",6,0,"G","","SA2","" ,"" ,"","",""}) AADD(aP,{"Fornecedor ate","C",6,0,"G","(mv_par02>=mv_par01)","SA2",; "" ,"" ,"","",""}) AADD(aP,{"Tipo de","C",3,0,"G","","05" ,"" ,"" ,"","",""}) AADD(aP,{"Tipo ate","C",3,0,"G","(mv_par04>=mv_par03)","05" ,"" ,; "" ,"","",""}) AADD(aP,{"Vencimento de","D",8,0,"G","","" ,"" ,"" ,"","",""}) AADD(aP,{"Vencimento ate","D",8,0,"G","(mv_par06>=mv_par05)","" ,; "" ,"" ,"","",""}) AADD(aP,{"Aglutinar pagto.de fornec.","N",1,0,"C","","",; "Sim","No","","",""}) AADD(aP,{"Abrir planilha MS-Excel" ,"N",1,0,"C","","",; "Sim","No","","",""}) AADD(aHelp,{"Informe o cdigo do fornecedor.","inicial."}) AADD(aHelp,{"Informe o cdigo do fornecedor.","final."})
- 110 ADVPL II

AADD(aHelp,{"Tipo de ttulo inicial."}) AADD(aHelp,{"Tipo de ttulo final."}) AADD(aHelp,{"Digite a data do vencimento inicial."}) AADD(aHelp,{"Digite a data do vencimento final."}) AADD(aHelp,{"Aglutinar os ttulos do mesmo forne-",; "cedor totalizando seus valores."}) AADD(aHelp,{"Ser gerada uma planilha para ",; "MS-Excel, abrir esta planilha?"}) For i:=1 To Len(aP) cSeq := StrZero(i,2,0) cMvPar := "mv_par"+cSeq cMvCh := "mv_ch"+IIF(i<=9,Chr(i+48),Chr(i+87)) PutSx1(cPerg,; cSeq,; aP[i,1],aP[i,1],aP[i,1],; cMvCh,; aP[i,2],; aP[i,3],; aP[i,4],; 0,; aP[i,5],; aP[i,6],; aP[i,7],; "",; "",; cMvPar,; aP[i,8],aP[i,8],aP[i,8],; "",; aP[i,9],aP[i,9],aP[i,9],; aP[i,10],aP[i,10],aP[i,10],; aP[i,11],aP[i,11],aP[i,11],; aP[i,12],aP[i,12],aP[i,12],; aHelp[i],; {},; {},; "") Next i Return

Exerccio Implementar um relatrio que fornea uma listagem de uma nota fiscal de entrada e seus itens.

- 111 ADVPL II

8. Manipulao de arquivos I 8.1. Gerao e leitura de arquivos em formato texto

Arquivos do tipo texto (tambm conhecidos como padro TXT) so arquivos com registros de tamanho varivel. A indicao do final de cada registro representada por dois bytes, 0D 0A em hexadecimal ou 13 10 em decimal ou, ainda, CR LF para padro ASCII. Apesar do tamanho dos registros ser varivel, a maioria dos sistemas gera este tipo de arquivo com registros de tamanho fixo, de acordo com um layout especfico que indica quais so os dados gravados. Para ilustrar estes procedimentos, sero gerados arquivos textos, com duas famlias de funes: 1) Famlia: nesta famlia sero utilizadas as funes: FCreate(), FSeek(), FOpen() e FRead(). FWrite(), FClose(),

2) Famlia: nesta famlia sero utilizadas as funes: FT_FUse(), FT_FGoTop(), FT_FLastRec(), FT_FEof(), FT_FReadLn(), FT_FSkip(), FT_FGoto(), FT_FRecno().

A diferena entre as duas famlias, est na leitura do arquivo texto. Quando se tratar de arquivo texto com tamanho fixo das linhas, podero ser utilizadas as duas famlias para leitura do arquivo, porm, quando se tratar de arquivo texto com tamanho varivel das linhas, somente poder ser utiliza a segunda famlia, representada pelas funes: FT_FUse(), FT_FGoTo(), FT_FRecno(), FT_FGoTop(), FT_FLastRec(), FT_FEof(), FT_FReadLn() e FT_FSkip().

- 112 ADVPL II

8.1.1.

1 Famlia de funes de gravao e leitura de arquivos texto


FCREATE()

8.1.1.1.

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

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

- 113 ADVPL II

8.1.1.2.

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

8.1.1.3.

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

- 114 ADVPL II

Parmetros: nHandle Retorno: Lgico Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos; do contrrio, retorna verdadeiro (.T.). FSEEK() Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().

8.1.1.4.

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

Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) Parmetros: nHandle nOffSet 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(). Manipulador obtido atravs das funes FCREATE,FOPEN. 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.

8.1.1.5.

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.

- 115 ADVPL II

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. Sintaxe: FOPEN ( < cArq > , [ nModo ] ) Parmetros: cArq nModo Nome do arquivo a ser aberto que inclui o path caso haja um. Modo de acesso DOS solicitado que indica como o arquivo aberto deve ser acessado. O acesso de uma das categorias relacionadas na tabela A e as restries de compartilhamento relacionada na Tabela B. O modo 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. FREAD()

8.1.1.6.

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

nQtdBytes

- 116 ADVPL II

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.

Exemplo: Gerao de arquivo TXT, utilizando a primeira famlia de funes

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Programa | GeraTXT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Gera o arquivo TXT, a partir do Cadastro de Clientes | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function GeraTXT() //+--------------------------------+ //| Declarao de Variveis | //+--------------------------------+ Local oGeraTxt Private cPerg := "EXPSA1" Private cAlias := "SA1" //CriaSx1(cPerg) //Pergunte(cPerg,.F.) dbSelectArea(cAlias) dbSetOrder(1) //+-----------------------------------+ //| Montagem da tela de processamento.| //+-----------------------------------+ DEFINE MSDIALOG oGeraTxt TITLE OemToAnsi("Gerao de Arquivo Texto") ; FROM 000,000 TO 200,400 PIXEL @ 005,005 TO 095,195 OF oGeraTxt PIXEL @ 010,020 Say " Este programa ira gerar um arquivo texto, conforme os parame"; OF oGeraTxt PIXEL @ 018,020 Say " tros definidos pelo usurio, com os registros do arquivo de "; OF oGeraTxt PIXEL @ 026,020 Say " SA1 " OF oGeraTxt PIXEL DEFINE SBUTTON FROM 070, 030 TYPE 1 ; ACTION (OkGeraTxt(),oGeraTxt:End()) ENABLE OF oGeraTxt DEFINE SBUTTON FROM 070, 070 TYPE 2 ; ACTION (oGeraTxt:End()) ENABLE OF oGeraTxt

- 117 ADVPL II

DEFINE SBUTTON FROM 070, 110 TYPE 5 ; ACTION (Pergunte(cPerg,.T.)) ENABLE OF oGeraTxt ACTIVATE DIALOG oGeraTxt CENTERED Return Nil Exemplo (continuao): /*/ +----------------------------------------------------------------------------| Funo | OKGERATXT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Funo chamada pelo boto OK na tela inicial de processamento. | | | Executa a gerao do arquivo texto. | +----------------------------------------------------------------------------/*/ Static Function OkGeraTxt // +----------------------------------------------------------------------------//| Cria o arquivo texto // +----------------------------------------------------------------------------Private cArqTxt := "\SYSTEM\EXPSA1.TXT" Private nHdl := fCreate(cArqTxt) If nHdl == -1 MsgAlert("O arquivo de nome "+cArqTxt+" no pode ser executado! Verifique os parmetros.","Ateno!") Return Endif // Inicializa a rgua de processamento Processa({|| RunCont() },"Processando...") Return Nil /*/ +----------------------------------------------------------------------------| Funo | RUNCONT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Funo auxiliar chamada pela PROCESSA. A funo PROCESSA | | | monta a janela com a rgua de processamento. | +----------------------------------------------------------------------------/*/ Static Function RunCont Local cLin dbSelectArea(cAlias) dbGoTop() ProcRegua(RecCount()) // Numero de registros a processar While (cAlias)->(!EOF()) //Incrementa a rgua IncProc()
- 118 ADVPL II

cLin := (cAlias)->A1_FILIAL cLin += (cAlias)->A1_COD cLin += (cAlias)->A1_LOJA cLin += (cAlias)->A1_NREDUZ cLin += STRZERO((cAlias)->A1_MCOMPRA*100,16) // 14,2 cLin += DTOS((cAlias)->A1_ULTCOM)//AAAAMMDD cLin += CRLF Exemplo (continuao): //+-------------------------------------------------------------------+ //| Gravao no arquivo texto. Testa por erros durante a gravao da | //| linha montada. | //+-------------------------------------------------------------------+ If fWrite(nHdl,cLin,Len(cLin)) != Len(cLin) If !MsgAlert("Ocorreu um erro na gravao do arquivo."+; "Continua?","Ateno!") Exit Endif Endif EndDo (cAlias)->(dbSkip())

// O arquivo texto deve ser fechado, bem como o dialogo criado na funo anterior fClose(nHdl) Return Nil

Note que para a gerao do arquivo TXT foram utilizadas, basicamente, as funes FCreate, FWrite e FClose que, respectivamente, gera o arquivo, adiciona dados e fecha o arquivo. No exemplo, o formato estabelecido pela concatenao dos dados na varivel cLin a qual utilizada na gravao dos dados. Para a leitura de dados TXT sero utilizada as funes FOpen e FRead. Exemplo: Leitura de arquivo TXT, utilizando a primeira famlia de funes

#Include "protheus.ch" /*/ +----------------------------------------------------------------------| Programa | LeTXT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------| Descrio| Leitura de arquivo TXT | +----------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------/*/ User Function LeTXT() //+-------------------------------------------------------------------+ //| Declarao de Variveis | //+-------------------------------------------------------------------+
- 119 ADVPL II

Local cPerg:= "IMPSA1" Local oLeTxt Private cAlias := "SA1" //CriaSx1(cPerg) //Pergunte(cPerg,.F.) Exemplo (continuao): dbSelectArea(cAlias) dbSetOrder(1) //+-------------------------------------------------------------------+ // Montagem da tela de processamento | //+-------------------------------------------------------------------+ DEFINE MSDIALOG oLeTxt TITLE OemToAnsi("Leitura de Arquivo Texto"); FROM 000,000 TO 200,400 PIXEL @ 005,005 TO 095,195 OF oLeTxt PIXEL @ 10,020 Say " Este programa ira ler o contedo de um arquivo texto, conforme"; OF oLeTxt PIXEL @ 18,020 Say " os parmetros definidos pelo usurio, com os registros do arquivo"; OF oLeTxt PIXEL @ 26,020 Say " SA1" OF oLeTxt PIXEL DEFINE SBUTTON FROM 070, 030 TYPE 1 ; ACTION (OkLeTxt(),oLeTxt:End()) ENABLE OF oLeTxt DEFINE SBUTTON FROM 070, 070 TYPE 2 ; ACTION (oLeTxt:End()) ENABLE OF oLeTxt DEFINE SBUTTON FROM 070, 110 TYPE 5 ; ACTION (Pergunte(cPerg,.T.)) ENABLE OF oLeTxt ACTIVATE DIALOG oLeTxt CENTERED Return Nil /*/ +----------------------------------------------------------------------------| Funo | OKLETXT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Funo chamada pelo boto OK na tela inicial de processamento | | | Executa a leitura do arquivo texto | +----------------------------------------------------------------------------/*/ Static Function OkLeTxt() //+-------------------------------------------------------------------+ //| Abertura do arquivo texto //+-------------------------------------------------------------------+ Private cArqTxt := "\SYSTEM\EXPSA1.TXT" Private nHdl := fOpen(cArqTxt,68) |

- 120 ADVPL II

If nHdl == -1 MsgAlert("O arquivo de nome "+cArqTxt+" no pode ser aberto! Verifique os parmetros.","Ateno!") Return Endif // Inicializa a rgua de processamento Processa({|| RunCont() },"Processando...") Return Nil /*/ +----------------------------------------------------------------------------| Funo | RUNCONT | Autor | SERGIO FUZINAKA | Data | | +----------------------------------------------------------------------------| Descrio| Funo auxiliar chamada pela PROCESSA. A funo PROCESSA | | | monta a janela com a rgua de processamento. | +----------------------------------------------------------------------------/*/ Static Function RunCont Local Local Local Local Local Local Local nTamFile nTamLin cBuffer nBtLidos cFilSA1 cCodSA1 cLojaSA1 := 0 := 56 := 0 := "" := ""

:= "" := ""

//1234567890123456789012345678901234567890123456789012345678901234567890 //00000000010000000002000000000300000000040000000005000000000600000000070 //FFCCCCCCLLNNNNNNNNNNNNNNNNNNNNVVVVVVVVVVVVVVVVDDDDDDDD //A1_FILIAL - 01, 02 - TAM: 02 //A1_COD - 03, 08 - TAM: 06 //A1_LOJA - 09, 10 - TAM: 02 //A1_NREDUZ- 11, 30 - TAM: 20 //A1_MCOMPRA - 31, 46 - TAM: 14,2 //A1_ULTCOM- 47, 54 - TAM: 08 nTamFile := fSeek(nHdl,0,2) fSeek(nHdl,0,0) cBuffer := Space(nTamLin) // Varivel para criao da linha do registro para leitura ProcRegua(nTamFile) // Numero de registros a processar While nBtLidos < nTamFile //Incrementa a rgua IncProc() // Leitura da primeira linha do arquivo texto nBtLidos += fRead(nHdl,@cBuffer,nTamLin) cFilSA1 cCodSA1 cLojaSA1 := Substr(cBuffer,01,02) //- 01, 02 - TAM: 02 := Substr(cBuffer,03,06) //- 03, 08 - TAM: 06 := Substr(cBuffer,09,02) //- 09, 10 - TAM: 02

While .T. IF dbSeek(cFilSA1+cCodSA1+cLojaSA1) cCodSA1 := SOMA1(cCodSA1)


- 121 ADVPL II

Else Endif Enddo

Loop Exit

Exemplo (continuao): dbSelectArea(cAlias) RecLock(cAlias,.T.) (cAlias)->A1_FILIAL (cAlias)->A1_COD (cAlias)->A1_LOJA (cAlias)->A1_NREDUZ //- 11, 30 - TAM: 20 (cAlias)->A1_MCOMPRA //- 31, 46 - TAM: 14,2 (cAlias)->A1_ULTCOM //- 47, 54 - TAM: 08 MSUnLock() EndDo // O arquivo texto deve ser fechado, bem como o dialogo criado na funo anterior. fClose(nHdl) Return Nil

:= := := :=

cFilSA1 //- 01, 02 - TAM: 02 cCodSA1 //- 03, 08 - TAM: 06 cLojaSA1 //- 09, 10 - TAM: 02 Substr(cBuffer,11,20)

:= Val(Substr(cBuffer,31,16))/100 := STOD(Substr(cBuffer,47,08))

- 122 ADVPL II

8.1.2.

2 Famlia de funes de gravao e leitura de arquivos texto


FT_FUSE()

8.1.2.1.

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

8.1.2.2.

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

8.1.2.3.

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

- 123 ADVPL II

8.1.2.4.

FT_FEOF()

Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE() estiver posicionado no final do arquivo, similar funo EOF() utilizada para arquivos de dados. Sintaxe: FT_FEOF( ) Parmetros: Nenhum Retorno: Lgico Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso contrrio. FT_FREADLN() .

8.1.2.5.

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. Sintaxe: FT_FREADLN( ) Parmetros: Nenhum Retorno: Caracter Retorna a linha inteira na qual est posicionado o ponteiro para leitura de dados. FT_FSKIP() .

8.1.2.6.

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 .

- 124 ADVPL II

8.1.2.7.

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 .

8.1.2.8.

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

Exemplo: Leitura de arquivo TXT, utilizando a segunda famlia de funes #Include "Protheus.ch" /*/ +----------------------------------------------------------------------------| Programa | LeArqTXT | Autor | Robson Luiz | Data | | +----------------------------------------------------------------------------| Descrio | Leitura de arquivo TXT | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function LeArqTxt() Private Private Private Private nOpc cCadastro aSay aButton := := := := 0 "Ler arquivo texto" {} {}

AADD( aSay, "O objetivo desta rotina e efetuar a leitura em um arquivo texto" )
- 125 ADVPL II

AADD( aButton, { 1,.T.,{|| nOpc := 1,FechaBatch()}}) AADD( aButton, { 2,.T.,{|| FechaBatch() }} ) FormBatch( cCadastro, aSay, aButton ) If nOpc == 1 Processa( {|| Import() }, "Processando..." ) Endif Return Nil //+------------------------------------------//| Funo - Import() //+------------------------------------------Static Function Import() Local Local Local Local cBuffer cFileOpen cTitulo1 cExtens := := := := "" "" "Selecione o arquivo" "Arquivo TXT | *.txt"

/*** * _________________________________________________________ * cGetFile(<ExpC1>,<ExpC2>,<ExpN1>,<ExpC3>,<ExpL1>,<ExpN2>) * * <ExpC1> - Expresso de filtro * <ExpC2> - Titulo da janela * <ExpN1> - Numero de mascara default 1 para *.Exe * <ExpC3> - Diretrio inicial se necessrio * <ExpL1> - .F. boto salvar - .T. boto abrir * <ExpN2> - Mascara de bits para escolher as opes de visualizao do objeto * (prconst.ch) */ cFileOpen := cGetFile(cExtens,cTitulo1,,cMainPath,.T.) If !File(cFileOpen) MsgAlert("Arquivo texto: "+cFileOpen+" no localizado",cCadastro) Return Endif FT_FUSE(cFileOpen) //ABRIR FT_FGOTOP() //PONTO NO TOPO ProcRegua(FT_FLASTREC()) //QTOS REGISTROS LER While !FT_FEOF() IncProc() //FACA ENQUANTO NAO FOR FIM DE ARQUIVO

// Capturar dados cBuffer := FT_FREADLN() //LENDO LINHA cMsg cMsg cMsg cMsg cMsg cMsg := += += += += += "Filial: " +SubStr(cBuffer,01,02) + Chr(13)+Chr(10) "Cdigo: " +SubStr(cBuffer,03,06) + Chr(13)+Chr(10) "Loja: " +SubStr(cBuffer,09,02) + Chr(13)+Chr(10) "Nome fantasia: " +SubStr(cBuffer,11,15) + Chr(13)+Chr(10) "Valor: " +SubStr(cBuffer,26,14) + Chr(13)+Chr(10) "Data: " +SubStr(cBuffer,40,08) + Chr(13)+Chr(10)

MsgInfo(cMsg) FT_FSKIP() //prximo registro no arquivo txt


- 126 ADVPL II

EndDo Exemplo (continuao): FT_FUSE() //fecha o arquivo txt MsgInfo("Processo finalizada") Return Nil

Exerccio Desenvolver uma rotina que realize a exportao dos itens marcados no cadastro de clientes para um arquivo TXT em um diretrio especificado pelo usurio.

Exerccio Desenvolver uma rotina que realize a importao dos dados de clientes contidos em um arquivo TXT, sendo o mesmo selecionado pelo usurio.

- 127 ADVPL II

9. Oficina de programao I 9.1. Interfaces com sintaxe clssica

A sintaxe convencional para definio de componentes visuais da linguagem ADVPL depende diretamente no include especificado no cabealho do fonte. Os dois includes disponveis para o ambiente ADVPL Protheus so: RWMAKE.CH: permite a utilizao da sintaxe CLIPPER na definio dos componentes visuais. PROTHEUS.CH: permite a utilizao da sintaxe ADVPL convencional, a qual um aprimoramento da sintaxe CLIPPER, com a incluso de novos atributos para os componentes visuais disponibilizados no ERP Protheus. Para ilustrar a diferena na utilizao destes dois includes, segue abaixo as diferentes definies para o componentes Dialog e MsDialog: Exemplo 01 Include Rwmake.ch #include rwmake.ch @ 0,0 TO 400,600 DIALOG oDlg TITLE "Janela em sintaxe Clipper" ACTIVATE DIALOG oDlg CENTERED

Exemplo 02 Include Protheus.ch #include protheus.ch DEFINE MSDIALOG oDlg TITLE "Janela em sintaxe ADVPL "FROM 000,000 TO 400,600 PIXEL ACTIVATE MSDIALOG oDlg CENTERED

Ambas as sintaxes produziro o mesmo efeito quando compiladas e executadas no ambiente Protheus, mas deve ser utilizada sempre a sintaxe ADVPL atravs do uso do include PROTHEUS.CH Os componentes da interface visual que sero tratados neste tpico, utilizando a sintaxe clssica da linguagem ADVPL so:

BUTTON() CHECKBOX() COMBOBOX() FOLDER() MSDIALOG()


- 128 ADVPL II

MSGET() RADIO() SAY() SBUTTON()

Executar o fonte DIALOG_OBJETOS.PRW e avaliar a definio dos componentes utilizados utilizando a sintaxe clssica .

BUTTON()
Sintaxe Descrio CHECKBOX() @ nLinha,nColuna CHECKBOX oCheckBox VAR VARIAVEL PROMPT cTexto WHEN WHEN UNIDADE OF oObjetoRef SIZE nLargura,nAltura MESSAGE cMensagem Define o componente visual CheckBox, o qual permite a utilizao da uma marca para habilitar ou no uma opo escolhida, sendo esta marca acompanhada de um texto explicativo. Difere do RadioMenu pois cada elemento do check nico, mas o Radio permite a utilizao de uma lista junto com um controle de seleo. @ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef ACTION AO Define o componente visual Button, o qual permite a incluso de botes de operao na tela da interface, os quais sero visualizados somente com um texto simples para sua identificao.

Sintaxe

Descrio

COMBOBOX() Sintaxe Descrio FOLDER() Sintaxe Descrio @ nLinha,nColuna FOLDER oFolder OF oObjetoRef PROMPT &cTexto1, ,&cTextoX PIXEL SIZE nLargura,nAltura Define o componente visual Folder, o qual permite a incluso de diversos Dialogs dentro de uma mesma interface visual. Um Folder pode ser entendido como um array de Dialogs, aonde cada painel recebe seus componentes e tem seus atributos definidos independentemente dos demais. @ nLinha,nColuna COMBOBOX VARIAVEL ITEMS AITENS SIZE nLargura,nAltura UNIDADE OF oObjetoRef Define o componente visual ComboBox, o qual permite seleo de um item dentro de uma lista de opes de textos simples no formato de um vetor.

MSDIALOG() Sintaxe DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO


- 129 ADVPL II

nLiFim,nColFim OF oObjetoRef UNIDADE Descrio Define o componente MSDIALOG(), o qual utilizado como base para os demais componentes da interface visual, pois um componente MSDIALOG() uma janela da aplicao.

- 130 ADVPL II

MSGET() Sintaxe Descrio @ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis na tela da interface.

RADIO() @ nLinha,nColuna RADIO oRadio VAR nRadio 3D SIZE nLargura,nAltura <ITEMS PROMPT> cItem1,cItem2,...,cItemX OF oObjetoRef UNIDADE ON CHANGE CHANGE ON CLICK CLICK Define o componente visual Radio, tambm conhecido como RadioMenu, o qual seleo de uma opo ou de mltiplas opes atravs de uma marca para os itens exibidos de uma lista. Difere do componente CheckBox, pois cada elemento de check sempre nico, e o Radio pode conter um ou mais elementos.

Sintaxe

Descrio

SAY() Sintaxe Descrio SBUTTON() Sintaxe Descrio DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF oObjetoRef 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. @ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de interface.

- 131 ADVPL II

9.2.

Rguas de processamento

Os indicadores de progresso ou rguas de processamento disponveis na linguagem ADVPL que sero abordados neste material so:

RPTSTATUS() PROCESSA() MSNEWPROCESS() MSAGUARDE() MSGRUN()


9.2.1. RptStatus()

Rgua de processamento simples, com apenas um indicador de progresso, utilizada no processamento de relatrios do padro SetPrint(). Sintaxe: RptStatus(bAcao, cMensagem) Retorno: Nil Parmetros: bAcao cMensagem Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento. Mensagem que ser exibida na rgua de processamento durante a execuo.

Aparncia

- 132 ADVPL II

Exemplo: Funo RPTStatus() e acessrias

/*/ +--------------------------------------------------------------------------| Funo | GRPTSTATUS | Autor | ROBSON LUIZ | Data | | +--------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao das funes RPTSTATUS() | | | SETREGUA() E INCREGUA() | +--------------------------------------------------------------------------| Uso | Curso ADVPL | +--------------------------------------------------------------------------/*/ User Function Local aSay Local aButton Local nOpc Local cTitulo Local cDesc1 em conjunto" Local cDesc2 GRptStatus() := {} := {} := 0 := "Exemplo de Funes" := "Este programa exemplifica a utilizao da funo Processa() := "com as funes de incremento ProcRegua() e IncProc()"

Private cPerg := "RPTSTA" CriaSX1() Pergunte(cPerg,.F.) AADD( aSay, cDesc1 ) AADD( aSay, cDesc2 ) AADD( aButton, { 5, .T., {|| Pergunte(cPerg,.T. ) }} ) AADD( aButton, { 1, .T., {|| nOpc := 1, FechaBatch() }} ) AADD( aButton, { 2, .T., {|| FechaBatch() }} ) FormBatch( cTitulo, aSay, aButton ) If nOpc <> 1 Return Nil Endif RptStatus( {|lEnd| RunProc(@lEnd)}, "Aguarde...","Executando rotina.", .T. ) Return Nil

- 133 ADVPL II

Exemplo: Funes acessrias da RPTStatus()

/*/ +----------------------------------------------------------------------------| Funo | RUNPROC | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Funo de processamento executada atravs da RPTSTATUS() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ Static Function RunProc(lEnd) Local nCnt := 0 dbSelectArea("SX5") dbSetOrder(1) dbSeek(xFilial("SX5")+mv_par01,.T.) While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA <= mv_par02 nCnt++ dbSkip() End dbSeek(xFilial("SX5")+mv_par01,.T.) SetRegua(nCnt) While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA <= mv_par02 IncRegua() If lEnd MsgInfo(cCancel,"Fim") Exit Endif dbSkip() End Return .T.

SETREGUA() A funo SetRegua() utilizada para definir o valor mximo da rgua de progresso criada atravs da funo RptStatus(). Sintaxe: SetRegua(nMaxProc) Parmetros: nMaxProc Varivel que indica o valor mximo de processamento (passos) que sero indicados pela rgua.

Retorno: Nenhum .

- 134 ADVPL II

Exemplo: ... dbSelectArea("SA1") dbGoTop() SetRegua(LastRec()) While !Eof() IncRegua() If Li > 60 ...

INCREGUA() A funo IncRegua() utilizada para incrementar valor na rgua de progresso criada atravs da funo RptStatus() Sintaxe: IncRegua(cMensagem) Parmetros: cMensagem Mensagem que ser exibida e atualizada na rgua de processamento a cada execuo da funo IncRegua(), sendo que a taxa de atualizao da interface controlada pelo Binrio.

Retorno: Nenhum Exemplo: ... dbSelectArea("SA1") dbGoTop() SetRegua(LastRec()) While !Eof() IncRegua(Avaliando cliente:+SA1->A1_COD) If Li > 60 ... .

- 135 ADVPL II

9.2.2.

Processa()

Rgua de processamento simples, com apenas um indicador de progresso, utilizada no processamento de rotinas. Sintaxe: Processa(bAcao, cMensagem) Retorno: Nil Parmetros: bAcao cMensagem Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento. Mensagem que ser exibida na rgua de processamento durante a execuo.

Aparncia

Exemplo: Funo PROCESSA() e acessrias

/*/ +----------------------------------------------------------------------------| Funo | GPROCES1 | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao das funes PROCESSA() | | | PROCREGUA() E INCPROC() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function Local aSay Local aButton Local nOpc Local cTitulo Local cDesc1 Local cDesc2 Local cDesc3 GProces1() := {} := {} := 0 := "Exemplo de Funes" := "Este programa exemplifica a utilizao da funo Processa()" := " em conjunto com as funes de incremento ProcRegua() e" := " IncProc()"

- 136 ADVPL II

Exemplo (continuao): Private cPerg := "PROCES" CriaSX1() Pergunte(cPerg,.F.) AADD( aSay, cDesc1 ) AADD( aSay, cDesc2 ) AADD( aButton, { 5, .T., {|| Pergunte(cPerg,.T. ) }} ) AADD( aButton, { 1, .T., {|| nOpc := 1, FechaBatch() }} ) AADD( aButton, { 2, .T., {|| FechaBatch() }} ) FormBatch( cTitulo, aSay, aButton ) If nOpc <> 1 Return Nil Endif Processa( {|lEnd| RunProc(@lEnd)}, "Aguarde...","Executando rotina.", .T. ) Return Nil /*/ +----------------------------------------------------------------------------| Funo | RUNPROC | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Funo de processamento executada atravs da PROCRSSA() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ Static Function RunProc(lEnd) Local nCnt := 0 dbSelectArea("SX5") dbSetOrder(1) dbSeek(xFilial("SX5")+mv_par01,.T.) dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5").And.X5_TABELA<=mv_par02}) dbSeek(xFilial("SX5")+mv_par01,.T.) ProcRegua(nCnt) While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA <= mv_par02 IncProc("Processando tabela: "+SX5->X5_CHAVE) If lEnd MsgInfo(cCancela,"Fim") Exit Endif dbSkip() End Return .T.

- 137 ADVPL II

SETPROC() A funo SetProc() utilizada para definir o valor mximo da rgua de progresso criada atravs da funo Processa(). Sintaxe: Processa(nMaxProc) Parmetros: nMaxProc Varivel que indica o valor mximo de processamento (passos) que sero indicados pela rgua.

Retorno: Nenhum .

Exemplo: ... dbSelectArea("SA1") dbGoTop() SetProc(LastRec()) While !Eof() IncProc() If Li > 60 ... INCPROC() A funo IncProc() utilizada para incrementar valor na rgua de progresso criada atravs da funo Processa() Sintaxe: IncProc(cMensagem) Parmetros: cMensagem Mensagem que ser exibida e atualizada na rgua de processamento a cada execuo da funo IncProc(), sendo que a taxa de atualizao da interface controlada pelo Binrio.

Retorno: Nenhum .

Exemplo: ... dbSelectArea("SA1") dbGoTop() SetProc(LastRec()) While !Eof() IncProc(Avaliando cliente:+SA1->A1_COD) If Li > 60 ...

- 138 ADVPL II

9.2.3.

MsNewProcess().

Rgua de processamento dupla, possuindo dois indicadores de progresso independentes, utilizada no processamento de rotinas. Sintaxe: MsNewProcess():New(bAcao, cMensagem) Retorno: oProcess objeto do tipo MsNewProcess() Parmetros: bAcao cMensagem Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento. Mensagem que ser exibida na rgua de processamento durante a execuo.

Aparncia

Mtodos: Activate() SetRegua1() IncRegua1() Inicia a execuo do objeto MsNewProcess instanciado. Define a quantidade de informaes que sero demonstradas pelo indicador de progresso superior. Parmetro: nMaxProc Incrementa em uma unidade o indicador de progresso superior, o qual ir demonstrar a evoluo do processamento de acordo com a quantidade definida pelo mtodo SetRegua1(). Parmetro: cMensagem Define a quantidade de informaes que sero demonstradas pelo indicador de progresso inferior. Parmetro: nMaxProc Incrementa em uma unidade o indicador de progresso inferior, o qual ir demonstrar a evoluo do processamento de acordo com a quantidade definida pelo mtodo SetRegua2(). Parmetro: cMensagem

SetRegua2() IncRegua2()

- 139 ADVPL II

Exemplo: Objeto MsNewProcess() e mtodos acessrios

/*/ +----------------------------------------------------------------------------| Funo | GPROCES2 | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao do objeto MsNewProcess() | | | e seus mtodos IncReguaX() e SetReguaX() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function GProces2() Private oProcess := NIL oProcess := MsNewProcess():New({|lEnd| RunProc(lEnd,oProcess)}; "Processando","Lendo...",.T.) oProcess:Activate() Return Nil /*/ +----------------------------------------------------------------------------| Funo | RUNPROC | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Funo de processamento executada atravs da MsNewProcess() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ Static Function RunProc(lEnd,oObj) Local i := 0 Local aTabela := {} Local nCnt := 0 aTabela := {{"00",0},{"13",0},{"35",0},{"T3",0}} dbSelectArea("SX5") cFilialSX5 := xFilial("SX5") dbSetOrder(1) For i:=1 To Len(aTabela) dbSeek(cFilialSX5+aTabela[i,1]) While !Eof() .And. X5_FILIAL+X5_TABELA == cFilialSX5+aTabela[i,1] If lEnd Exit Endif nCnt++ dbSkip() End aTabela[i,2] := nCnt nCnt := 0 Next i

- 140 ADVPL II

Exemplo (continuao): oObj:SetRegua1(Len(aTabela)) For i:=1 To Len(aTabela) If lEnd Exit Endif oObj:IncRegua1("Lendo Tabela: "+aTabela[i,1]) dbSelectArea("SX5") dbSeek(cFilialSX5+aTabela[i,1]) oObj:SetRegua2(aTabela[i,2]) While !Eof() .And. X5_FILIAL+X5_TABELA == cFilialSX5+aTabela[i,1] oObj:IncRegua2("Lendo chave: "+X5_CHAVE) If lEnd Exit Endif dbSkip() End Next i Return

9.2.4.

MsAguarde().

Indicador de processamento sem incremento. Sintaxe: Processa(bAcao, cMensagem, cTitulo) Retorno: Nil Parmetros: bAcao cMensagem cTitulo Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento. Mensagem que ser exibida na rgua de processamento durante a execuo. Ttulo da janela da rgua de processamento.

Aparncia

- 141 ADVPL II

Exemplo: MSAguarde()

/*/ +----------------------------------------------------------------------------| Funo | GMSAGUARDE | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao das funes MSAGUARDE() | | | e MSPROCTXT() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ USER FUNCTION GMsAguarde() PRIVATE lEnd := .F. MsAguarde({|lEnd| RunProc(@lEnd)},"Aguarde...","Processando Clientes",.T.) RETURN /*/ +----------------------------------------------------------------------------| Funo | RUNPROC | Autor | ROBSON LUIZ | Data | | +----------------------------------------------------------------------------| Descrio| Funo de processamento | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ STATIC FUNCTION RunProc(lEnd) dbSelectArea("SX5") dbSetOrder(1) dbGoTop() While !Eof() If lEnd MsgInfo(cCancel,"Fim") Exit Endif MsProcTxt("Tabela: "+SX5->X5_TABELA+" Chave: "+SX5->X5_CHAVE) dbSkip() End RETURN

- 142 ADVPL II

9.2.5.

MsgRun().

Indicador de processamento sem incremento. Sintaxe: Processa(cMensagem, cTitulo, bAcao) Retorno: Nil Parmetros: cMensagem cTitulo bAcao Mensagem que ser exibida na rgua de processamento durante a execuo. Ttulo da janela da rgua de processamento. Bloco de cdigo que especifica a ao que ser executada com o acompanhamento da rgua de processamento.

Aparncia

Exemplo: MSGRun()

/*/ +----------------------------------------------------------------------------| Funo | GMSGRUN | Autor | ROBSON LUIZ |Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao das funes MSGRUN() | | | e DBEVAL() | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ USER FUNCTION GMsgRun() LOCAL nCnt := 0 dbSelectArea("SX1") dbGoTop() MsgRun("Lendo arquivo, aguarde...","Ttulo opcional",{|| dbEval({|x| nCnt+ +}) }) MsgInfo("Ufa!!!, li "+AllTrim(Str(nCnt))+" registros",FunName()) RETURN

- 143 ADVPL II

- 144 ADVPL II

9.3.

ListBox()

A sintaxe clssica da linguagem ADVPL permite que o componente visual ListBox implemente dois tipos distintos de objetos: Lista simples: lista de apenas uma coluna no formato de um vetor, a qual no necessita da especificao de um cabealho. Lista com colunas: lista com diversas colunas que necessita de um cabealho no formato de um aHeader (array de cabealho).

9.3.1.

ListBox simples

Sintaxe:

@ nLinha,nColuna LISTBOX oListbox VAR nLista ITEMS aLista SIZE nLargura,nAltura OF oObjetoRef UNIDADE ON CHANGE CHANGE

Parmetros: nLinha,nColuna oListBox nLista aLista nLargura,nAltura oObjetoRef UNIDADE CHANGE Posio do objeto ListBox em funo da janela em que ele ser definido. Objeto ListBox que ser criado. Varivel numrica que contm o nmero do item selecionado no ListBox. Vetor simples contendo as strings que sero exibidas no ListBox. Dimenses do objeto ListBox. Objeto dialog no qual o componente ser definido. Unidade de medida das dimenses: PIXEL. Funo ou lista de expresses que ser executada na seleo de um item do ListBox.

Aparncia:

- 145 ADVPL II

Exemplo: LISTBOX como lista simples

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | LISTBOXITE | Autor | ROBSON LUIZ |Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao do LISTBOX() como lista | | | simples. | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function ListBoxIte() Local Local Local Local Local Local aVetor oDlg oLbx cTitulo nChave cChave := := := := := := {} Nil Nil "Consulta Tabela" 0 ""

dbSelectArea("SX5") dbSetOrder(1) dbSeek(xFilial("SX5")) CursorWait() //+-----------------------------------------+ //| Carrega o vetor conforme a condio | //+-----------------------------------------+ While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA=="00" AADD( aVetor, Trim(X5_CHAVE)+" - "+Capital(Trim(X5_DESCRI)) ) dbSkip() End CursorArrow() If Len( aVetor ) == 0 Aviso( cTitulo, "No existe dados a consultar", {"Ok"} ) Return Endif //+-----------------------------------------------+ //| Monta a tela para usurio visualizar consulta | //+-----------------------------------------------+ DEFINE MSDIALOG oDlg TITLE cTitulo FROM 0,0 TO 240,500 PIXEL @ 10,10 LISTBOX oLbx VAR nChave ITEMS aVetor SIZE 230,95 OF oDlg PIXEL oLbx:bChange := {|| cChave := SubStr(aVetor[nChave],1,2) } DEFINE SBUTTON FROM 107,183 TYPE 14 ACTION LoadTable(cChave) ENABLE OF oDlg DEFINE SBUTTON FROM 107,213 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg ACTIVATE MSDIALOG oDlg CENTER Return

- 146 ADVPL II

Exemplo: LISTBOX como lista simples funes acessrias

/*/ +----------------------------------------------------------------------------| Funo | LISTBOXITE | Autor | ROBSON LUIZ |Data | | +----------------------------------------------------------------------------| Descrio| Funo que carrega os dados da tabela selecionada em um | | | listbox. | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ STATIC FUNCTION LoadTable(cTabela) LOCAL aTabela := {} LOCAL oDlg := NIL LOCAL oLbx := NIL dbSelectArea("SX5") dbSeek(xFilial("SX5")+cTabela) //+------------------------------------------------------------//| O vetor pode receber carga de duas maneiras, acompanhe... | //+------------------------------------------------------------//| Utilizando While/End | //+------------------------------------------------------------dbEval({|| AADD(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{|| X5_TABELA==cTabela}) If Len(aTabela)==0 Aviso( "FIM", "Necessrio selecionar um item", {"Ok"} ) Return Endif DEFINE MSDIALOG oDlg TITLE "Dados da tabela selecionada" FROM 300,400 TO 540,900 PIXEL @ 10,10 LISTBOX oLbx FIELDS HEADER "Tabela", "Descrio" SIZE 230,095 OF oDlg PIXEL oLbx:SetArray( aTabela ) oLbx:bLine := {|| {aTabela[oLbx:nAt,1],aTabela[oLbx:nAt,2]} } DEFINE SBUTTON FROM 107,213 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg ACTIVATE MSDIALOG oDlg RETURN

- 147 ADVPL II

9.3.2.

ListBox mltiplas colunas

Sintaxe:

@ nLinha,nColuna LISTBOX oListbox FIELDS HEADER Header1, , HeaderX SIZE nLargura,nAltura OF oObjetoRef UNIDADE

Parmetros: nLinha,nColuna oListBox nLista Header1,...,HeaderX nLargura,nAltura oObjetoRef UNIDADE CHANGE Posio do objeto ListBox em funo da janela em que ele ser definido. Objeto ListBox que ser criado. Varivel numrica que contm o nmero do item selecionado no ListBox. Strings identificando os ttulos das colunas do Grid. Dimenses do objeto ListBox. Objeto dialog no qual o componente ser definido. Unidade de medida das dimenses: PIXEL. Funo ou lista de expresses que ser executada na seleo de um item do ListBox.

Mtodos: SetArray() Mtodo o objeto ListBox que define qual o array contm os dados que sero exibidos no grid.

Atributos: bLine Atributo do objeto ListBox que vincula cada linha,coluna do array, com cada cabealho do grid.

Aparncia:

- 148 ADVPL II

Exemplo: LISTBOX com grid

#include protheus.ch /*/ +----------------------------------------------------------------------------| Funo | LIST_BOX | Autor | ROBSON LUIZ |Data | | +----------------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao de um LISTBOX() com | | | grid. | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ User Function List_Box() Local Local Local Local Local aVetor := {} oDlg oLbx cTitulo := "Cadastro de Bancos" cFilSA6

dbSelectArea("SA6") dbSetOrder(1) cFilSA6 := xFilial("SA6") dbSeek(cFilSA6) // Carrega o vetor conforme a condio. While !Eof() .And. A6_FILIAL == cFilSA6 AADD( aVetor, { A6_COD, A6_AGENCIA, A6_NUMCON, A6_NOME, A6_NREDUZ, A6_BAIRRO, A6_MUN } ) dbSkip() End // Se no houver dados no vetor, avisar usurio e abandonar rotina. If Len( aVetor ) == 0 Aviso( cTitulo, "No existe dados a consultar", {"Ok"} ) Return Endif // Monta a tela para usurio visualizar consulta. DEFINE MSDIALOG oDlg TITLE cTitulo FROM 0,0 TO 240,500 PIXEL // Primeira opo para montar o listbox. @ 10,10 LISTBOX oLbx FIELDS HEADER ; "Banco", "Agencia", "C/C", "Nome Banco", "Fantasia", "Bairro", "Municpio" ; SIZE 230,95 OF oDlg PIXEL oLbx:SetArray( aVetor ) oLbx:bLine := {|| {aVetor[oLbx:nAt,1],; aVetor[oLbx:nAt,2],; aVetor[oLbx:nAt,3],; aVetor[oLbx:nAt,4],; aVetor[oLbx:nAt,5],; aVetor[oLbx:nAt,6],;
- 149 ADVPL II

aVetor[oLbx:nAt,7]}} Exemplo (continuao): // Segunda opo para monta o listbox /* oLbx := TWBrowse():New(10,10,230,95,,aCabecalho,,oDlg,,,,,,,,,,,,.F.,,.T.,,.F.,,,) oLbx:SetArray( aVetor ) oLbx:bLine := {|| aEval(aVetor[oLbx:nAt],{|z,w| aVetor[oLbx:nAt,w] } ) } */ DEFINE SBUTTON FROM 107,213 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg ACTIVATE MSDIALOG oDlg CENTER Return

9.4.

ScrollBox()

O ScrollBox o objeto utilizado para permitir a um Dialog exibir barras de rolagem verticais e Horizontais. Algumas aplicaes com objetos definem automaticamente o ScrollBox, tais como: Enchoice() ou MsMGet() NewGetDados() ListBox() Quando definido um objeto ScrollBox, os demais componentes da janela devero referenciar este objeto e no mais o objeto Dialog. Desta forma o ScrollBox atribudo a um objeto Dialog, e os componentes ao ScrollBox. MsDialog() ScrollBox() ScrollBox() Componentes Visuais Sintaxe:

@ nLinha,nColuna SCROLLBOX oScrollBox nLargura,nAltura OF oObjetoRef BORDER

HORIZONTAL

VERTICAL

SIZE

Parmetros: nLinha,nColuna oScrollBox HORIZONTAL VERTICAL nLargura,nAltura oObjetoRef BORDER Posio do objeto ScrollBox em funo da janela em que ele ser definido. Objeto ScrollBox que ser criado. Parmetro que quando definido habilita a rgua de rolagem horizontal. Parmetro que quando definido habilita a rgua de rolagem vertical. Dimenses do objeto ScrollBox. Objeto dialog no qual o componente ser definido. Parmetro que quando definido habilita a exibio de uma borda de delimitao do
- 150 ADVPL II

ScrollBox em relao a outros objetos.

Aparncia:

Exemplo: Utilizao de mltiplos ScrollBoxes

#INCLUDE "PROTHEUS.CH" /*/ +-----------------------------------------------------------------------| Funo | SCROLL() | Autor | ROBSON LUIZ |Data | | +-----------------------------------------------------------------------| Descrio| Programa que demonstra como montar uma enchoice apenas | | | com variveis, incluindo o recurso de rolagem. | +-----------------------------------------------------------------------| Uso | Curso ADVPL | +-----------------------------------------------------------------------/*/ USER FUNCTION Scroll() LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL LOCAL oDlg := NIL oScroll := NIL oLbx1 := NIL oLbx2 := NIL bGet := NIL oGet := NIL aAIIPM := {} aTitulo := {} nTop := 5 nWidth := 0 cGet := "" cPict := "" cVar := "" n := 0
- 151 ADVPL II

- 152 ADVPL II

Exemplo (continuao): PRIVATE PRIVATE PRIVATE PRIVATE cTitulo := "Consulta Parcelamento" aSay := {} cProcesso,cPrefixo,cTipo,cCliente,cLoja,cNome,cCGC dData,nTotal,nUFESP,cStatus,cCond := := := := := := := := := := := := "P00001" "UNI" "MAN" "000001" "01" "JOSE DA SILVA SANTOS SOARES" "00.000.000/0001-91" "26/03/03" 5922.00 1000.00 "Z" "001"

cProcesso cPrefixo cTipo cCliente cLoja cNome cCGC dData nTotal nUFESP cStatus cCond

// Vetor para os campos no Scrooll Box //+-------------------------------------+ //| aSay[n][1] - Titulo | //| aSay[n][2] - Tipo | //| aSay[n][3] - Tamanho | //| aSay[n][4] - Decimal | //| aSay[n][5] - Contedo/Varivel | //| aSay[n][6] - Formato | //+-------------------------------------+ AADD(aSay,{"Processo" ,"C",06,0,"cProcesso" AADD(aSay,{"Prefixo" ,"C",03,0,"cPrefixo" AADD(aSay,{"Tipo" ,"C",03,0,"cTipo" AADD(aSay,{"Cliente" ,"C",06,0,"cCliente" AADD(aSay,{"Loja" ,"C",02,0,"cLoja" AADD(aSay,{"Nome" ,"C",30,0,"cNome" AADD(aSay,{"CNPJ/CPF" ,"C",14,0,"cCGC" AADD(aSay,{"Dt.Processo" ,"D",08,0,"dData" AADD(aSay,{"Total R$" ,"N",17,2,"nTotal" AADD(aSay,{"Total UFESP" ,"N",17,2,"nUFESP" AADD(aSay,{"Status" ,"C",01,0,"cStatus" AADD(aSay,{"Cond.Pagto" ,"C",03,0,"cCond" // Vetor para List Box AADD(aAIIPM,{"1234","DCD9815","26/03/03"}) AADD(aAIIPM,{"1234","DCD9815","26/03/03"}) AADD(aAIIPM,{"1234","DCD9815","26/03/03"})

,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"}) ,"@!"})

// Vetor para List Box AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"}) AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"}) AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"}) DEFINE MSDIALOG @ 013,002 TO @ 013,195 TO @ 083,195 TO oDlg TITLE cTitulo FROM 122,0 154,192 LABEL "Parcelamento" 082,298 LABEL "Ttulos" 154,298 LABEL "AIIPM" TO OF OF OF 432,600 OF oDlg PIXEL oDlg PIXEL oDlg PIXEL oDlg PIXEL

//scrollbox @ 019,006 SCROLLBOX oScroll HORIZONTAL VERTICAL SIZE 131,182 OF oDlg BORDER For n:=1 TO Len(aSay)
- 153 ADVPL II

Exemplo (continuao): bGet := &("{|| '"+aSay[n][1]+"'}") cVar := aSay[n][5] cGet := "{|u| IIF(PCount()>0,"+cVar+":=u,"+cVar+")}" cPict := aSay[n][6] TSay():New(nTop,5,bGet,oScroll,,,.F.,.F.,.F.,.T.,,,; GetTextWidth(0,Trim(aSay[n][1])),15,; .F.,.F.,.F.,.F.,.F.) oGet:=TGet():New(nTop-2,40,&cGet,oScroll,,7,cPict,,,,,.F.,,.T.,; ,.F.,,.F.,.F.,,.T.,.F.,,(cVar),,,,.T.) nTop+=11 Next n //listbox ttulos @ 019,199 LISTBOX oLbx1 FIELDS HEADER ; "Parcela","Vencto","Vencto.Real","Valor R$","Qtd.UFESP"; COLSIZES 21,24,33,63,100; SIZE 095,059 OF oDlg PIXEL oLbx1:SetArray( aTitulo ) oLbx1:bLine := {||{aTitulo[oLbx1:nAt,1],aTitulo[oLbx1:nAt,2],; aTitulo[oLbx1:nAt,3],aTitulo[oLbx1:nAt,4],aTitulo[oLbx1:nAt,5]}} //listbox aiipm @ 089,199 LISTBOX oLbx2 FIELDS HEADER "AIIPM","Placa","Data Multa" ; COLSIZES 24,21,30 SIZE 095,061 OF oDlg PIXEL oLbx2:SetArray( aAIIPM ) oLbx2:bLine := {|| {aAIIPM[oLbx2:nAt,1],aAIIPM[oLbx2:nAt,2],aAIIPM[oLbx2:nAt,3]}} ACTIVATE MSDIALOG oDlg CENTER ON INIT EnchoiceBar(oDlg,{||oDlg:End()},{|| oDlg:End()}) RETURN

- 154 ADVPL II

9.5.

ParamBox()

Implementa uma tela de parmetros, que no necessita da criao de um grupo de perguntas no SX1, e com funcionalidades que a Pergunte() no disponibiliza, tais como CheckBox e RadioButtons. Cada componente da ParamBox ser associado a um parmetro Private denominado MV_PARxx, de acordo com a ordem do componente na tela. Os parmetros da ParamBox podem ser utilizados de forma independente em uma rotina especfica, ou complementando opes de uma rotina padro. Cuidados A PARAMBOX define os parmetros seguindo o princpio das variveis MV_PARxx. Caso ela seja utilizada em uma rotina em conjunto com parmetros padres (SX1 + Pergunte()) necessrio salvar os parmetros padres, chamar a Parambox(), salvar o retorno da Parambox() em variveis Private especficas (MVPARBOXxx) e depois restaurar os parmetros padres, conforme o exemplo desta documentao. O objeto COMBO() da PARAMBOX() possui um problema em seu retorno: Caso o combo no seja selecionado, ele manter seu contedo como numrico, caso seja ele receber o texto da opo e no o nmero da opo. O exemplo desta documentao ilustra o tratamento de cdigo necessrio para proteger a aplicao. Ao utilizar a ParamBox em uma funo que tambm utilize parmetros definidos pela funo Pergunte() deve-se: Salvar e restaurar os MV_PARs da Pergunte() Definir variveis Private prprias para a ParamBox, as quais iro armazenar o contedo das MV_PARs que esta retorna. Sintaxe: ParamBox (aParamBox, cTitulo, aRet, bOk, aButtons, lCentered,; nPosx, nPosy, oMainDlg, cLoad, lCanSave, lUserSave) Retorno: lOK indica se a tela de parmetros foi cancelada ou confirmada Parmetros: aParamBox cTitulo aRet bOk aButtons lCentered nPosx nPosy oMainDlg cLoad lCanSave lUserSave Array de parmetros de acordo com a regra da ParamBox Titulo da janela de parmetros Array que ser passado por referencia e retornado com o contedo de cada parmetro Bloco de cdigo para validao do OK da tela de parmetros Array contendo a regra para adio de novos botes (alm do OK e Cancelar) // AADD(aButtons,{nType,bAction,cTexto}) Se a tela ser exibida centralizada, quando a mesma no estiver vinculada a outra janela Posio inicial -> linha (Linha final: nPosX+274) Posio inicial -> coluna (Coluna final: nPosY+445) Caso o ParamBox deva ser vinculado a uma outra tela Nome do arquivo aonde as respostas do usurio sero salvas / lidas Se as respostas para as perguntas podem ser salvas Se o usurio pode salvar sua prpria configurao.
- 155 ADVPL II

Aparncia:

Regras do array aParamBox: [1] Tipo do parmetro: 1[2] [3] [4] [5] [6] [7] [8] [9] 2[2] [3] [4] [5] [6] [7] Para cada tipo de parmetro as demais posies do array variam de contedo conforme abaixo:

MsGet : Descrio : String contendo o inicializador do campo : String contendo a Picture do campo : String contendo a validao : Consulta F3 : String contendo a validao When : Tamanho do MsGet : Flag .T./.F. Parmetro Obrigatrio ? Combo : Descrio : Numrico contendo a opo inicial do combo : Array contendo as opes do Combo : Tamanho do Combo : Validao : Flag .T./.F. Parmetro Obrigatrio ?
- 156 ADVPL II

3[2] [3] [4] [5] [6] [7] 4[2] [3] [4] [5] [6] [7] 5[2] [3] [4] [5] [6]

Radio : Descrio : Numrico contendo a opo inicial do Radio : Array contendo as opes do Radio : Tamanho do Radio : Validao : Flag .T./.F. Parmetro Obrigatrio ? CheckBox ( Com Say ) : Descrio : Indicador Lgico contendo o inicial do Check : Texto do CheckBox : Tamanho do Radio : Validao : Flag .T./.F. Parmetro Obrigatrio ? CheckBox ( linha inteira ) : Descrio : Indicador Lgico contendo o inicial do Check : Tamanho do Radio : Validao : Flag .T./.F. Parmetro Obrigatrio ?

6 - File [2] : Descrio [3] : String contendo o inicializador do campo [4] : String contendo a Picture do campo [5] : String contendo a validao [6] : String contendo a validao When [7] : Tamanho do MsGet [8] : Flag .T./.F. Parmetro Obrigatrio ? [9] : Texto contendo os tipos de arquivo Ex.: "Arquivos .CSV |*.CSV" [10]: Diretrio inicial do CGETFILE() [11]: Parmetros do CGETFILE() 7[2] [3] [4] [5] 8[2] [3] [4] [5] [6] [7] [8] [9] Montagem de expresso de filtro : Descrio : Alias da tabela : Filtro inicial : Opcional - Clausula When Boto Editar Filtro MsGet Password : Descrio : String contendo o inicializador do campo : String contendo a Picture do campo : String contendo a validao : Consulta F3 : String contendo a validao When : Tamanho do MsGet : Flag .T./.F. Parmetro Obrigatrio ?

- 157 ADVPL II

9[2] [3] [4] [5]

MsGet Say : String Contendo o Texto a ser apresentado : Tamanho da String : Altura da String : Negrito (lgico)

Exemplo: Utilizao da ParamBox()

#include protheus.ch /*/ +----------------------------------------------------------------------| Funo | xParamBox | Autor | ROBSON LUIZ |Data | | +----------------------------------------------------------------------| Descrio| Programa que demonstra a utilizao da PARAMBOX como | | | forma alternativa de disponibilizar parmetros em um | | | processamento. +----------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------/*/ User Function xParamBox() Local aRet := {} Local aParamBox := {} Local aCombo := {"Janeiro","Fevereiro","Maro","Abril","Maio","Junho","Julho","Agosto","Setemb ro","Outubro","Novembro","Dezembro"} Local i := 0 Private cCadastro := "xParambox" AADD(aParamBox,{1,"Produto",Space(15),"","","SB1","",0,.F.}) AADD(aParamBox,{2,"Tipo de cliente",1,aCombo,50,"",.F.}) AADD(aParamBox,{3,"Mostra deletados",IIF(Set(_SET_DELETED),1,2), {"Sim","No"},50,"",.F.}) AADD(aParamBox,{4,"Marca todos ?",.F.,"Marque todos se necessrio for.",50,"",.F.}) AADD(aParamBox,{5,"Marca todos ?",.F.,50,"",.F.}) AADD(aParamBox,{6,"Qual arquivo",Space(50),"","","",50,.F.,; "Arquivo .DBF |*.DBF"}) AADD(aParamBox,{7,"Monte o filtro","SX5","X5_FILIAL==xFilial('SX5')"}) AADD(aParamBox,{8,"Digite a senha",Space(15),"","","","",80,.F.}) If ParamBox(aParamBox,"Teste Parmetros...",@aRet) For i:=1 To Len(aRet) MsgInfo(aRet[i],"Opo escolhida") Next Endif Return

- 158 ADVPL II

Exemplo: Protegendo os parmetros MV_PARs da Pergunte() em uso.

#include "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | XPARBOX() | Autor | ARNALDO RAYMUNDO JR.|Data | | +----------------------------------------------------------------------------| Descrio| Funo utilizando a PARAMBOX() e protegendo os MV_PARs | | | ativos do programa principal. | +----------------------------------------------------------------------------| Uso | Curso ADVPL | +----------------------------------------------------------------------------/*/ Static Function XPARBOX(cPerg) Local Local Local Local Local Local Local Local aParamBox := {} cTitulo := "Transferncia para Operao" bOk := {|| .T.} aButtons := {}; Local aRet := {} nPosx; Local nPosy; Local nX := 0 cLoad := "" lCentered := .T.; Local lCanSave := .F.; Local lUserSave := .F. aParamAtu := Array(4)

// Salva as perguntas padres antes da chamada da ParamBox For nX := 1 to Len(aParamAtu) aParamAtu [nX] := &("Mv_Par"+StrZero(nX,2)) Next nX AADD(aParamBox,{2,"Atualiza taxa de depreciao?", 2, {"Sim","No"}, 100,; "AllwaysTrue()",.T.}) ParamBox(aParamBox, cTitulo, aRet, bOk, aButtons, lCentered, nPosx, nPosy, /*oMainDlg*/ ,; cLoad, lCanSave, lUserSave) 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 // Restaura as perguntas padres apos a chamada da ParamBox For nX := 1 to Len(aParamAtu) &("Mv_Par"+StrZero(nX,2)) := aParamAtu[nX] Next nX Return

- 159 ADVPL II

MDULO 05: Introduo a orientao objetos


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

10.1.
Objeto

Definies

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.

- 160 ADVPL II

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

- 161 ADVPL II

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.

- 162 ADVPL II

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

- 163 ADVPL II

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.

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

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

- 164 ADVPL II

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.

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

- 165 ADVPL II

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

- 166 ADVPL II

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

- 167 ADVPL II

11.

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.

11.1.

Sintaxe e operadores para orientao a objetos

Palavras reservadas

CLASS CONSTRUCTOR DATA ENDCLASS FROM METHOD SELF


CLASS Descrio Sintaxe 1 Sintaxe 2 CONSTRUCTOR 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. METHOD <nome_do_mtodo()> CONSTRUCTOR Utilizada na declarao de uma classe de objetos, e para identificar a qual classe um determinado mtodo est relacionado. CLASS <nome_da_classe> METHOD <nome_do_mtodo> CLASS <nome_da_classe>

Descrio Sintaxe DATA Descrio Sintaxe ENDCLASS Descrio Sintaxe

Utilizada na declarao de um atributo da classe de objetos. DATA <nome_do_atributo>

Utilizada na finalizao da declarao da classe. ENDCLASS


- 168 ADVPL II

FROM 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. CLASS <nome_da_classe> FROM <nome_da_superclasse>

Descrio Sintaxe

METHOD Descrio Sintaxe 1 Sintaxe 2 SELF Descrio Sintaxe Utilizada principalmente pelo mtodo construtor para retornar o objeto criado para a aplicao. Return SELF Utilizada na declarao do prottipo do mtodo de uma classe de objetos, e na declarao do mtodo efetivamente desenvolvido. METHOD <nome_do_mtodo()> METHOD <nome_do_mtodo(<parmetros>)> CLASS <nome_da_classe>

Operadores especficos

: Exemplo 1 Exemplo 2

Utilizado para referenciar um mtodo ou um atributo de um objeto j instanciado. cNome := oAluno:sNome 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

- 169 ADVPL II

- 170 ADVPL II

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

- 171 ADVPL II

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

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

- 172 ADVPL II

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

- 173 ADVPL II

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

- 174 ADVPL II

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

- 175 ADVPL II

MDULO 06: ADVPL Orientado objetos I


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.

12.

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

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

- 176 ADVPL II

Tslider

Classes de Componentes Visuais Tsplitter Ttabs Ttoolbox Twbrowse Vcbrowse

Classes da interface visual TSRVOBJECT() Descrio Classe abstrata inicial de todas as classes de interface do ADVPL. No deve ser instanciada diretamente.

Classes auxiliares TFONT() Descrio Classe de objetos que define a fonte do texto utilizado nos controles visuais.

Classes de janelas MSDIALOG() 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.

Descrio

TDIALOG() Classe de objetos do tipo dilogo de entrada de dados, sendo seu uso reservado. Recomenda-se utilizar a classe MSDialog que herdada desta classe.

Descrio TWINDOW() Descrio

Classe de objetos do tipo dilogo principal de programa. Dever existir apenas uma instncia deste objeto na execuo do programa.

Classes de componentes TCONTROL() Descrio Classe abstrata comum entre todos os componentes visuais editveis. No deve ser instanciada diretamente.

- 177 ADVPL II

Classes de componentes visuais BRGETDDB() Descrio MSCALEND() Descrio Classe de objetos visuais do tipo Calendrio. Classe de objetos visuais do tipo Grid.

MSCALENDGRID() Descrio MSSELBR() Descrio Classe de objetos visuais do tipo controle - Grid Classe de objetos visuais do tipo Grade de Perodos.

MSWORKTIME() Descrio SBUTTON() Descrio TBAR() Descrio TBITMAP() Descrio Classe de objetos visuais que permite a exibio de uma imagem. Classe de objetos visuais do tipo Barra Superior. Classe de objetos visuais do tipo boto, o qual pode possuir imagens padres associadas ao seu tipo. Classe de objetos visuais do tipo controle - Barra de Perodo.

TBROWSEBUTTON() Descrio TBTNBMP() Descrio Classe de objetos visuais do tipo boto, o qual permite que seja vinculada uma imagem ao controle. Classe de objetos visuais do tipo boto no formato padro utilizado em browses da aplicao.

- 178 ADVPL II

TBTNBMP2() Descrio TBUTTON() Descrio TCBROWSE() Descrio TCHECKBOX() Descrio Classe de objetos visuais do tipo controle - CheckBox. Classe de objetos visuais do tipo Grid. Classe de objetos visuais do tipo boto, o qual permite a utilizao de texto para sua identificao. Classe de objetos visuais do tipo boto, o qual permite a exibio de uma imagem ou de um popup.

TCOLORTRIANGLE() Descrio TCOMBOBOX() 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. Classe de objetos visuais do tipo Paleta de Cores.

Descrio

TFOLDER() Descrio TGET() 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. Classe de objetos visuais do tipo controle - Folder.

Descrio

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

Descrio

- 179 ADVPL II

THBUTTON() Descrio TIBROWSER() Descrio TLISTBOX() 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. Classe de objetos visuais do tipo Pgina de Internet, sendo necessrio incluir a clausula BrowserEnabled=1 no Config do Remote.INI Classe de objetos visuais do tipo boto com hiperlink.

Descrio TMENU() Descrio TMENUBAR() Descrio TMETER()

Classe de objetos visuais do tipo controle - Menu.

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

Descrio TMSGRAPHIC() Descrio TMSGBAR() Descrio TMULTIBTN() Descrio TMULTIGET() 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.

Classe de objetos visuais do tipo controle - Grfico.

Classe de objetos visuais do tipo controle - Rodap.

Classe de objetos visuais do tipo controle - Mltiplos botes.

Classe de objetos visuais do tipo controle - edio de texto de mltiplas linhas.

- 180 ADVPL II

TOLECONTAINER() Descrio TPAGEVIEW() Descrio TPANEL() 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. Classe de objetos visuais do tipo controle, que permite a visualizao de arquivos no formato gerado pelo spool de impresso do Protheus. Classe de objetos visuais do tipo controle, a qual permite a criao de um boto vinculado a um objeto OLE.

Descrio TRADMENU() Descrio TSBROWSE() Descrio TSAY()

Classe de objetos visuais do tipo controle TRadMenu, a qual permite criar um controle visual no formato Radio Button.

Classe de objetos visuais do tipo controle TSBrowse, a qual permite criar um controle visual do tipo Grid.

Descrio TSCROLLBOX()

Classe de objetos visuais do tipo controle tSay, a qual exibe o contedo de texto esttico sobre uma janela ou controle previamente definidos.

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.

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

Descrio TSLIDER() Descrio TSPLITTER() Descrio

Classe de objetos visuais do tipo controle tSlider, a qual permite criar um controle visual do tipo boto deslizante.

Classe de objetos visuais do tipo controle tSplitter, a qual permite criar um controle visual do tipo divisor.
- 181 ADVPL II

TTABS() Descrio TTOOLBOX() Descrio TWBROWSE() Descrio VCBROWSE() Descrio Classe de objetos visuais do tipo controle VCBrowse, a qual permite criar um controle visual do tipo Grid. Classe de objetos visuais do tipo controle TWBrowse, a qual permite criar um controle visual do tipo Grid. Classe de objetos visuais do tipo controle tToolbox, a qual permite criar um controle visual para agrupar diferentes objetos. Classe de objetos visuais do tipo controle TTabs, a qual permite criar um controle visual do tipo pasta.

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:

- 182 ADVPL II

12.1. 12.1.1.

Particularidades dos componentes visuais 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 B 0 255 0 255 0 255 0 255 Valor 0 16711680 65280 16776960 255 16711935 65535 16777215

- 183 ADVPL II

Para atribuir as cores aos objetos visuais devem ser observados os atributos utilizados para estes fins em cada objeto, como por exemplo: MSDIALOG() nClrPane nClrText Cor de fundo do painel Cor da fonte das letras do painel

TSAY() nClrPane nClrText Cor de fundo do painel 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 nGreen nBlue Retorno Valor de 0-255 para o elemento vermelho da paleta RGB Valor de 0-255 para o elemento verde da paleta RGB Valor de 0-255 para o elemento azul da paleta RGB Valor a ser definido para o atributo cor do componente

- 184 ADVPL II

13.

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

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

- 185 ADVPL II

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

13.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
- 186 ADVPL II

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 Private aRotina := DbSelectArea("SA1") DbSetOrder(1) MBrowse(6,1,22,75,"SA1") Return User Function ModEnc(cAlias,nReg,nOpc) Local aCpoEnch Local aAlter := {} := {} cAlias {} {000,000,400,600} 3 .F. .T. .F. "" .F. .F. := " Cadastro de Clientes" {{"Pesquisar" , "axPesqui" {"Visualizar" , "U_ModEnc" , 0, 1},; , 0, 2}}

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] DbSelectArea("SX3") DbSetOrder(1) DbSeek(cAliasE)

- 187 ADVPL II

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

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

- 188 ADVPL II

lMemoria lColumn caTela lNoFolder lProperty

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

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 Private aRotina := 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] := cAlias {} {000,000,400,600} 3 .F. .T. := .F. := "" .F. .F. := " Cadastro de Clientes" {{"Pesquisar" , "axPesqui" {"Visualizar" , "U_ModEnc" , 0, 1},; , 0, 2}}

- 189 ADVPL II

Private aGETS[0]

- 190 ADVPL II

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

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

- 191 ADVPL II

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

- 192 ADVPL II

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

- 193 ADVPL II

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: 1234Pesquisar Visualizar Incluir Alterar

aHeader

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

- 194 ADVPL II

Variveis pblicas: nBrLin Indica qual a linha posicionada do aCols.

Funes de validao: cLinhaOk cTudoOk 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 := {} 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}}

Private Private Private Private

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

- 195 ADVPL II

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.

- 196 ADVPL II

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

- 197 ADVPL II

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: 6789Pesquisar Visualizar Incluir Alterar

aHeader

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

- 198 ADVPL II

Variveis pblicas: N Indica qual a linha posicionada do aCols.

Funes de validao: cLinhaOk cTudoOk 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")

- 199 ADVPL II

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.

- 200 ADVPL II

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

nMax cFieldOk cSuperDel cDelOk oDLG aHeader aCols

- 201 ADVPL II

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: 1234Pesquisar Visualizar Incluir Alterar

aHeader

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


- 202 ADVPL II

Variveis pblicas: N Indica qual a linha posicionada do aCols.

Funes de validao: cLinhaOk cTudoOk 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 MsNewGetDados com a tabela e posiciona na primeira linha. Oculta a MsNewGetDados. Mostra a MsNewGetDados.

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 Private aRotina := := "Pedidos de Venda" {{"Pesquisar" , "axPesqui" {"Visualizar" , "U_ModGtd" {"Incluir" , "U_ModGtd" , 0, 1},; , 0, 2},; , 0, 3}}

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

- 203 ADVPL II

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 := := := := := := := {000,000,080,400} 3 .F. .T. := .F. := "" .F. .F. := {} "SC6" := 081 := 000 := 250 := 400 := "AllwaysTrue" := "AllwaysTrue" := "C6_ITEM" := 000 := 999 := "AllwaysTrue" := "" := "AllwaysFalse" := {} := {} {}

:=

Private Private Private Private Private

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
- 204 ADVPL II

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
- 205 ADVPL II

13.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 Atributo que dever ser definido como .F. para que as alteraes nas cores sejam permitidas.

Mtodos adicionais: SetBlkBackColor 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:

- 206 ADVPL II

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 Private aRotina := := "Pedidos de Venda" {{"Pesquisar" , "axPesqui" {"Visualizar" , "U_ModGtd" {"Incluir" , "U_ModGtd" , 0, 1},; , 0, 2},; , 0, 3}}

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 := := := := :=
- 207 ADVPL II

Exemplo (continuao): Local Local Local Local Local Local cFieldOk cSuperDel cDelOk aHeader aCols aAlterGDa oDlg oGetD oEnch aTELA[0][0] aGETS[0] := := := := := "AllwaysTrue" "" "AllwaysFalse" {} {} := {}

Private Private Private Private Private

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

- 208 ADVPL II

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

- 209 ADVPL II

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

- 210 ADVPL II

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

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

- 211 ADVPL II

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

- 212 ADVPL II

- 213 ADVPL II

13.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 nBtnWidth nBtnHeight l3D cMode oCursor cResource lNoAutoAdjust Aparncia: Objeto, opcional. Janela ou controle onde o boto dever ser criado. Numrico, opcional. Largura do boto contido na barra Numrico, opcional. Altura do boto contido na barra Lgico, opcional. Define tipo da barra No utilizado. Objeto, opcional. Define Cursor ao posicionar o mouse sobre a barra. Caracter, opcional. Imagem do recurso a ser inserido como fundo da barra. Lgico.

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

- 214 ADVPL II

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

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

- 215 ADVPL II

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 oBar cAcao cTexto Nome da imagem disponvel na aplicao. Objeto do tipo TBar() no qual o boto ser adicionado. 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.

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
- 216 ADVPL II

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" ACTION NaoDisp() TOOLTIP "Recortar" ACTION NaoDisp() TOOLTIP "Copiar" ACTION NaoDisp() TOOLTIP "Colar" oBar GROUP;

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

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

- 217 ADVPL II

13.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 EDIT EXCLUIR GRAF2D LINE OBJETIVO PENDENTE PRODUTO S4WB001N S4WB006N S4WB008N S4WB010N S4WB013N S4WB016N VENDEDOR Exemplo: DISCAGEM EDITABLE FORM GRAF3D NOTE OK PRECO S4SB014N S4WB005N S4WB007N S4WB009N S4WB011N S4WB014A SIMULACA USER

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

- 218 ADVPL II

APNDICES BOAS PRTICAS DE PROGRAMAO


14. Arredondamento

Algumas operaes numricas podem causar diferenas de arredondamento. Isso ocorre devido a diferenas no armazenamento de variveis numricas nos diversos processadores, diferena esta, inclusive, presente no ADVPL, mesmo antes do surgimento do Protheus. Para evitar esses problemas de arredondamento, deve ser utilizada a funo Round(), principalmente antes de realizar uma comparao e antes de se utilizar a funo Int(). Desse modo, assegura-se que o resultado ser correto independentemente do processador ou plataforma. Exemplo 01:

If (Valor/30) == 50 If Round(Valor/30, 0) == 50 Exemplo 02:

// pode ser falso ou invlido // correto

M->EE8_QTDEM1 := Int(M->EE8_SLDINI/M->EE8_QE) // pode ser falso ou invlido M->EE8_QTDEM1 := Int(Round(M->EE8_SLDINI/M->EE8_QE,10)) // correto

15.

Utilizao de Identao

obrigatria a utilizao da identao, pois torna o cdigo muito mais legvel. Veja os exemplos abaixo:

While !SB1->(Eof()) If mv_par01 == SB1->B1_COD dbSkip() Loop Endif Do Case Case SB1->B1_LOCAL == 01 .OR. SB1->B1_LOCAL == 02 TrataLocal(SB1->B1_COD, SB1->B1_LOCAL) Case SB1->B1_LOCAL == 03 TrataDefeito(SB1->B1_COD) OtherWise TrataCompra(SB1->B1_COD, SB1->B1_LOCAL) EndCase dbSkip() EndDo

- 219 ADVPL II

A utilizao da identao seguindo as estruturas de controle de fluxo (while, IF, caso etc.) torna a compreenso do cdigo muito mais fcil:

While !SB1->(Eof()) If mv_par01 == SB1->B1_COD dbSkip() Loop Endif Do Case Case SB1->B1_LOCAL == 01 .OR. SB1->B1_LOCAL == 02 TrataLocal(SB1->B1_COD, SB1->B1_LOCAL) Case SB1->B1_LOCAL == 03 TrataDefeito(SB1->B1_COD) OtherWise TrataCompra(SB1->B1_COD, SB1->B1_LOCAL) EndCase dbSkip() EndDo

Para identar o cdigo utilize a tecla <TAB> e na ferramenta DEV-Studio, a qual pode ser configurada atravs da opo Preferncias:

- 220 ADVPL II

16.

Capitulao de Palavras-Chave

Uma conveno amplamente utilizada a de capitular as palavras chaves, funes, variveis e campos utilizando uma combinao de caracteres em maisculo e minsculo, visando facilitar a leitura do cdigo fonte. O cdigo a seguir:

Local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo

Ficaria melhor com as palavras chaves e variveis capituladas:

Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo

Para funes de manipulao de dados que comecem por db, a capitulao s ser efetuada aps o db: dbSeek() dbSelectArea()

16.1.

Palavras em maisculo

A regra utilizar caracteres em maisculo para: 1 Constantes:

#define NUMLINES 60 #define NUMPAGES 1000

Variveis de memria:

M-> CT2_CRCONV M->CT2_MCONVER := CriaVar("CT2_CONVER")

Campos:

SC6->C6_NUMPED

Querys:

SELECT * FROM...

- 221 ADVPL II

17.

Utilizao da Notao Hngara

A notao hngara consiste em adicionar os prefixos aos nomes de variveis, de modo a facilmente se identificar seu tipo. Isto facilita na criao de cdigos-fonte extensos, pois usando a Notao Hngara, voc no precisa ficar o tempo todo voltando definio de uma varivel para se lembrar qual o tipo de dados que deve ser colocado nela. Variveis devem ter um prefixo de Notao Hngara em minsculas, seguido de um nome que identifique a funo da varivel, sendo que a inicial de cada palavra deve ser maiscula. obrigatria a utilizao desta notao para nomear variveis. Notao a b c d l n o x Tipo de dado Array Bloco de cdigo Caracter Data Lgico Numrico Objeto Indefinido Exemplo aValores bSeek cNome dDataBase lContinua nValor oMainWindow xConteudo

18.

Tcnicas de programao eficiente

Para o desenvolvimento de sistemas e a programao de rotinas, sempre esperado que qualquer cdigo escrito seja: Funcionalmente correto Eficiente Legvel Reutilizvel Extensvel Portvel

Aps anos de experincia na utilizao de linguagens padro xBase e do desenvolvimento da linguagem ADVPL, algumas tcnicas para uma programao otimizada e eficiente foram reconhecidas. A utilizao das tcnicas a seguir, visa buscar o mximo aproveitamento dos recursos da linguagem com o objetivo de criar programas com estas caractersticas. Criao de funes segundo a necessidade Observe o cdigo de exemplo: User Function GetAnswer(lDefault) Local lOk lOk := GetOk(lDefault) If lOk Return .T. Else Return .F. Endif Return nil

- 222 ADVPL II

Utilizando-se apenas o critrio "a funo funciona corretamente?", a funo GetAnswer perfeita. Recebe um parmetro lgico com a resposta padro e retorna um valor lgico dependente da opo escolhida pelo usurio em uma funo de dilogo "sim/no" designada para isso. Pode entretanto ser melhorada, particularmente se eficincia for considerada como um critrio para um cdigo melhor. Eficincia tipicamente envolve a utilizao de poucos recursos de mquina, poucos chamadas de funes ou tornar mais rpido um processo. Segundo esse raciocnio, poderia se produzir o seguinte cdigo:

User Function GetAnswer(lDefault) Return If( GetOk(lDefault), .T., .F.)

O cdigo acima ainda pode ser aprimorado conforme abaixo: User Function GetAnswer(lDefault) Return GetOk(lDefault) Com a otimizao do cdigo da funo GetAnswer(), pode facilmente verificar que a mesma no realiza nada adicional chamada de GetOk(), podendo ser substituda por uma chamada direta desta, continuando a funcionar corretamente. Codificao auto-documentvel Nenhum comentrio substitui um cdigo claramente escrito, e este no um acidente. Considere o exemplo:

cVar := "

" // 11 espaos

O tamanho da varivel cVar no evidente por si s e no facilmente verificado. Estes mesmos 10 espaos estariam mais bvios e ainda assim garantidos se a instruo fosse escrita como: cVar := Space(11)

O mesmo princpio pode ser aplicado para qualquer string longa de caracteres repetidos. A funo Replicate pode ser utilizada como a seguir:

cVar := Replicate( "*", 80 ) Este tipo de programao deixa o cdigo fcil de digitar, fcil de ler e mais flexvel.

- 223 ADVPL II

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

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

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

Pode ser substitudo pelo operador de conteno: If cVar $ "ABCD"

Opo por flexibilidade A melhor soluo aquela que envolve o problema imediato e previne problemas no futuro. Considere o exemplo:

@nRow,nCol PSAY cVar Picture "!!!!!!!!!!!!!!!!!!!!" Exceto contando-se os caracteres, no existe maneira de saber se o nmero de caracteres de exclamao o esperado. Enquanto isto um problema, existem algo mais grave. A expresso de picture esttica. Se no futuro for necessrio ajustar o tamanho da varivel cVar, ser necessrio localizar todos os lugares no cdigo onde esta mscara de picture est sendo utilizada para ajuste manual.

- 224 ADVPL II

Existe uma opo de soluo de auto-ajuste disponvel que fcil de digitar e tem a garantia de executar a tarefa igualmente (tornar todos os caracteres maisculos): @nRow,nCol PSAY cVar Picture "@!"

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

@ 10,25 Say Substr(cCep,1,5) + "-" + Substr(cCep,6,3) Picture "!!!!!!!!!" Este cdigo pode ser escrito de uma forma muito mais simples, conforme demonstrado abaixo:

@ 10,25 Say cCep Picture "@R 99999-999" Utilizao de operadores de incremento/decremento Utilizados devidamente, os operadores de incremento e decremento tornam o cdigo mais fcil de ler e possivelmente um pouco mais rpidos. Ao contrrio de escrever adies simples como:

nVar := nVar + 1 nVar := nVar -1

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

- 225 ADVPL II

Evitar passos desnecessrios Existe uma diferena entre um bom hbito e perda de tempo. Algumas vezes estes conceitos podem estar muito prximos, mas um modo de diferenci-los balancear os benefcios de realizar alguma ao contra o problema que resultaria se no fosse executada. Observe o exemplo: Local nCnt := 0 For nCnt := 1 To 10 <cdigo> Next nCnt Inicializar a varivel no momento da declarao no um problema. Se o 0 fosse necessrio no exemplo, teria sido til a inicializao na declarao. Mas neste caso a estrutura de repetio For...Next atribui o seu valor imediatamente com 1, portanto no houve ganho em atribuir a varivel com 0 no comeo. Neste exemplo no h nenhum ponto negativo e nada errado ocorrer se a varivel no for inicializada, portanto aconselhvel evitar este tipo de inicializao, pois no torna o cdigo mais seguro e tambm no expressa a inteno do cdigo mais claramente. Porm note este exemplo, onde a varivel no inicializada: Local nCnt While ( nCnt++ < 10 ) <cdigo> EndDo Em ADVPL, variveis no inicializadas sempre tem seu valor contendo nulo (nil) a princpio, o que far com que uma exceo em tempo de execuo acontea quando a instruo de repetio while for executada. Diferentemente do primeiro exemplo, onde a inicializao da varivel no fazia diferena alguma, neste segundo exemplo a inicializao absolutamente necessria. Deve-se procurar inicializar variveis numricas com zero (0) e variveis caracter com string nula ("") apenas quando realmente necessrio.

- 226 ADVPL II

Utilizao de alternativas Quando se est trabalhando em uma simples rotina, deve-se tomar algum tempo para explorar duas ou trs diferentes abordagens. Quando se est trabalhando em algo mais complexo, deve-se planejar prototipar algumas a mais. Considere o seguinte cdigo: If cHair = "A" Replace hair With "Loira" Else If cHair = "B" Replace hair With "Morena" Else If cHair = "C" Replace hair With "Ruiva" Else If cHair = "D" Replace hair With "Grisalho" Else Replace hair With "Preto" Endif Endif Endif Endif

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

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

- 227 ADVPL II

Utilizao de arquivos de cabealho quando necessrio Se um arquivo de cdigo criado se referencia a comandos para interpretao e tratamento de arquivos XML, este deve se incluir o arquivo de cabealho prprio para tais comandos (XMLXFUN.CH no exemplo). Porm no deve-se incluir arquivos de cabealho apenas por segurana. Se no se est referenciando nenhuma das constantes ou utilizando nenhum dos comandos contidos em um destes arquivos, a incluso apenas tornar a compilao mais demorada. Constantes em maisculo Isto uma conveno que faz sentido. Em ADVPL, como em C por exemplo, a regra utilizar todos os caracteres de uma constante em maisculo, a fim de que possam ser claramente reconhecidos como constantes no cdigo, e que no seja necessrios lembrar onde foram declarados. Utilizao de identao Este um hbito que todo programador deve desenvolver. No consome muito esforo para manter o cdigo alinhado durante o trabalho, porm quando necessrio pode-se utilizar a ferramenta TOTVS DevStudio para a re-identao de cdigo. Para maiores detalhes, consulte a documentao sobre a identao de cdigos fontes disponvel nos demais tpicos deste material. Utilizao de espaos em branco Espaos em branco extras tornam o cdigo mais fcil para a leitura. No necessrio imensas reas em branco, mas agrupar pedaos de cdigo atravs da utilizao de espaos em branco funciona muito bem. Costuma-se separar parmetros com espaos em branco. Quebra de linhas muito longas Com o objetivo de tornar o cdigo mais fcil de ler e imprimir, as linhas do cdigo no devem estender o limite da tela ou do papel. Podem ser "quebradas" em mais de uma linha de texto utilizando o ponto-e-vrgula (;). Capitulao de palavras-chave Uma conveno amplamente utilizada a de capitular as palavras chaves, funes, variveis e campos utilizando uma combinao de caracteres em maisculo e minsculo, visando facilitar a leitura do cdigo fonte. Avaliando o cdigo a seguir:

local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo

- 228 ADVPL II

O mesmo ficaria muito mais claro se re-escrito conforme abaixo:

Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo Utilizao da Notao Hngara A Notao Hngara muito comum entre programadores xBase e de outras linguagens. A documentao do ADVPL utiliza esta notao para a descrio das funes e comandos e aconselhvel sua utilizao na criao de rotinas, pois ajuda a evitar pequenos erros e facilita a leitura do cdigo. Para maiores detalhes, consulte a documentao sobre a utilizao da Notao Hngara de cdigos fontes disponvel nos demais tpicos deste material. Utilizao de nomes significantes para variveis A principal vantagem da liberdade na criao dos nomes de variveis a facilidade de identificao da sua utilidade. Portanto deve-se utilizar essa facilidade o mximo possvel. Nomes sem sentido apenas tornaro difcil a identificao da utilidade de uma determinada varivel, assim como nomes extremamente curtos. Nem sempre a utilizao de uma varivel chamada i a melhor sada. Claro, no convm criar uma varivel com um nome muito longo que ser utilizada como um contador, e referenciada muitas vezes no cdigo. O bom senso deve ser utilizado. Criar variveis como nNumero ou dData tambm no ajudam na identificao. A Notao Hngara j est sendo utilizada para isso e o objetivo do nome da varivel deveria ser identificar sua utilizao, no o tipo de dado utilizado. Deve-se procurar substituir tais variveis por algo como nTotal ou dCompra. O mesmo vlido para nomes de funes, que devem descrever um pouco sobre o que a funo faz. Novamente nomes extremamente curtos no so aconselhveis. Utilizao de comentrios Comentrios so muito teis na documentao de programas criados e para facilitar a identificao de processos importantes no futuro e devem sempre ser utilizados. Sempre que possvel, funes criadas devem ter uma breve descrio do seu objetivo, parmetros e retorno. Alm de servir como documentao, os comentrios embelezam o cdigo ao separar as funes umas das outras. Os comentrios devem ser utilizados com bom senso, pois reescrever a sintaxe ADVPL em portugus torna-se apenas perda de tempo:

If nLastKey == 27 // Se o nLastKey for igual a 27

- 229 ADVPL II

Criao de mensagens sistmicas significantes e consistentes Seja oferecendo assistncia, exibindo mensagens de aviso ou mantendo o usurio informado do estado de algum processo, as mensagens devem refletir o tom geral e a importncia da aplicao. Em termos gerais, deve-se evitar ser muito informal e ao mesmo tempo muito tcnico.

"Aguarde. Reindexando (FILIAL+COD+ LOCAL) do arquivo: \DADOSADV\SB1990.DBF"

Esse tipo de mensagem pode dar informaes demais para o usurio e deix-lo sentindo-se desconfortvel se no souber o que significa "reindexando", etc. E de fato, o usurio no devia ser incomodado com tais detalhes. Apenas a frase "Aguarde, indexando." funcionaria corretamente, assim como palavras "processando" ou "reorganizando". Outra boa idia evitar a referencia a um item corrente de uma tabela como um "registro":

"Deletar este registro?"

Se a operao estiver sendo efetuada em um arquivo de clientes, o usurio deve ser questionado sobre a remoo do cliente corrente, se possvel informando valores de identificao como o cdigo ou o nome. Evitar abreviao de comandos em 4 letras Apesar do ADVPL suportar a abreviao de comandos em quatro letras (por exemplo, repl no lugar de replace) no h necessidade de utilizar tal funcionalidade. Isto apenas torna o cdigo mais difcil de ler e no torna a compilao mais rpida ou simples. Evitar "disfarces" no cdigo No deve-se criar constantes para expresses complexas. Isto tornar o cdigo muito difcil de compreender e poder causar erros primrios, pois pode-se imaginar que uma atribuio efetuada a uma varivel quando na verdade h toda uma expresso disfarada:

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

- 230 ADVPL II

A impresso que se tem aps uma leitura deste cdigo de que valores esto sendo atribudos s variveis ou que constantes esto sendo utilizadas. Se o objetivo flexibilidade, o cdigo anterior deve ser substitudo por:

#define NUMLINES 1 #define NUMPAGES 2 #define ISDISK 5 If aReturn[ISDISK] == 1 aPrintDefs[ NUMLINES ] := 55 Endif aPrintDefs[ NUMPAGES ] += 1 Evitar cdigo de segurana desnecessrio Dada sua natureza binria, tudo pode ou no acontecer dentro de um computador. Adicionar pedaos de cdigo apenas para "garantir a segurana" freqentemente utilizado como uma desculpa para evitar corrigir o problema real. Isto pode incluir a checagem para validar intervalos de datas ou para tipos de dados corretos, o que comumente utilizando em funes:

Static Function MultMalor( nVal ) If ValType( nVal ) != "N" nVal := 0 Endif Return ( nVal * nVal ) O ganho irrisrio na checagem do tipo de dado do parmetro j que nenhum programa corretamente escrito em execuo poderia enviar uma string ou uma data para a funo. De fato, este tipo de "captura" o que torna a depurao difcil, j que o retorno ser sempre um valor vlido (mesmo que o parmetro recebido seja de tipo de dado incorreto). Se esta captura no tiver sido efetuada quando um possvel erro de tipo de dado invlido ocorrer, o cdigo pode ser corrigido para que este erro no mais acontea. Isolamento de strings de texto No caso de mensagens e strings de texto, a centralizao um bom negcio. Pode-se colocar mensagens, caminhos para arquivos, e mesmo outros valores em um local especfico. Isto os torna acessveis de qualquer lugar no programa e fceis de gerenciar. Por exemplo, se existe uma mensagem comum como "Imprimindo, por favor aguarde..." em muitas partes do cdigo, corre-se o risco de no seguir um padro para uma das mensagens em algum lugar do cdigo. E mant-las em um nico lugar, como um arquivo de cabealho, torna fcil a produo de documentao e a internacionalizao em outros idiomas.

- 231 ADVPL II

- 232 ADVPL II

Educao Corporativa

Guia de Referncia Rpida ADVPL Intermedirio

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

- 234 Guia de Referncia Rpida ADVPL Intermedirio

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)

- 235 Guia de Referncia Rpida ADVPL Intermedirio

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 nTamanho Valor numrico que ser convertido para caractere. Tamanho total desejado para a string retornada.

Exemplo: FOR nPercorridos := 1 to 10 MSGINFO(Passos percorridos: +CvalToChar(nPercorridos)) NEXT nPercorridos

- 236 Guia de Referncia Rpida ADVPL Intermedirio

VAL() Realiza a converso de uma informao do tipo caracter em numrica. Sintaxe: VAL(cValor) Parmetros cValor 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) String que ser convertida para numrico.

- 237 Guia de Referncia Rpida ADVPL Intermedirio

Matemticas
ACOS() Funo utilizada para calcular o valor do arco co-seno. Sintaxe: ACOS(nValor) Parmetros: nValor 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 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 Retorno: Numrico Valor que representa o co-seno ou co-seno hiperblico do ngulo informado. Valor que representa o ngulo em radianos. Valor limite para anlise da funo, no formato floating-point. Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.

- 238 Guia de Referncia Rpida ADVPL Intermedirio

Situaes invlidas: Entrada QNAN,IND (cosf, cos) x 7.104760e+002 (cosh, coshf) 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 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). Valor cujo o logaritmo deve ser encontrado. Exceo apresentada None INVALID INEXACT+OVERFLOW Significado da Exceo Sem Domnio Sem Domnio OVERFLOW

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 Retorna o valor do seno do ngulo especificado. Valor do ngulo em radianos.

Situaes invlidas: Entrada QNAN,IND (senf, sen) x 7.104760e+002 (senh, senhf) Exceo apresentada None INVALID INEXACT+OVERFLOW Significado da Exceo Sem Domnio Sem Domnio OVERFLOW

- 239 Guia de Referncia Rpida ADVPL Intermedirio

SQRT() Funo utilizada para calcular a raiz quadrada de um nmero positivo. Sintaxe: SQRT(nValor) Parmetros: nValor 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. Um nmero positivo do qual ser calculada a raiz quadrada.

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 Retorna o valor da tangente do ngulo especificado. Valor do ngulo em radianos.

Situaes invlidas: Entrada QNAN,IND Exceo apresentada None INVALID Significado da Exceo Sem Domnio Sem Domnio

- 240 Guia de Referncia Rpida ADVPL Intermedirio

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

- 241 Guia de Referncia Rpida ADVPL Intermedirio

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 xItem 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 Array pr-existente no qual ser adicionado o item definido em xItem Item que ser adicionado ao array.

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
- 242 Guia de Referncia Rpida ADVPL Intermedirio

// aDados [3][2] -> corresponde ao contedo de cVariavel2 // aDados [3][3] -> corresponde ao contedo de cVariavel3 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 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. Array pr-existente que ter seu contedo copiado para o array especificado.

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 aDestino o array que contm os elementos a serem copiados. o array que receber a cpia dos elementos.
- 243 Guia de Referncia Rpida ADVPL Intermedirio

nInicio nQtde

nPosDestino

indica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se no for especificado, o valor assumido ser 01. 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 nPosio 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. Array do qual deseja-se remover uma determinada posio Posio do array que ser removida

- 244 Guia de Referncia Rpida ADVPL Intermedirio

ADIR() Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados. Importante: ADir uma funo obsoleta, utilize sempre Directory(). Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora], [ aAtributo ]) Parmetros: cArqEspec Caminho dos arquivos a serem includos na busca de informaes. Segue o padro para especificao de arquivos, aceitando arquivos no servidor Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ). 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.

aNomeArq aTamanho aData aHora aAtributos

Retorno: nArquivos Exemplo: LOCAL aFiles[ADIR("*.TXT")] ADIR("*.TXT", aFiles) AEVAL(aFiles, { |element| QOUT(element) }) Quantidade de arquivos encontrados.

- 245 Guia de Referncia Rpida ADVPL Intermedirio

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 xExpValor nInicio nCount o onde os dados sero preenchidos. 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. 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 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. } Retorna uma referncia para aDestino.

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 nPosicao Exemplo: aAlunos := {Edson, Robson, Renato, Tatiana} AINS(aAlunos,3) // Neste ponto o array aAlunos ter o seguinte contedo: // {Edson, Robson, nulo, Renato, Tatiana} Array pr-existente no qual desejasse inserir um novo elemento. Posio na qual o novo elemento ser inserido.

- 246 Guia de Referncia Rpida ADVPL Intermedirio

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 nColunas Exemplo: aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas. Determina o nmero de linhas com as quais o array ser criado Determina o nmero de colunas com as quais o array ser criado

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 Exemplo: aAlunos := {Mrcio, Denis, Arnaldo, Patrcia} bSeek := {|x| x == Denis} nPosAluno := aScan(aAlunos,bSeek) // retorno esperado 2 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.

- 247 Guia de Referncia Rpida ADVPL Intermedirio

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

- 248 Guia de Referncia Rpida ADVPL Intermedirio

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 nTamanho Array pr-existente que ter sua estrutura redimensionada. 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.

- 249 Guia de Referncia Rpida ADVPL Intermedirio

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}

- 250 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: nUltimo Exemplo: aArray := {"a", "b", "c", "d"} ATAIL(aArray) // Resultado: d Nmero do ltimo elemento do array. o array de onde ser retornado o ltimo elemento.

- 251 Guia de Referncia Rpida ADVPL Intermedirio

- 252 Guia de Referncia Rpida ADVPL Intermedirio

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 xParamZ Bloco de cdigo que ser interpretado. 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 bFor bWhile Bloco de cdigo principal, contendo as expresses que sero avaliadas para cada registro do alias ativo. Condio para continuao da anlise dos registros, com o efeito de uma estrutura For ... Next. Condio para continuao da anlise dos registros, com o efeito de uma estrutura While ... End

- 253 Guia de Referncia Rpida ADVPL Intermedirio

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.

- 254 Guia de Referncia Rpida ADVPL Intermedirio

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 bBloco nInicio 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)))}) Array que ser avaliado na execuo da funo. Bloco de cdigo principal, contendo as expresses que sero avaliadas para cada elemento do array informado. 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.

- 255 Guia de Referncia Rpida ADVPL Intermedirio

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"

- 256 Guia de Referncia Rpida ADVPL Intermedirio

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 cString Caractere ou string que se deseja verificar 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
- 257 Guia de Referncia Rpida ADVPL Intermedirio

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 nBitIni nBitEnd nStrLen 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 Retorno: String 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 Contedo da string original com as modificaes necessrias para atender a condio da funo. String a ser avaliada String no qual desejamos ligar os bits. Indica a partir de qual bit, comear a ser ligados os bits na String Indica a quantidade de bits que sero ligados a partir do inicio. Representa o tamanho da String passada para a funo.

Exemplo: #DEFINE CRLF CHR(13)+CHR(10) // FINAL DE LINHA

- 258 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Caracter String complementada da string analisada. Corresponde seqncia de caracteres a ser 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 Retorno: Numrico Retorna um dado numrico de acordo com o valor informado em <cDtoVal>. Representa uma string contendo um valor numrico no qual ser convertido.

- 259 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Lgico 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 Retorno: Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito entre zero e nove; caso contrrio, retorna falso (.F.). Cadeia de caracteres a ser examinada. Retorna verdadeiro (.T.) se o primeiro caractere em <cString> for alfabtico, caso contrrio, retorna falso (.F.). Cadeia de caracteres a ser examinada.

- 260 Guia de Referncia Rpida ADVPL Intermedirio

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

Exemplo: cNome := ALLTRIM(SA1->A1_NOME) MSGINFO(Dados do campo A1_NOME:+CRLF Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF Texto: + CVALTOCHAR(LEN(cNome)))

- 261 Guia de Referncia Rpida ADVPL Intermedirio

LOWER() Retorna uma string com todos os caracteres minsculos, tendo como base a string passada como parmetro. Sintaxe: LOWER(cString) Parmetros cString Exemplo: cTexto := ADVPL MSGINFO(Texto:+LOWER(cTexto)) String que ser convertida para caracteres minsculos.

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

- 262 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Caracter String convertida para ser exibida no Windows ( Formato ANSI ). String em formato OEM - MsDos a ser convertida.

- 263 Guia de Referncia Rpida ADVPL Intermedirio

PADL() / PADR() / PADC() Funes de tratamento de strings que inserem caracteres de preenchimento para completar um tamanho previamente especificado em vrios formatos como data ou numricos. PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e esquerda. PADL() adiciona caracteres de preenchimento esquerda. PADR() adiciona caracteres de preenchimento direita. Caso o tamanho de <cExp> exceda o argumento <nTamanho>, todas as funes PAD() truncam string preenchida ao <nTamanho> especificado. PADC(), PADL(), e PADR() so utilizadas para exibir cadeias de caracteres de tamanho varivel em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para assegurar o alinhamento com comandos ?? consecutivos. Outra utilizao exibir textos em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi completamente sobrescrito. PADC(), PADL(), e PADR() so o contrrio das funes ALLTRIM(), LTRIM(), e LTRIM(), as quais eliminam espaos em branco esquerda e direita de cadeias de caracteres. Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench ] ) Parmetros cExp nTamanho cCaracPreench Caractere, data, ou numrico no qual sero inseridos caracteres de preenchimento. Tamanho da cadeia de caracteres a ser retornada. 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 cString Caractere ou string que se deseja verificar String na qual ser verificada a existncia do contedo de cCaractere.

- 264 Guia de Referncia Rpida ADVPL Intermedirio

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 nCount Caracter que ser repetido Quantidade de ocorrncias do caracter base que sero geradas na string de destino.

Retorno: cReplicated 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. String contendo as ocorrncias de repeticao geradas para o caracter informado.

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

- 265 Guia de Referncia Rpida ADVPL Intermedirio

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

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

STRTOKARR() Funo utilizada para retornar um array, de acordo com os dados passados como parmetro para a funo. Esta funo recebe uma string <cValue> e um caracter <cToken> que representa um separador, e para toda ocorrncia deste separador em <cValue> adicionado um item no array. Sintaxe: STRTOKARR ( < cValue > , < cToken > ) Parmetros: cValue cToken Retorno: Array Exemplo: STRTOKARR('1;2;3;4;5', ';') //retorna {'1','2','3','4','5'} Array de caracteres que representa a string passada como parmetro. Representa a cadeia de caracteres no qual desejamos separar de acordo com <cToken>. Representa o caracter que indica o separador em <cValue>.

- 266 Guia de Referncia Rpida ADVPL Intermedirio

STRTRAN() Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive. Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) Parmetros: cString cSearch cReplace nStart Seqncia de caracteres ou campo memo a ser pesquisado. Seqncia de caracteres a ser procurada em cString. 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.

nCount

Retorno: Code-Block A funo STRTRAN retorna especificadas de cSearch parametrizao. uma nova string, com as ocorrncias trocadas para cReplace, conforme

STUFF() Funo que permite substituir um contedo caractere em uma string j existente, especificando a posio inicial para esta adio e o nmero de caracteres que sero substitudos. Sintaxe: STUFF(cString, nPosInicial, nExcluir, cAdicao) Parmetros: cString nPosInicial nExcluir cAdicao Retorno: Caracter Retorna a nova string gerada pela funo com as modificaes. 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. A cadeia de caracteres a ser inserida.

- 267 Guia de Referncia Rpida ADVPL Intermedirio

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 nPosInicial nCaracteres String que se deseja verificar Posio inicial da informao que ser extrada da string Quantidade de caracteres que dever ser retornada a partir daquele ponto (inclusive).

Exemplo: cCampo := A1_NOME nPosUnder := AT(cCampo) cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_

TRANSFORM() Funo de converso que formata valores caractere, data, lgicos e numricos conforme um string de mscara especificado, a qual inclui uma combinao de strings de template e funes de picture. Ela faz o mesmo que a clusula PICTURE do comando @...SAY, sendo normalmente utilizada para formatar dados a serem enviados tela ou impressora. Sintaxe: TRANSFORM ( < cExp > , < cSayPicture > ) Parmetros: cExp 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>.

- 268 Guia de Referncia Rpida ADVPL Intermedirio

UPPER() Retorna uma string com todos os caracteres maisculos, tendo como base a string passada como parmetro. Sintaxe: UPPER(cString) Parmetros cString Exemplo: cTexto := ADVPL MSGINFO(Texto:+LOWER(cTexto)) String que ser convertida para caracteres maisculos.

- 269 Guia de Referncia Rpida ADVPL Intermedirio

Manipulao de data / hora


CDOW() Funo que converte uma data para uma cadeia de caracteres. Sintaxe: CDOW( dExp ) Parmetros: dExp Retorno: cDayWeek Nome do dia da semana como uma cadeia de caracteres. A primeira letra maiscula e as demais minsculas. Data que ser convertida.

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

CMONTH() Funo de converso de datas que retorna uma cadeia de caracteres com o nome do ms em ingls. Sintaxe: CMONTH( dData ) Parmetros: dData Retorno: cMonth Retorna o nome do ms em uma cadeia de caracteres. A primeira letra do retorno em maiscula e o restante do nome, em minsculas. Data que ser convertida.

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

- 270 Guia de Referncia Rpida ADVPL Intermedirio

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 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 Data do sistema. .

DAY() Funo de converso de datas usada para converter o valor data em um nmero inteiro que representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR() para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas. Sintaxe: DAY( dData ) Parmetros: dData Retorno: nDias Se o ms do argumento dData for fevereiro, anos bissextos so considerados. Se a data do argumento dData for 29 de fevereiro e o ano no for bissexto, ou se o argumento dData for vazio. Data que ser convertida.

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

- 271 Guia de Referncia Rpida ADVPL Intermedirio

DOW() Funo que converte uma data para o valor numrico que representa o dia da semana. til quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o dia da semana como uma cadeia de caracteres. Sintaxe: DOW( dData ) Parmetros: dData Retorno: nDia Retorna um nmero entre zero e sete, representando o dia da semana. O primeiro dia da semana 1 (Domingo) e o ltimo 7 (Sbado). Se a data for vazia ou invlida, DOW() retorna zero. Data que ser convertida.

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

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

- 272 Guia de Referncia Rpida ADVPL Intermedirio

DTOS() Funo para converso de uma data que pode ser usada para criar expresses de ndice. O resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia). Sintaxe: DTOS( dData ) Parmetros: dData Retorno: sData Retorna uma cadeia de caracteres com oito byte de tamanho no formato yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia de caracteres com oito espaos. O valor retornado no afetado pela formato da data corrente. Data que ser convertida.

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)

- 273 Guia de Referncia Rpida ADVPL Intermedirio

MONTH() Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que retorna o nome do ms a partir do valor de dData. Sintaxe: MONTH( dData ) Parmetros: dData Retorno: Numrico >=0 e <=12 Para uma data vlida. 0 Se a data for nula ou invlida Data que ser convertida.

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

- 274 Guia de Referncia Rpida ADVPL Intermedirio

TIME() Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos. Sintaxe: TIME() Parmetros: Nenhum Retorno: Caracter A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos. .

Exemplo: cTime := TIME() // Resultado: 10:37:17 cHora := SUBSTR(cTime, 1, 2) // Resultado: 10 cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37 cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17

YEAR() YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR() membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui DAY() e MONTH() que retornam o dia e o ms como valores numricos. Sintaxe: YEAR( dData ) Parmetros: dData Retorno: Numrico Valor numrico do ano da data especificada em dData incluindo os dgitos do sculo. O valor retornado no afetado pelos valores especificados pelos comandos SET DATE ou SET CENTURY. Para uma data invlida ou nula ser retornado o valor 0. Data que ser convertida.

Exemplo 01: dData := DATE() // Resultado: 09/20/01 dAno := YEAR(dData) // Resultado: 2001 dAno := YEAR(dData) + 11 // Resultado: 2012

- 275 Guia de Referncia Rpida ADVPL Intermedirio

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 Exemplo: nPessoas := 20 nLugares := 18 IF nPessoas < nLugares MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis) ELSE MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando) ENDIF Valor que ser avaliado

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 nSeed Nmero mximo para a gerao do nmero aleatrio Semente para a gerao do nmero aleatrio

- 276 Guia de Referncia Rpida ADVPL Intermedirio

Exemplo Funo ALEATORIO() nSeed := 0 For i := 1 to 100 nSeed := Aleatorio(100,nSeed) ? Str(i,3)+ numero aleatorio gerado: +Str(nSeed,3) Next i inkey(0) Return

INT() Retorna a parte inteira de um valor especificado no parmetro. Sintaxe: INT(nValor) Parmetros nValor Exemplo: STATIC FUNCTION COMPRAR(nQuantidade) LOCAL nDinheiro := 0.30 LOCAL nPrcUnit := 0.25 IF nDinheiro >= (nQuantidade*nPrcUnit) RETURN nQuantidade ELSEIF nDinheiro > nPrcUnit nQuantidade := INT(nDinheiro / nPrcUnit) ELSE nQuantidade := 0 ENDIF RETURN nQuantidade Valor que ser avaliado

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 nCasas Valor que ser avaliado Nmero de casas decimais vlidas. A partir da casa decimal especificada os valores sero desconsiderados.

- 277 Guia de Referncia Rpida ADVPL Intermedirio

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

ROUND() Retorna um valor, arredondando a parte decimal do valor especificado no parmetro de acordo com a quantidades de casas decimais solicitadas, utilizando o critrio matemtico. Sintaxe: ROUND(nValor, nCasas) Parmetros nValor nCasas Valor que ser avaliado 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

- 278 Guia de Referncia Rpida ADVPL Intermedirio

Manipulao de arquivos
ADIR() Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados. Importante: ADir uma funo obsoleta, utilize sempre Directory(). Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora], [ aAtributo ]) Parmetros: cArqEspec Caminho dos arquivos a serem includos na busca de informaes. Segue o padro para especificao de arquivos, aceitando arquivos no servidor Protheus e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso seja omitido, sero aceitos todos os arquivos do diretrio default ( *.* ). 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.

aNomeArq aTamanho aData aHora aAtributos

Retorno: nArquivos Exemplo: LOCAL aFiles[ADIR("*.TXT")] ADIR("*.TXT", aFiles) AEVAL(aFiles, { |element| QOUT(element) }) Quantidade de arquivos encontrados.

- 279 Guia de Referncia Rpida ADVPL Intermedirio

- 280 Guia de Referncia Rpida ADVPL Intermedirio

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 ExpC2 ExpN1 ExpC3 Expl1 ExpN2 ExpL2 Mascara para filtro (Ex: 'Informes Protheus (*.##R) | *.##R') Titilo da Janela Numero da mascara default ( Ex: 1 p/ *.exe ) Diretrio inicial se necessrio .T. para mostrar boto como 'Salvar' e .F. para boto 'Abrir' Mascara de bits para escolher as opes de visualizao do Objeto. .T. para exibir diretrio [Servidor] e .F. para no exibir

Mscaras de bits para opes: GETF_OVERWRITEPROMPT GETF_MULTISELECT GETF_NOCHANGEDIR GETF_LOCALFLOPPY GETF_LOCALHARD GETF_NETWORKDRIVE GETF_SHAREWARE GETF_RETDIRECTORY Solicita confirmao para sobrescrever Permite selecionar mltiplos arquivos No permite mudar o diretrio inicial Exibe o(s) Drive(s) de disquete da maquina local Exibe o(s) HardDisk(s) Local(is) Exibe os drives da rede ( Mapeamentos ) No implementado Retorna um diretrio

Exemplo: cGetFile ( '*.PRW|*.CH' GETF_LOCALFLOPPY) , 'Fontes', 1, 'C:\VER507', .F., GETF_LOCALHARD +

- 281 Guia de Referncia Rpida ADVPL Intermedirio

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.

- 282 Guia de Referncia Rpida ADVPL Intermedirio

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

- 283 Guia de Referncia Rpida ADVPL Intermedirio

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

- 284 Guia de Referncia Rpida ADVPL Intermedirio

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

- 285 Guia de Referncia Rpida ADVPL Intermedirio

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

- 286 Guia de Referncia Rpida ADVPL Intermedirio

CPYS2T() Funo utilizada para copiar um arquivo do servidor para o cliente (Remote), sendo que os caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada (lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do uso. Sintaxe: CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) Parmetros: cOrigem cDestino lCompacta Retorno: Lgico lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em caso de falha na cpia. 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 ). Indica se a cpia deve ser feita compactando o arquivo antes do envio.

Exemplo: // Copia arquivos do servidor para o remote local, compactando antes de transmitir CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. ) // Copia arquivos do servidor para o remote local, sem compactar antes de transmitir CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. )

CPYT2S() Funo utilizada para copiar um arquivo do cliente (Remote) para o servidor, sendo que os caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada (lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do uso. Sintaxe: CpyT2S( cOrigem, cDestino, [ lCompacta ]) Parmetros: cOrigem cDestino lCompacta Retorno: Lgico Indica se o arquivo foi copiado para o cliente com sucesso. Nomes dos arquivos a serem copiados, aceita apenas arquivos locais ( Cliente ), WildCards so aceitos normalmente. Diretrio com o destino dos arquivos no remote ( Cliente ). Indica se a cpia deve ser feita compactando o arquivo antes.

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

- 287 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Caracter Diretrio corrente, sem a primeira barra. Caminho relativo , com o novo diretrio que ser ajustado como corrente.

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

- 288 Guia de Referncia Rpida ADVPL Intermedirio

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 H S D V 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 1 2 3 4 5 Metasmbolo cNome cTamanho dData cHora cAtributos Directry.ch F_NAME F_SIZE F_DATE F_TIME F_ATT

Sintaxe: DIRECTORY ( < cDirSpec > , [ ] ) Parmetros: cDirSpec <cDirSpec> especifica o drive, diretrio e arquivo para a pesquisa no diretrio. Caracteres do tipo coringa so permitidos na especificao de arquivos. Caso <cDirSpec> seja omitido, o valor padro *.*. O caminho especificado pode estar na estao (remote) , ou no servidor, obedecendo s definies de Path Absoluto / Relativo de acesso. <cAtributos> 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.

cAtributos>

- 289 Guia de Referncia Rpida ADVPL Intermedirio

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 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(). Nome do diretrio a ser removido.

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

- 290 Guia de Referncia Rpida ADVPL Intermedirio

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

- 291 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Lgico Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos; do contrrio, retorna verdadeiro (.T.). Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().

- 292 Guia de Referncia Rpida ADVPL Intermedirio

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

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

- 293 Guia de Referncia Rpida ADVPL Intermedirio

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.

- 294 Guia de Referncia Rpida ADVPL Intermedirio

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 Exemplo: Local cString := '\SIGAADV\ARQZZZ.DBF' cString := FileNoExt( cString ) // Retorno \SIGAADV\ARQZZZ String contendo o nome do arquivo.

- 295 Guia de Referncia Rpida ADVPL Intermedirio

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 nModo Nome do arquivo a ser aberto que inclui o path caso haja um. Modo de acesso DOS solicitado que indica como o arquivo aberto deve ser acessado. O acesso de uma das categorias relacionadas na tabela A e as restries de compartilhamento relacionada na Tabela B. O modo 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.

- 296 Guia de Referncia Rpida ADVPL Intermedirio

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

Tabela B: Modos de acesso de compartilhamento a arquivos binrios Modo 0 16 32 48 64 Constate(fileio.ch) FO_COMPAT FO_EXCLUSIVE FO_DENYWRITE FO_DENYREAD FO_DENYNONE Operao Modo de Compatibilidade (Default) Acesso total exclusivo 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.

- 297 Guia de Referncia Rpida ADVPL Intermedirio

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

nQtdBytes

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 Retorno: Caracter Retorna uma string contendo os caracteres lidos. o manipulador retornado pelas funes FOPEN(), FCREATE(), FOPENPORT(). Nmero mximo de bytes que devem ser lidos.

- 298 Guia de Referncia Rpida ADVPL Intermedirio

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.

- 299 Guia de Referncia Rpida ADVPL Intermedirio

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

Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) Parmetros: nHandle nOffSet 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(). Manipulador obtido atravs das funes FCREATE,FOPEN. 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.

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

- 300 Guia de Referncia Rpida ADVPL Intermedirio

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).
- 301 Guia de Referncia Rpida ADVPL Intermedirio

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

- 302 Guia de Referncia Rpida ADVPL Intermedirio

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 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. Retorna a posio corrente do ponteiro do arquivo texto. .

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
- 303 Guia de Referncia Rpida ADVPL Intermedirio

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)

- 304 Guia de Referncia Rpida ADVPL Intermedirio

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

- 305 Guia de Referncia Rpida ADVPL Intermedirio

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 cArqDest Retorno: Lgico Exemplo: Local cArqOrig := 'ARQ00001.DBF' Local cArqDest := 'ARQ00002.XXX' If MsCopyFile( cArqOrig, cArqDest ) APMsgInfo('Copia realizada com sucesso!') EndIf Se a copia for realizada com sucesso a funo retornar verdadeiro (.T.). Nome do arquivo origem e a extenso. Nome do arquivo destino e a extenso.

- 306 Guia de Referncia Rpida ADVPL Intermedirio

MSCOPYTO() Funo que realiza a cpia dos registros de uma base de dados para outra, criando o arquivo destino de acordo com a estrutura da base de dados origem. Sintaxe: MSCOPYTO( [cArqOrig], cArqDest ) Parmetros: cArqOrig cArqDest Retorno: Lgico Exemplo: Local cArqDest := 'SX2ZZZ.DBF' DbSelectArea('SX2') If MsCopyTo( , cArqDest ) APMsgInfo('Copia realizada com sucesso!') Else APMsgInfo('Problemas ao copiar o arquivo SX2!') EndIf Se a copia for realizada com sucesso a funo retornar verdadeiro (.T.). Nome do arquivo origem e a extenso se o ambiente for Top o parmetro passar a ser obrigatrio. Nome do arquivo destino e a extenso.

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 aStruct cDriver Nome do arquivo. Estrutura do arquivo. RDD do arquivo.

- 307 Guia de Referncia Rpida ADVPL Intermedirio

Retorno: Lgico 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 Indica se a operao foi executada com sucesso.

MSERASE() Funo utilizada para deletar fisicamente o arquivo especificado. Sintaxe: MsErase( cArquivo, [cIndice], [cDriver] ) Parmetros: cArquivo cIndice cDriver Retorno: Lgico 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 Indica se a operao foi executada com sucesso. Nome do arquivo e a extenso. Nome do arquivo de ndice e a extenso. RDD do arquivo, se no for informado assumir o RDD corrente.

- 308 Guia de Referncia Rpida ADVPL Intermedirio

MSRENAME() Funo que verifica a existncia do arquivo especificado. Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] ) Parmetros: cArquivo cIndice cDriver Retorno: Lgico Exemplo: Local cArquivo := 'SX2ZZZ.DBF' Local cIndice := 'SX2ZZZ'+ OrdBagExt() If !MsFile ( cArquivo, cIndice ) APMsgInfo( 'Arquivo no encontrado!' ) EndIf Indica se o arquivo especificado existe. Nome do arquivo e a extenso. Nome do arquivo de ndice e a extenso. RDD do arquivo, se no for informado assumir o RDD corrente.

RETFILENAME() Funo que retorna o nome de um arquivo contido em uma string, ignorando o caminho e a extenso. Sintaxe: RetFileName( cArquivo ) Parmetros: cArquivo Retorno: Caracter Exemplo: Local cArquivo := '\SIGAADV\ARQZZZ.DBF' cArquivo := RetFileName( cArquivo ) // retorno ARQZZZ Nome do arquivo contido na string cArquivo sem o caminho e a extenso. String contendo o nome do arquivo

- 309 Guia de Referncia Rpida ADVPL Intermedirio

Manipulao de arquivos e ndices temporrios


CRIATRAB() Funo que cria um arquivo de trabalho com uma estrutura especificada, sendo que: Caso o parmetro lDbf seja definido como .T., a funo criar um arquivo DBF com este nome e a estrutura definida em aArray. Caso o parmetro lDbf seja definido como .F., a funo no criar arquivo de nenhum tipo, apenas fornecer um nome vlido. Sintaxe: CriaTrab(aArray,lDbf) Parmetros: aArray lDbf Retorno: Caracter 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 Nome do Arquivo gerado pela funo. 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. )

Na criao de ndices de trabalho temporrios utilizada a sintaxe: CriaTrab(Nil, .F.)

- 310 Guia de Referncia Rpida ADVPL Intermedirio

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 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 (""). <nAreaTrabalho> o nmero da rea de trabalho a ser verificada.

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

- 311 Guia de Referncia Rpida ADVPL Intermedirio

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

- 312 Guia de Referncia Rpida ADVPL Intermedirio

A tabela de destino dos dados copiados criada, e aberta em modo exclusivo, antes da operao de cpia efetiva ser iniciada. Tabela A : Especificao do formato SDF ( System Data Format ) Elemento do Arquivo Campos 'C' Caractere Campos 'D' Data Campos 'L' lgicos Campos 'M' Memo Campos 'N' Numricos Delimitador de Campos Separador de Registros Marca de final de arquivo (EOF) Formato Tamanho fixo, ajustado com espaos em branco Formato aaaammdd ( ano, ms, dia ) T ou F (campo ignorado) Ajustados direita, com espaos em branco. Nenhum CRLF ( ASCII 13 + ASCII 10 ) Nenhum

Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED WITH <cDelimiter> ) Elemento do Arquivo Campos 'C' Caractere Campos 'D' Data Campos 'L' lgicos Campos 'M' Memo Campos 'N' Numricos Delimitador de Campos Separador de Registros Marca de final de arquivo (EOF) Formato Delimitados, ignorando espaos direita Formato aaaammdd ( ano, ms, dia ) T ou F (campo ignorado) sem espaos em branco. Vrgula CRLF ( ASCII 13 + ASCII 10 ) 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> ]

- 313 Guia de Referncia Rpida ADVPL Intermedirio

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

cEscopo

WHILE <lCondicao>

FOR <lCondicao> [SDF|DELIMITED]

VIA <cDriver>

Retorno: Nenhum .

- 314 Guia de Referncia Rpida ADVPL Intermedirio

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> 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. . Deve ser especificado em xcDatabase o nome da tabela a ser criada.

Retorno: Nenhum .

- 315 Guia de Referncia Rpida ADVPL Intermedirio

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

- 316 Guia de Referncia Rpida ADVPL Intermedirio

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

- 317 Guia de Referncia Rpida ADVPL Intermedirio

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 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 . . libera todos os registros de trabalho) como se

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

- 318 Guia de Referncia Rpida ADVPL Intermedirio

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

- 319 Guia de Referncia Rpida ADVPL Intermedirio

DBCREATE() A funo DBCREATE() utilizada para criar um novo arquivo de tabela cujo nome est especificado atravs do primeiro parmetro (cNome) e estrutura atravs do segundo (aEstrutura). A estrutura especificada atravs de um array com todos os campos, onde cada campo expresso atravs de um array contendo {Nome, Tipo, Tamanho, Decimais}. Sintaxe: DBCREATE ( < cNOME > , < aESTRUTURA > , [ cDRIVER ] ) Parmetros: cNOME aESTRUTURA cDRIVER Nome do arquivo a ser criado. Se contm pasta, ela se localiza abaixo do "RootPath". Se no, criado por padro no caminho formado por "RootPath"+"StartPath" Lista com as informaes dos campos para ser criada a tabela. Nome da RDD a ser utilizado para a criao da tabela. Se for omitido ser criada com a corrente.

Retorno: Nenhum Exemplo: // Este exemplo mostra como se pode criar novo arquivo atravs da funo DBCREATE: LOCAL aEstrutura :={{Cod,N,3,0}, {Nome,C,10,0}, {Idade,N,3,0}, {Nasc,D,8,0}, {Pagto,N,7,2}} // Cria a tabela com o RDD corrente DBCREATE('\teste\cliente.dbf', aEstrutura) USE '\teste\cliente.dbf' VIA 'DBFCDX' NEW .

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

(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: DBCREATEINDEX(<cNOME>, <cEXPCHAVE>, [bEXPCHAVE], [lUNICO]) Parmetros: cNOME cEXPCHAVE bEXPCHAVE lUNICO Retorno: Nenhum . Nome do arquivo de ndice a ser criado. Expresso das chaves do ndice a ser criado na forma de string. Expresso das chaves do ndice a ser criado na forma executvel. Cria ndice como nico (o padro .F.).

- 321 Guia de Referncia Rpida ADVPL Intermedirio

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

- 322 Guia de Referncia Rpida ADVPL Intermedirio

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 DBS_NAME DBS_DEC DBS_LEN DBS_TYPE Descrio Nome do campo. Nmero de casas decimais. Tamanho. Tipo. Retorno Caracter Numrico Numrico 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.

- 323 Guia de Referncia Rpida ADVPL Intermedirio

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

- 324 Guia de Referncia Rpida ADVPL Intermedirio

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

- 325 Guia de Referncia Rpida ADVPL Intermedirio

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 DBI_GETRECSIZE DBI_TABLEEXT DBI_FULLPATH DBI_BOF DBI_EOF DBI_FOUND DBI_FCOUNT DBI_ALIAS Descrio Tamanho do registro em nmero de bytes similar a RECSIZE. Extenso do arquivo da tabela corrente. Nome da tabela corrente com caminho completo. Se est posicionada no incio da tabela similar a BOF Se est posicionada no final da tabela similar a EOF Se a tabela est posicionada aps uma pesquisa similar a FOUND Nmero de campos na estrutura tabela corrente similar a FCOUNT Nome do Alias da rea corrente similar a ALIAS de da Retorno Numrico Caracter Caracter Lgico Lgico Lgico Numrico Caracter

trabalho

- 326 Guia de Referncia Rpida ADVPL Intermedirio

DBI_LASTUPDATE

Data da ltima modificao similar a LUPDATE

Data

Sintaxe: DBINFO(<nINFOTIPO>) Parmetros: nINFOTIPO Retorno: Indefinido Informao da Tabela Informao requisitada pelo usurio (o tipo depende da informao requisitada). Se no houver tabela corrente retorna NIL. Tipo de informao a ser verificada.

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 Retorno: Caracter Expresso do ndice identificado pelo "NickName". Indica o "NickName" da ordem de ndice.

- 327 Guia de Referncia Rpida ADVPL Intermedirio

- 328 Guia de Referncia Rpida ADVPL Intermedirio

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 DBOI_BAGNAME DBOI_FULLPATH DBOI_ORDERCOUNT Descrio Nome do arquivo de ndice ao qual a ordem pertence. do arquivo de ndice (com seu diretrio) ao qual a ordem pertence. Nmero de ordens existentes no arquivo de ndice especificado. Retorno Caracter Caracter Caracter

Sintaxe: DBORDERINFO(<nINFOTIPO>) Parmetros: nINFOTIPO 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. Nome do arquivo de ndice.

Exemplo: DBORDERINFO(DBOI_BAGNAME) // retorna: Ind DBORDERINFO(DBOI_FULLPATH) // retorna: C:\AP6\Teste\Ind.cdx

- 329 Guia de Referncia Rpida ADVPL Intermedirio

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 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. Nome do apelido da ordem a ser setada.

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() DBRECALL()
- 330 Guia de Referncia Rpida ADVPL Intermedirio

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 DBRI_DELETED DBRI_RECSIZE DBRI_UPDATED Descrio Estado de deletado similar a DELETED Tamanho do registro similar a RECSIZE Verifica se o registro foi alterado e ainda no foi atualizado fisicamente similar a UPDATED Retorno Lgico Numrico Lgico

- 331 Guia de Referncia Rpida ADVPL Intermedirio

Sintaxe: DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO Parmetros: nINFOTIPO nREGISTRO Retorno: Indefinido No h tabela corrente ou registro invlido. Informao do Registro. Informao requisitada pelo usurio (o tipo depende da informao requisitada). Tipo de informao a ser verificada. Nmero do registro a ser verificado.

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

- 332 Guia de Referncia Rpida ADVPL Intermedirio

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 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. Nmero do registro a ser bloqueado.

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

- 333 Guia de Referncia Rpida ADVPL Intermedirio

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: 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 . Nmero do registro a ser desbloqueado.

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 Retorno: Caracter Nome do RDD padro corrente. Novo nome do RDD a ser definido como padro.

- 334 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Nenhum . Nome do arquivo de ndice, com ou sem diretrio.

Exemplo: USE Cliente NEW DBSETINDEX("Ind1") DBSETINDEX("\teste\Ind2.cdx")

- 335 Guia de Referncia Rpida ADVPL Intermedirio

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 cAPELIDO 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. Nome da ordem que deve receber o apelido. Nome do apelido da ordem a ser setada.

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

- 336 Guia de Referncia Rpida ADVPL Intermedirio

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 Exemplo: DbSelectArea(SA1) DbSetOrder(1) // De acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA Nmero de referncia da ordem que deseja ser definida como ordem ativa para a rea de trabalho.

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 Exemplo: DbSelectArea(SA1) DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO NickName: Tipo NickName atribudo ao ndice criado pelo usurio

- 337 Guia de Referncia Rpida ADVPL Intermedirio

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 Endif MsgAlert(Cliente no encontrado, Consulta por cliente)

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 Filial: Cdigo: Loja: Nome: cliente localizado: +CRLF +; + A1_FILIAL + CRLF +; + A1_COD + CRLF +; + A1_LOJA + CRLF +; + A1_NOME + CRLF, Consulta por cliente)

- 338 Guia de Referncia Rpida ADVPL Intermedirio

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

- 339 Guia de Referncia Rpida ADVPL Intermedirio

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 cCondicao Bloco de expressa a condio de filtro em forma executvel 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.

- 340 Guia de Referncia Rpida ADVPL Intermedirio

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

- 341 Guia de Referncia Rpida ADVPL Intermedirio

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 Parmetro opcional que permite que se caso o cAlias especificado j esteja em uso, ele seja fechado antes da abertura do arquivo da base de dados. Driver que permita a aplicao manipular o arquivo de base de dados especificado. A aplicao ERP possui a varivel __LOCALDRIVER definida a partir das configuraes do .ini do server da aplicao. Algumas chaves vlidas: DBFCDX, CTREECDX, DBFCDXAX, TOPCONN. Nome do arquivo de base de dados que ser aberto com o alias especificado. Alias para referncia do arquivos de base de dados pela aplicao. Se o arquivo poder ser utilizado por outras conexes. Se o arquivo poder ser alterado pela conexo ativa.

cDriver

cArquivo cAlias lComparilhado lSoLeitura Exemplo:

DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.) DbSelectArea(SA1DBF) MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.) DbCloseArea()

- 342 Guia de Referncia Rpida ADVPL Intermedirio

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 Exemplo: DbSelectArea(SA1) nFields := FCOUNT() IF nFields > 0 MSGINFO(A estrutura da tabela contm :+CvalToChar(nFields)+campos.) ENDIF Quantidade de campos existentes na estrutura da rea de trabalho ativa. .

- 343 Guia de Referncia Rpida ADVPL Intermedirio

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

- 344 Guia de Referncia Rpida ADVPL Intermedirio

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

- 345 Guia de Referncia Rpida ADVPL Intermedirio

MSAPPEND() A funo MsAppend() adiciona registros de um arquivo para outro, respeitando a estrutura das tabelas. Sintaxe: MSAPPEND( [cArqDest], cArqOrig ) Parmetros: cArqDest cArqOrig Retorno: Lgico Se a operao for realizada com sucesso o funo retornar verdadeiro (.T.). 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.

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 .

- 346 Guia de Referncia Rpida ADVPL Intermedirio

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.

- 347 Guia de Referncia Rpida ADVPL Intermedirio

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 lInclui Alias que identifica a rea de trabalho que ser manipulada. 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()

- 348 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Numrico rea de trabalho do alias especificado na forma de um valor numrico inteiro.
- 349 Guia de Referncia Rpida ADVPL Intermedirio

Nome da rea de trabalho a ser verificada.

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: cCondicao Expresso que ser avaliada pela SET FILTER, definindo os registros que ficaro disponveis na rea de trabalho ativa. Esta expresso obrigatoriamente deve ter um retorno lgico.

Retorno: Nenhum .

O uso da sintaxe SET FILTER TO desativa o filtro na rea de trabalho corrente.

Exemplo: USE Employee INDEX Name NEW SET FILTER TO Age > 50 LIST LastName, FirstName, Age, Phone SET FILTER TO

- 350 Guia de Referncia Rpida ADVPL Intermedirio

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 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 Alias de referncia da rea de trabalho ativa, para o qual o registro posicionado ser travado.

- 351 Guia de Referncia Rpida ADVPL Intermedirio

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

- 352 Guia de Referncia Rpida ADVPL Intermedirio

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 cCampo cAliasSXE nOrdem CONFIRMSXE() Confirma o nmero alocado atravs do ltimo comando GETSXENUM(). Sintaxe: CONFIRMSXE(lVerifica) Parmetros Verifica se o nmero confirmado no foi alterado, e por conseqncia j existe na base de dados. Alias de referncia da tabela para a qual ser efetuado o controle da numerao seqencial. Nome do campo no qual est implementado o controle da numerao. Parmetro opcional, quando o nome do alias nos arquivos de controle de numerao no o nome convencional do alias para o sistema ERP. Nmero do ndice para verificar qual a prxima ocorrncia do nmero.

lVerifica

ROLLBACKSXE() Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao disponvel para outras conexes. Sintaxe: ROLLBACKSXE() Parmetros Nenhum .

- 353 Guia de Referncia Rpida ADVPL Intermedirio

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 cConteudo nIndice Alias de referncia para a validao da informao. Chave a ser pesquisada, sem a filial. ndice de busca para consulta da chave.
- 354 Guia de Referncia Rpida ADVPL Intermedirio

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

Alias de referncia para a validao da informao. Chave a ser pesquisada, sem a filial. 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 Retorno: Lgico NAOVAZIO() Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio. Sintaxe: NaoVazio() Parmetros Nenhum . Indica que se a string avaliada contm apenas letras e nmero, ou seja, alfanumrico. String que ter seu contedo avaliado.

NEGATIVO() Retorna .T. ou .F. se o contedo digitado para o campo negativo. Sintaxe: Negativo() Parmetros Nenhum .
- 355 Guia de Referncia Rpida ADVPL Intermedirio

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 String contendo as informaes vlidas que podem ser digitadas para um campo.

cString

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

- 356 Guia de Referncia Rpida ADVPL Intermedirio

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 Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema.

cParametro

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 Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema. Contedo padro que ser utilizado caso o parmetro no exista no SX6. Define para qual filial ser efetuada a consulta do parmetro. Padro filial corrente da conexo.

cParametro cPadrao cFilial

- 357 Guia de Referncia Rpida ADVPL Intermedirio

PUTMV() Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as parametrizaes informadas. Sintaxe: PUTMV(cParametro, cConteudo) Parmetros cParametro cConteudo 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 Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema. Se ser exibida a mensagem de Help caso o parmetro no seja encontrado no SX6. Contedo padro que ser utilizado caso o parmetro no exista no SX6. Define para qual filial ser efetuada a consulta do parmetro. Padro filial corrente da conexo. Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema. Contedo que ser atribudo ao parmetro no SX6.

cParametro

lHelp cPadrao cFilial

- 358 Guia de Referncia Rpida ADVPL Intermedirio

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)

- 359 Guia de Referncia Rpida ADVPL Intermedirio

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 cCabec1 cCabec2 cNomeProg nTamanho nCompress aCustomText lPerg Ttulo do relatrio String contendo as informaes da primeira linha do cabealho String contendo as informaes da segunda linha do cabealho Nome do programa de impresso do relatrio. Tamanho do relatrio em colunas (80, 132 ou 220) Indica se impresso ser comprimida (15) ou normal (18). Texto especfico para o cabealho, substituindo a estrutura padro do sistema. Permite a supresso da impresso das perguntas do relatrio, mesmo que o parmetro MV_IMPSX1 esteja definido como S

- 360 Guia de Referncia Rpida ADVPL Intermedirio

Parmetros (continuao): cLogo Redefine o bitmap que ser impresso no relatrio, no necessitando que ele esteja no formato padro da Microsiga: "LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"

Retorno: Nenhum Exemplo: #INCLUDE "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | MPTR001 | Autor | 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 Local cString Local cPerg Local lDic Local aOrd Local lCompres Local lFilter Local cNomeProg Local cTamanho Local nTipo Local nLimite

SetPrint() := "SA1" := "" := .T. // Habilita a visalizacao do dicionario := RetSixOrd(cString) := .T. // .F. - Normal / .T. - Comprimido := .T. // Habilita o filtro para o usuario := "MPTR002" := "M" := 18 := 132 := .T.

Default lCriaTrab

Private lEnd := .F. Private lAbortPrint := .F. Private aReturn := { "Zebrado", 1, "Administracao", 2, 2, 1, "", 1} //aReturn[4] 1- Retrato, 2- Paisagem //aReturn[5] 1- Em Disco, 2- Via Spool, 3- Direto na Porta, 4- Email Private nLastKey := 0 Private m_pag Private wnrel dbSelectArea("SA1") dbSetOrder(1)
- 361 Guia de Referncia Rpida ADVPL Intermedirio

:= 01 := "MPTR002"

Exemplo (continuao): // // Monta a interface padrao com o usuario... // wnrel := SetPrint(cString,cNomeProg,cPerg,@cTitulo,cDesc1,cDesc2,cDesc3,lDic,aOrd,lComp res,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 := += += := := 80 := "" := ""

cCabec1 cCabec1 cCabec1 cCabec2

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

- 362 Guia de Referncia Rpida ADVPL Intermedirio

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 cCab2 cCab3 cNomeProg cTam nLimite Primeira linha do cabealho Segunda linha do cabealho Terceira linha do cabealho Nome do programa Tamanho do relatrio nos formatos P, M e G. 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 .

- 363 Guia de Referncia Rpida ADVPL Intermedirio

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 := += += := := 80 := "" := "" .

cCabec1 cCabec1 cCabec1 cCabec2

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

- 364 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: . Exemplo: If aReturn[5]==1 // Indica impresso em disco. dbCommitAll() SET PRINTER TO OurSpool(wnrel) Endif . Nome do relatrio a ser visualizado.

- 365 Guia de Referncia Rpida ADVPL Intermedirio

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 uPar02 cSize 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 . No mais utilizado No mais utilizado Tamanho do relatrio (P,M,G)

- 366 Guia de Referncia Rpida ADVPL Intermedirio

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
- 367 Guia de Referncia Rpida ADVPL Intermedirio

SETDEFAULT() A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes configuradas no array aReturn, obtidas atravs da funo SetPrint(). Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] , [cSize] , [ nFormat ] )

Parmetros: aReturn cAlias uParm3 uParm4 cSize nFormat Retorno: Nenhum . Configuraes de impresso. Alias do arquivo a ser impresso. Parmetro reservado. Parmetro reservado. Tamanho da pgina "P","M" ou "G" Formato da pgina, 1 retrato e 2 paisagem.

Estrutura aReturn: aReturn[1] aReturn[2] aReturn[3] aReturn[4] aReturn[5] aReturn[6] aReturn[7] aReturn[8] aReturn[x] Caracter, tipo do formulrio Numrico, opo de margem Caracter, destinatrio Numrico, formato da impresso Numrico, dispositivo de impresso Caracter, driver do dispositivo de impresso Caracter, filtro definido pelo usurio Numrico, ordem 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().

- 368 Guia de Referncia Rpida ADVPL Intermedirio

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 nColuna 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) . Linha na qual dever ser posicionado o dispositivo de impresso. Coluna na qual dever ser posicionado o dispositivo de impresso.

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 cProgram cPergunte cTitle Alias do arquivo a ser impresso. Nome do arquivo a ser gerado em disco. Grupo de perguntas cadastrado no dicionrio SX1. Ttulo do relatrio.

- 369 Guia de Referncia Rpida ADVPL Intermedirio

Parmetros (continuao): cDesc1 cDesc2 cDesc3 lDic aOrd lCompres cSize uParm12 lFilter lCrystal cNameDrv uParm16 lServer cPortPrint Retorno: Caracter Nome do Relatrio Descrio do relatrio. Continuao da descrio do relatrio. Continuao da descrio do relatrio. Utilizado na impresso de cadastro genrico permite a escolha dos campos a serem impressos. Se o parametro cAlias no for informado o valor padro assumido ser .F. Ordem(s) de impresso. Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro assumido ser .T. Tamanho do relatrio "P","M" ou "G". Parmetro reservado Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro assumido ser .T. Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro assumido ser .F. Nome de um driver de impresso. Parmetro reservado. Se verdadeiro (.T.) fora impresso no servidor. Define uma porta de impresso padro.

Estrutura aReturn: aReturn[1] aReturn[2] aReturn[3] aReturn[4] aReturn[5] aReturn[6] aReturn[7] aReturn[8] aReturn[x] Caracter, tipo do formulrio Numrico, opo de margem Caracter, destinatrio Numrico, formato da impresso Numrico, dispositivo de impresso Caracter, driver do dispositivo de impresso Caracter, filtro definido pelo usurio Numrico, ordem 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().

- 370 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Lgico CLOSEOPEN() A funo CLOSEOPEN() utilizada para fechar e re-abrir uma lista de arquivos especificada. Sintaxe: CLOSEOPEN(aClose, aOpen) Parmetros: aClose aOpen Retorno: Lgico 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 /. Indica se todos os arquivos especificados em aOpen foram abertos com sucesso. Array contendo os Aliases dos arquivos que devero ser fechados. Array contendo os Aliases dos arquivos que devero ser abertos. Indica se foi possvel abrir o arquivo em modo exclusivo. Alias do arquivo que ser re-aberto em modo exclusivo.

Retorno: Lgico Indica se todos os arquivos foram fechados com sucesso.

- 371 Guia de Referncia Rpida ADVPL Intermedirio

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 lExcl cNewAlias Retorno: Lgico 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 Indica se o arquivo foi re-aberto com sucesso. Alias do arquivo a ser re-aberto. 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.

- 372 Guia de Referncia Rpida ADVPL Intermedirio

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: cMensagem String contendo a mensagem que dever ser exibida no console do Protheus.

Retorno: Nenhum CRIAVAR() A funo CRIAVAR() cria uma varivel, retornando o valor do campo, de acordo com o dicionrio de dados, inclusive avaliando o inicializador padro, permitindo um retorno de acordo com o tipo de dado definido no dicionrio. Sintaxe: CriaVar(cCampo,lIniPad,cLado) Parmetros: cCampo lIniPad cLado Nome do campo Indica se considera (.T.) ou no (.F.) o inicializador 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

- 373 Guia de Referncia Rpida ADVPL Intermedirio

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

Sintaxe: DISARMTRANSACTION() Parmetros: Nenhum Retorno: Nenhum Exemplo: lMsErroAuto := .F. MSExecAuto({|x,y| MATA240(x,y)}, aCampos, 3) If lMsErroAuto aAutoErro := GETAUTOGRLOG() DisarmTransaction() MostraErro() EndIf . .

- 374 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Lgico Indica se a funo de usurio existe compilada no repositrio de objetos corrente. Nome da funo que ser avaliada.

Exemplo: IF EXISTBLOCK(MT100GRV) EXECBLOCK(MT100GRV,.F.,.F.,aParam) ENDIF

- 375 Guia de Referncia Rpida ADVPL Intermedirio

Sintaxe: EXECBLOCK(cFuno, lReserv1, lReserv2, xParam) Parmetros: cFuno lReserv1 lReserv2 xParam Nome da funo de usurio que ser executada. Parmetro de uso reservado da aplicao. Definir como .F. Parmetro de uso reservado da aplicao. Definir como .F. Contedo que ficar disponvel na funo de usurio executada, na forma da varivel private PARAMIXB.

Retorno: Indefinido 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] O retorno da EXECBLOCK() definido pela funo que ser executada.

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,
- 376 Guia de Referncia Rpida ADVPL Intermedirio

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

- 377 Guia de Referncia Rpida ADVPL Intermedirio

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 cMensagem2 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 Retorno: Lgico Indica se a funo existe compilada no repositrio de objetos corrente. Nome da funo que ser avaliada no repositrio de objetos corrente. . Primeira mensagem Segunda mensagem

- 378 Guia de Referncia Rpida ADVPL Intermedirio

FUNDESC() A funo FunDesc() retornar a descrio de uma opo selecionada no menu da aplicao. Sintaxe: FUNDESC() Parmetros: Nenhum Retorno: Caracter 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. . Descrio da opo selecionada no 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 .

- 379 Guia de Referncia Rpida ADVPL Intermedirio

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 cStackExit Nome da funo que desejasse pesquisar na pilha. 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.

- 380 Guia de Referncia Rpida ADVPL Intermedirio

REGTOMEMORY() Inicializa as variveis de memria identificadas pelo uso do alias M-> de acordo com a estrutura e/ou informaes contidas no arquivo definido como referncia. Sintaxe: REGTOMEMORY(cAlias, lInclui) Parmetros: cAlias lInclui Alias do arquivo que ser utilizado como referncia para inicializao das variveis de memria. Identifica se as variveis devero ser inicializadas com contedos padres, ou contendo as informaes do registro posicionado do alias especificado.

Retorno: Nenhum .

- 381 Guia de Referncia Rpida ADVPL Intermedirio

RESTAREA() Funo utilizada para devolver a situao do ambiente salva atravs do comando GETAREA(). Deve-se observar que a ltima rea restaurada a rea que ficar ativa para a aplicao. Sintaxe: RESTAREA(aArea) Parmetros aArea 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 ) Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo uso da funo GetArea().

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:
- 382 Guia de Referncia Rpida ADVPL Intermedirio

Nenhum

- 383 Guia de Referncia Rpida ADVPL Intermedirio

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 aPergs Retorno: Nenhum . Grupo de perguntas do SX1 (X1_GRUPO) Array contendo a estrutura dos campos que sero gravados no SX1.

Estrutura Item do array aPerg: Posio 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 Campo X1_PERGUNT X1_PERSPA X1_PERENG X1_VARIAVL X1_TIPO X1_TAMANHO X1_DECIMAL X1_PRESEL X1_GSC X1_VALID X1_VAR01 X1_DEF01 X1_DEFSPA1 X1_DEFENG1 X1_CNT01 X1_VAR02 X1_DEF02 X1_DEFSPA2 X1_DEFENG2 X1_CNT02 X1_VAR03 X1_DEF03 Tipo Caractere Caractere Caractere Caractere Caractere Numrico Numrico Numrico Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere 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
- 384 Guia de Referncia Rpida ADVPL Intermedirio

Estrutura Item do array aPerg (continuao): 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 X1_DEFSPA3 X1_DEFENG3 X1_CNT03 X1_VAR04 X1_DEF04 X1_DEFSPA4 X1_DEFENG4 X1_CNT04 X1_VAR05 X1_DEF05 X1_DEFSPA5 X1_DEFENG5 X1_CNT05 X1_F3 X1_GRPSXG X1_PYME X1_HELP X1_PICTURE aHelpPor aHelpEng aHelpSpa Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Caractere Array Array 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.

- 385 Guia de Referncia Rpida ADVPL Intermedirio

ALLUSERS() A funo ALLUSERS() retorna um array multidimensional contendo as informaes dos usurios do sistema. Sintaxe: ALLUSERS() Parmetros: Nenhum Retorno: Array Array multidimensional contendo as informaes dos usurios do sistema, aonde para cada usurio sero demonstradas as seguintes informaes: aArray[x][1] Configuraes gerais de acesso aArray[x][2] Configuraes de impresso aArray[x][3] Condiguraes de acesso aos mdulos .

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

- 386 Guia de Referncia Rpida ADVPL Intermedirio

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

Array de informaes dos usurios: Configuraes de acesso aos mdulos Elemento 3 1 Descrio Mdulo+nvel+menu Tipo C Qtd.

- 387 Guia de Referncia Rpida ADVPL Intermedirio

ALLGROUPS() A funo ALLGROUPS() retorna um array multidimensional contendo as informaes dos grupos de usurios do sistema. Sintaxe: ALLGROUPS() Parmetros: Nenhum Retorno: Array Array multidimensional contendo as informaes dos grupos de usurios do sistema, aonde para cada grupo sero demonstradas as seguintes informaes: aArray[x][1] Configuraes gerais de acesso aArray[x][2] Configuraes de acesso aos mdulos .

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

Array de informaes dos grupos: Configuraes de acesso aos mdulos Elemento 2 1 CGC()
- 388 Guia de Referncia Rpida ADVPL Intermedirio

Descrio Modulo+nvel+menu

Tipo C

Qtd.

A funo CGC() valida o CGC digitado, utilizando o algoritmo nacional para verificao do dgito de controle. Sintaxe: CGC(cCGC) Parmetros: cCGC Retorno: Lgico Indica se o CGC informado vlido. String contendo o CGC a ser validado

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 uPar2 uPar3 cAlias cCampoRet uPar4 lOnlyView Retorno: Nenhum . Parmetro reservado. Parmetro reservado. Parmetro reservado. Consulta padro cadastrada no Dicionrio de Dados (SXB) a ser utilizada. Nome da varivel ou campo que receber o retorno da consulta padro. Parmetro Reservado. Indica se ser somente para visualizao. ,

- 389 Guia de Referncia Rpida ADVPL Intermedirio

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 EXISTINI() A funo EXISTINI() verifica se o campo possui inicializador padro. Sintaxe: EXISTINI(cCampo) Parmetros: cCampo Retorno: Lgico 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 Indica se o campo possui um inicializador padro. Nome do campo para verificao. Prxima data vlida, desconsiderando sbados, domingos e os feriados cadastrados no sistema.

- 390 Guia de Referncia Rpida ADVPL Intermedirio

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 lQtd nMoeda Retorno: String 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. Descrio do valor por extenso. Valor para gerao do extenso. Indica se o valor representa uma quantidade (.T.) ou dinheiro (.F.) Para qual moeda do sistema deve ser o extenso.

Retorno: Indefinido 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 uCpo uChave nOrder uDef Alias do arquivo Nome de um campo ou array contendo os nomes dos campos desejados Chave para a pesquisa Ordem do ndice para a pesquisa Valor ou array default para ser retornado caso a chave no seja encontrada Resultado da interpretao da frmula cadastrada no SM4.

- 391 Guia de Referncia Rpida ADVPL Intermedirio

Retorno: Indefinido Retorna o contedo de um campo ou array com o contedo de vrios campos

A funo GETADVFVAL() difere da funo POSICIONE() apenas por permitir o retorno de vrios campos em uma nica consulta. As duas funes devem ser protegidas por GETAREA() / RESTAREA() dependendo da aplicao. HELP() Esta funo exibe a ajuda especificada para o campo e permite sua edio. Se for um help novo, escreve-se o texto em tempo de execuo. Sintaxe: Help(cHelp,nLinha, cTitulo, uPar4,cMensagem,nLinMen,nColMen) Parmetros: cHelp nLinha cTitulo uPar4 cMensagem nLinMen nColMen Retorno: Nenhum . Nome da Rotina chamadora do help. (sempre branco) Nmero da linha da rotina chamadora. (sempre 1) Ttulo do help Sempre NIL Mensagem a ser exibida para o Help. Nmero de linhas da Mensagem. (relativa janela) Nmero de colunas da Mensagem. (relativa janela)

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

- 392 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Lgico Indica se todos os campos obrigatrios foram preenchidos. 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().

- 393 Guia de Referncia Rpida ADVPL Intermedirio

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" 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. ,0,1} ,; ,0,2} ,; ,0,4}}

- 394 Guia de Referncia Rpida ADVPL Intermedirio

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
- 395 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: Nenhum . Empresa cujo os arquivos sero re-abertos.

- 396 Guia de Referncia Rpida ADVPL Intermedirio

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 |Ask cTitle Retorno: Lgico Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou cancelada (.F.) Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada. Indica se exibir a tela para edio. Ttulo do dilogo.

PESQPICT() A funo PESQPICT() retorna a picture definida para um campo especificado no Dicionrio de Dados (SX3). Sintaxe: PesqPict(cAlias,cCampo,nTam) Parmetros: cAlias cCampo nTam Alias do arquivo Nome do campo 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.

- 397 Guia de Referncia Rpida ADVPL Intermedirio

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 nEdio Retorno: String Picture ideal para o espao definido por nEdio, sem a separao dos milhares por vrgula. Nome do campo a verificar a picture. Espao disponvel para edio.

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 nOrdem cChave cCampo Retorno: Indefinido Contedo do campo solicitado. Alias do arquivo Ordem utilizada Chave pesquisa Campo a ser retornado

A utilizao da funo POSICIONE() deve ser protegida com GETAREA() / RESTAREA() dependendo da aplicao.

- 398 Guia de Referncia Rpida ADVPL Intermedirio

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 cOrdem cPergunt cPerSpa cPerEng cVar cTipo nTamanho nDecimal nPresel cGSC cValid cF3 cGrpSxg cPyme cVar01 cDef01 cDefSpa1 cDefEng1 cCnt01 cDef0x cDefSpax cDefEngx aHelpPor aHelpEng aHelpSpa cHelp Grupo de perguntas do SX1 (X1_GRUPO) Ordem do parmetro no grupo (X1_ORDEM) Descrio da pergunta em portugus Descrio da pergunta em espanhol Descrio da pergunta em ingls Nome da varivel de controle auxiliar (X1_VARIAVL) 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 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 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 este item Descrio da opo X do combo em portugus Descrio da opo X do combo em espanhol Descrio da opo X do combo em ingls Vetor simples contendo as linhas de help em portugus para o parmetro. Vetor simples contendo as linhas de help em ingls para o parmetro. Vetor simples contendo as linhas de help em espanhol para o parmetro. Contedo do campo X1_HELP

- 399 Guia de Referncia Rpida ADVPL Intermedirio

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

Sintaxe: RETINDEX(cAlias) Parmetros: cAlias Retorno: Numrico Indica quantos ndices padres o alias especificado possui no Dicionrio de Dados. Alias de um arquivo do sistema existente no Dicionrio de Dados.

A funo RETINDEX() quando utilizada em ambientes TOPCONNECT retorna -1

SIXDESCRICAO() A funo SIXDESCRICAO() retorna a descrio da chave de ndice, de acordo com o registro posicionado no SIX e idioma corrente. Sintaxe: SIXDESCRICAO() Parmetros: Nenhum Retorno: String Exemplo: User Function <nome-da-funo>( cChave, cOrdem ) Local cSixDesc := dbSelectArea(SIX) dbSetOrder(1) If dbSeek(cChave+cOrdem) cSixDescr := SixDescricao() EndIf Return Descrio do indice posicionado no SIX de acordo com o idioma corrente. .

- 400 Guia de Referncia Rpida ADVPL Intermedirio

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 cChav lPrint Idenficao da tabela a pesquisar (deve ser informado como caracter). Chave a pesquisar na tabela informada. Indica se deve (.T.) ou no (.F.) exibir o help ou a chave NOTAB se a tabela no existir.

Retorno: String 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 Retorno: Array Array de duas posies contendo o tamanho total e o nmero de decimais do campo especificado respectivamente. Nome do campo a ser consultado no Dicionrio de Dados (SX3). Contedo da tabela na chave especificada. Retorna nulo caso a tabela no exista ou a chave no seja encontrada.

- 401 Guia de Referncia Rpida ADVPL Intermedirio

TM() A funo TM() retorna a picture de impresso para valores numricos dependendo do espao disponvel. Sintaxe: TM(nValor, nEdio, nDec) Parmetros: nValor nEdio nDec Retorno: String Picture ideal para edio do valor nValor Esta rotina leva em considerao duas variveis: Valor a ser avaliado. Espao disponvel para edio. Nmero de casas decimais.

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.

- 402 Guia de Referncia Rpida ADVPL Intermedirio

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 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 Contedo da primeira definio da pergunta no idioma corrente. .

- 403 Guia de Referncia Rpida ADVPL Intermedirio

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 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 Descrio da pergunta do Dicionrio de Dados (SX1) no idioma corrente. .

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
- 404 Guia de Referncia Rpida ADVPL Intermedirio

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

- 405 Guia de Referncia Rpida ADVPL Intermedirio

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 Retorno: String Exemplo: User Function <nome-da-funo>( cCampo ) Local cPicture cPicture := X3Picture( cCampo ) Return cPicture Picture do campo informado. Nome do campo contido no Dicionrio de Dados (SX3).

- 406 Guia de Referncia Rpida ADVPL Intermedirio

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 Modulo Contedo do campo X3_USADO a ser avaliado. 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).

- 407 Guia de Referncia Rpida ADVPL Intermedirio

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 Exemplo: User Function <nome-da-funo>( cFilial, cTabela, cChave ) Local cDescr dbSelectArea(SX5) dbSetOrder(1) If dbSeek( cFilial+cTabela+cChave ) cDescr := X5Descri() EndIf Return Decrio do item do Arquivo de Tabelas (SX5) no idioma corrente. .

- 408 Guia de Referncia Rpida ADVPL Intermedirio

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

- 409 Guia de Referncia Rpida ADVPL Intermedirio

X6DESCRIC() A funo X6DESCRI() retorna o contedo da descrio de um parmetro de acordo com o registro posicionado no Dicionrio de Dados (SX6) no idioma corrente. Sintaxe: X6DESCRIC() Parmetros: Nenhum Retorno: String Descrio do parmetro posicionado no Dicionrio de Dados (SX6) no idioma corrente. .

Para avaliar os contedos dos primeiro e segundo complementos da descrio do parmetro utilize as funes:

X6DESC01() retorna o primeiro complemento da descrio. X6DESC02() retorna o segundo complemento da descrio.

As trs funes possuem a mesma sintaxe e forma de utilizao.

Exemplo: User Function <nome-da-funo>( cFilial, cParam ) Local cDescr Local cConteud dbSelectArea(SX6) dbSetOrder(1) If dbSeek( cFilial+cParm ) cDescr := X6Descric() cDescr += X6Desc1() cDescr += X6Desc2() cConteud := X6Conteud() EndIf Return

- 410 Guia de Referncia Rpida ADVPL Intermedirio

XADESCRIC() A funo XADESCRI() retorna o contedo da descrio dos folders de acordo com o registro posicionado no Dicionrio de Dados (SXA) no idioma corrente. Sintaxe: XADESCRIC() Parmetros: Nenhum Retorno: String Descrio do folder posicionado no Dicionrio de Dados (SXA) no idioma corrente. .

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

Exemplo: User Function <nome-da-funo>( cAlias ) Local cDescr dbSelectArea(SXB) dbSetOrder(1) If dbSeek( cAlias + 1 ) cDescr := XBDescri() EndIf Return
- 411 Guia de Referncia Rpida ADVPL Intermedirio

XFILIAL() A funo XFILIAL() retorna a filial utilizada por determinado arquivo. Esta funo utilizada para permitir que pesquisas e consultas em arquivos trabalhem somente com os dados da filial corrente, dependendo claro se o arquivo est compartilhado ou no (definio que feita atravs do mdulo Configurador Dicionrio de Dados (SX2)). importante verificar que esta funo no tem por objetivo retornar apenas a filial corrente, mas retorn-la caso o arquivo seja exclusivo. Se o arquivo estiver compartilhado, a funo xFilial retornar dois espaos em branco. Sintaxe: XFILIAL(cAlias) Parmetros: cAlias Alias do arquivo desejado. Se no for especificado, o arquivo tratado ser o da rea corrente.

Retorno: Caracter String contendo a filial do arquivo corrente.

- 412 Guia de Referncia Rpida ADVPL Intermedirio

Componentes da interface visual


MSDIALOG() Define o componente MSDIALOG(), o qual utilizado como base para os demais componentes da interface visual, pois um componente MSDIALOG() uma janela da aplicao. Sintaxe:

DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO nLiFim,nColFim OF oObjetoRef UNIDADE

Parmetros oObjetoDLG cTitulo nLinIni, nColIni nLiFim, nColFim oObjetoRef UNIDADE Exemplo: DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL ACTIVATE MSDIALOG oDlg CENTERED Posio do objeto Say em funo da janela em que ele ser definido. Ttulo da janela de dilogo. Posio inicial em linha / coluna da janela. Posio final em linha / coluna da janela. Objeto dialog no qual a janela ser definida. Unidade de medida das dimenses: PIXEL

- 413 Guia de Referncia Rpida ADVPL Intermedirio

MSGET() Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis na tela da interface. Sintaxe:

@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture

Parmetros nLinha, nColuna VARIAVEL nLargura,nAltura UNIDADE oObjetoRef cF3 VALID WHEN cPicture Exemplo: @ 010,050 MSGET cCGC VALID !Vazio() SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99"; Posio do objeto MsGet em funo da janela em que ele ser definido. Varivel da aplicao que ser vinculada ao objeto MsGet, que definir suas caractersticas e na qual ser armezanado o que for informado no campo. Dimenses do objeto MsGet para exibio do texto. Unidade de medida das dimenses: PIXEL Objeto dialog no qual o componente ser definido. String que define a consulta padro que ser vinculada ao campo. Funo de validao para o campo. Condio para manipulao do campo, a qual pode ser diretamente .T. ou .F., ou uma varivel ou uma chamada de funo. String contendo a definio da Picture de digitao do campo.

- 414 Guia de Referncia Rpida ADVPL Intermedirio

SAY() Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de interface. Sintaxe:

@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef

Parmetros nLinha, nColuna cTexto nLargura,nAltura UNIDADE oObjetoRef Exemplo: @ 010,010 SAY cTexto SIZE 55, 07 OF oDlg PIXEL Posio do objeto Say em funo da janela em que ele ser definido. Texto que ser exibido pelo objeto Say. Dimenses do objeto Say para exibio do texto. Unidade de medida das dimenses: PIXEL Objeto dialog no qual o componente ser definido.

BUTTON() Define o componente visual Button, o qual permite a incluso de botes de operao na tela da interface, os quais sero visualizados somente com um texto simples para sua identificao. Sintaxe: BUTTON()

@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef ACTION AO

Parmetros nLinha,nColuna cTexto nLargura,nAltura UNIDADE oObjetoRef AO Exemplo:


- 415 Guia de Referncia Rpida ADVPL Intermedirio

Posio do objeto Button em funo da janela em que ele ser definido. String contendo o texto que ser exibido no boto. Dimenses do objeto Button para exibio do texto. Unidade de medida das dimenses: PIXEL Objeto dialog no qual o componente ser definido. Funo ou lista de expresses que define o comportamento do boto quando ele for utilizado.

010, 120 BUTTON Confirmar SIZE 080, 047 PIXEL OF oDlg; ACTION (nOpca := 1,oDlg:End())

SBUTTON() Define o componente visual SButton, o qual permite a incluso de botes de operao na tela da interface, os quais sero visualizados dependendo da interface do sistema ERP utilizada somente com um texto simples para sua identificao, ou com uma imagem (BitMap) prdefinido. Sintaxe: SBUTTON()

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

Parmetros nLinha, nColuna TYPE N AO STATUS oObjetoRet Posio do objeto sButton em funo da janela em que ele ser definido. Nmero que indica o tipo do boto (imagem) pr-definida que ser utilizada. Funo ou lista de expresses que define o comportamento do boto quando ele for utilizado. Propriedade de uso do boto: ENABLE ou DISABLE Objeto dialog no qual o componente ser definido.

Exemplo: DEFINE SBUTTON FROM 020, 120 TYPE 2 ACTION (nOpca := 2,oDlg:End()); ENABLE OF oDlg

Visual dos diferentes tipos de botes disponveis

CHECKBOX()
- 416 Guia de Referncia Rpida ADVPL Intermedirio

Define o componente visual CheckBox, o qual permite a utilizao da uma marca para habilitar ou no uma opo escolhida, sendo esta marca acompanhada de um texto explicativo. Difere do RadioMenu pois cada elemento do check nico, mas o Radio permite a utilizao de uma lista junto com um controle de seleo. Sintaxe:

@ nLinha,nColuna CHECKBOX oCheckBox VAR VARIAVEL PROMPT cTexto WHEN WHEN UNIDADE OF oObjetoRef SIZE nLargura,nAltura MESSAGE cMensagem

Parmetros: nLinha,nColuna oCheckBox VARIAVEL cTexto WHEN UNIDADE oObjetoRef nLargura,nAltura cMensagem Posio do objeto ComboBox em funo da janela em que ele ser definido. Objeto do tipo CheckBox que ser criado. Varivel do tipo lgico com o status do objeto (.T. marcado, .F. desmarcado). Texto que ser exibido ao lado do get de marcao. Condio para manipulao do objeto, a qual pode ser diretamente .T. ou .F., ou uma varivel ou uma chamada de funo. Unidade de medida das dimenses: PIXEL Objeto dialog no qual o componente ser definido. Dimenses do objeto CheckBox. Texto que ser exibido ao clicar no componente.

Exemplo: @ 110,10 CHECKBOX oChk VAR lChk PROMPT "Marca/Desmarca" SIZE 60,007 PIXEL OF oDlg ; ON CLICK(aEval(aVetor,{|x| x[1]:=lChk}),oLbx:Refresh())

- 417 Guia de Referncia Rpida ADVPL Intermedirio

COMBOBOX() Define o componente visual ComboBox, o qual permite seleo de um item dentro de uma lista de opes de textos simples no formato de um vetor. Sintaxe:

@ nLinha,nColuna COMBOBOX VARIAVEL ITEMS AITENS SIZE nLargura,nAltura UNIDADE OF oObjetoRef

Parmetros: nLinha,nColuna VARIAVEL AITENS nLargura,nAltura UNIDADE oObjetoRef Posio do objeto ComboBox em funo da janela em que ele ser definido. Varivel do tipo caracter que ir receber a descrio do item selecionado no ComboBox. Vetor simples contendo as strings que sero exibidas como opes do ComboBox. Dimenses do objeto ComboBox. Unidade de medida das dimenses: PIXEL Objeto dialog no qual o componente ser definido.

Exemplo: @ 40, 10 COMBOBOX oCombo VAR cCombo ITEMS aCombo SIZE 180,10 PIXEL OF oFld:aDialogs[2]

- 418 Guia de Referncia Rpida ADVPL Intermedirio

FOLDER() Define o componente visual Folder, o qual permite a incluso de diversos Dialogs dentro de uma mesma interface visual. Um Folder pode ser entendido como um array de Dialogs, aonde cada painel recebe seus componentes e tem seus atributos definidos independentemente dos demais. Sintaxe:

@ nLinha,nColuna FOLDER oFolder OF oObjetoRef PROMPT &cTexto1,,&cTextoX UNIDADE SIZE nLargura,nAltura

Parmetros nLinha,nColuna oFolder oObjetoRef &cTexto1,,&cTextoX UNIDADE nLargura,nAltura Posio do objeto Folder em funo da janela em que ele ser definido. Objeto Folder que ser criado. Objeto dialog no qual o componente ser definido. Strings de ttulos de cada uma das abas do Folder, sempre precedidas por &. Exemplo: &Pasta1,&PastaX. Unidade de medida das dimenses: PIXEL Dimenses do objeto Folder.

Exemplo: @ 50,06 FOLDER oFld OF oDlg PROMPT "&Buscas", "&Consultas", "Check-&Up / Botes" PIXEL SIZE 222,078

- 419 Guia de Referncia Rpida ADVPL Intermedirio

RADIO() Define o componente visual Radio, tambm conhecido como RadioMenu, o qual seleo de uma opo ou de mltiplas opes atravs de uma marca para os itens exibidos de uma lista. Difere do componente CheckBox, pois cada elemento de check sempre nico, e o Radio pode conter um ou mais elementos. Sintaxe:

@ nLinha,nColuna RADIO oRadio VAR nRadio 3D SIZE nLargura,nAltura <ITEMS PROMPT> cItem1,cItem2,...,cItemX OF oObjetoRef UNIDADE ON CHANGE CHANGE ON CLICK CLICK

Parmetros nLinha,nColuna oRadio nRadio 3D nLargura,nAltura <ITEMS PROMPT> cItem1,cItem2,...,cItemX oObjetoRef UNIDADE CHANGE CLICK Exemplo: aAdd( aRadio, "Disco" ) aAdd( aRadio, "Impressora" ) aAdd( aRadio, "Scanner" ) @ 30, 10 RADIO oRadio VAR nRadio ITEMS aRadio[1],aRadio[2],aRadio[3] SIZE 65,8 ; PIXEL OF ; oFld:aDialogs[3] ; ON CHANGE ; (Iif(nRadio==1,MsgInfo("Opco 1",cAtencao),; Iif(nRadio==2,MsgInfo("Opo 2",cAtencao),MsgInfo("Opo 3",cAtencao)))) Posio do objeto Radio em funo da janela em que ele ser definido. Objeto do tipo Radio que ser criado. Item do objeto Radio que est selecionado. Item opcional que define se o RadioButton ter aspecto simples ou 3D. Dimenses do objeto Radio. Utilizar um dos dois identificadores para definir quais os textos que sero vinculados a cada RadioButton. Texto que ser vinculado a cada RadioButton. Objeto dialog no qual o componente ser definido. Unidade de medida das dimenses: PIXEL Funo ou lista de expresses que ser executada na mudana de um item de um RadioButton para outro. Funo ou lista de expresses que ser executada na seleo de um item RadioButton.

- 420 Guia de Referncia Rpida ADVPL Intermedirio

Interfaces de cadastro
AXCADASTRO() Sintaxe Descrio AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt) O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes de customizao.

MBROWSE() Sintaxe Descrio MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias) A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de recursos mais aprimorados na visualizao e manipulao das informaes do sistema.

AXPESQUI() Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado na pesquisa e a digitao das informaes que compe a chave de busca. Sintaxe: AXPESQUI() Parmetros Nenhum .

- 421 Guia de Referncia Rpida ADVPL Intermedirio

AXVISUAL() Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,; aButtons, lMaximized ) Parmetros cAlias nReg nOpc aAcho nColMens cMensagem cFunc Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada Record number (recno) do registro posicionado no alias ativo. Nmero da linha do aRotina que definir o tipo de edio (Incluso, Alterao, Excluso, Visualizao). Vetor com nome dos campos que sero exibidos. Os campos de usurio sempre sero exibidos se no existir no parmetro um elemento com a expresso "NOUSER". Parmetro no utilizado. Parmetro no utilizado. Funo que dever ser utilizada para carregar as variveis que sero utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido internamente pela AxFunction() executada como .T. Botes adicionais para a EnchoiceBar, no formato: aArray[n][1] -> Imagem do boto aArray[n][2] -> bloco de cdigo contendo a ao do boto aArray[n][3] -> ttulo do boto Indica se a janela dever ser ou no maximizada

aButtons lMaximized AXINCLUI()

Funo de incluso padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized) Parmetros cAlias nReg nOpc aAcho cFunc aCpos Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada Record number (recno) do registro posicionado no alias ativo. Nmero da linha do aRotina que definir o tipo de edio (Incluso, Alterao, Excluso, Visualizao). Vetor com nome dos campos que sero exibidos. Os campos de usurio sempre sero exibidos se no existir no parmetro um elemento com a expresso "NOUSER". Funo que dever ser utilizada para carregar as variveis que sero utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido internamente pela AxFunction() executada como .T. Vetor com nome dos campos que podero ser editados
- 422 Guia de Referncia Rpida ADVPL Intermedirio

cTudoOk

Funo de validao de confirmao da tela. No deve ser passada como Bloco de Cdigo, mas pode ser passada como uma lista de expresses, desde que a ltima ao efetue um retorno lgico: (Func1(), Func2(), ...,FuncX(), .T. )

lF3 cTransact aButtons

Indica se a enchoice esta sendo criada em uma consulta F3 para utilizar variveis de memria Funo que ser executada dentro da transao da AxFunction() Botes adicionais para a EnchoiceBar, no formato: aArray[n][1] -> Imagem do boto aArray[n][2] -> bloco de cdigo contendo a ao do boto aArray[n][3] -> ttulo do boto Funes para execuo em pontos pr-definidos da AxFunction(), conforme abaixo: aParam[1] := Bloco de cdigo que ser processado antes da exibio da interface. aParam[2] := Bloco de cdigo para processamento na validao da confirmao. aParam[3] := Bloco de cdigo que ser executado dentro da transao da AxFunction(). aParam[4] := Bloco de cdigo que ser executado fora da transao da AxFunction(). Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja informado este array, no ser exibida a tela de interface, e ser executada a funo EnchAuto(). aAuto[n][1] := Nome do campo aAuto[n][2] := Contedo do campo aAuto[n][3] := Validao que ser utilizada em substituio as validaes do SX3 Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de memria ou os campos da tabela na edio Indica se a janela dever ser ou no maximizada

aParam

aAuto

lVirtual lMaximized AXALTERA()

Funo de alterao padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens, cMensagem,; cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual, lMaximized) Parmetros Vide documentao de parmetros da funo AxInclui().

- 423 Guia de Referncia Rpida ADVPL Intermedirio

AXDELETA() Funo de excluso padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). Sintaxe: AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,; aAuto, lMaximized) Parmetros cAlias nReg nOpc cTransact aCpos aButtons Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada Record number (recno) do registro posicionado no alias ativo. Nmero da linha do aRotina que definir o tipo de edio (Incluso, Alterao, Excluso, Visualizao). Funo que ser executada dentro da transao da AxFunction() Vetor com nome dos campos que podero ser editados Botes adicionais para a EnchoiceBar, no formato: aArray[n][1] -> Imagem do boto aArray[n][2] -> bloco de cdigo contendo a ao do boto aArray[n][3] -> ttulo do boto Funes para execuo em pontos pr-definidos da AxFunction(), conforme abaixo: aParam[1] := Bloco de cdigo que ser processado antes da exibio da interface. aParam[2] := Bloco de cdigo para processamento na validao da confirmao. aParam[3] := Bloco de cdigo que ser executado dentro da transao da AxFunction(). aParam[4] := Bloco de cdigo que ser executado fora da transao da AxFunction(). Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja informado este array, no ser exibida a tela de interface, e ser executada a funo EnchAuto(). aAuto[n][1] := Nome do campo aAuto[n][2] := Contedo do campo aAuto[n][3] := Validao que ser utilizada em substituio as validaes do SX3 Indica se a janela dever ser ou no maximizada

aParam

aAuto

lMaximized

- 424 Guia de Referncia Rpida ADVPL Intermedirio

Interfaces visuais para aplicaes


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

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

- 425 Guia de Referncia Rpida ADVPL Intermedirio

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

- 426 Guia de Referncia Rpida ADVPL Intermedirio

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

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

MSGALERT

MSGINFO

MSGSTOP

MSGYESNO

- 427 Guia de Referncia Rpida ADVPL Intermedirio

Recursos das interfaces visuais


GDFIELDGET() A funo GDFIELDGET() retorna o contedo de um campo especificado em uma grid formada por um objeto do tipo MsNewGetDados() de acordo com a linha da grid desejada. Sintaxe: GDFIELDGET(cCampo, nLinha) Parmetros: cCampo nLinha Retorno: Indefinido GDFIELDPOS() A funo GDFIELDPOS() retorna a posio de um campo especificado em uma gria formada por um objeto do tipo MsNewGetDados(). Sintaxe: GDFIELDPOS(cCampo) Parmetros: cCampo Retorno: Numrico GDFIELDPUT() A funo GDFIELDPUT() atualiza o contedo de uma grid formada por um objeto do tipo MsNewGetDados() de acordo com o campo e linha da grid especificados. Sintaxe: GDFIELDPUT(cCampo, xConteudo, nLinha) Parmetros: cCampo xConteudo nLinha Retorno: Nenhum . Nome do campo a ser atualizado. Contedo que ser atribudo a clula da grid. Linha da grid que ser atualizada. Posio que o campo ocupada na grid. Caso o mesmo no exista ser retornado 0. Nome do campo a ser avaliado na grid. Contedo do campo especificado de acordo com a linha da grid informada. Nome do campo para retorno do contedo. Linha da grid que dever ser avaliada.

- 428 Guia de Referncia Rpida ADVPL Intermedirio

GETMARK() A funo GETMARK() utilizada em conjunto com a funo MarkBrow(), para retornar o conjunto de caracteres que sero utilizados para identificar os registros marcados pelo browse. Sintaxe: GETMARK( [lUpper] ) Parmetros: lUpper Retorno: String Conjunto de caracteres que definem a marca que dever ser utilizada pela MarkBrowse durante o processamento corrente. Se verdadeiro (.T.) retorna somente caracteres em maisculos.

O retorno da funo GETMARK() depende do contedo atual do parmetro MV_MARCA.

altamente recomendvel limpar o contedo do campo marcado pela MarkBrowse() ao trmino do processamento, para se evitar problemas com a reutilizao da marca aps a exausto das possibilidades de combinao de dois caracteres, o qual o tamanho padro do campos utilizados para marcao de registros pela MarkBrowse(), que neste caso somam 1891 possibilidades de 00 a zz.

Exemplo: Function <nome-da-funo>( ) Local aCampos := {{'CB_OK' ,,''},; {'CB_USERLIB' ,,'Usurio'},; {'CB_TABHORA' ,,'Hora'},; {'CB_DTTAB' ,,'Data'}} Private cMarca := GetMark() Private cCadastro := 'Cadastro de Contrato' Private aRotina := { { 'Pesquisar' , 'AxPesqui' , 0, 1 }} MarkBrow( 'SCB', 'CB_OK','!CB_USERLIB',aCampos,, cMarca,'MarkAll()',,,,'Mark()' ) Return

- 429 Guia de Referncia Rpida ADVPL Intermedirio

MARKBREFRESH() A funo MARKBREFRESH() atualiza a exibio da marca no MarkBrowse(), sendo utilizada quando algum processamento paralelo atualiza o contedo do campo definido como controle de marca para os registros em exibio pelo browse. Este tipo de processamento comum, e normalmente est associonada a clique de inverter seleo, ou a opes de marcar e desmarcar todas.

A MarkBrowse() atualiza automaticamente a exibio da marca de registros quando utilizado o browse.

Sintaxe: MARKBREFRESH() Parmetros: Nenhum Retorno: Nenhum READVAR() A funo READVAR() retorna o nome da varivel ou campo associoado ao objeto do tipo GET() atualmente selecionado ou em edio. Sintaxe: READVAR() Parmetros: Nenhum Retorno: String Nome da varivel ou campo associado ao objeto do tipo GET. . . .

- 430 Guia de Referncia Rpida ADVPL Intermedirio