PreviousNational Language Support (NLS) Demonstration Mixed-language ProgrammingNext"

Chapter 9: The COBOL Interfacing Environment

Working in a mixed-language environment requires that the run-time support and program interfaces between programs from those different language compilers are consistent. Server Express can compile COBOL programs to standard native object code (.o) files, of the same type as those produced by many other language compilers. This makes it possible to create applications using subprograms written both in COBOL and in other languages.

This chapter explains the call mechanism provided by Server Express to help you interface between COBOL and other languages. It describes the problems encountered in interfacing between COBOL and other languages and describes the solutions provided by this COBOL system. You do not need to read this chapter for COBOL-to-COBOL calls.

When you have read this chapter, see the chapter Mixed-language Programming for specific details on interfacing between COBOL and the following:

9.1 Interfacing - The Issues

This section considers some of the basic issues involved in mixed-language working so you can get a better understanding of how and when to use the special COBOL syntax for overcoming these problems. It also describes the choice of run-time libraries provided with this COBOL system to be used for creating a mixed-language application as well as the additional syntax available for dealing with the different calling conventions.

You should also see the chapters:

9.1.1 Calling Interface Compatibility

In order for a call to work it is important that both calling program and called subprogram obey the same rules. The most important of these rules govern:

If the calling program and the called subprogram do not obey the same protocol, the application is liable to crash when the call is made.

9.1.1.1 Parameter Ordering

Parameters are always passed by pushing the parameters onto the stack before calling the subprogram. The parameters can be pushed onto the stack by either processing the list of call parameters from right-to-left (reverse order) or from left-to-right (order specified). The first of these methods is the convention used by COBOL and by C.

9.1.1.2 Parameter Format

COBOL supports two methods of passing parameters to a subprogram in a mixed-language environment.

Method
Format
by reference Passes an address (offset). Any changes made to the parameter by the subprogram is reflected in the calling program.
by value Passes only the value of the parameter to the subprogram. Any changes made to the parameter in the subprogram are not reflected in the calling program.

9.2 Interfacing - The Environment

This COBOL system provides various solutions to deal with the mixed-language issues. These solutions are provided by additional syntax for dealing with the different calling conventions.

Your Language Reference describes COBOL syntax intended to deal with the various program-to-program interface issues described earlier. The following sections explain how to use some of these features.

9.2.1 Call Conventions

The CALL-CONVENTION syntax can be used to control which mechanisms the COBOL program should use when calling a subprogram, or which mechanisms it expects to have been used by the program which calls it. Each calling convention you want to use should be declared in the Special-Names paragraph. Here you can assign one of the call convention numbers, defined below, to a user-defined mnemonic name for later use.

The call convention number is a 16-bit number defined as follows:

Bit
Meaning
0
0 Process parameters from right-to-left
1 Process parameters from left-to-right
1 Reserved. Should be set to 0.
2
0 RETURN-CODE is updated on exit
1 RETURN-CODE is not updated on exit
Any RETURNING phrase is not affected by this bit.
3
0 Normal linking behavior
1 Call is resolved at link time
4-15 Reserved. Should be set to 0

For example, you could define the following:

 special-names.
     call-convention 0 is c-callconv
     

The mnemonic-name defined could then be used to specify the convention to be used on a CALL statement by:

     call c-callconv "routine-name" using param-1,...,param-n

or to specify the convention that this program should expect to be called with by using the syntax:

 procedure division c-callconv using param-1,...,param-n

If no call convention is specified, the standard COBOL convention is assumed (CALL-CONVENTION 0).

9.2.2 Using BY VALUE Parameters

A parameter which is to be passed or received by value should be preceded by the BY VALUE phrase as documented in your Language Reference. You should ensure that any parameter passed by value is always an even number of bytes. The value of any parameter passed by value is always pushed onto the stack so that the lowest addressed byte is the last to be pushed.

If no SIZE clause is specified, the number of bytes passed is determined by the LITVAL-SIZE directive, which defaults to four.

Example:

The statement:

     call "routine-name" using by value 2 size 4.

passes a four-byte integer of value 2.

9.2.3 Storage Representation of COBOL Data Types

The format for most of the COBOL data types is described in the Language Reference. The following data types are the types which are relevant to mixed-language programming:

USAGE
Storage Representation
COMP-X The standard COBOL format. Data is stored with the most significant byte first; that is, the most significant byte is at the lowest address.
COMP-5 Data is stored in the order defined by the chip. You should use this if you call non-COBOL programs or APIs.

Pointer variables are extremely useful for holding the address of a dynamically allocated memory area. COBOL programs can then access this memory using the SET ADDRESS statement.

9.2.4 Aligning Parameters

In languages such as C it is normal for numeric items to be aligned on word or double-word boundaries. Provided you use the ALIGN directive with a parameter which is a multiple of four, all 01-level items are aligned on a double word boundary.

The Compiler uses ALIGN"8" by default.

If you are passing numeric parameters that are not level-01 data items in the COBOL program, or are in a parameter block passed as a single item, it is important that you make sure they are correctly aligned.

9.2.5 Handling Return Codes

There are two different methods for handling return codes passed back from a called subprogram to the calling program. The first method is to make use of the COBOL special register, RETURN-CODE. The register is given a value in the COBOL subprogram before that subprogram passes control back to the COBOL calling program with an EXIT PROGRAM or GOBACK statement. The RETURN-CODE register of the calling program is then automatically updated with the subprogram's return code and this register can be examined accordingly. The RETURN-CODE register is predefined as PIC S9(4) COMP (unless the program has been compiled with the RTNCODE-SIZE "4" directive when it is PIC S9(8) COMP) which, while being suitable for COBOL-to-COBOL interprogram communication, is not really flexible enough to deal with calls to non-COBOL subprograms.

The preferred, and more flexible, way of handling return codes to and from COBOL programs in mixed-language applications is to make use of the RETURNING phrase on the CALL, EXIT PROGRAM, GOBACK, STOP RUN statements. This syntax enables you to define the format of the return code yourself and so cope with whatever size of return code you require.

9.3 Example of Calling Standard C Library function

$set rtncode-size"4"
 working-storage section.

 01 my-c-string          pic x(80) value z"Hello world".
 01 my-c-len             pic s9(9) comp-5.

 procedure division.

     call "strlen" using
                   by reference my-c-string,
                   returning my-c-len
     end-call

     display "my-c-string is " my-c-len " chars long"
     display "my-c-string is: " my-c-string(1:my-c-len)

9.4 For More Information

For details of Compiler directives see the chapter Directives for Compiler in your Server Express User Guide. For details of COBOL syntax see your Language Reference.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousNational Language Support (NLS) Demonstration Mixed-language ProgrammingNext"