Input, output, actions

Work with DB-ALLe happens using action routines. An action routine typically reads some input, performs an action and produces some output. Example of action routines are idba_voglioquesto to query data from a database and idba_prendilo to write data into the database.

The input and the output of action routines are collections of parameters which have a name and a value. A list of parameters can be found in A.1.

You can set the input parameters using the idba_set* functions:

idba_seti(handle, "param", intvalue)

Set the input parameter to the integer value intvalue

idba_setc(handle, "param", charvalue)

Set the input parameter to the character value charvalue

idba_setr(handle, "param", realvalue)

Set the input parameter to the real value realvalue

idba_setd(handle, "param", doublevalue)

Set the input parameter to the real*8 value doublevalue

You can read the output parameters using the idba_enq* functions:

idba_enqi(handle, "param", intvalue)

Read the output parameter into the integer value intvalue

idba_enqc(handle, "param", charvalue)

Read the output parameter into the character value charvalue

idba_enqr(handle, "param", realvalue)

Read the output parameter into the real value realvalue

idba_enqd(handle, "param", doublevalue)

Read the output parameter into the real*8 value doublevalue

Note that all idba_set functions set input parameters, while all idb_enq* functions read output parameters. You cannot read input parameters or set output parameters: that is the job of action routines.

In other words, input and output parameters are different things. In this code:

c     A possible misunderstanding
      call idba_seti(handle, "height", 1)
      call idba_enqi(handle, "height", val)

the value of val after the idba_enqi will not probably be 1, and it could be either a value indicating ``missing value'' (in case no height parameter is set in the output parameters) or a height value previously retrieved by an action routine.

To reset one input parameter you can use idba_unset:

c     ...
c     We don't want to limit results by latitude this time
      call idba_unset(handle, "latmin")
      call idba_unset(handle, "latmax")
      call idba_voglioquesto(handle, count)

Alternatively, you can reset an input parameter by setting it to one of the special ``missing value'' values listed below.

To reset all input parameters you can use idba_unsetall:

c     Restart the query from scratch
      call idba_unsetall(handle)
      call idba_setd(handle, "latmin", 10.D0)
c     ...

There is no way to reset output parameters: it is not needed since all action routines will get rid of old output values before producing new ones.

In case one of the idba_enq* functions is called on a parameter which does not exist, it will return a special value that indicates ``missing value''. This is a list of such special values:

Data type	Missing value indicator
String	""
Int	0x7fffffff
Real	-1.1754944E-38
Double	-2.22507E-308