Calling C Programs via the Direct Method

The direct method allows you to pass arguments to C functions without writing special interfacing routines. Parameters are passed directly to the C function according to the CALL statement that invoked the function, using the standard C calling conventions. This direct method simulates the actions of a native code compiler such as Micro Focus or VAX/COBOL.

Note:

The runtime has an internal limit of 30 parameters that it can pass to a C routine called through the direct method; it aborts if more than 30 parameters are passed and suggests ways to work around the abort. You can change this limit by modifying the file "lib/callc.c" and relinking the runtime.

Use the BY VALUE phrase of the CALL statement to pass numeric parameters in a way that is compatible with C calling conventions. Use the BY REFERENCE phrase to pass address parameters.

With the direct method, using BY VALUE causes the actual value to be passed to the routine (as expected). Using NULL causes binary zeros to be passed to the routine (matching the NULL concept in C). With the direct method, passing a zero BY VALUE is much the same as specifying NULL (contrast this with the corresponding note under the interface method described in the topic Calling C Programs via the Interface Method).

When a C function is called by the direct method, its return value is placed in the special register RETURN-CODE.

You should note that the direct method makes it easy to generate memory access violations. You may omit a BY REFERENCE or BY VALUE phrase or forget to terminate strings properly with a NULL value (as required by C).

To use the direct method, add the name of the C function to be called to DIRECTTABLE in the file "direct.c". The table has three columns:

In the first column, place the name you want to use in the COBOL CALL statement. Use all uppercase characters, and place the name in quotation marks.
In the second column, place the address of the routine to be called. (You can accomplish this by specifying "FUNC" followed by the exact name of the routine as declared in C. "FUNC" is a macro that generates the appropriate cast of the routine name.)
In the third column, place the function's return type, which may be one of these seven types:
```
C_int
C_long
C_unsigned
C_pointer
C_short
C_void
C_char
```

You may need to prototype the function if it is not prototyped in an included header file. For example, to call the C function "open" directly, you would include the following code in the "direct.c" file:

extern int open();
struct  DIRECTTABLE LIBDIRECT[] = {
    { "OPEN",  FUNC open,  C_int }, 
    {NULL,     NULL,       0 }
    };

After you make the change to "direct.c", be sure to relink the runtime system.

To use the "open" function in COBOL, you might do something like this:

77   FILE-NAME      PIC X(20)
77   FILE-HANDLE    SIGNED-INT

MOVE "myfile" TO FILE-NAME.
INSPECT FILE-NAME REPLACING TRAILING SPACES 
     BY LOW-VALUES.
CALL "OPEN" USING BY REFERENCE FILE-NAME BY VALUE 0.
MOVE RETURN-CODE TO FILE-HANDLE.

Note:

Strings passed to C routines should have LOW-VALUE terminators. Variables that are not passed by address should have the BY VALUE qualifier in COBOL and should be COMP-5 or one of the C data types.

In the example above, FILE-NAME cannot be more than 19 characters, because the 20th, or last, character must be the string terminator.

Up to 20 parameters may be passed via the direct method. If you need to pass more than 20, call our Technical Support and request the routine "callc.c". The comments within the code explain how to use the "callc.c" routine.

External C variables and system functions can also be linked with COBOL EXTERNAL data items. One function in particular called "ERRNO" can be used to obtain error information from those system functions. The runtime exports the errno variable so that COBOL programs can reference it easily and without requiring a relink.

ERRNO should be shown as defined as:

77  ERRNO EXTERNAL SIGNED-INT.

Consult your preferred C manual for information on using ERRNO.