Home Building DHTML Scripting Using Diaperglu Documention Key Script Commands Reference C Library API Reference Handy References About License Contact Forth Draft Standard
C Functions dg_initbuffers dg_inithlists dg_initvariables dg_cleanup dg_gettruesize dg_initwithoutwordlists dg_init dg_main main
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_initbuffers 
//
// C prototype:
//  const char* dg_initbuffers( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Outputs:
//  const char*   return          dg_success if function succeeded, otherwise function 
//                                 failed
//                                                             
// Action:
//  initializes the Diaperglu process buffers
//
// Failure cases:
//  computer could be out of memory
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_inithlists
//
// C prototype:
//  void dg_inithlists( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Outputs:
//  none
//                                                             
// Action:
//  Initializes the Diaperglu process hierarchical lists.
//
// Failure cases:
//  computer could be out of memory
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_initvariables  
//
// C prototype:
//  void dg_initvariables (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Outputs:
//  none
//
// Action:
//  Initializes the Diaperglu process variables
//
// Failure cases:
//  There should not be any, since we are just writing to Diaperglu managed memory 
//   which should already be allocated.
//  But if there are any failures, an error message will be pushed to the error stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_cleanup  
//
// C prototype:
//  void dg_cleanup (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Outputs:
//  none
//
// Action:
//  Calls any functions pushed to the cleanup stack, last pushed functions are called 
//   first
//  Closes all open libraries in the library handle stack
//  Frees all buffers held in the in the buffer handle array
//  Frees the buffer handle array
//  Frees the buffer handle array head
//
// Note:
//  After this call, pBHarrayhead is invalid
//
// Failure cases:
//  failures are ignored during this call
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_gettruesize
//
// C prototype:
//  UINT64 dg_gettruesize()
//
// Inputs:
//
// Outputs:
//  UINT64  return          true size of master buffer handle in bytes
//
// Action:
//  Calculates the amount of memory needed to hold the bufferhandle array head
//   and the jump buffer. Since some operating systems only allocate memory
//   in units of the system page size, the true size is probably larger than
//   just the size of a buffer handle and jump buffer added together.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_initwithoutwordlists
//
// C prototype:
//  Bufferhandle* dg_initwithoutwordlists(int argc, char* argv[])
//
// Inputs:
//  int         argc        number of arguments from stdin command line
//  char*       argv[]      array of pointers to argument strings from stdin command line
//
// Outputs:
//  Bufferhandle* pBHarrayhead    On success contains a pointer to a Bufferhandle 
//                                 structure which is used as the bufferhandle for the 
//                                 array where the other bufferhandles are stored.
//                                 This one pointer points to all the data for this 
//                                  process, which is what allows Diaperglu to be 
//                                  reentrant.
//                                On failure contains badbufferhandle (-1)
//
// Action:
//  Takes the command line arguments from stdin and allocates the minimum memory for 
//   a Diaperglu process instance. Then initializes the allocated memory.
//   This includes: 
//    allocating memory for the Bufferhandle array head
//    allocating memory for the bufferhandle array
//    allocating memory for the initial Diaperglu process buffers
//    initializing the jumpbuffer code for 'safe' function call returns
//    initializing the Diaperglu process variables
//    copying the arguments to the args buffer
//
// Failure cases:
//  system could be out of memory
//  the argv[] pointer array could point to invalid memory
//  the operating system may not allow allocating the write execute memory Diaperglu 
//   needs to do just in time compiling (: definitions for Forth people) and the safe 
//   function call returns
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_init  
//
// C prototype:
//  Bufferhandle* dg_init(int argc, char* argv[])
//
// Inputs:
//  int         argc        number of arguments from stdin command line
//  char*       argv[]      array of pointers to argument strings from stdin command line
//
// Outputs:
//  Bufferhandle* pBHarrayhead    On success contains a pointer to a Bufferhandle 
//                                 structure which is used as the bufferhandle for the 
//                                 array where the other bufferhandles are stored.
//                                 This one pointer points to all the data for this 
//                                  process, which is what allows Diaperglu to be 
//                                  reentrant.
//                                On failure contains badbufferhandle (-1)
//
// Action:
//  Takes the command line arguments from stdin and allocates the minimum memory for 
//   a Diaperglu process instance. Then initializes the allocated memory.
//   This includes: 
//    allocating memory for the Bufferhandle array head
//    allocating memory for the bufferhandle array
//    allocating memory for the initial Diaperglu process buffers
//    initializing the jumpbuffer code for 'safe' function call returns
//    initializing the Diaperglu process variables
//    copying the arguments to the args buffer
//    initializing the Diaperglu process starting wordlists
//
// Failure cases:
//  system could be out of memory
//  the argv[] pointer array could point to invalid memory
//  the operating system may not allow allocating the write execute memory Diaperglu 
//   needs to do just in time compiling (: definitions for Forth people) and the safe 
//   function call returns
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_main  
//
// C prototype:
//  void dg_main (int argc, char* argv[])
//
// Inputs:
//  int         argc        number of arguments from stdin command line
//  char*       argv[]      array of pointers to argument strings from stdin command line
//
// Outputs:
//  none
//
// Action:
//  Program main entry point which does:
//   Initializes a Diaperglu instance, keeping track of held resources
//   calls dg_forthquit which determines
//    wether or not to process a cgi/isapi script file, a regular script file
//    or to just interpret user entered commands from stdin in a loop
//   then cleans up the Diaperglu instance, releasing all held resources
//   and exits
//
// Failure cases:
//  If an error occurs during initialization, the program exits
//  If an error occurs during the dg_forthquit processing, hopefully it trapped and 
//   dealt with. This is after all the point of Diaperglu.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// main  
//
// C prototype:
//  int main(int argc, char* argv[])
//
// Inputs:
//  int         argc        number of arguments from stdin command line
//  char*       argv[]      array of pointers to argument strings from stdin command line
//
// Outputs:
//  none
//
// Action:
//  C standard program entry point
//  calls dg_main and exits
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////