# AttachEnvelope

Attaches an envelope to an instrument and creates an attachment item.

### Synopsis

`Item AttachEnvelope (Item Instrument, Item Envelope, char *EnvName)`

### Description

This function attaches the specified envelope to the specified instrument and creates an attachment item. The attachment point (the hook) must be specified by name, as instruments may have multiple places where envelopes can be attached.

An instrument may, for example, have an amplitude envelope and a filter envelope, which may be called AmpEnv and FilterEnv respectively. The simple

envelope.dsp instrument has a hook name of Env. You'll find hook names in the Instrument Templates chapter of this book. Note that if EnvName is set to NULL, the Audio folio will look for "Env" as a default.

You may use the same envelope for several instruments. The envelope data may be edited at any time, but be aware that it is read by a high priority task in the Audio folio. Thus you should not leave it in a potentially "goofy" state if it is actively used.

When you finish, you should call `DetachEnvelope()` to delete the attachment and free its resources.

### Arguments

Instrument
  The item number of the instrument to which to attach the Envelope.

Envelope
  The item number of the envelope to be attached.

EnvName
  The name of the attachment point (hook). Can be NULL, in which case an Envelope Hook named "Env" is used.

### Return Value

The function returns the item number of the Attachment created (a positive value) or an error code (a negative value) if an error occurs.

### Implementation

Folio call implemented in Audio folio V20.

### Associated Files

audio.h

### Caveat

Prior to V24, EnvName == NULL was not supported.

### See Also

``DetachEnvelope`(), CreateEnvelope(), envelope.dsp`