Write Method
Writes data to the output queue.
Syntax
Syntax
Visual Basic
object.Write WriteBuffer [, NumBytesToWrite, Timeout]
Visual C++
object.Write(CString/BSTR/char* WriteBuffer, long NumBytesToWrite, long Timeout)
Delphi
object.Write(const WriteBuffer: WideString;
NumBytesToWrite: Integer; Timeout: Integer): Integer;
| Part
| Description |
| object |
An object expression that evaluates to a PortController object. |
| WriteBuffer |
A string containing the data to be written to the output queue.
|
| NumBytesToWrite |
A long integer indicating the number of bytes to be written to the output queue.
|
| Timeout |
A long integer indicating the amount of time in milliseconds to wait
before terminating the operation. Omitting this parameter or setting it to 0 causes the function to perform a write
and return immediately. Setting this parameter to a negative value causes the function to wait until the
write operation completes before returning.
|
Example
Visual Basic
myPortController.Write "This is a test"
myPortController.Write "This is a test", 9 'Writes "This is a"
myPortController.Write "This is a test", , 1000 'Times out after one second
myPortController.Write "This is a test", 9, -1 'Writes "This is a" and waits for the
'write to complete before returning
Visual C++
m_myPortController.Write("This is a test", 0, 0); // Writes "This is a test."
m_myPortController.Write("This is a test", 9, 0); // Writes "This is a"
m_myPortController.Write("This is a test", 0, 1000); // Times out after one second
m_myPortController.Write("This is a test", 9, -1); // Writes "This is a" and waits for the
// write to complete before returning
Delphi
myPortController.Write('This is a test', 0, 0); // Writes "This is a test."
myPortController.Write('This is a test', 9, 0) // Writes "This is a"
myPortController.Write('This is a test', 0, 1000) // Times out after one second
myPortController.Write('This is a test', 9, -1) // Writes "This is a" and waits for the
// write to complete before returning
Remarks
The NumBytesToWrite and Timeout parameters are optional (to omit these
parameters in VC++ and Delphi, simply pass 0 as the value). When the NumBytesToWrite parameter is omitted
or set to 0 the entire specified string is written to the output queue. When the Timeout parameter
is omitted or set to 0, the function does not wait for the operation to complete before returning. If Timeout is a negative value, this function will block until the write operation
completes. This will likely lock up the application and its UI if the device receiving the data has indicated
it is not ready to receive data and handshaking is enabled. See Reading and Writing Binary Data for
details on using Write() with outgoing binary data.
Returns
An integer indicating the number of bytes written to the output queue. If Timeout is 0, the return value
will be 0 if either no data was written, or no data has yet been written.
Errors
Attempting to write to the output queue when the port is closed will cause
the PortController to throw a "Port is closed." exception. If an error occurs during the write, a
"An error occurred while trying to place data in output queue." exception is thrown. Attempting to set NumBytesToWrite to a negative value
will cause the PortController to throw an "Invalid argument" exception. If there are greater than 10000 write operations queued for processing (occurs when Timeout is 0), a
"Maximum outstanding write operations limit has been reached" exception is thrown and
the write operation is ignored. This error will never occur when requiring a write operation to complete before control is returned by specifying a non-zero value for Timeout.
See Also
Open(), Read()
|
