;; 
;;=====================================================================================----- 
;; 
;;FUNCTION       Include() 
;; 
;;ACTION         Loads a KIX library (UDF)- checks multiple locations 
;; 
;;AUTHOR         Glenn Barnas  
;; 
;;VERSION        1.0  - 2002/09/17 
;; 
;;HISTORY        1.0  - 2002/09/17 - Initial Release 
;; 
;;SYNTAX         Include(IncludeFile [,AltLibPath [, Flag ]] ) 
;; 
;;PARAMETERS     IncludeFile - Required - String 
;;               - The UDF name to locate and load from the library - NO Extension! 
;;               AltLibPath - Optional - String 
;;               - An alternate path to search for UDFs, default path is defined in 
;;               the %KIXLIBPATH% environment variable. 
;;               Flag - Optional - Integer 
;;               - Set to return an error instead of terminating when the library 
;;               object can't be found. 
;; 
;;REMARKS        Provides an intelligent alternative to the built-in CALL and INCLUDE. 
;;               Terminates the script if the library isn't found unless the  
;;               SoftErr value is set. If SoftErr is set and the library can't 
;;               be found, the calling routine must handle the lack of 
;;               functionality. Unless customized, it tries to load .KXF and  
;;               .UDF files from \usr\lib, %KixLibPath%, or @ScriptDir. 
;;               AltLibPath can be used to specify additional search directories, 
;;               these directories will be searched FIRST. 
;; 
;;RETURNS        nothing - loads the specified UDF or terminates 
;; 
;;DEPENDENCIES   none 
;; 
;;TESTED WITH    NT4, W2K, WXP 
;; 
;;EXAMPLES       Include("tsControl")      ; find and load tscontrol.udf, terminate  
;;                                         ; if not found 
;;               Include("tsControl","",1) ; find and load tscontrol.udf, return an 
;;                                         ; error if not found 
;; 
;; DO NOT REMOVE TRAILING "; COMMENT REQUIRED FOR KGEN STRIP FUNC" FROM THE ANY SOURCE LINES! 
; 
Function Include($LibFile, OPTIONAL $AltLibPath, OPTIONAL $SoftErr)
 
  Dim $Extensions, $DefPath, $LoadPath, $PATHS, $PATH, $EXTS, $EXT
 
  ; define a comma-separated list of allowed library file extensions  
  $Extensions = '.kxf, .udf'
 
  ; define the locations where the UDFs are maintained 
  ; default is C:\usr\lib, then %KIXLIBPATH%, then script-start directory 
  $DefPath = '%SystemDrive%\usr\lib;%KixLibPath%;@ScriptDir'	; COMMENT REQUIRED FOR KGEN STRIP FUNC 
 
  ; Make sure AltLibPath ends with ';' if specified 
  If $AltLibPath <> ''
    If Right($AltLibPath,1) <> ';'				; COMMENT REQUIRED FOR KGEN STRIP FUNC 
      $AltLibPath = $AltLibPath + ';'				; COMMENT REQUIRED FOR KGEN STRIP FUNC 
    EndIF
  EndIf
 
  ; Define the default search locations 
  $PATHS = Split($AltLibPath + $DefPath, ';')			; COMMENT REQUIRED FOR KGEN STRIP FUNC 
 
  ; use split to insure array format, even with one extension name 
  $EXTS  = Split($Extensions, ',')
  For Each $PATH in $PATHS
    If Right($PATH,1) <> '\' $PATH = $PATH + '\' EndIF
    For Each $EXT in $EXTS
      $LoadPath = $PATH + $LibFile + Trim($EXT)
      If Exist($LoadPath)
        Call $LoadPAth
        Exit 0
      EndIf
    Next
  Next
 
  ; Lib not found! Return error if SoftErr is set or DIE! 
  If $SoftErr
    Exit 1
  Else
    ; use a hard print statement (not MSG function) when aborting. 
    @CRLF 'Failed to load required library: ' + $LibFile + ' - Aborting!' @CRLF
    Quit 1
  EndIf
 
EndFunction