HP OpenVMS Systems Documentation

HP COBOL
User Manual

When creating a shared library using ld , be aware of the following restrictions:

• Programs that are installed setuid or setgid will not use any libraries that have been installed using the inlib shell command, but only systemwide shared libraries (for security reasons).
• For other restrictions imposed by the operating system, refer to your operating system documentation. If you create a shared library that contains routines written in C, refer to your operating system documentation for any restrictions associated with the cc command.

Once the shared library is created, it must be installed before you run a program that refers to it. The following describes how you can install a shared library for private or systemwide use:

• To install a private shared library, such as for testing, set the environment variable LD_LIBRARY_PATH, as described in ld(1).
• To install a systemwide shared library, place the shared library file in one of the standard directory paths used by ld (see ld(1)).

For complete information on installing shared libraries, refer to your operating system documentation.

Specifying Shared Object Libraries

When you link your program with a shared library, all symbols must be referenced before ld searches the shared library, so you should always specify libraries at the end of the cobol command line after all file names. Unless you specify the -non_shared flag, shared libraries will be searched before the corresponding archive libraries.

For instance, the following command generates an error if the file rest.o references routines in the library libX :

% cobol -call_shared test.cob -lX rest.o

The correct order follows:

% cobol -call_shared test.cob rest.o -lX

Link errors can occur with symbols that are defined twice, as when both an archive and shared object are specified on the same command line. In general, specify any archive libraries after the last file name, followed by any shared libraries at the end of the command line.

Before you reference a shared library at run time, it must be installed.

1.1.3.7 Interpreting Messages from the Linker

If the linker detects any errors while linking object modules, it displays messages about their cause and severity. If any errors occur, the linker does not produce an image file.

Linker messages are descriptive, and you do not normally need additional information to determine the specific error. The general format for ld messages follows:

ld:
message-text

The message-text may be on multiple lines and is sometimes accompanied by a cobol error.

Some common errors that occur during linking resemble the following:

• An object module has compilation errors. This error occurs when you attempt to link a module that had warnings or errors during compilation. Although you can usually link compiled modules for which the compiler generated messages, you should verify that the modules will actually produce the output you expect.
• The modules being linked define more than one transfer address. The linker generates a warning if more than one main program has been defined. This can occur, for example, when an extra END statement exists in the program. The image file created by the linker in this case can be run; the entry point to which control is transferred is the first one that the linker found.
• A reference to a symbol name remains unresolved. This error occurs when you omit required module or library names from the cobol or ld command and the linker cannot locate the definition for a specified global symbol reference.

If an error occurs when you link modules, you may be able to correct it by retyping the command string and specifying the correct routines or libraries ( -l string flag, -L dir flag), or specify the object library or object modules on the command line.

1.1.4 Running an HP COBOL Program on Tru64 UNIX

The simplest form of the run command to execute a program is to type its file name at the operating system prompt, as follows:

% myprog.out

In addition to normal IO accesses, your HP COBOL programs can read command-line arguments and access (read and write) environment variables.

1.1.4.1 Accessing Command-Line Arguments

Command-line arguments allow you to provide information to a program at run time. Your program provides the logic to parse the command line, identify command-line options, and act upon them. For example, you might develop a program that will extract a given amount of data from a specified file, where both the number of records to read and the file name are highly dynamic, changing for each activation of your program. In this case your program would contain code that reads a command-line argument for the number of records to read, and a second argument for the file specification. Your program execution command could look like the following:

% myprog 1028 powers.dat

In the preceding example the program myprog would read 1028 records from the file powers.dat.

Multiple command-line arguments are delimited by spaces, as shown in the preceding example. If an argument itself contains spaces, enclose that argument in quotation marks (" ") as follows:

% myprog2 "all of this is argument 1" argument2

You provide definitions for the command-line arguments with the SPECIAL-NAMES paragraph in your program's Environment Division, and you include ACCEPT and DISPLAY statements in the Procedure Division to parse the command line and access the arguments. Detailed information about command-line argument capability is in the ACCEPT and DISPLAY sections in the HP COBOL Reference Manual.

1.1.4.2 Accessing Environment Variables

You can read and write environment variables at run time through your HP COBOL program.

Example 1-1 allows you to specify a file specification by putting the directory in the value of the environment variable COBOLPATH, and the file name in a command-line argument:

identification division.
PROGRAM-ID. MYPROG.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SYSERR              IS STANDARD-ERROR
    ENVIRONMENT-NAME    IS NAME-OF-ENVIRONMENT-VARIABLE
    ENVIRONMENT-VALUE   IS ENVIRONMENT-VARIABLE
    ARGUMENT-NUMBER     IS POS-OF-COMMAND-LINE-ARGUMENT
    ARGUMENT-VALUE      IS COMMAND-LINE-ARGUMENT.

DATA DIVISION.
WORKING-STORAGE SECTION.
01 howmany-records PIC 9(5).
01 env-dir PIC x(50).
01 file-name PIC x(50).
01 file-spec PIC x(100).
PROCEDURE DIVISION.
BEGIN.
  ACCEPT howmany-records FROM COMMAND-LINE-ARGUMENT
    ON EXCEPTION
      DISPLAY "No arguments specified"
        UPON STANDARD-ERROR
      END-DISPLAY
      STOP RUN
  END-ACCEPT.

  DISPLAY "COBOLPATH" UPON NAME-OF-ENVIRONMENT-VARIABLE.
  ACCEPT env-dir FROM ENVIRONMENT-VARIABLE
    ON EXCEPTION
      DISPLAY "Environment variable COBOLPATH is not set"
        UPON STANDARD-ERROR
      END-DISPLAY
    NOT ON EXCEPTION
      ACCEPT file-name FROM COMMAND-LINE-ARGUMENT
        ON EXCEPTION
          DISPLAY
          "Attempt to read beyond end of command line"
            UPON STANDARD-ERROR
          END-DISPLAY
        NOT ON EXCEPTION
          STRING env-dir "/" file-name delimited by " " into file-spec
          DISPLAY "Would have read " howmany-records " records from " file-spec
      END-ACCEPT
  END-ACCEPT.

This example requires that the following command has been executed to set an environment variable:

% setenv COBOLPATH /usr/files

When you execute the following command lines:

% cobol -o myprog myprog.cob
% myprog 1028 powers.dat

The following will result:

• howmany-records will contain "1028"
• env-dir will contain "/usr/files"
• file-name will contain "powers.dat"
• file-spec will contain "/usr/files/powers.dat"

For additional information, refer to the ACCEPT and DISPLAY statements in the HP COBOL Reference Manual.