read()

Read from a PSL file or process channel.

Syntax

read(channel,[size])

Parameter

Parameter	Definition
channel	process I/O channel number from which the read() function reads data
size	optional integer value controlling the amount of data that the read() function reads from channel Valid Values size = 0 read() returns as soon as it has read something from the channel. size = -1 read() returns all data available by either reading until the end of file on a channel opened with fopen(), or by blocking until the child process completes for a channel opened with popen(). size = n, where n is a number greater than zero read() returns n bytes from the output of the channel. As with -1, read() operates in blocking mode. size = "n", where "n" is a literal switch read() performs a non-blocking read of all data available and returns control immediately. If no text is available, the empty string is returned and the errno variable is not set. The non-blocking mode only applies to channels opened by popen() --it is ignored without error for channels opened by fopen(). Note: Do not compare the output to EOF. Use the chan_exists() function to determine if the channel is still open. See Example section. Default size = 0\|

Parameter

Definition

channel

process I/O channel number from which the read() function reads data

size

optional integer value controlling the amount of data that the read() function reads from channel

*Valid Values*

size = 0 read() returns as soon as it has read something from the channel.
size = -1 read() returns all data available by either reading until the end of file on a channel opened with fopen(), or by blocking until the child process completes for a channel opened with popen().
size = n, where n is a number greater than zero read() returns n bytes from the output of the channel. As with -1, read() operates in blocking mode.
size = "n", where "n" is a literal switch read() performs a non-blocking read of all data available and returns control immediately. If no text is available, the empty string is returned and the errno variable is not set. The non-blocking mode only applies to channels opened by popen() --it is ignored without error for channels opened by fopen().
Note: Do not compare the output to EOF. Use the chan_exists() function to determine if the channel is still open. See Example section.

Default
size = 0|

Description

The read() function returns the data it reads one byte at a time from channel. The read() function returns the value EOF (that is, the NULL string) on an end-of-file or error condition.

Channels are created by calling the fopen() or popen() function. (For more information, see fopen() and popen().)

Note

The read() function can block for a process channel created using the popen() function but not for a file channel created using the fopen() function.

To enforce serialization for shared channels, no two reader processes (that is, read() or readln() functions) can be blocked on the same channel. The second reader process that attempts to block on the shared channel will fail, returning the NULL string and setting the PSL variable errno to E_PSL_BUSY_CHANNEL.

Another possible shared channel failure can be caused by a close() function being executed against a channel that also has a blocked reader process. The close() function will cause the reader process to return the NULL string and set errnoto E_PSL_UNBLOCKED_BY_CLOSE.

Issues for Internationalized PSL Scripts

The issues in this section require that you understand how to create Internationalized PSL scripts. For more information about Internationalized PSL scripts, see PATROL Script Language Reference Manual Volume 1 --PSL Essentials.

Codeset Conversion

When you use the popen() or fopen() function to open a channel, the codeset of the CODECVT locale category becomes the registered codeset of the channel. If the registered codeset differs from the CTYPE locale category, read() converts the codeset and returns text in the CTYPE codeset.

Size Parameter and Multi-byte Characters

The size parameter specifies the number of bytes that the function reads from the channel. Do not use this parameter if you expect to read multi-byte characters. Using size with multi-byte characters could cause read() to read only part of a multi-byte character. Also consider using the readln() function, which poses no risk of truncating multi-byte characters.

Example

The following PSL example shows a blocking use of the read() function. This example opens a channel to the Windows operating system, executes a Windows dir command, and prints the directory entries returned by the dir command.

chan = popen ("OS", "dir");
data = read (chan,"-1");
print (data);
close (chan);

This example uses the read() function in non-blocking mode.

# This PSL script connects to an ftp server or times out after 10 seconds
# if it cannot connect.
IP = "ftp.bmc.com";
timeout = 10;
FTPChan = popen("OS", "ftp -nv ".IP);
timeouttime = time()+timeout;
do {
# The sleep stops this script consuming large amounts of CPU time
# due to looping whilst waiting for data
sleep(1);
data = read(FTPChan,"n");
} until(!chan_exists(FTPChan) || data!="" || (time()>=timeouttime));
# Either some data has been read or the timeout has expired.
if(!chan_exists(FTPChan) || data=="") {
# Tidy up
if(chan_exists(FTPChan)) {
close(FTPChan);
}
print("Connection failed!\n");
} else {
DataRead = DataRead.data;
print(DataRead);
# Carry on reading/writing to the channel. Data was returned.
print("Data returned on the channel\n");
}