COBOL-IT Library Routines
COBOL-IT supports a number of library routines, which are built into the compiled objects, and can be CALL'ed directly.
These library routines cover a range of functionalities, including:
-
Bytestream routines
Bytestream routines allow for file handling without having
FDandSELECTstatements for a file. -
File/Directory routines
File/Directory routines allow for the creation and deletion of files and directories, and various other functionalities such as
COPYfunctionality, andRENAMEfunctionality, and routines which can be used to retrieve information about given files. -
Logical Operation routines
Logical Operation routines allow for the application of logical operators such as
AND,OR,XOR,NOT, to parameters provided by the user. -
Text String routines
Text String routines allow for the case transformation and justification of given strings of text.
-
Linkage-oriented routines
Linkage-oriented routines allow the user to check the number of parameters passed from a
CALL'ing program, as wells as parameter size. -
System-level routines
System-level routines include calls to "SYSTEM", as well as to "Sleep" routines, which can be used to pause the system.
-
Debugging-oriented routines
Debugging-oriented routines allow the user to pause the runtime so that it may be restarted in the debugger.
-
Error and Exit routines
Error and Exit routines allow the user to direct control to routines set up to handle error and exit procedure code.
-
Call-by-number routines
Call-by-number routines provide compatibility with the commonly used X"91", X"F4" and X"F5" function.
General Notes applying to Library Routines
The General Format for callable Library Routines is:
CALL library-routine [ USING { parameter-n,... } ]
[ GIVING call-status ].
-
library-routineis represented as an alphanumeric literal, or, in some cases, as a variable. Note that theSYSTEMroutine, and library routines that are prefixed withC$(example:C$COPY) can be dynamically called. In a dynamicCALL, the library name is replaced by a variable name, which can be populated anywhere prior to the execution of theCALLstatement.-
Format 1 -
CALL "library routine" USING parameter-1, GIVING call-status. -
Format 2
77 function-call PIC X(20). MOVE “library routine” to function-call. CALL function-call. -
-
The
GIVINGphrase is always optional. If theGIVINGphrase is omitted, then the return value from the CALL to the library routine will be returned to the return-code register. -
Supported Library Routines are listed alphabetically.
-
Runtime Abort Codes
-
CALL's to Library Routines return a 0 when successful. For the behavior of a Library Routine when unsuccessful, check the documentation for the specific routine. Most commonly, you will find that file-oriented routines return file-status codes that can be instructive as to why an operation has failed, and other routines will return a 128 (Call Unresolved). -
If your
CALLreturns an error code that is not mentioned in this documentation, check the full list of runtime abort codes.
-
C$CALLERNAME
C$CALLERNAME returns the program-id name of the CALL'ing program in a CALL'ed program.
Usage:
CALL "C$CALLERNAME" USING calling-program-name.
| Parameters | |
|---|---|
| calling-program-name | PIC X(n) |
| Syntax | |
|---|---|
| calling-program-name | is the program-id name of the program that CALLed the currently running program. |
General Rules
-
The function does note update return-code.
-
When executed from within a
CALL'ed program, the function returns the program-id name of theCALL'ing program. When executed from within aMAINprogram that has not been called, the function returns the string "UNDEFINED".
Code Sample:
* C$CALLERNAME
77 CALLINGPGM-NAME PIC X(30)
. . . .
*
. . .
INITIALIZE CALLINGPGM-NAME.
CALL "C$CALLERNAME" USING CALLINGPGM-NAME.
*
C$CHDIR
C$CHDIR changes the current working directory to the directory named in new-dir.
Usage:
CALL "C$CHDIR" USING new-dir,
GIVING call-status.
| Parameters | |
|---|---|
| new-dir | PIC X(n) |
| call-status | PIC S9(9) |
| Syntax | |
|---|---|
| new-dir | is the name of the new current working directory. |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 128.
Code Sample:
* C$CHDIR
77 NEW-DIR PIC X(6).
77 CALL-STATUS PIC S9(9).
. . .
*
. . .
INITIALIZE NEW-DIR, CALL-STATUS.
MOVE "SUBDIR" TO NEW-DIR.
CALL "C$CHDIR" USING NEW-DIR,
GIVING CALL-STATUS.
*
C$COPY
C$COPY copies a source file to a target filename.
Usage:
CALL "C$COPY"
USING src-file,
target-file,
file-type,
GIVING call-status.
| Parameters | |
|---|---|
| source-file | PIC X(n) |
| target-file | PIC X(n) |
| file-type | PIC X. |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| source-file | is the original file to be copied. |
| target-file | is the new file which is a copy of source-file. |
| file-type | Permissible values are: |
| "S" | Sequential |
| "R" | Relative |
| "I" | Indexed |
| "T" | Text |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 128.
Code Sample:
* C$COPY VARIABLES
77 SRC-FILE PIC X(11).
77 TARGET-FILE PIC X(10).
77 FILE-TYPE PIC X VALUE "T".
77 CALL-STATUS PIC S9(9).
...
INITIALIZE CALL-STATUS.
MOVE "LIBTEST.CBL" TO SRC-FILE.
MOVE "NEWFIL.CBL" TO TARGET-FILE.
CALL "C$COPY" USING SRC-FILE,
TARGET-FILE,
FILE-TYPE,
GIVING CALL-STATUS.
C$DEBUG
C$DEBUG is a library routine which can be called using either the PID of the runtime session, or the value of the environment variable COB_DEBUG_ID. Prior to calling C$DEBUG, the program should acquire the value of the PID/COB_DEBUG_ID.
You may acquire the value of the PID of the runtime session by calling the C$PID library routine, using a PIC 9(n) parameter. The parameter must be numeric, and large enough to hold the value of the Process ID.
For example:
77 ws-pid PIC 9(5).
…..
CALL « C$PID » USING ws-pid.
CALL « C$DEBUG » USING ws-pid.
You may also call C$DEBUG using the value of the runtime environment variable COB_DEBUG_ID. Using the runtime environment variable COB_DEBUG_ID to hold the value of this parameter has an advantage if you prefer to set the value of the parameter yourself. Acquire the value of COB_DEBUG_ID programmatically before calling the C$DEBUG library routine. The parameter must be numeric, and large enough to hold the value of the value of the runtime environment variable COB_DEBUG_ID.
For example:
77 ws-did PIC 9(5).
…..
ACCEPT ws-did FROM ENVIRONMENT « COB_DEBUG_ID ».
CALL «C$DEBUG » USING ws-did.
After a call to C$DEBUG is made, the executing program, or subprogram is paused. In this state, the COBOL-IT Debugger may be attached to this runtime process from the COBOL-IT Developer Studio.
Key concepts
-
In order to attach to the COBOL-IT Debugger, the program containing the call to C$DEBUG library routine must be compiled with -g.
-
The COBOL-IT Developer Studio will request the location of the source file associated with the program/subprogram that has been paused by the C$DEBUG command, for purposes of debugging.
-
The COBOL-IT Developer Studio attaching to the paused runtime session requires a COBOL Project, and requires that some configuration. Recommended settings are:
Window>Preferences>Run/Debug>Perspectives>Open the associated perspective when lauching (Always)
Demonstration
For our test, we have a program, debugid.cbl, which calls a subprogram, subpgm.cbl, which retrieves the PID of the runtime session, and then calls C$DEBUG to pause the runtime session. We will run these programs from a batch file, as follows:
Launch and pause the runtime using "C$DEBUG" runit.bat
SET COB_LIBRARY_PATH=.\object
cobcrun debugid
This will return the screen below. Note that in your case, the Process ID will likely be different.
Attach the Debugger from the Developer Studio
When this program is paused, we will open the Developer Studio, configure:
Window>Preferences>Run/Debug>Perspectives>Open the associated perspective when launching (Select Always).
Create a new project
Select Debug Attach Function
In the Navigator Window, right-click on the Project, and select COBOL>Debug Attach from the dropdown list:
Select ID
In the Debug Configuration for Reverse Attach Window, select the entry with the PID that matches the PID of the paused runtime session. Click Debug.
Edit Source Lookup Path
The Developer Studio opens in the Debugger Perspective. Note that there is a message, in red, that "Source Not Found". To associate the the source code of subpgm.cbl with the project, click on the Edit Source Lookup Path... button.
On the Edit the Source Lookup Path Screen, the Default setting is your current Project Path. If the source files are not in your Project Path, click the Add button.
Select File System Directory, Click Ok.
Use the Browse button to locate the Source Location
Your selection will appear in ithe Source Lookup Path window . Click OK.
Debug in the Developer Studio
You are now ready to debug in the Developer Studio:
Use the Debugger toolbar buttons to debug your program.
Terminate the Debugger by clicking on the Terminate button.
Programs used in this sample
debugid.cbl
IDENTIFICATION DIVISION.
PROGRAM-ID. debugid.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
PROCEDURE DIVISION.
MAIN.
DISPLAY "C$DEBUG Usage", LINE 6 COL 10.
CALL "subpgm".
DISPLAY "Back in DebugID..." LINE 20 COL 10.
STOP RUN.
subpgm.cbl
IDENTIFICATION DIVISION.
PROGRAM-ID. subpgm.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 ws-process-id PIC 9(5).
PROCEDURE DIVISION.
MAIN.
CALL "C$PID" USING ws-process-id.
DISPLAY "Process ID: ", ws-process-id LINE 10 COL 10.
DISPLAY "PAUSING IN SUBPGM" LINE 12 COL 10.
CALL "C$DEBUG" USING ws-process-id.
DISPLAY "YOU CAN DEBUG NOW" LINE 16 COL 10.
DISPLAY "AND" LINE 17 COL 10.
DISPLAY "FIND THE PROBLEM" LINE 18 COL 10.
EXIT PROGRAM.
runit.bat
SET COB_LIBRARY_PATH=.\object
cobc -o .\object -g debugid.cbl
cobc -o .\object -g subpgm.cbl
cobcrun debugid
C$DELETE
C$DELETE deletes a source file.
Usage:
CALL "C$DELETE" USING DEL-FILE-NAME,
DEL-FILE-TYPE,
GIVING call-status.
| Parameters | |
|---|---|
| del-file-name | PIC X (n) |
| del-file-type | PIC X. |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| del-file-name | is the file to be deleted. |
| del-file-type | is the type of file. Permissible values are: |
| “S” | Sequential |
| “R” | Relative |
| “I” | Indexed |
| “T” | Text |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 128.
Code Sample:
* C$DELETE
77 DEL-FILE-NAME PIC X(20).
77 DEL-FILE-TYPE PIC X VALUE "T".
77 CALL-STATUS PIC S9(9).
...
INITIALIZE CALL-STATUS.
MOVE "NEWFIL.CBL" TO DEL-FILE-NAME.
CALL "C$DELETE" USING DEL-FILE-NAME,
DEL-FILE-TYPE,
GIVING CALL-STATUS.
C$FILEINFO
C$FILEINFO retrieves the size and date/time stamp of a file.
Usage:
CALL "C$FILEINFO" USING file-name,
file-info,
GIVING call-status.
| Parameters | ||
|---|---|---|
| info-file-name | PIC X(n) | |
| info-file-info | A group item with the following elements: | |
| file-size | PIC X(8) COMP-X. | |
| file-date | PIC 9(8) COMP-X. | |
| file-time | PIC 9(8) COMP-X. | |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| info-file-name | must be terminated with a space. |
| info-file-info | receives data if file-name exists. |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 35.
Code Sample:
* C$FILEINFO
77 INFO-FILENAME PIC X(16).
01 INFO-FILE-INFO.
05 FILE-SIZE PIC X(8) COMP-X.
05 FILE-DATE PIC 9(8) COMP-X.
05 FILE-TIME PIC 9(8) COMP-X.
77 CALL-STATUS PIC S9(9).
...
INITIALIZE CALL-STATUS.
MOVE "NEWFIL.CBL" TO INFO-FILENAME.
CALL "C$FILEINFO" USING INFO-FILENAME,
INFO-FILE-INFO
GIVING CALL-STATUS.
*
C$JUSTIFY
C$JUSTIFY performs left/right/center justification of data by removing leading and/or trailing spaces.
Usage:
CALL "C$JUSTIFY" USING SOURCE-DATA-1,
JUSTIFY-TYPE.
| Parameters | |
|---|---|
| source-data-1 | Any data type |
| justify-type | PIC X |
| Syntax | |
|---|---|
| source-data-1 | contains the data to be justified. |
| justify-type | indicates whether justification is L (left), R (right), or C (center). |
General Rules:
The source-data item is transformed by the routine, as leading/trailing spaces are manipulated.
Code Sample:
* C$JUSTIFY
77 SOURCE-DATA-1 PIC X(20).
77 JUSTIFY-TYPE PIC X.
...
MOVE " ABCDEFGHIJ " TO SOURCE-DATA-1.
MOVE "L" TO JUSTIFY-TYPE.
CALL "C$JUSTIFY" USING SOURCE-DATA-1, JUSTIFY-TYPE.
MOVE "R" TO JUSTIFY-TYPE.
CALL "C$JUSTIFY" USING SOURCE-DATA-1, JUSTIFY-TYPE.
MOVE "C" TO JUSTIFY-TYPE.
CALL "C$JUSTIFY" USING SOURCE-DATA-1, JUSTIFY-TYPE.
...
*
C$MAKEDIR
C$MAKEDIR creates a directory.
Usage:
CALL "C$MAKEDIR" USING dir-name
GIVING call-status.
| Parameters | |
|---|---|
| make-dir-name | PIC X(n) |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| make-dir-name | is the name of the directory to be created. |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 128.
-
make-dir-namecan contain full-path or relative-path notations. -
C$MAKEDIRcannot be used to create a series of sub-directories.
Code Sample:
*
77 MAKE-DIR-NAME PIC X(20).
77 CALL-STATUS PIC S9(9).
...
INITIALIZE CALL-STATUS.
MOVE "SUBDIR" TO MAKE-DIR-NAME.
CALL "C$MAKEDIR" USING MAKE-DIR-NAME
GIVING CALL-STATUS.
...
*
C$NARG
C$NARG returns the number of parameters that have been passed through linkage to the executing program.
Usage:
CALL "C$NARG" USING number-of-parameters.
| Parameters | |
|---|---|
| number-of-parameters | Numeric data item. |
| Syntax | |
|---|---|
| number-of-paramters | is returned as a result of the call. |
General Rules:
Number-of-parameters is returned the number of USING items in the CALL statement that are in the CALL'ing program.
Code Sample:
*
77 NUM-PARAMS PIC S9.
LINKAGE SECTION.
01 LK-NAME PIC X(25).
01 LK-ADDR PIC X(25).
01 LK-CUSTOMERID PIC X(5).
...
PROCEDURE DIVISION USING LK-NAME, LK-ADDR, LK-CUSTOMERID.
MAIN.
CALL "C$NARG" USING NUM-PARAMS.
...
*
C$PARAMSIZE
C$PARAMSIZE takes the ordinal number of a parameter as input in a USING phrase, and returns its size in bytes in a parameter named in the GIVING phrase.
Usage:
CALL "C$PARAMSIZE" USING param-num,
GIVING param-size.
| Parameters | |
|---|---|
| param-num | PIC 9(n), or any numeric data item. |
| param-size | PIC 9(n). |
| Syntax | |
|---|---|
| param-num | represents the ordinal position of parameter |
| param-size | receives from the function the number of bytes in the named data item |
General Rules:
There are no general rules.
Code Sample:
*
77 FIRST-PARAM-SIZE PIC 99.
LINKAGE SECTION.
01 LK-NAME PIC X(25).
01 LK-ADDR PIC X(25).
01 LK-CUSTOMERID PIC X(5).
PROCEDURE DIVISION USING LK-NAME, LK-ADDR, LK-CUSTOMERID.
MAIN.
CALL "C$PARAMSIZE" USING 1, GIVING FIRST-PARAM-SIZE.
...
*
C$PID
C$PID retrieves the Process ID of the current process.
Note
C$PID is not currently available on Windows platforms.
Usage:
CALL "C$PID" USING process-id.
| Parameters | |
|---|---|
| process-id | PIC 9(n). |
| Syntax | |
|---|---|
| process-id | is a numeric data item which must be large enough to hold the process-id. |
Code Sample:
*
77 PROCESS-ID PIC 9(7).
...
CALL "C$PID" USING PROCESS-ID.
...
*
C$SLEEP
C$SLEEP causes the program to "sleep" in a defined interval that is represented in seconds, or fractions of seconds.
Usage:
CALL "C$SLEEP” USING number-seconds.
| Parameters | |
|---|---|
| number-seconds | Numeric literal or data item |
| Syntax | |
|---|---|
| number-seconds | is the elapsed time in seconds to sleep |
Code Sample:
*
...
CALL "C$SLEEP" USING 1.5.
...
*
C$TOLOWER
C$TOLOWER translates a text string into lower-case.
Usage:
CALL "C$TOLOWER" USING ctl-source-data,
VALUE ctl-source-length.
| Parameters | |
|---|---|
| ctl-source-data | PIC X(10). |
| ctl-source-length | USAGE UNSIGNED-INT. |
| Syntax | |
|---|---|
| ctl-source-data | is the data to translate to upper-case. |
| ctl-source-length | is the number of characters to translate. |
General Rules:
-
The string in
ctl-source-datais transformed by the operation, with all characters being translated to lower-case. -
Return-codeis not updated following the operation.
Code Sample:
*
77 CTL-SOURCE-DATA PIC X(10).
77 CTL-SOURCE-LENGTH USAGE UNSIGNED-INT.
...
MOVE "ABCDEFGHIJ" TO CTL-SOURCE-DATA.
MOVE 10 TO CTL-SOURCE-LENGTH.
CALL "C$TOLOWER"
USING CTL-SOURCE-DATA,
VALUE CTL-SOURCE-LENGTH.
...
*
C$TOUPPER
C$TOUPPER translates a text string into upper-case.
Usage:
CALL "C$TOUPPER" USING ctu-source-data,
VALUE ctu-source-length.
| Parameters | |
|---|---|
| ctu-source-data | PIC X(n) |
| ctu-source-length | USAGE UNSIGNED-INT, or a numeric literal |
| Syntax | |
|---|---|
| ctu-source-data | is the data to translate to upper-case. |
| ctu-source-length | is the number of haracters to translate. |
General Rules:
-
The string in
ctu-source-datais transformed by the operation, with all characters being translated to upper-case. -
Return-codeis not updated following the operation.
Code Sample:
*
77 CTU-SOURCE-DATA PIC X(10).
77 CTU-SOURCE-LENGTH USAGE UNSIGNED-INT.
...
MOVE "ABCDEFGHIJ" TO CTU-SOURCE-DATA.
MOVE 10 TO CTU-SOURCE-LENGTH.
CALL "C$TOUPPER"
USING CTU-SOURCE-DATA,
VALUE CTU-SOURCE-LENGTH.
...
*
CBL_ALLOC_DYN_MEM
CBL_ALLOC_DYN_MEM dynamically allocates memory, returning an address (MEMORY-POINTER) and a size.
Usage:
CALL "CBL_ALLOC_DYN_MEM" USING memory-pointer,
BY VALUE memory-size,
BY VALUE memory-flags,
RETURNING call-status.
| Syntax: | |
|---|---|
| memory-pointer | is a data element described as USAGE POINTER. Memory-pointer must be described as an 01-level data item. The memory allocated is not initialized. |
| memory-size | represents the size of the memory being allocated, in bytes. memory size is described as PIC x(4) comp-5. |
| memory-flags | describe the type of memory being allocated. This is done by setting of bits on a 4-byte field. See the table below for guidelines on setting bits to describe a type of memory. memory-flags is described as PIC x(4) comp-5. |
| bits 0-1 Reserved. Must be set to 0. | |
| bit 2 Allocate this memory independently from any calling program. | |
| bits 4-31 Reserved.Must be set to 0. | |
| If bit 2 is not set, the memory allocated is freed when the currently running program is cancelled from memory. If bit 2 is set, the memory allocated is freed when the runtime session terminates. Memory allocated can also be freed by the CBL_FREE_DYN_MEM library routine. | |
| call-status | is a return code. Call-status settings are: |
| 0 successful allocation of memory | |
| 157 unsuccessful allocation of memory | |
| 181 contradictory setting of flags |
General Rules:
The General Rules are described above.
CBL_ALLOC_MEM
CBL_ALLOC_MEM dynamically allocates memory, returning an addres (MEMORY-POINTER) and a size.
Usage:
CALL "CBL_ALLOC_MEM" USING memory-pointer,
BY VALUE memory-size,
BY VALUE memory-flags,
RETURNING call-status.
| Syntax: | |
|---|---|
| memory-pointer | is a data element described as USAGE POINTER. Memory-pointer must be described as an 01-level data item. |
| memory-size | represents the size of the memory being allocated, in bytes. memory size is described as PIC x(4) comp-5. |
| memory-Flags | describe the type of memory being allocated. This is done by setting of bits on a 4-byte field. See the table below for guidelines on setting bits to describe a type of memory. Memory-flags is described as PIC x(4) comp-5. |
| bit 0 Allocate the memory as shared memory | |
| bit 1 Reserved. Must be set to 0. | |
| bit 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. | |
| bit 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. | |
| bits 4-31 Reserved. Must be set to 0. | |
| call-status | is a return code.Call-status settings are: |
| 0 successful allocation of memory | |
| 157 unsuccessful allocation of memory | |
| 181 contradictory setting of flags |
General Rules:
-
Use the memory allocation functions with caution. Updates to shared memory allocated to this function are not serialized or protected by the run-time system. It is advised that you use semaphores to maintain the integrity of the data
-
If the memory is allocated by a thread, it is freed when the thread terminates.
-
Bit 1 and bit 2 or bit 3 are mutually exclusive. The contradictory setting of flags (error 181) is returned otherwise.
-
If there is no calling program (directly or indirectly in a mixed language environment) bit 2 is ignored.
-
If a COBOL program is directly or indirectly the caller of
CBL_ALLOC_MEM, then all standard memory allocated byCBL_ALLOC_MEMis freed when the program that allocated it is canceled (logically or physically) if bit 2 is not set.
CBL_AND
CBL_AND performs a logical AND operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_AND" USING and-param-1,
and-param-2,
BY VALUE and-length-in-bytes.
| Parameters | |
|---|---|
| and-param-1 | PIC X(n) |
| and-param-2 | PIC X(n) |
| and-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| and-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| and-param-2 | must be a data item. Must be at least 1 byte in length. Is transformed by the operation, as it will hold the result of the logical AND operation. |
| and-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
ANDoperation is performed on corresponding bits inparam-1andparam-2, with the result of the logicalANDoperation written toparam-2. -
The
ANDoperation uses the following "truth table":
AND 0 1
0 0 0
1 0 1
Code Sample:
77 AND-PARAM-1 PIC X VALUE "A".
77 AND-PARAM-2 PIC X VALUE "B".
77 AND-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
MOVE "A" TO AND-PARAM-1.
MOVE "B" TO AND-PARAM-2.
CALL "CBL_AND" USING AND-PARAM-1,
AND-PARAM-2,
BY VALUE AND-LENGTH-IN-BYTES.
...
CBL_CHANGE_DIR
CBL_CHANGE_DIR changes the current working directory to the directory named in new-dir.
Usage:
CALL "CBL_CHANGE_DIR" USING new-dir
GIVING call-status.
| Parameters | |
|---|---|
| new-dir | PIC X(n) |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| new-dir | is the name of the new current working directory. |
| call-status | is updated with the success or failure status. |
General Rules:
-
When the function is successful, call-status is set to 0.
-
When the function fails, call-status is set to 128.
Code Sample:
*
77 NEW-DIR PIC XX.
77 CALL-STATUS PIC S9(9).
...
MOVE ".." TO NEW-DIR.
CALL "CBL_CHANGE_DIR" USING NEW-DIR
GIVING CALL-STATUS.
*
CBL_CHECK_FILE_EXIST
CBL_CHECK_FILE_EXIST checks to see if a file exists.
Usage:
CALL "CBL_CHECK_FILE_EXIST" USING ccfe-file-name,
ccfe-file-details.
| Parameters | ||
|---|---|---|
| ccfe-file-name | PIC X(n) | |
| ccfe-file-details | A group item with the following elements: | |
| file-size | PIC X(8) COMP-X. | |
| file-date | A group item with the following elements: | |
| f-day | PIC X COMP-X. | |
| f-month | PIC X COMP-X. | |
| f-year | PIC X(2) COMP-X. | |
| file-time | A group item with the following elements: | |
| f-hours | PIC X COMP-X. | |
| f-minutes | PIC X COMP-X. | |
| f-seconds | PIC X COMP-X. | |
| f-hundredths | PIC X COMP-X. |
| Syntax | |
|---|---|
| ccfe-file-name | must be terminated with a space. |
| ccfe-file-details | is populated with data if file-name exists. |
General Rules:
When the function is successful, return-code is set to 0. When the function fails, return-code is set to 35.
Code Sample:
77 CCFE-FILENAME PIC X(15).
01 CCFE-FILE-DETAILS.
05 FILE-SIZE PIC X(8) COMP-X.
05 FILE-DATE.
10 F-DAY PIC X COMP-X.
10 F-MONTH PIC X COMP-X.
10 F-YEAR PIC X(2) COMP-X.
05 FILE-TIME.
10 F-HOURS PIC X COMP-X.
10 F-MINUTES PIC X COMP-X.
10 F-SECONDS PIC X COMP-X.
10 F-HUNDREDTHS PIC X COMP-X.
...
INITIALIZE RETURN-CODE.
MOVE "NEWFIL.CBL " TO CCFE-FILENAME.
CALL "CBL_CHECK_FILE_EXIST"
USING CCFE-FILENAME,
CCFE-FILE-DETAILS.
CBL_CLOSE_FILE
CBL_CLOSE_FILE closes a file that was created with either the CBL_OPEN_FILE or CBL_CREATE_FILE function.
Usage:
CALL "CBL_CLOSE_FILE" using my-file-handle.
| Parameters | |
|---|---|
| my-file-handle | PIC X(4) COMP-5. |
| Syntax | |
|---|---|
| my-file-handle | is returned after a successful Create, or Open. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
Code Sample:
*
77 MY-FILE-HANDLE PIC X(4) COMP-5.
...
CALL "CBL_CLOSE_FILE" USING MY-FILE-HANDLE.
...
*
CBL_COPY_FILE
CBL_COPY_FILE copies a source file to a target filename.
Usage:
CALL "CBL_COPY_FILE" USING CCF-SOURCE-FILE,
CCF-TARGET-FILE.
| Parameters | |
|---|---|
| ccf-source-file | PIC X(n) |
| ccf-target-file | PIC X(n) |
| Syntax | |
|---|---|
| ccf-source-file | is the original file to be copied. |
| ccf-target-file | is the new file which is a copy of source-file. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to -1.
Code Sample:
*
77 CCF-SOURCE-FILE PIC X(20).
77 CCF-TARGET-FILE PIC X(20).
...
MOVE "COPYFIL.CBL" TO CCF-SOURCE-FILE.
MOVE "NEWFIL.CBL" TO CCF-TARGET-FILE.
CALL "CBL_COPY_FILE" USING CCF-SOURCE-FILE,
CCF-TARGET-FILE.
*
CBL_CREATE_DIR
CBL_CREATE_DIR creates a directory.
Usage:
CALL "CBL_CREATE_DIR" USING CCD-DIR-NAME.
| Parameters | |
|---|---|
| ccd-dir-name | PIC X(n) |
| Syntax | |
|---|---|
| ccd-dir-name | is the name of the directory to be created. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to 128.
-
ccd-dir-namecan contain full-path or relative-path notations. -
If path notations are part of
dir-name, then the parent directory to the last directory must exist. -
CBL_CREATE_DIRcannot be used to create a series of sub-directories.
Code Sample:
*
77 CCD-DIR-NAME PIC X(20).
...
INITIALIZE RETURN-CODE.
MOVE "SUBDIR" TO CCD-DIR-NAME.
CALL "CBL_CREATE_DIR" USING CCD-DIR-NAME.
*
CBL_CREATE_FILE
CBL_CREATE_FILE creates a sequential file with READ/WRITE permissions described by the parameters passed.
Usage:
CALL "CBL_CREATE_FILE" USING my-file-name,
my-file-permissions,
my-file-restrictions,
my-device,
my-file-handle.
| Parameters | |
|---|---|
| my-file-name | PIC X(n). |
| my-file-permissions | PIC X COMP-X. |
| my-file-restrictions | PIC X COMP-X. |
| my-device | PIC X COMP-X. |
| my-file-handle | PIC X(4) COMP-5. |
| Syntax | |
|---|---|
| my-file-name | is a null-terminated character string. |
| file-permissions | describes Read/Write permissions. It must be one of the following: |
| 1 Read-only | |
| 2 Write-only | |
| 3 Read-Write | |
| 64 Read-Write for large files (> 4GB) | |
| my-file-restrictions | describes Read/Write restrictions. It must be one of the following: |
| 0 Write-only | |
| 1 No write | |
| 2 No read | |
| 3 No read/write restrictions | |
| my-device | must be set to 0. |
| my-file-handle | is stored after a successful Create, or Open. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
Code Sample:
*
* CBL_CREATE_FILE
77 MY-FILE-NAME PIC X(11).
77 MY-ACCESS-MODE PIC X COMP-X VALUE 3.
77 MY-DENY-MODE PIC X COMP-X VALUE 3.
77 MY-DEVICE PIC X COMP-X VALUE 0.
77 MY-FILE-HANDLE PIC X(4) COMP-5.
...
INITIALIZE RETURN-CODE.
STRING "AAAAAA.TXT" DELIMITED BY SIZE,
X"00", DELIMITED BY SIZE,
INTO MY-FILE-NAME.
CALL "CBL_CREATE_FILE"
USING MY-FILE-NAME,
MY-ACCESS-MODE,
MY-DENY-MODE,
MY-DEVICE,
MY-FILE-HANDLE.
*
CBL_DEBUGBREAK
CBL_DEBUGBREAK is a synonym for C$DEBUG. CBL_DEBUGBREAK is a library routine which can be called using either the PID of the runtime session, or the value of the environment variable COB_DEBUG_ID.
For example:
77 ws-pid PIC 9(5).
…..
CALL « C$PID » USING ws-pid.
CALL « CBL_DEBUGBREAK » USING ws-pid.
For more details, see the documentation of the C$DEBUG library routine.
CBL_DELETE_DIR
CBL_DELETE_DIR deletes the named directory.
Usage:
CALL "CBL_DELETE_DIR" USING del-dir-name.
| Parameters | |
|---|---|
| del-dir-name | PIC X(n). |
| Syntax | |
|---|---|
| del-dir-name | is the name of the directory to be deleted. |
General Rules:
When the function is successful, return-code is set to 0. When the function fails, return-code is set to 128.
Code Sample:
*
77 DEL-DIR-NAME PIC X(20).
...
INITIALIZE RETURN-CODE.
MOVE "SUBDIR" TO DEL-DIR-NAME.
CALL "CBL_DELETE_DIR" USING DEL-DIR-NAME.
*
CBL_DELETE_FILE
CBL_DELETE_FILE deletes the named file.
Usage:
CALL "CBL_DELETE_FILE" USING CDF-FILE-NAME.
| Parameters | |
|---|---|
| cdf-file-name | PIC X(n). |
| Syntax | |
|---|---|
| cdf-file-name | is the name of the file to be deleted |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to 128.
Code Sample:
*
77 CDF-FILE-NAME PIC X(20).
...
INITIALIZE RETURN-CODE.
MOVE "README.TXT" TO CDF-FILE-NAME.
CALL "CBL_DELETE_FILE" USING CDF-FILE-NAME.
...
*
CBL_ERROR_PROC
CBL_ERROR_PROC installs or uninstalls an error procedure, which is run when a program-ending error occurs. The Error Routine allows the user to register procedures that will automatically be executed either when a program-ending error occurs.
Usage:
call "CBL_ERROR_PROC" using error-proc-flag, error-proc-addr.
| Parameters | |
|---|---|
| error-proc-flag | set to 0 to install error proc set to 1 to uninstall error proc 01 ERROR-PROC-FLAG PIC X COMP-X VALUE 0. |
| error-proc-addr | address of error proc01 ERROR-PROC-ADDR USAGE PROCEDURE-POINTER. |
| error-proc-msg | message from error LINKAGE SECTION.01 ERROR-PROC-MSG PIC X(ERROR-PROC-MSG-LEN). |
| Syntax | |
|---|---|
| error-proc-flag | set to 0 to install error proc set to 1 to uninstall error proc |
| error-proc-addr | address of error proc |
| error-proc-msg | message returned through linkage |
Code Sample:
...
78 ERROR-PROC-MSG-LEN VALUE 325.
01 ERROR-PROC-FLAG PIC X COMP-X VALUE 0.
01 ERROR-PROC-ADDR USAGE PROCEDURE-POINTER.
01 STATUS-CODE PIC 9(4) COMP VALUE ZEROS.
...
LINKAGE SECTION.
01 ERROR-PROC-MSG PIC X(ERROR-PROC-MSG-LEN).
PROCEDURE DIVISION.
MAIN.
SET ERROR-PROC-ADDR TO ENTRY "ERROR-PROC".
CALL "CBL_ERROR_PROC" USING ERROR-PROC-FLAG,
ERROR-PROC-ADDR
RETURNING STATUS-CODE.
...
*
ENTRY "ERROR-PROC" USING ERROR-PROC-MSG.
DISPLAY "IN ERROR PROCEDURE".
DISPLAY FUNCTION TRIM(ERROR-PROC-MSG).
DISPLAY FUNCTION EXCEPTION-LOCATION.
EXIT PROGRAM.
STOP RUN.
CBL_EQ
CBL_EQ performs a logical EQUAL operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_EQ" USING eq-param-1,
eq-param-2,
BY VALUE eq-length-in-bytes.
| Parameters | |
|---|---|
| eq-param-1 | PIC X(n) |
| eq-param-2 | PIC X(n) |
| eq-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| eq-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| eq-param-2 | must be a data item. Must be at least 1 byte in length.is transformed by the operation, as it will hold the result of the logical EQ operation. |
| eq-length-in-bytes | must be passed "by value". |
General Rules:
A logical EQ operation is performed on corresponding bits in eq-param-1 and eq-param-2, with the result of the logical EQ operation written to eq-param-2.
The EQ operation uses the following "truth table":
EQ 0 1
0 1 0
1 0 1
Code Sample:
*
77 EQ-PARAM-1 PIC X VALUE "A".
77 EQ-PARAM-2 PIC X VALUE "B".
77 EQ-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_EQ" USING EQ-PARAM-1,
EQ-PARAM-2,
BY VALUE EQ-LENGTH-IN-BYTES.
...
CBL_EXIT_PROC
CBL_EXIT_PROC installs or uninstalls an exit procedure, which is run when the application terminates either normally or abnormally. The Exit
Routine allows the user to register procedures that will automatically be executed when the program does a normal exit.
Usage:
call "CBL_EXIT_PROC" using exit-proc-flag,
exit-proc-addr.
| Parameters | |
|---|---|
| exit-proc-flag | PIC X COMP-X value 0. |
| exit-proc-addr | USAGE PROCEDURE-POINTER. |
| Syntax | |
|---|---|
| exit-proc-flag | set to 0 to install exit proc, set to 1 to uninstall exit proc |
| exit-proc-addr | is the address of exit proc |
Code Sample:
*
...
01 ERROR-PROC-FLAG PIC X COMP-X VALUE 0.
01 ERROR-PROC-ADDR USAGE PROCEDURE-POINTER.
*
...
SET EXIT-PROC-ADDR TO ENTRY "EXIT-PROC".
...
CALL "CBL_EXIT_PROC" USING EXIT-PROC-FLAG,
EXIT-PROC-ADDR.
STOP RUN.
...
ENTRY "EXIT-PROC".
DISPLAY "IN EXIT PROCEDURE".
EXIT PROGRAM.
STOP RUN.
*
CBL_FLUSH_FILE
CBL_FLUSH_FILE causes any file buffers that have not been flushed to disk to be flushed.
Usage:
CALL "CBL_FLUSH_FILE" USING my-file-handle.
| Parameters | |
|---|---|
| my-file-handle | PIC X(4) COMP-5. |
| Syntax | |
|---|---|
| my-file-handle | is returned after a successful Create, or Open. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
Code Sample:
*
77 MY-FILE-HANDLE PIC X(4) COMP-5.
...
INITIALIZE RETURN-CODE.
CALL "CBL_FLUSH_FILE" USING MY-FILE-HANDLE.
*
CBL_FREE_MEM
CBL_FREE_MEM frees memory allocated by the CBL_ALLOC_MEM routine.
Usage:
CALL “CBL_FREE_ MEM” USING BY VALUE memory-pointer
RETURNING call-status.
| Parameters | |
|---|---|
| memory-pointer | USAGE POINTER. |
| call-status PIC | S9(9). |
| Syntax | |
|---|---|
| memory-pointer | is a data element described as USAGE POINTER, which has been populated with a value by the CBL_ALLOC_ MEM routine. |
| call-status | is a return code. |
CBL_FREE_DYN_MEM
CBL_FREE_DYN_MEM frees memory allocated by the CBL_ALLOC_DYN_MEM routine.
Usage:
CALL “CBL_FREE_DYN_MEM” USING BY VALUE memory-pointer
RETURNING call-status.
| Parameters | |
|---|---|
| memory-pointer | USAGE POINTER. |
| call-status | PIC S9(9). |
| Syntax | |
|---|---|
| memory-pointer | is a data element described as USAGE POINTER, which has been populated with a value by the CBL_ALLOC_DYN_MEM routine. |
| call-status | is a return code. |
CBL_GET_CURRENT_DIR
CBL_GET_CURRENT_DIR returns the full path of the current directory.
Usage:
CALL "CBL_GET_CURRENT_DIR"
USING BY VALUE FLAGS
BY VALUE LENGTH-OF-DIRNAME
BY REFERENCE DIRECTORY-NAME.
| Parameters | |
|---|---|
| flags | PIC X COMP-X VALUE 0. |
| length-of-dirname | PIC 9(n) |
| directory-name | PIC X(n) |
| Syntax | |
|---|---|
| flags | must be set to 0. |
| length-of-dirname | corresponds to the length of directory-name. |
| directory-name | must contain enough characters to store the full path name of the current directory. The function call returns the full path into directory-name. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an 128.
Code Sample:
*
77 FLAGS PIC X COMP-X VALUE 0.
77 LENGTH-OF-DIRNAME PIC 99 VALUE 50.
77 DIRECTORY-NAME PIC X(50) VALUE SPACES.
...
CALL "CBL_GET_CURRENT_DIR"
USING BY VALUE FLAGS
BY VALUE LENGTH-OF-DIRNAME
BY REFERENCE DIRECTORY-NAME.
...
*
CBL_IMP
CBL_IMP performs a logical IMPLIES operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_IMP" USING IMP-PARAM-1,
` IMP-PARAM-2,
BY VALUE IMP-LENGTH-IN-BYTES.
| Parameters | |
|---|---|
| imp-param-1 | PIC X(n) |
| imp-param-2 | PIC X(n) |
| imp-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| imp-param-1 | may be an alphanumeric literal or data item.must be at least 1 byte in length. |
| imp-param-2 | must be a data item. Must be at least 1 byte in length. is transformed by the operation, as it will hold the result of the logical IMP operation. |
| Imp-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
IMPoperation is performed on corresponding bits inparam-1andparam-2, with the result of the logicalIMPoperation written toparam-2. -
The
IMPoperation uses the following "truth table":
IMP 0 1
0 1 1
1 0 1
Code Sample:
*
77 IMP-PARAM-1 PIC X VALUE "A".
77 IMP-PARAM-2 PIC X VALUE "B".
77 IMP-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
MOVE "A" TO IMP-PARAM-1.
MOVE "B" TO IMP-PARAM-2.
CALL "CBL_IMP" USING IMP-PARAM-1,
IMP-PARAM-2,
BY VALUE IMP-LENGTH-IN-BYTES.
...
CBL_NIMP
CBL_NIMP performs a logical NOT IMPLIES operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_NIMP" USING NIMP-PARAM-1,
NIMP-PARAM-2,
BY VALUE NIMP-LENGTH-IN-BYTES.
| Parameters | |
|---|---|
| nimp-param-1 | PIC X(n) |
| nimp-param-2 | PIC X(n) |
| nimp-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| nimp-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| nimp-param-2 | must be a data item. Must be at least 1 byte in length. Is transformed by the operation, as it will hold the result of the logical NIMP operation. |
| nimp-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
NIMPoperation is performed on corresponding bits inparam-1andparam-2, with the result of the logicalNIMPoperation written toparam-2. -
The
NIMPoperation uses the following “truth table”:
IMP 0 1
0 0 0
1 1 0
Code Sample:
*
77 NIMP-PARAM-1 PIC X VALUE "A".
77 NIMP-PARAM-2 PIC X VALUE "B".
77 NIMP-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_NIMP" USING NIMP-PARAM-1,
NIMP-PARAM-2,
BY VALUE NIMP-LENGTH-IN-BYTES.
...
*
CBL_NOR
CBL_NOR performs a logical NOR operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_NOR" USING nor-param-1,
nor-param-2,
BY VALUE nor-length-in-bytes.
| Parameters | |
|---|---|
| nor-param-1 | PIC X(n) |
| nor-param-2 | PIC X(n) |
| nor-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| nor-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| nor-param-2 | must be a data item. Must be at least 1 byte in length. Is transformed by the operation, as it will hold the result of the logical NOR operation. |
| nor-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
NORoperation is performed on corresponding bits inparam-1andparam-2, with the result of the logicalNORoperation written toparam-2. -
The
NORoperation uses the following "truth table":
NOR 0 1
0 1 0
1 0 0
Code Sample:
*
77 NOR-PARAM-1 PIC X VALUE "A".
77 NOR-PARAM-2 PIC X VALUE "B".
77 NOR-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_NOR" USING NOR-PARAM-1,
NOR-PARAM-2,
BY VALUE NOR-LENGTH-IN-BYTES.
...
CBL_NOT
CBL_NOT performs a logical NOT operation on bits of param-1 and over the course of a byte-length which is given in param-1.
Usage:
CALL "CBL_NOT" USING not-param-1,
BY VALUE not-length-in-bytes.
| Parameters | |
|---|---|
| not-param-1 | PIC X(n) |
| not-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| not-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. Is transformed by the operation, as it will hold the result of the logical NOT operation. |
| not-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
NOToperation is performed on bits inparam-1, with the result of the logicalNOToperation written toparam-1. -
The
NOToperation uses the following "truth table":
NOT
0 1
1 0
Code Sample:
*
77 NOT-PARAM-1 PIC X VALUE "A".
77 NOT-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_NOT" USING NOT-PARAM-1,
BY VALUE NOT-LENGTH-IN-BYTES.
...
*
CBL_OC_NANOSLEEP
CBL_OC_NANOSLEEP causes the program to "sleep" in a defined interval that is represented in nanoseconds.
Usage:
CALL "CBL_OC_NANOSLEEP” USING number-nanoseconds.
| Parameters | |
|---|---|
| number-nanoseconds | Numeric literal or data item |
| Syntax | |
|---|---|
| number-nonoseconds | is the elapsed time in nanoseconds to sleep |
Code Sample:
*
...
CALL “CBL_OC_NANOSLEEP” USING 250000000.
...
*
CBL_OPEN_FILE
CBL_OPEN_FILE opens a sequential file with READ/WRITE permissions described by the parameters passed.
Usage:
CALL "CBL_OPEN_FILE” USING my-file-name,
my-file-permissions,
my-file-restrictions,
my-device,
my-file-handle.
| Parameters | |
|---|---|
| my-file-name | PIC X(n). |
| my-file-permissions | PIC X COMP-X. |
| my-file-restrictions | PIC X COMP-X. |
| my-device | PIC X COMP-X. |
| my-file-handle | PIC X(4) COMP-5. |
| Syntax | |
|---|---|
| my-file-name | is a null-terminated character string. |
| my-file-permissions | describes Read/Write permissions. It must be one of the following: |
| 1 Read-only | |
| 2 Write-only | |
| 3 Read-Write | |
| 64 Read-Write for large files (> 4GB) | |
| my-file-restrictions | describes Read/Write restrictions. It must be one of the following: |
| 0 Write-only | |
| 1 No write | |
| 2 No read | |
| 3 No read/write restrictions | |
| my-device | must be set to 0. |
| my-file-handle | is stored after a successful Create, or Open. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
-
My-file-namemay include an environment variable notation, for purposes of locating the file, as follows:
01 my-file-name pic x(40) value "$MYPATH/workfile.txt".
….
In this case, the $MYPATH notation would cause the value of the "MYPATH" environment variable to be prepended to workfile.txt, for purposes of locating the file.
Code Sample:
*
77 MY-FILE-NAME PIC X(11).
77 MY-FILE-PERMISSIONS PIC X COMP-X VALUE 3.
77 MY-FILE-RESTRICTIONS PIC X COMP-X VALUE 3.
77 MY-DEVICE PIC X COMP-X VALUE 0.
77 MY-FILE-HANDLE PIC X(4) COMP-5. .
..
STRING "MYTEXTFILE" DELIMITED BY SIZE,
X"00", DELIMITED BY SIZE,
INTO MY-FILE-NAME.
CALL "CBL_OPEN_FILE"
USING MY-FILE-NAME,
MY-FILE-PERMISSIONS,
MY-FILE-RESTRICTIONS,
MY-DEVICE,
MY-FILE-HANDLE.
*
CBL_OR
CBL_OR performs a logical OR operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_OR" USING or-param-1,
or-param-2,
BY VALUE or-length-in-bytes.
| Parameters | |
|---|---|
| or-param-1 | PIC X(n) |
| or-param-2 | PIC X(n) |
| or-length-in-bytes | PIC 9(n) |
| Syntax | |
|---|---|
| or-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| or-param-2 | must be a data item. Must be at least 1 byte in length. Is transformed by the operation, as it will hold the result of the logical OR operation. |
| or-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical
ORoperation is performed on corresponding bits inparam-1andparam-2, with the result of the logical OR operation written toparam-2. -
The
ORoperation uses the following "truth table":
OR 0 1
0 0 1
1 1 1
Code Sample:
*
77 OR-PARAM-1 PIC X VALUE "A".
77 OR-PARAM-2 PIC X VALUE "B".
77 OR-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_OR" USING OR-PARAM-1,
OR-PARAM-2,
BY VALUE OR-LENGTH-IN-BYTES.
...
*
CBL_READ_FILE
CBL_READ_FILE READ's a number of bytes from an offset of a file into a buffer.
Usage:
CALL "CBL_READ_FILE" USING my-file-handle,
my-file-offset,
my-byte-count,
my-read-flag,
my-read-buffer.
| Parameters | |
|---|---|
| my-file-handle | PIC X(4) COMP-5. |
| my-file-offset | PIC X(8) COMP-X. |
| my-byte-count | PIC X(n) COMP-X. |
| my-read-flag | PIC X COMP-X. |
| my-read-buffer | PIC X(n). |
| Syntax | |
|---|---|
| my-file-handle | is required, and obtained by performing a successful CREATE or OPEN. |
| my-file-offset | is the offset to begin the READ operation, beginning the file at offset 0. |
| my-byte-count | is the number of bytes to read from the file. |
| my-read-flag | must be one of the following: |
| 0 Standard read | |
| 128 Return the current file size in file-offset | |
| my-read-buffer | is the data that is being read from the file. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
Code Sample:
*
77 MY-FILE-HANDLE PIC X(4) COMP-5.
77 MY-FILE-OFFSET PIC X(8) COMP-X VALUE 0.
77 MY-BYTE-COUNT PIC X(4) COMP-X VALUE 11.
77 MY-READ-FLAG PIC X COMP-X VALUE 0.
77 MY-READ-BUFFER PIC X(11) VALUE SPACES.
...
INITIALIZE MY-READ-BUFFER.
CALL "CBL_READ_FILE"
USING MY-FILE-HANDLE,
MY-FILE-OFFSET,
MY-BYTE-COUNT,
MY-READ-FLAG,
MY-READ-BUFFER.
CBL_RENAME_FILE
CBL_RENAME_FILE renames the named source file.
Usage:
CALL "CBL_RENAME_FILE" USING source-filename,
renamed-filename.
| Parameters | |
|---|---|
| source-filename | PIC X(n). |
| renamed-filename | PIC X(n). |
| Syntax | |
|---|---|
| source-filename | is the name of the original source file. |
| renamed-filename | is the name to which it is renamed. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to 128.
Code Sample:
*
77 SOURCE-FILENAME PIC X(20).
77 RENAMED-FILENAME PIC X(20).
...
MOVE "HELLO.CBL" TO SOURCE-FILENAME.
MOVE "WORLD.CBL" TO RENAMED-FILENAME.
CALL "CBL_RENAME_FILE"
USING SOURCE-FILENAME,
RENAMED-FILENAME.
...
*
CBL_TOLOWER
CBL_TOLOWER translates a text string into lower-case.
Usage:
CALL "CBL_TOLOWER" USING source-data,
VALUE source-length.
| Parameters | |
|---|---|
| source-data | PIC X(n) |
| source-length | USAGE UNSIGNED-INT, or a numeric literal |
| Syntax | |
|---|---|
| source-data | is the data to translate to upper-case. Is transformed by the CBL_TOLOWER operation, with all characters being translated to lower-case. |
| source-length | is the number of characters to translate. |
General Rules:
Return-code is not updated following the operation.
Code Sample:
*
77 SOURCE-DATA PIC X(10).
77 SOURCE-LENGTH USAGE UNSIGNED-INT.
...
MOVE "ABCDEFGHIJ" TO SOURCE-DATA.
MOVE 10 TO SOURCE-LENGTH.
CALL "CBL_TOLOWER"
USING SOURCE-DATA, VALUE SOURCE-LENGTH.
...
*
CBL_TOUPPER
CBL_TOUPPER translates a text string into upper-case.
Usage:
CALL "CBL_TOUPPER" USING source-data, VALUE source-length
| Parameters | |
|---|---|
| source-data | PIC X(n) |
| source-length | USAGE UNSIGNED-INT, or a numeric literal |
| Syntax | |
|---|---|
| source-data | is the data to translate to upper-case. Is transformed by the CBL_TOUPPER operation, with all characters being translated to upper-case. |
| source-length | is the number of characters to translate. |
General Rules:
Return-code is not updated following the operation.
Code Sample:
*
77 SOURCE-DATA PIC X(10).
77 SOURCE-LENGTH USAGE UNSIGNED-INT.
...
MOVE "ABCDEFGHIJ" TO SOURCE-DATA.
MOVE 10 TO SOURCE-LENGTH.
CALL "CBL_TOUPPER"
USING SOURCE-DATA,
VALUE SOURCE-LENGTH.
...
*
CBL_WRITE_FILE
CBL_WRITE_FILE is WRITE's a number of bytes to an offset of a file from a buffer.
Usage:
CALL "CBL_WRITE_FILE" USING my-file-handle,
my-file-offset,
my-byte-count,
my-write-flag,
my-write-buffer.
| Parameters | |
|---|---|
| my-file-handle | PIC X(4) COMP-5. |
| my-file-offset | PIC X(8) COMP-X. |
| my-byte-count | PIC X(n) COMP-X. |
| my-write-flag | PIC X COMP-X. |
| my-write-buffer | PIC X(n). |
| Syntax | |
|---|---|
| my-file-handle | Required, and can only be obtained by performing a successful CREATE or OPEN. |
| my-file-offset | The offset to begin the WRITE operation on;- the beginning of the file is offset 0. |
| my-byte-count | The number of bytes to write to the file. |
| my-write-flag | Must be one of the following: |
| 0 Standard write | |
| 128 Return the current file size in file-offset | |
| my-write-buffer | The data that is being written to the file. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to an ANSI-74 file-status code according to the nature of the error.
Code Sample:
*
77 MY-FILE-HANDLE PIC X(4) COMP-5.
77 MY-FILE-OFFSET PIC X(8) COMP-X VALUE 0.
77 MY-BYTE-COUNT PIC X(4) COMP-X VALUE 11.
77 MY-WRITE-FLAG PIC X COMP-X VALUE 0.
77 MY-WRITE-BUFFER PIC X(11) VALUE SPACES.
...
MOVE “HELLO WORLD” TO MY-WRITE-BUFFER.
CALL "CBL_WRITE_FILE"
USING MY-FILE-HANDLE,
MY-FILE-OFFSET,
MY-BYTE-COUNT,
MY-WRITE-FLAG,
MY-WRITE-BUFFER.
CBL_XOR
CBL_XOR performs a logical XOR operation on bits of param-1 and param-2, over the course of a byte-length which is given in param-3.
Usage:
CALL "CBL_XOR" USING xor-param-1,
xor-param-2,
BY VALUE xor-length-in-bytes.
| Parameters | |
|---|---|
| xor-param-1 | PIC X(n) |
| xor-param-2 | PIC X(n) xor-length-in-bytes PIC 9(n) |
| Syntax | |
|---|---|
| xor-param-1 | may be an alphanumeric literal or data item. Must be at least 1 byte in length. |
| xor-param-2 | must be a data item. Must be at least 1 byte in length.Is transformed by the operation, as it will hold the result of the logical XOR operation. |
| xor-length-in-bytes | must be passed “by value”. |
General Rules:
-
A logical XOR operation is performed on corresponding bits in
param-1andparam-2, with the result of the logical XOR operation written toparam-2. -
The XOR operation uses the following "truth table":
XOR 0 1
0 0 1
1 1 0
Code Sample:
* #
77 XOR-PARAM-1 PIC X VALUE "A".
77 XOR-PARAM-2 PIC X VALUE "B".
77 XOR-LENGTH-IN-BYTES PIC 9 VALUE 1.
...
CALL "CBL_XOR" USING XOR-PARAM-1,
XOR-PARAM-2,
BY VALUE XOR-LENGTH-IN-BYTES.
...
SYSTEM
SYSTEM provides a means of executing command-line commands from within the COBOL program. The program is paused until the command is complete.
Usage:
CALL "SYSTEM" USING command,
GIVING exit-status.
| Parameters | |
|---|---|
| command | PIC X(n) |
| exit-status | Any numeric data item |
| Syntax | |
|---|---|
| command | is the command-line command that is executed. |
| exit-status | returns the called program's exit status, or -1 if the command failed. |
General Rules:
-
When the function is successful, return-code is set to 0.
-
When the function fails, return-code is set to 128.
Code Sample:
*
...
CALL “SYSTEM” USING “NOTEPAD.EXE”.
...
*
X "91" function 11
X"91" function 11 sets the Special-Names programmable switches.
Usage:
call x"91" using fn-status,
x91-function,
group-item.
| Parameters | |
|---|---|
| fn-status | PIC X COMP-X |
| x91-function | PIC X COMP-X |
| group-item | group-item with |
| switch-flags | PIC X COMP-X occurs 8 |
| debug-flag | PIC X COMP-X |
| Syntax | |
|---|---|
| fn-status | set to 0 if the function is successful, else 1. |
| X91-function | set to 11. |
| group-item | group-item with |
| switch-flags values | ( 0 or 1 ) for each of the 8 switches |
| debug-flag | set to 0. |
Code Sample:
* #
77 FN-STATUS PIC X COMP-X.
77 X91-FUNCTION PIC X COMP-X VALUE 11.
01 GROUP-ITEM.
05 SWITCH-FLAGS PIC X COMP-X OCCURS 8.
05 DEBUG-FLAG PIC X COMP-X.
...
MOVE 1 TO SWITCH-FLAGS(1).
CALL X"91" USING FN-STATUS, X91-FUNCTION, GROUP-ITEM.
...
*
X "91" function 12
X"91" function 12 reads the Special-Names programmable switches.
Usage:
call x"91" using fn-status,
x91-function,
group-item.
| Parameters | |
|---|---|
| fn-status | PIC X COMP-X |
| x91-function | PIC X COMP-X |
| group-item | group-item with |
| switch-flags | PIC X COMP-X occurs 8 |
| debug-flag | PIC X COMP-X |
| Syntax | |
|---|---|
| fn-status | set to 0 if the function is successful, else 1. |
| X91-function | set to 11. |
| group-item | group-item with |
| switch-flags values | (0 or 1) for each of the 8 switches |
| debug-flag | set to 0. |
Code Sample:
*
...
SPECIAL-NAMES.
SWITCH 1 IS SWITCH-1.
...
77 FN-STATUS PIC X COMP-X.
77 X91-FUNCTION PIC X COMP-X VALUE 12.
01 GROUP-ITEM.
05 SWITCH-FLAGS PIC X COMP-X OCCURS 8.
05 DEBUG-FLAG PIC X COMP-X.
...
SET SWITCH-1 TO ON.
CALL X"91" USING FN-STATUS, X91-FUNCTION, GROUP-ITEM.
...
*
X "91" function 15
X"91" function 15 checks to see if a program exists.
Usage:
call x"91" using fn-status,
x91-function,
param.
| Parameters | |
|---|---|
| fn-status | PIC X COMP-X |
| x91-function | PIC X COMP-X |
| param | Group Item containing |
| length-of-progname | PIC X COMP-X |
| program-name | PIC X(N). |
| Syntax | |
|---|---|
| fn-status | set to program-name if successful, 0 if program not found. |
| X91-function | set to 15. |
| param | group item containing length of program-name, and program-name. |
Code Sample:
*
...
77 FN-STATUS PIC X COMP-X.
77 X91-FUNCTION PIC X COMP-X VALUE 15.
01 PARAM.
05 LWNGTH-OF-PROGNAME PIC X COMP-X.
05 PROGNAME PIC X(6).
...
PROCEDURE DIVISION.
...
MOVE 6 TO LENGTH-OF-PROGNAME.
MOVE “TESTIT” TO PROGRAM-NAME.
CALL X"91" USING FN-STATUS, X91-FUNCTION, PARAM.
...
*
X "91" function 16
X"91" function 16 returns the number of parameters passed through linkage to a sub-program.
Usage:
call x"91" using fn-status,
x91-function,
num-params.
| Parameters | |
|---|---|
| fn-status | PIC X COMP-X |
| x91-function | PIC X COMP-X |
| num-params | PIC X COMP-X |
| Syntax | |
|---|---|
| fn-status | set to 0 if the function is successful, else 1. |
| X91-function | set to 16. |
| num-params | receives the number of parameters on the Procedure Division USING statement. |
Code Sample:
*
...
77 FN-STATUS PIC X COMP-X.
77 X91-FUNCTION PIC X COMP-X VALUE 16.
77 NUM-PARAMS PIC X COMP-X.
...
LINKAGE SECTION.
01 LK-NAME PIC X(25).
01 LK-ADDR PIC X(25).
01 LK-CUSTOMERID PIC X(5).
PROCEDURE DIVISION USING LK-NAME, LK-ADDR, LK-CUSTOMERID.
...
CALL X"91" USING FN-STATUS, X91-FUNCTION, NUM-PARAMS.
...
*
X"F4"
X"F4" builds a byte (or bytes), bit-by-bit, using the least significant bits of bytes that have been supplied in a table.
Usage:
CALL X"F4" using new-byte,
byte-array.
| Parameters | |
|---|---|
| new-byte | PIC X COMP-X |
| byte-array | A group-item table with: |
| tbl-byte | USAGE BINARY-CHAR OCCURS 8 |
| Syntax | |
|---|---|
| new-byte | contains the new byte. |
| byte-array | array of eight bytes. |
General Rules:
The least significant bit of each byte in byte-array will form a bit in new-byte. To manufacture the letter "A", which consists of the bits 0100 0001 for example, the least significant bit of tblbyte(1) must be 0, the least significant bit of tbbyte(2) must be 1, and in so forth. In this fashion, the byte is constructed from left to right, adding 0, then 1, then 0, then 0, then 0, then 0, then 0, then 1 to build 0100 0001, or the character "A".
Code Sample:
*
01 NEW-BYTE PIC X COMP-X.
01 BIT-TABLE.
05 TBL-BYTE OCCURS 8 TIMES USAGE BINARY-CHAR.
...
MOVE 0 TO TBL-BYTE(1).
MOVE 1 TO TBL-BYTE(2).
MOVE 0 TO TBL-BYTE(3).
MOVE 0 TO TBL-BYTE(4).
MOVE 0 TO TBL-BYTE(5).
MOVE 0 TO TBL-BYTE(6).
MOVE 0 TO TBL-BYTE(7).
MOVE 1 TO TBL-BYTE(8).
CALL X"F4" USING NEW-BYTE, BIT-TABLE.
...
X"F5"
X"F5" unpacks a byte (or bytes), bit-by-bit, into an array of bytes, mapping the first bit of the byte into the least significant bit of the first item in the array, the second bit into the least significant bit of the second byte in the array, and so forth.
Usage:
CALL X"F5" using source-byte,
byte-array.
| Parameters | |
|---|---|
| source-byte | PIC X COMP-X |
| byte-array | A group-item table with: |
| tbl-byte | USAGE BINARY-CHAR OCCURS 8 |
| Syntax | |
|---|---|
| source-byte | contains the new byte. |
| byte-array | array of eight bytes. |
General Rules:
To unpack the letter "A", for example, which consists of the bits 0100 0001 the most significant bit (0) is written to the least significant bit of tblbyte(1), then moving from left to right, the next most significant bit (1) is written to the least significant bit of tblbyte(2) and so forth. In this fashion, the byte is unpacked, from left to right, adding 0, then 1, then 0, then 0, then 0, then 0, then 0, then 1 to transform the table such that the least significant bits of each of its entries hold the bits 0, 1, 0, 0, 0, 0, 0 ,1.
Code Sample:
*
...
01 SRC-BYTE PIC X VALUE "A".
01 SOURCE-BYTE REDEFINES SRXC-BYTE PIC X COMP-X.
01 BYTE-ARRAY.
05 TBL-BYTE OCCURS 8 TIMES USAGE BINARY-CHAR.
...
CALL X"F5" USING SOURCE-BYTE, BYTE-ARRAY.
...
*