Escolar Documentos
Profissional Documentos
Cultura Documentos
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
NDICE
Converso entre tipos de dados .................................................................................................................. 8
CTOD() ............................................................................................................................................................ 8 CVALTOCHAR() ............................................................................................................................................ 8 DTOC() ............................................................................................................................................................ 8 DTOS() ............................................................................................................................................................ 9 STOD() ............................................................................................................................................................ 9 STR() ............................................................................................................................................................. 10 STRZERO() ................................................................................................................................................... 10 VAL() ............................................................................................................................................................. 11
Matemticas ............................................................................................................................................... 11
ACOS() .......................................................................................................................................................... 11 CEILING() ..................................................................................................................................................... 12 COS() ............................................................................................................................................................. 12 LOG10()......................................................................................................................................................... 13 SIN() .............................................................................................................................................................. 13 SQRT()........................................................................................................................................................... 13 TAN() ............................................................................................................................................................. 14
Manipulao de arrays.............................................................................................................................. 16
AADD() ......................................................................................................................................................... 16 ACLONE() ..................................................................................................................................................... 17 ACOPY() ....................................................................................................................................................... 17 ADEL() .......................................................................................................................................................... 18 ADIR() ........................................................................................................................................................... 18 AFILL() ......................................................................................................................................................... 19 AINS() ........................................................................................................................................................... 20 ARRAY() ....................................................................................................................................................... 20 ASCAN() ....................................................................................................................................................... 21 ASCANX() .................................................................................................................................................... 22 ASIZE() ......................................................................................................................................................... 22 ASORT() ........................................................................................................................................................ 23 ATAIL() ......................................................................................................................................................... 24
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
ISUPPER() ..................................................................................................................................................... 32 LEN() ............................................................................................................................................................. 33 LOWER() ....................................................................................................................................................... 33 LTRIM() ........................................................................................................................................................ 33 MATHC() ...................................................................................................................................................... 34 OEMTOANSI() ............................................................................................................................................. 34 PADL() / PADR() / PADC() .......................................................................................................................... 35 RAT() ............................................................................................................................................................. 35 REPLICATE() ............................................................................................................................................... 36 RTRIM() ........................................................................................................................................................ 36 SPACE() ........................................................................................................................................................ 37 STRTOKARR() ............................................................................................................................................. 37 STRTRAN() ................................................................................................................................................... 37 STUFF() ......................................................................................................................................................... 38 SUBSTR() ...................................................................................................................................................... 38 TRANSFORM() ............................................................................................................................................ 39 UPPER() ........................................................................................................................................................ 39
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
FILENOEXT() ............................................................................................................................................... 63 FOPEN() ........................................................................................................................................................ 63 FREAD() ........................................................................................................................................................ 65 FREADSTR () ............................................................................................................................................... 65 FRENAME() .................................................................................................................................................. 66 FSEEK()......................................................................................................................................................... 66 FT_FEOF() .................................................................................................................................................... 67 FT_FGOTO() ................................................................................................................................................. 67 FT_FGOTOP() ............................................................................................................................................... 68 FT_FLASTREC() .......................................................................................................................................... 68 FT_FREADLN() ............................................................................................................................................ 69 FT_FRECNO() .............................................................................................................................................. 69 FT_FSKIP() ................................................................................................................................................... 70 FT_FUSE() .................................................................................................................................................... 70 FWRITE() ...................................................................................................................................................... 70 MSCOPYFILE() ............................................................................................................................................ 73 MSCOPYTO() ............................................................................................................................................... 73 MSCREATE()................................................................................................................................................ 74 MSERASE() .................................................................................................................................................. 75 MSRENAME() .............................................................................................................................................. 75 RETFILENAME() ......................................................................................................................................... 76
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
DBSETINDEX() .......................................................................................................................................... 100 DBSETNICKNAME() ................................................................................................................................. 100 DBSELECTAREA() .................................................................................................................................... 101 DBSETORDER() ......................................................................................................................................... 102 DBORDERNICKNAME() .......................................................................................................................... 102 DBSEEK() E MSSEEK()............................................................................................................................. 102 DBSKIP()..................................................................................................................................................... 104 DBSETFILTER() ......................................................................................................................................... 104 DBSTRUCT() .............................................................................................................................................. 105 DBUNLOCK() ............................................................................................................................................. 106 DBUNLOCKALL() ..................................................................................................................................... 106 DBUSEAREA() ........................................................................................................................................... 107 DELETED() ................................................................................................................................................. 107 FCOUNT() ................................................................................................................................................... 108 FOUND() ..................................................................................................................................................... 108 INDEXKEY() .............................................................................................................................................. 109 INDEXORD() .............................................................................................................................................. 109 LUPDATE() ................................................................................................................................................. 110 MSAPPEND().............................................................................................................................................. 110 MSUNLOCK() ............................................................................................................................................ 111 ORDBAGEXT() .......................................................................................................................................... 111 ORDKEY() .................................................................................................................................................. 112 RECLOCK() ................................................................................................................................................ 112 RECNO() ..................................................................................................................................................... 114 SELECT() .................................................................................................................................................... 114 SET FILTER TO .......................................................................................................................................... 115 SOFTLOCK() .............................................................................................................................................. 115 USED() ........................................................................................................................................................ 116
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
X5DESCRI() ................................................................................................................................................ 167 X6CONTEUD() ........................................................................................................................................... 168 X6DESCRIC() ............................................................................................................................................. 168 XADESCRIC() ............................................................................................................................................ 169 XBDESCRI() ............................................................................................................................................... 170 XFILIAL() ................................................................................................................................................... 170
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cData
Exemplo: LOCAL cData := 31/12/2006 LOCAL dData := CTOD(cData) IF dDataBase >= dData MSGALERT(Data do sistema fora da competncia) ELSE MSGINFO(Data do sistema dentro da competncia) ENDIF
CVALTOCHAR() Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de espaos a informao. Sintaxe: CVALTOCHAR(nValor) Parmetros Valor numrico que ser convertido para caractere.
nValor
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
dData
DTOS() Realiza a converso de uma informao do tipo data em um caracter, sendo o resultado no formato AAAAMMDD. Sintaxe: DTOS(dData) Parmetros Varivel com contedo data
dData
Exemplo: cQuery := SELECT A1_COD, A1_LOJA, A1_NREDUZ FROM SA1010 WHERE cQuery += A1_DULTCOM >=+DTOS(dDataIni)+
STOD() Realiza a converso de uma informao do tipo string com contedo no formato AAAAMMDD em data, no formato DD/MM/AAAA. Sintaxe: STOD(sData) Parmetros String no formato AAAAMMDD
sData
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
STR() Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos direita. Sintaxe: STR(nValor) Parmetros Valor numrico que ser convertido para caractere.
nValor
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 Valor numrico que ser convertido para caractere. Tamanho total desejado para a string retornada.
nValor nTamanho
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
10
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
VAL() Realiza a converso de uma informao do tipo caracter em numrica. Sintaxe: VAL(cValor) Parmetros String que ser convertida para numrico.
cValor
Exemplo: LOCAL cValor := 12345 LOCAL nValor := VAL( cValor ) + 1 MSGINFO( nValor )
Matemticas
ACOS() Funo utilizada para calcular o valor do arco co-seno. Sintaxe: ACOS(nValor) Parmetros: Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.
nValor Retorno:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
11
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Valor limite para anlise da funo, no formato floating-point.
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. Sintaxe: COS(nAngulo) Parmetros: Valor que representa o ngulo em radianos.
nAngulo Retorno:
Numrico
Situaes invlidas: Exceo apresentada None INVALID INEXACT+OVERFLOW Significado da Exceo Sem Domnio Sem Domnio OVERFLOW
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da funo COS().
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
12
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Valor cujo o logaritmo deve ser encontrado.
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).
SIN() Funo utilizada para calcular o valor do seno ou seno hiperblico. Devemos informar como parmetro para a funo um valor que representa o angulo em radianos. Sintaxe: SIN(nAngulo) Parmetros: Valor do ngulo em radianos.
nAngulo Retorno:
Numrico
Situaes invlidas: Exceo apresentada None INVALID INEXACT+OVERFLOW Significado da Exceo Sem Domnio Sem Domnio OVERFLOW
Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da funo SIN().
SQRT() Funo utilizada para calcular a raiz quadrada de um nmero positivo. Sintaxe: SQRT(nValor)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
13
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
TAN() Funo utilizada para calcular o valor da tangente ou tangente hiperblica. Sintaxe: TAN(nAngulo) Parmetros: Valor do ngulo em radianos.
nAngulo Retorno:
Numrico
Situaes invlidas: Exceo apresentada None INVALID Significado da Exceo Sem Domnio Sem Domnio
Entrada QNAN,IND
Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da funo cos.
Anlise de variveis
TYPE() Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo. Sintaxe: TYPE(cVariavel) Parmetros Nome da varivel que se deseja avaliar, entre aspas ().
cVariavel
Exemplo: 14
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
VALTYPE() Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo. Sintaxe: VALTYPE(cVariavel) Parmetros Nome da varivel que se deseja avaliar.
cVariavel
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
15
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Array pr-existente no qual ser adicionado o item definido em xItem Item que ser adicionado ao array.
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
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
16
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
// aDados [3][2] -> corresponde ao contedo de cVariavel2 // aDados [3][3] -> corresponde ao contedo de cVariavel3 // Desta forma, o array aDados montando com uma estrutura de 03 linhas e 03 colunas, com // o contedo definido por variveis externas, mas com a mesma forma obtida com o uso do // comando: aDados := ARRAY(3,3).
ACLONE() A funo ACLONE() realiza a cpia dos elementos de um array para outro array integralmente. Sintaxe: ACLONE(aArray) Parmetros Array pr-existente que ter seu contedo copiado para o array especificado.
aArray
Exemplo: Utilizando o array aDados utilizado no exemplo da funo AADD() Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array aDados aItens := ACLONE(aDados)
Por ser uma estrutura de memria, um array no pode ser simplesmente copiado para outro array atravs de uma atribuio simples (:=). Para mais informaes sobre a necessidade de utilizar o comando ACLONE() verifique o tpico 6.1.3 Cpia de Arrays.
ACOPY() Funo de array que copia elementos do array aOrigem para array aDestino. O array destino aDestino j deve ter sido declarado e grande o bastante para conter os elementos que sero copiados. Se o array aOrigem contiver mais elementos, alguns dos elementos no sero copiados. ACOPY() copia os valores de todos os dados, incluindo valores nulos (NIL) e cdigos de bloco. Se um elemento for um subarray, o elemento correspondente no array aDestino, conter o mesmo subarray. Portanto, ACOPY() no produzir uma cpia completa de array multidimensionais. Sintaxe: ACOPY( aOrigem, aDestino , [ nInicio ], [ nQtde ], [ nPosDestino ]) Parmetros: o array que contm os elementos a serem copiados. o array que receber a cpia dos elementos. 17
aOrigem aDestino
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
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 Array do qual deseja-se remover uma determinada posio Posio do array que ser removida
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.
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. 18
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Importante: ADir uma funo obsoleta, utilize sempre Directory(). Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora], [ aAtributo ]) Parmetros: 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.
cArqEspec
nArquivos
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 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: 19
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
aDestino
Exemplo: LOCAL aLogic[3] // Resultado: aLogic AFILL(aLogic, .F.) // Resultado: aLogic AFILL(aLogic, .T., 2, // Resultado: aLogic
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 Array pr-existente no qual desejasse inserir um novo elemento. Posio na qual o novo elemento ser inserido.
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}
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 Determina o nmero de linhas com as quais o array ser criado Determina o nmero de colunas com as quais o array ser criado
SP
nLinhas nColunas
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
20
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Exemplo: aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.
O array definido pelo comando Array() apesar de j possuir a estrutura solicitada, no possui contedo em nenhum de seus elementos, ou seja: aDados[1] -> array de trs posies aDados[1][1] -> posio vlida, mas de contedo nulo.
ASCAN() A funo ASCAN() permite que seja identificada a posio do array que contm uma determinada informao, atravs da anlise de uma expresso descrita em um bloco de cdigo. Sintaxe: ASCAN(aArray, bSeek) Parmetros 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.
aArray bSeek
Exemplo: aAlunos := {Mrcio, Denis, Arnaldo, Patrcia} bSeek := {|x| x == Denis} nPosAluno := aScan(aAlunos,bSeek) // retorno esperado
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. 21
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
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. 22
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: ASIZE(aArray, nTamanho) Parmetros 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.
aArray nTamanho
Exemplo: // Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo ADEL() ASIZE(aItens,Len(aItens-1)) // Neste ponto o array aItens possui 02 elementos, ambos com contedos vlidos.
Utilizar a funo ASIZE() aps o uso da funo ADEL() uma prtica recomendada e evita que seja acessada uma posio do array com um contedo invlido para a aplicao em uso.
ASORT() A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio pr-estabelecido. Sintaxe: ASORT(aArray, nInicio, nItens, bOrdem) Parmetros 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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
23
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Ao Z-> expresso que ser executadas pelo bloco de cdigo Ao1... AoZ -> intervalo de expresses que sero executadas pelo bloco de cdigo, no formato de lista de expresses. Retorno -> resultado da ultima ao executada pelo bloco de cdigo, no caso AoZ. Para maiores detalhes sobre a estrutura e utilizao de blocos de cdigo consulte o tpico 6.2 Listas de Expresses e Blocos de cdigo.
Exemplo 1: Ordenao ascendente aAlunos := { Mauren, Soraia, Andria} aSort(aAlunos) // Neste ponto, os elementos do array aAlunos sero {Andria, Mauren, Soraia}
Exemplo 2 : Ordenao descendente aAlunos := { Mauren, Soraia, Andria} bOrdem := {|x,y| x > y } // // // // // // Durante a execuo da funo aSort(), a varivel x receber o contedo do item que est posicionado. Como o item que est posicionado a posio aAlunos[x] e aAlunos[x] -> string contendo o nome de um aluno, pode-se substituir x por cNomeAtu. A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de cdigo bOrdem pode ser re-escrito como:
bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx} aSort(aAlunos,,bOrdem) // Neste ponto, os elementos do array aAlunos sero {Soraia , Mauren, Andria}
ATAIL() ATAIL() uma funo de manipulao de array que retorna o ltimo elemento de um array. Ela deve ser usada em substituio da seguinte construo: aArray [LEN( aArray )] Sintaxe: ATAIL( aArray ) Parmetros: o array de onde ser retornado o ltimo elemento.
aArray
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
24
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nUltimo
bBloco xParamZ
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
25
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
bBloco
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
bFor
bWhile
Exemplo 1: // Considerando o trecho de cdigo abaixo: dbSelectArea(SX5) dbSetOrder(1) dbGotop() While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA <= mv_par02 nCnt++ dbSkip() End // O mesmo pode ser re-escrito com o uso da funo DBEVAL(): dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5") .And. X5_TABELA<=mv_par02})
Exemplo 2: // Considerando o trecho de cdigo abaixo: dbSelectArea(SX5) dbSetOrder(1) dbGotop() While !Eof() .And. X5_TABELA == cTabela AADD(aTabela,{X5_CHAVE, Capital(X5_DESCRI)}) dbSkip() End // O mesmo pode ser re-escrito com o uso da funo DBEVAL(): dbEval({|| AADD(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{|| X5_TABELA==cTabela})
Na utilizao da funo DBEVAL() deve ser informado apenas um dos dois parmetros: bFor ou bWhile.
AEVAL() A funo AEVAL() permite que todos os elementos de um determinada array sejam analisados e para cada elemento ser executado o bloco de cdigo definido. Sintaxe: AEVAL(aArray, bBloco, nInicio, nFim)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
26
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros 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.
aArray bBloco
nInicio nFim
Exemplo 1: Considerando o trecho de cdigo abaixo: AADD(aCampos,A1_FILIAL) AADD(aCampos,A1_COD) SX3->(dbSetOrder(2)) For nX:=1 To Len(aCampos) SX3->(dbSeek(aCampos[nX])) AADD(aTitulos,AllTrim(SX3->X3_TITULO)) Next nX O mesmo pode ser re-escrito com o uso da funo AEVAL(): aEval(aCampos,{|x| SX3->(dbSeek(x)),IIF(Found(), AADD(aTitulos,; AllTrim(SX3->X3_TITULO)))})
Manipulao de strings
ALLTRIM() Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado como parmetro. A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left trim). Sintaxe: ALLTRIM(cString) Parmetros String que ser avaliada para remoo dos espaos a direita e a esquerda.
cString
Exemplo: cNome := ALLTRIM(SA1->A1_NOME) MSGINFO(Dados do campo A1_NOME:+CRLF Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF Texto: + CVALTOCHAR(LEN(cNome))) 27
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
ASC() Converte uma informao caractere em seu valor de acordo com a tabela ASCII. Sintaxe: ASC(cCaractere) Parmetros Caracter que ser consultado na tabela ASCII.
cCaractere
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"
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)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
28
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
AT() Retorna a primeira posio de um caracter ou string dentro de outra string especificada. Sintaxe: AT(cCaractere, cString ) Parmetros Caractere ou string que se deseja verificar String na qual ser verificada a existncia do contedo de cCaractere.
cCaractere cString
IF !Empty(cMascara) .AND. AT(cMascara,cString) > 0 FOR nX := 1 TO Len(cString) IF !(SUBSTR(cString,nX,1) $ cMascara) cNoMascara += SUBSTR(cString,nX,1) ENDIF NEXT nX cNoMascara := PADR(ALLTRIM(cNoMascara),nTamanho) ELSE cNoMascara := PADR(ALLTRIM(cString),nTamanho) ENDIF RETURN cNoMascara
BITON() Funo utilizada para ligar determinados bits de uma String passada por parmetro para a funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem alterados(ligados) e o tamanho da string passada. Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > ) Parmetros 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.
Funo que avalia a string passada como parmetro alterando a primeira letra de cada palavra para maiscula e as demais letras como minsculas.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
29
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cFrase Retorno:
String
Contedo da string original com as modificaes necessrias para atender a condio da funo.
CHR() Converte um valor nmero referente a uma informao da tabela ASCII no caractere que esta informao representa. Sintaxe: CHR(nASCII) Parmetros Cdigo ASCII do caractere
nASCII
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: Corresponde seqncia de caracteres a ser analisada.
cString Retorno:
Caracter
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
30
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
// 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: Representa uma string contendo um valor numrico no qual ser convertido.
cDtoVal Retorno:
Numrico
Exemplo: GetDtoVal('123456') GetDtoVal('1/2/3/4/5/6') GetDtoVal('fim.123456') GetDtoVal('teste') //retorno 123456.0000 //retorno 123456.0000 //retorno 0.123456 //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: Cadeia de caracteres a ser examinada.
cString Retorno:
Lgico
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
31
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
caso contrrio, retorna falso (.F.). ISDIGIT() Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um dgito numrico entre zero e nove. Sintaxe: ISDIGIT ( < cString > ) Parmetros: Cadeia de caracteres a ser examinada.
cString Retorno:
Lgico
Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito entre zero e nove; caso contrrio, retorna falso (.F.).
ISLOWER() Funo utilizada para determinar se o caractere mais esquerda uma letra minscula, permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa. Sintaxe: ISLOWER( < cString > ) Parmetros: Cadeia de caracteres a ser examinada.
cString Retorno:
Lgico
Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo , caso contrrio, retorna falso (.F.).
ISUPPER() Funo utilizada para determinar se o caractere mais esquerda uma letra maiscula, permitindo avaliar se o primeiro caractere de um string uma letra maiscula. o contrrio de ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa. Sintaxe: ISUPPER( < cString > ) Parmetros: Cadeia de caracteres a ser examinada.
cString
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
32
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Retorno: Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo , caso contrrio, retorna falso (.F.).
Lgico
LEN() Retorna o tamanho da string especificada no parmetro. Sintaxe: LEN(cString) Parmetros String que ser avaliada
cString
Exemplo: cNome := ALLTRIM(SA1->A1_NOME) MSGINFO(Dados do campo A1_NOME:+CRLF Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF Texto: + CVALTOCHAR(LEN(cNome))) LOWER() Retorna uma string com todos os caracteres minsculos, tendo como base a string passada como parmetro. Sintaxe: LOWER(cString) Parmetros String que ser convertida para caracteres minsculos.
cString
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. 33
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: LTRIM ( < cString > ) Parmetros: <cString> a cadeia de caracteres a ser copiada sem os espaos em branco esquerda.
cString
Retorno: 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 ("").
Caracter
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: 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.
Caracter
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 > )
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
34
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cStringOEM Retorno:
Caracter
PADL() / PADR() / PADC() Funes de tratamento de strings que inserem caracteres de preenchimento para completar um tamanho previamente especificado em vrios formatos como data ou numricos. PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e esquerda. PADL() adiciona caracteres de preenchimento esquerda. PADR() adiciona caracteres de preenchimento direita.
Caso o tamanho de <cExp> exceda o argumento <nTamanho>, todas as funes PAD() truncam string preenchida ao <nTamanho> especificado. PADC(), PADL(), e PADR() so utilizadas para exibir cadeias de caracteres de tamanho varivel em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para assegurar o alinhamento com comandos ?? consecutivos. Outra utilizao exibir textos em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi completamente sobrescrito. PADC(), PADL(), e PADR() so o contrrio das funes ALLTRIM(), LTRIM(), e LTRIM(), as quais eliminam espaos em branco esquerda e direita de cadeias de caracteres. Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench ] ) Parmetros Caractere, data, ou numrico no qual sero inseridos caracteres de preenchimento. Tamanho da cadeia de caracteres a ser retornada. Caractere a ser inserido em cExp. Caso no seja especificado, o padro o espao em branco.
Retorno: Retornam o resultado de <cExp> na forma de uma cadeia de caracteres preenchida com <cCaracPreench>, para totalizar o tamanho especificado por <nTamanho>.
Caracter
RAT() Retorna a ltima posio de um caracter ou string dentro de outra string especificada.
35
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cCaractere cString
Caractere ou string que se deseja verificar String na qual ser verificada a existncia do contedo de cCaractere.
REPLICATE() A funo Replicate() utilizada para gerar uma cadeira de caracteres repetidos a partir de um caracter base informado, podendo a string gerada conter at 64KB. Caso seja especificado no parmetro de itens a repetir o nmero zero, ser retornada uma string vazia. Sintaxe: REPLICATE(cString, nCount) Parmetros: Caracter que ser repetido Quantidade de ocorrncias do caracter base que sero geradas na string de destino.
cString nCount
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> a cadeia de caracteres a ser copiada sem os espaos em branco direita.
cString
Retorno: 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 ("").
SP
Caracter
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
36
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: A quantidade de espaos a serem retornados, sendo que o nmero mximo 65.535 (64K).
nCont
Retorno: Retorna uma cadeia de caracteres. Se <nCont> for zero, SPACE()retorna uma cadeia de caracteres nula ("").
Caracter
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: Representa a cadeia de caracteres no qual desejamos separar de acordo com <cToken>. Representa o caracter que indica o separador em <cValue>.
Array
STRTRAN() Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive. Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) 37
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros: 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.
nStart
nCount
Retorno: A funo STRTRAN retorna uma nova string, com as ocorrncias especificadas de cSearch trocadas para cReplace, conforme parametrizao.
Code-Block
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: 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.
Caracter
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()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
38
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 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).
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: 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.
cExp cSayPicture
Retorno: Retorna a converso de <cExp> para uma cadeia de caracteres formatada conforme a definio em <cSayPicture>.
UPPER() Retorna uma string com todos os caracteres maisculos, tendo como base a string passada como parmetro. Sintaxe: UPPER(cString) Parmetros String que ser convertida para caracteres maisculos. 39
cString
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
dExp Retorno:
cDayWeek
Nome do dia da semana como uma cadeia de caracteres. A primeira letra maiscula e as demais minsculas.
Exemplo: dData := DATE() // Resultado: 09/01/90 cDiaDaSemana := CDOW(DATE()) // Resultado: Friday cDiaDaSemana := CDOW(DATE() + 7) // Resultado: Friday cDiaDaSemana := CDOW(CTOD("06/12/90")) // Resultado: Tuesday
A funo FG_CDOW(dExp) retorna o nome do dia da semana de acordo com o idioma em uso pelo ERP.
CMONTH() Funo de converso de datas que retorna uma cadeia de caracteres com o nome do ms em ingls. Sintaxe: CMONTH( dData ) Parmetros: Data que ser convertida.
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.
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
40
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
DATE() Funo que retorna a data do atual sistema. O formato de sada controlado pelo comando SET DATE, sendo que o formato padro mm/dd/yy. Sintaxe: DATE() Parmetros: .
Nenhum Retorno:
dData
Data do sistema.
Exemplo: dData := DATE() // Resultado: 09/01/01 dData := DATE() + 30 // Resultado: 10/01/01 dData := DATE() - 30 // Resultado: 08/02/90 dData := DATE() cMes := CMONTH(dData) // Resultado: September
DAY() Funo de converso de datas usada para converter o valor data em um nmero inteiro que representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR() para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas. Sintaxe: DAY( dData ) Parmetros: Data que ser convertida.
dData Retorno:
nDias
Se o ms do argumento dData for fevereiro, anos bissextos so considerados. Se a data do argumento dData for 29 de fevereiro e o ano no for bissexto, ou se o argumento dData for vazio.
Exemplo:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
41
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
// 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
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: Data que ser convertida.
dData Retorno:
nDia
Retorna um nmero entre zero e sete, representando o dia da semana. O primeiro dia da semana 1 (Domingo) e o ltimo 7 (Sbado). Se a data for vazia ou invlida, DOW() retorna zero.
Exemplo: 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: Data que ser convertida.
dData
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
42
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Retorno: 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.
cData
Exemplo: cData := DATE() // Resultado: 09/01/90 cData := DTOC(DATE()) // Resultado: 09/01/90 cData := "Today is " + DTOC(DATE()) // Resultado: Today is 09/01/90
DTOS() Funo para converso de uma data que pode ser usada para criar expresses de ndice. O resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia). Sintaxe: DTOS( dData ) Parmetros: Data que ser convertida.
dData Retorno:
sData
Retorna uma cadeia de caracteres com oito byte de tamanho no formato yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia de caracteres com oito espaos. O valor retornado no afetado pela formato da data corrente.
Exemplo: cData := DATE() // Resultado: 09/01/90 cData := DTOS(DATE()) // Resultado: 19900901 nLen := LEN(DTOS(CTOD(""))) // Resultado: 8
ELAPTIME() Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos. Sintaxe: ElapTime( cHoraInicial , cHoraFinal ) Parmetros: 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.
cHoraInicial CHoraFinal
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
43
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Caracter
Exemplo: cHoraInicio := TIME() // Resultado: 10:00:00 ... <instrues> ... cElapsed := ELAPTIME(TIME(), cHoraInicio)
MONTH() Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que retorna o nome do ms a partir do valor de dData. Sintaxe: MONTH( dData ) Parmetros: Data que ser convertida.
dData Retorno:
Numrico
>=0 e <=12 Para uma data vlida. 0 Se a data for nula ou invlida
Exemplo: dData := DATE() // Resultado: 09/01/01 nMes := MONTH(DATE()) // Resultado: 9 nMes := MONTH(DATE()) + 1 // Resultado: 10
SECONDS() Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a hora do sistema. Est relacionada funo TIME() que retorna a hora do sistema como uma cadeia de caracteres no formato hh:mm:ss. Sintaxe: SECONDS() Parmetros: .
Nenhum Retorno:
Numrico
>=0 e <=86399 Retorna a hora do sistema em segundos. O valor numrico representa o nmero de segundos decorridos desde a meia-noite,
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
44
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Exemplo: cHora := TIME() // Resultado: 10:00:00 cSegundos := SECONDS() // Resultado: 36000.00 //Este exemplo usa a funo SECONDS() para cronometrar o tempo decorrido: LOCAL nStart, nElapsed nStart:= SECONDS()
TIME() Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos. Sintaxe: TIME() Parmetros: .
Nenhum Retorno:
Caracter
A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.
Exemplo: cTime := TIME() // Resultado: 10:37:17 cHora := SUBSTR(cTime, 1, 2) // Resultado: 10 cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37 cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17
YEAR() YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR() membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui DAY() e MONTH() que retornam o dia e o ms como valores numricos. Sintaxe: YEAR( dData ) Parmetros: Data que ser convertida.
dData Retorno:
Numrico
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
45
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
do sculo. O valor retornado no afetado pelos valores especificados pelos comandos SET DATE ou SET CENTURY. Para uma data invlida ou nula ser retornado o valor 0.
Exemplo 1: dData := DATE() // Resultado: 09/20/01 dAno := YEAR(dData) // Resultado: 2001 dAno := YEAR(dData) + 11 // Resultado: 2012
Exemplo 2: // Este exemplo cria uma funo de usurio que usa a funo YEAR() para formatar o valor da // data: cData := Mdy(DATE()) // Result: September 20, 1990 FUNCTION Mdy( dDate ) RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))) + "," + STR(YEAR(dDate))
nValor
Exemplo: nPessoas := 20 nLugares := 18 IF nPessoas < nLugares MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis) ELSE MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando) ENDIF
ALEATORIO() Gera um nmero aleatrio de acordo com a semente passada. Esta funo retorna um nmero aleatrio menor ou igual ao primeiro parmetro informado, usando como semente o segundo 46
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
parmetro. recomendado que esta semente seja sempre o ltimo nmero aleatrio gerado por esta funo. Sintaxe: Aleatorio(nMax,nSeed) Parmetros Nmero mximo para a gerao do nmero aleatrio Semente para a gerao do nmero aleatrio
nMax nSeed
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 Valor que ser avaliado
nValor
Exemplo: STATIC FUNCTION COMPRAR(nQuantidade) LOCAL nDinheiro := 0.30 LOCAL nPrcUnit := 0.25 IF nDinheiro >= (nQuantidade*nPrcUnit) RETURN nQuantidade ELSEIF nDinheiro > nPrcUnit nQuantidade := INT(nDinheiro / nPrcUnit) ELSE nQuantidade := 0 ENDIF RETURN nQuantidade
NOROUND()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
47
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Valor que ser avaliado Nmero de casas decimais vlidas. A partir da casa decimal especificada os valores sero desconsiderados.
nValor nCasas
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 . nMinimo nMaximo Retorno: 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 . Sintaxe: RANDOMIZE ( < nMinimo > , < nMaximo > ) Parmetros Corresponde ao menor numero a ser gerado pela funo. Corresponde ao maior nmero ( menos um ) a ser gerado pela funo.
Numrico
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
48
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
2.99
Manipulao de arquivos
ADIR() Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados. Importante: ADir uma funo obsoleta, utilize sempre Directory(). Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora], [ aAtributo ]) Parmetros: 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.
cArqEspec
nArquivos
49
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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: 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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
50
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
#include "protheus.ch" //+--------------------------------------------------------------------+ //| Rotina | SELFILE | Autor | | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Funo exemplo para seleo de mltiplos arquivos. | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
51
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
//+--------------------------------------------------------------------+ //| Rotina | PARBOXFILE | Autor | | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Funo exemplo de uso da PARAMBOX em conjunto com CGETFILE| //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ STATIC FUNCTION PARBOXFILE() Local Local Local Local Local Local Local aParamBox := {} cTitulo := "Filtros Adicionais" aRet := {} bOk := {|| .T.} aButtons := {} lCentered := .T. nPosx
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
52
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
//+--------------------------------------------------------------------+ //| Rotina | MARKFILE | Autor | | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Descr. | Funo exemplo para marcao de mltiplos arquivos. | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ STATIC FUNCTION MARKFILE(aArquivos,cDiretorio,cDriver,lSelecao) Local aChaveArq := {} Local cTitulo := "Arquivos para importao: " Local bCondicao := {|| .T.} // Variveis utilizadas na seleo de categorias Local oChkQual,lQual,oQual,cVarQ // Carrega bitmaps Local oOk := LoadBitmap( GetResources(), "LBOK") Local oNo := LoadBitmap( GetResources(), "LBNO") // Variveis utilizadas para lista de filiais Local nx := 0 Local nAchou := 0 //+--------------------------------------------------------------------+ //| Carrega os arquivos do diretrio no array da ListBox | //+--------------------------------------------------------------------+ For nX := 1 to Len(aArquivos)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
53
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
//+--------------------------------------------------------------------+ //| 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
//+--------------------------------------------------------------------+ //| Rotina | TROCA | Autor | | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ STATIC FUNCTION Troca(nIt,aArray) aArray[nIt,1] := !aArray[nIt,1] Return aArray
//+--------------------------------------------------------------------+ //| Rotina | MARCAOK | Autor | | Data | 01.01.2007 | //+--------------------------------------------------------------------+ //| Uso | CURSO DE ADVPL | //+--------------------------------------------------------------------+ STATIC FUNCTION MarcaOk(aArray) Local lRet:=.F.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
54
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Local nx:=0 // Checa marcaes efetuadas For nx:=1 To Len(aArray) If aArray[nx,1] lRet:=.T. EndIf Next nx // Checa se existe algum item marcado na confirmao If !lRet HELP("SELFILE",1,"HELP","SEL. FILE","No existem itens marcados",1,0) EndIf Return lRet
CPYS2T() Funo utilizada para copiar um arquivo do servidor para o cliente (Remote), sendo que os caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada (lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do uso. Sintaxe: CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) Parmetros: cOrigem cDestino lCompacta Retorno: 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.
Lgico
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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
55
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
Lgico
Exemplo: // Copia arquivos do cliente( remote ) para o Servidor compactando antes de transmitir CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP", .T. ) // Copia arquivos do cliente( remote ) para o Servidor sem compactar. CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" )
CURDIR() Funo que retorna o diretrio corrente do servidor. O caminho retornado sempre relativo ao RootPath definido na configurao do Environment no .INI do Protheus Server. Inicialmente , o diretrio atual da aplicao o constante na chave StartPath , tambm definido na configurao do Environment no .INI do Protheus Server. Caso seja passado o parmetro cNovoPath , este path assumido como sendo o Path atual. Caso o path recebido como parmetro no exista , seja invlido , ou seja um path absoluto (iniciado com uma letra de drive ou caminho de rede), a funo no ir setar o novo path, mantendo o atual . Sintaxe: CURDIR ( [ cNovoPath ] ) Parmetros: Caminho relativo , com o novo diretrio que ser ajustado como corrente.
cNovoPath Retorno:
Caracter
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
56
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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> 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.
cDirSpec
cAtributos>
Retorno:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
57
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
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: Nome do diretrio a ser removido.
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().
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
58
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
nDrive
Numrico
Exemplo: nBytesLocal := DISKSPACE( ) // Retorna o espao disponvel na unidade de disco local IF nBytesLocal < 1048576 MsgStop('Unidade de Disco local possui menos de 1 MB livre.') Else MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes livres.') Endif nBytes_A := DISKSPACE( 1 ) // Retorna o espao disponvel no drive A: local ( remote ). If nBytes_A == -1 MsgStop('Unidade A: no est disponvel ou no h disco no Drive') ElseIf nBytes_A < 8192 MsgStop('No h espao disponvel no disco. Substitua o disco na Unidade A:') Else MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes livres.') Endif
EXISTDIR() Funo utilizada para determinar se um path de diretrio existe e valido. Sintaxe: EXISTDIR (< cPath >)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
59
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros: 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.
cPath
Retorno: Retorna se verdadeiro(.T.) caso o diretrio solicitado exista, falso(.F.) caso contrrio.
Lgico
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: Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().
nHandle Retorno:
Lgico
Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos; do contrrio, retorna verdadeiro (.T.).
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
60
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
cArquivo
nAtributo
Retorno: 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() .
Numrico
FERASE()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
61
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
cArquivo
Retorno: 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().
Numrico
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: Nome do arquivo , podendo ser especificado um path (caminho) . Caminhos locais (Remote) ou caminhos de servidor so aceitos , bem como wildcards (Caracteres * e ? ).
cArquivo
Retorno: O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no exista no path especificado , a funo retorna .F.
Lgico
Exemplo: 62
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
//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 String contendo o nome do arquivo.
cString
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
63
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
cArq nModo
Retorno: FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso ocorra um erro, FOPEN() retorna -1.
Numrico
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 Constate(fileio.ch) FO_READ FO_WRITE FO_READWRITE Operao Aberto para leitura (padro assumido) Aberto para gravao Aberto para leitura e gravao
Modo 0 1 2
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
64
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Tabela B: Modos de acesso de compartilhamento a arquivos binrios 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.
Modo 0 16 32 48 64
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: 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.
nHandle cBuffer
nQtdBytes
Retorno: 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.
Numrico
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
65
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: o manipulador retornado pelas funes FOPEN(), FCREATE(), FOPENPORT(). Nmero mximo de bytes que devem ser lidos.
Caracter
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: 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.
cOldFile
cNewFile
Retorno: 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.
Numrico
FSEEK()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
66
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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. 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.
Origem 0 1 2
Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) Parmetros: 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.
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().
FT_FEOF() Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE() estiver posicionado no final do arquivo, similar funo EOF() utilizada para arquivos de dados. Sintaxe: FT_FEOF( ) Parmetros: .
Nenhum Retorno:
Lgico
Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso contrrio.
FT_FGOTO()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
67
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Indica a posio que ser colocado o ponteiro para leitura dos dados no arquivo.
nPos
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: Indica a posio que ser colocado o ponteiro para leitura dos dados no arquivo.
nPos
Retorno: .
Nenhum
FT_FLASTREC() Funo que retorna o nmero total de linhas do arquivo texto aberto pela FT_FUse. As linhas so delimitadas pela seqncia de caracteres CRLF o LF. Verifique maiores informaes sobre formato do arquivo e tamanho mximo da linha de texto na funo FT_FREADLN(). Sintaxe: FT_FLASTREC( ) Parmetros: .
Nenhum Retorno:
Numrico
Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja vazio, ou no exista arquivo aberto, a funo retornar 0 (zero).
Exemplo:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
68
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
Nenhum Retorno:
Caracter
Retorna a linha inteira na qual est posicionado o ponteiro para leitura de dados.
FT_FRECNO()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
69
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 corresponde ao nmero de linhas do arquivo TXT ref. movimentao do ponteiro de leitura do arquivo.
nLinhas
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: Corresponde ao nome do arquivo TXT a ser aberto. Caso o nome no seja passado, e j exista um arquivo aberto. o mesmo fechado.
cTXTFile
Retorno: A funo retorna o Handle de controle do arquivo. Em caso de falha de abertura, a funo retornar -1
Numrico
FWRITE() 70
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
nHandle cBuffer
nQtdBytes
Retorno: 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.
Numrico
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)
Exemplo (continuao):
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
71
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
// 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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
72
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Nome do arquivo origem e a extenso. Nome do arquivo destino e a extenso.
Lgico
Exemplo: Local cArqOrig := 'ARQ00001.DBF' Local cArqDest := 'ARQ00002.XXX' If MsCopyFile( cArqOrig, cArqDest ) APMsgInfo('Copia realizada com sucesso!') EndIf
MSCOPYTO() Funo que realiza a cpia dos registros de uma base de dados para outra, criando o arquivo destino de acordo com a estrutura da base de dados origem. Sintaxe: MSCOPYTO( [cArqOrig], cArqDest )
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
73
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros: 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.
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
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: Nome do arquivo. Estrutura do arquivo. RDD do arquivo.
Lgico
Exemplo:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
74
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Local cTarget := '\sigaadv\' Local aStrut aStrut := { { 'Campo', 'C', 40, 0 } } If MsCreate( cTarget+'ARQ1001', aStrut ) APMsgInfo('Criado com sucesso!') Else APMsgInfo('Problemas ao criar o arquivo!') EndIf
MSERASE() Funo utilizada para deletar fisicamente o arquivo especificado. Sintaxe: MsErase( cArquivo, [cIndice], [cDriver] ) Parmetros: 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.
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
MSRENAME() Funo que verifica a existncia do arquivo especificado. Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] ) Parmetros: 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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
75
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Lgico
Exemplo: Local cArquivo := 'SX2ZZZ.DBF' Local cIndice := 'SX2ZZZ'+ OrdBagExt() If !MsFile ( cArquivo, cIndice ) APMsgInfo( 'Arquivo no encontrado!' ) EndIf
RETFILENAME() Funo que retorna o nome de um arquivo contido em uma string, ignorando o caminho e a extenso. Sintaxe: RetFileName( cArquivo ) Parmetros: String contendo o nome do arquivo
cArquivo Retorno:
Caracter
aArray
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
76
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
criada no formato: {Nome, Tipo, Tamanho, Decimal} lDbf Retorno: Nome do Arquivo gerado pela funo. Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )
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
77
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 ("").
Exemplo: cAlias := alias() IF empty(cAlias) alert('No h Area em uso') Else alert(Area em uso atual : '+cAlias) Endif
BOF() / EOF() As funes BOF() e EOF() so utilizadas para determinar se o ponteiro de leitura do arquivo encontra-se no comeo ou no final do mesmo conforme abaixo: BOF() uma funo de tratamento de banco de dados utilizada para condio de limite de inicial do arquivo quando o ponteiro de registros est para trs em um arquivo de banco de dados. EOF() uma funo de tratamento de banco de dados utilizada para condio de limite de final de arquivo quando o ponteiro de registros est para frente em um arquivo de banco de dados. testar uma se movendo testar uma se movendo
Normalmente utilizada a condio EOF() como parte do argumento <lCondicao> de uma construao DO WHILE que processa registros sequencialmente em um arquivo de banco de dados. Neste caso <lCondicao> incluiria um teste para .NOT. EOF(), forando o lao DO WHILE a terminar quando EOF() retornar verdadeiro (.T.) Sintaxe: BOF() / EOF() Parmetros: .
Nenhum Retorno:
Lgico
Lgico
Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de registros para alm do primeiro registro lgico em um arquivo de banco de dados, do contrrio, ela retorna falso (.F.). Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de registros para alm do ltimo registro lgico em um arquivo de banco de dados, do contrrio, ela retorna falso (.F.). Caso nao haja nenhum arquivo de banco de dados aberto na rea de trabalho corrente, EOF() retorna falso
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
78
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
(.F.). Se o arquivo de banco de dados corrente no possui registros, EOF() retorna verdadeiro (.T.).
COPY() O comando COPY TO permite a cpia de todos ou parte dos registros da tabela atualmente selecionada como rea de trabalho atual, para um novo arquivo. Os registros considerados para a cpia podem ser limitados pela clusula <escopo>, atravs de expresses FOR/WHILE, e/ou atravs de um filtro. Se o filtro para registros deletados ( SET DELETED ) estiver desligado (OFF), registros deletados ( marcados para deleo ) so copiados para o arquivo de destino, mantendo este status. Caso contrrio, nenhum registro deletado copiado. Da mesma maneira, caso exista uma condio de filtro na tabela atual ( SET FILTER ), apenas os registros que satisfaam a condio de fintro sero copiados. Os registros so lidos na tabela atual, respeitando a ordem de ndice setada. Caso no hajam ndices abertos, ou a ordem de navegao nos ndices (SET ORDER ) seja 0 (zero), os registros so lidos em orden natural ( ordem de RECNO ) . A tabela de destino dos dados copiados criada, e aberta em modo exclusivo, antes da operao de cpia efetiva ser iniciada. Tabela A : Especificao do formato SDF ( System Data Format ) 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
SP
Elemento do Arquivo Campos 'C' Caractere Campos 'D' Data Campos 'L' lgicos Campos 'M' Memo Campos 'N' Numricos Delimitador de Campos
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
79
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED WITH <cDelimiter> ) 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
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)
A Linguagem Advpl, antes do Protheus, suportava a gerao de uma tabela delimitada diferenciada, obtida atravs do comando COPY TO (...) DELIMITED WITH BLANK . No Protheus este formato no suportado. Caso utilize-se este comando com a sintaxe acima, o arquivo ASCII gerado ser delimitado, utilizando-se a sequncia de caracteres 'BLANK' como delimitadora de campos Caractere.
Sintaxe:
COPY [ FIELDS <campo,...> ] TO cFile [cEscopo] [ WHILE <lCondicao> ] [ FOR <lCondicao> ] [ SDF | DELIMITED [WITH <cDelimiter>] ] [ VIA <cDriver> ]
Parmetros:
FIELDS <campo,...> 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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
cEscopo
80
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
WHILE <lCondicao>
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.
VIA <cDriver>
Retorno: .
Nenhum
COPY STRUCTURE() O comando COPY STRUCTURE cria uma nova tabela vazia, com a estrutura da tabela ativa na rea de trabalho atual. Se a tabela a ser criada j exista, a mesma sobrescrita. A tabela de destino criada utiliza o mesmo RDD da tabela de origem ( tabela ativa na rea de trabalho atual ). A Linguagem Advpl, antes do Protheus, suportava a parametrizao de uma lista de campos da tabela atual, para compor a estrutura da tabela de destino, atravs da clusula FIELDS <campo,...>. Esta opo no suportada no Protheus. Caso seja utilizada, o programa ser abortado com a ocorrncia de erro fatal : 'DBCopyStruct - Parameter <Fields> not supported in Protheus' Sintaxe:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
81
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Se o valor for .T., libera todos os registros bloqueados anteriormente (locks). Se for .F., todos os bloqueios anteriores so mantidos. Valor default: .T.
lLiberaBloqueios
Retorno: .
Nenhum
Exemplo: USE Clientes NEW FOR i:=1 to 5 DBAPPEND(.F.) NOME := "XXX" END : ="YYY" NEXT // Os 5 registros includos permanecem bloqueados DBAPPEND() // Todos os bloqueios anteriores so liberados
DBCLEARALLFILTER() A funo DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as tabelas e depois limpa as condies de filtro de todas as tabelas. Sintaxe: DBCLEARALLFILTER() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
82
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
Nenhum
Exemplo: USE Clientes NEW DBSETFILTER( {|| Idade < 40}, 'Idade < 40') // Seta a expresso de filtro ... DBCLEARALLFILTER() // Limpa a expresso de filtro de todas as ordens
DBCLEARFILTER() A funo DBCLEARFILTER() salva as atualizaes realizadas e pendentes na tabela corrente e depois limpa todas as condies de filtro da ordem ativa no momento. Seu funcionamento oposto ao comando SET FILTER. Sintaxe: DBCLEARFILTER() Parmetros: .
Nenhum Retorno:
Nenhum
Exemplo: USE Clientes NEW DBSETFILTER( {|| Idade < 40}, "Idade < 40" ) // Seta a expresso de filtro ... DBCLEARFILTER() // Limpa a expresso de filtro
DBCLEARINDEX() A funo DBCLEARINDEX() salva as atualizaes pendentes na tabela corrente e fecha todos os arquivos de ndice da rea de trabalho. Por conseqncia, limpa todas as ordens da lista. Seu funcionamento oposto ao comando SET INDEX. Sintaxe: DBCLEARINDEX() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
83
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
Nenhum
Exemplo: USE Clientes NEW DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome" ... DBCLEARINDEX() // Fecha todos os arquivos de ndices
DBCLOSEALL() A funo DBCLOSEALL() salva as atualizaes pendentes, bloqueados e fecha todas as tabelas abertas (reas chamasse DBCLOSEAREA para cada rea de trabalho. Sintaxe: DBCLOSEALL() Parmetros: . libera todos os registros de trabalho) como se
Nenhum Retorno:
Nenhum
Exemplo: // Este exemplo demonstra como se pode utilizar o DBCLOSEALL para fechar a rea de trabalho atual. USE Clientes NEW DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome" USE Fornecedores NEW DBSETINDEX("Idade") // Abre o arquivo de ndice "Idade" ... DBCLOSEALL() //Fecha todas as reas de trabalho, todos os indices e ordens
DBCLOSEAREA() A funo DBCLOSEAREA() permite que um alias presente na conexo seja fechado, o que viabiliza seu reuso em outro operao. Este comando tem efeito apenas no alias ativo na conexo, sendo necessria sua utilizao em conjunto com o comando DbSelectArea(). Sintaxe: DBCLOSEAREA() 84
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros: .
Nenhum Retorno:
Nenhum
Exemplo: DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.) DbSelectArea(SA1DBF) MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.) DbCloseArea()
DBCOMMIT() A funo DBCOMMIT() salva em disco todas as atualizaes pendentes na rea de trabalho corrente. Sintaxe: DBCOMMIT() Parmetros: .
Nenhum Retorno:
Nenhum
Exemplo: USE Clientes NEW DBGOTO(100) Nome := "Jose" 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: 85
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
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: 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.
cNOME
aESTRUTURA cDRIVER
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 86
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Erros mais comuns: 1. DBCreate - Data base files can only be created on the server: O nome do arquivo a ser criado no pode conter 'driver', pois, por conveno, ele seria criado na mquina onde o Remote est rodando. 2. DBCreate - Invalid empty filename: Nome do arquivo no foi especificado 3. DBCreate - Field's name cannot be 'DATA': Algumas RDD's no suportam este nome de campo. uma palavra reservada. 4. DBCreate - The length of Field's name must be at most 10: Nome do campo no pode ter mais que 10 caracteres. 5. DBCreate - Field's name must be defined: Nome do campo no foi definido. 6. DBCreate - Field's type is not defined: Tipo do campo no foi definido. 7. DBCreate - invalid Field's type: Tipo do campo diferente de 'C', 'N', 'D', 'M' ou 'L'. 8. DBCreate - Invalid numeric field format: Considerando 'len' o tamanho total do campo numrico e 'dec' o nmero de decimais, ocorre este erro se: (len = 1) .and. (dec <> 0): Se o tamanho total 1, o campo no pode ter decimais (len>1) .and. (len< dec + 2): Se o tamanho total maior que 1, ele deve ser maior que o nmero de decimais mais 2, para comportar o separador de decimais e ter pelo menos um algarismo na parte inteira. Exemplo: O nmero 12.45 poderia ser o valor de um campo com len=5 e dec=2 (no mnimo).
Erros mais comuns: Podem ocorrer tambm erros decorrentes de permisso e direitos na pasta onde se est tentando criar o arquivo ou por algum problema no banco de dados. Verifique as mensagens do servidor Protheus e do banco de dados.
DBCREATEINDEX() A funo DBCREATEINDEX() utilizada para criar um novo arquivo de ndice com o nome especificado atravs do primeiro parmetro, sendo que se o mesmo existir deletado e criado o novo. Para tanto so executados os passos a seguir: Salva fisicamente as alteraes ocorridas na tabela corrente; Fecha todos os arquivos de ndice abertos; Cria o novo ndice; Seta o novo ndice como a ordem corrente; Posiciona a tabela corrente no primeiro registro do ndice. 87
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: [lUNICO]) Parmetros: 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.). DBCREATEINDEX(<cNOME>, <cEXPCHAVE>, [bEXPCHAVE],
Nenhum
Exemplo: // Este exemplo mostra como se pode criar novo arquivo de ndice criando a ordem sobre os // campos Nome e End e no aceitar duplicao: USE Cliente VIA "DBFCDX" NEW DBCREATEINDEX("\teste\ind2.cdx","Nome+End",{ || Nome+End },.T.)
DBDELETE() A funo DBDELETE() marca o registro corrente como apagado logicamente(), sendo necessria sua utilizao em conjunto com as funes RecLock() e MsUnLock(). Para filtrar os registro marcados do alias corrente pode-se utilizar o comando SET DELETED e para apag-los fisicamente pode-se utilizar a funo __DBPACK(). Sintaxe: DBDELETE ( ) Parmetros: .
Nenhum Retorno:
Nenhum
88
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
DbSeek(01 + 900001 + 01) // Busca exata IF Found() RecLock(SA1,.F.) // Define que ser realizada uma alterao no registro posicionado DbDelete() // Efetua a excluso lgica do registro posicionado. MsUnLock() // Confirma e finaliza a operao ENDIF
DBF() A funo DBF() verifica qual o Alias da rea de trabalho corrente. O Alias definido quando a tabela aberta atravs do parmetro correspondente (DBUSEAREA()). Esta funo o inverso da funo SELECT(), pois nesta retornado o nmero da rea de trabalho do Alias correspondente. Sintaxe: DBF() Parmetros: .
Nenhum Retorno:
Caracter
Retorna o Alias corrente. Caso no exista Alias corrente retorna "" (String vazia).
Exemplo: dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. ) MessageBox("O Alias corrente : "+DBF(),"Alias", 0) //Resultado: "O Alias corrente : SSS"
DBFIELDINFO() A funo DBFIELDINFO() utilizada para obter informaes sobre determinado campo da tabela corrente. O tipo de informao (primeiro argumento) escolhido de acordo com as constantes abaixo: Tabela A : Constantes utilizadas na parametrizao da funo Constante 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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
89
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nINFOTIPO nCAMPO
Tipo de informao a ser verificada (DBS_NAME, DBS_DEC, DBS_LEN e DBS_TYPE). Posio do campo a ser verificado.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
90
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Retorno: 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).
Indefinido
Exemplo: USE Clientes NEW DBFIELDINFO(DBS_NAME,1) // Retorno: Nome DBFIELDINFO(DBS_TYPE,1) // Retorno: C DBFIELDINFO(DBS_LEN,1) // Retorno: 10 DBFIELDINFO(DBS_DEC,1) // Retorno: 0
DBFILTER() A funo DBFILTER() utilizada para verificar a expresso de filtro ativo na rea de trabalho corrente. Sintaxe: DBFILTER() Parmetros: .
Nenhum Retorno:
Caracter
Retorna a expresso do filtro ativo na rea de trabalho atual. Caso no exista filtro ativo retorna "" (String vazia).
Exemplo: USE Cliente INDEX Ind1 NEW SET FILTER TO Nome > "Jose" DBFILTER() // retorna: Nome > "Jose" SET FILTER TO Num < 1000 DBFILTER() // retorna: Num < 1000
DBGOTO() Move o cursor da rea de trabalho ativa para o record number (recno) especificado, realizando um posicionamento direto, sem a necessidade uma busca (seek) prvio. Sintaxe: DbGoto(nRecno) Parmetros
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
91
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nRecno
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.
DBGOBOTTON() Move o cursor da rea de trabalho ativa para o ltimo registro lgico. Sintaxe: DbGoBotton() Parmetros .
Nenhum Exemplo:
92
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 DBI_LASTUPDATE 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 da Retorno Numrico Caracter Caracter Lgico Lgico Lgico Numrico Caracter Data
de trabalho
nINFOTIPO Retorno:
Indefinido
Informao da Tabela Informao requisitada pelo usurio (o tipo depende da informao requisitada). Se no houver tabela corrente retorna NIL.
Exemplo:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
93
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Indica o "NickName" da ordem de ndice.
cNick Retorno:
Caracter
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
nINFOTIPO Retorno:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
94
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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.
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: Nome do apelido da ordem a ser setada.
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.
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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
95
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
USE Clientes NEW DBGOTO(100) DBDELETE() DBGOTO(105) DBDELETE() DBGOTO(110) DBDELETE() // Se a excluso for confirmada: __DBPACK()
DBRECALL() A funo DBRECALL() utilizada para retirar a marca de registro deletado do registro atual. Para ser executada o registro atual deve estar bloqueado ou a tabela deve estar aberta em modo exclusivo. Se o registro atual no estiver deletado, esta funo no faz nada. Ela o oposto da funo DBDELETE() que marca o registro atual como deletado. Sintaxe: DBRECALL() Parmetros: .
Nenhum Retorno:
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()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
96
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
Sintaxe: DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO Parmetros: Tipo de informao a ser verificada. Nmero do registro a ser verificado.
Indefinido
No h tabela corrente ou registro invlido. Informao do Registro. Informao requisitada pelo usurio (o tipo depende da informao requisitada).
Exemplo: USE Clientes NEW DBGOTO(100) DBRECORDINFO(DBRI_DELETED) // Retorno: .F. DBDELETE() DBRECORDINFO(DBRI_DELETED) // Retorno: .F. DBRECALL() DBRECORDINFO(DBRI_RECSIZE) // Retorno: 230 NOME := "JOAO" DBGOTO(200) DBRECORDINFO(DBRI_UPDATED) // Retorno: .F. DBRECORDINFO(DBRI_UPDATED,100) // Retorno: .T.
DBREINDEX() A funo DBREINDEX() reconstri todos os ndices da rea de trabalho corrente e posiciona as tabelas no primeiro registro lgico. Sintaxe: DBREINDEX() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
97
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
Nenhum
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: Nmero do registro a ser bloqueado.
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.
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()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
98
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros: .
Nenhum Retorno:
Array
Retorna NIL se no existe tabela corrente ou no existe nenhum registro locado. Retorna a lista com os recnos dos registros locados na tabela corrente.
Exemplo: DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. ) DBGOTOP() DBRLOCK() // Bloqueia o primeiro registro DBRLOCK(110) // Bloqueia o registro de nmero 110 DBRLOCK(100) // Bloqueia o registro de nmero 100 DBRLOCKLIST() // Retorna: {1,100,110}
DBRUNLOCK() A funo DBRUNLOCK() utilizada para liberar determinado registro bloqueado. O usurio pode escolher o registro a ser desbloqueado atravs do parmetro (Recno), mas se este for omitido ser desbloqueado o registro corrente como na funo DBUNLOCK(). Esta funo o oposto DBRLOCK, que bloquea os registros. Sintaxe: DBRUNLOCK([nREGISTRO]) Parmetros: Nmero do registro a ser desbloqueado.
nREGISTRO Retorno: .
Nenhum
Exemplo: DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. ) DBGOTO(100) DBRUNLOCK() //Desbloqueia o registro atual (100) DBRUNLOCK(110) // Desbloqueia o registro de nmero 110
DBSETDRIVER() A funo DBSETDRIVER() pode ser utilizada apenas para verificar qual o RDD que est definido como padro quando for omitido seu parmetro. Ela tambm pode ser utilizada para especificar outro RDD como padro, especificando-o atravs do parmetro.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
99
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: DBSETDRIVER([cNOVORDD]) Parmetros: Novo nome do RDD a ser definido como padro.
cNOVORDD Retorno:
Caracter
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: Nome do arquivo de ndice, com ou sem diretrio.
cARQINDICE Retorno: .
Nenhum
DBSETNICKNAME()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
100
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Nome da ordem que deve receber o apelido. Nome do apelido da ordem a ser setada.
Caracter
Retorna "" (String vazia) se no conseguiu encontrar a ordem especificada, no conseguiu setar o apelido ou no havia apelido. Retorna o apelido corrente.
Exemplo: USE Cliente NEW DBSETNICKNAME("IndNome") // retorna: "" DBSETNICKNAME("IndNome","NOME") // retorna: "" DBSETNICKNAME("IndNome") // retorna: "NOME"
DBSELECTAREA() Define a rea de trabalho especificada com sendo a rea ativa. Todas as operaes subseqentes que fizerem referncia a uma rea de trabalho a utilizao, a menos que a rea desejada seja informada explicitamente. Sintaxe: DbSelectArea(nArea | cArea) Parmetros 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.
nArea cArea
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
101
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Nmero de referncia da ordem que deseja ser definida como ordem ativa para a rea de trabalho.
nOrdem
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 atribudo ao ndice criado pelo usurio
NickName
Exemplo: DbSelectArea(SA1) DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO NickName: Tipo
DBSEEK() E MSSEEK()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
102
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 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.
cChave
lSoftSeek lLast
Exemplo 01: Busca exata DbSelectArea(SA1) DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001, Loja: 02 MsgInfo(Cliente localizado, Consulta por cliente) Else MsgAlert(Cliente no encontrado, Consulta por cliente) Endif
Exemplo 02: Busca aproximada DbSelectArea(SA1) DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA DbSeek(01 + 000001 + 02, .T. ) // Filial: 01, Cdigo: 000001, Loja: 02 // Exibe os dados do cliente localizado, o qual pode no ser o especificado na chave: MsgInfo(Dados do cliente localizado: +CRLF +; Filial: + A1_FILIAL + CRLF +; Cdigo: + A1_COD + CRLF +; Loja: + A1_LOJA + CRLF +; Nome: + A1_NOME + CRLF, Consulta por cliente) MsSeek(): Funo desenvolvida pela rea de Tecnologia da Microsiga, a qual possui as mesmas funcionalidades bsicas da funo DbSeek(), com a vantagem de no necessitar
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
103
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
acessar novamente a base de dados para localizar uma informao j utilizada pela thread (conexo) ativa. Desta forma, a thread mantm em memria os dados necessrios para reposicionar os registros j localizados atravs do comando DbSeek (no caso o Recno()) de forma que a aplicao pode simplesmente efetuar o posicionamento sem executar novamente a busca. A diferena entre o DbSeek() e o MsSeek() notada em aplicaes com grande volume de posicionamentos, como relatrios, que necessitam referenciar diversas vezes o mesmo registro durante uma execuo.
DBSKIP() Move o cursor do registro posicionado para o prximo (ou anterior dependendo do parmetro), em funo da ordem ativa para a rea de trabalho. Sintaxe: DbSkip(nRegistros) Parmetros Define em quantos registros o cursor ser deslocado. Padro 1
nRegistros
Exemplo 01: Avanando registros DbSelectArea(SA1) DbSetOrder(2) // A1_FILIAL + A1_NOME DbGotop() // Posiciona o cursor no incio da rea de trabalho ativa While !EOF() // Enquanto o cursor da rea de trabalho ativa no indicar fim de arquivo MsgInfo(Voc est no cliente: + A1_NOME) DbSkip() End
Exemplo 02: Retrocedendo registros DbSelectArea(SA1) DbSetOrder(2) // A1_FILIAL + A1_NOME DbGoBotton() // Posiciona o cursor no final da rea de trabalho ativa While !BOF() // Enquanto o cursor da rea de trabalho ativa no indicar incio de arquivo MsgInfo(Voc est no cliente: + A1_NOME) DbSkip(-1) End
DBSETFILTER()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
104
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Bloco de expressa a condio de filtro em forma executvel Expresso de filtro simples na forma de string
bCondicao cCondicao
Exemplo 01: Filtro com bloco de cdigo bCondicao := {|| A1_COD >= 000001 .AND. A1_COD <= 001000} DbSelectArea(SA1) DbSetOrder(1) DbSetFilter(bCondicao) DbGoBotton() While !EOF() MsgInfo(Voc est no cliente:+A1_COD) DbSkip() End // O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
Exemplo 02: Filtro com expresso simples cCondicao := A1_COD >= 000001 .AND. A1_COD <= 001000 DbSelectArea(SA1) DbSetOrder(1) DbSetFilter(,cCondicao) DbGoBotton() While !EOF() MsgInfo(Voc est no cliente:+A1_COD) DbSkip() End // O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
DBSTRUCT() Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura ser um array bidimensional conforme abaixo: ID* Nome campo Tipo campo Tamanho Decimais
ndice do array
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
105
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum
Exemplo: cCampos := DbSelectArea(SA1) aStructSA1 := DbStruct() FOR nX := 1 to Len(aStructSA1) cCampos += aStructSA1[nX][1] + / NEXT nX ALERT(cCampos)
DBUNLOCK() A funo DBUNCLOK() retira os bloqueios dos registros e do arquivo da tabela corrente. Sintaxe: DBUNLOCK() Parmetros: .
Nenhum Retorno:
Nenhum
DBUNLOCKALL() A funo DBUNLOCKALL() Retira os bloqueios de todos os registros e dos arquivos de todas as tabelas abertas. Esta funo utilizada para liberar todos os registros bloqueados e equivalente a executar DBUNLOCK para todas as tabelas da rea de trabalho. Sintaxe: DBUNLOCKALL() Parmetros: .
Nenhum Retorno:
Nenhum
. 106
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 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.
lNovo
cDriver
Exemplo: DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.) DbSelectArea(SA1DBF) MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.) DbCloseArea()
DELETED() A funo DELETED() Verifica se o registro est com marca de excludo. Quando o registro excludo, permanece fisicamente na tabela, mas fica marcado como excludo. Esta funo verifica este estado. Se nenhuma rea est selecionada, retorna .F.. Quando executada a funo DBPACK() todos os registros marcados como deletados so apagados fisicamente. A funo DBRECALL() retira todas as marcas. Sintaxe: DELETED() Parmetros: .
Nenhum Retorno:
Nenhum
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
107
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
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.).
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
108
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
nOrdem
Retorno: 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 ("").
Caracter
INDEXORD() A funo INDEXORD() verifica a posio do ndice corrente na lista de ndices do respectivo alias. Sintaxe: INDEXORD() Parmetros: .
Nenhum Retorno:
Numrico
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
109
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Exemplo: USE Cliente NEW SET INDEX TO Nome, End, Cep nOrd:=INDEXORD() // Return: 1 - o primeiro ndice da lista
LUPDATE() A funo LUPDATE() verifica qual a data da ltima modificao e fechamento da tabela corrente, sendo que caso no exista tabela corrente retornada uma data em branco. Sintaxe: LUPDATE() Parmetros: .
Nenhum Retorno:
Data
Retorna um valor do tipo Data , indicando a data da ultima modificao e fechamento da Tabela. Caso no haja tabela selecionada na rea de trabalho atual , a funo retornar uma data vazia (ctod("")) .
Exemplo: // Mostra a data da ltima modificao da tabela corrente, dModificacao := LUpdate() IF (EMPTY(dModificacao)) CONOUT("No h tabela corrente") ELSE CONOUT(("Data da ultima modificacao : " + DTOS(dModificacao))) ENDIF
MSAPPEND() A funo MsAppend() adiciona registros de um arquivo para outro, respeitando a estrutura das tabelas. Sintaxe: MSAPPEND( [cArqDest], cArqOrig ) Parmetros: 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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
110
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Lgico
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
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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
111
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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.
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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
112
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: RecLock(cAlias,lInclui) Parmetros Alias que identifica a rea de trabalho que ser manipulada. Define se a operao ser uma incluso (.T.) ou uma alterao (.F.)
cAlias lInclui
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()
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() 113
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
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: Nome da rea de trabalho a ser verificada.
cAlias Retorno:
Numrico
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
114
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
SET FILTER TO O comando SET FILTER TO define uma condio de filtro que ser aplicada a rea de trabalho ativa.
Recomenda-se o uso da funo DbSetFilter() em substituio ao comando SET FILTER TO Sintaxe: SET FILTER TO cCondicao Parmetros: Expresso que ser avaliada pela SET FILTER, definindo os registros que ficaro disponveis na rea de trabalho ativa. Esta expresso obrigatoriamente deve ter um retorno lgico.
cCondicao
Retorno: .
Nenhum
Exemplo: USE Employee INDEX Name NEW SET FILTER TO Age > 50 LIST LastName, FirstName, Age, Phone SET FILTER TO
SOFTLOCK() Permite a reserva do registro posicionado na rea de trabalho ativa de forma que outras operaes, com exceo da atual, no possam atualizar este registro. Difere da funo RecLock() pois no gera uma obrigao de atualizao, e pode ser sucedido por ele. Na aplicao ERP Protheus, o SoftLock() utilizado nos browses, antes da confirmao da operao de alterao e excluso, pois neste momento a mesma ainda no foi efetivada, mas outras conexes no podem acessar aquele registro pois o mesmo est em manuteno, o que implementa da integridade da informao. Sintaxe: SoftLock(cAlias) Parmetros 115
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cAlias
Alias de referncia da rea de trabalho ativa, para o qual o registro posicionado ser travado.
Exemplo: cChave := GetCliente() // Funo ilustrativa que retorna os dados de busca de um cliente DbSelectArea(SA1) DbSetOrder(1) DbSeek(cChave) IF Found() SoftLock() // Reserva o registro localizado lConfirma := AlteraSA1() // Funo ilustrativa que exibe os dados do registro // posicionado e pemite a alterao dos mesmos. IF lConfirma RecLock(SA1,.F.) GravaSA1() // Funo ilustrativa que altera os dados conforme a AlertaSA1() MsUnLock() // Liberado o RecLock() e o SoftLock() do registro. Endif Endif
USED() A funo USED() utilizada para determinar se h um arquivo de banco de dados em uso em uma rea de trabalho especfica. O padro que USED() opere na rea de trabalho correntemente selecionada. Sintaxe: USED() Parmetros: .
Nenhum Retorno:
Lgico
Verdadeiro (.T.) caso haja um arquivo de banco de dados em uso; caso contrrio, retorna falso (.F.).
Exemplo:
USE Customer NEW CONOUT(USED()) // Resulta: .T. CLOSE CONOUT (USED()) // Resulta: .F.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Alias de referncia da tabela para a qual ser efetuado o controle da numerao seqencial. Nome do campo no qual est implementado o controle da numerao. Parmetro opcional, quando o nome do alias nos arquivos de controle de numerao no o nome convencional do alias para o sistema ERP. Nmero do ndice para verificar qual a prxima ocorrncia do nmero.
CONFIRMSXE() Confirma o nmero alocado atravs do ltimo comando GETSXENUM(). Sintaxe: CONFIRMSXE(lVerifica) Parmetros
lVerifica
Verifica se o nmero confirmado no foi alterado, e por conseqncia j existe na base de dados.
ROLLBACKSXE() Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao disponvel para outras conexes. Sintaxe: ROLLBACKSXE() Parmetros .
Nenhum
Validao
ALLWAYSFALSE() A funo AllwaysFalse() foi criada com o objetivo de compatibilidade, sendo que sempre ir retornar um valor lgico falso, facilitando a especificao desta situao nas parametrizaes de validaes de modelos de interface pr-definidos no sistema. Sintaxe: ALLWAYSFALSE() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
117
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
Lgico
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
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 Alias de referncia para a validao da informao. Chave a ser pesquisada, sem a filial. ndice de busca para consulta da chave.
EXISTCPO() Retorna .T. ou .F. se o contedo especificado no existe no alias especificado. Caso no exista ser exibido um help de sistema com um aviso informando da ocorrncia. Funo utilizada normalmente para verificar se a informao digitada em um campo, a qual depende de outra tabela, realmente existe nesta outra tabela, como por exemplo o cdigo de um cliente em um pedido de venda. Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
118
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros
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: String que ter seu contedo avaliado.
cString Retorno:
Lgico
Indica que se a string avaliada contm apenas letras e nmero, ou seja, alfanumrico.
NAOVAZIO() Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio. Sintaxe: NaoVazio() Parmetros .
Nenhum
NEGATIVO() Retorna .T. ou .F. se o contedo digitado para o campo negativo. Sintaxe: Negativo() Parmetros .
Nenhum
PERTENCE() Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida como parmetro da funo. Normalmente utilizada em campos com a opo de combo, pois caso contrrio seria utilizada a funo ExistCpo(). 119
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cString
String contendo as informaes vlidas que podem ser digitadas para um campo.
POSITIVO() Retorna .T. ou .F. se o contedo digitado para o campo positivo. Sintaxe: Positivo() Parmetros .
Nenhum
TEXTO() Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou alfanumricos. Sintaxe: Texto() Parmetros .
Nenhum
VAZIO() Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio. Sintaxe: Vazio() Parmetros .
Nenhum
120
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
cParametro
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 corrente da conexo. filial
cPadrao
cFilial
PUTMV() Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as parametrizaes informadas. Sintaxe: PUTMV(cParametro, cConteudo) Parmetros Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema. Contedo que ser atribudo ao parmetro no SX6.
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. 121
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cParametro
lHelp
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 corrente da conexo. filial
cPadrao
cFilial
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: Tamanho do relatrio em colunas, podendo assumir os valores 80,132 ou 220 colunas, respectivamente para os formatos P, M ou G de impresso.
nLimite
Retorno: String com caracteres de controle, dependente das configuraes escolhidas pelo usurio e do arquivo de driver especificado.
Caracter
Exemplo: /*/ +----------------------------------------------------------------------------| Funo | XAVALIMP | Autor | | Data | 01.01.2007 | +----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo AXCADASTRO() | |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/ USER FUNCTION XAVALIMP()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
122
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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) 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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
123
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: Cabec(cTitulo, cCabec1, cCabec2, cNomeProg, nTamanho, nCompress, aCustomText, lPerg, cLogo) Parmetros: 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): Redefine o bitmap que ser impresso no relatrio, no necessitando que ele esteja no formato padro da Microsiga: "LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"
cLogo
Retorno: .
Nenhum
Exemplo: #INCLUDE "protheus.ch" /*/ +----------------------------------------------------------------------------| Funo | MPTR001 | Autor | | Data | 01.01.2007 | +----------------------------------------------------------------------------| Descrio | Exemplo de utilizao das funes de impresso CABEC() | |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/ User Function MPTR001() Local Local Local Local Local cDesc1 cDesc2 cDesc3 cTitulo lImprime := := := := := "Este programa tem como objetivo imprimir relatorio " "de acordo com os parametros informados pelo usuario." "Listagem de clientes" "Listagem de clientes" .T.
// Parametros da SetPrint() Local cString := "SA1" Local cPerg := "" Local lDic := .T. // Habilita a visalizacao do dicionario
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
124
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
:= := := := := := :=
RetSixOrd(cString) .T. // .F. - Normal / .T. - Comprimido .T. // Habilita o filtro para o usuario "MPTR002" "M" 18 132
Default lCriaTrab := .T. Private lEnd := .F. Private lAbortPrint := .F. Private aReturn := { "Zebrado", 1, "Administracao", 2, 2, 1, "", 1} //aReturn[4] 1- Retrato, 2- Paisagem //aReturn[5] 1- Em Disco, 2- Via Spool, 3- Direto na Porta, 4- Email Private nLastKey Private m_pag Private wnrel := 0 := 01 := "MPTR002"
dbSelectArea("SA1") dbSetOrder(1)
Exemplo (continuao): // // Monta a interface padrao com o usuario... // wnrel := SetPrint(cString,cNomeProg,cPerg,@cTitulo,cDesc1,cDesc2,cDesc3,lDic,aOrd,lCompre s,cTamanho,,lFilter) If nLastKey == 27 Return Endif SetDefault(aReturn,cString,,,cTamanho,aReturn[4]) // nFormato: 1- Retrato, 2Paisagem If nLastKey == 27 Return Endif nTipo := IIF(aReturn[4]==1,15,18) // // Processamento. RPTSTATUS monta janela com a regua de processamento. // RptStatus({|| RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)},cTitulo) Return /*/ +----------------------------------------------------------------------------| Funo | RUNREPORT | Autor | -------------------- | Data | 01.01.2007 | +----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001() | |+---------------------------------------------------------------------------Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
125
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/ Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite) Local Local Local Local nLin cCabec1 cCabec2 cArqInd := += += := := 80 := "" := ""
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: 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
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
126
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cAlias Retorno:
M- 132 colunas G- 220 colunas Alias do arquivo de cadastro que ser impresso
Nenhum
MS_FLUSH() A funo MS_FLUSH() envia o spool de impresso para o dispositivo previamente especificado com a utilizao das funes AVALIMP() ou SETPRINT(). Sintaxe: MS_FLUSH() Parmetros: .
Nenhum Retorno:
Nenhum
Exemplo: /*/ +----------------------------------------------------------------------------| Funo | RUNREPORT | Autor | | Data | 01.01.2007 | +----------------------------------------------------------------------------| Descrio | Funo interna de processamento utilizada pela MPTR001() | |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------| Observao| Continuao do exemplo da funo CABEC() | |+---------------------------------------------------------------------------/*/ Static Function RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite) Local Local Local Local nLin cCabec1 cCabec2 cArqInd := += += := := 80 := "" := ""
127
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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++ 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) 128
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cArquivo . Retorno:
Exemplo: If aReturn[5]==1 // Indica impresso em disco. dbCommitAll() SET PRINTER TO OurSpool(wnrel) Endif
RODA() A funo RODA() imprime o rodap da pgina do relatrio, o que pode ser feito a cada pgina, ou somente ao final da impresso.
Pode ser utilizado o ponto de entrada "RodaEsp" para tratamento de uma impresso especfica. Sintaxe: Roda(uPar01, uPar02, cSize) Parmetros: No mais utilizado No mais utilizado Tamanho do relatrio (P,M,G)
Nenhum
Exemplo: /*/ +----------------------------------------------------------------------------| Funo | TESTIMPR | Autor | | Data | 01.01.2007 | +----------------------------------------------------------------------------| Descrio | Exemplo de utilizao da funo RODA() em conjunto com a CABEC.| |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
129
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
#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 Exemplo (continuao): /*/ +----------------------------------------------------------------------------| Funo | TESTREL | Autor | | Data | | +----------------------------------------------------------------------------| Descrio | Funo interna de impresso da TestImpr(). | |+---------------------------------------------------------------------------| Uso | Curso ADVPL | |+---------------------------------------------------------------------------/*/ User Function TestRel(lEnd,WnRel,cString,Tamanho,NomeProg) LOCAL LOCAL Local Local cabec1,cabec2 cRodaTxt := oemtoansi("Rodap") nCntImpr nTipo
nCntImpr := 0 li := 80 m_pag := 1 nTipo := 15 titulo:= oemtoansi("Lista de Clientes") cabec1:= oemtoansi("COD LOJA NOME"+Space(27)+ "NOME FANTASIA") cabec2:="" dbSelectArea("SA1") dbGoTop() SetRegua(LastRec()) While !Eof() IncRegua() If Li > 60 cabec(titulo,cabec1,cabec2,nomeprog,tamanho,15) @ Li,0 PSAY __PrtThinLine() Endif nCntImpr++ Li++ @ Li,01 PSAY A1_COD @ Li,05 PSAY A1_LOJA @ Li,10 PSAY A1_NOME
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
130
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
@ Li,51 PSAY A1_NREDUZ If Li > 60 Li:=66 Endif dbSkip() EndDO If li != 80 Roda(nCntImpr,cRodaTxt,Tamanho) EndIf Set Device to Screen If aReturn[5] = 1 Set Printer To dbCommitAll() OurSpool(wnrel) Endif MS_FLUSH() Return
SETDEFAULT() A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes configuradas no array aReturn, obtidas atravs da funo SetPrint(). Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] , [cSize] , [ nFormat ] ) Parmetros: 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.
Nenhum
Estrutura aReturn: Caracter, tipo do formulrio Numrico, opo de margem Caracter, destinatrio Numrico, formato da impresso Numrico, dispositivo de impresso Caracter, driver do dispositivo de impresso 131
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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().
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
132
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Linha na qual dever ser posicionado o dispositivo de impresso. Coluna na qual dever ser posicionado o dispositivo de impresso.
Nenhum
Exemplo: aReturn := { "", 1, "" , 2, 3, cPorta , "",IndexOrd() } SetPrint(Alias(),"","","",,,,.F.,,,,,,,'EPSON.DRV',.T.,,cPorta) if nLastKey == 27 Return (.F.) Endif SetDefault(aReturn,Alias()) SetPrc(0,0)
SETPRINT() A funo SetPrint() cria uma interface padro onde as opes de impresso de um relatrio podem ser configuradas. Basicamente duas variveis m_pag e aReturn precisam ser declaradas como privadas (private) antes de executar a SetPrint(), sendo que: m_pag: controla o nmero de pginas. aReturn: vetor contendo as opes de impresso, sendo sua estrutura bsica composta de 8 (oito) elementos.
Aps confirmada, os dados so armazenados no vetor aReturn que ser passado como parmetro para funo SetDefault(). Sintaxe: SetPrint ( < cAlias > , < cProgram > , [ cPergunte ] , [ cTitle ] , [ cDesc1 ] , [ cDesc2 ] , [ cDesc3 ] , [ lDic ] , [ aOrd ] , [ lCompres ] , [ cSize ] , [ uParm12 ] , [ lFilter ] , [ lCrystal ] , [ cNameDrv ] , [ uParm16 ] , [ lServer ] , [ cPortPrint ] ) --> cReturn Parmetros: Alias do arquivo a ser impresso. Nome do arquivo a ser gerado em disco. Grupo de perguntas cadastrado no dicionrio SX1.
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
133
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cTitle
Ttulo do relatrio.
Parmetros (continuao): 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.
cDesc1 cDesc2 cDesc3 lDic aOrd lCompres cSize uParm12 lFilter lCrystal cNameDrv uParm16 lServer cPortPrint Retorno:
Caracter
Nome do Relatrio
Estrutura aReturn: 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().
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
134
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Alias do arquivo que ser re-aberto em modo exclusivo.
cAlias Retorno:
Lgico
CLOSEOPEN() A funo CLOSEOPEN() utilizada para fechar e re-abrir uma lista de arquivos especificada. Sintaxe: CLOSEOPEN(aClose, aOpen) Parmetros: Array contendo os Aliases dos arquivos que devero ser fechados. Array contendo os Aliases dos arquivos que devero ser abertos.
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: String contendo os nomes dos demais Aliases que no devero ser fechados, separando os itens com /.
cAlias
Retorno:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
135
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Lgico
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: 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.
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
CONOUT()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
136
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
A funo CONOUT() permite a exibio de uma mensagem de texto no console do Server do Protheus. Caso o Protheus esteja configurado como servio a mensagem ser gravada no arquivo de log. Sintaxe: CONOUT(cMensagem) Parmetros: String contendo a mensagem que dever ser exibida no console do Protheus.
cMensagem
Retorno: .
Nenhum
CRIAVAR() A funo CRIAVAR() cria uma varivel, retornando o valor do campo, de acordo com o dicionrio de dados, inclusive avaliando o inicializador padro, permitindo um retorno de acordo com o tipo de dado definido no dicionrio. Sintaxe: CriaVar(cCampo,lIniPad,cLado) Parmetros: 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: Tipo de dado de acordo com o dicionrio de dados, considerando inicializador padro
Indefinido
Exemplo: // Exemplo do uso da funo CriaVar: cNumNota := CriaVar(F2_DOC) // Retorna o contedo do // inicializador padro, // se existir, ou espaos em branco Alert(cNumNota) Return
DISARMTRANSACTION() A funo DISARMTRANSATCION() utilizada para realizar um RollBack de uma transao aberta com o comando BEGIN TRANSACTION e delimitada com o comando END TRANSACTION.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
137
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
Nenhum Retorno:
Nenhum
Exemplo: lMsErroAuto := .F. MSExecAuto({|x,y| MATA240(x,y)}, aCampos, 3) If lMsErroAuto aAutoErro := GETAUTOGRLOG() DisarmTransaction() MostraErro() EndIf
EXECBLOCK() A funo EXECBLOCK() executa uma funo de usurio que esteja compilada no repositrio. Esta funo normalmente utilizada pelas rotinas padres da aplicao Protheus para executar pontos de entrada durante seu processamento. A funo de usurio executada atravs da EXECBLOCK() no recebe parmetros diretamente, sendo que estes estaro disponveis em uma varivel private denominada PARAMIXB.
A varivel PARAMIXB o reflexo do parmetro xParam, definido na execuo da funo EXECBLOCK(). Caso seja necessria a passagem de vrias informaes, as mesmas devero ser definidas na forma de um array, tornando PARAMIXB um array tambm, a ser tratado na funo de usurio que ser executada.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
138
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Nome da funo que ser avaliada.
cFuno Retorno:
Lgico
Exemplo: IF EXISTBLOCK(MT100GRV) EXECBLOCK(MT100GRV,.F.,.F.,aParam) ENDIF Sintaxe: EXECBLOCK(cFuno, lReserv1, lReserv2, xParam) Parmetros: 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.
Indefinido
Exemplo: aParam := {cNota, cSerie, cFornece, cLoja) IF EXISTBLOCK(MT100GRV) lGravou := EXECBLOCK(MT100GRV,.F.,.F.,aParam) ENDIF USER FUNCTION MT100GRV()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
139
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
RETURN .T.
ERRORBLOCK() A funo ERRORBLOCK() efetua o tratamento de erros e define a atuao de um handler de erros sempre que ocorrer um erro em tempo de execuao. O manipulador de erros especificado como um bloco de cdigo da seguinte forma: { |<objError>| <lista de expressoes>, ... }, onde:
<objError> um error object que contm informaoes sobre o erro.Dentro do bloco de cdigo, podem ser enviadas mensagens ao error object para obter informaoes sobre o erro. Se o bloco de tratamento de erros retornar verdadeiro (.T.), a operaao que falhou repetida, e se retornar falso (.F.), o processamento recomea. Se nao foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer um erro em tempo de execuao, o bloco de tratamento ao de erros padrao avaliado. Este manipulador de erros exibe uma mensagem descritiva na tela, ajusta a funao ERRORLEVEL() para 1, e depois sai do programa (QUIT). Como ERRORBLOCK() retorna o bloco de tratamento ao de erros corrente, possvel especificar um bloco de tratamento de erros para uma operaao gravando-se o bloco de manipulaao de erros corrente e depois recuperando-o aps o final da operaao. Alm disso, uma importante consequncia do fato de os blocos de tratamento de erros serem especificados como blocos de cdigo, que eles podem ser passados pararotinas e funoes definidas por usurio e depois retornadas como valores. Sintaxe: ERRORBLOCK ( < bErrorHandler > ) Parmetros: 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.
bErrorHandler
Retorno: 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.
Code-block
Exemplo: Function CA010Form() LOCAL xResult LOCAL cForm:= Upper(&(ReadVar())) LOCAL bBlock:= ErrorBlock( { |e| ChecErro(e) } )
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
140
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
LOCAL cOutMod Local lOptimize := GetNewPar("MV_OPTNFE",.F.) .Or. GetNewPar("MV_OPTNFS",.F.) PRIVATE lRet:=.T. cVarOutMod := If(Type("cVarOutMod") = "U", "", cVarOutMod) cOutMod := cVarOutMod + If(Right(cVarOutMod, 1) = ",", "", ",") While ! Empty(cOutMod) If Left(cOutMod, At(",", cOutMod) - 1) $ Upper(cForm) // no modulo Help( " ",1,"ERR_FORM,,"Variavel nao disponivel para este modulo" Return .F. Endif cOutMod := Subs(cOutMod, At(",", cOutMod) + 1) EndDo If ("LERSTR"$cForm .or. "LERVAL"$cForm .or. "LERDATA"$cForm) .And. M->I5_CODIGO > "499" Help( " ",1,"CA010TXT") ErrorBlock(bBlock) Return .F. Endif BEGIN SEQUENCE If !"EXECBLOCK"$cForm .and. !"LERSTR"$cForm .And.; // nao executa execblock !"LERVAL"$cForm .And.; // nem funcao de leitura !"LERDATA"$cForm .And.; // de texto no cadastramento IIf(!lOptimize,.T.,!"CTBANFS"$cForm .And. !"CTBANFE"$cForm) xResult := &cForm Endif END SEQUENCE ErrorBlock(bBlock) Return lRet
FINAL() A funo FINAL() executa as operaes bsicas que garantem a integridade dos dados ao finalizar o sistema desmontando as transaes (se houver), desbloqueando os semforos e fechando as tabelas abertas, finalizando-o em seguinda. Sintaxe: Final( [cMensagem1], [cMensagem2] ) Parmetros: Primeira mensagem Segunda mensagem
Nenhum
141
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Nome da funo que ser avaliada no repositrio de objetos corrente.
cFuno Retorno:
Lgico
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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
142
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
Caracter
GETAREA() Funo utilizada para proteger o ambiente ativo no momento de algum processamento especfico. Para salvar uma outra rea de trabalho (alias) que no o ativo, a funo GetArea() deve ser executada dentro do alias: ALIAS->(GetArea()). Sintaxe: GETAREA() Retorno: Array contendo {Alias(),IndexOrd(),Recno()} Parmetros .
Nenhum
GETCOUNTRYLIST() A funo GETCOUNTRYLIST() retorna um array de duas dimenses contendo informaes dos pases localizados. Sintaxe: GetCountryList() Parmetros: .
Nenhum Retorno:
Array Array de duas dimenses, sendo uma linha para cada pas localizado, contendo em cada posio a sigla dos pases, o nome do pas e a identificao do pas com dois dgitos.
Exemplo: Local aArray := GetCountryList() Local cSigla := GetMv( MV_PAISLOC ) Local nPos nPos := Ascan( aArray, {|d| d[1] == Upper(cSigla) } ) If nPos > 0 APMsgInfo( Pas de localizao + aArray[nPos,2] ) EndIf
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
143
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
ISINCALLSTACK() A funo ISINCALLSTACK() verifica se uma determinada funo est existe dentro da pilha de chamadas do processamento corrente. Sintaxe: IsInCallStack( cIsInCallStack , cStackExit ) Parmetros: 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".
cIsInCallStack cStackExit
Retorno: Indica se a funo especificada encontrasse na pilha de chamadas do processsamento corrente, at o ponto de sada especificado.
Lgico
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: 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.
cAlias lInclui
Retorno: .
Nenhum
RESTAREA() Funo utilizada para devolver a situao do ambiente salva atravs do comando GETAREA(). Deve-se observar que a ltima rea restaurada a rea que ficar ativa para a aplicao. Sintaxe: RESTAREA(aArea) Parmetros Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo uso da funo GetArea().
aArea
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
144
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
User Function XATF001() LOCAL cVar LOCAL aArea := GetArea() LOCAL lRet := .T. cVar := &(ReadVar()) dbSelectArea("SX5") IF !dbSeek(xFilial()+"Z1"+cVar) cSTR0001 := "REAV - Tipo de Reavaliacao" cSTR0002 := "Informe um tipo de reavalicao valido" cSTR0003 := "Continuar" Aviso(cSTR0001,cSTR0002,{cSTR0003},2) lRet := .F. ENDIF RestArea(aArea) Return( lRet )
USEREXCEPTION() A funo USEREXCEPTION() tem o objetivo de forar um erro em ADVPL de forma que possamos tratar de alguma forma. USEREXCEPTION() recebe uma string contendo uma descrio do erro, essa descrio ser exibida de acordo com o ambiente que se est executando, caso um ambiente ERP, ser exibida uma tela de erro. Sintaxe: USEREXCEPTION(cMensagem) Parmetros: Mensagem que ser exibida no cabealho do erro, contendo a explicao da exceo.
cMensagem
Retorno: .
Nenhum
145
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Grupo de perguntas do SX1 (X1_GRUPO) Array contendo a estrutura dos campos que sero gravados no SX1.
Nenhum
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
Estrutura Item do array aPerg (continuao): 23 24 25 26 27 28 X1_DEFSPA3 X1_DEFENG3 X1_CNT03 X1_VAR04 X1_DEF04 X1_DEFSPA4 Caractere Caractere Caractere Caractere Caractere Caractere Descrio da opo Descrio da opo No informado No informado Descrio da opo portugus Descrio da opo X do combo em espanhol X do combo em ingls
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
146
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
29 30 31 32 33 34 35 36 37
38 39 40 41
42
aHelpEng
Array
43
aHelpSpa
Array
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.
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] aArray[x][2] aArray[x][3] Configuraes gerais de acesso Configuraes de impresso Condiguraes de acesso aos mdulos
Array de informaes dos usurios: Configuraes gerais de acesso Elemento Descrio Tipo Qtd. 147
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
1 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 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 C C C C A D N L L A C C C C N D L N L C 6 15 6 30 -8 4 1 1 -6 30 30 130 4 8 1 1 1 4
Array de informaes dos usurios: Configuraes de impresso Elemento 2 1 2 3 4 5 6 7 8 9 10 11 12 13 Vetor com horrios de acesso Idioma Diretrio Impressora Acessos Vetor com empresas Ponto de entrada Tipo de impresso Formato Ambiente Prioridade p/ config. do grupo Opo de impresso Acesso a outros dir de impresso A N C C C A C N N N L C L -1 100 -512 -10 1 1 1 1 50 1 Descrio Tipo Qtd.
Descrio
Tipo
Qtd. 148
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Mdulo+nvel+menu
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] aArray[x][2] Configuraes gerais de acesso 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 ID Nome Vetor com horrios de acesso Data de validade Quantas vezes para expirar Autorizado a alterar a senha Idioma Diretrio Impressora Acessos Vetor com empresas Data da ltima alterao Tipo de impresso Formato Ambiente Opo de impresso Acesso a outros Dir de impresso C C A D N L N C C C A D N N N L L 8 1 1 1 1 1 512 8 4 1 1 100 6 20 Descrio Tipo Qtd.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
149
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Elemento 2 1
Descrio Modulo+nvel+menu
Tipo C
Qtd.
CGC() A funo CGC() valida o CGC digitado, utilizando o algoritmo nacional para verificao do dgito de controle. Sintaxe: CGC(cCGC) Parmetros: String contendo o CGC a ser validado
cCGC Retorno:
Lgico
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: 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. ,
Nenhum
DATAVALIDA() A funo DATAVALIDA() retorna a primeira data vlida a partir de uma data especificada como referncia, considerando inclusive a data informada para anlise. 150
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: DATAVALIDA(dData) Parmetros: Data a partir da qual ser avaliada a prxima data vlida, considerando-a inclusive como uma possibilidade.
dData
Retorno: Prxima data vlida, desconsiderando sbados, domingos e os feriados cadastrados no sistema.
Data
EXISTINI() A funo EXISTINI() verifica se o campo possui inicializador padro. Sintaxe: EXISTINI(cCampo) Parmetros: Nome do campo para verificao.
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
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: 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. 151
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Cdigo da frmula a ser avaliada e cadastrada no SM4 Cadastro de Frmulas.
cFormula
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: 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
Indefinido
A funo GETADVFVAL() difere da funo POSICIONE() apenas por permitir o retorno de vrios campos em uma nica consulta. As duas funes devem ser protegidas por GETAREA() / RESTAREA() dependendo da aplicao. 152
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: 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)
Nenhum
A funo HELP() tratada na execuo das rotinas com o recurso de MSEXECAUTO(), permitindo a captura e exibio da mensagem no log de processamento. Por esta razo, em rotinas que podem ser chamadas atravs da funo MSEXECAUTO() deve-se sempre utilizar avisos utilizando esta funo, para que este tipo de processamento no seja travado indevidamente.
Exemplo: IF lAuto // Se for rotina automtica Help("ESPECIFICO",1,"HELP","PROCESSAMENTO","Parmetros do JOB Invlidos",1,0) ELSE MsgAlert(Parmetros do JOB Invlidos, PROCESSAMENTO) ENDIF
MESEXTENSO() A funo MESEXTENSO() retorna o nome de um ms por extenso. Sintaxe: MESEXTENSO(nMes) Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
153
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nMes
Este parmetro pode ser definido tambm como caracter ou como data.
String
OBRIGATORIO() A funo OBRIGATORIO() avalia se todos os campos obrigatrios de uma Enchoice() foram digitados. Sintaxe: OBRIGATORIO(aGets, aTela, aTitulos) Parmetros: 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().
Lgico
Exemplo: #INCLUDE "protheus.ch" /*/ +----------------------------------------------------------------------------| Programa | ATFA010A | Autor | | Data | | +----------------------------------------------------------------------------| Desc. | Cadastro de dados complementares do bem Ativo Fixo | +---------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ User Function ATFA010A() Private cCadastro := "Atualizacao de dados do bem" Private aRotina := { {"Pesquisar" ,"AxPesqui" {"Visualizar" ,"AxVisual" {"Atualizar" ,"U_A010AATU" ,0,1} ,; ,0,2} ,; ,0,4}}
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
154
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Private cDelFunc := ".T." Private cString := "SN1" dbSelectArea("SN1") dbSetOrder(1) dbSelectArea(cString) mBrowse( 6,1,22,75,cString) Return /*/ +----------------------------------------------------------------------------| Programa | A010AATU | Autor | | Data | | +----------------------------------------------------------------------------| Desc. | Atualizao de dados do bem Ativo Fixo | +----------------------------------------------------------------------------| 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.
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()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
155
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 Exemplo (continuao):
/*/ +----------------------------------------------------------------------------| Programa | A010AGRV | Autor | | Data | | +----------------------------------------------------------------------------| Desc. | Validao da enchoice e gravao dos dados do bem | +----------------------------------------------------------------------------| Uso | Curso de ADVPL | +----------------------------------------------------------------------------/*/ Static Function A010AGRV(aCpos,aAlter,nOpc) Local aArea Local nX := GetArea() := 0
156
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Empresa cujo os arquivos sero re-abertos.
cEmp Retorno:
Nenhum
PERGUNTE() A funo PERGUNTE() inicializa as variveis de pergunta (mv_par01,...) baseada na pergunta cadastrado no Dicionrio de Dados (SX1). Se o parmetro lAsk no for especificado ou for verdadeiro ser exibida a tela para edio da pergunta e se o usurio cofirmar as variveis sero atualizadas e a pergunta no SX1 tambm ser atualizada. Sintaxe: Pergunte( cPergunta , [lAsk] , [cTitle] ) Parmetros: Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada. Indica se exibir a tela para edio. Ttulo do dilogo.
Lgico
Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou cancelada (.F.)
PESQPICT()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
157
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
A funo PESQPICT() retorna a picture definida para um campo especificado no Dicionrio de Dados (SX3). Sintaxe: PesqPict(cAlias,cCampo,nTam) Parmetros: 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.
String
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: Nome do campo a verificar a picture. Espao disponvel para edio.
String
Picture ideal para o espao definido por nEdio, sem a separao dos milhares por vrgula.
POSICIONE() A funo POSICIONE() permite o retorno do contedo de um campo de um registro de uma tabela especificado atravs de uma chave de busca. Sintaxe: Posicione(cAlias, nOrdem, cChave, cCampo) Parmetros: Alias do arquivo Ordem utilizada Chave pesquisa
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
158
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cCampo Retorno:
Indefinido
A utilizao da funo POSICIONE() deve ser protegida com GETAREA() / RESTAREA() dependendo da aplicao.
PUTSX1() A funo PUTSX1() permite a incluso de um nico item de pergunta em um grupo de definido no Dicionrio de Dados (SX1). Todos os vetores contendo os textos explicativos da pergunta devem conter at 40 caracteres por linha. Sintaxe: PutSx1(cGrupo, cOrdem, cPergunt, cPerSpa, cPerEng, cVar, cTipo, nTamanho, nDecimal, nPresel, cGSC, cValid, cF3, cGrpSxg ,cPyme, cVar01, cDef01, cDefSpa1 , cDefEng1, cCnt01, cDef02, cDefSpa2, cDefEng2, cDef03, cDefSpa3, cDefEng3, cDef04, cDefSpa4, cDefEng4, cDef05, cDefSpa5, cDefEng5, aHelpPor, aHelpEng, aHelpSpa, cHelp) Parmetros: 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 159
cGrupo cOrdem cPergunt cPerSpa cPerEng cVar cTipo nTamanho nDecimal nPresel cGSC cValid cF3 cGrpSxg cPyme cVar01 cDef01 cDefSpa1
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
RETINDEX() A funo RETINDEX() Dados (SIX). restaura os ndices padres de um alias definidos no Dicionrio de
cAlias Retorno:
Numrico
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
160
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Exemplo: User Function <nome-da-funo>( cChave, cOrdem ) Local cSixDesc := dbSelectArea(SIX) dbSetOrder(1) If dbSeek(cChave+cOrdem) cSixDescr := SixDescricao() EndIf Return
TABELA() A funo TABELA() retorna o contedo de uma tabela cadastrada no Arquivo de Tabelas (SX5) de acordo com a chave especificada. Caso a tabela ou a chave especificada no existir ser exibido um HELP() padro do sistema. Sintaxe: Tabela(cTab,cChav,lPrint) Parmetros: 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: Contedo da tabela na chave especificada. Retorna nulo caso a tabela no exista ou a chave no seja encontrada.
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: Nome do campo a ser consultado no Dicionrio de Dados (SX3).
cCampo Retorno:
Array
Array de duas posies contendo o tamanho total e o nmero de decimais do campo especificado respectivamente.
TM()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
161
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
A funo TM() retorna a picture de impresso para valores numricos dependendo do espao disponvel. Sintaxe: TM(nValor, nEdio, nDec) Parmetros: Valor a ser avaliado. Espao disponvel para edio. Nmero de casas decimais.
String
Esta rotina leva em considerao duas variveis: MV_MILHAR Determina se deve haver separao de milhar; MV_CENT Nmero de casas decimais padro da moeda corrente. Para ajustar o valor passado (nValor) ao espao disponvel (nEdio) a funo verifica se pode haver separao de milhar, neste caso, a rotina eliminar tantos pontos decimais quantos sejam necessrios ao ajuste do tamanho. Caso no seja possvel ajustar o valor ao espao dado, ser colocado na picture o caracter de estouro de campo *.A funo tambm ajusta um valor ao nmero de decimais (nDec), sempre imprimindo a quantidade de decimais passados no parmetro.
X1DEF01() A funo X1DEF01() retorna o contedo da primeira definio da pergunta posicionada no SX1 (caso seja combo) no idioma corrente. Sintaxe: X1DEF01() Parmetros: .
Nenhum Retorno:
String
Exemplo: User Function <nome-da-funo>( cGrupo, cPerg ) Local cDef01 Local cDef02
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
162
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Local cDef03 Local cDef04 Local cDef05 dbSelectArea(SX1) dbSetOrder(1) If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg. cDef01 := X1Def01() cDef02 := X1Def02() cDef03 := X1Def03() cDef04 := X1Def04() cDef05 := X1Def05() EndIf Return
X1PERGUNT() A funo X1PERGUNT() retorna a descrio da pergunta posicionada no Dicionrio de Dados (SX1) para o idioma corrente. Sintaxe: X1PERGUNT() Parmetros: .
Nenhum Retorno:
String
Exemplo: User Function <nome-da-funo>( cGrupo, cPerg ) Local cDescr dbSelectArea(SX1) dbSetOrder(1) If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg. cDescr := X1Pergunt() EndIf Return
X2NOME() A funo X2NOME() retorna a descrio de uma tabela posicionada no Dicionrio de Dados (SX2) no idioma corrente. Sintaxe: X2NOME() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
163
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
String
Exemplo: User Function <nome-da-funo>( ) Local cTabela dbSelectArea(SX2) dbSetOrder(1) If dbSeek( SA1 ) cTabela := X2Nome() EndIf Return
X3CBOX() A funo X3CBOX() retorna o contedo de um campo tipo combo posicionado no Dicionrio de Dados (SX3) no idioma corrente. Sintaxe: X3CBOX() Parmetros: .
Nenhum Retorno:
String
Contedo do campo do tipo combo posicionado no Dicionrio de Dados (SX3) no idioma corrente.
Exemplo: 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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
164
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Return
X3DESCRIC() A funo X3DESCRIC() retorna a descrio de um campo posicionado no Dicionrio de Dados (SX3) no idioma corrente. Sintaxe: X3DESCRIC() Parmetros: .
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: Nome do campo contido no Dicionrio de Dados (SX3).
cCampo Retorno:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
165
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
String
Exemplo: User Function <nome-da-funo>( cCampo ) Local cPicture cPicture := X3Picture( cCampo ) Return cPicture
X3TITULO() A funo X3TITULO() retorna o ttulo de um campo posicionado no Dicionrio de Dados (SX3) no idioma corrente. Sintaxe: X3TITULO() Parmetros: .
Nenhum Retorno:
String
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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
166
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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: Indica se o campo est configurado como usado no Dicionrio de Dados (SX3).
Lgico 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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
167
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Return
X6CONTEUD() A funo X6CONTEUD() retorna o contedo de um parmetro posicionado no Dicionrio de Dados (SX6) para o idioma corrente. Sintaxe: X6CONTEUD() Parmetros: .
Nenhum Retorno:
Indefinido
Exemplo: User Function <nome-da-funo>( cFilial, cParam ) Local cDescr Local cConteud dbSelectArea(SX6) dbSetOrder(1) If dbSeek( cFilial+cParm ) cDescr := X6Descric() cDescr += X6Desc1() cDescr += X6Desc2() cConteud := X6Conteud() EndIf Return
X6DESCRIC() A funo X6DESCRI() retorna o contedo da descrio de um parmetro de acordo com o registro posicionado no Dicionrio de Dados (SX6) no idioma corrente. Sintaxe: X6DESCRIC() Parmetros:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
168
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Nenhum Retorno:
String
Para avaliar os contedos dos primeiro e segundo complementos da descrio do parmetro utilize as funes: X6DESC01() X6DESC02() retorna o primeiro complemento da descrio. retorna o segundo complemento da descrio.
Exemplo: User Function <nome-da-funo>( cFilial, cParam ) Local cDescr Local cConteud dbSelectArea(SX6) dbSetOrder(1) If dbSeek( cFilial+cParm ) cDescr := X6Descric() cDescr += X6Desc1() cDescr += X6Desc2() cConteud := X6Conteud() EndIf Return
XADESCRIC() A funo XADESCRI() retorna o contedo da descrio dos folders de acordo com o registro posicionado no Dicionrio de Dados (SXA) no idioma corrente. Sintaxe: XADESCRIC() Parmetros: .
Nenhum Retorno:
String
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
169
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
Exemplo: User Function <nome-da-funo>( cAlias ) Local cDescr dbSelectArea(SXB) dbSetOrder(1) If dbSeek( cAlias + 1 ) cDescr := XBDescri() EndIf Return
XFILIAL() A funo XFILIAL() retorna a filial utilizada por determinado arquivo. Esta funo utilizada para permitir que pesquisas e consultas em arquivos trabalhem somente com os dados da filial corrente, dependendo claro se o arquivo est compartilhado ou no (definio que feita atravs do mdulo Configurador Dicionrio de Dados (SX2)). importante verificar que esta funo no tem por objetivo retornar apenas a filial corrente, mas retorn-la caso o arquivo seja exclusivo. Se o arquivo estiver compartilhado, a funo xFilial retornar dois espaos em branco.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
170
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe: XFILIAL(cAlias) Parmetros: Alias do arquivo desejado. Se no for especificado, o arquivo tratado ser o da rea corrente.
cAlias
Caracter
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO nLiFim,nColFim OF oObjetoRef UNIDADE
Parmetros 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
Exemplo: DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL ACTIVATE MSDIALOG oDlg CENTERED
MSGET() Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis na tela da interface.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
171
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Sintaxe:
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture
Parmetros 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.
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";
SAY() Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de interface. Sintaxe:
Parmetros 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.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
172
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
UNIDADE oObjetoRef
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()
Parmetros 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()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
173
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros 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() 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:
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
174
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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())
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:
Parmetros: 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: 175
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
@ 40, 10 COMBOBOX oCombo VAR cCombo ITEMS aCombo SIZE 180,10 PIXEL OF oFld:aDialogs[2]
FOLDER() Define o componente visual Folder, o qual permite a incluso de diversos Dialogs dentro de uma mesma interface visual. Um Folder pode ser entendido como um array de Dialogs, aonde cada painel recebe seus componentes e tem seus atributos definidos independentemente dos demais. Sintaxe:
Parmetros 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
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
176
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nLinha,nColuna oRadio nRadio 3D nLargura,nAltura <ITEMS PROMPT> cItem1,cItem2,...,cItemX oObjetoRef UNIDADE CHANGE CLICK
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.
Exemplo: aAdd( aRadio, "Disco" ) aAdd( aRadio, "Impressora" ) aAdd( aRadio, "Scanner" ) @ 30, 10 RADIO oRadio VAR nRadio ITEMS aRadio[1],aRadio[2],aRadio[3] SIZE 65,8 ; PIXEL OF ; oFld:aDialogs[3] ; ON CHANGE ; (Iif(nRadio==1,MsgInfo("Opco 1",cAtencao),; Iif(nRadio==2,MsgInfo("Opo 2",cAtencao),MsgInfo("Opo 3",cAtencao))))
Interfaces de cadastro
AXCADASTRO() Sintaxe 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.
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
177
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
AXPESQUI() Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado na pesquisa e a digitao das informaes que compe a chave de busca. Sintaxe: AXPESQUI() Parmetros .
Nenhum
AXVISUAL() Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro(). Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,; aButtons, lMaximized ) Parmetros 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)
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br SP
178
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
Parmetros 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 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. )
cFunc aCpos
cTudoOk
lF3 cTransact
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
aButtons
aParam
aAuto
lVirtual lMaximized
AXALTERA() 179
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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().
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
180
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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 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
aButtons
aParam
aAuto
lMaximized
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
181
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
cTexto
AVISO() Sintaxe: AVISO(cTitulo, cTexto, aBotoes, nTamanho) Retorno: numrico indicando o boto selecionado. Parmetros Ttulo da janela Texto do aviso Array simples (vetor) com os botes de opo Tamanho (1,2 ou 3)
FORMBACTH() Sintaxe: FORMBATCH(cTitulo, aTexto, aBotoes, bValid, nAltura, nLargura ) Parmetros 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
SP
cTitulo aTexto
aBotoes
bValid
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
182
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
nAltura nLargura
MSGFUNCTIONS() Sintaxe: Sintaxe: Sintaxe: Sintaxe: MSGALERT(cTexto, cTitulo) MSGINFO(cTexto, cTitulo) MSGSTOP(cTexto, cTitulo) MSGYESNO(cTexto, cTitulo)
cTexto cTitulo
MSGALERT
MSGINFO
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
183
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
MSGSTOP
MSGYESNO
Indefinido GDFIELDPOS()
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
184
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
A funo GDFIELDPOS() retorna a posio de um campo especificado em uma gria formada por um objeto do tipo MsNewGetDados(). Sintaxe: GDFIELDPOS(cCampo) Parmetros: Nome do campo a ser avaliado na grid.
cCampo Retorno:
Numrico
Posio que o campo ocupada na grid. Caso o mesmo no exista ser retornado 0.
GDFIELDPUT() A funo GDFIELDPUT() atualiza o contedo de uma grid formada por um objeto do tipo MsNewGetDados() de acordo com o campo e linha da grid especificados. Sintaxe: GDFIELDPUT(cCampo, xConteudo, nLinha) Parmetros: Nome do campo a ser atualizado. Contedo que ser atribudo a clula da grid. Linha da grid que ser atualizada.
Nenhum
GETMARK() A funo GETMARK() utilizada em conjunto com a funo MarkBrow(), para retornar o conjunto de caracteres que sero utilizados para identificar os registros marcados pelo browse. Sintaxe: GETMARK( [lUpper] ) Parmetros: Se verdadeiro (.T.) retorna somente caracteres em maisculos.
lUpper Retorno:
String Conjunto de caracteres que definem a marca que dever ser utilizada pela MarkBrowse durante o processamento corrente.
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
185
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
altamente recomendvel limpar o contedo do campo marcado pela MarkBrowse() ao trmino do processamento, para se evitar problemas com a reutilizao da marca aps a exausto das possibilidades de combinao de dois caracteres, o qual o tamanho padro do campos utilizados para marcao de registros pela MarkBrowse(), que neste caso somam 1891 possibilidades de 00 a zz.
Exemplo: Function <nome-da-funo>( ) Local aCampos := {{'CB_OK' ,,''},; {'CB_USERLIB' ,,'Usurio'},; {'CB_TABHORA' ,,'Hora'},; {'CB_DTTAB' ,,'Data'}} Private cMarca := GetMark() Private cCadastro := 'Cadastro de Contrato' Private aRotina := { { 'Pesquisar' , 'AxPesqui' , 0, 1 }} MarkBrow( 'SCB', 'CB_OK','!CB_USERLIB',aCampos,, cMarca,'MarkAll()',,,,'Mark()' ) Return
MARKBREFRESH() A funo MARKBREFRESH() atualiza a exibio da marca no MarkBrowse(), sendo utilizada quando algum processamento paralelo atualiza o contedo do campo definido como controle de marca para os registros em exibio pelo browse. Este tipo de processamento comum, e normalmente est associonada a clique de inverter seleo, ou a opes de marcar e desmarcar todas. A MarkBrowse() atualiza automaticamente a exibio da marca de registros quando utilizado o browse. Sintaxe: MARKBREFRESH() Parmetros: .
Nenhum Retorno:
Nenhum
.
SP
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
186
ADVPL
GUIA DE REFERNCIA
Verso 1.0 06/2008 Todos direitos reservados Escola Parceira Certificao
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
Av. Leona rdo da Vinci, n 608 Metr Conceio - So Paulo Tel: 11 50114895 / 50116082 / 98081988 E m a i l / M S N : suporte@advpl.com.br - www.advpl.com.br
SP
187