HP 3000 Manuals HP 3000 Manuals
Operation
This section covers the concept of devices, terminal handling
considerations, and terminfo entries.
Devices
Built into the compiler and the RTS is the concept of certain devices. A
program that reads from the standard input device
stdin will access the standard UNIX input.
A program that writes to the standard output device
stdout will access the standard UNIX output.
A program that writes to the standard error device
stderr will access the standard UNIX error output. All Micro Focus
utilities write error messages to the error output, and not to standard
output. At run time the Run- Time System recognizes sequential or
line-sequential files opened with these names and directs its output to
the appropriate target. Similarly, any sequential or line-sequential
files can be redirected
to or from stdin, stdout or stderr by using file-name mapping, as
described in Chapter 14 , Callable File Handler. Note that if stdin
is line sequential the first READ can be from the command line tail,
depending on cobconfig. (See Chapter 31 , Run-Time Configuration for
details of cobconfig.)
Your system emulates printer channels
C01 through C12 by line feeds and form feeds. If you want to write to
these channels you should set the environment variable COBLPFORM
to define the line numbers on the form. This must consist of a series of
numbers separated by colons as in the following example:
COBLPFORM = "1:::::::::::60"
This sets channel 1 to line 1 (the beginning of the page) and channel 12
to line 60. You can specify only a single line number for each channel.
Those channels which have line number zero; mnemonics S01, S02, CSP; or
are undefined, are set to line 1. See Appendix I , Environment
Variables for details of COBLPFORM.
Any WRITE BEFORE/AFTER PAGE
statements cause positioning at line 1. Each line that is advanced
increases the line number by one. A request to skip to a line number
less than or equal to the current line causes a new page to begin. The
appropriate number of line feeds are then generated.
Any WRITE BEFORE/AFTER TAB
statements generate a form feed and cause any subsequent skips to a
channel number to start a new page.
Printing
The system provides support for the DISPLAY UPON PRINTER
clause, and for printer control and string printing.
The DISPLAY UPON PRINTER Statement.
The DISPLAY UPON PRINTER statement writes single messages to the standard
input of a spawned process. See your Language Reference for full details
on this syntax. You can specify the process to be spawned by using the
COBPRINTER environment variable.
You may include a command line in the COBPRINTER environment variable,
but by default the DISPLAY UPON PRINTER statement writes messages to the
spawned process /usr/bin/lp. See Appendix I , Environment Variables
for details of COBPRINTER.
The data given in this form of the DISPLAY statement is piped to the
spooler,
and a line is thrown unless you have specified the WITH NO ADVANCING
option. Once the data has been written, the pipe to the spooler process
is closed.
The code to execute this command is found in the function lprdisp()
in lprdisp.o which is located in libcobol.a. This defines the function
parameters as follows:
lprdisp(buf, len, naflag)
char *buf;
int len, naflag;
where:
buf is a pointer to the characters to be displayed
len is the number of characters to be displayed
naflag is non-zero if the WITH NO ADVANCING option is
specified
You can replace the lprdisp.o module with another containing a lprdisp()
routine, provided it has a similar specification to that given above.
Controlling Terminal Printers.
Your Micro Focus COBOL system supports a number of calls which allow you
to control a printer attached to your terminal. Using these calls, you
can switch the printer on- or off-line,
print the current screen, and cause a string of characters to be printed.
Note that using these calls may affect the portability
of your application.
All of these calls cause the screen handling system to be initialized, if
it is not already.
Putting the Printer On-Line
To switch the attached printer on- or off-line, you need to add the
following record to the Working-Storage Section of your program:
01 state pic x comp-x
Then at run time you use the following call:
call "cobprt" using state
where:
state is a PIC X COMP-X data item which is set to 0 to
put the printer off-line or 1 to put the printer
on-line
When the printer is on-line all screen output goes to the printer (it may
also show on your screen, but this is terminal dependent). You must be
aware that the behavior of your terminal and printer, once you have set
the printer on-line, is entirely hardware dependent.
The screen handling library will send various control codes
to the terminal (for example, to position the cursor) which some
terminals may pass to the printer, though this is undefined, as is the
action the printer will take if these codes are passed to it.
Once the printer is placed off-line, the RTS redraws the screen to ensure
it is up to date, as the terminal may not have updated it during printer
output.
If the printer is placed on-line by this call and the RTS terminates, the
RTS will automatically place the printer off-line.
Results of animating programs which make this call are undefined.
Printing a Screen
To print the contents of the current screen on the printer, you use the
following call at run time:
call "cobprtscrn"
Although this call causes the screen handling system to be initialized,
this call is pointless if the screen handling system has not already been
initialized as it will simply cause a blank screen to be printed.
Printing a String of Characters
To print a string of characters on the printer, you need to add these
records to the Working-Storage Section of your program:
01 strng pic x(100).
01 strng-length pic x comp-x value 100.
Then at run time you use the following call:
call "cobprtstring" using strng
strng-length
where:
strng is a string which can contain only printable
characters: control characters are not allowed.
strng-length is the number of characters to be output
This causes the string to be output to the printer, and possibly to the
screen as well depending on the terminal.
After the completion of this call, the RTS redraws the screen.
Points to Note
While using the above three calls, you must be aware of the following:
* If the printer is switched off,
not available or otherwise off-line, the results are undefined.
Some terminals may wait forever for the printer to be available,
some give up.
* Some terminals hold back all screen output
while a print-screen is occurring, some allow screen output to
continue. For those which allow screen output to continue, it is
not defined if the new output appears on the printer while it is
working its way down the screen.
* If highlighting appears on the screen and the screen is printed,
the highlighting may be preserved by some terminal/printer
combinations, thrown away by some, or cause spurious results in
others. Again, the actual behavior is entirely hardware
dependent.
* In addition, RETURN-CODE will be set to zero if the required
capability for the call was found and no errors were encountered,
or non-zero if the capability was missing or some other error was
encountered.
* The COBCTRLCHAR environment variable
must not be set (see Appendix B , Compatibility Issues).
Terminfo Requirements
These calls require additional terminfo capabilities as shown below. The
last column shows the behavior if the named capability is not present:
Call Capabilities Action if Not Present
Required
cobprt 1 prtr_on The printer cannot be placed on-line
cobprt 0 prtr_off The printer cannot be placed off-line
cobprtscrn print_screen Attempts to print the screen will have
no effect
cobprtstring prtr_non Attempts to print a string will have
no effect
Terminal Handling
This section covers terminal handling considerations.
Control and Alt Key Support.
Some UNIX terminals are not capable of detecting the Alt, Ctrl and a
number of other keys when they are pressed alone.
For this reason, an alternative is provided:
Enter /a to simulate the depression or release of the Alt key. Enter /c
to simulate the depression or release of the Ctrl key
To use the forward slash character,
enter it twice: //. To get help on these and other keyboard mappings,
enter /m. See also Appendix N , UNIX Key Usage Chart for a list of
keystroke mappings.
Wide Terminal Mode.
This facility is for use with COBOL only, and enables you to use a wide
mode if supported on your terminal; for example vt100 style terminals
have a 132 column mode. All normal methods of screen output are allowed
including ANSI DISPLAY, ADIS DISPLAY and the cobprintf() calls. See
Chapter 20 ADIS for details of these. You must be aware that cursor
addressing
will apply to the current mode. If you ask ADIS to position the cursor
to column 100 while in 80 column mode, this will not be successful, nor
will it cause an automatic switch from normal to wide mode. Wide mode
must be set explicitly as shown below.
To use this facility you must include a record in the Working-Storage
Section as follows:
01 mode-number PIC X COMP-X.
then at run time you use the following call:
call "cobtermmode" using mode-number
where mode-number can have one of the following values:
0 standard terminal mode. The standard terminal terminfo file is
used.
1 wide terminal mode. The standard terminal name suffixed by -w is
the name of the terminfo file used
The value of RETURN-CODE is set to zero if the call completes
successfully, or to non-zero if the call fails, for example if the
required terminfo file cannot be found. The search path for the terminfo
file
follows the usual Micro Focus rules for file searches as shown below:
1. If COBTERMINFO
is not set, it is considered to be set to $COBDIR/terminfo (if
COBDIR is not set it is assumed to be /usr/lib/cobol).
2. If COBTERMINFO is set then it is read as a set of colon separated
paths to the terminfo database. If the required file is found on
any of these paths (parsed from left to right), then it is used.
3. If TERMINFO
is set, it is used as a path to the terminfo database. If the
file is found, it is used.
4. Use /usr/lib/terminfo as the path to the terminfo database. If
the file is found here, it is used.
5. If the file is not found,
an error is returned.
If the call is successful the screen handling system is initialized (if
it was not already) and:
* a RETURN-CODE of zero is returned
* ADIS restarts in the new mode. It will reread all configuration
files and any dynamic changes will be lost
* all character and attribute maps are cleared
* the screen is cleared and the cursor positioned in the home
position
As the screen handling system is now initialized all DISPLAYS will now
use it, including ANSI DISPLAYS.
If the call fails the RETURN-CODE is non-zero and the screen does not
change. The RETURN-CODE is set as follows:
0 operation successful
1 the terminfo file has not been found, is not readable, is corrupt
or there is insufficient memory
2 the terminfo file does not contain one or more of the required
capabilities
3 the environment does not support the requested code
If you use the cobtermmode call
you must be aware of the following:
* the number of columns in wide mode must not exceed 255.
* as this call causes ADIS to be reinitialized, ADIS
support must be present in those Run-Time Systems which support
this call. If you attempt to exclude ADIS from these Run-Time
Systems, you will receive a run-time error.
* when running under ANIMATOR, this call causes the terminal to be
initialized to the new mode, which may produce some flicker
of the display. Switching between the ANIMATOR and user screens
will cause mode changes
as the wide terminal mode is not supported for the ANIMATOR
screen.
* when the RTS exits the terminal is restored to normal mode. This
applies only to mode changes made under the control of this call.
* since the usual path searching rules are used, if the directory
pointed to by COBTERMINFO
contains an entry for the terminal in normal mode, but not wide
mode, but the system terminfo directory does contain an entry for
that terminal in wide mode, the normal mode will use the
COBTERMINFO version and wide mode will use the system version.
This may lead to unexpected results where the two files differ in
capabilities other than column size changes.
* The COBCTRLCHAR
environment variable must not be set (see Appendix B ,
Compatibility Issues.
* if you have already set TERM
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 will
result in a suffix of "-w-w" which will almost certainly fail,
unless the terminal has a double wide mode and a terminfo file for
this mode is available.
In order to cause the terminal to switch states, six new terminfo
capabilities will be used:
Full-name Abbreviated Name
init_1string
is1
init_2string
is2
init_3string
is3
reset_1string
rs1
reset_2string
rs2
reset_3string
rs3
These entries are fully documented in the AT&T UNIX System V Interface
Definition (SVID) and are used as follows:
* when the screen libraries start up normally, is1, is2 and is3 will
be output, in that order. When the terminal mode is changed, rs1,
rs2, rs3 will be output, then is1, is2, is3 of the new terminfo
will be output in that order.
* standard terminfos can contain the column switching sequences
in either the "rs" family or the "is" family, hence both need to
be used. Terminfos that do not provide it in either will need to
be modified, or a new terminfo file will need to be supplied.
It is your responsibility to ensure that the terminal mode and terminfo
specified by the terminal name in TERM match when you run an application.
Wyse Terminal Support.
Your Micro Focus COBOL system supports terminals such as Wyse terminals,
whose escape sequence
s
are prefixed with a character other than escape (0x1b). The cursor and
function keys are fully operable.
Terminfo Entries
The following tables detail terminfo entries and are divided into two
categories: the first table contains those entries which must be present
for the software to function. The remaining tables contain optional
entries; for example, those which will be used if they are present but
which are not mandatory.
Essential Entries.
The following entries must be present for the Micro Focus COBOL system to
operate correctly. Entries marked "(if appropriate)" should be set
appropriately for the type of terminal.
Entry Mnemonic
auto right margin (if am
appropriate)
clear to end of line el
clear screen clear
clear to end of screen ed
cursor address cup
cursor down cud1
cursor home home
cursor left cub1
cursor right cuf1
cursor up cuu1
eat newline glitch (if xen1
appropriate)
entries for arrow keys (cursor kcud1, kcub1, kcuf1, kcuu1
keys)
entries for function keys f1 kf1 to kf63
to f10 (if appropriate)
entries for home key, next khome, knp, kpp, kend, kcbt
page key, previous page key,
end key and backtab key (if
appropriate)
exit attribute mode sgr0
number of columns cols
number of lines lines
xon/xoff (if appropriate) xon
Optional Entries.
The following entries should be used if they are required for the
particular type of terminal. However, the Micro Focus COBOL system does
not insist that they are present.
Entry Mnemonic
bell bel
carriage return cr
enter ca mode smcup
exit ca mode rmcup
keypag local rmkx
keypad transmit smkx
Note that some terminals must have smcup
and rmcup
in order to work correctly.
Highlighting
For terminals which have additive attributes
the following are used:
Entry Mnemonic
enter blink mode blink
(if appropriate)
enter bold mode bold
(if appropriate)
enter dim mode dim
(if appropriate)
enter reverse mode rev
(if appropriate)
enter underline mode smul
(if appropriate)
For terminals which do not have additive attributes, the following is
needed:
Entry Mnemonic
set attributes sgr
Performance Considerations
The following optional entries may be included and can improve the
performance of screen displays
in some situations:
Entry Mnemonic
cursor
down
parameterized cud
parameterized cursor left cub
parameterized cursor right cuf
parameterized cursor up cuu
If the following entries are present, scroll region
s can be used to scroll areas of the screen which greatly speeds up such
operations:
Entry Mnemonic
change scroll region csr
insert line il1
delete line dl1
Wide Terminal Mode
If you wish to use wide terminal mode,
you must ensure that the sequence to set the number of columns appears in
one of the following entries:
Entry Mnemonic
initialize string 1 is1
initialize string 2 is2
initialize string 3 is3
reset string 1 rs1
reset string 2 rs2
reset string 3 rs3
Printer Support
The following entries are required for printer support:
Entry Mnemonic
turn on printer mc5
turn off printer mc4
print screen mc0
parameterized print string mc5p
Line Drawing
For terminals which have additive attributes the following are used:
Entry Mnemonic
enable alternate character set enacs
alternate character set acsc
characters
enter alternate character set smacs
exit alternate character set rmacs
For terminals which do not have additive attributes, the following is
needed:
Entry Mnemonic
set attributes sgr
If you do not specify the appropriate alternate character set
characters for your terminal, or your terminal does not provide a
complete set, normal ASCII characters will be substituted for the missing
line drawing characters.
Color
Only the Tektronics
method can be used, for example ANSI color terminal
s. The following entries are required:
Entry Mnemonic
number of colors colors
set foreground setf
set background setb
original colors oc
original pairs op
Only one of oc or op needs to be specified, but it must reset to the
default colors.
Check that these entries are included in your terminfo database by
running the "untic
" or "infocmp
" program if supported by your operating system. See your operating
system manuals for details of how to do this.
Should you require, you can add entries to your terminfo database by
running the "tic
" program. See your operating system manuals for details of how to do
this.
If you find that certain entries are not included in your terminfo
database and you cannot add entries to it, please contact the supplier of
your operating system.
A set of single line drawing characters
are supported, as shown below:
* divider
* up arrow
* down arrow
* right arrow
* left arrow
* top left of box
* top right of box
* bottom right of box
* bottom left of box
* cross lines
* vertical line
* horizontal line
* left tee
* right tee
* bottom tee
* top tee
Note that the actual graphic characters
are machine dependent. If your system does not support these graphics,
then the equivalent ASCII characters will be displayed. See the appendix
Generic Line Drawing for details.