Play

(Engine-Level Function)

Description:	Plays a multimedia sound file as installed in the operating system. It differs from Sound in that it is a steady-state statement and is supported by VTScada Internet Client (VIC).
Returns:	Boolean. See comments.
Usage:	Steady State only.
Function Groups:	Speech and Sound
Related to:	Sound
Format:	Play(File, Option, Enable [, DevID])
Parameters:

File

Required. Any text expression giving the file name to play. If the extension is omitted, the default extension ".WAV" is added. If an empty string is provided here, then any currently playing sound is stopped.

Option

Required. Any numeric expression that indicates how to play the file. The value of Option may be obtained by adding together numbers from the following table:

Value	Bit No.	Option
1	0	Play asynchronously (don't wait)
2	1	Don't use default sound if file missing.
4	2	Reserved for future use.
8	3	Loop the sound until next Sound function executed.
16	4	Don't stop any currently playing sound.

If Option is "0", VTScada will halt all execution until the sound is finished. This is not recommended. Add "1" to avoid this behavior.

(See: Bitwise Parameters & Operations)

Enable

Required. A value indicating whether the sound is played. This can be one of:

Value	Description
1	Sound is played.
0 or Invalid	The sound being played is stopped.

DevID

An optional parameter that is required when you wish to play a sound through a device other than the default system audio device. The ModemDev function can return the identifier of the wave device for a voice modem.
Option value 8 is the only option considered when DevID has been set.
Note: DevID is ignored for VIC sessions. Options must be configured appropriately if there is a chance that playback might occur over a VTScada Internet Client.

Comments:

The return value is a Boolean flag. It is TRUE while the file is playing and FALSE when not playing.

Playback will stop when any of the following conditions occur:

Enable is set to false
File is set to Invalid or ""
The steady state call, Play() is stopped.

If the session is remote via a VTScada Internet Client (VIC), the return value of this function will not be set to true until the audio file has been completely transferred and the playback has begun remotely.