Manual Sqllib Rdd

GUIADEREFERNCIAE MANUALDEINSTALAO

AbrangeaSQLLIBv1.5deAbrilde2007.

Reproduototalouparcialproibidaexcetocomconsentimentoexpressoeporescritodoautor

Reviso2.8Abrilde2007 [email protected]

ndiceGer alIntr oduo.............................................................................................................. Legenda............................................................................................................ Agradecimentos................................................................................................. InstalaoePr imeir osPassos ................................................................................................... ComoinstalaraSQLLIB....................................................................................................... Quaisbibliotecas(*.LIB)eunecessitoutilizaremmeuprojeto?........................................... ProblemasnaconexoaoservidorSQL?............................................................................... GuiadeRefer encia .................................................................................................. ComandosSQLCONNECTON................................................................................................. SQLCONNECT(comStringsdeConexo)............................................................ SQLDISCONNECT................................................................................................. SQLEXECUTE...................................................................................................... SQLTRANSLATEPATH.......................................................................................... SQLTRANSLATECASE........................................................................................... SQLCUSTOMINDEXES........................................................................................... SQLPACKETSIZE................................................................................................. SQLCURRENTPACKETSIZE.................................................................................... SQLFULLDELETE................................................................................................. SQLFILTER........................................................................................................ COPYTABLE........................................................................................................ DELETETABLE..................................................................................................... DELETEINDEX..................................................................................................... RENAMETABLE..................................................................................................... RENAMEINDEX..................................................................................................... STARTTRANSACTION............................................................................................ ENDTRANSACTION................................................................................................ COMMITTRANSACTION........................................................................................... ROLLBACKTRANSACTION....................................................................................... CLEARINDEXES................................................................................................... SELECTSCHEMA................................................................................................... USE.................................................................................................................... USESQL/USEAS.............................................................................................. I I1 I2 II II1 II2 II3 III III1 III2 III3 III4 III5 III6 III7 III8 III9 III10 III11 III12 III13 III14 III15 III16 III17 III18 III19 III20 III21 III22 III23 III24 IV IV1 IV2 IV3

Funes.................................................................................................................. Tr aduodenomesdearquivosSQLParseStyle()................................................................................................ SQLParseCase()................................................................................................. SQLParse()........................................................................................................

Ger enciamentodeconexesSQLConnect()..................................................................................................... SQLConnParse()................................................................................................. SQLDisconnect()................................................................................................ SQLGetConnection()........................................................................................... SQLSetConnection()........................................................................................... SQLGetConnections()......................................................................................... SQLGetConnectionInfo().................................................................................... SQLGetRddName()................................................................................................ SQLErrorMsg()................................................................................................... SQLErrorNO().................................................................................................... SQLPacketSize()................................................................................................ IV4 IV5 IV6 IV7 IV8 IV9 IV10 IV11 IV12 IV13 IV14

ExecuodecomandosSQLSQLExecute()...................................................................................................... SQLArray().......................................................................................................... SQLArrayAssoc()................................................................................................. IV15 IV16 IV17

SQLLIBRDDparaHarbour&xHarbour,20032006porVailtonRenato [email protected].

Pg.2

SQLNullDate().................................................................................................... SQLNull()...........................................................................................................

IV18 IV19

ManipulaodedadosSQLFilter()........................................................................................................ SQLRefresh()...................................................................................................... SQL_AffectedRows()............................................................................................ SQL_FullDelete()................................................................................................ IV20 IV21 IV22 IV23

Manipulaodetabelas/ndicesSQLCreateFlags()................................................................................................ DBCreate().......................................................................................................... TABLE()............................................................................................................... INDEX()............................................................................................................... TAG().................................................................................................................. DATABASE().......................................................................................................... TrueReccount()................................................................................................... SQLCopyTable()................................................................................................... SQLRenameTable()................................................................................................ SQLRenameIndex()................................................................................................ SQLDropTable()................................................................................................... SQLDropIndex()................................................................................................... SQLAlterTable()................................................................................................. SQLUseCustomIndexes()....................................................................................... IV24 IV25 IV26 IV27 IV28 IV29 IV30 IV31 IV32 IV33 IV34 IV35 IV36 IV37

Ger enciamentodetransaesSQLBeginTrans()................................................................................................ SQLEndTrans()................................................................................................... SQLCommit()....................................................................................................... SQLRollBack()................................................................................................... SQLTransCount()................................................................................................ IV38 IV39 IV40 IV41 IV42

Funesdiver sasdoser vidor SQLSQLGetDBInfo().................................................................................................. SQLGetTables().................................................................................................. SQLGetIndexes()................................................................................................ SQLGetDBs()....................................................................................................... SQLGetUsers()................................................................................................... SQLGetConnectedUsers().................................................................................... SQLServerVersion()............................................................................................ SQLServerDate()................................................................................................. SQLServerTime()................................................................................................. IV43 IV44 IV45 IV46 IV47 IV48 IV49 IV50 IV51

FunesdeconversoSQLDate().......................................................................................................... SQLStr()............................................................................................................ SQLNTrim()........................................................................................................... ToString()........................................................................................................ IV52 IV53 IV54 IV55

Funesdiver sasSQLRowID()........................................................................................................ SQLVersion()..................................................................................................... SQLLIB()............................................................................................................ IV56 IV57 IV58

Backup&Restor eSQLBackupStart().............................................................................................. SQLBackupEnd().................................................................................................. SQLBackupRestore()........................................................................................... SQLBackupTable().............................................................................................. SQLBackupRoutines()......................................................................................... SQLBackupBlock().............................................................................................. IV59 IV60 IV61 IV62 IV63 IV64

SchemasSQLSchema()....................................................................................................... IV65


Pg.3

SQLSystemSChema().............................................................................................

IV66

FunesdebaixonveldaAPI_SQL_GetPointer()............................................................................................. _SQL_GetConn().................................................................................................. _SQL_SystemID()................................................................................................ _SQL_SystemIDStr()........................................................................................... _SQL_TableStyle()............................................................................................. _SQL_TableName()............................................................................................... _SQL_FullTableName()........................................................................................ _SQL_TableSchema()............................................................................................ IV67 IV68 IV69 IV70 IV71 IV72 IV73 IV74

Compatibilidade ApndiceA ndicescomaSQLLIB.......................................................................................... ApndiceBDicasdeperformance............................................................................................... ApndicaCUsandooFiveWineaSQLLIBRDD....................................................................

A1 A2 A3


Pg.4

I Intr oduoOProjetoSQLLIBfoidesenvolvidoparasuprirumagrandedeficinciadaatualcomunidadexBase, necessidadeestadeconexocombancodedadosremotosnaslinguagensHarbourexHarbour. Anteriormente estes usurios xBase no contavam comuma soluoque fosse acessvel todos para conexocomosbancosdedadosremotos,limitandoseapenasaosantigosarquivosDBFs(DataBase Files). Foipensandonissoquensconstrumosentoumaferramentamodernaquesurgiuparapossibilitare tornarvivelestetipodecomunicaocliente/servidor,deumaformaseguraeeficiente. ASQLLIBestsendoprojetadaparapermitirconexesremotasdemodotransparenteviaRDDcom asseguintesbasesdedados: MySQL,PostgreSQL, Firebirde ODBC. Afacilidadeeaperformancedesuautilizaopermitemque,comumconjuntomnimodeadaptaes, ossistemaspossammigrardemodotransparenteparataisSGBDs(SistemasGerenciadoresdeBanco deDadosouservidoresSQL),evitandoassimumagrandecurvadeaprendizadoeaproveitandotodaa experinciadoprofissionalxBase,almderepresentarumaexcelenterelaocusto/benefcio. ASQLLIBumasoluocompletaparaaatualcomunidade,comsuporteeatualizaesconstantes mantidaspornossaequipededesenvolvimento. EstedocumentocontminformaesimportantessobreoscomandosefunessuportadospelaSQL LIB.Esperamosqueestadocumentaosejadegrandeajudaparatodos,especialmenteosnovosque desejaminiciarnoempolgantemundodoSQL!

1. conesutilizadosAsexplicaeseomaterialcontidonestedocumentoquandoapropriadosseroacompanhadosdeum coneparaidentificaraimportnciadaorientaoquesesegue.EisabaixonatabelaI1oscones empregadosesuasrespectivasimportncias: Esteconedenotamateriainformativa,comoumaexplanaodealgumassunto relativoaocontexto Esteconeidentificaummaterialimportante queexigeatenoepodelhepouparum tempo,talcomoumadicaoumaceteenvolvendoalgumafunoemSQL. Esteconeindicaalgumaadvertnciaouinformaodeextremaimportncia.TabelaI1

2. Agr adecimentosAgradeotodosqueacreditaramemmeutrabalhomasespecialmenteFrankLenonRodriguespela ajudaeapoioprestadosetambm KleyberDrickB.Ribeiro pelaatenonosmomentosdifceisdese domaroFivewindevidominhafaltadeexperinciainicial.Masgostariadeespecialmenteagradecer aquelas pessoas queno meapoiaramem nenhum momentoepelo contrrio atdificultaram e em muitoascoisasparamim,nodecorrerdestepercurso. Sendoassimtodosagradeo:obrigado,muito obrigadoporutilizarnossasferramentas. Desejosucessotodoseataprxima!

VailtonRenatoSQLLIB,WxWeb,MyMake&xDevStudio Developer


Pg.5

II InstalaoePr imeir ospassosA SQLLIBdistribudadepormeioseletrnicos porduasmaneirasdistintas,poispossui2verses:a FREEquevisaajudartodosnacomunidadeoferecendoacessonativoMySQLeumaverso comercial,maisrobustaecompletacomacessocompletotodososbancosSQLsuportadospelaLIB. ParaclientesdaversoFREE, baixeopacotedeinstalaodiretamentedenossosite,clicando aqui: http://www.sqllib.com.br/download.php Paraclientescomerciais,vocreceberum email confirmandoosdadoscadastraisdesua empresa,juntamentecomseunmerodesrieparasuporte. Sigaasinstruesqueconstam nesteemailparaefetuarodownloaddaRDDcomercial. Osarquivosdeinstalaoda SQLLIBobedecemumanomenclaturadefcilcompreenso: SQLLIBv1.5cFREE.zip DenotaumarquivodeinstalaodaSQLLIBnaverso1.0eindicaqueamesmatrataseda versoFREE daRDD. SQLLIBv1.5cComercialDEMO.zip Denota umarquivodeinstalaodaSQLLIBnaverso1.0eindicaaversoCOMERCIAL da RDD,liberadaapenasparaclientesregistrados.

1.Comoinstalar aSQLLIBOprocessodeinstalao paraambosomesmo. Descompacteoarquivo.ZIPeexecuteoaplicativode instalaocontidodentrodopacote.Certifiquesededescompactarosarquivosnamesmapastadoteu compilador.VocpodeseguramenteinstalaraSQLLIBemoutrodiretrio quenosejao do teucompilador.Nestecasosernecessrio quevoccopieosarquivosdeINCLUDEeasLIBsparaassuasdevidaspastas,ondeestinstaladooseuHarbourou xHarbour.

Aps o trmino do processo acima, voc j estar tudo pronto para utilizar a ferramenta. Como downloadadicional,recomendamosquevocbaixetambmoDBF2SQL(antigoDBF2MYSQL) quese encontraparadownloademnossosite,afimdelheajudarnoprocessodemigraodesuasbasesde dadosatuaisemDBFparaoservidorSQL.

2.QuaisLIBseunecessitoemmeupr ojeto?ASQLLIBumprojetofantsticopeloqueelasepropeafazeretemfeito:ofereceromesmoRDD paratodasasversesdoHarbouredoxHarbouratualmentemaisusadas.Sendoassim,temoshojeno cenrio10 versesda SQLLIBcadaumacompiladaeotimizada paraseucompiladorespecfico: SuporteparaHarbourverso45.0 SuporteparaxHarbourverso0.99.0,0.99.1,0.99.2,0.99.3,0.99.4, 0.99.50,0.99.51a(FW2.6),0.99.51(FW2.7),99.60eversesfuturas. QuandovocinstalaaSQLLIBestarrecebendoversesdaRDDparavrioscompiladores. necessriosaberidentificarqualaLIBcorretaparaexecuodoseuaplicativo.Umexemploda nomenclaturautilizadaparaidentificaomostradocomonesteexemplo:P:\SQLLIB\COMERCIAL\LIB>dir OvolumenaunidadePP43.2HT OnmerodesriedovolumeCCD86FDF PastadeP:\SQLLIB\COMERCIAL\LIB 30/01/200620:45.


Pg.6

30/01/200620:45.. 17/11/200419:3916.384libmysql.lib 28/01/2006 19:39 102.912blibpq.lib 30/01/200620:45148.480sqllib_HB_450.LIB 30/01/200620:44149.504sqllib_xHB_0990.LIB Istoidentificaqualo 30/01/200620:44149.504sqllib_xHB_0991.LIB 30/01/200620:43 149.504sqllib_xHB_0992.LIB compiladorsuportadoporesta LIBHarbourouxHarbour 30/01/200620:36149.504sqllib_xHB_0993.LIB 30/01/200620:35150.016sqllib_xHB_0994.LIB 30/01/200620:35150.016sqllib_xHB_09950.LIB 30/01/200620:34146.944sqllib_xHB_09951.LIB Istoindicaaversodo 30/01/200620:34150.016sqllib_xHB_09951a.LIB compiladorsuportado. 11arquivo(s)1.359.872bytes Nestecaso,oxHB0.99.50 2pasta(s)907.030.528bytesdisponveis P:\SQLLIB\COMERCIAL\LIB>

Para identificarmos a verso correta a ser utilizada simples, basta observar o esquema acima. Por exemplo, se estivermos compilando com o xHarbour verso 0.99.50, iremos utilizar a sqllib_xhb_09950.lib emnossoprojeto. Visto que a SQL LIB oferece acesso nativo, iremos necessitar tambm de algumas libs adicionais, conforme o servidor que iremos nos conectar. A tabela II1 mostra quais arquivos adicionais so necessrios,dependendo dodriverqueiremosutilizar:Arquivo DriverRDDlibmysql.lib EstalibcontmasrotinasdeacessoaobancoMySQL. blibpq.lib

EstalibutilizadapelaRDDparaefetuarconexocomoPostgreSQL.

TabelaII1

Lembrando que tais arquivos so obrigatrios apenas quando se deseja utilizar o respectivo banco. Sendo assim, um programador que ir utilizar MySQL apenas pode decidir no incluir as LIBs do PostgreSQLouviceversa,tornandootamanhodoseuexecutvelfinalmenor.

3. Pr oblemasnaconexoaoser vidor SQL?ASQLLIBforneceocomandoSQLCONNECTparaestabelecerumaconexocomoservidorSQL. Consulte logo abaixo neste manual sobre este o comando. Se estiver encontrando problemas em estabeleceraconexo,observealgumasdicas: 1. FirewallNocasodevocestartentandoacessarummicronaredeouviainternetenoestar conseguindo logar, verifique se h algum firewall ativo. Se houver, talvez seja necessrio habilitar acesso externo este micro pela porta que o servidor SQL usa por exemplo: o MySQLusaaporta3306eoPostgreSQL5432. 2. Autenticao Servidores SQL possuem um sistema de controle de acesso que variam de servidorparaservidor,masbasicamenteconsistememverificar3coisas: a. Seousuriovlido b. Seasenhainformadaconfere c. SeoIPdeonde partiuasolicitaodeconexovlido Este ltimo ponto importante por que, mesmo se um nome e senha corretos forem fornecidos,o servidor SQL pode recusar a conexo casooIP deondepartiu a solicitao noforvlido,combasenassuasconfiguraesinternas.


Pg.7

Problemascomautenticaosofceisdese solucionar,maso procedimentopara seefetuar estaconfiguraomuda deacordocomoSGBDutilizado.Eisalgumasrefernciasparasua pesquisa(todosemportugus): Umartigointeressantesobreesteassuntoem MySQL,estdisponvelnestelink: http://dev.mysql.com/doc/refman/4.1/pt/addingusers.html http://dev.mysql.com/doc/refman/4.1/pt/oldclient.html (emportugus) http://dev.mysql.com/doc/refman/5.0/en/oldclient.html(emingls) EmPostgreSQLnecessrioeditaroarquivopg_hba.conf liberandoacesso,umexemplo encontradonesteLINKepodeserdeajudanestescasos: http://pgdocptbr.sourceforge.net/pg80/clientauthentication.html#EXAMPLEPG HBA.CONF


Pg.8

III GuiadeRefer nciaEsta seo descreve os novos comandos e as novas funes introduzidas pela SQL LIB. O arquivo SQLLIB.CH contm as definiesde todos os comandos suportadospela RDD. Algo importantea ser mencionado, que tendo em vista que a SQL LIB foi projetada para ser de fcil utilizao e especialmente pensando nosusuriosque migram deoutras ferramentas parao nossoprojeto, muitos comandospossuemmaisdeumasintaxeemuitasfunespossuem aliasesvisandoagilizaroacessoea migraodecdigojexistente. Um exemplo tpico disto, o comando SQL CONNECT quepode ser acionado normalmente como:SQLCONNECTON'localhost' PORT3306 DATABASE"test" USER"root" PASSWORD'' LIB'MySQL'

No entanto, visando auxiliar aqueles usurios que estejam migrando de outras ferramentas, disponibilizamostambmuma sintaxeadicional paraestecomando:cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=jose" SQLCONNECTcConnINTOnMySQL

Basicamenteestasduaslinhasacimatmomesmoefeitoqueocomandoanteriormentepassado. Istoocorreparafacilitaramigraodecdigosjexistentesefacilitatambmaoprogramadorquepode selecionarqualmodo eleseadaptamelhorequalmaistilpara utilizaremseusaplicativos.Outroscomandosqueutilizamestamesmasintaxeso:SETPACKETSIZE,SETTRANSLATEentremuitosoutros. Semprequeistoocorrer,iremosdemonstrarambasassintaxes,relacionandoambasassintaxes.Istoocorrertantopara oscomandos,quantoparaasfunes demodoquevocpossadecidirqualsintaxedesejautilizar,lembrandosesempre dequeambososcomandos/funessomapeadosparaamesmafuncionalidade.

Aseoquesesegue,conteroscomandose funessuportadas pelaRDD.


Pg.9

COMANDOSA SQL LIB introduz diversos comandos novos ao programador, tanto para controle de conexes, gerenciamentodastabelasouaindaexecuodecomandosSQLdiretamentenoservidor.Naseoque se segue, listaremos todos os novos comandos introduzidos pela SQL LIB e listados no arquivo SQLLIB.CHqueacompanhaainstalaodaRDDporpadro.

1. SQLCONNECTONEstabilizaumaconexoumservidorSQL suportadopelaSQLLIBeretornaonmerodaconexo sebemsucedidoouzeroemcasodeerro. Sintaxe:SQLCONNECTON [PORT] [DATABASE] [USER] [PASSWORD] [OPTIONS] [] [INTO]

Onde:

Indica o nome ou o IP do micro qual voc deseja se conectar e em alguns casospodeserutilizadoapalavrachavelocalhostindicandoqueoservidorest instaladonamesmaCPUondeoaplicativoestsendoexecutado. o nmero da porta que deve ser utilizada para conexo ao servidor. Por exemplo, podemos citar que normalmente o MySQL est operando na porta 3306eoPostgreSQL na5432eassimpordiante.Esteparmetroopcionale serpreenchidocomovalorpadrodecadabancosenoforespecificado. onomedobancodedadosaoqualdevemosinicialmentenosconectar.Alguns servidores como o MySQL permitem que seja omitido este parmetro no comando de conexo, pois posteriormente podese selecionar um Database diferente logo aps a conexo estar estabelecida. No entanto, para outros servidorescomooPostgreSQLobrigatrioapassagemdesteparmetroeno permitidaaalteraodomesmoumavezjestabelecidaaconexo. o nome do usurio utilizado para autenticao no servidor. Este usurio j deveestarpreviamentecadastradonoservidorSQLedevepossuirprivilgiode acessoparaqueaconexosejaestabelecidacomsucesso. asenhautilizadaparaautenticarousurioespecificadonoparmetroanterior juntoaoservidor. umvaloropcionalconformeatabelaabaixo:SQL_NO_ERROR

Indica que quaisquer erros que ocorram durante o processo devem ser suprimidos. Consulte o valor de SQLERRORNO()parachecaraocorrnciadealgumerro. Oponomaisutilizada.

SQL_NO_WARNING


Pg.10

Identificaonomedodriverquevocdesejautilizarparaefetuarestaconexo.A SQLLIBsuporteatualmenteosseguintesdrivers:MYSQL

IndicaqueaSQLLIBdeveutilizarodrivernativopara MySQLparacuidardestaconexo. No entanto para que voc possa linkar o suporte MySQL noseuaplicativo,noesqueadeadicionar no inicodoseucdigofonteasseguinteslinhas:REQUESTSQLLIB REQUESTMYSQL

Feito isto, durante o processo de linkedio as funes necessriasseroincludasnoseuexecutvel.PGSQL

IndicaqueaSQLLIBdeveutilizarodrivernativopara PostgreSQL para gerenciar esta conexo. No incio do seuaplicativo,vocdeveincluirobrigatoriamente:REQUESTSQLLIB REQUESTPGSQL

Apelidos: PostgreSQL Postgres PostSQL

As duas linhas abaixo produzem o mesmo efeito do exemplo acima, pois chamam o driver do PostgreSQL porumdosseusapelidos:REQUESTSQLLIB REQUESTPostgreSQL

Isto inclui as funes necessrias para suporte PostgreSQLemseuexecutvel.

Especificaonomedeumavarivelqueirreceberonmerodaconexoatual, sebemsucedidoouzeroemcasodeerro.Casoavarivelnoexista,sercriada comovalorderetorno.

Se a conexo for efetuada com sucesso, ela tornase a conexo ativa. Consulte a funo SQLSETCONNECT()paramaioresdetalhessobreogerenciamentodeconexesdaSQLLIB. Exemplo:#include'sqllib.ch' REQUESTSQLLIB REQUESTMySQL /*IstoincluisuporteMySQLemnossoaplicativo*/ REQUESTPGSQL/*SuportePostgres*/ functionMain() SQLCONNECTON'localhost' PORT3306 DATABASE"test" USER"root" PASSWORD'' OPTIONSSQL_NO_ERROR LIB'MySQL' IFSQLErrorNO()>0 alert('Noconectou') else alert('Conexoestabelecidacomsucesso!')


Pg.11

endif

Consultetambm:SQLCONNECT(comStringsdeConexo) SQLDISCONNECT SQLSETCONNECT()

2. SQLCONNECT(comStr ingsdeConexo)A SQL LIB a partir da verso 1.0, disponibiliza uma forma modificada do comando SQL CONNECT com suporte Stringsde conexo. Nesta sintaxe, este comando processa uma string passada como argumento e estabiliza uma conexo ao servidor utilizando os parmetros contidos nestastring. Estecomandoretornaonmerodaconexosebemsucedidoouzeroemcasodeerro.Noteainda que esta funo no emite nenhum erro em caso de falha , sendo necessrio verificar SQLERRORNO()e SQLERRORMSG()paraaveriguaromotivoqueocasionouafalhanaconexo. Sintaxe:SQLCONNECT[INTO]

Onde:

Representa a string de conexo contendo os parmetros necessrios para conectarse ao servidor, bem como o nome do prprio driver RDD utilizado paragerenciarestaconexo. Todososparmetrosdestastringdeconexopossuemumoumaisapelidos,por exemplo, para especificar o nome de usurio voc poderia utilizar o termo usernameouusurioouaindauser. Atabelaabaixolistatodososparmetrosdisponveisparausoemumastringde conexoelistatambmosapelidos disponveisparacada parmetro. Note que a partir da verso 1.2, a SQL LIB novamente inova, possibilitando passar os parmetros dentro da string de conexo utilizando a lngua portuguesa ,oquecomcertezairfacilitaremmuitoasua utilizao. ParmetroUSERNAME

ApelidosUSUARIO,NOME, UID,USER,ID, USERID,USER NAME,NAME, LOGIN SENHA,PWD, PASS,PASSWRD BASEDEDADOS, BASEDEDADOS, DADOS,BANCODE DADOS,BANCO, DADOS,DTB,DB, DATA,BASE, PATH,DBQ

Descr io Especifica o nomedousurioutilizado paraautenticaonoservidorSQL.

PASSWORD

Senhaparaautenticao. Nome do banco de dados ao qual desejamosnosconectar.

DATABASE


Pg.12

DRIVER

RDD,DRV,SQL, LIB SERVER, SERVIDOR, CONECTAR,IP, CONECTA,HST PORTA,PRT,EM

Nome do driver interno da SQL LIB quedevegerenciarestaconexo. Nome do computador ou IP aonde a conexodeveserestabelecida.

HOST

PORT

Nmerodaportaquedeveserutilizada para conexo. Este parmetro quando no especificado, utilizar o valor padrodorespectivodriverqueaSQL LIB ir utilizar para gerenciar a conexo.

Nota: S no sei ao certo explicar por que alguns parmetros possuem tantos apelidos, mas acreditoquenoserporfaltadeumanomenclaturaapropriadaqueaconexodeixardeser estabelecida.=D

Almdosparmetrospassadosacima,aSQLLIBaceitatambmumparmetro adicional: o nome dodriver desejado, seguidodo IP onde a conexo deve ser efetuada. Este parmetro quando usado, deve ser o primeiro a ser passado na stringdeconexo,comomostraoexemploabaixo:cConn:=PostgreSQL=192.168.0.1usuario=postgres+ senha=postbanco=Demos SQLCONNECTcConnINTOnPostSQL

Especificaonomedeumavarivelqueirreceberonmerodaconexoatual, sebemsucedidoouzeroemcasodeerro.Casoavarivelnoexista,sercriada comovalor deretorno.

Se a conexo for efetuada com sucesso, ela tornase a conexo ativa. Consulte a funo SQLSETCONNECT()paramaioresdetalhessobreogerenciamentodeconexesdaSQLLIB. Eisumexemplocompletoqueefetuaaconexoem2servidoresdiferentesetestaseacomunicao foibemsucedida:#include'sqllib.ch' REQUESTSQLLIB REQUESTMySQL REQUESTPostgreSQL functionMain() cConn:="Driver=PostgreSQLServidor=192.168.0.1+ usuario=postgressenha=postbanco=Demos" SQLCONNECTcConnINTOnPostSQL /* *Houvealgumerronaconexao? */ IFSQLErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQLErrorMsg()) Return(.F.) ENDIF cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=jose"


Pg.13

SQLCONNECTcConnINTOnMySQL /* *Houvealgumerronaconexao? */ IFSQLErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQLErrorMsg()) Return(.F.) ENDIF

Este um recurso muito til quando se necessita determinar em tempo de execuo as configuraes do banco, do host e outrosparmetrosnecessriospara conexo, pois uma string utilizada como parmetro desdecomandoalgorelativamentesimplesepodeserarmazenadaemumarquivo.INI,emumavarivel deambienteparaserrecuperadaporGETENV()ouatmesmoemumsimplesDBF.

Consultetambm:SQLDISCONNECT SQLSETCONNECT()

3. SQLDISCONNECTFecha uma conexo aberta com o comando SQL CONNECT ou pelas funes SQLCONNECT()/SQLCONNPARSE() egravaquaisquertransaesqueaindaestiverempendentes.Este comandomapeadointernamenteparachamarSQLDISCONNECT(). Sintaxes:SQLDISCONNECT[FROM] SQLDISCONNECT[]

Onde:

Especificaonmerodaconexoquesedesejafinalizar. Quandoespecificado,indicaquetodasasconexesabertasdevemserfechadas. Seomitidosomenteaconexoatualfechada.

Tenhasempremuitocuidadoaofinalizarumaconexo,certifiquesedequenenhumatabelaest atualmente abertaeutilizandoestamesmaconexo. Pois istopoderiagerardiversoserrosno seuaplicativo,almde instabilidadeeGPFs.

Consultetambm:SQLCONNECT

4. SQLEXECUTEExecuta um comando SQL diretamente noservidore retorna. Esta funo nodeve ser utilizada

para enviar comandosqueretornemdadosdoservidor,utilizeocomandoUSESQLouafuno SQLARRAY()paraestafinalidade.Sintaxes:SQLEXECUTE[INTO][WITH[ARRAY]]

Onde:


Pg.14

EspecificaocomandoSQLqueserexecutadonoservidor. IndicaonmerodaconexoondeocomandoSQLdeveserexecutado. um lista de argumentos utilizados para prprocessar utilizando o PARSERinternodaSQLLIB,antesdeenvialoaoservidor. Utilize a palavrachave WITH ARRAY caso deseja utilizar um ARRAY ao invsdeuma normaldelistadeparmetros.

A partir da verso 1.3 da SQL LIB este comando no gerar nenhuma mensagem caso, tenha ocorridoalgumerroduranteaexecuode juntoaoservidor.Useovalorderetornopara testar se o comando foi executado com sucesso e consulte as funes SQLErrorMsg() e SQLErrorNO()para obteramensagemeonmerodoerrorespectivamentedaltimafalha. Exemplo1(semparmetros):cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=test" SQLCONNECTcConnINTOnMySQL SQLEXECUTEINSERTINTOCLIENTES(nome,salario)+ VALUES(JosMatias,2500.00)

Exemplo2(comlistadeparmetros):cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=test" SQLCONNECTcConnINTOnMySQL SQLEXECUTEINSERTINTOCLIENTES(nome,salario)VALUES($1,$2) WITHJoseMatias,2500.00

Exemplo3(utilizandoparmetrosdeumarray):cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=test" SQLCONNECTcConnINTOnMySQL SQLEXECUTEINSERTINTOCLIENTES(nome,salario)VALUES($1,$2) WITHARRAY{JoseMatias,2500.00}

Consultetambm:USESQL SQLEXECUTE() SQLARRAY() SQLPARSER()

5. SQLTRANSLATEPATHEspecifica o tipo de converso a ser aplicada no PATH dos arquivos passados para a SQL LIB. Nomes de arquivos DBFs e de ndices esto sujeitos alteraes por esta funo para facilitar a migraodesoftwaresantigos. Sintaxes:


Pg.15

SETTRANSLATEPATHTO SQLTRANSLATEPATHTO

Onde:

EspecificaotipodeconversoaplicadaaoPATHdeumarquivo. Parailustrarautilizaodestecomando,atabelaabaixoirlistarospossveis valoresparaedemonstraroresultadoquevocobteriaseutilizasseo comandoUSEC:\PROGRAMA\ARQUIVOS\DBF\ESTOQUE.DBF,vejacomoaSQL LIBirinterpretarestavalor,dependendodeSETTRANSLATE: Valor tpFileName

Descrioeexemplo Retorna apenas o nome do arquivo sem extenso. No comandoUSEacima,resultariaem"ESTOQUE",este ovalor padro daSQLLIB. Retornaopathdoarquivoprocessado massem extenso.NocomandoUSEacima,seriaomesmoque PROGRAMA_ARQUIVOS_DBF_ESTOQUE. Resultanonomedoarquivosempath,mascom extenso.Noexemploacima,seriaomesmoque ESTOQUE_DBF. Retornaopathdoarquivocompletoe comextenso. Noexemplodocomandouseresultariaem PROGRAMA_ARQUIVOS_DBF_ESTOQUE_DBF

tpFullPath

tpFullName

tpFullNamePath

Consultetambm:SQLTRANSLATECASE SQLParse()

6.SQLTRANSLATECASEEspecifica o tipodeconverso a ser aplicada no NOME dos arquivospassados para a SQL LIB. Nomes de arquivos DBFs e de ndices esto sujeitos alteraes por esta funo para facilitar a migraodesoftwaresantigos. Esta funo determina o tipo de converso (no caso de maisculas ou minsculas) que deve ser aplicadaaos osnomesdearquivospassadosparacomandoscomoUSEouSETINDEX.Istoajudaa converter todo o sistema utilizandose um nico comando, para o caso de haver vrios mdulos PRGs,comcomandosutilizandonomesdearquivoscomcaixaalta,baixaoumista. Porexemplo,casooservidorsejaLINUXeosnomesdastabelasestiverememletrasmaisculas,o servidor pode gerar um erro, dizendo que determinada tabela no existe, se o nome do arquivo passadonocoincidir exatamentecomonomeexistente. Sintaxes:SETTRANSLATECASETO SQLTRANSLATECASETO

Onde:


Pg.16

EspecificaotipodeconversoaplicadaaoNOME deumarquivo. Atabelalistatodos ospossveisvalorespara: Valor tcNone

Descr ioeexemplo Noefetuaconversoalgumaouseja,onome digitadoprocessadodomodocomodigitado. EsteopadrodaSQLLIB.

tcUpperCase tcLowerCase

Convertetodososcaracteresparaletrasmaisculas. Convertetodososcaracterespassadosparaletras minsculas.

Consultetambm:SQLTRANSLATEPATH SQLParse()

7.SQLCUSTOMINDEXESIndicaseaSQLLIBdevepermitirounoousodendicescustomizados. Sintaxe:SETCUSTOMINDEXES SQLCUSTOMINDEXES

Onde:

Permitequesejamcriadosndicescustomizadosquandonecessrio. Indicaqueapenasousodendicessimplespermitido.

OvalorpadroparaestecomandoOFF,parasemanteracompatibilidadecomversesanteriores da SQL LIB. Caso deseje utilizar ndices customizados, voc deve ativar esta opo com SET CUSTOMINDEXESON. ConsulteoapndiceAparaobtermaioresinformaesdetalhadassobrecomotrabalharcomndices naSQLLIB. Exemplo:demos\index.prg

8.SQLPACKETSIZEEspecificaaquantidadede registrosque devemserlidosdoservidorsemprequenecessrio.Ovalor padrodaSQLLIBtrazer 50registros porvez. Sintaxe:SQLPACKETSIZE[TO]


Pg.17

SETPACKETSIZE[TO]

Onde:

Representaumnmeromaiorque2e de preferncia menorque1000.

A SQL LIB possui um mecanismo de paginao que puxa do servidor apenas os registros necessrios,mesmoqueatabelatenhamilharesderegistros.Istoasseguraummelhordesempenho viaredeegarantequeaquantidadedememriaRAMdisponvelnoseusistemasejasuficientepara execuodoseusoftware.Estecomandonoafetaastabelasjseencontramabertasnosistema,nemseaplica tabelasabertas comocomandoUSESQL.ParatabelasquejforamabertascomocomandoUSEno comocomandoUSESQL utilizeocomandoSQLCURRENTPACKETSIZE.

Exemplo:SETPACKETSIZETO25 /*L25registrosporvez*/ USEc:\test\table.dbfNEWVIA'PGSQL'

Consultetambm:SQLCURRENTPACKETSIZE SQLPACKETSIZE()

9.SQLCURRENTPACKETSIZEAlteraoPACKETSIZE deum arquivojabertonosistema,estandoele noALIAS()atual. Sintaxe:SQLCURRENTPACKETSIZE[TO] SETCURRENTPACKETSIZE[TO]

Onde:

Representaumnmeromaiorque2e de preferncia menorque1000.

Exemplo:SETPACKETSIZETO25 /*L25registrosporvez*/ USEc:\test\table.dbfNEWVIA'PGSQL' SETCURRENTPACKETSIZETO50 /*Definequedeveler50porvez*/

Consultetambm:SQLPACKETSIZE SQLPACKETSIZE()

10. SQLFULLDELETEDeterminaseumregistrodeveserrealmente deletadodatabelaouapenasmarcadopararemoo.O padro daSQLLIBparaestecomando OFF. Sintaxe:SQLFULLDELETE


Pg.18

Onde:

Faz com que o registro seja realmente deletado e suas informaes sejam descartadasdobancodedados.OcomandoRECALLnopoderserutilizado

pararecuperarestesdadosposteriormente.

Apenasmarcaoregistrocomodeletado,masoregistrocontinuaapermanecer natabelaatqueumRECALLsejadadoouelesejacompletamenteremovido pelocomandoPACK.

Consultetambm:SQL_FULLDELETE()

11. SQLFILTERDefineumfiltroparaatabelaatual,quedeverserprocessadonoladodoservidor.Ousodestetipo dendicemaisrecomendadodoqueousodeSETFILTER. Sintaxe:SQLFILTERTO[]

Onde:

aexpressoquedefinirofiltroativoparaatabelaatual.Seumastringvazia forpassadacomoparmetro,ofiltroatualserremovido.

SesomenteSQLFILTERTO forespecificadosemexpressonenhuma,ofiltroatualserremovido. Exemplo:demos\filtros.prg

Consultetambm:SQLFILTER()

12. COPYTABLECopiaocontedodeuma tabelaexistenteparaumanovatabelaviaSQL. Sintaxe:COPYTABLETO

Onde:

onomedatabelaatual,existentenoservidor. Especifica o nome da nova tabela que ser criada com base nos dados e na estruturadatabelaoriginal.

Notaimportante:estafunocopia apenas aestruturaeosdadosparaanovatabelanoincluindo triggers,viewseoutrosobjetosvinculadostabelaoriginal.


Pg.19

Consultetambm:RENAMETABLE DELETETABLE

13. DELETETABLEApagauma tabela existente no servidor SQL, eliminando todosos dados e a prpria estruturada tabela. Sintaxes:DELETETABLE DROP TABLE

Onde:

onomedatabelaqueserremovidadoservidor.

Ateno: Estecomandonoestsujeitoa um ROLLBACK.Consultetambm:DELETEINDEX RENAMETABLE COPYTABLE

14. DELETEINDEXDeletaumoumaisndicesdobancodedados. Sintaxe:DELETEINDEX DROP INDEX

Onde:

o nome do ndice que se deseja excluir do servidor. Voc pode utilizar um asterisco"*"comocuringaparaexcluirmaisdeumndicecomestecomando.

Ateno: Estecomandonoestsujeitoa umROLLBACK.Consultetambm:DELETETABLE

15. RENAMETABLEAlteraonomedeumatabelaexistentenoservidor. Sintaxe:


Pg.20

RENAMETABLETO

Onde:

onomeatualdatabelaexistentenoservidor onovonomequeserdadotabela.

Consultetambm:RENAMEINDEX

16. RENAMEINDEXRenomeiaum ndiceexistentenoservidorparaoutronome. Sintaxe:RENAMEINDEXTO

Onde:

onomeatualdondiceexistentenoservidor onovonomequeserdadoestendice.

Consultetambm:RENAMETABLE

17. STARTTRANSACTIONInicia uma nova transao em todas as conexes atualmente abertase incrementa o contador de transaesem+1.Estecomandopossuioutrosapelidosconformeexibidonasintaxeabaixo: Sintaxes:STARTTRANSACTION BEGINTRANSACTION TRANSACTIONSTART

OcomandoSTARTTRANSACTIONiniciaumnovoblocodetransaonoservidorSQL.Todos oscomandosqueforemexecutadosdentrodestebloco,entodeverosergravadoscom COMMITou descartadoscomocomandoROLLBACK. Embora a funo SQL_TRANSCOUNT() retorne a quantidade de transaes abertas at o momento,transaesaninhadasnososuportadaspelaSQLLIB. importante mencionar neste ponto, que alguns comandos e instrues SQL no podem ser desfeitos.Istoocorreporquenosepoderefetuarum ROLLBACKdealgumasinstruesSQL.Em geral, estas incluem instrues DDL (data definition language), como aquelas que criam ou removembancodedados,ouaquelasquecriam,apagamoualteramtabelas.


Pg.21

Voc pode desejar projetar as suas transaes para no incluir estas instrues. Se voc executar umainstruodaqualnosepodefazerROLLBACKemumatransao,eentooutrainstrues falhar posteriormente, o efeito total da transao no pode ser desfeito usando uma instruo ROLLBACK. Os seguintes comandos finalizam uma transao implicitamente (como se voc tivesse feito um COMMIT depoisdeexecutarocomando): ComandoALTERTABLE DROPDATABASE LOADMASTERDATA SETAUTOCOMMIT=1

ComandoBEGIN DROPINDEX LOCKTABLES STARTTRANSACTION

ComandoCREATEINDEX DROPTABLE RENAMETABLE TRUNCATE

Exemplo:SELECTTEST *EstecomandoiniciaumatransaoSQL. BEGINTRANSACTION WHILE!Eof() SELECTTESTSQL APPENDBLANK REPLACECODWITHTEST>COD REPLACENOMEWITHTEST>NOME REPLACEANIVWITHTEST>ANIV REPLACEBLOQWITHTEST>BLOQ REPLACELIMCWITHTEST>LIMC REPLACEULTCWITHTEST>ULTC REPLACEATIVWITHTEST>ATIV SELECTTEST SKIP End * *Gravaosdadoseterminaatransao. * ENDTRANSACTION

OutrosExemplos:demos\simples.prg demos\AppendFrom.prg

Consultetambm:ENDTRANSACTION COMMITTRANSACTION ROLLBACKTRANSACTION SQL_TRANSCOUNT()

18. ENDTRANSACTION


Pg.22

Finaliza um bloco de transao aberto com START TRANSACTION, envia um COMMIT das alteraespendentes(sehouver)edecrementaocontadordetransaesativasem 1. Sintaxe:ENDTRANSACTION

Estecomando antes definalizar atransao,enviaumCOMMITTRANSACTION explcitoparaevitara percadedados. Poristo,casodesejecancelarumatransao,envieumROLLBACKantesde finalizaratransaocomENDTRANSACTION. Consultetambm:COMMITTRANSACTION ROLLBACKTRANSACTION BEGINTRANSACTION

19. COMMITTRANSACTIONGravatodasasalteraesfeitasdentrodeumblocodetransaes,masnoafinaliza. Sintaxes:COMMITTRANSACTION SQLCOMMIT

Consultetambm:ROLLBACKTRANSACTION BEGINTRANSACTION ENDTRANSACTION

20. ROLLBACKTRANSACTIONDescartatodasasalteraesefetuadasnoblocodetransaoatualemtodasastabelasenvolvidas, masnofinalizaoblocodetransaes. Sintaxe:ROLLBACKTRANSACTION SQLROLLBACK

AoseefetuarumROLLBACKnumblocodetransao,todasastabelasenvolvidasnestaoperao teroosseusregistrosatualizadoscomGOTORECNO(),parasecertificardequeosdadosatuais soosmaisrecentesdo bancodedados. Consultetambm:BEGINTRANSACTION COMMITTRANSACTION

21. CLEARINDEXESSQLLIBRDDparaHarbour&xHarbour,20032006porVailtonRenato [email protected].

Pg.23

Limpatodososndicesanexadostabelaatualou umaoutratabelaespecficanoservidor. Sintaxe:CLEARINDEXES[FOR ] CLEARINDEXES[FROM]

Onde:

o nome da tabela cujo os ndices devem ser deletados. Caso seja omitido, todososndicesdatabelaatualserodeletados.

Quando se indexa um campo utilizandose a SQL LIB, as informaes sobre aquele ndice tais como tamanho, expresso da chave, flag indicando se ele um ndice composto e muitas outras informaessogravadasnumatabeladesistemachamadaSQL$INDEXES. Emalgunscasos,asinformaesnestatabelapodemnosermaisteiscomoporexemplo, quandovamosreindexaratabelaatual.DesdemodovocdevechamarCLEARINDEXES,para garantirquetodasasinformaesnosistemasoconsistentes. Consultetambm:DELETEINDEX

22. SELECTSCHEMAInforma em qual SCHEMA deve ser utilizado para procura e acesso as tabelas no servidor ou opcionalmenteinformaemqualSCHEMAestoarmazenadosastabelasdesistemadaSQLLIB. Sintaxes:SELECTSCHEMA SELECTSYSTEMSCHEMA

Onde:

onomedoSCHEMAquedeveserconfiguradoparapesquisanoservidor.

OsuporteSCHEMAsnocaractersticade todososservidores.Nomomentoemqueeste documentoestavasendoredigido,oMySQLnopossuaaindaestacaracterstica(versoatual 5.0.18). JcomPostgreSQLestecomandomuitotil,poismudaoSCHEMAativo.Vocpodeobtero nomedoSCHEMAatualapenaschamandoafunoSQLSCHEMA()semparmetros. Note que temos dois comandos para manipulao de SCHEMAS, a primeira sintaxa para a TABELA individualmente aberta com USE. A segunda funo utilizada pela SQL LIB para acessarastabelasdosistema,taiscomoSQL$INDEXESeoutrasquepossamsurgir. OcomandoUSESQLeafunoSQLARRAY()nosoafetadosporestafuno,poisnestescasos ocomandoSQLdeveserpassadojnoformatofinalparaexecuo. Exemplo:cConn:="PostgreSQL=192.168.0.1usuario=postsenha=postbanco=Demos" SQLCONNECTcConnINTOnPostSQL


Pg.24

SELECTSCHEMApublic USEvendedoresNEWVIAPGSQL //Abreatabelapublic.vendedores SELECTSCHEMAvendas USEpedidosNEWVIAPGSQL

//Abreatabelavendas.pedidos

Consultetambm:SQLSCHEMA() SQLSYSTEMSCHEMA()

23. USEOcomandoUSEporpadronoClippereporextensonoHarbour/xHarbour,abreumarquivoDBF nareaatualeopcionalmenteos seundices.ComaSQLLIB estecomandomantm suasintaxe original, mas agora importante(especialmente parao Clippeiros) a ateno alguns parametros opcionaisdocomandoUSE. SuasintaxepadronoClipper5.3:USE [VIA] [ALIAS] [] [] [] [INDEX[,]]

OpontoemdestaquequequeremosdaraquiparaoparmetroVIA.Estaclusulaidentificaparaa RTL(runtimelibrary)docompilador,sobrequalonomedoRDDquevocdesejautilizarpara gerenciarnosomenteaaberturadestearquivo,mastambmseuscomandosdeleituraegravao. Sendoassim,semprequeformosutilizaraSQLLIBparaabrirumatabelanoservidorprecisamos informar o nome do RDD valor na clausula VIA, indicando o driver que ir manipular estas informaesparans.Vejadoisexemplosabaixo:usec:\test\table.dbfaliasTestSQLnewviaMySQL usetest.dbfaliasTestviaPGSQLnew

Nos exemplos acima, indicamos no primeiro caso que devese utilizar a SQLLIB para abrir o arquivo,utilizandoseodriverparaMySQLenosegundousamosodriverparaPostgreSQL. Neste ponto a mgica da SQL LIB comea a funcionar. O ponto de maior dificuldade e compreensoimediata paraos novos, que a SQL LIB no vaiprocurar um arquivo no seu HD chamadoc:\test\table.dbf conformeespecificadonalinhadecomando. Aoinvsdisto,aSQLLIBchecaseexisteuma conexoativaparaumservidorMySQL.Sehouver, elavaibuscarporumatabela nesteservidor.Onomedatabelapodemudarconformeosvaloresdos comandosSETTRANSLATEPATHe SQLTRANSLATECASE. Omesmoocorrecomosegundoexemplo,pormdestavez,odriverutilizadoodoPostgreSQL.A tabelaabaixolistaosnomesdosRDDsintroduzidospelaSQLLIBemostraaqualservidorsecada umseraplicam: RDD MySQL Servidor Supor tado MySQL,verso4.1.7ousuperior.


Pg.25

PGSQL

PostgreSQLverso8.0ousuperior.

Podemos evitar o trabalho de especificar a clusula VIA seguida do nome de um RDD em cada comandoUSEqueformosexecutar.OsegredoparaistoqueseVIAforomitido,ovalorpadro paraestaclusulaonomedoRDDqueestiverdefinidoemRDDSETDEFAULT(). PorpadroodriverinicialdefinidocomoDBFNTX,mas podemosalterlo nossofavor eisum exemplocompleto ecomentado:?'TestRDDon'+SQLVersion()+'&'+Version() /* *UtilizamosestecommandoparaseconectaraoservidorSQLviaTCP/IP */ SQLCONNECTON'localhost'//NomedaestaoouIP PORT3306//Numerodaporta DATABASE'test' USER'root' PASSWORD'' OPTIONSSQL_NO_WARNING LIB'MySQL' /* *Houvealgumerronaconexao? */ IFSQLErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQLErrorMsg()) QUIT ENDIF /* *Aquiabrimosoarquivo.DBFlocal,vejaquenoespecificamos *aclausulaVIA,forandoeleaabriropadro. */ USEtest.dbfALIASTestNEW Struct:=dbStruct() CLOSEALL /* *Ocomandoaseguir,dizquetodososarquivosabertoscom *USE,COPYouqualquercomandodemanipulaodedados,deve *usarodriverparaMySQLdaSQLLIB: */ rddSetDefault(mysql) /* *AgoravamosCRIARumatabelanoservidorMySQLcomamesma *estruturadoarquivo.DBFlocal: */ dbCreate('test_table.dbf',Struct) /* *AbreoarquivoremotamenteviaMySQL,poisagoraopadroparaVIA *senoespecificadoMySQL. */ USEtest_tableALIASTestSQLNEW /* *Agoraabrimosoaquivo.DBFlocalmenteeprecisamosabrilocomo *DBFexplicitamente,poismudamosovalordeRDDSETDEFAULT() */ USEtest.dbfALIASTestNEWVIADBFNTX//ouDBFCDXsepreferir ...


Pg.26

Sendoassimcompoucosajustes,possvelmigrarumsistemainteiroparaSQL.Desdeque faamosumbomusodasrotinasadequadasdaSQLLIB. Consultetambm:SETTRANSLATEPATH SQLTRANSLATECASE USESQL

24. USESQL/USEASExecutaumcomandoSQLnoservidoreobtmoresultadodaconsultaabrindoocomoumtabela somenteparaleitura. Sintaxerecomendada :USESQL [VIA] [ALIAS] [INTO] [NEW] [EXCLUSIVE] [SHARED] [READONLY]

Sintaxealternativa:USE AS [INTO] [VIA] [ALIAS] [NEW] [SHARED] [EXCLUSIVE] [READONLY] [C1LOGICAL] [OVERWRITE] [RECISION] [SCROLLABLE] [PERMANENT]

OndeamaioriadosparmetrosmantmaformatradicionaldocomandoUSE,excetopor alguns novos:

ocomandoSQLaserexecutadonoservidor o numero da conexo especfica para utilizada para enviar o comando SQL paraoservidor onomedoRDDqueiroretornodestecomandoSQL.Consulteocomando USEparaobterumatabelacomtodososnomesdeRDDsdisponveis.

OcomandoUSESQL importanteparaexecutarcomandosnoladodoservidorqueretornemdados especficos,porexemplo:dadosparaumrelatrio,umalistadeusuriosconectadosou obterovalor de retornode umaStoredProcedure.


Pg.27

Notaimportante:Desdeaverso1.4da SQLLIBRDD,ascolunasSQL_ROWIDe SQL_DELETEDsetornamvisveisdentroeumUSESQLouSQLARRAY()edeste modopodemserconsultadascomoqualqueroutrocamponormaldatabela. ElediferedocomandoSQLEXECUTEpois pode processar osvaloresderetornodocomandoSQL ediferentementedeSQLARRAY(),estecomando abre oresultadodocomandocomoumALIAS() vlido. Exemplo:cSQL:="showfullcolumnsfromtest_table" *Abreocomandoepuxaosdadoscomosomenteleitura USESQL(cSQL)ALIASTempVIAMySQL /* *ExibimososdadosdoresultadoatualizadosnumDBEDIT */ cls SETCOLORTOW+/B @5,02to24,77doub DBEdit(6,3,23,76)

Consultetambm:DEMOS\USE_SQL1.PRG DEMOS\USE_SQL2.PRG SQLARRAY()


Pg.28

IVFUNESASQLLIB compostaporumagrande variedadedefunes,querealizamdiversastarefastantodo lado do servidor SQL, como no lado do cliente. Esta seo ir descrever as funes disponveis e algumas funes interessantes da API de baixo nvel da SQL LIB, lembrando que as constantes utilizadasporestasfunesestolistadasnoarquivoSQLLIB.CHqueacompanhaainstalao.

1. SQLPARSESTYLE()RetornaeopcionalmentealteraotipodeconversoaseraplicadanoPATHdosarquivospassados para a SQL LIB. O comando SQL TRANSLATE PATH mapeado internamente como uma chamadaestafuno. Sintaxe:SQLParseStyle([])>nOldStyle

Onde:

oparmetroopcional que identifica o novo estilo a ser aplicado nas futuras conversesefetuadaspelaSQLLIB. ovaloratualdeSQLPARSESTYLE()

Paraobterumalistacompletados valorespara, verifique areferncia ao comandoSQL TRANSLATEPATHnesteguia. Exemplo:SQLParseStyle(tpFullNamePath)

Consultetambm:SQLTRANSLATEPATH

2. SQLPARSECASE()Retorna e opcionalmente altera o tipo de converso a ser aplicada aos NOMES dos arquivos passados para a SQL LIB. O comando SQLTRANSLATE CASE mapeado internamente como umachamadaestafuno. Sintaxe:SQLParseCase(nStyle)>nOldStyle

Onde:

oparmetroopcional que identifica o novo estilo a ser aplicado nas futuras conversesefetuadaspelaSQLLIB. ovaloratualdeSQLPARSECASE()

Paraobterumalistacompletadosvaloresparaeumaexplicaomaisdetalhada,verifique arefernciaaocomandoSQLTRANSLATECASEnesteguia.


Pg.29

Exemplo:SQLParseCase(tcLowerCase)

Consultetambm:SQLTRANSLATECASE

3. SQLPARSE()Converteonomedearquivopassadocomoargumento,aplicandoasconfiguraesdefinidaspelas funesSQLPARSESTYLEeSQLPARSECASE. Sintaxe:SQLParse(,[])>cResult

Onde:

astringcontendoonomedoarquivoaserconvertido. umparmetroopcionalqueindicaotipodeconversoaseraplicada.Seno forespecificadoovalordeSQLPARSESTYLE()serassumidocomopadro. onomedoarquivoespecificadoemconvertidoeformatado.

Exemplo:#include'sqllib.ch' arq=C:\PROGRAMA\NETPLUS\DBF\NETEST.DBF /* *PoderamosutilizarocomandoSQLTRANSLATEPATH/CASE,masvamos *passarosegundoparmetroparailustrarcomofunciona. */ ?SQLPARSE(arq,tpFileName )//=>NETEST(padrodaSQLLIB) ?SQLPARSE(arq,tpFullName)//=>NETEST_DBF ?SQLPARSE(arq,tpFullPath)//=>PROGRAMA_NETPLUS_DBF_NETEST ?SQLPARSE(arq,tpFullNamePath)//=>PROGRAMA_NETPLUS_DBF_NETEST_DBF quit

Consultetambm:SQLPARSESTYLE() SQLPARSECASE()

4. SQLCONNECT()EstabilizaumaconexoumservidorSQL suportadopelaSQLLIBeretornaonmerodaconexo sebemsucedidoouzeroemcasodeerro. Sintaxe:


Pg.30

SQLConnect(,[],[],[], ,[],)>nHandle

Onde:

onomedocomputadorouIPaoqualdeveserestabelecidaaconexo. Nmerodaportaparacomunicaocom oservidor,esteparmetroopcionale senoforespecificadoopadrodobancoserassumido. o nomedo Database aoqual devemos nos conectar. Alguns drivers comoo MySQL suportam que este parmetro seja omitido, j para PostgreSQL obrigatrio. Nomedousurioparaautenticao. Senhadousurioparaautenticao. umvaloropcionalquepodealteraromododecomportamentodaconexoem casodeerro. Identificaonomedodriverquevocdesejautilizarparaefetuarestaconexo. onumerodohandledestaconexosebemsucedidoouzeroindicandoerro.

Para uma lista completa de valores para o parmetro e tambm para , consulteocomando SQLCONNECTON neste guia.Seaconexoforestabelecidacomsucesso, estasetornaraconexoativa. Exemplo:#include'sqllib.ch' SQLConnect(localhost,3306,test,root,, SQL_NO_WARNING,MySQL) /* *Houvealgumerronaconexao? */ IFSQLErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQLErrorMsg()) Return(.F.) ENDIF

Consultetambm:SQLCONNECTON SQLSETCONNECT()

5. SQLCONNPARSE()Estabilizauma conexo um servidor SQLutilizando os parmetros passados por umastringde conexoeretornaum nmeromaiorquezerosebemsucedidoouzeroemcasodeerro. Sintaxe:


Pg.31

SQLConnParse()>nHandle

Onde:

Representa a string de conexo contendo os parmetros necessrios para conectarse ao servidor, bem como o nome do prprio driver RDD utilizado paragerenciarestaconexo. onumerodestaconexosebemsucedidoouzeroindicandoerro.

Estafunonogeranenhumerrooumensagemdealertaemcasodefalha,seacomunicaofor estabelecida com sucesso ela se tornar a conexo ativa. Consulte SQLERRORNO() ou SQLERRORMSG() para obter detalhes sobre o ltimo erro ocorrido e tambm a funo SQLSETCONNECT()paramaioresdetalhessobreogerenciamentodeconexesdaSQLLIB. Paraumaconsideraodetalhadasobrequaisparmetrossopermitidosdentrode, consulte a explanao pormenorizada do comando SQL CONNECT (com Strings de Conexo) nesteguia. Exemplo:cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=jose" nConn:=SQLConnParse(cConn) /* *Houvealgumerronaconexao? */ IFSQLErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQLErrorMsg()) Return(.F.) ENDIF

Consultetambm:SQLCONNECT(comStringsdeConexo) SQLSETCONNECT()

6. SQLDISCONNECT()Fecha uma conexo aberta com o comando SQL CONNECT ou pelas funes SQLCONNECT() e SQLCONNPARSE() e grava quaisquer transaes que ainda estiverem pendentes. O comando SQL DISCONNECTmapeadoparaestafuno. Sintaxes:SQLDisconnect([]) >lSuccess SQLDisconnect([]) >lSuccess

Onde:

Especifica o nmeroda conexoque se deseja finalizar, se omitido aconexo atualserfechada.


Pg.32

Se um valor lgico for passado como parmetro, SQLDISCONNECT fechar todasasconexesabertasseforverdadeira. um valor lgico, indicando se a conexo ou conexes foram fechadas com sucesso.

lSuccess

No necessrio finalizar todas as conexes por ocasio da sada do seu aplicativo. A SQL LIB finalizaautomaticamenteeenviaumCOMMITtodasasconexesabertas. Exemplo:Closeall SQLDisconnect(.T.) quit

Consultetambm:SQLCONNECT()

7. SQLGETCONNECTION()RetornaoHANDLEdaconexoatualemusopelaSQLLIBoupesquisaporumaconexovlida para o RDD solicitado. Esta funo possui outros nomes como SQLGETCONNECT() e SQLGETCONN(). Sintaxe:SQLGETCONNECTION([])>nHandle

Onde:

uma string que identifica o nome do RDD a ser pesquisado na tabela de conexes. onmerodaconexoouzerosenadasemelhanteforencontrado.

nHandle

Se foromitido, esta funo retorna o nmerodaconexo atualmente em uso.Caso contrrio,elapesquisadentrodetodasasconexesjestabelecidaseregistradasinternamentepela SQLLIB,procurandoa primeiraconexobemsucedidaparaodriversolicitado. Exemplo:#include'sqllib.ch' cConn:="Driver=PostgreSQLServidor=192.168.0.1+ "usuario=postgressenha=postbanco=Demosporta=5432" SQLCONNECTcConnINTOnPostSQL cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=jose" SQLCONNECTcConnINTOnMySQL /* *OcomandoSQLCONNECT,efetuaumaconexoeregistraacomoativa. *Sendoassim,ocomandoabaixoretornarovalordenMySQL: */


Pg.33

?SQLGETCONNECTION() //RetornaomesmovalordenMySQL ?SQLGETCONNECTION("POSTGRESQL")//RetornaomesmovalordenPostSQL ?SQLGETCONNECTION("MYSQL")//RetornaomesmovalordenMySQL ?

Consultetambm:SQLSETCONNECTION() SQLGETCONNECTIONS()

8. SQLSETCONNECTION()AlteraonmerodaconexoatualmenteemusopelaSQLLIB.Estafunopossuioutrosnomes comoSQLSETCONNECT()e SQLSETCONN(). Sintaxe:SQLSETCONNECTION()>lSuccess

Onde: lSuccess

onmeroda novaconexoquedeverserdefinidacomoativa. umvalorderetornolgicoindicandoseaalteraofoiefetuadacomsucesso.

Exemplo:/* *Nesteexemploiremosestabelecerduasconexesedemonstrarouso *dafunoSQLSETCONNECTION(): */ cConn:="Driver=PostgreSQLServidor=192.168.0.1"+ "usuario=postgressenha=postbanco=Demosporta=5432" SQLCONNECTcConnINTOnPostSQL cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=jose" SQLCONNECTcConnINTOnMySQL /* *Abrimosoarquivoutilizandoaconexoatual(quefoiaultima *serefetuadanestecaso) */ USEestoqueNEWVIAMySQL /* *AgorairemosselecionaraconexodoPostgreSQLeabriruma *tabelanestaconexo. */ SQLSETCONNECTION(nPostSQL) USEclientesNEWVIAPGSQL ....

Consultetambm:SQLGETCONNECTION()


Pg.34

9. SQLGETCONNECTIONS()RetornaumARRAYcontendoinformaessobre todasasconexesativasregistradaspelaSQL LIB. Sintaxe:SQLGetConnections()>aResult

Onde:

um array multidimensional contendo informaes sobre as conexes ativas registradaspelaSQLLIB.

OarquivoSQLLIB.CHdefineasseguintesconstantesparaoarrayretornadoporestafuno: ConstanteSQL_CONN_HANDLE SQL_CONN_RDD SQL_CONN_HOST SQL_CONN_PORT SQL_CONN_DB SQL_CONN_USER SQL_CONN_PASSWORD SQL_CONN_FLAGS SQL_CONN_SYSTEMID

Descrio Identificaohandledaconexo NomedoRDDquegerenciaestaconexo Nomedohostaoqualestaconexoestconectada Nmerodaportautilizadaparacomunicao NomedoDatabase originalmenteconectado Nomedousurioutilizadoparaautenticao Senhausadaparaautenticaraconexo Flagsopcionaisutilizadosparaestabeleceraconexo umvalornumricointernodaSQLLIBqueidentificaoSYSTEM IDdodriverutilizadoparagerenciarestaconexo.

Exemplo:#include'sqllib.ch' aList:=SQLGetConnections() FORI:=1TOLen(aList) Conn:=aList[i] ?Usurio,Conn[SQL_CONN_USER],conectadoem, Conn[SQL_CONN_HOST],via,Conn[SQL_CONN_RDD], naconexo,Conn[SQL_CONN_HANDLE] End

Consultetambm:SQLGETCONNECTIONINFO()


Pg.35

10. SQLGETCONNECTIONINFO()Retornaumarraycontendoinformaessobreaconexopassadacomoargumento. Sintaxes:SQLGetConnectionInfo([])>aInfo SQLGetConnectionInfo() >aInfo

Onde:

onmerodaconexoquesedesejaobterinformaes.Seesteargumentofor omitidoaconexoativaserassumida. Se o argumento passado como parmetro for uma expresso caracter, deveconteronomedodriverRDDespecficoparapesquisa. Nestecasoaprimeiraconexobemsucedida,quepossuaoRDDsolicitadoser processada.

aInfo

um array multidimensionalcomas informaes da conexo ou NIL se nada forencontrado.

EstearrayderetornopossuiamesmaestruturaindividualdeSQLGETCONNECTIONS(). Exemplo:#include'sqllib.ch' Conn:=SQLGetConnectionInfo(nConn) ?Usurio,Conn[SQL_CONN_USER],conectadoem, Conn[SQL_CONN_HOST],via,Conn[SQL_CONN_RDD], naconexo,Conn[SQL_CONN_HANDLE]

Consultetambm:SQLGETCONNECTIONS()

11. SQLGETRDDNAME()RecebecomoparmetroonumerodaconexoeretornaonomedodriverinternodaSQLLIBque estgerenciandoestaconexo. Sintaxe:SQLGetRddName([])>cRddName

Onde:

onmerodaconexoquesedesejaobterinformaes.Seesteargumentofor omitidoaconexoativaserassumida. onomedodriverinternodaSQLLIBqueestgerenciandoestaconexo.


Pg.36

ParaumatabelaabertacomPostgreSQLporexemplo,estafunoretornarPGSQL,jparauma conexoMySQLretornarMYSQLeassimpordiante. Consultetambm:SQLGetConnectionInfo()

12. SQLERRORMSG()Retornaumastringrepresentandoaltimamensagemdeerro obtida(sehouver) duranteuma operaointernadaSQLLIB. Sintaxe:SQLErrorMsg()>cMsg

Onde:

Representaastringcontendoaltimamensagemdeerrogerada.

Vejaumexemplodetalhadoem SQLERRORNO(). Consultetambm:SQLERRORNO()

13. SQLERRORNO()Retornaonmerodoltimoerro(sehouver)duranteumaoperaointernadaSQLLIB. Sintaxe:SQLErrorNo()>nError

Onde:

onmerodoltimoerroocorridoouzeroemcasodesucesso.

Exemplo:cConn:="Driver=PostgreSQLServidor=192.168.0.1"+ "usuario=postgressenha=postbanco=Demosporta=5432" SQLCONNECTcConnINTOnPostSQL /* *Houvealgumerronaconexao? */ IFSQL_ErrorNO()>0 Alert("Nofoipossvelconectaraobancodedados!"+ "Informeestamensagemaosuporte:"+ SQL_ErrorMsg()) Return(.F.) ENDIF

Consultetambm:SQLErrorMsg()


Pg.37

14. SQLPACKETSIZE()Especifica a quantidade de registros que devem ser lidos do servidor sempre que necessrio. O comandoSQLPACKETSIZEeSQLCURRENTPACKETSIZEsomapeadosinternamentepara chamarestafuno. Sintaxe:SQLPacketSize([],[nOldSize

Onde:

onovovalorindicandoquantosregistrosdevemserlidos. umvalorlgicoindicandoseaplicaseapenasatabelaatual.

Consultetambm:SQLPACKETSIZE

15. SQLEXECUTE()ExecutaumcomandoSQLdiretamente noservidoreretorna verdadeirooufalsoindicandoxito. Outrosapelidos queestafunopossui:SQLEXEC()eSQLLIB_EXECSQL(). Sintaxe:SQLExecute(,[],[])>lResult

Onde:

astringcontendoocomandoSQLaserexecutado. umarraycomumalistadeargumentosutilizadosparaprprocessar utilizandooPARSERinternodaSQLLIB,antesdeenvialoaoservidor. IndicaonmerodaconexoondeocomandoSQLdeveserexecutado. um valor de retorno lgico indicando verdadeiroou falso se o comando foi executadocomsucesso.

lResult

Estafunonodeveserutilizadaparaenviarcomandosqueretornemdadosdoservidor,taiscomo o comando SELECT ou SHOW. Nestes casos, utilize o comando USE SQL ou ainda a funo SQLARRAY()queso prpriasparaestafinalidade. Apartirdaverso1.3daSQLLIBestafunonogerarnenhumamensagemcaso,tenhaocorrido algum erro durante a execuo de no servidor. Use o valorde retorno para testar se o comandofoiexecutado comsucessoeconsulteasfunesSQLErrorMsg() e SQLErrorNO() para obteramensagemeonmerodoerrorespectivamentedaltimafalha. Exemplo:SETDATETOBRIT


Pg.38

cConn:="Driver=MySQLip=192.168.0.1usuario=rootbanco=test" SQLCONNECTcConnINTOnMySQL SQLExecute(INSERTINTOCLIENTES(nome,salario,aniv)VALUES($1,$2,$3), {JoseMatias,2500.00,CTOD(10/05/1965)},nMySQL)

Consultetambm:SQLARRAY() SQLPARSER() USESQL ApndiceCTrabalhandocomoPARSERSQLinternodaSQLLIB

16. SQLARRAY()Envia um comando SQL direto ao servidor e obtm o valor de retorno armazenandoo em um ARRAY. Esta funo s deve ser utilizada com comandos SQL que retornem dados, tais como SELECT,SHOW,EXPLAINentreoutros. Sintaxe:SQLArray(,[],[], [],[])>aResult

Onde:

EspecificaocomandoSQLqueserexecutadonoservidor. um lista de argumentos opcionais utilizados para prprocessar utilizando o PARSER interno da SQL LIB, antes de enviar o comando ao servidor. IndicaonmerodaconexoondeocomandoSQLdeveserexecutado. um array opcional que se especificado, ser preenchido com os nomes dos camposretornadosnaconsultaefetuada. Porexemplo,emumcomandoSELECTNOME,FONEFROMCLIENTES, estearrayconteriadoisvalores:{NOME,FONE}

um valor numrico interno da SQL LIB que identifica o SYSTEM ID do driverutilizadoparagerenciarestaconexo. Especificar este parmetro acelera a execuo do comando SQL quando h muitas conexes efetuadas ao mesmo tempo, pois a SQL LIB no necessita pesquisarinternamenteparaaveriguarqualodrivercorretoparagerenciaresta conexo,vistoqueoesteparmetroserveparaobtermosestainformao.

aResult

o array multidimensional que contm os valores de retorno do comando executadonosistema. Para cada registro (ou tuples) retornados pela consulta ser criado um item correspondente em aResult e para cada campo retornado ser criado um item dentrodestalinha.DemodoqueaResultserdeclaradocomo:


Pg.39

DECLAREaResult[numero_de_linhas][numero_de_colunas]

Exemplo1(MySQL):/* *ListatodasastabelascadastradasnoservidorMySQL */ tabelas:=SQLArray(SHOWTABLES) ?ToString(tabelas)

Exemplo2(PostgreSQL com parmetros):/* *TestaseatabelaCLIENTESexistircdigoemPostgreSQL: */ SQL:="SELECTtablenameFROMpg_tablesWHEREtablename=$1" Arr:=SQLArray(SQL,{CLIENTES}) ifEmpty(Arr) ?Tabelanaoexiste! else ?Tabelaexisteservidor! endif

Consultetambm:SQLEXECUTE() SQLPARSER() USESQL ApndiceCTrabalhandocomoPARSERSQLinternodaSQLLIB

17. SQLARRAYASSOC()Envia um comando SQL direto ao servidor e obtm o valor de retorno armazenandoo em um ARRAY associativo. Esta funo semelhante SQLARRAY() e segue as suas mesmas regras, diferenciandose apenas no vetor de retorno que possui associao com os campos das tabelas (sempreemletrasminsculas). Sintaxe:SQLArrayAssoc(,[],[], [],[])>aResult

Onde:

EspecificaocomandoSQLqueserexecutadonoservidor. um lista de argumentos opcionais utilizados para prprocessar utilizando o PARSER interno da SQL LIB, antes de enviar o comando ao servidor. IndicaonmerodaconexoondeocomandoSQLdeveserexecutado. um array opcional que se especificado, ser preenchido com os nomes dos camposretornadosnaconsultaefetuada. Porexemplo,emumcomandoSELECTNOME,FONEFROMCLIENTES,


Pg.40

estearrayconteriadoisvalores:{NOME,FONE}

um valor numrico interno da SQL LIB que identifica o SYSTEM ID do driverutilizadoparagerenciarestaconexo. Especificar este parmetro acelera a execuo do comando SQL quando h muitas conexes efetuadas ao mesmo tempo, pois a SQL LIB no necessita pesquisarinternamenteparaaveriguarqualodrivercorretoparagerenciaresta conexo,vistoqueoesteparmetroserveparaobtermosestainformao.

aResult

o array multidimensional que contm os valores de retorno do comando executadonosistema. Para cada registro (ou tuples) retornados pela consulta ser criado um item correspondente em aResult e para cada campo retornado ser criado um item dentrodestalinha.DemodoqueaResultserdeclaradocomo:DECLAREaResult[numero_de_linhas][numero_de_colunas]

Exemplo:/* *TestaseatabelaCLIENTESexistircdigoemPostgreSQL: */ result:=SQLArrayAssoc("SELECT*fromUSERSorderbyNAME") forn:=1tolen(result) /* *Exibenatelaovalordocamponamede *todososregistrosdevolvidos */ ?result[n]['name'] next

Consultetambm:SQLARRAY() SQLEXECUTE() SQLPARSER() USESQL ApndiceCTrabalhandocomoPARSERSQLinternodaSQLLIB

18. SQLNULLDATE()Retornaumastringrepresentandoumadataembrancoounula. Sintaxe:SQLNullDate([])>cData

Onde:

o nmero identificadordo driver (tambm conhecido comoSystem ID) que deveserutilizadoparadeterminarqual ovalorcorretoderetorno. Caso este parmetro seja omitido, a SQL LIB determinar o valor padro de nSystemIDverificandoaconexoatual.


Pg.41

cData

astring representandoumadatavaziaounula.

Utilizeestafunoaoefetuarpesquisasdiretonoservidor,demodoamanterseusoftwareportvel entreosdiversosdriverssuportadospelaSQLLIBistoapenasnecessriocasovocnoesteja utilizandonenhumdosparsersinternosdaRDD. EmalgunsservidoresSQLcomooPostgreSQL,camposcomvaloresNULLnosoarmazenados emndicesforandocomqueumapesquisatalcomoSELECT*FROMDATEISNULLrealize um tablescan oquecomcertezasacrificariaseuaplicativoeobanco. Por isto a SQL LIB trabalha com esta funo para determinar qual a expresso correta a ser utilizadanestescasos. Exemplo:?SQLNullDate(POSTGRESQL_ID) ?SQLNullDate(MYSQL_ID) //Retornar:00010101

/*Utilizandoparamontarumfiltronoservidor*/ SQLFILTER(aniversario=+SQLNullDate())

Consultetambm:SQLNULL()

19. SQLNULL()Retornaaexpressocaracterutilizadaparagravaoemcamposstring,quandonenhumvalorfor especificado,evitandoquevaloresNULLsejamgravadosnatabela. Sintaxe:SQLNULL()>cChar

Onde:

ocaracterformatadoparastring,representandoovalordeNULL.

Lembrandoque ousodestafunoapenasnecessrio, caso vocno estejautilizandonenhum dosparsersinternosda SQLLIB.VejamaioresdetalhesemSQLNULLDATE()sobre quandoaplicarestetipodefuno.

Exemplo:/*Filtrarosclientesqueestejamsemtelefone*/ SQLFILTERTOfone=+SQLNull())

Consultetambm:SQLNULLDATE()


Pg.42

20. SQLFILTER()Retornaeopcionalmentedefineumfiltroparaseraplicadonoladodoservidor paraatabelaatual. A expresso passada por argumento deve ser formatada como um filtro SQL. O comando SQL FILTERmapeadointernamenteparaexecutarestafuno. Sintaxe:SQLFilter([])>cCurrentFilter

Onde:

a expresso que dever ser aplicada como filtro no ALIAS() atual. Se uma string vazia for passada como argumento, o filtro atualmente definido para estatabelaserremovido. ofiltroatualmenteemuso.

cCurrentFilter

O uso deste comando altamente recomendado como substituto de SET FILTER e SET RELATION sempre que possvel, por ser aplicado diretamente no servidor o que torna o seu processamentomaisrpido. Exemplo:/* *FiltratodososclientesquecontenhamapalavraJOAOemqualquer *posioemseunomesejanoinicio,meiooufim */ USEclientesNEWALIAScliVIAmysql SQLFILTER(nomeLIKE%JOAO%) GOTOP BROWSE()

21. SQLREFRESH()Atualizaosdadosdatabelaatual,forandoumsincronismoda cacheatualcomosdadosdo servidor SQL. Sintaxe:SQLRefresh()>nil

Esta rotina atualiza os dados da tabela atual dando um GOTO para o mesmo registro onde est atualmente posicionadooponteiro de registros. Caso esta funo seja chamadasobreum registro deletadocom FULLDELETE()estandoativo,atabelaatual irretornarum EOF(). Exemplo:USEpedidosNEWVIAmysql /* *Deletatodososregistrosdatabelaeatualizao *osdadosdamemoria */ SQLEXECUTEDELETEFROMPEDIDOS


Pg.43

SQLRefresh()

Consultetambm:FULLDELETE()

22. SQL_AFFECTEDROWS()RetornaonmerodelinhasafetadaspeloltimocomandoSQL. Sintaxe:SQL_AffectedRows()>nRowCount

Onde:

o nmero de linhas atualizadas / deletadas / inseridas pelo ltimo comando SQLenviadoaoservidor.

Exemplo:SQLEXECUTEDELETEFROMpedidos ALERT(ntrim(SQL_AffectedRows())+linhasforamexcludas)

23. SQL_FULLDELETE()Especifica se um registro deve ser excludo definitivamente da tabela ou apenas marcado para remoofuturacomocomandoPACK.OcomandoSQLFULLDELETEmapeadointernamente parachamarestafuno. Sintaxe:SQL_FullDelete([])>lOldValue

Onde:

Se verdadeiro o registro atual ser definitivamente deletado da tabela caso contrrio,serapenasmarcadopararemoofuturacomocomandoPACK. ovaloratual destafuno.

lOldValue

Estafunotilpara seefetuarvalidaesdoladodoservidor imagineaseguintesituao:

Um aplicativo possui uma tabela de clientes e outra de pedidos, que vinculada aos clientes.Estemesmoaplicativo,podedeixarparaousurioaopodeseEXCLUIR umitemdocadastrodeclienteseestecomando,efetuariaumDBDELETE()noregistro selecionadodestatabela.

Noteo pontoimportanteagora: Oservidor SQL poderecusarestaoperaodeexclusosejhouverumachaveestrangeiravinculadanestatabela,porexemplo.


Pg.44

Utilizando esta linha de raciocnio acima, nunca haveria em sua base de dados nenhum pedido efetuadoparaalgumclienteexcludo(registrorfo)esendoassim, vocsempretersuabasede dadosconsistente.

Consultetambm:SQLFULLDELETE

24. SQLCREATEFLAGS ()DefineparmetrosadicionaisqueseroanexadosfunoDBCreate()antesdeseremenviados para o servidor SQL. Esta funo deve ser usada para se alterar algum parmetro da tabela, que normalmente no est disponvel pelos parmetros de DBCreate(), como por exemplo, o seu TABLETYPEouROW_FORMAT. Sintaxe:SQLCreateFlags([],[])>cCurrentFlags

Onde:

a string contendouma ou mais opes que sero enviadas ao servidor SQL juntamentecomocomandoDDLnomomentodecriaodatabela. um valor numrico interno da SQL LIB que identifica o SYSTEM ID do driverutilizadoparagerenciarestaconexo. Este parmetro importante, pois ele determina que seja aplicado APENASconexesqueutilizemestedriver. Istosignificaque,casosuaaplicaoutilizeaomesmotempoumaconexocom MySQL e outra com PostgreSQL, voc podepor exemplo, mudar os flags de DBCreate()apenasparaasconexesqueusamsomenteMySQL.Destemodo, cadabancoSQLtersuaprpriaconfiguraogerenciadapelaSQLLIBRDD individualmente. Se este parmetro for omitido ser substitudo pelo SYSTEM ID da conexo atual.

cCurrentFlags

ovaloratualmenteemvigorparao especificado.

ExemplodecomocriartabelascomestruturaspersonalizadascomaSQLLIB:LOCALaStru:={{'nome','c',25,0},{'aniv','d',10,0}} LOCALcFlag /* *Criaumatabelanormalmentesemalterarnada. *Seuformatoser InnoDB(comsuportetransaes) */ DBCREATE('test1',aStru) /* *AlteramosumparmetroeforamoseleacriaratabelacomoMyISAM *esteformatonosuportatransaes. *


Pg.45

*Observequenoexemploabaixo,ovaloratualemvigorparaaconexo *salvonavariavelcFlagedepoisrestaurado. */ cFlag:=SQLCreateFlags('ENGINE=MyISAM') DBCREATE('test2',aStru) SQLCreateFlags("ENGINE=MyISAMDEFAULTCHARSET=latin1"+ "PACK_KEYS=1ROW_FORMAT=COMPRESSED") DBCREATE('test3',aStru) SQLCreateFlags(cFlag) /* *Afunoabaixo,ircriaratabelatest4comomesmoformatodetest1 *Poisnoexemploacima,RESTAURAMOSovalordeSQLCreateFlags()aoseu *padrologodepoisdecriarmostest3. */ DBCREATE('test4',aStru)

Consultetambm:DBCREATE()

25. DBCREATE()CriaumarquivodedadosnoformatoDBFouumatabelanoservidorSQLcomaSQLLIB. Sintaxe:DBCreate(,[])>NIL

Onde:

onomedoarquivo.DBFouonomedatabelaSQLquesercriadacontendoa estruturadesejada. Aprimeiracolunadeveconteronomedocampo,asegundaotipo,aterceira,o tamanhodocampoeaquarta,onmerodecasasdecimais.Osdadosfornecidos devemseguirasregrasusadaspelocomandoCreatedoDBU.Informesempre asquatrocolunas,ouseja,acolunaDecimalsdeveserespecificadacom0(zero) paracamposnonumricos um array contendo a estrutura da nova tabela ou arquivo .DBF que ser criado. Quando se trabalha com Clipper, estearray deve ter no mnimoquatro colunas quando se deseja criar um arquivo DBF, sendo que cada linha correspondeaumcampoasercriado. No entanto, quando se trabalha com a SQL LIB RDD este array pode conter mais informaes, indicando outras caractersticas que se deseja agregar aos camposdanovatabela. A listagem que se segue abaixo, destaca as posies que este array poder possui,bemcomoosignificadodecadavalor: Posio 1 Refer ncia Nomedocamposercriado(semespaos)


Pg.46

2

Tipodocamporepresentado pelaprimeiraletra: CHAR(texto) NUMERICO DATA LGICO MEMO

Voctambmpodercriarcamposemumatabelacom tipodedadosespecficosdoseubancodedados.Para especificarexplicitamenteoformatoemSQLparaum determinado campo, de modo que a SQL LIB possa interpretar isto de modo correto, o dcimo valor do itemquedefineocampousadoparaindicarseotipo docampo nativo doservidor SQL. 3 4 5 Tamanhodocampoembytes. Nmerodecasasdecimais. Umflag,indicandocomvalorverdadeiroseestecampo devesercriadocomo NOTNULL. Valorlgico,indicandoseocampopossuirounooflag UNIQUE. Valorlgico,indicandoseocampopossuirounooflag AUTOINCREMENT. Valorlgico,indicandoseocampopossuirounooflag PRIMARYKEY IndicaaexpressoDEFAULTparaocampo,casoo usurionoapreencha. Valorlgico,indicandoseotipodestecampoumtipo nativo doservidorSQL.

6

7

8

9

10

Exemplo1(criandoumatabelaemSQLcomalgunsparametrosadicionais):aStru:={} *CampoNOTNULL AAdd(aStru,{"key","n",10,0,.t.}) *PRIMARYKEYeAUTOINCREMENTO AAdd(aStru,{"codigo","n",10,0,,,.t.,.t.}) *Nomeumcampocaracternormal AAdd(aStru,{"nome","c",25,0}) *campocaracternormal AAdd(aStru,{"endereco","c",40,0}) *NOTNULLeUNIQUE


Pg.47

AAdd(aStru,{"cpf","c",21,0,.T.,.T.}) *Camposcomformataonormal AAdd(aStru,{"civil","c",1,0}) AAdd(aStru,{"obs","m",10,0}) AAdd(aStru,{"cadastro","d",10,0}) DBCreate('test6',aStru)

ApartirdaSQLLIB v1.3,doisnovoscomandospersonalizadosforamintroduzidoscomointuito deajudaraoprogramadornamontagemdoARRAYcorretoparaDBCreate().Elesestodefinidos dentrodoarquivoSQLLIB.CHeoexemplo2abaixo,demonstraasuafacilidade: Exemplo2(mesmoresultadodoexemplo1,pormcomalgumasregrasdevalidaoadicionais):/* *Mesmoexemplodecamposacima,utilizandoa *sintaxecomosnovoscomandosintroduzidosnaSQLLIB. */ aCampos:={} SQLADDFIELD"KEY"TYPEINTEGERINTOaCampos SQLADDFIELD"Codigo"NUM(10)PRIMARY_KEYAUTO_INCINTOaCampos SQLADDFIELD"Nome"CHAR(25)DEFAULT""NOTNULLINTOaCampos SQLADDFIELD"Endereco"CHAR(40) INTOaCampos SQLADDFIELD"CPF"CHAR(21)NOTNULLUNIQUEINTOaCampos SQLADDFIELD"Civil"TYPE"ENUM('Casado','Solteiro')" NOTNULLDEFAULT'Solteiro'INTOaCampos SQLADDFIELD"OBS"MEMO(10) INTOaCampos SQLADDFIELD"Cadastro"DATE(10)DEFAULTDate()INTOaCampos DBCreate('test7',aCampos)

Consultetambm:SQLCREATEFLAGS()

26. TABLE()Testaseumaoumaistabelasexistemnoservidor. Sintaxe:Table(,[])>lFound

Onde:

astringcontendoonomeouamscaradastabelasqueseropesquisadasno servidorSQL. Utilize o asterisco * como caracter curinga para pesquisar por mais de uma tabela.

onmerodaconexocomoservidorutilizadaparaextrairainformao.Se este parmetro for omitido ser substitudo por um valor padro, segundo o algoritmoabaixo: Sehouveralgumarquivoabertonareaatualeseeleforumatabelaaberta


Pg.48

comaSQLLIB,utilizeeconexodestatabela . Casocontrrioaconexoatualserassumida.lFound

um valor lgico indicando se um ou mais arquivos foram encontrados no servidor. EstafunofazusodoSCHEMAatualparaefetuarapesquisa.

Exemplo1(checandoseumatabelaexiste):ifTable(clientes.dbf) ?tabeladeclientesjexiste! else dbCreate(clientes.dbf,aEstrutura) endif

Exemplo2(checandosevriastabelasexistem):if!Table(NET*.dbf) ?tabelasdosistemanoforamencontradas endif

Consultetambm:SQLGETTABLES() INDEX() TAG()

27. INDEX()Checaseum oumaisndicesexistemnoservidorSQL.Estafunoconsideraapenas osndices criadoscomocomandoINDEXONouDBCREATEINDEX(). Sintaxe:Index(,[])>lFound

Onde:

astringcontendoonomeouamscaradosndicesqueseropesquisadosno servidorSQL. Utilize o asterisco * como caracter curinga para pesquisar por mais de uma tabela.

onmerodaconexocomoservidorutilizadaparaextrairainformao.Se este parmetro for omitido ser substitudo por um valor padro, segundo o algoritmoabaixo: Sehouveralgumarquivoabertonareaatualeseeleforumatabelaaberta comaSQLLIB,utilizeeconexodestatabela . Casocontrrioaconexoatualserassumida.


Pg.49

lFound

um valor lgico indicando se um ou mais arquivos foram encontrados no servidor.

Exemplo:USEclientesNEWVIAPGSQL IF!index(nome.ntx) ?indexandotabeladeclientes. INDEXONnomeTOnome.ntx Else SETINDEXTOnome End

Consultetambm:SQLGETINDEXES() TAG() TABLE()

28. TAG()Checa a existncia de uma tag especfica dentro deum ndice criado pela SQL LIB. Esta funo considera apenas osndicescriadoscomocomandoINDEXONouDBCREATEINDEX(). Sintaxe:Tag(,,[])>lFound

Onde:

onomedatagquesedesejapesquisarnondice. onomedondice quecontmatagprocurada. onmerodaconexocomoservidorutilizadaparaextrairainformao.Se este parmetro for omitido ser substitudo por um valor padro, segundo o algoritmoabaixo: Sehouveralgumarquivoabertonareaatualeseeleforumatabelaaberta comaSQLLIB,utilizeeconexodestatabela . Casocontrrioaconexoatualserassumida.

lFound

umvalorlgicoindicandose existeem.

Exemplo:USEclientesNEWVIAPGSQL CLEARINDEXES INDEXONnome INDEXONendereco TAGnome TOclientes.cdx TAGende TOclientes.cdx


Pg.50

?tag(nome,clientes.cdx) ?tag(fone,clientes.cdx) ?tag(ende,clientes.cdx)

//Result:.T. //Result:.F. //Result:.T.

Consultetambm:SQLGETINDEXES() INDEX() TABLE()

29. DATABASE()ChecaaexistnciadeumDATABASEjuntoaoservidorSQL. Sintaxe:DataBase(,[])>lFound

Onde:

onomedoDATABASEquesedesejaaveriguar. onmerodaconexocomoservidorutilizadaparaextrairainformao.Se este parmetro for omitido ser substitudo por um valor padro, segundo o algoritmoabaixo: Sehouveralgumarquivoabertonareaatualeseeleforumatabelaaberta comaSQLLIB,utilizeeconexodestatabela . Casocontrrioaconexoatualserassumida.

lFound

umvalorlgicoindicandoseexistenoservidor.Estafunofazuso doSCHEMAatualparaefetuarapesquisa.

Exemplo:#include'sqllib.ch' /* *Nesteexemplo,checamosseobancodedadosjexiste,caso *contrriocriamosele. */ SQLCONNECTON'192.168.0.1' PORT3306 DATABASE'template1' USER'postgres' PASSWORD'sql' LIB'PostgreSQL' INTOnPostSQL IFDatabase(sistema) *Databasejexiste! ELSE SQLEXECUTECREATEDATABASEsistema End SQLDISCONNECTnPostSQL


Pg.51

/* *TudoOk!Usamosagoraobancodedadoscorreto=D */ SQLCONNECTON'192.168.0.1' PORT3306 DATABASE'sistema' USER'postgres' PASSWORD'sql' LIB'PostgreSQL'

Consultetambm:SQLGETDBS() TABLE() INDEX()

30. TRUERECCOUNT()Retorna a quantidade correta de registros de uma tabela. Esta funo ignora o valor de SQL_ROWIDaocalcularosregsitros. Sintaxe:TrueReccount()>nCount

Onde:

Representaaquantidadederegistrosreaisdatabela.

NormalmenteaSQLLIBcalculaaquantidadederegistrosdeumatabelaatravsdoseguinte comando: SELECTmax(sql_rowid)FROMtabela No entanto, em alguns casos necessrio sabermos aquantidade realderegistros deumatabela, nestecasoentooprogramadorpodefazerusodestafuno.

31. SQLCOPYTABLE()Duplica os dados da tabela passada como argumento para uma nova, incluindo seus dados e sua estrutura. Sintaxe:SQLCopyTable(,)>lSuccess

Onde:

onomedatabelaouviewquesedesejaduplicar. onomedanovatabelasequedesejacriarcomosdadosdatabelaoriginal. Casoestatabelajexistanoservidor,elaserapagadaeumanovasercriada comaestruturaigual,demodoquenenhumerrosergeradopela


Pg.52

SQLLIB. Notaimportante:estafunocopia apenas aestruturaeosdadosparaanovatabelanoincluindo triggers,viewseoutrosobjetosvinculadostabelaoriginal. Consultetambm:SQLRENAMETABLE()

32. SQLRENAMETABLE()Altera o nome de uma tabela existente no servidor. O comando RENAME TABLE mapeado internamenteparaexecutarestafuno. Sintaxe:SQLRenameTable(,)>lSuccess

Onde: lSuccess

onomeatualdatabelaexistentenoservidor onovonomequeserdadotabela. umvalorlgicoindicandoxitoounonaexecuodocomando.

Exemplo:?SQLRenameTable(clientes.dbf,clientes_antigo.dbf)

Consultetambm:SQLCOPYTABLE() SQLRENAMEINDEX() SQLDROPTABLE()

33. SQLRENAMEINDEX()AlteraonomedeumndiceexistentejcriadopelaSQLLIB.OcomandoRENAMEINDEX mapeadointernamenteparaexecutarestafuno. Sintaxe:SQLRenameIndex(,)>lSuccess

Onde: lSuccess

onomeatualdatabelaexistentenoservidor onovonomeque deverserrepaadoaondice umvalorlgicoindicandoxitoounonaexecuodocomando.


Pg.53

Exemplo:USEclientesNEWVIAMySQL INDEXONnomeTOidxnome.ntx CLOSEALL ?SQLRenameIndex(idxnome.ntx,nomeindex.ntx) USEclientesNEWVIAMySQL SETINDEXTOnomeindex.ntx

Consultetambm:SQLCOPYTABLE() SQLRENAMETABLE()

34. SQLDROPTABLE()Removeumatabelaespecficadobancodedados. Sintaxe:SQLDropTable()>nil

Onde:

astringidentificandoonomedatabelaqueser removidadobancodedados.

Exemplo:SQLDropTable(tabla.dbf)

Consultetambm:SQLRENAMETABLE()

35. SQLDROPINDEX()Removeumoumaisndicesexistentescomnomeigualaopassadoporparmetro. Sintaxe:SQLDropIndex()>nil

Onde:

astringidentificandoonomedondiceaserremovido.Vocpodeutilizaro asterisco * como curinga para excluir mais de um ndice com o mesmo comando.


Pg.54

Exemplo:USEclientesNEWVIAMySQL INDEXONnomeTOidxnome.ntx CLOSEALL ?SQLDropIndex(idxnome.ntx) USEclientesNEWVIAMySQL SETINDEXTOidxnome.ntx

//Erro:oindicenaoexiste

Consultetambm:SQLRENAMEINDEX()

36. SQLALTERTABLE()Altera a estrutura de uma tabela existente e deixaa igual estrutura passada como parmetro inclusivenaORDEMEXATAdoscampos (seoservidorforMySQL). Sintaxe:SQLAlterTable(,,[])>lSuccess

Onde:

onomedatabelaexistentequeseratualizada. umarraycomanovaestruturaparaatabela,esteparmetropossuiomesmo formatodoarray utilizadoporDBCREATE()respeitandoasseguintesregras:

Casoumcampoexistaem ,masaindanoexista natabelasercriado.

Casoumcampoexistanatabela ,masnoemserdeletado Caso um campo exista em ambos o tipo de campo, tamanho e outroscritriosserovalidadosesenecessrio,ocamposeralteradoparapossuir asnovascarac

Manual Sqllib Rdd

Documents

Transcript of Manual Sqllib Rdd