# AdoptInstrument

Adopt an abandoned instrument.

### Synopsis

`Item AdoptInstrument (Item instrumentTemplate)`

### Description

This function adopts an instrument from this template's abandoned instrument pool (finds an instrument belonging to the template whose status is AF_ABANDONED). It then sets the instrument state to AF_STOPPED and returns the instrument item number. If the template has no abandoned instruments, this function returns 0.

Note that this function does not create a new Instrument Item; it returns an Instrument Item that was previously passed to `AbandonInstrument()` (or became abandoned because AF_INSF_AUTOABANDON was set).

This function together with `AbandonIntrument()` form a simple, but efficient, voice allocation system for a single instrument Template.

### Arguments

instrumentTemplate
  The item number for the instrument template from which to attempt to adopt an instrument.

### Return Value

>0
  Instrument Item number if an instrument could be adopted.

0
  If no abandoned instruments in template.

<0
  Error code on failure.

### Implementation

SWI implemented in Audio folio V20.

### Associated Files

audio.h

### See Also

``AbandonInstrument`(), GetAudioItemInfo(), Instrument`