Library: File system utilities (OMVFS) Import: omvfs.xmd

Return type: vfsFile Returns: A vfs.file object representing the file.

Declaration

export external file function open-ftp
                     value string     filename
        on           value directory  on-dir      optional
        for          value integer    access-type optional initial {read-mode}

Argument definitions

filename

The URL the file to be opened.

on-dir

A connected vfs.directory object. This parameter is not supported in the current implementation.

access-type

An integer constant signifying the desired mode of access. The default value is vfs.read-mode.

You can use vfs.open-ftp to open a file that resides on an FTP server. vfs.open-ftp creates a vfs.file object that represents the file, and which can be used with various OMVFS functions to manipulate the file.

  process
     local vfs.file foo
     set foo 
      to vfs.open-ftp "ftp://ftp.omnimark.com/test.txt"
      for vfs.read-mode

Transfers to and from FTP servers may be made in either binary mode or text mode. This is determined not by a parameter of the vfs.open-ftp function but by the use of binary-mode or text-mode modifiers on a stream attached to the vfs.file object:

  import "omvfs.xmd" prefixed by vfs.
  
  process
     local vfs.file foo
     local stream bar
     set foo 
      to vfs.open-ftp "ftp://ftp.omnimark.com/test.txt"
      for vfs.read-mode
     set bar to binary-mode vfs.reader of foo 
     output bar

Note that the OMVFS library functions do not do "URL fix-up", which means that the URL "ftp://ftp.omnimark.com" (without the final slash) will not be accepted. Nor will a URL that lacks the introductory "ftp://".

Note that not all OMVFS functions are supported by all protocols. You will receive a runtime error if you attempt to perform an operation on a file on anFTP server if that operation is not supported by the FTP protocol, or if that function is not supported in the current version of OMVFS. In the current implementation, the following functions are supported:

• vfs.close
• vfs.file-name
• vfs.reader
• vfs.writer

You may specify the mode in which the file is opened. The default mode is read mode. The following modes are available:

• vfs.read-mode - open the file in read-only mode. You can only read from the file.
• vfs.write-mode - allows only writing to the file. File is truncated to byte 0 when opened.
• vfs.read-write-mode - allows for both reading and writing to the file. The cursor is positioned at the first byte of the file.
• vfs.read-write-append-mode - allows both reading and writing of the file. The cursor is positioned after the last byte of the file.
• vfs.write-append-mode - file opened for writing only. The cursor is positioned after the last byte of the file.

Exceptions

The following exceptions may occur:

• VFS001 The requested function is not supported for the type of connection
• VFS004 The specified name 'X' exceeds system length limits
• VFS100 The vfsDir object must be connected before it can be used
• VFS105 The path 'X' is not a valid absolute or relative path
• VFS111 The URL 'X' contains invalid encoding
• VFS201 An invalid value was specified for the file access
• VFS300 Generic operating system error
• VFS306 The file 'X' does not exist

Other Library Functions vfs.change-directory vfs.change-owner vfs.change-permissions vfs.close vfs.connect vfs.connect-directory vfs.copy vfs.cursor-position vfs.default-certificates-file vfs.delete-directory vfs.delete-file vfs.describe vfs.describe-file vfs.directory vfs.directory-name vfs.disconnect vfs.file vfs.file-directory vfs.file-name vfs.link vfs.list vfs.lock vfs.make-directory vfs.move vfs.move-cursor vfs.omvfs-version vfs.open vfs.open-file-system vfs.open-ftp vfs.open-http vfs.open-https vfs.reader vfs.set-default-certificates-file vfs.truncate vfs.unlock vfs.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]