Você está na página 1de 151

Funções Genéricas

EVAL
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

EVAL ( < bBloco > , [ ] ) --> UltValorBloco

Parâmetros

Argumento Tipo Descrição


bBloco Code-Block <bBloco> é o bloco de código a ser avaliado.
<ListaArgBloco> é uma lista de argumentos a ser
<ListaArgBloco> (Qualquer)
enviada ao bloco de código antes que ele seja avaliado.

Retorno

Tipo Descrição
EVAL() retorna o valor da última expressao dentro do bloco. Um bloco de
(Qualquer)
código pode retornar um valor de qualquer tipo.

Descrição

EVAL() é uma funçao de tratamento de blocos de código. Ela é o dispositivo mais


básico no sistema Advpl para avaliar blocos de código. Um bloco de código é um valor
de dados especiais que se refere a uma parte do código de programa compilado. Para
maiores informaçoes sobre blocos de código, consulte o capítulo Conceitos Básicos
neste livro.
Para executar ou avaliar um bloco de código, você pode chamar EVAL() com o valor de
bloco e quaisquer parâmetros. Os parâmetros sao Fornecidos ao bloco quando ele é
executado. Blocos de código podem ser uma série de expressoes separadas por vírgulas.
Quando um bloco de código é avaliado, o valor retornado é o valor da última expressao
no bloco.
Um bloco de código geralmente é compilado em tempo de compilaçao pelo compilador
do Advpl. Existem, porém, ocasioes em tempo de execuçao quando pode ser necessário
que você compile um bloco de código a partir de uma cadeia de caracteres. Isto pode ser
feito utilizando-se o operador macro (&).
EVAL() é frequentemente utilizado para criar funçoes iterator. Estas funçoes aplicam
um bloco para cada membro de uma estrutura de dados. AEVAL(), ASORT(),
ASCAN(), e DBEVAL() sao funçoes iterator. AEVAL(), por exemplo, aplica um bloco
para cada elemento dentro de um vetor.
GETREMOTETYPE
Revisão: 19/11/2004

Abrangência

Versão 8.11

Sintaxe

GETREMOTETYPE ( ) --> nRmtType

Retorno

Tipo Descrição
Numérico nRmtType corresponde ào número correspondente à interface utilizada.

Descrição

Através da função GetRemoteType(), é possível identificar sob qual interface o


programa atual está em execução.

Esta função está disponível a partir do Protheus 8, Build 7.00.040308a

Pode-se utilizar as constantes abaixo, para avaliar o retorno da função.

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
Revisão: 12/06/2003

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

ISSRVUNIX ( ) --> lisUnix

Retorno

Tipo Descrição
Se .T. o servidor está sendo executado em ambiente Unix(r) ou Linux(r)
Lógico
Se .F. o servidor está sendo executado em ambiente Windows(r)

Descrição

Informa se o servidor Advanced Protheus está sendo executado em ambiente UNIX ou


Linux.
MSCRC32
Revisão: 03/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Sintaxe

MSCRC32 ( < cString > ) --> nCRC

Parâmetros

Argumento Tipo Descrição


String de onde será calculado um CRC32, é garantido que
para a mesma string sempre se obterá um mesmo número,
cString Caracter
porém, não é garantido que para strings diferentes, os
números sejam sempre diferentes.

Retorno

Tipo Descrição
Um número inteiro , com até 10 (dez) dígitos , correspondente ao CRC da
Numérico
string informada como parâmetro.

Descrição

Calcula um CRC de uma string. A função MSCRC32() calcula um CRC de uma string
informada e retorna um número com esse cálculo.

Note que strings iguais retornam CRC iguais, porém, nem sempre strings diferentes
retornam CRC diferentes.
MSCRC32STR
Revisão: 02/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Sintaxe

MSCRC32STR ( < cString > ) --> cCRC32

Parâmetros

Argumento Tipo Descrição


String a partir da qual será calculado o CRC32. É garantido
que para a mesma string sempre será obtido um mesmo
cString Caracter
CRC , mas não é garantido que para strings diferentes os
CRCs sejam sempre diferentes.

Retorno

Tipo Descrição
Caracter Uma string com o CRC da string informada.

Descrição

MSCRC32STR() calcula um CRC de uma string informada , retornando uma string com
esse cálculo.

Note que strings iguais retornam CRC iguais, porém nem sempre strings diferentes
retornam CRC diferentes.
RANDOMIZE
Revisão: 11/12/2003

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

RANDOMIZE ( < nMinimo > , < nMaximo > ) --> nAleatorio

Parâmetros

Argumento Tipo Descrição


nMinimo Numérico Corresponde ao menor numero a ser gerado pela função.
Corresponde ao maior número ( menos um ) a ser gerado
nMaximo Numérico
pela função.

Retorno

Tipo Descrição
Numero randômico , compreendido no intervalo entre (nMinimo) e
Numérico (nMaximo-1) : O numero gerado pode ser maior ou igual à nMinimo e
menor ou igual a nMaximo-1 .

Descrição

Através da função randomize() , geramos um numero inteiro aleatório, compreendido


entre a faixa inferior e superior recebida através dos parâmetros nMinimo e nMaximo,
respectivamente.

Observação :

O limite inferior recebido através do parâmetro nMinimo é "maior ou igual a ", podendo
ser sorteado e fazer parte do retorno; porém o limite superior é "menor que", de modo a
nunca será atingido ou devolvido no resultado. Por exemplo , a chamada da função
randomize(1,2) sempre retornará 1 .
SENDTOFORE
Revisão: 14/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Sintaxe

SENDTOFORE ( ) --> Nil

Retorno

Tipo Descrição
(NULO) Esta função não retorna valor

Descrição

Esta função torna a aplicação do Remote foreground na estação em que está sendo
executado.

Faz com que a janela ativa do Remote fique acima de todas as janelas de outras
aplicações executadas na estação.

Extremamente dependente do sistema operacional em uso, as vezes pode falhar devido


ao sistema operacional não suportar o comando ou devido a carga excessiva do sistema,
o sistema operacional pode ignorar o comando.
XMLERROR
Revisão: 16/07/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

XMLERROR ( ) --> nXmlStatus

Retorno

Tipo Descrição
Retorna o status da ultima operação de Criação de Objeto XML realizado
Caracter
pelo comando CREATE oXml ...

Descrição

A funcao XmlError() retorna um status da execução da ultima rotina de criação 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
----------------------------------------
Funções de Banco de Dados
ALIAS
Revisão: 25/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ALIAS ( [ nAreaTrabalho ] ) --> cAlias

Parâmetros

Argumento Tipo Descrição


<nAreaTrabalho> é o número da área de trabalho a ser
nAreaTrabalho Numérico
verificada.

Retorno

Tipo Descrição
ALIAS() retorna o alias da área de trabalho especificada na forma de uma
cadeia de caracteres, em letra maiúscula. Caso <nAreaTrabalho> nao seja
Caracter 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 ("").

Descrição

ALIAS() é uma funçao 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 através da cláusula
ALIAS do comando USE.

ALIAS() é o inverso da funçao SELECT(). ALIAS() retorna o alias através do número


da área de trabalho, e SELECT() retorna o número da área de trabalho através do alias.
BTVCANOPEN
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

BTVCANOPEN ( < cNome > , [ cIndice ] ) --> lRet

Parâmetros

Argumento Tipo Descrição


cNome Caracter Nome da tabela a ser testada.
cIndice Caracter Nome do arquivo de índice da tabela a ser testada.

Retorno

Tipo Descrição
Retorna falso se não foi possível abrir a tabela a ser testada. Principais
motivos: Não existe o arquivo da tabela ou
(NULO) do índice fisicamente; ou as definições da tabela ou índice em questão não
foram encontradas.
Retorna verdadeiro se a tabela testada pode ser aberta.

Descrição

BTVCONOPEN() é uma função que verifica se a tabela definida pelo parâmetro cNome
pode ser aberta e, se existir, o parâmetro cIndice verifica, também, se o índice pode ser
aberto. Para tanto, é testado se os arquivos envolvidos existem fisicamente, caso
afirmativo, é verificado se as definições envolvidas são encontradas nos arquivos do
DDF's.

Exemplo
// Este exemplo demonstra o uso típico de BTVCanOpen().
Se não falhar, a tabela e o índice testados serão abertos. Se falhar,
uma mensagem é apresentada.

IF !BTVCanOpen("\dadosadv\aa1990.dat","\dadosadv\ind1.ind")
Messagebox("Não é possível abrir a tabela testada","Erro", 0)
ELSE
Use "\dadosadv\aa1990.dat" SHARED NEW
OrdListAdd("\dadosadv\ind1.ind")
ENDIF
BTVCREATEDDFS
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

BTVCREATEDDFS ( < aTabelas > , < cDiretorio > ) --> lRet

Parâmetros

Argumento Tipo Descrição


aTabelas Array Nomes das tabelas e os respectivos diretórios.
Nome do diretório (abaixo do root) onde serão criados os
cDiretorio Caracter
novos DDF's.

Retorno

Tipo Descrição
Retorna falso se não conseguiu gerar os novos arquivos de definição.
Principais erros: RDD não é Btrieve; diretório não está dentro do Protheus;
não pode carregar as informações de definição
(NULO)
ou não pode gravar os novos arquivos de definição.

Retorna verdadeiro se a transformação de definições ocorrida com sucesso.

Descrição

BTVCREATEDDFS() é uma função que transforma as informações armazenadas nos


arquivos DDF's para o padrão utilizado por outras ferramentas, principalmente para
geração de relatórios. Sendo que podem ser selecionadas apenas as tabelas de interesse
através do parâmetro aTabelas.
Ex: aTabelas := {{"AA3990", "C:\DADOS"},{"AA4990","C:\DADOS1"},
{"AA5990"}}
Se o diretório não for especificado, será utilizado o diretório definido no arquivo
FILE.BTV.
Os novos arquivos de definição, FILE.DDF, FIELD.DDF e INDEX.DDF, são
gerados no diretório especificado pelo parâmetro cDiretório, se ele
for omitido, serão gerados no mesmo diretório dos SXs.
Exemplo:
// Este exemplo demonstra o uso típico de BTVCreateDDFs().
Se não falhar, serão gerados os novos arquivos de definição. Se falhar,
uma mensagem é apresentada.
b:= {{"AA3990"}, {"SA1990", "c:\protheus507\dadosadv"}}
IF !BTVCreateDDFs(b,"\temp")
Messagebox("Não foi possível montar o array com os nomes das tabelas","Erro", 0)
ENDIF
BTVDROPIDXS
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

BTVDROPIDXS ( ) --> lRet

Retorno

Tipo Descrição
Retorna Falso se não conseguiu apagar os índices. Principais erros: RDD
não é Btrieve, não achou as definições no DDF, o arquivo não está
Lógico
exclusivo;
Retorna Verdadeiro se a deleção de índices ocorrida com sucesso;

Descrição

BTVDropIdxs() apaga os índices da tabela corrente, com exceção 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 definições dos índices nos arquivos do diretório 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
serão abertos também. Por isso, é recomendada a criação de índices de
forma temporária.

Exemplo:
// Este exemplo demonstra o uso típico de BTVDropIdxs(). Se não falhar, os índices são
apagados e o processo continua. Se falhar, uma mensagem é apresentada.

USE Clientes SHARED NEW


IF !BTVDropIdxs()
Messagebox("Não foi possível deletar os índices da tabela corrente","Erro",
0)
ENDIF
BTVTABLES
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

BTVTABLES ( ) --> aTables

Retorno

Tipo Descrição
Retorna NIL se não conseguiu montar o array. Principais erros: RDD não é
Btrieve ou não conseguiu recuperar as informações corretamente do
Array
arquivo FILE.BTV do DDFs.
Retorna um Array com a lista com os nomes das tabelas extraídas do DDF.

Descrição

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 definições.

Exemplo:
// Este exemplo demonstra o uso típico de BTVTables(). Se não falhar, é montado um
array com os nomes das tabelas e esses nomes são mostrados no servidor. Se falhar,
uma mensagem é apresentada.

a:= BTVTables()
IF a=Nil
Messagebox("Não foi possível montar o array com os nomes das tabelas","Erro", 0)
ELSE
FOR i:= 1 to LEN(a)
ConOut(a[i])
NEXT
ENDIF
CTREEDELIDXS
Revisão: 26/08/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

CTREEDELIDXS ( ) --> lRet

Retorno

Tipo Descrição
Retorna Falso se não conseguiu deletar os índices. Principais
erros: RDD não é Ctree, não fechou a tabela, não apagou o arquivo de
Lógico índice ou não atualizou as informações da tabela; não abriu a tabela
novamente.
Retorna Verdadeiro se a deleção de índices ocorrida com sucesso.

Descrição

CtreeDelIdxs() apaga os índices da tabela corrente, com exceção 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 informações 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, não adianta deletar os arquivos de índices, pois quando a tabela for
aberta, todos os índices criados de forma permanente e o índice interno serão recriados
fisicamente (se não existirem); caso contrário, a tabela não será aberta. Por isso, é
recomendada a criação de índices de forma temporária.

Importante: Após a remoção dos índices a tabela será posicionada no primeiro registro.
Exemplo:
// Este exemplo demonstra o uso típico de CtreeDelIdxs(). Se não falhar,
os índices são apagados e o processo continua. Se falhar, uma mensagem
é apresentada.
USE Clientes SHARED NEW
IF !CtreeDelIdxs()
Messagebox('Não foi possível deletar os índices da tabela corrente','Erro',0)
ENDIF
CTREEDELINT
Revisão: 22/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

CTREEDELINT ( < cNOME > ) --> lRet

Parâmetros

Argumento Tipo Descrição


Especifica o nome da tabela cujo índice interno deve ser
cNOME Caracter
deletado.

Retorno

Tipo Descrição
Retorna Falso se não conseguiu deletar o índice interno. Principais
erros: tabela não está dentro do diretório do Protheus, não abriu a tabela ou
Lógico
não deletou o arquivo de índice interno.
Retorna Verdadeiro se a deleção do índice interno ocorrida com sucesso.

Descrição

CTREEDELINT() apaga o índice interno de tabela Ctree, estando a mesma fechada.


Para tanto, são executados os seguintes procedimentos:
- Abre a tabela especificada pelo parâmetro 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 após a chamada desta função, pois a tabela CTree não pode
ser aberta sem índice interno.
Exemplo:
// Este exemplo demonstra o uso típico de CtreeDelInt(). Sendo que a tabela
'\dadosadv\sa1990.dtc' deve estar fechada. Se não falhar, o índice interno é apagado e o
processo continua. Se falhar, uma mensagem é apresentada.
IF !CtreeDelInt('\dadosadv\sa1990.dtc')
Messagebox('Não foi possível deletar o índice da tabela','Erro', 0)
ENDIF
fErase('\dadosadv\sa1990.dtc')
DBAPPEND
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBAPPEND ( [ lLiberaBloqueios ] ) --> uRet

Parâmetros

Argumento Tipo Descrição


Se o valor for .T., libera todos os registros bloqueados
lLiberaBloqueios Lógico anteriormente (locks). Se for .F., todos os bloqueios
anteriores são mantidos. Valor default: .T.

Retorno

Tipo Descrição
(NULO) Retorno nulo.

Descrição

DBAPPEND() acrescenta mais um registro em branco no final da tabela corrente. Se


não houver erro da RDD, o registro é acrescentado e bloqueado.
DBCLEARALLFILTER
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLEARALLFILTER ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLEARALLFILTER() salva as atualizações realizadas e pendentes de todas as


tabelas e depois limpa as condições de filtro de todas as tabelas.
DBCLEARALLFILTER
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLEARALLFILTER ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLEARALLFILTER() salva as atualizações realizadas e pendentes de todas as


tabelas e depois limpa as condições de filtro de todas as tabelas.
DBCLEARFILTER
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLEARFILTER ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLEARFILTER() salva as atualizações realizadas e pendentes na tabela corrente e


depois limpa todas as condições de filtro da ordem ativa no momento. Seu
funcionamento é oposto ao comando SET FILTER.
DBCLEARINDEX
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLEARINDEX ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLEARINDEX() salva as atualizações pendentes na tabela corrente e fecha todos os


arquivos de índice da área de trabalho. Por conseqüência, limpa todas as ordens da lista.
Seu funcionamento é oposto ao comando SET INDEX.
DBCLOSEALL
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLOSEALL ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLOSEALL() salva as atualizações 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
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCLOSEAREA ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCLOSEAREA() salva as atualizações 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 à função
DBUSEAREA e ao comando USE.
DBCOMMIT
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCOMMIT ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCOMMIT() salva em disco todas as atualizações pendentes na área de


trabalho corrente.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCOMMIT para salvar todas as
alterações 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 alterações realizadas na tabela Fornecedores
DBCOMMITALL
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCOMMITALL ( ) --> uRet

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCOMMITALL() salva em disco todas as atualizações pendentes em todas


as áreas de trabalho.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBCOMMITALL para salvar todas
as alterações 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 alterações realizadas nas tabelas Clientes e Fornecedores
DBCREATE
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCREATE ( < cNOME > , < aESTRUTURA > , [ @cDRIVER ] ) --> uRet

Parâmetros

Argumento Tipo Descrição


Nome do arquivo da tabela a ser criada (abaixo do
cNOME Caracter
"RootPath").
Lista com as informações dos campos para ser criada a
aESTRUTURA Array
tabela.
Nome do RDD a ser utilizado para a criação da tabela. Se
cDRIVER Caracter
for omitido será criada com o corrente.

Retorno

Tipo Descrição
Caracter Nenhum

Descrição

DBCREATE() é utilizada para criar um novo arquivo de tabela cujo nome


está especificado através do primeiro parâmetro (cNome) e estrutura através do segundo
(aEstrutura).
A estrutura é especificada através de um array com todos os campos,
onde cada campo é expresso através 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 através da função
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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBCREATEINDEX ( < cNOME > , < cEXPCHAVE > , [ bEXPCHAVE ] ,


[ lUNICO ] ) --> uRet

Parâmetros

Argumento Tipo Descrição


cNOME Caracter Nome do arquivo de índice a ser criado.
Expressão das chaves do índice a ser criado na forma de
cEXPCHAVE Caracter
string.
Expressão das chaves do índice a ser criado na forma
bEXPCHAVE Code-Block
executável.
lUNICO Lógico Cria índice como único (o padrão é .F.).

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBCREATEINDEX() é utilizada para criar um novo arquivo de índice com o nome


especificado através do primeiro parâmetro, sendo que se o mesmo existir é deletado e
criado o novo. Para tanto são executados os passos a seguir:
- Salva fisicamente as alterações 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 exceção do RDD Ctree, a tabela corrente não precisa estar aberta em modo
exclusivo para a criação de índice, pois na criação 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 não aceitará duplicação:
USE Cliente VIA "DBFCDX" NEW
DBCREATEINDEX("\teste\ind2.cdx","Nome+End",{ || Nome+End },.T.)
DBDELETE
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBDELETE ( ) --> uRet

Retorno

Tipo Descrição
Caracter Nenhum

Descrição

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 função 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBEVAL ( < bBLOCO > , [ bFORCOND ] , [ bWHILECOND ] , [ nPROXREGS ] ,


[ nRECNO ] , [ lRESTANTE ] ) --> uRET

Parâmetros

Argumento TipoDescrição
Expressão na forma executável a ser resolvida para cada
bBLOCO Code-Block
registro processado.
Expressão na forma executável a ser resolvida para
bFORCOND Code-Block verificar se o registro em questão está dentro do escopo
definido.
Expressão na forma executável a ser resolvida para
bWHILECOND Code-Block verificar até qual registro será processado (até o bloco
retornar .F.).
Número de registros a ser processado a partir do registro
nPROXREGS Numérico
corrente.
Identificação de determinado registro a ser resolvida a
nRECNO Numérico
expressão (recno).
lRESTANTE Lógico Processa o restante dos registro.

Retorno

Tipo Descrição
Caracter Retorno nulo.

Descrição

DBEVAL() é utilizada para executar uma expressão definida pelo bloco


de código do primeiro parâmetro para cada registro que está dentro do
escopo definido através dos blocos de condição de "for" e "while".
O número de registros a ser executado será definido com o parâmetro
nProxRegs ou se setado o parâmetro lRestante serão executados todos
os registros a partir do registro corrente até o final da tabela corrente.
Se for especificado o parâmetro nRecno apenas o registro com o recno especificado será
processado. Se forem omitidos os blocos de "for" e "while",
os mesmos serão considerados .T. como padrão, estão assim todos os registros dentro
do escopo. Se o parâmetro lRestante for omitido a tabela inicia o processamento dos
registros a partir do topo da tabela, caso contrário serão processados os registros a partir
do posicionamento corrente da tabela.

Exemplo:
// Este exemplo mostra como se pode usar o DBEVAL para contar quantos registros
estão dentro do escopo especificado em toda a tabela, pois como o parâmetro 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, serão processados registros com o
Nome cuja ordem alfabética é 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
estão 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 variável 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
décimo 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBF ( ) --> cAlias

Retorno

Tipo Descrição
Retorna o Alias corrente. Caso não exista Alias corrente retorna "" (String
Caracter
vazia).

Descrição

DBF() verifica qual é o Alias da área de trabalho corrente. O Alias é definido


quando a tabela é aberta através do parâmetro correspondente (DBUSEAREA()). Esta
função é o inverso da função SELECT(), pois nesta é retornado o número da área de
trabalho do Alias correspondente.

Exemplo:
// Este exemplo mostra como o DBF corrente pode ser mostrado para o usuário.
dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F. )
MessageBox("O Alias corrente é: "+DBF(),"Alias", 0) //Resultado: "O Alias corrente é:
SSS"
DBFIELDINFO
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBFIELDINFO ( < nINFOTIPO > , < nCAMPO > ) --> xINFO

Parâmetros

Argumento Tipo Descrição


Tipo de informação a ser verificada (DBS_DEC,
nINFOTIPO Numérico
DBS_LEN e DBS_TYPE).
nCAMPO Numérico Posição do campo a ser verificado.

Retorno

Tipo Descrição
Retorna NIL se não há tabela corrente ou a posição do campo
especificado está inválida.
(Qualquer) Informação do campo Informação requisitada pelo usuário (pode ser de
tipo numérico se for tamanho ou casas decimais, tipo caracter se for nome
ou tipo).

Descrição

DBFIELDINFO() é utilizada para obter informações sobre determinado campo da


tabela corrente. O tipo de informação (primeiro argumento) é escolhido de acordo com
as constantes abaixo:
DBS_DEC - Número de casas decimais (tipo numérico)
DBS_LEN - Tamanho (tipo numérico)
DBS_TYPE - Tipo (tipo caracter)
A posição do campo não leva em consideração os campos internos do Protheus (recno e
deleted).
Exemplo:
// Este exemplo demonstra como se pode utilizar o DBFIELDINFO para obter as
informações 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBFILTER ( ) --> cEXPFILTRO

Retorno

Tipo Descrição
Retorna a expressão do filtro ativo na área de trabalho atual. Caso não
Caracter
exista filtro ativo retorna "" (String vazia).

Descrição

DBFILTER() é utilizada para verificar a expressão de filtro ativo na área de trabalho


corrente.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBFILTER para verificar a
expressão 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBGOBOTTOM ( ) --> uRET

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBGOBOTTOM() é utilizada para posicionar a tabela corrente no último registro


lógico. A seqüência lógica depende da ordem e do filtro ativo sobre a tabela corrente,
portanto o último registro lógico pode não ser o último registro físico.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBGOBOTTOM para posicionar no
último registro físico.
USE Cliente
DBGOBOTTOM() // Posiciona no último registro físico, pois não há ordem ativa

// Este exemplo demonstra como se pode utilizar o DBGOBOTTOM para posicionar no


último registro lógico.
USE Cliente INDEX Ind1 NEW
DBGOBOTTOM() // Posiciona no último registro lógico (último registro na seqüência
gerada pelo índice)
DBGOTOP
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBGOTOP ( ) --> uRET

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBGOTOP() é utilizada para posicionar a tabela corrente no primeiro registro lógico. A


seqüência lógica depende da ordem e do filtro ativo sobre a tabela corrente, portanto o
primeiro registro lógico pode não ser o primeiro registro físico.

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

// Este exemplo demonstra como se pode utilizar o DBGOTOP para posicionar no


primeiro registro lógico.
USE Cliente INDEX Ind1 NEW
DBGOTOP() // Posiciona no primeiro registro lógico (primeiro registro na següência
gerada pelo índice)
DBGOTO
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBGOTO ( ) --> uRET

Retorno

Tipo Descrição
(NULO) Retorno nulo.

Descrição

DBGOTO() é utilizado para posicionar a tabela corrente em determinado registro,


segundo a ordem física (seqüência 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBINFO ( < nINFOTIPO > ) --> xINFO

Parâmetros

Argumento Tipo Descrição


nINFOTIPO Numérico Tipo de informação a ser verificada.

Retorno

Tipo Descrição
Informação da Tabela Informação requisitada pelo usuário (o tipo depende
(Qualquer)
da informação requisitada). Se não houver tabela corrente retorna NIL.

Descrição

DBINFO() é utilizada para obter informações sobre a tabela corrente. O tipo de


informação (primeiro argumento) é escolhido de acordo com as constantes abaixo:
DBI_GETRECSIZE - Tamanho do registro em número de bytes similar a RECSIZE
(tipo numérico)
DBI_TABLEEXT - Extensão 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 início da tabela similar a BOF (tipo lógico)
DBI_EOF - Verifica se está posicionada no final da tabela similar a EOF (tipo lógico)
DBI_FOUND - Verifica se a tabela está posicionada após uma pesquisa similar a
FOUND (tipo lógico)
DBI_FCOUNT - Número de campos na estrutura da tabela corrente similar a FCOUNT
(tipo numérico)
DBI_ALIAS - Nome do Alias da área de trabalho corrente similar a ALIAS (tipo
caracter)
DBI_LASTUPDATE - Verifica a data da última modificação similar a LUPDATE (tipo
data)

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBINFO para obter as informações
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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBORDERINFO ( < nINFOTIPO > ) --> xINFO

Parâmetros

Argumento Tipo Descrição


nINFOTIPO Numérico Nome do arquivo de índice.

Retorno

Tipo Descrição
Retorna a informação da Ordem requisitada pelo usuário (pode ser de tipo
numérico se for número de ordens no índice, tipo caracter se for nome do
Caracter
arquivo de índice). Caso não exista ordem corrente ou a posição da ordem
especificada está inválida retorna NIL.

Descrição

DBORDERINFO() é utilizada para obter informações sobre determinada ordem.


A especificação da ordem pode ser realizada através de seu nome ou sua
posição dentro da lista de ordens, mas se ela não for especificada serão
obtidas informações da ordem corrente.
O tipo de informação (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 diretório) ao qual a ordem
pertence (tipo caracter)
DBOI_ORDERCOUNT - Número de ordens existentes no arquivo de índice
especificado

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBORDERINFO para obter
informações 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBORDERNICKNAME ( < cAPELIDO > ) --> lRET

Parâmetros

Argumento Tipo Descrição


cAPELIDO Caracter Nome do apelido da ordem a ser setada.

Retorno

Tipo Descrição
Retorna Falso se não conseguiu tornar a ordem ativa. Principais erros: Não
Lógico existe tabela ativa ou não foi encontrada a ordem com o apelido.
Retorna Verdadeiro se a ordem foi setada com sucesso.

Descrição

DBORDERNICKNAME() é utilizada para selecionar a ordem ativa através de seu


apelido. Esta ordem é a responsável seqüência lógica 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 não encontrado","Erro", 0)
ENDIF
DBRECALL
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBRECALL ( ) --> uRET

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

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 não estiver deletado, esta função não faz nada. Ela é
o oposto da função 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
deleções da tabela corrente.
USE Cliente
DBGOTOP()
WHILE !EOF()
DBRECALL()
DBSKIP()
ENDDO
DBRECORDINFO
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO

Parâmetros

Argumento Tipo Descrição


nINFOTIPO Numérico Tipo de informação a ser verificada.
nREGISTRO Numérico Número do registro a ser verificado.

Retorno

Tipo Descrição
Não há tabela corrente ou registro inválido.
(Qualquer) Informação do Registro. Informação requisitada
pelo usuário (o tipo depende da informação requisitada).

Descrição

DBRECORDINFO() é utilizada para obter informações sobre o registro especificado


pelo segundo argumento (recno) da tabela corrente, se esta informação for omitida será
verificado o registro corrente. O tipo de informação
(primeiro argumento) é escolhido de acordo com as constantes abaixo:
DBRI_DELETED - Estado de deletado similar a DELETED (tipo lógico)
DBRI_RECSIZE - Tamanho do registro similar a RECSIZE (tipo numérico)
DBRI_UPDATED - Verifica se o registro foi alterado e ainda não foi atualizado
fisicamente similar a UPDATED (tipo lógico)

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBRECORDINFO para se obter as
informações 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBREINDEX ( ) --> uRET

Retorno

Tipo Descrição
(NULO) Nenhum

Descrição

DBREINDEX() reconstrói todos os índices da área de trabalho corrente e posiciona as


tabelas no primeiro registro lógico.

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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBRLOCK ( [ nREGISTRO ] ) --> lRET

Parâmetros

Argumento Tipo Descrição


nREGISTRO Numérico Número do registro a ser bloqueado.

Retorno

Tipo Descrição
Retorna Falso se não conseguiu bloquear o registro. Principal motivo: o
Lógico registro já foi bloqueado por outro usuário.
Retorna Verdadeiro se o registro foi bloqueado com sucesso

Descrição

DBRLOCK() é utilizada quando se tem uma tabela aberta e compartilhada e se deseja


bloquear um registro para que outros usuários não possam alterá-lo.
Se a tabela já está aberta em modo exclusivo, a função não altera seu estado.
O usuário pode escolher o registro a ser bloqueado através do parâmetro
(recno), mas se este for omitido será bloqueado o registro corrente como na função
RLOCK().
Esta função é o oposto à DBRUNLOCK, que libera registros bloqueados.

Exemplo
// Este exemplo mostra duas variações 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 número 110
DBRLOCKLIST
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBRLOCKLIST ( ) --> aRET

Retorno

Tipo Descrição
Retorna NIL se não existe tabela corrente ou não existe nenhum
Array registro locado.
Retorna a lista com os recnos dos registros locados na tabela corrente.

Descrição

DBRLOCKLIST() é utilizada para verificar quais registros estão locados na tabela


corrente. Para tanto, é retornada uma tabela unidimensional com os números dos
registros.

Exemplo:
// Este exemplo mostra como é utilizada a função DBRLOCKLIST para verificar quais
registros estão 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 número 110
DBRLOCK(100) // Bloqueia o registro de número 100
DBRLOCKLIST() // Retorna: {1,100,110}
DBRUNLOCK
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBRUNLOCK ( [ nREGISTRO ] ) --> uRET

Parâmetros

Argumento Tipo Descrição


nREGISTRO Numérico Número do registro a ser desbloqueado.

Retorno

Tipo Descrição
(NULO) Sem retorno.

Descrição

DBRUNLOCK() é utilizada para liberar determinado registro bloqueado. O usuário


pode escolher o registro a ser desbloqueado através do parâmetro
(recno), mas se este for omitido será desbloqueado o registro corrente como na função
DBUNLOCK().
Esta função é o oposto à DBRLOCK, que bloquea os registros.

Exemplo:
// Este exemplo mostra duas variações 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 número 110
DBSEEK
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSEEK ( < xEXP > , [ lSOFTSEEK ] , [ lULTIMO ] ) --> lRET

Parâmetros

Argumento Tipo Descrição


Valor de chave a ser encontrado do tipo caracter (todos os
xEXP (Qualquer) tipos de expressão de índice com exceção do índice com
apenas um campo do tipo numérico).
Posiciona no primeiro registro com expressão de chave
lSOFTSEEK Lógico
maior que o valor procurado. O padrão é .F.
Procura a última ocorrência do valor procurado. O padrão
lULTIMO Lógico
é .F.

Retorno

Tipo Descrição
Retorna Falso se não foi encontrado nenhum registro com o valor
Lógico especificado.
Retorna Verdadeiro se foi encontrado um registro com o valor especificado

Descrição

DBSEEK() é utilizada para encontrar um registro com determinado valor da expressão


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
expressão possuir apenas uma campo numérico, o primeiro parâmetro deve ser do tipo
numérico, mas nos demais casos deve-se utilizar um valor do tipo caracter para este
parâmetro (mesmo se forem apenas dois campos numéricos ou do tipo data).
Quando o segundo parâmetro for especificado como .T. (softseek), mesmo
que a expressão pesquisada não encontrar nenhum registro com este valor,
a tabela será posicionada no próximo valor maior que o especificado no
primeiro parâmetro, mas mesmo posicionando no próximo valor esta função
retornará .F. (pois não encontrou).
Quando não 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 parâmetro for especificado com valor .T. a função posiciona a tabela no
último registro com o valor procurado, caso não seja especificado
ou for .F., será posicionada na primeira ocorrência.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSEEK para busca de valores
numéricos.
USE Clientes NEW
ORDLISTADD ("/teste/ind1.cdx") // Expressão é Num (campo numérico)
DBSEEK(100) // Retorna: .F.
EOF() // Retorna: .T.
DBSEEK(100,.T.) // Retorna: .F.
EOF() // Retorna: .F. (pois o softseek posicionou no próximo 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") // Expressão é Nome+Venc (campo caracter + data)
DBSEEK("joao200101",.T.) // Procura a primeira ocorrência de Nome "joao" e
vencimento maior que Janeiro de 2001
WHILE !EOF() .AND. Nome == "joao"
DBSKIP()
ENDDO
DBSETDRIVER
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSETDRIVER ( [ cNOVORDD ] ) --> cULTIMORDD

Parâmetros

Argumento Tipo Descrição


cNOVORDD Caracter Novo nome do RDD a ser definido como padrão.

Retorno

Tipo Descrição
Caracter Nome do RDD padrão corrente

Descrição

DBSETDRIVER() pode ser utilizada apenas para verificar qual o RDD que está
definido como padrão quando for omitido seu parâmetro.
Ela também pode ser utilizada para especificar outro RDD como padrão,
especificando-o através do parâmetro.

Exemplo:
// Este exemplo demonstra como se pode utilizar o DBSETDRIVER para alterar o valor
do RDD padrão.
DBSETDRIVER("CTREECDX") // Retorna: DBFCDX
DBSETDRIVER() // Retorna: CTREECDX
DBSETFILTER
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSETFILTER ( < @bCONDICAO > , < @cCONDICAO > ) --> uRET

Parâmetros

Argumento Tipo Descrição


bCONDICAO Code-Block Expressão do filtro na forma executável.
cCONDICAO Caracter Expressão do filtro na forma de string.

Retorno

Tipo Descrição
(NULO) Sem retorno.

Descrição

DBSETFILTER é utilizada para setar um filtro nos registros da tabela corrente


especificado através do bloco de código no primeiro parâmetro. Quando um registro não
está dentro do filtro setado ele continua existindo fisicamente, mas não logicamente (nas
funções de manipulação 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSETINDEX ( < @cARQINDICE > ) --> uRET

Parâmetros

Argumento Tipo Descrição


cARQINDICE Caracter Nome do arquivo de índice, com ou sem diretório

Retorno

Tipo Descrição
(NULO) Sem retorno.

Descrição

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 são acrescentadas à lista e a primeira torna-se ativa.
Para se utilizar arquivos de extensão padrão do RDD, este dado pode ser omitido no
primeiro parâmetro, mas caso contrário 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
Revisão: 30/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSETNICKNAME ( < cINDICE > , [ cAPELIDO ] ) --> cAPELIDO

Parâmetros

Argumento Tipo Descrição


cINDICE Caracter Nome da ordem que deve receber o apelido.
cAPELIDO Caracter Nome do apelido da ordem a ser setada.

Retorno

Tipo Descrição
Retorna "" (String vazia) se não conseguiu encontrar a ordem especificada,
Caracter não conseguiu setar o apelido ou não havia apelido.
Retorna o apelido corrente.

Descrição

DBSETNICKNAME é utilizada para colocar um apelido em determinada ordem


especificada pelo primeiro parâmetro. Caso seja omitido o nome do apelido a ser dado,
a função 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
Revisão: 09/04/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DBSETORDER ( < nOrdem > ) --> NIL

Parâmetros

Argumento Tipo Descrição


nOrdem corresponde ao número da posição da ordem na
nOrdem Numérico
lista de ordens ativas.

Retorno

Tipo Descrição
(NULO) Esta função sempre retorna NIL.

Descrição

Esta função é utilizada para selecionar a ordem ativa da área de trabalho. Esta ordem é a
responsável seqüência lógica 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, porém os
indexadores são mantidos abertos. Vale salientar que , quando alteramos a ordem atual
de uma determinada tabela , o registro atual não é desposicionado.
DBSKIP
Revisão: 07/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSKIP ( [ NREGISTROS ] ) --> NIL

Parâmetros

Argumento Tipo Descrição


Número de registros a ser deslocado a partir do corrente.
NREGISTROS Numérico Se for positivo, desloca em direção ao final da tabela. Se
for negativo, ao início da tabela. Valor default: 1.

Retorno

Tipo Descrição
Caracter Sem retorno.

Descrição

Desloca para outro registro na tabela corrente. Esta função é utilizada para deslocar para
outro registro a partir do registro atual. O deslocamento é lógico, ou seja, leva em
consideração ordem no índice e também filtro (se existir).
Caso passe do início 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 convenção "LastRec() + 5000".
DBSTRUCT
Revisão: 08/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBSTRUCT ( ) --> aStruDB

Retorno

Tipo Descrição
Array com a estrutura dos campos. Cada elemento é um subarray contendo
Array
Nome, Tipo, Tamanho e Decimais.

Descrição

Retorna a estrutura da tabela corrente. Esta função é utilizada para verificar a estrutura
da tabela corrente da mesma forma que é utilizada para criar a tabela com a função
DBCREATE. Para isto ela cria um array para gravar as informações e as retorna.

Veja Também
AFields( )
DBUNLOCK
Revisão: 08/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBUNLOCK ( ) --> NIL

Retorno

Tipo Descrição
Caracter Sem retorno.

Descrição

Retira bloqueios de registros e de arquivo da tabela corrente.


DBUNLOCKALL
Revisão: 08/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DBUNLOCKALL ( ) --> NIL

Retorno

Tipo Descrição
Caracter Sem retorno.

Descrição

Retira o bloqueio de todos os registros e arquivos de todas as tabelas abertas. Esta


função é utilizada para liberar todos os registros bloqueados e é equivalente a executar
DBUNLOCK para todas as tabelas da área de trabalho.
DELETED
Revisão: 09/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DELETED ( ) --> lDeleted

Retorno

Tipo Descrição
Se for .T. o registro tem a marca de excluído, se for .F., o registro não tem
Lógico
a marca (ou não há área em uso).

Descrição

Verifica se o registro está com marca de excluído. Quando o registro é excluído,


permanece fisicamente na tabela, mas fica marcado como excluído. Esta função verifica
este estado. Se nenhuma área está selecionada, retorna .F.. Quando é executada a função
DBPACK todos os registros marcados como deletados são apagados fisicamente. A
função 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
Revisão: 12/06/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FIELDBLOCK ( < cCampo > ) --> bBloco

Parâmetros

Argumento Tipo Descrição


cCampo Caracter Nome do campo a ser retornado o bloco de código.

Retorno

Tipo Descrição
Code-Block Bloco de código para o campo especificado na tabela corrente.

Descrição

Retorna um bloco de código para um campo determinado da tabela corrente. Esta


função é utilizada para retornar um bloco de código executável com o campo
especificado. Quando o bloco resultante é executado sem parâmetro, 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 = parâmetro da função FIELDBLOCK()
Valor = valor executado no bloco de código

Exemplo
// Este exemplo mostra como se pode usar o FIELDBLOCK para criar o bloco de
código para o campo 'Nome' da tabela corrente na variável bBloco:

USE Cliente ALIAS Cliente NEW VIA "DBFCDX"


bBloco := FIELDBLOCK("NOME")
HEADER
Revisão: 03/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

HEADER ( ) --> nBytes

Retorno

Tipo Descrição
HEADER() retorna a quantidade de bytes no cabeçalho do arquivo de
Caracter
banco de dados corrente na forma de um valor numérico inteiro.

Descrição

HEADER() é uma funçao de tratamento de banco de dados utilizado com LASTREC(),


RECSIZE(), e DISKSPACE() para criar rotinas de cópia de segurança de arquivos.

O padrao é que a funçao 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 expressão alias.
LUPDATE
Revisão: 19/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

LUPDATE ( ) --> dLastUpdate

Retorno

Tipo Descrição
Retorna um valor do tipo Data , indicando a data da ultima modificação e
Data fechamento da Tabela. Caso não haja tabela selecionada na área de
trabalho atual , a função retornará uma data vazia (ctod ("")) .

Descrição

Verifica a data da última modificação da tabela corrente. Esta função verifica qual a
data da última modificação e fechamento da tabela corrente, caso não exista tabela
corrente é retornada uma data em branco.

Exemplo :

// Mostra a data da última modificação da tabela corrente,


dModificacao := LUpdate()
IF (EMPTY(dModificacao))
CONOUT("Não há tabela corrente")
ELSE
CONOUT(("Data da ultima modificacao : " + DTOS(dModificacao)))
ENDIF
SELECT
Revisão: 24/02/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

SELECT ( [ cAlias ] ) --> nAreaTrabalho

Parâmetros

Argumento Tipo Descrição


cAlias Caracter <cAlias> é o nome da área de trabalho a ser verificada.

Retorno

Tipo Descrição
SELECT() retorna a área de trabalho do alias especificado na forma de um
Numérico
valor numérico inteiro.

Descrição

SELECT() é uma funçao de tratamento de bancos de dados que determina o número da


área de trabalho de um alias. O número retornado pode variar de zero a 250. Se
<cAlias> não for especificado, é retornado o número 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 funçao SELECT(), use o comando SELECT


com a sintaxe SELECT (<idVarMem>), desta forma:
USE Sales NEW
nWorkArea := SELECT()
USE Customer NEW
SELECT (nWorkArea)
TCGENQRY
Revisão: 25/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

TCGENQRY ( [ xPar1 ] , [ xPar2 ] , < cQuery > ) --> ""

Parâmetros

Argumento Tipo Descrição


Parâmetros apenas para compatibilização. Não tem
xPar1 (Qualquer)
função
Parâmetros apenas para compatibilização. Não tem
xPar2 (Qualquer)
função
cQuery Caracter Contém a expressão da query que será aberta.

Retorno

Tipo Descrição
Caracter Sempre retorna uma string vazia.

Descrição

Define a execução de uma Query. Esta função determina que a próxima chamada à
DBUseArea será a abertura
de uma Query e não 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
Revisão: 09/07/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11
Versões Anteriores

Sintaxe

USED ( ) --> lDbfUsed

Retorno

Tipo Descrição
USED() retorna verdadeiro (.T.) caso haja um arquivo de banco de dados
Lógico
em uso; caso contrário, retorna falso (.F.).

Descrição

USED() é uma funçao de tratamento de banco de dados utilizada para determinar se há


um arquivo de banco de dados em uso em uma área de trabalho específica. 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
Revisão: 09/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

__DBPACK ( ) --> URET

Retorno

Tipo Descrição
(NULO) Retorno nulo.

Descrição

Remove todos os registros com marca de excluído da tabela. Esta função apaga
(fisicamente) todos os registros "excluídos" da tabela corrente.

Exemplo
// Este exemplo demonstra como se pode utilizar a função 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 exclusão for confirmada:


__DBPACK()
Funções de disco e arquivos.
ADIR
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ADIR ( [ ] , [ ] , [ ] , [ ] , [ ] , [ ] ) --> nArquivos

Parâmetros

Argumento Tipo Descrição


<cEspecArq> é a especificaçao dos arquivos a serem
incluidos na pesquisa do diretório padrao. É uma
especificaçao de arquivo padrao que pode incluir os
<cEspecArq> Caracter
caracteres coringa do tipo * e ?, bem como referência a
diretório e path. Caso nao seja especificado, o padrao
assumido é *.*.
<aNomesArq> é o vetor a ser preenchido com os nomes de
arquivo que correspondem a <cEspecArq>. Cada elemento
<aNomesArq> Array
contém o nome do arquivo e extensao na forma de uma
cadeia de caracteres em letras maiúsculas.
<aTamanhos> é o vetor a ser preenchido com os tamanhos
<aTamanhos> Array dos arquivos correspondentes no vetor <aNomesArq>.
Cada elemento é numérico.
<aDatas> é o vetor a ser preenchido com as datas dos
<aDatas> Array arquivos correspondentes no vetor <aNomesArq>. Cada
elemento é uma data.
<aHoras> é o vetor a ser preenchido com as horas dos
arquivos correspondentes no vetor <aNomesArq>. Cada
<aHoras> Array
elemento preenchido contém uma cadeia de caracteres da
forma: hh:mm:ss.
<aAtributos> é o vetor a ser preenchido com os atributos
dos arquivos correspondentes no vetor <aFilenames>. Cada
elemento é uma cadeia de caracteres. Caso <aAtributos>
<aAtributos> Array seja especificado, os arquivos de diretório, sistema, e
escondidos sao incluidos, assim como os arquivos normais.
Se <aAtributos> nao for especificado, somente os arquivos
normais sao incluidos.
Retorno

Tipo Descrição
ADIR() retorna a quantidade de arquivos que correspondem ao esqueleto
Numérico
de diretório especificado.

Descrição

ADIR() é uma funçao de tratamento de vetor que executa duas operaçoes básicas.
Primeiro, ele retorna a quantidade de arquivos que correspondem à especificaçao de
arquivo. Segundo, preenche uma série de vetores com nomes de arquivos, tamanhos,
datas, horas e atributos.

ADIR() é uma funçao de compatibilidade e portanto desaconselhada. Ele está superado


pela funçao DIRECTORY(), que retorna todas as informaçoes de arquivo em um vetor
multi-dimensional.

OBSERVAÇÃO

Diretórios: Caso o argumento <aAtributos> seja especificado e <cEspecArq> seja


especificado como *.*, os diretórios serao incluidos em <aNomesArq>. No vetor
<aAtributos>, os diretórios sao indicados com um valor atributo de "D." Se ADIR() for
executado dentro de um subdiretório, as duas primeiras entradas do vetor
<aNomesArq> sao "." e "..", os "alias" dos diretórios corrente e raiz. A data e hora da
última atualizaçao sao informadas para diretórios, mas o tamanho de um diretório é
sempre zero.
CPYS2T
Revisão: 19/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess

Parâmetros

Argumento Tipo Descrição


Nome(s) dos arquivos a serem copiados, aceita apenas
cOrigem Caracter arquivos
no servidor, WildCards ( * e ? ) são aceitos normalmente.
cDestino Caracter Diretório com o destino dos arquivos no Client ( Remote )
Indica se a cópia deve ser feita compactando o arquivo
lCompacta Lógico
antes do envio.

Retorno

Tipo Descrição
lSucess retorna .T. caso o arquivo seja copiado com sucesso , ou .F. em
Lógico
caso de falha na cópia.

Descrição

Copia um arquivo, do servidor para o cliente ( Remote ). .Caso a compactação seja


habilitada (lCompacta ), os dados serão 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
Revisão: 19/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

CPYT2S ( < cOrigem > , < cDestino > , [ lCompacta ] ) --> lSucess

Parâmetros

Argumento Tipo Descrição


Nomes dos arquivos a serem copiados, aceita apenas
cOrigem Caracter arquivos locais ( Cliente ), WildCards ( * e ? ) são aceitos
normalmente.
cDestino Caracter Diretório com o destino dos arquivos no Servidor
lCompacta indica se o(s) arquivo(s) deve(m) ser enviados
lCompacta Lógico
em formato compactado.

Retorno

Tipo Descrição
lSucess indica , caso verdadeiro , que a cópia foi realizada com sucesso.
Lógico
Caso retorne .F. , houve erro na copia do arquivo.

Descrição

Copia um arquivo, do cliente ( Remote ) para o servidor,. Caso a compactação seja


habilitada ( lCompacta ), os dados serão 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
Revisão: 28/04/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

CURDIR ( [ cNovoPath ] ) --> cPathAtual

Parâmetros

Argumento Tipo Descrição


Caminho relativo , com o novo diretório que será ajustado
cNovoPath Caracter
como corrente.

Retorno

Tipo Descrição
Caracter Diretório corrente, sem a primeira barra.

Descrição

Retorna o diretório corrente do servidor. O caminho retornado é sempre relativo ào


RootPath definido na configuração do Environment no .INI do Protheus Server.
Inicialmente , o diretório atual da aplicação é o constante na chave StartPath , também
definido na configuração do Environment no .INI do Protheus Server.

Caso seja passado o parâmetro cNovoPath , este path é assumido como sendo o Path
atual. Caso o path recebido como parÂmetro não exista , seja inválido , ou seja um path
absoluto ( iniciado com uma letra de drive ou caimnho de rede ) , a função não irá setar
o novo path , mantendo o atual .
DIRECTORY
Revisão: 17/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DIRECTORY ( < cDirSpec > , [ ] ) --> aDiretorio

Parâmetros

Argumento Tipo Descrição


<cDirSpec> especifica o drive, diretório e arquivo para a
pesquisa no diretório. Caracteres do tipo coringa sao
permitidos na especificaçao de arquivos. Caso <cDirSpec>
cDirSpec Caracter seja omitido, o valor padrao é *.*.
O caminho especificado pode estar na estação (remote) , ou
no servidor , obedecendo às definicões de Path Absoluto /
Relativo de acesso
<cAtributos> especifica que arquivos com atributos
especiais devem ser incluidos na informaçao retornada.
<cAtributos> Caracter <cAtributos> consiste em uma cadeia de caracteres que
contém um ou mais dos seguintes caracteres, contidos na
tabela adicional A , especificada abaixo:

Retorno

Tipo Descrição
DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor
Array contém informaçoes sobre cada arquivo que atenda a <cDirSpec>.Veja
maiores detalhes na Tabela B, abaixo discriminada.

Descrição

DIRECTORY() é uma funçao de tratamento de ambiente que retorna informaçoes a


respeito dos arquivos no diretório corrente ou especificado. É semelhante a ADIR(),
porém retorna um único vetor ao invés de adicionar valores a uma série de vetores
existentes passados por referência.

DIRECTORY() pode ser utilizada para realizar operaçoes em conjuntos de arquivos.


Em combinaçao com AEVAL(), você pode definir um bloco que pode ser aplicado a
todos os arquivos que atendam a <cDirSpec> especificada.
Para tornar as referências aos vários elementos de cada sub-vetor de arquivo mais
legíveis, é fornecido o arquivo header Directry.ch, que contém os #defines para os
subarray subscripts.

TABELA A: Atributos de DIRECTORY()


Atributo Significado
H Incluir arquivos ocultos
S Incluir arquivos de sistema
D Incluir diretórios
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()


Posiçao Metasímbolo Directry.ch
1 cNome F_NAME
2 cTamanho F_SIZE
3 dData F_DATE
4 cHora F_TIME
5 cAtributos F_ATT
DIRREMOVE
Revisão: 01/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DIRREMOVE ( < cDiretorio > ) --> lSucesso

Parâmetros

Argumento Tipo Descrição


cDiretorio Caracter Nome do diretório a ser removido.

Retorno

Tipo Descrição
lSucesso será .T. caso o diretório tenha sido eliminado , ou .F. caso não
seja possível excluir o diretório. Quando a função DirRemove retornar .F. ,
Lógico
é possível obter mais detalhes da ocorrência recuperando o código do Erro
através da função FError().

Descrição

DIRREMOVE() elimina um diretório 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 começe com \ ) , ou a partir do diretório corrente ( caso o path
não seja iniciado com \ ) . E , quando especificado um path absoluto ( com unidade de
disco preenchida ) , a função será executada na estação onde está sendo executado o
Protheus Remote. Quando executamos a função DirRemove() em JOB ( processo
isolado no Server , sem interface ) , não é possível especificar um Path absoluto de
disco. Caso isto seja realizado , a função retornará .F. e FError() retornará -1 ( Syntax
Error ) .

Note que é necessário ter direitos suficientes para remover um diretório, e o


diretório a ser eliminado precisa estar vazio, sem subdiretórios ou arquivos dentro
do mesmo.
DISKSPACE
Revisão: 01/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DISKSPACE ( [ nDrive ] ) --> nBytesFree

Parâmetros

Argumento Tipo Descrição


Número do drive, onde 0 é o espaço na unidade de disco
nDrive Numérico corrente, e 1 é o drive A: do cliente, 2 é o drive B: do
cliente, etc.

Retorno

Tipo Descrição
Numérico Número de bytes disponíveis no disco informado como parâmetro.

Descrição

DISKSPACE() é uma função de ambiente que determina quantos bytes estão


disponíveis em uma determinada uinidade de disco. Esta função obtém a informação
sempre relativa à estação onde está sendo executado o Protheus Remote. Através do
parâmetro nDRive , selecionamos qual a unidade de disco que desejamos obter a
informação do espaço livre , onde:

0 : Unidade de disco atual da estação (DEFAULT).


1 : Drive A: da estação remota.
2 : Drive B: da estação remota.
3 : Drive C: da estação remota.
4 : Drive D: da estação remota ... e assim por diante.

Caso a função DiskSpace seja executada através de um Job ( processo isolado no


Servidor , sem interface Remota ) , ou seja passado um argumento de unidade de
disco inexistente ou indisponível , a função DISKSPACE() retornará -1
FCLOSE
Revisão: 09/04/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FCLOSE ( < nHandle > ) --> lError

Parâmetros

Argumento Tipo Descrição


<nHandle> é o handle do arquivo obtido previamente
nHandle Numérico
através de FOPEN() ou FCREATE().

Retorno

Tipo Descrição
FCLOSE() retorna falso (.F.) se ocorre um erro enquanto os buffers estao
Lógico
sendo escritos; do contrário, retorna verdadeiro (.T.).

Descrição

FCLOSE() é uma funçao de tratamento de arquivos de baixo nível utilizada para fechar
arquivos binários e forçar que os respectivos buffers do DOS sejam escritos no disco.
Caso a operaçao 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) inválido retorna falso
(.F.) e FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para
obter uma lista completa dos códigos de erro.

Aviso

Esta funçao permite acesso de baixo nível aos arquivos e dispositivos do DOS. Ela deve
ser utilizada com extremo cuidado e exige que se conheça a fundo o sistema operacional
utilizado.

Exemplos

O exemplo a seguir utiliza FCLOSE() para fechar um arquivo binário recém 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
Revisão: 01/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FCREATE ( < cArquivo > , [ nAtributo ] ) --> nHandle

Parâmetros

Argumento Tipo Descrição


Nome do arquivo a ser criado , podendo ser especificado
um path absoluto ou relativo , para criar arquivos no
cArquivo Caracter
ambiente local ( Remote ) ou no Servidor ,
respectivamente .
Atributos do arquivo a ser criado (Vide Tabela de
nAtributo Numérico atributos abaixo). Caso não especificado , o DEFAULT é
FC_NORMAL.

Retorno

Tipo Descrição
A função retornará o Handle do arquivo para ser usado nas demais funções
de manutenção de arquivo. O Handle será maior ou igual a zero. Caso não
Numérico
seja possível criar o arquivo , a função retornará o handle -1 , e será
possível obter maiores detalhes da ocorrencia através da função FERror()

Descrição

FCREATE() é uma função de baixo-nível que permite a manipulação direta dos


arquivos textos como binários. Ao ser executada FCREATE() cria um arquivo ou
elimina o seu conteúdo, e retorna o handle (manipulador) do arquivo, para ser usado nas
demais funções de manutenção de arquivo. Após ser utilizado , o Arquivo deve ser
fechado através da função FCLOSE().

Na tabela abaixo , estão descritos os atributos para criação do arquivo , definidos no


arquivo header fileio.ch

Constante Valor Descrição


FC_NORMAL 0 Criação normal do Arquivo (default/padrão).
FC_READONLY 1 Cria o arquivo protegido para gravação.
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 gravação e escondido , passamos como atributo
FC_READONLY + FC_HIDDEN .

ATENÇÃO : Caso o arquivo já exista , o conteúdo do mesmo será ELIMINADO ,


e seu tamanho será truncado para 0 ( ZERO ) bytes.
FERASE
Revisão: 01/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FERASE ( < cArquivo > ) --> nStatus

Parâmetros

Argumento Tipo Descrição


Nome do arquivo a ser apagado . Pode ser especificado um
cArquivo Caracter path absoluto ou relativo , para apagar arquivos na estação
local ( Remote ) ou no Servidor , respéctivamente .

Retorno

Tipo Descrição
A função retornará 0 caso o arquivop seja apagado com sucesso , e -1 caso
Numérico não seja possível apagar o arquivo. Caso a função retorne -1 , é possível
obter mauires detalhes da ocorrência através da função fError()

Descrição

Através da função Ferase , é possível apagar um arquivo no disco . O Arquivo pode


estar no Servidor ou na estação local (Remote).
O Arquivo para ser apagado deve estar fechado. Não é permitido a utilização de
caracteres coringa (wildcards).
FILE
Revisão: 04/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FILE ( < cArquivo > ) --> lExiste

Parâmetros

Argumento Tipo Descrição


Nome do arquivo , podendo ser especificado um path
(caminho ) . Caminhos locais (Remote) ou caminhos de
cArquivo Caracter
servidor são aceitos , bem como wildcards ( Caracteres *
e?)

Retorno

Tipo Descrição
O retorno será .T. caso o arquivo especificado exista. Caso o mesmo não
Lógico
exista no path especificado , a função retorna .F.

Descrição

Verifica se existe um arquivo ou um padrão de arquivos, no diretório. Pordemos


especificar caminhos absolutos ( arquivos na estação - Remote ) ou relativos ( A partir
do RootPath do Protheus Server) . Os caracteres * e ? ( wildcards). são aceitos.
FOPEN
Revisão: 05/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

FOPEN ( < cArq > , [ nModo ] ) --> nRet

Parâmetros

Argumento Tipo Descrição


Nome do arquivo a ser aberto que inclui o path caso haja
cArq Caracter
um.
Modo de acesso DOS solicitado que indica como o
arquivo aberto deve ser acessado. O acesso é de uma das
categorias relacionadas na tabela A e as restrições de
compartilhamento relacionada na Tabela B. O modo
nModo Numérico
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 Descrição
FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535.
Numérico
Caso ocorra um erro, FOPEN() retorna -1.

Descrição

Abre um arquivo binário.

FOPEN() é uma funçao de tratamento de arquivo de baixo nível que abre um arquivo
binário 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 código 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 códigos 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 funçoes
de tratamento de arquivo. Portanto, é importante sempre atribuir o valor que foi
retornado a uma variável para uso posterior, como mostra o exemplo desta função.

Aviso
Esta funçao permite acesso de baixo nível a arquivos e dispositivos. Ela deve ser
utilizada com extremo cuidado e exige que se conheça a fundo o sistema operacional
utilizado.

Notas

• FOPEN procura o arquivo no diretório corrente e nos diretórios configurados na


variável 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 funções de
tratamento de arquivos podem trabalhar em arquivos localizados no cliente
(estação) ou no servidor. O ADVPL identifica o local onde o arquivo será
manipulado através da existência ou não 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 estação. Caso contrário, será aberto no servidor com o diretório
configurado como rootpath sendo o diretório raíz para localização do arquivo.

Tabela A: Modos de Acesso a Arquivos Binários

Modo Constante (fileio.ch) Operação


0 FO_READ Aberto para leitura (padrão assumido)
1 FO_WRITE Aberto para gravação
2 FO_READWRITE Aberto para leitura e gravação

Tabela B: Modos de Acesso de Compartilhamento a Arquivos Binários

Constante
Modo Operação
(fileio.ch)
0 FO_COMPAT Modo de Compatibilidade (Default)
16 FO_EXCLUSIVE Acesso total exclusivo
Acesso bloqueando a gravação de outros processos ao
32 FO_DENYWRITE
arquivo.
48 FO_DENYREAD Acesso bloqueando a leitura de outros processos ao arquivo.
Acesso compartilhado. Permite a leitura e gravação por
64 FO_DENYNONE
outros processos ao arquivo..
64 FO_SHARED Igual à FO_DENYNONE

FREAD
Revisão: 19/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FREAD ( < nHanvle > , < cBuffer > , < nQtdBytes > ) --> nBytesLidos

Parâmetros

Argumento Tipo Descrição


É o manipulador (Handle) retornado pelas funções
FOPEN(),
nHanvle Numérico
FCREATE(), FOPENPORT(), que faz referência ao
arquivo a ser lido.
É o nome de uma variável do tipo String , a ser utilizada
como buffer de leitura , onde os dados lidos
deverão ser armazenados. O tamanho desta variável deve
ser maior ou igual ao tamanho informado em nQtdBytes.
cBuffer Caracter
Esta variável deve ser sempre passada por referência. ( @
antes do nome da variável ), caso contrário os dados lidos
não serão retornados.
Define a quantidade de Bytes que devem ser lidas do
nQtdBytes Numérico
arquivo a partor posicionamento do ponteiro atual.

Retorno

Tipo Descrição
Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada,
Numérico isto indica erro de leitura ou final de arquivo, Verifique a função
FERROR() para maiores detalhes.

Descrição

FREAD() lê os dados a partir um arquivo aberto, através de FOPEN(), FCREATE()


e/ou FOPENPORT(), e armazena os dados lidos por referência no buffer informado.

FREAD() lerá até o número de bytes informado em nQtdBytes; caso aconteça algum
erro ou o arquivo chegue ao final, FREAD() retornará um número menor que o
especificado em nQtdBytes. FREAD() lê normalmente caracteres de controle (ASC
128, ASC 0, etc.).

A variável String a ser utiilzada como buffer de leitura deve ser sempre pré-alocado e
passado como referência. Caso contrário, os dados não poderão ser retornados.
FREAD() lê a partir da posição atual do ponteiro atual do arquivo , que pode ser
ajustado ou modificado pelas funções FSEEK() , FWRITE() ou FREADSTR().
FREADSTR
Revisão: 02/06/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FREADSTR ( < nHandle > , < nQtdBytes > ) --> cLidos

Parâmetros

Argumento Tipo Descrição


É o manipulador retornado pelas funções FOPEN(),
nHandle Numérico
FCREATE(), FOPENPORT().
nQtdBytes Numérico Número máximo de bytes que devem ser lidos.

Retorno

Tipo Descrição
Retorna uma string contendo os caracteres
Caracter
lidos.

Descrição

Lê caracteres de um arquivo binário.

FREADSTR() lê de um arquivo aberto, através de FOPEN(), FCREATE(),


FOPENPORT().

FREADSTR() lerá até o número de bytes informado em nQtdBytes ou até encontrar um


CHR(0). Caso aconteça 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 posição atual do ponteiro, que pode ser ajustado pelo
FSEEK(), FWRITE( ) ou FREAD().
FRENAME
Revisão: 11/06/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FRENAME ( < cOldFile > , < cNewFile > ) --> nStatus

Parâmetros

Argumento Tipo Descrição


Nome do arquivo será renomeado, aceita caminhos do
servidor e caminhos do cliente. Caso não seja especificado
cOldFile Caracter
nenhuma unidade de disco e path, é considerado o path
atual no servidor.
Novo nome do arquivo, aceita também caminho do
cNewFile Caracter
servidor, e caminho do cliente.

Retorno

Tipo Descrição
Se o status retornado for -1 , ocorreu algum erro na mudança de nome :
Verifique se os dois caminhos estão no mesmo ambiente, verifique a
Numérico existência do arquivo de origem, se ele não está em uso no momento por
outro processo , e verifique se o nome do arquivo de destino já não existe
no path de destino especificado.

Descrição

Através da função FRENAME() é possível renomear um arquivo para outro nome, tanto
no servidor como na estação. Ao renomear um arquivo não esqueça que esta arquivo
deverá
estar fechado ( isto é , não pode estar em uso por nenhum outro processo ou estação).
Caso o arquivo esteja aberto por outro processo , a operação de renomear o arquivo não
é possível. A função fRename() não aceita wildcards ( * e/ou ? ).
Vale lembrar que não é possível renomear um arquivo especificando nos parâmetros
simultaneamente um caminho de servidor e um de estação remota, bem como
especificar dois arquivos remotos e executar a função fername() através de um JOB.
Caso isto ocorra, a função retornará -1 , e fError() retornará também -1.
Importante : Quando especificamos um path diferente nos arquivos de origem e
destino , a função fRename() realiza a funcionalidade de MOVER o arquivo para o
Path especificado.
FSEEK
Revisão: 05/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] ) --> nPos

Parâmetros

Argumento Tipo Descrição


Manipulador obtido através das funções
nHandle Numérico
FCREATE,FOPEN.
nOffSet corresponde ao número de bytes no ponteiro de
posicionamento do arquivo a ser movido. Pode ser um
nOffSet Numérico
numero positivo , zero ou negativo, a ser considerado a
partir do parâmetro passado em nOrigem.
Indica a partir de qual posição do arquivo, o nOffset será
nOrigem Numérico
considerado.

Retorno

Tipo Descrição
FSEEK() retorna a nova posiçao do ponteiro de arquivo com relaçao ao
início do arquivo (posiçao 0) na forma de um valor numérico inteiro. Este
Numérico
valor nao leva em conta a posiçao original do ponteiro de arquivos antes da
execução da função FSEEK().

Descrição

FSEEK() posiciona o ponteiro do arquivo para as próximas operações de leitura ou


gravação. As movimentações de ponteiros são relativas à nOrigem que pode ter os
seguintes valores, definidos em fileio.ch:

Tabela A: Origem a ser considerada para a movimentação do ponteiro de


posicionamento do Arquivo.

Origem Constante Operação


0 FS_SET Ajusta a partir do inicio do arquivo. (Default)
1 FS_RELATIVE Ajuste relativo a posição atual do arquivo.
2 FS_END Ajuste a partir do final do arquivo.
FWRITE
Revisão: 27/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] ) --> nBytesEscritos

Parâmetros

Argumento Tipo Descrição


É o manipulador de arquivo ou device retornado pelas
nHandle Numérico
funções FOPEN(), FCREATE(), ou FOPENPORT().
<cBuffer> é a cadeia de caracteres a ser escrita no arquivo
especificado. O tamanho desta variável deve ser maior ou
cBuffer Caracter
igual ao tamanho informado em nQtdBytes (caso
seja informado o tamanho).
<nQtdBytes> indica a quantidade de bytes a serem
escritos a partir da posiçao corrente do ponteiro de
nQtdBytes Numérico
arquivos. Caso seja omitido, todo o conteúdo de
<cBuffer> é escrito.

Retorno

Tipo Descrição
FWRITE() retorna a quantidade de bytes escritos na forma de um valor
numérico inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a
Numérico operaçao 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 função FERROR() para obter maiores detalhes da ocorrência.

Descrição

Você pode escrever todo ou parte do conteúdo do buffer , limitando a quantidade de


Bytes através do parâmetro nQtdBytes. A escrita começa a partir da posição corrente do
ponteiro de arquivos, e a função FWRITE retornará a quantidade real de bytes escritos.

Através das funções FOPEN(), FCREATE(), ou FOPENPORT(), podemos abrir ou


criar um arquivo ou abrir uma porta de comunicação , para o qual serão gravados ou
enviados os dados do buffer informado. Por tratar-se de uma função de manipulação de
conteúdo binário , são suportados na String cBuffer todos os caracteres da tabela
ASCII , inclusive caracteres de controle ( ASC 0 , ASC 12 , ASC 128 , etc... ).
Caso aconteça alguma falha na gravação , a função retornará um número menor que o
nQtdBytes. Neste caso , a função FERROR() pode ser utilizada para determinar o erro
específico ocorrido. A gravação no arquivo é realizada a partir da posição atual do
ponteiro , que pode ser ajustado através das funções FSEEK() , FREAD() ou
FREADSTR().
GETCLIENTDIR
Revisão: 04/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

GETCLIENTDIR ( ) --> cPath

Retorno

Tipo Descrição
Caracter Retona o path onde está instalado o Protheus Remote.

Descrição

Retorna o diretório completo onde o Remote está instalado, informando inclusive a


unidade de disco.

Observação : Esta função apenas retornará um resultádo válido caso seja


executada em um programa através do Protheus Remote . Caso esta função seja
chamada em JOB , a mesma ocasionará um erro de execução ( Error to
comunicate with Remote ) .
GETREMOTEININAME
Revisão: 12/06/2003

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

GETREMOTEININAME ( ) --> cArqConf

Retorno

Tipo Descrição
Caracter Path e nome do arquivo de configuração

Descrição

Retorna o nome do arquivo de configuração do AP Remote.


GETSRVPROFSTRING
Revisão: 03/09/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

GETSRVPROFSTRING ( < cChave > , < cDefault > ) --> cConteudo

Parâmetros

Argumento Tipo Descrição


cChave Caracter Chave do INI do environment a ser lida,
cDefault é o conteudo da chave a ser retornado caso a
cDefault Caracter
chave não seja encontrada no .ini

Retorno

Tipo Descrição
Caracter Conteudo da chave especificada

Descrição

Através da função GetSrvProfString , podemos obter o conteúdo de uma chave de


configuração do environment atual em uso no arquivo de Inicialização do Server
Protheus ( APxSrv.ini ) .
MAKEDIR
Revisão: 12/06/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

MAKEDIR ( < cNovoDir > ) --> nResultado

Parâmetros

Argumento Tipo Descrição


Nome do diretório a ser criado, incluindo opcionalmente o
cNovoDir Caracter
caminho (path).

Retorno

Tipo Descrição
Retorno zero ( 0 ),o diretório foi criado com sucesso. Caso contrário,
Numérico
houve erro na criação do diretório.

Descrição

Cria um diretório na estação ou no servidor APx.

Caso o diretório comece com um drive ( Ex: C:, X: ) o diretório será criado na estação,
caso contrário será criado no servidor.

MAKEDIR("c:\teste\um") // Cria um diretório na estacao


nResult := MAKEDIR("\teste\um") // Cria o diretorio no servidor
Advanced protheus
IF nResult != 0
Conout( "Impossivel Criar o diretório no servidor Protheus", nResult
)
ENDIF
MAKEDIR( "teste" ) // Exemplo também válido ( Criando o diretório no
servidor ) dentro do diretório corrente
MSCOMPRESS
Revisão: 07/05/2003

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

MSCOMPRESS ( < cArq | aArquivos > , [ cDestino ] , [ cSenha ] ) --> cFileName

Parâmetros

Argumento Tipo Descrição


Arquivo(s) a ser(em) compactado(s). Pode ser do tipo
String , para especificar um único arquivo , ou do tipo
cArq | aArquivos (Qualquer)
Array , contendo um ou mais arquivo(s) a ser(em)
compatado(s).
Nome do Arquivo destino, caso a extensão seja omitida
será assumido .MZP, se não for informado assumirá o
cDestino Caracter
mesmo nome do cArq com extensão .MZP ou o nome do
1º. Arquivo no Array <aArquivos>.
Senha a ser utilizada para criptografar o arquivo
cSenha Caracter
compactado.

Retorno

Tipo Descrição
Caso a compactação seja executada com sucesso , a função retornará uma
sring contendo o nome do arquivo gerado . Caso não seja possível a
Caracter compactação , por falta de espaço em disco ou erro de acesso a algum dos
arquivos a ser(em) compactado(s), a função retornará uma string em
branco ("").

Descrição

Compacta um ou vários arquivos em um único arquivo com extensão .MZP.


MSCOMPRESS() compacta os arquivos informados em um único arquivo com
extensão default .MZP. O formato é proprietário e multiplataforma.
Caso a senha seja informada apenas com a senha poderemos descompactar os arquivos.

Tanto arquivos no local ( Remote ) como no Servidor são aceitos.


MSDECOMP
Revisão: 07/05/2003

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

MSDECOMP ( < cArq > , [ cPathDestino ] , [ cSenha ] ) --> lSucess

Parâmetros

Argumento Tipo Descrição


cArq Caracter Nome do Arquivo no formato MZP a ser descompactado.
Path de destino onde serão gravados o(s) arquivo(s)
cPathDestino Caracter descompactado(s). Note que podem ser incluídos caminhos
do servidor como caminhos locais.
Caso o arquivo tenha sido compactado com senha , esta
cSenha Caracter deve ser especificada ñeste parâmetro para ser poss;ivel a
descompactação do arquivo.

Retorno

Tipo Descrição
Caso a descompactação foi executada com sucesso, a função retornará .T. ,
Em caso de erro durante a descompactação, a função retrornará .F.
Lógico Verifique o espaço disponível 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 , atribuído como "REad-Only".

Descrição

MSDECOMP() descompacta o arquivo informado em um diretório. O Formato é


proprietário, e multi-plataforma, suporta apenas arquivos compactados pela função
MSCOMPRESS().

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

Tanto arquivos no local ( Remote ) como no Servidor são aceitos.


SPLITPATH
Revisão: 05/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

SPLITPATH ( < cArq > , [ @cDrive ] , [ @cCaminho ] , [ @cNome ] , [ @cExt ] ) -->


NIL

Parâmetros

Argumento Tipo Descrição


Nome do Arquivo a ser quebrado. Opcionalmente, pode
cArq Caracter
incluir caminho e drive.
Nome do Drive. Exemplo ( C: ). Caso o Arquivo
cDrive Caracter informado não possua drive ou o caminho refira-se ao
servidor, o retorno será uma string em branco.
Nome do Caminho. Caso o Arquivo informado não possua
cCaminho Caracter
caminho, será uma string em branco.
Nome do Arquivo sem a extensão. Caso em cArq não seja
cNome Caracter especificado um nome do Arquivo, será retornada uma
string em branco.
Extensão do arquivo informado em cArq , prefizada com
cExt Caracter um ponto ".". Caso a extensão em cArq não seja
especificada , o retorno será uma string em branco.

Retorno

Tipo Descrição
Caracter Esta função sempre retorna NIL.

Descrição

A função SplitPath() divide um caminho completo em todas as suas subpartes ( Drive ,


Caminho , Nome e Extensão ) .
Tanto arquivos locais ( Remote ) quanto arquivos no servidor, podem ser informados.
O caminho, caso informado, incluirá uma barra como último caracter. A extensão ,
quando retornada , inclui sempre o ponto ( . ) antes da extensão.
Todos os parâmetros , a partir do segundo , quando passados devem ser por referência.

Observação : Vale lembrar que a função SplitPath não valida a sintaxe do caminho
e/ou arquivo digitados , nem a existência do mesmo . Esta função é utilizada para
determinar em uma string os elementos que compõe um caminho para a
localização de um arquivo.
WRITEPPROSTRING
Revisão: 05/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

WRITEPPROSTRING ( < cSecao > , < cChave > , < cConteudo > , < cArqIni > ) -->
lSucess

Parâmetros

Argumento Tipo Descrição


cSecao corresponde ào nome da seção do íni a ser
cSecao Caracter
utilizada. Caso a seção não exista , a mesma será criada.
Chave da seção do ini a ter seu conteúco alterado . Caso a
cChave Caracter chave não esxista na seção especificada, a mesma será
criada.
cConteudo corresponde ào conteúdo da chave a ser
cConteudo Caracter
atualizado.
cArqIni corresponde ao nome do arquivo de inicialização a
ser alterado. Caso o arquivo não exista , ele será criado .
Caso o path do arquivo não seja informado , o mesmo será
cArqIni Caracter criado/atualizado no diretório 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 estação remota , no path informado.

Retorno

Tipo Descrição
Caso a chave seja incluida e/ou alterada com sucesso , a função
retornatá .T. (true) , e caso ocorra alguma falha ou impossibilidade de
Lógico acesso ao arquivo .ini , a função retornará .F. (false). Dentre as causas mais
comuns de falha , podemos citar erro de sintaxe no nome do arquivo e/ou
path inexistente ou inacessível.

Descrição

Através da funcao WritePProString() , é possível criar e/ou alterar uma seção / chave de
configuração em um arquivo .ini . Caso o arquivo não 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 estação remota ( onde está sendo
executado o Protheus Remote ) . Caso não 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 .
Funções de tratamento de caracteres
ALLTRIM
Revisão: 26/02/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ALLTRIM ( < cString > ) --> cTrimString

Parâmetros

Argumento Tipo Descrição


<cString> é a expressao caractere cujos espaços em branco
cString Caracter
serao eliminados.

Retorno

Tipo Descrição
ALLTRIM() retorna uma cadeia de caracteres cujos espaços em branco à
Caracter
direita e à esquerda foram removidos.

Descrição

ALLTRIM() é uma função de tratamento de dados do tipo caractere que remove os


espaços em branco à direita e à esquerda de uma cadeia de caracteres. É relacionada a
LTRIM() e RTRIM(), que removem espaços em branco à esquerda e à direita de uma
cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM()
sao as funçoes PADC(), PADR(), e PADL(), as quais centralizam, alinham à direita, ou
alinham à esquerda cadeias de caracteres através da inserção de caracteres de
preenchimento.
DESCEND
Revisão: 08/09/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

DESCEND ( < cString > ) --> cDescend

Parâmetros

Argumento Tipo Descrição


<cString> corresponde à sequência de caracteres a ser
cString Caracter
analisada.

Retorno

Tipo Descrição
DESCEND() retorna a string especificada como parâmetro de uma forma
Caracter
complementada. Um DESCEND() de CHR(0) sempre retorna CHR(0).

Descrição

DESCEND() é uma função de conversão que retorna a forma complementada da


expressão string especificada. Esta função normalmente é utilizada para a criação de
indexadores em Ordem Decrescente.
LTRIM
Revisão: 26/02/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

LTRIM ( < cString > ) --> cStringResult

Parâmetros

Argumento Tipo Descrição


<cString> é a cadeia de caracteres a ser copiada sem os
cString Caracter
espaços em branco à esquerda.

Retorno

Tipo Descrição
LTRIM() retorna uma cópia de <cString>, sendo que os espaços em branco
à esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres
Caracter
nula ("") ou toda composta de espaços em branco, LTRIM() retorna uma
cadeia de caracteres nula ("").

Descrição

LTRIM() é uma funçao de tratamento de caracteres utilizada para Formatar cadeias de


caracteres que possuam espaços em branco à esquerda. Pode ser o caso de, por exemplo,
números convertidos para cadeias de caracteres através da funçao STR().

LTRIM() é relacionada a RTRIM(), a qual remove espaços em branco à direita, e a


ALLTRIM(), que remove espaços tanto à esquerda quanto à direita. O contrário de
ALLTRIM(), LTRIM(), e RTRIM() sao as funçoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham à direita, ou alinham à esquerda as cadeias de caracteres,
através da inserçao de caracteres de preenchimento.
PADL / PADR / PADC
Revisão: 26/02/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

PADL / PADR / PADC ( < exp > , < nTamanho > , [ cCaracPreench ] ) -->
cStringPreench

Parâmetros

Argumento Tipo Descrição


<exp> é um valor caractere, data, ou numérico no qual
exp Caracter
serao inseridos caracteres de preenchimento.
<nTamanho> é o tamanho da cadeia de caracteres a ser
nTamanho Numérico
retornada.
<cCaracPreench> é o caractere a ser inserido em <exp>.
cCaracPreench Caracter Caso nao seja especificado, o padrao é o espaço em
branco.

Retorno

Tipo Descrição
PADC(), PADL(), e PADR() retornam o resultado de <exp> na forma de
Caracter uma cadeia de caracteres preenchida com <cCaracPreench>, para totalizar
o tamanho especificado por <nTamanho>.

Descrição

PADC(), PADL(), e PADR() sao funçoes de tratamento de caracteres que inserem


caracteres de preenchimento em valores caractere, data ou numéricos 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 funçoes PAD() truncam cStringPreench ao <nTamanho> especificado.

PADC(), PADL(), e PADR() sao utilizadas para exibir cadeias de caracteres de tamanho
variável em uma área de tamanho fixo. Elas podem ser usadas, por exemplo, para
assegurar o alinhamento com comandos ?? consecutivos. Outra utilizaçao é 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 contrário das funçoes ALLTRIM(), LTRIM(), e
LTRIM(), as quais eliminam espaçoes em branco à esquerda e à direita de cadeias de
caracteres.
RTRIM
Revisão: 26/02/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

RTRIM ( < cString > ) --> cTrimString

Parâmetros

Argumento Tipo Descrição


<cString> é a cadeia de caracteres a ser copiada sem os
cString Caracter
espaços em branco à direita.

Retorno

Tipo Descrição
RTRIM() retorna uma cópia de <cString>, sendo que os espaços em
branco à direita foram removidos. Caso <cString> seja uma cadeia de
Caracter
caracteres nula ("") ou totalmente composta por espaços, RTRIM() retorna
uma cadeia de caracteres nula ("").

Descrição

RTRIM() é uma funçao de tratamento de caracteres utilizada para Formatar cadeias de


caracteres que contenham espaços em branco à direita. Ela é útil quando você deseja
eliminar espaços em branco à direita ao se concatenar cadeias de caracteres. É o caso
típico 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 espaços em branco à direita, e a


ALLTRIM(), que remove espaços em branco à direita e à esquerda. O contrário de
ALLTRIM(), LTRIM(), e RTRIM() sao as funçoes PADC(), PADR(), e PADL(), as
quais centralizam, alinham à direita, ou alinham à esquerda cadeias de caracteres,
inserindo caracteres de preenchimento.
Funcöes de Tratamento de Data / Hora
CDOW
Revisão: 04/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

CDOW ( < dExp > ) --> cNomeDia

Parâmetros

Argumento Tipo Descrição


dExp Data <dExp> é o valor data a ser convertido.

Retorno

Tipo Descrição
CDOW() retorna o nome do dia da semana na forma de uma cadeia de
caracteres. A primeira letra será maiúscula e o resto dos caracteres virá em
Caracter
minúsculas. Para um valor de data nulo ou inválido, CDOW() retorna uma
cadeia de caracteres vazia ("").

Descrição

CDOW() é uma função utilizada para obter, a partir de uma data, a cadeia de caracteres
contendo o dia da semana correspondente.
CMONTH
Revisão: 04/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

CMONTH ( < dData > ) --> cMês

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é a data a converter.

Retorno

Tipo Descrição
CMONTH() retorna o nome do mês a partir de uma data como sendo uma
cadeia de caracteres com a primeira letra maiúscula e o restante da string
Caracter
em letras minúsculas. Para uma data nula, CMONTH() retornará uma
string nula ("").

Descrição

CMONTH() é uma função de conversão de datas que , a partir de uma data , retorna
uma cadeia de caracteres correspondendo ao nome do mês correspondente.
DATE
Revisão: 04/08/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DATE ( ) --> dSistema

Retorno

Tipo Descrição
DATE() retorna a data do sistema como sendo um valor do tipo data.
Data

Descrição

Retorna a data do sistema.


DATE() é a função que retorna a data do atual sistema. O formato de
saída é controlado pelo comando SET DATE. O formato padrão é mm/dd/yy.
DAY
Revisão: 22/09/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DAY ( < dData > ) --> nDia

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é a data a converter.

Retorno

Tipo Descrição
DAY() retorna um número na faixa de 0 até 31, sendo este um valor
numérico inteiro. Caso o mês seja Fevereiro, os anos bissextos sao
Numérico considerados. Se o argumento de data é 29 de Fevereiro e o ano nao é
bissexto, DAY() retornará zero. Se o argumento de data é vazio, DAY()
também retornará zero.

Descrição

Retorna o dia do mês como valor numérico. DAY() é uma funçao de conversao de datas
utilizada para converter um valor do tipo data para o dia do mês correspondente. Esta
função é usada em conjunto com CMONTH() e YEAR() para formatar datas. Além
disso, é geralmente usada em cálculos que envolvam datas.
DOW
Revisão: 13/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DOW ( < dData > ) --> nDia

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é o valor data que será convertido.

Retorno

Tipo Descrição
DOW() retorna o dia da semana na forma de um número entre zero e sete.
Numérico O primeiro dia da semana é um (Domingo) e o último é sete (Sábado). Se
<dData> estiver vazio, DOW() retorna zero.

Descrição

DOW() é uma funçao de conversao de datas que converte um valor data para um
número que identifica o dia da semana. Ela é útil quando você deseja cálculos 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 invés de um número.
DTOC
Revisão: 13/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

DTOC ( < dData > ) --> cData

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é o valor data que será convertido.

Retorno

Tipo Descrição
DTOC() retorna uma cadeia de caracteres que representa uma data. O valor
de retorno é formatado de acordo com o formato de datas corrente. O
Caracter
formato padrao é mm/dd/aa. Uma data nula retorna uma cadeia de
caracteres em branco igual em tamanho ao formato de data corrente.

Descrição

DTOC() é uma funçao de conversao de datas utilizada por motivos de Formataçao


quando você deseja exibir a data no formato SET DATE e é necessária uma expressao
caractere. Caso você precise de um formato de data específico, você pode utilizar
TRANSFORM() ou uma expressao customizada.

Se você estiver INDEXando uma data juntamente com uma cadeia de caracteres, use
DTOS() ao invés de DTOC() para converter o valor data para uma cadeia de caracteres.
ELAPTIME
Revisão: 08/09/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

ELAPTIME ( < cHoraInicial > , < cHoraFinal > ) --> cIntervalo

Parâmetros

Argumento Tipo Descrição


Informe a hora inicial no formato hh:mm:ss, onde hh é a
cHoraInicial Caracter
hora ( 1 a 24 ), mm os minutos e ss os segundos
Informe a hora final no formato hh:mm:ss, onde hh é a
cHoraFinal Caracter
hora ( 1 a 24 ), mm os minutos e ss os segundos.

Retorno

Tipo Descrição
A diferença de tempo no formato hh:mm:ss, onde hh é a hora ( 1 a 24 ),
Caracter
mm os minutos e ss os segundos

Descrição

ElapTime() retorna uma cadeia de caracteres contendo a diferença de


tempo entre cHoraFinal - cHoraInicial , no formato hh:mm:ss.

Os dois parâmetros , cHoraInicial e cHoraFinal , devem ser especificados no formato


hh:mm:ss , com tamanho de 8 bytes . Caso um dos parâmetros tenha tamanho diferente
de 8 Bytes, é gerada uma ocorrência de Erro Fatal "invalid len". Qualquer caracter
invalido nas posicões referentes à hora (hh) , minuto (mm) e segundo (ss) , serão
ignorados na composição de numeros para o cálculo. Caso o horário inicial seja maior
que o horário final , é retornada a diferença entre os horários acrescidos de 24h. Para
maiores detalhes , consulte o exemplo da função ElapTime()
MONTH
Revisão: 22/09/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

MONTH ( < dData > ) --> nMês

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é o valor data a ser convertido.

Retorno

Tipo Descrição
MONTH() retorna um valor numérico inteiro na faixa de 0 (zero) a 12.
Numérico
Uma data nula (CTOD("")) retorna zero.

Descrição

MONTH() é uma funçao de conversao de datas que é útil quando você precisa de um
valor de mês numérico durante cálculos para, por exemplo, relatórios periódicos.
MONTH() faz parte de um grupo de funçoes que retornam componentes de um valor
data na forma de valores numéricos. O grupo inclui DAY() e YEAR(), que retornam os
valores de dia e ano na Forma de númericos. CMONTH() é uma funçao relacionada,
que permite a você retornar o nome do mês a partir de um valor data.
SECONDS
Revisão: 09/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

SECONDS ( ) --> nSegundos

Retorno

Tipo Descrição
SECONDS() retorna a hora do sistema como um valor numérico na forma
segundos.centésimos. O valor numérico retornado é a quantidade de
Numérico
segundos decorridos desde a meia-noite, e tem base em um relógio de
vinte e quatro horas em uma faixa de zero a 86399.

Descrição

SECONDS() é uma funçao de horas utilizada para fornecer um método simples de


calcular o tempo decorrido, com base no relógio do sistema, durante a execuçao do
programa. É relacionado à funçao TIME(), a qual retorna a hora do sistema como uma
cadeia de caracteres na forma hh:mm:ss.
TIME
Revisão: 13/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

TIME ( ) --> cStringHora

Retorno

Tipo Descrição
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,
Caracter
e ss indica os segundos. Horas, minutos e segundos sao separadas por dois
pontos.

Descrição

TIME() é uma funçao de tratamento de tempo, utilizada para exibir ou imprimir a hora
do sistema em um relatório 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 cálculos sobre o tempo.
YEAR
Revisão: 13/10/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

YEAR ( < dData > ) --> nAno

Parâmetros

Argumento Tipo Descrição


dData Data <dData> é o valor data a ser convertido.

Retorno

Tipo Descrição
YEAR() retorna o ano do valor data especificado, inclusive dígitos
indicativos de século, na forma de um valor numérico de quatro dígitos. O
Numérico
valor retornado nao é influenciado pelo formato de DATE ou CENTURY
corrente. A especificaçao de uma data nula (CTOD("")) retorna zero.

Descrição

YEAR() é uma funçao de conversao de datas utilizada para converter um valor data para
um valor numérico indicativo do ano. Pode ser utilizada em cálculos de, por exemplo,
relatórios periódicos, ou para Formataçao de exibiçoes de data.

YEAR() é membro de um grupo de funçoes que retornam componentes de um valor


data na forma de valores numéricos. Este grupo inclui DAY() e MONTH(), que
retornam valores de dia e mês na forma de valores numéricos.
Funcöes de Tratamento de Matrizes (Arrays)
AADD
Revisão: 26/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

AADD ( < aDestino > , [ expValor ] ) --> Valor

Parâmetros

Argumento Tipo Descrição


aDestino Array É o array ao qual o novo elemento será adicionado.
É uma expressão válida que será o valor do
expValor (Qualquer)
novo elemento.

Retorno

Tipo Descrição
Avalia expValor e retorna seu Valor. Se expValor não for especificado,
(Qualquer)
AADD() retorna NIL.

Descrição

AADD() é uma função de tratamento de vetor que adiciona um elemento ao vetor. Ao


elemento de vetor recém criado é atribuido o valor especificado por <expValor>.

AADD() é utilizado para aumentar o tamanho de um vetor dinamicamente. É útil na


construção de filas ou listas dinâmicas.

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

OBSERVAÇÃO : Caso <expValor> seja um outro vetor, o novo elemento no vetor


destino conterá uma referência ao vetor especificado por <expValor>.
ACLONE
Revisão: 13/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ACLONE ( < aFonte > ) --> aDuplica

Parâmetros

Argumento Tipo Descrição


aFonte Array <aFonte> é o vetor a ser duplicado.

Retorno

Tipo Descrição
Array Array idêntico ao aFonte , porem sem nenhuma referência ao mesmo.

Descrição

ACLONE() é uma funçao 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 cópias dos valores contidos nos sub-vetores de
<aFonte>.

Ao igualarmos dois arrays, eles ficam associados por referência, utilizando


aClone() não existe referência. ACLONE() é semelhante a ACOPY(), porém ACOPY()
nao duplica vetores aninhados.
ACOPY
Revisão: 13/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

ACOPY ( < aFonte > , < aDestino > , [ nInicio ] , [ nCont ] , [ nPosDestino ] ) -->
aDestino

Parâmetros

Argumento Tipo Descrição


aFonte Array <aFonte> é o vetor de onde serao copiados os elementos.
<aDestino> é o vetor para onde serao copiados os
aDestino Array
elementos.
<nInicio> é a posiçao do elemento inicial no vetor
nInicio Numérico <aFonte>. Se nao for especificado, o valor assumido é um
(01).
<nCont> é a quantidade de elementos a serem copiados do
vetor <aFonte> a partir da posiçao <nInicio>. Caso
nCont Numérico <nCont> nao seja especificado, todos os elementos em
<aFonte> que começam com o elemento inicial sao
copiados.
<nPosDestino> é a posiçao do elemento inicial no vetor
nPosDestino Numérico <aDestino> que receberá os elementos de <aFonte>. Se
nao for especificado, o valor padrao é um (01).

Retorno

Tipo Descrição
Array ACOPY() retorna uma referência ao vetor destino, <aDestino>.

Descrição

ACOPY() é uma funçao 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 código.
Se um elemento do vetor <aFonte> for um sub-vetor, o elemento correspondente no
vetor <aDestino> conterá uma referência ao sub-vetor. Consequentemente, ACOPY()
nao cria duplicatas completas de vetores multi-dimensionais. Para fazer isto, use a
funçao ACLONE().
ADEL
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ADEL ( < aFonte > , < nPosicao > ) --> aFonte

Parâmetros

Argumento Tipo Descrição


<aFonte> é o vetor que contém um elemento a ser
aFonte Array
eliminado.
<nPosiçao> é a posiçao do elemento de vetor , a partir do
nPosicao Numérico
primeiro , que será eliminado.

Retorno

Tipo Descrição
ADEL() retorna uma referência ao vetor destino, <aFonte>.
Array

Descrição

ADEL() é uma funçao de tratamento de vetor que elimina um elemento de um vetor. O


conteúdo do elemento de vetor especificado é perdido, e todos os elementos a partir
daquela posiçao até o final do elemento sobem uma posiçao. O último elemento no
vetor torna-se NIL.

AVISO : Em Advpl, vetores multi-dimensionais sao implementados através 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 <nPosiçao>,
forçando <aFonte> a nao mais ter dimensoes regulares.
AEVAL
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

AEVAL ( < aVetor > , < bBloco > , [ nInicio ] , [ nCont ] ) --> aVetor

Parâmetros

Argumento Tipo Descrição


aVetor Array <aVetor> é o vetor a ser varrido.
<bBloco> é um bloco de código a ser executado para
bBloco Code-Block
cada elemento encontrado.
<nInicio> é o elemento inicial. Caso nao seja
nInicio Numérico
especificado, o padrao assumido é o elemento um.
<nCont> é a quantidade de elementos a serem
nCont Numérico processados a partir de <nInício>. Se nao for
especificado, o padrao é todos os elementos no vetor.

Retorno

Tipo Descrição
Array AEVAL() retorna uma referência a <aVetor>.

Descrição

AEVAL() é uma funçao de tratamento de vetor que avalia um bloco de código uma vez
para cada elemento de um vetor, passando o valor do elemento como um parâmetro 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 suposiçoes sobre o conteúdo 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 construçao de comandos de interaçao tanto para estruturas de
vetor complexas como simples.
Consulte a seçao Blocos de Código no na seção A Linguagem Advpl para maiores
informações sobre Code-Blocks.
AFILL
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

AFILL ( < aDestino > , < ValorExp > , [ nInicio ] , [ nCont ] ) --> aDestino

Parâmetros

Argumento Tipo Descrição


aDestino Array <aDestino> é o vetor a ser preenchido.
<ValorExp> é o valor a ser alocado em cada elemento de
ValorExp (Qualquer) vetor. Pode ser uma expressao de qualquer tipo de dados
válido.
<nInicio> é a posiçao do primeiro elemento a ser
nInicio Numérico preenchido. Caso este argumento seja omitido, o valor
padrao é um.
<nCont> é a quantidade de elementos a serem
preenchidos iniciando com o elemento <nInicio>. Se este
nCont Numérico
argumento for omitido, os elementos sao preenchidos a
partir da posiçao do elemento inicial até o final do vetor.

Retorno

Tipo Descrição
Array AFILL() retorna uma referência ao <aDestino>.

Descrição

AFILL() é uma funçao de vetor que preenche um vetor especificado com um único
valor de qualquer tipo de dados (inclusive vetores, blocos de código ou NIL) atribuindo
<ValorExp> a cada elemento de vetor na faixa especificada.

ATENÇÃO : 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 utilizaçao de AFILL() com vetores multi-dimensionais
sobre-escreverá vetores para as outras dimensoes do vetor.
AINS
Revisão: 16/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

AINS ( < aDestino > , < @nPos > ) --> aDestino

Parâmetros

Argumento Tipo Descrição


aDestino Array É o array de onde será inserido um item NIL.
É a posição, a partir da 1, na qual será inserido um
nPos Numérico
elemento NIL

Retorno

Tipo Descrição
Retorna uma referência ao vetor aDestino
Array

Descrição

AINS() é uma função de vetor que insere um novo elemento em um vetor especificado.
O elemento recém inserido é NIL até que um novo valor seja atribuido a ele. Após a
inserção, o último elemento no vetor é descartado, e todos os elementos depois do novo
elemento descem uma posição.

¤ AVISO : AINS() deve ser utilizado com cuidado quando se tratar de vetores multi-
dimensionais. Vetores multi-dimensionais em Advpl sao implementados através 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
Revisão: 26/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versões Anteriores

Sintaxe

ARRAY ( < nElementos,... > ) --> aVetor

Parâmetros

Argumento Tipo Descrição


<nElementos> é a quantidade de elementos na dimensao
nElementos,... Numérico especificada.Os vetores em Advpl podem ter um número
ilimitado de dimensoes.

Retorno

Tipo Descrição
Array ARRAY() retorna um vetor de dimensoes especificadas.

Descrição

ARRAY() é uma funçao 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á várias 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 variável existente; ou você pode
usar a funçao ARRAY(). ARRAY() tem a vantagem de possibilitar a você a criaçao de
vetores dentro de expressoes ou blocos de código.
ASCAN
Revisão: 26/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

ASCAN ( < aDestino > , < ProcuraExp > , [ nInicio ] , [ nCont ] ) --> nParouEm

Parâmetros

Argumento Tipo Descrição


aDestino Array <aDestino> é o vetor a ser varrido.
<ProcuraExp> pode ser um valor simples a ser procurado,
ou um bloco de código. Caso <ProcuraExp> seja um valor
ProcuraExp (Qualquer)
simples, este poderá ser do tipo numérico, lógico, data, ou
caractere.
<nInicio> é o elemento a partir do qual terá início a
nInicio Numérico pesquisa. Se este argumento nao for especificado, a
posiçao inicial padrao é um.
<nCont> é a quantidade de elementos que serao varridos a
partir da posiçao inicial. Caso este argumento nao seja
nCont Numérico
especificado, todos os elementos, desde o elemento inicial
até o final do vetor, serao varridos.

Retorno

Tipo Descrição
ASCAN() retorna um valor numérico que representa a posiçao ocupada no
vetor pelo último elemento varrido. Se <ProcuraExp> for um valor
simples, ASCAN() retorna a posiçao do primeiro elemento que
Numérico
corresponder ao valor procurado, ou zero caso nao haja correspondência.
Se <ProcuraExp> for um bloco de código, ASCAN() retorna a posiçao do
elemento onde o bloco retornou verdadeiro (.T.).

Descrição

ASCAN() é uma funçao 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 começa
com o caractere mais à esquerda no elemento destino e prossegue até que nao haja mais
nenhum caractere em <ProcuraExp>. Caso nao haja correspondência, ASCAN() vai
para o próximo elemento no vetor.
Como ASCAN() utiliza o operador (=) para comparaçoes, ele é sensível ao status de
EXACT. Caso EXACT esteja ON, o elemento de vetor destino deve ser exatamente
igual ao resultado de <ProcuraExp> para que haja correspondência.

Se o argumento de <ProcuraExp> seja um bloco de código, 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 código, e depois executa um EVAL() no bloco. A operaçao de pesquisa pára
quando o bloco de código retorna verdadeiro (.T.), ou quando ASCAN() atinge o último
elemento no vetor.
ASIZE
Revisão: 13/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

ASIZE ( < aDestino > , < @nTamanho > ) --> ASIZE()

Parâmetros

Argumento Tipo Descrição


aDestino Array <aDestino> é o vetor a ser aumentado ou diminuido.
nTamanho Numérico <nTamanho> é o novo tamanho do vetor.

Retorno

Tipo Descrição
Array Retorna uma referência ao array aDestino.

Descrição

ASIZE() é uma função 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
Revisão: 26/07/2002

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

ASORT ( < aDestino > , [ nInicio ] , [ nCont ] , [ bOrdem ] ) --> aDestino

Parâmetros

Argumento Tipo Descrição


<aDestino> é o vetor cujos elementos serao colocados em
aDestino Array
ordem.
<nInicio> é o primeiro dos elementos que serao
nInicio Numérico colocados em ordem. Caso nao seja especificada, a
posiçao inicial assumida é um.
<nCont> é a quantidade de elementos que serao
colocados em ordem. Se nao for especificada, todos os
nCont Numérico
elementos no vetor que começam com o elemento inicial
sao ordenados.
<bOrdem> é um bloco de código opcional utilizado para
determinar qual a ordem que será seguida. Caso nao seja
especificada, a ordem padrao é ascendente. *** Atenção :
bOrdem Code-Block
Caso utilizada a função aSort para um array aninhado
(milti-dimensional), o parâmetro bOrdem deve ser
passado ; caso contrário o array não será ordenado.

Retorno

Tipo Descrição
Array ASORT() retorna uma referência ao vetor <aDestino>.

Descrição

ASORT() é uma funçao de vetor que coloca em ordem todo ou parte de um vetor que
contém elementos de um único tipo de dados. Os tipos de dados que podem ser
ordenados incluem caractere, data, lógico e numérico.

Se o argumento <bOrdem> nao for especificado, a ordem padrao é ascendente.


Elementos com valores baixos sao colocados no início 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 parâmetros de bloco. O bloco deve
retornar verdadeiro (.T.) se os elementos estiverem ordenados. Isto pode ser usado para
criar uma ordem descendente ou de dicionário. Veja os exemplos abaixo.

Quando ordenadas, as cadeias de caracteres sao colocadas na sequência ASCII; valores


lógicos sao ordenados com falso (.F.) sendo considerado o valor menor; valores data sao
ordenados cronologicamente; e numéricos sao ordenados por magnitude.

OBSERVAçÃO : Sendo os vetores multi-dimensionais em Clipper implementados


através 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 código que dará o tratamento adequado aos sub-vetores.
Funções de Impressão
GETIMPWINDOWS
Revisão: 05/05/2003

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10

Sintaxe

GETIMPWINDOWS ( < lServer > ) --> aPrinters

Parâmetros

Argumento Tipo Descrição


Informar .T. se a lista de impressoras deve ser obtida do
lServer Lógico Protheus Server ou .F. para obter lista de imporessoras da
estação Remota. Este parâmetro é obrigatório.

Retorno

Tipo Descrição
Array com nome das impressoras disponíveis. Vale lembrar que esta
Array
função não verifica o status atual da(s) impressora(s) encontrada(s).

Descrição

GETIMPWINDOWS( ) retorna uma lista de impressoras disponíveis 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 configuração do Protheus Server.

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

Observação : Caso a função seja passada com o argumento .F. ( buscar


impressoras da estação Remote ) , porém a função 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
Revisão: 23/12/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Sintaxe

GETPORTACTIVE ( < lServer > ) --> aPortImp

Parâmetros

Argumento Tipo Descrição


CAso especificado .T. , a lista de impressoras será obtida do
lServer Lógico
Server, caso .F. a lista será obtida da estação (Remote).

Retorno

Tipo Descrição
Array Array com as portas de impressão disponíveis.

Descrição

Retorna lista de portas de impressão disponíveis. A função GETPORTACTIVE( )


retorna uma lista de portas de impressão disponíveis do Protheus Server ou Remote. Se
o Protheus Server está em ambiente Unix, a GETPORTACTIVE() retornará uma lista
com os nomes de devices possíveis para impressão.
Caso não sejam encontradas portas para impressão , é retornado um array com apenas
um elemento , contendo a string "Nao existem portas disponiveis".
Observação : Caso a função seja chamada com o parâmetro .F. , para obter as
portas de impressão da estação remota , porém a função seja chamada através 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 impressão disponíveis no SERVER, os devices especificados


na configuração de bloqueio de portas de impressão ( DisableDevicePort ) no server
não são listados por esta função.

Quando executada em ambiente Linux, os devices de impressão disponíveis no


SERVER, a função 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 máximo
4 portas paralelas e 4 portas seriais.
Funções de Interface HTTP
GETWEBJOB
Revisão: 16/10/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

GETWEBJOB ( ) --> cJobName

Retorno

Tipo Descrição
cJobName corresponde ào nome do job que configura a working Thread
atual em uso. Caso a chamada da função seja realizada a partir de uma
Caracter thread que não seja uma Working Thread ( como por exemplo , uma thread
iniciada a partir de um ApxRemote ) , a função GetWebJob() retornará
uma string vazia ("").

Descrição

Através desta função , é possível recuperar o nome da configuração de Working


Threads ( Job ) que está sendo utilizada pela Working Thread atual.

Observação : Esta função está disponível a partir dos Build's Ap6 gerados a partir
de 05/09/2002.
HTTPCACHE
Revisão: 16/09/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPCACHE ( < cCacheControl > ) --> cLastCache

Parâmetros

Argumento Tipo Descrição


Define o novo conteúdo da etiqueta do Header de Retorno
cCacheControl Caracter
HTTP Cache-Control.

Retorno

Tipo Descrição
Esta função retorna a definição atualmente utilizada para a etiqueta Cache-
Caracter
Control do Header HTTP.

Descrição

Através desta função , podemos redefinir a etiqueta CACHE-CONTROL do Header de


Resposta de requisição HTTP , sobrepondo à definição defaut de retorno CACHE-
CONTROL , opcionalmente definida na configuração do HOST HTTP no Arquivo de
configuração do Protheus Server.

Tabela A - Definições CACHE-CONTROL


Conteúdo Aplicação
Nenhuma informação deve ser guardada em Cache pelo servidor e/ou
no-store
proxie(s).

Observação : A definição de um novo conteúdo para o CACHE-CONTROL do


Header HTTP apenas será possível caso esta função Advpl seja executada antes de
qualquer envio parcial de html ao browser , realizado pela função HttpSend().
HTTPCOUNTSESSION
Revisão: 25/08/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPCOUNTSESSION ( ) --> nCount

Retorno

Tipo Descrição
nCount corresponde ao número de usuários que possuem variáveis de
Numérico
session em uso no Server PRotheus.

Descrição

Esta função retorna o número de Sessions de usuários que estão atualmente em uso na
memória.

** ATENÇÃO : Devemos atentar ao fato que esta função apenas terá o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAÇÃO : Esta função foi implementada na Ferramenta Ap6 Server , sendo


necessário adquirir um Build de Protheus Server com data igual ou superior a
22/04/2002.
HTTPFREESESSION
Revisão: 25/08/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPFREESESSION ( ) --> NIL

Retorno

Tipo Descrição
(NULO) Esta função sempre retorna NIL

Descrição

Através da função HttpFreeSession , eliminamos da memória do Servidor Protheus


todas as variáveis de Session do usuário atual. Normalmente utilizamos esta função em
operações de LOGOFF , onde necessitamos limpar todas os conteudos relacionados à
Session deste usuário.

** ATENÇÃO : Devemos atentar ao fato que esta função apenas terá o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAÇÃO : Esta função foi implementada na Ferramenta Ap6 Server , sendo


necessário adquirir um Build do Servidor Protheus Server com data igual ou superior a
22/04/2002.
HTTPGET
Revisão: 16/08/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPGET ( < cUrl > , [ cGETParms ] , [ nTimeOut ] ) --> cHttp

Parâmetros

Argumento Tipo Descrição


cUrl corresponde ao endereço http , juntamente com a
cUrl Caracter
pasta e o documento solicitados.
cGETParms corresponde à StringList de parâmetros a
cGETParms Caracter serem enviados ao servidor http através da URl . Caso não
especificado , este parâmetro é considerado vazio ("")
Em nTimeOut especificamos o tempo em segundos
máximo de inatividade permitido durante a recepção do
nTimeOut Numérico
documento . Caso não especificado , o valor default
assumido é 120 segundos ( 2 minutos).

Retorno

Tipo Descrição
Caracter String Html correspondendo ao documento solicitado.

Descrição

A função HttpGet() permite a emulação de um Client HTTP através de uma função


Advpl, acessando um determinado documento html publicado em um servidor Web,
utiliando o método GET , permitindo a passagem de parâmetros via URL, aguardando
por um tempo determinado (time-out) pela resposta do servidor solicitado.

Observações :

--- Na passagem de parâmtros GET , devemos atentar ao formato da string a ser passada
como parâmetros , pois a mesma segue o formato URI (Uniform Resource Identifiers) :
Query Component.
--- Caso nao seja retornado o documento antes do término do Time-out especificado na
chamada da função; ou caso não seja possível localizar o servidor ; seja por falha de
resolução de DNS , ou por erro de sintaxe ao especificar a URL , a função retornará
Nulo (NIL).
--- Caso nao seja possível o acesso ao documento , como por exemplo o documento não
exista , será retornado uma string html com a mensagem de erro html enviada pelo
servidor correspondente.
OBSERVACAO : Esta funcão está disponivel apenas em Builds Ap6 gerados a partir de
10/07/2002
HTTPLEAVESESSION
Revisão: 25/08/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPLEAVESESSION ( ) --> NIL

Retorno

Tipo Descrição
(NULO) A função HttpLeaveSession() sempre retorna NIL

Descrição

Esta função , uma vez executada , libera o processamento de requisição de atualizãção


de conteúdos de variáveis tipo HttpSession para requisições de consulta e/ou
atualizações simultâneas para o usuário atual.

** ATENÇÃO : Devemos atentar ao fato que esta função apenas terá o efeito
desejado caso o ambiente atual em uso pelo Projeto WEB seja WEBEX ( Web
Extended ) **

OBSERVAÇÃO : Esta função foi implementada na Ferramenta Ap6 Server , sendo


necessário adquirir um build de Server PRotheus com data igual ou superior a
22/04/2002.
HTTPLOGONUSER
Revisão: 24/09/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPLOGONUSER ( ) --> cLogonUser

Retorno

Tipo Descrição
String contendo o login do usuário, no formato DOMINIO\login. Caso a
função não seja executada em uma thread iniciada em uma interface http ,
Caracter
ou o acesso anônimo ào site no IIS esteja habilitado , a função retornará
uma string em branco ("").

Descrição

Através da Função HttpLogonUser() , quando utilizamos o AP Server ISAPI


( AdvplIsapi.dll) , em conjunto com o Microsoft IIS (Internet Information Services ) ,
obtemos o login do usuário atual.

Observação : Para que o usuário seja obrigado a informar um login individual ,


deve ser desabilitado no IIS a configuração que permite acesso anônimo ao site.
Caso esta configuração não seja alterada , todos os usuários serão identificados
como "anônimos" pelo IIS, e a função retornará uma String em branco.
HTTPOTHERCONTENT
Revisão: 10/09/2002

Abrangência

Versão 7.10

Sintaxe

HTTPOTHERCONTENT ( ) --> cContent

Retorno

Tipo Descrição
cContent é a string correspondendo ao conteúdo do corpo do pacote
Caracter
HTML postado no Server.

Descrição

A função HttpOtherContent() , quando utilizada em uma thread montada e/ou


inicializada para atender à uma requisição Http ( .apl , .apw ) , retorna o conteúdo do
pacote html proveniente de uma operação de POSTagem de dados, se e somente se a
operacão de POSTagem especificou no HEader HTTP um content-disposition ou
content-type não tratados automaticamente pelo Server PRotheus.

Caso a requisição não tenha sido realizada por um client HTTP através do método de
postagem , ou a postagem já possua tratamento nativo no Server Protheus , ou a função
seja chamada em um ambiente que não esteja atendendo à uma requisição Http ( como
um JOB , por exemplo) , a função retornará uma string em branco ("").
HTTPPOST
Revisão: 07/08/2003

Abrangência

Versão 6.09 Versão 7.10 Versão 8.11

Sintaxe

HTTPPOST ( < cUrl > , [ cGETParms ] , [ cPOSTParms ] , [ nTimeOut ] ,


[ aHeadStr ] ) --> cHtml

Parâmetros

Argumento Tipo Descrição


cUrl corresponde ao endereço http , juntamente com a
cUrl Caracter
pasta e o documento solicitados.
cGETParms corresponde à StringList de parâmetros a
cGETParms Caracter serem enviados ao servidor http através da URl . Caso não
especificado , este parâmetro é considerado vazio ("")
cPostParms corresponde à StringList de parâmetros a
serem enviados ao servidor http através do pacote HTTP .
cPOSTParms Caracter
Caso não especificado , este parâmetro é considerado
vazio ("")
Em nTimeOut especificamos o tempo em segundos
máximo de inatividade permitido durante a recepção do
nTimeOut Numérico
documento . Caso não especificado , o valor default
assumido é 120 segundos ( 2 minutos).
Através deste parametro , podemos especificar um array
aHeadStr Array com strings a serem acrescentadas ao Header da requisição
HTTP a ser realizada.

Retorno

Tipo Descrição
Através de cHtml será retornada a String Html correspondendo ao
Caracter
documento solicitado.

Descrição

A função HttpPost() permite a emulação de um Client HTTP através de uma função


Advpl, postando um bloco de informações para um determinado documento publicado
em um servidor Web, utiliando o método POST , permitindo a passagem de parâmetros
adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta
do servidor solicitado.
Observações :

• Na passagem de parâmtros GET e POST , devemos atentar ao formato da string


a ser passada como parâmetros , pois a mesma segue o formato URI (Uniform
Resource Identifiers) : Query Component.
• Caso nao seja retornado o documento antes do término do Time-out especificado
na chamada da função; ou caso não seja possível localizar o servidor ; seja por
falha de resolução de DNS , ou por erro de sintaxe ao especificar a URL , a
função retornará Nulo (NIL).
• Caso nao seja possível o acesso ao documento , como por exemplo o documento
não exista ,será retornado uma string html com a mensagem de erro html
enviada pelo servidor correspondente.
• Quando utilizamos a função HttpPost() , podemos especificar um Content-Type
diferenciado para o conteúdo postado. Caso não seja especificado um Content-
Type , alguns servidores tratam a informação postada como sendo um dado do
tipo 'application/x-www-form-url' , seria o equivalente a um formulário HTML
postado via Browser, outros servidores poderão não reconhecer tal informação
postada dessa forma. Para especificar que o conteúdo postado deve ser tratado
como um POST de formulário HTTP , devemos passar no parâmetro aHeadStr ,
um elemento contendo 'Content-Type: application/x-www-form-url'.

ATENÇÃO

1. Esta funcão está disponivel apenas em Builds Ap6 gerados a partir de


10/07/2002 .
2. O parametro aHeadStr apenas está disponível em Build's Ap6 e posteriores
gerados apos 01/10/2002.
HTTPPRAGMA
Revisão: 16/09/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPPRAGMA ( < cPragma > ) --> cOldPragma

Parâmetros

Argumento Tipo Descrição


cPragma corresponde ao conteudo do PRAGMA a ser
cPragma Caracter definido no Header de retorno HTTP. Veja tabela "A" de
definições PRAGMA.

Retorno

Tipo Descrição
A função HttpPragma retornará a definição anterior de PRAGMA
Caracter
utilizada.

Descrição

Através desta função , podemos redefinir a etiqueta PRAGMA do Header de Resposta


de requisição HTTP , sobrepondo à definição defaiut de retorno PRAGMA ,
opcionalmente definida na configuração do HOST HTTP no Arquivo de configuração
do Protheus Server.

Tabela A - Definições Pragma


Conteúdo Aplicação
Informa ao Client HTTP ( Browser ) que a página retornada não deve ser
no-cache
colocada em Cache, independente da configuração de Cache do Browser.

Observação : A definição de um novo conteúdo para o PRAGMA do Header


HTTP apenas será possível caso esta função Advpl seja executada antes de
quaqlquer envio parcial de html ao browser , realizado pela função HttpSend().
HTTPRCTDISP
Revisão: 10/09/2002

Abrangência

Versão 7.10

Sintaxe

HTTPRCTDISP ( ) --> cCtDisp

Retorno

Tipo Descrição
cCtDisp corresponde ào conteudo do identificador Content-disposition ,
Caracter recebido quando um Web Browser realiza uma requisição via HTTP ao
servidor.

Descrição

A função HttpRCtDisp() , quando utilzada em uma thread montada e/ou inicializada


para atender à uma requisição Http ( .apl , .apw ) , retorna o conteúdo do identificador
Content-disposition do Header HTTP .

Caso a requisição tenha sido realizada por um client HTTP que não enviou este
identificador no Header HTTP , ou a função seja chamada em um ambiente que não
esteja atendendo à uma requisição Http ( como um JOB , por exemplo) , a função
retornará uma String em branco ("").
HTTPRCTLEN
Revisão: 10/09/2002

Abrangência

Versão 7.10

Sintaxe

HTTPRCTLEN ( ) --> nCtLen

Retorno

Tipo Descrição
nCtLen corresponde ào conteudo do identificador Content-length ,
Numérico recebido quando um Web Browser realiza uma requisição via HTTP ao
servidor.

Descrição

A função HttpRCtLen() , quando utilizada em uma thread montada e/ou inicializada


para atender à uma requisição Http ( .apl , .apw ) , retorna o conteúdo do identificador
Content-length do Header HTTP , como um dado numérico .

Caso a requisição tenha sido realizada por um client HTTP que não enviou este
identificador no Header HTTP , ou a função seja chamada em um ambiente que não
esteja atendendo à uma requisição Http ( como um JOB , por exemplo) , a função
retornará 0 ( Zero ) .
HTTPRCTTYPE
Revisão: 10/09/2002

Abrangência

Versão 7.10

Sintaxe

HTTPRCTTYPE ( ) --> cCtType

Retorno

Tipo Descrição
cCtType corresponde ào conteudo do identificador Content-type , recebido
Caracter
quando um Web Browser realiza uma requisição via HTTP ao servidor.

Descrição

A função HttpRCtType() , quando utilzada em uma thread montada e/ou inicializada


para atender à uma requisição Http ( .apl , .apw ) , retorna o conteúdo do identificador
Content-type do Header HTTP .

Caso a requisição tenha sido realizada por um client HTTP que não enviou este
identificador no Header HTTP , ou a função seja chamada em um ambiente que não
esteja atendendo à uma requisição Http ( como um JOB , por exemplo) , a função
retornará uma String em branco ("").
HTTPSEND
Revisão: 10/09/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPSEND ( < cHtmlStr > ) --> cHtmlNoSend

Parâmetros

Argumento Tipo Descrição


cHtmlStr corresponde à string a ser enviada ao Browser
cHtmlStr Caracter
solicitante de um processamento .

Retorno

Tipo Descrição
Caso a função obtenha sucesso em enviar a String cHtmlStr para o Browse
solicitante , o retorno será uma string vazia ("").

Caracter Caso não seja possível o envio da string , devido ào recurso de envio
simultâneo estar desabilitado ; ou ocorra uma falha de comunicação, ou a
função HttpSend() seja executada a partir de uam thread que não uma
Working Thread , a função irá retornar a string passada como parâmetro.

Descrição

Através desta função, é possivel retornar uma string Html à um browser durante o
processamento de uma requisição realizada através de um link .APW , utilizando
Working Threads , durante o processamento da mesma.

Observação : Este recurso não funciona em requisições de procesamento


realizadas a partir de um link .apl . É necessário que a requisição seja para um
link .apw , atendida por uma Working Thread.
HTTPSETPART
Revisão: 10/09/2002

Abrangência

Versão 6.09 Versão 7.10

Sintaxe

HTTPSETPART ( < lHttpSend > ) --> NIL

Parâmetros

Argumento Tipo Descrição


lHttpSend é um valor booleano que habilita o envio parcial
lHttpSend Lógico
( caso .T. ) ou desabilita o envio parcial de HTML ( .F. )

Retorno

Tipo Descrição
(NULO) Esta função sempre retorna NIL

Descrição

Através desta funcão , podemos habilitar ou desabilitar o envio parcial de Html ,


realizado pela função HttpSend() , para o Browser solicitante de um processamento
Advpl através de uma Working Thread.
SOAPRACTION
Revisão: 10/09/2002

Abrangência

Versão 7.10

Sintaxe

SOAPRACTION ( ) --> cSoapAction

Retorno

Tipo Descrição
cSoapAction corresponde ào conteudo do identificador soapaction ,
Caracter recebido quando um Web Browser realiza uma requisição via HTTP ao
servidor.

Descrição

A função SoapRAction() , quando utilizada em uma thread montada e/ou inicializada


para atender à uma requisição Http ( .apl , .apw ) , retorna o conteúdo string do
identificador soapaction do Header HTTP .

Caso a requisição tenha sido realizada por um client HTTP que não enviou este
identificador no Header HTTP , ou a função seja chamada em um ambiente que não
esteja atendendo à uma requisição Http ( como um JOB , por exemplo) , a função
retornará uma string em branco ("").