HP OpenVMS Systems Documentation

HP COBOL
User Manual

Because lowercase is the names option default, the names upper option is only required to call C functions whose names contain uppercase letters, as described in Table 12-2.

For example, an HP COBOL program must be compiled with the names upper option to be able to call a C program named JOB1.

12.8.4.3 Calling COBOL Programs from C on Tru64 UNIX

The lower and upper options to the -names flag and /names= option apply to the PROGRAM-ID as well as to the literals used with CALL literal. This makes it possible for C programs to call HP COBOL programs with either lowercase or uppercase names, as described in Table 12-3.

The lower(case) and upper(case) options to the -names flag and /names= option preserve the semantics of calls among HP COBOL programs. However, the as_is option does not preserve these semantics. For example, the following code fragment will have different behavior if compiled with as_is.

PROGRAM ID JOB1.
CALL "Job2."
END-PROGRAM JOB1.
PROGRAM ID JOB2.
END-PROGRAM JOB2.

With the lower(case) and upper(case) options on the -names flag and /names= option, the program JOB2 will be called by JOB1. However, with the as_is option, the linker will look to resolve a call to "Job2"---which in this case is just as different as if it were named job3, WORLD99, or any other routine name other than JOB2. <>

12.8.5 Additional Information

On OpenVMS, for more detailed information on system services and Run-Time Library routines, refer to the following manuals in the OpenVMS documentation set:

• Material on calling system routines in the OpenVMS Programming Concepts Manual
• OpenVMS RTL Library (LIB$) Manual
• OpenVMS System Services Reference Manual

The following OpenVMS documentation mentioned in this chapter may also be of interest:

• HP OpenVMS Calling Standard
• Guide to Creating OpenVMS Modular Procedures <>

For more detailed information on programming in the Tru64 UNIX environment, refer to the following manuals in the Tru64 UNIX documentation set:

• Programmer's Guide
• Assembly Language Programmer's Guide
• Tru64 UNIX Calling Standard for Alpha Systems

Refer to also the following:

• The man pages for information on system service routines in Tru64 UNIX.
• Reading an Indexed File from Other Languages on Tru64 UNIX section in Chapter 6 of this manual
• HP COBOL Reference Manual, CALL and CANCEL sections <>

The HP COBOL compiler is part of the common language environment. This environment defines certain calling procedures and guidelines that allow you to call programs written in different languages or prewritten system routines from HP COBOL. You can call the following routine types from HP COBOL:

• Subprograms written in other languages supported by Alpha, I64 or VAX
• Run-Time Library routines
• OpenVMS system services
• Tru64 UNIX library routines

On Tru64 UNIX, your HP COBOL programs can also call routines written in other languages, including system services routines on Tru64 UNIX. These calls must conform to the Tru64 UNIX Calling Standard for Alpha Systems.

For information on Tru64 UNIX, refer to the Tru64 UNIX operating system documentation. Alternatively, use the man -k command to search through the man pages for topics. For example, to find all routines containing the string "curses," enter the following command:

%  man -k curses

The operating system will display information similar to the following:

curses (3)              - Library that controls cursor movement and windowing
curses_intro (3)        - Introduction to the curses routines which optimizes
                          terminal screen handling and updating
restartterm (3)         - Restart terminal for curses application        <>

The terms routine, procedure, and function are used throughout this chapter. A routine is a closed, ordered set of instructions that performs one or more specific tasks. Every routine has an entry point (the routine name) and optionally an argument list. Procedures and functions are specific types of routines: a procedure is a routine that does not return a value, whereas a function is a routine that returns a value by assigning that value to the function's identifier. In COBOL, routines are also referred to as subprograms and called programs.

System routines are prewritten operating system routines that perform common tasks, such as finding the square root of a number or allocating virtual memory. You can call any system routine from your program, provided that COBOL supports the data structures required to call the routine. The system routines used most often are Run-Time Library routines and system services.

For more information on system routines on OpenVMS Alpha and I64, refer to the OpenVMS RTL Library (LIB$) Manual and the OpenVMS System Services Reference Manual. <>

13.2 The OpenVMS Calling Standard (OpenVMS)

The HP OpenVMS Calling Standard and OpenVMS Programming Interfaces: Calling a System Routine (an archived manual still available on the documentation CD-ROM) describe the concepts used by all OpenVMS Alpha and VAX languages for invoking routines and passing data between them. The following attributes are specified by the HP OpenVMS Calling Standard:

• Register usage
• Stack usage
• Function value return
• Argument list

The following sections discuss these attributes in more detail. The HP OpenVMS Calling Standard also defines such attributes as the calling sequence, the argument data types and descriptor formats, condition handling, and stack unwinding. These attributes are discussed in detail in the OpenVMS Programming Concepts Manual.

13.2.1 Register and Stack Usage (Alpha, I64)

The OpenVMS Alpha and I64 architecture provides 32 general purpose integer registers (R0-R31) and 32 floating-point registers (F0-F31), each 64 bits in length. The OpenVMS Programming Interfaces: Calling a System Routine defines the use of these registers, as listed in Table 13-1.