
           Ŀ
                    Developer Kit For Sound Blaster Series        
                               Second Edition                     
               Copyright (c) Creative Technology Ltd, 1992-1993.  
                             All Rights Reserved.                 
                                                                  
                                SBKHELP.TXT                       
           


This file describes SBK helper functions in detailed. The prototypes of these
functions are in the file SBKX.H, SBKX.BI and SBKX.PAS for C language, Basic
and Pascal respectively. Note that all SBK helper functions have the prefix
"sbk????".

The source codes for all the helper functions are provided in the directory
\SBK\HELPER. You can  modify or use these  codes in any way that you find
useful provided that you agree that Creative Technology Ltd and Creative Lab
Inc has no warranty obligations or liability for any function which has been
modified.


Ŀ
   How to rebuild SBK helper functions libraries ?                         

To build the SBK helper libraries, assuming that you have Basic version of
SBK installed, edit the Make file MKBHLP.MK. Make changes to the compilers
path and add in your source files if you wish to. You also need to add the
following two lines :-
    set LIB=C:\SBK\LIB
    set INCLUDE=C:\SBK\INCLUDE 
in your AUTOEXEC.BAT file if you are using Microsoft's C or BASIC compilers
for command line compiling. Whereas for Turbo Pascal compilers, you may need
to edit the compiler configuration file to set the INCLUDE(/I) and UNIT(/U)
paths as shown above appropriately.

Finally execute BHLP.BAT to start building the libraries.


Ŀ
   SBK Helper Functions List.                                              

The following describes the SBK helper functions in detailed. There are
totally thirty three functions :-



Function 1
    BASIC   FUNCTION sbkMakeDWord& (BYVAL wHiWord%, BYVAL wLoWord%)

Description
    Make a four byte long integer value.

Entry
    wHiWord         - upper two bytes value.
    wLoWord         - lower two bytes value.
Exit
    return a long integer value.


Function 2
    BASIC   FUNCTION sbkMakeWord% (BYVAL bHiByte%, BYVAL bLoByte%)

Description
    Make a two bytes integer value.

Entry
    bHiByte         - upper byte value.
    bLoByte         - lower byte value.
Exit
    return an integer value.



Function 3
    BASIC   FUNCTION sbkHighWord% (BYVAL dwData&)

Description
    Get an upper two bytes value from a four bytes long integer value.

Entry
    dwData          - four byte long integer value.

Exit
    return a two byte short integer value.



Function 4
    BASIC   FUNCTION sbkLowWord% (BYVAL dwData&)

Description
    Get a lower two bytes value from a four bytes long integer value.

Entry
    dwData          - four byte long integer value.

Exit
    return a two byte short integer value.



Function 5
    BASIC   FUNCTION sbkHighByte% (BYVAL wData%)

Description
    Get an upper one byte value from a two byte short integer value.

Entry
    wData           - two byte short integer value.

Exit
    return a two byte integer value with upper byte set to zero and
    lower byte contains the upper byte of wData.



Function 6
    BASIC   FUNCTION sbkLowByte% (BYVAL wData%)

Description
    Get a lower one byte value from a two byte short integer value.

Entry
    wData           - two byte short integer value.

Exit
    return a two byte integer value with upper byte set to zero and
    lower byte contains the lower byte of wData.



Function 7
    BASIC   FUNCTION sbkMakeBasicString$ (BYVAL lpCString&)

Description
    Convert a null terminated C Language string to Basic string.

Entry
    lpCString       - long integer value with upper two bytes contains
                      segment and lower two bytes contains offset of
                      the location of the string to be converted.

Exit
    return a converted Basic string.


Function 8
    BASIC   FUNCTION sbkReleaseBasicString ()

Description
    Release a Basic string that obtained from a prior call to
    sbkMakeBasicString$. After the call to this function, the
    Basic string will be no longer valid.

Entry
    none.

Exit
    none.



Function 9
    PASCAL  FUNCTION sbkMakePascalString (lpCString: ^char) : string

Description
    Convert a null terminated C Language string to Pascal string.

Entry
    lpCString       - a far pointer to the string to be converted.

Exit
    return a converted Pascal string.



Function 10
    BASIC   FUNCTION sbkMakeAsciizString& (BString$)
    PASCAL  FUNCTION sbkMakeAsciizString  (PasString: string) : ^char

Description
    Convert a Basic or Pascal string to null terminated C language
    string.

Entry
    BString         - a Basic string to be converted.
    PasString       - a Pascal string to be converted.

Exit
    BASIC   return a long integer value with upper two bytes and
            lower two bytes contain segment and offset of the
            location of the converted string respectively.
    PASCAL  return a pointer to the converted string.



Function 11
    BASIC   FUNCTION sbkDosOpen% (BYVAL lpFilename&)
    C       int far  sbkDosOpen  (char far * lpFilename)
    PASCAL  FUNCTION sbkDosOpen  (lpFilename: ^char) : integer

Description
    Open a file for reading or writing.

Entry
    lpFilename      -
        BASIC       long integer value with upper two bytes and lower
                    two bytes contain segment and offset of the file
                    name to be opened respectively.
        C           far pointer to the file name to be opened.
        PASCAL      far pointer to the file name to be opened.

Note
    The filename must be in null terminated C Language string format.

Exit
    return handle of the file if successful else return -1.



Function 12
    BASIC   SUB       sbkDosClose (BYVAL iFileHandle%)
    C       void far  sbkDosClose (int iFileHandle)
    PASCAL  PROCEDURE sbkDosClose (iFileHandle: integer)

Description
    Close a file associate with file handle obtained from a prior call
    to sbkDosOpen or sbkDosCreate.

Entry
    iFileHandle     - file handle to be closed.

Exit
    none.



Function 13
    BASIC   FUNCTION sbkDosCreate% (BYVAL lpFilename&)
    C       int far  sbkDosCreate  (char far * lpFilename)
    PASCAL  FUNCTION sbkDosCreate  (lpFilename: ^char) : integer

Description
    Create a file for writing. If the file already exists, it
    will be overwritten.

Entry
    lpFilename      -
        BASIC       long integer value with upper two bytes and lower
                    two bytes contain segment and offset of the file
                    name to be created respectively.
        C           far pointer to the file name to be created.
        PASCAL      far pointer to the file name to be created.

Note
    The filename must be in null terminated C Language string format.

Exit
    return handle of the file if successful else return -1.



Function 14
    BASIC   FUNCTION sbkDosRead% (iFileHandle%, wSegment%,
                                  wOffset%, dwLength&)
    C       WORD far sbkDosRead  (int iFileHandle, char far * lpBuffer,
                                  WORD wLength, WORD far * wByteRead)
    PASCAL  FUNCTION sbkDosRead  (iFileHandle: integer; wSegment,
                                  wOffset, wLength: word) : word

Description
    Read number of bytes from a file.

Entry
    iFileHandle     - file handle to be read.
    wSegment        - segment of the buffer to store the data read.
    wOffset         - offset of the buffer to store the data read.
    lpBuffer        - far pointer to the buffer to store the data read.
    dwLength        - number of bytes to read.
    wLength         - number of bytes to read.
    wByteRead       - number of bytes successfully read.

Exit
    BASIC   return non-zero if successful else return zero.
    C       return zero if successful else return non-zero.
    PASCAL  return non-zero if successful else return zero.



Function 15
    BASIC   FUNCTION sbkDosWrite% (iFileHandle%, wSegment%,
                                   wOffset%, dwLength&)
    C       WORD far sbkDosWrite  (int iFileHandle, char far * lpBuffer,
                                   WORD wLength, WORD far * wByteWritten)
    PASCAL  FUNCTION sbkDosWrite  (iFileHandle: integer; wSegment,
                                   wOffset, wLength: word) : word

Description
    Write number of bytes to a file.

Entry
    iFileHandle     - file handle to be written.
    wSegment        - segment of the buffer contains data to be written.
    wOffset         - offset of the buffer contains data to be written.
    lpBuffer        - far pointer to the buffer contains data to be written.
    dwLength        - number of bytes to write.
    wLength         - number of bytes to write.
    wByteWritten    - number of bytes successfully written.

Exit
    BASIC   return non-zero if successful else return zero.
    C       return zero if successful else return non-zero.
    PASCAL  return non-zero if successful else return zero.



Function 16
    BASIC   FUNCTION sbkFileSize& (BYVAL iFileHandle%)
    PASCAL  FUNCTION sbkFileSize  (iFileHandle: integer) : longint

Description
    Get the size of a file.

Entry
    iFileHandle     - file handle obtained from a prior call to
                      sbkDosOpen.

Exit
    return the size of a file in bytes if successful else return a
    long integer value -1.



Function 17
    BASIC   FUNCTION sbkDosLSeek& (BYVAL iFileHandle%, BYVAL lOffset&
                                   BYVAL wSeekMode%)
    PASCAL  FUNCTION sbkDosLSeek& (iFileHandle: integer; lOffset: longint,
                                   wSeekMode: word) : longint

Description
    Move a file pointer to a new location. The next operation on the
    file occurs at the new location.

Entry
    iFileHandle     - file handle.
    lOffset         - offset of the file pointer to be moved, in bytes,
                      from an original location specified by wSeekMode.
    wSeekMode       - specifies the original point from where the pointer
                      moves. The wSeekMode can be one of these which
                      defined in SBKX.BI or SBKX.PAS :-
                        SEEKSET, SEEKCUR or SEEKEND for BASIC
                        SEEK_SET, SEEK_CUR or SEEK_END for PASCAL

                      SEEKSET   specifies the origin starts from the
                                beginning or the file.
                      SEEKCUR   specifies the origin starts from the
                                current location.
                      SEEKEND   specifies the origin starts from the
                                end of the file.

Exit
    return the offset, in bytes, of the new position from the beginning
    of the file if successful else return a long integer value -1.



Function 18
    BASIC   FUNCTION sbkFindFile% (BYVAL lpFilename&)
    PASCAL  FUNCTION sbkFindFile  (lpFilename: ^char) : integer

Description
    Find the existing of a file.

Entry
    lpFilename      -
        BASIC       long integer value with upper two bytes and lower
                    two bytes contain the segment and offset of the
                    file name to be searched respectively.
        PASCAL      far pointer to the file name to be searched.

Note
    The file name must be in null terminated C Language string format.

Exit
    return non-zero if successful else return zero.



Function 19
    BASIC   FUNCTION sbkFindFirst% (BYVAL lpFilename&, BYVAL wAttributes%,
                                    SEG lpSearchRec AS SEARCHxREC)

Description
    Search information about the first instance of a file whose name and
    attributes match the lpfilename and wAttributes arguments. Information
    of the file is stored in a record SEARCHxREC which is defined in SBKX.BI

Note
    The file name must be in null terminated C Language string format.

Entry
    lpFilename      - file name to be searched. It can be wild cards * and ?.
    wAttributes     - the attributes can be one of the following constants
                      which are defined in SBKX.BI.

        ARCHIVE       Archive. Set whenever the file is changed.
                      Cleared by the DOS BACKUP command.

        HIDDEN        Hidden file. Cannot be found with the DOS DIR
                      command. Returns information about normal files as
                      well as files with this attribute.

        ANYFILE       Normal. File can be read or written to without
                      restriction.

        READONLY      Read only. File cannot be opened for writing, and
                      a file with the same name cannot be created. Returns
                      information about normal files as well as files with
                      this attribute.

        DIRECTORY     Sub directory. Returns information about normal files
                      as well as files with this attribute.

        SYSFILE       System file. Cannot be found with the DOS DIR
                      command. Returns information about normal files as
                      well as files with this attribute.

        VOLUMEID      Volume ID. Only one file can have this attribute,
                      and it must be in the root directory.


        Multiple constants can be combined with the OR operator.

    lpSearchRec     - store information of the file.

Exit
    return
        0   - successful.
        2   - file not found.
        18  - no more file.



Function 20
    BASIC   Function sbkFindNext% (SEG lpSearchRec AS SEARCHxREC)

Description
    Search the next name, if any, that matches the lpFilename and
    wAttributes arguments specified in a prior call to sbkFindFirst.
    The file information argument lpSearchRec must point to a structure
    initialised by a previous call to sbkFindFirst. As described above,
    the contents of the structure will be altered if a match is found.

Entry
    lpSearchRec     - store information of the file.

Exit
    return
        0   - successful.
        2   - file not found.
        18  - no more file.



Function 21
    BASIC   SUB sbkGetCmdLine (NumArgs%, Args$(), MaxArgs%)

Description
    Get and split command line into arguments.

Entry
    NumArgs%        - number of command-line argument found.
    Args$()         - array in which to return arguments.
    MaxArgs%        - maximum number of arguments array can be returned.

Exit
    none.



Function 22
    BASIC   FUNCTION sbkLoadDriver% (DriverName$, wEmbedBuffer%)
    PASCAL  FUNCTION sbkLoadDriver  (DriverName: string;
                                     wEmbedBuffer: word ) : pointer

Description
    Load a SBK driver into memory. Note that the driver is loaded into
    offset 0 of the segment to conform to the driver requirements.
    sbkLoadDriver will first search the driver base on "SOUND" setting
    in the environment, else it will search the current directory for
    the matched driver. For example if you set SOUND=C:\SBK, sbkLoadDriver
    will load the driver from C:\SBK\DRV directory.

Entry
    DriverName      - specifies the driver to be loaded.
    wEmbedBuffer    - wEmbedBuffer = non-zero, the driver will be loaded
                      together with embedded buffer.
                      wEmbedBuffer = zero, the driver will be loaded without
                      embedded buffer.

Note
    The wEmbedBuffer argument only applicable to Creative Voice drivers
    CTVDSK.DRV and CT-VOICE.DRV

Exit
    BASIC   upon successful, a segment value where the driver located is
            returned else return zero
    PASCAL  return a pointer to the driver location if successful else
            return nil.



Function 23
    BASIC   FUNCTION sbkAllocMem% (BYVAL wParaSize%)
    PASCAL  FUNCTION sbkAllocMem (wParaSize: word) : word

Description
    Use DOS system call to allocate a memory buffer from
    conventional memory.

Entry
    wParaSize       - number of bytes to allocate in units of paragraph
                      size (16 bytes).

Exit
    return a segment value where the memory buffer is allocated if
    successful else return 0.
Note
    Set the offset of the buffer to zero.



Function 24
    BASIC   SUB       sbkFreeMem (BYVAL wSegment%)
    PASCAL  PROCEDURE sbkFreeMem (wSegment: word)

Description
    Free memory buffer associate with the segment that obtained from
    a prior call to sbkAllocMem.

Entry
    wSegment        - segment of the memory buffer to be freed.

Exit
    none.



Function 25
    BASIC   FUNCTION sbkGetXMSEntry% ()
    C       WORD far sbkGetXMSEntry (void)
    PASCAL  FUNCTION sbkGetXMSEntry : WORD

Description
    Get XMS driver entry address.

Entry
    none.

Exit
    non-zero if successful else return zero.



Function 26
    BASIC   FUNCTION sbkAllocXM% (BYVAL wKiloSize%)
    C       WORD far sbkAllocXM  (WORD wKiloSize)
    PASCAL  FUNCTION sbkAllocXM  (wKiloSize: word) : word

Description
    Allocate a memory buffer from extended memory.

Entry
    wKiloSize       - number of bytes to allocate in units of kilobytes
                      (1000).

Exit
    return handle of the allocated block if successful else return zero.



Function 27
    BASIC   FUNCTION sbkFreeXM% (BYVAL wXMHandle%)
    C       WORD far sbkFreeXM  (WORD wXMHandle)
    PASCAL  FUNCTION sbkFreeXM  (wXMHandle: word) : WORD

Description
    Free extended memory buffer associate with the handle that obtained
    from a prior call to sbkAllocXM.

Entry
    wXMHandle      - extended memory handle.

Exit
    non-zero if successful else return zero.



Function 28
    BASIC   FUNCTION sbkMoveCMtoXM% (BYVAL lpSrcBuf&, BYVAL dwMoveLength&,
                                     BYVAL wXMHandle%, BYVAL dwXMOffset%)
    C       WORD far sbkMoveCMtoXM  (BYTE far lpSrcBuf, DWORD dwMoveLength,
                                     WORD wXMHandle, DWORD dwXMOffset)
    PASCAL  FUNCTION sbkMoveCMtoXM  (lpSrcBuf: pointer; dwMoveLength: longint,
                                     wXMHandle: word; dwXMOffset: longint) : WORD

Description
    Move data from conventional memory to extended memory.

Entry
    lpSrcBuf
        BASIC       - long integer value contains segment at high word and
                      offset at low word of the data buffer that to be moved
                      to extended memory.
        C &         - far pointer to the data buffer that to be moved to
        PASCAL        extended memory.
    dwMoveLength    - number of bytes, in even value, to be moved to
                      extended memory.
    wXMHandle       - handle of extended memory that obtained from a prior
                      call to sbkAllocXM.
    dwXMOffset      - offset at extended memory buffer that the storing of
                      data starts.

Exit
    non-zero if successful else return zero.



Function 29
    BASIC   FUNCTION sbkMoveXMtoCM% (BYVAL lpDestBuf&, BYVAL dwMoveLength&,
                                     BYVAL wXMHandle%, BYVAL dwXMOffset%)
    C       WORD far sbkMoveXMtoCM  (BYTE far lpDestBuf, DWORD dwMoveLength,
                                     WORD wXMHandle, DWORD dwXMOffset)
    PASCAL  FUNCTION sbkMoveXMtoCM  (lpDestBuf: pointer; dwMoveLength: longint,
                                     wXMHandle: word; dwXMOffset: longint) : WORD

Description
    Move data from extended memory to conventional memory.

Entry
    lpDestBuf
        BASIC       - long integer value contains segment at high word and
                      offset at low word of the buffer at conventional
                      memory that data will be stored.
        C &         - far pointer to the buffer at conventional memory that
        PASCAL        data will be stored.
    dwMoveLength    - number of bytes, in even value, to be moved to
                      conventional memory.
    wXMHandle       - handle of extended memory that obtained from a prior
                      call to sbkAllocXM.
    dwXMOffset      - offset at extended memory buffer that the moving of
                      data starts.

Exit
    non-zero if successful else return zero.



Function 30 & 31
    BASIC   FUNCTION sbkNormalizeSegment% (BYVAL wSegment%, BYVAL wOffset%)
    BASIC   FUNCTION sbkNormalizeOffset% (BYVAL wOffset%)

Description
    Adjust the segment and offset of a memory pointer to prevent segment
    overwrap.

Entry
    wSegment        - segment of the memory buffer.
    wOffset         - offset of the memory buffer.

Exit
    sbkNormalizeSegment return the newly adjusted segment value.
    sbkNormalizeOffset return the newly adjusted offset value.



Function 32
    C       FUNCSTATUS  FAR CDECL ctmmInit (void)

Description
    Set up entry point to the CTMMSYS.SYS driver.

Entry
    None.

Exit
    return 0 if successful else return 1.



Function 33

    C       MMSTATUS    FAR CDECL ctmmCall (IN      HMMDEVICE hDev,
                                            IN      MMDEVICE MmDevice,
                                            IN      WORD wMsg,
                                            IN OUT  DWORD dwParam1,
                                            IN OUT  DWORD dwParam2) ;

Description
    Invoke CTMMSYS driver function specified in the wMsg parameter.

Entry
    hDev            - handle of openned device.
    mmDevice        - type of device.
    wMsg            - Message being sent to the driver.
    dwParam1        - Message-dependent parameter.
    dwParam2        - Message-dependent parameter.

Exit
    return 0 if successful else return error code.


                            ---  THE END ---
