HP 3000 Manuals HP 3000 Manuals
Mixing C and COBOL Programs
The Micro Focus COBOL system provides a number of C functions and COBOL
library routines to enable you to mix C and COBOL programs.
C Functions
The functions cobcall, cobcancel, cobexit, cobfunc and cobtidy, are
provided to enable you to mix C and COBOL programs in an application.
Descriptions of these routines are contained in the following sections.
The cobkeypad function, which enables you to determine the mode of your
numeric keypad, is also described.
A C program can call a COBOL program in the same way as it would call
another C program. In the following example of C code the COBOL program
name is called using the arguments a and b:
name (a, b);
cobcall
Enables C programs to call COBOL programs. Parameters are passed BY
REFERENCE.
Syntax:.
cobcall (name, argc, argv)
char *name;
int argc;
char **argv;
Remarks:.
This function is used to call the COBOL program name using the arguments
given in argv. cobcall is a COBOL type call as defined in the ANSI '74
standard and behaves in the same way as if the COBOL subprogram had been
called from COBOL.
cobcancel
Cancels the COBOL program name previously called. This leaves the data
contained in this program in the initial state as defined for the COBOL
CANCEL verb (see your Language Reference for details).
Syntax:.
int cobcancel (name)
char *name;
Remarks:.
The return from cobcancel is undefined.
cobexit
Closes down the global COBOL run environment. It terminates the
program's run in the same way as if a COBOL STOP RUN statement had been
executed, emptying buffers, closing files and freeing any data areas
allocated by the COBOL system.
Syntax:.
cobexit (exitstatus)
int exitstatus;
Remarks:.
You must use the cobexit functions to exit from non-COBOL modules back to
UNIX rather than just using "exit".
cobfunc
The cobfunc function has the same effect as specifying cobcall then
cobcancel. That is, it calls the specified program and then cancels it,
leaving the data contained in the program in its initial state.
Syntax:.
int cobfunc (name, argc, argv)
char *name;
int argc; char **argv;
Remarks:.
This function, unlike the previous example, causes the program to behave
as if it had been called using C function rules rather than COBOL call
rules. cobfunc returns the return code of the called program.
cobkeypad
Toggles the numeric keypad between local mode and transmit mode.
Syntax:.
cobkeypad(mode)
Parameters:.
mode 1 for transmit mode 0 for local mode.
Remarks:.
To function correctly, the smkx (transmit mode) and rmkx (local mode)
entries must be present in the terminfo database for the terminal type
you are using. By default, the run-time system puts the numeric keypad
into transmit mode when smkx is present in your terminfo database.
cobtidy
Tidies up the global COBOL run environment.
Syntax:.
void cobtidy( );
Remarks:.
You can call this function from non-COBOL modules to empty buffers, close
files and free any data areas allocated by the COBOL system. You should
call this function when all COBOL modules have been exited, and you do
not intend to reenter them. You can use this function if you want to
close down the COBOL system, but are not yet ready to exit to UNIX. Do
not call cobtidy( ) directly from a COBOL program, as this gives
undefined results.
Sample Program.
The sample program account.cbl is located in $COBDIR/demo. It
demonstrates a C program calling a COBOL program. It shows:
* how to pass a string from C to COBOL
* how to pass a number from C to COBOL
* how a called COBOL program can keep its data active
* how to make use of the powerful COBOL editing facilities from C
* how to animate a COBOL program called from C
* how to use the symbolic debugger sdb to debug a C program calling
COBOL
Miscellaneous Routines
The following sections describe the routines cobsavenv and coblongjmp,
which enable you to mix C and COBOL programs. They provide functions
similar to the C routines setjmp and longjmp (see your UNIX Programmer's
Manual for details of setjmp and longjmp). The purpose of these library
routines is to provide the capability of a non-local GO TO, for use in
error or exception handling.
cobsavenv and coblongjmp.
The cobsavenv routine is called with a single parameter. This routine
saves the environment of the current COBOL program in the buffer provided
by the parameter, and returns immediately with the status flag set to 0.
A subsequent call to coblongjmp either from elsewhere in the program
which called cobsavenv, or from one of its subprograms, causes execution
to be resumed at the point immediately after the call to cobsavenv.
Before calling coblongjmp, the status flag in the buffer can be set to a
non-zero value, thus enabling the value to be tested after the cobsavenv
call.
Remarks:.
The following restrictions apply when using these routines:
* cobsavenv and coblongjmp can be called only from a C program; they
cannot be called from COBOL.
* coblongjmp must be called from the same or from a lower level in
the CALL/PERFORM hierarchy of control flow as cobsavenv was. In
the intervening time, control must not have been returned to a
higher level. Specifically, control must not have been returned
from the C program that called cobsavenv.
* If coblongjmp returns control to a different call level than
cobsavenv used, programs exited by this mechanism appear to have
been exited normally and can be called again later in the
program's run.
* coblongjmp cannot be used if a CHAIN has been made since cobsavenv
was last called.
Example:.
The parameter can be defined and used as follows:
#include setjmp.h
struct {
int cobbuf[3];
char* cobbuf2[3];
jmp_buf cbuf;
char* cobbuf3;
} cobjmp_buf;
*
*
*
if (setjmp(cobsavenv(&cobjmp_buf)) !=0)
{
printf("Returned from coblongjmp\n");
}
*
*
*
coblongjmp(&cobjmp_buf);
Screen Handling from C.
The Micro Focus COBOL system supports a number of screen handling
routines which can be used from C programs. These enable the RTS and
run-time support libraries to handle output from both C programs called
from COBOL programs and from ACCEPT/DISPLAY operations performed by the
calling COBOL programs. Normally if any screen handling is carried out
outside of the control of COBOL (for example, under the control of C)
COBOL is not aware of the output from the screen handling operation when
control returns to COBOL. The effect of subsequent screen handling
operations could thus be undefined. The routines described below enable
you to avoid this problem.
The routines currently supported are:
cobaddch
cobaddstr
cobaddstrc
cobclear
cobcols
cobgetch
coblines
cobmove
cobprintf
cobscroll
These routines are described in the following sections:
When using any of these routines you must include the header file
cobscreen.h
, which is provided with this COBOL system. This file defines the
attributes you can use, the type (cobchtype)
and declares any external functions the routine needs. The type
cobchtype defines a two-byte pair, with the first byte containing a
character and the second the attribute for that character.
For those routines where attributes are allowed, you can use the bit-wise
OR operator to combine any of the attributes defined in the cobscreen.h
file (see the chapter Library Routines (Call-by-name) for details of the
CBL_OR routine). These attributes are listed below:
Attribute Description
A_NORMAL Normal, no attribute
A_BOLD Bold or highlight
A_UNDER Underline
A_REVERSE Reverse
A_BLINK Blink
Several of these routines have been replaced by COBOL System Library
Routines, described in your COBOL System Reference, which you should use
in preference.
cobaddch
Displays the specified character on the screen at the virtual cursor's
current position.
Syntax:.
void cobaddch (ch)
cobchtype ch;
Parameters:.
ch The required character. This can include
attributes.
cobaddstr
Displays the specified string on the screen starting at the virtual
cursor's current position.
Syntax:.
int cobaddstr (s)
cobchtype *s;
Parameters:.
s The required string. This can be up to 255
characters long and can include attributes. The
only control character that s can include is \n
(new line).
cobaddstrc
Displays the specified string on the screen starting at the virtual
cursor's current position.
Syntax:.
int cobaddstrc (c)
char *c;
Parameters:.
c The required string. This can be up to 255
characters long and cannot include attributes; the
normal attribute is used. The only control
character that s can include is \n (new line).
cobclear
Clears the screen and positions the cursor at line 0, column 0.
Syntax:.
void cobclear ( )
Remarks:.
The COBOL system library routine CBL_CLEAR_SCREEN has the same effect and
should be used in preference to cobclear.
cobcols
Returns the number of columns on the screen.
Syntax:.
int cobcols ( )
Remarks:.
The COBOL system library routine CBL_GET_SCR_SIZE has the same effect and
should be used in preference to cobcols.
cobgetch
Gets a character from the keyboard.
Syntax:.
int cobgetch ( )
Remarks:.
The COBOL system library routine CBL_READ_KBD_CHAR has the same effect
and should be used in preference to cobgetch.
coblines
Returns the number of lines on the screen.
Syntax:.
int coblines ( )
Remarks:.
The COBOL system library routine CBL_GET_SCR_SIZE has the same effect and
should be used in preference to coblines.
cobmove
Moves the virtual cursor to the specified line and column on the screen.
Syntax:.
void cobmove (y,x)
int y,x;
Parameters:.
y The line number to move the virtual cursor to
x The column number to move the virtual cursor to
Remarks:.
The COBOL system library routine CBL_GET_SCR_POS has the same effect and
should be used in preference to cobmove.
cobprintf
Displays the specified formatted string on the screen at the virtual
cursor's current position.
Syntax:.
int cobprintf (fmt)
char *fmt;
Parameters:.
fmt The required format in printf() style. This can be
a maximum of 255 characters long in its extended
form, and cannot include attributes. The only
control character can contain is \n (new line).
Remarks:.
This routine returns either the number of arguments output or -1 (for an
error condition).
cobscroll
Scrolls the screen display, starting and finishing at the specified
lines, up one line.
Syntax:.
void cobscroll (top,bot)
int top,bot;
Parameters:.
top The first line to be scrolled up one line. This
must be two lines less than the physical screen
size to prevent the top line from scrolling off the
screen.
bot The last line to be scrolled up one line
Environment Handling
The following routines enable you to read and change the environment at
run time. They should only be called from C. In COBOL, the syntax:
DISPLAY ... UPON ENVIRONMENT-NAME ...
ACCEPT ... FROM ENVIRONMENT-NAME ...
enables you do the same things, and should be used in preference to these
routines.
* cobgetenv
* cobputenv
* cobrescanenv
cobgetenv
Provides the same functionality as the C library call getenv().
Syntax:.
char * cobgetenv(char * name)
Parameters:.
name The string to search the environment for. This
environment string is in the following format:
NAME = VALUE
where NAME is the name specified in name. If NAME
is not found, a NULL value is returned.
cobputenv
Allows you to dynamically change the environment at run time.
Syntax:.
int cobputenv (char * string)
Parameters:.
string The value of string is placed in the environment,
which the RTS then rescans for file-name mapping
variables. By convention, environment strings have
the format:
NAME = VALUE
but the RTS does not check that string is in this
format.
Remarks:.
string is passed into the C library call putenv(), and so the value of
string cannot be modified or freed (if at all) until the environment
variable has been redefined using another cobputenv. So, for example, if
cobputenv is called from a COBOL subprogram then the subprogram must not
be canceled.
This routine returns a value of 0 if the operation was successful; any
other value indicates an unsuccessful operation. Illegal environment
names lead to undefined results.
cobrescanenv
Causes the RTS to rescan the environment for file-name mapping entries.
Syntax:.
void cobrescanenv()
Remarks:.
This routine is useful if the environment has been changed without the
knowledge of the RTS. It returns a value of 0 if the call was successful;
any other value indicates an unsuccessful call.
Example.
The following example demonstrates calling a C routine directly from a
COBOL program using the cobgetenv routine. (This is only for example
purposes. We recommend you do not use cobgetenv from COBOL.) It also
shows how the C data item errno
may be accessed.
* Example of direct calling of C routines from a COBOL program
* using cobgetenv, a general library routine.
$set rtncode-size(4)
* The return code size of 4 bytes is required for
* returning a pointer to set the compiler directive.
working-storage section.
01 sleep-time pic 9(9) comp-5 value 10.
01 errno is external pic 9(9) comp-5.
* errno is the external Unix data item to which the error number
* returned by a Unix System service Routine is assigned.
01 cobdir pic x(100) value spaces.
01 env-name pic x(100).
01 return-pointer usage pointer.
linkage section.
01 name-buff pic x(100).
* Linkage items have no physical storage but the names can be
* used to reference addresses given by the SET verb.
* Return-pointer is used to dereference the pointer and set
* name-buf to point to the character string associated with the
* pointer returned by the call to cobgetenv.
procedure division.
get-cobdir section.
move 0 to errno
* "cobgetenv" expects a pointer to an array of characters
* terminated by a low-value.
* COBOL can pass its parameters by REFERENCE, CONTENT or VALUE:
* By REFERENCE passes to the function the address of the
* parameter (in C a PIC X(n) would look like a char*, except it
* would not be NULL terminated).
* By CONTENT passes to the function the address of a
* temporary data item (to which there is an implied move from
* the parameter before the call is made).
* The only difference between by CONTENT and by REFERENCE is
* that the called module cannot effect the value of the
* parameter as seen from the calling module.
* By VALUE passes to the function the actual value of the
* data item rather than its address. By VALUE should only be
* used to call non-COBOL modules (because the PROCEDURE DIVISION
* USING statement has no way of specifying that a VALUE
* parameter is to be expected). If the size of the
* parameter being passed exceeds 4 bytes then it is passed
* as if BY REFERENCE had been specified, also any numeric
* literals passed in this way are passed to the called
* module as a 4 byte comp numeric in machine byte order (in C as
* a long on a 32 bit machine).
* Ensure that parameter to "cobgetenv" is NULL terminated.
string "COBDIR" low-values
delimited by size into env-name
call "cobgetenv" using env-name returning return-pointer
if return-pointer = null
display "COBDIR not found"
stop run
end-if
set address of name-buff to return-pointer
* Function result of "cobgetenv" is a NULL terminated string,
* COBOL requires SPACE termination.
string name-buff delimited by low-values into cobdir
display cobdir
call "sleep" using by value sleep-time
display "that was a nice sleep"
stop run.