PEAR Manual
Prev |  | Next

# DB_common::nextId()

DB_common::nextId() -- Returns the next number from a sequence

## Synopsis

``integer nextId` (string $seq_name, boolean `$onDemand = `TRUE``)`

## Description

Returns the next available number from a sequence. The sequence is automatically incremented each time this method is called.

See "Intro - Sequences" for a more complete discusion.

## Parameter

string `$seq_name`

  name of the sequence

  To avoid problems with various database systems, sequence names should start with a letter and only contain letters, numbers and the underscore character.

boolean `$onDemand`

  When `TRUE`, the sequence is automatically created if it does not exist yet.

  The on demand creation process necessitates the database user specified in the script having the database permissions needed to create a table or sequence. The exact privileges involved depends on the DBMS being used.

## Return value

integer - a free id number or a DB_Error object on failure

## Throws

Table 33-1. Possible PEAR_Error values

Error code | Error message | Reason | Solution
--- | --- | --- | ---
`DB_ERROR_NOT_CAPABLE` | DB backend not capable | Function is not supported by the database backend | Switch to another database system, if you really need this feature.
`DB_ERROR_NOT_LOCKED` | not locked | Locking of sequence table fails | Database specific, check documentation of your database,
`DB_ERROR_NOSUCHTABLE` | no such table | Sequence table was not found | Try to create a new sequence or if you are sure, a sequence was already create, check database integrity

## Note

This function can not be called statically.

Warning
When using PEAR DB's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR DB's methods to access sequences that were created directly in the DBMS. See the warning on the "Intro - Sequences" page complete information.

## Example

Example 33-1. Using nextId()
    <?php
    // Once you have a valid DB object named $db...
    $id = $db->nextId('mySequence');
    if (PEAR::isError($id)) {
        die($id->getMessage());
    }

    // Use the ID in your INSERT query
    $res =& $db->query("INSERT INTO myTable (id, text) VALUES ($id, 'foo')");
    ?>

## See

"Intro - Sequences", createSequence(), dropSequence()

Prev | Home | Next
DB_common::limitQuery() | Up | DB_common::prepare()