.TH PUTAMCMD 3  MIDI
.UC 4
.SH NAME
putamcmd, flushamcmd \- write MPU data asynchronously
.SH SYNOPSES
cc ... -lmidi
.br
#include <midi.h>
.sp 4p
.nf
long Onowa;		/* time of last command actually output */
.sp 4p
long putamcmd(fp, mp) 
FILE *fp;
MCMD *mp;
.sp 4p
flushamcmd(fp)
FILE *fp;
.fi
.SH DESCRIPTION
These routines are written to work with those described in getmcmd(3).
In particular, see the manual entry for those commands for a description
of the MCMD structure.
.PP
The call \fIputamcmd(fp, mp)\fP
buffers midi command \fI*mp\fP to be written (eventually)
to file descriptor \fIfp\fP.
The time (mp->when) may be any value equal to or greater than \fIOnowa\fP.
The commands being buffered are only written when \fIflushamcmd()\fP is
called or the buffer fills up (in which case \fIputamcmd()\fP calls
\fIflushamcmd()\fP to make room).
\fIPutamcmd()\fP returns the ``real'' output MPU clock
(identical to \fIOnowa\fP, the time of the last command actually written).
This can be used as a low limit for values of mp->when;
commands sent to \fIputamcmd()\fP with mp->when values less than \fIOnowa\fP
will be output with mp->when set to \fIOnowa\fP.
.PP
There are several special argument conventions:
.Cs
putamcmd((FILE *) 0, mp)		/* set Onowa to mp->when */
putamcmd((FILE *) 0, (MCMD *) 0)	/* set Onowa to 0L */
.Ce
Also see getmcmd(3) for definitions of Rt_tcwme & Mpu_nop.
.PP
The routine \fIflushamcmd()\fP sorts and writes out all buffered
commands in chronological order, resetting the buffers to their empty state,
but leaving \fIOnowa\fP correctly set (probably not to 0).
.PP
An example of using \fIgetmcmd()\fP and \fIputamcmd()\fP
to perturb the time values in a MPU stream by \(+- 30 MPU clocks
(\(+- a sixteenth note):
.Cs
	long now = 0L, limit = 0L;
	MCMD *mp;

	while (mp = getmcmd(stdin, now)) {
	    now = mp->when;
	    mp->when += (rand() % 29) - (rand() % 29);
	    if (mp->when < limit)
		mp->when = limit;
	    limit = putamcmd(stdout, mp);
	}
	flushamcmd(stdout);
.Ce
.SH "SEE ALSO"
getmcmd(3)
.SH AUTHOR
Peter Langston, Bell Communications Research
(bellcore!psl)