WIN$PLAYSOUND Routine

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.

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.

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. For more information about the COPY RESOURCE statement, see section 2.4.1 in Book 3, "Reference Manual." For more information about the CBLUTIL utility program, see section 3.2 in Book 1, "User's Guide." 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. See the documentation in Appendix H, Configuration File Entries, 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 95/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".

-1	Operation not available - host machine is not Windows
0	Operation failed
1	Operation succeeded