get_chan_info()

Return status information about a file or process channel.

Syntax

get_chan_info(channel,[flags],[separator])

Parameter

Parameter	Definition
channel	channel name (shared channels), channel number (local channels), or "" indicating all channels (subject to flags control)
flags	optional integer value that controls the format and content of the output Valid Values 1 global channels only 2 local channels only 3 both global and local channels Default 1 The flags parameter determines whether this function returns output in the short or long format. Omitflags to return the short format and include flags to return the long format. The get_chan_info() function ignores the value of flags unless channel equals "". For example, if channelis 208 and flags is 1, the function returns information about the local channel even though the 1 flag requests information about only global channels. The existence of the 1 flag, however, causes get_chan_info() to use the long format for the result.
separator	Specify a string to separate the channel fields displayed in the output of the function. A single space character is used by default. To aid in parsing when the field may contain spaces, such as a file channel open to a file at a path with spaces, it may be useful to specify a different separator.

Description

The get_chan_info() function returns channel information as a string. The string takes the form of the short or long format based on the existence of the flags parameter.

The following table shows the field names for each format and the following table shows the valid values for each field name.

Format of the Result of the get_chan_info() Function

Format	Field Names
short	status details
long	name status details type scope read_pid read_name write_pid write_name

Valid Values for the Result of the get_chan_info() function

Field	Valid Values
name	scope =SHARED--channel name scope =LOCAL--local channel number scope=" "--all shared and local channels
status	OPEN CLOSED
details	fopen() channel--file name that is opened or NONE if no file name is open popen() channel--process ID of the external operating system process to which the channel is attached or -1 if the process has terminated

Warning: For fopen(), a space in the name of the file or directory path adds an unwanted space to the text string returned by get_chan_info(). An extra space is a problem because the string is delimited by spaces. You can specify a different delimiter by specifying a string for separator|

type	PIPE FILE
scope	SHARED LOCAL
read_pid	process ID of the PSL process waiting to be read from the channel -1 if no process is waiting
read_name	name of the process waiting to be read from the channel NONE if no process is waiting UNAVAILABLE if the process name is not available
write_pid	process ID of the PSL process waiting to be written to the channel -1 if no process is waiting
write_name	name of the process waiting to be written to the channel NONE if no process is waiting UNAVAILABLE if there is a process but the name is not available

The get_chan_info() function returns all the fields for each channel even if they do not apply to the particular channel.

When information is returned for more than one channel, the channel descriptions are formatted as a list with one channel per line separated by new-line characters.

If the flags parameter is nonnumeric or less than one, the get_chan_info() function produces a run-time warning, and the PSL errno variable remains zero.

The get_chan_info() function returns the NULL string under the following circumstances:

no channels exist for the given value of flags
a bad channel number or name is specified for channel
In this case, the get_chan_info() function also sets the PSL errno variable to 40 (E_PSL_GET_CHAN_INFO_BAD_CHANNEL ).

Example

Omitting the flags parameter in the following example returns descriptions for all global shared channels, but returns no information for local channels:

get_chan_info("");

The following example returns descriptions for the local, global, or both local and global channels as controlled by the value of flags:

get_chan_info("",flags);

The following example returns the description of the local or global channel specified by the value of channel:

get_chan_info("channel");

The following example prints both the short and long formats:

file_name = "C:\\Program Files\\BMC Software\\Patrol3\\lib\\config.default";
chan1 = fopen(file_name,"r");
print("Short form of output\n".get_chan_info(chan1));
print("\n\nLong form of output\n".get_chan_info(chan1,1));
print("\nLong form of output with separator\n".get_chan_info(chan1,1,"|"));

The preceding code creates the following output:

Note

In the preceding output, the details field contains spaces in the path directory name. See Valid Values for the Result of the get_chan_info() function .