Chapter 17: Library Routines

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

For other library routines, see the following references:

Using the Library Routine Type Definitions and Call Prototypes

Server Express 2.0 contains two copyfiles; one contains data items used by the library routines specified as type definitions, or TYPEDEFs, while the other contains call prototypes for the library routines. These can be used in your COBOL programs to enable the Compiler to validate all calls to these routines.

The file $COBDIR/cpylib/cbltypes.cpy contains all types required by the system library routines. In order to avoid conflict with data-names contained within your program, all TYPEDEF names include the prefix CBLT-. Where the types are not elementary items, any subordinate elements will have the prefix CBLTE-.

The file $COBDIR/cpylib/cblproto.cpy contains all prototypes of the system library routines. In some cases, these prototypes have parameters declared as ANY; this is usually when variable length data is required as input.

In the descriptions of the parameters for the library routines, references to the system-defined USAGE types have the prefix CBLT-, while subordinate items have the prefix CBLTE-. If you declare variables using the new USAGE types, you do not declare the subordinate items; you can, however, use the subordinate items anywhere that variable usage is allowed. If you declare more than one variable of the same type which contains subordinate items, then you must use qualification in order to tell the compiler which variable you intend to reference, as each group variable will have subordinate items of the same name. If, for whatever reason, you decide not to use the new USAGE types defined in cbltypes.cpy, you must declare a group item and all the listed subordinate variables explicitly; in this case you can give the subordinate variables any name you want.

In your programs, you need only specify the copyfile cblproto.cpy; it must be specified before the Identification Division of your program. You do not need to specify the copyfile cbltypes.cpy, as this is included in cblproto.cpy.

For information on the use of call prototypes and TYPEDEFs, see the section Call Prototypes in the chapter Calling Programs. For an extended example of using call prototypes, see the section Call Prototypes in the chapter Examples in your Language Reference - Additional Topics. For information on the CALL statement syntax, and the ANY and TYPEDEF keywords, see your Language Reference.

Note: The call prototypes only apply to call-by-name routines (those of the form CBL_name_name), not to the call-by-number routines (those of the form X"NN").

Below is an example of the use of these prototypes in a program. The program displays the size of the file mymain.cbl:

 copy "cblproto.cpy".
 
 program-id. MYMAIN.
 working-storage section.
 01  .
     05  file-details    cblt-fileexist-buf.
 procedure division.
     call 'CBL_CHECK_FILE_EXIST' using 'mymain.cbl '
                                       file-details
     if  return-code not = 0
       display "File mymain.cbl does not exist (or error)"
     else
       display "File mymain.cbl size is " cblt-fe-filesize
       of file-details
     end-if
 end program MYMAIN.

Routines by Category

Server Express provides routines in the following categories:

• Application subsystems
  
  
• Byte packing
  
  
• Concurrency support
  
  
• Exit and error procedures
  
  
• Logical operations
  
  
• National Language Support
  
  
• Operating system information
  
  
• Portability
  
  
• Program canceling
  
  
• Program information
  
  
• Text
  
  
• Virtual heaps

Application Subsystem Routine

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.

Byte-packing Routines

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

Concurrency - Run-unit and Memory Routines

Memory allocation:

Run-unit Handling:

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

Exit and Error Procedure Routines

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.

Logic Routines

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.

National Language Support Routines

Operating System Information Routine

Portability Routine

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.

Program Canceling Routine

Program Information Routine

Text Routines

Virtual Heap Routines

A heap is a byte-stream file which is buffered in available memory.

The status word specified when the heap is created is associated with each heap. It is written to when an operation on the heap fails. Each heap is thereby attached to a particular program, namely the program which contains the heap's status word, and is automatically deallocated (unless it has already been explicitly deallocated by a call to CBL_CLOSE_VFILE) when that program is canceled.

A heap is identified by a heap identifier 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.

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

List of Routines

CBL_ABORT_RUN_UNIT

Abort the current run-unit irrespective of the state of existing threads.

Syntax:

call "CBL_ABORT_RUN_UNIT" using by value ret-value

Parameters:

On Entry:

Comments:

In a single-threaded application or run-time system this call is equivalent to the following syntax:

stop run returning ret-value

In a multi-threaded application STOP RUN waits for all existing threads to exit before terminating the run-unit. CBL_ABORT_RUN_UNIT, however, does not wait for any existing thread to exit. It cancels all running threads and then terminates the run-unit, returning control to the operating system.

Note:

We recommend that you use this call only when a critical problem has been detected in the application. Calling this routine in a multi-threaded application could cause severe problems, as threads might be terminated in the middle of critical file operations.

CBL_ALLOC_DYN_MEM

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

Syntax:

call "CBL_ALLOC_DYN_MEM" using     mem-pointer 
                         by value  mem-size 
                                   flags 
                         returning status-code

Parameters:

On Entry:

On Exit:

Comments:

The memory allocated is not initialized to any value.

The maximum size of memory is restricted only by your 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 canceled (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.

See Also:

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:

On Entry:

On Exit:

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.

If the memory has been allocated by a thread, it is freed when the calling thread terminates.

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.

Bit 1 and bit 2 or bit 3 are mutually exclusive. This is checked and error 181 returned otherwise. If there is no calling program (directly or indirectly in a mixed-language environment) bit 2 is ignored.

If bit 2 is not set all standard memory allocated by CBL_ALLOC_MEM is freed when the program that allocated it is canceled (logically or physically), if there is a COBOL program that is directly or indirectly the caller.

See Also:

CBL_FREE_MEM

CBL_ALLOC_SHMEM

Dynamically allocates shared memory.

Syntax:

call "CBL_ALLOC_SHMEM" using     mem-pointer 
                     by value  mem-size 
                     returning status-code

Parameters:

On Entry:

On Exit:

Comments:

The memory allocated is not initialized to any value.

The size for shared memory allocated using this routine is limited to a maximum of around of 64000 bytes.

See Also:

CBL_FREE_SHMEM

CBL_AND

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

Syntax:

call "CBL_AND" using    source 
                        target 
               by value length

Parameters:

On Entry:

On Exit:

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:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in the chapter Advanced Language Features.

CBL_CANCEL_PROC

Provides control over program cancels.

Syntax:

call "CBL_CANCEL_PROC" using by value function 
                             by reference parameter-block 
                             by value user-data-length 
                             returning status-code

Parameters:

On Entry:

On Exit:

Comments:

This routine provides a mechanism by which a COBOL program can receive notification of an impending cancel of either itself, or another COBOL program.

Such notification enables a COBOL program to finalize its use of, and deallocate, any resources it has allocated during its existence that are not already handled automatically by the COBOL run-time system or the operating system. These resources are normally those provided by the operating system or run-time system, but could also be some resource provided by another module in the application itself.

The COBOL run-time system performs notifications by processing a list (the cancel list) which it has associated with the program being canceled. Therefore, to enable a notification, the COBOL run-time system must be instructed to register a cancel routine for the program, by creating an entry in the cancel list. Managing entries in cancel lists is the purpose of CBL_CANCEL_PROC.

To create an entry in the cancel list, CBL_CANCEL_PROC needs to know three things:

• The program which, when canceled, triggers the notification. This program is identified by a program handle (set on entry by the parameter handle).

• The cancel routine to call. The cancel routine is the entry point called when the program is canceled.

• A cancel priority. This is the priority for this notification

You provide this information to the run-time system when you issue CBL_CANCEL_PROC with the parameter function set to 0 or 1. The run-time system then creates an entry in the cancel list associated with the program handle. The entry specifies that the cancel routine should be called when notification is due. The position in the list is determined by the value of cancel priority.

You can reference the entry in the cancel list using the value returned in the handle parameter by the call that registered the cancel routine. This enables you to modify the registration at a later time, using this routine with function set to 2, 3 or 4; for example, you can change the priority of the registration, or remove it from the list.

Obtaining a program handle

A program handle is a unique value which the COBOL run-time system associates with a cancelable entity. Therefore, all entry points in a COBOL program share the same program handle, as canceling any entry point in a COBOL program cancels all entry points in that program.

There are two basic methods of using the CBL_CANCEL_PROC routine, and the amount of work a program needs to do in order to obtain the correct program handle depends on which method is used:

• Local registration.

  When a program wishes to receive a notification that it is to be canceled, it can make a local registration - usually in its "first time in" code. For this method of registration, the program need only pass NULL as a program handle. The CBL_CANCEL_PROC routine then automatically locates the correct program handle and creates an entry in the correct list.

  Usually, the cancel routine specified in a local registration is an entry point in the registering program (though it doesn't have to be).

  A program which allocates some resource directly from the operating system and which needs the opportunity to deallocate it before being canceled would use local registration.

• Service registration

  This is a slightly more complicated type of registration, and is used when a service program (that is, a program which manages a resource on behalf of other COBOL programs) needs to receive notification that one of its clients is being canceled. For this method of registration, the service program should get the handle of the client program using a call to the CBL_GET_PROGRAM_INFO routine with its function parameter set to 2.

  Usually, the cancel routine specified in a service registration is an entry point in the service program (though it doesn't have to be).

  A program that opens and manages files on behalf of several other COBOL programs would use service registration so that when one of its client programs is canceled, all files opened on behalf of that program can be closed automatically.

  Note that you could handle this situation by using local registration in each program that calls the service program; the cancel routine simply closes the files that have been opened on the behalf of the client program. However, such an approach would be prone to error, does not conform to COBOL semantics, and is very untidy.

  When you use the CBL_CANCEL_PROC routine in a service program, it is important that when an applicable resource is relinquished by the client program, the notification for it is removed from the cancel list of that client program. You can do this by setting function to 3 or 4. To make this efficient, the service program could store the program handle returned when function is set to 0 or 1 within the resource structure, so that it can be easily located to be passed back as the registration handle when function is set to 3 or 4.

  If the service program fails to de-register a registration using function 3 or 4, a spurious notification will occur when the client program is eventually canceled, leading to unpredictable results.

User data

In addition to the three mandatory pieces of information required by CBL_CANCEL_PROC when function is set to 0 or 1 (that is, handle, cancel-routine and install-priority) , it can accept an optional fourth, user-data, which is a pointer to an address of an area containing user data.

If a program registering a cancel routine supplies a user-data parameter, the parameter is passed to the cancel routine when the program is canceled. You can specify a different user-data parameter for each registration, or use the same one for multiple registrations. In addition, you can specify that the actual user data area is copied (and the copy passed to the cancel routine as a parameter), by specifying a non-zero user-data-length parameter.

If the user-data-length parameter is set to non-zero, the specified number of bytes are copied from the address in the user-data parameter, and that copy is retained in the list entry. When the program associated with the relevant program handle is canceled, the cancel routine receives the copy of the user data area as a parameter. The copy is deleted automatically by the COBOL run-time system after the cancel routine has returned. Passing the user data to the cancel routine is more convenient than passing a pointer to it but should typically be used only for small user-data areas. A typical use of this facility is in service registrations: instead of managing a list to associate a client program with a cancel routine in the service program, the service program can receive the handle of the client program directly as a parameter to the cancel routine provided it passed the handle to the CBL_CANCEL_PROC registration process as a user-data parameter.

Note that the CBL_CANCEL_PROC routine knows nothing about the structure of the user data area passed to it, and only copies a flat memory block. For instance, items of USAGE POINTER embedded within the block will be copied, but the memory to which they point will not. If there are such items in the user data area it is probably more appropriate for your program to allocate and copy the entire data structure itself, and pass the copy using a user-data-length of zero.

If the user-data-length parameter is set to zero (and therefore the original user-data pointer parameter specified to the registration process is passed to the cancel-routine), it is up to the cancel routine to delete or deallocate all data structures within the block.

You must take special care when using this method to pass a user-data parameter, especially if the same user data area is registered to more than one registration handle (the registration handle is returned on exit in the handle parameter). Specifically, you must take care to ensure that any allocated resources are deallocated exactly once, and that allocated resources remain valid until after the last registration handle with which they are associated has been destroyed. This can usually be accomplished by having a usage count field somewhere in the user data area, which is incremented each time the user-data parameter is registered to a registration handle and decremented each time a cancel routine is called with it as a parameter.

Example

This skeleton cancel routine is an example of an entry point that could be passed in the cblte-cppb-handle parameter to CBL_CANCEL_PROC for registration. The run-time system calls this routine when the program with which it is associated is canceled.

 working-storage section.
 01 cancel-status   pic x(4) comp-5.

 linkage-section.
 01 cancel-reason   cblt-x4-comp5.
 01 cancel-flags    cblt-x4-comp5.
 01 program-id      cblt-pointer.
 01 user-data       cblt-pointer.

 procedure division.
 entry "user-cancel-routine" using by value cancel-reason
                             by value       cancel-flags
                             by value       program-id
                             by value       user-data.
 cancel-routine section.
 cancel-routine-para.
*> This is where the code which handles the CANCEL-notification goes.
*> The user-data field specified in the registration is passed to us here,
*> along with the program-id of the program being canceled.
*> Iff this routine is handling registrations which specified a
*> user-data-field length of zero, then the memory pointed to by user-data
*> may also need to be freed before returning.

 exit program returning cancel-status.

The cancel-reason parameter describes the reason for the cancel. Possible values are:

All other bits are reserved and should be ignored.

The cancel-flags parameter is currently reserved and should be ignored.

See Also:

CBL_GET_PROGRAM_INFO

CBL_CLOSE_VFILE

Closes a heap.

Syntax:

call "CBL_CLOSE_VFILE" using by value  heap-id 
                             returning status-code

Parameters:

On Entry:

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:

On Entry:

On Exit:

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:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in 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:

On Entry:

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       cblt-x1-compx. 
 01 install-address    cblt-ppointer. 
 01 status-code        cblt-rtncode 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 
                         returning    status-code

Parameters:

On Entry:

On Exit:

Comments:

The run-unit that makes the call is known as the parent; 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.
  
  
• Data can be shared between run-units by allocating it as shared memory using CBL_ALLOC_MEM or CBL_ALLOC_SHMEM, and then passing the address of this memory between the run-units using CBL_PUT_SHMEM_PTR and CBL_GET_SHMEM_PTR.
  
  
• COBOL and RTS switches, environment variables, and open libraries are inherited by the child.
  
  
• Open files and heaps are not inherited by the child.
  
  
• Screen I/O from one run-unit can interfere with that from another run-unit causing unexpected results. This is particularly a problem on UNIX. Avoid screen I/O operations from more than one concurrent run-unit.
  

On platforms that enable you to create executable files that have either a 32-bit address space, or a 64-bit address space, the run-units comprising a coru must use the appropriate address space.

If a 32-bit run-unit creates a 64-bit run-unit, no attributes are shared between the run-units; this is also true if a 64-bit run-unit creates a 32-bit run-unit. In either case, the mismatching child run-unit is treated as an initial run-unit of a new coru.

See Also:

The chapter Concurrency Support

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:

On Entry:

On Exit:

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, cblte-ep-install-addr must be the address of an entry point. You can obtain this address using the statement:

     set cblte-ep-install-addr 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 cblte-ep-install-priority if it is found. The procedure is identified by its install-addrs. If the procedure cannot be found, RETURN-CODE is set nonzero.

CBL_FREE_DYN_MEM

Frees memory dynamically allocated by the CBL_ALLOC_DYN_MEM routine.

Syntax:

call "CBL_FREE_DYN_MEM" using by value  mem-pointer 
                              returning status-code

Parameters:

On Entry:

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_DYN_MEM routine.

See Also:

CBL_ALLOC_DYN_MEM

CBL_FREE_MEM

Frees dynamically allocated memory.

Syntax:

call "CBL_FREE_MEM" using by value  mem-pointer 
                          returning status-code

Parameters:

On Entry:

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_MEM routine.

See Also:

CBL_ALLOC_MEM

CBL_FREE_SHMEM

Frees dynamically allocated shared memory.

Syntax:

call "CBL_FREE_SHMEM" using by value  mem-pointer 
                          returning status-code

Parameters:

On Entry:

On Exit:

None

Comments:

This routine releases memory allocated by the CBL_ALLOC_SHMEM routine.

See Also:

CBL_ALLOC_SHMEM

CBL_GET_EXIT_INFO

Enables an application to determine under what circumstances an exit procedure has been invoked.

Syntax:

call "CBL_GET_EXIT_INFO" using by reference param-block
                               returning    status-code

Parameters:

On Entry:

On Exit:

Comments:

This routine must only be called from within an exit procedure that has been installed using CBL_EXIT_PROC.

A typical use of this routine would be in database applications which need to be able to determine under what circumstances an exit procedure has been invoked. Database applications would typically need to be able to determine whether the exit procedure had been invoked due to a normal or abnormal run-time system termination. This routine would enable them to decide whether to commit or rollback.

See Also:

CBL_EXIT_PROC

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:

On Entry:

On Exit:

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:

On Exit:

CBL_GET_SHMEM_PTR

Reads a named value.

Syntax:

call "CBL_GET_SHMEM_PTR" using     node-value               
                                   node-name 
                         returning status-code

Parameters:

On Entry:

On Exit:

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:

On Entry:

On Exit:

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:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in the chapter Advanced Language Features.

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:

On Entry:

On Exit:

Comments:

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.

See Also:

The chapter Internationalization Support.

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:

On Entry:

On Exit:

See Also:

The chapter Internationalization Support.

CBL_NLS_INFO

Gets/sets national language information

Syntax:

call "CBL_NLS_INFO" using     function-code
                              info-category
                              info-buffer
                    returning status-code

Parameters:

On Entry:

With function-code = 1:

With function-code = 2:

On Exit:

With function-code = 1:

With function-code = 2:

Comments:

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. With function-code = 1 (get information) you can obtain correct information about the program's locale only if the program was compiled with the NLS Compiler directive.

See Also:

The chapter Internationalization Support.

CBL_NLS_OPEN_MSG_FILE

Open a National Language Support (NLS) message catalog.

Syntax:

call "CBL_NLS_OPEN_MSG_FILE" using     msg-filename
                                       msg-filename-ln
                                       msg-file-handle
                             returning status-code

Parameters:

On Entry:

On Exit:

Comments:

This routine opens an NLS message catalog, returning an identifying handle that you can use with the CBL_NLS_READ_MSG and CBL_NLS_CLOSE_MSG_FILE routines.

Message catalogs are searched for in the directories specified in the $NLSPATH environment variable. If $NLSPATH contains the %L element, the user can choose the language in which they want messages by setting the $LC_MESSAGES or $LANG environment variables at run-time. You create message catalogs using the gencat command. Message catalogs are explained in more detail in the section Writing NLS Message Files in the chapter Internationalisation Support.

See Also:

The chapter Internationalization Support.

CBL_NLS_READ_MSG

Read a message from a National Language Support (NLS) message catalog.

Syntax:

call "CBL_NLS_READ_MSG" using     msg-file-handle
                                  full-msg-number
                                  msg-ins-struct
                                  msg-buffer
                        returning status-code

Parameters:

On Entry:

On Exit:

Comments:

In each message catalog, messages can be divided into sets. Each message in a set has an identifying message number. Message catalogs are explained in more detail in the section Writing NLS Message Files in the chapter Internationalization Support.

This routine also enables you to insert portions of text in a message fetched from the message catalog, replacing any %s formatting sequences in the original message. There must not be more %s formatting sequences than cblte-nmis-ins-count.

The inserted portions of text can be inserted in the order appropriate to the rules of the grammer for the national language. This is achieved using the %n$s formatting syntax, where n is the nth cblte-nmis-ins-pointer. The value of n must not exceed cblte-nmis-ins-count.

See Also:

The chapter Internationalization Support.

CBL_NOT

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

Syntax:

call "CBL_NOT" using    target 
               by value length

Parameters:

On Entry:

On Exit:

Comments:

The routine starts at the left-hand end of target and inverts bits. The truth table for this is:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in 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:

On Entry:

None.

On Exit:

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:

On Entry:

On Exit:

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:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in 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:

On Entry:

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:

On Entry:

On Exit:

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:

On Entry:

None

On Exit:

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.

CBL_SUBSYSTEM

Declares or deallocates subsystems.

Syntax:

call "CBL_SUBSYSTEM" using     function-code
                               parameter 
                     returning status-code

Parameters:

On Entry:

On Exit:

With function-code = 0:

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:

On Entry:

On Exit:

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:

On Entry:

On Exit:

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:

On Entry:

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:

On Entry:

On Exit:

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:

See Also:

The section Manipulating Bits Using Logic (Boolean) Operators in 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.

"F4" - Pack Byte

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

Syntax:

call x"F4" using byte 
                 array

Parameters:

On Entry:

On Exit:

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 

"F5" - Unpack Byte

Unpacks the bits in a byte into eight bytes.

Syntax:

call x"F5" using byte 
                 array

Parameters:

On Entry:

On Exit:

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 © 2003 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.