HP OpenVMS Systems Documentation

HP COBOL
User Manual

Using Transfer Vectors (VAX)

Using transfer vectors can be helpful when creating shareable images for the following reasons:

• They make it easy for you to modify the contents of shareable images.
• They allow you to avoid relinking user programs bound to the shareable image if you modify the image.

The command procedure in Example 1-5 shows how to create a transfer vector table and how to link the main program and subprograms (shown in Example 1-2) with the transfer vector table.

$!
$! Create a transfer vector table (TRAVEC.MAR).
$  MACRO /OBJ=TRAVEC SYS$INPUT
    .PSECT TRANSFER_VECTOR
;
;
; The transfer vector table is used to map entry points at
; run time to a shareable library. If you make changes to the
; shareable library, you only have to relink the library.
; You do not have to relink all the programs linked to the
; library.
;
; This example transfer vector table maps the entry points
; of the shareable subprograms: SUBSHR1, SUBSHR2.
;
    .TRANSFER   SUBSHR1
    .MASK       SUBSHR1
    BRW         SUBSHR1+2
    RET
    .QUAD
    .TRANSFER   SUBSHR2
    .MASK       SUBSHR2
    BRW         SUBSHR2+2
    RET
    .QUAD
;
; Note that there must be an entry point for each shareable image.
; Any future additions should be made at the end of the vector.
; The order of the entries must remain intact once established.
; Do not delete any entries (even if the shareable image is deleted).
$
$  LINK/SHARE=MYSHRLIB SUBSHR1,SUBSHR2,TRAVEC

Once you have created the transfer vector table, you can install the subprograms and link the main program to the shareable library as shown in Example 1-4.

For more information on transfer vectors, refer to the documentation on the OpenVMS Linker. <>

1.2.3.6 Interpreting Messages from the Linker

If the linker detects any errors while linking object modules, it displays system messages indicating their cause and severity. If any error or fatal error conditions occur, the linker does not produce an image file. Refer to the OpenVMS Linker Utility Manual for complete information about the format of linker options.

Linker messages are self-explanatory; you do not usually need additional information to determine the specific error.

Common Linking Errors to Avoid

The following are some common errors to avoid when linking COBOL programs:

• Trying to link a module that produced warning or error messages during compilation. Although you can usually link compiled modules for which the compiler generated system messages, you should verify that the modules actually produce the expected output during program execution.
• Forgetting to specify a file type for an input file that has a file type other than the default on the command line. The linker searches for a file that has a file type .OBJ by default. When the linker cannot locate an object file and you have not identified your input file with the appropriate file type, the linker signals an error message and does not produce an image file.
• Trying to link a nonexistent module. The linker signals an error message if you misspell a module name on the command line or if the compilation contains fatal messages.
• Omitting required module or library names from the command line. The linker cannot locate the definition for a specified global symbol reference.
  Consider, for example, the following LINK command for a main program module, OCEAN.OBJ, that calls the subprograms REEF, SHELLS, and SEAWEED:

  $ LINK OCEAN,REEF,SHELLS

  
  If the routine SEAWEED.OBJ does not exist in the directory from which the command is issued, an error occurs and the linker issues the following diagnostic messages:

  %LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, undefined symbol SEAWEED referenced in psect $CODE offset %X0000000C in module OCEAN file DEVICE$:[COBOL.EXAMPLES]PROG.OBJ;1 %LINK-W-USEUNDEF, undefined symbol SEAWEED referenced in psect $CODE offset %X00000021 in module OCEAN file DEVICE$:[COBOL.EXAMPLES]PROG.OBJ;1

  
  If an error occurs when you link modules, you can often correct it by reentering the command string and specifying the correct modules or libraries. For a complete list of linker options, refer to the OpenVMS Linker Utility Manual. For further information on a particular linker message, refer to the online OpenVMS Help Message utility.

After you compile and link your program, use the RUN command to execute it. In its simplest form the RUN command has the following format:

$ RUN myprog

In the preceding example MYPROG.EXE is the file specification of the image you want to run. If you omit the file type from the file specification, the system automatically provides a default value. The default file type is .EXE. If you omit a path specification, the system will expect MYPROG.EXE to be in the current directory.

When you run your application it makes calls to the HP COBOL Run-Time Library (RTL) installed on your system. If your application is run on a system other than the one where the application was compiled, there are two requirements that must be met:

• The HP COBOL Run-Time Library must be installed.
• The RTL version must match (or be higher than) the version of the RTL on the system where the application was compiled. Otherwise, the system displays a diagnostic message each time you run the application.

Your HP COBOL programs can read command-line arguments and access (read and write) system logicals. Command-line arguments enable 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 named MYPROG 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.

To run the program with command-line arguments, you must define it as a foreign command, as follows:

$ MYPROG :== "$device:[dir]MYPROG.EXE"

When you use this command, you will replace device and dir with the valid device:[dir] names where MYPROG.EXE is located. Your program execution command could then look like the following:

$ MYPROG 1028 POWERS.DAT

In this hypothetical case, the program MYPROG would read 1,028 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

In this example the returned value of argument1 will be the entire string "all of this is argument1", and argument2 will be simply "argument2".

You provide definitions for the command-line arguments with the
SPECIAL-NAMES paragraph in your program's Environment Division, and 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.2.4.2 Accessing System Logicals at Run Time (Alpha, I64)

You can read and write system logicals at run time through your HP COBOL program.

Example 1-6 allows the user to specify a file specification by putting the directory in the value of the logical COBOLPATH and the file name in a command-line argument.

IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMPLE.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SYSERR              IS STANDARD-ERROR
    ENVIRONMENT-NAME    IS NAME-OF-LOGICAL
    ENVIRONMENT-VALUE   IS LOGICAL-VALUE
    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
        STOP RUN
    END-ACCEPT.

    DISPLAY "COBOLPATH" UPON NAME-OF-LOGICAL.
    ACCEPT env-dir FROM LOGICAL-VALUE
      ON EXCEPTION
        DISPLAY "Logical 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.