It's not quite an MP3, but the iSeries does provide an API that makes sound. I was inspired to tell you about the API when I recently read a posting in the iSeries Network CL forum where Herman Van der Staey posted a CL program using API QsnBeep (Generate a Beep). As I read Herman's posting, I was reminded of a situation we had with a System/32 in the 1970s. These iSeries ancestors could do only one thing at a time and, as you might imagine, couldn't do things very quickly! We had some long-running jobs and because of the processing time required to run them all, it was important that we not waste time between starting each job.

Not wanting to hover over the machine waiting for each job to finish so that we could start the next immediately, we made an unsanctioned engineering change to the machine. We wired in an alarm that the machine sounded as jobs finished! We could finally stop making so many status-checking trips to the room where the system was located.

If we had a similar need today, we would opt to use API QsnBeep from the Screen Output category of Dynamic Screen Manager (DSM) APIs. You could also sound the beep by writing a display file record format with keyword Alarm in effect, but the API doesn't have the overhead and the intent is clearer.

Following are the API's parameters:

  * Command buffer handle
    Input  -- This is a handle for the command buffer in which to store the beep
              command. If you omit this parameter or specify a zero value, this
              is a direct operation and the beep sounds immediately.

  * Low-level environment
    Input  -- This is the low-level environment to which the command applies.

  * Error code
    I/O    -- This is the standard API error structure.

A discussion of these parameters is outside the scope of this tip because the DSM APIs are reasonably complex. We don't really need to understand them for our project, fortunately. Only when you're writing commands to the workstation management buffers (i.e., really using DSM) do you need to worry about the handle parameters. Using zero values for the handles allows us to generate a beep immediately, which is precisely what we want to do.

The API returns a return code indicating success (value is 0) or failure (value is -1).

Let's look now at service program Misc0001 where procedure SoundBeep encapsulates the API.

       //  *****************************************************************
       //  * Service program... Misc0001                                   *
       //  * Description....... Miscellaneous routines                     *
       //  *****************************************************************

     H NoMain

       //  =================================================================
       //  = Procedure prototypes                                          =
       //  =================================================================

       //  -----------------------------------------------------------------
       //  - SoundBeep - Generate a beep at a workstation                  -
       //  -                                                               -
       //  - Return value: Boolean flag indicating success or failure      -
       //  -               (*On = Error, *Off = Success)                   -
       //  -----------------------------------------------------------------

     D SoundBeep...
     D                 Pr              N

       //  -----------------------------------------------------------------
       //  - SoundBeepWithAPI - Generate a beep using API QsnBeep          -
       //  -                                                               -
       //  - Parameters:   Usage   Description                             -
       //  -                                                               -
       //  -               Input   Command buffer handle                   -
       //  -               Input   Low-level environment handle            -
       //  -               I/O     Error structure                         -
       //  -                                                               -
       //  - Return value: Success (0) or failure (-1)                     -
       //  -----------------------------------------------------------------

     D SoundBeepWithAPI...
     D                 Pr            10I 0 ExtProc( 'QsnBeep' )
     D  ParameterIn                  10I 0
     D  ParameterIn                  10I 0
     D  ParameterIO                        LikeDS( StdErrorModel )

      *    =================================================================
      *    = Global definitions                                            =
      *    =================================================================

      *    -----------------------------------------------------------------
      *    - Standard error structure model                                -
      *    -----------------------------------------------------------------

     D StdErrorModel   DS                  Qualified
     D                               10I 0 Inz( %Size( StdErrorModel ) )
     D  BytesAvail                   10I 0 Inz( *Zero )
     D  MsgID                         7    Inz( *Blank )
     D                                1    Inz( X'00' )
     D  MsgDta                      256    Inz( *Blank )

       //  *****************************************************************
       //  * Procedure.... SoundBeep                                       *
       //  * Description...Generate a beep at a workstation                *
       //  *****************************************************************

     P SoundBeep...
     P                 B                   Export
     D SoundBeep...
     D                 PI              N

       //  =================================================================
       //  = Definitions                                                   =
       //  =================================================================

      *    -----------------------------------------------------------------
      *    - Standard error structure                                      -
      *    -----------------------------------------------------------------

     D  StdError       DS                  LikeDS( StdErrorModel )
     D                                     Inz( *LikeDS )
       //  -----------------------------------------------------------------
       //  - Work variables                                                -
       //  -----------------------------------------------------------------

     D CmdBufferHdl    S             10I 0 Inz ( *Zero )
     D LowLevelHdl     S             10I 0 Inz ( *Zero )
     D APIRtnCode      S             10I 0
     D RtnStatus       S               N

      /Free

       //  =================================================================
       //  = Generate beep                                                 =
       //  =================================================================

           Reset StdError ;

           APIRtnCode = SoundBeepWithAPI
                        (
                          CmdBufferHdl :
                          LowLevelHdl  :
                          StdError
                        ) ;

           Select ;

           When StdError.MsgID <> *Blank ;
             RtnStatus = *On ;

           When APIRtnCode <> *Zero ;
             RtnStatus = *On ;

           When APIRtnCode = *Zero ;
             RtnStatus = *Off ;

           Other ;
             RtnStatus = *On ;

           EndSl ;

           Return RtnStatus ;

      /End-Free

     P SoundBeep...
     P                 E 

Service program Misc0001 begins with procedure prototypes. Applications use procedure SoundBeep to generate a beep at a workstation. Procedure SoundBeep has no parameters, but does have a Boolean return value your applications can check if you wish. A value of *Off indicates successful completion, while a value of *On indicates failure.

Procedure SoundBeep is very straightforward. It simply calls API QsnBeep, and then sets the Boolean return value based on the standard API error structure and the API's return code value.

Here's an example showing how applications use the procedure:

       //  =================================================================
       //  = Program....... Misc0001Ex                                     =
       //  = Description... Sounding a beep example                        =
       //  =================================================================

       //  =================================================================
       //  = Procedure prototypes                                          =
       //  =================================================================

       //  -----------------------------------------------------------------
       //  - SoundBeep - Generate a beep at a workstation                  -
       //  -----------------------------------------------------------------

     D SoundBeep...
     D                 Pr              N

       //  =================================================================
       //  = Definitions                                                   =
       //  =================================================================

       //  -----------------------------------------------------------------
       //  - Work variables                                                -
       //  -----------------------------------------------------------------

     D RtnStatus       S               N

      /Free

       //  =================================================================
       //  = Sound a beep                                                  =
       //  =================================================================
           *InLR = *On ;

       //  -----------------------------------------------------------------
       //  - with a return value                                           -
       //  -----------------------------------------------------------------

           RtnStatus= SoundBeep( ) ;

       //  -----------------------------------------------------------------
       //  - without a return value                                        -
       //  -----------------------------------------------------------------

           SoundBeep( ) ;

      /End-Free

Program Misc0001Ex is straightforward, showing you how to invoke procedure SoundBeep with and without a return value. You can add the standard API structure as a parameter to procedure SoundBeep if you wish to check specific error conditions that might be reported.