Skip navigation links
2.3.18 The NdbScanOperation Class »
Section Navigation      [Toggle]

2.3.17.2. NdbScanFilter Methods

[+/-]

2.3.17.2.1. NdbScanFilter Class Constructor
2.3.17.2.2. NdbScanFilter::begin()
2.3.17.2.3. NdbScanFilter::end()
2.3.17.2.4. NdbScanFilter::istrue()
2.3.17.2.5. NdbScanFilter::isfalse()
2.3.17.2.6. NdbScanFilter::cmp()
2.3.17.2.7. NdbScanFilter Integer Comparison Methods
2.3.17.2.8. NdbScanFilter::isnull()
2.3.17.2.9. NdbScanFilter::isnotnull()
2.3.17.2.10. NdbScanFilter::getNdbError()
2.3.17.2.11. NdbScanFilter::getNdbOperation()

Abstract

This section lists and describes the public methods of the NdbScanFilter class.

2.3.17.2.1. NdbScanFilter Class Constructor

Description.  This is the constructor method for NdbScanFilter, and creates a new instance of the class.

Signature.  

NdbScanFilter
    (
      class NdbOperation* op
    )

Parameters.  This method takes a single parameter: a pointer to the NdbOperation to which the filter applies.

Return value.  A new instance of NdbScanFilter.

Destructor.  The destructor takes no arguments and does not return a value. It should be called to remove the NdbScanFilter object when it is no longer needed.

2.3.17.2.2. NdbScanFilter::begin()

Description.  This method is used to start a compound, and specifies the logical operator used to group together the conditions making up the compound. The default is AND.

Signature.  

int begin
    (
      Group group = AND
    )

Parameters.  A Group value: one of AND, OR, NAND, or NOR. See Section 2.3.17.1.2, “The NdbScanFilter::Group Type”, for additional information.

Return value.  0 on success, -1 on failure.

2.3.17.2.3. NdbScanFilter::end()

Description.  This method completes a compound, signalling that there are no more conditions to be added to it.

Signature.  

int end
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.17.2.4. NdbScanFilter::istrue()

Description.  Defines a term of the current group as TRUE.

Signature.  

int istrue
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.17.2.5. NdbScanFilter::isfalse()

Description.  Defines a term of the current group as FALSE.

Signature.  

int isfalse
    (
      void
    )

Parameters.  None.

Return value.  0 on success, -1 on failure.

2.3.17.2.6. NdbScanFilter::cmp()

Description.  This method is used to perform a comparison between a given value and the value of a column.

Note

In many cases, where the value to be compared is an integer, you can instead use one of several convenience methods provided by NdbScanFilter for this purpose. See Section 2.3.17.2.7, “NdbScanFilter Integer Comparison Methods”.

Signature.  

int cmp
    (
      BinaryCondition condition,
      int columnId,
      const void* value,
      Uint32 length = 0
    )

Parameters.  This method takes the following parameters:

  • condition: This represents the condition to be tested which compares the value of the column having the column ID columnID with some arbitrary value. The condition is a BinaryCondition value; for permitted values and the relations that they represent, see Section 2.3.17.1.1, “The NdbScanFilter::BinaryCondition Type”.

    The condition values COND_LIKE or COND_NOTLIKE are used to compare a column value with a string pattern.

  • columnId: This is the column's identifier, which can be obtained using the Column::getColumnNo() method (see Section 2.3.1.2.5, “Column::getColumnNo()”, for details).

  • value: The value to be compared, repesented as a pointer to void.

    Using using a COND_LIKE or COND_NOTLIKE comparison condition, the value is treated as a string pattern which can include the pattern metacharacters or “wildcard” characters % and _, which have the meanings shown here:

    Metacharacter Description
    % Matches zero or more characters
    _ Matches exactly one character

    To match against a literal “%” or “_” character, use the backslash (\) as an escape character. To match a literal “\” character, use \\.

    Note

    These are the same wildcard characters that are supported by the SQL LIKE and NOT LIKE operators, and are interpreted in the same way. See String Comparison Functions, for more information.

  • length: The length of the value to be compared. The default value is 0. Using 0 for the length has the same effect as comparing to NULL, that is using the isnull() method (see Section 2.3.17.2.8, “NdbScanFilter::isnull()”).

Return value.  This method returns an integer whose value can be interpreted as shown here:

  • 0: The comparison is true.

  • -1: The comparison is false.

2.3.17.2.7. NdbScanFilter Integer Comparison Methods

[+/-]

2.3.17.2.7.1. NdbScanFilter::eq()
2.3.17.2.7.2. NdbScanFilter::ne()
2.3.17.2.7.3. NdbScanFilter::lt()
2.3.17.2.7.4. NdbScanFilter::le()
2.3.17.2.7.5. NdbScanFilter::gt()
2.3.17.2.7.6. NdbScanFilter::ge()

This section provides information about several convenience methods which can be used in lieu of the NdbScanFilter::cmp() method when the arbitrary value to be compared is an integer. Each of these methods is essentially a wrapper for cmp() that includes an appropriate value of BinaryCondition for that method's condition parameter; for example, NdbScanFilter::eq() is defined like this: 

int eq(int columnId, Uint32 value)
{
  return cmp(BinaryCondition::COND_EQ, columnId, &value, 4);
}

For more information about the cmp() method, see Section 2.3.17.2.6, “NdbScanFilter::cmp()”.

2.3.17.2.7.1. NdbScanFilter::eq()

Description.  This method is used to perform an equality test on a column value and an integer.

Signature.  

int eq
    (
      int    ColId,
      Uint32 value
    )

or 

int eq
    (
      int    ColId,
      Uint64 value
    )

Parameters.  This method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.7.2. NdbScanFilter::ne()

Description.  This method is used to perform an inequality test on a column value and an integer.

Signature.  

int ne
    (
      int    ColId,
      Uint32 value
    )

or 

int ne
    (
      int    ColId,
      Uint64 value
    )

Parameters.  Like eq() and the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.7.3. NdbScanFilter::lt()

Description.  This method is used to perform a less-than (strict lower bound) test on a column value and an integer.

Signature.  

int lt
    (
      int    ColId,
      Uint32 value
    )

or 

int lt
    (
      int    ColId,
      Uint64 value
    )

Parameters.  Like eq(), ne(), and the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.7.4. NdbScanFilter::le()

Description.  This method is used to perform a less-than-or-equal test on a column value and an integer.

Signature.  

int le
    (
      int    ColId,
      Uint32 value
    )

or 

int le
    (
      int    ColId,
      Uint64 value
    )

Parameters.  Like the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.7.5. NdbScanFilter::gt()

Description.  This method is used to perform a greater-than (strict upper bound) test on a column value and an integer.

Signature.  

int gt
    (
      int    ColId,
      Uint32 value
    )

or 

int gt
    (
      int    ColId,
      Uint64 value
    )

Parameters.  Like the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.7.6. NdbScanFilter::ge()

Description.  This method is used to perform a greater-than-or-equal test on a column value and an integer.

Signature.  

int ge
    (
      int    ColId,
      Uint32 value
    )

or 

int ge
    (
      int    ColId,
      Uint64 value
    )

Parameters.  Like eq(), lt(), le(), and the other NdbScanFilter methods of this type, this method takes two parameters:

  • The ID (ColId) of the column whose value is to be tested

  • An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return value.  0 on success, -1 on failure.

2.3.17.2.8. NdbScanFilter::isnull()

Description.  This method is used to check whether a column value is NULL.

Signature.  

int isnull
    (
      int ColId
    )

Parameters.  The ID of the column whose value is to be tested.

Return value.  0 if the value is NULL.

2.3.17.2.9. NdbScanFilter::isnotnull()

Description.  This method is used to check whether a column value is not NULL.

Signature.  

int isnotnull
    (
      int ColId
    )

Parameters.  The ID of the column whose value is to be tested.

Return value.  0 if the value is not NULL.

2.3.17.2.10. NdbScanFilter::getNdbError()

Description.  Because errors encountered when building an NdbScanFilter do not propagate to any involved NdbOperation object, it is necessary to use this method to access error information.

Signature.  

const NdbError& getNdbError
    (
      void
    )

Parameters.  None.

Return value.  A reference to an NdbError. See Section 2.3.31, “The NdbError Structure”, for more information.

2.3.17.2.11. NdbScanFilter::getNdbOperation()

Description.  If the NdbScanFilter was constructed with an NdbOperation, this method can be used to obtain a pointer to that NdbOperation object.

Signature.  

NdbOperation* getNdbOperation
    (
      void
    )

Parameters.  None.

Return value.  A pointer to the NdbOperation associated with this NdbScanFilter, if there is one. Otherwise, NULL.