HP 3000 Manuals HP 3000 Manuals
Overview
The call-by-name
library routines supplied with the run-time system in this product supply
features that cannot be accessed using COBOL syntax, such as operating
system functions.
Many of the features can be accessed directly by calling functions
supplied as part of the operating system. However, such calls have the
disadvantage of tying the program to a particular operating system.
In earlier versions of this COBOL system all run-time library routines
were accessed by calling a single hexadecimal number. These routines,
known as call-by-number routines, are being replaced by routines accessed
by calling a name: call-by-name routines. In some cases the
call-by-name routine has additional features. Descriptions of the
available call-by-name routines are contained in Chapter 9 , Library
Routines (Call-by-Number).
You are encouraged to use call-by-name routines rather than
call-by-number routines where possible. Similarly, where COBOL run-time
system routines prefixed "CBL_" exist, you are encouraged to use these in
Library routines (call-by-name);CBL_routines vs. operating system
preference to calling operating system functions since using these calls
gives you portability with other UNIX systems as well as with other COBOL
systems supporting the same calls, such as Micro Focus COBOL for DOS and
OS/2.
Portability of Call-by-Name Routines
CBL_routines are intended to be fully portable across all run-time
systems; however, a number are currently available only in one or two
run-time systems. The following table contains a list of the CBL_
routines available on this COBOL system for UNIX, DOS and OS/2 to enable
you to consider portability issues when writing your applications.
Note: A number of UNIX-specific routines prefixed "cob" are also
provided with this COBOL system. Because they they are not
portable to non-UNIX environments they have not been described
in this chapter. See Appendix A Advanced Programming
Features for details on these routines.
Routines marked by a single asterisk (*) may not yet be supported in the
specified environment. Your Release Notes will list any routines which
become available under additional run-time systems in later releases of
this product. A double asterisk (**) indicates that there are no plans
to support the routine in the specified environment.
--------------------------------------------------------------------------------
| | | |
| COBOL System Library Routines | DOS and OS/2 | UNIX |
| | | |
--------------------------------------------------------------------------------
| | | | |
| | COBLIC | LCOBOL | |
| | | | |
| Application Subsystems: | | | |
| | | | |
| CBL_SUBSYSTEM | | * | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Byte-Stream Files: | | | |
| | | | |
| CBL_CLOSE_FILE | | | |
| | | | |
| CBL_CREATE_FILE | | | |
| | | | |
| CBL_OPEN_FILE | | | |
| | | | |
| CBL_READ_FILE | | | |
| | | | |
| CBL_WRITE_FILE | | | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Closedown Procedure: | | | |
| | | | |
| CBL_EXIT_PROC | | * | |
| | | | |
--------------------------------------------------------------------------------
-----------------------------------------------------------------------
| | | |
| COBOL System Library Routines | DOS and OS/2 | UNIX |
| | | |
-----------------------------------------------------------------------
| | | | |
| | COBLIC | LCOBOL | |
| | | | |
| Error Procedures: | | | |
| | | | |
| CBL_ERROR_PROC | ** | ** | |
| | | | |
-----------------------------------------------------------------------
| | | | |
| Files: | | | |
| | | | |
| CBL_CHANGE_DIR | | | |
| | | | |
| CBL_CHECK_FILE_EXIST | | | |
| | | | |
| CBL_COPY_FILE | | * | |
| | | | |
| CBL_CREATE_DIR | | | |
| | | | |
| CBL_DELETE_DIR | | | |
| | | | |
| CBL_LOCATE_FILE | | * | |
| | | | |
| CBL_READ_DIR | | | |
| | | | |
| CBL_RENAME_FILE | | | |
| | | | |
-----------------------------------------------------------------------
| | | | |
| File-names: | | | |
| | | | |
| CBL_JOIN_FILENAME | | | |
| | | | |
| CBL_SPLIT_FILENAME | | | |
| | | | |
-----------------------------------------------------------------------
| | | | |
| Keyboard: | | | |
| | | | |
| CBL_GET_KBD_STATUS | | | |
| | | | |
| CBL_READ_KBD_CHAR | | | |
| | | | |
-----------------------------------------------------------------------
| | | | |
| CBL_AND | | | |
| | | | |
| CBL_EQ | | | |
| | | | |
| CBL_IMP | | | |
| | | | |
| CLB_NOT | | | |
| | | | |
-----------------------------------------------------------------------
--------------------------------------------------------------------------------
| | | |
| COBOL System Library Routines | DOS and OS/2 | UNIX |
| | | |
--------------------------------------------------------------------------------
| | | | |
| | COBLIC | LCOBOL | |
| | | | |
| CBL_OR | | | |
| | | | |
| CBL_XOR | | | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Mouse: | | | |
| | | | |
| CBL_GET_MOUSE_MASK | | | * |
| | | | |
| CBL_GET_MOUSE_POSITION | | | * |
| | | | |
| CBL_GET_MOUSE_STATUS | | | * |
| | | | |
| CBL_HIDE_MOUSE | | | * |
| | | | |
| CBL_INIT_MOUSE | | | * |
| | | | |
| CBL_READ_MOUSE_EVENT | | | * |
| | | | |
| CBL_SET_MOUSE_MASK | | | * |
| | | | |
| CBL_SET_MOUSE_POSITION | | | * |
| | | | |
| CBL_SHOW_MOUSE | | | * |
| | | | |
| CBL_TERM_MOUSE | | | * |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Multiple Run-Units: | | | |
| | | | |
| CBL_ALLOC_MEM | | | |
| | | | |
| CBL_CULL_RUN_UNITS | | | |
| | | | |
| CBL_EXEC_RUN_UNIT | | | |
| | | | |
| CBL_FREE_MEM | | | |
| | | | |
| CBL_GET_SHMEM_PTR | | | |
| | | | |
| CBL_PUT_SHMEM_PTR | | | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| National Language Support: | | | |
| | | | |
| CBL_NLS_CLOSE_MSG_FILE | | | * |
| | | | |
| CBL_NLS_COMPARE | | | * |
| | | | |
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
| | | |
| COBOL System Library Routines | DOS and OS/2 | UNIX |
| | | |
--------------------------------------------------------------------------------
| | | | |
| | COBLIC | LCOBOL | |
| | | | |
| CBL_NLS_INFO | | | * |
| | | | |
| CBL_NLS_OPEN_MSG_FILE | | | * |
| | | | |
| CBL_NLS_READ_MSG | | | * |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Operating System Information: | | | |
| | | | |
| CBL_GET_OS_INFO | | | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Screen: | | | |
| | | | |
| CBL_CLEAR_SCR | | | |
| | | | |
| CBL_GET_CSR_POS | | | |
| | | | |
| CBL_GET_SCR_SIZE | | | |
| | | | |
| CBL_READ_SCR_ATTRS | | | |
| | | | |
| CBL_READ_SCR_CHARS | | | |
| | | | |
| CBL_READ_SCR_CHATTRS | | | |
| | | | |
| CBL_SET_CSR_POS | | | |
| | | | |
| CBL_SWAP_SCR_CHATTRS | | | |
| | | | |
| CBL_WRITE_SCR_ATTRS | | | |
| | | | |
| CBL_WRITE_SCR_CHARS | | | |
| | | | |
| CBL_WRITE_SCR_CHARS_ATTR | | | |
| | | | |
| CBL_WRITE_SCR_SCR_CHATTRS | | | |
| | | | |
| CBL_WRITE_SCR_N_ATTR | | | |
| | | | |
| CBL_WRITE_SCR_N_CHAR | | | |
| | | | |
| CBL_WRITE_SCR_N_CHATTR | | | |
| | | | |
| CBL_WRITE_SCR_TTY | | | |
| | | | |
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
| | | |
| COBOL System Library Routines | DOS and OS/2 | UNIX |
| | | |
--------------------------------------------------------------------------------
| | | | |
| | COBLIC | LCOBOL | |
| | | | |
| Text: | | | |
| | | | |
| CBL_TOLOWER | | | |
| | | | |
| CBL_TOUPPER | | | |
| | | | |
--------------------------------------------------------------------------------
| | | | |
| Virtual Heaps: | | | |
| | | | |
| CBL_CLOSE_VFILE | | | |
| | | | |
| CBL_OPEN_VFILE | | | |
| | | | |
| CBL_READ_VFILE | | | |
| | | | |
| CBL_WRITE_VFILE | | | |
| | | | |
--------------------------------------------------------------------------------
The section Routines by Category is intended to 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
The categories of call-by-name routines are:
* Application Subsystems
* Byte-Stream Files
* Closedown Procedure
* Error Procedure
* File-names
* Files
* Keyboard
* Logic Operators
* Mouse
* Multiple Run-Units
* National Language Support
* Operating System Information
* Screen
* Text
* Virtual Heaps
The routines in each category are listed below. Details common to all
the routines in a category are also shown.
Application Subsystems.
CBL_SUBSYSTEM Declare/deallocate subsystems
Byte-Stream Files.
CBL_CLOSE_FILE Close a 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
The Micro Focus byte-stream file routines allow 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 will be set to zero. If the routine fails, the RETURN-CODE
register will contain a file status value indicating the failure. This
file status will always be the standard ANSI '74 file status value. If
no ANSI '74 file status is defined for the error, a standard Micro Focus
error status will be returned (9/nnn where nnn is the RTS error number).
Closedown Procedure.
CBL_EXIT_PROC Register a closedown procedure
Error Procedure.
CBL_ERROR_PROC Post and remove user error procedures
File-names.
CBL_JOIN_FILENAME Join parts of file-name
CBL_SPLIT_FILENAME Divide file-name into parts
These 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, base-name and extension. For example,
in the following file-name:
abc/def/file.dat
the path is abc/def, the base-name is file, and the extension is dat.
The routines can work with strings up to 65,535 characters long, but your
environment imposes a limit on the maximum length of a file-name:
Micro Focus COBOL for UNIX - 100 characters. The maximum number of
characters allowed between / characters is 14.
DOS - 65 characters
OS/2 - 265 characters
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
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
These routines carry out logic operations on bits. Apart from CBL_NOT,
all these operations have two operands.
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
The routines are available on DOS and OS/2; they have no effect in Micro
Focus COBOL for UNIX V3.0.
Multiple Run-Units.
CBL_ALLOC_MEM Dynamic memory allocation
CBL_CULL_RUN_UNITS Clear dead run-units
CBL_EXEC_RUN_UNIT Create run-unit
CBL_FREE_MEM Free dynamically allocated memory
CBL_GET_SHMEM_PTR Read named value
CBL_PUT_SHMEM_PTR Create/update named value
CBL_YIELD_RUN_UNIT Other environments.
National Language Support.
CBL_NLS_CLOSE_MSG_FILE Close NLS message file
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
These COBOL system library routines are available only on DOS and OS/2
environments. This COBOL system does support a number of NLS routines
for UNIX environments, including: cobgetenv(), nl_langinfo() and
nl_cobcmp(). These NLS routines are described in Chapter 30 National
Language Support.
Operating System Information.
CBL_GET_OS_INFO Get operating system environment
information
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
Text.
CBL_TOLOWER Convert a string to lower case
CBL_TOUPPER Convert a string to upper case
Virtual Heaps.
CBL_CLOSE_VFILE Close heap
CBL_OPEN_VFILE Open heap
CBL_READ_VFILE Read heap
CBL_WRITE_VFILE Write heap
There are four library routines available for handling heaps. A heap
is a byte-stream file which is buffered in available memory. Each heap
is associated with a status word specified when the heap is created,
which 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.
Each heap is paged, if necessary. Each run-unit is limited to 128 local
heaps.
Heaps are accessed by means of heap identifier words, which may be passed
around between programs so that any heap may 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 also can 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.
Notes:
* You can use reference modification to declare a 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.
* If the read/write succeeds, the return code is zero. If it fails,
the return code is nonzero and the heap status byte is nine, with
detail in the second byte.
* The buffer for both the CBL_READ_VFILE and CBL_WRITE_VFILE
routines can reside anywhere within the data or Linkage Section.
The buffer can also be dynamically allocated via the CBL_ALLOC_MEM
routine.