Aptilis manual: Open

Open		Streams
Aptilis 2

Open([protocol://]Path/Domain[:port][,mode])

This predefined sub opens a stream.

What is a stream?
A stream is an advanced facility for you to read and write files a specified amount of bytes at a time, as opposed to LoadFile and SaveFile which read and write WHOLE files in one go without giving you a choice.

Protocols - Aptilis streams support three protocols:
- file://
- socket://
- ssl://

Ssl:// is the same as socket, except that this is using SSL encryption. As of this writing Aptilis does not offer any functionality to deal with certificates.

Modes - for file:// only
One of "read", "write", "writeread" or "readwrite" - it's NOT case-sensitive.

The same Aptilis predefined subs can be used indifferently to read and write to either files or sockets. Sockets allow computers to talk to each other over Networks.

File example: file:///c:/test/testFile.txt (PC) or file:///test/testfile (Unix)
Socket example: socket://www.cnn.com:80
As far as sockets are concerned, no assumption is made about the protocol. Because protocols usually define a port, it's up to you to explicitly specify a port (here 80, standard http port).

Yes, sockets will allow you plenty of hacking possibilities!

Each consecutive read or write operation will augment a hidden 'cursor' or position. To go back or move forward use SetPosition and GetPosition if you need to find out where in the stream you are.

Important Notes

- File streams need a mode. If you don't specify one, 'read' is assumed by default.
The 'mode' is ignored for sockets, even if you specify one.

- Files are always opened in 'append' mode. If you want to write a file from scratch, make sure you call DeleteFile on it first.

- Opening more than one stream to the same file may yield unpredictable results, especially if the file has been locked with Lock.

- To get a stream to a locked file, proceed as follows:
+ Lock the file - even if it does not exist yet.
+ Use open on the file name to get a stream.
+ Do your read / write stuff on the stream.
+ Once finished, call Unlock on the filename. DO NOT close it! Unlock will have closed it for you. Closing a file before unlocking will cause your file not to be written properly.

- On PC platforms file streams are opened in 'Binary' mode, that means you get to write exactly what you specified and read exactly what's there.

- Make sure you close streams once you're done with them. Aptilis will close opened streams for you if you've forgotten to do so, but if you don't close streams and then re-open them, you may get funny results. (For example data you've written may be lost.)

- All sockets are of TCP/IP ones and of type SOCK_STREAM. (Technical)

Return Value:
A Stream (in effect a number) to use with the other stream subs or -1 in case of error, in which case _errno$ will give you more details.

Example 1:
Files

sm1 = open("file://test.txt", "write")
write(sm1, "Little Red Hood")
close(sm1)

// Now we have a file called 'test.txt' in the current
// directory of our disk.


// if not protocol is specified, file:// is assumed by default
sm2 = open("test.txt", "read")
setPosition(sm2, 7)
piece = read(sm2, 3) $

print("I read: ", piece$, "\n")

close(sm2)

Result:

I read: Red

Example 2:
Opening a socket and playing with the http protocol. Here we will get 500 characters from the CNN website. Use LoadFile if you want the entire web page.

s = open("socket://www.cnn.com:80")

write(s, "GET / HTTP/1.0\r\nAccept: *\r\n\r\n")
p = read(s, 500) $
print(p$)

close(s)

Result:

HTTP/1.0 200 OK
Date: Thu, 13 Dec 2001 01:56:30 GMT
Server: Netscape-Enterprise/4.1
Last-Modified: Thu, 13 Dec 2001 01:56:31 GMT
Expires: Thu, 13 Dec 2001 01:57:31 GMT
Cache-Control: private, max-age=60
Content-Type: text/html
Age: 72
Via: HTTP/1.0 ntl_site (Traffic-Server/3.5.7-10686 [uScMsSf pSeN:t cCMi p sS])

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang=

See also: Close, Read, ReadLine, Write, SetPosition, GetPosition
and:
LoadFile and SaveFile.