Click above to get retro games delivered to your door ever month!

  m6_ChgOwner():

  Purpose:  This function allows you to change to ownership of a filter
            from "system-owned" to "user-owned" which prevents it
            from being released by the system.

   Syntax:  m6_ChgOwner( <nHandle> )

    Where:  <nHandle>     --  Is a handle to a previously allocated
                              filter.

     Note:  This function has no effect on filters that are already
            "user-owned".

  Returns:  Logical value:  .T. means the operation was successful,  .F.
            indicates it failed.  In the case of a .F. value call m6_Error()
            to retrieve the reason for the error.


  Example:

        #include "SIXCDX.CH"
        #include "MACHSIX.CH"

        USE Salesmen INDEX Sales

        //..................................................Set a filter
        SET FILTER TO SaleTot > 10000

        //..........................................Initialize the filter
        GO TOP

        //.................Get the handle to the filter in this workarea
        nHandle := m6_GetAreaFilter()

        //...............................Get information about the filter
        aInfo := m6_FiltInfo( nHandle )

        //..........Display filter owner.  Note it's owned by the system
        ? "Filter owner="
        ?? aInfo[ INFO_OWNER ]                      //  1 - System owned

        //..........................Change ownership from system to user
        lSuccess := m6_ChgOwner( nHandle )

        //...............................................Check for error
        if !lSuccess
           ? "Error changing filter ownership to user."
           ? "m6_Error()="
           ?? m6_Error()
           quit
        endif

        //..................................Get information about filter
        aInfo := m6_FiltInfo( nHandle )

        //...............................Note that we own the filter now
        ? "Filter owner ( before SET FILTER TO )="
        ?? aInfo[ INFO_OWNER ]                       // 2 - User owned

        //......................... Clear the filter from this workarea
        SET FILTER TO

        //............................................Get info once again
        aInfo := m6_FiltInfo( nHandle )

        //.Even after the filter has been cleared we still retain ownership
        ? "Filter owner ( after SET FILTER TO )="
        ?? aInfo[ INFO_OWNER ]                       // 2 - User owned

        //.Because we own the filter, it is our responsibility to free it
        m6_FreeFilter( nHandle )