!fnshellex.bsi [101] - Wrapper for shell execute (with possible file xfer)
!----------------------------------------------------------------------------------------
!EDIT HISTORY
![101] 28-Apr-26 / jdm / Added keywords (for FUNCIDX)
![100] 15-Jan-17 / jdm / Created
!    Created   
!----------------------------------------------------------------------------------------
!Function:
!   Fn'Shell'Exec(objspec$) - launch object, return status
!   Fn'Shell'Exec'Status'Description$(status,exitstatus,wait) - return message for status
!----------------------------------------------------------------------------------------
!Keywords: shellex launch execute xshlex
!----------------------------------------------------------------------------------------

++include'once ashinc:types.def     ! [101] needed for BOOLEAN

!---------------------------------------------------------------------
!Function:
!   shell exec specified object, transferring it to pc if necessary
!Params:
!   object$  (s0) [in] - object spec
!Returns:
!   status (0 for ok, else error)
!Globals:
!Notes:
!   Requires XSHLEX.SBX for full capability; but falls back to simple
!   MX_SHELLEX under local windows otherwise
!---------------------------------------------------------------------
Function Fn'Shell'Exec(objspec$ as s0:inputonly) as T_INT

    map1 locals
        map2 guiflags,T_BITFLAGS32
        map2 status,T_INT
        
    if lookup("bas:xshlex.sbx") > 0 or lookup("xshlex.sbx") > 0 then
        xcall XSHLEX, objspec$, Fn'Shell'Exec
    else
        xcall MIAMEX, MX_SHELLEX, Fn'Shell'Exec, objspec$
    endif
    
EndFunction

!---------------------------------------------------------------------
!Function:
!   Display exit status info
!Params:
!   status  (num) [in] - status returned from XSHLEX or MX_SHELLEX
!   exitstatus (num) [in] - launch target exit status (report if wait or nonzero)
!   wait (num) [in]  - if set, report exitstatus even if 0
!Returns
!   description (s,60)
!Globals:
!Notes:
!   This is a union of the status codes from MX_SHELLEX, ATEAPX.SBX
!   and XSHLEX.SBX
!---------------------------------------------------------------------
Function Fn'Shell'Exec'Status'Description$(status as T_INT:inputonly, &
                         exitstatus as T_INT:inputonly, &
                         wait as B2:inputonly) as s60

    if status = 0 then
        Fn'Shell'Exec'Status'Description$ = "Command launched successfully"
        if wait # 0 or exitstatus # 0 then
            Fn'Shell'Exec'Status'Description$ += ", target exit status: " + exitstatus
        endif
    else
        switch status
            case -99
                Fn'Shell'Exec'Status'Description$ = "ATE version not high enough"
                exit
            case -98 
                Fn'Shell'Exec'Status'Description$ = "A-Shell version not high enough for binary transfer"
                exit
            case 17
                Fn'Shell'Exec'Status'Description$ = "Unexpected ZTERM response"
                exit
            case -16
                Fn'Shell'Exec'Status'Description$ = "ZTERM failed to respond"
                exit
            case -15
                Fn'Shell'Exec'Status'Description$ = "ATE failed to respond"
                exit
            case -5
                Fn'Shell'Exec'Status'Description$ = "ATE or ZTERM required"
                exit
            case -4
                Fn'Shell'Exec'Status'Description$ = "FTP error - file failed to transfer to PC"
                exit
            case -3
                Fn'Shell'Exec'Status'Description$ = "File transferred to PC but failed to verify afterwards"
                exit
            case -2
                Fn'Shell'Exec'Status'Description$ = "Host file doesn't exist"
                exit
            case -1
                Fn'Shell'Exec'Status'Description$ = "Out of system resources"
                exit
            case 2
                Fn'Shell'Exec'Status'Description$ = "File not found"
                exit
            case 3
                Fn'Shell'Exec'Status'Description$ = "Path not found"
                exit
            case 5
                Fn'Shell'Exec'Status'Description$ = "Access denied"
                exit
            case 8
                Fn'Shell'Exec'Status'Description$ = "Out of memory"
                exit
            case 11
                Fn'Shell'Exec'Status'Description$ = "Bad format"
                exit
            case 26
                Fn'Shell'Exec'Status'Description$ = "Sharing error"
                exit
            case 27
                Fn'Shell'Exec'Status'Description$ = "File association incomplete"
                exit
            case 31
                Fn'Shell'Exec'Status'Description$ = "No association defined"
                exit
            case 32
                Fn'Shell'Exec'Status'Description$ = "DLL not found"
                exit
            case 1223
                Fn'Shell'Exec'Status'Description$ = "User cancelled launch and/or elevation required"
                exit
            default
                Fn'Shell'Exec'Status'Description$ = "Unknown error " + status
                exit
        endswitch
    endif

EndFunction