This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: DB_File/Lock, Next: DBass, Prev: DB_File, Up: Module List Locking with flock wrapper for DB_File ************************************** NAME ==== DB_File::Lock - Locking with flock wrapper for DB_File SYNOPSIS ======== use DB_File::Lock; $locking = "read"; $locking = "write"; $locking = { mode => "read", nonblocking => 0, lockfile_name => "/path/to/shared.lock", lockfile_mode => 0600, }; [$X =] tie %hash, 'DB_File::Lock', [$filename, $flags, $mode, $DB_HASH], $locking; [$X =] tie %hash, 'DB_File::Lock', $filename, $flags, $mode, $DB_BTREE, $locking; [$X =] tie @array, 'DB_File::Lock', $filename, $flags, $mode, $DB_RECNO, $locking; ...use the same way as DB_File for the rest of the interface... DESCRIPTION =========== This module provides a wrapper for the DB_File module, adding locking. When you need locking, simply use this module in place of DB_File and add an extra argument onto the tie command specifying if the file should be locked for reading or writing. The alternative is to write code like: open(LOCK, "<$db_filename.lock") or die; flock(LOCK, LOCK_SH) or die; tie(%db_hash, 'DB_File', $db_filename, O_RDONLY, 0600, $DB_HASH) or die; ... then read the database ... untie(%db_hash); close(LOCK); This module lets you write tie(%db_hash, 'DB_File', $db_filename, O_RDONLY, 0600, $DB_HASH, 'read') or die; ... then read the database ... untie(%db_hash); This is better for two reasons: (1) Less cumbersome to write. (2) A fatal exception in the code working on the database which does not lead to process termination will probably not close the lockfile and therefore cause a dropped lock. USAGE DETAILS ============= The filename used for the lockfile defaults to "$filename.lock" (the filename of the DB_File with ".lock" appended). Using a lockfile separate from the database file is recommended because it prevents weird interactions with the underlying database file library The additional locking argument added to the tie call, can be: (1) "read" - aquires a shared lock for reading (2) "write" - aquires an exclusive lock for writing (3) A hash with the following keys (all optional except for the "mode"): mode the locking mode, "read" or "write". lockfile_name specifies the name of the lockfile to use. Default is "$filename.lock". This is useful for locking multiple resources with the same lockfiles. nonblocking determines if the flock call on the lockfile should block waiting for a lock, or if it should return failure if a lock can not be immediately attained. If "nonblocking" is set and a lock can not be attained, the tie command will fail. Currently, I'm not sure how to differentiate this between a failure form the DB_File layer. lockfile_mode determines the mode for the sysopen call in opening the lockfile. The default mode will be formulated to allow anyone that can read or write the DB_File permission to read and write the lockfile. (This is because some systems may require that one have write access to a file to lock it for reading, I understand.) The umask will be prevented from applying to this mode. Note: One may import the same values from DB_File::Lock as one may import from DB_File. OTHER LOCKING MODULES ===================== There are three locking wrappers for DB_File in CPAN right now. Each one implements locking differently and has different goals in mind. It is therefore worth knowing the difference, so that you can pick the right one for your application. Here are the three locking wrappers: Tie::DB_Lock - DB_File wrapper which creates copies of the database file for read access, so that you have kind of a multiversioning concurrent read system. However, updates are still serial. Use for databases where reads may be lengthy and consistency problems may occur. Tie::DB_LockFile - DB_File wrapper that has the ability to lock and unlock the database while it is being used. Avoids the tie-before-flock problem by simply re-tie-ing the database when you get or drop a lock. Because of the flexibility in dropping and re-acquiring the lock in the middle of a session, this can be massaged into a system that will work with long updates and/or reads if the application follows the hints in the POD documentation. DB_File::Lock (this module) - extremely lightweight DB_File wrapper that simply flocks a lockfile before tie-ing the database and drops the lock after the untie. Allows one to use the same lockfile for multiple databases to avoid deadlock problems, if desired. Use for databases where updates are reads are quick and simple flock locking semantics are enough. (This text duplicated in the POD documentation, by the way.) AUTHOR ====== David Harris Helpful insight from Stas Bekman SEE ALSO ======== DB_File(3).  File: pm.info, Node: DBass, Next: DCE/ACL, Prev: DB_File/Lock, Up: Module List DBM with associative arrays, file locking and XML records ********************************************************* NAME ==== `DBass' - DBM with associative arrays, file locking and XML records SYNOPSIS ======== use DBass; die unless DBass::gestalt (-api => 'xeen'); my $db = DBass->new ( -api => 'neo', -file => '+ 'file.lock', -mode => 0644 ); DESCRIPTION =========== This module provides methods to read, write and delete associative arrays in DBM files, with file locking and XML records. It uses a named argument `-api' for class methods new and `gestalt' to try to prevent later versions of the module from breaking preexisting APIs. METHODS ======= `gestalt' This method checks for the existence of an API: die 'no API neo' unless DBass::gestalt (-api => 'neo'); `-api' is the calling API to check for. One should use this method only for development or testing, and not in frequently used applications. new This method creates a new DBass object, and should be the first one called: my $db = DBass->new ( '-api' => 'neo', '-file' => '+ 'file.lock', '-mode' => 0644 ); `-api' is the calling API to use. `-file' is the read/write mode (default is read-only) and DBM filename. `-lock' is the lock filename. `-mode' is the file permissions mode of the DBM file. If the DBM file is opened for read-only access, the lock file must preexist, but can be empty. In MacOS, one can create an empty file with SimpleText. In *nix, one can create an empty file with touch: touch file.lock This version of the module has APIs `xeen' and X. The `xeen' API is deprecated and provided for backward compatibility only, and the `neo' API should be used when possible. close This method releases various resources in the DBass object, to allow other processes to access the DBM file: $db->close; Normally this method should not be used, as it renders the object useless for the remainder of the program execution (and is automatically called when the object is destroyed). delete This method deletes records from the DBM file: $db->delete ('-keys' => \@keys); $db->delete ('-keys' => \%keys); $db->delete ('-keys' => $key ); *Be careful.* It can also delete all records: $db->delete; keys This method returns record keys: my @keys = $db->keys; read This method returns a hash reference pointing to records in the DBM file: my $smallerhashref = $db->read ('-keys' => \@keys, '-root' => $root); my $smallerhashref = $db->read ('-keys' => \%keys, '-root' => $root); my $smallhashref = $db->read ('-keys' => $keys, '-root' => $root); my $entirehashref = $db->read ('-root' => $root); `-keys' are the keys to match against. `-root' is the XML root tag name used in storing the records. write This method writes key-value pairs to the DBM file: $db->write (-hash => \%hash, -root => $root); `-hash' is the hash reference pointing to the key-value pairs (records). `-root' is the XML root tag name to use in storing the records. KNOWN ISSUES ============ The `xeen' API is deprecated and provided for backward compatibility only, and the `neo' API should be used when possible. The main reason for the API name change is that the `neo' record format is significantly different from that of `xeen'. On platforms other than MacOS, *nix or Windows NT, flock will probably cause the module to crash and burn. The module should be pronounced `/di'bas/'. The `xeen' API is not named after the IBM alphaWorks `Xeena' XML editor. CHANGES ======= 0.53 2000.01.11 fixed Makefile.PL (oops!) 0.52 1999.10.30 added check for _OBJ added check for _HASHREF fixed neo_read handling of _UNTAGGED fixed neo_read to check for _HASHREF fixed neo_write to check for _OBJ fixed xeen_delete to check for _OBJ fixed xeen_destroy to check for _OBJ fixed xeen_new die preparation fixed xeen_new to include _UNTAGGED fixed xeen_read handling of _UNTAGGED fixed xeen_read to check for _HASHREF fixed xeen_write to check for _OBJ 0.51 1999.10.26 fixed gestalt for wantarray fixed neo_read to accept hash references as -keys fixed xeen_delete to accept hash references as -keys fixed xeen_read to accept hash references as -keys 0.50 1999.10.06 added neo API (valid XML tags and lists of lists) 0.40 1999.09.20 fixed DBM file locking bug in xeen_destroy fixed DBM file locking bug in xeen_new fixed xeen_delete to accept scalars as -keys fixed xeen_read to accept scalars as -keys AUTHOR ====== Copyright 1999, 2000 Nguon Hao Ching (`spiderboy@spiderboy.net'). CREDITS ======= Thanks to Tom Christiansen for Perl Cookbook recipe 14.5. Thanks to Mark-Jason Dominus for the Perl Monger tutorial on file locking. Thanks to David Harris and Paul Marquess for the recipe bug report. Thanks to Chris Nandor for `perlport'. Thanks to James Wismer for feedback on the initial, unreleased version. Thanks to Jay Trolley for her patience and understanding. Thanks to xeenie for everything else.  File: pm.info, Node: DCE/ACL, Next: DCE/DFS, Prev: DBass, Up: Module List Perl interface to DCE ACL client API ************************************ NAME ==== DCE::ACL - Perl interface to DCE ACL client API SYNOPSIS ======== use DCE::ACL; $aclh = DCE::ACL->bind($object); =head1 DESCRIPTION DCE::ACL provides a Perl interface to the sec_acl_* client API. As the sec_acl_list_t structure is rather complex, additional classes and methods are provided so Perl scripts can deal with it in a reasonable fashion. DCE::ACL::handle methods ======================== DCE::ACL::handle->bind See `DCE::ACL->bind' in this node. $aclh->num_acls Returns the number of acls in the sec_acl_list_t structure. $num = $aclh->num_acls $aclh->get_manager_types Equivalent to the sec_acl_get_manager_types function. `$manager_types' is a array reference. ($num_used, $num_types, $manager_types, $status) = $aclh->get_manager_types(); If called in a scalar context, only the `$manager_types' array reference is returned. $manager = $achl->get_manager_types->[0]; #first manager =item $aclh->get_access Equivalent to the sec_acl_get_access function. ($permset, $status) = $aclh->get_access($manager); $aclh->get_printstring Equivalent to the sec_acl_get_printstring function. `$printstrings' is an array reference of hash references. ($chain, $mgr_info, $tokenize, $total, $num, $printstrings, $status) = $aclh->get_printstring($manager); If called in a scalar context, only the `$printstrings' reference is returned. $printstrings = $aclh->get_printstring($manager); foreach $str (@$printstrings) { $permstr .= ($str->{permissions} & $entry->perms) ? $str->{printstring} : "-"; } $aclh->test_access Equivalent to the sec_acl_test_access function. ($ok, $status) = $aclh->test_access($manager, $perms); $aclh->replace Equivalent to the sec_acl_replace function. $status = $aclh->replace($manager, $aclh->type_object, $list); $aclh->lookup Equivalent to the sec_acl_lookup function. $list is a reference to a sec_acl_list_t structure, blessed into the *DCE::ACL::list* class. $type is an optional argument which defaults to `DCE::ACL-'type_object>. ($list, $status) = $aclh->lookup($manager, [$type]); $aclh->new_list This method does a lookup, deleting all entries and returns the empty list. $type is an optional argument which defaults to `DCE::ACL-'type_object>. ($list, $status) = $aclh->new_list($manager, [$type]); DCE::ACL::list methods ====================== $list->acls Returns a list of all acls if no index argument is given, when called in a scalar context, only the first acl is returned. Objects returned are references to sec_acl_t structures, blessed into the *DCE::ACL* class. $acl = $list->acls; DCE::ACL methods ================ DCE::ACL->bind Equivalent to the sec_acl_bind function. Returns a reference to the sec_acl_list_t structure bless into the *DCE::ACL::handle* class. The optional argument `$bind_to_entry' defaults to FALSE. ($aclh, $status) = DCE::ACL->bind($object, [$bind_to_entry]); DCE::ACL->type When given an integer argument, returns the string representation. $str = DCE::ACL->type(0); #returns 'user_obj' A method is provided foreach sec_acl_type_t type, returning an integer. $type = DCE::ACL->type_user; $acl->num_entries Returns the number of sec_acl_entry_t structures. $num = $acl->num_entries; =item $acl->default_realm Returns a hash reference with *uuid* and name keys. $name = $acl->default_realm->{name}; #/.../cell.foo.com $acl->remove Removes the specifed entry from the acl structure, where entry is a reference to sec_acl_entry_t structure, blessed into the *DCE::ACL::entry* class. $status = $acl->remove($entry); $acl->delete Removes all entries from the $acl. =item $acl->new_entry Allocates memory needed for a new sec_acl_entry_t structure, returns a reference to that structure blessed in to the *DCE::ACL::entry* class. $entry = $acl->new_entry; =item $acl->add Adds a sec_acl_entry_t structure to a sec_acl_t structure. $status = $acl->add($entry); $acl->entries Returns references to sec_acl_entry_t structures blessed in to the *DCE::ACL::entry* class. If an integer argument is given, only that entry will be returned, otherwise, a list of all entries will be returned. $entry = $acl->entries(0); #return the first entry foreach $entry ($acl->entries) { #return all entries ... DCE::ACL::entry methods ======================= $entry->compare Compares two acl entries, returns true if they are the same, returns false otherwise. $match = $entry1->compare($entry2); $entry->perms Returns the permission bits for the specified entry, setting the bits if given an argument. $bits = $entry->perms; for (qw(perm_read perm_control perm_insert)) { $bits |= DCE::ACL->$_(); } $e->perms($bits); $entry->entry_info Returns a hash reference containing entry info, changing it if given an argument. $uuid = $entry->entry_info->{id}{uuid}; $entry->entry_info({ entry_type => DCE::ACL->type_user, id => { uuid => $uuid, }, }); AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1), DCE::aclbase(3), DCE::Registry(3), DCE::UUID(3), DCE::Login(3), DCE::Status(3).  File: pm.info, Node: DCE/DFS, Next: DCE/Login, Prev: DCE/ACL, Up: Module List Perl module interface to DFS internals ************************************** NAME ==== DCE::DFS - Perl module interface to DFS internals SYNOPSIS ======== use DCE::DFS; DESCRIPTION =========== General DFS methods =================== DCE::DFS::cellname(path) DCE::DFS::crmount(path, fileset, read_write) DCE::DFS::delmount(path) DCE::DFS::fid(path) ACL stuff ========= DCE::DFS::acl(path, acl_type, registry_handle); $acl->entries() $acl->entry(entry_key) $acl->modify(entry_key, permissions) $acl->delete(entry_key) $acl->deleteall() $acl->calc_mask() $acl->commit() FLDB methods ============ DCE::DFS::flserver(cell_fs) $flserver->ftserver() $flserver->fileset_mask_reset() $flserver->fileset_mask_ftserver(ftserver) $flserver->fileset_mask_aggregate(aggregate) $flserver->fileset() $flserver->fileset_by_name(name) $flserver->fileset_by_id(fid) ftserver methods ================ $ftserver->address() $ftserver->hostname() $ftserver->aggregate() aggregate methods ================= $aggregate->ftserver() $aggregate->name() $aggregate->device() $aggregate->id() $aggregate->type() $aggregate->size() $aggregate->free() fileset methods =============== $fileset->ftserver() $fileset->aggregate() $fileset->name() $fileset->quota() $fileset->used() $fileset->set_quota(quota) $fileset->update() AUTHOR ====== Paul Henson SEE ALSO ======== perl(1), DCE::*.  File: pm.info, Node: DCE/Login, Next: DCE/Registry, Prev: DCE/DFS, Up: Module List Perl extension for interfacing to the DCE login API *************************************************** NAME ==== DCE::Login - Perl extension for interfacing to the DCE login API SYNOPSIS ======== use DCE::Login; my($l, $status) = DCE::Login->get_current_context; my $pwent = $l->get_pwent; DESCRIPTION =========== Perl extension for interfacing to the DCE login API. AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1), DCE::login_base(3), DCE::Registry(3).  File: pm.info, Node: DCE/Registry, Next: DCE/Status, Prev: DCE/Login, Up: Module List Perl interface to DCE Registry API ********************************** NAME ==== DCE::Registry - Perl interface to DCE Registry API SYNOPSIS ======== use DCE::Registry; my $rgy = DCE::Registry->site_open($site_name); DESCRIPTION =========== This module provides an OO Perl interface to the DCE Registry API. The sec_rgy_ prefix has been dropped and methods are invoked via a blessed registry_context object. AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1), DCE::rgybase(3), DCE::Status(3), DCE::Login(3), DCE::UUID(3).  File: pm.info, Node: DCE/Status, Next: DCE/UUID, Prev: DCE/Registry, Up: Module List Make sense of DCE status codes ****************************** NAME ==== DCE::Status - Make sense of DCE status codes SYNOPSIS ======== use DCE::Status; $errstr = error_inq_text($status); tie $status => DCE::Status; DESCRIPTION =========== When a $scalar is tie'd to the DCE::Status class, it has a different value depending on the context it is evaluated in, similar to the magic $! variable. When evaluated in a numeric context, the numeric value is returns, otherwise, the string value obtained from *dce_error_inq_text* is returned. EXPORTS ======= error_inq_text Equivalent to the dce_error_inq_text function. $errstr = error_inq_text($status); AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1), DCE::Registry(3), DCE::Login(3), DCE::ACL(3).  File: pm.info, Node: DCE/UUID, Next: DCE/aclbase, Prev: DCE/Status, Up: Module List Misc UUID functions ******************* NAME ==== DCE::UUID - Misc UUID functions SYNOPSIS ======== use DCE::UUID; DESCRIPTION =========== DCE::UUID exports the following functions: uuid_create() my($uuid, $status) = uuid_create(); uuid_hash() my($hash, $status) = uuid_hash($uuid); AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1), DCE::Status(3), DCE::Registry(3), DCE::Login(3).  File: pm.info, Node: DCE/aclbase, Next: DCE/attrbase, Prev: DCE/UUID, Up: Module List Constants from dce/aclbase.h **************************** NAME ==== DCE::aclbase - Constants from dce/aclbase.h SYNOPSIS ======== use DCE::aclbase; DESCRIPTION =========== AUTHOR ====== h2xs SEE ALSO ======== DCE::ACL(3), perl(1).  File: pm.info, Node: DCE/attrbase, Next: DCE/login_base, Prev: DCE/aclbase, Up: Module List Perl extension for blah blah blah ********************************* NAME ==== DCE::attrbase - Perl extension for blah blah blah SYNOPSIS ======== use DCE::attrbase; blah blah blah DESCRIPTION =========== Stub documentation for DCE::attrbase was created by h2xs. It looks like the author of the extension was negligent enough to leave the stub unedited. Blah blah blah. Exported constants ================== sec_attr_base_v0_0_included sec_attr_bind_type_string sec_attr_bind_type_svrname sec_attr_bind_type_twrs sec_attr_sch_entry_multi_inst sec_attr_sch_entry_none sec_attr_sch_entry_reserved sec_attr_sch_entry_unique sec_attr_sch_entry_use_defaults sec_attr_schema_part_acl_mgrs sec_attr_schema_part_comment sec_attr_schema_part_defaults sec_attr_schema_part_intercell sec_attr_schema_part_multi_inst sec_attr_schema_part_name sec_attr_schema_part_reserved sec_attr_schema_part_scope sec_attr_schema_part_trig_bind sec_attr_schema_part_trig_types sec_attr_schema_part_unique sec_attr_trig_type_none sec_attr_trig_type_query sec_attr_trig_type_update volatile AUTHOR ====== A. U. Thor, a.u.thor@a.galaxy.far.far.away SEE ALSO ======== perl(1).  File: pm.info, Node: DCE/login_base, Next: DCE/rgybase, Prev: DCE/attrbase, Up: Module List Constants from sec_login_*.h **************************** NAME ==== DCE::login_base - Constants from sec_login_*.h SYNOPSIS ======== use DCE::login_base; DESCRIPTION =========== These constant methods are inherited by DCE::Login, a developer should not need to use this module and its methods directly. AUTHOR ====== h2xs SEE ALSO ======== perl(1), DCE::Login(3), DCE::Registry(3).  File: pm.info, Node: DCE/rgybase, Next: DCE/rpcbase, Prev: DCE/login_base, Up: Module List Constants from dce/rgybase.h **************************** NAME ==== DCE::rgybase - Constants from dce/rgybase.h SYNOPSIS ======== use DCE::rgybase; DESCRIPTION =========== These constant methods are inherited by DCE::Registry, a developer should not need to use this module and its methods directly. Here is a list of the available constants: acct_admin_audit acct_admin_client acct_admin_flags_none acct_admin_server acct_admin_valid acct_auth_dup_skey acct_auth_flags_none acct_auth_forwardable acct_auth_post_dated acct_auth_proxiable acct_auth_renewable acct_auth_tgt acct_key_group acct_key_last acct_key_none acct_key_org acct_key_person acct_user_flags_none acct_user_passwd_valid domain_group domain_last domain_org domain_person max_unix_passwd_len name_max_len name_t_size no_override no_resolve_pname override pgo_flags_none pgo_is_an_alias pgo_is_required pgo_projlist_ok plcy_pwd_flags_none plcy_pwd_no_spaces plcy_pwd_non_alpha pname_max_len pname_t_size prop_auth_cert_unbound prop_embedded_unix_id prop_readonly prop_shadow_passwd properties_none quota_unlimited resolve_pname rgynbase_v0_0_included status_ok uxid_unknown wildcard_name wildcard_sid AUTHOR ====== h2xs SEE ALSO ======== perl(1), DCE::Registry(3), DCE::Login(3).  File: pm.info, Node: DCE/rpcbase, Next: DDL/Oracle, Prev: DCE/rgybase, Up: Module List Perl extension for blah blah blah ********************************* NAME ==== DCE::rpcbase - Perl extension for blah blah blah SYNOPSIS ======== use DCE::rpcbase; blah blah blah DESCRIPTION =========== Stub documentation for DCE::rpcbase was created by h2xs. It looks like the author of the extension was negligent enough to leave the stub unedited. Blah blah blah. Exported constants ================== rpc_c_authn_dce_dummy rpc_c_authn_dce_public rpc_c_authn_dce_secret rpc_c_authn_default rpc_c_authn_dssa_public rpc_c_authn_none rpc_c_authz_dce rpc_c_authz_name rpc_c_authz_none rpc_c_binding_default_timeout rpc_c_binding_infinite_timeout rpc_c_binding_max_count_default rpc_c_binding_max_timeout rpc_c_binding_min_timeout rpc_c_call_brdcst rpc_c_call_idempotent rpc_c_call_in_pipe rpc_c_call_maybe rpc_c_call_non_idempotent rpc_c_call_out_pipe rpc_c_cancel_infinite_timeout rpc_c_ep_max_annotation_size rpc_c_listen_max_calls_default rpc_c_mgmt_inq_if_ids rpc_c_mgmt_inq_princ_name rpc_c_mgmt_inq_stats rpc_c_mgmt_is_server_listen rpc_c_mgmt_stop_server_listen rpc_c_ns_dec_dns rpc_c_ns_default_exp_age rpc_c_ns_none rpc_c_ns_syntax_dce rpc_c_ns_syntax_dec_dns rpc_c_ns_syntax_default rpc_c_ns_syntax_internet_dns rpc_c_ns_syntax_unknown rpc_c_ns_syntax_uuid rpc_c_ns_syntax_x500 rpc_c_profile_all_elts rpc_c_profile_default_elt rpc_c_profile_match_by_both rpc_c_profile_match_by_if rpc_c_profile_match_by_mbr rpc_c_protect_level_call rpc_c_protect_level_connect rpc_c_protect_level_default rpc_c_protect_level_none rpc_c_protect_level_pkt rpc_c_protect_level_pkt_integ rpc_c_protect_level_pkt_privacy rpc_c_protseq_max_reqs_default rpc_s_ok rpcbase_v0_0_included volatile AUTHOR ====== A. U. Thor, a.u.thor@a.galaxy.far.far.away SEE ALSO ======== perl(1).  File: pm.info, Node: DDL/Oracle, Next: DFA/ATN, Prev: DCE/rpcbase, Up: Module List a DDL generator for Oracle databases ************************************ NAME ==== DDL::Oracle - a DDL generator for Oracle databases VERSION ======= VERSION = 1.04 SYNOPSIS ======== use DBI; use DDL::Oracle; my $dbh = DBI->connect( "dbi:Oracle:dbname", "username", "password", { PrintError => 0, RaiseError => 1 } ); # Use default resize and schema options. # query default DBA_xxx tables (could use USER_xxx for non-DBA types) DDL::Oracle->configure( dbh => $dbh, ); # Create a list of one or more objects my $sth = $dbh->prepare( "SELECT owner , table_name FROM dba_tables WHERE tablespace_name = 'MY_TBLSP' -- your mileage may vary " ); $sth->execute; my $list = $sth->fetchall_arrayref; my $obj = DDL::Oracle->new( type => 'table', list => $list, ); ); my $ddl = $obj->create; # or $obj->resize; or $obj->drop; etc. print $ddl; # Use STDOUT so user can redirect to desired file. DESCRIPTION =========== Overview -------- Designed for Oracle DBA's and users. It reverse engineers database objects (tables, indexes, users, profiles, tablespaces, roles, constraints, etc.). It generates DDL to *resize* tables and indexes to the provided standard or to a user defined standard. We originally wrote a script to defrag tablespaces, but as DBA's we regularly find a need for the DDL of a single object or a list of objects (such as all of the indexes for a certain table). So we took all of the DDL statement creation logic out of defrag.pl, and put it into the general purpose DDL::Oracle module, then expanded that to include tablespaces, users, roles, and all other dictionary objects. Oracle tablespaces tend to become fragmented (now THAT's an understatement). Even when object sizing standards are adopted, it is difficult to get 100% compliance from users. And even if you get a high degree of compliance, objects turn out to be a different size than originally thought/planned - small tables grow to become large (i.e., hundreds of extents), what was thought would be a large table ends up having only a few rows, etc. So the main driver for DDL::Oracle was the object management needs of Oracle DBA's. The "resize" method generates DDL for a list of tables or indexes. For partitioned objects, the "appropriate" size of EACH partition is calculated and supplied in the generated DDL. The original defrag.pl will be rewritten to use DDL::Oracle, and supplied with its distribution. Initialization and Constructor ------------------------------ configure The configure method is used to supply the DBI connection and to set several session level attributes. These are: dbh A reference to a valid DBI connection (obtained via DBI->connect). This is the only mandatory attribute. NOTE: The user connecting should have SELECT privileges on the following views (in addition to the DBA or USER views), but see attributes 'heading', 'blksize' and 'version' below for exceptions: V$VERSION V$DATABASE V$PARAMETER And, in order to generate CREATE SNAPSHOT LOG statements, you will also need to create a PUBLIC SYNONYM for DBA_SNAPSHOT_LOG_FILTER_COLS. In order for non-DBA users to do the same, you will need to grant SELECT on this view to them (e.g., to PUBLIC). Why Oracle Corp. feels this view is of no interest to non-replication users is a mystery to the author. And, in order to generate CREATE INDEX statements for indexes which have DESCending column(s) and/or include FUNCTION based column(s), you must have select privileges on SYS.COL$, wherein the real name of the column or function definition is held. schema Defines whether and what to use as the schema for DDL on objects which use this syntax. "1" means use the owner of the object as the schema; "0" or "" means omit the schema syntax; any other arbtrary string will be imbedded in the DDL as the schema. The default is "1". resize Defines whether and what to use in resizing segments. "1" means resize segments using the default algorithm; "0" or "" means keep the current INITIAL and NEXT values; any other string will be interpreted as a resize definition. The default is "1". To establish a user defined algorithm, define this with a string consisting of n sets of LIMIT:INITIAL:NEXT. LIMIT is expressed in Database Blocks. The highest LIMIT may contain the string 'UNLIMITED', and in any event will be forced to be so by DDL::Oracle. view Defines which Dictionary views to query: DBA or USER (e.g., DBA_TABLES or USER_TABLES). The default is DBA. heading Defines whether to include a Heading having Host, Instance, Date/Time, List of generated Objects, etc. "1" means include the heading; "0" or "" means to suppress the heading (and eliminate the query against V$DATABASE). The default is "1". blksize Defines the database block size. If this attribute is supplied, you eliminate the query against V$PARAMETER. The default is to query V$PARAMETER for this value. version A quoted string which defines the version of the database, and must be a version supported by the module (currently 7.x, 8.0 and 8.1). If this attribute is supplied, you eliminate the query against V$VERSION. The default is to query V$VERSION for this value. new The new method is the object constructor. The two mandatory object definitions are supplied with this method, to wit: type The type of object (e.g., TABLE, INDEX, SYNONYM, family, etc.). For 'table family', supply the name(s) of tables -- the DDL will include the table and its: Comments (Table and Column) Indexes Constraints Triggers list An arrayref to an array of arrayrefs (as in the DBI's "fetchall_arrayref" method) containing pairs of owner and name. Object methods -------------- create The create method generates the DDL to create the list of Oracle objects. drop The drop method generates the DDL to drop the list of Oracle objects. resize The *resize* method generates the DDL to resize the list of Oracle objects. The 'type' defined in the 'new' method is limited to 'index' and 'table'. For tables, this generates an ALTER TABLE MOVE statement; for indexes, it generates an ALTER INDEX REBUILD statement. If the table or index is partitioned, then a statement for each partition is generated. To generate DDL for a single partition of an index or table, define the 'name' as a colon delimited field (e.g., 'name:partition'). compile The compile method generates the DDL to compile the list of Oracle objects. The 'type' defined in the 'new' method is limited to 'function', 'package', 'procedure', 'trigger' and 'view'. BUGS ==== The generated DDL contains the Schema and Object Name in lower case. In the case of triggers, this will cause a problem if the "... ON ." clause is quoted. For example, a trigger on table MY_TABLE in schema ME written as '...BEFORE INSERT ON "ME"."MY_TABLE"...' will generate the DDL as '... BEFORE INSERT ON "me"."my_table"...' There are no plans to change this. FILES ===== copy_user.pl copy_user.sh ddl.pl defrag.pl query.pl AUTHOR ====== Richard V. Sutherland rvsutherland@yahoo.com COPYRIGHT ========= Copyright (c) 2000, 2001 Richard V. Sutherland. All rights reserved. This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself. See: http://www.perl.com/perl/misc/Artistic.html  File: pm.info, Node: DFA/ATN, Next: DFA/Command, Prev: DDL/Oracle, Up: Module List An augmented transition network object. *************************************** NAME ==== `DFA::ATN' - An augmented transition network object. DESCRIPTION =========== my $Obj = new DFA::ATN $Actions,[States]; This creates a powerful automaton with a finite number of individual states. It inherits many of its methods from `DFN::Simple' in this node. The object is composed of the following three things (with methods to match): State The object has a particular state it is in; a specific state from a set of possible states. *Note DFA/Simple: DFA/Simple, *State Stack* You can push a stack onto the stack, or pop one off. The register frame is saved and restored as well. Actions The object when enterring or leaving a state may perform some action. *Note DFA/Simple: DFA/Simple, Rules The object has rules for determining what its next state should be, and how to get there. *Note DFA/Simple: DFA/Simple, Registers The object has the method for storing and retrieving information about its processing. The State Stack --------------- $Obj->Save; $Obj->Restore; Save will save the current state of the automaton, including the registers. Restore will restore the automaton's previously saved state and registers. Register -------- $Obj->Register->{'name'}='fred'; Register is a method that can set or get the objects register reference. This is a information that the actions, conditions, or transitions can employ in their processing. The reference can be anything. It is otherwise not used by the object implementation. Installation ============ perl Makefile.PL make make install Author ====== Randall Maas (`randym@acm.org' in this node, `http:' in this node)  File: pm.info, Node: DFA/Command, Next: DFA/Kleene, Prev: DFA/ATN, Up: Module List A Discrete Finite Automata command processor. ********************************************* NAME ==== `DFA::Command' - A Discrete Finite Automata command processor. `DFA::Generate' - A DFA program generator. SYNOPSIS ======== use DFA::Command; $stateMachine = new DFA::Command('Name of first event'); # Or: #$stateMachine = DFA::Command -> new('Name of first event'); $stateMachine -> load('Name of STT file'); $stateMachine -> dump() if ($YouAreDebugging); $stateMachine -> process('Name of a event file'); DESCRIPTION =========== `DFA::Command' This module reads a state transition table and then reads a data file looking for patterns as defined by regular expressions in the state transition table. When a transition is detected, a sub is called. `DFA::Generate' This module reads a state transition table and generates a Perl script which uses the module `DFA::Command' to process data according to the said table. These 2 modules are installed together. The name `DFA::Command' was chosen because: * Somebody beat me to it. I wanted to use FSM (Finite State Machine) * It creates an appropriate and convenient naming structure for related packages * It installs easily in Unix, DOS and NT file systems * It was developed in an environment where the input file contained commands and non-commands INSTALLATION ============ You install `DFA::Command', as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of `DFA::Command' in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl or perl Makefile.PL LIB=C:/Perl/Site/Lib If, like me, you don't have permission to write man pages into unix system directories, use: make pure_install instead of make install. This option is secreted in the middle of p 414 of the second edition of the dromedary book. FEATURES ======== When input is recognised, and an action function is about to be called, `popEvent()' checks that the event just detected was one of those expected in the current state. Just after an action function is called, the names of those events expected next are saved by `pushEvent()', in preparation for the next call to popEvent(). This feature and the previous one add overhead to the code, but form a marvellous debugging aid. TEST SCRIPTS ============ This package contains 3 sets of test files: * Chinese * Citizen * X500 Each set of test files contains: * A state transition table. These files are called: Chinese.STT, Citizen.STT and X500DN.STT. * A data file comtaining commands to be recognized by the DFA. These files are called: Chinese.dat, Citizen.dat and X500DN.dat. * A script (1) demonstrating DFA::Generate, which when run generates a script (2) demonstrating DFA::Command. These scripts (1) are called: Chinese_Gen.pl, Citizen_Gen.pl and X500DN_Gen.pl. * A script (2) which is the output of the previous script (1). These scripts (2) are called: ChineseTest.pl, CitizenTest.pl and X500DNTest.pl. * A script (3) which is a version of (2), ie which I have generated and then modified to demonstrate some possibilities. These scripts (3) are called: Chinese.pl, Citizen.pl and X500DN.pl. * 2 log files output by these 2 scripts (2, 3). These logs are called: ChineseTest.log, Chinese.log, CitizenTest.log, Citizen.log, X500DNTest.log, X500DN.log. These scripts are all in a subdirectory called test. They are not in a subdirectory called t because the test harness does not provide for scripts to be run which generate scripts to be run. CONFIGURATION OPTIONS ===================== chomp. Chomp each input line before processing it. Default: True commentPrefix. Ignore any input lines which start with this character. If trimLeading is false, and a line starts with whitespace followed by this character, that line will still be ignored. Default: '#' ignoreBlankLines. If true, ignore input lines which are blank after any chomping. Default: True trimLeading. If true, trim leading whitespace from each input line before processing it. Default: True trimTrailing. If true, trim trailing whitespace from each input line before processing it. This takes place after any chomping. Default: True WARNING ======= Go to any lengths whatsoever to avoid '%' characters in your input, since some C compilers butcher such input. Eg: The thrice-cursed Pyramid C++ compiler. FORMAT OF A STATE TRANSITION TABLE ================================== Typically, there will be several lines for each state. These lines will differ by their event names, and the corresponding regexp which recognises the given event. Each line consists of these fields: * The name of the state. Use \w as your guideline for forming names - ie no whitespace * The regexp to be used to search for an event in the input line. In colloquial terms, this means the regexp to be used to search for the presence of a command in the input line. The arrival of this command is the event in question. Don't use whitespace within the regexp, since these lines are split on whitespace. (No package is perfect...) * The name of the event detected if the regexp fires. Use \w - ie no whitespace * The name of the action function to call if the regexp fires * The names of the events which are allowed to follow the current event. Separate event names with '|', without surrounding whitespace. Alternately, as syntactic sugar, use the special token commandList to refer to all events where the name of the state is 'commandState' Q & A ===== How do I skip input text? Use a regexp of '.*' in your state transition table. If my input is 'abcd' and I have 2 regexps, 'abc.*' and 'abcd.*', which regexp fires? Hmmm. Grammatically speaking, that is a question. Seriously tho, the order of evaluation will be the order in which keys are stored in hashes, which is not under user control. In short, you bungled it by using ambiguous regexps. DEREFERENCING GUIDELINES ======================== $self -> {$state} -> {$event} -> {'sub'} Name of subroutine $self -> {$state} -> {$event} -> {'nextState'} Name of state $self -> {$state} -> {$event} -> {'validEvents'} Event|Event $self -> {$state} -> {'RE'} [REs] $self -> {$state} -> {'event'} [Events] $self -> {'nextEvent'} [Expected events] $self -> {'state'} Current state $self -> {'event'} Current event $self -> {'command'} Current command $self -> {'RE'} Current RE $self -> {'original'} Current input line, original $self -> {'clean'} Current input line, cleaned up $self -> {'$1'} Current text matching () IN RE $self -> {'$2'} Current text matching () IN RE $self -> {'$3'} Current text matching () IN RE PROCESSING of #if defined() =========================== Reference: PC Techniques, Aug/Sep 1993, p 102, Hax 166. Unimplemented. WARNING re Perl bug =================== As always, be aware that these 2 lines mean the same thing, sometimes: * $self -> {'thing'} * $self->{'thing'} The problem is the spaces around the ->. Inside double quotes, "...", the first space stops the dereference taking place. Outside double quotes the scanner correctly associates the $self token with the {'thing'} token. I regard this as a bug. AUTHOR ====== `DFA::Command' and `DFA::Generate' were written by Ron Savage ** in 1997. ACKNOWLEDGEMENTS ================ The processing loop at the heart of this module is something I downloaded from comp.land.perl.misc circa 1994. I encourage the author to contact me. You'll know who you are: There were 2 bugs - both harmless - in 1 line of code, in the routine I call load(). Anybody who accepts responsibility for this code will be deemed to be the author. Well done! LICENCE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DFA/Kleene, Next: DFA/Simple, Prev: DFA/Command, Up: Module List Kleene's Algorithm for Deterministic Finite Automata **************************************************** NAME ==== DFA::Kleene - Kleene's Algorithm for Deterministic Finite Automata Calculates the "language" (set of words) accepted (= recognized) by a Deterministic Finite Automaton See `Math::Kleene(3)' in this node for the theory behind this algorithm! SYNOPSIS ======== * `use DFA::Kleene qw(initialize define_accepting_states' `define_delta kleene example);' * `use DFA::Kleene qw(:all);' * `&initialize(6,"ab");' Define the number of states (state #1 is the "start" state!) of your Deterministic Finite Automaton and the alphabet used (as a string containing all characters which are part of the alphabet). * `&define_accepting_states(2,3,4,5);' Define which states are "accepting states" in your Deterministic Finite Automaton (list of state numbers). * `&define_delta(1,'a',4);' Define the state transition function "delta" (arguments are: "from" state, character (or empty string!) read during the transition, "to" state). You need several calls to this function in order to build a complete transition table describing your Deterministic Finite Automaton. * `@language = &kleene();' Returns a (sorted) list of regular expressions describing the language (= set of patterns) recognized ("accepted") by your Deterministic Finite Automaton. * `&example();' Calculates the language of a sample Deterministic Finite Automaton. Prints a (sorted) list of regular expressions which should be equivalent to the following regular expression: (a(a)*b)*a(a)*(b)* This is the same as ((a+)b)*(a+)b* DESCRIPTION =========== The routines in this module allow you to define a Deterministic Finite Automaton and to compute the "language" (set of "words" or "patterns") accepted (= recognized) by it. Actually, a list of regular expressions is generated which describe the same language (set of patterns) as the one accepted by your Deterministic Finite Automaton. The output generated by this module can easily be modified to produce Perl-style regular expressions which can actually be used to recognize words (= patterns) contained in the language defined by your Deterministic Finite Automaton. Other modules in this series (variants of Kleene's algorithm): * Math::MatrixBool (see "Kleene()") * Math::MatrixReal (see "kleene()") SEE ALSO ======== Math::MatrixBool(3), Math::MatrixReal(3), Math::Kleene(3), Set::IntegerRange(3), Set::IntegerFast(3), Bit::Vector(3). VERSION ======= This man page documents "DFA::Kleene" version 1.0. AUTHOR ====== Steffen Beyer . COPYRIGHT ========= Copyright (c) 1996, 1997 by Steffen Beyer. All rights reserved. LICENSE ======= This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DFA/Simple, Next: DNS/ZoneFile, Prev: DFA/Kleene, Up: Module List A PERL module to implement simple Discrete Finite Automata ********************************************************** NAME ==== `DFA::Simple' - A PERL module to implement simple Discrete Finite Automata SYNOPSIS ======== my $Obj = new DFA::Simple or my $Obj = new DFA::Simple $Transitions; or my $Obj = new DFA::Simple $Actions, $StateRules; $Obj->Actions = [...]; my $Trans = $LP->Actions; $Obj->StateRules = [...]; my $StateRules = $LP->StateRules; DESCRIPTION =========== my $Obj = new DFA::Simple $Actions,[States]; This creates a simple automaton with a finite number of individual states. The object is composed of the following three things (with methods to match): State The object has a particular state it is in; a specific state from a set of possible states Actions The object when enterring or leaving a state may perform some action. Rules The object has rules for determining what its next state should be, and how to get there. State ----- State is a method that can get the current state or initiate a transition to a new state. my $S = $Obj->State; $Obj->State = $NewState; The last one leaves the current state and goes to the specified *NewState*. If the current state is defined, its *StateExitCodeRef* will be called (see below). Then the new states *StateEnterCodeRef* will be called (if defined) (see below). Cavaet, no check is made to see if the new state is the same as the old state; this can be used to `reset' the state. Actions ------- Actions is a method that can set or get the objects list of actions to perform when enterring or leaving a particular state. my $Actions = $Obj->Actions; $Obj->Actions = [ [StateEnterCodeRef, StateExitCodeRef], ]; I is an array reference describing what to do when enterring and leaving various states. When a state is entered, its I will be called (if defined). When a state is left (as in going to a new state) its I will be called (if defined). StateRules ---------- my $StateRules = [ #Rules for state 0 [ [NextState, Test, Thing to do after getting there ], #Rules for state 1 [ ... ], ]; Installation ============ perl Makefile.PL make make install Author ====== Randall Maas (`randym@acm.org' in this node, `http:' in this node)