Cabeçalho

TCLink [AS]

Autor: Eurai Criado: 01/01/2016 Atualizado: 25/04/2025 Acesso a Dados

Postagem

Descrição

TCLink [AS] - Cria uma nova conexão com um banco de dados SGBD através do TOPConnect ou DBAccess.

Sintaxe

TCLink( <cConexao>, <cServerAddr>, <nPort> )

Parâmetros

Par	Nome	Tipo	Descrição	Default	Obg	Ref
01	cConexao	Caracter	Indica a string de conexão do DBAccess, composta por um identificador do tipo da conexão mais o nome do alias/environment da conexão, configurada do TOPConnect ou DBAccess		X
02	cServerAddr	Caracter	Indica o nome ou endereço IP do servidor onde está o TOPConnect ou DBAccess onde a conexão deve ser realizada
03	nPort	Numérico	Indica o número da porta TCP que o TOPConnect ou DBAccess está configurado aguardando por novas conexões	7890

Retorno

Retorno	Tipo	Descrição
nRet	Numérico	Retorna um identificador numérico igual ou maior que zero para a conexão em caso de sucesso. Em caso de falha, será retornado um número negativo, indicando uma ocorrência de falha na conexão.

Exemplo

#INCLUDE "TOTVS.CH"
 
 
User Function TCLink()
Local nRet		:= 0
Local cMsg		:= ''
 
 
If ( nRet := TCLink( 'MSSQL/UAUA', '127.0.0.1', 7890 ) ) < 0
	cMsg += 'Conexão (MSSQL/UAUA): Erro ' + Str( nRet, 4 )
Else
	TcUnlink( nRet )
Endif
 
If ( nRet := TCLink( 'MSSQL/UNIVERSOADVPL', '127.0.0.1', 7890 ) ) < 0
	cMsg += 'Conexão (MSSQL/UNIVERSOADVPL): Erro ' + Str( nRet, 4 )
Else
	TcUnlink( nRet )
Endif
 
 
MsgInfo( cMsg, 'UniversoADVPL' )
 
 
Return( Nil )

Resultado
tclink_-_resultado_01

Informações adicionais

Através da função TCLink(), é possível abrir uma nova conexão em um banco de dados (SGBD) através do TOPconnect ou DBAccess. Apenas após realizar uma conexão, é possível utilizar a RDD "TOPCONN".Em um ambiente configurado, no Application Server, para utilizar RPODB=TOP (para Microsiga Protheus 8 e anteriores) ou RPODB=SQL, para Microsiga Protheus 10, quando executamos aplicações e/ou User Functions a partir do menu do ERP, as rotinas de montagem de ambiente do Framework ERP internamente utilizam a função TCLink() para abrir a conexão com o TOPConnect ou DBAccess e utilizar a RDD TOPCONN.A montagem da string de conexão (1º parâmetro) deve conter um identificador de tipo de conexão, seguido do caractere "/" (barra) e do nome da conexão configurada no TOPConnect ou DBAccess. Os tipos de conexões podem ser :
- MSSQL – Para bancos de dados Microsoft SQL Server
- ORACLE – Para bancos de dados Oracle.
- INFORMIX – Para bancos de dados Informix.
- DB2 – Para bancos de dados DB2 (DB2 UDB e DB2 400 com TOP4 para AS400/iSeries).
- POSTGRES – Para bancos de dados PostgreSQL.
- ODBC – Para estabelecer uma conexão ODBC (*) Genérica.

(*) Uma conexão ODBC genérica pode ser utilizada em fontes para integrações e customizações, mas não pode ser utilizada como base de dados principal da aplicação Microsiga Protheus/ERP.

O nome da conexão configurada no DBAccess, para a maioria dos bancos, é o nome dado à conexão ODBC configurada no equipamento, com exceção para conexões com banco de dados Oracle, onde o nome das conexões é definido no arquivo TNSNAMES.ORA, configurado junto do engine OCI Client do Oracle, usado pelo DBAccess para estabelecer conexão com o SGBD.

O handler da conexão retornado pela função TCLink(), é utilizado para ser possível realizar mais de uma conexão no mesmo processo entre bancos diferentes, trocar entre as conexões ativas em tempo de execução de código e ainda fechar posteriormente as conexões estabelecidas. Quando a função TCLink() é executada e estabelece uma nova conexão com sucesso, esta conexão torna-se a conexão ativa imediatamente. A conexão existente continua aberta e todas as tabelas e queries abertas na conexão anteriormente ativas permanecem amarradas à conexão na qual elas foram abertas. Ao tornar uma nova conexão ativa, ela será efetivamente utilizada a partir do momento em que se tornou ativa nas operações de abertura de queries e abertura de tabelas e execução de statements.

Caso a conexão não seja estabelecida com sucesso, o handler será um número negativo, indicando uma situação de erro. Para mais detalhes sobre os códigos de erros retornados, consulte a documentação "Lista dos códigos de erros do TOTVSDBAccess".

BANCOS

Microsoft SQL Server	MSSQL
Oracle	ORACLE
IBM DB2 ( UDB )	DB2
IBM DB2 ( AS400 / iSeries ) (**)	DB2/400
IBM Informix	INFORMIX
Sybase	SYBASE
PostgreSQL	POSTGRES
Generic ODBC Connection	ODBC
MySQL	MYSQL