Python calling C functions – passing structures

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.