WIN$PLAYSOUND

The WIN$PLAYSOUND routine lets you play a .WAV file on Microsoft Windows machines (wave-form sound). You can also play sounds that the user has assigned to system events in the control panel.

WIN$PLAYSOUND is supported and can be used by applications deployed in Acucorp's Thin Client environment.

Usage

CALL "WIN$PLAYSOUND" 
    USING SOUND-NAME, SOUND-FLAGS
    GIVING SOUND-STATUS

Parameters

SOUND-NAME PIC X(n)	Identifies the sound to play. This is either the name of a registered system sound or the name of a .WAV file.
SOUND-FLAGS numeric parameter	One or more optional values added together. The SOUND-FLAG options are described below. The option names are contained in the COPY library acugui.def.
SOUND-STATUS signed numeric data item	Indicates the status of the operation as follows: `-1` - Operation not available - host machine is not Windows `0` - Operation failed `1` - Operation succeeded

Description

WIN$PLAYSOUND causes the sound specified in SOUND-NAME to be played. If SOUND-NAME contains the name of a system event, the sound associated with that event is played (the association is made via the Windows Control Panel). Otherwise, WIN$PLAYSOUND assumes that SOUND-NAME contains the name of a .WAV audio file.

Note: When you are running in a thin client environment, and a file name beginning with @[DISPLAY] is passed to this routine, it will attempt to access the file in the display host's file system. It does not download the file from the server. For more information, see the topic, Using Library Routines and DLLs in Thin Client of the AcuConnect User's Guide.

If SOUND-NAME does not correspond to a system event and the file cannot be found, the default system sound is played. The default sound is also played when there is not enough memory available to load the specified file. If a default sound is not available, the routine does nothing and returns 0 in SOUND-STATUS.

This routine searches for the specified .WAV file in the object libraries, the working directory, and then the directories specified in the PATH environment variable. You can add .WAV files to your object library by using the COPY RESOURCE statement or CBLUTIL utility program. Specifying a SOUND-NAME of spaces stops any sound that is currently playing.

Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H, Configuration Variables for information about the terminating character for path names.

System event names are implementation dependent. The Windows API documents that the following sounds are always available:

SystemAsterisk
SystemExclamation
SystemExit
SystemHand
SystemQuestion
SystemStart

Other system sound events are defined in the registry under Windows 98. Use regedit to look in the registry location:

HKEY_CURRENT_USER\AppEvents\EventLabels

The naming conventions for system sound events is implementation dependent.

The following options can be specified in SOUND-FLAGS. To use them, add together the values of the options and assign them to SOUND-FLAGS. The optional values have level 78 names associated with them. These names are defined in acugui.def.

SND-SYNC (value 0)	This option causes the program to pause while the sound is being played. WIN$PLAYSOUND will not return until the sound has finished.
SND-ASYNC (value 1)	This option causes the program to continue to run while the sound is playing. Note that you can halt a sound that is playing by passing a SOUND-NAME of spaces to a subsequent call to WIN$PLAYSOUND.
SND-LOOP (value 8)	To work, this option must be used with the SND-ASYNC option. This option causes the sound to play continuously, restarting from the beginning when the end is reached. The sound can be stopped by passing a SOUND-NAME of spaces on a subsequent call.
SND-NOSTOP (value 16)	Normally, any sound playing will be stopped when a new sound is specified. With NOSTOP, if a sound is already playing, it will continue to play and WIN$PLAYSOUND will return a SOUND-STATUS value of `0`.