| 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.
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.Server Express 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 | Allocate dynamic memory |
| CBL_ALLOC_MEM | Allocate dynamic memory |
| CBL_FREE_DYN_MEM | Free dynamically allocated 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 concurrency 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_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 |
| 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; it is defined
in cbltypes.cpy as 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_DYN_MEM" using mem-pointer
by value mem-size
flags
returning status-code
mem-pointer |
cblt-pointer. |
mem-size |
cblt-os-size. |
flags |
cblt-os-flags. |
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 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.
Dynamically allocates memory.
call "CBL_ALLOC_MEM" using mem-pointer
by value mem-size
flags
returning status-code
mem-pointer |
cblt-pointer. |
mem-size |
cblt-os-size. |
flags |
cblt-os-flags. |
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.
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.
Does a logical AND between the bits of two data items.
call "CBL_AND" using source
target
by value length
source |
cblt-x1-compx. |
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in the chapter Advanced Language Features.
Closes a heap.
call "CBL_CLOSE_VFILE" using by value heap-id
returning status-code
heap-id |
cblt-vfile-handle. |
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 |
cblt-x1-compx. |
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in 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 |
cblt-x1-compx. |
install-addrs |
cblt-ppointer. |
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 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.
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
|
cblt-os-size. |
run-unit-id |
cblt-x8-comp5. |
stack-size |
cblt-os-size. |
flags |
cblt-os-flags. |
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 |
Ignored. | ||||
flags |
Control the behaviour of the child and parent
run-unit.
You can set the following bits:
|
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:
|
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.
The chapter Concurrency Support
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 |
cblt-x1-compx. | ||||||
install-params |
A group item predefined as cblt-exit-params,
containing the following subordinate items:
|
||||||
status-code |
See Key. |
install-flag |
The operation to be performed:
|
||||||||
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. |
cblte-ep-install-priority |
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,
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.
Frees memory dynamically allocated by the CBL_ALLOC_DYN_MEM routine.
call "CBL_FREE_DYN_MEM" using by value mem-pointer
returning status-code
mem-pointer |
cblt-pointer. |
status-code |
See Key. |
mem-pointer |
The pointer returned when the memory was allocated using CBL_ALLOC_DYN_MEM. |
None
This routine releases memory allocated by the CBL_ALLOC_DYN_MEM routine.
Frees dynamically allocated memory.
call "CBL_FREE_MEM" using by value mem-pointer
returning status-code
mem-pointer |
cblt-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 |
cblt-x4-comp5. | |||||||||||||||
param-block |
A group item predefined as cblt-prog-info-params,
containing the following subordinate items:
|
|||||||||||||||
name-buf |
pic x(n). | |||||||||||||||
name-len |
cblt-x4-comp5. | |||||||||||||||
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 on 32-bit
systems, or 28 on 64-bit systems. |
||||||||||||||||||||||||||||
cblte-gpi-flags |
A 32-bit word indicating what information is to be
returned:
|
||||||||||||||||||||||||||||
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. |
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:
|
||||||||||||||||||||||||||||||||||||
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
|
A group item predefined as cblt-os-info-params,
containing the following subordinate items:
|
||||||||||||||||||||||||||||||
status-code |
See Key. |
cblte-osi-os-type |
COBOL system and operating system:
|
||||||||||||||||||||
cblte-osi-os-version |
Version number of the operating system. | ||||||||||||||||||||
cblte-osi-dbcs-support |
DBCS support flag:
|
||||||||||||||||||||
cblte-osi-char-coding |
Character encoding:
|
||||||||||||||||||||
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:
|
||||||||||||||||||||
cblte-osi-reserved |
Reserved. Set to nulls. |
Reads a named value.
call "CBL_GET_SHMEM_PTR" using node-value
node-name
returning status-code
node-value |
cblt-pointer. | ||||||
node-name |
A group item predefined as cblt-node-name,
containing the following subordinate items:
|
||||||
status-code |
See Key. |
cblte-nname-name-len |
The length of node-name. |
cblte-nname-name-text |
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 |
cblt-x1-compx. |
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in the chapter Advanced Language Features.
Closes a National Language Support (NLS) message file.
call "CBL_NLS_CLOSE_MSG_FILE" using msg-file-handle
returning status-code
msg-file-handle |
cblt-x4-compx. |
status-code |
See Key. |
msg-file-handle |
The identifying handle returned when the message file was opened. |
status-code |
Indicates whether the routine was successful:
|
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.
The chapter National Language Support.
Compares two strings
call "CBL_NLS_COMPARE" using string1
string2
by value string1-length
by value string2-length
by reference result-byte
returning status-code
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. |
string1 |
The first string. |
string2 |
The second string. |
string1-length |
Length of the first string. |
string2-length |
Length of the second string. |
result-byte |
Result of the comparison:
|
||||||
status-code |
Indicates whether the routine was successful:
|
This routine can be used only from a program that was compiled with the NLS Compiler directive.
The chapter National Language Support.
Gets/sets national language information
call "CBL_NLS_INFO" using function-code
info-category
info-buffer
returning status-code
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. |
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. |
With function-code = 1:
info-buffer |
The information requested. |
||
status-code |
Indicates whether the routine was successful:
|
With function-code = 2:
status-code |
Indicates whether the routine was successful:
|
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.
The chapter National Language Support.
Open a National Language Support (NLS) message catalog.
call "CBL_NLS_OPEN_MSG_FILE" using msg-filename
msg-filename-ln
msg-file-handle
returning status-code
msg-filename |
pic x(n). |
msg-filename-ln |
cblt-x1-compx. |
msg-file-handle |
cblt-x4-compx. |
status-code |
See Key. |
msg-filename |
The name of the message file to be opened. |
msg-filename-ln |
The length of msg-filename. |
msg-file-handle |
The identifying handle. | ||
status-code |
Indicates whether the routine was successful:
If status-code contains any other value, it is the number of a run-time error message. |
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.
The chapter National Language Support.
Read a message from a National Language Support (NLS) message catalog.
call "CBL_NLS_READ_MSG" using msg-file-handle
full-msg-number
msg-ins-struct
msg-buffer
returning status-code
msg-file-handle |
cblt-x4-compx. | ||||
full-msg-number |
A group item predefined as cblt-nls-msg-number-pair,
containing the following subordinate items:
|
||||
msg-ins-struct |
A group item predefined as cblt-nls-msg-ins-struct,
containing the following subordinate items:
|
||||
msg-buffer |
A group item predefined as cblt-nls-msg-buffer,
containing the following subordinate items:
|
||||
status-code |
See Key. |
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. |
cblte-nmb-buff-text |
The returned text (null-terminated). | ||||||||||
status-code |
Indicates whether the routine was successful:
If status-code contains a value other than these, it is the number of a run-time error message. |
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.
The chapter National Language Support.
Does a logical NOT on the bits of a data item.
call "CBL_NOT" using target
by value length
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in the chapter Advanced Language Features.
Opens a heap.
call "CBL_OPEN_VFILE" using heap-id
status-word
returning status-code
heap-id |
cblt-vfile-handle. |
status-word |
cblt-vfile-status. |
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 |
cblt-x1-compx. |
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in 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 |
cblt-pointer. | ||||||
node-name |
A group item predefined as cblt-node-name,
containing the following subordinate items:
|
||||||
status-code |
See Key. |
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. |
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 |
cblt-vfile-handle. |
heap-ref |
cblt-x4-comp5. |
heap-length |
cblt-x4-comp5. |
heap-buffer |
pic x(n). |
status-code |
See Key. |
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. |
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.
Declares or deallocates subsystems.
call "CBL_SUBSYSTEM" using function-code
parameter
returning status-code
function-code |
cblt-x1-compx. Contains one of the following values:
|
|||||||||
| With function-code = 0: | ||||||||||
parameter |
A group item predefined as cblt-subsys-params,
containing the following subordinate items:
|
|||||||||
With function-code = 1: |
||||||||||
parameter |
cblt-x2-compx. | |||||||||
With function-code = 2: |
||||||||||
parameter |
cblt-x2-compx value 0. | |||||||||
status-code |
See Key. |
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. |
With function-code = 0:
cblte-ssp-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.
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.
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.
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 |
cblt-os-size. |
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 |
cblt-os-size. |
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 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 |
cblt-vfile-handle. |
heap-ref |
cblt-x4-comp5. |
heap-length |
cblt-x4-comp5. |
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 |
cblt-x1-compx. |
target |
cblt-x1-compx. |
length |
cblt-os-size. |
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 section Manipulating Bits Using Logic (Boolean) Operators in 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 |
cblt-x1-compx |
array |
cblt-x1-compx 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 |
cblt-x1-compx |
array |
cblt-x1-compx 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 |