Integrated Preprocessor Interface |
This chapter describes the set of COBOL system library routines that can help you control the environment your application is running in.
Object COBOL provides routines in the following categories:
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.
X"F4" | Pack bytes |
X"F5" | Unpack bytes |
The byte-packing routines enable you to pack and unpack bytes.
CBL_ALLOC_DYN_MEM | Dynamically allocate memory, and associate it with the calling program |
CBL_ALLOC_MEM | Dynamic allocate memory |
CBL_ALLOC_SHMEM | Dynamically allocate shared memory |
CBL_FREE_MEM | Free dynamically allocated memory |
CBL_CULL_RUN_UNITS | Clear dead run-units |
CBL_EXEC_RUN_UNIT | Create run-unit |
CBL_GET_SHMEM_PTR | Read named value |
CBL_PUT_SHMEM_PTR | Create/update named value |
CBL_YIELD_RUN_UNIT | Yield the remainder of a run-unit's time-slice |
The concurrency support routines enable you to manage concurrency. For information on concurrent support, see the chapter Concurrency Support.
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.
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.
CBL_GET_OS_INFO | Get operating system information |
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.
CBL_GET_PROGRAM_INFO | Get operating system information |
CBL_TOLOWER | Convert a string to lower case |
CBL_TOUPPER | Convert a string to upper case |
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.
Descriptions for all of the library routines appear alphabetically. Each description contains the routine name and function and the following entries (as appropriate):
Syntax: | Shows the CALL statement you could use to call the
routine.
The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.) status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5. The name of the routine must be coded in upper case. |
Parameters: | Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine. |
On Entry: | Indicates which of the parameters shown are passed on entry. |
On Exit: | Indicates which of the parameters shown are returned
on exit.
Where bits of one or more bytes are referenced, bit 0 is the least significant (right-most) bit. |
Comments: | Provides any additional information necessary for the successful use of the routine. |
Related Topics:
Lists other related topics.
Dynamically allocates memory, and can associate it with the calling program.
call "CBL_ALLOC_MEM" using mem-pointer by value mem-size flags returning status-code
mem-pointer |
usage pointer. Must be level 01. |
mem-size |
pic x(4) comp-5. |
flags |
pic x(4) comp-5. |
status-code |
See Key. |
mem-size |
The number of bytes of memory to allocate. | ||||||
flags |
The type of memory required. You can set the following
bits:
|
mem-pointer |
A pointer to the memory allocated. The allocated memory is not initialized. | ||||||
status-code |
|
The memory allocated is not initialized to any value.
The maximum size of nonshared memory is restricted only by the operating system (unless the -l run-time switch is set).
If bit 2 is not set the memory allocated by CBL_ALLOC_DYN_MEM is freed when the program that allocated it is cancelled (logically or physically), if there is a COBOL program that is directly or indirectly the caller. If bit 2 is set, this memory is freed when the run-unit terminates, if it has not been previously freed by CBL_FREE_DYN_MEM.
Dynamically allocates memory.
call "CBL_ALLOC_MEM" using mem-pointer by value mem-size flags returning status-code
mem-pointer |
usage pointer. Must be level 01. |
mem-size |
pic x(4) comp-5. |
flags |
pic x(4) comp-5. |
status-code |
See Key. |
mem-size |
The number of bytes of memory to allocate. | ||||
flags |
The type of memory required:
|
mem-pointer |
A pointer to the memory allocated. The allocated memory is not initialized. |
The memory allocated is not initialized to any value.
Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.
Nonshared memory is owned by the program that created it, and is released when the program is canceled if it hasn't already been released using CBL_FREE_MEM routine. Shared memory is owned by the COBOL run-unit (coru) - the set of run-units containing the initial run-unit and all run-units created from it; it is released when the coru is terminated.
The maximum size of nonshared memory is restricted only by the operating system (unless the -l run-time switch is set). The size for shared memory allocated using this routine is limited to a maximum of around of 64000 bytes.
Dynamically allocates memory.
call "CBL_ALLOC_MEM" using mem-pointer by value mem-size returning status-code
mem-pointer |
usage pointer. Must be level 01. |
mem-size |
pic x(4) comp-5. |
status-code |
See Key. |
mem-size |
The number of bytes of memory to allocate. |
mem-pointer |
A pointer to the memory allocated. The allocated memory is not initialized. | ||||
status-code |
|
The memory allocated is not initialized to any value.
Updates to any shared memory allocated to this function are not serialized or protected by the run-time system; you should use semaphores to maintain the integrity of the data.
The maximum size of nonshared memory is restricted only by the operating system (unless the -l run-time switch is set). The size for shared memory allocated using this routine is limited to a maximum of around of 64000 bytes.
Does a logical AND between the bits of two data items.
call "CBL_AND" using source target by value length
source |
Any data item |
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5. |
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. |
target |
The result. |
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 |
The chapter Advanced Language Features.
Closes a heap.
call "CBL_CLOSE_VFILE" using by value heap-id returning status-code
heap-id |
pic x(2) comp-5. |
status-code |
See Key. |
heap-id |
This contains the heap handle assigned when the heap was opened. |
None
Clears any dead run-units.
call "CBL_CULL_RUN_UNITS"
None
This routine clears any run-units that have been terminated by a STOP RUN or kill, but have not yet been removed.
The chapter Concurrency Support
Does a logical EQUIVALENCE between the bits of two data items.
call "CBL_EQ" using source target by value length
source |
Any data item. |
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5. |
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. |
target |
The result. |
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 |
The chapter Advanced Language Features.
Installs or removes an error procedure to be invoked automatically when a run-time system error occurs.
call "CBL_ERROR_PROC" using install-flag install-addrs returning status-code
install-flag |
pic x comp-x. |
install-addrs |
usage procedure-pointer. |
status-code |
See Key. |
install-flag |
The operation to be performed:
|
||||
install-addrs |
Address of error procedure to install or de-install. |
None
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.
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.
The following is an example of installing an error procedure, and the skeleton of the error procedure that is called if an error occurs.
working-storage section 01 install-flag pic x comp-x value 0. 01 install-address usage procedure-pointer. 01 status-code pic 9(4) comp value zeros. linkage section. 01 err-msg pic x(325). procedure division. set install-address to entry "err-proc". call "CBL_ERROR_PROC" using install-flag install-address returning status-code. * Error procedure: entry "err-proc" using err-msg. * Process err-msg to find out the error number. * Act accordingly. ... * Terminate, but allow other error procedures to be executed. move 1 to return-code exit program stop run.
Installs or removes a closedown procedure to be invoked automatically when the application terminates.
call "CBL_EXIT_PROC" using install-flag install-params returning status-code
install-flag |
pic x comp-x. |
install-params |
Group item defined as: |
install-addrs
|
usage procedure-pointer |
install-prrty |
pic x comp-x |
status-code |
See Key. |
install-flag |
The operation to be performed:
|
||||||||
install-addrs |
Address of closedown procedure to install, de-install or query. | ||||||||
install-prrty |
When install-flag is 3, contains
the priority of the closedown procedure being installed, in range 0 to
127. Otherwise, ignored. |
install-prrty |
When install-flag is set to 2,
returns the priority of the selected procedure. |
The installed closedown procedure is executed whether the application finishes normally (with a STOP RUN) or abnormally (for example, with a keyboard interrupt or run-time system error). You can install several closedown procedures for an application by repeated calls of this routine.
A closedown procedure can be written in any language. If it is in COBOL, install-addrs must be the address of an entry point. You can obtain this address using the statement:
set install-addrs to entry "entry-name"
A closedown procedure in COBOL can include any legal COBOL, including call statements. The closedown procedure terminates when the main program in the procedure executes an EXIT PROGRAM/GOBACK or when a STOP RUN statement is executed.
A closedown procedure does not have any parameters passed to it when it is called.
Every closedown procedure installed has a priority. This priority determines the order in which the procedures are executed - procedures with the lowest values are processed first. If several procedures have the same priority, they are executed in reverse order of installation - that is the last one installed is executed first.
Procedures installed without a priority (install-flag = 0) are given the default priority of 64. To set your own priority, set install-flag = 3 and set the priority to a value in the range 0 to 127. Priorities 128 to 256 are reserved for use by the COBOL system. You must not set a priority higher than 127 unless your program is a user-written file handler, in which case it must be 200.
If a closedown procedure has already been installed, an attempt to install again fails. However, if the priority used on the second attempt is different to that used when it was installed, its priority is changed. RETURN-CODE is set to zero.
Use install-flag = 2 to find the priority of a previously installed procedure. This returns the priority in install-prrty if it is found The procedure is identified by its install-addrs. If the procedure cannot be found, RETURN-CODE is set to nonzero.
Creates an asynchronous run-unit.
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
command-line |
pic x(n). |
command-line-len
|
pic x(4) comp-5. |
run-unit-id |
pic x(8) comp-5. Must be level 01. |
stack-size |
pic x(4) comp-5. |
flags |
pic x(4) comp-5. |
status-code |
See Key. |
command-line |
The command passed to the new run-unit. This should be the program name followed by any parameters. |
line-length |
The length of the command line. |
stack-size |
This parameter is ignored . |
flags |
Reserved for future use. Must be zero. |
run-unit-id |
The unique handle identifying the new run-unit. | ||||||||
status-code |
Status of operation:
|
You must set either the ALIGN"4" or ALIGN"8" Compiler directive if you use this routine.
The run-unit that makes the call is known as the parent, while the run-unit created is known as the child. On creation, the child inherits certain attributes from its parent. The attributes inherited by the child are copies of the attributes in the parent at the exact time of the call; any changes made to the attributes of the parent after the call are not reflected in the child's attributes. Similarly, any changes made to the child's attributes are not reflected in the parent's attributes.
The set of run-units containing the initial run-unit and all run-units created from it is known as the coru.
You should be aware of the following when using run-units:
The chapter Concurrency Support
Frees dynamically allocated memory.
call "CBL_FREE_MEM" using by value mem-pointer returning status-code
mem-pointer |
usage pointer. |
status-code |
See Key. |
mem-pointer |
The pointer returned when the memory was allocated using CBL_ALLOC_MEM. |
None
This routine releases memory allocated by the CBL_ALLOC_MEM routine.
Returns information for a named program, or a program in the current call stack.
call "CBL_GET_PROGRAM_INFO" using by value function by reference param-block by reference name-buf by reference name-len returning status-code
function | pic x(4) comp-5. | ||||||||||
param-block | Group item defined as:
|
||||||||||
name-buf | pic x(n). | ||||||||||
name-len | pic x(4) comp-5. | ||||||||||
status-code | See Key. |
function | Specifies the function to be performed:
|
||||||||||||||||||||||||||||
size | The size of the parameter block including this field. This should be set to a value of 20. | ||||||||||||||||||||||||||||
flags | A 32-bit word indicating what information is to be
returned:
|
||||||||||||||||||||||||||||
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. |
handle | The handle returned by functions 0 and 1, which must be used for all other functions. | ||||||||||||||||||||||||||||||||||||
prog-handle | Unique identifier for the program currently associated with handle. | ||||||||||||||||||||||||||||||||||||
prog-attr | Attributes of the program currently associated with handle:
|
||||||||||||||||||||||||||||||||||||
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:
|
Returns information about the current operating system and environment.
call "CBL_GET_OS_INFO" using parameter-block returning status-code
parameter-block
|
Group item defined as:
|
||||||||||||||||||||||||||||||||||||||||
status-code |
See Key. |
p-os-type |
COBOL system and operating system:
|
||||||||||||||||
p-os-version |
Version number of the operating system. | ||||||||||||||||
p-DBCS-support |
DBCS support flag:
|
||||||||||||||||
p-char-coding
|
Character encoding:
|
||||||||||||||||
p-country-id |
Reserved; set to zero. | ||||||||||||||||
p-code-page |
Reserved; set to zero. | ||||||||||||||||
p-process-type |
Reserved; undefined. | ||||||||||||||||
p-rts-capabilities |
Special features of the COBOL run-time system:
|
||||||||||||||||
p-reserved |
Reserved. Set to nulls. |
Reads a named value.
call "CBL_GET_SHMEM_PTR" using node-value node-name returning status-code
node-value |
usage pointer. |
node-name |
Group item defined as: |
name-length |
pic x comp-5 value n. |
name |
pic x(n) value "name". |
status-code |
See Key. |
node-name |
The length of name. |
name |
The value assigned to node-name. |
node-value |
The value of the named value. |
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.
CBL_PUT_SHMEM_PTR
The chapter Concurrency
Support
Does a logical IMPLIES between the bits of two data items.
call "CBL_IMP" using source target by value length
source |
Any data item. |
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5. |
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. |
target |
The result. |
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 |
The chapter Advanced Language Features.
Does a logical NOT on the bits of a data item.
call "CBL_NOT" using target by value length
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5. |
target |
The data to operate on. |
target |
The data with the bits inverted. |
length |
The number of bytes of target to change. Positions beyond this are unchanged. |
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 |
The chapter Advanced Language Features.
Opens a heap.
call "CBL_OPEN_VFILE" using heap-id status-word returning status-code
heap-id |
pic x(2) comp-5. |
status-word |
pic x(2). |
status-code |
See Key. |
None.
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:
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. |
Does a logical OR between the bits of two data items.
call "CBL_OR" using source target by value length
source |
Any data item. |
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5 |
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. |
target |
The result. |
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 |
The chapter Advanced Language Features.
Creates or updates a named value.
call "CBL_PUT_SHMEM_PTR" using by value node-value by reference node-name returning status-code
node-value |
usage pointer. |
node-name |
Group item defined as: |
name-length |
pic x comp-5 value n. |
name |
pic x(n) value "name". |
status-code |
See Key. |
node-value |
The value to assign to the created/updated named value. |
name-length |
The length of name. |
name |
The name of the named value. |
None
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.
CBL_GET_SHMEM_PTR
The chapter Concurrency
Support
Reads bytes from a heap.
call "CBL_READ_VFILE" using by value heap-id heap-ref heap-length by reference heap-buffer returning status-code
heap-id |
pic x(2) comp-5. |
heap-ref |
pic x(4) comp-5. |
heap-length |
pic x(4) comp-5. |
heap-buffer |
pic x(n). |
status-code |
See Key. |
heap-id |
This contains the heap handle assigned when the heap was opened. |
heap-ref |
Offset in the heap at which to start reading. |
heap-length |
Number of bytes to read. |
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. |
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.
Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.
call "CBL_SCR_SET_PC_ATTRIBUTES" returning status-code
status-code |
See Key. |
None
status-code |
The return status:
|
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.
The chapter Generic Display Attributes in your Programmer's Guide to Creating User Interfaces.
Declares or deallocates subsystems.
call "CBL_SUBSYSTEM" using function-code parameter returning status-code
function-code |
pic x comp-x. Contains one of the following values:
|
||||||
With function-code = 0: | |||||||
parameter |
Group item defined as: | ||||||
ss-handle |
pic x(2) comp-x. | ||||||
ss-name-len |
pic x(2) comp-x. | ||||||
ss-name |
pic x(n) | ||||||
With function-code = 1: | |||||||
parameter |
pic x(2) comp-x. | ||||||
With function-code = 2: | |||||||
parameter |
pic x(2) comp-x value 0 | ||||||
status-code |
See Key. |
function-code |
The subfunction value. |
With function-code = 0: | |
ss-name-len |
The length of subsystem program-name field. |
ss-name |
The subsystem program-name (space-terminated). This must be a COBOL .int file or .gnt file. |
With function-code = 1: | |
ss-handle |
The subsystem handle returned by a function 0 call. |
With function-code = 2: | |
dummy-param | Value 0. |
With function-code = 0:
ss-handle |
The subsystem handle. |
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. |
Converts a string of letters to lower case.
call "CBL_TOLOWER" using string by value length returning status-code
string |
pic x(n). |
length |
pic x(4) comp-5. |
status-code |
See Key. |
string |
The string to convert. |
length |
The number of bytes of string to change; positions beyond this are unchanged. |
string |
The converted string. |
The routine starts at the left-hand end of string and converts letters to lower case (also called folding to lower case).
Converts a string of letters to upper case.
call "CBL_TOUPPER" using string by value length returning status-code
string |
pic x(n). |
length |
pic x(4) comp-5. |
status-code |
SeeKey. |
string |
The string to convert. |
length |
The number of bytes of string to change; positions beyond this are unchanged. |
string |
The converted string. |
The routine starts at the left-hand end of string and converts letters to upper case (also called folding to upper case).
Writes bytes to a heap.
call "CBL_WRITE_VFILE" using by value heap-id heap-ref heap-length by reference heap-buffer returning status-code
heap-id |
pic x(2) comp-5. |
heap-ref |
pic x(4) comp-5. |
heap-length |
pic x(4) comp-5. |
heap-buffer |
pic x(n). |
status-code |
See Key. |
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. |
None
Does a logical XOR between the bits of two data items.
call "CBL_XOR" using source target by value length
source |
Any data item. |
target |
Any data item. |
length |
Numeric literal or pic x(4) comp-5. |
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. |
target |
The result. |
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 |
The chapter Advanced Language Features.
Yields the remainder of a run-unit's time-slice.
call "CBL_YIELD_RUN_UNIT"
None
The remainder of the run-unit's time-slice is yielded to unspecified run-units.
Packs the least significant bits in eight bytes into a single byte.
call x"F4" using byte array
byte |
pic x comp-x |
array |
pic x comp-x occurs 8 |
array |
The bits to be packed. |
byte |
The packed byte. |
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
Unpacks the bits in a byte into eight bytes.
call x"F5" using byte array
byte |
pic x comp-x |
array |
pic x comp-x occurs 8 |
byte |
The byte to be unpacked |
array |
The unpacked bits |
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.
Integrated Preprocessor Interface |