1. You can have Python programs which are pure Python.
2. You can call C programs that act like Python programs, using Python constructs within the C program
3. You can call a C program from Python, and it processes parameters like a normal C program.
   • You can pass simple data types such as char, integers and strings.
   • You can pass structures. See Python calling C functions – passing structures

This blog post is about the third, calling a C program from Python, passing simple data types such as char, integers and strings.

I have based a lot of this on the well written pyzfile package by @daveyc.

The glue that makes it work is the ctypes package a “foreign function library” package.

Before you start

The blog post is called “Python calling C functions”. I tried using a z/OS stub code directly. This is not written in C, and I got.

CEE3595S DLL ... does not contain a CELQSTRT CSECT.

Which shows you must supply a C program.

The C program that I wrote, calls z/OS services. These must be defined like (or default to)

#pragma linkage(...,OS64_NOSTACK)     

Getting started

My C program has several functions including

int query() {  
return 0;
}

The compile instructions said exportall – so all functions are visible from outside of the load module.

You access this from Python using code like

lib_file = pathlib.Path(__file__).parent / "pySMFRealTime.so"
self.lib = ctypes.CDLL(str(lib_file))
...
result = self.lib.query()  

Where

• lib_file = pathlib.Path(__file__).parent / “pySMFRealTime.so” says get the file path of the .so module in the same directory as the current Python file.
• self.lib = ctypes.CDLL(str(lib_file)) load the file and extract information.
• result = self.lib.query() execute the query function, passing no parameters, and store any return code in the variable result

Passing simple parameters

A more realistic program, passing parameters in, and getting data back in the parameters is

int conn(const char* resource_name,  // input:  what we want to connect to
         char * pOut,                // output: where we return the handle
         int * rc,                   // output: return code  
         int * rs,                   // output: reason code 
         int * debug)                // input:  pass in debug information 
{
    int lName = strlen(resource_name); 
    if  (*debug >= 1) 
    { 
      printf("===resource_namen"); 
      printHex(stdout,pFn,20); 
    } 
    ...
    return 0;
}

The Python code has

lib_file = pathlib.Path(__file__).parent / "pySMFRealTime.so"
self.lib = ctypes.CDLL(str(lib_file))
self.lib.conn.argtypes = [c_char_p,  # the name of stream
                          c_char_p,  # the returned buffer
                          ctypes.POINTER(ctypes.c_int), # rc
                          ctypes.POINTER(ctypes.c_int), # rs 
                          ctypes.POINTER(ctypes.c_int), # debug
                          ] 
self.lib.conn.restype = c_int

The code to do the connection is

def conn(self,name: str,):
    token =  ctypes.create_string_buffer(16) # 16 byte handle
    rc = ctypes.c_int(0)
    rs = ctypes.c_int(0)
    debug = ctypes.c_int(self.debug)
    self.token = None
    retcode  = self.lib.conn(name.encode("cp500"),
                                token,
                                rc,
                                rs,
                                debug)
    if retcode != 0:
        print("returned rc",rc, "reason",rs)
        print(">>>>>>>>>>>>>>>>> connect error ")
        return None
    print("returned rc",rc, "reason",rs)
    self.token = token
    return rc

The code does

• def conn(self,name: str,): define the conn function and pass in the variable name which is a string
• token = ctypes.create_string_buffer(16) # 16 byte handle create a 16 byte buffer and wrap it in ctypes stuff.
• rc = ctypes.c_int(0), rs = ctypes.c_int(0), debug = ctypes.c_int(self.debug) create 3 integer variables.
• self.token = None preset this
• retcode = self.lib.conn( invoke the conn function
  • name.encode(“cp500”), convert the name from ASCII (all Python printable strings are in ASCII) to code page 500.
  • token, the 16 byte token defined above
  • rc, rs, debug) the three integer variables
• if retcode != 0: print out error messages
• print(“returned rc”,rc, “reason”,rs) print the return and reason code
• self.token = token save the token for the next operation
• return rc return to caller, with the return code.

Once I got my head round the ctypes… it was easy.

The C program

There are some things you need to be aware of.

• Python is compiled with the -qascii compiler option, so all strings etc are in ASCII. The code name.encode(“cp500”), converts it from ASCII to EBCDIC. The called C program sees the data as a valid EBCDIC string (null terminated).
• If a character string is returned, with printable text. Either your program coverts it to ASCII, or your Python calling code needs to convert it.
• Your C program can be compiled with -qascii – or as EBCDIC(no -qascii)
  • Because Python is compiled in ASCII, the printf routines are configured to print ASCII. If your program is compiled as ASCII, printf(“ABCD”) will print as ABCD. If your program is compiled as EBCDIC printf(“ABCD”) will print garbage – because the hex values for EBCDIC ABCD are not printable as ASCII characters.
  • If your program is compiled as ASCII you can define EBCDIC constants.
    • #pragma convert(“IBM-1047”)
    • char * pEyeCatcher = “EYEC”; // EBCDIC eye catcher for control block
    • #pragma convert(pop)

I’ve written how you can pass simple data from Python to a C function, see Python calling C functions.

This article explains how you can pass structures and point to buffers in the Python program. it extends Python calling C functions. It allows you to move logic from the C program to a Python program.

Using complex arguments

The examples in Python calling C functions were for using simple elements, such as Integers or strings.

I have a C structure I need to pass to a C function. The example below passes in an eye catcher, some lengths, and a buffer for the C function to use.

The C structure

typedef struct querycb {                                                         
      char        Eyecatcher[4];  /* Eye catcher   offset    0    */                   
      uint16_t    Length;         /* Length of the block     4    */                   
      char        Rsvd1[1];       /* Reserved                6    */                   
      uint8_t     Version;        /* Version number          7   */                    
      char        Flags[2];       /* Flags                   8    */                   
      uint16_t    Reserved8;      //   10                                              
      uint32_t    Count;          // number returned  12                                       
      uint32_t    lBuffer;        // length of buffer 16                                      
      uint32_t    Reservedx ;     //              20                                    
      void        *pBuffer;       //              24                                 
    } querycb;   

The Python code

# create the variables
eyec = "EYEC".encode("cp500")  # char[4] eye catcher
l = 32                         # uint16_t
res1 = 0                       # char[1] 
version = 1                    # uint8_t -same as a char
flags = 0                      # char[2]
res2 = 0                       # uint16_t
count = 0                      # uint32_t  
lBuffer = 4000                 # uint32_t 
res3 = 0                       # uint32_t 
# pBuffer                      # void *  
# allocate a buffer for the C program to use and put some data
# into it
pBuffer = ctypes.create_string_buffer(b'abcdefg',size=lBuffer)
# cast the pBuffer so it is a void * 
pB =  ctypes.cast(pBuffer, ctypes.c_void_p)
# use the struct.pack function.  See @4shbbhhiiiP below
# @4 is 4 bytes, the eye catcher
# h half word
# bb two char fields res1, and version
# hh two half word s flags and res2
# iii three integer fields.  count lBuffer and res3
# P void * pointer 
# Note pB is a ctype, we need the value of it, so pB.value
p = pack("@4shbbhhiiiP", eyec,l,res1,version,flags,
         res2,count,lBuffer,res3,pB.value)

#create first parm
p1 = ctypes.c_int(3)  # pass in the integer 3 as an example
# create second parm
p2 = ctypes.cast(p, ctypes.c_void_p)

# invoke the function 

retcode  = lib.conn(p1,p2) 

The C program

int conn(int * p1, char * p2) 
// int conn(int  max,...)
{ 
    typedef struct querycb {                                                         
      char        Eyecatcher[4];  /* Eye catcher             0    */                   
      uint16_t    Length;         /* Length of the block     4    */                   
      char        Rsvd1[1];       /* Reserved                6    */                   
      uint8_t     Version;        /* Version number          7   */                    
      char        Flags[2];       /* Flags                   8    */                   
      uint16_t    Reserved8;      //   10                                              
      uint32_t    Count;  // number returned  12                                       
      uint32_t    lBuffer; // length of buffer 16                                      
      uint32_t    Reservedx ;    //              20                                    
      void        *pBuffer;      //              24                                    
    } querycb;  

    querycb * pcb = (querycb * ) p2;

    printf("P1 %i\n",*p1);
    printHex(stdout,p2,32); 
    printf("Now the structure\n")
    printHex(stdout,pcb -> pBuffer,32); 
    return 0 ;
} 

The output

P1 3
00000000 : D8D9D7C2 00200001 00000000 00000000  ..... .......... EYEC............ 
00000010 : 00000FA0 00000000 00000050 0901BCB0  ...........P.... ...........&.... 
Now the structure
00000000 : 61626364 65666700 00000000 00000000  abcdefg......... /............... 
00000010 : 00000000 00000000 00000000 00000000  ................ ................ 

Where

• EYEC is the passed in eye catcher
• 00000FA0 is the length of 4000
• 00000050 0901BCB0 is the 64 address of the structure
• abcdefg is the data used to initialise the buffer

Observations

It took me a couple of hours to get this to work. I found it hard to get the cast, and the ctype…. functions to work successfully. There may be a better way of coding it, if so please tell me. The code works, which is the objective – but there may be better more correct ways of doing it.

Benefits

By using this technique I was able to move code from my C program to set up the structure needed by the z/OS service into C. My C program was just parse input parameters, set up the linkage for the z/OS service, and invoke the service.

If course I did not have the constants available from the C header file for the service, but that’s a different problem.