% Here are some notes from Joseph Bostian (an IBM Systems Programmer) on
% accessing data sets from within C code / USS, with comments from me
% inserted:

I took some time today to look a little deeper into things  I've known 
that these facilities are here, but I don't have a lot of direct 
experience with them directly beyond open read/write close of an existing 
dataset.  The function set available is a lot richer than that, but I 
haven't taken the time to do much with anything.

% One of the links on the webpage points to the C/C++ APIs on z/OS.
% Take a very careful look at the documentation for fopen.
%

As for catalog access, I haven't yet run across anything that can can be 
done from a C program.  There is a lot of information on managing 
structures like catalogs in the DFSMS component of the system, and there 
is an interface to something called dynamic allocation that allows an 
application to do I/O to all different types of system resources, like 
tapes, consoles, generation datasets, dumps - pretty much any kind of 
resource in the system.  Some of this I/O functionality is exposed through 
the dynalloc/dynfree/dyninit interfaces of the C runtime library. Dynalloc 
in particular has a description of the __dyn_t data structure that 
probably has some of the dataset characteristics that you may find 
interesting.  This would be a good place to start when diving into the 
inner workings of the system

% dynalloc is also documented in the C/C++ reference mentioned above.
% You could use this to create data sets from C, but not to list
% directories (as far as I can tell).

These dynamic allocation services (described in the LE RTL reference - 
attached) are built on top of the svc99( ) service that gives a caller 
access to a whole host of system services - all of which are authorized 
versions of assembler interfaces.  If you want people to get really deep 
into the system, svc99( ) is an entry point.  There are multiple volumes 
of documentation on the assembler interfaces that you can use.  There's 
too much to send as an attachment here, but you should be able to see the 
library of books at:

http://publibfi.boulder.ibm.com/libraryserver/index.html

% The svc99 call is kind-of documented in the C/C++ API book,
% but you need to look at the assembler documentation to get
% all the details.  You can use either the sys99 wrapper or
% assembly code to list catalogs as far as I can tell.
% Look in particular at the MVS authorized assembler book;
% chapter 25 is on dynamic allocation, but that you might be
% able to do more easily with dynalloc/dynfree/dyninit.
% Can you write similar wrappers providing something like
% "opencat" (in the spirit of "opendir") using sys99?  This
% is the essence of the project!

Most of what you might find interesting are in the MVS and DFSMS 
categories.  One thing about DFSMS - I'm not exactly sure how DFSMS is 
exposed through all of the various interfaces of the system.  Mostly I've 
seen it used through JCL instead of a compiled program.  I know that there 
are real programs written to use the DFSMS interfaces directly in 
assembler, and these interfaces are an integral part of the system behind 
the dynalloc C APIs, but I don't have a clear picture in my mind about how 
it all goes together.  If you wanted to expose your students to JCL, that 
would be a rich area of function to explore.