HP 3000 Manuals HP 3000 Manuals
Overview
The call-by-name library routines supplied with the run-time systems in
this product supply features that cannot be accessed using COBOL syntax,
such as operating system functions.
Where COBOL run-time system routines prefixed "CBL_" exist, you are
encouraged to use these in preference to calling the operating system
directly. By doing so, your programs are portable between all operating
systems supported by a version of this COBOL system.
On 32-bit systems, parameters to the call-by-name routines can be defined
anywhere. On 16-bit systems they must not cross a segment boundary.
Portability of Call-by-name Routines
The prefix assigned to a call-by-name routine indicates its level of
availability as follows:
CBL_ available on all environments supported by a version of
this COBOL system.
PC_ available only on DOS, Windows and OS/2 environments and
usually specific to those environments.
Note that while CBL_ routines are intended to be fully portable across
all run-time systems, there are a number which are currently available
only in one or two run-time systems. The following sections include
information about which routines are affected. Your Release Notes will
list any routines which become available under additional run-time
systems in later releases of this product.
To guarantee the portability of programs using CBL_ routines you must
ensure that the name of a routine is coded in upper case in your program.
The portability specifications are applicable only in environments where
the Micro Focus COBOL System is available in all the given environments.
The section Routines by Category will help you find routines for
particular purposes; it lists their names, organized into categories,
with a very brief description of the purpose of each. The section
Descriptions of Routines contains complete descriptions of the routines,
listed in alphabetical order.
Routines by Category
* Application Subsystems
* Byte-Stream Files
* Exit and Error Procedures
* File-names
* Files
* Keyboard
* Logic Operators
* Memory Allocation
* Mouse
* Multiple Run-units
* National Language Support
* Operating System Information
* Printer
* Screen
* Text
* Virtual Heaps
* Windows
The routines in each category are listed below. Details common to all
the routines in a category are also shown.
Application Subsystem.
CBL_SUBSYSTEM Declare/deallocate subsystems
Introduction to the Subsystem Routine.
The subsystem routine enables you to logically group a number of programs
in your application into a subsystem. You can then cancel these programs
in a single operation without having to cancel each individual program.
Byte-Stream Files.
CBL_CLOSE_FILE Close byte-stream file
CBL_CREATE_FILE Create byte-stream file
CBL_OPEN_FILE Open byte-stream file
CBL_READ_FILE Read byte-stream file
CBL_WRITE_FILE Write byte-stream file
Introduction to Byte-stream Routines.
The byte-stream file routines enable you to read and write data files
without the need to adhere to COBOL record definitions.
For all these routines, if the routine is successful the RETURN-CODE
register is set to zero. If the routine fails, the RETURN-CODE register
contains a file status value indicating the failure. This file status is
always the standard ANSI'74 file status value. If no ANSI'74 file status
is defined for the error, an extended error status is returned (9/nnn
where nnn is the RTS error number).
Exit and Error Procedures.
CBL_ERROR_PROC Register error procedures
CBL_EXIT_PROC Register closedown procedure
CBL_ERROR_PROC is not available in DOS, Windows and OS/2 environments.
Introduction to the Exit and Error Procedure Routines.
When your application ends or an error occurs, the run-time system closes
it down, closing files and releasing resources cleanly. However, you may
want to do additional work before closedown is complete.
The exit and error procedure routines enable you to register your own
procedures so that they are executed when an error occurs or as part of
the normal termination of your application.
File-names.
CBL_SPLIT_FILENAME Divide file-name into parts
CBL_JOIN_FILENAME Join parts of file-name
Introduction to File-name Routines.
The file-name routines enable you to parse a file-name into its component
strings and to join strings together to form a file-name. They can be
used together to replace components of a file-name, such as the
extension. They can handle both null-terminated and space-terminated
file-names.
A file-name is split up into path, basename and extension. For example,
in the following DOS file-name:
d:\dir1\dir2\file.dat
the path is d:\dir1\dir2, the basename is file, and the extension is dat;
and in the following UNIX file-name:
/dir1/dir2/file.dat
the path is /dir1/dir2, the basename is file, and the extension is dat.
The routines can work with strings up to 65,535 characters long, but your
environment or run-time system imposes a limit on the maximum length of a
file-name:
DOS 65 characters
Windows 65 characters
OS/2 265 characters
UNIX 14 or 100 characters depending on the version of UNIX
Files.
CBL_CHANGE_DIR Change current directory
CBL_CHECK_FILE_EXIST Check if file exists
CBL_COPY_FILE Copy file
CBL_CREATE_DIR Create directory
CBL_DELETE_DIR Delete directory
CBL_DELETE_FILE Delete file
CBL_LOCATE_FILE Locate file/Expand path
CBL_READ_DIR Read current directory
CBL_RENAME_FILE Rename file
PC_FIND_DRIVES Find valid drives
PC_READ_DRIVE Read current drive
PC_SET_DRIVE Set current drive
The PC_ routines are not available in UNIX environments.
Keyboard.
CBL_GET_KBD_STATUS Test for character at keyboard
CBL_READ_KBD_CHAR Read character from keyboard (no echo)
Logic Operators.
CBL_AND Logical AND
CBL_EQ Logical EQuivalence
CBL_IMP Logical IMPlies
CBL_NOT Logical NOT
CBL_OR Logical OR
CBL_XOR Logical eXclusive OR
Introduction to Logic Routines.
The logic routines carry out logic operations on bits. Apart from
CBL_NOT, all these operations have two operands.
When native code is generated these routines are optimized into in-line
code if the length is specified as a literal and is no more than eight.
In the two-operand routines, interchanging the two operands, source and
target, does not change the result except in CBL_IMP. However, the result
is always stored in the second operand, target.
If length is longer than either data item, bytes following that data item
are used, up to the length specified.
The parameter length can be replaced by the syntax:
length of source
or
length of target
assuming all the bytes of the data item are to be used.
Logical AND and OR operations can also be cariied out using the VALUE
clause.
Memory Allocation.
CBL_ALLOC_MEM Dynamic memory allocation
CBL_FREE_MEM Free dynamically allocated memory
Mouse.
CBL_GET_MOUSE_MASK Get mouse event mask
CBL_GET_MOUSE_POSITION Get mouse screen coordinates
CBL_GET_MOUSE_STATUS Get number of events in queue
CBL_HIDE_MOUSE Hide mouse pointer
CBL_INIT_MOUSE Initialize mouse support
CBL_READ_MOUSE_EVENT Read mouse event queue
CBL_SET_MOUSE_MASK Set mouse event mask
CBL_SET_MOUSE_POSITION Set mouse screen coordinates
CBL_SHOW_MOUSE Draw mouse pointer
CBL_TERM_MOUSE Terminate mouse support
PC_GET_MOUSE_SHAPE Get mouse pointer shape
PC_SET_MOUSE_HIDE_AREA Set mouse hide area
PC_SET_MOUSE_SHAPE Set mouse pointer shape
These routines are not available on UNIX.
Introduction to Mouse Routines.
The mouse is useful for applications that require users to select from a
list of options or move objects around on the screen.
To use these routines, you must add the necessary 'DEVICE=...'
statements in your CONFIG.SYS file.
You must hide the mouse during the execution of any ANSI ACCEPT or
DISPLAY statement that operates on the area of the screen where the mouse
pointer is located.
The attributes referred to in the descriptions of routines are screen
attributes, not user attributes. The top left-hand corner of the screen
is row 0, column 0.
Mouse Events.
Whenever the mouse is moved or a button on the mouse is pressed or
released, the mouse hardware causes an interrupt. The mouse device
driver takes control and, depending on a mask you have set, either saves
it in a queue or ignores it. This prevents events being lost if a
subsequent interrupt occurs before the application has read the event.
With the mouse routines, you can read the event queue and determine how
many events are in the queue.
When an event is generated, a description of it is stored in a data
structure called the event-data. If the mask allows (see below), this is
added to the queue. The layout of event-data is:
event-type PIC X(2) COMP-X.
event-time PIC X(4) COMP-X.
event-row PIC X(2) COMP-X.
event-col PIC X(2) COMP-X.
where:
event-type is the action (that is, change of state) that took
place:
bits 7 - 4 - reserved
bit 3 set = button 3 pressed
bit 2 set = button 2 pressed
bit 1 set = button 1 pressed
bit 0 set = mouse moved
A button release is indicated by the bit for that
button changing from 1 to 0. For example, if the
mouse moves and button 1 is pressed at the same time,
event-type contains 3.
event-time is the time elapsed between when the event took place
and some arbitrary but fixed starting time.
event-row
event-col\ together, give the position of the mouse
when the event took place.
The Event Mask.
The event mask, which the programmer supplies, tells the system which
kinds of event should be queued and which ignored. It has the same
structure as event-type. An event is queued only if it happens while the
corresponding mask bit is on, or while another state is on whose mask bit
is on. When an event-data is queued, the bit for each state is set
correctly; that is, the mask does not mask them out.
For example, the operator moving the mouse generates an event if either
the mask bit for "mouse moved" is off or the operator is holding down a
button and the mask bit for that button is off.
Multiple Run-units.
CBL_CULL_RUN_UNITS Clear dead run-units
CBL_EXEC_RUN_UNIT Create run-unit
CBL_GET_SHMEM_PTR Read named value
CBL_PUT_SHMEM_PTR Create/update named value
CBL_YIELD_RUN_UNIT Yield the current run-unit
Introduction to Multiple Run-unit Routines.
The multiple run-unit routines enable you to make use of the Concurrency
support provided with this system.
On DOS, Windows and OS/2, to use the multiple run-unit routines, you must
place the module cobenv.dle (DOS), cobenv.dll (OS/2) or cobenv.dlw
(Windows) in the install section of your trigger's configuration file.
The routines work only with .int and .gnt files. They do not work with
linked executable files.
On DOS, Windows and OS/2 these routines and .int and .gnt files are
available only with the add-on product, Toolset, available from Micro
Focus.
National Language Support.
CBL_NLS_COMPARE Compare two strings
CBL_NLS_INFO Get/set national information
CBL_NLS_OPEN_MSG_FILE Open NLS message file
CBL_NLS_READ_MSG Read message from message file
CBL_NLS_CLOSE_MSG_FILE Close NLS message file
These routines can be called only from a program which has been compiled
with the NLS directive.
These routines are not available on 32-bit environments.
Operating System Information.
CBL_GET_OS_INFO Get operating system information
Printer.
PC_TEST_PRINTER Test printer status
This routine is only available on DOS environments.
Screen.
CBL_CLEAR_SCR Clear screen
CBL_GET_CSR_POS Get cursor position
CBL_GET_SCR_SIZE Get screen size
CBL_READ_SCR_ATTRS Read attribute string
CBL_READ_SCR_CHARS Read character string
CBL_READ_SCR_CHATTRS Read character & attribute strings
CBL_SET_CSR_POS Set cursor position
CBL_SWAP_SCR_CHATTRS Swap character & attribute
CBL_WRITE_SCR_ATTRS Write attribute string
CBL_WRITE_SCR_CHARS Write character string
CBL_WRITE_SCR_CHARS_ATTR Write character string with attribute
CBL_WRITE_SCR_CHATTRS Write character & attribute strings
CBL_WRITE_SCR_TTY Write characters TTY-style
CBL_WRITE_SCR_N_ATTR Repeat write attribute
CBL_WRITE_SCR_N_CHAR Repeat write character
CBL_WRITE_SCR_N_CHATTR Repeat write character & attributes
Notes on Screen Routines.
A number of the screen routines specify the screen-position parameter.
In this COBOL system, the top left corner of the screen is row 0, column
0. For example, if you want to change attributes beginning in row 5,
column 8, you specify row-number as 4 and column-number as 7.
If you are using an add-on product, these routines enable you to use
generic attributes. You must, however, use the CBL_SCR_ routines to
correctly set up the attribute palette before using these routines. See
the appendix Additional Library Routines in your Toolset Reference or
Toolbox Operating Guide for information on the CBL_SCR_ routines.
Text.
CBL_TOLOWER Convert a string to lower case
CBL_TOUPPER Convert a string to upper case
Virtual Heaps.
CBL_OPEN_VFILE Open heap
CBL_READ_VFILE Read heap
CBL_WRITE_VFILE Write heap
CBL_CLOSE_VFILE Close heap
Introduction to Heap Routines.
A heap is a byte-stream file which is buffered in available memory.
The status word specified when the heap is created is associated with
each heap It is written to when an operation on the heap fails. Each
heap is thereby attached to a particular program, namely the program
which contains the heap's status word, and is automatically deallocated
(unless it has already been explicitly deallocated by a call to
CBL_CLOSE_VFILE) when that program is canceled.
A heap is identified by a heap identifier words. This can be passed
around between programs so that the heap can be read or written by any
program. However, in order to check for failure, the program needs to
have access (using a pointer variable, for example, or via normal linkage
section mapping) to the associated status word.
Alternatively the RETURN-CODE register can be examined to catch a general
heap function failure, or the ON OVERFLOW/EXCEPTION syntax can also be
used on the CALL statement to trap any error. In these two cases, the
specific error can then be determined by examining the heap status word.
If the read/write succeeds, the RETURN-CODE is zero. If it fails, the
RETURN-CODE is non zero and the heap status first byte contains "9", with
detail in the second byte.
On 16-bit environments the heap status word used by CBL_READ_VFILE and
CBL_WRITE_VFILE, must reside within the first 64K of a COBOL program:
note that it can be in the Linkage Section of the current program, as
long as it is within the first 64K of another COBOL program.
On 16-bit environments the buffer used with CBL_READ_VFILE and
CBL_WRITE_VFILE can reside anywhere within the Data or Linkage Section,
or it can be dynamically allocated using the CBL_ALLOC_MEM routine. The
buffer must not cross a 64K boundary. Use the FLAG-CHIP directive to
highlight data items that cross a 64K boundary.
Each heap is paged, if necessary. On DOS, Windows and OS/2, a heap is
paged into a separate file on disk with name progname.vnn, where progname
is the root name of the program to which the heap is attached and nn is
an integer from 1 to 99. Once nnreaches 99, the v is overwritten. The
maximum number allowed for the extension is 384.
On DOS, Windows and OS/2 each program is limited to 384 local heaps. On
UNIX each run-unit is limited to 128 local heaps.
NOTE You can use reference modification in the buffer call parameter to
declare the heap buffer in the middle of a COBOL record. This is
compiled efficiently provided the length is given as fixed; since
the length is ignored by the call interface, you can give it as
one.
Windows.
PC_WIN_ABOUT Add a Windows "About" box
PC_WIN_HANDLE Obtain handle of window used for screen I/O
PC_WIN_INIT Get Windows startup values
PC_WIN_YIELD Process outstanding Windows messages
These routines are available only on the Windows environment.