September 26, 2024: PostgreSQL 17 Released!
Unsupported versions: 7.2 / 7.1
This documentation is for an unsupported version of PostgreSQL.
You may want to view the same page for the current version, or one of the other supported versions listed above instead.

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