NAME

DBIx::OracleSequence - interface to Oracle sequences via DBI.

DESCRIPTION

DBIx::OracleSequence is an object oriented interface to Oracle Sequences via DBI. A sequence is an Oracle database object from which multiple users may generate unique integers. You might use sequences to automatically generate primary key values. See http://technet.oracle.com/doc/server.815/a68003/01_03sch.htm#1203 for the full story on Oracle sequences. Note that you must register to access this URL, but registration is free.

SYNOPSIS

    use DBIx::OracleSequence;

    $oracleDbh = DBI->connect("dbi:Oracle:SID", 'login', 'password');

    my $seq = new DBIx::OracleSequence($oracleDbh,'my_sequence_name');

    $seq->create();                 # create a new sequence with default parms
    $seq->incrementBy(5);           # alter the seq to increment by 5

    my $nextVal = $seq->nextval();  # get the next sequence value
    my $currval = $seq->currval();  # retrieve the current sequence value
    $seq->print();                  # print information about the sequence

    # connect to a sequence that already exists
    my $seq2 = new DBIx::OracleSequence($oracleDbh,'preexisting_seq');
    $seq2->print();
    $seq2->drop();                  # get rid of it

    # see if sequence name 'foo' exists
    my $seq3 = new DBIx::OracleSequence($oracleDbh);
    die "Doesn't exist!\n" unless $seq3->sequenceNameExists('foo');
    $seq3->name('foo');             # attach to it
    $seq3->print;

NOTE

The constructor is lazy, so if you want to alter the defaults for a sequence, you need to use the maxvalue(), cache(), incrementBy(), etc. methods after constructing your sequence.

You can access an existing Oracle sequence by calling the constructor with the existing sequence name as the second parameter. To create a new sequence, call the constructor with your new sequence name as the second parameter, then call the create() method.

The OracleSequence object holds no state about the Oracle sequence (well, except for its name.) Instead it just serves as a passthrough to the Oracle DDL to create, drop, and set and get information about a sequence.

METHODS

• new($dbh,$S) - construct a new sequence with name $S

• new($dbh) - construct a new sequence without naming it yet

• name($S) - set the sequence name

• name() - get the sequence name

• create() - create a new sequence. Must have already called new(). Sequence will start with 1.

• create($N) - create a new sequence. Must have already called new(). Sequence will start with $N

• currval() - return the current sequence value. Note that for a brand new sequence, Oracle requires one reference to nextval before currval is valid.

• nextval() - return the next sequence value

• reset() - drop and recreate the sequence with default parms

• incrementBy($N) - alter sequence to increment by $N

• incrementBy() - return the current sequence's INCREMENT_BY value

• maxvalue($N) - alter sequence setting maxvalue to $N

• maxvalue() - return the current sequence's maxvalue

• minvalue($N) - alter sequence setting minvalue to $N

• minvalue() - return the current sequence's minvalue

• cache($N) - alter sequence to cache the next $N values

• cache() - return the current sequence's cache size

• nocache() - alter sequence to not cache values

• cycle('Y')/cycle('N') - alter sequence to cycle/not cycle after reaching maxvalue instead of returning an error. Note that cycle('N') and nocycle() are equivalent.

• cycle() - return the current sequence's cycle flag

• nocycle() - alter sequence to return an error after reaching maxvalue instead of cycling

• order('Y')/order('N') - alter sequence to guarantee/not guarantee that sequence numbers are generated in the order of their request. Note that order('N') and noorder() are equivalent.

• order() - return current sequence's order flag

• noorder() - alter sequence to not guarantee that sequence numbers are generated in order of request

• sequenceNameExists() - return 0 if current sequence's name does not already exist as a sequence name, non-zero if it does

• sequenceNameExists($S) - return 0 if $S does not exist as a sequence name, non-zero if it does

• getSequencesAref() - return an arrayRef of all existing sequence names in the current schema

• printSequences() - print all existing sequence names in the current schema

• info() - return a string containing information about the sequence

• print() - print a string containing information about the sequence

• drop() - drop the sequence

COPYRIGHT

Copyright (c) 1999 Doug Bloebaum. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Doug Bloebaum <bloebaum@dma.org>