To create a shared library, first create the .o file, such as octagon.o in the following example:

% cobol -O3 -c octagon.cob

The file octagon.o is then used as input to the ld command to create the shared library, named octagon.so :

% ld -shared -no_archive octagon.o \ -lcob -lcurses -lFutil -lots2 -lots -lisam -lsort -lexc -lmld -lm

A description of each ld flag follows:

• The -shared flag is required to create a shared library.
• The -no_archive flag indicates that ld should not search archive libraries to resolve external names (only shared libraries).
• The name of the object module is octagon.o . You can specify multiple .o files.
• The -lcob and subsequent flags are the standard list of libraries that the COBOL command would have otherwise passed to ld . When you create a shared library, all symbols must be resolved. For more information about the standard list of libraries used by Compaq COBOL, see Section 1.1.3.2.

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 a Compaq 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 Compaq 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 Compaq COBOL Reference Manual.

1.1.4.2 Accessing Environment Variables

You can read and write environment variables at run time through your Compaq 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:

Example 1-1 Accessing Environment Variables and Command-Line Arguments

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 Compaq COBOL Reference Manual.

1.1.4.3 Errors and Switches

See Section 1.4 for a discussion of errors that can cause incorrect or undesirable results when you run a program.

See Section 1.5 for a discussion of controlling program execution with switches.

1.1.5 Program Development Stages and Tools

This manual primarily addresses the program development activities associated with development and testing phases. For information about topics usually considered during application design, specification, and maintenance, refer to your operating system documentation, appropriate reference pages, or appropriate commercially published documentation.

Table 1-3 lists and describes some of the software tools you can use when developing and testing a program.

Table 1-3 Main Tools for Program Development and Testing

Task or Activity	Tool and Description
Manage source files	Use RCS or sccs to manage source files. For more information, refer to the Tru64 UNIX documentation on programming support tools or the appropriate reference page.
Create and modify source files	Use a text editor, such as vi , emacs , or another editor. For more information, refer to your operating system documentation.
Analyze source code	Use searching commands such as grep and diff . For more information, refer to the Tru64 UNIX documentation on programming support tools or the appropriate reference page.
Build program (compile and link)	You can use the cobol command to create small programs, perhaps using shell scripts, or use the make command to build your application in an automated fashion using a makefile. For more information on make , refer to the make(1) reference page and the Tru64 UNIX documentation on programming support tools.
Debug and test program	Use the Ladebug Debugger to debug your program or run it for general testing. For more information on Ladebug Debugger, refer to the Ladebug Debugger Manual.
Install program	Use setld and related commands such as tar . For more information, refer to the Tru64 UNIX documentation on programming support tools.

In addition, you might use the following shell commands at various times during program development:

• To view information about an object file or an object library, use the following commands:
  • The file command shows the type of a file (such as which programming language, whether it is an object library, ASCII file, and so forth).
  • The nm command (perhaps with the -a or -o flag) shows symbol table information, including the identification field of each object file.
  • The odump command shows the contents of a file and other information.
  • The size command shows the size of the code and data sections.
  
  For more information on these commands, refer to the appropriate reference page or the Tru64 UNIX documentation on programming support tools.
• Use the ar command to create an archive object library ( -r flag), maintain the modules in the library, list the modules in the library ( -t ), and perform other functions. Use -ts to add a table of contents to the object library for linking purposes. For more information, refer to ar(1) or the Tru64 UNIX programmer's documentation.
• To create shared libraries on Tru64 UNIX systems, use ld , not the ar command. For more information, see Section 1.1.3.4 and refer to the Tru64 UNIX programmer's documentation.
• The strip command removes symbolic and other debugging information to minimize image size. For additional information, refer to the strip(1) reference page.

In most instances, use the cobol command to invoke both the Compaq COBOL compiler and the ld linker. To link one or more object files created by the Compaq COBOL compiler, you should use the cobol command instead of the ld command, because the cobol command automatically references the appropriate Compaq COBOL Run-Time Libraries when it invokes ld . If the executable image is not in your current working directory, specify the directory path in addition to the file name.

Compilation does the following for you:

• Detects errors in your program syntax
• Displays compiler messages on your terminal screen
• Generates machine language instructions from valid source statements
• Groups the instructions into an object module for the linker
• Launches the linker with the compiled file or files
• Creates an executable image

You use the cobol command to compile and link your program. The cobol command invokes the Compaq COBOL compiler driver that is the actual user interface to the Compaq COBOL compiler. The compiler driver can accept command options and multiple file names, and normally causes the compiler and linker to process each file. A variety of qualifiers to the compile command are available to specify optional processing and to specify the names of output files.

After the Compaq COBOL compiler processes the source files to create one or more object files, the compiler driver passes a list of object files and other information to the linker. <>

1.2 Developing Programs on OpenVMS

You use DCL commands (commands used at the OpenVMS system prompt) to create, compile, link, and run Compaq COBOL programs on OpenVMS systems.

1.2.1 Creating a Compaq COBOL Program on OpenVMS

To create and modify a Compaq COBOL program, you must invoke a text editor. The default editor for OpenVMS is the Text Processing Utility (TPU). Other editors, such as EDT or the Language-Sensitive Editor (LSE), may be available on your system. Check with your system administrator and refer to the OpenVMS EDT Reference Manual (this manual has been archived but is available on the OpenVMS Documentation CD-ROM) for more information about EDT or the Guide to Language-Sensitive Editor for additional information about LSE.

Figure 1-2 shows the basic steps in Compaq COBOL program development.

Figure 1-2 DCL Commands for Developing Programs

Use the text editor of your preference to create and revise your source files. For example, the following command line invokes the TPU editor and creates the source file PROG_1.COB:

$ EDIT PROG_1.COB

The file type .COB is used to indicate that you are creating a Compaq COBOL program. COB is the default file type for all Compaq COBOL programs.

The COPY Statement, Dictionaries and Libraries

Including the COPY statement in your program allows separate programs to share common source text, reducing development and testing time as well as storage requirements. You can use the COPY statement to access modules in libraries. The COPY statement causes the compiler to read the file or module specified during the compilation of a program. When the compiler reaches the end of the included text, it resumes reading from the previous input file.

By using the /INCLUDE qualifier on the COBOL command line, you can set up a search list for files specified by the COPY statement. For more information, refer to the Compaq COBOL Reference Manual.

You can use the COPY FROM DICTIONARY statement in your program to access a data dictionary and copy Oracle CDD/Repository record descriptions into your program as COBOL record descriptions. Before you can copy record descriptions from Oracle CDD/Repository, you must create the record descriptions using the Common Data Dictionary Language (CDDL) or Common Dictionary Operator (CDO).

For more information about using Oracle CDD/Repository and creating and maintaining text libraries, refer to the Compaq COBOL Reference Manual and Using Oracle CDD/Repository on OpenVMS Systems.

1.2.2 Compiling a Compaq COBOL Program on OpenVMS

To compile your program, use the COBOL command. The Compaq COBOL compiler performs these primary functions:

• Detects errors in your program.
• Displays each compiler message on your terminal screen.
• Generates machine language instructions from valid source statements.
• Groups these language instructions into an object module for the linker.
• Creates an analysis file if you request it with the /ANALYSIS_DATA qualifier. SCA uses this file to display information about program symbols and source files.

The compiler outputs an object module that provides the following information:

• The name of the entry point. It takes this name from the program name in the first PROGRAM-ID paragraph in the program.
• A list of variables that are declared in the module. The linker uses this information when it binds two or more modules together and must resolve references to the same names in the modules.
• Traceback information. This information is used by the system default condition handler when an error occurs that is not handled by the program. The traceback information permits the default handler to display a list of the active blocks in the order of activation; this is an aid in program debugging.
• A symbol table and a source line correlation table, only if you request them with the /DEBUG qualifier. A symbol table is a list of the names of all external and internal variables within a module, with definitions of their locations. The source line correlation table associates lines in your source file with lines in your program. These tables are of primary help when you use the OpenVMS Debugger.

To invoke the Compaq COBOL compiler, use the COBOL command (explained in Section 1.2.2.1). You can specify qualifiers with the COBOL command. The following sections discuss the COBOL command and its qualifiers.