Sun Setup

This section begins the machine specific information for setting up Open C API on a Sun system and includes the necessary information you need to create environment variables and to compile, link, and run your Open C API programs.
 

Defining a Required Environment Variable


 
Environment Variable Description
UGII_USERFCN This variable is defined in .ugii_env and points to the NX directory where the Open C API libraries reside.

 
Although this variable is defined for you in .ugii_env, you can customize this variable for your own Open C API environment. For example, you can define UGII_USERFCN to point to the directory that contains the libraries. On a typical system, this environment variable points to: ${UGII_BASE_DIR}/ugii.
 

External Open C API Link Swap Space

When linking large external Open C API programs (images larger than a couple of megabytes), we suggest configuring more swap space to handle the linker's space requirements. We recommend 200 megabytes total swap space.
 

Debugging an Internal mode Open C program

To debug an internal Open C API program, perform the steps listed below.
 
In this discussion, the word debugger refers to the debugging tool itself, which means either the dbx command or the debugger command. The window interface is available with the debugger command only, not with the dbx command. The only other difference between the two is that the dbx command uses the prompt (dbx) while the debugger command uses the prompt (debugger).
 
The SunPro V3.0.1 SPARCworks debugger can debug an object opened using dlopen, such as an internal Open C API program, but it cannot set any breakpoint in that module until it is loaded. So you must set an extra breakpoint, as explained below, before you can set any breakpoint in your internal Open C API program.
NOTE: In the steps below, we use (dbx) to indicate the prompt when you use the dbx command. If you use the debugger command instead, then substitute the (debugger) prompt for (dbx).
  1. Have the proper setup for internal Open C API execution. Also compile your routines/files with -g with cc or f77 and link your image using the uflink script.
  2. Then start UGMENU, and select the graphics driver you wish to run. Then select option 2, UGOPEN-API. From ufmenu, select option 7, Non-menu activities. This ensures your environment is set correctly. Then start NX with the command lines:
    % dbx $UGII_BASE_DIR/ugii/ugraf or % debugger $UGII_BASE_DIR/ugii/ugraf
    where % indicates your shell prompt. You are now in debugger. If your path is not set properly to find these commands, use /opt/SUNWspro/bin/dbx or /opt/SUNWspro/bin/debugger.
  3. Now set the breakpoint for dlopen to load your internal Open C API program. You must give the full path. For purposes of illustration, assume that your internal Open C API program is called libtest.so and that it is in the directory /your_dir_path.
    (dbx) stop dlopen /your_dir_path/libtest.so
    Then something like the following displays:
    (2) stop dlopen /your_dir_path/libtest.so
  4. Run the NX process. If you run with xwimod, then:
    (dbx) run
    If you run with xglmod, then:
    (dbx) run -term=xgl
  5. Choose and run your internal Open C API program.
  6. It will stop at the dlopen breakpoint when your internal Open C API program is loaded and then you will see something like:
    Reading symbolic information for libtest.so stopped in (unknown) at 0xef7e2a20 0xef7e2a20: jmp %o7 + 8 (dbx)
    The address "0xef7e2a20" may be a different value. Also note that the first line of messages shows your internal Open C API program name.
  7. Note that loadobject still shows UG as the current object.
    (dbx) loadobject /usr/ugs160/ugraf
  8. Your internal Open C API is now loaded and you can set the desired breakpoint(s) in it. For example, set the breakpoint at the entry point:
    (dbx) stop in ufusr
    (3) stop in ufusr
  9. Continue the NX session to run your internal Open C API program:

    10. (dbx) cont
  10. NX will stop at the breakpoint in your internal Open C API program. You should be able to see your source code and proceed with your debugging.
    stopped in ufusr_ at line 3 in file "test.c"
    3 printf ("this is to debug an internal ufun program.\n");
    (dbx)
  11. You can check your current loaded object:
    (dbx) loadobject /your_dir_path/libtest.so

 

Running Open C API Programs

Open C API programs can be run from any of the 3 environments: the operating system, an NX Open C API interface, or a NX GRIP program.
 
UNIX does not require special run time support for Open C API programs. To run an external Open C API program, simply type its name at the UNIX shell prompt.
 
GRIP Open C API Interface
 
Any task which can be run from the Open C API interface can also execute from a GRIP program using the XSPAWN command. See the GRIP programmers manual for more details.
 
Error Messages
 
Error messages display in a message window one line at a time. To see the second line of an error message you click the OK button in the first message window. When setting up the execution of an Internal Open C API program, several errors can exist:
 
1. "SYMBOL NOT FOUND"
 
Possible cause: The program was linked as an Internal Open C API program, but does NOT have the required UFUSR Entry Point.