HP 3000 Manuals HP 3000 Manuals
Operation
Call-by-number routines are accessed using a CALL statement of the form
:
CALL x"hh" USING parameter-list
where:
hh is a two-digit hexadecimal code that identifies the
library routine
parameter-list is a list of the data items in your programs that
are to be passed as parameters. The number and type
of parameters is, of course, dependent upon the
particular subprogram you are calling.
Descriptions of Routines
Descriptions
for all of the call-by-number routines appear in numerical order
according to their hex numbers. Each routine is shown in a CALL
statement that you could use to call it. The parameters it needs are
shown in the USING clause.
Put a Character to the Screen.
CALL x"82" USING character
where:
character is a PIC X COMP-X field containing the character to
be displayed at the current cursor position.
Call x"82" displays a character on the screen.
Read a Character from the Keyboard.
CALL x"83" USING character
where:
character is a PIC X field that contains the character that is
returned. Call x"83" accepts a character from the
keyboard.
Split a File-name.
CALL x"8C" USING filespec, directory, file-name, extension
where:
filespec is a PIC X field of variable length, but not less
than 101 bytes, containing the full file
specification
directory is a PIC X field of variable length, but not less
than 101 bytes, containing the directory path-name
file-name is a PIC X field of variable length, but not less
than 15 bytes, containing the name of the file
extension is a PIC X field of variable length, but not less
than 15 bytes, containing the file-name extension
Call x"8C" allows you to separate the standard file-names into their
component parts. The component parts of a file-name are the directory
(for example, /usr/demo), the name itself (for example, prog) and the
file extension (for example, cbl) which together form the file
specification (for example, /usr/demo/prog.cbl).
The split file-name routine takes the string found in filespec and stores
its component parts in directory, file-name and extension.
Join a File-name.
CALL x"8D" USING filespec, directory, file-name, extension
where:
filespec is a PIC X field of variable length, but not less
than 101 bytes, containing the full file
specification
directory is a PIC X field of variable length, but not less
than 101 bytes, containing the directory path-name
file-name is a PIC X field of variable length, but not less
than 15 bytes, containing the name of the file
extension is a PIC X field of variable length, but not less
than 15 bytes, containing the file-name extension
Call x"8D" allows you to join the parts to make a standard file-name.
The component parts of a file-name are the directory (for example,
/usr/demo), the name itself (for example, prog) and the file extension
(for example, cbl) which together form the file specification (for
example, /usr/demo/prog.cbl).
The join file-name routine takes the strings found in directory,
file-name and extension and combines them to form a complete file
specification which it stores in filespec.
The Micro Focus COBOL system uses the split and join file-name routines
to:
* produce default listing and intermediate code file-names from the
source file-name
* produce overlay names
* produce file-names for segments and the intersegment reference
files
The values allowed in filespec, directory, file-name, and extension must
conform to the standards described in the documentation supplied with
your UNIX operating system, and each data item must end with a space
character. You must ensure that the area allocated within the
Working-Storage section for each data item is not less than the minimum
length given above.
Interprogram Function Calls.
CALL x"91" USING result, function-num, file
where:
result is a PIC 9(2) COMP-X field that contains zero if the
call is successful, or non-zero if not successful.
The number returned for non-successful calls varies
according to function-num.
function-num is a PIC X COMP-X field that contains one of the
values listed below, depending on which function you
want.
file depends upon the function
Call x"91" imposes heavy size penalties as it needs a large number of
support routines.
function-num can contain:
18 to delete the file
46 to enable insertion of null characters
47 to disable insertion of null characters
48 to enable tab insertion
49 to disable tab insertion
52 to use two-byte record terminators for line sequential and
relative files
53 to use one-byte record terminators for line sequential and
relative files
Function 18
file is a PIC X field of variable length that identifies the file on
which this subprogram is to work.
The format for function 18 is:
01 file.
03 file-name-length pic 9(2) comp-x.
03 file-name pic x(nn).
Function 46
Enables insertion of a null character x"00" before data characters whose
value is less than x"1B" in line sequential files. If you wish to
include non-ASCII data in a file then you must enable null insertion.
This function allows you to enable
null insertion for individual files regardless of the setting of the
run-time switch N. file is the file-identifier specified in the File
Description (FD), and must refer to a line sequential file which is
currently open. For example:
fd payroll-file
...
call x"91" using result, func-num, payroll-file
Function 47
Disables insertion of a null character x"00" before data characters whose
value is less than x"1B" in line sequential files. This function allows
you to disable null insertion for individual files regardless of the
setting of the run-time switch N. file is the file-identifier specified
in the File Description (FD) and must refer to a line sequential file
which is currently open (see Function 46 above for an example). This
function cannot be used if the file is declared as EXTERNAL.
Function 48
Enables insertion of tab characters in line sequential files. On input
all tab characters are expanded to the correct number of spaces, while on
output to disk, multiple spaces before a tab stop position are contracted
to a tab character. This function allows you to enable tab insertion for
individual files regardless of the setting of the run-time
switch T. file is the file-identifier specified in the File Description
(FD) and must refer to a line sequential file which is currently open.
See Function 46 above for an example.
Function 49
Disables insertion of tab characters in line sequential files. On input
all tab characters are expanded to the correct number of spaces; on
output to disk, spaces are output as spaces. This function allows you to
disable tab insertion for individual files regardless of the setting of
the run-time switch T. parameter is the file-identifier specified in the
File Description (FD) and must refer to a line sequential file which is
currently open. See Function 46 above for an example.
Function 52
Causes a two-byte record terminator to be used for particular files when
your program writes records to a line sequential or relative file. The
record terminator has the value x"0D0A" (carriage return - line feed).
file is the file-name used in the SELECT statement.
Function 53
Restores the default of one-byte record terminators used when your
program writes records to a line sequential or relative file. The
one-byte record terminator has the value x"0A" (line feed). file is the
file-name used in the SELECT statement.
Control the Screen.
CALL x"A7" USING function-num, parameter
where:
function-num is a PIC X COMP-X field which contains a value
indicating the function required:
6 reads the current User attribute contained in
parameter
7 sets the current User attribute, which is held
in parameter
16 turns the User attribute on. parameter
contains zero.
You should note that although it is not possible to
turn off the attribute byte, you can instead set the
attribute type to normal by calling the x"A7"
routine function 7 to set the user attribute to
normal and then calling x"A7" function 16 with a
value of 0 in parameter. This results in the same
effect as turning off the attribute byte.
You can also use Call x"A7" subfunction 3 to change
the user attribute dynamically. You should use the
same caution when using this library routine as when
using any other, using only regular COBOL syntax
wherever possible.
parameter is a PIC X COMP-X field containing:
for functions 6 and 7: the User attribute
for function 16: 0 to turn the User attribute on
The
User attribute is initially off for each program. Once it is enabled,
some of the various methods which you can use to display text upon the
screen; for example, DISPLAY ... UPON CRT, screen I/O subprograms and
the ADIS module all use this attribute. The ANSI form of the DISPLAY
statement (DISPLAY ... UPON CONSOLE) uses the User attribute only if on
e of the other DISPLAY methods has been used previously. DISPLAY SPACE
UPON CRT clears the screen to the user attribute for each screen
position.
The User attribute affects the results of ADIS DISPLAY operations only
once ADIS has been requested to set up the attribute. Such a request can
be made by asking ADIS to perform and ACCEPT or DISPLAY using an
attribute. For example:
display spaces upon crt with highlight
The
User attribute, if turned on, is used when displaying text upon the
screen and supersedes any Screen attribute set for the character
positions being used in the display.
Modify ACCEPT/DISPLAY Behavior.
CALL x"AF" USING function, parameter
where:
function is the name of a PIC 9(2) COMP-X field whose value
indicates which of the subprograms controlled by
this call code is to be called.
parameter is the name of a data item whose size and type
depends on the value of function.
function may take any of the following values:
1 enable or disable user function keys at run
time
3 control data keys
18 display a character to the screen at the
current cursor position
22 sound the terminal alarm
27 get a character from the keyboard
Function 1
Allows individual user function keys, or a series of consecutive user
function keys, to be enabled or disabled at run-time. You must have
already set up the actual key codes for the user functions with the
keybcf utility. See Chapter 24 , Keyboard Configuration Utility for
details.
parameter is a group item defining user key control consisting of four
data items:
user-key-setting PIC 9(2) COMP-X field that contains 0 to disable
user function keys, or 1 to enable them.
filler a PIC X field whose value must be "1".
first-user-key a PIC 9(2) COMP-X field that contains the number of
the first function key to be enabled or disabled.
This number is as defined with the keybcf utility.
See Chapter 24 , Keyboard Configuration Utility
for details.
number-of-keys a PIC 9(2) COMP-X field that specifies the number of
consecutive function keys that are to be enabled or
disabled. These numbers are as defined with the
keybcf utility.
Function keys are enabled or disabled until explicitly changed by another
call to x"AF" or until the application terminates. Calls to enable or
disable functions keys are additive. For example, if you call x"AF" to
enable function key F1 and then make a second call to enable F10, both
keys are enabled.
Example
If you want to enable the Escape key and function keys F1 and F10, but
you want to ensure that all other user function keys are disabled, then
the following code will do this:
* Enable 11 keys starting from key 0 (escape key)
move 1 to User-Key-Setting
move 0 to First-User-Key
move 11 to Number-Of-Keys
call x"AF" using Set-Bit-Pairs User-Key-Control
* Disable 117 keys starting from key 11
move 0 to User-Key-Setting
move 11 to First-User-Key
move 117 to Number-Of-Keys
call x"AF" using Set-Bit-Pairs User-Key-Control.
* Enable F1 and F10.
move 1 to User-Key-Setting
* Enable F1.
move 1 to First-User-Key
move 1 to Number-Of-Keys
call x"AF" using Set-Bit-Pairs User-Key-Control
* Enable F10
move 10 to First-User-Key
call x"AF" using Set-Bit-Pairs User-Key-Control
Function 3
Disable data keys or make them act like function keys; that is, they
terminate the ACCEPT.
parameter is a group item defining data-key-control containing four data
items:
data-key-setting a PIC 9(2) COMP-X field which defines the action of
the keys affected, as follows:
0 The key is disabled. If it is pressed during
an ACCEPT, the terminal alarm sounds and the
key rejected.
1 The key will act as a function key (see
below). It will terminate the ACCEPT.
2 (The default). The character will simply be
entered into the field.
filler a PIC X field whose value must be "3".
first-data-key a PIC X defining the first character to be affected.
number-of-data-keys a PIC 9(2) COMP-X field
containing the number of characters to be affected.
Function 18
Displays a character to the screen at the current cursor position.
parameter is the name of a PIC X item containing the character to be
displayed.
Function 22
Sounds the terminal alarm. parameter is the name of a PIC X item that
can contain any value.
Function 27
Gets a character from the keyboard. parameter is the name of a
three-byte group item declared in the form of a CRT status data item (see
the Language Reference). A keystroke is read from the keyboard and
parameter is updated as follows:
Byte 1 Meaning
1 The second byte contains the number of a user-defined function
key, in binary (in the range 0 to 127). See Chapter 21 ,
ADIS Configuration Utility for more details on function keys.
2 The second byte contains the number of an ADIS function key, in
binary (in the range 0 to 39). See Chapter 21 , ADIS
Configuration Utility for more details on function keys.
3 The second byte contains the ASCII code of the keyed character.
9 The second byte contains one of the following error codes:
8 A disabled character has been keyed, and byte 3 contains
the character.
9 An invalid keystroke (more than one byte) has occurred.
This routine also causes the COBOL screen handling system to be invoked.
See Chapter 19 , Introduction to Screen Handling for details.
Call x"AF" gives access to a number of subprograms that affect the
behavior of ACCEPT and DISPLAY statements in a program. ACCEPT and
DISPLAY statements are handled by a part of the RTS called ADIS (see
Chapter 20 , ADIS for details).
Disable Interrupt Key.
CALL x"B0" USING function-code, parameter
where:
function-code is a PIC X COMP-X VALUE 4 data item
parameter is a PIC X COMP-X VALUE 1 data item
Call x"B0" disables the interrupt key for the rest of the application.
Therefore, it should be called before any subprograms are called.
Control Screen I/O.
Two call-by-number routines are available for controlling screen I/O:
x"B7" and x"B8".
CALL x"B7" USING function, parameter, buffer
where:
function is the name of a PIC 9(2) COMP-X data item whose
value indicates which of the subprograms controlled
by this call code is to be called.
parameter is a group item consisting of three data items:
- a PIC 9(4) COMP-X field showing the length of
the data to be read or written
- a PIC 9(4) COMP-X field giving the start
position on the screen. Top left is position 1,
81 is the start of the next line, assuming an 80
column display, etc.
- a PIC 9(4) COMP-X field showing the start
position in the buffer, starting from position
1.
buffer is the COBOL data area. It is a PIC X (n) field and
may be as large or as small as you require in order
to write your data.
function can take any of the following values:
0 Read a string of characters from the screen
1 Write a string of characters to the screen
2 Read a string of attributes from the screen
3 Write a string of attributes to the screen
4 Clear a specified string of consecutive character positions to
spaces
5 Clear a specified string of consecutive character positions to
normal attributes
6 Write a specified character to a string of consecutive character
positions
7 Write a specified attribute to a string of consecutive character
positions
Note that the structure of the attribute byte is given in Chapter 19
Introduction to Screen Handling.
Call x"B7" gives access to a number of subprograms that control screen
output. These subprograms cause the COBOL screen handling system to be
invoked. See Chapter 19 , Introduction to Screen Handling for
details.
While call x"B7" provides you with the means for direct screen handling
from COBOL, the Micro Focus COBOL system also supports additional
screen-handling calls which are designed to be used from C. See Appendix
A , Advanced Programming Features for full details on these additional
calls.
CALL x"B8" USING function, parameter, text-buffer, attribute-buffer
where:
function is the name of a PIC 9(2) COMP-X data item whose
value indicates which of the subprograms controlled
by this call code is to be called.
parameter is a group item consisting of three data items:
- a PIC 9(4) COMP-X field showing the length of
the data to be read or written
- a PIC 9(4) COMP-X field giving the start
position on the screen
- a PIC 9(4) COMP-X field showing the start
position in the buffer, starting from position
1.
text-buffer is a COBOL data area. It is a PIC X(n) field and
may be as large or as small as you require in order
to read or write your text.
attribute-buffer is a COBOL data area. It is a PIC X(n) field and
may be as large or as small as you require in order
to read or write your text. Note that the structure
of the attribute byte is given in Chapter 19 ,
Introduction to Screen Handling.
function may take any of the following values:
0 Read strings of text and attributes from the screen
1 Write strings of text and attributes to the screen
2 Swap the text and attributes on the screen with those in the text
and attribute buffers respectively
Call x"B8" gives access to a number of other subprograms that affect
screen input and output.
While call x"B8" provides you with the means for direct screen handling
from COBOL, the Micro Focus COBOL system also supports additional
screen-handling calls which are designed to be used from C. See Appendix
A Advanced Programming Features for full details on these additional
calls.
Test Keyboard Status.
CALL x"D9" USING parameter
where parameter is the name of a PIC 9(2) COMP-X item. The routine
returns a zero value in parameter if there is no character waiting to be
read, or a non-zero value if there is a character waiting to be read.
Call x"D9" determines whether or not there is a character waiting to be
read from the keyboard.
Some UNIX implementations do not allow you to poll the keyboard in this
way. See the documentation supplied with your UNIX system, which will
tell you if this is the case in your implementation.
Sound the Beep.
CALL x"E5"
This
routine causes a beep.
Move the Cursor to a Defined Position.
CALL x"E6" USING result, parameter
where:
result is not used
parameter is an 01 level item containing:
03 row-number pic 9(2) comp-x.
03 column-number pic 9(2) comp-x.
The value of row-number should be in the range 0 to x, where x is the
number of lines on the screen minus 1. The value of column- number
should be in the range 0 to y, where y is the number of columns on the
screen minus 1. The number of rows and columns on the screen are defined
in the terminfo database in the variables lines and cols respectively.
For details on terminfo, see Chapter 22 , Device Handling and
Terminfo.
Call x"E6" positions the cursor at the specified screen position.
Pack Byte.
CALL x"F4" USING byte, array
where:
byte is a PIC X COMP-X field that contains the new byte.
array is a PIC X COMP-X OCCURS 8 field that contains the
eight bytes to be packed.
The routine takes the eight fields from array and uses the least
significant bit of each byte to form byte. The first occurrence in array
becomes the most significant bit of byte (bit 7).
Unpack Byte.
CALL x"F5" USING byte, array
where:
byte is a PIC X COMP-X field that contains the byte to be
unpacked.
array is a PIC X COMP-X OCCURS 8 field that contains the
unpacked bits.
The routine takes the eight bits of byte and moves them to the
corresponding occurrence within array.