Blitz:Dos.include.ab3

The dos.include.ab3 Include file contains some useful functions for handling paths, directories and general DOS-related tasks.

Path Handling

dos_AddPart

This function adds the two given string arguments together and returns the result as an AmigaDOS-legal path. Very useful for adding a filename onto a directory name to produce the full path, but without having to worry about whether the path string ends in :, / or just the drawer name:

fullpath$ = dos_AddPart{"Workbench:System", "Format"}
fullpath2$ = dos_AddPart{"Workbench:System/", "Format"}

Both examples above will return the string "Workbench:System/Format".

dos_PathPart

This function returns the part of the given string that constitutes the directory in which the target of the given path resides. Useful for getting the directory of a file:

MyDirectory$ = dos_PathPart{"Workbench:System/Format"}

Will return the path "Workbench:System".

dos_FilePart

Similar to dos_PathPart{} above, but returns the filename instead:

MyFile$ = dos_FilePart{"Workbench:System/Format"}

Will return the string "Format".

dos_GetProgDir

This function returns the full path to your program. This can be useful to determine the absolute path to any files or directories in your program's directory:

MyDir$ = dos_GetProgDir{"Projects:MyProgram"}

The string argument given is only used when the program is run directly from the editor.

File Checking

dos_Exist

This function checks if the given file exists, and returns True (-1) if it does or False (0) otherwise:

result.l = dos_Exist{"Workbench:System/Format"}

This should return True unless someone has moved the Format command on your system...

dos_IsDir

This function checks if the given path is a directory, and returns True (-1) if so. If the path is a file or doesn't exist, dos_IsDir will return False (0):

result.l = dos_IsDir("SYS:System/Format")

This will return False (0).

dos_Check

This function tries to open a file for reading and close it again. It will return True(-1) if everything worked ok, or the DOS error code if it failed. This means it's important to check for a result equal to True instead of just a non-zero result. For example:

If dos_Check("Files:Test-File")
  NPrint "File ready"
Else
  NPrint "File error!"
End If

This will always say "File Ready" because the result will either be true (-1), or a numerical value corresponding to the DOS error code. The correct way to do this is:

If dos_Check("Files:Test-File")
  NPrint "File ready"
Else
  NPrint "File error!"
End If

This function does not try to write to the file, so it won't create a blank file if the filename doesn't exist. Instead, the DOS error code for "Object not found" (205) will be returned if the specified file doesn't exist.

dos_CheckLib

This function can be used to check if a particular library is present and of an appropriate version. It is important to check that libraries of the correct version exist before using them, otherwise crashes can occur. This function will return True (-1) if the specified library exists and has the version number specified or above, or False (0) otherwise:

If dos_CheckLib("workbench.library", 44) = False
  NPrint "This program requires at least workbench.library version 44 (OS 3.5) to work!"
  End
End If

The version is an integer and is checked against the version number of the library only. Revision is ignored in this case, so you can't check for a particular minor revision of a library - 37.299 and 37.350 both qualify as version 37 for example.

Generally, the standard internal Blitz commands work with the standard Amiga ROM libraries of any version and therefore you don't need to check for specific versions. However, when using additional Blitz commands (such as MUI), or using library calls, be sure to check the documentation to see the minimum version of the library you need. The Blitz Basic 2.1 manual includes a list of the system library calls available by default, and a note to tell you which functions are only available with release 2.0+ (version 37) and 3.0+ (version 39). The autodocs for any additional libraries you use will include similar information.