HP 3000 Manuals HP 3000 Manuals
Interfacing - The Environment
This COBOL system provides various solutions to deal with the
mixed-language issues. These solutions come in the choice of run-time
libraries to be used for creating the mixed-language application and
additional syntax for dealing with the different calling conventions.
Advanced COBOL Syntax for Interfacing
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.
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 = 0 - parameters removed from stack by calling
program
= 1 - parameters removed from stack by called
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-15 reserved (always 0)
The standard C calling convention is represented by bits 0 and 1 being
zero.
For example, you could define the following:
special-names.
call-convention 0 is c
The mnemonic name defined can then be used to specify the convention to
be used on a call statement by:
call c "routine-name" using param-1,...,param-n
or on a Procedure Division header by:
procedure division c using param-1,...,param-n
If no call convention is specified then the standard COBOL convention is
assumed (CALL-CONVENTION 0).
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. A parameter passed by value can be up to 4 bytes long.
If no SIZE clause is specified, the number of bytes passed is determined
by the LITVAL-SIZE directive, which defaults to 4.
Example.
The statement:
call "routine-name" using by value 2 size 2.
passes a two-byte value of 2.
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:
COMP-X COBOL COMP-X data is stored with the most
significant byte first; that is, the most
significant byte is at the lowest address.
Although this is standard COBOL format, it
might not be the format used by your system.
For example, systems based on the Intel 80x86
processor store the most significant byte last.
COMP-5 COBOL COMP-5 is defined as native format. That
is, the number is stored in the same way that
the processor stores numbers. Using this data
type enables you to pass parameters directly
from COBOL to non-COBOL programs without
parameter conversion.
POINTER COBOL POINTER items are currently stored as
32-bit quantities in native byte format.
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.
PROCEDURE-POINTER COBOL PROCEDURE-POINTER items are currently
stored as 32-bit quantities in native byte
format.
NOTE Pointers and Procedure-pointers might change in future on systems
with more than 32-bit addressing. We recommend that you do not
redefine or process the information held in these data items other
than using the COBOL syntax supplied for setting, modifying and
using the data they hold.
Alignment of Parameters.
In languages such as C and assembler it is normal for numeric items to be
aligned on word or double-word boundaries. Provided you use the
ALIGNdirective with a parameter which is a multiple of four, all 01-level
items are aligned on a double word boundary.
If you are passing numeric parameters that are not 01 level 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.
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(8) COMP (unless the program has been compiled with the
RTNCODE-SIZE "2" directive when it is PIC S9(4) COMP) which, while being
suitable for COBOL-to-COBOL interprogram communication, is not really
suitable to deal with calls to non-COBOL subprograms.
A 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.