# Using Probes

A Probe is an item that gives a program access to the output of a DSP instrument. It is sort of like the opposite of a knob. Multiple probes can be connected to a single output. A probe does not interfere with a connection between instruments.

## Creating Probes

You can create a probe for any named output of any DSP instrument using this call:

  `Item CreateProbe( Item Instrument, const char *Name, const TagArg *Tags )
  Item CreateProbeVA( Item Instrument, const char *Name, uint32 tag1, ... )`

`CreateProbe()` accepts three arguments: `Item`, the Item number of the instrument; `Name`, the name of the output; and `Tags`, which should be a NULL pointer because there are currently no tag arguments defined for Probes. The call creates a Probe item that provides a fast connection between a task and one of an instrument's outputs. You can then call `ReadProbe()` to poll the value of output. When you finish with the probe item, you should call `DeleteProbe()` to deallocate the item.

`CreateProbe()` returns the item number of the probe if successful, or an error code (a negative value) if an error occurs.

## Reading Probes

You can read the most recent value of an output for which you have created a Probe. To do so, use the `ReadProbe()` call:

  `Err ReadProbe( Item ProbeItem, int32 *ValuePtr )`

The call accepts two arguments: `ProbeItem`, the Item number of the knob to be tweaked; and `ValuePtr`, a pointer to where to put result. The task must have write permission for the address specified by `ValuePtr`.

`ReadProbe()` reads the instantaneous value of an instrument output. It is useful for reading the output of slowly changing instruments such as `envelope.dsp`, `envfollower.dsp`, `minimum.dsp`, and `maximum.dsp`. It replaces the now obsolete function `DSPReadEO()`.

`ReadProbe()` returns a non-negative value if successful, or an error code ( a negative value) if unsuccessful.

## Deleting Probes

When you are finished using a Probe, you should delete it with this call:

  `Err DeleteProbe( Item ProbeItem )`

The call accepts one argument: `ProbeItem`, the Item number of the Probe to delete. `DeleteProbe()` deletes the probe item created by `CreateProbe()`, freeing its resource and disconnecting the task that created the probe item from the instrument containing the probe.

`DeleteProbe()` returns a non-negative value if successful, or an error code ( a negative value) if an error occurs.