ADVPL

ADVPL GUIA DE REFERNCIA Verso 1.0 06/2008 Todos direitos reservadosEscola conveniada

LADVPL

GUIA DE REFERNCIA

NDICE

8Converso entre tipos de dados

8CTOD()

8CVALTOCHAR()

8DTOC()

9DTOS()

9STOD()

10STR()

10STRZERO()

11VAL()

11Matemticas

11ACOS()

12CEILING()

12COS()

13LOG10()

13SIN()

13SQRT()

14TAN()

14Anlise de variveis

14TYPE()

15VALTYPE()

16Manipulao de arrays

16AADD()

17ACLONE()

17ACOPY()

18ADEL()

18ADIR()

19AFILL()

20AINS()

20ARRAY()

21ASCAN()

22ASCANX()

22ASIZE()

23ASORT()

24ATAIL()

25Manipulao de blocos de cdigo

25EVAL()

25DBEVAL()

26AEVAL()

27Manipulao de strings

27ALLTRIM()

28ASC()

28AT()

29BITON()

29CAPITAL()

30CHR()

30DESCEND()

31GETDTOVAL()

31ISALPHA()

31ISDIGIT()

32ISLOWER()

32ISUPPER()

33LEN()

33LOWER()

33LTRIM()

34MATHC()

34OEMTOANSI()

35PADL() / PADR() / PADC()

35RAT()

36REPLICATE()

36RTRIM()

36SPACE()

37STRTOKARR()

37STRTRAN()

38STUFF()

38SUBSTR()

39TRANSFORM()

39UPPER()

40Manipulao de data / hora

40CDOW()

40CMONTH()

41DATE()

41DAY()

42DOW()

42DTOC()

43DTOS()

43ELAPTIME()

44MONTH()

44SECONDS()

45TIME()

45YEAR()

46Manipulao de variveis numricas

46ABS()

46ALEATORIO()

47INT()

47NOROUND()

48RANDOMIZE()

48ROUND()

49Manipulao de arquivos

49ADIR()

49CGETFILE()

51Funo Principal: SELFILE()

52Funo auxiliar: PARBOXFILE()

53Funo auxiliar: MARKFILE()

54Funo auxiliar: TROCA()

54Funo auxiliar: MARCAOK()

55CPYS2T()

55CPYT2S()

56CURDIR()

57DIRECTORY()

58DIRREMOVE()

58DISKSPACE()

59EXISTDIR()

60FCLOSE()

61FCREATE()

61FERASE()

62FILE()

63FILENOEXT()

63FOPEN()

65FREAD()

65FREADSTR ()

66FRENAME()

66FSEEK()

67FT_FEOF()

67FT_FGOTO()

68FT_FGOTOP()

68FT_FLASTREC()

69FT_FREADLN()

69FT_FRECNO()

70FT_FSKIP()

70FT_FUSE()

70FWRITE()

73MSCOPYFILE()

73MSCOPYTO()

74MSCREATE()

75MSERASE()

75MSRENAME()

76RETFILENAME()

76Manipulao de arquivos e ndices temporrios

76CRIATRAB()

77Manipulao de bases de dados

77ALIAS()

78BOF() / EOF()

79COPY()

81COPY STRUCTURE()

82DBAPPEND()

82DBCLEARALLFILTER()

83DBCLEARFILTER()

83DBCLEARINDEX()

84DBCLOSEALL()

84DBCLOSEAREA()

85DBCOMMIT()

85DBCOMMITALL()

86DBCREATE()

87DBCREATEINDEX()

88DBDELETE()

89DBF()

89DBFIELDINFO()

90DBFILTER()

90DBGOTO()

91DBGOTOP()

91DBGOBOTTON()

92DBINFO()

93DBNICKINDEXKEY()

93DBORDERINFO()

94DBORDERNICKNAME()

94DBPACK()

95DBRECALL()

95DBRECORDINFO()

96DBREINDEX()

97DBRLOCK()

97DBRLOCKLIST()

98DBRUNLOCK()

98DBSETDRIVER()

99DBSETINDEX()

99DBSETNICKNAME()

100DBSELECTAREA()

101DBSETORDER()

101DBORDERNICKNAME()

101DBSEEK() E MSSEEK()

103DBSKIP()

103DBSETFILTER()

104DBSTRUCT()

105DBUNLOCK()

105DBUNLOCKALL()

105DBUSEAREA()

106DELETED()

107FCOUNT()

107FOUND()

108INDEXKEY()

108INDEXORD()

109LUPDATE()

109MSAPPEND()

109MSUNLOCK()

110ORDBAGEXT()

111ORDKEY()

111RECLOCK()

112RECNO()

113SELECT()

113SET FILTER TO

114SOFTLOCK()

115USED()

115Controle de numerao seqencial

115GETSXENUM()

116CONFIRMSXE()

116ROLLBACKSXE()

116Validao

116ALLWAYSFALSE()

116ALLWAYSTRUE()

117EXISTCHAV()

117EXISTCPO()

117LETTERORNUM()

118NAOVAZIO()

118NEGATIVO()

118PERTENCE()

118POSITIVO()

119TEXTO()

119VAZIO()

119Manipulao de parmetros do sistema

119GETMV()

119GETNEWPAR()

120PUTMV()

120SUPERGETMV()

121Controle de impresso

121AVALIMP()

122CABEC()

125IMPCADAST()

125MS_FLUSH()

127OURSPOOL()

128RODA()

130SETDEFAULT()

131SETPRC()

131SETPRINT()

133Controle de processamentos

133ABREEXCL()

133CLOSEOPEN()

133CLOSESFILE()

134CHKFILE()

134CONOUT()

135CRIAVAR()

135DISARMTRANSACTION()

136EXECBLOCK()

137EXISTBLOCK()

138ERRORBLOCK()

139FINAL()

140FINDFUNCTION()

140FUNDESC()

140FUNNAME()

141GETAREA()

141GETCOUNTRYLIST()

141ISINCALLSTACK()

142REGTOMEMORY()

142RESTAREA()

143USEREXCEPTION()

143Utilizao de recursos do ambiente ERP

143AJUSTASX1()

145ALLUSERS()

147ALLGROUPS()

148CGC()

148CONPAD1()

148DATAVALIDA()

149EXISTINI()

149EXTENSO()

150FORMULA()

150GETADVFVAL()

150HELP()

151MESEXTENSO()

152OBRIGATORIO()

155OPENFILE()

155PERGUNTE()

155PESQPICT()

156PESQPICTQT()

156POSICIONE()

157PUTSX1()

158RETINDEX()

158SIXDESCRICAO()

159TABELA()

159TAMSX3()

159TM()

160X1DEF01()

161X1PERGUNT()

161X2NOME()

162X3CBOX()

162X3DESCRIC()

163X3PICTURE()

164X3TITULO()

164X3USO()

165X5DESCRI()

165X6CONTEUD()

166X6DESCRIC()

167XADESCRIC()

168XBDESCRI()

168XFILIAL()

169Componentes da interface visual

169MSDIALOG()

169MSGET()

170SAY()

170BUTTON()

171SBUTTON()

172CHECKBOX()

173COMBOBOX()

173FOLDER()

174RADIO()

175Interfaces de cadastro

175AXCADASTRO()

175MBROWSE()

175AXPESQUI()

176AXVISUAL()

176AXINCLUI()

177AXALTERA()

178AXDELETA()

178Interfaces visuais para aplicaes

178ALERT()

179AVISO()

179FORMBACTH()

180MSGFUNCTIONS()

181Recursos das interfaces visuais

181GDFIELDGET()

181GDFIELDPOS()

182GDFIELDPUT()

182GETMARK()

183MARKBREFRESH()

184READVAR()

Converso entre tipos de dados

CTOD()

Realiza a converso de uma informao do tipo caracter no formato DD/MM/AAAA para uma varivel do tipo data.

Sintaxe: CTOD(cData) Parmetros

cDataCaracter no formato DD/MM/AAAA

Exemplo:

LOCAL cData := 31/12/2006

LOCAL dData := CTOD(cData)

IF dDataBase >= dData

MSGALERT(Data do sistema fora da competncia)

ELSE

MSGINFO(Data do sistema dentro da competncia)

ENDIF

CVALTOCHAR()

Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de espaos a informao.

Sintaxe: CVALTOCHAR(nValor) Parmetros

nValorValor numrico que ser convertido para caractere.

Exemplo:

FOR nPercorridos := 1 to 10

MSGINFO(Passos percorridos: +CVALTOCHAR(nPercorridos))

NEXT nPercorridos

DTOC()

Realiza a converso de uma informao do tipo data para em caracter, sendo o resultado no formato DD/MM/AAAA.

Sintaxe: DTOC(dData) Parmetros

dDataVarivel com contedo data

Exemplo:

MSGINFO(Database do sistema: +DTOC(dData))DTOS()

Realiza a converso de uma informao do tipo data em um caracter, sendo o resultado no formato AAAAMMDD.

Sintaxe: DTOS(dData) Parmetros

dDataVarivel com contedo data

Exemplo:

cQuery := SELECT A1_COD, A1_LOJA, A1_NREDUZ FROM SA1010 WHERE

cQuery += A1_DULTCOM >=+DTOS(dDataIni)+

STOD()

Realiza a converso de uma informao do tipo string com contedo no formato AAAAMMDD em data, no formato DD/MM/AAAA. Sintaxe: STOD(sData) Parmetros

sDataString no formato AAAAMMDD

Exemplo:

LOCAL sData := 20080601LOCAL dData := STOD(sData)MSGINFO(dData)

STR()

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

Sintaxe: STR(nValor) Parmetros

nValorValor numrico que ser convertido para caractere.

Exemplo:

LOCAL nPassos := 6MSGINFO(Passos percorridos: +STR(nPassos)

STRZERO()

Realiza a converso de uma informao do tipo numrico em uma string, adicionando zeros esquerda do nmero convertido, de forma que a string gerada tenha o tamanho especificado no parmetro. Sintaxe: STRZERO(nValor, nTamanho) Parmetros

nValorValor numrico que ser convertido para caractere.

nTamanhoTamanho total desejado para a string retornada.

Exemplo:

LOCAL nPassos := 6

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

VAL()

Realiza a converso de uma informao do tipo caracter em numrica. Sintaxe: VAL(cValor) Parmetros

cValorString que ser convertida para numrico.

Exemplo:

LOCAL cValor := 12345LOCAL nValor := VAL( cValor ) + 1MSGINFO( nValor )

Matemticas

ACOS()

Funo utilizada para calcular o valor do arco co-seno.

Sintaxe: ACOS(nValor) Parmetros:

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

Retorno:

NumricoRange de 0 a radianos.

Se o valor informado no parmetro for menor que1 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

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

Retorno:

NumricoValor do tipodouble, 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 doco-seno ou co-seno hiperblico.

Sintaxe: COS(nAngulo) Parmetros:

nAnguloValor que representa o ngulo em radianos.

Retorno:

NumricoValorque representa o co-seno ou co-seno hiperblicodo ngulo informado.

Situaes invlidas:

EntradaExceo apresentadaSignificado da Exceo

QNAN,INDNoneSem Domnio

(cosf, cos)INVALIDSem Domnio

x 7.104760e+002(cosh, coshf)INEXACT+OVERFLOWOVERFLOW

Importante: Se x >=2^63 ou x =2^63 ou x =2^63 ou x corresponde ao contedo de cVariavel1

// aItem[2] -> corresponde ao contedo de cVariavel2

// aItem[3] -> corresponde ao contedo de cVariavel3

AADD(aDados,aItem) // Adiciona no array aDados o contedo do array aItem

// Neste ponto, o array a aDados possui apenas um elemento, que tambm um array

// contendo 03 elementos:

// aDados [1][1] -> corresponde ao contedo de cVariavel1

// aDados [1][2] -> corresponde ao contedo de cVariavel2

// aDados [1][3] -> corresponde ao contedo de cVariavel3

AADD(aDados, aItem)

AADD(aDados, aItem)

// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros

// 03 elementos, sendo:

// aDados [1][1] -> corresponde ao contedo de cVariavel1

// aDados [1][2] -> corresponde ao contedo de cVariavel2

// aDados [1][3] -> corresponde ao contedo de cVariavel3

// aDados [2][1] -> corresponde ao contedo de cVariavel1

// aDados [2][2] -> corresponde ao contedo de cVariavel2

// aDados [2][3] -> corresponde ao contedo de cVariavel3

// aDados [3][1] -> corresponde ao contedo de cVariavel1

// aDados [3][2] -> corresponde ao contedo de cVariavel2

// aDados [3][3] -> corresponde ao contedo de cVariavel3

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

aArrayArray pr-existente que ter seu contedo copiado para o array especificado.

Exemplo:

Utilizando o array aDados utilizado no exemplo da funo AADD()

Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array

aDados

aItens := ACLONE(aDados)Por ser uma estrutura de memria, um array no pode ser simplesmente copiado para outro array atravs de uma atribuio simples (:=).

Para mais informaes sobre a necessidade de utilizar o comando ACLONE() verifique o tpico 6.1.3 Cpia de Arrays.

ACOPY()

Funo de array que copia elementos do array aOrigem para array aDestino. O array destino aDestino j deve ter sido declarado e grande o bastante para conter os elementos que sero copiados. Se o array aOrigem contiver mais elementos, alguns dos elementos no sero copiados. ACOPY() copia os valores de todos os dados, incluindo valores nulos (NIL) e cdigos de bloco.

Se um elemento for um subarray, o elemento correspondente no array aDestino, conter o mesmo subarray. Portanto, ACOPY() no produzir uma cpia completa de array multidimensionais.

Sintaxe: ACOPY( aOrigem, aDestino , [ nInicio ], [ nQtde ], [ nPosDestino ]) Parmetros:

aOrigem o array que contm os elementos a serem copiados.

aDestino o array que receber a cpia dos elementos.

nInicioindica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se no for especificado, o valor assumido ser 01.

nQtdeindica a quantidade de elementos a serem copiados a partir do array aOrigem. iniciando-se a contagem a partir da posio nInicio. Se nQtde no for especificado, todos os elementos do array aOrigem sero copiados, iniciando-se a partir da posio nInicio.

nPosDestino a posio do elemento inicial no array aDestino que receber os elementos de aOrigem. Se no especificado, ser assumido 01.

Retorno:

aDestinoreferncia ao array aDestino.

Exemplo:

LOCAL nCount := 2, nStart := 1, aOne, aTwo

aOne := { 1, 1, 1 }

aTwo := { 2, 2, 2 }

ACOPY(aOne, aTwo, nStart, nCount)

// Result: aTwo is now { 1, 1, 2 }

ADEL()

A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a excluso de um elemento, todos os demais so reorganizados de forma que a ultima posio do array passar a ser nula.

Sintaxe: ADEL(aArray, nPosio)

Parmetros

aArrayArray do qual deseja-se remover uma determinada posio

nPosioPosio do array que ser removida

Exemplo:

// Utilizando o array aItens do exemplo da funo ACLONE() temos:

ADEL(aItens,1) // Ser removido o primeiro elemento do array aItens.

// Neste ponto, o array aItens continua com 03 elementos, aonde:

// aItens[1] -> antigo aItens[2], o qual foi reordenado como efeito da excluso do item 1.

// aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito da excluso do item 1.

// aItens[3] -> contedo nulo, por se tratar do item excludo.

ADIR()

Funo que preenche os arrays passados com os dados dos arquivos encontrados, atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor podem ser informados.

Importante: ADir uma funo obsoleta, utilize sempre Directory(). Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ], [aHora], [ aAtributo ]) Parmetros:

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

aNomeArqArray de Caracteres. o array com os nomes dos arquivos encontrados na busca.O contedo anterior do array apagado.

aTamanhoArray Numrico. So os tamanhos dos arquivos encontrados na busca.

aDataArray de Datas. So as datas de modificao dos arquivos encontrados na busca.

aHoraArray de Caracteres. So os horrios de modificao dos arquivos encontrados. Cada elemento contm horrio no formato: hh:mm:ss.

aAtributosArray de Caracteres. So os atributos dos arquivos, caso esse array seja passado como parmetros, sero includos os arquivos com atributos de sistema e ocultos.

Retorno:

nArquivosQuantidade de arquivos encontrados.

Exemplo:

LOCAL aFiles[ADIR("*.TXT")]

ADIR("*.TXT", aFiles)

AEVAL(aFiles, { |element| QOUT(element) })

AFILL()

Funo de manipulao de arrays, que preenche os elementos do array com qualquer tipo de dado. Incluindo code-block. Esta funo no deve ser usada para preencher um array com outro array.

Sintaxe: AFILL( aDestino , xExpValor, [ nInicio ], [ nQuantidade ]) Parmetros

aDestino o onde os dados sero preenchidos.

xExpValor o dado que ser preenchido em todas as posies informadas, no permitida a utilizao de arrays.

nInicio a posio inicial de onde os dados sero preenchidos, o valor padro 1.

nCountQuantidade de elementos a partir de [nInicio] que sero preenchidos com , caso no seja informado o valor ser a quantidade de elementos at o final do array.

Retorno:

aDestinoRetorna uma referncia para aDestino.

Exemplo:

LOCAL aLogic[3]

// Resultado: aLogic { NIL, NIL, NIL }

AFILL(aLogic, .F.)

// Resultado: aLogic { .F., .F., .F. }

AFILL(aLogic, .T., 2, 2)

// Resultado: aLogic { .F., .T., .T. }

AINS()

A funo AINS() permite a insero de um elemento no array especificado em qualquer ponto da estrutura do mesmo, diferindo desta forma da funo AADD() a qual sempre insere um novo elemento ao final da estrutura j existente.

Sintaxe: AINS(aArray, nPosicao)

Parmetros

aArrayArray pr-existente no qual desejasse inserir um novo elemento.

nPosicaoPosio na qual o novo elemento ser inserido.

Exemplo:

aAlunos := {Edson, Robson, Renato, Tatiana}

AINS(aAlunos,3)

// Neste ponto o array aAlunos ter o seguinte contedo:

// {Edson, Robson, nulo, Renato, Tatiana}

Similar ao efeito da funo ADEL(), o elemento inserido no array pela funo AINS() ter um contedo nulo, sendo necessrio trata-lo aps a realizao deste comando.

ARRAY()

A funo Array() utilizada na definio de variveis de tipo array, como uma opo a sintaxe utilizando chaves ({}).

Sintaxe: Array(nLinhas, nColunas)

Parmetros

nLinhasDetermina o nmero de linhas com as quais o array ser criado

nColunasDetermina o nmero de colunas com as quais o array ser criado

Exemplo:

aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.O array definido pelo comando Array() apesar de j possuir a estrutura solicitada, no possui contedo em nenhum de seus elementos, ou seja:

aDados[1] -> array de trs posies

aDados[1][1] -> posio vlida, mas de contedo nulo.

ASCAN()

A funo ASCAN() permite que seja identificada a posio do array que contm uma determinada informao, atravs da anlise de uma expresso descrita em um bloco de cdigo.

Sintaxe: ASCAN(aArray, bSeek)

Parmetros

aArrayArray pr-existente no qual desejasse identificar a posio que contm a informao pesquisada.

bSeekBloco de cdigo que configura os parmetros da busca a ser realizada.

Exemplo:

aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}

bSeek := {|x| x == Denis}

nPosAluno := aScan(aAlunos,bSeek) // retorno esperado ( 2

Durante a execuo da funo aScan, a varivel x receber o contedo o item que est posicionado no momento, no caso aAlunos[x]. Como aAlunos[x] uma posio do array que contm o nome do aluno, x poderia ser renomeada para cNome, e a definio do bloco bSeek poderia ser re-escrita como:

bSeek := {|cNome| cNome == Denis}

Na definio dos programas sempre recomendvel utilizar variveis com nomes significativos, desta forma os blocos de cdigo no so exceo.

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

ASCANX()

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

xDestinoRepresenta o objeto a ser varrido pela funo, pode ser atribudo ao parmetro um array um Objeto.

bSeekRepresenta o valor que ser pesquisado, podendo ser um bloco de cdigo.

nInicioRepresenta o elemento a partir do qual ter inicio a pesquisa, quando este argumento no for informado o valor default ser 1.

nContRepresenta a quantidade de elementos que sero pesquisados a partir da posio inicial, quando este argumento no for informado todos elementos do array sero pesquisados.

Exemplo:

nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y define o intervalo onde esto compreendidos os parmetros

Ao Z-> expresso que ser executadas pelo bloco de cdigo

Ao1... AoZ -> intervalo de expresses que sero executadas pelo bloco de cdigo, no formato de lista de expresses.

Retorno -> resultado da ultima ao executada pelo bloco de cdigo, no caso

AoZ.

Para maiores detalhes sobre a estrutura e utilizao de blocos de cdigo consulte o tpico 6.2 Listas de Expresses e Blocos de cdigo.

Exemplo 1: Ordenao ascendente

aAlunos := { Mauren, Soraia, Andria}

aSort(aAlunos)

// Neste ponto, os elementos do array aAlunos sero {Andria, Mauren, Soraia}

Exemplo 2 :

Ordenao descendente

aAlunos := { Mauren, Soraia, Andria}

bOrdem := {|x,y| x > y }

// Durante a execuo da funo aSort(), a varivel x receber o contedo do item que est

// posicionado. Como o item que est posicionado a posio aAlunos[x] e aAlunos[x] ->

// string contendo o nome de um aluno, pode-se substituir x por cNomeAtu.

// A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma

// analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de cdigo

// bOrdem pode ser re-escrito como:

bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}

aSort(aAlunos,,bOrdem)

// Neste ponto, os elementos do array aAlunos sero {Soraia , Mauren, Andria}

ATAIL()

ATAIL() uma funo de manipulao de array que retorna o ltimo elemento de um array. Ela deve ser usada em substituio da seguinte construo: aArray [LEN( aArray )]

Sintaxe: ATAIL( aArray ) Parmetros:

aArray o array de onde ser retornado o ltimo elemento.

Retorno:

nUltimoNmero do ltimo elemento do array.

Exemplo:

aArray := {"a", "b", "c", "d"}

ATAIL(aArray) // Resultado: d

Manipulao de blocos de cdigo

EVAL()

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

Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)

Parmetros

bBlocoBloco de cdigo que ser interpretado.

xParamZParmetros que sero passados ao bloco de cdigo. A partir da passagem do bloco, todos os demais parmetros da funo sero convertidos em parmetros para a interpretao do cdigo.

Exemplo:

nInt := 10

bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}

nValor := EVAL(bBloco, nInt)

// O retorno ser dado pela avaliao da ultima ao da lista de expresses, no caso z.

// Cada uma das variveis definidas em uma das aes da lista de expresses fica disponvel

// para a prxima ao.

// Desta forma temos:

// N ( recebe nInt como parmetro (10)

// X ( tem atribudo o valor 10 (10)

// Y ( resultado da multiplicao de X por N (100)

// Z ( resultado a diviso de Y pela multiplicao de X por N ( 100 / 100) ( 1

DBEVAL()

A funo DBEval() permite que todos os registro de uma determinada tabela sejam analisados e para cada registro ser executado o bloco de cdigo definido.

Sintaxe: Array(bBloco, bFor, bWhile)

Parmetros

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

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

bWhileCondio para continuao da anlise dos registros, com o efeito de uma estrutura While ... End

Exemplo 1:// Considerando o trecho de cdigo abaixo:

dbSelectArea(SX5)dbSetOrder(1)dbGotop()

While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA (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

cStringString que ser avaliada para remoo dos espaos a direita e a esquerda.

Exemplo:

cNome := ALLTRIM(SA1->A1_NOME)

MSGINFO(Dados do campo A1_NOME:+CRLF

Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF

Texto: + CVALTOCHAR(LEN(cNome)))

ASC()

Converte uma informao caractere em seu valor de acordo com a tabela ASCII.

Sintaxe: ASC(cCaractere) Parmetros

cCaractereCaracter que ser consultado na tabela ASCII.

Exemplo:

USER FUNCTION NoAcento(Arg1)

Local nConta := 0

Local cLetra := ""

Local cRet := ""

Arg1 := Upper(Arg1)

For nConta:= 1 To Len(Arg1)

cLetra := SubStr(Arg1, nConta, 1)

Do Case

Case (Asc(cLetra) > 191 .and. Asc(cLetra) < 198) .or.;

(Asc(cLetra) > 223 .and. Asc(cLetra) < 230)

cLetra := "A"

Case (Asc(cLetra) > 199 .and. Asc(cLetra) < 204) .or.;

(Asc(cLetra) > 231 .and. Asc(cLetra) < 236)

cLetra := "E"

Exemplo (continuao):

Case (Asc(cLetra) > 204 .and. Asc(cLetra) < 207) .or.;

(Asc(cLetra) > 235 .and. Asc(cLetra) < 240)

cLetra := "I"

Case (Asc(cLetra) > 209 .and. Asc(cLetra) < 215) .or.;

(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) < 247)

cLetra := "O"

Case (Asc(cLetra) > 216 .and. Asc(cLetra) < 221) .or.;

(Asc(cLetra) > 248 .and. Asc(cLetra) < 253)

cLetra := "U"

Case Asc(cLetra) == 199 .or. Asc(cLetra) == 231

cLetra := "C"

EndCase

cRet := cRet+cLetra

Next

Return UPPER(cRet)AT()

Retorna a primeira posio de um caracter ou string dentro de outra string especificada.

Sintaxe: AT(cCaractere, cString ) Parmetros

cCaractereCaractere ou string que se deseja verificar

cStringString na qual ser verificada a existncia do contedo de cCaractere.

Exemplo:STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)

LOCAL cNoMascara := ""

LOCAL nX := 0

IF !Empty(cMascara) .AND. AT(cMascara,cString) > 0

FOR nX := 1 TO Len(cString)

IF !(SUBSTR(cString,nX,1) $ cMascara)

cNoMascara += SUBSTR(cString,nX,1)

ENDIF

NEXT nX

cNoMascara := PADR(ALLTRIM(cNoMascara),nTamanho)

ELSE

cNoMascara := PADR(ALLTRIM(cString),nTamanho)

ENDIF

RETURN cNoMascaraBITON()

Funo utilizada para ligar determinados bits de uma String passada por parmetro para a funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem alterados(ligados) e o tamanho da string passada.

Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > ) Parmetros

cValue String no qual desejamos ligar os bits.

nBitIni Indica a partir de qual bit, comear a ser ligados os bits na String

nBitEnd Indica a quantidade de bits que sero ligados a partir do inicio.

nStrLen Representa o tamanho da String passada para a funo.

CAPITAL()

Funo que avalia a string passada como parmetro alterando a primeira letra de cada palavra para maiscula e as demais letras como minsculas.

Sintaxe: CAPITAL(cFrase) Parmetros:

cFraseString a ser avaliada

Retorno:

StringContedo 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

nASCIICdigo ASCII do caractere

Exemplo:

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

DESCEND()

Funo de converso que retorna a forma complementada da expresso string especificada. Esta funo normalmente utilizada para a criao de indexadores em ordem decrescente

Sintaxe: DESCEND ( < cString > ) Parmetros:

cString Corresponde seqncia de caracteres a ser analisada.

Retorno:

Caracter

String complementada da string analisada.

Exemplo:

// Este exemplo utiliza DESCEND() em uma expresso INDEX para criar um ndice de datas de

// ordem descendente:

USE Sales NEWINDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate

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

// descendente:

DbSEEK(DESCEND(DTOS(dFindDate)))

GETDTOVAL()

Funo utilizada para retornar umnumero 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 '.' retornandoum numero fracionrio, na ordem dos nmeros contidos na string.

A funo muito til quando desejamos utilizar o valor numrico de uma data que est contida em uma string.

Sintaxe: GETDTOVAL ( < cDtoVal > ) Parmetros:

cDtoVal Representa uma string contendo um valor numrico no qual ser convertido.

Retorno:

NumricoRetorna um dado numrico de acordo com o valor informado em .

Exemplo:

GetDtoVal('123456') //retorno 123456.0000GetDtoVal('1/2/3/4/5/6')//retorno 123456.0000GetDtoVal('fim.123456')//retorno 0.123456GetDtoVal('teste') //retorno 0.0

ISALPHA()

Funo utilizada paradeterminar se o caractere mais esquerda em uma cadeia de caracteresalfabtico, permitindo avaliar se o string especificado comea com um caractere alfabtico. Um caractere alfabtico consiste em qualquer letra maiscula ou minscula de A a Z.

Sintaxe: ISALPHA ( < cString > ) Parmetros:

cString Cadeia de caracteres a ser examinada.

Retorno:

LgicoRetorna verdadeiro (.T.) se o primeiro caractere em for alfabtico, caso contrrio, retorna falso (.F.).

ISDIGIT()

Funo utilizada paradeterminar se o caractere mais esquerda em uma cadeia de caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um dgito numrico entre zero e nove.

Sintaxe: ISDIGIT ( < cString > ) Parmetros:

cString Cadeia de caracteres a ser examinada.

Retorno:

LgicoRetorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito entre zero e nove; caso contrrio, retorna falso (.F.).

ISLOWER()

Funo utilizada paradeterminar se o caractere mais esquerda uma letra minscula, permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa.

Sintaxe: ISLOWER( < cString > ) Parmetros:

cString Cadeia de caracteres a ser examinada.

Retorno:

LgicoRetorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo , caso contrrio, retorna falso (.F.).

ISUPPER()

Funo utilizada paradeterminar se o caractere mais esquerda uma letra maiscula, permitindo avaliar se o primeiro caractere de um string uma letra maiscula. o contrrio de ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa.

Sintaxe: ISUPPER( < cString > ) Parmetros:

cString Cadeia de caracteres a ser examinada.

Retorno:

LgicoRetorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo , caso contrrio, retorna falso (.F.).

LEN()

Retorna o tamanho da string especificada no parmetro.

Sintaxe: LEN(cString) Parmetros

cStringString que ser avaliada

Exemplo:cNome := ALLTRIM(SA1->A1_NOME)

MSGINFO(Dados do campo A1_NOME:+CRLF

Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF

Texto: + CVALTOCHAR(LEN(cNome)))

LOWER()

Retorna uma string com todos os caracteres minsculos, tendo como base a string passada como parmetro.

Sintaxe: LOWER(cString) Parmetros

cStringString que ser convertida para caracteres minsculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

LTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que possuam espaos em branco esquerda. Pode ser o caso de, por exemplo, nmeros convertidos para cadeias de caracteres atravs da funo STR().

LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a ALLTRIM(), que remove espaos tanto esquerda quanto direita.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs da insero de caracteres de preenchimento.

Sintaxe: LTRIM ( < cString > ) Parmetros:

cString a cadeia de caracteres a ser copiada sem os espaos em branco esquerda.

Retorno:

CaracterLTRIM() retorna uma cpia de , sendo que os espaos em branco esquerda foram removidos. Caso seja uma cadeia de caracteres nula ("") ou toda composta de espaos em branco, LTRIM() retorna uma cadeia de caracteres nula ("").

MATHC()

Funo utilizada para realizar operaes matemticas com strings que contm um valor numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao, Diviso, Multiplicao e Exponenciao.

A funo ir retornar uma string contendo o resultado da operao matemtica, com uma especificao de at 18 casas de preciso no numero.

Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > ) Parmetros:

cNum1String contendo um valor numrico, representando o numero no qual desejamos realizar uma operao.

cOperacaoRepresenta a string que indica a operao que desejamos realizar. Olhar na tabela para verificar quais valores devem ser informados aqui.

cNum2String contendo um valor numrico, representando o numero no qual desejamos realizar uma operao.

Retorno:

CaracterRetorna uma nova string contendo o resultado matemtico da operao.

OEMTOANSI()

Funo que transforma uma string no Formato OEM/ MS-DOS Textpara uma stringANSI Text( formato do Windows ).

Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de dados , os acentos e caracteres especiais so gravados como texto OEM . Para tornar possvel a correta visualizao destes dados em uma interface Windows , utilizamos a funo OemToAnsi() para realizar a converso.

Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados , o texto capturado no formato ANSI Text . Caso este texto seja utilizado para alimentar uma base de dados a ser acessada atravs de um programa MS-DOS , devemos converter o dado para OEM antes de grav-lo , atravs da funo AnsiToOem().

Sintaxe: OemToAnsi ( < cStringOEM > ) Parmetros:

cStringOEM String em formato OEM - MsDos a ser convertida.

Retorno:

CaracterString convertida para ser exibida no Windows ( Formato ANSI ).

PADL() / PADR() / PADC()

Funes de tratamento de strings que inserem caracteres de preenchimento para completar um tamanho previamente especificado em vrios formatos como data ou numricos.

PADC() centraliza , adicionando caracteres de preenchimento direita e esquerda.

PADL() adiciona caracteres de preenchimento esquerda.

PADR() adiciona caracteres de preenchimento direita.

Caso o tamanho de exceda o argumento , todas as funes PAD() truncam string preenchida ao 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

cExpCaractere, data, ou numrico no qual sero inseridos caracteres de preenchimento.

nTamanho Tamanho da cadeia de caracteres a ser retornada.

cCaracPreench Caractere a ser inserido em cExp. Caso no seja especificado, o padro o espao em branco.

Retorno:

CaracterRetornam o resultado de na forma de uma cadeia de caracteres preenchida com , para totalizar o tamanho especificado por .

RAT()

Retorna a ltima posio de um caracter ou string dentro de outra string especificada.

Sintaxe: RAT(cCaractere, cString) Parmetros

cCaractereCaractere ou string que se deseja verificar

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

cStringCaracter que ser repetido

nCountQuantidade de ocorrncias do caracter base que sero geradas na string de destino.

Retorno:

cReplicatedString contendo as ocorrncias de repeticao geradas para o caracter informado.

RTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que contenham espaos em branco direita. Ela til quando voc deseja eliminar espaos em branco direita ao se concatenar cadeias de caracteres. o caso tpico com campos de banco de dados que so armazenados em formato de tamanho fixo. Por exemplo, voc pode usar RTRIM() para concatenar o primeiro e o ltimo campos de nome para formar uma cadeia de caracteres de nome.

LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a ALLTRIM(), que remove espaos em branco direita e esquerda.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres, inserindo caracteres de preenchimento.

Sintaxe: RTRIM ( < cString > ) --> cTrimString Parmetros:

cString a cadeia de caracteres a ser copiada sem os espaos em branco direita.

Retorno:

Caracter

RTRIM() retorna uma cpia de , sendo que os espaos em branco direita foram removidos. Caso seja uma cadeia de caracteres nula ("") ou totalmente composta por espaos, RTRIM() retorna uma cadeia de caracteres nula ("").

SPACE()

Funo de tratamento de caracteres utilizada para retornar uma quantidade especificada de espaos. A utilizao desta funo tem o mesmo efeito que REPLICATE(' ', ), e normalmente utilizada para inicializar uma varivel do tipo caractere, antes que a mesma seja associada a um GET.

Sintaxe: SPACE ( < nCont > ) Parmetros:

nContA quantidade de espaos a serem retornados, sendo que o nmero mximo 65.535 (64K).

Retorno:

CaracterRetorna uma cadeia de caracteres. Se for zero, SPACE()retorna uma cadeia de caracteres nula ("").

STRTOKARR()

Funo utilizada para retornar um array, de acordo com os dados passados como parmetro para a funo. Esta funo recebe uma string e um caracter que representa um separador, e para toda ocorrncia deste separador em adicionado um item no array.

Sintaxe: STRTOKARR ( < cValue > , < cToken > ) Parmetros:

cValueRepresenta a cadeia de caracteres no qual desejamos separar de acordo com .

cTokenRepresenta o caracter que indica o separador em .

Retorno:

ArrayArray de caracteres que representa a string passada como parmetro.

Exemplo:

STRTOKARR('1;2;3;4;5', ';') //retorna {'1','2','3','4','5'}STRTRAN()

Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.

Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) Parmetros:

cStringSeqncia de caracteres ou campo memo a ser pesquisado.

cSearchSeqncia de caracteres a ser procurada em cString.

cReplaceSeqncia de caracteres que deve substituir a string cSearch. Caso no seja especificado, as ocorrncias de cSearch em cString sero substitudas por uma string nula ("").

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

nCountnCount corresponde ao nmero mximo de trocas que dever ser realizada pela funo . Caso este argumento no seja especificado , o default substituir todas as ocorrncias encontradas.

Retorno:

Code-Block

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

STUFF()

Funo que permite substituir um contedo caractere em uma string j existente, especificando a posio inicial para esta adio e o nmero de caracteres que sero substitudos.

Sintaxe: STUFF(cString, nPosInicial, nExcluir, cAdicao) Parmetros:

cStringA cadeia de caracteres destino na qual sero eliminados e inseridos caracteres.

nPosInicialA posio inicial na cadeia de caracteres destino onde ocorre a insero/eliminao.

nExcluirA quantidade de caracteres a serem eliminados.

cAdicaoA cadeia de caracteres a ser inserida.

Retorno:

CaracterRetorna a nova string gerada pela funo com as modificaes.

Exemplo:

cLin := Space(100)+cEOL // Cria a string base

cCpo := PADR(SA1->A1_FILIAL,02) // Informao que ser armazenada na string

cLin := Stuff(cLin,01,02,cCpo) // Substitui o contedo de cCpo na string base

SUBSTR()

Retorna parte do contedo de uma string especificada, de acordo com a posio inicial deste contedo na string e a quantidade de caracteres que dever ser retornada a partir daquele ponto (inclusive).

Sintaxe: SUBSTR(cString, nPosInicial, nCaracteres) Parmetros

cStringString que se deseja verificar

nPosInicialPosio inicial da informao que ser extrada da string

nCaracteresQuantidade de caracteres que dever ser retornada a partir daquele ponto (inclusive).

Exemplo:

cCampo := A1_NOME

nPosUnder := AT(cCampo)

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

TRANSFORM()

Funo de converso que formata valores caractere, data, lgicos e numricos conforme um string de mscara especificado, a qual inclui uma combinao de strings de template e funes de picture. Ela faz o mesmo que a clusula PICTURE do comando @...SAY, sendo normalmente utilizada para formatar dados a serem enviados tela ou impressora.

Sintaxe: TRANSFORM ( < cExp > , < cSayPicture > ) Parmetros:

cExpO valor a ser formatado. Esta expresso pode ser qualquer tipo de dados vlidos, exceto vetor, bloco de cdigo, e NIL.

cSayPictureUma string de caracteres de mscara e template usado para descrever o formato da cadeia de caracteres a ser retornada.

Retorno:

-Retorna a converso de para uma cadeia de caracteres formatada conforme a definio em .

UPPER()

Retorna uma string com todos os caracteres maisculos, tendo como base a string passada como parmetro.

Sintaxe: UPPER(cString) Parmetros

cStringString que ser convertida para caracteres maisculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

Manipulao de data / hora

CDOW()

Funo que converte uma data para uma cadeia de caracteres.

Sintaxe: CDOW( dExp ) Parmetros:

dExpData que ser convertida.

Retorno:

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

dDataData que ser convertida.

Retorno:

cMonthRetorna o nome do ms em uma cadeia de caracteres. A primeira letra do retorno em maiscula e o restante do nome, em minsculas.

Exemplo:

cMes := CMONTH(DATE()) // Resultado: September

cMes := CMONTH(DATE() + 45) // Resultado: October

cMes := CMONTH(CTOD("12/01/94")) // Resultado: December

cMes := SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE())) // Resultado: Sep 1

DATE()

Funo que retorna a data do atual sistema. O formato de sada controlado pelo comando SET DATE, sendo que o formato padro mm/dd/yy.

Sintaxe: DATE() Parmetros:

Nenhum.

Retorno:

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

dDataData que ser convertida.

Retorno:

nDiasSe o ms do argumento dData for fevereiro, anos bissextos so considerados. Se a data do argumento dData for 29 de fevereiro e o ano no for bissexto, ou se o argumento dData for vazio.

Exemplo:// Estes exemplos mostram a funo DAY() de diversas maneiras:

dData := DATE() // Resultado: 09/01/01

nDia := DAY(DATE()) // Resultado: 1

nDia := DAY(DATE()) + 1 // Resultado: 2

nDia := DAY(CTOD("12/01/94")) // Resultado: 1

// Este exemplo mostra a funo DAY() usada em conjunto com CMONTH() e

YEAR() para formatar o valor da data:

dData := Date()

cData := CMONTH(dData) + STR(DAY(dData)) + "," + STR(YEAR(dData)) // Resultado: June 15, 2001

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:

dDataData que ser convertida.

Retorno:

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

dDataData que ser convertida.

Retorno:

cData uma cadeia de caracteres representando o valor da data. O retorno formatado utilizando-se o formato corrente definido pelo comando SET DATE FORMAT. O formato padro mm/dd/yy. Para uma data nula ou invlida, o retorno ser uma cadeia de caracteres com espaos e tamanho igual ao formato atual.

Exemplo:

cData := DATE() // Resultado: 09/01/90

cData := DTOC(DATE()) // Resultado: 09/01/90

cData := "Today is " + DTOC(DATE()) // Resultado: Today is 09/01/90

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:

dDataData que ser convertida.

Retorno:

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

cHoraInicialInforme a hora inicial no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos

CHoraFinalInforme a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

Retorno:

CaracterA diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

Exemplo:

cHoraInicio := TIME() // Resultado: 10:00:00

...

...

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:

dDataData que ser convertida.

Retorno:

Numrico>=0 e =0 e = (nQuantidade*nPrcUnit)

RETURN nQuantidade

ELSEIF nDinheiro > nPrcUnit

nQuantidade := INT(nDinheiro / nPrcUnit)

ELSE

nQuantidade := 0

ENDIF

RETURN nQuantidade

NOROUND()

Retorna um valor, truncando a parte decimal do valor especificado no parmetro de acordo com a quantidade de casas decimais solicitadas.

Sintaxe: NOROUND(nValor, nCasas) Parmetros

nValorValor que ser avaliado

nCasasNmero de casas decimais vlidas. A partir da casa decimal especificada os valores sero desconsiderados.

Exemplo:

Funo NOROUND()

nBase := 2.985

nValor := NOROUND(nBase,2) ( 2.98

RANDOMIZE()

Atravs da funo RANDOMIZE() , geramos um numero inteiro aleatrio, compreendido entre a faixa inferior e superior recebida atravs dos parmetros nMinimo e nMaximo, respectivamente.

Observao:

O limite inferior recebido atravs do parmetro nMinimo "maior ou igual a ", podendo ser sorteado e fazer parte do retorno; porm o limite superior "menor que", de modo a nunca ser atingido ou devolvido no resultado.Por exemplo , a chamada da funo RANDOMIZE(1,2) sempre retornar 1 .

Sintaxe: RANDOMIZE ( < nMinimo > , < nMaximo > ) Parmetros

nMinimo Corresponde ao menor numero a ser gerado pela funo.

nMaximo Corresponde ao maior nmero ( menos um ) a ser gerado pela funo.

Retorno:

NumricoNumero randmico , compreendido no intervalo entre (nMinimo) e (nMaximo-1) : O numero gerado pode ser maior ou igual nMinimo e menor ou igual a nMaximo-1 .

ROUND()

Retorna um valor, arredondando a parte decimal do valor especificado no parmetro de acordo com a quantidades de casas decimais solicitadas, utilizando o critrio matemtico.

Sintaxe: ROUND(nValor, nCasas) Parmetros

nValorValor que ser avaliado

nCasasNmero de casas decimais vlidas. As demais casas decimais sofrero o arredondamento matemtico, aonde:

Se nX , < cDestino > , [ lCompacta ] )

Parmetros:

cOrigemNome(s) dos arquivos a serem copiados, aceita apenas arquivos no servidor, WildCards ( * e ? ) so aceitos normalmente.

cDestinoDiretrio com o destino dos arquivos no Client ( Remote ).

lCompactaIndica se a cpia deve ser feita compactando o arquivo antes do envio.

Retorno:

Lgico

lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em caso de falha na cpia.

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

CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. )

CPYT2S()

Funo utilizada para copiar um arquivo do cliente (Remote) para o servidor, sendo que os caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada (lCompacta), os dados sero transmitidos de maneira compacta e descompactados antes do uso. Sintaxe: CpyT2S( cOrigem, cDestino, [ lCompacta ])

Parmetros:

cOrigemNomes dos arquivos a serem copiados, aceita apenas arquivos locais ( Cliente ), WildCards so aceitos normalmente.

cDestinoDiretrio com o destino dos arquivos no remote ( Cliente ).

lCompactaIndica se a cpia deve ser feita compactando o arquivo antes.

Retorno:

LgicoIndica se o arquivo foi copiado para o cliente com sucesso.

Exemplo:// Copia arquivos do cliente( remote ) para o Servidor compactando antes de transmitir

CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP", .T. )

// Copia arquivos do cliente( remote ) para o Servidor sem compactar.

CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" )

CURDIR()

Funo que retorna o diretrio corrente do servidor. O caminho retornado sempre relativo ao RootPath definido na configurao do Environment no .INI do Protheus Server. Inicialmente , o diretrio atual da aplicao o constante na chave StartPath , tambm definido na configurao do Environment no .INI do Protheus Server.

Caso seja passado o parmetro cNovoPath , este path assumido como sendo o Path atual. Caso o path recebido como parmetro no exista , seja invlido , ou seja um path absoluto (iniciado com uma letra de drive ou caminho de rede), a funo no ir setar o novo path, mantendo o atual .

Sintaxe: CURDIR ( [ cNovoPath ] ) Parmetros:

cNovoPathCaminho relativo , com o novo diretrio que ser ajustado como corrente.

Retorno:

CaracterDiretrio corrente, sem a primeira barra.

Exemplo:

cOldDir := curdir()

cNewDir := '\webadv\xis'

curdir(cNewDir) // Troca o path

If cNewDir '\'+curdir() // E verifica se trocou mesmo

conout('Falha ao Trocar de Path de '+cOldDir + ' para '+cNewDir)

Else conout('Path de '+cOldDir + ' trocado para '+cNewDir+' com sucesso.')

Endif

DIRECTORY()

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

AtributoSignificado

HIncluir arquivos ocultos

SIncluir arquivos de sistema

DIncluir diretrios

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

PosioMetasmboloDirectry.ch

1cNomeF_NAME

2cTamanhoF_SIZE

3dDataF_DATE

4cHoraF_TIME

5cAtributosF_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 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. consiste em uma cadeia de caracteres que contm um ou mais dos seguintes caracteres, contidos na tabela adicional A , especificada anteriormente.

Retorno:

Array

DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor contm informaes sobre cada arquivo que atenda a .Veja maiores detalhes na Tabela B, discriminada anteriormente.

Exemplo:#INCLUDE "Directry.ch"

aDirectory := DIRECTORY("*.*","D")

AEVAL( aDirectory, {|aFile| CONOUT(aFile[F_NAME])} )

DIRREMOVE()

Funo que elimina um diretrio especifico. Caso especifiquemos um path sem a unidade de disco , ele ser considerado no ambiente do Servidor , a partir do RootPath do ambiente ( caso o path comece com \ ), ou a partir do diretrio corrente (caso o path no seja iniciado com \ ).

Quando especificado um path absoluto ( com unidade de disco preenchida ), a funo ser executada na estao onde est sendo executado o Protheus Remote. Quando executamos a funo DirRemove() em JOB ( processo isolado no Server , sem interface ), no possvel especificar um Path absoluto de disco. Caso isto seja realizado , a funo retornar .F. e FError() retornar -1 ( Syntax Error ).

Note que necessrio ter direitos suficientes para remover um diretrio, e o diretrio a ser eliminado precisa estar vazio, sem subdiretrios ou arquivos dentro do mesmo.

Sintaxe: DIRREMOVE ( < cDiretorio > ) Parmetros:

cDiretorio Nome do diretrio a ser removido.

Retorno:

LgicolSucesso ser .T. caso o diretrio tenha sido eliminado , ou .F. caso no seja possvel excluir o diretrio. Quando a funo DirRemove retornar .F. , possvel obter mais detalhes da ocorrncia recuperando o cdigo do Erro atravs da funo FError().

Exemplo:cDelPath := 'c:\TmpFiles'

lRemoveOk := DIRREMOVE(cDelPath)

IF !lRemoveOk

MsgStop('Falha ao remover a pasta '+cDelPath+' ( File Error '+str(Fewrror(),4)+' ) ')

Else MsgStop('Pasta '+cDelPath+' removida com sucesso.')

Endif

DISKSPACE()

Funo de ambiente que determina quantos bytes esto disponveis em uma determinada unidade de disco. Esta funo obtm a informao sempre relativa estao onde est sendo executado o Protheus Remote. Atravs do parmetro nDrive , selecionamos qual a unidade de disco que desejamos obter a informao do espao livre , onde:

0 : Unidade de disco atual da estao (DEFAULT).

1 : Drive A: da estao remota.

2 : Drive B: da estao remota.

3 : Drive C: da estao remota.

4 : Drive D: da estao remota ... e assim por diante.

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

Sintaxe: DISKSPACE ( [ nDrive ] ) Parmetros:

nDriveNmero do drive, onde 0 o espao na unidade de disco corrente, e 1 o drive A: do cliente, 2 o drive B: do cliente, etc.

Retorno:

NumricoNmero de bytes disponveis no disco informado como parmetro.

Exemplo:

nBytesLocal := DISKSPACE( ) // Retorna o espao disponvel na unidade de disco local

IF nBytesLocal < 1048576

MsgStop('Unidade de Disco local possui menos de 1 MB livre.')

Else MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes livres.')

EndifnBytes_A := DISKSPACE( 1 ) // Retorna o espao disponvel no drive A: local ( remote ).

If nBytes_A == -1

MsgStop('Unidade A: no est disponvel ou no h disco no Drive')

ElseIf nBytes_A < 8192

MsgStop('No h espao disponvel no disco. Substitua o disco na Unidade A:')

Else MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes livres.')

Endif

EXISTDIR()

Funo utilizada para determinar se um path de diretrio existe e valido.

Sintaxe: EXISTDIR (< cPath >) Parmetros:

cPath String contendo o diretrio que ser verificado, caso seja feita uma verificao a partir do server, devemos informar a partir do rootPath do Protheus, caso contrrio devemos passar o path completo do diretrio.

Retorno:

LgicoRetorna se verdadeiro(.T.) caso o diretrio solicitado exista, falso(.F.) caso contrrio.

Exemplo 1: No server a partir do rootPath

lRet := ExistDir('\teste')

Exemplo 2: No client, passando o FullPath

lRet := ExistDir('c:\APO')

FCLOSE()

Funo de tratamento de arquivos de baixo nvel utilizada para fechar arquivos binrios e forar que os respectivos buffers do DOS sejam escritos no disco. Caso a operao falhe, FCLOSE() retorna falso (.F.). FERROR() pode ento ser usado para determinar a razo exata da falha. Por exemplo, ao tentar-se usar FCLOSE() com um handle (tratamento dado ao arquivo pelo sistema operacional) invlido retorna falso (.F.) e FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para obter uma lista completa dos cdigos de erro.

Nota: Esta funo permite acesso de baixo nvel aos arquivos e dispositivos do DOS. Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional utilizado.

Sintaxe: FCLOSE ( < nHandle > ) Parmetros:

nHandle Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().

Retorno:

LgicoRetorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos; do contrrio, retorna verdadeiro (.T.).

Exemplo:

#include "Fileio.ch"

nHandle := FCREATE("Testfile", FC_NORMAL)

If !FCLOSE(nHandle)

conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )

EndIf

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

ConstanteValorDescrio

FC_NORMAL0Criao normal do Arquivo (default/padro).

FC_READONLY1Cria o arquivo protegido para gravao.

FC_HIDDEN2Cria o arquivo como oculto.

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

cArquivoNome do arquivo a ser criado , podendo ser especificado um path absoluto ou relativo , para criar arquivos no ambiente local ( Remote ) ou no Servidor, respectivamente .

nAtributoAtributos do arquivo a ser criado (Vide Tabela de atributos abaixo). Caso no especificado, o DEFAULT FC_NORMAL.

Retorno:

Numrico

A funo retornar o Handle do arquivo para ser usado nas demais funes de manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no seja possvel criar o arquivo , a funo retornar o handle -1 , e ser possvel obter maiores detalhes da ocorrncia atravs da funo FERROR() .

FERASE()

Funo utilizada para apagar um arquivo no disco . O Arquivo pode estar no Servidor ou na estao local (Remote). O arquivo para ser apagado deve estar fechado, no sendo permitido a utilizao de caracteres coringa (wildcards).

Sintaxe: FERASE ( < cArquivo > ) Parmetros:

cArquivoNome do arquivo a ser apagado . Pode ser especificado um path absoluto ou relativo , para apagar arquivos na estao local ( Remote ) ou no Servidor, respectivamente.

Retorno:

NumricoA funo retornar 0 caso o arquivo seja apagado com sucesso , e -1 caso no seja possvel apagar o arquivo. Caso a funo retorne -1, possvel obter maiores detalhes da ocorrncia atravs da funo FERROR().

Exemplo:

#include 'DIRECTRY.CH'

aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })

// Este exemplo apaga um arquivo no cliente ( Remote ) , informando o status da operao

IF FERASE("C:\ListaTXT.tmp") == -1

MsgStop('Falha na deleo do Arquivo ( FError'+str(ferror(),4)+ ')')

Else MsgStop('Arquivo deletado com sucesso.')

ENDIF

FILE()

Funo que verifica se existe um arquivo ou um padro de arquivos, no diretrio. Podem ser especificados caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( a partir do RootPath do Protheus Server) , sendo os caracteres * e ? ( wildcards) aceitos.

Sintaxe: FILE ( < cArquivo > ) Parmetros:

cArquivoNome do arquivo , podendo ser especificado um path (caminho) . Caminhos locais (Remote) ou caminhos de servidor so aceitos , bem como wildcards (Caracteres * e ? ).

Retorno:

LgicoO retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no exista no path especificado , a funo retorna .F.

Exemplo:

//Verifica no diretrio corrente do servidor se existe o arquivo teste.dbf

FILE("teste.dbf")

// Verifica no diretrio Sigaadv do servidor se existe o arquivo teste.dbf

FILE("\SIGAADV\TESTE.dbf")

// Verifica no diretrio Temp do cliente (Remote) se existe o arquivo teste.dbf

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

cStringString contendo o nome do arquivo.

Exemplo:

Local cString := '\SIGAADV\ARQZZZ.DBF'

cString := FileNoExt( cString )

// Retorno ( \SIGAADV\ARQZZZ

FOPEN()

Funo de tratamento de arquivo de baixo nvel que abre um arquivo binrio existente para que este possa ser lido e escrito, dependendo do argumento . Toda vez que houver um erro na abertura do arquivo, FERROR() pode ser usado para retornar o cdigo de erro do Sistema Operacional. Por exemplo, caso o arquivo no exista, FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o arquivo no foi encontrado. Veja FERROR() para uma lista completa dos cdigos de erro.

Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de banco de dados, e ele exigido para identificar o arquivo aberto para as outras funes de tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi retornado a uma varivel para uso posterior, como mostra o exemplo desta funo.

Nota: Esta funo permite acesso de baixo nvel a arquivos e dispositivos. Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional utilizado.

FOPEN procura o arquivo no diretrio corrente e nos diretrios configurados na varivel de pesquisa do Sistema Operacional, a no ser que um path seja declarado explicitamente como parte do argumento .

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

cArqNome do arquivo a ser aberto que inclui o path caso haja um.

nModoModo de acesso DOS solicitado que indica como o arquivo aberto deve ser acessado. O acesso de uma das categorias relacionadas na tabela A e as restries de compartilhamento relacionada na Tabela B. O modo padro zero, somente para leitura, com compartilhamento por Compatibilidade. Ao definirmos o modo de acesso , devemos somar um elemento da Tabela A com um elemento da Tabela B.

Retorno:

NumricoFOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso ocorra um erro, FOPEN() retorna -1.

Exemplo:

#include 'fileio.ch'...nH := fopen('\sigaadv\error.log' , FO_READWRITE + FO_SHARED )If nH == -1 MsgStop('Erro de abertura : FERROR '+str(ferror(),4))Else MsgStop('Arquivo aberto com sucesso.') ... fclose(nH)Endif...

Tabela A: Modos de acesso a arquivos binriosModoConstate(fileio.ch)Operao

0FO_READAberto para leitura (padro assumido)

1FO_WRITEAberto para gravao

2FO_READWRITEAberto para leitura e gravao

Tabela B: Modos de acesso de compartilhamento a arquivos binriosModoConstate(fileio.ch)Operao

0FO_COMPATModo de Compatibilidade (Default)

16FO_EXCLUSIVEAcesso total exclusivo

32FO_DENYWRITEAcesso bloqueando a gravao de outros processos ao arquivo.

48FO_DENYREADAcesso bloqueando a leitura de outros processos ao arquivo.

64FO_DENYNONEAcesso compartilhado. Permite a leitura e gravao por outros.

FREAD()

Funo que realiza a leitura dos dados a partir um arquivo aberto, atravs de FOPEN(), FCREATE() e/ou FOPENPORT(), e armazena os dados lidos por referncia no buffer informado.FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum erro ou o arquivo chegue ao final, FREAD() retornar um nmero menor que o especificado em nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128, ASC 0, etc.) e l a partir da posio atual do ponteiro atual do arquivo , que pode ser ajustado ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().

A varivel String a ser utilizada como buffer de leitura deve ser sempre pr-alocado e passado como referncia. Caso contrrio, os dados no podero ser retornados.

Sintaxe: FREAD ( < nHandle > , < cBuffer > , < nQtdBytes > ) Parmetros:

nHandle o manipulador (Handle) retornado pelas funes FOPEN(),FCREATE(), FOPENPORT(), que faz referncia ao arquivo a ser lido.

cBuffer o nome de uma varivel do tipo String , a ser utilizada como buffer de leitura , onde os dados lidos devero ser armazenados. O tamanho desta varivel deve ser maior ou igual ao tamanho informado em nQtdBytes.

Esta varivel deve ser sempre passada por referncia. ( @ antes do nome da varivel ), caso contrrio os dados lidos no sero retornados.

nQtdBytesDefine a quantidade de Bytes que devem ser lidas do arquivo a partir posicionamento do ponteiro atual.

Retorno:

NumricoQuantidades de bytes lidos. Caso a quantidade seja menor que a solicitada, isto indica erro de leitura ou final de arquivo, Verifique a funo FERROR() para maiores detalhes.

FREADSTR ()

Funo que realiza a leitura de caracteres de um arquivo binrio. FREADSTR() l de um arquivo aberto, atravs de FOPEN(), FCREATE(), FOPENPORT(). FREADSTR() ler at o nmero de bytes informado em nQtdBytes ou at encontrar um CHR(0). Caso acontea algum erro ou o arquivo chegue ao final, FREADSTR() retornar uma string menor do que nQdBytes e colocar o erro em FERROR(). FREADSTR() l a partir da posio atual do ponteiro, que pode ser ajustado pelo FSEEK(), FWRITE( ) ou FREAD().

Sintaxe: FREADSTR ( < nHandle > , < nQtdBytes > ) Parmetros:

nHandle o manipulador retornado pelas funes FOPEN(),FCREATE(), FOPENPORT().

nQtdBytesNmero mximo de bytes que devem ser lidos.

Retorno:

CaracterRetorna uma string contendo os caractereslidos.

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

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

cNewFileNovo nome do arquivo, aceita tambm caminho do servidor, e caminho do cliente.

Retorno:

NumricoSe o status retornado for -1 , ocorreu algum erro na mudana de nome : Verifique se os dois caminhos esto no mesmo ambiente, verifique a existncia do arquivo de origem, se ele no est em uso no momento por outro processo , e verifique se o nome do arquivo de destino j no existe no path de destino especificado.

FSEEK()

Funo que posiciona o ponteiro do arquivo para as prximas operaes de leitura ou gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os seguintes valores, definidos em fileio.ch:

Tabela A: Origem a ser considerada para a movimentao do ponteiro de posicionamento do Arquivo.OrigemConstate(fileio.ch)Operao

0FS_SETAjusta a partir do inicio do arquivo. (Default)

1FS_RELATIVEAjuste relativo a posio atual do arquivo.

2FS_ENDAjuste a partir do final do arquivo.

Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) Parmetros:

nHandleManipulador obtido atravs das funes FCREATE,FOPEN.

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

nOrigemIndica a partir de qual posio do arquivo, o nOffset ser considerado.

Retorno:

NumricoFSEEK() 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 funoEOF() utilizada para arquivos de dados.

Sintaxe: FT_FEOF( ) Parmetros:

Nenhum.

Retorno:

LgicoRetorna true caso o ponteiro do arquivo tenha chegado ao final, false caso contrrio.

FT_FGOTO()

Funo utilizada para mover o ponteiro, que indica a leitura do arquivo texto, para a posio absoluta especificada pelo argumento.

Sintaxe: FT_FGOTO ( < nPos > ) Parmetros:

nPosIndica a posio que ser colocado o ponteiro para leitura dos dados no arquivo.

Retorno:

Nenhum.

FT_FGOTOP()

A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto, para a posio absoluta especificada pelo argumento.

Sintaxe: FT_FGOTO ( < nPos > ) Parmetros:

nPosIndica a posio que ser colocado o ponteiro para leitura dos dados no arquivo.

Retorno:

Nenhum.

FT_FLASTREC()

Funo que retorna o nmero total de linhas do arquivo texto aberto pela FT_FUse. As linhas so delimitadas pela seqncia de caracteres CRLF o LF.

Verifique maiores informaes sobre formato do arquivo e tamanho mximo da linha de texto na funo FT_FREADLN().

Sintaxe: FT_FLASTREC( )

Parmetros:

Nenhum.

Retorno:

NumricoRetorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja vazio, ou no exista arquivo aberto, a funo retornar 0 (zero).

Exemplo:

FT_FUse('teste.txt') // Abre o arquivo

CONOUT("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")

FT_FGOTOP()

While !FT_FEof()

conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha ["+FT_FReadln()+"]")

FT_FSkip()

Enddo

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

A utilizaodesta 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 superiora 7.00.050713P, a funo FT_FREADLN() tambm capaz de ler arquivos texto / ASCII, que utilizam tambm o caractere LF ( chr(10) ) como separador de linha.

Sintaxe: FT_FREADLN( )

Parmetros:

Nenhum.

Retorno:

CaracterRetorna a linha inteira na qual est posicionado o ponteiro para leitura de dados.

FT_FRECNO()

A funo tem o objetivo de retornar a posio do ponteiro do arquivo texto.

A funo FT_FRecno retorna a posiocorrente do ponteiro do arquivo texto aberto pela FT_FUse.

Sintaxe: FT_FRECNO ( ) Parmetros:

Nenhum.

Retorno:

CaracterRetorna a posio corrente do ponteiro do arquivo texto.

FT_FSKIP()

Funo que move o ponteiro do arquivo texto aberto pela FT_FUSE() para a prxima linha, similar ao DBSKIP() usado para arquivos de dados.

Sintaxe: FT_FSKIP ( [ nLinhas ] ) Parmetros:

nLinhasnLinhas corresponde ao nmero de linhas do arquivo TXT ref. movimentao do ponteiro de leitura do arquivo.

Retorno

Nenhum.

FT_FUSE()

Funo que abre ou fecha um arquivo texto para uso das funes FT_F*. As funes FT_F* so usadas para ler arquivos texto, onde as linhas so delimitadas pela seqncia de caracteres CRLF ou LF (*) e o tamanho mximo de cada linha 1022 bytes.. O arquivo aberto em uma rea de trabalho, similar usada pelas tabelas de dados.

Verifique maiores informaes sobre formato do arquivo e tamanho mximo da linha de texto na funo FT_FREADLN().

Sintaxe: FT_FUSE ( [ cTXTFile ] ) Parmetros:

cTXTFileCorresponde ao nome do arquivo TXT a ser aberto. Caso o nome no seja passado, e j exista um arquivo aberto. o mesmo fechado.

Retorno:

NumricoA funo retorna o Handle de controle do arquivo. Em caso de falha de abertura, a funo retornar -1

FWRITE()

Funo que permite a escrita em todo ou em parte do contedo do buffer , limitando a quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da posio corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade real de bytes escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou criar um arquivo ou abrir uma porta de comunicao , para o qual sero gravados ou enviados os dados do buffer informado. Por tratar-se de uma funo de manipulao de contedo binrio , so suportados na String cBuffer todos os caracteres da tabela ASCII , inclusive caracteres de controle ( ASC 0 , ASC 12 , ASC 128 , etc.).

Caso acontea alguma falha na gravao , a funo retornar um nmero menor que o nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do ponteiro , que pode ser ajustado atravs das funes FSEEK() , FREAD() ou FREADSTR().

Sintaxe: FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) Parmetros:

nHandle o manipulador de arquivo ou device retornado pelas funes FOPEN(), FCREATE(), ou FOPENPORT().

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

Retorno:

NumricoFWRITE() retorna a quantidade de bytes escritos na forma de um valor numrico inteiro. Caso o valor retornado seja igual a , a operao foi bem sucedida. Caso o valor de retorno seja menor que ou zero, ou o disco est cheio ou ocorreu outro erro. Neste caso , utilize a funo FERROR() para obter maiores detalhes da ocorrncia.

Exemplo:

#INCLUDE "FILEIO.CH"#DEFINE F_BLOCK 1024 // Define o bloco de Bytes a serem lidos / gravados por vez

User Function TestCopy()Local cBuffer := SPACE(F_BLOCK)Local nHOrigem , nHDestino Local nBytesLidos , nBytesFalta , nTamArquivoLocal nBytesLer , nBytesSalvoLocal lCopiaOk := .T.

// Abre o arquivo de OrigemnHOrigem := FOPEN("ORIGEM.TXT", FO_READ)

Exemplo (continuao):

// Testa a abertura do ArquivoIf nHOrigem == -1

MsgStop('Erro ao abrir origem. Ferror = '+str(ferror(),4),'Erro')

Return .F. Endif

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

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

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

// Testa a criao do arquivo de destinoIf 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 ArquivonBytesFalta := nTamArquivo

// Enquanto houver dados a serem copiadosWhile 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

Exemplo (continuao):

// Elimina do Total do Arquivo a quantidade de bytes copiados

nBytesFalta -= nBytesLer

Enddo

// Fecha os arquivos de origem e destinoFCLOSE(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:

cArqOrigNome do arquivo origem e a extenso.

cArqDestNome do arquivo destino e a extenso.

Retorno:

LgicoSe a copia for realizada com sucesso a funo retornar verdadeiro (.T.).

Exemplo:

Local cArqOrig := 'ARQ00001.DBF'

Local cArqDest := 'ARQ00002.XXX'

If MsCopyFile( cArqOrig, cArqDest )

APMsgInfo('Copia realizada com sucesso!')

EndIf

MSCOPYTO()

Funo que realiza a cpia dos registros de uma base de dados para outra, criando o arquivo destino de acordo com a estrutura da base de dados origem.

Sintaxe: MSCOPYTO( [cArqOrig], cArqDest )

Parmetros:

cArqOrigNome do arquivo origem e a extenso se o ambiente for Top o parmetro passar a ser obrigatrio.

cArqDestNome do arquivo destino e a extenso.

Retorno:

LgicoSe a copia for realizada com sucesso a funo retornar verdadeiro (.T.).

Exemplo:

Local cArqDest := 'SX2ZZZ.DBF'

DbSelectArea('SX2')

If MsCopyTo( , cArqDest )

APMsgInfo('Copia realizada com sucesso!')

Else

APMsgInfo('Problemas ao copiar o arquivo SX2!')

EndIf

MSCREATE()

Funo que cria um arquivo (tabela) de acordo com a estrutura informada no parmetro aStruct. Se o parmetro cDriver no for informado o RDD corrente ser assumido como padro. Para criao de tabelas no TopConnect necessrio estar conectado ao banco e o environment do protheus ser TOP.

aStruct: array contendo a estrutura da tabela aonde:

1 - caracter, nome do campo;

2 - caracter, tipo do campo;

3 - numrico, tamanho do campo;

4 - numrico, decimais.

Sintaxe: MsCreate( cArquivo, aStru ,[cDriver] ) Parmetros:

cArquivoNome do arquivo.

aStructEstrutura do arquivo.

cDriverRDD do arquivo.

Retorno:

LgicoIndica se a operao foi executada com sucesso.

Exemplo:

Local cTarget := '\sigaadv\'

Local aStrut

aStrut := { { 'Campo', 'C', 40, 0 } }

If MsCreate( cTarget+'ARQ1001', aStrut )

APMsgInfo('Criado com sucesso!')

Else

APMsgInfo('Problemas ao criar o arquivo!')

EndIfMSERASE()

Funo utilizada para deletar fisicamente o arquivo especificado. Sintaxe: MsErase( cArquivo, [cIndice], [cDriver] ) Parmetros:

cArquivoNome do arquivo e a extenso.

cIndiceNome do arquivo de ndice e a extenso.

cDriverRDD do arquivo, se no for informado assumir o RDD corrente.

Retorno:

LgicoIndica se a operao foi executada com sucesso.

Exemplo:

Local cArquivo := 'SX2ZZZ.DBF'

Local cIndice := 'SX2ZZZ'+ OrdBagExt()

If MsErase( cArquivo, cIndice )

APMsgInfo( 'Arquivo deletado com sucesso!' )

Else

APMsgInfo( 'Problemas ao deletar arquivo!' )

EndIf

MSRENAME()

Funo que verifica a existncia do arquivo especificado.

Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] )

Parmetros:

cArquivoNome do arquivo e a extenso.

cIndiceNome do arquivo de ndice e a extenso.

cDriverRDD do arquivo, se no for informado assumir o RDD corrente.

Retorno:

LgicoIndica se o arquivo especificado existe.

Exemplo:

Local cArquivo := 'SX2ZZZ.DBF'

Local cIndice := 'SX2ZZZ'+ OrdBagExt()

If !MsFile ( cArquivo, cIndice )

APMsgInfo( 'Arquivo no encontrado!' )

EndIf

RETFILENAME()

Funo que retorna o nome de um arquivo contido em uma string, ignorando o caminho