HP OpenVMS Systems Documentation

Content starts here

User Manual

Previous Contents Index Calling C Programs from HP COBOL on Tru64 UNIX

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.

Table 12-2 C Routine Called by Statement: CALL" Job1"
Routine Called
-names lowercase
job1() {}
-names uppercase
JOB1() {}
-names as_is
Job1() {}

For example, an HP COBOL program must be compiled with the names upper option to be able to call a C program named JOB1. 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.

Table 12-3 C Invocation to Call COBOL PROGRAM-ID" Job2"
Routine Called
-names lowercase
-names uppercase
-names as_is
not possible

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.

CALL "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:

Chapter 13
Using HP COBOL in the Alpha, I64, or VAX Common Language Environment

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        <>

13.1 Routines, Procedures, and Functions

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.

Table 13-1 OpenVMS Alpha and I64 Register Usage
Register Use
R0 Function value return register (see also F0, F1)
R1 Conventional scratch register
R2-R15 Conventional saved registers
R16-R21 Argument registers, one register per argument, additional arguments are placed on the stack
R22-R24 Conventional scratch registers
R25 Argument information (AI); contains argument count and argument type
R26 Return address (RA) register
R27 Procedure value (PV) register
R28 Volatile scratch register
R29 Frame pointer (FP)
R30 Stack pointer (SP)
R31 Read As Zero/Sink (RZ) register
PC Program counter
F0,F1 Function value return registers for floating-point values (F1 is used if floating-point data exceeds 8 bytes)
F2-F9 Conventional saved registers for floating-point values
F10-F15 Conventional scratch registers for floating-point values
F16-F21 Argument registers for floating-point values (one per argument, additional arguments are placed on the stack)
F22-F30 Conventional scratch registers
F31 Read As Zero/Sink (RZ) register

Previous Next Contents Index