Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management. Open link

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 

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:

Short form of output
OPEN C:\Program Files\BMC Software\Patrol3\lib\config.default
Long form of output
3 OPEN C:\Program Files\BMC Software\Patrol3\lib\config.default FILE LOCAL -1 <NONE>
-1 <NONE>
Long form of output with separator
3|OPEN|C:\Program Files\BMC Software\Patrol3\lib\config.default|FILE|LOCAL|-1|<NONE>|
-1|<NONE>

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 .

Was this page helpful? Yes No Submitting... Thank you

Comments