Chapter Contents |
Previous |
Next |
The CMS REXX SAS/C Interface |
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
execfetch
fetches a REXX variable.
execdrop
drops a REXX variable.
cmsstack
cmspush
|
stack (LIFO) access. |
cmsqueue
|
queue (FIFO) access. |
You use these functions in your program as follows:
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.
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
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
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.
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
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
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.)
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 |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.