HP 3000 Manuals HP 3000 Manuals
List of Routines
CBL_ALLOC_MEM
Dynamically allocates memory.
Syntax:.
call "CBL_ALLOC_MEM" using mem-pointer
by value mem-size
flags
Parameters:.
mem-pointer USAGE POINTER.
mem-size PIC X(4) COMP-5.
flags PIC X(4) COMP-5.
Remarks:.
Updates to any shared memory allocated to this function are NOT
serialized or protected by the run-time system; you should use semaphores
to maintain the integrity of the data.
Non-shared memory is owned by the program that created it, and is
released when the program is canceled if it hasn't already been released
using CBL_FREE_MEM routine. Shared memory is owned by the COBOL run-unit
(coru) - the set of run-units containing the initial run-unit and all
run-units created from it; it is released when the coru is terminated.
With 16-bit run-time systems, the size of each block of memory allocated
using CBL_ALLOC_MEM is limited to 65531 bytes.
WARNING With 16-bit run-time systems, if you use CBL_ALLOC_MEM to
allocate memory for an item in the Linkage Section, the
potential size of the item must not exceed 65531 bytes. If this
limit is exceeded, results are unpredictable and include the
possibility of a protection violation occuring.
The potential size of a Linkage Section item is determined by
the total size of all the data items defined within the item.
For example:
01 lk-item1.
03 filler pic x
occurs 65536 times depending on lk-item1-size.
03 lk-item1a pic x(50).
03 lk-item2a pic x(4) comp-x.
lk-item-1 has the potential of exceeding the maximum size of
65531 as the total of the data items it contains is 65590.
With 32-bit run-time systems, the maximum size of non-shared
memory is restrictred only by your operating system (unless the
-l run-time switch is set). The size for shared memory
allocated using this routine is limited to a maximum of around
of 64000 bytes.
On Entry:.
memsize The number of bytes of memory to allocate.
flags bits 7 - 2 - reserved
bit 1 = 0 make the allocated memory
relocatable. This is the default.
= 1 make the allocated memory fixed.
This bit has no effect on UNIX, OS/2
or Windows.
bit 0 = 0 make the allocated memory
nonshared. This is the default.
= 1 make the allocated memory shared.
On Exit:.
mem-pointer A pointer to the memory returned. Must be an
01-level data item.
CBL_AND
Does a logical AND between the bits of two data items.
Syntax:.
call "CBL_AND" 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 ANDs the
bits together, storing the result in target. The truth table for this
is:
source target result
--------------------
0 0 0
0 1 0
1 0 0
1 1 1
See Introduction to Logic Routines.
On Entry:.
source One of the data items to AND.
target The other data item to AND.
length The number of bytes of source and target to AND.
Positions in target beyond this are unchanged.
Exit:.
target The result.
CBL_CHANGE_DIR
Changes the current directory.
Syntax:.
call "CBL_CHANGE_DIR" using path-name
returning status-code
Parameters:.
path-name PIC X(n).
status-code See section Key
On Entry:.
path-name Relative or absolute path-name terminated by space or
null (x"00"). This must be no longer than the number
of characters allowed by your operating system and
must be valid from the directory that is current when
the routine is called.
On Exit:.
None
CBL_CHECK_FILE_ EXIST
Checks whether a file exists and returns details if it does.
Syntax:.
call "CBL_CHECK_FILE_EXIST" using file-name
file-details
returning status-code
Parameters:.
file-name PIC X(n).
file-details Group item defined as:
file-size PIC X(8) COMP-X.
file-date
day PIC X COMP-X.
month PIC X COMP-X.
year PIC X(2) COMP-X.
file-time
hours PIC X COMP-X.
minutes PIC X COMP-X.
seconds PIC X COMP-X.
hundredths PIC X COMP-X.
status-code See section Key
On Entry:.
file-name The file to look for. The name can contain a path,
and is terminated by a space. If no path is given,
the current directory is assumed.
On Exit:.
file-size The size of the file in bytes.
file-date The date the file was created.
file-time The time the file was created.
CBL_CLEAR_SCR
Clears the whole screen to a specified character and attribute.
Syntax:.
call "CBL_CLEAR_SCR" using character
attribute
returning status-code
Parameters:.
character PIC X.
attribute PIC X.
status-code See section Key
On Entry:.
character The character to write.
attribute The attribute to write.
On Exit:.
None
CBL_CLOSE_FILE
Closes a file opened for byte-stream operations.
Syntax:.
call "CBL_CLOSE_FILE" using file-handle
returning status-code
Parameters:.
file-handle PIC X(4).
status-code See section Key
Remarks:.
Any byte-stream file open when a STOP RUN is executed is automatically
closed.
See Introduction to Byte-stream Routines
On Entry:.
file-handle The file handle returned when the file was opened.
On Exit:.
None
CBL_CLOSE_VFILE
Closes a heap.
Syntax:.
call "CBL_CLOSE_VFILE" using by value heap-id
Parameters:.
heap-id PIC X(2) COMP-5.
Remarks:.
See Introduction to Heap Routines
On Entry:.
heap-id This contains the heap handle assigned when the heap
was opened.
On Exit:.
None
CBL_COPY_FILE
Copies a file.
Syntax:.
call "CBL_COPY_FILE" using file-name1
file-name2
returning status-code
Parameters:.
file-name1 PIC X(n).
file-name2 PIC X(n).
status-code See section Key
Remarks:.
The file-names specified must be unique names. They cannot include
wildcard characters.
On Entry:.
file-name1 The file to copy. The name can contain a path and is
terminated by a space. If no path is given, the
current directory is assumed.
file-name2 The name of the new file. The name can contain a
path and is terminated by a space. If no path is
given, the current directory is assumed.
On Exit:.
None
CBL_CREATE_DIR
Creates a subdirectory. All the directories in the given path, except
the last, must already exist.
Syntax:.
call "CBL_CREATE_DIR" using path-name
returning status-code
Parameters:.
path-name PIC X(n).
status-code See section Key
On Entry:.
path-name Relative or absolute path-name terminated by space or
null (x"00").
On Exit:.
None
CBL_CREATE_FILE
Creates a new file for byte-stream operations.
Syntax:.
call "CBL_CREATE_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_CULL_RUN_UNITS
Clears any dead run-units.
Syntax:.
call "CBL_CULL_RUN_UNITS"
Parameters:.
None
Remarks:.
This routine clears any run-units that have been terminated by a STOP RUN
or Kill, but have not yet been removed.
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:.
None
On Exit:.
None
CBL_DELETE_DIR
Deletes a directory. The directory is deleted only if it is empty.
Syntax:.
call "CBL_DELETE_DIR" using path-name
returning status-code
Parameters:.
path-name PIC X(n).
status-code See section Key
On Entry:.
path-name Relative or absolute path-name terminated by space or
null (x"00").
On Exit:.
None
CBL_DELETE_FILE
Deletes a file.
Syntax:.
call "CBL_DELETE_FILE" using file-name
returning status-code
Parameters:.
file-name PIC X(n).
status-code See section Key
On Entry:.
file-name The file to delete. The name can contain a
path-name, and is terminated by a space. If no path
is given, the current directory is assumed.
On Exit:.
None
CBL_EQ
Does a logical EQUIVALENCE between the bits of two data items.
Syntax:.
call "CBL_EQ" 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
EQUIVALENCEs the bits together, storing the result in target. The truth
table for this is:
source target result
--------------------------------------------------------------------------------------
0 0 1
0 1 0
1 0 0
1 1 1
See Introduction to Logic Routines.
On Entry:.
source One of the data items to EQUIVALENCE.
target The other data item to EQUIVALENCE.
length The number of bytes of source and target to
EQUIVALENCE. Positions in target beyond this length
are unchanged.
On Exit:.
target The result.
CBL_ERROR_PROC
Installs or removes an error procedure to be invoked automatically when a
run-time system error occurs.
Syntax:.
call "CBL_ERROR_PROC" using install-flag
install-addrs
returning status-code
Parameters:.
install-flag PIC X COMP-X.
install-addrs USAGE PROCEDURE POINTER
status-code See section Key
Remarks:.
This routine is available only in UNIX environments. Any attempt to link
or run in other environments a program containing a call to this routine
will result in an error.
You can install several error procedures for an application by repeated
calls of this routine.
An error procedure can be written in any language. If it is in COBOL,
install-addrs must be the address of an entry point. You can obtain this
address using the statement:
set install-addrs to entry entry-name
An error procedure in COBOL can include any legal COBOL, including CALL
statements.
When an error occurs the installed procedures are executed, starting with
the most recently installed and ending with the first one installed.
When all have been processed, the RTS error handling procedure is then
started.
If you don't want any other error procedures, including the RTS error
handling, to be executed after terminating your error procedure, set
RETURN-CODE to zero.
When an installed error procedure is called, the character string
containing the relevant RTS error message is passed as a parameter. You
should define this parameter in the Linkage Section as PIC X(325), and
include it in the USING phrase of the entry to the error procedure.
The following is an example of the RTS error message string:
Load Error : file '<prog-name>'\n
error code: 173, pc=0, call=-1, seg=0\n
173 Called program file not found in drive/directory\n\0
where \n is a new-line character and \0 is a null (x"00") terminator.
This format is described in your Error Messages manual.
If a program containing an error procedure is canceled, the
error-procedure is removed.
An error procedure installed in one program can be removed by another
program.
An error procedure can install an error procedure.
If an RTS error occurs within an error procedure, the procedure is
terminated. The RTS then processes the new RTS error, starting with the
next error procedure, if there is one.
You must ensure that the procedure-pointer you use to install the
procedure is valid.
An error procedure belongs to the run-unit from which it was installed.
So the error procedure is executed only by the run-unit that installed
it.
Pressing interrupt does not cause any error procedures to be called.
On Entry:.
install-flag Indicates the operation to be performed:
0 - install error procedure
1 - de-install error procedure
install-addrs Address of error procedure to install or de-install.
On Exit:.
None
Example:.
The following is an example of installing an error procedure, and the
skeleton of the error procedure that is called if an error occurs.
working-storage section.
01 install-flag pic x comp-x value 0.
01 install-address usage procedure-pointer.
01 status-code pic 9(4) comp value zeros.
linkage section.
01 err-msg pic x(325).
procedure division.
set install-address to entry "err-proc"
call "CBL_ERROR_PROC" using install-flag
install-address
returning status-code.
* Error procedure:
entry "err-proc" using err-msg.
* Process err-msg to find out the error number.
* Act accordingly.
...
* Terminate, but allow other error procedures to be executed.
move 1 to return-code
exit program
stop run.
CBL_EXEC_RUN_UNIT
Creates an asynchronous run-unit.
Syntax:.
call "CBL_EXEC_RUN_UNIT" using command-line
by value command-line-len
by reference run-unit-id
by value stack-size
flags
Parameters:.
command-line PIC X(n).
command-line-len PIC X(4) COMP-5.
run-unit-id PIC X(8) COMP-5.
stack-size PIC X(4) COMP-5.
flags PIC X(4) COMP-5.
Remarks:.
The run-unit that makes the call is known as the "parent", while the
run-unit created is known as the "child". On creation, the child
inherits certain attributes from its parent. The attributes inherited by
the child are copies of the attributes in the parent at the exact time of
the call; any changes made to the attributes of the parent after the call
are not reflected in the child's attributes. Similarly, any changes made
to the child's attributes are not reflected in the parent's attributes.
The set of run-units containing the initial run-unit and all run-units
created from it is known as the coru.
You should be aware of the following when using run-units:
* All COBOL programs in the child are in their initial state.
* To improve both speed and size, the stack-size and flags
parameters should be either literal ot level-01 items.
* Data is not shared between run-units unless explicitly specified
using CBL_GET_SHMEM_PTR, CBL_PUT_SHMEM_PTR or CBL_ALLOC_MEM.
* COBOL and RTS switches, environment variables, and open libraries
are inherited by the child.
* Open files and heaps are not inherited by the child.
After using CBL_EXEC_RUN_UNIT, RETURN-CODE contains one of the following
values:
0 = Success
157 = Out of memory
181 = Invalid parameter
200 = Internal logic error
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:.
command-line The command passed to the new run-unit. This should
be the program name followed by any parameters.
line-length The length of the command-line.
stack-size Suggests the size of the stack (in bytes) to be
allocated to the new run-unit. Specifying zero for
this parameter causes the child's stack to be the
same size as the parent's.
A minimum of 2K must be allocated if running under
DOS, Windows or OS/2. DOS, Windows and OS/2 allocate
8K for the stack of the initial run-unit.
This parameter is ignored if running under UNIX.
flags Reserved for future use. Must be zero.
On Exit:.
run-unit-id The unique handle identifying the new run-unit. This
must be a 01-level data item.
CBL_EXIT_PROC
Installs or removes a closedown procedure to be invoked automatically
when the application terminates.
Syntax:.
call "CBL_EXIT_PROC" using install-flag
install-params
returning status-code
Parameters:.
install-flag PIC X COMP-X.
install-params Group item defined as:
install-addrs USAGE PROCEDURE POINTER
install-prrty PIC X COMP-X
status-code See section Key
Remarks:.
The installed closedown procedure is executed whether the application
finishes normally (with a STOP RUN) or abnormally (for example, with a
keyboard interrupt or RTS error). You can install several closedown
procedures for an application by repeated calls of this routine.
A closedown procedure can be written in any language. If it is in COBOL,
install-addrs must be the address of an entry point. You can obtain this
address using the statement:
set install-addrs to entry "entry-name"
A closedown procedure in COBOL can include any legal COBOL, including
call statements. The closedown procedure terminates when the main
program in the procedure executes an EXIT PROGRAM/GOBACK or when a STOP
RUN statement is executed.
A closedown procedure does not have any parameters passed to it when it
is called.
On DOS, Windows and OS/2, a closedown procedure in any other language
must preserve the i86 machine code BP register and direction flag, and
terminate with a far return (RETF) instruction; that is, it must be a far
procedure.
Every closedown procedure installed has a priority. This priority
determines the order in which the procedures are executed - procedures
with the lowest values are processed first. If several procedures have
the same priority, they are executed in reverse order of installation -
that is the last one installed is executed first.
Procedures installed without a priority (install-flag = 0) are given the
default priority of 64. To set your own priority, set install-flag = 3
and set the priority to a value in the range 0 to 127. Priorities 128 to
256 are reserved for use by the COBOL system. You must not set a
priority higher than 127.
If a closedown procedure has already been installed, an attempt to
install again fails. However, if the priority used on the second attempt
is different to that used when it was installed, its priority is changed.
Note that RETURN-CODE is set to zero.
Use install-flag = 2 to find the priority of a previously installed
procedure. This returns the priority in install-prrty if it is found The
procedure is identified by its install-addrs. If the procedure cannot be
found, RETURN-CODE is set nonzero.
On Entry:.
install-flag Indicates the operation to be performed:
0 = install closedown procedure with default priority
of 64
1 = de-install closedown procedure
2 = query priority of installed closedown procedure
3 = install closedown procedure with given priority
install-addrs Address of closedown procedure to install, de-install
or query.
install-prrty When install-flag is 3, contains the priority of the
closedown procedure being installed, in range 0 to
127. Otherwise, ignored.
On Exit:.
install-prrty When install-flag is set to 2, returns the priority
of the selected procedure