Query Execution Functions

PostgreSQL 7.2 Documentation
Prev | Chapter 3. libpq++ - C++ Binding Library | Next

# 3.5. Query Execution Functions

## 3.5.1. Main Routines

- `Exec` sends a command to the backend server. It's probably more desirable to use one of the next two functions.

      ExecStatusType PgConnection::Exec(const char* query)

  Returns the result status of the command. The following status results can be expected:

  `PGRES_EMPTY_QUERY`
  `PGRES_COMMAND_OK`, if the command was not a query
  `PGRES_TUPLES_OK`, if the query successfully returned tuples
  `PGRES_COPY_OUT`
  `PGRES_COPY_IN`
  `PGRES_BAD_RESPONSE`, if an unexpected response was received
  `PGRES_NONFATAL_ERROR`
  `PGRES_FATAL_ERROR`

- `ExecCommandOk` sends a non-query command (one that does not return rows) to the backend server.

      int PgConnection::ExecCommandOk(const char *query)

  Returns true (1) if the command succeeds.

- `ExecTuplesOk` Sends a query command (one that returns rows) to the backend server.

      int PgConnection::ExecTuplesOk(const char *query)

  Returns true (1) if the query succeeds.

- `ErrorMessage` returns the last error message text.

      const char *PgConnection::ErrorMessage()

## 3.5.2. Retrieving SELECT Result Information

- `Tuples` returns the number of tuples (rows) in the query result.

      int PgDatabase::Tuples() const

- `Fields` returns the number of fields (rows) in each tuple of the query result.

      int PgDatabase::Fields()

- `FieldName` returns the field (column) name associated with the given field index. Field indices start at 0.

      const char *PgDatabase::FieldName(int field_num) const

- `FieldNum` returns the field (column) index associated with the given field name.

      int PgDatabase::FieldNum(const char* field_name) const

  -1 is returned if the given name does not match any field.

- `FieldType` returns the field type associated with the given field index. The integer returned is an internal coding of the type. Field indices start at 0.

      Oid PgDatabase::FieldType(int field_num) const

- `FieldType` returns the field type associated with the given field name. The integer returned is an internal coding of the type. Field indices start at 0.

      Oid PgDatabase::FieldType(const char* field_name) const

- `FieldSize` returns the size in bytes of the field associated with the given field index. Field indices start at 0.

      int PgDatabase::FieldSize(int field_num) const

  Returns the space allocated for this field in a database tuple given the field number. In other words the size of the server's binary representation of the data type. -1 is returned if the field is variable size.

- `FieldSize` returns the size in bytes of the field associated with the given field index. Field indices start at 0.

      int PgDatabase::FieldSize(const char *field_name) const

  Returns the space allocated for this field in a database tuple given the field name. In other words the size of the server's binary representation of the data type. -1 is returned if the field is variable size.

## 3.5.3. Retrieving SELECT Result Values

- `GetValue` returns a single field (column) value of one tuple of a `PGresult`. Tuple and field indices start at 0.

      const char *PgDatabase::GetValue(int tup_num, int field_num) const

  For most queries, the value returned by `GetValue` is a null-terminated string representation of the attribute value. But if `BinaryTuples` is true, the value returned by `GetValue` is the binary representation of the type in the internal format of the backend server (but not including the size word, if the field is variable-length). It is then the programmer's responsibility to cast and convert the data to the correct C type. The pointer returned by `GetValue` points to storage that is part of the `PGresult` structure. One should not modify it, and one must explicitly copy the value into other storage if it is to be used past the lifetime of the `PGresult` structure itself. `BinaryTuples` is not yet implemented.

- `GetValue` returns a single field (column) value of one tuple of a `PGresult`. Tuple and field indices start at 0.

      const char *PgDatabase::GetValue(int tup_num, const char *field_name) const

  For most queries, the value returned by `GetValue` is a null-terminated string representation of the attribute value. But if `BinaryTuples` is true, the value returned by `GetValue` is the binary representation of the type in the internal format of the backend server (but not including the size word, if the field is variable-length). It is then the programmer's responsibility to cast and convert the data to the correct C type. The pointer returned by `GetValue` points to storage that is part of the `PGresult` structure. One should not modify it, and one must explicitly copy the value into other storage if it is to be used past the lifetime of the `PGresult` structure itself. `BinaryTuples` is not yet implemented.

- `GetLength` returns the length of a field (column) in bytes. Tuple and field indices start at 0.

      int PgDatabase::GetLength(int tup_num, int field_num) const

  This is the actual data length for the particular data value, that is the size of the object pointed to by `GetValue`. Note that for character-represented values, this size has little to do with the binary size reported by `PQfsize`.

- `GetLength` returns the length of a field (column) in bytes. Tuple and field indices start at 0.

      int PgDatabase::GetLength(int tup_num, const char* field_name) const

  This is the actual data length for the particular data value, that is the size of the object pointed to by `GetValue`. Note that for character-represented values, this size has little to do with the binary size reported by `PQfsize`.

- `GetIsNull` returns whether a field has the null value.

      bool GetIsNull(int tup_num, int field_num) const

  Note that `GetValue` will return the empty string for null fields, not the NULL pointer.

- `GetIsNull` returns whether a field has the null value.

      bool GetIsNull(int tup_num, const char *field_name) const

  Note that `GetValue` will return the empty string for null fields, not the NULL pointer.

- `DisplayTuples` prints out all the tuples and, optionally, the attribute names to the specified output stream.

      void PgDatabase::DisplayTuples(FILE *out = 0, bool fillAlign = true,
      const char* fieldSep = "|", bool printHeader = true, bool quiet = false) const

  This function is obsolescent.

- `PrintTuples` prints out all the tuples and, optionally, the attribute names to the specified output stream.

      void PgDatabase::PrintTuples(FILE *out = 0, bool printAttName = true,
      bool terseOutput = false, bool fillAlign = false) const

  This function is obsolescent.

## 3.5.4. Retrieving Non-SELECT Result Information

- `CmdTuples` returns the number of rows affected after an INSERT, UPDATE, or DELETE. If the command was anything else, it returns -1.

      int PgDatabase::CmdTuples() const

- `OidStatus`

      const char *PgDatabase::OidStatus() const

Prev | Home | Next
Database Connection Functions | Up | Asynchronous Notification