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 devicestdin accesses the
standard UNIX input. A program that writes to the standard output
devicestdout accesses the standard UNIX output. A program that writes to
the standard error devicestderr accesses 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 RTS 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 redirectedto or from stdin, stdout or stderr using file-name
mapping. See the chapter Callable File Handler (Extfh) for more
information on these redirections. If stdin is line sequential, the
first READ can be from the command line tail, depending on the COBCONFIG
environment variable. See the chapter Run-time Configuration for details
of COBCONFIG.
Your system emulates printer channelsC01 through C12 by line feeds and
form feeds. If you want to write to these channels you should set the
COBLPFORM environment variableto 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 the appendix Micro Focus
Environment Variables for details of COBLPFORM.
Any WRITE BEFORE/AFTER PAGEstatements cause positioning to be 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 TABstatements 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 PRINTERstatement, 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 the
appendix Micro Focus 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 nonzero if the WITH NO ADVANCING clause 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 enable 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.
Using these calls may affect the portabilityof 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 sends various control codesto 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 takes
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 might not have updated it during
printer output.
If the printer is placed on-line by this call and the RTS terminates, the
RTS automatically places 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.
When 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 outputwhile 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 unexpected results in
others. Again, the actual behavior is entirely hardware
dependent.
* RETURN-CODE is set to zero if the required capability for the call
was found and no errors were encountered. It is set to nonzero if
the capability was missing or some other error was encountered.
* The COBCTRLCHAR environment variablemust not be set. See the
chapter Portability Issues in your COBOL User Guide for more
information.
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 prtr_on The printer cannot be placed
on-line.
cobprt 0 prtr_off The printer cannot be placed
off-line.
cobprtscrn print_screen Attempting to print the screen
has no effect.
cobprtstring prtr_non Attempting to print a string has
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 the appendix UNIX Key
Usage Chart for a list of keystroke mappings.
If your UNIX system supports the use of Alt and Ctrl keys (for example,
SCO Open Desktop V2.0) you should use the detect_alt_ctrl run-time
configurable. See your Release Notes for information on detect_alt_ctrl.
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 the
chapter Adis for details of these. You must be aware that cursor
addressingapplies to the current mode. For example, if you ask Adis to
position the cursor at column 100 while in 80 column mode, this will not
be successful, neither 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 of your program 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:
Value Meaning
-------------------------------------------------
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. It is set to nonzero if the call fails, for example if the
required terminfo file cannot be found. The search path for the terminfo
filefollows the usual Micro Focus rules for file searches as shown below:
1. If the COBTERMINFOenvironment varaible is not set, it is
considered to be set to $COBDIR/terminfo. If the COBDIR
environment variable is not set it is assumed to be
/usr/lib/cobol.
2. If COBTERMINFO is set, 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 the TERMINFOenvironment variable 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 rereads all configuration files
and any dynamic changes are 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 DISPLAY statements
now use it, including ANSI DISPLAY statements.
If the call fails, the RETURN-CODE is nonzero and the screen does not
change. The RETURN-CODE is set as follows:
Value Meaning
-------------------------------------------------
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.
When using 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, Adissupport must be
present in those run-time systems which support this call. If you
attempt to exclude Adis from these run-time systems, you 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 flickerof the
display. Switching between Animator and user screens causes mode
changesas the wide terminal mode is not supported for Animator's
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 COBTERMINFOcontains 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 uses the COBTERMINFO version and wide mode uses the system
version. This can cause unexpected results where the two files
differ in capabilities other than column size changes.
* The COBCTRLCHARenvironment variable must not be set. See the
chapter Portability Issues in your COBOL User Guide for more
information.
* If you have already set the TERMenvironment 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 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 are 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 are
output in that order. When the terminal mode is changed, rs1,
rs2, rs3 are output, then is1, is2, is3 of the new terminfo are
output in that order.
* standard terminfos can contain the column switching sequencesin
either the rsx family or the isx family, hence both need to be
used. Terminfos that do not provide it in either need to be
modified, or a new terminfo file needs 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 sequencesare 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 which are 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 with an asterisk (*) should be set
appropriately for the type of terminal.
Entry Mnemonic
-----------------------------------------------------
Auto right margin. am
*
Clear to end of el
line.
Clear screen. clear
Clear to end of ed
screen.
Cursor address. cup
Cursor down. cud1
Cursor home. home
Cursor left. cub1
Cursor right. cuf1
Cursor up. cuu1
Eat newline glitch. xen1
*
Entries for arrow kcud1, kcub1, kcuf1, kcuu1
keys (cursor keys).
Entries for function kf1 to kf63
keys f1 to f10. *
Entries for home, khome, knp, kpp, kend, kcbt
next page, previous
page, end and
backtab keys. *
Exit attribute mode. sgr0
Number of columns. cols
Number of lines. lines
Xon/xoff. * 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
-----------------------------------------------------
bel
Carriage return. cr
Enter ca mode. smcup
Exit ca mode. rmcup
Keypad local. rmkx
Keypad transmit. Smkx
Some terminals must have smcupand rmcupin order to work correctly.
Highlighting.
For terminals which have additive attributesthe following are used.
Entries marked with an asterisk (*) should be set appropriately for the
type of terminal:
Entry Mnemonic
-----------------------------------------------------
Enter blink mode. * blink
Enter bold mode. * bold
Enter dim mode. * dim
Enter reverse mode. rev
*
Enter underline smul
mode. *
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 displaysin some situations:
Entry Mnemonic
-----------------------------------------------------------
Parameterizedcursordown. cud
Parameterized cursor left. cub
Parameterized cursor cuf
right.
Parameterized cursor up. cuu
If the following entries are present, scroll regions can be used to
scroll areas of the screen which greatly speeds up such operations:
Entry Mnemonic
-----------------------------------------------------
Change scroll csr
region.
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 Mc5p
string.
Line Drawing.
For terminals which have additive attributes the following are used:
Entry Mnemonic
-----------------------------------------------------
Enable alternate enacs
character set.
Alternate character acsc
set characters.
Enter alternate smacs
character set.
Alternate character rmacs
set.
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 setcharacters
for your terminal, or your terminal does not provide a complete set,
normal ASCII characters are substituted for the missing line drawing
characters.
Color.
Only the Tektronicsmethod can be used, for example, ANSI color terminals.
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 ticprogram. 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, you should contact the
supplier of your operating system.
NOTE If you use an attribute that is defined in your terminfo, but which
your terminal does not recognize, the attribute is not displayed
and no error message is given.