PreviousIntegrated Preprocessor Interface

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.

17.1 Using the Library Routine TYPEDEFs and CALL Prototypes

Server Express 2.0 contains two copyfiles; one contains data items used by the library routines specified as 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 TYPEDEF, 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 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.

17.2 Routines by Category

Server Express provides routines in the following categories:

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

17.2.2 Byte-packing Routines

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

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

17.2.3 Concurrency - Run-unit and Memory Routines

Memory allocation:
CBL_ALLOC_DYN_MEM Allocate dynamic memory
CBL_ALLOC_MEM Allocate dynamic memory
CBL_FREE_DYN_MEM Free dynamically allocated 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 concurrency support, see the chapter Concurrency Support.

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

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

17.2.6 National Language Support Routines

CBL_NLS_CLOSE_MSG_FILE Close message file
CBL_NLS_COMPARE Compare two strings
CBL_NLS_INFO Get or set national language information
CBL_NLS_OPEN_MSG_FILE Open message file
CBL_NLS_READ_MSG Read message from message file

17.2.7 Operating System Information Routine

CBL_GET_OS_INFO Get operating system information

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

17.2.9 Program Information Routine

CBL_GET_PROGRAM_INFO Get operating system information

17.2.10 Text Routines

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

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

17.3 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; it is defined in cbltypes.cpy as cblt-rtn-code.

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.

17.4 List of Routines


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:
mem-pointer cblt-pointer.
mem-size cblt-os-size.
flags cblt-os-flags.
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 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:
mem-pointer cblt-pointer.
mem-size cblt-os-size.
flags cblt-os-flags.
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 Allocate this memory as shared.
1 Reserved. Must be set to 0.
2 Allocate this memory independently from any calling program. If bit 3 is set it will be freed automatically when the calling thread ends. If bit 3 is unset it will be freed when the run-unit ends.
3 Allocate this memory as thread local. If bit 2 is unset and there is a direct or indirect (in a mixed-language environment) calling COBOL program, it will be freed when the calling program is canceled or the thread ends - whichever comes first.
4-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.

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_AND

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

Syntax:
call "CBL_AND" using    source 
                        target 
               by value length
Parameters:
source cblt-x1-compx.
target cblt-x1-compx.
length cblt-os-size.
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 section Manipulating Bits Using Logic (Boolean) Operators in 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 cblt-vfile-handle.
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 cblt-x1-compx.
target cblt-x1-compx.
length cblt-os-size.
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 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:
install-flag cblt-x1-compx.
install-addrs cblt-ppointer.
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       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:
command-line pic x(n).
command-line-len cblt-os-size.
run-unit-id cblt-x8-comp5.
stack-size cblt-os-size.
flags cblt-os-flags.
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 Ignored.
flags
Control the behaviour of the child and parent run-unit.

You can set the following bits:

0 The parent waits for the child run-unit to complete before returning from this call
1 Only environment variables are inherited from the parent, not switches or other attributes
On Exit:
run-unit-id
If bit 0 of flags is not set, the unique handle identifying the new run-unit. If bit 0 of flags is set, this value is unchanged.
status-code Status of operation:
0 Success
157 Out of memory
181 Invalid parameter
200 Internal logic error
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:

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:
install-flag cblt-x1-compx.
install-params A group item predefined as cblt-exit-params, containing the following subordinate items:
cblte-ep-install-addr  cblt-pointer.
cblte-ep-install-priority cblt-x1-compx.
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
cblte-ep-install-addr Address of closedown procedure to install, de-install or query.
cblte-ep-install-priority When install-flag is 3, contains the priority of the closedown procedure being installed, in range 0 to 127. Otherwise, ignored.
On Exit:
cblte-ep-install-priority 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, 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:
mem-pointer cblt-pointer.
status-code See Key.
On Entry:
mem-pointer The pointer returned when the memory was allocated using CBL_ALLOC_DYN_MEM.
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:
mem-pointer cblt-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 cblt-x4-comp5.
param-block A group item predefined as cblt-prog-info-params, containing the following subordinate items:
cblte-gpi-size cblt-x4-comp5.
cblte-gpi-flags cblt-x4-comp5.
cblte-gpi-handle cblt-pointer.
cblte-gpi-prog-id cblt-pointer.
cblte-gpi-attrs cblt-x4-comp5.
name-buf pic x(n).
name-len cblt-x4-comp5.
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 cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function values 2 through 7. The initial program associated with cblte-gpi-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 cblte-gpi-handle, which will be used as an input to function 2-7. The initial program associated with cblte-gpi-handle is the named program.
2 Return status information for the program that called the program currently associated with cblte-gpi-handle. This function requires that cblte-gpi-handle has been set up using functions 0 or 1. The program associated with cblte-gpi-handle is updated to the calling program.
3 Close a previously created cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been created using function 0 or 1. A call with this function must be made when cblte-gpi-handle is finished with.
4 Find the first entry point of the program currently associated with cblte-gpi-handle. cblte-gpi-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 cblte-gpi-handle. This function requires a valid cblte-gpi-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 cblte-gpi-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 cblte-gpi-handle. This function requires a valid cblte-gpi-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 on 32-bit systems, or 28 on 64-bit systems.
cblte-gpi-flags A 32-bit word indicating what information is to be returned:
Bit Meaning
0

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

0 Do not return cblte-gpi-handle (if function is set to 0 or 1)
1 Return cblte-gpi-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, 1 and 2 should return the program's attributes in cblte-gpi-attrs .

0 Do not return program attributes in cblte-gpi-attrs.
1 Return program attributes in cblte-gpi-attrs.
4-31

Reserved for future use - must be set to 0.

cblte-gpi-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:
cblte-gpi-handle The handle returned by functions 0 and 1, which must be used for all other functions.
cblte-gpi-prog-id Unique identifier for the program currently associated with cblte-gpi-handle.
cblte-gpi-attrs Attributes of the program currently associated with cblte-gpi-handle:
Bit Value Meaning
0 0
1
Program not compiled using AMODE"24" Compiler directive (
Program compiled using the AMODE"24" Compiler directive (this Compiler directive is not currently available in Net Express).
1 0
1
Program not compiled using AMODE"32" Compiler directive
Program compiled using the AMODE"31" Compiler directive (this Compiler directive is not currently available in Net Express).
2 0
1
Program compiled using the CHARSET(ASCII) Compiler directive.
Program compiled using the CHARSET(EBCDIC) Compiler directive.
3 0
1
Program not compiled using the ANS85 Compiler directive
Program compiled using the ANS85 Compiler directive.
4 0
1
Program not compiled using the VSC2 Compiler directive
Program compiled using the VSC2 Compiler directive (this Compiler directive is not currently available in Net Express).
5 0
1
Program not compiled using the OSVS Compiler directive
Program compiled using the OSVS Compiler directive (this Compiler directive is not currently available in Net Express).
6-27 0
1
Reserved for future use - must be set to 0
28 0
1
Program is not a member not of a subsystem.
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 not canceled.
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 cblte-gpi-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 A group item predefined as cblt-os-info-params, containing the following subordinate items:
cblte-osi-length cblt-x2-compx value 23.
cblte-osi-os-type cblt-x1-compx.
cblte-osi-os-version cblt-x4-compx.
cblte-osi-dbcs-support cblt-x1-compx.
cblte-osi-char-coding cblt-x1-compx.
cblte-osi-country-id cblt-x2-compx.
cblte-osi-code-page cblt-x2-compx.
cblte-osi-process-type cblt-x1-compx.
cblte-osi-rts-capabilities cblt-x4-compx.
cblte-osi-reserved cblt-x1 occurs 5.
status-code See Key.
On Exit:
cblte-osi-os-type COBOL system and operating system:
128 COBOL system on UNIX
cblte-osi-os-version Version number of the operating system.
cblte-osi-dbcs-support DBCS support flag:
bit 0 0 If DBCS validation unsupported
1 If DBCS validation supported
bit 1 0 If PIC N data-type unsupported
1 If PIC N data-type supported
cblte-osi-char-coding Character encoding:
0 ASCII
1 Shift-JIS
2 EUC Japan
3 BIG-5 (Traditional Chinese)
4 5550 (Traditional Chinese)
5 GB (Simplified Chinese)
6 KS-CODE (Korean)
7 PC-CODE (Korean)
8 EUC Taiwan
9 Other EUC locales
cblte-osi-country-id Reserved; set to zero.
cblte-osi-code-page Reserved; set to zero.
cblte-osi-process-type Reserved; undefined.
cblte-osi-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.
cblte-osi-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 cblt-pointer.
node-name A group item predefined as cblt-node-name, containing the following subordinate items:
cblte-nname-name-len cblt-x1-comp5.
cblte-nname-name-text cblt-x1. (Occurs depending on cblte-nname-name-len)
status-code See Key.
On Entry:
cblte-nname-name-len The length of node-name.
cblte-nname-name-text 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 cblt-x1-compx.
target cblt-x1-compx.
length cblt-os-size.
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 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:
msg-file-handle cblt-x4-compx.
status-code See Key.
On Entry:
msg-file-handle The identifying handle returned when the message file was opened.
On Exit:
status-code Indicates whether the routine was successful:
0 Success
404 Invalid msg-file-handle
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.

This routine can be used only from a program that was compiled with the NLS Compiler directive.

See Also:

The chapter National Language 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:
string1 pic x(n).
string2 pic x(n).
string1-length cblt-os-size.
string2-length cblt-os-size.
result-byte cblt-sx1-comp5.
status-code See Key.
On Entry:
string1 The first string.
string2 The second string.
string1-length Length of the first string.
string2-length Length of the second string.
On Exit:
result-byte Result of the comparison:
0 The two strings are the same
-1 string1 < string2
+1 string1 > string2
status-code Indicates whether the routine was successful:
0 Success
Comments:

This routine can be used only from a program that was compiled with the NLS Compiler directive.

See Also:

The chapter National Language 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:
function-code cblt-x1-compx.. Contains one of the following:
1    Get national language information
2    Set national language information
info-category cblt-x1-compx.
info-buffer pic x(n).
status-code See Key.
On Entry:

With function-code = 1:

info-category Category of information to get from the NLS module:
1    Currency symbol
2    Thousands separator
3    Decimal separator

With function-code = 2:

info-category Category of information to set:
1    Currency symbol
2    Thousands separator
3    Decimal separator
info-buffer Information to set (null-terminated). The thousands and decimal separators are each one character long. The currency symbol is up to 10 characters long.
On Exit:

With function-code = 1:

info-buffer The information requested.
status-code Indicates whether the routine was successful:
0 Success

With function-code = 2:

status-code Indicates whether the routine was successful:
0 Success
164 Failure
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.

This routine can be used only from a program that was compiled with the NLS Compiler directive.

See Also:

The chapter National Language 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:
msg-filename pic x(n).
msg-filename-ln cblt-x1-compx.
msg-file-handle cblt-x4-compx.
status-code See Key.
On Entry:
msg-filename The name of the message file to be opened.
msg-filename-ln The length of msg-filename.
On Exit:
msg-file-handle The identifying handle.
status-code Indicates whether the routine was successful:
0 Success

If status-code contains any other value, it is the number of a run-time error message.

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.

This routine can be used only from a program that was compiled with the NLS Compiler directive.

See Also:

The chapter National Language 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:
msg-file-handle cblt-x4-compx.
full-msg-number A group item predefined as cblt-nls-msg-number-pair, containing the following subordinate items:
cblte-nmnp-set-number cblt-x2-compx.
cblte-nmnp-number cblt-x2-compx.
msg-ins-struct A group item predefined as cblt-nls-msg-ins-struct, containing the following subordinate items:
cblte-nmis-ins-count cblt-x2-compx.
cblte-nmis-ins-pointer cblt-pointer. Occurs depending on cblte-nmis-ins-count .
msg-buffer A group item predefined as cblt-nls-msg-buffer, containing the following subordinate items:
cblte-nmb-buff-len cblt-x2-compx.
cblte-nmb-buff-text cblt-x1. Occurs depending on cblte-nmb-buff-len.
status-code See Key.
On Entry:
msg-file-handle The identifying handle of the message file to fetch the message from.
cblte-nmnp-set-number The set in the message file to fetch the message from..
cblte-nmnp-number The message number in the message set to fetch the message from.
cblte-nmis-ins-count The number of portions of text to insert in the message.
cblte-nmis-ins-pointer A pointer to a null-terminated portion of text to insert in the message.
cblte-nmb-buff-len The length of cblte-nmb-buff-text.
On Exit:
cblte-nmb-buff-text The returned text (null-terminated).
status-code Indicates whether the routine was successful:
0 Success
401 Message set not found
402 Message not found in set
403 Message too long for message text buffer
404 Invalid message file handle

If status-code contains a value other than these, it is the number of a run-time error message.

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

This routine can be used only from a program that was compiled with the NLS Compiler directive.

See Also:

The chapter National Language Support.


CBL_NOT

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

Syntax:
call "CBL_NOT" using    target 
               by value length
Parameters:
target cblt-x1-compx.
length cblt-os-size.
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 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:
heap-id cblt-vfile-handle.
status-word cblt-vfile-status.
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 cblt-x1-compx.
target cblt-x1-compx.
length cblt-os-size.
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 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:
node-value cblt-pointer.
node-name A group item predefined as cblt-node-name, containing the following subordinate items:
cblte-nname-name-len cblt-x1-comp5.
cblte-nname-name-text cblt-x1. (Occurs depending on cblte-nname-name-len)
status-code See Key.
On Entry:
node-value The value to assign to the created/updated named value.
cblte-nname-name-len The length of cblte-nname-name-text.
cblte-nname-name-text 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 cblt-vfile-handle.
heap-ref cblt-x4-comp5.
heap-length cblt-x4-comp5.
heap-buffer pic x(n).
status-code See Key.
On Entry:
heap-id 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.


CBL_SUBSYSTEM

Declares or deallocates subsystems.

Syntax:
call "CBL_SUBSYSTEM" using     function-code
                               parameter 
                     returning status-code
Parameters:
function-code cblt-x1-compx. Contains one of the following values:
0 Declare subsystem
1 Cancel subsystem
2 Remove from subsystem
With function-code = 0:
parameter A group item predefined as cblt-subsys-params, containing the following subordinate items:
cblte-ssp-handle cblt-x2-compx.
cblte-ssp-name-len cblt-x2-compx.
cblet-ssp-name cblt-x1. (Occurs depending on cblte-ssp-name-len)
With function-code = 1:
parameter cblt-x2-compx.
With function-code = 2:
parameter cblt-x2-compx value 0.
status-code See Key.
On Entry:
function-code The subfunction value.
With function-code = 0:
cblte-ssp-name-len The length of subsystem program-name field.
cblte-ssp-name The subsystem program-name (space-terminated). This must be a COBOL .int file or .gnt file.
With function-code = 1:
parameter The subsystem handle returned by a function 0 call.
With function-code = 2:
parameter Value 0.
On Exit:

With function-code = 0:

cblte-ssp-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 cblt-os-size.
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 cblt-os-size.
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 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 cblt-vfile-handle.
heap-ref cblt-x4-comp5.
heap-length cblt-x4-comp5.
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 cblt-x1-compx.
target cblt-x1-compx.
length cblt-os-size.
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 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.


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 cblt-x1-compx
array cblt-x1-compx 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 cblt-x1-compx
array cblt-x1-compx 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