Palm: Tutorial para Desenvolvimento de Conduits em Delphi

O objetivo deste documento é exibir ao programador Palm uma forma de sincronizar os dados em um arquivo .pdb (Palm) com um arquivo .mdb (PC).

por Wellington Pinto de Oliveira

O objetivo deste documento é exibir ao programador Palm uma forma de sincronizar os dados em um arquivo .pdb (Palm) com um arquivo .mdb (PC).

Por que arquivo .mdb?

Utilizando um arquivo como o .mdb vou ter certeza que atingirei um grande número de pessoas que tenha um sistema compatível com este arquivo ou pelo menos tenha utilizado este uma vez na vida.

Criando um Arquivo .mdb.

Para criar um arquivo .mdb (Access) clique em Iniciar | Programas | Microsoft Access conforme a imagem abaixo.

Figura 1 - Iniciando o Microsoft Access

Será então aberto o Microsoft Access conforme a imagem abaixo. Selecione a opção "Banco de Dados Vazio do Access".

Figura 2 - Opções de Microsoft Access

Após selecionar a opção que criará um novo banco de dados você terá que salvar este arquivo, pedimos que para manter o padrão deste Tutorial crie uma pasta chamada "Conduits" na raiz C:\. Salve este arquivo como "Agenda".

Posso adiantar que nosso Conduit irá sincronizar o banco de dados criado no exemplo "Agenda" que está devidamente exemplificado no livro "Desenvolvendo Aplicações Palm com NS Basic", não se preocupe pois este arquivo já vem dentro do mesmo arquivo .zip que contem este Tutorial.

Então vamos criar uma tabela no Access que será chamada de "contatos". Para isso selecione a opção "Criar tabela no modo estrutura" conforme a imagem abaixo:

Figura 3 - Opções para criar uma tabela

Será aberta uma nova janela conforme a Figura abaixo, aqui você poderá criar a estrutura da Tabela utilizada no nosso exemplo.

Figura 4 - Estrutura da Tabela Contatos

Agora que temos os campos preenchidos precisamos definir o campo chave, no NS Basic temos sempre o primeiro campo como chave e por convenção vamos adotar este campo chave aqui também.

Para definir um campo como chave clique com o botão direito do mouse na lateral do campo, conforme a figura abaixo:

Figura 5 - Definindo o campo chave

Após definir os campos e as chaves podemos agora editar nossos primeiros registros nesta tabela e exportar para o Palm.

Para entrar no modo de edição no Access precisamos salvar esta tabela, para isso clique no ícone "Exibir".

Figura 6 - Modo edição .

Salve a tabela com o nome de "Contatos" conforme a figura abaixo:

Figura 7 - Salvando a Tabela

Agora que temos nossa tabela pronta precisamos editar alguns registros para mais tarde exportar para o Palm, abaixo temos alguns registros já preenchidos.

Figura 8 - Editando alguns registros.

Esta lista deve estar devidamente ordenada, caso não esteja o NS Basic não terá capacidade de encontrar as chaves das procuras. O Ns Basic utiliza a Busca binária.

Guarde os dois últimos telefones pois caso tenha dúvidas a Softpalm terá prazer em ajudar.

Feche a tabela e saia do Access, lembre-se este é um Tutorial passo a passo, logo não entraremos em detalhes sobre o Access.

Arquivos

No download que você efetuou você encontrou vários arquivos, abaixo estou descrevendo cada um.

Arquivo	Descrição
TemplateConduit	Contem um template já pré-pronto para ser utilizado.
ConduitFeito	Contem o Conduit já editado. Utilize para referencia se o seu apresentar problemas.
ConduitDelphi.pdf	Arquivo para auxilio no desenvolvimento de Conduits (Tutorial)
Agenda.prc	Aplicativo já compilado
NSBRunTime.prc	Run-Time para executar o Agenda.prc no Palm, é obrigatório a instalação deste para executar a Agenda.
AgendaD.prj	Aplicativo não compilado, você encontra o código fonte para o NS Basic
Agendaa.cód	Arquivo module para uso no AgendaD.prj
Agenda.mdb	Banco de Dados Do Access.
DTAgenda	Arquivo Data Link
Condcfg.exe	Executável utilizado para registro de Conduits
Delphi-conduits	Pasta com os componentes para o Delphi 4, 5, 6, e 7

Antes de continuar você ainda precisa instalar o PalmDesktop e o Delphi.

O PalmDesktop é um Software gratuito e você pode adquirir no site www.palmbrasil.com.br. Já o Delphi não é gratuito, aconselhamos o uso do Delphi 7.

Instalando os componentes

Após instalar o Delphi e descompactar o conjunto de componentes que você pode baixar no site www.softpalm.com.br. Em File | Open... conforme a imagem abaixo

Figura 9 - Abrindo os componentes.

Abra a pasta com os componentes e escolha o componente respectivo ao seu Delphi, no meu caso vou utilizar o Delphi 7. Veja a figura abaixo:

Figura 10 - Componentes do Delphi 4, 5, 6 e 7.

Será aberta uma nova janela com a relação de componentes a serem instalados.

Figura 11 - Conjunto de componentes a serem Instalados.

Clique em Install e depois em Compile. Será exibido um relatório e o resultado da instalação.

Figura 12 - Relatório de arquivos instalados. Agora que temos os componentes instalados podemos iniciar nosso projeto, para isso clique em File | Open... Abra o arquivo Conduit que está dentro da pasta TemplateConduit.

Figura 13 - Template do Projeto

Após abrir o projeto devemos abrir o Data Module, para isso clique em View | Project Manager conforme a figura abaixo.

Figura 14 - Abrindo o Project Manager

Será aberta uma nova janela com os componentes já adicionados no template, abra o Data Module conforme a figura abaixo:

Figura 15 - DataModule

Será aberta o Data Module conforme a imagem abaixo, repare que já temos um componente adicionado. Utilizamos este componente para alterar as configurações básicas do Conduit, tais como: Nome, CreatorID, etc.

Figura 16 - DataModule

Vamos abrir as propriedades deste componente para isso clique sobre o PalmComponent e tecle F11.

Figura 17 - Propriedades do Componente

Abaixo temos uma relação dos principais campos desta Paleta de Propriedades:

Campo	Descrição
ConduitName	Nome do Conduit.
ConduitVersion	Versão do Conduit.
Name	Nome deste componente.

Já podemos compilar nosso Conduit, porem é claro que ele não irá fazer nada de muito impressionante, talvez nem funcione, porem podemos agora ver os problemas básicos de configuração. Vamos efetuar o seguinte passo.

Vamos compilar nosso projeto, mas antes vamos direcionar nossa dll para o diretório do PalmDesktop, para isso clique em Projetc | Options conforme a figura abaixo.

Figura 18 - Opções para Project

Será aberta uma nova janela conforme a imagem abaixo, digite o diretório de instalação do PalmDesktop.

Figura 19 - Opções de diretórios.

Agora que redirecionamos nossa DLL para o diretório do PalmDesktop vamos compilar nosso arquivo clicando em Project | Build Conduit conforme duas Figuras acima.

Caso nosso projeto tenha exibido algum erro você deve recompilar os componente conforme o procedimento abaixo.

Recompilando os Comonentes do Delphi

Nosso primeiro passo é:
Clicar em Component | Install Component...

Figura 20 - Compilando os componentes.

Em Pakager file name selecione o pfgPalmConduitsD7.dpk conforme a figura abaixo:

Figura 21 - Janela de Instalação de Componentes

No campo Unit file name clique em Browse... e será aberta uma nova janela como no exemplo abaixo:

Figura 22 - Relação de todos os componentes

Selecione todos os componentes e clique em Abrir.

Nada foi digitado no campo Search Path. Agora que selecionamos todos os componentes basta clicar em Ok

Figura 23 - Janela de Instalação de Componentes

Será aberta novamente a janela de Pakager conforme a figura abaixo. Clique em Compile e feche a janela.

Figura 24 - Package - pfgPalmConduitsD7 Voltando ao projeto da DLL compile novamente. Podemos ver a DLL compilada no diretório do PalmDesktop conforme a imagem.

Figura 25 - Windows Explorer C:\Arquivos de Programas\Palm

Se você tentar executar o HotSync você não encontrará nenhum vestígio da execução do conduit pois para que este seja executado devemos ainda instalar no Palm a agenda e configurar o Conduit com o auxilio de uma ferramenta que acompanha este arquivo.

Vamos primeiro instalar a agenda no Palm. Isso não é segredo para ninguém, basta dar um duplo clique no arquivo agenda.prc e sincronizar.

Após instalar a agenda no palm temos que registrar o conduit, para isso copie a ferramenta Condcfg.exe que acompanha este arquivo e cole na raiz da pasta do PalmDesktop, ou seja, junto com o Conduit.dll, estando lá execute o mesmo. Será aberta uma janela conforme a exibida abaixo:

Figura 26 - CondCFG.exe

Há primeira vista podemos ver todos os conduits já instalados. Vamos Configurar o nosso, para isso clique em Add..

Será aberta uma nova tela conforme abaixo:

Figura 27 - Informações básicas para registro do Conduit

Edite as propriedades deste componente conforme a tabela abaixo:

Campo	Valor
Conduit Type	Component
Conduit	Conduit
Creator ID	EX04
Priority	2

Agora clique em OK.

Nossa DLL já faz parte do conjunto de conduits a serem executados no HotSync.

Figura 28 - Relação de conduits para Sincronização.

Clique em Exit.

Será exibida a seguinte mensagem.

Figura 29 - Mensagem do Conduit Manager.

O HotSync será Reiniciado, caso isto não ocorra reinicie manualmente o HotSync. Agora que a DLL está devidamente registrada estamos prontos para efetuar o primeiro HotSync com o Conduit. Efetue o HotSync.

Para saber se o conduit foi executado basta clicar com o botão direito do mouse sobre o ícone de hotsync

Figura 30 - Opções do HotSync.

Será exibido uma nova janela com o relatório completo do andamento do HotSync, incluindo data, componentes, becaps, etc..

Figura 31 - Relatório da execução do HotSync

Temos nosso conduit funcionado, você deve estar pensando duas coisas:

1 - Ele não fez nada de especial.
2 - Por que não ligar para a esposa (patroa) para desmarcar tudo e continuar estudando este Tutorial?

Para o pensamento 1 ele fez a coisa mais difícil, ele acionou um conduit, agora tudo vai ficar mais fácil pois o template já está rodando.

Configurando a Conexão do Conduit com o Banco de Dados

Vamos agora configurar a conexão do nosso conduit com o Banco de dados Agenda.mdb.

Vamos copiar o arquivo DTAgenda que acompanha este Tutoria e colar em:

C:\Arquivos de programas\Arquivos comuns\System\Ole DB\Data Links

Este arquivo Data Link será utilizado como ancora para nosso conduit pois se o usuário modificar o diretório do Banco de Dados Agenda.mdb ele não precisa recompilar a DLL, basta modificar o endereço no Data Link.

Dê um duplo clique sobre o objeto Data Link para entrar nas configurações deste arquivo, será exibido uma janela de configurações de conexão conforme a Figura abaixo:

Figura 32 - Propriedade do Data Link

Voltando ao Delphi, vamos adicionar um componente de conexão e apontar para este Data Link, para isso selecione a paleta ADO conforme a imagem abaixo.

Figura 33 - Paleta de Componentes do Delphi 7

Adicione o componente de conexão indicado na figura acima, basta clicar no componente e depois clicar sobre o Data Module.

Figura 34 - Data Module

Agora precisamos modificar as propriedades do ADOConnection1.

Figura 35 - Data Module com o objeto ADOConnection

Ao dar um duplo clique no componente ADOConnection você pode configurar a conexão apontando para o Data Link. Selecione Use Data Link File e clique em Browse.

Figura 36 - Configuração da Conexão ADOConnection1 Será aberta uma nova janela onde podemos escolher o Data Link DTAgenda.

Figura 37 - Arquivos Data Link

Clique em Abrir e será fechado esta janela e voltaremos ao componente de Conexão "ADOConnection1".

Figura 38 - Configuração da Conexão ADOConnection1

Clique em OK e pronto, temos nossa conexão perfeitamente configurada.

Adicionado Tabelas

Para utilizar as tabelas temos que adicionar componentes ao Data Module. Cada banco terá um componente diferente e serão feitos por partes.

Tabelas do Agenda.mdb

Nosso próximo passo é adicionar um componente ADO que faça a conexão com a tabela Contatos no arquivo Agenda.mdb.

Selecione o componente ADOTable na paleta ADO, conforme na Figura abaixo:

Figura 39 - Objetos ADO

Agora basta dar um clique sobre o Data Module, posicione o componente conforme a Figura abaixo:

Figura 40 - Data Module

Selecione o componente ADOTable1 e clique F11, repare que será aberta uma Janela de propriedades no lado esquerdo do Delphi.

Figura 41 - Propriedades do Componente ADOTable1

Clique sobre o campo Connection para selecionar a conexão que esta tabela deve utilizar.

Selecione a conexão configurada no componente ADOConnection1 conforme a Figura abaixo.

Figura 42 - Propriedades do ADOTable1

Agora que selecinamos o objeto ADOConnection1 vamos selecionar a tabela que este componente deve se conectar, para isso clique sobre o campo TableName e selecione a tabela Contatos.

Figura 43 - Propriedades do ADOTable1

Vamos agora definir o campo chave, este deverá ser ordenado durante o Sincronismo, para isso basta informar o campo nome em IndexFieldNames.

Figura 44 - Propriedades do ADOTable1

Agora só falta modificar o nome do componente. Será por este nome que vamos nos referir no Delphi a este componente.

Selecione o campo Name e edite PCContatos conforme a Figura abaixo.

Figura 45 - Propriedades do ADOTable1

Agora vamos editar os Fields que estão nesta tabela, para isso clique com o botão direito do Mouse sobre o objeto PCContatos (antigo ADOTable1) e selecione a opção Fields Editor... conforme a imagem abaixo.

Figura 46 - Abrindo o Editor de Fields

O Editor de Fields do componente PCContatos é bem simples, veja a figura abaixo:

Figura 47 - Editor de Fields do PCContatos

Para carregar os Fields basta clicar com o botão direito do mouse sobre este editor e selecionar a opção Add All Fields.

Figura 48 - Adicionando automaticamente todos os Fields Ao clicar em Add All Fieds o Delphi irá reconhecer automaticamente os campos da tabela Contatos do arquivo Agenda.mdb, conforme a figura abaixo.

Figura 49 - Campos da tabela Contatos

Tabela Remota DBAgen.pdb

Para acessar a tabela do palm temos que criar um componente Remoto, para isso selecione a paleta Palm Pilot, caso ela não esteja visível clique em avançar para visualizar esta paleta. Veja a figura abaixo:

Figura 50 - Visualizando as demais paletas do Delphi.

Abaixo temos a paleta de componentes para Palm Pilot.

Figura 51 - Paleta de componentes Palm Pilot

Selecione pfgPalmRemoteTable e clique no Data Module.

Clique sobre o componente adicionado ao Data Module e tecle F11 para acessar suas propriedades. Modifique o campo Nome para PalmContatos. No campo TableName digite DBAgen e no campo Creator ID digite EX04. Veja a figura abaixo.

Figura 52 - Propriedades do pfgPalmRemoteTable

Para editar os fields desta tabela remota basta clicar no campo FieldDefs, irá aparecer 3 pontos conforme a imagem abaixo:

Figura 53 - Propriedades do PalmContatos

Será exibido a janela abaixo, este editor não reconhece automaticamente os campos, porem temos que adicionar um a um e configurar os Fields.

Figura 54 - Editor de Fields do PalmContatos

Ao adicionar dois novos Fields clique sobre o primeiro e tecle F11 para editar as propriedade deste Field.

Figura 55 - Editor de Fields do PalmContatos

No editor de propriedades do primeiro field Altere suas propriedades para:

Campo	Valor
Data Type	ptString
Field Name	Nome

Veja a Figura abaixo:

Figura 56 - Propriedades do Primeiro Field

Modifique as propriedades do segundo Field para:

Campo	Valor
Data Type	ptString
Field Name	Telefone

Logo nossa Tabela Remota (PalmContatos) terá os seguintes campos:

Figura 57 - Campos em PalmContatos

Editando os códigos do conduit

Podem dizer adeus as configurações, agora vamos entrar no código fonte do conduit. Não se assuste pois utilizaremos poucos conceitos de Delphi. Para entrar no editor de código do Data Module basta clicar na tela ao fundo do Data Module ou teclar F12.

Figura 58 Delphi 7

Para entrar ou sair do Editor de Códigos do Data Module basta teclar F12.

Abaixo temos o código já gerado para o Data Module.

unit DataModule;

interface

uses
  SysUtils, Classes, Forms, pfgPalmDb, pfgBaseClasses, pfgPalmComp, DB,
  ADODB;


type
  TDados = class(TDataModule)
    PalmComponent: TpfgPalmComponent;
    ADOConnection1: TADOConnection;
unit DataModule;

interface

uses
  SysUtils, Classes, Forms, pfgPalmDb, pfgBaseClasses, pfgPalmComp, DB,
  ADODB;


type
  TDados = class(TDataModule)
    PalmComponent: TpfgPalmComponent;
    ADOConnection1: TADOConnection;
    PCContatos: TADOTable;
    PCContatosNome: TWideStringField;
    PCContatosTelefone: TWideStringField;
    PalmContatos: TpfgPalmRemoteTable;
    procedure PalmComponentExecConduit(const props: TpfgSyncProperties);
    procedure DataModuleCreate(Sender: TObject);
    procedure DataModuleDestroy(Sender: TObject);
  private
    FCacheLocaliza: TStringList;
    //-----------------Campo 1-----------------------------------
    //-----------------Não modificar nada acima------------------
    //-----------------Aqui eu Declaro as Procedures-------------


    //----------------Fim das declarações------------------------
    //----------------Não modificar nada abaixo------------------
  public
  end;

var
  Dados: TDados;

implementation
uses pfgWTypes, pfgPalmMisc, pfgPalmSyncError, pfgSyncMgr, pfgHslog;

{$R *.dfm}
//-----------------Campo 2---------------------------------------
//-----------------Não modificar nada Acima----------------------
//-----------------Aqui eu Implemento as Procedures--------------


//----------------Fim da área de Implementação de Procedures-----
//----------------Não modificar nada abaixo----------------------
procedure TDados.PalmComponentExecConduit(const props: TpfgSyncProperties);
var h: CONDHANDLE;
begin
  // Register the conduit activity
  PalmCheck(SyncRegisterConduit(h));
  try
    try
      Log("", slSyncStarted);

      Log("*************************************************************");
      Log("*************************************************************");
      Log("http://br.groups.yahoo.com/group/livro-nsbasic");
      Log("*************************************************************");
      Log("*************************************************************");
      Log("Livro de NS Basic para PalmOS www.softpalm.com.br");
      //--------------Campo 3------------------------------------
      //--------------Não modificar nada acima-------------------
      //--------------Aqui eu chamo as procedures----------------


      Log(" Aqui faço as chamadas as procedures....");


      //--------------Fim----------------------------------------
      //--------------Não modificar nada abaixo------------------
      Log("************************************************************");
      Log("************************************************************");
   

      Log(" ");
    except
      on E: Exception do Log("Erro durante sincronização. Mensagem original: " + e.Message);
    end;
    Log(ConduitName, slSyncFinished);
  finally
    SyncUnRegisterConduit(h);
  end;
end;

procedure TDados.DataModuleCreate(Sender: TObject);
begin
  FCacheLocaliza:= TStringList.Create;
  FCacheLocaliza.Sorted:= True;
end;

procedure TDados.DataModuleDestroy(Sender: TObject);
begin
  FCacheLocaliza.Free;
end;

initialization
  Dados:= TDados.Create(Application);

finalization
  Dados.Free;

end.

Marquei três campos editáveis, não que você não possa modificar todo o código apenas quis padronizar o conduit.

No campo 1 vamos declarar as procedures que vamos utilizar. Vamos dividir em duas parocidures diferentes a TransferePamparaPC e TransferePCparaPalm.

Edite no campo 1 o seguinte código:

procedure TransferePalmparaPC;
procedure TransferePCparaPalm;

No campo 2 vamos implementar as duas procedures declaradas acima, para isso digite o seguinte código:

procedure TDados.TransferePalmparaPC();
begin
  //Confirmando se exixte a tabela DBAgen.pdb no Palm
  //Caso não exista devemos criar utilizando CreateTable
  if not PalmContatos.Exists then
    PalmContatos.CreateTable;
  //Devemos abrir todas as tabelas envolvidas no processo
  PalmContatos.Open;
  PCContatos.Open;
  try
    //Informando o numero de registro no Palm. Utilizamos RecordCount
    //RecordCout retorna um número Inteiro
    Log("total de registros no Palm: " + InttoStr(PalmContatos.RecordCount));
    //Se possuimos um ou mais registro devemos iniciar a trasferencia
    if PalmContatos.RecordCount> 0 then
    begin
      Log("Iniciando a trasferencia");
      //Aplicanto um While no PalmContatos. EOF se for fim de arquivo
      while not PalmContatos.EOF do
      begin
        //Verificando se exite o nome no banco de dados Agenda.mdb
        if not PCContatos.Locate("Nome", PalmContatos.FieldByName("Nome").asString, []) then
        begin
          //Caso não exista devemos inserir em Agenda.mdb o registro que
          //vem do DBAgen.pdb
          Log("Inserindo: " + PalmContatos.FieldByName("Nome").asString);
          PCContatos.Insert;
        end else
        begin
          //Caso já exista vamos modificar
          Log("Alterando: " + PalmContatos.FieldByName("Nome").asString);
          PCContatos.Edit;
        End;
        PCContatos.FieldByName("Nome").asString := PalmContatos.FieldByname("Nome").asString ;
        PCContatos.FieldByName("Telefone").asString := PalmContatos.FieldByname("Telefone").asString ;
        //Temos que enviar, para isso vamos utilizar o Post
        PCContatos.Post;
        //Avançar um Registro com o Next
        PalmContatos.Next;
      End;
    end;
  finally
    //Caso ocorra algum erro ou tudo ocorra bem vamos fechar no finally
    PalmContatos.Close;
    PCContatos.Close;
  end;
end;

procedure TDados.TransferePCparaPalm();
begin
  if PalmContatos.Exists then
    PalmContatos.DeleteTable;
  PalmContatos.CreateTable;
  PalmContatos.Open;
  PCContatos.Open;
  try
    Log("total de Registros no PC: " + InttoStr(PCContatos.RecordCount));
    if PCContatos.RecordCount> 0 then
    begin
      Log("Iniciando a trasferencia");
      while not PCContatos.EOF do
      begin
        PalmContatos.Insert;
        Log("Inserindo: " + PCContatos.FieldByName("Nome").asString );
        PalmContatos.FieldByName("Nome").asString := PCContatos.FieldByname("Nome").asString ;
        PalmContatos.FieldByName("Telefone").asString := PCContatos.FieldByname("Telefone").asString ;
        PalmContatos.Post;
        PCContatos.Next;
      End;
    end;
  finally
    PalmContatos.Close;
    PCContatos.Close;
  end;
end;

No campo 3 estaremos chamando as procedures. Sempre que o Conduit for executado ele acionará a procedure PalmComponentExecConduit().

Log("Palm -> PC");
TransferePalmparaPC();
Log("");
Log("PC -> Palm");
TransferePCparaPalm();
Log("Trasferencia finalizada com sucesso.");

Sincronize o Palm, não se esqueça de instalar a Agenda no palm.

Bom visualize a execução do Conduit através da Janela HotSync Progress.

Figura 59 - HotSync Progress

Para visualizar o relatório gerado pelo HotSync clique com o botão direito do mouse sobre o símbolo de Hostync no canto inferior direito da tela e selecione View Log...,veja a figura abaixo.

Figura 60 - Opções da ferramenta Hotsync

Abaixo temos uma descrição do Log.

Este foi um simples exemplo de conduit que desenvolvi para auxiliar a configuração e desenvolvimento. Estamos na primeira versão deste tutorial e falta muito para este se tornar um Tutorial completo, porem já é um grande avanço divulgar o básico da construção do conduit em Delphi.

Estaremos sempre atualizando este tutorial e divulgando nestes dois links:
http://www.softpalm.com.br
http://br.groups.yahoo.com/group/livro-nsbasic

Caso tenha alguma sugestão entre em algum destes dois links acima e envie.

Todos os arquivos estão disponíveis para download nos links acima.

Muito obrigado.

Wellington Pinto de Oliveira.