Table of Contents

OIL2 Class Standard.IOobject


class Standard . IOobject {
        int32   deleteOnClose;
        int32   ioID;
        int32   selectFlags;
inherits from Object;

DESCRIPTION

The IOobject class is the base class for all I/O objects. Because it can handle multiple transport schemes, derived classes that implement specialized functionality are uncommon.

METHODS


Standard.IOobject:create

IOobject:create(any name)

Method Description

See initialize.


Standard.IOobject:initialize

IOobject:initialize(any name)

Method Description

The initialize method takes a single argument that indicates the transport mechanism, address and desired operation.

Return Value

The underlying Id for the descriptor is returned; it will be set to -1 if an error has occurred.


Standard.IOobject:getID

IOobject:getID()

Method Description

The getID method returns the Id of the underlying I/O descriptor for this object and is intended to indicate whether or not the IOobject was successfully initialized. If the object was not successfully created, -1 is returned. Any value other than -1 is intended to indicate a successfully opened I/O service.

Semantics


Standard.IOobject:getDescriptor

IOobject:getDescriptor()

Method Description

The getDescriptor method returns the underlying file descriptor/handle for the IOobject. If the object was not successfully created or the underlying I/O service does not make use of a file description, -1 is returned.


Standard.IOobject:setDeleteOnClose

IOobject:setDeleteOnClose()

Method Description

The setDeleteOnClose method sets a delete-on-close flag, which will cause the IOobject to be automatically deleted (it sends itself a deleteYourself message) when all associated descriptors are closed. By default, the flag is not set. Once the delete-on-close flag has been set by setDeleteOnClose, it can be cleared by the clearDeleteOnClose method. This is most commonly used when handing an IOobject off to another application that will not delete an object that it did not create. The class SendFile, which attempts to perform optimal copying of data between two opened IOobject objects, is an excellent example of such an application.

Return Value

The constant value 0 is returned.


Standard.IOobject:clearDeleteOnClose

IOobject:clearDeleteOnClose()

Method Description

The clearDeleteOnClose method is the inverse of the method setDeleteOnClose. It clears the delete-on-close flag. If an end-of-file condition is reached, the IOobject object will not automatically delete itself.

Return Value

The constant value 0 is returned.


Standard.IOobject:open

IOobject:open(string name)

Method Description

The open method is identical in behavior to the initialize method, with the exception that it will close any existing I/O association.

Return Value

If fromObject is not nil, the value of the underlying I/O descriptor for the object is returned (see getID for details). If the open operation was not successful, -1 is returned.


Standard.IOobject:readBytes

IOobject:readBytes(optional int32 bytesToRead, optional int32 bfrSize)

Method Description

Data is retrieved from a stream using the readBytes method. The number of desired bytes of data is passed as the first argument, bytesToRead. If bytesToRead is set to -1 or nil, the read will return all data available up to some reasonable buffer size (the exact size can be obtained by retrieving the system information attribute IOmaxReadBuffer).

In some situations, the exact amount of the data to be read is known to an application ahead of time. As an example, consider a file whose length was obtained using the getFileInfo() function or an interprocess message prefixed with a length. Rather than performing a read into an internal buffer and then copy the result to a string, the data can be read directly into the result string if the optional argument bfrSize is set to the correct size.

Return Value

If fromObject is nil, this method will return no value; otherwise:


Standard.IOobject:seekToOffset

IOobject:seekToOffset(int32 offset)

Method Description

For some media, such as files, the position pointer associated with the open descriptor can be altered using seekToOffset.

Return Value

If unsuccessful, -1 is returned; otherwise, the offset is returned.


Standard.IOobject:seekThenRead

IOobject:seekThenRead(int32 offset, int32 bytesToRead, optional int32 bfrSize)

Method Description

The seekThenRead method is a combination of seekToOffset and readBytes. A seek is performed to offset and then number of bytes indicated by bytesToRead is retrieved.

Return Value

See readBytes.


Standard.IOobject:writeBytes

IOobject:writeBytes(string dataToSend)

Method Description

The writeBytes method outputs the contents of a string to an I/O stream. A more powerful facility is provided by writeVectorOfBytes.

Return Value

If fromObject is not nil, then the number of bytes written to the stream is returned. If the buffer fills up in the process of writing data to the output stream, this routine will wait for it to drain so that the I/O operation can proceeed, thus partial writes are an indication that an error was encountered.


Standard.IOobject:writeVectorOfBytes

IOobject:writeVectorOfBytes(int32 skipOffset, string data1, optional string data2)

Method Description

The writeVectorOfBytes method implements a powerful I/O primitive that minimizes the number of bytes of data that must be copied in order to perform an I/O operation. It takes a minimum of two arguments:

Logically, the data to be sent is formed by concatenating all of the strings and then deleting the initial number of bytes indicated by skipOffset. The underlying implementation performs no actual concatenation nor modification of the source strings, so the data is copied only once from the address space of the FARGOS/VISTA Object Management Environment process into the kernel.

Return Value

If fromObject is not nil, then the number of bytes written to the stream is returned. If the buffer fills up in the process of writing data to the output stream, this routine will wait for it to drain so that the I/O operation can proceeed, thus partial writes are an indication that an error was encountered. While waiting for the kernel's I/O buffer to drain, all other threads within the FARGOS/VISTA Object Management Environment will continue execution.


Standard.IOobject:sendDatagram

IOobject:sendDatagram(string dataToSend, string destination)

Method Description

The sendDatagram method sends a datagram, whose contents are specified by the string dataToSend, to another communications port, whose address is specified in destination. The IOobject must have been created using a datagram-based protocol. The most common such protocol is the User Datagram Protocol (UDP) of the TCP/IP version 4 protocol suite. Other transport schemes that use datagrams include:

The corresponding method receiveDatagram is used to receive datagrams.

Return Value

If fromObject is not nil, then the number of bytes written when sending the datagram is returned. Normally, this is the same as length(dataToSend), but it may be -1 if an error was detected locally. Many datagram-based protocols are unreliablea by design, such successfully sending a datagram does not usually carry with it an assurance that it was received by the target destination.


Standard.IOobject:receiveDatagram

IOobject:receiveDatagram(any maxBytes)

Method Description

The receiveDatagram method receives a datagram that was sent to the communications port represented by the IOobject. The IOobject must have been created using a datagram-based protocol. The most common such protocol is the User Datagram Protocol (UDP) in the TCP/IP protocol suite. The corresponding method sendDatagram is used to send datagrams.

Return Value

If a datagram is successfully received, a two-element array is returned. The first element of the array (subscript 0) contains a string that holds the contents of the datagram. The second element of the array holds a string that identifies the transport address of the sender, which is in a format identical to that returned by getLocalAddress and getPeerAddress. The selectForRead or waitUntilReadyForRead methods can be used to ensure that a datagram is available prior to invoking receiveDatagram.


Standard.IOobject:selectForRead

IOobject:selectForRead(optional oid clientObj)

Method Description

An object can request to be notified when there is data available for reading using the selectForRead method. Normally the object to be notified is implied as being the fromObject, but the selectForRead method takes an optional argument that permits the specification of an alternate client. The client object is sent a canRead message and passed the object Id of the IOobject.

Return Value

This method does not return a value.


Standard.IOobject:waitUntilReadyForRead

IOobject:waitUntilReadyForRead()

Method Description

The waitUntilReadyForRead method can be used to block the progress of a thread until data is available. It is intended to be used by an RPC-style method invocation, thus a value is returned only when data is available for reading.

Return Value

An integer value indicating the pending status of any other selectForRead or selectForWrite operations is returned. Typically, the value will be zero, but a simultaneous selectForWrite might be on-going, in which case the return value will be 2.


Standard.IOobject:selectForWrite

IOobject:selectForWrite(oid clientObj)

Method Description

The selectForWrite method is identical to selectForRead, except that it sends a canWrite message (instead of canRead) when it is possible to write more data on the IOobject.


Standard.IOobject:waitUntilReadyForWrite

IOobject:waitUntilReadyForWrite()

Method Description

The waitUntilReadyForWrite method is identical to waitUntilReadyForRead, except that it returns a value when it is possible to write more data on the IOobject.

Return Value

An integer value indicating the pending status of any other selectForRead or selectForWrite operations is returned. Typically, the value will be zero, but a simultaneous selectForRead might be on-going, in which case the return value will be 1.


Standard.IOobject:acceptConnection

IOobject:acceptConnection(assoc acl)

Method Description

New connections can be accepted from an IOobject that is in a listen state by using the acceptConnection method. It takes a single argument, which is an access control list to be set for the new IOobject that is associated with the accepted connection.

Return Value

This method returns the object Id of the IOobject that represents the new connection. A nil value indicates an error.


Standard.IOobject:closeForRead

IOobject:closeForRead()

Method Description

Some connections are bi-directional and closeForRead permits one end of the connection to be closed. No further reads will be possible. If the delete-on-close flag is set (see setDeleteOnClose), the object will automatically be deleted.

Return Value

If fromObject is not nil, then a value is returned indicating the success of the request. A value of 0 indicates success, -1 indicates an error.


Standard.IOobject:closeForWrite

IOobject:closeForWrite()

Method Description

Some connections are bi-directional and closeForWrite permits one end of the connection to be closed. No further writes will be possible.

Return Value

If fromObject is not nil, then a value is returned indicating the success of the request. A value of 0 indicates success, -1 indicates an error.


Standard.IOobject:getLocalAddress

IOobject:getLocalAddress()

Method Description

The getLocalAddress method returns the transport address associated with the IOobject. This method is supported for all instances of IOobject, including files.


Standard.IOobject:getPeerAddress

IOobject:getPeerAddress()

Method Description

The getPeerAddress method returns the transport address of the endpoint associated with the IOobject. While this method can be invoked on any IOobject, a useful return value is obtained only for connected streams.