database_doc: pq_exec_params

Next: pq_update_types, Up: Data exchange [Index]

#### 6.3.1 Issuing SQL commands

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.

  See also: pq_update_types, pq_conninfo.

#### Type mapping

For the mapping of currently implemented Postgresql types to Octave types, see Postgresql data types.

Next: pq_update_types, Up: Data exchange [Index]