System Functions

TCB(FILE | OBJECT | WINDOW | CONTROL)

Return Active Elements

Format

1. Return Open (and Accessible) Files:	TCB(FILE index [,ERR=stmtref])
2. Return Existing Objects:	TCB(OBJECT index [,ERR=stmtref])
3. Return Open Windows:	TCB(WINDOW index [::name] [,ERR=stmtref])
4. Return Existing Controls:	TCB(CONTROL index [,ERR=stmtref])

Where:

index

A numeric value containing either 0 (to retrieve the count of elements) or the index of the desired element.

stmtref

Program line number or statement label to which to transfer control.

::name

Can be any of the following window attributes for which information is to be retrieved:

::name	Return Value
::Columns	Number of columns wide.
::Lines	Number of lines high.
::CurrentColumn	Current column.
::CurrentLine	Current line.
::AbsColumn	Column window was created at (*not current if moved*).
::AbsLine	Line window was created at.
::ScrollColumn	Scroll region column.
::ScrollLine	Scroll region line.
::ScrollColumns	Scroll region number of columns.
::ScrollLines	Scroll region number of lines.
::LeftColumn	Leftmost column displayed on screen.
::TopLine	Top line displayed on screen.
::ViewableColumns	Number of visible columns.
::ViewableLines	Number of visible lines.
::IsDialogue	Returns 1 if a Dialogue window; else 0.

(The ::name option was added in PxPlus 2021.)

Description

The TCB(FILE | OBJECT | WINDOW | CONTROL index) function is designed to allow the programmer an easy method to determine which elements are currently in existence/active in the system.

In all cases when using this function, if the value in index is zero, the function will return the number of currently active elements. For example, TCB(OBJECT 0) will return the total number of objects currently active in the system.

If the value of index is non-zero, it is considered the relative number of the specified element. For example, TCB(WINDOW 2) will return the window number of the second relative window (the window directly behind the current one).

If the value of index is < zero or greater than the number of elements, an Error #41: Invalid integer encountered will be generated and an error exception will occur.

Using this function with the ::name option provides the ability to access a number of window attributes.

(The TCB(FILE | OBJECT | WINDOW | CONTROL index) function was added in PxPlus v7.00.)

Format 1

Return Open/Accessible Files

TCB(FILE index [,ERR=stmtref])

This function will return the count and channel number for open and currently accessible files. Files that are opened exclusively by objects and thus may not be accessible are not included.

If this function is invoked from within an object that does have access to the file, it will be included in the count. The return value for a non-zero index will be the file channel number. TCB( FILE 1) will always return zero.

Format 2

Return Objects Handles

TCB(OBJECT index [,ERR=stmtref])

This function will return the count and handle numbers for the PxPlus objects that currently exist in the system. The return value for a non-zero index will be the object number (handle).

Format 3

Return Open Windows

TCB(WINDOW index [::name] [,ERR=stmtref])

This function will return the count and window numbers for all the windows currently in existence. The values returned will reflect the display order of the windows; thus, TCB(WINDOW 1) will return the current window number. The return value for a non-zero index will be the window number.

When used with the ::name option, the index must be a variable, not a literal window number or expression. This function provides the ability to access information for the Window Attributes in the table above.

Example:

This example uses the ::Columns option to return the width of the current window:

X = TCB(WINDOW 1)
TCB(WINDOW X::Columns)

(The ::name option was added in PxPlus 2021.)

Format 4

Return Control Handles

TCB(CONTROL index [,ERR=stmtref])

This function will return the count and CTL value associated with all the controls currently in use. This will include all controls in the current window (whether hidden or disabled) and controls in any concurrent windows. Global controls are not accessible.

The return value for a non-zero index will be the CTL value associated with the control.

Note:
When using the TCB(CONTROL index) function under WindX, the system will have to send the request to the workstation in order to get the value. This can result in performance problems when used repeatedly. The suggestion is that if you want to access the list of active controls, you should use the FIN (0, "CTLLIST") function, which will return a comma-separated list of CTL numbers.