PreviousIntegrated Preprocessor Interface

Chapter 16: Library Routines

This chapter describes the set of COBOL system library routines that can help you control the environment your application is running in.

16.1 Routines by Category

Object COBOL provides routines in the following categories:

16.1.1 Application Subsystem Routine

CBL_SUBSYSTEM Declare/deallocate subsystems

The application subsystem routine enables you to logically group a number of programs. This enables you to cancel these programs, the subsystem, with a single statement.

16.1.2 Byte Packing Routines

X"F4" Pack bytes
X"F5" Unpack bytes

The byte-packing routines enable you to pack and unpack bytes.

16.1.3 Concurrency - Run-unit and Memory Routines

Memory allocation:
CBL_ALLOC_DYN_MEM Dynamically allocate memory, and associate it with the calling program
CBL_ALLOC_MEM Dynamic allocate memory
CBL_ALLOC_SHMEM Dynamically allocate shared memory
CBL_FREE_MEM Free dynamically allocated memory
Run-unit Handling:
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 remainder of a run-unit's time-slice

The concurrency support routines enable you to manage concurrency. For information on concurrent support, see the chapter Concurrency Support.

16.1.4 Exit and Error Procedure Routines

CBL_ERROR_PROC Register error procedures
CBL_EXIT_PROC Register closedown procedure

The exit and error procedure routines enable you to register your own routines which are executed by the run-time system when your application terminates, either normally or abnormally.

16.1.5 Logic Routines

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

The logic routines carry out logic operations on bits. Apart from CBL_NOT, all these operations have three operands.

If the length is specified as a literal and there is no RETURNING clause then native code is optimized to generate in-line code.

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 carried out using the VALUE clause.

RETURN-CODE is not affected by these routines.

16.1.6 Operating System Information Routine

CBL_GET_OS_INFO Get operating system information

16.1.7 Portability Routine

CBL_SCR_SET_PC_ATTRIBUTES Set up IBM-PC attribute palette

This routine is provided to help you make existing applications portable to other environments. It should not be used in new applications where alternative mechanisms are provided.

16.1.8 Program Information Routine

CBL_GET_PROGRAM_INFO Get operating system information

16.1.9 Text Routines

CBL_TOLOWER Convert a string to lower case
CBL_TOUPPER Convert a string to upper case

16.1.10 Virtual Heap Routines

CBL_CLOSE_VFILE Close heap
CBL_OPEN_VFILE Open heap
CBL_READ_VFILE Read from heap
CBL_WRITE_VFILE Write to heap

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 word. 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 nonzero and the heap status first byte contains "9", with detail in the second byte.

The buffer used with CBL_READ_VFILE and CBL_WRITE_VFILE can reside anywhere in the Data or Linkage Section, or it can be dynamically allocated using the CBL_ALLOC_MEM routine.

Each heap is paged, if necessary.

Each run-unit is limited to 128 local heaps.

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.

16.2 Key to COBOL System Library Routines

Descriptions for all of the library routines appear alphabetically. Each description contains the routine name and function and the following entries (as appropriate):

Syntax: Shows the CALL statement you could use to call the routine.

The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.)

status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5.

The name of the routine must be coded in upper case.

Parameters: Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.
On Entry: Indicates which of the parameters shown are passed on entry.
On Exit: Indicates which of the parameters shown are returned on exit.

Where bits of one or more bytes are referenced, bit 0 is the least significant (right-most) bit.

Comments: Provides any additional information necessary for the successful use of the routine.

Related Topics:

Lists other related topics.

16.3 List of Routines


CBL_ALLOC_DYN_MEM

Dynamically allocates memory, and can associate it with the calling program.

Syntax:
call "CBL_ALLOC_MEM" using     mem-pointer 
                     by value  mem-size 
                               flags 
                     returning status-code
Parameters:
mem-pointer usage pointer. Must be level 01.
mem-size pic x(4) comp-5.
flags pic x(4) comp-5.
status-code See Key.
On Entry:
mem-size The number of bytes of memory to allocate.
flags The type of memory required. You can set the following bits:
0-1 Reserved. Must be set to 0.
2 Allocate this memory independently from any calling program.
3-31 Reserved. Must be set to 0.
On Exit:
mem-pointer A pointer to the memory allocated. The allocated memory is not initialized.
status-code
0 Successful allocation
157 Unable to allocate memory
181 Contradictory flags specification
Comments:

The memory allocated is not initialized to any value.

The maximum size of nonshared memory is restricted only by the operating system (unless the -l run-time switch is set).

If bit 2 is not set the memory allocated by CBL_ALLOC_DYN_MEM is freed when the program that allocated it is cancelled (logically or physically), if there is a COBOL program that is directly or indirectly the caller. If bit 2 is set, this memory is freed when the run-unit terminates, if it has not been previously freed by CBL_FREE_DYN_MEM.


CBL_ALLOC_MEM

Dynamically allocates memory.

Syntax:
call "CBL_ALLOC_MEM" using     mem-pointer 
                     by value  mem-size 
                               flags 
                     returning status-code
Parameters:
mem-pointer usage pointer. Must be level 01.
mem-size pic x(4) comp-5.
flags pic x(4) comp-5.
status-code See Key.
On Entry:
mem-size The number of bytes of memory to allocate.
flags The type of memory required:
0 Relocatable and nonshared.
1 Relocatable and shared.
On Exit:
mem-pointer A pointer to the memory allocated. The allocated memory is not initialized.
Comments:

The memory allocated is not initialized to any value.

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.

Nonshared 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.

The maximum size of nonshared memory is restricted only by the 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.


CBL_ALLOC_SHMEM

Dynamically allocates memory.

Syntax:
call "CBL_ALLOC_MEM" using     mem-pointer 
                     by value  mem-size 
                     returning status-code
Parameters:
mem-pointer usage pointer. Must be level 01.
mem-size pic x(4) comp-5.
status-code See Key.
On Entry:
mem-size The number of bytes of memory to allocate.
On Exit:
mem-pointer A pointer to the memory allocated. The allocated memory is not initialized.
status-code
0 Successful allocation
157 Unable to allocate memory
Comments:

The memory allocated is not initialized to any value.

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.

The maximum size of nonshared memory is restricted only by the 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.


CBL_AND

Does a logical AND between the bits of two data items.

Syntax:
call "CBL_AND" using    source 
                        target 
               by value length
Parameters:
source Any data item
target Any data item.
length Numeric literal or pic x(4) comp-5.
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.
On Exit:
target The result.
Comments:

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 Also:

The chapter Advanced Language Features.


CBL_CLOSE_VFILE

Closes a heap.

Syntax:
call "CBL_CLOSE_VFILE" using by value heap-id 
                       returning      status-code
Parameters:
heap-id pic x(2) comp-5.
status-code See Key.
On Entry:
heap-id This contains the heap handle assigned when the heap was opened.
On Exit:

None

See Also:

Virtual Heap Routines


CBL_CULL_RUN_UNITS

Clears any dead run-units.

Syntax:
call "CBL_CULL_RUN_UNITS"
Parameters:

None

Comments:

This routine clears any run-units that have been terminated by a STOP RUN or kill, but have not yet been removed.

See Also:

The chapter Concurrency Support


CBL_EQ

Does a logical EQUIVALENCE between the bits of two data items.

Syntax:
call "CBL_EQ" using     source 
                        target 
              by value  length
Parameters:
source Any data item.
target Any data item.
length Numeric literal or pic x(4) comp-5.
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.
Comments:

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 Also:

The chapter Advanced Language Features.


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 Key.
On Entry:
install-flag 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

Comments:

You can install several error procedures for an application by repeatedly calling this routine.

Once an error procedure has been posted, subsequent attempts to install that error procedure are silently ignored until it is removed either implicitly (for example, during error processing) or explicitly (by calling CBL_ERROR_PROC with install-flag set to "1").

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 run-time system error handling procedure is then started.

If you don't want any other error procedures, including the run-time system error handling, to be executed after terminating your error procedure, set RETURN-CODE to zero.

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 error procedure is installed during error processing (either by itself, or by another error procedure) then it is executed as soon as the error procedure that installed it returns, assuming that it doesn't return with a ZERO return code.

If a run-time system error occurs in an error procedure, the procedure is terminated. The run-time system then processes the new run-time system 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.

If the error procedure is defined as an entry point in a program that itself could give an error, you must ensure that the program has a Local-Storage Section. This ensures that the program is reentrant and the run-time system will not give error 166 ("Recursive COBOL call is illegal") when trying to execute the error procedure.

Parameter Passed to the Error Procedure

When an installed error procedure is called, the character string containing the relevant run-time system error message is passed as a parameter.

You 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. An example of the run-time system error message string follows:

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.

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_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 Key.
On Entry:
install-flag 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.
Comments:

The installed closedown procedure is executed whether the application finishes normally (with a STOP RUN) or abnormally (for example, with a keyboard interrupt or run-time system 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.

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 unless your program is a user-written file handler, in which case it must be 200.

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. 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 to nonzero.


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 
                         returning    status-code
Parameters:
command-line pic x(n).
command-line-len pic x(4) comp-5.
run-unit-id pic x(8) comp-5. Must be level 01.
stack-size pic x(4) comp-5.
flags pic x(4) comp-5.
status-code See Key.
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

This parameter is ignored .

flags Reserved for future use. Must be zero.
On Exit:
run-unit-id The unique handle identifying the new run-unit.
status-code Status of operation:
0 Success
157 Out of memory
181 Invalid parameter
200 Internal logic error
Comments:

You must set either the ALIGN"4" or ALIGN"8" Compiler directive if you use this routine.

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:

See Also:

The chapter Concurrency Support


CBL_FREE_MEM

Frees dynamically allocated memory.

Syntax:
call "CBL_FREE_MEM" using by value mem-pointer 
                    returning      status-code
Parameters:
mem-pointer usage pointer.
status-code See Key.
On Entry:
mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_MEM.
On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_MEM routine.

See Also:

CBL_ALLOC_MEM


CBL_GET_PROGRAM_INFO

Returns information for a named program, or a program in the current call stack.

Syntax:
call "CBL_GET_PROGRAM_INFO" using by value     function
                                       by reference param-block
                                       by reference name-buf
                                       by reference name-len
                                       returning    status-code
Parameters:
function pic x(4) comp-5.
param-block Group item defined as:
size pic x(4) comp-5.
flags pic x(4) comp-5.
handle

pointer.

prog-handle pointer.
attributes pic x(4) comp-5.
name-buf pic x(n).
name-len pic x(4) comp-5.
status-code See Key.
On Entry:
function Specifies the function to be performed:
0

Return status information for the current program. If you want to retrieve further information on this program, then bit 0 of the flags parameter must be set to indicate that this function should return handle, which will be used as an input to function 2-7. The initial program associated with handle is the current program.

1

Return status information for named program. If you want to retrieve further information on this program, then bit 0 of the flags parameter must be set to indicate that this function should return handle, which will be used as an input to function 2-7. The initial program associated with handle is the named program.

2

Return status information for the program that called the program currently associated with handle. This function requires that handle has been set up using functions 0 or 1. The program associated with handle is updated to the calling program.

3

Close a previously created handle. This function requires a valid handle to have been created using function 0 or 1. A call with this function must be made when handle is finished with.

4

Find the first entry point of the program currently associated with handle. handle must have been set up using function 0 or 1. Once a call with this function has been made, you can repeatedly use this routine with function set to 5 to retrieve all remaining entry points in the program. Once all of the required entry points have been returned, you can use this routine with function set to 6 to terminate the entry-point search.

5

Find the next entry point of the program currently associated with handle. This function requires a valid handle to have been set up using function 0 or 1, and for function 4 to have been used to initiate the find first/next entry-point sequence.

6

Terminate the entry-point search. It requires a valid handle to have been set up using function 0 or 1, and for function 4 to have been called to initiate the find first/next entry-point sequence.

7

Return the full program-name of the program currently associated with handle. This function requires a valid handle to have been set up using function 0 or 1.

size The size of the parameter block including this field. This should be set to a value of 20.
flags A 32-bit word indicating what information is to be returned:
Bit Meaning
0

Determines whether functions 0 and 1 return handle. For all other functions, this bit is ignored.

0 Do not return handle (if function is set to 0 or 1)
1 Return handle (if function is set to 0 or 1)
1

Determines whether functions 0 and 2 should return the program's basename in name-buf as part of the program status information.

0 Do not return basename of program (if function is set to 0 or 2)
1 Return basename of program in name-buf (if function is set to 0 or 2)
2

Determines whether basenames and full program names that are input or returned in name-buf should be in null-terminated or space- terminated format.

0 All input and output names are space-terminated
1 All input and output names are null-terminated.
3

Determines whether functions 0, 1and 2 should return the program's attributes in prog-attr .

0 Do not return program attributes in prog-attr.
1 Return program attributes in prog-attr.
4-31

Reserved for future use - must be set to 0.

handle A handle created by function 0 or 1.
name-buf If function is set to 1, the basename of the program for which information is required.
name-len The length of name-buf. If this is too small for the information being returned, the routine fails.
On Exit:
handle The handle returned by functions 0 and 1, which must be used for all other functions.
prog-handle Unique identifier for the program currently associated with handle.
prog-attr Attributes of the program currently associated with handle:
Bit Value Meaning
0 0
1

Program compiled using the AMODE(24) Compiler directive (this Compiler directive is not currently available in NetExpress).
1 0
1

Program compiled using the AMODE(31) Compiler directive (this Compiler directive is not currently available in NetExpress).
2 0
1

Program compiled using the CHARSET(ASCII) Compiler directive. Program compiled using the CHARSET(EBCDIC) Compiler directive.
3 0
1

Program compiled using the ANS85 Compiler directive.
4 0
1

Program compiled using the VSC2 Compiler directive (this Compiler directive is not currently available in NetExpress).
5 0
1

Program compiled using the OSVS Compiler directive (this Compiler directive is not currently available in NetExpress).
6-27 0
1
Reserved for future use - must be set to 0
28 0
1

Program is a member of a subsystem.
29 0
1
Program exists in current call-stack.
Program does not exist in current call-stack.
30 0
1

Program is canceled.

31 0
1

Program is COBOL.

Program is non-COBOL.

name-buf Any basename, entry-point name or full program-name that was requested.
name-len Length of the name returned in name-buf, or required buffer length if the status-code is 1013.
status-code Status of operation:
0 Success.
500 End of information (returned if function is set to 2 when there is no caller of the currently associated program, or if function is set to 5 when no more entry points exist).
1001 Invalid handle input.
1009 Invalid parameter.
1013 Buffer too small for information to be returned.

CBL_GET_OS_INFO

Returns information about the current operating system and environment.

Syntax:
call "CBL_GET_OS_INFO" using     parameter-block 
                       returning status-code
Parameters:
parameter-block
parameter-size
p-os-type
p-os-version
p-DBCS-support
p-char-coding
p-country-id
p-code-page
p-process-type
p-rts-capabilities
p-reserved
Group item defined as:
pic x(2) comp-x value 23
pic x comp-x.
pic x(4) comp-x
pic x comp-x.
pic x comp-x.
pic x(2) comp-x.
pic x(2) comp-x
pic x comp-x.
pic x(4) comp-x.
pic x(5).
status-code See Key.
On Exit:
p-os-type COBOL system and operating system:
128 COBOL system on UNIX
129 COBOL system on XENIX
p-os-version Version number of the operating system.
p-DBCS-support DBCS support flag:
bit 0 0 If DBCS validation unsupported 1
1 If DBCS validation supported
bit 1 0 If PIC N data-type unsupported 1
1 If PIC N data-type supported
p-char-coding Character encoding:
0 ASCII
1 Shift-JIS
2 EUC
3 BIG-5 (Traditional Chinese)
4 5550 (Traditional Chinese)
5 GB (Simplified Chinese)
6 KS-CODE (Korean)
7 PC-CODE (Korean)
p-country-id Reserved; set to zero.
p-code-page Reserved; set to zero.
p-process-type Reserved; undefined.
p-rts-capabilities Special features of the COBOL run-time system:
bit 0 Multi-threading.
bit 1 Mainframe offloading capabilities, namely mainframe pointer emulation.
bit 2 64-bit capability; the run-time system is running on a 64-bit operating system.
bits 3-31 Reserved.
p-reserved Reserved. Set to nulls.

CBL_GET_SHMEM_PTR

Reads a named value.

Syntax:
call "CBL_GET_SHMEM_PTR" using     node-value 
                                   node-name 
                         returning status-code
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".
status-code See Key.
On Entry:
node-name The length of name.
name The value assigned to node-name.
On Exit:
node-value The value of the named value.
Comments:

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.

See Also:

CBL_PUT_SHMEM_PTR
The chapter Concurrency Support


CBL_IMP

Does a logical IMPLIES between the bits of two data items.

Syntax:
call "CBL_IMP" using     source 
                         target 
                by value length
Parameters:
source Any data item.
target Any data item.
length Numeric literal or pic x(4) comp-5.
On Entry:
source One of the data items to IMPLIES.
target The other data item to IMPLIES.
length The number of bytes of source and target to IMPLIES. Positions in target beyond this length are unchanged.
On Exit:
target The result.
Comments:

The routine starts at the left-hand end of source and target and IMPLIES the bits together, storing the result in target. The truth table for this is:

source target Result
0 0 1
0 1 1
1 0 0
1 1 1
See Also:

The chapter Advanced Language Features.


CBL_NOT

Does a logical NOT on the bits of a data item.

Syntax:
call "CBL_NOT" using     target 
                by value length
Parameters:
target Any data item.
length Numeric literal or pic x(4) comp-5.
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.
Comments:

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 Also:

The chapter Advanced Language Features.


CBL_OPEN_VFILE

Opens a heap.

Syntax:
call "CBL_OPEN_VFILE" using     heap-id
                                status-word 
                      returning status-code
Parameters:
heap-id pic x(2) comp-5.
status-word pic x(2).
status-code See Key.
On Entry:

None.

On Exit:
heap-id Contains the assigned heap handle. A heap handle of zero means the open failed.
status-word The status word for the heap, set to zero on the open. When the first status byte contains the character 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, WRITE or CLOSE that encounters allocation or 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.

See Also:

Virtual Heap Routines


CBL_OR

Does a logical OR between the bits of two data items.

Syntax:
call "CBL_OR" using     source 
                        target 
               by value length
Parameters:
source Any data item.
target Any data item.
length Numeric literal or pic x(4) comp-5
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.
Comments:

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 Also:

The chapter Advanced Language Features.


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 
                         returning      status-code
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".
status-code See Key.
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

Comments:

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.

See Also:

CBL_GET_SHMEM_PTR
The chapter Concurrency Support


CBL_READ_VFILE

Reads bytes from a heap.

Syntax:
call "CBL_READ_VFILE" using by value heap-id 
                                     heap-ref 
                                     heap-length 
                      by reference   heap-buffer 
                      returning      status-code
Parameters:
heap-id pic x(2) comp-5.
heap-ref pic x(4) comp-5.
heap-length pic x(4) comp-5.
heap-buffer pic x(n).
status-code See Key.
On Entry:
heap-id This contains the heap handle assigned when the heap was opened.
heap-ref Offset in the heap at which to start reading.
heap-length Number of bytes to read.
On Exit:
heap-buffer Buffer into which bytes are read. It is your program's responsibility to ensure that the buffer is large enough to hold the number of bytes being read.
Comments:

Trying to read data from an area of the heap which has not yet been written results in indeterminate data being returned to the buffer.

See Also:

Virtual Heap Routines


CBL_SCR_SET_PC_ATTRIBUTES

Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.

Syntax:
call "CBL_SCR_SET_PC_ATTRIBUTES" returning status-code
Parameters:
status-code See Key.
On Entry:

None

On Exit:
status-code The return status:
0 Successful.
1 Successful, but one or more colors not exact.
2 Failed.
Comments:

Using this routine is equivalent to setting the entire IBM-PC attribute table using the generic attribute routines. It is provided to enable you to apply generic attributes to existing programs, making their attribute handling portable. However, this routine is inefficient because it defines every possible attribute. For new applications use the generic attribute routines and define only the attributes you need.

This routine is provided to help you make existing applications portable to other environments. It should not be used in new applications where alternative mechanisms are provided.

See Also:

The chapter Generic Display Attributes in your Programmer's Guide to Creating User Interfaces.


CBL_SUBSYSTEM

Declares or deallocates subsystems.

Syntax:
call "CBL_SUBSYSTEM" using      function-code
                                parameter 
                     returning  status-code
Parameters:
function-code pic x comp-x. Contains one of the following values:
0 Declare subsystem
1 Cancel subsystem
2 Remove from subsystem
With function-code = 0:
parameter Group item defined as:
    ss-handle     pic x(2) comp-x.
    ss-name-len     pic x(2) comp-x.
    ss-name     pic x(n)
With function-code = 1:
parameter pic x(2) comp-x.
With function-code = 2:
parameter pic x(2) comp-x value 0
status-code See Key.
On Entry:
function-code The subfunction value.
With function-code = 0:
ss-name-len The length of subsystem program-name field.
ss-name The subsystem program-name (space-terminated). This must be a COBOL .int file or .gnt file.
With function-code = 1:
ss-handle The subsystem handle returned by a function 0 call.
With function-code = 2:
dummy-param Value 0.
On Exit:

With function-code = 0:

ss-handle The subsystem handle.
Comments:

A subsystem is defined to be a specified program in an application, plus any subprograms subsequently called by programs already in the subsystem that do not already belong to any other subsystems.

With function-code = 0:

This function declares a subsystem. The routine returns a subsystem handle. If the program is not already loaded the function loads it. If an error occurs in finding or loading the program a subsystem handle of zero is returned.

A program belonging to a subsystem is only deallocated (that is, deleted from memory), when either it is canceled by the CANCEL verb, or the program cancels the entire subsystem using function-code = 1, or the application executes a STOP RUN or CHAIN statement. The main program of a subsystem should not be canceled with the CANCEL statement unless all other programs in the subsystem have already been canceled.

With function-code = 1:

This function cancels all programs in the specified subsystem. If any program in the subsystem is still active, that program is released from the subsystem and is not canceled.

With function-code = 2:

This function removes the program that called it from any subsystem the program is in. To ensure a program is never included in any subsystem, call this function at the start of each entry in to the program.


CBL_TOLOWER

Converts a string of letters to lower case.

Syntax:
call "CBL_TOLOWER" using     string 
                   by value  length 
                   returning status-code
Parameters:
string pic x(n).
length pic x(4) comp-5.
status-code See Key.
On Entry:
string The string to convert.
length The number of bytes of string to change; positions beyond this are unchanged.
On Exit:
string The converted string.
Comments:

The routine starts at the left-hand end of string and converts letters to lower case (also called folding to lower case).


CBL_TOUPPER

Converts a string of letters to upper case.

Syntax:
call "CBL_TOUPPER" using     string 
                   by value  length 
                   returning status-code
Parameters:
string pic x(n).
length pic x(4) comp-5.
status-code SeeKey.
On Entry:
string The string to convert.
length The number of bytes of string to change; positions beyond this are unchanged.
On Exit:
string The converted string.
Comments:

The routine starts at the left-hand end of string and converts letters to upper case (also called folding to upper case).


CBL_WRITE_VFILE

Writes bytes to a heap.

Syntax:
call "CBL_WRITE_VFILE" using by value heap-id
                                      heap-ref 
                                      heap-length 
                       by reference   heap-buffer 
                       returning      status-code
Parameters:
heap-id pic x(2) comp-5.
heap-ref pic x(4) comp-5.
heap-length pic x(4) comp-5.
heap-buffer pic x(n).
status-code See Key.
On Entry:
heap-id This contains the heap handle assigned when the heap was opened.
heap-ref Offset in the heap at which to start writing.
heap-length Number of bytes to write.
heap-buffer Buffer from which bytes are written. It is your program's responsibility to ensure that the buffer is large enough to hold the number of bytes being written.
On Exit:

None

See Also:

Virtual Heap Routines


CBL_XOR

Does a logical XOR between the bits of two data items.

Syntax:
call "CBL_XOR" using     source 
                         target 
                by value length
Parameters:
source Any data item.
target Any data item.
length Numeric literal or pic x(4) comp-5.
On Entry:
source One of the data items to exclusive-OR.
target The other data item to exclusive-OR.
length The number of bytes of source and target to exclusive-OR. Positions in target beyond this are unchanged.
On Exit:
target The result.
Comments:

The routine starts at the left-hand end of source and target and exclusive-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 0
See Also:

The chapter Advanced Language Features.


CBL_YIELD_RUN_UNIT

Yields the remainder of a run-unit's time-slice.

Syntax:
call "CBL_YIELD_RUN_UNIT"
Parameters:

None

Comments:

The remainder of the run-unit's time-slice is yielded to unspecified run-units.


X"F4" - Pack Byte

Packs the least significant bits in eight bytes into a single byte.

Syntax:
call x"F4" using byte 
                 array
Parameters:
byte pic x comp-x
array pic x comp-x occurs 8
On Entry:
array The bits to be packed.
On Exit:
byte The packed byte.
Comments:

The routine takes the eight bytes 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).

  00000001 00000001 00000000 00000000 00000001 00000000 00000001 00000001
         |        |        |        |+-------+        |        |        |
         |        |        +-------+||+---------------+        |        |
         |        +---------------+||||+-----------------------+        |
         +-----------------------+||||||+-------------------------------+
                                 VVVVVVVV
                                 11001011 

X"F5" - Unpack Byte

Unpacks the bits in a byte into eight bytes.

Syntax:
call x"F5" using byte 
                 array
Parameters:
byte pic x comp-x
array pic x comp-x occurs 8
On Entry:
byte The byte to be unpacked
On Exit:
array The unpacked bits
Comments:

The routine takes the eight bits of byte and moves them to the corresponding occurrence within array:

                                10110011
        +-----------------------+||||||+-------------------------------+
        |        +---------------+||||+-----------------------+        |
        |        |        +-------+||+---------------+        |        |
        |        |        |        |+-------+        |        |        |
        V        V        V        V        V        V        V        V
 00000001 00000000 00000001 00000001 00000000 00000000 00000001 00000001 


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousIntegrated Preprocessor Interface