Function File: pq_exec_params (connection, command)
Loadable Function: pq_exec_params (connection, command, params)
Loadable Function: pq_exec_params (connection, command, settings)
Loadable Function: pq_exec_params (connection, command, params, settings)

Sends the string command, which must contain a single SQL command, over the connection connection. Parameters in command can be replaced by $1, $2, etc and their values given in the one-dimensional cell-array params. Parameters of composite type sent this way must have their type defined in the database. For typeconversions, the package maintains a notion of defined types, which should be refreshed with pq_update_types if types are defined or dropped after establishing the connection, or if the schema search path changes. settings is a structure of settings, it can be created by setdbopts.

Settings currently understood by pq_exec_params:

param_types

One-dimensional cell-array with type specifications for parameters in params. If present, must have the same length as params. Entries may be empty if no specification is necessary (see below). Type specifications are strings corresponding to the entries returned by SELECT typname FROM pg_type WHERE typarray != 0 OR typtype = 'c';, optionally having [] appended (without space) to indicate an array. Type specifications can be schema-qualified, otherwise they refer to the visible type with that name.

copy_in_path, copy_out_path

Path to files at the client side for copy from stdin and copy to stdout, respectively.

copy_in_from_variable

Logical scalar, default false. If true, copy from stdin uses data from an Octave variable instead of from a file.

copy_in_data

2-dimensional cell-array with columns of suitable type (see below) – will be used instead of a file as data for copy from stdin if copy_in_from_variable is true.

copy_in_types

If some columns in copy_in_data need a type specification (see below), copy_in_types has to be set to a cell-array with type specifications, with an entry (possibly empty) for each column.

copy_in_with_oids

If you want to copy in with oids when using data from an Octave variable, the first column of the data must contain the OIDs and copy_in_with_oids has to be set to true (default false); with oids should be specified together with copy from stdin in the command, otherwise Postgresql will ignore the copied oids.

There is no way to copy to stdout into an Octave variable, but a select command can be used for this purpose.

copy from stdin from an Octave variable is only supported in binary mode, so this has to be specified in the SQL command.

The output depends on the type of command.

  • queries (commands potentially returning data): The output will be a structure with fields data (containing a cell array with the data, columns correspond to returned database columns, rows correspond to returned tuples), columns (containing the column headers), and types (a structure-vector with the postgresql data types of the columns, subfields name (string with typename), is_array (boolean), is_composite (boolean), is_enum (boolean), and elements (if is_composite == true, structure-vector of element types, containing fields corresponding to those of types)).
  • copy commands: Nothing is returned (this may change in the future).
  • other commands: The output will be the number of affected rows in the database.

For the mapping of currently implemented Postgresql types to Octave types, type database_doc ("Postgresql data types").

See also: pq_update_types, pq_conninfo.

Package: database