TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Window Manipulation

Manipulation of TRIP kernel windows. More...

Functions

int TdbCheckScreenWindow (int windowType, int *windowId)
 Retrieve the identifier of a kernel output window.
 
int TdbDefineWindow (int windowType, int height, int width)
 Define a kernel window buffer for formatted output.
 
int TdbDeleteWindow (int windowNumber)
 Deletes the specified TRIP kernel window.
 
int TdbGetWindowHit (int windowType, int *linePosition, int *length)
 Retrieve the next hit word in a formatted line.
 
int TdbGetWindowHits (int windowType, int *hitCount, int **windowHits)
 Return hit words in a TRIP window.
 
int TdbGetWindowInfo (int windowType, char **windowBuffer, int *rowSize, int *colSize, int *rowCount, int *flags)
 Load all lines from a TRIP window.
 
int TdbGetWindowLine (int windowType, char *line)
 Load a formatted line from a TRIP window.
 
int TdbGetWindowType (int windowId, int *windowType)
 Returns the window type for a window.
 
int TdbSetScreenWindow (int windowType, int windowNumber)
 Set the identifier of a kernel output window.
 

Detailed Description

Manipulation of TRIP kernel windows.

This group of TRIPtoolkit functions cover manipulation of TRIP kernel windows. These are required to access TRIP features such as output formats via the SHOW command.

Function Documentation

◆ TdbCheckScreenWindow()

int TdbCheckScreenWindow ( int  windowType,
int *  windowId 
)

Retrieve the identifier of a kernel output window.

Parameters
windowTypeType of window to be retrieved
windowIdWindow identifier
Returns
1 or other odd value on success, even value on error

Description

The TdbCheckScreenWindow() can be used to gain the identifier of the output window associated with a particular type of output. This is especially useful when processing scrolling commands, such as More and Back, when it is important to know the identifier of the current window being scrolled. In this case, use the special constant CURRENT_WINDOW as the type argument. A window can be made current with a call to the TdbSetScreenWindow() function.

The window of the specified type must have been previously created by a call to the TdbDefineWindow() function.

Parameter Values

The windowType parameter is passed an int as the type of the window for which the identifier is to be retrieved. Valid values are:

Symbolic Constant Value of Constant Window Usage
CURRENT_WINDOW 0 Current window
SHOW_WINDOW 1 Show window
EXPAND_WINDOW 2 Expand window
DISPLAY_WINDOW 3 Display window
HISTORY_WINDOW 4 History window (Base, Find, List, etc)
SYSINFO_WINDOW 5 System information window (Help, STatus, TRace, etc)
PRINT_WINDOW 6 Print Local window

The windowId parameter is passed an integer as the actual identifier associated with the particular type of output. The identifier is by default equal to the type number.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
22690 Argument wintypenr - value out of range. The specified window type number was out of range.
See also
TdbDefineWindow()
TdbSetScreenWindow()

◆ TdbDefineWindow()

int TdbDefineWindow ( int  windowType,
int  height,
int  width 
)

Define a kernel window buffer for formatted output.

Parameters
windowTypeWindow type
heightNumber of rows
widthNumber of columns
Returns
1 or other odd value on success, even value on error

Description

The function TdbDefineWindow() defines a kernel memory buffer for holding the results of commands which produce output, such as Show and STatus. The value passed in the type parameter specifies what type of output this window is to be used for.

Most applications will simply define the six windows during program initialization, however if memory is a significant resource, then a program can choose to define only those windows that it will require.

The maximum window size (rows*cols) is 64KB.

Parameter Values

The windowType parameter is passed an int as the type of window buffer to be defined. The available window types are:

Window Name Constant Value Window Purpose
SHOW_WINDOW 1 Output from the Show order
EXPAND_WINDOW 2 Output from the Expand order
DISPLAY_WINDOW 3 Output from the Display order
HISTORY_WINDOW 4 Output from the History order
SYSINFO_WINDOW 5 Output from Help, Status, or Trace orders
PRINT_WINDOW 6 Output from Print Local order

The height parameter is passed an integer as the number of rows in the window.

The width parameter is passed an integer as the number of columns in the window.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
3618 Pagebuffersize size beyond limits. There is an upper limit of 64KB in how large a window can be. The specified value (rows*cols) exeeded that limit.
See also
TdbCheckScreenWindow()
TdbSetScreenWindow()

◆ TdbDeleteWindow()

int TdbDeleteWindow ( int  windowNumber)

Deletes the specified TRIP kernel window.

Parameters
windowNumberWindow number
Returns
1 or other odd value on success, even value on error

Parameter Values

The windowNumber parameter is passed the number of the TRIP window to be deleted. The window number is retrieved using TdbCheckScreenWindow().

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbCheckScreenWindow()

◆ TdbGetWindowHit()

int TdbGetWindowHit ( int  windowType,
int *  linePosition,
int *  length 
)

Retrieve the next hit word in a formatted line.

Parameters
windowTypeWindow type
linePositionPosition of hit word
lengthLength of hit word
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetWindowHit() returns the position of the next hit word in a formatted line within a TRIP window. It can only be called after first calling TdbGetWindowLine() . Successive hits on the the same line can be retrieved by calling the function TdbGetWindowHit() multiple times until a status code of 0 (zero) is returned.

Parameter Values

The windowType parameter is passed a the window type for which highlighting information is returned. Valid values are:

Symbolic Name Constant Value Purpose
SHOW_WINDOW 1 CCL Show window
EXPAND_WINDOW 2 CCL Expand window
DISPLAY_WINDOW 3 CCL Display window
HISTORY_WINDOW 4 CCL History window
SYSINFO_WINDOW 5 CCL Help, Status, Trace window
PRINT_WINDOW 6 CCL Print Local window

The linePosition parameter receives the position of the hit word within the current line.

The length parameter receives the length of the hit word.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 No more hits on the current TRIP window line.
See also
TdbGetWindowLine()

◆ TdbGetWindowHits()

int TdbGetWindowHits ( int  windowType,
int *  hitCount,
int **  windowHits 
)

Return hit words in a TRIP window.

Parameters
windowTypeWindow type
hitCountNumber of hits in window
windowHitsHit word locations
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetWindowHits() returns an array containing all hits in a TRIP window. It is called after a previous call to the TdbGetWindowInfo() function.

Parameter Values

The windowType parameter is passed the window type for which highlighting information is returned. Valid values are:

Symbolic Name Constant Value Purpose
SHOW_WINDOW 1 CCL Show window
EXPAND_WINDOW 2 CCL Expand window
DISPLAY_WINDOW 3 CCL Display window
HISTORY_WINDOW 4 CCL History window
SYSINFO_WINDOW 5 CCL Help, Status, Trace window
PRINT_WINDOW 6 CCL Print Local window

The hitCount parameter receives the number of hits in the window.

The windowHits parameter receives the address of an integer array with hit information. The size of the array is three times the number of hits (3 * hitCount ). Each hit is represented as a triplet where:

Nr in triplet Description
1 Row number the hit is on.
2 Column number the hit is on.
3 Length of hit item.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 The TRIP window did not contain any hits.
See also
TdbGetWindowInfo()

◆ TdbGetWindowInfo()

int TdbGetWindowInfo ( int  windowType,
char **  windowBuffer,
int *  rowSize,
int *  colSize,
int *  rowCount,
int *  flags 
)

Load all lines from a TRIP window.

Parameters
windowTypeWindow type
windowBufferBuffer to recieve information in window
rowSizeNumber of rows in buffer
colSizeNumber of columns in buffer
rowCountCount of rows filled
flagsPosition in output
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetWindowInfo() returns the whole contents of a TRIP window in one call.

Parameter Values

The windowType parameter is passed an int as the window type for which content is returned. Valid values are:

Symbolic Name Constant Value Purpose
SHOW_WINDOW 1 CCL Show window
EXPAND_WINDOW 2 CCL Expand window
DISPLAY_WINDOW 3 CCL Display window
HISTORY_WINDOW 4 CCL History window
SYSINFO_WINDOW 5 CCL Help, Status, Trace window
PRINT_WINDOW 6 CCL Print Local window

The windowBuffer parameter a string buffer that will recieve information in the window.

The rowCount parameter receives the count of how many rows of windowBuffer have been used. For example, if the output buffer is not completely filled by the data contained in the window because you are at the end of the output then the rowCount argument will be set to the number of lines actually used in the buffer. Otherwise, the value of the rowCount argument will be equal to the rowSize argument.

The colSize parameter receives the number of columns in the windowBuffer buffer.

The rowSize parameter receives the number of rows in windowBuffer buffer.

The flags parameter receives a bit vector indicating where in the output the window is positioned. Valid values are:

Bit Number Purpose
0 When bit 0 is set the window is covering the bottom of the output.
1 When bit 1 is set the window is covering the top of the output.
2 When bit 2 is set the window is subject to paged output (i.e., the output format being used has ended with a <FF> filter or has a page header/trailer defined).

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 The TRIP window did not contain any hits.

◆ TdbGetWindowLine()

int TdbGetWindowLine ( int  windowType,
char *  line 
)

Load a formatted line from a TRIP window.

Parameters
windowTypeWindow type
lineWindow line.
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetWindowLine() returns a line formatted for output in a TRIP kernel window. Repeated calls to this routine until it returns zero will retrieve each line in the window.

The window receives its contents when a CCL order which generates output for the window type in question is issued (using the TdbExecuteCcl() function). Prior to this, the window must have been defined by a call to the TdbDefineWindow() function.

If the window line contains hit words, these can be obtained by calling the TdbGetWindowHit() function.

Parameter Values

The windowType parameter is passed an int as the window type for which content is returned. Valid values are:

Symbolic Name Constant Value Purpose
SHOW_WINDOW 1 CCL Show window
EXPAND_WINDOW 2 CCL Expand window
DISPLAY_WINDOW 3 CCL Display window
HISTORY_WINDOW 4 CCL History window
SYSINFO_WINDOW 5 CCL Help, Status, Trace window
PRINT_WINDOW 6 CCL Print Local window

The line parameter receives the content of the current window line. Its minimum allocated size must be the window's defined row size plus one.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 No more lines are available.
See also
TdbExecuteCcl()
TdbDefineWindow()
TdbGetWindowHit()

◆ TdbGetWindowType()

int TdbGetWindowType ( int  windowId,
int *  windowType 
)

Returns the window type for a window.

Parameters
windowIdThe number of the window for which to request the type.
windowTypeThe window type of the specified window.
Returns
1 or other odd value on success, even value on error

Description

The TdbGetWindowType() function returns the window type for the window with the specified number.

The windowId parameter is passed a window number, or DEFAULT_WINDOW for the current window. This is a read-only value.

The windowType parameter recieves the type of the specified window. Window types are:

Symbolic Name Constant Value Purpose
SHOW_WINDOW 1 CCL Show window
EXPAND_WINDOW 2 CCL Expand window
DISPLAY_WINDOW 3 CCL Display window
HISTORY_WINDOW 4 CCL History window
SYSINFO_WINDOW 5 CCL Help, Status, Trace window
PRINT_WINDOW 6 CCL Print Local window
See also
TdbStartTrip()
TdbDefineWindow()
TdbSetScreenWindow()
TdbCheckScreenWindow()

◆ TdbSetScreenWindow()

int TdbSetScreenWindow ( int  windowType,
int  windowNumber 
)

Set the identifier of a kernel output window.

Parameters
windowTypeWindow type number
windowNumberWindow identifier
Returns
1 or other odd value on success, even value on error

Description

The function TdbSetScreenWindow() connects an identifier to a specified output window.

This routine should only be used to set the ID of the current window (CURRENT_WINDOW ), as the windows automatically receive an ID equal to the type when they are created by the TdbDefineWindow() function.

A window is set to be the current window when it receives content from an output-generating CCL command. A Show command, e.g., makes the SHOW window the current window and subsequent scroll commands, such as MORE and BACK, will operate on that window until another CCL command changes the status. Thus TdbSetScreenWindow() can be used to direct scrolling orders to a window other than that which most recently received output.

Parameter Values

The windowType parameter is passed an int as the window type number.

Symbolic Constant Value of Constant Window Usage
CURRENT_WINDOW 0 Current window
SHOW_WINDOW 1 Show window
EXPAND_WINDOW 2 Expand window
DISPLAY_WINDOW 3 Display window
HISTORY_WINDOW 4 History window (Base, Find, List, etc)
SYSINFO_WINDOW 5 System information window (Help, STatus, TRace, etc)
PRINT_WINDOW 6 Print Local window

The windowNumber parameter is passed an int as the window identifier.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbDefineWindow()