rxresult

Additional Guidelines and Related Topics

This section covers topics related to the REXX interface of the SAS/C Library. Included are additional guidelines for developing and using C function packages, linking function packages, and using the SAS/C Source Level Debugger with function packages.

Developing C Function Packages

The following notes should be considered when developing function packages:

Function names are truncated to six characters, and lowercase letters are converted to uppercase. REXX prefixes the name with RX to form the eight-character command name.
The argv array used by cmsrxfn is not a normal C argv array. It can be inspected but not modified.
cmsrxfn expects functions to return normally via a RETURN statement. Therefore, exit and longjmp should not be used. Calls to these functions are trapped and cause an ABEND. Similarly, the REXXMAIN entry point also expects the main function to return by a RETURN statement. To comply with this condition, do not use exit to terminate a REXX function package.
The function package is loaded in protected storage. Therefore, all REXX function packages must be compiled with the RENT compiler option. If the function package is not compiled with RENT , a diagnostic message is issued when the package is called, and it is not loaded.
Very large function packages can be split into several dynamically loaded modules (see loadm). If you use dynamically loaded modules, all of the REXX function package functions ( cmsrxfn , rxresult , rxeval ) should be used only in the main load module. Using one of these functions in a dynamically loaded module will result in problems when the module is linked.
REXX function packages written in SAS/C cannot be invoked recursively from REXX.

Linking REXX Function Packages

Refer to Chapter 6, "Compiling, Linking, and Executing Programs under CMS," in SAS/C Compiler and Library User's Guide for general information about how to link C programs. If you do not need to use COOL to preprocess the function package TEXT files, use the following CMS commands to create the function package MODULE. Assume that the function package is named RXLOCFN:

LOAD RXLOCFN (RLDSAVE RESET REXXMAIN
GENMOD RXLOCFN (FROM first_CSECT

Inspect the LOAD map produced by the LOAD command to determine the name of the first CSECT. The RLDSAVE option in the LOAD command causes the resulting MODULE to be relocatable. The RESET REXXMAIN option causes REXXMAIN to be the entry point for the MODULE. The FROM option forces the GENMOD command to save the MODULE, beginning with the first CSECT. Always use the name of the first CSECT in the object code as the FROM parameter. (The LOAD MAP file lists the names of the CSECTs in your program.)

If you have more than one compilation in your function package that initializes external variables, you need to use COOL to preprocess the TEXT files. You may also need to use COOL to remove pseudoregisters from the TEXT files. In this case, the following commands can be used to create the function package MODULE. (This assumes that the function package is created from several compilations named RXLOCP1, RXLOCP2, and so on.)

COOL RXLOCP1 RXLOCP2 ...
LOAD COOL (RLDSAVE RESET REXXMAIN
GENMOD RXLOCFN (FROM @EXTERN#

Do not use the GENMOD option of the COOL EXEC to produce the MODULE file. The COOL EXEC will not produce a relocatable MODULE. Instead, use a separate LOAD command to load the COOL370 TEXT file with the correct options. Note that, in this case, the first CSECT in the COOL370 TEXT file is @EXTERN#, which is used as the parameter to the FROM option in the GENMOD command.

Using the SAS/C Debugger and the IC Command

Function packages written in the C language can be debugged using the debugger just like any other C program.

Because you cannot specify the =debug run-time option via the command line, set the _DEBUG flag in the _options variable to start the debugger (see the previous example). When the function package is called the first time, the debugger initializes normally and prompts for a command. Use the debugger as you would in any other C program. When you finish debugging, recompile the function package without the _DEBUG flag set. (For more information about the _options variable, refer to the "Library Options" section of Chapter 9, "Run-Time Argument Processing," in SAS/C Compiler and Library User's Guide).

If the function package is active but no debugger commands are in effect or no debugger breakpoints are set, you can force the debugger to issue a prompt by entering IC on the CMS command line. The next time an EXEC calls a C function in the package, the debugger will issue a prompt.

Chapter Contents
Previous
Next
Top of Page