{
    "content": [
        {
            "type": "text",
            "text": "# DBI::DBD::SqlEngine::Developers (perldoc)\n\n## NAME\n\nDBI::DBD::SqlEngine::Developers - Developers documentation for DBI::DBD::SqlEngine\n\n## SYNOPSIS\n\npackage DBD::myDriver;\nuse base qw(DBI::DBD::SqlEngine);\nsub driver\n{\n...\nmy $drh = $proto->SUPER::driver($attr);\n...\nreturn $drh->{class};\n}\nsub CLONE { ... }\npackage DBD::myDriver::dr;\n@ISA = qw(DBI::DBD::SqlEngine::dr);\nsub datasources { ... }\n...\npackage DBD::myDriver::db;\n@ISA = qw(DBI::DBD::SqlEngine::db);\nsub initvalidattributes { ... }\nsub initdefaultattributes { ... }\nsub setversions { ... }\nsub validateSTOREattr { my ($dbh, $attrib, $value) = @; ... }\nsub validateFETCHattr { my ($dbh, $attrib) = @; ... }\nsub getmydversions { ... }\nsub getavailtables { ... }\npackage DBD::myDriver::st;\n@ISA = qw(DBI::DBD::SqlEngine::st);\nsub FETCH { ... }\nsub STORE { ... }\npackage DBD::myDriver::Statement;\n@ISA = qw(DBI::DBD::SqlEngine::Statement);\nsub opentable { ... }\npackage DBD::myDriver::Table;\n@ISA = qw(DBI::DBD::SqlEngine::Table);\nmy %resetonmodify = (\nmydabc => \"mydfoo\",\nmydmno => \"mydbar\",\n);\nPACKAGE->registerresetonmodify( \\%resetonmodify );\nmy %compatmap = (\nabc => 'fooabc',\nxyz => 'fooxyz',\n);\nPACKAGE->registercompatmap( \\%compatmap );\nsub bootstraptablemeta { ... }\nsub inittablemeta { ... }\nsub tablemetaattrchanged { ... }\nsub opendata { ... }\nsub new { ... }\nsub fetchrow { ... }\nsub pushrow { ... }\nsub pushnames { ... }\nsub seek { ... }\nsub truncate { ... }\nsub drop { ... }\n# optimize the SQL engine by add one or more of\nsub updatecurrentrow { ... }\n# or\nsub updatespecificrow { ... }\n# or\nsub updateonerow { ... }\n# or\nsub insertnewrow { ... }\n# or\nsub deletecurrentrow { ... }\n# or\nsub deleteonerow { ... }\n\n## DESCRIPTION\n\nThis document describes the interface of DBI::DBD::SqlEngine for DBD developers who write\nDBI::DBD::SqlEngine based DBI drivers. It supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo,\nwhich you should read first.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CLASSES**\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "DBI::DBD::SqlEngine::Developers",
        "section": "",
        "mode": "perldoc",
        "summary": "DBI::DBD::SqlEngine::Developers - Developers documentation for DBI::DBD::SqlEngine",
        "synopsis": "package DBD::myDriver;\nuse base qw(DBI::DBD::SqlEngine);\nsub driver\n{\n...\nmy $drh = $proto->SUPER::driver($attr);\n...\nreturn $drh->{class};\n}\nsub CLONE { ... }\npackage DBD::myDriver::dr;\n@ISA = qw(DBI::DBD::SqlEngine::dr);\nsub datasources { ... }\n...\npackage DBD::myDriver::db;\n@ISA = qw(DBI::DBD::SqlEngine::db);\nsub initvalidattributes { ... }\nsub initdefaultattributes { ... }\nsub setversions { ... }\nsub validateSTOREattr { my ($dbh, $attrib, $value) = @; ... }\nsub validateFETCHattr { my ($dbh, $attrib) = @; ... }\nsub getmydversions { ... }\nsub getavailtables { ... }\npackage DBD::myDriver::st;\n@ISA = qw(DBI::DBD::SqlEngine::st);\nsub FETCH { ... }\nsub STORE { ... }\npackage DBD::myDriver::Statement;\n@ISA = qw(DBI::DBD::SqlEngine::Statement);\nsub opentable { ... }\npackage DBD::myDriver::Table;\n@ISA = qw(DBI::DBD::SqlEngine::Table);\nmy %resetonmodify = (\nmydabc => \"mydfoo\",\nmydmno => \"mydbar\",\n);\nPACKAGE->registerresetonmodify( \\%resetonmodify );\nmy %compatmap = (\nabc => 'fooabc',\nxyz => 'fooxyz',\n);\nPACKAGE->registercompatmap( \\%compatmap );\nsub bootstraptablemeta { ... }\nsub inittablemeta { ... }\nsub tablemetaattrchanged { ... }\nsub opendata { ... }\nsub new { ... }\nsub fetchrow { ... }\nsub pushrow { ... }\nsub pushnames { ... }\nsub seek { ... }\nsub truncate { ... }\nsub drop { ... }\n# optimize the SQL engine by add one or more of\nsub updatecurrentrow { ... }\n# or\nsub updatespecificrow { ... }\n# or\nsub updateonerow { ... }\n# or\nsub insertnewrow { ... }\n# or\nsub deletecurrentrow { ... }\n# or\nsub deleteonerow { ... }",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 88,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "CLASSES",
                "lines": 584,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "DBI::DBD::SqlEngine::Developers - Developers documentation for DBI::DBD::SqlEngine\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "package DBD::myDriver;\n\nuse base qw(DBI::DBD::SqlEngine);\n\nsub driver\n{\n...\nmy $drh = $proto->SUPER::driver($attr);\n...\nreturn $drh->{class};\n}\n\nsub CLONE { ... }\n\npackage DBD::myDriver::dr;\n\n@ISA = qw(DBI::DBD::SqlEngine::dr);\n\nsub datasources { ... }\n...\n\npackage DBD::myDriver::db;\n\n@ISA = qw(DBI::DBD::SqlEngine::db);\n\nsub initvalidattributes { ... }\nsub initdefaultattributes { ... }\nsub setversions { ... }\nsub validateSTOREattr { my ($dbh, $attrib, $value) = @; ... }\nsub validateFETCHattr { my ($dbh, $attrib) = @; ... }\nsub getmydversions { ... }\nsub getavailtables { ... }\n\npackage DBD::myDriver::st;\n\n@ISA = qw(DBI::DBD::SqlEngine::st);\n\nsub FETCH { ... }\nsub STORE { ... }\n\npackage DBD::myDriver::Statement;\n\n@ISA = qw(DBI::DBD::SqlEngine::Statement);\n\nsub opentable { ... }\n\npackage DBD::myDriver::Table;\n\n@ISA = qw(DBI::DBD::SqlEngine::Table);\n\nmy %resetonmodify = (\nmydabc => \"mydfoo\",\nmydmno => \"mydbar\",\n);\nPACKAGE->registerresetonmodify( \\%resetonmodify );\nmy %compatmap = (\nabc => 'fooabc',\nxyz => 'fooxyz',\n);\nPACKAGE->registercompatmap( \\%compatmap );\n\nsub bootstraptablemeta { ... }\nsub inittablemeta { ... }\nsub tablemetaattrchanged { ... }\nsub opendata { ... }\n\nsub new { ... }\n\nsub fetchrow { ... }\nsub pushrow { ... }\nsub pushnames { ... }\nsub seek { ... }\nsub truncate { ... }\nsub drop { ... }\n\n# optimize the SQL engine by add one or more of\nsub updatecurrentrow { ... }\n# or\nsub updatespecificrow { ... }\n# or\nsub updateonerow { ... }\n# or\nsub insertnewrow { ... }\n# or\nsub deletecurrentrow { ... }\n# or\nsub deleteonerow { ... }\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This document describes the interface of DBI::DBD::SqlEngine for DBD developers who write\nDBI::DBD::SqlEngine based DBI drivers. It supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo,\nwhich you should read first.\n",
                "subsections": []
            },
            "CLASSES": {
                "content": "Each DBI driver must provide a package global \"driver\" method and three DBI related classes:\n\nDBI::DBD::SqlEngine::dr\nDriver package, contains the methods DBI calls indirectly via DBI interface:\n\nDBI->connect ('DBI:DBM:', undef, undef, {})\n\n# invokes\npackage DBD::DBM::dr;\n@DBD::DBM::dr::ISA = qw(DBI::DBD::SqlEngine::dr);\n\nsub connect ($$;$$$)\n{\n...\n}\n\nSimilar for \"datasources ()\" and \"disconnectall()\".\n\nPure Perl DBI drivers derived from DBI::DBD::SqlEngine usually don't need to override any of\nthe methods provided through the DBD::XXX::dr package. However if you need additional\ninitialization not fitting in \"initvalidattributes()\" and \"initdefaultattributes()\" of\nyou're ::db class, the connect method might be the final place to be modified.\n\nDBI::DBD::SqlEngine::db\nContains the methods which are called through DBI database handles ($dbh). e.g.,\n\n$sth = $dbh->prepare (\"select * from foo\");\n# returns the fencoding setting for table foo\n$dbh->csvgetmeta (\"foo\", \"fencoding\");\n\nDBI::DBD::SqlEngine provides the typical methods required here. Developers who write DBI\ndrivers based on DBI::DBD::SqlEngine need to override the methods \"setversions\" and\n\"initvalidattributes\".\n\nDBI::DBD::SqlEngine::TieMeta;\nProvides the tie-magic for \"$dbh->{$drvpfx . \"meta\"}\". Routes \"STORE\" through\n\"$drv->setsqlenginemeta()\" and \"FETCH\" through \"$drv->getsqlenginemeta()\". \"DELETE\" is\nnot supported, you have to execute a \"DROP TABLE\" statement, where applicable.\n\nDBI::DBD::SqlEngine::TieTables;\nProvides the tie-magic for tables in \"$dbh->{$drvpfx . \"meta\"}\". Routes \"STORE\" though\n\"$tblClass->settablemetaattr()\" and \"FETCH\" though \"$tblClass->gettablemetaattr()\".\n\"DELETE\" removes an attribute from the *meta object* retrieved by\n\"$tblClass->gettablemeta()\".\n\nDBI::DBD::SqlEngine::st\nContains the methods to deal with prepared statement handles. e.g.,\n\n$sth->execute () or die $sth->errstr;\n\nDBI::DBD::SqlEngine::TableSource;\nBase class for 3rd party table sources:\n\n$dbh->{sqltablesource} = \"DBD::Foo::TableSource\";\n\nDBI::DBD::SqlEngine::DataSource;\nBase class for 3rd party data sources:\n\n$dbh->{sqldatasource} = \"DBD::Foo::DataSource\";\n\nDBI::DBD::SqlEngine::Statement;\nBase class for derived drivers statement engine. Implements \"opentable\".\n\nDBI::DBD::SqlEngine::Table;\nContains tailoring between SQL engine's requirements and \"DBI::DBD::SqlEngine\" magic for\nfinding the right tables and storage. Builds bridges between \"sqlmeta\" handling of\n\"DBI::DBD::SqlEngine::db\", table initialization for SQL engines and *meta object*'s\nattribute management for derived drivers.\n\nDBI::DBD::SqlEngine\nThis is the main package containing the routines to initialize DBI::DBD::SqlEngine based DBI\ndrivers. Primarily the \"DBI::DBD::SqlEngine::driver\" method is invoked, either directly from DBI\nwhen the driver is initialized or from the derived class.\n\npackage DBD::DBM;\n\nuse base qw( DBI::DBD::SqlEngine );\n\nsub driver\n{\nmy ( $class, $attr ) = @;\n...\nmy $drh = $class->SUPER::driver( $attr );\n...\nreturn $drh;\n}\n\nIt is not necessary to implement your own driver method as long as additional initialization\n(e.g. installing more private driver methods) is not required. You do not need to call\n\"setupdriver\" as DBI::DBD::SqlEngine takes care of it.\n\nDBI::DBD::SqlEngine::dr\nThe driver package contains the methods DBI calls indirectly via the DBI interface (see \"DBI\nClass Methods\" in DBI).\n\nDBI::DBD::SqlEngine based DBI drivers usually do not need to implement anything here, it is\nenough to do the basic initialization:\n\npackage DBD:XXX::dr;\n\n@DBD::XXX::dr::ISA = qw (DBI::DBD::SqlEngine::dr);\n$DBD::XXX::dr::impdatasize     = 0;\n$DBD::XXX::dr::datasourcesattr = undef;\n$DBD::XXX::ATTRIBUTION = \"DBD::XXX $DBD::XXX::VERSION by Hans Mustermann\";\n\nMethods provided by \"DBI::DBD::SqlEngine::dr\":\nconnect\nSupervises the driver bootstrap when calling\n\nDBI->connect( \"dbi:Foo\", , , { ... } );\n\nFirst it instantiates a new driver using \"DBI::newdbh\". After that, initial bootstrap of\nthe newly instantiated driver is done by\n\n$dbh->func( 0, \"initdefaultattributes\" );\n\nThe first argument (0) signals that this is the very first call to\n\"initdefaultattributes\". Modern drivers understand that and do early stage setup here\nafter calling\n\npackage DBD::Foo::db;\nour @DBD::Foo::db::ISA = qw(DBI::DBD::SqlEngine::db);\n\nsub initdefaultattributes\n{\nmy ($dbh, $phase) = @;\n$dbh->SUPER::initdefaultattributes($phase);\n...; # own setup code, maybe separated by phases\n}\n\nWhen the $phase argument is passed down until\n\"DBI::DBD::SqlEngine::db::initdefaultattributes\", \"connect()\" recognizes a *modern* driver\nand initializes the attributes from *DSN* and *$attr* arguments passed via \"DBI->connect(\n$dsn, $user, $pass, \\%attr )\".\n\nAt the end of the attribute initialization after *phase 0*, \"connect()\" invoked\n\"initdefaultattributes\" again for *phase 1*:\n\n$dbh->func( 1, \"initdefaultattributes\" );\n\ndatasources\nReturns a list of *DSN*'s using the \"datasources\" method of the class specified in\n\"$dbh->{sqltablesource}\" or via \"\\%attr\":\n\n@ary = DBI->datasources($driver);\n@ary = DBI->datasources($driver, \\%attr);\n\ndisconnectall\n\"DBI::DBD::SqlEngine\" doesn't have an overall driver cache, so nothing happens here at all.\n\nDBI::DBD::SqlEngine::db\nThis package defines the database methods, which are called via the DBI database handle $dbh.\n\nMethods provided by \"DBI::DBD::SqlEngine::db\":\nping\nSimply returns the content of the \"Active\" attribute. Override when your driver needs more\ncomplicated actions here.\n\nprepare\nPrepares a new SQL statement to execute. Returns a statement handle, $sth - instance of the\nDBD:XXX::st. It is neither required nor recommended to override this method.\n\nvalidateFETCHattr\nCalled by \"FETCH\" to allow inherited drivers do their own attribute name validation. Calling\nconvention is similar to \"FETCH\" and the return value is the approved attribute name.\n\nreturn $validatedattributename;\n\nIn case of validation fails (e.g. accessing private attribute or similar),\n\"validateFETCHattr\" is permitted to throw an exception.\n\nFETCH\nFetches an attribute of a DBI database object. Private handle attributes must have a prefix\n(this is mandatory). If a requested attribute is detected as a private attribute without a\nvalid prefix, the driver prefix (written as $drvprefix) is added.\n\nThe driver prefix is extracted from the attribute name and verified against \"$dbh->{\n$drvprefix . \"validattrs\" }\" (when it exists). If the requested attribute value is not\nlisted as a valid attribute, this method croaks. If the attribute is valid and readonly\n(listed in \"$dbh->{ $drvprefix . \"readonlyattrs\" }\" when it exists), a real copy of the\nattribute value is returned. So it's not possible to modify \"fvalidattrs\" from outside of\nDBI::DBD::SqlEngine::db or a derived class.\n\nvalidateSTOREattr\nCalled by \"STORE\" to allow inherited drivers do their own attribute name validation. Calling\nconvention is similar to \"STORE\" and the return value is the approved attribute name\nfollowed by the approved new value.\n\nreturn ($validatedattributename, $validatedattributevalue);\n\nIn case of validation fails (e.g. accessing private attribute or similar),\n\"validateSTOREattr\" is permitted to throw an exception\n(\"DBI::DBD::SqlEngine::db::validateSTOREattr\" throws an exception when someone tries to\nassign value other than \"SQLICUPPER .. SQLICMIXED\" to \"$dbh->{sqlidentifiercase}\" or\n\"$dbh->{sqlquotedidentifiercase}\").\n\nSTORE\nStores a database private attribute. Private handle attributes must have a prefix (this is\nmandatory). If a requested attribute is detected as a private attribute without a valid\nprefix, the driver prefix (written as $drvprefix) is added. If the database handle has an\nattribute \"${drvprefix}validattrs\" - for attribute names which are not listed in that\nhash, this method croaks. If the database handle has an attribute\n\"${drvprefix}readonlyattrs\", only attributes which are not listed there can be stored\n(once they are initialized). Trying to overwrite such an immutable attribute forces this\nmethod to croak.\n\nAn example of a valid attributes list can be found in\n\"DBI::DBD::SqlEngine::db::initvalidattributes\".\n\nsetversions\nThis method sets the attributes \"fversion\", \"sqlnanoversion\", \"sqlstatementversion\" and\n(if not prohibited by a restrictive \"${prefix}validattrs\") \"${prefix}version\".\n\nThis method is called at the end of the \"connect ()\" phase.\n\nWhen overriding this method, do not forget to invoke the superior one.\n\ninitvalidattributes\nThis method is called after the database handle is instantiated as the first attribute\ninitialization.\n\n\"DBI::DBD::SqlEngine::db::initvalidattributes\" initializes the attributes\n\"sqlvalidattrs\" and \"sqlreadonlyattrs\".\n\nWhen overriding this method, do not forget to invoke the superior one, preferably before\ndoing anything else.\n\ninitdefaultattributes\nThis method is called after the database handle is instantiated to initialize the default\nattributes. It expects one argument: $phase. If $phase is not given, \"connect\" of\n\"DBI::DBD::SqlEngine::dr\" expects this is an old-fashioned driver which isn't capable of\nmulti-phased initialization.\n\n\"DBI::DBD::SqlEngine::db::initdefaultattributes\" initializes the attributes\n\"sqlidentifiercase\", \"sqlquotedidentifiercase\", \"sqlhandler\", \"sqlinitorder\",\n\"sqlmeta\", \"sqlengineversion\", \"sqlnanoversion\" and \"sqlstatementversion\" when\nSQL::Statement is available.\n\nIt sets \"sqlinitorder\" to the given $phase.\n\nWhen the derived implementor class provides the attribute to validate attributes (e.g.\n\"$dbh->{dbmvalidattrs} = {...};\") or the attribute containing the immutable attributes\n(e.g. \"$dbh->{dbmreadonlyattrs} = {...};\"), the attributes \"drvvalidattrs\",\n\"drvreadonlyattrs\" and \"drvversion\" are added (when available) to the list of valid and\nimmutable attributes (where \"drv\" is interpreted as the driver prefix).\n\ngetversions\nThis method is called by the code injected into the instantiated driver to provide the user\ncallable driver method \"${prefix}versions\" (e.g. \"dbmversions\", \"csvversions\", ...).\n\nThe DBI::DBD::SqlEngine implementation returns all version information known by\nDBI::DBD::SqlEngine (e.g. DBI version, Perl version, DBI::DBD::SqlEngine version and the SQL\nhandler version).\n\n\"getversions\" takes the $dbh as the first argument and optionally a second argument\ncontaining a table name. The second argument is not evaluated in\n\"DBI::DBD::SqlEngine::db::getversions\" itself - but might be in the future.\n\nIf the derived implementor class provides a method named \"get${drvprefix}versions\", this\nis invoked and the return value of it is associated to the derived driver name:\n\nif (my $dgv = $dbh->{ImplementorClass}->can (\"get\" . $drvprefix . \"versions\") {\n(my $deriveddriver = $dbh->{ImplementorClass}) =~ s/::db$//;\n$versions{$deriveddriver} = &$dgv ($dbh, $table);\n}\n\nOverride it to add more version information about your module, (e.g. some kind of parser\nversion in case of DBD::CSV, ...), if one line is not enough room to provide all relevant\ninformation.\n\nsqlparserobject\nReturns a SQL::Parser instance, when \"sqlhandler\" is set to \"SQL::Statement\". The parser\ninstance is stored in \"sqlparserobject\".\n\nIt is not recommended to override this method.\n\ndisconnect\nDisconnects from a database. All local table information is discarded and the \"Active\"\nattribute is set to 0.\n\ntypeinfoall\nReturns information about all the types supported by DBI::DBD::SqlEngine.\n\ntableinfo\nReturns a statement handle which is prepared to deliver information about all known tables.\n\nlisttables\nReturns a list of all known table names.\n\nquote\nQuotes a string for use in SQL statements.\n\ncommit\nWarns about a useless call (if warnings enabled) and returns. DBI::DBD::SqlEngine is\ntypically a driver which commits every action instantly when executed.\n\nrollback\nWarns about a useless call (if warnings enabled) and returns. DBI::DBD::SqlEngine is\ntypically a driver which commits every action instantly when executed.\n\nAttributes used by \"DBI::DBD::SqlEngine::db\":\nThis section describes attributes which are important to developers of DBI Database Drivers\nderived from \"DBI::DBD::SqlEngine\".\n\nsqlinitorder\nThis attribute contains a hash with priorities as key and an array containing the $dbh\nattributes to be initialized during before/after other attributes.\n\n\"DBI::DBD::SqlEngine\" initializes following attributes:\n\n$dbh->{sqlinitorder} = {\n0 => [qw( Profile RaiseError PrintError AutoCommit )],\n90 => [ \"sqlmeta\", $dbh->{$drvpfxmeta} ? $dbh->{$drvpfxmeta} : () ]\n}\n\nThe default priority of not listed attribute keys is 50. It is well known that a lot of\nattributes needed to be set before some table settings are initialized. For example, for\nDBD::DBM, when using\n\nmy $dbh = DBI->connect( \"dbi:DBM:\", undef, undef, {\nfdir => \"/path/to/dbm/databases\",\ndbmtype => \"BerkeleyDB\",\ndbmmldbm => \"JSON\", # use MLDBM::Serializer::JSON\ndbmtables => {\nquick => {\ndbmtype => \"GDBMFile\",\ndbmMLDBM => \"FreezeThaw\"\n}\n}\n});\n\nThis defines a known table \"quick\" which uses the GDBMFile backend and FreezeThaw as\nserializer instead of the overall default BerkeleyDB and JSON. But all files containing the\ntable data have to be searched in \"$dbh->{fdir}\", which requires \"$dbh->{fdir}\" must be\ninitialized before \"$dbh->{sqlmeta}->{quick}\" is initialized by \"bootstraptablemeta\"\nmethod of \"DBI::DBD::SqlEngine::Table\" to get \"$dbh->{sqlmeta}->{quick}->{fdir}\" being\ninitialized properly.\n\nsqlinitphase\nThis attribute is only set during the initialization steps of the DBI Database Driver. It\ncontains the value of the currently run initialization phase. Currently supported phases are\n*phase 0* and *phase 1*. This attribute is set in \"initdefaultattributes\" and removed in\n\"initdone\".\n\nsqlengineingofer\nThis value has a true value in case of this driver is operated via DBD::Gofer. The impact of\nbeing operated via Gofer is a read-only driver (not read-only databases!), so you cannot\nmodify any attributes later - neither any table settings. But you won't get an error in\ncases you modify table attributes, so please carefully watch \"sqlengineingofer\".\n\nsqltablesource\nNames a class which is responsible for delivering *data sources* and *available tables*\n(Database Driver related). *data sources* here refers to \"datasources\" in DBI, not\n\"sqldatasource\".\n\nSee \"DBI::DBD::SqlEngine::TableSource\" for details.\n\nsqldatasource\nName a class which is responsible for handling table resources open and completing table\nnames requested via SQL statements.\n\nSee \"DBI::DBD::SqlEngine::DataSource\" for details.\n\nsqldialect\nControls the dialect understood by SQL::Parser. Possible values (delivery state of\nSQL::Statement):\n\n* ANSI\n* CSV\n* AnyData\n\nDefaults to \"CSV\". Because an SQL::Parser is instantiated only once and SQL::Parser doesn't\nallow one to modify the dialect once instantiated, it's strongly recommended to set this\nflag before any statement is executed (best place is connect attribute hash).\n\nDBI::DBD::SqlEngine::st\nContains the methods to deal with prepared statement handles:\n\nbindparam\nCommon routine to bind placeholders to a statement for execution. It is dangerous to\noverride this method without detailed knowledge about the DBI::DBD::SqlEngine internal\nstorage structure.\n\nexecute\nExecutes a previously prepared statement (with placeholders, if any).\n\nfinish\nFinishes a statement handle, discards all buffered results. The prepared statement is not\ndiscarded so the statement can be executed again.\n\nfetch\nFetches the next row from the result-set. This method may be rewritten in a later version\nand if it's overridden in a derived class, the derived implementation should not rely on the\nstorage details.\n\nfetchrowarrayref\nAlias for \"fetch\".\n\nFETCH\nFetches statement handle attributes. Supported attributes (for full overview see \"Statement\nHandle Attributes\" in DBI) are \"NAME\", \"TYPE\", \"PRECISION\" and \"NULLABLE\". Each column is\nreturned as \"NULLABLE\" which might be wrong depending on the derived backend storage. If the\nstatement handle has private attributes, they can be fetched using this method, too. Note\nthat statement attributes are not associated with any table used in this statement.\n\nThis method usually requires extending in a derived implementation. See DBD::CSV or DBD::DBM\nfor some example.\n\nSTORE\nAllows storing of statement private attributes. No special handling is currently implemented\nhere.\n\nrows\nReturns the number of rows affected by the last execute. This method might return \"undef\".\n\nDBI::DBD::SqlEngine::TableSource\nProvides data sources and table information on database driver and database handle level.\n\npackage DBI::DBD::SqlEngine::TableSource;\n\nsub datasources ($;$)\n{\nmy ( $class, $drh, $attrs ) = @;\n...\n}\n\nsub availtables\n{\nmy ( $class, $drh ) = @;\n...\n}\n\nThe \"datasources\" method is called when the user invokes any of the following:\n\n@ary = DBI->datasources($driver);\n@ary = DBI->datasources($driver, \\%attr);\n\n@ary = $dbh->datasources();\n@ary = $dbh->datasources(\\%attr);\n\nThe \"availtables\" method is called when the user invokes any of the following:\n\n@names = $dbh->tables( $catalog, $schema, $table, $type );\n\n$sth = $dbh->tableinfo( $catalog, $schema, $table, $type );\n$sth = $dbh->tableinfo( $catalog, $schema, $table, $type, \\%attr );\n\n$dbh->func( \"listtables\" );\n\nEvery time where an \"\\%attr\" argument can be specified, this \"\\%attr\" object's\n\"sqltablesource\" attribute is preferred over the $dbh attribute or the driver default.\n\nDBI::DBD::SqlEngine::DataSource\nProvides base functionality for dealing with tables. It is primarily designed for allowing\ntransparent access to files on disk or already opened (file-)streams (e.g. for DBD::CSV).\n\nDerived classes shall be restricted to similar functionality, too (e.g. opening streams from an\narchive, transparently compress/uncompress log files before parsing them,\n\npackage DBI::DBD::SqlEngine::DataSource;\n\nsub completetablename ($$;$)\n{\nmy ( $self, $meta, $table, $respectcase ) = @;\n...\n}\n\nThe method \"completetablename\" is called when first setting up the *meta information* for a\ntable:\n\n\"SELECT user.id, user.name, user.shell FROM user WHERE ...\"\n\nresults in opening the table \"user\". First step of the table open process is completing the\nname. Let's imagine you're having a DBD::CSV handle with following settings:\n\n$dbh->{sqlidentifiercase} = SQLICLOWER;\n$dbh->{fext} = '.lst';\n$dbh->{fdir} = '/data/web/adrmgr';\n\nThose settings will result in looking for files matching \"[Uu][Ss][Ee][Rr](\\.lst)?$\" in\n\"/data/web/adrmgr/\". The scanning of the directory \"/data/web/adrmgr/\" and the pattern match\ncheck will be done in \"DBD::File::DataSource::File\" by the \"completetablename\" method.\n\nIf you intend to provide other sources of data streams than files, in addition to provide an\nappropriate \"completetablename\" method, a method to open the resource is required:\n\npackage DBI::DBD::SqlEngine::DataSource;\n\nsub opendata ($)\n{\nmy ( $self, $meta, $attrs, $flags ) = @;\n...\n}\n\nAfter the method \"opendata\" has been run successfully, the table's meta information are in a\nstate which allows the table's data accessor methods will be able to fetch/store row\ninformation. Implementation details heavily depends on the table implementation, whereby the\nmost famous is surely DBD::File::Table.\n\nDBI::DBD::SqlEngine::Statement\nDerives from DBI::SQL::Nano::Statement for unified naming when deriving new drivers. No\nadditional feature is provided from here.\n\nDBI::DBD::SqlEngine::Table\nDerives from DBI::SQL::Nano::Table for unified naming when deriving new drivers.\n\nYou should consult the documentation of \"SQL::Eval::Table\" (see SQL::Eval) to get more\ninformation about the abstract methods of the table's base class you have to override and a\ndescription of the table meta information expected by the SQL engines.\n\nbootstraptablemeta\nInitializes a table meta structure. Can be safely overridden in a derived class, as long as\nthe \"SUPER\" method is called at the end of the overridden method.\n\nIt copies the following attributes from the database into the table meta data\n\"$dbh->{ReadOnly}\" into \"$meta->{readonly}\", \"sqlidentifiercase\" and \"sqldatasource\" and\nmakes them sticky to the table.\n\nThis method should be called before you attempt to map between file name and table name to\nensure the correct directory, extension etc. are used.\n\ninittablemeta\nInitializes more attributes of the table meta data - usually more expensive ones (e.g. those\nwhich require class instantiations) - when the file name and the table name could mapped.\n\ngettablemeta\nReturns the table meta data. If there are none for the required table, a new one is\ninitialized. When after bootstrapping a new *tablemeta* and completing the table name a\nmapping can be established between an existing *tablemeta* and the new bootstrapped one,\nthe already existing is used and a mapping shortcut between the recent used table name and\nthe already known table name is hold in \"$dbh->{sqlmetamap}\". When it fails, nothing is\nreturned. On success, the name of the table and the meta data structure is returned.\n\ngettablemetaattr\nReturns a single attribute from the table meta data. If the attribute name appears in\n%compatmap, the attribute name is updated from there.\n\nsettablemetaattr\nSets a single attribute in the table meta data. If the attribute name appears in\n%compatmap, the attribute name is updated from there.\n\ntablemetaattrchanged\nCalled when an attribute of the meta data is modified.\n\nIf the modified attribute requires to reset a calculated attribute, the calculated attribute\nis reset (deleted from meta data structure) and the *initialized* flag is removed, too. The\ndecision is made based on %registerresetonmodify.\n\nregisterresetonmodify\nAllows \"settablemetaattr\" to reset meta attributes when special attributes are modified.\nFor DBD::File, modifying one of \"ffile\", \"fdir\", \"fext\" or \"flockfile\" will reset\n\"ffqfn\". DBD::DBM extends the list for \"dbmtype\" and \"dbmmldbm\" to reset the value of\n\"dbmtietype\".\n\nIf your DBD has calculated values in the meta data area, then call\n\"registerresetonmodify\":\n\nmy %resetonmodify = ( \"xxxfoo\" => \"xxxbar\" );\nPACKAGE->registerresetonmodify( \\%resetonmodify );\n\nregistercompatmap\nAllows \"gettablemetaattr\" and \"settablemetaattr\" to update the attribute name to the\ncurrent favored one:\n\n# from DBD::DBM\nmy %compatmap = ( \"dbmext\" => \"fext\" );\nPACKAGE->registercompatmap( \\%compatmap );\n\nopendata\nCalled to open the table's data storage. This is silently forwarded to\n\"$meta->{sqldatasource}->opendata()\".\n\nAfter this is done, a derived class might add more steps in an overridden \"openfile\"\nmethod.\n\nnew Instantiates the table. This is done in 3 steps:\n\n1. get the table meta data\n2. open the data file\n3. bless the table data structure using inherited constructor new\n\nIt is not recommended to override the constructor of the table class. Find a reasonable\nplace to add you extensions in one of the above four methods.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "The module DBI::DBD::SqlEngine is currently maintained by\n\nH.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack\n\nAll rights reserved.\n\nYou may freely distribute and/or modify this module under the terms of either the GNU General\nPublic License (GPL) or the Artistic License, as specified in the Perl README file.\n",
                "subsections": []
            }
        }
    }
}