regina/gci/gci.h

   1 /*
   2  *  Generic Call Interface for Rexx
   3  *  Copyright © 2003-2004, Florian Große-Coosmann
   4  *
   5  *  This library is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Library General Public
   7  *  License as published by the Free Software Foundation; either
   8  *  version 2 of the License, or (at your option) any later version.
   9  *
  10  *  This library is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  Library General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Library General Public
  16  *  License along with this library; if not, write to the Free
  17  *  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  *
  19  * ----------------------------------------------------------------------------
  20  *
  21  * This file contains types, constants and prototypes which are global to the
  22  * GCI system and may be used to invoke the GCI.
  23  */
  24
  25 #ifndef incl_LINK_FUNCS_ONLY
  26 #include "embedded.h"
  27
  28 /*
  29  * GCI_result is either GCI_OK for success or a more or less understandable
  30  * error code.
  31  */
  32 typedef enum {
  33    GCI_OK = 0,
  34    GCI_NoMemory,          /* out of memory while processing                  */
  35    GCI_WrongInput,        /* unexpected input, either unknown type (e.g. FIXED)
  36                              or illegal data (e.g. 0xFF as an integer).      */
  37    GCI_NumberRange,       /* Number doesn't fit in the allowed range..       */
  38    GCI_StringRange,       /* String too big for the defined buffer.          */
  39    GCI_UnsupportedType,   /* Illegal combination of type/size, e.g. INTEGER3 */
  40    GCI_UnsupportedNumber, /* nan, inf, etc                                   */
  41    GCI_BufferTooSmall,    /* Internal error: insufficent buffer size. The    */
  42                           /* structure is too complex.                       */
  43    GCI_MissingName,       /* A name in the structure is missing.             */
  44    GCI_MissingValue,      /* A value in the structure is missing.            */
  45    GCI_IllegalName,       /* The name or part of a name is illegal for the   */
  46                           /* interpreter                                     */
  47    GCI_RexxError,         /* Problems communicating with the interpreter.    */
  48                           /* NEVER FORGET TO EXTEND gci_helper.c:GCI_describe*/
  49    GCI_NoBaseType,        /* The type won't fit the requirements for basic   */
  50                           /* types.                                          */
  51    GCI_InternalError,     /* Internal, unknown problems                      */
  52    GCI_FunctionAlreadyKnown, /* New name already registered to Rexx          */
  53    GCI_LibraryNotFound,   /* The given external library can't be loaded      */
  54    GCI_NoLibraryFunction, /* The given external function can't be found in   */
  55                           /* the library                                     */
  56    GCI_FunctionNotFound,  /* The name was not registered in the Rexx core    */
  57    GCI_SyntaxError,       /* The number of arguments is wrong                */
  58    GCI_CoreConfused,      /* The core of GCI can't determine how to invoke   */
  59                           /* generic functions                               */
  60    GCI_ArgStackOverflow,  /* GCI's internal stack for arguments got an       */
  61                           /* overflow                                        */
  62    GCI_NestingOverflow,   /* GCI counted too many nested LIKE containers     */
  63    GCI_LastResult         /* currently not used.                             */
  64 } GCI_result;
  65
  66 /*
  67  * GCI understands some basic types of which it builds more complex type
  68  * structures. The basic types are listed here, although we need some extra
  69  * types while parsing the name; these have negative values.
  70  */
  71 typedef enum {
  72    GCI_unknown = -3,
  73    GCI_like = -2,
  74    GCI_indirect = -1,
  75    GCI_integer = 0,
  76    GCI_unsigned,
  77    GCI_float,
  78    GCI_char,
  79    GCI_string,
  80    GCI_raw,
  81    GCI_container,
  82    GCI_array
  83 } GCI_basetype;
  84
  85 /*
  86  * GCI enumerates all basic types while parsing the type tree. Each leaf or
  87  * branch has an info node for the type.
  88  */
  89 typedef struct {
  90    GCI_basetype type;
  91    unsigned     indirect;  /* flag "indirect" */
  92    unsigned     size;      /* bytes or # of elements (array, container) */
  93    unsigned     generated; /* generated indirection for arrays */
  94 } GCI_parseinfo;
  95
  96 /*
  97  * GCI knows several basic call types.
  98  * cdecl: arguments pushed in order right to left, stack cleanup by caller
  99  * stdcall: arguments pushed in order right to left, stack cleanup by callee
 100  * pascal: arguments pushed in order left to right, stack cleanup by callee
 101  */
 102 typedef enum {
 103       GCI_ctUnknown = 0,
 104       GCI_ctCdecl,
 105       GCI_ctStdcall,
 106       GCI_ctPascal
 107 } GCI_calltype;
 108
 109 /*
 110  * GCI has a structure for the call type.
 111  */
 112 typedef struct {
 113    GCI_calltype type;
 114    unsigned     as_function;     /* flag "as function" */
 115    unsigned     with_parameters; /* flag "as parameters" */
 116 } GCI_callinfo;
 117
 118 /*
 119  * GCI_nodeinfo provides all informations needed for one branch or leaf in the
 120  * type information tree.
 121  */
 122 typedef struct {
 123    GCI_parseinfo type;
 124    int           parent;         /* index of the parent's node or -1 */
 125    int           child;          /* index of the first child or -1 */
 126    int           sibling;        /* next if same depth with same parent */
 127    unsigned      direct_size;    /* size in bytes of this and all children */
 128    unsigned      indirect_size;  /* as direct_size, but for INDIRECT children */
 129    unsigned      direct_pos;     /* pos in buffer of this node */
 130    unsigned      indirect_pos;   /* as direct_pos, but for INDIRECT children */
 131 } GCI_nodeinfo;
 132
 133 /*
 134  * GCI_treeinfo provides all informations needed for all arguments and the
 135  * return value for one call.
 136  */
 137 typedef struct {
 138    GCI_callinfo  callinfo;
 139    GCI_nodeinfo *nodes;
 140    int           used;                /* used elements of nodes */
 141    int           max;                 /* current maximum of elements of nodes */
 142    int           args[GCI_REXX_ARGS]; /* ??? arguments' starting index or -1 */
 143    int           retval;              /* return value's starting index or -1 */
 144    unsigned      size;                /* size in bytes of all args */
 145 } GCI_treeinfo;
 146
 147 /*
 148  * STEMDEPTH is the amount of space which will be allocated additionally to
 149  * a stem's string length for iterative access. We shall support roughly
 150  * a depth of 100 elements, most of a short depth. Don't forgetting the
 151  * separating dot we have about 250 chars.
 152  */
 153 #define STEMDEPTH 250
 154
 155 #define elements(array) ( sizeof( array ) / sizeof( (array)[0] ) )
 156
 157 /*
 158  * gci_convert.c
 159  */
 160 GCI_result GCI_string2bin( void *hidden,
 161                            const char *str,
 162                            int size,
 163                            void *dest,
 164                            int destbyte,
 165                            GCI_basetype type );
 166 GCI_result GCI_bin2string( void *hidden,
 167                            const void *base,
 168                            int size,
 169                            char *str,
 170                            int *strsize,
 171                            GCI_basetype type );
 172 GCI_result GCI_validate( int size,
 173                          GCI_basetype type,
 174                          int basetype );
 175
 176 /*
 177  * gci_helper.c
 178  */
 179 int GCI_strlen( const GCI_str *str );
 180 int GCI_strmax( const GCI_str *str );
 181 char * GCI_content( GCI_str *str );
 182 const char * GCI_ccontent( const GCI_str *str );
 183 int GCI_streq( const GCI_str *s1,
 184                const GCI_str *s2 );
 185 GCI_result GCI_strcat( GCI_str *first,
 186                        const GCI_str *second );
 187 GCI_result GCI_strcats( GCI_str *first,
 188                         const char *second );
 189 void GCI_strsetlen( GCI_str *str,
 190                     int max );
 191 GCI_result GCI_strcpy( GCI_str *first,
 192                        const GCI_str *second );
 193 GCI_str *GCI_strfromascii( GCI_str *str,
 194                            char *ptr,
 195                            int max );
 196 const GCI_str *GCI_migratefromascii( GCI_str *str,
 197                                      const char *ptr );
 198 GCI_result GCI_stralloc( void *hidden,
 199                          GCI_str *str,
 200                          unsigned size );
 201 void GCI_strfree( void *hidden,
 202                   GCI_str *str );
 203 GCI_result GCI_strdup( void *hidden,
 204                        GCI_str *first,
 205                        const GCI_str *second );
 206 char *GCI_strtoascii( void *hidden,
 207                       const GCI_str *str );
 208 void GCI_uppercase( void *hidden,
 209                     GCI_str *str );
 210 void GCI_describe( GCI_str *description,
 211                    GCI_result rc );
 212 void GCI_strswap( GCI_str *first,
 213                   GCI_str *second );
 214
 215 /*
 216  * gci_prepare.c
 217  */
 218 GCI_result GCI_parsenodes( void *hidden,
 219                            GCI_str *base,
 220                            GCI_treeinfo *ti,
 221                            unsigned argc,
 222                            unsigned return_valid,
 223                            const char *prefixChar );
 224
 225 /*
 226  * gci_rexxbridge.c
 227  */
 228 GCI_result GCI_readRexx( void *hidden,
 229                          const GCI_str *name,
 230                          GCI_str *target,
 231                          int symbolicAccess,
 232                          int signalOnNoValue,
 233                          int *novalue );
 234 GCI_result GCI_readNewRexx( void *hidden,
 235                             const GCI_str *name,
 236                             GCI_str *target,
 237                             int symbolicAccess,
 238                             int signalOnNoValue,
 239                             int *novalue );
 240 GCI_result GCI_writeRexx( void *hidden,
 241                           const GCI_str *name,
 242                           const GCI_str *value,
 243                           int symbolicAccess );
 244 GCI_result GCI_RegisterDefinedFunction( void *hidden,
 245                                         const GCI_str *internal,
 246                                         const GCI_str *library,
 247                                         const GCI_str *external,
 248                                         const GCI_treeinfo *ti );
 249 void GCI_remove_structure( void *hidden,
 250                            GCI_treeinfo *gci_info );
 251
 252 /*
 253  * gci_rxfuncdefine.c
 254  */
 255 GCI_result GCI_ParseTree( void *hidden,
 256                           const GCI_str *stem,
 257                           GCI_treeinfo *gci_info,
 258                           GCI_str *error_disposition,
 259                           const char *prefixChar );
 260 GCI_result GCI_RxFuncDefine( void *hidden,
 261                              const GCI_str *internal,
 262                              const GCI_str *library,
 263                              const GCI_str *external,
 264                              const GCI_str *stem,
 265                              GCI_str *error_disposition,
 266                              const char *prefixChar );
 267
 268 /*
 269  * gci_tree.c
 270  */
 271 GCI_result GCI_parsetree( void *hidden,
 272                           GCI_str *base,
 273                           GCI_result (*callback)(int depth,
 274                                                  int itemnumber,
 275                                                  void *arg,
 276                                                  const GCI_parseinfo *info),
 277                           void *arg,
 278                           const char *prefixChar );
 279
 280 /*
 281  * gci_execute.c
 282  */
 283 GCI_result GCI_execute( void *hidden,
 284                         void (*func)(),
 285                         const GCI_treeinfo *ti,
 286                         int argc,
 287                         const GCI_str *args,
 288                         GCI_str *error_disposition,
 289                         GCI_str *retval,
 290                         const char *prefixChar );
 291
 292 /*
 293  * gci_call.c
 294  */
 295 GCI_result GCI_call( void *hidden,
 296                      void (*func)(),
 297                      const GCI_treeinfo *ti,
 298                      char *basebuf );
 299
 300 #endif /* incl_LINK_FUNCS_ONLY */
 301
 302 /*
 303  * gci_oslink.c (not used for a GCI which is embedded in a true interpreter)
 304  */
 305 void *GCI_getLibrary( const char *libname, int libnamelen, char *buf );
 306 void GCI_freeLibrary( void *handle );
 307 void ( *GCI_getEntryPoint( void *handle, const char *function ) )();
 308