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 name, cobcall, cobcancel, cobexit, cobfunc, and cobtidy are
provided to allow 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.
Name Function.
A C program can call a COBOL program in the same way as it would call
another C program. In the following example the COBOL program name is
called using the arguments a and b:
name (a, b);
Cobcall Function.
The cobcall function allows C programs to call COBOL programs.
Parameters are passed BY REFERENCE as follows:
cobcall (name, argc, argv)
char *name;
int argc;
char **argv;
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 Function.
The cobcancel function 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). Note that the return from cobcancel is undefined.
The format of this function is:
int cobcancel (name)
char *name;
Cobexit Function.
The cobexit library function 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. You must
use the cobexit functions to exit from non-COBOL modules back to UNIX
rather than just using "exit".
The format for this function is:
cobexit (exitstatus)
int exitstatus;
Cobfunc Function.
The cobfunc function has the same effect as specifying the previous two
examples, that is, it calls the specified program and then cancels it,
leaving the data contained in the program in its initial state. However,
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. Note that cobfunc returns the return code of the called program.
The format for this function is:
int cobfunc (name, argc, argv)
char *name;
int argc; char **argv;
Cobkeypad Function.
The cobkeypad function toggles the numeric keypad between local mode and
transmit mode. 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 (see Chapter 22 , Device Handling and
Terminfo). By default, the run-time system puts the numeric keypad into
transmit mode when smkx is present in your terminfo database.
The format for this function is:
cobkeypad(mode)
where:
mode is 1 for transmit mode or 0 for local mode.
Cobtidy Function.
The cobtidy library function tidies up the global COBOL run environment.
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 may use this function if you wish 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.
The format for this function is:
void cobtidy( );
Example Program.
The example 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
Library Routines
The following sections describe the library 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.
Cobsavenv 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. Note that
before calling coblongjmp, the status flag in the buffer may be set to a
non-zero value, thus allowing the value to be tested after the cobsavenv
call.
Restrictions
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 may be CALLed again later in the
program's run.
* coblongjmp cannot be used if a CHAIN has been made since cobsavenv
was last CALLed.
The parameter may be defined and used as follows:
#include setjmp.h
struct {
int cobbuf[24];
jmp_buf cbuf;
} 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 allow 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
* cobgetenv
* coblines
* cobmove
* cobprintf
* cobputenv
* cobrescanenv
* 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 Chapter 8 , 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
cobaddch
Displays the specified character on the screen at the virtual cursor's
current position.
This routine has the form:
void cobaddch (ch)
cobchtype ch;
where:
ch is the required character. This can include
attributes.
cobaddstr
Displays the specified string on the screen starting at the virtual
cursor's current position.
This routine has the form:
int cobaddstr (s)
cobchtype *s;
where:
s is 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.
This routine has the form:
int cobaddstrc (c)
char *c;
where:
c is the required string. This can be up to 255
characters long and can not 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.
This routine has the form:
void cobclear ( )
cobcols
Returns the number of columns on the screen.
This routine has the form:
int cobcols ( )
cobgetch
Gets a character from the keyboard.
This routine has the form:
int cobgetch ( )
cobgetenv
Provides the same functionality as the C library call getenv().
This routine has the form:
char * cobgetenv(char * name)
where:
name is the string to search the environment for. This
environment string will be in the following format:
NAME = VALUE
where NAME is the name specified in name. If NAME
is not found, a NULL value is returned.
coblines
Returns the number of lines on the screen.
This routine has the form:
int coblines ( )
cobmove
Moves the virtual cursor to the specified line and column on the screen.
This routine has the form:
void cobmove (y,x)
int y,x;
where:
y is the line number to move the virtual cursor to
x is the column number to move the virtual cursor to
cobprintf
Displays the specified formatted string on the screen at the virtual
cursor's current position.
This routine has the form:
int cobprintf (fmt)
char *fmt;
where:
fmt is the required 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).
This routine returns either the number of arguments output or -1 (for an
error condition).
cobputenv
Allows you to dynamically change the environment at run-time.
This routine has the form:
int cobputenv (char * string)
where:
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.
This routine returns a value of 0 if the operation was successful; any
other value indicates an unsuccessful operation. Note that illegal
environment names will lead to undefined results.
cobrescanenv
Causes the RTS to rescan the environment for file-name mapping entries.
This routine has the form:
void cobrescanenv()
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.
cobscroll
Scrolls the screen display, starting and finishing at the specified
lines, up one line.
This routine has the form:
void cobscroll (top,bot)
int top,bot;
where:
top is 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 is the last line to be scrolled up one line
Screen Handling Example.
The following example demonstrates calling a C routine directly from a
COBOL program using the cobgetenv routine.
* Example of direct calling of C routines from a COBOL program
* using cobgetenv, a general library routine.
$set rtncode-size(4)
* Note that 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 will pass 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 will pass 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 will pass 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). Note that if the size of the
* parameter being passed exceeds 4 bytes then it will be passed
* as if BY REFERENCE had been specified, also any numeric
* literals passed in this way will be 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.