TCLink

TCLink ( < cConexao>, < cServerAddr>, [ nPort] ) --> nHndConn

(numerico)
• 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.

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

User Function MyLink()
Local cDBOra := "ORACLE/P10_TESTE"
Local cSrvOra := "172.16.0.1"
Local nHndOra
nHndOra := TcLink(cDbOra,cSrvOra,7890)
If nHndOra < 0
    UserException("Erro ("+srt(nHndOra,4)+") ao conectar com "+cDbOra+" em "+cSrvOra)
Endif
conout("Oracle conectado - Handler"+str(nHndOra,4))
TcUnlink(nHndOra)
conout("Oracle desconectado.")
Return