The CMS REXX SAS/C Interface

How the Library Interfaces with REXX

The library takes advantage of all aspects of the REXX function package interface. This section explains how the library provides the functions that enable you to create function packages in C.

The SAS/C Library REXX Interface Functions

The library provides a set of functions that help you create and use REXX function packages. These functions and their purposes are as follows: cmsrxfn creates a function package by defining a set of C functions that can be called directly from REXX. rxeval returns a function result to REXX. rxresult returns a function result to REXX. cmsshv provides a way of assigning values to new and existing variables shared with REXX or of dropping REXX variables or stems. (REXX stems allow collections of variables to be handled.) The following three macros are provided with this function:

execset

sets a REXX variable. execfetch fetches a REXX variable. execdrop drops a REXX variable.

cmsstack

inserts a string into the CMS program stack (the system-provided data queue that can be shared by REXX and your program). The following two macros provide stack access as well:

`cmspush`	stack (LIFO) access.
`cmsqueue`	queue (FIFO) access.

You use these functions in your program as follows:

Code a main function that uses cmsrxfn to define all the functions in the function package. You do not need to have the main function return a value to CMS because cmsrxfn sets these return values.
Code the individual functions for the package. If the function or subroutine returns a result, use the rxeval or rxresult function to set the value of the REXX RESULT variable. The following differences between functions and subroutines should be considered in your program: 6pt
- If the REXX program can call the function as a true function, be sure the C function returns a value.
- If the REXX program only calls the C function as a subroutine using a CALL statement, the C function does not need to return a value.
Use the cmsshv and cmsstack functions and the execset , execfetch , execdrop , cmspush , and cmsqueue macros as needed in the function package.

The SAS/C Library Function Package Support

In addition to these functions, the library defines a special C program entry point, REXXMAIN. Together with cmsrxfn , REXXMAIN provides the interface that supports the use of C programs as REXX function packages. Together, REXXMAIN and cmsrxfn provide all of the support necessary to

load the C program as a nucleus extension
identify C functions as REXX external functions
transfer control and parameter lists from REXX to C functions
transfer control and result values from C functions back to REXX
handle special situations under CMS, such as the NUCXDROP command and ABENDs.

When a C program is entered via REXXMAIN, the REXXMAIN code copies the program into storage and identifies it as a nucleus extension by calling the CMS command NUCXLOAD for itself. REXXMAIN then transfers control to the normal C initialization routine, passing a specially formatted parameter list. The C environment is created normally, and the parameter list created by REXXMAIN is passed to the main function as the argument array argv . (Note that REXX function packages are slightly unusual because they are always invoked by REXX instead of from the CMS command line.)

The C program then calls the cmsrxfn function, passing it the argv array and an array of pointers to C functions. The C functions pointed to by this array are made available to REXX as external functions. cmsrxfn thereafter handles the transfer of control and data between REXX and C. If a special situation occurs, such as an ABEND under CMS, cmsrxfn returns to its caller, which can then do such cleanup as required.

C Function Packages and Nucleus Extensions

During the execution of a REXX function package written using the library interface, several nucleus extension entry points are created. Two have the same name as the function package. The first of these nucleus extension entry points has the SYSTEM attribute and owns the storage occupied by the package code. The entry point identifies the location where the package should be entered if the C environment has been destroyed by an ABEND and must be reinitialized. This support ensures that the C program remains in storage even if an ABEND occurs under CMS. Thus, the function package does not need to be reloaded from disk. The C environment, even though destroyed by the ABEND, is reinitialized automatically the next time the function package is called. The second nucleus extension entry point has the SERVICE attribute. Its entry point identifies the location within cmsrxfn that REXX enters on the second and subsequent calls to the function package.

A nucleus extension entry point is created for each C function called by REXX. The name is the name of the C function prefixed with RX . All of these entry points identify the same location within cmsrxfn . When REXX calls the function directly, this entry point is responsible for restoring the C environment and transferring control to the C function.

As a result of using two entry points, two NUCXDROP commands must be issued to remove a SAS/C REXX nucleus extension. The first command is to drop the entry point for each C function to be called from REXX. The second command is to drop the entry point that handles initialization and ABEND recovery.

Between calls to the function package (after a function returns to REXX), the C environment is saved. Thus, open files remain open, memory stays allocated, and external variables retain their values.

For more information on the SYSTEM and SERVICE command attributes and nucleus extensions, refer to the CMS command and macro reference appropriate for your release.

The SAS/C Library Interface and the REXX Extended Plist

When a C function is called by REXX, the first parameter is always a pointer to an array of Adlen pairs. Each Adlen pair describes an argument to the function. The REXX_PLIST structure can reference members of this array. This structure, contained in the <cmsexec.h> header file, is defined as follows:

struct REXX_PLIST {
   char *ad;
   int len;
};

The variable ad points to an argument string, and len provides the length. Together these fields are used by REXX to map the elements in a REXX argument array (Adlen pairs). Omitted function arguments are denoted by a NULL value in the ad element. To see how these arguments are used with the REXX plist, refer to cmsrxfn.

When REXX Calls a C Function Package

When REXX calls one of the functions in a C function package, REXX creates the six-word plist and invokes the function as a command. Because the nucleus extension entry point indicates a location inside cmsrxfn , cmsrxfn is re-entered. cmsrxfn then

re-establishes the C environment
determines whether the C function was called as a subroutine or as a function
creates the parameter list ( args and subflag ) where args is a pointer to an array of Adlen pairs, and subflag is an integer that is nonzero when the function is called as a subroutine
proceeds to call the function via the function pointer in the fncv array.

When the function returns, cmsrxfn checks the return value. If the return value is 0 , it checks to see if rxeval or rxresult was called within the same module in which cmsrxfn was called. If either result function was called within the same module in which cmsrxfn was called, cmsrxfn puts the value passed to rxeval or rxresult (via a special control block called an EVALBLOK) in word 6 of the REXX plist and then returns to REXX. The current C environment is then saved for the next call. (Note that if both rxresult and rxeval are called, cmsrxfn uses the value from the last call made.)

CAUTION:: 370 mode Do not issue CMS commands between main and the call to cmsrxfn in 370 mode. The parameter list that is created by REXXMAIN and passed to main as the argument array argv is destroyed before it can be passed to cmsrxfn .

Chapter Contents
Previous
Next
Top of Page