Você está na página 1de 152

Funes Genricas

EVAL
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores
Sintaxe
EVAL ( < bBloco > , [ ] ) --> UltValorBloco
Parmetros
Argumento Tipo Descrio
bBloco Code-Block <bBloco> o bloco de cdigo a ser avaliado.
<ListaArgBloco> (Qualquer)
<ListaArgBloco> uma lista de argumentos a ser
enviada ao bloco de cdigo antes que ele seja avaliado.
Retorno
Tipo Descrio
(Qualquer)
EVAL() retorna o valor da ltima expressao dentro do bloco. Um bloco de
cdigo pode retornar um valor de qualquer tipo.
Descrio
EVAL() uma funao de tratamento de blocos de cdigo. Ela o dispositivo mais
bsico no sistema Advpl para avaliar blocos de cdigo. Um bloco de cdigo um valor
de dados especiais que se refere a uma parte do cdigo de programa compilado. Para
maiores informaoes sobre blocos de cdigo, consulte o captulo Conceitos Bsicos
neste livro.
Para executar ou avaliar um bloco de cdigo, voc pode chamar EVAL() com o valor de
bloco e quaisquer parmetros. Os parmetros sao Fornecidos ao bloco quando ele
executado. Blocos de cdigo podem ser uma srie de expressoes separadas por vrgulas.
Quando um bloco de cdigo avaliado, o valor retornado o valor da ltima expressao
no bloco.
Um bloco de cdigo geralmente compilado em tempo de compilaao pelo compilador
do Advpl. Existem, porm, ocasioes em tempo de execuao quando pode ser necessrio
que voc compile um bloco de cdigo a partir de uma cadeia de caracteres. Isto pode ser
feito utilizando-se o operador macro (&).
EVAL() frequentemente utilizado para criar funoes iterator. Estas funoes aplicam
um bloco para cada membro de uma estrutura de dados. AEVAL(), ASORT(),
ASCAN(), e DBEVAL() sao funoes iterator. AEVAL(), por exemplo, aplica um bloco
para cada elemento dentro de um vetor.
GETREMOTETYPE
Reviso: 19/11/2004
Abrangncia
Verso 8.11

Sintaxe
GETREMOTETYPE ( ) --> nRmtType
Retorno
Tipo Descrio
Numrico nRmtType corresponde o nmero correspondente interface utilizada.
Descrio
Atravs da funo GetRemoteType(), possvel identificar sob qual interface o
programa atual est em execuo.
Esta funo est disponvel a partir do Protheus 8, Build 7.00.040308a
Pode-se utilizar as constantes abaixo, para avaliar o retorno da funo.
NO_REMOTE -1 // Job, Web ou Working Thread ( Sem remote )
REMOTE_QT_WIN32 1 // Remote em ambiente Windows
REMOTE_QT_LINUX 2 // Remote em ambiente Unix/Linux
ISSRVUNIX
Reviso: 12/06/2003
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
ISSRVUNIX ( ) --> lisUnix
Retorno
Tipo Descrio
Lgico
Se .T. o servidor est sendo executado em ambiente Unix(r) ou Linux(r)
Se .F. o servidor est sendo executado em ambiente Windows(r)
Descrio
Informa se o servidor Advanced Protheus est sendo executado em ambiente UNIX ou
Linux.
MSCRC32
Reviso: 03/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Sintaxe
MSCRC32 ( < cString > ) --> nCRC
Parmetros
Argumento Tipo Descrio
cString Caracter
String de onde ser calculado um CRC32, garantido que
para a mesma string sempre se obter um mesmo nmero,
porm, no garantido que para strings diferentes, os
nmeros sejam sempre diferentes.
Retorno
Tipo Descrio
Numrico
Um nmero inteiro , com at 10 (dez) dgitos , correspondente ao CRC da
string informada como parmetro.
Descrio
Calcula um CRC de uma string. A funo MSCRC32() calcula um CRC de uma string
informada e retorna um nmero com esse clculo.
Note que strings iguais retornam CRC iguais, porm, nem sempre strings diferentes
retornam CRC diferentes.
MSCRC32STR
Reviso: 02/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Sintaxe
MSCRC32STR ( < cString > ) --> cCRC32
Parmetros
Argumento Tipo Descrio
cString Caracter
String a partir da qual ser calculado o CRC32.
garantido que para a mesma string sempre ser obtido um
mesmo CRC , mas no garantido que para strings
diferentes os CRCs sejam sempre diferentes.
Retorno
Tipo Descrio
Caracter Uma string com o CRC da string informada.
Descrio
MSCRC32STR() calcula um CRC de uma string informada , retornando uma string com
esse clculo.
Note que strings iguais retornam CRC iguais, porm nem sempre strings diferentes
retornam CRC diferentes.
RANDOMIZE
Reviso: 11/12/2003
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
RANDOMIZE ( < nMinimo > , < nMaximo > ) --> nAleatorio
Parmetros
Argumento Tipo Descrio
nMinimo Numrico Corresponde ao menor numero a ser gerado pela funo.
nMaximo Numrico
Corresponde ao maior nmero ( menos um ) a ser gerado
pela funo.
Retorno
Tipo Descrio
Numrico
Numero randmico , compreendido no intervalo entre (nMinimo) e
(nMaximo-1) : O numero gerado pode ser maior ou igual nMinimo e
menor ou igual a nMaximo-1 .
Descrio
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 .
SENDTOFORE
Reviso: 14/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Sintaxe
SENDTOFORE ( ) --> Nil
Retorno
Tipo Descrio
(NULO) Esta funo no retorna valor
Descrio
Esta funo torna a aplicao do Remote foreground na estao em que est sendo
executado.
Faz com que a janela ativa do Remote fique acima de todas as janelas de outras
aplicaes executadas na estao.
Extremamente dependente do sistema operacional em uso, as vezes pode falhar devido
ao sistema operacional no suportar o comando ou devido a carga excessiva do sistema,
o sistema operacional pode ignorar o comando.
XMLERROR
Reviso: 16/07/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
XMLERROR ( ) --> nXmlStatus
Retorno
Tipo Descrio
Caracter
Retorna o status da ultima operao de Criao de Objeto XML realizado
pelo comando CREATE oXml ...
Descrio
A funcao XmlError() retorna um status da execuo da ultima rotina de criao de
Objeto XML realizada pelo comando CREATE oXML. Podemos utilizar-nos das
constantes definidas no arquivo #INCLUDE "XmlxFun.CH" para realizar o tratamento
de erro. Vide tabelas de constantes abaixo :
----------------------------------------
Constante Valor
----------------------------------------
XERROR_ONLYFIRSTNODE -1
XERROR_SUCCESS 0
XERROR_FILE_NOT_FOUND 1
XERROR_OPEN_ERROR 2
XERROR_INVALID_XML 3
----------------------------------------
Funes de Banco de Dados
ALIAS
Reviso: 25/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ALIAS ( [ nAreaTrabalho ] ) --> cAlias
Parmetros
Argumento Tipo Descrio
nAreaTrabalho Numrico
<nAreaTrabalho> o nmero da rea de trabalho a ser
verificada.
Retorno
Tipo Descrio
Caracter
ALIAS() 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 ("").
Descrio
ALIAS() uma funao de banco de dados utilizada para determinar o alias da rea de
trabalho especificada. Alias o nome atribuido a uma rea de trabalho quando um
arquivo de banco de dados est em uso. O nome real atribuido o nome do arquivo de
banco de dados, ou um nome que foi explicitamente atribuido atravs da clusula
ALIAS do comando USE.

ALIAS() o inverso da funao SELECT(). ALIAS() retorna o alias atravs do nmero
da rea de trabalho, e SELECT() retorna o nmero da rea de trabalho atravs do alias.
BTVCANOPEN
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
BTVCANOPEN ( < cNome > , [ cIndice ] ) --> lRet
Parmetros
Argumento Tipo Descrio
cNome Caracter Nome da tabela a ser testada.
cIndice Caracter Nome do arquivo de ndice da tabela a ser testada.
Retorno
Tipo Descrio
(NULO)
Retorna falso se no foi possvel abrir a tabela a ser testada. Principais
motivos: No existe o arquivo da tabela ou
do ndice fisicamente; ou as definies da tabela ou ndice em questo no
foram encontradas.
Retorna verdadeiro se a tabela testada pode ser aberta.
Descrio
BTVCONOPEN() uma funo que verifica se a tabela definida pelo parmetro cNome
pode ser aberta e, se existir, o parmetro cIndice verifica, tambm, se o ndice pode ser
aberto. Para tanto, testado se os arquivos envolvidos existem fisicamente, caso
afirmativo, verificado se as definies envolvidas so encontradas nos arquivos do
DDF's.

Exemplo
// Este exemplo demonstra o uso tpico de BTVCanOpen().
Se no falhar, a tabela e o ndice testados sero abertos. Se falhar,
uma mensagem apresentada.

IF !BTVCanOpen("\dadosadv\aa1990.dat","\dadosadv\ind1.ind")
Messagebox("No possvel abrir a tabela testada","Erro", 0)
ELSE
Use "\dadosadv\aa1990.dat" SHARED NEW
OrdListAdd("\dadosadv\ind1.ind")
ENDIF
BTVCREATEDDFS
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
BTVCREATEDDFS ( < aTabelas > , < cDiretorio > ) --> lRet
Parmetros
Argumento Tipo Descrio
aTabelas Array Nomes das tabelas e os respectivos diretrios.
cDiretorio Caracter
Nome do diretrio (abaixo do root) onde sero criados os
novos DDF's.
Retorno
Tipo Descrio
(NULO)
Retorna falso se no conseguiu gerar os novos arquivos de definio.
Principais erros: RDD no Btrieve; diretrio no est dentro do
Protheus; no pode carregar as informaes de definio
ou no pode gravar os novos arquivos de definio.

Retorna verdadeiro se a transformao de definies ocorrida com
sucesso.
Descrio
BTVCREATEDDFS() uma funo que transforma as informaes armazenadas nos
arquivos DDF's para o padro utilizado por outras ferramentas, principalmente para
gerao de relatrios. Sendo que podem ser selecionadas apenas as tabelas de interesse
atravs do parmetro aTabelas.
Ex: aTabelas := {{"AA3990",
"C:\DADOS"},{"AA4990","C:\DADOS1"},{"AA5990"}}
Se o diretrio no for especificado, ser utilizado o diretrio definido no arquivo
FILE.BTV.
Os novos arquivos de definio, FILE.DDF, FIELD.DDF e INDEX.DDF, so
gerados no diretrio especificado pelo parmetro cDiretrio, se ele
for omitido, sero gerados no mesmo diretrio dos SXs.
Exemplo:
// Este exemplo demonstra o uso tpico de BTVCreateDDFs().
Se no falhar, sero gerados os novos arquivos de definio. Se falhar,
uma mensagem apresentada.
b:= {{"AA3990"}, {"SA1990", "c:\protheus507\dadosadv"}}
IF !BTVCreateDDFs(b,"\temp")
Messagebox("No foi possvel montar o array com os nomes das tabelas","Erro", 0)
ENDIF
BTVDROPIDXS
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
BTVDROPIDXS ( ) --> lRet
Retorno
Tipo Descrio
Lgico
Retorna Falso se no conseguiu apagar os ndices. Principais erros: RDD
no Btrieve, no achou as definies no DDF, o arquivo no est
exclusivo;
Retorna Verdadeiro se a deleo de ndices ocorrida com sucesso;
Descrio
BTVDropIdxs() apaga os ndices da tabela corrente, com exceo do ndice interno,
apenas se o mesmo for Btrieve e estiver aberto exclusivo. Para tanto ela executa os
seguintes passos:
- Fecha todos os ndices;
- Apaga as definies dos ndices nos arquivos do diretrio DDF;
- Apaga os ndices do arquivo da tabela corrente. Todos os ndices criados de
forma permanente ficam guardados na estrutura da tabela. Quando a tabela
for aberta, todos os ndices criados de forma permanente e o ndice interno
sero abertos tambm. Por isso, recomendada a criao de ndices de
forma temporria.

Exemplo:
// Este exemplo demonstra o uso tpico de BTVDropIdxs(). Se no falhar, os ndices so
apagados e o processo continua. Se falhar, uma mensagem apresentada.

USE Clientes SHARED NEW
IF !BTVDropIdxs()
Messagebox("No foi possvel deletar os ndices da tabela corrente","Erro",
0)
ENDIF
BTVTABLES
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
BTVTABLES ( ) --> aTables
Retorno
Tipo Descrio
Array
Retorna NIL se no conseguiu montar o array. Principais erros: RDD no
Btrieve ou no conseguiu recuperar as informaes corretamente do
arquivo FILE.BTV do DDFs.
Retorna um Array com a lista com os nomes das tabelas extradas do
DDF.
Descrio
BTVTABLES retorna array composto por nomes das tabelas definidas no DDF do
Protheus. Para tanto verifica todos os nomes das tabelas armazenados no arquivo
FILE.BTV do DDF e retorna um array com todos eles. Toda tabela criada possui o
nome acrescentado neste arquivo de definies.

Exemplo:
// Este exemplo demonstra o uso tpico de BTVTables(). Se no falhar, montado um
array com os nomes das tabelas e esses nomes so mostrados no servidor. Se falhar,
uma mensagem apresentada.

a:= BTVTables()
IF a=Nil
Messagebox("No foi possvel montar o array com os nomes das tabelas","Erro", 0)
ELSE
FOR i:= 1 to LEN(a)
ConOut(a[i])
NEXT
ENDIF
CTREEDELIDXS
Reviso: 26/08/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
CTREEDELIDXS ( ) --> lRet
Retorno
Tipo Descrio
Lgico
Retorna Falso se no conseguiu deletar os ndices. Principais
erros: RDD no Ctree, no fechou a tabela, no apagou o arquivo de
ndice ou no atualizou as informaes da tabela; no abriu a tabela
novamente.
Retorna Verdadeiro se a deleo de ndices ocorrida com sucesso.
Descrio
CtreeDelIdxs() apaga os ndices da tabela corrente, com exceo do ndice interno,
apenas se o mesmo for CTree e estiver exclusiva. Para tanto, ela executa os seguintes
passos:
- Fecha os ndices abertos;
- Fecha a tabela;
- Deleta os arquivos de ndice fisicamente;
- Atualiza as informaes da tabela, removendo os ndices de sua estrutura;
- Abre novamente a tabela.
Todos os ndices criados de forma permanente ficam guardados na estrutura
da tabela. Portanto, no adianta deletar os arquivos de ndices, pois quando a tabela for
aberta, todos os ndices criados de forma permanente e o ndice interno sero recriados
fisicamente (se no existirem); caso contrrio, a tabela no ser aberta. Por isso,
recomendada a criao de ndices de forma temporria.
Importante: Aps a remoo dos ndices a tabela ser posicionada no primeiro registro.
Exemplo:
// Este exemplo demonstra o uso tpico de CtreeDelIdxs(). Se no falhar,
os ndices so apagados e o processo continua. Se falhar, uma mensagem
apresentada.
USE Clientes SHARED NEW
IF !CtreeDelIdxs()
Messagebox('No foi possvel deletar os ndices da tabela corrente','Erro',0)
ENDIF
CTREEDELINT
Reviso: 22/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
CTREEDELINT ( < cNOME > ) --> lRet
Parmetros
Argumento Tipo Descrio
cNOME Caracter
Especifica o nome da tabela cujo ndice interno deve ser
deletado.
Retorno
Tipo Descrio
Lgico
Retorna Falso se no conseguiu deletar o ndice interno. Principais
erros: tabela no est dentro do diretrio do Protheus, no abriu a tabela ou
no deletou o arquivo de ndice interno.
Retorna Verdadeiro se a deleo do ndice interno ocorrida com sucesso.
Descrio
CTREEDELINT() apaga o ndice interno de tabela Ctree, estando a mesma fechada.
Para tanto, so executados os seguintes procedimentos:
- Abre a tabela especificada pelo parmetro cNome;
- Verifica o nome do arquivo do ndice interno na tabela;
- Fecha a tabela;
- Deleta fisicamente o arquivo do ndice interno.

A tabela deve ser apagada aps a chamada desta funo, pois a tabela CTree no pode
ser aberta sem ndice interno.
Exemplo:
// Este exemplo demonstra o uso tpico de CtreeDelInt(). Sendo que a tabela
'\dadosadv\sa1990.dtc' deve estar fechada. Se no falhar, o ndice interno apagado e o
processo continua. Se falhar, uma mensagem apresentada.
IF !CtreeDelInt('\dadosadv\sa1990.dtc')
Messagebox('No foi possvel deletar o ndice da tabela','Erro', 0)
ENDIF
fErase('\dadosadv\sa1990.dtc')
DBAPPEND
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBAPPEND ( [ lLiberaBloqueios ] ) --> uRet
Parmetros
Argumento Tipo Descrio
lLiberaBloqueios Lgico
Se o valor for .T., libera todos os registros bloqueados
anteriormente (locks). Se for .F., todos os bloqueios
anteriores so mantidos. Valor default: .T.
Retorno
Tipo Descrio
(NULO) Retorno nulo.
Descrio
DBAPPEND() acrescenta mais um registro em branco no final da tabela corrente. Se
no houver erro da RDD, o registro acrescentado e bloqueado.
DBCLEARALLFILTER
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLEARALLFILTER ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as
tabelas e depois limpa as condies de filtro de todas as tabelas.
DBCLEARALLFILTER
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLEARALLFILTER ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as
tabelas e depois limpa as condies de filtro de todas as tabelas.
DBCLEARFILTER
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLEARFILTER ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
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.
DBCLEARINDEX
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLEARINDEX ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
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.
DBCLOSEALL
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLOSEALL ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCLOSEALL() salva as atualizaes pendentes, libera todos os registros
bloqueados e fecha todas as tabelas abertas (reas de trabalho) como se
chamasse DBCLOSEAREA para cada rea de trabalho.

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
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCLOSEAREA ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCLOSEAREA() salva as atualizaes pendentes na tabela corrente, libera todos os
registros bloqueados e fecha a tabela corrente (rea de trabalho).
Seu funcionamento semelhante ao comando CLOSE e oposto funo
DBUSEAREA e ao comando USE.
DBCOMMIT
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCOMMIT ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCOMMIT() salva em disco todas as atualizaes pendentes na rea de
trabalho corrente.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCOMMIT para salvar todas as
alteraes realizadas na rea de trabalho atual.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCOMMITALL ( ) --> uRet
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCOMMITALL() salva em disco todas as atualizaes pendentes em todas
as reas de trabalho.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCOMMITALL para salvar todas
as alteraes realizadas nas reas de trabalho abertas no momento.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCREATE ( < cNOME > , < aESTRUTURA > , [ @cDRIVER ] ) --> uRet
Parmetros
Argumento Tipo Descrio
cNOME Caracter
Nome do arquivo da tabela a ser criada (abaixo do
"RootPath").
aESTRUTURA Array
Lista com as informaes dos campos para ser criada a
tabela.
cDRIVER Caracter
Nome do RDD a ser utilizado para a criao da tabela. Se
for omitido ser criada com o corrente.
Retorno
Tipo Descrio
Caracter Nenhum
Descrio
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}, como visto no exemplo a seguir.

Exemplo:
// Este exemplo mostra como se pode criar novo arquivo de tabela 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}}
DBCREATE("\teste\amigos.xxx",aEstrutura)
// Cria a tabela com o RDD corrente
USE "\teste\amigos.xxx" VIA "DBFCDX" NEW
DBCREATEINDEX
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBCREATEINDEX ( < cNOME > , < cEXPCHAVE > , [ bEXPCHAVE ] , [ lUNICO
] ) --> uRet
Parmetros
Argumento Tipo Descrio
cNOME Caracter Nome do arquivo de ndice a ser criado.
cEXPCHAVE Caracter
Expresso das chaves do ndice a ser criado na forma de
string.
bEXPCHAVE Code-Block
Expresso das chaves do ndice a ser criado na forma
executvel.
lUNICO Lgico Cria ndice como nico (o padro .F.).
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBCREATEINDEX() utilizada para criar um novo arquivo de ndice com o nome
especificado atravs do primeiro parmetro, sendo que se o mesmo existir deletado e
criado o novo. Para tanto so executados os passos a seguir:
- Salva fisicamente as alteraes ocorridas na tabela corrente;
- Fecha todos os arquivos de ndice abertos;
- Cria o novo ndice;
- Seta o novo ndice como a ordem corrente;
- Posiciona a tabela corrente no primeiro registro do ndice.
Com exceo do RDD Ctree, a tabela corrente no precisa estar aberta em modo
exclusivo para a criao de ndice, pois na criao de ndices no Ctree alterada a
estrutura da tabela, precisando para isto a tabela estar aberta em modo exclusivo.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBDELETE ( ) --> uRet
Retorno
Tipo Descrio
Caracter Nenhum
Descrio
DBDELETE() marca o arquivo corrente como deletado. Para filtrar os arquivos
marcados pode-se utilizar o comando SET DELETED e para delet-los fisicamente
pode-se utilizar o comando PACK.

Exemplo:
// Este exemplo demonstra como se pode utilizar a funo DBDELETE() para marcar
alguns registros como deletados e o PACK para delet-los fisicamente.
USE Clientes NEW
DBGOTO(100)
DBDELETE()
DBGOTO(105)
DBDELETE()
DBGOTO(110)
DBDELETE()
PACK
DBEVAL
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBEVAL ( < bBLOCO > , [ bFORCOND ] , [ bWHILECOND ] , [ nPROXREGS ] , [
nRECNO ] , [ lRESTANTE ] ) --> uRET
Parmetros
Argumento Tipo Descrio
bBLOCO Code-Block
Expresso na forma executvel a ser resolvida para cada
registro processado.
bFORCOND Code-Block
Expresso na forma executvel a ser resolvida para
verificar se o registro em questo est dentro do escopo
definido.
bWHILECOND Code-Block
Expresso na forma executvel a ser resolvida para
verificar at qual registro ser processado (at o bloco
retornar .F.).
nPROXREGS Numrico
Nmero de registros a ser processado a partir do registro
corrente.
nRECNO Numrico
Identificao de determinado registro a ser resolvida a
expresso (recno).
lRESTANTE Lgico Processa o restante dos registro.
Retorno
Tipo Descrio
Caracter Retorno nulo.
Descrio
DBEVAL() utilizada para executar uma expresso definida pelo bloco
de cdigo do primeiro parmetro para cada registro que est dentro do
escopo definido atravs dos blocos de condio de "for" e "while".
O nmero de registros a ser executado ser definido com o parmetro
nProxRegs ou se setado o parmetro lRestante sero executados todos
os registros a partir do registro corrente at o final da tabela corrente.
Se for especificado o parmetro nRecno apenas o registro com o recno especificado ser
processado. Se forem omitidos os blocos de "for" e "while",
os mesmos sero considerados .T. como padro, esto assim todos os registros dentro
do escopo. Se o parmetro lRestante for omitido a tabela inicia o processamento dos
registros a partir do topo da tabela, caso contrrio sero processados os registros a partir
do posicionamento corrente da tabela.

Exemplo:
// Este exemplo mostra como se pode usar o DBEVAL para contar quantos registros
esto dentro do escopo especificado em toda a tabela, pois como o parmetro lRestante
foi omitido a tabela ir para o topo antes de iniciar a processar os registros. Supondo
que a tabela est sobre um ndice no campo idade, sero processados registros com o
Nome cuja ordem alfabtica maior que "FFFFF" e at encontrar algum registro de
idade igual a 40:
USE Cliente VIA "DBFCDX" NEW
LOCAL nCount := 0;
DBGOTO(100)
DBEVAL( {|| nCount++}, {|| Nome > "FFFFF"}, {|| Idade < 40})

// Este exemplo mostra como se pode usar o DBEVAL para contar quantos registros
esto dentro do escopo especificado (como o exemplo anterior) a partir do registro atual
(100):
USE Cliente VIA "DBFCDX" NEW
LOCAL nCount := 0;
DBGOTO(100)
DBEVAL( {|| nCount++}, {|| Nome > "FFFFF"}, {|| Idade < 40},,,.T.)

// Este exemplo mostra como se pode usar o DBEVAL para colocar numa varivel um
nome inicial que est definido em um registro de recno definido (100):
USE Cliente VIA "DBFCDX" NEW
LOCAL cNomeIni := ""
DBEVAL( {|| cNomeIni := Nome},,,,100)

// Este exemplo mostra como se pode usar o DBEVAL para verificar qual o recno do
dcimo registro a partir do corrente dentro do escopo definido:
USE Cliente VIA "DBFCDX" NEW
LOCAL nRecno := 0;
DBGOTO(100)
DBEVAL( {|| nRecno := RECNO()}, {|| Nome > "FFFFF"}, {|| Idade < 40},10,,.T.)
DBF
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBF ( ) --> cAlias
Retorno
Tipo Descrio
Caracter
Retorna o Alias corrente. Caso no exista Alias corrente retorna "" (String
vazia).
Descrio
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.

Exemplo:
// Este exemplo mostra como o DBF corrente pode ser mostrado para o usurio.
dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
MessageBox("O Alias corrente : "+DBF(),"Alias", 0) //Resultado: "O Alias corrente :
SSS"
DBFIELDINFO
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBFIELDINFO ( < nINFOTIPO > , < nCAMPO > ) --> xINFO
Parmetros
Argumento Tipo Descrio
nINFOTIPO Numrico
Tipo de informao a ser verificada (DBS_DEC,
DBS_LEN e DBS_TYPE).
nCAMPO Numrico Posio do campo a ser verificado.
Retorno
Tipo Descrio
(Qualquer)
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).
Descrio
DBFIELDINFO() utilizada para obter informaes sobre determinado campo da
tabela corrente. O tipo de informao (primeiro argumento) escolhido de acordo com
as constantes abaixo:
DBS_DEC - Nmero de casas decimais (tipo numrico)
DBS_LEN - Tamanho (tipo numrico)
DBS_TYPE - Tipo (tipo caracter)
A posio do campo no leva em considerao os campos internos do Protheus (recno e
deleted).
Exemplo:
// Este exemplo demonstra como se pode utilizar o DBFIELDINFO para obter as
informaes do primeiro campo da tabela Clientes.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBFILTER ( ) --> cEXPFILTRO
Retorno
Tipo Descrio
Caracter
Retorna a expresso do filtro ativo na rea de trabalho atual. Caso no
exista filtro ativo retorna "" (String vazia).
Descrio
DBFILTER() utilizada para verificar a expresso de filtro ativo na rea de trabalho
corrente.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBFILTER para verificar a
expresso do filtro corrente.
USE Cliente INDEX Ind1 NEW
SET FILTER TO Nome > "Jose"
DBFILTER() // retorna: Nome > "Jose"
SET FILTER TO Num < 1000
DBFILTER() // retorna: Num < 1000
DBGOBOTTOM
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBGOBOTTOM ( ) --> uRET
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBGOBOTTOM() utilizada para posicionar a tabela corrente no ltimo registro
lgico. A seqncia lgica depende da ordem e do filtro ativo sobre a tabela corrente,
portanto o ltimo registro lgico pode no ser o ltimo registro fsico.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBGOBOTTOM para posicionar no
ltimo registro fsico.
USE Cliente
DBGOBOTTOM() // Posiciona no ltimo registro fsico, pois no h ordem ativa

// Este exemplo demonstra como se pode utilizar o DBGOBOTTOM para posicionar no
ltimo registro lgico.
USE Cliente INDEX Ind1 NEW
DBGOBOTTOM() // Posiciona no ltimo registro lgico (ltimo registro na seqncia
gerada pelo ndice)
DBGOTOP
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBGOTOP ( ) --> uRET
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBGOTOP() utilizada para posicionar a tabela corrente no primeiro registro lgico. A
seqncia lgica depende da ordem e do filtro ativo sobre a tabela corrente, portanto o
primeiro registro lgico pode no ser o primeiro registro fsico.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBGOBOTOP para posicionar no
primeiro registro fsico.
USE Cliente
DBGOTOP() // Posiciona no primeiro registro fsico, pois no h ordem ativa

// Este exemplo demonstra como se pode utilizar o DBGOTOP para posicionar no
primeiro registro lgico.
USE Cliente INDEX Ind1 NEW
DBGOTOP() // Posiciona no primeiro registro lgico (primeiro registro na segncia
gerada pelo ndice)
DBGOTO
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBGOTO ( ) --> uRET
Retorno
Tipo Descrio
(NULO) Retorno nulo.
Descrio
DBGOTO() utilizado para posicionar a tabela corrente em determinado registro,
segundo a ordem fsica (seqncia sobre o recno).

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBGOTO para posicionar a tabela
corrente em determinado registro.
USE Cliente INDEX Ind1 NEW
DBGOTO(100) // Posiciona no registro de recno 100
DBINFO
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBINFO ( < nINFOTIPO > ) --> xINFO
Parmetros
Argumento Tipo Descrio
nINFOTIPO Numrico Tipo de informao a ser verificada.
Retorno
Tipo Descrio
(Qualquer)
Informao da Tabela Informao requisitada pelo usurio (o tipo depende
da informao requisitada). Se no houver tabela corrente retorna NIL.
Descrio
DBINFO() utilizada para obter informaes sobre a tabela corrente. O tipo de
informao (primeiro argumento) escolhido de acordo com as constantes abaixo:
DBI_GETRECSIZE - Tamanho do registro em nmero de bytes similar a RECSIZE
(tipo numrico)
DBI_TABLEEXT - Extenso do arquivo da tabela corrente (tipo caracter)
DBI_FULLPATH - Nome da tabela corrente com caminho completo (tipo caracter)
DBI_BOF - Verifica se est posicionada no incio da tabela similar a BOF (tipo lgico)
DBI_EOF - Verifica se est posicionada no final da tabela similar a EOF (tipo lgico)
DBI_FOUND - Verifica se a tabela est posicionada aps uma pesquisa similar a
FOUND (tipo lgico)
DBI_FCOUNT - Nmero de campos na estrutura da tabela corrente similar a FCOUNT
(tipo numrico)
DBI_ALIAS - Nome do Alias da rea de trabalho corrente similar a ALIAS (tipo
caracter)
DBI_LASTUPDATE - Verifica a data da ltima modificao similar a LUPDATE (tipo
data)

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBINFO para obter as informaes
da tabela corrente (Clientes).
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.
DBORDERINFO
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBORDERINFO ( < nINFOTIPO > ) --> xINFO
Parmetros
Argumento Tipo Descrio
nINFOTIPO Numrico Nome do arquivo de ndice.
Retorno
Tipo Descrio
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.
Descrio
DBORDERINFO() utilizada para obter informaes sobre determinada ordem.
A especificao da ordem pode ser realizada atravs de seu nome ou sua
posio dentro da lista de ordens, mas se ela no for especificada sero
obtidas informaes da ordem corrente.
O tipo de informao (primeiro argumento) escolhido de acordo com
as constantes abaixo:
DBOI_BAGNAME - Nome do arquivo de ndice ao qual a ordem pertence (tipo
caracter).
DBOI_FULLPATH - Nome do arquivo de ndice (com seu diretrio) ao qual a ordem
pertence (tipo caracter)
DBOI_ORDERCOUNT - Nmero de ordens existentes no arquivo de ndice
especificado

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBORDERINFO para obter
informaes sobre o nome do arquivo de ndice da ordem corrente.
DBORDERINFO(DBOI_BAGNAME) // retorna: Ind
DBORDERINFO(DBOI_FULLPATH) // retorna: C:\AP6\Teste\Ind.cdx
DBORDERNICKNAME
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBORDERNICKNAME ( < cAPELIDO > ) --> lRET
Parmetros
Argumento Tipo Descrio
cAPELIDO Caracter Nome do apelido da ordem a ser setada.
Retorno
Tipo Descrio
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.
Descrio
DBORDERNICKNAME() utilizada para selecionar a ordem ativa atravs de seu
apelido. Esta ordem a responsvel seqncia lgica dos registros da tabela corrente.

Exemplo:
//Este exemplo demonstra como se pode utilizar o DBORDERNICKNAME para setar
nova ordem.
USE Cliente NEW
SET INDEX TO Nome, Idade
IF !DBORDERNICKNAME("IndNome")
Messagebox("Registro no encontrado","Erro", 0)
ENDIF
DBRECALL
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBRECALL ( ) --> uRET
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
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.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBRECALL para retornar o estado
do registro atual para normal.
USE Cliente
DBGOTO(100)
DBDELETE()
DELETED() // Retorna: .T.
DBRECALL()
DELETED() // Retorna: .F.

// Este exemplo demonstra como se pode utilizar o DBRECALL para desfazer todas as
delees da tabela corrente.
USE Cliente
DBGOTOP()
WHILE !EOF()
DBRECALL()
DBSKIP()
ENDDO
DBRECORDINFO
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO
Parmetros
Argumento Tipo Descrio
nINFOTIPO Numrico Tipo de informao a ser verificada.
nREGISTRO Numrico Nmero do registro a ser verificado.
Retorno
Tipo Descrio
(Qualquer)
No h tabela corrente ou registro invlido.
Informao do Registro. Informao requisitada
pelo usurio (o tipo depende da informao requisitada).
Descrio
DBRECORDINFO() utilizada para obter informaes sobre o registro especificado
pelo segundo argumento (recno) da tabela corrente, se esta informao for omitida ser
verificado o registro corrente. O tipo de informao
(primeiro argumento) escolhido de acordo com as constantes abaixo:
DBRI_DELETED - Estado de deletado similar a DELETED (tipo lgico)
DBRI_RECSIZE - Tamanho do registro similar a RECSIZE (tipo numrico)
DBRI_UPDATED - Verifica se o registro foi alterado e ainda no foi atualizado
fisicamente similar a UPDATED (tipo lgico)

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBRECORDINFO para se obter as
informaes sobre registros da tabela corrente.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBREINDEX ( ) --> uRET
Retorno
Tipo Descrio
(NULO) Nenhum
Descrio
DBREINDEX() reconstri todos os ndices da rea de trabalho corrente e posiciona as
tabelas no primeiro registro lgico.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBREINDEX para reconstruir os
ndices depois que um novo ndice foi gerado.
USE Clientes NEW
DBSETINDEX("IndNome")
DBREINDEX()
DBRLOCK
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBRLOCK ( [ nREGISTRO ] ) --> lRET
Parmetros
Argumento Tipo Descrio
nREGISTRO Numrico Nmero do registro a ser bloqueado.
Retorno
Tipo Descrio
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
Descrio
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.

Exemplo
// Este exemplo mostra duas variaes do uso de DBRLOCK.
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBRLOCKLIST ( ) --> aRET
Retorno
Tipo Descrio
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.
Descrio
DBRLOCKLIST() utilizada para verificar quais registros esto locados na tabela
corrente. Para tanto, retornada uma tabela unidimensional com os nmeros dos
registros.

Exemplo:
// Este exemplo mostra como utilizada a funo DBRLOCKLIST para verificar quais
registros esto bloqueados na tabela corrente:
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
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBRUNLOCK ( [ nREGISTRO ] ) --> uRET
Parmetros
Argumento Tipo Descrio
nREGISTRO Numrico Nmero do registro a ser desbloqueado.
Retorno
Tipo Descrio
(NULO) Sem retorno.
Descrio
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.

Exemplo:
// Este exemplo mostra duas variaes do uso de DBRUNLOCK.
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
DBSEEK
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSEEK ( < xEXP > , [ lSOFTSEEK ] , [ lULTIMO ] ) --> lRET
Parmetros
Argumento Tipo Descrio
xEXP (Qualquer)
Valor de chave a ser encontrado do tipo caracter (todos os
tipos de expresso de ndice com exceo do ndice com
apenas um campo do tipo numrico).
lSOFTSEEK Lgico
Posiciona no primeiro registro com expresso de chave
maior que o valor procurado. O padro .F.
lULTIMO Lgico
Procura a ltima ocorrncia do valor procurado. O padro
.F.
Retorno
Tipo Descrio
Lgico
Retorna Falso se no foi encontrado nenhum registro com o valor
especificado.
Retorna Verdadeiro se foi encontrado um registro com o valor
especificado
Descrio
DBSEEK() utilizada para encontrar um registro com determinado valor da expresso
de chave de ndice. Antes da chamada do DBSEEK deve-se certificar de que existe uma
ordem ativa no momento com os campos que se deseja pesquisar o valor. Se a
expresso possuir apenas uma campo numrico, o primeiro parmetro deve ser do tipo
numrico, mas nos demais casos deve-se utilizar um valor do tipo caracter para este
parmetro (mesmo se forem apenas dois campos numricos ou do tipo data).
Quando o segundo parmetro for especificado como .T. (softseek), mesmo
que a expresso pesquisada no encontrar nenhum registro com este valor,
a tabela ser posicionada no prximo valor maior que o especificado no
primeiro parmetro, mas mesmo posicionando no prximo valor esta funo
retornar .F. (pois no encontrou).
Quando no for especificado este valor ou estiver .F. e falhar o valor de pesquisa, a
tabela ser posicionada em LASTREC + 1 e ser setada a flag de EOF.
Se o terceiro parmetro for especificado com valor .T. a funo posiciona a tabela no
ltimo registro com o valor procurado, caso no seja especificado
ou for .F., ser posicionada na primeira ocorrncia.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSEEK para busca de valores
numricos.
USE Clientes NEW
ORDLISTADD ("/teste/ind1.cdx") // Expresso Num (campo numrico)
DBSEEK(100) // Retorna: .F.
EOF() // Retorna: .T.
DBSEEK(100,.T.) // Retorna: .F.
EOF() // Retorna: .F. (pois o softseek posicionou no prximo registro)

// Este exemplo demonstra como se pode utilizar o DBSEEK para percorrer todos os
registros de Clientes com o nome joao e vencimentos a partir de janeiro de 2001.
USE Clientes NEW
ORDLISTADD ("/teste/ind2.cdx") // Expresso Nome+Venc (campo caracter + data)
DBSEEK("joao200101",.T.) // Procura a primeira ocorrncia de Nome "joao" e
vencimento maior que Janeiro de 2001
WHILE !EOF() .AND. Nome == "joao"
DBSKIP()
ENDDO
DBSETDRIVER
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSETDRIVER ( [ cNOVORDD ] ) --> cULTIMORDD
Parmetros
Argumento Tipo Descrio
cNOVORDD Caracter Novo nome do RDD a ser definido como padro.
Retorno
Tipo Descrio
Caracter Nome do RDD padro corrente
Descrio
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.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSETDRIVER para alterar o valor
do RDD padro.
DBSETDRIVER("CTREECDX") // Retorna: DBFCDX
DBSETDRIVER() // Retorna: CTREECDX
DBSETFILTER
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSETFILTER ( < @bCONDICAO > , < @cCONDICAO > ) --> uRET
Parmetros
Argumento Tipo Descrio
bCONDICAO Code-Block Expresso do filtro na forma executvel.
cCONDICAO Caracter Expresso do filtro na forma de string.
Retorno
Tipo Descrio
(NULO) Sem retorno.
Descrio
DBSETFILTER utilizada para setar um filtro nos registros da tabela corrente
especificado atravs do bloco de cdigo no primeiro parmetro. Quando um registro no
est dentro do filtro setado ele continua existindo fisicamente, mas no logicamente (nas
funes de manipulao de banco de dados como DBGOTOP, DBSEEK, DBSKIP, etc).

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSETFILTER para filtrar todos os
clientes com menos de 40 anos.
USE Cliente NEW
DBSETFILTER( {||Idade < 40}, "Idade < 40" )
DBGOTOP()
DBSETINDEX
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSETINDEX ( < @cARQINDICE > ) --> uRET
Parmetros
Argumento Tipo Descrio
cARQINDICE Caracter Nome do arquivo de ndice, com ou sem diretrio
Retorno
Tipo Descrio
(NULO) Sem retorno.
Descrio
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 se utilizar arquivos de extenso padro do RDD, este dado pode ser omitido no
primeiro parmetro, mas caso contrrio deve ser especificado.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSETINDEX para acrescentar
novos ndices lista de ordens.
USE Cliente NEW
DBSETINDEX("Ind1")
DBSETINDEX("\teste\Ind2.cdx")
DBSETNICKNAME
Reviso: 30/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSETNICKNAME ( < cINDICE > , [ cAPELIDO ] ) --> cAPELIDO
Parmetros
Argumento Tipo Descrio
cINDICE Caracter Nome da ordem que deve receber o apelido.
cAPELIDO Caracter Nome do apelido da ordem a ser setada.
Retorno
Tipo Descrio
Caracter
Retorna "" (String vazia) se no conseguiu encontrar a ordem
especificada, no conseguiu setar o apelido ou no havia apelido.
Retorna o apelido corrente.
Descrio
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.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSETNICKNAME para setar um
novo apelido e verificar qual o apelido atual.
USE Cliente NEW
DBSETNICKNAME("IndNome") // retorna: ""
DBSETNICKNAME("IndNome","NOME") // retorna: ""
DBSETNICKNAME("IndNome") // retorna: "NOME"
DBSETORDER
Reviso: 09/04/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DBSETORDER ( < nOrdem > ) --> NIL
Parmetros
Argumento Tipo Descrio
nOrdem Numrico
nOrdem corresponde ao nmero da posio da ordem na
lista de ordens ativas.
Retorno
Tipo Descrio
(NULO) Esta funo sempre retorna NIL.
Descrio
Esta funo utilizada para selecionar a ordem ativa da rea de trabalho. Esta ordem a
responsvel seqncia lgica dos registros da tabela corrente.

Exemplo:

// Este exemplo demonstra como se pode utilizar o DBSETORDER
para selecionar a ordem corrente.

USE Cliente NEW
SET INDEX TO Nome,Cep
DBSETORDER(2)


Caso seja setada a ordem 0 , a tabela corrente na area de trabalho ser colocada na
ordem natural , isto , a ordem na qual os registros foram acrescentados, porm os
indexadores so mantidos abertos. Vale salientar que , quando alteramos a ordem atual
de uma determinada tabela , o registro atual no desposicionado.
DBSKIP
Reviso: 07/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSKIP ( [ NREGISTROS ] ) --> NIL
Parmetros
Argumento Tipo Descrio
NREGISTROS Numrico
Nmero de registros a ser deslocado a partir do corrente.
Se for positivo, desloca em direo ao final da tabela. Se
for negativo, ao incio da tabela. Valor default: 1.
Retorno
Tipo Descrio
Caracter Sem retorno.
Descrio
Desloca para outro registro na tabela corrente. Esta funo utilizada para deslocar para
outro registro a partir do registro atual. O deslocamento lgico, ou seja, leva em
considerao ordem no ndice e tambm filtro (se existir).
Caso passe do incio da tabela, posiciona no primeiro registro e seta BOF. Caso passe
do final da tabela, posiciona no registro "LastRec()+1" e seta EOF. Neste ltimo caso,
se a RDD for TopConnect, o Recno() retornado ser por conveno "LastRec() + 5000".
DBSTRUCT
Reviso: 08/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBSTRUCT ( ) --> aStruDB
Retorno
Tipo Descrio
Array
Array com a estrutura dos campos. Cada elemento um subarray contendo
Nome, Tipo, Tamanho e Decimais.
Descrio
Retorna a estrutura da tabela corrente. Esta funo utilizada para verificar a estrutura
da tabela corrente da mesma forma que utilizada para criar a tabela com a funo
DBCREATE. Para isto ela cria um array para gravar as informaes e as retorna.

Veja Tambm
AFields( )
DBUNLOCK
Reviso: 08/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBUNLOCK ( ) --> NIL
Retorno
Tipo Descrio
Caracter Sem retorno.
Descrio
Retira bloqueios de registros e de arquivo da tabela corrente.
DBUNLOCKALL
Reviso: 08/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DBUNLOCKALL ( ) --> NIL
Retorno
Tipo Descrio
Caracter Sem retorno.
Descrio
Retira o bloqueio de todos os registros e 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.
DELETED
Reviso: 09/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DELETED ( ) --> lDeleted
Retorno
Tipo Descrio
Lgico
Se for .T. o registro tem a marca de excludo, se for .F., o registro no tem
a marca (ou no h rea em uso).
Descrio
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.

Exemplo
// Este exemplo verifica se determinado registro est deletado, caso positivo, mostra
uma mensagem:
USE "\DADOSADV\AA1990.DBF" SHARED NEW
DBGOTO(100)
IF DELETED()
Messagebox("O registro atual foi deletado","Erro", 0)
ENDIF
FIELDBLOCK
Reviso: 12/06/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FIELDBLOCK ( < cCampo > ) --> bBloco
Parmetros
Argumento Tipo Descrio
cCampo Caracter Nome do campo a ser retornado o bloco de cdigo.
Retorno
Tipo Descrio
Code-Block Bloco de cdigo para o campo especificado na tabela corrente.
Descrio
Retorna um bloco de cdigo para um campo determinado da tabela corrente. Esta
funo utilizada para retornar um bloco de cdigo executvel com o campo
especificado. Quando o bloco resultante executado sem parmetro, recupera o valor
armazenado no campo. Quando executado com um valor, seta este valor no
determinado campo.
Portanto, o bloco retornado similar a: &("{|Valor| IF(Valor==NIL, Campo,
Campo:=Valor)}")
Sendo: Campo = parmetro da funo FIELDBLOCK()
Valor = valor executado no bloco de cdigo

Exemplo
// Este exemplo mostra como se pode usar o FIELDBLOCK para criar o bloco de
cdigo para o campo 'Nome' da tabela corrente na varivel bBloco:

USE Cliente ALIAS Cliente NEW VIA "DBFCDX"
bBloco := FIELDBLOCK("NOME")
HEADER
Reviso: 03/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
HEADER ( ) --> nBytes
Retorno
Tipo Descrio
Caracter
HEADER() retorna a quantidade de bytes no cabealho do arquivo de
banco de dados corrente na forma de um valor numrico inteiro.
Descrio
HEADER() uma funao de tratamento de banco de dados utilizado com LASTREC(),
RECSIZE(), e DISKSPACE() para criar rotinas de cpia de segurana de arquivos.

O padrao que a funao HEADER() opere na rea de trabalho correntemente
selecionada. Pode-se faz-la operar em uma rea de trabalho nao selecionada se esta for
especificada em uma expresso alias.
LUPDATE
Reviso: 19/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
LUPDATE ( ) --> dLastUpdate
Retorno
Tipo Descrio
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 ("")) .
Descrio
Verifica a data da ltima modificao da tabela corrente. Esta funo verifica qual a
data da ltima modificao e fechamento da tabela corrente, caso no exista tabela
corrente retornada uma data em branco.

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
SELECT
Reviso: 24/02/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
SELECT ( [ cAlias ] ) --> nAreaTrabalho
Parmetros
Argumento Tipo Descrio
cAlias Caracter <cAlias> o nome da rea de trabalho a ser verificada.
Retorno
Tipo Descrio
Numrico
SELECT() retorna a rea de trabalho do alias especificado na forma de um
valor numrico inteiro.
Descrio
SELECT() uma funao de tratamento de bancos de dados que 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.
Exemplos

* O exemplo a seguir ilustra como utilizar SELECT() para determinar qual rea de
trabalho o comando USE...NEW selecionou:
USE Sales NEW
SELECT 1
conout(SELECT("Sales")) // Resulta: 4
* Para re-selecionar o valor retornado da funao SELECT(), use o comando SELECT
com a sintaxe SELECT (<idVarMem>), desta forma:
USE Sales NEW
nWorkArea := SELECT()
USE Customer NEW
SELECT (nWorkArea)
TCGENQRY
Reviso: 25/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
TCGENQRY ( [ xPar1 ] , [ xPar2 ] , < cQuery > ) --> ""
Parmetros
Argumento Tipo Descrio
xPar1 (Qualquer)
Parmetros apenas para compatibilizao. No tem
funo
xPar2 (Qualquer)
Parmetros apenas para compatibilizao. No tem
funo
cQuery Caracter Contm a expresso da query que ser aberta.
Retorno
Tipo Descrio
Caracter Sempre retorna uma string vazia.
Descrio
Define a execuo de uma Query. Esta funo determina que a prxima chamada
DBUseArea ser a abertura
de uma Query e no de tabela.

Exemplo

cQuery := 'SELECT X2_CHAVE CHAVE, R_E_C_N_O_ RECNO from SX2990'
cQuery := ChangeQuery(cQuery)

dbUseArea(.T., 'TOPCONN', TCGenQry(,,cQuery),'TRB', .F., .T.)
while !Eof()
conout(TRB->CHAVE)
dbSkip()
enddo
dbCloseArea()
USED
Reviso: 09/07/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
Verses Anteriores

Sintaxe
USED ( ) --> lDbfUsed
Retorno
Tipo Descrio
Lgico
USED() retorna verdadeiro (.T.) caso haja um arquivo de banco de dados
em uso; caso contrrio, retorna falso (.F.).
Descrio
USED() uma funao de tratamento de banco de dados utilizada para determinar se h
um arquivo de banco de dados em uso em uma rea de trabalho especfica. O padrao
que USED() opere na rea de trabalho correntemente selecionada. Pode-se faz-la
operar em uma rea de trabalho nao selecionada se esta for especificada em uma
expressao alias.
__DBPACK
Reviso: 09/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
__DBPACK ( ) --> URET
Retorno
Tipo Descrio
(NULO) Retorno nulo.
Descrio
Remove todos os registros com marca de excludo da tabela. Esta funo apaga
(fisicamente) todos os registros "excludos" da tabela corrente.

Exemplo
// Este exemplo demonstra como se pode utilizar a funo DBDELETE() para marcar
alguns registros como deletados e o comando PACK para delet-los fisicamente.

USE Clientes NEW
DBGOTO(100)
DBDELETE()
DBGOTO(105)
DBDELETE()
DBGOTO(110)
DBDELETE()

// Se a excluso for confirmada:
__DBPACK()
Funes de disco e arquivos.
ADIR
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ADIR ( [ ] , [ ] , [ ] , [ ] , [ ] , [ ] ) --> nArquivos
Parmetros
Argumento Tipo Descrio
<cEspecArq> Caracter
<cEspecArq> a especificaao dos arquivos a serem
incluidos na pesquisa do diretrio padrao. uma
especificaao de arquivo padrao que pode incluir os
caracteres coringa do tipo * e ?, bem como referncia a
diretrio e path. Caso nao seja especificado, o padrao
assumido *.*.
<aNomesArq> Array
<aNomesArq> o vetor a ser preenchido com os nomes de
arquivo que correspondem a <cEspecArq>. Cada elemento
contm o nome do arquivo e extensao na forma de uma
cadeia de caracteres em letras maisculas.
<aTamanhos> Array
<aTamanhos> o vetor a ser preenchido com os tamanhos
dos arquivos correspondentes no vetor <aNomesArq>.
Cada elemento numrico.
<aDatas> Array
<aDatas> o vetor a ser preenchido com as datas dos
arquivos correspondentes no vetor <aNomesArq>. Cada
elemento uma data.
<aHoras> Array
<aHoras> o vetor a ser preenchido com as horas dos
arquivos correspondentes no vetor <aNomesArq>. Cada
elemento preenchido contm uma cadeia de caracteres da
forma: hh:mm:ss.
<aAtributos> Array
<aAtributos> o vetor a ser preenchido com os atributos
dos arquivos correspondentes no vetor <aFilenames>.
Cada elemento uma cadeia de caracteres. Caso
<aAtributos> seja especificado, os arquivos de diretrio,
sistema, e escondidos sao incluidos, assim como os
arquivos normais. Se <aAtributos> nao for especificado,
somente os arquivos normais sao incluidos.
Retorno
Tipo Descrio
Numrico
ADIR() retorna a quantidade de arquivos que correspondem ao esqueleto
de diretrio especificado.
Descrio
ADIR() uma funao de tratamento de vetor que executa duas operaoes bsicas.
Primeiro, ele retorna a quantidade de arquivos que correspondem especificaao de
arquivo. Segundo, preenche uma srie de vetores com nomes de arquivos, tamanhos,
datas, horas e atributos.

ADIR() uma funao de compatibilidade e portanto desaconselhada. Ele est superado
pela funao DIRECTORY(), que retorna todas as informaoes de arquivo em um vetor
multi-dimensional.

OBSERVAO

Diretrios: Caso o argumento <aAtributos> seja especificado e <cEspecArq> seja
especificado como *.*, os diretrios serao incluidos em <aNomesArq>. No vetor
<aAtributos>, os diretrios sao indicados com um valor atributo de "D." Se ADIR() for
executado dentro de um subdiretrio, as duas primeiras entradas do vetor
<aNomesArq> sao "." e "..", os "alias" dos diretrios corrente e raiz. A data e hora da
ltima atualizaao sao informadas para diretrios, mas o tamanho de um diretrio
sempre zero.
CPYS2T
Reviso: 19/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento Tipo Descrio
cOrigem Caracter
Nome(s) dos arquivos a serem copiados, aceita apenas
arquivos
no servidor, WildCards ( * e ? ) so aceitos normalmente.
cDestino Caracter Diretrio com o destino dos arquivos no Client ( Remote )
lCompacta Lgico
Indica se a cpia deve ser feita compactando o arquivo
antes do envio.
Retorno
Tipo Descrio
Lgico
lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em
caso de falha na cpia.
Descrio
Copia um arquivo, do servidor para o cliente ( Remote ). .Caso a compactao seja
habilitada (lCompacta ), os dados sero transmitidos de maneira compactada e
descompactados antes do uso.

Exemplo :

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

CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. ) // Copia arquivos do
servidor para o remote local, sem compactar antes de transmitir
CPYT2S
Reviso: 19/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
CPYT2S ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess
Parmetros
Argumento Tipo Descrio
cOrigem Caracter
Nomes dos arquivos a serem copiados, aceita apenas
arquivos locais ( Cliente ), WildCards ( * e ? ) so aceitos
normalmente.
cDestino Caracter Diretrio com o destino dos arquivos no Servidor
lCompacta Lgico
lCompacta indica se o(s) arquivo(s) deve(m) ser enviados
em formato compactado.
Retorno
Tipo Descrio
Lgico
lSucess indica , caso verdadeiro , que a cpia foi realizada com sucesso.
Caso retorne .F. , houve erro na copia do arquivo.
Descrio
Copia um arquivo, do cliente ( Remote ) para o servidor,. Caso a compactao seja
habilitada ( lCompacta ), os dados sero transmitidos de maneira compacta e
descompactados antes do uso.

Exemplo

CpyT2S( "C:\TEMP\MANUAL.DOC","\BKP", .T. ) // Copia arquivos do
cliente( remote ) para o Servidor compactando antes de transmitir

CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" ) // Copia arquivos do cliente(
remote ) para o Servidor sem compactar.
CURDIR
Reviso: 28/04/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
CURDIR ( [ cNovoPath ] ) --> cPathAtual
Parmetros
Argumento Tipo Descrio
cNovoPath Caracter
Caminho relativo , com o novo diretrio que ser ajustado
como corrente.
Retorno
Tipo Descrio
Caracter Diretrio corrente, sem a primeira barra.
Descrio
Retorna o diretrio corrente do servidor. O caminho retornado sempre relativo o
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 caimnho de rede ) , a funo no ir setar
o novo path , mantendo o atual .
DIRECTORY
Reviso: 17/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DIRECTORY ( < cDirSpec > , [ ] ) --> aDiretorio
Parmetros
Argumento Tipo Descrio
cDirSpec Caracter
<cDirSpec> especifica o drive, diretrio e arquivo para a
pesquisa no diretrio. Caracteres do tipo coringa sao
permitidos na especificaao de arquivos. Caso <cDirSpec>
seja omitido, o valor padrao *.*.
O caminho especificado pode estar na estao (remote) ,
ou no servidor , obedecendo s definices de Path
Absoluto / Relativo de acesso
<cAtributos> Caracter
<cAtributos> especifica que arquivos com atributos
especiais devem ser incluidos na informaao retornada.
<cAtributos> consiste em uma cadeia de caracteres que
contm um ou mais dos seguintes caracteres, contidos na
tabela adicional A , especificada abaixo:
Retorno
Tipo Descrio
Array
DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor
contm informaoes sobre cada arquivo que atenda a <cDirSpec>.Veja
maiores detalhes na Tabela B, abaixo discriminada.
Descrio
DIRECTORY() uma funao de tratamento de ambiente que retorna informaoes 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 operaoes em conjuntos de arquivos.
Em combinaao com AEVAL(), voc pode definir um bloco que pode ser aplicado a
todos os arquivos que atendam a <cDirSpec> especificada.

Para tornar as referncias aos vrios elementos de cada sub-vetor de arquivo mais
legveis, fornecido o arquivo header Directry.ch, que contm os #defines para os
subarray subscripts.
TABELA A: Atributos de DIRECTORY()
Atributo Significado
H Incluir arquivos ocultos
S Incluir arquivos de sistema
D Incluir diretrios
V Procura pelo volume DOS e exclui outros arquivos


Arquivos normais sao sempre incluidos na pesquisa, a nao ser que V seja especificado.
TABELA B: Estrutura dos Subvetores de DIRECTORY()
Posiao Metasmbolo Directry.ch
1 cNome F_NAME
2 cTamanho F_SIZE
3 dData F_DATE
4 cHora F_TIME
5 cAtributos F_ATT

DIRREMOVE
Reviso: 01/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DIRREMOVE ( < cDiretorio > ) --> lSucesso
Parmetros
Argumento Tipo Descrio
cDiretorio Caracter Nome do diretrio a ser removido.
Retorno
Tipo Descrio
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().
Descrio
DIRREMOVE() 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 comee com \ ) , ou a partir do diretrio corrente ( caso o path
no seja iniciado com \ ) . E , 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.
DISKSPACE
Reviso: 01/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DISKSPACE ( [ nDrive ] ) --> nBytesFree
Parmetros
Argumento Tipo Descrio
nDrive Numrico
Nmero do drive, onde 0 o espao na unidade de disco
corrente, e 1 o drive A: do cliente, 2 o drive B: do
cliente, etc.
Retorno
Tipo Descrio
Numrico Nmero de bytes disponveis no disco informado como parmetro.
Descrio
DISKSPACE() uma funo de ambiente que determina quantos bytes esto
disponveis em uma determinada uinidade 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
FCLOSE
Reviso: 09/04/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FCLOSE ( < nHandle > ) --> lError
Parmetros
Argumento Tipo Descrio
nHandle Numrico
<nHandle> o handle do arquivo obtido previamente
atravs de FOPEN() ou FCREATE().
Retorno
Tipo Descrio
Lgico
FCLOSE() retorna falso (.F.) se ocorre um erro enquanto os buffers estao
sendo escritos; do contrrio, retorna verdadeiro (.T.).
Descrio
FCLOSE() uma funao 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 operaao falhe, FCLOSE() retorna falso (.F.). FERROR() pode entao ser usado
para determinar a razao 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.

Aviso

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



Exemplos

O exemplo a seguir utiliza FCLOSE() para fechar um arquivo binrio recm criado e
exibe uma mensagem de erro caso o fechamento falhe:
#include "Fileio.ch"

nHandle := FCREATE("Testfile", FC_NORMAL)

If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf
FCREATE
Reviso: 01/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FCREATE ( < cArquivo > , [ nAtributo ] ) --> nHandle
Parmetros
Argumento Tipo Descrio
cArquivo Caracter
Nome do arquivo a ser criado , podendo ser especificado
um path absoluto ou relativo , para criar arquivos no
ambiente local ( Remote ) ou no Servidor ,
respectivamente .
nAtributo Numrico
Atributos do arquivo a ser criado (Vide Tabela de
atributos abaixo). Caso no especificado , o DEFAULT
FC_NORMAL.
Retorno
Tipo Descrio
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 ocorrencia atravs da funo FERror()
Descrio
FCREATE() uma 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
Constante Valor Descrio
FC_NORMAL 0 Criao normal do Arquivo (default/padro).
FC_READONLY 1 Cria o arquivo protegido para gravao.
FC_HIDDEN 2 Cria o arquivo como oculto.
FC_SYSTEM 4 Cria o arquivo como sistema.


Caso desejemos especificar mais de um atributo , basta som-los . Por exemplo , para
criar um arquivo protegiro contra gravao e escondido , passamos como atributo
FC_READONLY + FC_HIDDEN .

ATENO : Caso o arquivo j exista , o contedo do mesmo ser ELIMINADO ,
e seu tamanho ser truncado para 0 ( ZERO ) bytes.
FERASE
Reviso: 01/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FERASE ( < cArquivo > ) --> nStatus
Parmetros
Argumento Tipo Descrio
cArquivo Caracter
Nome do arquivo a ser apagado . Pode ser especificado um
path absoluto ou relativo , para apagar arquivos na estao
local ( Remote ) ou no Servidor , respctivamente .
Retorno
Tipo Descrio
Numrico
A funo retornar 0 caso o arquivop seja apagado com sucesso , e -1 caso
no seja possvel apagar o arquivo. Caso a funo retorne -1 , possvel
obter mauires detalhes da ocorrncia atravs da funo fError()
Descrio
Atravs da funo Ferase , possvel 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 permitido a utilizao de
caracteres coringa (wildcards).
FILE
Reviso: 04/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FILE ( < cArquivo > ) --> lExiste
Parmetros
Argumento Tipo Descrio
cArquivo Caracter
Nome do arquivo , podendo ser especificado um path
(caminho ) . Caminhos locais (Remote) ou caminhos de
servidor so aceitos , bem como wildcards ( Caracteres * e
? )
Retorno
Tipo Descrio
Lgico
O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no
exista no path especificado , a funo retorna .F.
Descrio
Verifica se existe um arquivo ou um padro de arquivos, no diretrio. Pordemos
especificar caminhos absolutos ( arquivos na estao - Remote ) ou relativos ( A partir
do RootPath do Protheus Server) . Os caracteres * e ? ( wildcards). so aceitos.
FOPEN
Reviso: 05/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
FOPEN ( < cArq > , [ nModo ] ) --> nRet
Parmetros
Argumento Tipo Descrio
cArq Caracter
Nome do arquivo a ser aberto que inclui o path caso haja
um.
nModo Numrico
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
padrao 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
Tipo Descrio
Numrico
FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535.
Caso ocorra um erro, FOPEN() retorna -1.
Descrio
Abre um arquivo binrio.

FOPEN() uma funao 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 nao exista, FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o
arquivo nao 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 funoes
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.

Aviso
Esta funao 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.



Notas
FOPEN procura o arquivo no diretrio corrente e nos diretrios configurados na
varivel de pesquisa do Sistema Operacional, a nao ser que um path seja
declarado explicitamente como parte do argumento <cArq>.
Por serem executadas em um ambiente cliente-servidor, as funes de
tratamento de arquivos podem trabalhar em arquivos localizados no cliente
(estao) ou no servidor. O ADVPL identifica o local onde o arquivo ser
manipulado atravs da existncia ou no da letra do drive no nome do arquivo
passado em <cArq>. Ou seja, se o arquivo for especificado com a letra do drive,
ser aberto na estao. Caso contrrio, ser aberto no servidor com o diretrio
configurado como rootpath sendo o diretrio raz para localizao do arquivo.


Tabela A: Modos de Acesso a Arquivos Binrios
Modo Constante (fileio.ch) Operao
0 FO_READ Aberto para leitura (padro assumido)
1 FO_WRITE Aberto para gravao
2 FO_READWRITE Aberto para leitura e gravao


Tabela B: Modos de Acesso de Compartilhamento a Arquivos Binrios
Modo
Constante
(fileio.ch)
Operao
0 FO_COMPAT Modo de Compatibilidade (Default)
16 FO_EXCLUSIVE Acesso total exclusivo
32 FO_DENYWRITE
Acesso bloqueando a gravao de outros processos ao
arquivo.
48 FO_DENYREAD Acesso bloqueando a leitura de outros processos ao arquivo.
64 FO_DENYNONE
Acesso compartilhado. Permite a leitura e gravao por
outros processos ao arquivo..
64 FO_SHARED Igual FO_DENYNONE
FREAD
Reviso: 19/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FREAD ( < nHanvle > , < cBuffer > , < nQtdBytes > ) --> nBytesLidos
Parmetros
Argumento Tipo Descrio
nHanvle Numrico
o manipulador (Handle) retornado pelas funes
FOPEN(),
FCREATE(), FOPENPORT(), que faz referncia ao
arquivo a ser lido.
cBuffer Caracter
o nome de uma varivel do tipo String , a ser utilizada
como buffer de leitura , onde os dados lidos
devero ser armazenados. O tamanho desta varivel deve
ser maior ou igual ao tamanho informado em nQtdBytes.

Esta varivel deve ser sempre passada por referncia. ( @
antes do nome da varivel ), caso contrrio os dados lidos
no sero retornados.
nQtdBytes Numrico
Define a quantidade de Bytes que devem ser lidas do
arquivo a partor posicionamento do ponteiro atual.
Retorno
Tipo Descrio
Numrico
Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada,
isto indica erro de leitura ou final de arquivo, Verifique a funo
FERROR() para maiores detalhes.
Descrio
FREAD() l os 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.).

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

FREAD() l a partir da posio atual do ponteiro atual do arquivo , que pode ser
ajustado ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().
FREADSTR
Reviso: 02/06/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FREADSTR ( < nHandle > , < nQtdBytes > ) --> cLidos
Parmetros
Argumento Tipo Descrio
nHandle Numrico
o manipulador retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT().
nQtdBytes Numrico Nmero mximo de bytes que devem ser lidos.
Retorno
Tipo Descrio
Caracter
Retorna uma string contendo os caracteres
lidos.
Descrio
L 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().
FRENAME
Reviso: 11/06/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FRENAME ( < cOldFile > , < cNewFile > ) --> nStatus
Parmetros
Argumento Tipo Descrio
cOldFile Caracter
Nome do arquivo ser renomeado, aceita caminhos do
servidor e caminhos do cliente. Caso no seja especificado
nenhuma unidade de disco e path, considerado o path
atual no servidor.
cNewFile Caracter
Novo nome do arquivo, aceita tambm caminho do
servidor, e caminho do cliente.
Retorno
Tipo Descrio
Numrico
Se o status retornado for -1 , ocorreu algum erro na mudana de nome :
Verifique se os dois caminhos esto no mesmo ambiente, verifique a
existncia do arquivo de origem, se ele no est em uso no momento por
outro processo , e verifique se o nome do arquivo de destino j no existe
no path de destino especificado.
Descrio
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 fername() atravs de um JOB.
Caso isto ocorra, a funo retornar -1 , e fError() retornar tambm -1.
Importante : 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.
FSEEK
Reviso: 05/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) --> nPos
Parmetros
Argumento Tipo Descrio
nHandle Numrico
Manipulador obtido atravs das funes
FCREATE,FOPEN.
nOffSet Numrico
nOffSet corresponde ao nmero de bytes no ponteiro de
posicionamento do arquivo a ser movido. Pode ser um
numero positivo , zero ou negativo, a ser considerado a
partir do parmetro passado em nOrigem.
nOrigem Numrico
Indica a partir de qual posio do arquivo, o nOffset ser
considerado.
Retorno
Tipo Descrio
Numrico
FSEEK() retorna a nova posiao do ponteiro de arquivo com relaao ao
incio do arquivo (posiao 0) na forma de um valor numrico inteiro. Este
valor nao leva em conta a posiao original do ponteiro de arquivos antes
da execuo da funo FSEEK().
Descrio
FSEEK() posiciona o ponteiro do arquivo para as prximas operaes de leitura ou
gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os
seguintes valores, definidos em fileio.ch:

Tabela A: Origem a ser considerada para a movimentao do ponteiro de
posicionamento do Arquivo.
Origem Constante Operao
0 FS_SET Ajusta a partir do inicio do arquivo. (Default)
1 FS_RELATIVE Ajuste relativo a posio atual do arquivo.
2 FS_END Ajuste a partir do final do arquivo.
FWRITE
Reviso: 27/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) --> nBytesEscritos
Parmetros
Argumento Tipo Descrio
nHandle Numrico
o manipulador de arquivo ou device retornado pelas
funes FOPEN(), FCREATE(), ou FOPENPORT().
cBuffer Caracter
<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 Numrico
<nQtdBytes> indica a quantidade de bytes a serem
escritos a partir da posiao corrente do ponteiro de
arquivos. Caso seja omitido, todo o contedo de
<cBuffer> escrito.
Retorno
Tipo Descrio
Numrico
FWRITE() retorna a quantidade de bytes escritos na forma de um valor
numrico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
operaao 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.
Descrio
Voc pode escrever todo ou 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().
GETCLIENTDIR
Reviso: 04/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
GETCLIENTDIR ( ) --> cPath
Retorno
Tipo Descrio
Caracter Retona o path onde est instalado o Protheus Remote.
Descrio
Retorna o diretrio completo onde o Remote est instalado, informando inclusive a
unidade de disco.

Observao : Esta funo apenas retornar um resultdo vlido caso seja
executada em um programa atravs do Protheus Remote . Caso esta funo seja
chamada em JOB , a mesma ocasionar um erro de execuo ( Error to
comunicate with Remote ) .
GETREMOTEININAME
Reviso: 12/06/2003
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
GETREMOTEININAME ( ) --> cArqConf
Retorno
Tipo Descrio
Caracter Path e nome do arquivo de configurao
Descrio
Retorna o nome do arquivo de configurao do AP Remote.
GETSRVPROFSTRING
Reviso: 03/09/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
GETSRVPROFSTRING ( < cChave > , < cDefault > ) --> cConteudo
Parmetros
Argumento Tipo Descrio
cChave Caracter Chave do INI do environment a ser lida,
cDefault Caracter
cDefault o conteudo da chave a ser retornado caso a
chave no seja encontrada no .ini
Retorno
Tipo Descrio
Caracter Conteudo da chave especificada
Descrio
Atravs da funo GetSrvProfString , podemos obter o contedo de uma chave de
configurao do environment atual em uso no arquivo de Inicializao do Server
Protheus ( APxSrv.ini ) .
MAKEDIR
Reviso: 12/06/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
MAKEDIR ( < cNovoDir > ) --> nResultado
Parmetros
Argumento Tipo Descrio
cNovoDir Caracter
Nome do diretrio a ser criado, incluindo opcionalmente o
caminho (path).
Retorno
Tipo Descrio
Numrico
Retorno zero ( 0 ),o diretrio foi criado com sucesso. Caso contrrio,
houve erro na criao do diretrio.
Descrio
Cria um diretrio na estao ou no servidor APx.

Caso o diretrio comece com um drive ( Ex: C:, X: ) o diretrio ser criado na estao,
caso contrrio ser criado no servidor.

MAKEDIR("c:\teste\um") // Cria um diretrio na estacao
nResult := MAKEDIR("\teste\um") // Cria o diretorio no servidor
Advanced protheus
IF nResult != 0
Conout( "Impossivel Criar o diretrio no servidor Protheus", nResult
)
ENDIF
MAKEDIR( "teste" ) // Exemplo tambm vlido ( Criando o diretrio no
servidor ) dentro do diretrio corrente
MSCOMPRESS
Reviso: 07/05/2003
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
MSCOMPRESS ( < cArq | aArquivos > , [ cDestino ] , [ cSenha ] ) --> cFileName
Parmetros
Argumento Tipo Descrio
cArq | aArquivos (Qualquer)
Arquivo(s) a ser(em) compactado(s). Pode ser do tipo
String , para especificar um nico arquivo , ou do tipo
Array , contendo um ou mais arquivo(s) a ser(em)
compatado(s).
cDestino Caracter
Nome do Arquivo destino, caso a extenso seja omitida
ser assumido .MZP, se no for informado assumir o
mesmo nome do cArq com extenso .MZP ou o nome do
1. Arquivo no Array <aArquivos>.
cSenha Caracter
Senha a ser utilizada para criptografar o arquivo
compactado.
Retorno
Tipo Descrio
Caracter
Caso a compactao seja executada com sucesso , a funo retornar uma
sring contendo o nome do arquivo gerado . Caso no seja possvel a
compactao , por falta de espao em disco ou erro de acesso a algum dos
arquivos a ser(em) compactado(s), a funo retornar uma string em
branco ("").
Descrio
Compacta um ou vrios arquivos em um nico arquivo com extenso .MZP.
MSCOMPRESS() compacta os arquivos informados em um nico arquivo com
extenso default .MZP. O formato proprietrio e multiplataforma.
Caso a senha seja informada apenas com a senha poderemos descompactar os arquivos.

Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
MSDECOMP
Reviso: 07/05/2003
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess
Parmetros
Argumento Tipo Descrio
cArq Caracter Nome do Arquivo no formato MZP a ser descompactado.
cPathDestino Caracter
Path de destino onde sero gravados o(s) arquivo(s)
descompactado(s). Note que podem ser includos
caminhos do servidor como caminhos locais.
cSenha Caracter
Caso o arquivo tenha sido compactado com senha , esta
deve ser especificada este parmetro para ser poss;ivel a
descompactao do arquivo.
Retorno
Tipo Descrio
Lgico
Caso a descompactao foi executada com sucesso, a funo retornar .T.
, Em caso de erro durante a descompactao, a funo retrornar .F.
Verifique o espao disponvel na unidade de disco para descompactar o(s)
arquivo(s) e/ou se existe amgum arquivo a ser descompactado no pacote
que j exista na unidade de disco , atribudo como "REad-Only".
Descrio
MSDECOMP() descompacta o arquivo informado em um diretrio. O Formato
proprietrio, e multi-plataforma, suporta apenas arquivos compactados pela funo
MSCOMPRESS().

Caso o arquivo seja protegido por senha, apenas com a senha poderemos descompact-
lo.

Tanto arquivos no local ( Remote ) como no Servidor so aceitos.
SPLITPATH
Reviso: 05/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) -->
NIL
Parmetros
Argumento Tipo Descrio
cArq Caracter
Nome do Arquivo a ser quebrado. Opcionalmente, pode
incluir caminho e drive.
cDrive Caracter
Nome do Drive. Exemplo ( C: ). Caso o Arquivo
informado no possua drive ou o caminho refira-se ao
servidor, o retorno ser uma string em branco.
cCaminho Caracter
Nome do Caminho. Caso o Arquivo informado no possua
caminho, ser uma string em branco.
cNome Caracter
Nome do Arquivo sem a extenso. Caso em cArq no seja
especificado um nome do Arquivo, ser retornada uma
string em branco.
cExt Caracter
Extenso do arquivo informado em cArq , prefizada com
um ponto ".". Caso a extenso em cArq no seja
especificada , o retorno ser uma string em branco.
Retorno
Tipo Descrio
Caracter Esta funo sempre retorna NIL.
Descrio
A funo SplitPath() divide um caminho completo em todas as suas subpartes ( Drive ,
Caminho , Nome e Extenso ) .
Tanto arquivos locais ( Remote ) quanto arquivos no servidor, podem ser informados.
O caminho, caso informado, incluir uma barra como ltimo caracter. A extenso ,
quando retornada , inclui sempre o ponto ( . ) antes da extenso.
Todos os parmetros , a partir do segundo , quando passados devem ser por referncia.

Observao : Vale lembrar que a funo SplitPath no valida a sintaxe do caminho
e/ou arquivo digitados , nem a existncia do mesmo . Esta funo utilizada para
determinar em uma string os elementos que compe um caminho para a
localizao de um arquivo.
WRITEPPROSTRING
Reviso: 05/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
WRITEPPROSTRING ( < cSecao > , < cChave > , < cConteudo > , < cArqIni > ) -->
lSucess
Parmetros
Argumento Tipo Descrio
cSecao Caracter
cSecao corresponde o nome da seo do ni a ser
utilizada. Caso a seo no exista , a mesma ser criada.
cChave Caracter
Chave da seo do ini a ter seu conteco alterado . Caso a
chave no esxista na seo especificada, a mesma ser
criada.
cConteudo Caracter
cConteudo corresponde o contedo da chave a ser
atualizado.
cArqIni Caracter
cArqIni corresponde ao nome do arquivo de inicializao a
ser alterado. Caso o arquivo no exista , ele ser criado .
Caso o path do arquivo no seja informado , o mesmo ser
criado/atualizado no diretrio onde est instalado o
Protheus Server, no servidor. Caso especificado um path
absoluto , com unidade de disco , o arquivo .ini ser criado
e/ou atualizado na estao remota , no path informado.
Retorno
Tipo Descrio
Lgico
Caso a chave seja incluida e/ou alterada com sucesso , a funo retornat
.T. (true) , e caso ocorra alguma falha ou impossibilidade de acesso ao
arquivo .ini , a funo retornar .F. (false). Dentre as causas mais comuns
de falha , podemos citar erro de sintaxe no nome do arquivo e/ou path
inexistente ou inacessvel.
Descrio
Atravs da funcao WritePProString() , possvel criar e/ou alterar uma seo / chave de
configurao em um arquivo .ini . Caso o arquivo no exista , o mesmo ser criado . No
nome do arquivo , podemos opcionalmente definir um path absoluto , com unidade de
disco , de modo que o arquivo .ini ser atualizado na estao remota ( onde est sendo
executado o Protheus Remote ) . Caso no seja especificado nenhum path ou caminho
do arquivo .ini , o caminho de disco considerado ser o path no Servidor onde est
instalado o Protheus Server .
Funes de tratamento de caracteres
ALLTRIM
Reviso: 26/02/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ALLTRIM ( < cString > ) --> cTrimString
Parmetros
Argumento Tipo Descrio
cString Caracter
<cString> a expressao caractere cujos espaos em branco
serao eliminados.
Retorno
Tipo Descrio
Caracter
ALLTRIM() retorna uma cadeia de caracteres cujos espaos em branco
direita e esquerda foram removidos.
Descrio
ALLTRIM() uma funo de tratamento de dados do tipo caractere que remove os
espaos em branco direita e esquerda de uma cadeia de caracteres. relacionada a
LTRIM() e RTRIM(), que removem espaos em branco esquerda e direita de uma
cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM()
sao as funoes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou
alinham esquerda cadeias de caracteres atravs da insero de caracteres de
preenchimento.
DESCEND
Reviso: 08/09/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
DESCEND ( < cString > ) --> cDescend
Parmetros
Argumento Tipo Descrio
cString Caracter
<cString> corresponde sequncia de caracteres a ser
analisada.
Retorno
Tipo Descrio
Caracter
DESCEND() retorna a string especificada como parmetro de uma forma
complementada. Um DESCEND() de CHR(0) sempre retorna CHR(0).
Descrio
DESCEND() uma funo de converso que retorna a forma complementada da
expresso string especificada. Esta funo normalmente utilizada para a criao de
indexadores em Ordem Decrescente.
LTRIM
Reviso: 26/02/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
LTRIM ( < cString > ) --> cStringResult
Parmetros
Argumento Tipo Descrio
cString Caracter
<cString> a cadeia de caracteres a ser copiada sem os
espaos em branco esquerda.
Retorno
Tipo Descrio
Caracter
LTRIM() retorna uma cpia de <cString>, sendo que os espaos em
branco esquerda foram removidos. Caso <cString> seja uma cadeia de
caracteres nula ("") ou toda composta de espaos em branco, LTRIM()
retorna uma cadeia de caracteres nula ("").
Descrio
LTRIM() uma funao de 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 funao 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() sao as funoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres,
atravs da inserao de caracteres de preenchimento.
PADL / PADR / PADC
Reviso: 26/02/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
PADL / PADR / PADC ( < exp > , < nTamanho > , [ cCaracPreench ] ) -->
cStringPreench
Parmetros
Argumento Tipo Descrio
exp Caracter
<exp> um valor caractere, data, ou numrico no qual
serao inseridos caracteres de preenchimento.
nTamanho Numrico
<nTamanho> o tamanho da cadeia de caracteres a ser
retornada.
cCaracPreench Caracter
<cCaracPreench> o caractere a ser inserido em <exp>.
Caso nao seja especificado, o padrao o espao em
branco.
Retorno
Tipo Descrio
Caracter
PADC(), PADL(), e PADR() retornam o resultado de <exp> na forma de
uma cadeia de caracteres preenchida com <cCaracPreench>, para totalizar
o tamanho especificado por <nTamanho>.
Descrio
PADC(), PADL(), e PADR() sao funoes de tratamento de caracteres que inserem
caracteres de preenchimento em valores caractere, data ou numricos a fim de criar uma
nova cadeia de caracteres de tamanho especificado. PADC() centraliza <exp>,
adicionando caracteres de preenchimento direita e esquerda; PADL() adiciona
caracteres de preenchimento esquerda; e PADR() adiciona caracteres de
preenchimento direita. Caso o tamanho de <exp> exceda o argumento <nTamanho>,
todas as funoes PAD() truncam cStringPreench ao <nTamanho> especificado.

PADC(), PADL(), e PADR() sao 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 utilizaao exibir textos
em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi
completamente sobreescrito.

PADC(), PADL(), e PADR() sao o contrrio das funoes ALLTRIM(), LTRIM(), e
LTRIM(), as quais eliminam espaoes em branco esquerda e direita de cadeias de
caracteres.
RTRIM
Reviso: 26/02/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
RTRIM ( < cString > ) --> cTrimString
Parmetros
Argumento Tipo Descrio
cString Caracter
<cString> a cadeia de caracteres a ser copiada sem os
espaos em branco direita.
Retorno
Tipo Descrio
Caracter
RTRIM() retorna uma cpia de <cString>, sendo que os espaos em
branco direita foram removidos. Caso <cString> seja uma cadeia de
caracteres nula ("") ou totalmente composta por espaos, RTRIM() retorna
uma cadeia de caracteres nula ("").
Descrio
RTRIM() uma funao de 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 sao 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() sao as funoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres,
inserindo caracteres de preenchimento.
Funces de Tratamento de Data / Hora
CDOW
Reviso: 04/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
CDOW ( < dExp > ) --> cNomeDia
Parmetros
Argumento Tipo Descrio
dExp Data <dExp> o valor data a ser convertido.
Retorno
Tipo Descrio
Caracter
CDOW() retorna o nome do dia da semana na forma de uma cadeia de
caracteres. A primeira letra ser maiscula e o resto dos caracteres vir em
minsculas. Para um valor de data nulo ou invlido, CDOW() retorna uma
cadeia de caracteres vazia ("").
Descrio
CDOW() uma funo utilizada para obter, a partir de uma data, a cadeia de caracteres
contendo o dia da semana correspondente.
CMONTH
Reviso: 04/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
CMONTH ( < dData > ) --> cMs
Parmetros
Argumento Tipo Descrio
dData Data <dData> a data a converter.
Retorno
Tipo Descrio
Caracter
CMONTH() retorna o nome do ms a partir de uma data como sendo uma
cadeia de caracteres com a primeira letra maiscula e o restante da string
em letras minsculas. Para uma data nula, CMONTH() retornar uma
string nula ("").
Descrio
CMONTH() uma funo de converso de datas que , a partir de uma data , retorna
uma cadeia de caracteres correspondendo ao nome do ms correspondente.
DATE
Reviso: 04/08/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DATE ( ) --> dSistema
Retorno
Tipo Descrio
Data
DATE() retorna a data do sistema como sendo um valor do tipo data.
Descrio
Retorna a data do sistema.
DATE() a funo que retorna a data do atual sistema. O formato de
sada controlado pelo comando SET DATE. O formato padro mm/dd/yy.
DAY
Reviso: 22/09/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DAY ( < dData > ) --> nDia
Parmetros
Argumento Tipo Descrio
dData Data <dData> a data a converter.
Retorno
Tipo Descrio
Numrico
DAY() retorna um nmero na faixa de 0 at 31, sendo este um valor
numrico inteiro. Caso o ms seja Fevereiro, os anos bissextos sao
considerados. Se o argumento de data 29 de Fevereiro e o ano nao
bissexto, DAY() retornar zero. Se o argumento de data vazio, DAY()
tambm retornar zero.
Descrio
Retorna o dia do ms como valor numrico. DAY() uma funao de conversao de datas
utilizada para converter um valor do tipo data para o dia do ms correspondente. Esta
funo usada em conjunto com CMONTH() e YEAR() para formatar datas. Alm
disso, geralmente usada em clculos que envolvam datas.
DOW
Reviso: 13/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DOW ( < dData > ) --> nDia
Parmetros
Argumento Tipo Descrio
dData Data <dData> o valor data que ser convertido.
Retorno
Tipo Descrio
Numrico
DOW() retorna o dia da semana na forma de um nmero entre zero e sete.
O primeiro dia da semana um (Domingo) e o ltimo sete (Sbado). Se
<dData> estiver vazio, DOW() retorna zero.
Descrio
DOW() uma funao de conversao de datas que converte um valor data para um
nmero que identifica o dia da semana. Ela til quando voc deseja clculos de data
em uma base semanal. DOW() semelhante a CDOW(), a qual retorna o dia da semana
na forma de uma cadeia de caracteres ao invs de um nmero.
DTOC
Reviso: 13/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
DTOC ( < dData > ) --> cData
Parmetros
Argumento Tipo Descrio
dData Data <dData> o valor data que ser convertido.
Retorno
Tipo Descrio
Caracter
DTOC() retorna uma cadeia de caracteres que representa uma data. O
valor de retorno formatado de acordo com o formato de datas corrente. O
formato padrao mm/dd/aa. Uma data nula retorna uma cadeia de
caracteres em branco igual em tamanho ao formato de data corrente.
Descrio
DTOC() uma funao de conversao de datas utilizada por motivos de Formataao
quando voc deseja exibir a data no formato SET DATE e necessria uma expressao
caractere. Caso voc precise de um formato de data especfico, voc pode utilizar
TRANSFORM() ou uma expressao customizada.

Se voc estiver INDEXando uma data juntamente com uma cadeia de caracteres, use
DTOS() ao invs de DTOC() para converter o valor data para uma cadeia de caracteres.
ELAPTIME
Reviso: 08/09/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
ELAPTIME ( < cHoraInicial > , < cHoraFinal > ) --> cIntervalo
Parmetros
Argumento Tipo Descrio
cHoraInicial Caracter
Informe a hora inicial no formato hh:mm:ss, onde hh a
hora ( 1 a 24 ), mm os minutos e ss os segundos
cHoraFinal Caracter
Informe a hora final no formato hh:mm:ss, onde hh a
hora ( 1 a 24 ), mm os minutos e ss os segundos.
Retorno
Tipo Descrio
Caracter
A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),
mm os minutos e ss os segundos
Descrio
ElapTime() retorna uma cadeia de caracteres contendo a diferena de
tempo entre cHoraFinal - cHoraInicial , no formato hh:mm:ss.

Os dois parmetros , cHoraInicial e cHoraFinal , devem ser especificados no formato
hh:mm:ss , com tamanho de 8 bytes . Caso um dos parmetros tenha tamanho diferente
de 8 Bytes, gerada uma ocorrncia de Erro Fatal "invalid len". Qualquer caracter
invalido nas posices referentes hora (hh) , minuto (mm) e segundo (ss) , sero
ignorados na composio de numeros para o clculo. Caso o horrio inicial seja maior
que o horrio final , retornada a diferena entre os horrios acrescidos de 24h. Para
maiores detalhes , consulte o exemplo da funo ElapTime()
MONTH
Reviso: 22/09/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
MONTH ( < dData > ) --> nMs
Parmetros
Argumento Tipo Descrio
dData Data <dData> o valor data a ser convertido.
Retorno
Tipo Descrio
Numrico
MONTH() retorna um valor numrico inteiro na faixa de 0 (zero) a 12.
Uma data nula (CTOD("")) retorna zero.
Descrio
MONTH() uma funao de conversao de datas que til quando voc precisa de um
valor de ms numrico durante clculos para, por exemplo, relatrios peridicos.
MONTH() faz parte de um grupo de funoes que retornam componentes de um valor
data na forma de valores numricos. O grupo inclui DAY() e YEAR(), que retornam os
valores de dia e ano na Forma de nmericos. CMONTH() uma funao relacionada,
que permite a voc retornar o nome do ms a partir de um valor data.
SECONDS
Reviso: 09/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
SECONDS ( ) --> nSegundos
Retorno
Tipo Descrio
Numrico
SECONDS() retorna a hora do sistema como um valor numrico na forma
segundos.centsimos. O valor numrico retornado a quantidade de
segundos decorridos desde a meia-noite, e tem base em um relgio de
vinte e quatro horas em uma faixa de zero a 86399.
Descrio
SECONDS() uma funao de horas utilizada para fornecer um mtodo simples de
calcular o tempo decorrido, com base no relgio do sistema, durante a execuao do
programa. relacionado funao TIME(), a qual retorna a hora do sistema como uma
cadeia de caracteres na forma hh:mm:ss.
TIME
Reviso: 13/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
TIME ( ) --> cStringHora
Retorno
Tipo Descrio
Caracter
TIME() retorna a hora do sistema como uma cadeia de caracteres na forma
hh:mm:ss. hh indica a hora no formato de 24 horas, mm indica os minutos,
e ss indica os segundos. Horas, minutos e segundos sao separadas por dois
pontos.
Descrio
TIME() uma funao de tratamento de tempo, utilizada para exibir ou imprimir a hora
do sistema em um relatrio ou na tela. TIME() est relacionada a SECONDS(), que
retorna a quantidade de segundos decorridos desde a meia-noite. SECONDS()
geralmente utilizada em lugar de TIME() para clculos sobre o tempo.
YEAR
Reviso: 13/10/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
YEAR ( < dData > ) --> nAno
Parmetros
Argumento Tipo Descrio
dData Data <dData> o valor data a ser convertido.
Retorno
Tipo Descrio
Numrico
YEAR() retorna o ano do valor data especificado, inclusive dgitos
indicativos de sculo, na forma de um valor numrico de quatro dgitos. O
valor retornado nao influenciado pelo formato de DATE ou CENTURY
corrente. A especificaao de uma data nula (CTOD("")) retorna zero.
Descrio
YEAR() uma funao de conversao de datas utilizada para converter um valor data para
um valor numrico indicativo do ano. Pode ser utilizada em clculos de, por exemplo,
relatrios peridicos, ou para Formataao de exibioes de data.

YEAR() membro de um grupo de funoes que retornam componentes de um valor
data na forma de valores numricos. Este grupo inclui DAY() e MONTH(), que
retornam valores de dia e ms na forma de valores numricos.
Funces de Tratamento de Matrizes (Arrays)
AADD
Reviso: 26/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
AADD ( < aDestino > , [ expValor ] ) --> Valor
Parmetros
Argumento Tipo Descrio
aDestino Array o array ao qual o novo elemento ser adicionado.
expValor (Qualquer)
uma expresso vlida que ser o valor do
novo elemento.
Retorno
Tipo Descrio
(Qualquer)
Avalia expValor e retorna seu Valor. Se expValor no for especificado,
AADD() retorna NIL.
Descrio
AADD() uma funo de tratamento de vetor que adiciona um elemento ao vetor. Ao
elemento de vetor recm criado atribuido o valor especificado por <expValor>.

AADD() utilizado para aumentar o tamanho de um vetor dinamicamente. til na
construo de filas ou listas dinmicas.

AADD() semelhante funo ASIZE(), mas adiciona apenas um elemento por vez;
ASIZE() pode aumentar ou diminuir um vetor a um tamanho especificado. AADD(),
porm, possui a vantagem de poder atribuir um valor ao novo elemento, enquanto que
ASIZE() nao pode. AADD() pode tambm parecer ser igual a AINS(), mas isso nao
verdade: AINS() move elementos dentro de um vetor, mas nao modifica o tamanho do
vetor.

OBSERVAO : Caso <expValor> seja um outro vetor, o novo elemento no vetor
destino conter uma referncia ao vetor especificado por <expValor>.
ACLONE
Reviso: 13/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ACLONE ( < aFonte > ) --> aDuplica
Parmetros
Argumento Tipo Descrio
aFonte Array
<aFonte> o vetor a ser duplicado.
Retorno
Tipo Descrio
Array Array idntico ao aFonte , porem sem nenhuma referncia ao mesmo.
Descrio
ACLONE() uma funao de vetor que cria uma duplicata completa do vetor de
<aFonte>. Caso <aFonte> contenha sub-vetores, ACLONE() cria sub-vetores
correspondentes e os preenche com cpias dos valores contidos nos sub-vetores de
<aFonte>.

Ao igualarmos dois arrays, eles ficam associados por referncia, utilizando
aClone() no existe referncia. ACLONE() semelhante a ACOPY(), porm ACOPY()
nao duplica vetores aninhados.
ACOPY
Reviso: 13/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
ACOPY ( < aFonte > , < aDestino > , [ nInicio ] , [ nCont ] , [ nPosDestino ] ) -->
aDestino
Parmetros
Argumento Tipo Descrio
aFonte Array <aFonte> o vetor de onde serao copiados os elementos.
aDestino Array
<aDestino> o vetor para onde serao copiados os
elementos.
nInicio Numrico
<nInicio> a posiao do elemento inicial no vetor
<aFonte>. Se nao for especificado, o valor assumido um
(01).
nCont Numrico
<nCont> a quantidade de elementos a serem copiados
do vetor <aFonte> a partir da posiao <nInicio>. Caso
<nCont> nao seja especificado, todos os elementos em
<aFonte> que comeam com o elemento inicial sao
copiados.
nPosDestino Numrico
<nPosDestino> a posiao do elemento inicial no vetor
<aDestino> que receber os elementos de <aFonte>. Se
nao for especificado, o valor padrao um (01).
Retorno
Tipo Descrio
Array ACOPY() retorna uma referncia ao vetor destino, <aDestino>.
Descrio
ACOPY() uma funao de tratamento de vetor que copia elementos do vetor <aFonte>
para o vetor <aDestino>. O vetor <aDestino> j deve existir e ser grande o suficiente
para conter os elementos copiados. Caso o vetor <aFonte> tenha mais elementos, alguns
elementos nao serao copiados.

ACOPY() copia valores de todos os tipos de dados, inclusive NIL e blocos de cdigo.
Se um elemento do vetor <aFonte> for um sub-vetor, o elemento correspondente no
vetor <aDestino> conter uma referncia ao sub-vetor. Consequentemente, ACOPY()
nao cria duplicatas completas de vetores multi-dimensionais. Para fazer isto, use a
funao ACLONE().
ADEL
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ADEL ( < aFonte > , < nPosicao > ) --> aFonte
Parmetros
Argumento Tipo Descrio
aFonte Array
<aFonte> o vetor que contm um elemento a ser
eliminado.
nPosicao Numrico
<nPosiao> a posiao do elemento de vetor , a partir do
primeiro , que ser eliminado.
Retorno
Tipo Descrio
Array
ADEL() retorna uma referncia ao vetor destino, <aFonte>.
Descrio
ADEL() uma funao de tratamento de vetor que elimina um elemento de um vetor. O
contedo do elemento de vetor especificado perdido, e todos os elementos a partir
daquela posiao at o final do elemento sobem uma posiao. O ltimo elemento no
vetor torna-se NIL.

AVISO : Em Advpl, vetores multi-dimensionais sao implementados atravs do
aninhamento de vetores dentro de outros vetores. Caso o vetor <aFonte> seja um vetor
multi-dimensional, ADEL() eliminar todo o sub-vetor especificado por <nPosiao>,
forando <aFonte> a nao mais ter dimensoes regulares.
AEVAL
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
AEVAL ( < aVetor > , < bBloco > , [ nInicio ] , [ nCont ] ) --> aVetor
Parmetros
Argumento Tipo Descrio
aVetor Array <aVetor> o vetor a ser varrido.
bBloco Code-Block
<bBloco> um bloco de cdigo a ser executado para
cada elemento encontrado.
nInicio Numrico
<nInicio> o elemento inicial. Caso nao seja
especificado, o padrao assumido o elemento um.
nCont Numrico
<nCont> a quantidade de elementos a serem
processados a partir de <nIncio>. Se nao for
especificado, o padrao todos os elementos no vetor.
Retorno
Tipo Descrio
Array
AEVAL() retorna uma referncia a <aVetor>.
Descrio
AEVAL() uma funao de tratamento de vetor que avalia um bloco de cdigo uma vez
para cada elemento de um vetor, passando o valor do elemento como um parmetro de
bloco. O valor de retorno do bloco ignorado. Todos os elementos no <aVetor> sao
processados a nao ser que o argumento <nInicio> ou <nCont> seja especificado.
AEVAL() nao faz suposioes sobre o contedo dos elementos de vetor que ele est
passando para o bloco. assumido que o bloco sabe qual o tipo de dados haver em
cada elemento.
AEVAL() semelhante a DBEVAL(), que aplica um bloco para cada registro de um
arquivo de banco de dados. Da mesma forma que DBEVAL(), AEVAL() pode ser
utilizado como base para a construao de comandos de interaao tanto para estruturas de
vetor complexas como simples.
Consulte a seao Blocos de Cdigo no na seo A Linguagem Advpl para maiores
informaes sobre Code-Blocks.
AFILL
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
AFILL ( < aDestino > , < ValorExp > , [ nInicio ] , [ nCont ] ) --> aDestino
Parmetros
Argumento Tipo Descrio
aDestino Array <aDestino> o vetor a ser preenchido.
ValorExp (Qualquer)
<ValorExp> o valor a ser alocado em cada elemento de
vetor. Pode ser uma expressao de qualquer tipo de dados
vlido.
nInicio Numrico
<nInicio> a posiao do primeiro elemento a ser
preenchido. Caso este argumento seja omitido, o valor
padrao um.
nCont Numrico
<nCont> a quantidade de elementos a serem
preenchidos iniciando com o elemento <nInicio>. Se este
argumento for omitido, os elementos sao preenchidos a
partir da posiao do elemento inicial at o final do vetor.
Retorno
Tipo Descrio
Array AFILL() retorna uma referncia ao <aDestino>.
Descrio
AFILL() uma funao de vetor que preenche um vetor especificado com um nico
valor de qualquer tipo de dados (inclusive vetores, blocos de cdigo ou NIL) atribuindo
<ValorExp> a cada elemento de vetor na faixa especificada.

ATENO : AFILL() nao pode ser utilizado para preencher vetores multi-
dimensionais. Este tipo de vetores em Clipper sao implementados aninhando-se vetores
dentro de outros vetores. A utilizaao de AFILL() com vetores multi-dimensionais
sobre-escrever vetores para as outras dimensoes do vetor.
AINS
Reviso: 16/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
AINS ( < aDestino > , < @nPos > ) --> aDestino
Parmetros
Argumento Tipo Descrio
aDestino Array o array de onde ser inserido um item NIL.
nPos Numrico
a posio, a partir da 1, na qual ser inserido um
elemento NIL
Retorno
Tipo Descrio
Array
Retorna uma referncia ao vetor aDestino
Descrio
AINS() uma funo de vetor que insere um novo elemento em um vetor especificado.
O elemento recm inserido NIL at que um novo valor seja atribuido a ele. Aps a
insero, o ltimo elemento no vetor descartado, e todos os elementos depois do novo
elemento descem uma posio.

AVISO : AINS() deve ser utilizado com cuidado quando se tratar de vetores multi-
dimensionais. Vetores multi-dimensionais em Advpl sao implementados atravs do
aninhamento de vetores dentro de outros vetores. Utilizar AINS() com um vetor multi-
dimensional descarta o ltimo sub-vetor no vetor destino especificado, o que causa a
perda de uma ou mais dimensoes. Para inserir uma nova dimensao em um vetor,
primeiramente adicione um novo elemento ao final do vetor utilizando AADD() ou
ASIZE() antes de usar AINS().
ARRAY
Reviso: 26/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verses Anteriores

Sintaxe
ARRAY ( < nElementos,... > ) --> aVetor
Parmetros
Argumento Tipo Descrio
nElementos,... Numrico
<nElementos> a quantidade de elementos na dimensao
especificada.Os vetores em Advpl podem ter um nmero
ilimitado de dimensoes.
Retorno
Tipo Descrio
Array ARRAY() retorna um vetor de dimensoes especificadas.
Descrio
ARRAY() uma funao de tratamento de vetor que retorna um vetor nao inicializado
com a quantidade especificada de elementos e dimensoes. Se for especificado mais de
um argumento <nElementos>, criado um vetor multi-dimensional ou aninhado, sendo
que a quantidade de dimensoes igual quantidade de argumentos <nElementos>
especificada.

No Advpl, h vrias formas de se criar um vetor. Voc pode declarar um vetor
utilizando LOCAL ou STATIC; voc pode criar um vetor utilizando PRIVATE ou
PUBLIC; voc pode atribuir um vetor literal a uma varivel existente; ou voc pode
usar a funao ARRAY(). ARRAY() tem a vantagem de possibilitar a voc a criaao de
vetores dentro de expressoes ou blocos de cdigo.
ASCAN
Reviso: 26/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm
Parmetros
Argumento Tipo Descrio
aDestino Array <aDestino> o vetor a ser varrido.
ProcuraExp (Qualquer)
<ProcuraExp> pode ser um valor simples a ser
procurado, ou um bloco de cdigo. Caso <ProcuraExp>
seja um valor simples, este poder ser do tipo numrico,
lgico, data, ou caractere.
nInicio Numrico
<nInicio> o elemento a partir do qual ter incio a
pesquisa. Se este argumento nao for especificado, a
posiao inicial padrao um.
nCont Numrico
<nCont> a quantidade de elementos que serao varridos
a partir da posiao inicial. Caso este argumento nao seja
especificado, todos os elementos, desde o elemento
inicial at o final do vetor, serao varridos.
Retorno
Tipo Descrio
Numrico
ASCAN() retorna um valor numrico que representa a posiao ocupada no
vetor pelo ltimo elemento varrido. Se <ProcuraExp> for um valor
simples, ASCAN() retorna a posiao do primeiro elemento que
corresponder ao valor procurado, ou zero caso nao haja correspondncia.
Se <ProcuraExp> for um bloco de cdigo, ASCAN() retorna a posiao do
elemento onde o bloco retornou verdadeiro (.T.).
Descrio
ASCAN() uma funao de tratamento de vetor que varre um vetor procurando um valor
especificado e opera da mesma forma que o comando SEEK quando pesquisa um valor
simples. O valor <ProcuraExp> comparado ao elemento de vetor destino que comea
com o caractere mais esquerda no elemento destino e prossegue at que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondncia, ASCAN() vai
para o prximo elemento no vetor.

Como ASCAN() utiliza o operador (=) para comparaoes, ele sensvel ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente
igual ao resultado de <ProcuraExp> para que haja correspondncia.

Se o argumento de <ProcuraExp> seja um bloco de cdigo, ASCAN() varre o vetor
<aDestino> executando o bloco para cada elemento acessado. medida em que cada
elemento encontrado, ASCAN() passa o valor do elemento como um argumento para
o bloco de cdigo, e depois executa um EVAL() no bloco. A operaao de pesquisa pra
quando o bloco de cdigo retorna verdadeiro (.T.), ou quando ASCAN() atinge o ltimo
elemento no vetor.
ASIZE
Reviso: 13/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
ASIZE ( < aDestino > , < @nTamanho > ) --> ASIZE()
Parmetros
Argumento Tipo Descrio
aDestino Array <aDestino> o vetor a ser aumentado ou diminuido.
nTamanho Numrico <nTamanho> o novo tamanho do vetor.
Retorno
Tipo Descrio
Array Retorna uma referncia ao array aDestino.
Descrio
ASIZE() uma funo de tratamento de vetor que muda o valor real do vetor
<aDestino>. O vetor diminuido ou aumentado para corresponder ao tamanho
especificado. Caso o vetor seja diminuido, os elementos no final do vetor sao perdidos.
Se o vetor for aumentado, novos elementos sao adicionados ao final do vetor e a eles
atribuido NIL.

ASIZE() semelhante a AADD(), o qual adiciona somente um novo elemento ao final
de um vetor e opcionalmente atribui um novo valor ao mesmo tempo. Observe que
ASIZE() diferente de AINS() e ADEL(), os quais na realidade nao modificam o
tamanho do vetor.
ASORT
Reviso: 26/07/2002
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
ASORT ( < aDestino > , [ nInicio ] , [ nCont ] , [ bOrdem ] ) --> aDestino
Parmetros
Argumento Tipo Descrio
aDestino Array
<aDestino> o vetor cujos elementos serao colocados
em ordem.
nInicio Numrico
<nInicio> o primeiro dos elementos que serao
colocados em ordem. Caso nao seja especificada, a
posiao inicial assumida um.
nCont Numrico
<nCont> a quantidade de elementos que serao
colocados em ordem. Se nao for especificada, todos os
elementos no vetor que comeam com o elemento inicial
sao ordenados.
bOrdem Code-Block
<bOrdem> um bloco de cdigo opcional utilizado para
determinar qual a ordem que ser seguida. Caso nao seja
especificada, a ordem padrao ascendente. *** Ateno
: Caso utilizada a funo aSort para um array aninhado
(milti-dimensional), o parmetro bOrdem deve ser
passado ; caso contrrio o array no ser ordenado.
Retorno
Tipo Descrio
Array ASORT() retorna uma referncia ao vetor <aDestino>.
Descrio
ASORT() uma funao de vetor que coloca em ordem todo ou parte de um vetor que
contm elementos de um nico tipo de dados. Os tipos de dados que podem ser
ordenados incluem caractere, data, lgico e numrico.

Se o argumento <bOrdem> nao for especificado, a ordem padrao ascendente.
Elementos com valores baixos sao colocados no incio do vetor (primeiro elemento),
enquanto elementos com valores altos sao colocados no final do vetor (ltimo
elemento).
Caso o argumento de bloco <bOrdem> seja especificado, ele utilizado para determinar
a ordem em que os elementos serao colocados. Cada vez que o bloco avaliado, dois
elementos do vetor destino sao passados como parmetros de bloco. O bloco deve
retornar verdadeiro (.T.) se os elementos estiverem ordenados. Isto pode ser usado para
criar uma ordem descendente ou de dicionrio. Veja os exemplos abaixo.

Quando ordenadas, as cadeias de caracteres sao colocadas na sequncia ASCII; valores
lgicos sao ordenados com falso (.F.) sendo considerado o valor menor; valores data sao
ordenados cronologicamente; e numricos sao ordenados por magnitude.

OBSERVAO : Sendo os vetores multi-dimensionais em Clipper implementados
atravs do aninhamento de sub-vetores dentro de outros vetores, ASORT() nao ordena
diretamente vetores deste tipo. Para ordenar um vetor aninhado, voc deve fornecer um
bloco de cdigo que dar o tratamento adequado aos sub-vetores.
Funes de Impresso
GETIMPWINDOWS
Reviso: 05/05/2003
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10

Sintaxe
GETIMPWINDOWS ( < lServer > ) --> aPrinters
Parmetros
Argumento Tipo Descrio
lServer Lgico
Informar .T. se a lista de impressoras deve ser obtida do
Protheus Server ou .F. para obter lista de imporessoras da
estao Remota. Este parmetro obrigatrio.
Retorno
Tipo Descrio
Array
Array com nome das impressoras disponveis. Vale lembrar que esta
funo no verifica o status atual da(s) impressora(s) encontrada(s).
Descrio
GETIMPWINDOWS( ) retorna uma lista de impressoras disponveis no spool do Server
ou Remote. Se o Server est em ambiente Unix, a GETIMPWINDOWS() retornar a
lista com os nomes de impressoras cadastradas na chave PRINTERSNAME do arquivo
de configurao do Protheus Server.

Caso no seja encontrada nenhuma impressora , retornado um array com 1 elemento ,
contendo a String "Nenhuma Impressora Disponivel".

Observao : Caso a funo seja passada com o argumento .F. ( buscar
impressoras da estao Remote ) , porm a funo seja executada a partir de um
JOB ( programa sem a interface Remota ) , o array retornado ter apenas 1
elemento , contendo a String "Nenhuma Impressora Disponivel".
GETPORTACTIVE
Reviso: 23/12/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11

Sintaxe
GETPORTACTIVE ( < lServer > ) --> aPortImp
Parmetros
Argumento Tipo Descrio
lServer Lgico
CAso especificado .T. , a lista de impressoras ser obtida
do Server, caso .F. a lista ser obtida da estao (Remote).
Retorno
Tipo Descrio
Array Array com as portas de impresso disponveis.
Descrio
Retorna lista de portas de impresso disponveis. A funo GETPORTACTIVE( )
retorna uma lista de portas de impresso disponveis do Protheus Server ou Remote. Se
o Protheus Server est em ambiente Unix, a GETPORTACTIVE() retornar uma lista
com os nomes de devices possveis para impresso.
Caso no sejam encontradas portas para impresso , retornado um array com apenas
um elemento , contendo a string "Nao existem portas disponiveis".
Observao : Caso a funo seja chamada com o parmetro .F. , para obter as
portas de impresso da estao remota , porm a funo seja chamada atravs de
um JOB ( programa sem a interface Remote ) , a mesma retornar um array com
um elemento , contendo a string "Nao existem portas disponiveis".
[RELEASE] Builds superiores a 7.00.041130p
Ao verificar os devices de impresso disponveis no SERVER, os devices especificados
na configurao de bloqueio de portas de impresso ( DisableDevicePort ) no server
no so listados por esta funo.
Quando executada em ambiente Linux, os devices de impresso disponveis no
SERVER, a funo deixa de retornar os devices como /dev/lp0 e /dev/ttys0 ... e passa a
retorn-los a nomenclatura LPT1:...COM1:... , limitando o retorno em no mximo
4 portas paralelas e 4 portas seriais.
Funes de Interface HTTP
GETWEBJOB
Reviso: 16/10/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
GETWEBJOB ( ) --> cJobName
Retorno
Tipo Descrio
Caracter
cJobName corresponde o nome do job que configura a working Thread
atual em uso. Caso a chamada da funo seja realizada a partir de uma
thread que no seja uma Working Thread ( como por exemplo , uma
thread iniciada a partir de um ApxRemote ) , a funo GetWebJob()
retornar uma string vazia ("").
Descrio
Atravs desta funo , possvel recuperar o nome da configurao de Working
Threads ( Job ) que est sendo utilizada pela Working Thread atual.

Observao : Esta funo est disponvel a partir dos Build's Ap6 gerados a partir
de 05/09/2002.
HTTPCACHE
Reviso: 16/09/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPCACHE ( < cCacheControl > ) --> cLastCache
Parmetros
Argumento Tipo Descrio
cCacheControl Caracter
Define o novo contedo da etiqueta do Header de Retorno
HTTP Cache-Control.
Retorno
Tipo Descrio
Caracter
Esta funo retorna a definio atualmente utilizada para a etiqueta Cache-
Control do Header HTTP.
Descrio
Atravs desta funo , podemos redefinir a etiqueta CACHE-CONTROL do Header de
Resposta de requisio HTTP , sobrepondo definio defaut de retorno CACHE-
CONTROL , opcionalmente definida na configurao do HOST HTTP no Arquivo de
configurao do Protheus Server.
Tabela A - Definies CACHE-CONTROL
Contedo Aplicao
no-store
Nenhuma informao deve ser guardada em Cache pelo servidor e/ou
proxie(s).


Observao : A definio de um novo contedo para o CACHE-CONTROL do
Header HTTP apenas ser possvel caso esta funo Advpl seja executada antes de
qualquer envio parcial de html ao browser , realizado pela funo HttpSend().
HTTPCOUNTSESSION
Reviso: 25/08/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPCOUNTSESSION ( ) --> nCount
Retorno
Tipo Descrio
Numrico
nCount corresponde ao nmero de usurios que possuem variveis de
session em uso no Server PRotheus.
Descrio
Esta funo retorna o nmero de Sessions de usurios que esto atualmente em uso na
memria.

** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um Build de Protheus Server com data igual ou superior a
22/04/2002.
HTTPFREESESSION
Reviso: 25/08/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPFREESESSION ( ) --> NIL
Retorno
Tipo Descrio
(NULO) Esta funo sempre retorna NIL
Descrio
Atravs da funo HttpFreeSession , eliminamos da memria do Servidor Protheus
todas as variveis de Session do usurio atual. Normalmente utilizamos esta funo em
operaes de LOGOFF , onde necessitamos limpar todas os conteudos relacionados
Session deste usurio.

** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um Build do Servidor Protheus Server com data igual ou superior a
22/04/2002.
HTTPGET
Reviso: 16/08/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPGET ( < cUrl > , [ cGETParms ] , [ nTimeOut ] ) --> cHttp
Parmetros
Argumento Tipo Descrio
cUrl Caracter
cUrl corresponde ao endereo http , juntamente com a
pasta e o documento solicitados.
cGETParms Caracter
cGETParms corresponde StringList de parmetros a
serem enviados ao servidor http atravs da URl . Caso no
especificado , este parmetro considerado vazio ("")
nTimeOut Numrico
Em nTimeOut especificamos o tempo em segundos
mximo de inatividade permitido durante a recepo do
documento . Caso no especificado , o valor default
assumido 120 segundos ( 2 minutos).
Retorno
Tipo Descrio
Caracter String Html correspondendo ao documento solicitado.
Descrio
A funo HttpGet() permite a emulao de um Client HTTP atravs de uma funo
Advpl, acessando um determinado documento html publicado em um servidor Web,
utiliando o mtodo GET , permitindo a passagem de parmetros via URL, aguardando
por um tempo determinado (time-out) pela resposta do servidor solicitado.

Observaes :

--- Na passagem de parmtros GET , devemos atentar ao formato da string a ser passada
como parmetros , pois a mesma segue o formato URI (Uniform Resource Identifiers) :
Query Component.
--- Caso nao seja retornado o documento antes do trmino do Time-out especificado na
chamada da funo; ou caso no seja possvel localizar o servidor ; seja por falha de
resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a funo retornar
Nulo (NIL).
--- Caso nao seja possvel o acesso ao documento , como por exemplo o documento no
exista , ser retornado uma string html com a mensagem de erro html enviada pelo
servidor correspondente.
OBSERVACAO : Esta funco est disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002
HTTPLEAVESESSION
Reviso: 25/08/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPLEAVESESSION ( ) --> NIL
Retorno
Tipo Descrio
(NULO) A funo HttpLeaveSession() sempre retorna NIL
Descrio
Esta funo , uma vez executada , libera o processamento de requisio de atualizo
de contedos de variveis tipo HttpSession para requisies de consulta e/ou
atualizaes simultneas para o usurio atual.

** ATENO : Devemos atentar ao fato que esta funo apenas ter o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAO : Esta funo foi implementada na Ferramenta Ap6 Server , sendo
necessrio adquirir um build de Server PRotheus com data igual ou superior a
22/04/2002.
HTTPLOGONUSER
Reviso: 24/09/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPLOGONUSER ( ) --> cLogonUser
Retorno
Tipo Descrio
Caracter
String contendo o login do usurio, no formato DOMINIO\login. Caso a
funo no seja executada em uma thread iniciada em uma interface http ,
ou o acesso annimo o site no IIS esteja habilitado , a funo retornar
uma string em branco ("").
Descrio
Atravs da Funo HttpLogonUser() , quando utilizamos o AP Server ISAPI (
AdvplIsapi.dll) , em conjunto com o Microsoft IIS (Internet Information Services ) ,
obtemos o login do usurio atual.

Observao : Para que o usurio seja obrigado a informar um login individual ,
deve ser desabilitado no IIS a configurao que permite acesso annimo ao site.
Caso esta configurao no seja alterada , todos os usurios sero identificados
como "annimos" pelo IIS, e a funo retornar uma String em branco.
HTTPOTHERCONTENT
Reviso: 10/09/2002
Abrangncia
Verso 7.10

Sintaxe
HTTPOTHERCONTENT ( ) --> cContent
Retorno
Tipo Descrio
Caracter
cContent a string correspondendo ao contedo do corpo do pacote
HTML postado no Server.
Descrio
A funo HttpOtherContent() , quando utilizada em uma thread montada e/ou
inicializada para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do
pacote html proveniente de uma operao de POSTagem de dados, se e somente se a
operaco de POSTagem especificou no HEader HTTP um content-disposition ou
content-type no tratados automaticamente pelo Server PRotheus.

Caso a requisio no tenha sido realizada por um client HTTP atravs do mtodo de
postagem , ou a postagem j possua tratamento nativo no Server Protheus , ou a funo
seja chamada em um ambiente que no esteja atendendo uma requisio Http ( como
um JOB , por exemplo) , a funo retornar uma string em branco ("").
HTTPPOST
Reviso: 07/08/2003
Abrangncia
Verso 6.09 Verso 7.10 Verso 8.11

Sintaxe
HTTPPOST ( < cUrl > , [ cGETParms ] , [ cPOSTParms ] , [ nTimeOut ] , [ aHeadStr ]
) --> cHtml
Parmetros
Argumento Tipo Descrio
cUrl Caracter
cUrl corresponde ao endereo http , juntamente com a
pasta e o documento solicitados.
cGETParms Caracter
cGETParms corresponde StringList de parmetros a
serem enviados ao servidor http atravs da URl . Caso no
especificado , este parmetro considerado vazio ("")
cPOSTParms Caracter
cPostParms corresponde StringList de parmetros a
serem enviados ao servidor http atravs do pacote HTTP .
Caso no especificado , este parmetro considerado
vazio ("")
nTimeOut Numrico
Em nTimeOut especificamos o tempo em segundos
mximo de inatividade permitido durante a recepo do
documento . Caso no especificado , o valor default
assumido 120 segundos ( 2 minutos).
aHeadStr Array
Atravs deste parametro , podemos especificar um array
com strings a serem acrescentadas ao Header da
requisio HTTP a ser realizada.
Retorno
Tipo Descrio
Caracter
Atravs de cHtml ser retornada a String Html correspondendo ao
documento solicitado.
Descrio
A funo HttpPost() permite a emulao de um Client HTTP atravs de uma funo
Advpl, postando um bloco de informaes para um determinado documento publicado
em um servidor Web, utiliando o mtodo POST , permitindo a passagem de parmetros
adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta
do servidor solicitado.

Observaes :
Na passagem de parmtros GET e POST , devemos atentar ao formato da string
a ser passada como parmetros , pois a mesma segue o formato URI (Uniform
Resource Identifiers) : Query Component.
Caso nao seja retornado o documento antes do trmino do Time-out especificado
na chamada da funo; ou caso no seja possvel localizar o servidor ; seja por
falha de resoluo de DNS , ou por erro de sintaxe ao especificar a URL , a
funo retornar Nulo (NIL).
Caso nao seja possvel o acesso ao documento , como por exemplo o documento
no exista ,ser retornado uma string html com a mensagem de erro html
enviada pelo servidor correspondente.
Quando utilizamos a funo HttpPost() , podemos especificar um Content-Type
diferenciado para o contedo postado. Caso no seja especificado um Content-
Type , alguns servidores tratam a informao postada como sendo um dado do
tipo 'application/x-www-form-url' , seria o equivalente a um formulrio HTML
postado via Browser, outros servidores podero no reconhecer tal informao
postada dessa forma. Para especificar que o contedo postado deve ser tratado
como um POST de formulrio HTTP , devemos passar no parmetro aHeadStr ,
um elemento contendo 'Content-Type: application/x-www-form-url'.
ATENO
1. Esta funco est disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002 .
2. O parametro aHeadStr apenas est disponvel em Build's Ap6 e posteriores
gerados apos 01/10/2002.
HTTPPRAGMA
Reviso: 16/09/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPPRAGMA ( < cPragma > ) --> cOldPragma
Parmetros
Argumento Tipo Descrio
cPragma Caracter
cPragma corresponde ao conteudo do PRAGMA a ser
definido no Header de retorno HTTP. Veja tabela "A" de
definies PRAGMA.
Retorno
Tipo Descrio
Caracter
A funo HttpPragma retornar a definio anterior de PRAGMA
utilizada.
Descrio
Atravs desta funo , podemos redefinir a etiqueta PRAGMA do Header de Resposta
de requisio HTTP , sobrepondo definio defaiut de retorno PRAGMA ,
opcionalmente definida na configurao do HOST HTTP no Arquivo de configurao
do Protheus Server.
Tabela A - Definies Pragma
Contedo Aplicao
no-cache
Informa ao Client HTTP ( Browser ) que a pgina retornada no deve ser
colocada em Cache, independente da configurao de Cache do Browser.


Observao : A definio de um novo contedo para o PRAGMA do Header
HTTP apenas ser possvel caso esta funo Advpl seja executada antes de
quaqlquer envio parcial de html ao browser , realizado pela funo HttpSend().
HTTPRCTDISP
Reviso: 10/09/2002
Abrangncia
Verso 7.10

Sintaxe
HTTPRCTDISP ( ) --> cCtDisp
Retorno
Tipo Descrio
Caracter
cCtDisp corresponde o conteudo do identificador Content-disposition ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.
Descrio
A funo HttpRCtDisp() , quando utilzada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-disposition do Header HTTP .

Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no
esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo
retornar uma String em branco ("").
HTTPRCTLEN
Reviso: 10/09/2002
Abrangncia
Verso 7.10

Sintaxe
HTTPRCTLEN ( ) --> nCtLen
Retorno
Tipo Descrio
Numrico
nCtLen corresponde o conteudo do identificador Content-length ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.
Descrio
A funo HttpRCtLen() , quando utilizada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-length do Header HTTP , como um dado numrico .

Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no
esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo
retornar 0 ( Zero ) .
HTTPRCTTYPE
Reviso: 10/09/2002
Abrangncia
Verso 7.10

Sintaxe
HTTPRCTTYPE ( ) --> cCtType
Retorno
Tipo Descrio
Caracter
cCtType corresponde o conteudo do identificador Content-type , recebido
quando um Web Browser realiza uma requisio via HTTP ao servidor.
Descrio
A funo HttpRCtType() , quando utilzada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo do identificador
Content-type do Header HTTP .

Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no
esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo
retornar uma String em branco ("").
HTTPSEND
Reviso: 10/09/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPSEND ( < cHtmlStr > ) --> cHtmlNoSend
Parmetros
Argumento Tipo Descrio
cHtmlStr Caracter
cHtmlStr corresponde string a ser enviada ao Browser
solicitante de um processamento .
Retorno
Tipo Descrio
Caracter
Caso a funo obtenha sucesso em enviar a String cHtmlStr para o Browse
solicitante , o retorno ser uma string vazia ("").

Caso no seja possvel o envio da string , devido o recurso de envio
simultneo estar desabilitado ; ou ocorra uma falha de comunicao, ou a
funo HttpSend() seja executada a partir de uam thread que no uma
Working Thread , a funo ir retornar a string passada como parmetro.
Descrio
Atravs desta funo, possivel retornar uma string Html um browser durante o
processamento de uma requisio realizada atravs de um link .APW , utilizando
Working Threads , durante o processamento da mesma.

Observao : Este recurso no funciona em requisies de procesamento
realizadas a partir de um link .apl . necessrio que a requisio seja para um
link .apw , atendida por uma Working Thread.
HTTPSETPART
Reviso: 10/09/2002
Abrangncia
Verso 6.09 Verso 7.10

Sintaxe
HTTPSETPART ( < lHttpSend > ) --> NIL
Parmetros
Argumento Tipo Descrio
lHttpSend Lgico
lHttpSend um valor booleano que habilita o envio parcial
( caso .T. ) ou desabilita o envio parcial de HTML ( .F. )
Retorno
Tipo Descrio
(NULO) Esta funo sempre retorna NIL
Descrio
Atravs desta funco , podemos habilitar ou desabilitar o envio parcial de Html ,
realizado pela funo HttpSend() , para o Browser solicitante de um processamento
Advpl atravs de uma Working Thread.
SOAPRACTION
Reviso: 10/09/2002
Abrangncia
Verso 7.10

Sintaxe
SOAPRACTION ( ) --> cSoapAction
Retorno
Tipo Descrio
Caracter
cSoapAction corresponde o conteudo do identificador soapaction ,
recebido quando um Web Browser realiza uma requisio via HTTP ao
servidor.
Descrio
A funo SoapRAction() , quando utilizada em uma thread montada e/ou inicializada
para atender uma requisio Http ( .apl , .apw ) , retorna o contedo string do
identificador soapaction do Header HTTP .

Caso a requisio tenha sido realizada por um client HTTP que no enviou este
identificador no Header HTTP , ou a funo seja chamada em um ambiente que no
esteja atendendo uma requisio Http ( como um JOB , por exemplo) , a funo
retornar uma string em branco ("").