HP 3000 Manuals HP 3000 Manuals
List of Routines (cont)
CBL_NLS_CLOSE_MSG_ FILE
Closes a National Language Support (NLS) message file.
Syntax:.
call "CBL_NLS_CLOSE_MSG_FILE" using msg-file-handle
returning status-code
Parameters:.
msg-file-handle PIC X(4).
status-code See section Key
Remarks:.
This routine is not available in UNIX environments.
This routine enables you to close a National Language Support
(NLS) message file that had been previously opened using the
CBL_NLS_OPEN_MSG_FILE routine.
This routine can be used only from a program that was compiled with the
NLS Compiler directive. For more details on National Language Support
see the chapter National Language Support in your COBOL System Reference.
On Entry:.
msg-file-handle The identifying handle returned when the message file
was opened.
On Exit:.
status-code Indicates whether the routine was successful:
0 = success
40 = NLS module not initialized
404 = invalid msg-file-handle
If status-code contains a value other than these, it
is the number of a run-time error message.
CBL_NLS_COMPARE
Compares two strings.
Syntax:.
call "CBL_NLS_COMPARE" using string1
string2
by value string1-length
by value string2-length
by reference result-byte
returning status-code
Parameters:.
string1 PIC X(n).
string2 PIC X(n).
string1-length PIC X(4) COMP-5.
string2-length PIC X(4) COMP-5.
result-byte PIC S9 COMP-5.
status-code See section Key
Remarks:.
This routine is not available in UNIX environments.
This routine can be used only from a program that was compiled with the
NLS Compiler directive. For more details on National Language Support
see the chapter National Language Support in your COBOL System Reference.
On Entry:.
string1 The first string.
string2 The second string.
string1-length Length of the first string.
string2-length Length of the second string.
On Exit:.
result-byte Result of the comparison:
0 = the two strings have equal weights
-1 = string1 < string2
+1 = string1 &> string2
status-code Indicates whether the routine was successful:
0 = success
40 = NLS module not initialized
CBL_NLS_INFO
Get/set national language information.
Syntax:.
call "CBL_NLS_INFO" using function-code
info-category
info-buffer
returning status-code
Parameters:.
function-code PIC X COMP-X.
info-category PIC X COMP-X.
info-buffer PIC X(n).
status-code See section Key
Function-code Contains one of the following subfunction numbers:
1 = get national language information
2 = set national language information
3 = reserved
4 = reserved
Remarks:.
This routine is not available in UNIX environments.
This routine enables you to both get and set information about the
national language. With function-code = 2 (set information) the change
made only applies to the program that made the call.
This routine can be used only from a program that was compiled with the
NLS Compiler directive. For more details on National Language Support
see the chapter National Language Support in your COBOL System Reference.
On Entry:.
With function-code = 1:
info-category Category of information to get from the NLS module:
1 = currency symbol
2 = thousands separator
3 = decimal separator
With function-code = 2:
info-category Category of information to set:
1 = currency symbol
2 = thousands separator
3 = decimal separator
info-buffer Information to set (null-terminated). The thousands
and decimal separators are each one character long.
The currency symbol is upto 10 characters long.
On Exit:.
With function-code = 1:
info-buffer The information requested.
status-code Indicates whether the routine was successful:
0 = success
40 = NLS module not initialized
With function-code = 2:
status-code Indicates whether the routine was successful:
0 = success
40 = NLS module not initialized
405 = failure
CBL_NLS_OPEN_MSG_ FILE
Open a National Language Support (NLS) message file.
Syntax:.
call "CBL_NLS_OPEN_MSG_FILE" using msg-file-name
msg-file-name-ln
msg-file-handle
returning status-code
Parameters:.
msg-file-name PIC X(n).
msg-file-name-ln PIC X COMP-X.
msg-file-handle PIC X(4).
status-code See section Key
Remarks:.
This routine is not available in UNIX environments.
This routine opens an NLS message file, returning an identifying handle
that you can use with the CBL_NLS_READ_MSG and CBL_NLS_CLOSE_MSG_FILE
routines. You can create different message files for each language you
want your program to work with, usingthe same call to access each message
in the appropriate national language. You can use a default message
file, or create your own.
This routine can be used only from a program that was compiled with the
NLS Compiler directive. For more details on National Language Support
see the chapter National Language Support in your COBOL System Reference.
On Entry:.
msg-file-name The name of the message file to be opened.
msg-file-name-ln The length of msg-file-name. If this parameter is
set to zero, the default message file is opened
regardless of the contents of msg-file-name.
On Exit:.
msg-file-handle The identifying handle. Indicates whether the
routine was successful:
0 = success
40 = NLS module not initialized
If status-code contains a value other than these, it
is the number of a run-time error message.
CBL_NLS_READ_MSG
Reads a message from a National Language Support (NLS) message file.
Syntax:.
call "CBL_NLS_READ_MSG" using msg-file-handle
full-msg-number
msg-ins-structure
msg-buffer
returning status-code
Parameters:.
msg-file-handle PIC X(4).
full-msg-number Group item defined as:
msg-set-number PIC X(2) COMP-X.
msg-number PIC X(2) COMP-X.
msg-ins-struct Group item defined as:
ins-count PIC X(2) COMP-X.
ins-pointer USAGE POINTER OCCURS n TIMES
msg-buffer Group item defined as:
msg-buff-len PIC X(2) COMP-X.
msg-buff-text PIC X(n).
status-code See section Key
Remarks:.
This routine is not available in UNIX environments.
In each message file, messages are divided into sets; this enables you to
define your own message set in the default message file if you wish.
This routine also enables you to insert portions of text into a message
fetched from the message file in the order appropriate to the rules of
the grammar for the national language.
This routine can be used only from a program that was compiled with the
NLS Compiler directive. For more details on National Language Support
see the chapter National Language Support in yourCOBOL System Reference.
On Entry:.
msg-file-handle The identifying handle of the message file to fetch
the message from.
msg-set-number The set in the message file to fetch the message
from.
msg-number The message number in the message set to fetch the
message from.
ins-count The number of portions of text to insert in to the
message.
ins-pointer A pointer to a null-terminated portion of text to
insert in to the message.
msg-buff-len The length of msg-buff-text.
On Exit:.
msg-buff-text The returned text (null-terminated).
status-code Indicates whether the routine was successful:
0 = success
40 = NLS module not initialized
401 = message set not found
402 = message not found in set
403 = message too long for message-text-buffer
404 = invalid msg-file-handle
If status-code contains a value other than these, it
is the number of a run-time error message.
CBL_NOT
Does a logical NOT on the bits of a data item.
Syntax:.
call "CBL_NOT" using target
by value length
returning status-code
Parameters:.
target Any data item.
length Numeric literal or PIC X(4) COMP-5.
status-code See section Key
Remarks:.
The routine starts at the left-hand end of target and inverts bits. The
truth table for this is:
before after
---------------------------------------------------------------------------------------
0 1
1 0
See Introduction to Logic Routines.
On Entry:.
target The data to operate on.
On Exit:.
target The data with the bits inverted.
length The number of bytes of target to change. Positions
beyond this are unchanged.
CBL_OPEN_FILE
Opens an existing file for byte-stream operations.
Syntax:.
call "CBL_OPEN_FILE" using file-name
access-mode
deny-mode
device
file-handle
returning status-code
Parameters:.
file-name PIC X(n).
access-mode PIC X COMP-X.
deny-mode PIC X COMP-X.
device PIC X COMP-X.
file-handle PIC X(4).
status-code See section Key
Remarks:.
See Introduction to Byte-stream Routines
On Entry:.
file-name Space- or null-terminated file-name of the file to be
opened.
access-mode Defines access mode:
1 = read only
2 = write only (deny-mode must be 0)
3 = read/write
deny-mode Defines deny mode:
0 = deny both read and write (exclusive)
1 = deny write
2 = deny read
3 = deny neither read nor write
device Reserved for future use (must be 0).
On Exit:.
file-handle Returns a file handle for a successful open.
CBL_OPEN_VFILE
Opens a heap.
Syntax:.
call "CBL_OPEN_VFILE" using heap-id
status-word
Parameters:.
heap-id PIC X(2) COMP-5.
status-word PIC X(2).
Remarks:.
See Introduction to Heap Routines
On Entry:.
None
On Exit:.
heap-id This contains the heap handle assigned. A heap
handle of zero means the open failed.
status-word The status word for the heap, set to zero on the
open. When heap-id = 9, binary values in the second
status byte are:
000 = heap closed by user request
001 = heap access failure - out of buffers
002 = heap deallocated while program inactive
014 = backing-file failure: too many files
037 = backing-file failure: file access denied
201 = backing-file failure: I/O failure
status-word remains associated with the heap until
the heap is closed; the first byte is set to ASCII
zero by a successful OPEN; status-word is written as
file status data by a subsequent heap READ or WRITE
or CLOSE that encounters allocationor I/O errors (but
is not reset to zero by successful operations).
If a program in which a heap status-word actually
exists (that is, it is not in a Linkage Section) is
canceled, all heaps with status- words in that
program are automatically canceled, and the heap
identifiers (which might have been passed to other
programs) should not be used any more.
CBL_OR
Does a logical OR between the bits of two data items.
Syntax:.
call "CBL_OR" using source
target
by value length
returning status-code
Parameters:.
source Any data item.
target Any data item.
length Numeric literal or PIC X(4) COMP-5.
status-code See section Key
Remarks:.
The routine starts at the left-hand end of source and target and ORs the
bits together, storing the result in target. The truth table for this
is:
source target result
--------------------------------------------------------------------------------------
0 0 0
0 1 1
1 0 1
1 1 1
See Introduction to Logic Routines.
On Entry:.
source One of the data items to OR.
target The other data item to OR.
length The number of bytes of source and target to OR.
Positions in target beyond this are unchanged.
On Exit:.
target The result.
CBL_PUT_SHMEM_PTR
Creates or updates a named value.
Syntax:.
call "CBL_PUT_SHMEM_PTR" using by value node-value
by reference node-name
Parameters:.
node-value USAGE POINTER.
node-name Group item defined as:
name-length PIC X COMP-5 VALUE n.
name PIC X(n) VALUE "name".
Remarks:.
Named values provide a way of passing pointers between different
run-units using a name agreed at run-time. Named values can be read
simultaneously by all units in the coru because the run-time system
protects and serializes any updates. The maximum number of named values
depends on how much memory your machine has.
On DOS, Windows and OS/2 this routine is available only with the add-on
product, Toolset, available from Micro Focus. It works only with .int
and .gnt files. It does not work with linked object code.
On Entry:.
node-value The value to assign to the created/updated named
value.
name-length The length of name.
name The name of the named value.
On Exit:.
None
CBL_READ_DIR
Returns the current directory or path.
Syntax:.
call "CBL_READ_DIR" using path-name
path-name-length
returning status-code
Parameters:.
path-name PIC X(n).
path-name-length PIC X COMP-X.
status-code See section Key
On Entry:.
path-name-length Length of path-name to be used. If this is too small
for the path-name, the routine fails.
On Exit:.
path-name Relative or absolute path-name terminated by space or
null (x"00").
CBL_READ_FILE
Reads bytes from a file.
Syntax:.
call "CBL_READ_FILE" using file-handle
file-offset
byte-count
flags
buffer
returning status-code
Parameters:.
file-handle PIC X(4).
file-offset PIC X(8) COMP-X.
byte-count PIC X(4) COMP-X.
flags PIC X COMP-X.
buffer PIC X(n).
status-code See section Key
Remarks:.
See Introduction to Byte-stream Routines
On Entry:.
file-handle'\\ The offset in the file at which to read. This field
The file handle is currently limited to a maximum value of
returned when the x"00FFFFFFFF".
file was opened.
\ file-offset
byte-count The number of bytes to read. This field is currently
limited to a maximum value of x"00FFFF".
flags This parameter can take the following values:
0 = standard read
128 = the current file size returned in the
file-offset field
On Exit:.
file-offset Contains the current file size on return if the flags
parameter is set to 128 on entry.
buffer The buffer into which the bytes are read. It is your
responsibility to ensure that the buffer is large
enough to hold the number of bytes to be read.
The buffer parameter is allowed to cross a 64K
segment boundary.
CBL_READ_KBD_CHAR
Waits until a character is typed and then reads it with no echo.
Syntax:.
call "CBL_READ_KBD_CHAR" using char
returning status-code
Parameters:.
char PIC X.
status-code See section Key
On Entry:.
None
On Exit:.
char The character that was typed, in ASCII.
CBL_READ_MOUSE_ EVENT
Reads the mouse event queue and returns information about an event.
Syntax:.
call "CBL_READ_MOUSE_EVENT" using mouse-handle
event-data
read-type
returning status-code
Parameters:.
mouse-handle PIC X(4) COMP-X.
event-data See Introduction to Mouse Routines
read-type PIC X COMP-X.
status-code See section Key
Remarks:.
This routine has no effect in UNIX environments.
If there are no events in the event queue, the return from this routine
depends on the value of read-type. If read-type is zero, the routine
returns immediately with all zero values in event-data. If read-type has
a value of one, return is delayed until an event has been queued.
See Introduction to Mouse Routines.
On Entry:.
mouse-handle Mouse identifier, obtained by earlier call to
CBL_INIT_MOUSE.
read-type Indicates what to do if there are no events in the
queue:
0 = return immediately.
1 = wait for an event, then return.
On Exit:.
event-data See Introduction to Mouse Routines
CBL_READ_SCR_ATTRS
Reads a string of attributes from the screen.
Syntax:.
call "CBL_READ_SCR_ATTRS" using screen-position
attribute-buffer
string-length
returning status-code
Parameters:.
screen-position Group item defined as:
row-number PIC X COMP-X.
column-number PIC X COMP-X.
attribute-buffer PIC X(n).
string-length PIC X(2) COMP-X.
status-code See section Key
On Entry:.
screen-position The screen position to start reading at. The top
left corner is row 0, column 0. See Notes on Screen
Routines.
string-length The length of the string to read.
On Exit:.
attribute-buffer The attributes read from the screen. This data item
must be at least as long as specified by
string-length; positions in it beyond that length are
unchanged.
string-length If the end of the screen is reached the length read
is returned in here.
CBL_READ_SCR_CHARS
Reads a string of characters from the screen.
Syntax:.
call "CBL_READ_SCR_CHARS" using screen-position
character-buffer
string-length
returning status-code
Parameters:.
screen-position Group item defined as:
row-number PIC X COMP-X.
column-number PIC X COMP-X.
character-buffer PIC X(n).
string-length PIC X(2) COMP-X.
status-code See section Key
On Entry:.
screen-position The screen position to start reading at. The top
left corner is row 0, column 0. See Notes on Screen
Routines.
string-length The length of the string to read.
On Exit:.
character-buffer The characters read from the screen. This data item
must be at least as long as specified by
string-length; positions in it beyond that length are
unchanged.
string-length If the end of the screen is reached, the length read
is returned in here.