TRIPsystem Kernel API 8.3
|
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. | |
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.
int TdbCheckScreenWindow | ( | int | windowType, |
int * | windowId | ||
) |
Retrieve the identifier of a kernel output window.
windowType | Type of window to be retrieved |
windowId | Window identifier |
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.
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.
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. |
int TdbDefineWindow | ( | int | windowType, |
int | height, | ||
int | width | ||
) |
Define a kernel window buffer for formatted output.
windowType | Window type |
height | Number of rows |
width | Number of columns |
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.
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.
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. |
int TdbDeleteWindow | ( | int | windowNumber | ) |
Deletes the specified TRIP kernel window.
windowNumber | Window number |
The windowNumber
parameter is passed the number of the TRIP window to be deleted. The window number is retrieved using TdbCheckScreenWindow().
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetWindowHit | ( | int | windowType, |
int * | linePosition, | ||
int * | length | ||
) |
Retrieve the next hit word in a formatted line.
windowType | Window type |
linePosition | Position of hit word |
length | Length of hit word |
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.
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.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | No more hits on the current TRIP window line. |
int TdbGetWindowHits | ( | int | windowType, |
int * | hitCount, | ||
int ** | windowHits | ||
) |
Return hit words in a TRIP window.
windowType | Window type |
hitCount | Number of hits in window |
windowHits | Hit word locations |
The function TdbGetWindowHits() returns an array containing all hits in a TRIP window. It is called after a previous call to the TdbGetWindowInfo() function.
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. |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | The TRIP window did not contain any hits. |
int TdbGetWindowInfo | ( | int | windowType, |
char ** | windowBuffer, | ||
int * | rowSize, | ||
int * | colSize, | ||
int * | rowCount, | ||
int * | flags | ||
) |
Load all lines from a TRIP window.
windowType | Window type |
windowBuffer | Buffer to recieve information in window |
rowSize | Number of rows in buffer |
colSize | Number of columns in buffer |
rowCount | Count of rows filled |
flags | Position in output |
The function TdbGetWindowInfo() returns the whole contents of a TRIP window in one call.
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). |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | The TRIP window did not contain any hits. |
int TdbGetWindowLine | ( | int | windowType, |
char * | line | ||
) |
Load a formatted line from a TRIP window.
windowType | Window type |
line | Window line. |
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.
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.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | No more lines are available. |
int TdbGetWindowType | ( | int | windowId, |
int * | windowType | ||
) |
Returns the window type for a window.
windowId | The number of the window for which to request the type. |
windowType | The window type of the specified window. |
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 |
int TdbSetScreenWindow | ( | int | windowType, |
int | windowNumber | ||
) |
Set the identifier of a kernel output window.
windowType | Window type number |
windowNumber | Window identifier |
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.
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.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |