Micro Focus Visual COBOL 2.3 Update 2 for Eclipse (Windows) > General Reference > C Functions for Calling COBOL > cobtermmode

cobtermmode

Toggles the terminal screen between standard and wide modes.

Restriction: This function is supported for native COBOL only.

Syntax:

#include "cobscreen.h"

int cobtermmode(const cobuns8_t *mode);

Parameters:

mode

The terminal mode; the address of a byte that is either 0 or 1.

Comments:

This routine toggles the terminal screen between default and wide modes, if this functionality is present in the terminfo database for the terminal type you are using.

To function correctly, the terminfo database must support a terminal whose name is the current terminal type with a -w suffix, and the terminfo entries must also have appropriate initialization and/or reset capabilities. For example, if the current terminal is vt100 then there also needs to be a vt100-w in the terminfo database and the vt100 and vt100-w need appropriate is1, is2, is3, rs1, rs2 and/or rs3 entries.

The mode parameter should be 0 to put the terminal into standard (default) terminal mode or 1 to put the terminal into wide terminal mode. Any other value gives undefined results.

When the terminal mode is successfully toggled, the screen handling system is initialised (if it wasn't already), the screen is cleared and the cursor positioned in the home position.

This routine can be safely called from COBOL. See the section Wide Terminal Modein the chapter Terminfo Database and Terminal Devices of yourUser's Guide for more details.

When using this routine, you must be aware of the following:

The number of columns in wide mode must not exceed 255
When running under Animator, this call causes the terminal to be initialized to the new mode which can produce some flicker of the display. Switching between Animator and user screens causes mode changes as the wide terminal mode is not supported for Animator's screen.
When the run-time system exits, the terminal is restored to normal mode. This applies only to mode changes made under the control of this call.
The usual terminfo path-searching rules are used. Therefore, if the directory pointed to by COBTERMINFO contains an entry for the terminal in normal mode, but not wide mode and the system terminfo directory does contain an entry for the terminal in wide mode, the normal mode uses the COBTERMINFO version and the wide mode uses the system version. This can cause unexpected results where the two files differ in capabilities other than column size changes.
See the chapter Terminfo Database and Terminal Devicesin yourUser's Guide for more details on the terminfo search order.
If you have already set the TERM environment variable to indicate that a wide mode is required (that is the TERM value already has a -w suffix), issuing the call to use wide mode results in a suffix of "-w-w". This almost certainly fails, unless the terminal has a double wide mode and a terminfo file for this mode is available.

This routine returns 0 on success, non-zero on error. The following error values are currently returned

1	The terminfo file has not been found, is not readable, is corrupt or there is not enough memory.
2	The terminfo file does not contain one or more of the required capabilities.
3	The environment does not support the requested code.

Equivalent COBOL Syntax:

call "cobtermmode" using mode

Example:

The following code switches the terminal into wide mode, displays some text, waits for a keypress and restores the terminal back to normal mode:

cobuns8_t mode_on=1, mode_off=0;

if (cobtermmode(&mode_on) == 0)
{
    /* Display some text over beyond column 80 to demo */
    /* wide mode */
    cobmove(10, 100);
    cobprintf("Line 10, Column 100");
    cobgetch();
    /* Wait for a key press */
    
    cobtermmode(&mode_off);
    /* Back into standard mode */
}