G:/ScriptBasic/source/scriba.c

Go to the documentation of this file.
00001 /*
00002 FILE:   scriba.c
00003 HEADER: scriba.h
00004 
00005 --GNU LGPL
00006 This library is free software; you can redistribute it and/or
00007 modify it under the terms of the GNU Lesser General Public
00008 License as published by the Free Software Foundation; either
00009 version 2.1 of the License, or (at your option) any later version.
00010 
00011 This library is distributed in the hope that it will be useful,
00012 but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014 Lesser General Public License for more details.
00015 
00016 You should have received a copy of the GNU Lesser General Public
00017 License along with this library; if not, write to the Free Software
00018 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00019 
00020 TO_HEADER:
00021 #include "report.h"
00022 #include "lexer.h"
00023 #include "sym.h"
00024 #include "expression.h"
00025 #include "syntax.h"
00026 #include "reader.h"
00027 #include "myalloc.h"
00028 #include "builder.h"
00029 #include "memory.h"
00030 #include "execute.h"
00031 #include "buildnum.h"
00032 #include "conftree.h"
00033 #include "filesys.h"
00034 #include "errcodes.h"
00035 #ifdef _DEBUG
00036 #include "testalloc.h"
00037 #endif
00038 #include "command.h"
00039 #include "epreproc.h"
00040 #include "ipreproc.h"
00041 #include "uniqfnam.h"
00042 #include "modumana.h"
00043 #include "ipreproc.h"
00044 
00045 typedef struct _SbProgram {
00046   void *pMEM;
00047   void * (*maf)(size_t);
00048   void   (*mrf)(void *);
00049   unsigned long fErrorFlags;
00050   char *pszFileName;
00051   char *pszCacheFileName;
00052   char *FirstUNIXline;
00053 
00054   void *fpStdouFunction;
00055   void *fpStdinFunction;
00056   void *fpEnvirFunction;
00057   void *pEmbedder;
00058   void *fpReportFunction;
00059   void *pReportPointer;
00060   pSupportTable pSTI;
00061   ExecuteObject *pEPo;
00062 
00063   tConfigTree   *pCONF;
00064   ReadObject    *pREAD;
00065   LexObject     *pLEX;
00066   eXobject      *pEX;
00067   BuildObject   *pBUILD;
00068   ExecuteObject *pEXE;
00069   PreprocObject *pPREP;
00070   } SbProgram, *pSbProgram;
00071 
00072 // type to pass and receive arguments and result values from ScriptBasic functions
00073 typedef struct _SbData {
00074   unsigned char type;
00075   unsigned long size;
00076   union {
00077     double d;
00078     long   l;
00079     unsigned char *s;
00080     } v;
00081   } SbData, *pSbData;
00082 #define SBT_UNDEF  0
00083 #define SBT_DOUBLE 1
00084 #define SBT_LONG   2
00085 #define SBT_STRING 3
00086 #define SBT_ZCHAR  4
00087 
00088 // Access SbData content. Y is present to emulate class argument passing.
00089 #define scriba_GetType(Y,X)   ( (X).type )
00090 #define scriba_GetLength(Y,X) ( (X).size )
00091 #define scriba_GetString(Y,X) ( (X).v.s  )
00092 #define scriba_GetLong(Y,X)   ( (X).v.l  )
00093 #define scriba_GetDouble(Y,X) ( (X).v.d  )
00094 
00095 
00096 #ifdef WIN32
00097 #define CONFIG_ENVIR "Software\\ScriptBasic\\config"
00098 #define CONFIG_FILE  "SCRIBA.INI"
00099 #else
00100 #define CONFIG_ENVIR "SCRIBACONF"
00101 #define CONFIG_FILE  "/etc/scriba/basic.conf"
00102 #endif
00103 
00104 
00105 */
00106 
00107 #include <stdio.h>
00108 #include <stdlib.h>
00109 #include <string.h>
00110 #include <stdarg.h>
00111 #include <stddef.h>
00112 
00113 #include "scriba.h"
00114 #include "basext.h"
00115 
00116 /*POD
00117 =H scriba_new()
00118 
00119 To create a new T<SbProgram> object you have to call this function. The two arguments
00120 should point to T<malloc> and T<free> or similar functions. All later memory allocation
00121 and releasing will be performed using these functions.
00122 
00123 Note that this is the only function that does not require a pointer to an
00124 T<SbProgram> object.
00125 
00126 /*FUNCTION*/
00127 pSbProgram scriba_new(void * (*maf)(size_t),
00128                       void   (*mrf)(void *)
00129   ){
00130 /*noverbatim
00131 CUT*/
00132   pSbProgram pProgram;
00133   void *p;
00134 
00135   p = alloc_InitSegment(maf,mrf);
00136   if( p == NULL )return NULL;
00137 
00138   pProgram = (pSbProgram)alloc_Alloc(sizeof(SbProgram),p);
00139   if( pProgram == NULL ){
00140     alloc_FinishSegment(p);
00141     return NULL;
00142     }
00143 
00144   pProgram->maf              = maf;
00145   pProgram->mrf              = mrf;
00146   pProgram->pMEM             = p;
00147   pProgram->fErrorFlags      = 0;
00148   pProgram->pszFileName      = NULL;
00149   pProgram->pszCacheFileName = NULL;
00150   pProgram->FirstUNIXline    = NULL;
00151   pProgram->fpStdouFunction  = NULL;
00152   pProgram->fpStdinFunction  = NULL;
00153   pProgram->fpEnvirFunction  = NULL;
00154   pProgram->pEmbedder        = NULL;
00155   pProgram->fpReportFunction = report_report;
00156   pProgram->pReportPointer   = (void *)stderr;
00157   pProgram->pSTI             = NULL;
00158   pProgram->pEPo             = NULL;
00159 
00160   pProgram->pCONF  = NULL;
00161   pProgram->pREAD  = NULL;
00162   pProgram->pLEX   = NULL;
00163   pProgram->pEX    = NULL;
00164   pProgram->pBUILD = NULL;
00165   pProgram->pEXE   = NULL;
00166   pProgram->pPREP  = NULL;
00167 
00168   return pProgram;
00169   }
00170 
00171 /*POD
00172 =H scriba_destroy()
00173 
00174 After a ScriptBasic program was successfully execued and there is no need to
00175 run it anymore call this function to release all memory associated with the
00176 code.
00177 
00178 /*FUNCTION*/
00179 void scriba_destroy(pSbProgram pProgram
00180   ){
00181 /*noverbatim
00182 CUT*/
00183 
00184 
00185   scriba_PurgeReaderMemory(pProgram);
00186   scriba_PurgeLexerMemory(pProgram);
00187   scriba_PurgeSyntaxerMemory(pProgram);
00188   scriba_PurgeBuilderMemory(pProgram);
00189   scriba_PurgeExecuteMemory(pProgram);
00190   scriba_PurgePreprocessorMemory(pProgram);
00191 
00192   /* Note that finishing this segment will release the configuration 
00193      information in case it was loaded for this object and not 
00194      inherited from another one. */
00195   alloc_FinishSegment(pProgram->pMEM);
00196   }
00197 
00198 /*POD
00199 =H scriba_NewSbData()
00200 
00201 Allocate and return a pointer to the allocated T<SbData> structure.
00202 
00203 This structure can be used to store ScriptBasic variable data,
00204 long, double or string. This function is called by other functions
00205 from this module. Usually the programmer, who embeds ScriptBasic will rarely
00206 call this function directly. Rather he/she will use R<scriba_NewSbLong()> (as an example)
00207 that creates a variable capable holding a T<long>, sets the type to 
00208 be T<SBT_LNG> and stores initial value.
00209 
00210 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00211 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00212 
00213 /*FUNCTION*/
00214 pSbData scriba_NewSbData(pSbProgram pProgram
00215   ){
00216 /*noverbatim
00217 CUT*/
00218   pSbData p;
00219   p = alloc_Alloc(sizeof(SbData),pProgram->pMEM);
00220   if( p )scriba_InitSbData(pProgram,p);
00221   return p;
00222   }
00223 
00224 /*POD
00225 =H scriba_InitSbData()
00226 
00227 This function initializes an SbData structure to hold undef value.
00228 This function should be used to initialize an allocated T<SbData>
00229 memory structure. This function internally is called by R<scriba_NewSbData()>.
00230 
00231 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00232 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00233 
00234 /*FUNCTION*/
00235 void scriba_InitSbData(pSbProgram pProgram,
00236                          pSbData p
00237   ){
00238 /*noverbatim
00239 CUT*/
00240   p->v.s = NULL;
00241   p->type = SBT_UNDEF;
00242   }
00243 
00244 /*POD
00245 =H scriba_UndefSbData()
00246 
00247 This function sets an T<SbData> structure to hold the undefined value.
00248 
00249 This function should should not be used instead of R<scriba_InitSbData()>.
00250 While that function should be used to inititalize the memory structure this
00251 function should be used to set the value of an alreasdy initialized and probably
00252 used T<SbData> variable to T<undef>.
00253 
00254 The difference inside is that if the T<SbData> structure is a string then this
00255 function releases the memory occupied by the string, while R<scriba_InitSbData()> does not.
00256 
00257 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00258 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00259 
00260 /*FUNCTION*/
00261 void scriba_UndefSbData(pSbProgram pProgram,
00262                         pSbData p
00263   ){
00264 /*noverbatim
00265 CUT*/
00266   if( p->type == SBT_STRING && p->v.s )alloc_Free(p->v.s,pProgram->pMEM);
00267   p->v.s = NULL;
00268   p->type = SBT_UNDEF;
00269   }
00270 
00271 
00272 /*POD
00273 =H scriba_NewSbLong()
00274 
00275 This function allocates and returns a pointer pointing to a structure of
00276 type T<SbData> holding a T<long> value. If the allocation failed the return
00277 value is T<NULL>. If the memory allocation was successful the allocated
00278 structure will have the type T<SBT_LONG> and will hold the initial value
00279 specified by the argument T<lInitValue>.
00280 
00281 /*FUNCTION*/
00282 pSbData scriba_NewSbLong(pSbProgram pProgram,
00283                          long lInitValue
00284   ){
00285 /*noverbatim
00286 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00287 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00288 CUT*/
00289   pSbData p;
00290 
00291   p = scriba_NewSbData(pProgram);
00292   if( p == NULL )return NULL;
00293   p->type = SBT_LONG;
00294   p->v.l = lInitValue;
00295   return p;
00296   }
00297 
00298 /*POD
00299 =H scriba_NewSbDouble()
00300 
00301 This function allocates and returns a pointer pointing to a structure of
00302 type T<SbData> holding a T<double> value. If the allocation failed the return
00303 value is T<NULL>. If the memory allocation was successful the allocated
00304 structure will have the type T<SBT_DOUBLE> and will hold the initial value
00305 specified by the argument T<dInitValue>.
00306 
00307 /*FUNCTION*/
00308 pSbData scriba_NewSbDouble(pSbProgram pProgram,
00309                            double dInitValue
00310   ){
00311 /*noverbatim
00312 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00313 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00314 CUT*/
00315   pSbData p;
00316 
00317   p = scriba_NewSbData(pProgram);
00318   if( p == NULL )return NULL;
00319   p->type = SBT_DOUBLE;
00320   p->v.d = dInitValue;
00321   return p;
00322   }
00323 
00324 /*POD
00325 =H scriba_NewSbUndef()
00326 
00327 This function allocates and returns a pointer pointing to a structure of
00328 type T<SbData> holding an T<undef> value. If the allocation failed the return
00329 value is T<NULL>. If the memory allocation was successful the allocated
00330 structure will have the type T<SBT_UNDEF>.
00331 
00332 /*FUNCTION*/
00333 pSbData scriba_NewSbUndef(pSbProgram pProgram
00334   ){
00335 /*noverbatim
00336 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00337 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00338 CUT*/
00339   pSbData p;
00340 
00341   p = scriba_NewSbData(pProgram);
00342   if( p == NULL )return NULL;
00343   p->type = SBT_UNDEF;
00344   return p;
00345   }
00346 
00347 
00348 /*POD
00349 =H scriba_NewSbString()
00350 
00351 This function allocates and returns a pointer pointing to a structure of
00352 type T<SbData> holding a string value. If the allocation failed the return
00353 value is T<NULL>. If the memory allocation was successful the allocated
00354 structure will have the type T<SBT_STRING> and will hold the initial value
00355 specified by the argument T<pszInitValue>.
00356 
00357 /*FUNCTION*/
00358 pSbData scriba_NewSbString(pSbProgram pProgram,
00359                            char *pszInitValue
00360   ){
00361 /*noverbatim
00362 B<Note on ZCHAR termination:>
00363 
00364 The init value T<pszInitValue> should be a zchar terminated string. Note that
00365 ScriptBasic internally stores the strings as series byte and the length of the
00366 string without any terminating zchar. Therefore the length of the string
00367 that is stored should have been T<strlen(pszInitValue)>. This does not contain the
00368 terminating zchar.
00369 
00370 In reality however we allocate an extra byte that stores the zchar, but the
00371 size of the string is one character less. Therefore ScriptBasic routines
00372 will recognize the size of the string correct and also the caller can
00373 use the string using the macro T<scriba_GetString> as a zchar terminated
00374 C string. This requires an extra byte of storage for each string passed from the
00375 embedding C application to ScriptBasic, but saves a lot of hedeache and also
00376 memory copy when the string has to be used as a zchar terminated string.
00377 
00378 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00379 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00380 CUT*/
00381   pSbData p;
00382 
00383   if( pszInitValue == NULL )return scriba_NewSbUndef(pProgram);
00384 
00385   p = scriba_NewSbData(pProgram);
00386   if( p == NULL )return NULL;
00387   p->type = SBT_STRING;
00388   p->size = strlen(pszInitValue);
00389   if( p->size ){
00390     p->v.s = alloc_Alloc(p->size+1,pProgram->pMEM);
00391     if( p->v.s == NULL ){
00392       alloc_Free(p,pProgram->pMEM);
00393       return NULL;
00394       }
00395     memcpy(p->v.s,pszInitValue,p->size+1);
00396     }else{
00397     p->v.s = NULL;
00398     }
00399   return p;
00400   }
00401 
00402 /*POD
00403 =H scriba_NewSbBytes()
00404 
00405 This function allocates and returns a pointer pointing to a structure of
00406 type T<SbData> holding a string value. If the allocation failed the return
00407 value is T<NULL>. If the memory allocation was successful the allocated
00408 structure will have the type T<SBT_STRING> and will hold the initial value
00409 specified by the argument T<pszInitValue> of the length T<len>.
00410 
00411 /*FUNCTION*/
00412 pSbData scriba_NewSbBytes(pSbProgram pProgram,
00413                           unsigned long len,
00414                           unsigned char *pszInitValue
00415   ){
00416 /*noverbatim
00417 This function allocates T<len>+1 number of bytes data and
00418 stores the initial value pointed by T<pszInitValue> in it.
00419 
00420 The extra plus one byte is an extra terminating zero char
00421 that may help the C programmers to handle the string
00422 in case it is not binary. Please also read the not on the terminating ZChar
00423 in the function R<scriba_NewSbString()>.
00424 
00425 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00426 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00427 CUT*/
00428   pSbData p;
00429 
00430   if( pszInitValue == NULL )return scriba_NewSbUndef(pProgram);
00431 
00432   p = scriba_NewSbData(pProgram);
00433   if( p == NULL )return NULL;
00434   p->type = SBT_STRING;
00435   p->size = len;
00436   if( p->size ){
00437     p->v.s = alloc_Alloc(p->size+1,pProgram->pMEM);
00438     if( p->v.s == NULL ){
00439       alloc_Free(p,pProgram->pMEM);
00440       return NULL;
00441       }
00442     memcpy(p->v.s,pszInitValue,p->size);
00443     /* for the sake of lasy C programmers we store a terminating zchar */
00444     p->v.s[p->size] = (char)0;
00445     }else{
00446     p->v.s = NULL;
00447     }
00448   return p;
00449   }
00450 
00451 /*POD
00452 =H scriba_DestroySbData()
00453 
00454 Call this function to release the memory that was allocated by any
00455 of the T<NewSbXXX> functions. This function releases the memory and
00456 also cares to release the memory occupied by the characters in case the
00457 value had the type T<SBT_STRING>.
00458 
00459 /*FUNCTION*/
00460 void scriba_DestroySbData(pSbProgram pProgram,
00461                           pSbData p
00462   ){
00463 /*noverbatim
00464 See also R<scriba_NewSbLong()>, R<scriba_NewSbDouble()>, R<scriba_NewSbUndef()>, R<scriba_NewSbString()>,
00465 R<scriba_NewSbBytes()>, R<scriba_DestroySbData()>.
00466 CUT*/
00467   if( p->type == SBT_STRING )
00468     alloc_Free(p->v.s,pProgram->pMEM);
00469   alloc_Free(p,pProgram->pMEM);
00470   }
00471 
00472 /*POD
00473 =H scriba_PurgeReaderMemory()
00474 
00475 Call this function to release all memory that was allocated by the
00476 reader module. The memory data is needed so long as long the lexical analyzer
00477 has finished.
00478 /*FUNCTION*/
00479 void scriba_PurgeReaderMemory(pSbProgram pProgram
00480   ){
00481 /*noverbatim
00482 CUT*/
00483   if( pProgram->pREAD ){
00484     alloc_FinishSegment(pProgram->pREAD->pMemorySegment);
00485     alloc_Free(pProgram->pREAD,pProgram->pMEM);
00486     }
00487   pProgram->pREAD = NULL;
00488   }
00489 
00490 /*POD
00491 =H scriba_PurgeLexerMemory()
00492 
00493 /*FUNCTION*/
00494 void scriba_PurgeLexerMemory(pSbProgram pProgram
00495   ){
00496 /*noverbatim
00497 CUT*/
00498   if( pProgram->pLEX )
00499     alloc_FinishSegment(pProgram->pLEX->pMemorySegment);
00500   alloc_Free(pProgram->pLEX,pProgram->pMEM);
00501   pProgram->pLEX = NULL;
00502   }
00503 
00504 /*POD
00505 =H scriba_PurgeSyntaxerMemory()
00506 
00507 /*FUNCTION*/
00508 void scriba_PurgeSyntaxerMemory(pSbProgram pProgram
00509   ){
00510 /*noverbatim
00511 CUT*/
00512   if( pProgram->pEX )
00513     ex_free( pProgram->pEX );
00514   alloc_Free(pProgram->pEX,pProgram->pMEM);
00515   pProgram->pEX = NULL;
00516   }
00517 
00518 /*POD
00519 =H scriba_PurgeBuilderMemory()
00520 
00521 /*FUNCTION*/
00522 void scriba_PurgeBuilderMemory(pSbProgram pProgram
00523   ){
00524 /*noverbatim
00525 CUT*/
00526   if( pProgram->pBUILD && pProgram->pBUILD->pMemorySegment)
00527     alloc_FinishSegment(pProgram->pBUILD->pMemorySegment);
00528   alloc_Free(pProgram->pBUILD,pProgram->pMEM);
00529   pProgram->pBUILD = NULL;
00530   }
00531 
00532 
00533 /*POD
00534 =H scriba_PurgePreprocessorMemory()
00535 
00536 This function purges the memory that was needed to run the preprocessors.
00537 
00538 /*FUNCTION*/
00539 void scriba_PurgePreprocessorMemory(pSbProgram pProgram
00540   ){
00541 /*noverbatim
00542 CUT*/
00543 
00544   if( pProgram->pPREP ){
00545     ipreproc_PurgePreprocessorMemory(pProgram->pPREP);
00546     alloc_Free(pProgram->pPREP,pProgram->pMEM);
00547     pProgram->pPREP = NULL;
00548     }
00549   }
00550 
00551 /*POD
00552 =H scriba_PurgeExecuteMemory()
00553 
00554 This function purges the memory that was needed to execute the program,
00555 but before that it executes the finalization part of the execution.
00556 
00557 /*FUNCTION*/
00558 void scriba_PurgeExecuteMemory(pSbProgram pProgram
00559   ){
00560 /*noverbatim
00561 CUT*/
00562   int iErrorCode;
00563 
00564   if( pProgram->pEXE ){
00565     execute_FinishExecute(pProgram->pEXE,&iErrorCode);
00566     if( pProgram->pEXE->pMo &&
00567         pProgram->pEXE->pMo->pMemorySegment )alloc_FinishSegment(pProgram->pEXE->pMo->pMemorySegment);
00568     alloc_FinishSegment(pProgram->pEXE->pMemorySegment);
00569     }
00570   alloc_Free(pProgram->pEXE,pProgram->pMEM);
00571   pProgram->pEXE = NULL;
00572   }
00573 
00574 /*POD
00575 =H scriba_SetFileName()
00576 
00577 Call this function to set the file name where the source informaton is.
00578 This file name is used by the functions R<scriba_LoadBinaryProgram()> and
00579 R<scriba_LoadSourceProgram> as well as error reporting functions to display
00580 the location of the error.
00581 
00582 /*FUNCTION*/
00583 int scriba_SetFileName(pSbProgram pProgram,
00584                        char *pszFileName
00585   ){
00586 /*noverbatim
00587 The argument T<pszFileName> should be zchar terminated
00588 string holding the file name.
00589 CUT*/
00590   if( pProgram->pszFileName )alloc_Free(pProgram->pszFileName,pProgram->pMEM);
00591   pProgram->pszFileName = NULL;
00592   if( pszFileName ){
00593     pProgram->pszFileName = alloc_Alloc(strlen(pszFileName)+1,pProgram->pMEM);
00594     if( pProgram->pszFileName == NULL )SCRIBA_ERROR_MEMORY_LOW;
00595     strcpy(pProgram->pszFileName,pszFileName);
00596     }
00597   return SCRIBA_ERROR_SUCCESS;
00598   }
00599 
00600 /*POD
00601 =H scriba_GettingConfiguration()
00602 
00603 R<scriba_LoadConfiguration()> and R<scriba_InheritConfiguration()> can be used to
00604 specify configuration information for a ScriptBasic program. Here
00605 we describe the differences and how to use the two functions for
00606 single-process single-basic and for single-process multiple-basic
00607 applications.
00608 
00609 To execute a ScriptBasic program you usually need configuration information.
00610 The configuration information for the interpreter is stored in a file.
00611 The function R<scriba_LoadConfiguration()> reads the file and loads it into memory
00612 into the T<SbProgram> object. When the object is destroyed the configuration
00613 information is automatically purged from memory.
00614 
00615 Some implementations like the Eszter SB Engine variation of ScriptBasic starts
00616 several interpreter thread within the same process. In this case the configuration
00617 information is read only once and all the running interpreters share the same
00618 configuration information.
00619 
00620 To do this the embedding program has to create a pseudo T<SbProgram> object that
00621 does not run any ScriptBasic program, but is used only to load the configuration
00622 information calling the function R<scriba_LoadConfiguration()>. Other T<SbProgram> objects
00623 that do intepret ScriptBasic program should inherit this configuration calling the
00624 function R<scriba_InheritConfiguration()>. When a T<SbProgram> object is destroyed the
00625 configuration is not destroyed if that was inherited belonging to a different object.
00626 It remains in memory and can later be used by other intrepreter instances.
00627 
00628 Inheriting the configuration is fast because it does not require loading the
00629 configuration information from file. This is essentially sets a pointer in the
00630 internal interpreter structure to point to the configuration information held
00631 by the other object and all the parallel running interpreters structures
00632 point to the same piece of memory holding the common configuration information.
00633 
00634 See the configuration handling functions R<scriba_LoadConfiguration()> and R<scriba_InheritConfiguration()>.
00635 CUT*/
00636 
00637 /*POD
00638 =H scriba_LoadConfiguration()
00639 
00640 This function should be used to load the configuration information
00641 from a file.
00642 
00643 The return value is zero on success and the error code when error happens.
00644 /*FUNCTION*/
00645 int scriba_LoadConfiguration(pSbProgram pProgram,
00646                              char *pszForcedConfigurationFileName
00647   ){
00648 /*noverbatim
00649 CUT*/
00650   int iError;
00651   pProgram->pCONF = alloc_Alloc(sizeof(tConfigTree),pProgram->pMEM);
00652   if( pProgram->pCONF == NULL )return SCRIBA_ERROR_MEMORY_LOW;
00653 
00654   iError = cft_start(pProgram->pCONF,alloc_Alloc,alloc_Free,pProgram->pMEM,CONFIG_ENVIR,CONFIG_FILE,pszForcedConfigurationFileName);
00655   return iError;
00656   }
00657 
00658 /*POD
00659 =H scriba_GetConfigFileName()
00660 
00661 This function tells whet the configuration file is. There is no need to call this function to read the configuration file.
00662 This is needed only when the main program want to manipulate the configuration file in some way. For example the command
00663 line version of ScriptBasic uses this function when the option T<-k> is used to compile a configuration file.
00664 
00665 The first argument has to be a valid ScriptBasic program object. The second argument should point to a valid T<char *> pointer that
00666 will get the pointer value to the configuration file name after the function returns.
00667 /*FUNCTION*/
00668 int scriba_GetConfigFileName(pSbProgram pProgram,
00669                              char **ppszFileName
00670   ){
00671 /*noverbatim
00672 The function returns zero if no error happens, or the error code.
00673 CUT*/
00674   int iError;
00675 
00676   iError = cft_GetConfigFileName(pProgram->pCONF,ppszFileName,CONFIG_ENVIR,CONFIG_FILE);
00677   return iError;
00678   }
00679 
00680 /*POD
00681 =H scriba_InheritConfiguration()
00682 
00683 Use this function to get the configuration from another program object.
00684 
00685 The return value is zero on success and error code if error has happened.
00686 /*FUNCTION*/
00687 int scriba_InheritConfiguration(pSbProgram pProgram,
00688                                 pSbProgram pFrom
00689   ){
00690 /*noverbatim
00691 CUT*/
00692   if( pFrom == NULL )return 1;
00693   pProgram->pCONF = pFrom->pCONF;
00694   if( pProgram->pCONF == NULL )return 1;
00695   return 0;
00696   }
00697 
00698 /*POD
00699 =H scriba_InitModuleInterface()
00700 
00701 Initialize the Support Function Table of a process level ScriptBasic program object to be inherited
00702 by other program objects. If you read it first time, read on until you understand what this
00703 function really does and rather how to use it!
00704 
00705 This is going to be a bit long, but you better read it along with the documentation of the
00706 function R<scriba_InheritModuleInterface()>.
00707 
00708 This function is needed only for programs that are
00709 =itemize
00710 =item multi thread running several interpreters simultaneous in a single process
00711 =item support modules like the sample module T<mt> that support multithread behaviour and
00712       need to implement worker thread needing call-back functions.
00713 =noitemize
00714 
00715 You most probably know that modules can access system and ScriptBasic fucntions via a
00716 call-back table. That is a huge T<struct> containing pointers to the functions that
00717 ScriptBasic implements. This is the T<ST> (aka support table).
00718 
00719 This helps module writers to write system independent
00720 code as well as to access ScriptBasic functions easily. On the other hand modules are
00721 also free to alter this table and because many functions, tough not all are called via this
00722 table by ScriptBasic itself a module may alter the core behavior of ScriptBasic.
00723 
00724 For this reason each interpreter has its own copy of T<ST>.
00725 This means that if an interpreter alters the table it has no effect on another interpreter
00726 running in the same process in anther thread.
00727 
00728 This is fine so far. How about modules that run asynchronous threads? For example the very first
00729 interpter thread that uses the module T<mt> starts in the initialization a thread that later 
00730 deletes all sessions that time out. This thread lives a long life.
00731 
00732 The thread that starts the worker thread is an interpreter thread and has its own copy of the T<ST>.
00733 The thread started asynchronous however should not use this T<ST> because the table is purged 
00734 from memory when the interpreter instance it blelonged to finishes.
00735 
00736 To have T<ST> for worker threads there is a need for a program object that is not purged
00737 from memory so long as long the process is alive. Fortunately there is such an object: the
00738 configuration program object. Configuration is usually read only once by multi-thread implementations
00739 and the same configuration information is shared by the serveral threads. The same way the
00740 several program objects may share a T<ST>.
00741 
00742 The difference is that configuration is NOT altered by the interpreter or by any module in any way
00743 but T<ST> may. Thus each  execution object has two pointers: T<pST> and T<pSTI>. While T<pST> points to
00744 the support table that belongs to the interpreter instance the secondpointer T<pSTI> points to
00745 a T<ST> that is global for the whole process and is permanent. This T<ST> is to be used by worker threads
00746 and should not be altered by the module without really good reason.
00747 
00748 Thus: Don't call this function for normal program objects! For usualy program objects module
00749 interface is automatically initialized when the first module function is called. Call this function
00750 to initialize a T<ST> for a pseudo program object that is never executed but rather used to inherit this
00751 T<ST> for worker threads.
00752 
00753 /*FUNCTION*/
00754 int scriba_InitModuleInterface(pSbProgram pProgram
00755   ){
00756 /*noverbatim
00757 CUT*/
00758 
00759   if( pProgram->pEXE == NULL ){
00760     pProgram->pEXE = alloc_Alloc( sizeof(ExecuteObject) , pProgram->pMEM );
00761     if( pProgram->pEXE == NULL )return SCRIBA_ERROR_MEMORY_LOW;
00762     /* The support table should be set to NULL because this is checked by modu_Init. */
00763     pProgram->pEXE->pST = NULL;
00764     /* The inherited execution object is itself so that besPROCXXX works correct. */
00765     pProgram->pEXE->pEPo = pProgram->pEXE;
00766     thread_InitMutex( &(pProgram->pEXE->mxModules) );
00767     pProgram->pEXE->memory_allocating_function = pProgram->maf;
00768     pProgram->pEXE->memory_releasing_function = pProgram->mrf;
00769     pProgram->pEXE->pMemorySegment = alloc_InitSegment(pProgram->pEXE->memory_allocating_function,
00770                                                        pProgram->pEXE->memory_releasing_function);
00771     if( pProgram->pEXE->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
00772     /* we set this field also and thus in case the config program object and the module interface
00773        program object is the same the external module worker thread can access config information */
00774     pProgram->pEXE->pConfig = pProgram->pCONF;
00775     }
00776   modu_Init(pProgram->pEXE,1);
00777   return SCRIBA_ERROR_SUCCESS;
00778   }
00779 
00780 /*POD
00781 =H scriba_InheritModuleInterface()
00782 
00783 Inherit the support function table (T<ST>) from another program object.
00784 
00785 Note that the program object is going to initialize its own T<ST> the normal
00786 way. The inherited T<ST> will only be used by worker threads that live a long
00787 life and may exist when the initiating interpreter thread already exists.
00788 
00789 For further information please read the description of the function R<scriba_InitModuleInterface()>.
00790 
00791 /*FUNCTION*/
00792 int scriba_InheritModuleInterface(pSbProgram pProgram,
00793                                   pSbProgram pFrom
00794   ){
00795 /*noverbatim
00796 CUT*/
00797 
00798   pProgram->pSTI = pFrom->pEXE->pST;
00799   return SCRIBA_ERROR_SUCCESS;
00800   }
00801 
00802 /*POD
00803 =H scriba_InheritExecuteObject()
00804 
00805 /*FUNCTION*/
00806 int scriba_InheritExecuteObject(pSbProgram pProgram,
00807                                   pSbProgram pFrom
00808   ){
00809 /*noverbatim
00810 CUT*/
00811   pProgram->pEPo = pFrom->pEXE;
00812   return SCRIBA_ERROR_SUCCESS;
00813   }
00814 
00815 /*POD
00816 =H scriba_SetProcessSbObject()
00817 
00818 Use this program in multi-thread environment to tell the actual interpreter
00819 which object is the process level pseudo object that 
00820 
00821 =itemize
00822 =item holds the shared (among interpreter thread objects) configuration 
00823 information (see R<scriba_InheritConfiguration()>)
00824 =item holds the process level module interface (see R<scriba_InheritModuleInterface()>)
00825 =item holds the list of loaded modules that are not unloaded by the thread loaded the module
00826 =noitemize
00827 
00828 If the embeddingprogram calls this function there is no need to call R<scriba_InheritConfiguration()>
00829 and R<scriba_InheritModuleInterface()>. This function call does all those tasks and also other things.
00830 
00831 /*FUNCTION*/
00832 int scriba_SetProcessSbObject(pSbProgram pProgram,
00833                               pSbProgram pProcessObject
00834   ){
00835 /*noverbatim
00836 CUT*/
00837   int iError;
00838 
00839   if( iError = scriba_InheritConfiguration(pProgram,pProcessObject) )return iError;
00840   if( iError = scriba_InheritModuleInterface(pProgram,pProcessObject) )return iError;
00841   if( iError = scriba_InheritExecuteObject(pProgram,pProcessObject) )return iError;
00842   return SCRIBA_ERROR_SUCCESS;
00843   }
00844 
00845 /*POD
00846 =H scriba_ShutdownMtModules()
00847 
00848 A multi threaded application should call this function for the process SB object
00849 when the process finishes. Calling this function will call each of the shutdown
00850 functions of those external modules that decided to keep in memory and export
00851 the shutdown function named T<shutmodu>. This allows these modules to gracefully
00852 shut down their operation. As an example cached data can be written to disk, or
00853 database connections can be closed.
00854 
00855 /*FUNCTION*/
00856 int scriba_ShutdownMtModules(pSbProgram pProgram
00857   ){
00858 /*noverbatim
00859 CUT*/
00860   pModule pThisModule;
00861 
00862   thread_LockMutex( &(pProgram->pEXE->mxModules) );
00863   pThisModule = pProgram->pEXE->modules;
00864   while( pThisModule ){
00865     modu_ShutdownModule(pProgram->pEXE,pThisModule);
00866     pThisModule = pThisModule->next;
00867     }
00868   thread_UnlockMutex( &(pProgram->pEXE->mxModules) );
00869   return SCRIBA_ERROR_SUCCESS;
00870   }
00871 
00872 
00873 /*POD
00874 =H scriba_SetCgiFlag()
00875 
00876 You can call this function to tell the reporting subsystem that
00877 this code runs in a CGI environment and therefore it should format
00878 error messages according to the CGI standard sending to the 
00879 standard output including HTTP headers and HTML code pieces.
00880 
00881 /*FUNCTION*/
00882 void scriba_SetCgiFlag(pSbProgram pProgram
00883   ){
00884 /*noverbatim
00885 CUT*/
00886   pProgram->fErrorFlags |= REPORT_F_CGI;
00887   }
00888 
00889 /*POD
00890 =H scriba_SetReportFunction()
00891 
00892 This function should be used to set the report function for a program. The report function
00893 is used to send info, warning, error, fatal and internal error messages to the user.
00894 
00895 In case you want to implement a specific report function see the sample implementation in the
00896 file T<report.c>. The documentation of the function T<report_report> describes not only the details
00897 of the sample implementation but also the implementation requests for other reporting functions.
00898 
00899 /*FUNCTION*/
00900 void scriba_SetReportFunction(pSbProgram pProgram,
00901                               void *fpReportFunction
00902   ){
00903 /*noverbatim
00904 CUT*/
00905   pProgram->fpReportFunction = fpReportFunction;
00906   if( pProgram->pEXE )pProgram->pEXE->report = fpReportFunction;
00907   }
00908 
00909 /*POD
00910 =H scriba_SetReportPointer()
00911 
00912 This pointer will be passed to the reporting function. The default
00913 reporting uses this pointer as a T<FILE *> pointer. The default value
00914 for this pointer is T<stderr>.
00915 
00916 Other implementations of the reporting function may use this pointer
00917 according their needs. For example the WIN32 IIS ISAPI implementation
00918 uses this pointer to point to the extension controll block structure.
00919 /*FUNCTION*/
00920 void scriba_SetReportPointer(pSbProgram pProgram,
00921                              void *pReportPointer
00922   ){
00923 /*noverbatim
00924 CUT*/
00925   pProgram->pReportPointer = pReportPointer;
00926   if( pProgram->pEXE )pProgram->pEXE->reportptr = pReportPointer;
00927   }
00928 
00929 /*POD
00930 =H scriba_SetStdin()
00931 
00932 You can call this function to define a special standard input function. This
00933 pointer should point to a function that accepts a T<void *> pointer
00934 as argument. Whenever the ScriptBasic program tries to read from the
00935 standard input it calls this function pasing the embedder pointer as
00936 argument.
00937 
00938 If the T<stdin> function is not defined or the parameter is T<NULL>
00939 the interpreter will read the normal T<stdin> stream.
00940 
00941 /*FUNCTION*/
00942 void scriba_SetStdin(pSbProgram pProgram,
00943                      void *fpStdinFunction
00944   ){
00945 /*noverbatim
00946 CUT*/
00947   pProgram->fpStdinFunction = fpStdinFunction;
00948   if( pProgram->pEXE )pProgram->pEXE->fpStdinFunction = fpStdinFunction;
00949   }
00950 
00951 /*POD
00952 =H scriba_SetStdout()
00953 
00954 You can call this function to define a special standard output function. This
00955 pointer should point to a function that accepts a T<(char, void *)> arguments.
00956 Whenever the ScriptBasic program tries to send a character to the standard output
00957 it calls this function. The first parameter is the character to write, the second
00958 is the embedder pointer.
00959 
00960 If the standard output function is not defined or the parameter is T<NULL>
00961 the interpreter will write the normal T<stdout> stream.
00962 
00963 /*FUNCTION*/
00964 void scriba_SetStdout(pSbProgram pProgram,
00965                       void *fpStdoutFunction
00966   ){
00967 /*noverbatim
00968 CUT*/
00969   pProgram->fpStdouFunction = fpStdoutFunction;
00970   if( pProgram->pEXE )pProgram->pEXE->fpStdouFunction = fpStdoutFunction;
00971   }
00972 
00973 /*POD
00974 =H scriba_SetEmbedPointer()
00975 
00976 This function should be used to set the embed pointer.
00977 
00978 The embed pointer is a pointer that is not used by ScriptBasic itself. This
00979 pointer is remembered by ScriptBasic and is passed to call-back functions.
00980 Like the standard input, output and environment functions that the embedding
00981 application may provide this pointer is also available to external modules implemented
00982 in C or other compiled language in DLL or SO files.
00983 
00984 The embedder pointer should usually point to the T<struct> of the thread local data.
00985 For example the Windows NT IIS variation of ScriptBasic sets this variable to point to
00986 the extension control block.
00987 
00988 If this pointer is not set ScriptBasic will pass T<NULL> pointer to the extensions and
00989 to the call-back function.
00990 /*FUNCTION*/
00991 void scriba_SetEmbedPointer(pSbProgram pProgram,
00992                             void *pEmbedder
00993   ){
00994 /*noverbatim
00995 CUT*/
00996   pProgram->pEmbedder = pEmbedder;
00997   if( pProgram->pEXE )pProgram->pEXE->pEmbedder = pEmbedder;
00998   }
00999 
01000 /*POD
01001 =H scriba_SetEnvironment()
01002 
01003 You can call this function to define a special environment query function. This
01004 pointer should point to a function that accepts a T<(void *, char *, long )> arguments.
01005 
01006 Whenever the ScriptBasic program tries to get the value of an enviroment variable
01007 it calls this function. The first argument is the embedder pointer.
01008 
01009 The second argument is the name of the environment variable to retrieve or T<NULL>.
01010 
01011 The third argument is either zero or is the serial number of the environment variable.
01012 
01013 ScriptBasic never calls this function with both specifying the environment variable name
01014 and the serial number.
01015 
01016 The return value of the function should either be T<NULL> or should point to a string that
01017 holds the zero character terminated value of the environment variable. This string is not
01018 changed by ScriptBasic.
01019 
01020 If the special environment function is not defined or is T<NULL> ScriptBasic uses the
01021 usual environment of the process calling the system functionT<getenv>.
01022 
01023 /*FUNCTION*/
01024 void scriba_SetEnvironment(pSbProgram pProgram,
01025                            void *fpEnvirFunction
01026   ){
01027 /*noverbatim
01028 For a good example of a self-written environment function see the source of the Eszter SB Engine
01029 that alters the environment function so that the ScriptBasic programs feel as if they were executed in a
01030 real CGI environment.
01031 CUT*/
01032   pProgram->fpEnvirFunction = fpEnvirFunction;
01033   if( pProgram->pEXE )pProgram->pEXE->fpEnvirFunction = fpEnvirFunction;
01034   }
01035 
01036 
01037 /*POD
01038 =H scriba_LoadBinaryProgramWithOffset()
01039 
01040 Use this function to load ScriptBasic program from a file that is already compiled into
01041 internal form, and the content of the program is starting on T<lOffset>
01042 
01043 The return value is the number of errors (hopefully zero) during program load.
01044 
01045 /*FUNCTION*/
01046 int scriba_LoadBinaryProgramWithOffset(pSbProgram pProgram,
01047                                        long lOffset,
01048                                        long lEOFfset
01049   ){
01050 /*noverbatim
01051 Before calling this function the function R<scriba_SetFileName()> should have been called specifying the
01052 file name.
01053 CUT*/
01054   pProgram->pBUILD = alloc_Alloc( sizeof(BuildObject) , pProgram->pMEM);
01055   if( pProgram->pBUILD == NULL )return 1;
01056 
01057   pProgram->pBUILD->memory_allocating_function = pProgram->maf;
01058   pProgram->pBUILD->memory_releasing_function  = pProgram->mrf;
01059   pProgram->pBUILD->iErrorCounter = 0;
01060   pProgram->pBUILD->reportptr = pProgram->pReportPointer;
01061   pProgram->pBUILD->report   = pProgram->fpReportFunction;
01062   pProgram->pBUILD->fErrorFlags = pProgram->fErrorFlags;
01063   build_LoadCodeWithOffset(pProgram->pBUILD,pProgram->pszFileName,lOffset,lEOFfset);
01064   return pProgram->pBUILD->iErrorCounter;
01065   }
01066 
01067 /*POD
01068 =H scriba_LoadBinaryProgram()
01069 
01070 Use this function to load ScriptBasic program from a file that is already compiled into
01071 internal form.
01072 
01073 The return value is the number of errors (hopefully zero) during program load.
01074 
01075 /*FUNCTION*/
01076 int scriba_LoadBinaryProgram(pSbProgram pProgram
01077   ){
01078 /*noverbatim
01079 Before calling this function the function R<scriba_SetFileName()> should have been called specifying the
01080 file name.
01081 CUT*/
01082   return scriba_LoadBinaryProgramWithOffset(pProgram,0L,0L);
01083   }
01084 
01085 /*POD
01086 =H scriba_InheritBinaryProgram()
01087 
01088 Use this function in application that keeps the program code in memory.
01089 
01090 /*FUNCTION*/
01091 int scriba_InheritBinaryProgram(pSbProgram pProgram,
01092                                 pSbProgram pFrom
01093   ){
01094 /*noverbatim
01095 
01096 The function inherits the binary code from the program object T<pFrom>.
01097 In server type applications the compiled binary code of a BASIC program may
01098 be kept in memory. To do this a pseudo program object should be created that
01099 loads the binary code and is not destroyed.
01100 
01101 The program object used to execute the code should inherit the binary code from
01102 this pseudo object calling this function. This is similar to the configuration
01103 inheritance.
01104 
01105 CUT*/
01106   pProgram->pBUILD = alloc_Alloc( sizeof(BuildObject) , pProgram->pMEM);
01107   if( pProgram->pBUILD == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01108 
01109   memcpy(pProgram->pBUILD,pFrom->pBUILD,sizeof(BuildObject));
01110   pProgram->pBUILD->memory_allocating_function = pProgram->maf;
01111   pProgram->pBUILD->memory_releasing_function  = pProgram->mrf;
01112   pProgram->pBUILD->iErrorCounter = 0;
01113   pProgram->pBUILD->reportptr = pProgram->pReportPointer;
01114   pProgram->pBUILD->report   = pProgram->fpReportFunction;
01115   pProgram->pBUILD->fErrorFlags = pProgram->fErrorFlags;
01116   return SCRIBA_ERROR_SUCCESS;
01117   }
01118 
01119 
01120 /*POD
01121 =H scriba_LoadInternalPreprocessor()
01122 
01123 This function can be used by embedding applications to load an
01124 internal preprocessor into the interpereter. Note that preprocessors
01125 are usually loaded by the reader module when a T<preprocess> statement
01126 is found. However some preprocessors in some variation of the interpreter
01127 may be loaded due to configuration or command line option and not
01128 because the source requests it.
01129 
01130 The preprocessors that are requested to be loaded because the source
01131 contains a T<preprocess> line usually implement special language
01132 fetures. The preprocessors that are loaded independent of the source
01133 because command line option or some other information tells the variation
01134 to call this function are usually debuggers, profilers.
01135 
01136 (To be honest, by the time I write it there is no any internal preprocessors
01137 developed except the test one, but the statement above will become true.)
01138 
01139 /*FUNCTION*/
01140 int scriba_LoadInternalPreprocessor(pSbProgram pProgram,
01141                             char *ppszPreprocessorName[]
01142   ){
01143 /*noverbatim
01144 The first argument is the program object. If the program object does not
01145 have a preprocessor object the time it is called the preprocessor object is
01146 created and initiated.
01147 
01148 The second argument is the array of names of the preprocessor as it is present
01149 in the configuration file. This is not the name of the DLL/SO file, but
01150 rather the symbolic name, which is associated with the file. The final element
01151 of the array has to be T<NULL>.
01152 
01153 The return value is zero or the error code.
01154 CUT*/
01155   int iError,i;
01156 
01157   /* if the program object does not have a PreprocObject then create it */
01158   if( pProgram->pPREP == NULL ){
01159     pProgram->pPREP = alloc_Alloc( sizeof(PreprocObject) , pProgram->pMEM );
01160     if( pProgram->pPREP == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01161     ipreproc_InitStructure(pProgram->pPREP);
01162     pProgram->pPREP->pMemorySegment = alloc_InitSegment(pProgram->maf,
01163                                                         pProgram->mrf);
01164     if( pProgram->pPREP->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01165     pProgram->pPREP->pSB = pProgram;
01166     }
01167 
01168   for( i = 0 ; ppszPreprocessorName[i] ; i++ )
01169     if( iError = ipreproc_LoadInternalPreprocessor(
01170                    pProgram->pPREP,
01171                    ppszPreprocessorName[i]) )return iError;
01172   return COMMAND_ERROR_SUCCESS;
01173   }
01174 
01175 /*POD
01176 =H scriba_ReadSource()
01177 
01178 Loads the source code of a ScriptBasic program from a text file.
01179 
01180 The return code is the number of errors happened during read.
01181 
01182 /*FUNCTION*/
01183 int scriba_ReadSource(pSbProgram pProgram
01184   ){
01185 /*noverbatim
01186 B<Do not get confused!> This function only reads the source. Does not compile it.
01187 You will usually need R<scriba_LoadSourceProgram()> that does reading, analyzing, building
01188 and all memory releases leaving finally a ready-to-run code in memory.
01189 
01190 Before calling this function the function R<scriba_SetFileName()> should have been called specifying the
01191 file name.
01192 
01193 See also R<scriba_ReadSource()>, R<scriba_DoLexicalAnalysis()>,
01194 R<scriba_DoSyntaxAnalysis()>, R<scriba_BuildCode()>.
01195 CUT*/
01196 
01197   pProgram->pREAD = alloc_Alloc( sizeof(ReadObject) , pProgram->pMEM );
01198   if( pProgram->pREAD == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01199 
01200   reader_InitStructure(pProgram->pREAD);
01201   pProgram->pREAD->memory_allocating_function = alloc_Alloc;
01202   pProgram->pREAD->memory_releasing_function = alloc_Free;
01203   pProgram->pREAD->pMemorySegment = alloc_InitSegment(
01204                                      pProgram->maf,
01205                                      pProgram->mrf);
01206   if( pProgram->pREAD->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01207   pProgram->pREAD->report = pProgram->fpReportFunction;
01208   pProgram->pREAD->reportptr = pProgram->pReportPointer;
01209   pProgram->pREAD->iErrorCounter = 0;
01210   pProgram->pREAD->fErrorFlags = pProgram->fErrorFlags;
01211   pProgram->pREAD->pConfig = pProgram->pCONF;
01212 
01213   /* here we have to initialize the preprocessor object 
01214      if it was not initialized before because the reader uses that */
01215   if( pProgram->pPREP == NULL ){
01216     pProgram->pPREP = alloc_Alloc( sizeof(PreprocObject) , pProgram->pMEM );
01217     if( pProgram->pPREP == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01218     ipreproc_InitStructure(pProgram->pPREP);
01219     pProgram->pPREP->pMemorySegment = alloc_InitSegment(
01220                                        pProgram->maf,
01221                                        pProgram->mrf);
01222     if( pProgram->pPREP->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01223     pProgram->pPREP->pSB = pProgram;
01224     }
01225   pProgram->pREAD->pPREP = pProgram->pPREP; /* this is needed by the reader to handle the internal preprocessors */
01226 
01227   if( ! reader_ReadLines(pProgram->pREAD,pProgram->pszFileName) ){
01228     if( pProgram->pREAD->FirstUNIXline ){
01229       pProgram->FirstUNIXline = alloc_Alloc(strlen(pProgram->pREAD->FirstUNIXline)+1,pProgram->pMEM);
01230       if( pProgram->FirstUNIXline == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01231       strcpy(pProgram->FirstUNIXline,pProgram->pREAD->FirstUNIXline);
01232       }
01233     }
01234   return pProgram->pREAD->iErrorCounter;
01235   }
01236 
01237 /*POD
01238 =H scriba_DoLexicalAnalysis()
01239 
01240 This function performs lexical analysis after the source file has beed read.
01241 
01242 This function is rarely needeed by applicationdevelopers. See R<scriba_LoadSourceProgram()>
01243 instead.
01244 /*FUNCTION*/
01245 int scriba_DoLexicalAnalysis(pSbProgram pProgram
01246   ){
01247 /*noverbatim
01248 See also R<scriba_ReadSource()>, R<scriba_DoLexicalAnalysis()>,
01249 R<scriba_DoSyntaxAnalysis()>, R<scriba_BuildCode()>.
01250 CUT*/
01251   pProgram->pLEX = alloc_Alloc( sizeof(LexObject) , pProgram->pMEM );
01252   if( pProgram->pLEX == NULL )return 1;
01253 
01254   reader_StartIteration(pProgram->pREAD);
01255 
01256   pProgram->pLEX->memory_allocating_function = alloc_Alloc;
01257   pProgram->pLEX->memory_releasing_function = alloc_Free;
01258   pProgram->pLEX->pMemorySegment = alloc_InitSegment(
01259                                        pProgram->maf,
01260                                        pProgram->mrf);
01261   if( pProgram->pLEX->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01262   /* Inherit the preprocessor object to the lexical analyzer */
01263   pProgram->pLEX->pPREP = pProgram->pPREP;
01264   lex_InitStructure(  pProgram->pLEX);
01265 
01266   pProgram->pLEX->pfGetCharacter = reader_NextCharacter;
01267   pProgram->pLEX->pfFileName = reader_FileName;
01268   pProgram->pLEX->pfLineNumber = reader_LineNumber;
01269 
01270   if( pProgram->pLEX->pNASymbols == NULL )pProgram->pLEX->pNASymbols = NASYMBOLS;
01271   if( pProgram->pLEX->pASymbols == NULL )pProgram->pLEX->pASymbols  = ASYMBOLS;
01272   if( pProgram->pLEX->pCSymbols == NULL )pProgram->pLEX->pCSymbols  = CSYMBOLS;
01273   pProgram->pLEX->report = pProgram->fpReportFunction;
01274   pProgram->pLEX->reportptr = pProgram->pReportPointer;
01275   pProgram->pLEX->fErrorFlags = pProgram->fErrorFlags;
01276   pProgram->pLEX->iErrorCounter = 0;
01277   pProgram->pLEX->pLexResult = (void *)stderr;
01278 
01279 
01280   pProgram->pLEX->pvInput = (void *)  pProgram->pREAD;
01281   lex_ReadInput(pProgram->pLEX);
01282 
01283   if( pProgram->pLEX->iErrorCounter )return pProgram->pLEX->iErrorCounter;
01284   lex_RemoveComments(pProgram->pLEX);
01285   lex_RemoveSkipSymbols(pProgram->pLEX);
01286   lex_HandleContinuationLines(pProgram->pLEX);
01287   return pProgram->pLEX->iErrorCounter;
01288   }
01289 
01290 /*POD
01291 =H scriba_DoSyntaxAnalysis()
01292 
01293 This function performs syntax analysis after the lexical analysis has been finished.
01294 
01295 This function is rarely needeed by applicationdevelopers. See R<scriba_LoadSourceProgram()>
01296 instead.
01297 /*FUNCTION*/
01298 int scriba_DoSyntaxAnalysis(pSbProgram pProgram
01299   ){
01300 /*noverbatim
01301 See also R<scriba_ReadSource()>, R<scriba_DoLexicalAnalysis()>,
01302 R<scriba_DoSyntaxAnalysis()>, R<scriba_BuildCode()>.
01303 CUT*/
01304   peNODE_l CommandList;
01305   int iError;
01306 
01307   pProgram->pEX = alloc_Alloc( sizeof(eXobject) , pProgram->pMEM);
01308   if( pProgram->pEX == NULL )return 1;
01309 
01310   pProgram->pEX->pPREP = pProgram->pPREP;
01311   pProgram->pEX->memory_allocating_function = pProgram->maf;
01312   pProgram->pEX->memory_releasing_function = pProgram->mrf;
01313   pProgram->pEX->cbBuffer = 1024; /* init will allocate the space of this number of characters */
01314   pProgram->pEX->cbCurrentNameSpace = 1024; /* init will allocate the space of this number of characters */
01315   pProgram->pEX->pLex = pProgram->pLEX;
01316 
01317   pProgram->pEX->Unaries  = UNARIES;
01318   pProgram->pEX->Binaries = BINARIES;
01319   pProgram->pEX->BuiltInFunctions = INTERNALFUNCTIONS;
01320   pProgram->pEX->MAXPREC  = MAX_BINARY_OPERATOR_PRECEDENCE;
01321   pProgram->pEX->PredeclaredLongConstants = PREDLCONSTS;
01322   pProgram->pEX->reportptr = pProgram->pReportPointer;
01323   pProgram->pEX->report   = pProgram->fpReportFunction;
01324   pProgram->pEX->fErrorFlags = pProgram->fErrorFlags;
01325   pProgram->pEX->iErrorCounter = 0;
01326   iError = 0;
01327 
01328   pProgram->pEX->Command = COMMANDS;
01329 
01330   ex_init(pProgram->pEX);
01331 
01332   ex_Command_l(pProgram->pEX,&CommandList);
01333 
01334   pProgram->pEX->pCommandList = CommandList;
01335   if( pProgram->pPREP && pProgram->pPREP->n )
01336     iError = ipreproc_Process(pProgram->pPREP,PreprocessorExFinish,pProgram->pEX);
01337   if( iError )pProgram->pEX->iErrorCounter++;
01338 
01339   return pProgram->pEX->iErrorCounter;
01340   }
01341 
01342 /*POD
01343 =H scriba_BuildCode()
01344 
01345 This function builds the finall ready-to-run code after the syntax
01346 analisys has been finished.
01347 
01348 This function is rarely needeed by applicationdevelopers. See R<scriba_LoadSourceProgram()>
01349 instead.
01350 /*FUNCTION*/
01351 int scriba_BuildCode(pSbProgram pProgram
01352   ){
01353 /*noverbatim
01354 See also R<scriba_ReadSource()>, R<scriba_DoLexicalAnalysis()>,
01355 R<scriba_DoSyntaxAnalysis()>, R<scriba_BuildCode()>.
01356 CUT*/
01357 
01358   pProgram->pBUILD = alloc_Alloc( sizeof(BuildObject) , pProgram->pMEM );
01359   if( pProgram->pBUILD == NULL )return 1;
01360 
01361   pProgram->pBUILD->pPREP = pProgram->pPREP;
01362   pProgram->pBUILD->memory_allocating_function = pProgram->maf;
01363   pProgram->pBUILD->memory_releasing_function  = pProgram->mrf;
01364   pProgram->pBUILD->pEx =   pProgram->pEX;
01365   pProgram->pBUILD->iErrorCounter = 0;
01366   pProgram->pBUILD->fErrorFlags = pProgram->pEX->fErrorFlags;
01367   pProgram->pBUILD->FirstUNIXline = pProgram->FirstUNIXline;
01368 
01369   build_Build(pProgram->pBUILD);
01370 
01371   if( pProgram->pBUILD->iErrorCounter )return pProgram->pBUILD->iErrorCounter;
01372   return 0;
01373   }
01374 
01375 /*POD
01376 =H scriba_IsFileBinaryFormat()
01377 
01378 This function decides if a file is a correct binary format ScriptBasic
01379 code file and returns true if it is binary. If the file is a ScriptBasic
01380 source file or an older version binary of ScriptBasic or any other file
01381 it returns zero.
01382 
01383 This function just calls the function T<build_IsFileBinaryFormat>
01384 
01385 /*FUNCTION*/
01386 int scriba_IsFileBinaryFormat(pSbProgram pProgram
01387   ){
01388 /*noverbatim
01389 CUT*/
01390 
01391   return  build_IsFileBinaryFormat(pProgram->pszFileName);
01392   }
01393 
01394 /*POD
01395 =H scriba_GetCacheFileName()
01396 
01397 Calculate the name of the cache file for the given source file name and
01398 store the calculated file name in the program object.
01399 
01400 /*FUNCTION*/
01401 int scriba_GetCacheFileName(pSbProgram pProgram
01402   ){
01403 /*noverbatim
01404 The program returns zero or the error code. It returns T<SCRIBA_ERROR_FAIL> if there
01405 is no cache directory configured.
01406 
01407 The code uses a local buffer of length 256 bytes. The full cached file name should
01408 fit into this otherwise the program will return T<SCRIBA_ERROR_BUFFER_SHORT>.
01409 
01410 The code does not check if there exists an appropriate cache directory or file. It
01411 just calculates the file name.
01412 CUT*/
01413 #define FULL_PATH_BUFFER_LENGTH 256
01414   char *pszCache;
01415   char *s,*q;
01416   char CachedFileName[FULL_PATH_BUFFER_LENGTH];
01417 
01418   if( pProgram->pszFileName == NULL )return SCRIBA_ERROR_FAIL;
01419   pszCache = cft_GetString(pProgram->pCONF,"cache");
01420   if( pszCache == NULL)return SCRIBA_ERROR_FAIL;
01421   if( strlen(pszCache) >= FULL_PATH_BUFFER_LENGTH )return SCRIBA_ERROR_BUFFER_SHORT;
01422   strcpy(CachedFileName,pszCache);
01423   s = CachedFileName + strlen(CachedFileName); /* point to the end of the cache directory */
01424 
01425 #ifdef WIN32
01426 /* under Win32 we convert the argv[0] to the full path file name */
01427   if( GetFullPathName(pProgram->pszFileName,
01428                       FULL_PATH_BUFFER_LENGTH-strlen(CachedFileName),s,&q)==0 )
01429     return SCRIBA_ERROR_FAIL;
01430 #else
01431 /* under UNIX we can not convert, but it usually contains the full path */
01432   if( strlen(pProgram->pszFileName) > FULL_PATH_BUFFER_LENGTH - strlen(CachedFileName) )
01433     return SCRIBA_ERROR_BUFFER_SHORT;
01434   strcpy(s,pProgram->pszFileName);
01435 #endif
01436   /* convert the full path to MD5 digest unique file name */
01437   uniqfnam(s,s);
01438   if( pProgram->pszCacheFileName )alloc_Free(pProgram->pszCacheFileName,pProgram->pMEM);
01439   pProgram->pszCacheFileName = alloc_Alloc(strlen(CachedFileName)+1,pProgram->pMEM);
01440   if( pProgram->pszCacheFileName == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01441   strcpy(pProgram->pszCacheFileName,CachedFileName);
01442   return SCRIBA_ERROR_SUCCESS;
01443   }
01444 
01445 /*POD
01446 =H scriba_UseCacheFile()
01447 
01448 Call this function to test that the cache file is usable. This function
01449 calls the function R<scriba_GetCacheFileName()> to calculate the cache file name.
01450 
01451 If 
01452 =itemize
01453 =item the cache file exists
01454 =item is newer than the source file set by R<scriba_SetFileName()>
01455 =item is a correct ScriptBasic binary file
01456 =noitemize
01457 then this function alters the source file name property (T<pszFileName>)
01458 of the program object so that the call to R<scriba_LoadBinaryProgram()> will try to
01459 load the cache file.
01460 
01461 /*FUNCTION*/
01462 int scriba_UseCacheFile(pSbProgram pProgram
01463   ){
01464 /*noverbatim
01465 The function returns zero or the error code. The function returns T<SCRIBA_ERROR_FAIL>
01466 in case the cache file is old, or not valid. Therefore returning a positive value
01467 does not neccessarily mean a hard error.
01468 CUT*/
01469   unsigned long FileTime,CacheTime;
01470   int iError;
01471 
01472   if( iError = scriba_GetCacheFileName(pProgram) )return iError;
01473 
01474   FileTime  = file_time_modified(pProgram->pszFileName);
01475   CacheTime = file_time_modified(pProgram->pszCacheFileName);
01476   if( FileTime && CacheTime && CacheTime > FileTime &&
01477       build_IsFileBinaryFormat(pProgram->pszCacheFileName) ){
01478     alloc_Free(pProgram->pszFileName,pProgram->pMEM);
01479     pProgram->pszFileName = alloc_Alloc(strlen(pProgram->pszCacheFileName)+1,
01480                                                                pProgram->pMEM);
01481     if( pProgram->pszFileName == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01482     strcpy(pProgram->pszFileName,pProgram->pszCacheFileName);
01483     return SCRIBA_ERROR_SUCCESS;
01484     }
01485   return SCRIBA_ERROR_FAIL;
01486   }
01487 
01488 /*POD
01489 =H scriba_SaveCacheFile()
01490 
01491 Call this function to generate a cache file after
01492 a successful program compilation.
01493 
01494 /*FUNCTION*/
01495 int scriba_SaveCacheFile(pSbProgram pProgram
01496   ){
01497 /*noverbatim
01498 The function returns zero (T<SCRIBA_ERROR_SUCCESS>) if there was no error.
01499 This does not mean that the cache file was saved. If there is no cache
01500 directory configured doing nothing is success.
01501 
01502 Returning any positive error code means that ScriptBasic tried to write a
01503 cache file but it could not.
01504 CUT*/
01505 
01506   if( ! pProgram->pszCacheFileName )
01507     scriba_GetCacheFileName(pProgram);
01508   if( pProgram->pszCacheFileName )
01509     return scriba_SaveCode(pProgram,pProgram->pszCacheFileName);
01510   return SCRIBA_ERROR_SUCCESS;
01511   }
01512 
01513 /*POD
01514 =H scriba_RunExternalPreprocessor()
01515 
01516 This function should be called to execute external preprocessors.
01517 
01518 This function does almost nothing else but calls the function
01519 T<epreproc()>.
01520 
01521 /*FUNCTION*/
01522 int scriba_RunExternalPreprocessor(pSbProgram pProgram,
01523                                    char **ppszArgPreprocessor
01524   ){
01525 /*noverbatim
01526 The argument T<ppszArgPreprocessor> should point to a string array. This string array
01527 should contain the configured names of the preprocessors that are applied one after the
01528 other in the order they are listed in the array.
01529 
01530 Note that this array should contain the symbolic names of the preprocessors. The actual
01531 preprocessor executable programs, or command lines are defined in the configuration
01532 file.
01533 
01534 After calling this function the source file name property of the program object (T<pszFileName>)
01535 is also modified so that it points to the result of the preprocessor. This means that after the
01536 successful return of this function the application may immediately call R<scriba_LoadSourceProgram()>.
01537 
01538 If there is any error during the preprocessor execution the function returns some error code
01539 (returned by T<epreproc>) otherwise the return value is zero.
01540 CUT*/
01541   int iError;
01542   char *pszPreprocessedFileName=NULL;
01543 
01544   iError = epreproc(pProgram->pCONF,
01545                     pProgram->pszFileName,
01546                     &pszPreprocessedFileName,
01547                     ppszArgPreprocessor,
01548                     pProgram->maf,
01549                     pProgram->mrf);
01550 
01551   /* If there was error then return it. */
01552   if( iError )return iError;
01553 
01554   /* If there was no error, but there is no need to preprocess. */
01555   if( pszPreprocessedFileName == NULL )return SCRIBA_ERROR_SUCCESS;
01556 
01557   if( pProgram->pszFileName ){
01558     alloc_Free(pProgram->pszFileName,pProgram->pMEM);
01559     pProgram->pszFileName = NULL;
01560     }
01561 
01562   /* Allocated space for the preprocessed file name and store it in the
01563      memory segment pProgram->pMEM. */
01564   pProgram->pszFileName = alloc_Alloc(strlen(pszPreprocessedFileName)+1,pProgram->pMEM);
01565   if( pProgram->pszFileName == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01566   strcpy(pProgram->pszFileName,pszPreprocessedFileName);
01567   pProgram->mrf(pszPreprocessedFileName);
01568   return SCRIBA_ERROR_SUCCESS;
01569   }
01570 
01571 /*POD
01572 =H scriba_SaveCode()
01573 
01574 Call this function to save the compiled byte code of the program
01575 into a specific file. This function is called by the function R<scriba_SaveCacheFile()>.
01576 /*FUNCTION*/
01577 int scriba_SaveCode(pSbProgram pProgram,
01578                      char *pszCodeFileName
01579   ){
01580 /*noverbatim
01581 The function does nothing else, but calls T<build_SaveCode>.
01582 
01583 The return code is zero or the error code returned by T<build_SaveCode>.
01584 CUT*/
01585   return build_SaveCode(pProgram->pBUILD,pszCodeFileName);
01586   }
01587 
01588 /*POD
01589 =H scriba_SaveCCode()
01590 
01591 /*FUNCTION*/
01592 void scriba_SaveCCode(pSbProgram pProgram,
01593                       char *pszCodeFileName
01594   ){
01595 /*noverbatim
01596 CUT*/
01597   build_SaveCCode(pProgram->pBUILD,pszCodeFileName);
01598   }
01599 
01600 /*POD
01601 =H scriba_SaveECode()
01602 
01603 /*FUNCTION*/
01604 void scriba_SaveECode(pSbProgram pProgram,
01605                       char *pszInterpreter,
01606                       char *pszCodeFileName
01607   ){
01608 /*noverbatim
01609 CUT*/
01610   build_SaveECode(pProgram->pBUILD,pszInterpreter,pszCodeFileName);
01611   }
01612 
01613 /*POD
01614 =H scriba_LoadSourceProgram()
01615 
01616 Call this function to load a BASIC program from its source format after
01617 optionally checking that there is no available cache file and after
01618 executing all required preprocessors. This function calls
01619 R<scriba_ReadSource()>, R<scriba_DoLexicalAnalysis()>, R<scriba_DoSyntaxAnalysis()>, R<scriba_BuildCode()>,
01620 and also releases the memory that was needed only for code building
01621 calling R<scriba_PurgeReaderMemory()>, R<scriba_PurgeLexerMemory()>, R<scriba_PurgeSyntaxerMemory()>.
01622 
01623 After the successful completion of this program the BASIC program is in
01624 the memory in the ready-to-run state.
01625 /*FUNCTION*/
01626 int scriba_LoadSourceProgram(pSbProgram pProgram
01627   ){
01628 /*noverbatim
01629 Before calling this function the function R<scriba_SetFileName()> should have been called specifying the
01630 file name.
01631 
01632 The return value is zero (T<SCRIBA_ERROR_SUCCESS>) or the error code returned by the
01633 underlying layer that has detected the error.
01634 CUT*/
01635   int iError;
01636 
01637   if( iError = scriba_ReadSource(pProgram) )return iError;
01638   if( iError = scriba_DoLexicalAnalysis(pProgram) )return iError;
01639   if( iError = scriba_DoSyntaxAnalysis(pProgram) )return iError;
01640   if( iError = scriba_BuildCode(pProgram) )return iError;
01641 
01642   /* we can not purge these memory areas sooner because some
01643      error messages even during build refer to names read
01644      by the reader and still stored intheir memory heap. */
01645   scriba_PurgeReaderMemory(pProgram);
01646   scriba_PurgeLexerMemory(pProgram);
01647   scriba_PurgeSyntaxerMemory(pProgram);
01648   return SCRIBA_ERROR_SUCCESS;
01649   }
01650 
01651 /*
01652 This structure is used to imitate character fetching from a file when
01653 the source code is in a string that the caller has already loaded.
01654 */
01655 typedef struct _StringInputState {
01656   char *pszFileName;
01657   char *pszBuffer;
01658   unsigned long cbBuffer;
01659   unsigned long lBufferPosition;
01660   /* pointers to store the original functions */
01661   void * (*fpOpenFile)(char *, void *);
01662   int (*fpGetCharacter)(void *, void *);
01663   void (*fpCloseFile)(void *, void *);
01664   int iActive;
01665   } StringInputState, *pStringInputState;
01666 
01667 static void *StringOpen(char *psz, pStringInputState p){
01668   p->iActive = 0;
01669   if( psz != p->pszFileName )return p->fpOpenFile(psz,NULL);
01670   p->iActive = 1;
01671   p->lBufferPosition = 0;
01672   return (void *)p;
01673   }
01674 
01675 static void StringClose(void *p, pStringInputState q){
01676   if( ! q->iActive ){
01677     q->fpCloseFile(p,NULL);
01678     return;
01679     }
01680   return;
01681   }
01682 
01683 static int StringGetCharacter(void *pv, pStringInputState p){
01684   if( ! p->iActive )return p->fpGetCharacter(pv,NULL);
01685 
01686   if( p->lBufferPosition < p->cbBuffer )return p->pszBuffer[p->lBufferPosition++];
01687   return -1;
01688   }
01689 
01690 /*POD
01691 =H scriba_LoadProgramString()
01692 
01693 Use this function to convert a string containing a BASIC program
01694 that is already in memory to ready-to-run binary format. This function
01695 is same as R<scriba_LoadSourceProgram()> except that this function reads the source
01696 code from a string instead of a file.
01697 /*FUNCTION*/
01698 int scriba_LoadProgramString(pSbProgram pProgram,
01699                              char *pszSourceCode,
01700                              unsigned long cbSourceCode
01701   ){
01702 /*noverbatim
01703 The argument T<pProgram> is the program object. The argument T<pszSourceCode>
01704 is the BASIC program itself in text format. Because the source code may
01705 contain ZCHAR just for any chance the caller has to provide the number of
01706 characters in the buffer via the argument T<cbSourceCode>. In case the
01707 source program is zero terminated the caller can simply say
01708 T<strlen(pszSourceCode)> to give this argument.
01709 
01710 Before calling this function the function R<scriba_SetFileName()> may be called. Altough
01711 the source code is read from memory and thus there is no source file the
01712 BASIC program may use the command T<include> or T<import> that includes
01713 another source file after reading the code. If the program does so the reader
01714 functions need to know the actual file name of the source code to find
01715 the file to be included. To help this process the caller using this function
01716 may set the file name calling R<scriba_SetFileName()>. However that file is never used
01717 and need not even exist. It is used only to calculate the path of included files
01718 that are specified using relative path.
01719 
01720 The return value is zero (T<SCRIBA_ERROR_SUCCESS>) or the error code returned by the
01721 underlying layer that has detected the error.
01722 CUT*/
01723   int iError;
01724   StringInputState SIS;
01725 
01726   if( pProgram->pszFileName == NULL )scriba_SetFileName(pProgram,"");
01727 
01728   pProgram->pREAD = alloc_Alloc( sizeof(ReadObject) , pProgram->pMEM );
01729   if( pProgram->pREAD == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01730 
01731   reader_InitStructure(pProgram->pREAD);
01732   /* here we have to alter the default reader functions that would
01733      originally read a file from disk to perform the reading from
01734      the string that was specified on the command line. */
01735   SIS.fpOpenFile = pProgram->pREAD->fpOpenFile;
01736   pProgram->pREAD->fpOpenFile     = (void *)StringOpen;
01737   SIS.fpGetCharacter = pProgram->pREAD->fpGetCharacter;
01738   pProgram->pREAD->fpGetCharacter = (void *)StringGetCharacter;
01739   SIS.fpCloseFile = pProgram->pREAD->fpCloseFile;
01740   pProgram->pREAD->fpCloseFile    = (void *)StringClose;
01741 
01742   pProgram->pREAD->memory_allocating_function = alloc_Alloc;
01743   pProgram->pREAD->memory_releasing_function = alloc_Free;
01744   pProgram->pREAD->pMemorySegment = alloc_InitSegment(
01745                                      pProgram->maf,
01746                                      pProgram->mrf);
01747   if( pProgram->pREAD->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01748   pProgram->pREAD->report = pProgram->fpReportFunction;
01749   pProgram->pREAD->reportptr = pProgram->pReportPointer;
01750   pProgram->pREAD->iErrorCounter = 0;
01751   pProgram->pREAD->fErrorFlags = pProgram->fErrorFlags;
01752   pProgram->pREAD->pConfig = pProgram->pCONF;
01753   pProgram->pREAD->pFileHandleClass = &SIS;
01754   SIS.pszBuffer = pszSourceCode;
01755   SIS.cbBuffer = cbSourceCode;
01756   SIS.pszFileName = pProgram->pszFileName;
01757 
01758   /* here we have to initialize the preprocessor object 
01759      if it was not initialized before because the reader uses that */
01760   if( pProgram->pPREP == NULL ){
01761     pProgram->pPREP = alloc_Alloc( sizeof(PreprocObject) , pProgram->pMEM );
01762     if( pProgram->pPREP == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01763     ipreproc_InitStructure(pProgram->pPREP);
01764     pProgram->pPREP->pMemorySegment = alloc_InitSegment(
01765                                        pProgram->maf,
01766                                        pProgram->mrf);
01767     if( pProgram->pPREP->pMemorySegment == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01768     pProgram->pPREP->pSB = pProgram;
01769     }
01770   pProgram->pREAD->pPREP = pProgram->pPREP;
01771 
01772   if( ! (iError = reader_ReadLines(pProgram->pREAD,pProgram->pszFileName)) ){
01773     if( pProgram->pREAD->FirstUNIXline ){
01774       pProgram->FirstUNIXline = alloc_Alloc(strlen(pProgram->pREAD->FirstUNIXline)+1,pProgram->pMEM);
01775       if( pProgram->FirstUNIXline == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01776       strcpy(pProgram->FirstUNIXline,pProgram->pREAD->FirstUNIXline);
01777       }
01778     }else{
01779     return iError;
01780     }
01781   if( pProgram->pREAD->iErrorCounter )return pProgram->pREAD->iErrorCounter;
01782   if( iError = scriba_DoLexicalAnalysis(pProgram) )return iError;
01783   if( iError = scriba_DoSyntaxAnalysis(pProgram) )return iError;
01784   if( iError = scriba_BuildCode(pProgram) )return iError;
01785 
01786   /* we can not purge these memory areas sooner because some
01787      error messages even during build refer to names read
01788      by the reader and still stored intheir memory heap. */
01789   scriba_PurgeReaderMemory(pProgram);
01790   scriba_PurgeLexerMemory(pProgram);
01791   scriba_PurgeSyntaxerMemory(pProgram);
01792   return SCRIBA_ERROR_SUCCESS;
01793   }
01794 
01795 static int scriba_PreRun(pSbProgram pProgram){
01796   int iError;
01797 
01798   if( pProgram->pEXE == NULL ){
01799     pProgram->pEXE = alloc_Alloc( sizeof(ExecuteObject) , pProgram->pMEM );
01800     if( pProgram->pEXE == NULL )return SCRIBA_ERROR_MEMORY_LOW;
01801 
01802     pProgram->pEXE->memory_allocating_function = pProgram->maf;
01803     pProgram->pEXE->memory_releasing_function = pProgram->mrf;
01804     pProgram->pEXE->reportptr = pProgram->pReportPointer;
01805     pProgram->pEXE->report   = pProgram->fpReportFunction;
01806     pProgram->pEXE->fErrorFlags = pProgram->fErrorFlags;
01807 
01808     pProgram->pEXE->pConfig = pProgram->pCONF;
01809     build_MagicCode(&(pProgram->pEXE->Ver));
01810     if( iError=execute_InitStructure(  pProgram->pEXE,pProgram->pBUILD) )
01811       return iError;
01812     pProgram->pEXE->fpStdouFunction = pProgram->fpStdouFunction;
01813     pProgram->pEXE->fpStdinFunction = pProgram->fpStdinFunction;
01814     pProgram->pEXE->fpEnvirFunction = pProgram->fpEnvirFunction;
01815     pProgram->pEXE->pEmbedder       = pProgram->pEmbedder;
01816     pProgram->pEXE->pSTI            = pProgram->pSTI;
01817     pProgram->pEXE->pEPo            = pProgram->pEPo;
01818     }else{
01819     if( iError=execute_ReInitStructure(  pProgram->pEXE,pProgram->pBUILD) )
01820       return iError;
01821     }
01822 
01823   pProgram->pEXE->CmdLineArgument = NULL;
01824 
01825   return SCRIBA_ERROR_SUCCESS;
01826   }
01827 
01828 /*POD
01829 =H scriba_Run()
01830 
01831 Call this function to execute a program. Note that you can call this function
01832 many times. Repetitive execution of the same program will execute the
01833 ScriptBasic code again and again with the global variables keeping their values.
01834 
01835 If you want to reset the global variables you have to call R<scriba_ResetVariables()>.
01836 
01837 There is no way to keep the value of the local variables.
01838 
01839 The argument T<pszCommandLineArgument> is the command part that is passed to the
01840 BASIC program.
01841 /*FUNCTION*/
01842 int scriba_Run(pSbProgram pProgram,
01843                char *pszCommandLineArgument
01844   ){
01845 /*noverbatim
01846 The return value is zero in case of success or the error code returned by the underlying
01847 execution layers.
01848 
01849 Note that you can not call BASIC subroutines or functions without initializations that
01850 T<scriba_Run> performs. You also can not access global variables. Therefore you either have
01851 to call T<scriba_Run> or its brother R<scriba_NoRun()> that performs the initializations without execution.
01852 
01853 You also have to call R<scriba_NoRun()> if you want to execute a program with some global variables
01854 having preset values that you want to set from the embedding C program. In that case you
01855 have to call R<scriba_NoRun()> then one or more times R<scriba_SetVariable()> and finally T<Run>.
01856 
01857 CUT*/
01858   int iError;
01859 
01860   if( iError = scriba_PreRun(pProgram) ){
01861     return iError;
01862     }
01863   
01864   pProgram->pEXE->CmdLineArgument = pszCommandLineArgument;  
01865   execute_InitExecute(pProgram->pEXE,&iError);
01866 
01867   iError = 0;
01868   if( pProgram->pPREP && pProgram->pPREP->n )
01869     iError = ipreproc_Process(pProgram->pPREP,PreprocessorExeStart,pProgram->pEXE);
01870   if( iError )return iError;
01871 
01872   execute_Execute_r(pProgram->pEXE,&iError);
01873   if( iError )return iError;
01874   if( pProgram->pPREP && pProgram->pPREP->n )
01875     iError = ipreproc_Process(pProgram->pPREP,PreprocessorExeFinish,pProgram->pEXE);
01876   return iError;
01877   }
01878 
01879 /*POD
01880 =H scriba_NoRun()
01881 
01882 In case the embedding program want to set global variables and
01883 execute subroutines without or before starting the main program it has to call this
01884 function first. It does all the initializations that are done by
01885 R<scriba_Run()> except that it does not actually execute the program.
01886 
01887 After calling this function the main program may access global variables
01888 and call BASIC functions.
01889 
01890 /*FUNCTION*/
01891 int scriba_NoRun(pSbProgram pProgram
01892   ){
01893 /*noverbatim
01894 See also R<scriba_Run()>.
01895 CUT*/
01896   int iError;
01897 
01898   scriba_PreRun(pProgram);
01899   execute_InitExecute(pProgram->pEXE,&iError);
01900   if( iError )return iError;
01901   if( pProgram->pPREP && pProgram->pPREP->n )
01902     iError = ipreproc_Process(pProgram->pPREP,PreprocessorExeNoRun,pProgram->pEXE);
01903   return iError;
01904   }
01905 
01906 /*POD
01907 =H scriba_ResetVariables()
01908 
01909 Call this function if you want to execute a program object that was already executed
01910 but you do not want the global variables to keep their value they had when
01911 the last execution of the BASIC code finished.
01912 
01913 Global variables in ScriptBasic are guaranteed to be T<undef> before they get any other
01914 value and some programs depend on this.
01915 
01916 /*FUNCTION*/
01917 void scriba_ResetVariables(pSbProgram pProgram
01918   ){
01919 /*noverbatim
01920 See also R<scriba_SetVariable()>, R<scriba_Run()>, R<scriba_NoRun()>.
01921 CUT*/
01922 
01923   memory_ReleaseVariable(pProgram->pEXE->pMo,pProgram->pEXE->GlobalVariables);
01924   pProgram->pEXE->GlobalVariables = NULL;
01925   }
01926 
01927 /*POD
01928 =H scriba_Call()
01929 
01930 This function can be used to call a function or subroutine. This function does not
01931 get any arguments and does not provide any return value.
01932 
01933 /*FUNCTION*/
01934 int scriba_Call(pSbProgram pProgram,
01935                 unsigned long lEntryNode
01936   ){
01937 /*noverbatim
01938 The return value is zero or the error code returned by the interpreter.
01939 
01940 B<Note on how to get the Entry Node value:>
01941 
01942 The argument T<lEntryNode> should be the node index of the subroutine or function that
01943 we want to execute. This can be retrieved using the function R<scriba_LookupFunctionByName()> if the
01944 name of the function or subroutine is know. Another method is that the BASIC program
01945 stored this value in some global variables. BASIC programs can access this information
01946 calling the BASIC function T<Address( f() )>.
01947 CUT*/
01948   int iError;
01949 
01950   execute_ExecuteFunction(pProgram->pEXE,lEntryNode,0,NULL,NULL,&iError);
01951 
01952   return iError;
01953   }
01954 
01955 /*POD
01956 =H scriba_CallArg()
01957 
01958 This function can be used to call a function or subroutine with arguments passed by value.
01959 Neither the return value of the SUB nor the modified argument variables are not accessible 
01960 via this function. T<CallArg> is a simple interface to call a ScriptBasic subroutine or
01961 function with argument.
01962 
01963 /*FUNCTION*/
01964 int scriba_CallArg(pSbProgram pProgram,
01965                    unsigned long lEntryNode,
01966                    char *pszFormat, ...
01967   ){
01968 /*noverbatim
01969 Arguments
01970 
01971 =itemize
01972 =item T<pProgram> is the class variable.
01973 =item T<lEntryNode> is the start node of the SUB. (See R<scriba_Call()> note on how to get the entry node value.)
01974 =item T<pszFormat> is a format string that defines the rest of the areguments
01975 =noitemize
01976 
01977 The format string is case insensitive. The characters T<u>, T<i>, T<r>, T<b> and T<s> have meaning.
01978 All other characters are ignored. The format characters define the type of the arguments
01979 from left to right.
01980 
01981 =itemize
01982 =item T<u> means to pass an T<undef> to the SUB. This format character is exceptional that it does not
01983 consume any function argument.
01984 =item T<i> means that the next argument has to be T<long> and it is passed to the BASIC SUB as an integer.
01985 =item T<r> means that the next argument has to be T<double> and it is passed to the BASIC SUB as a real.
01986 =item T<s> means that the next argument has to be T<char *> and it is passed to the BASIC SUB as a string.
01987 =item T<b> means that the next two arguments has to be T<long cbBuffer> and T<unsigned char *Buffer>.
01988 The T<cbBuffer> defines the length of the T<Buffer>.
01989 =noitemize
01990 
01991 Note that this SUB calling function is a simple interface and has no access to the modified values of the argument
01992 after the call or the return value.
01993 
01994 If you need any of the functionalities that are not implemented in this function call a more sophisticated
01995 function.
01996 
01997 Example:
01998 =verbatim
01999 
02000   iErrorCode = scriba_CallArg(&MyProgram,lEntry,"i i s d",13,22,"My string.",54.12);
02001 
02002 =noverbatim
02003 
02004 CUT*/
02005   int iError;
02006   VARIABLE vArgs;
02007   va_list marker;
02008   unsigned long cArgs,i,slen;
02009   char *s;
02010   char *arg;
02011 
02012   cArgs = 0;
02013   if( pszFormat ){
02014     s = pszFormat;
02015     while( *s ){
02016       switch( *s++ ){
02017         case 'U': /* undef argument */
02018         case 'u': /* It eats no actual C level caller argument */
02019 
02020         case 'B': /* byte argument   */
02021         case 'b': /* it eats two arguments: a length and the pointer to the byte stream */
02022 
02023         case 'S': /* string argument */
02024         case 's':
02025         case 'I': /* Integer argument */
02026         case 'i':
02027         case 'R': /* Real number argument */
02028         case 'r':
02029           cArgs ++;
02030           break;
02031         default:; /* ignore all non-format characters */
02032         }
02033       }
02034     }
02035 
02036   if( cArgs )
02037     vArgs = memory_NewArray(pProgram->pEXE->pMo,0,cArgs-1);
02038   else
02039     vArgs = NULL;
02040 
02041   if( vArgs ){
02042     i = 0;
02043     va_start(marker,pszFormat);
02044     s = pszFormat;
02045     while( *s ){
02046       switch( *s++ ){
02047         case 'U':
02048         case 'u':
02049           vArgs->Value.aValue[i] = NULL;
02050           i++;
02051           break;
02052         case 'B': /* byte stream argument */
02053         case 'b':
02054           slen = va_arg(marker, long);
02055           arg = va_arg(marker, char *);
02056           if( arg == NULL )arg = "";
02057           vArgs->Value.aValue[i] = memory_NewString(pProgram->pEXE->pMo,slen);
02058           memcpy(STRINGVALUE(vArgs->Value.aValue[i]),arg,slen);
02059           i++;
02060           break;
02061         case 'S': /* string argument */
02062         case 's':
02063           arg = va_arg(marker, char *);
02064           if( arg == NULL )arg = "";
02065           slen = strlen(arg);
02066           vArgs->Value.aValue[i] = memory_NewString(pProgram->pEXE->pMo,slen);
02067           memcpy(STRINGVALUE(vArgs->Value.aValue[i]),arg,slen);
02068           i++;
02069           break;
02070         case 'I': /* Integer argument */
02071         case 'i':
02072           vArgs->Value.aValue[i] = memory_NewLong(pProgram->pEXE->pMo);
02073           LONGVALUE(vArgs->Value.aValue[i]) = va_arg(marker, long);
02074           i++;
02075           break;
02076         case 'R': /* Real number argument */
02077         case 'r':
02078           vArgs->Value.aValue[i] = memory_NewDouble(pProgram->pEXE->pMo);
02079           DOUBLEVALUE(vArgs->Value.aValue[i]) = va_arg(marker, double);
02080           i++;
02081           break;
02082         }
02083       }
02084     }
02085 
02086   execute_ExecuteFunction(pProgram->pEXE,lEntryNode,cArgs,vArgs ? vArgs->Value.aValue : NULL ,NULL,&iError);
02087   memory_ReleaseVariable(pProgram->pEXE->pMo,vArgs);
02088   return iError;
02089   }
02090 
02091 /*POD
02092 =H scriba_DestroySbArgs()
02093 
02094 This function can be used to release the memory used by arguments created by the
02095 function R<scriba_NewSbArgs()>.
02096 
02097 /*FUNCTION*/
02098 void scriba_DestroySbArgs(pSbProgram pProgram,
02099                           pSbData Args,
02100                           unsigned long cArgs
02101   ){
02102 /*noverbatim
02103 
02104 Arguments:
02105 =itemize
02106 =item T<pProgram> class variable
02107 =item T<Args> pointer returned by R<scriba_NewSbArgs()>
02108 =item T<cArgs> the number of arguments pointed by T<Args>
02109 =noitemize
02110 
02111 CUT*/
02112   unsigned long i;
02113 
02114   for( i=0 ; i<cArgs ; i++ )
02115     if( Args[i].type == SBT_STRING )
02116       alloc_Free(Args[i].v.s,pProgram->pMEM);
02117   alloc_Free(Args,pProgram->pMEM);
02118   }
02119 
02120 /*POD
02121 =H scriba_NewSbArgs()
02122 
02123 Whenever you want to handle the variable values that are returned by the scriba subroutine
02124 you have to call R<scriba_CallArgEx()>. This function needs the arguments passed in an array of T<SbDtata> type.
02125 
02126 This function is a usefuly tool to convert C variables to an array of T<SbData>
02127 
02128 /*FUNCTION*/
02129 pSbData scriba_NewSbArgs(pSbProgram pProgram,
02130                          char *pszFormat, ...
02131   ){
02132 /*noverbatim
02133 The arguments passed are 
02134 
02135 =itemize
02136 =item T<pProgram> is the class variable
02137 =item T<pszFormat> is the format string
02138 =noitemize
02139 
02140 The format string is case insensitive. The characters T<u>, T<i>, T<r>, T<b> and T<s> have meaning.
02141 All other characters are ignored. The format characters define the type of the arguments
02142 from left to right.
02143 
02144 =itemize
02145 =item T<u> means to pass an T<undef> to the SUB. This format character is exceptional that it does not
02146 consume any function argument.
02147 =item T<i> means that the next argument has to be T<long> and it is passed to the BASIC SUB as an integer.
02148 =item T<r> means that the next argument has to be T<double> and it is passed to the BASIC SUB as a real.
02149 =item T<s> means that the next argument has to be T<char *> and it is passed to the BASIC SUB as a string.
02150 =item T<b> means that the next two arguments has to be T<long cbBuffer> and T<unsigned char *Buffer>.
02151 The T<cbBuffer> defines the leng of the T<Buffer>.
02152 =noitemize
02153 
02154 Example:
02155 
02156 =verbatim
02157 
02158 pSbData MyArgs;
02159 
02160 
02161   MyArgs = scriba_NewSbArgs(pProgram,"i i r s b",13,14,3.14,"string",2,"two character string");
02162   if( MyArgs == NULL )error("memory alloc");
02163 
02164   scriba_CallArgEx(pProgram,lEntry,NULL,5,MyArgs);
02165 
02166 =noverbatim
02167 
02168 This example passes five arguments to the ScriptBasic subroutine. Note that the last one is only
02169 two character string, the rest of the characters are ignored.
02170 
02171 CUT*/
02172   va_list marker;
02173   unsigned long cArgs,i;
02174   char *s;
02175   char *arg;
02176   pSbData p;
02177 
02178   if( pszFormat == NULL )return NULL;
02179 
02180   cArgs = 0;
02181   s = pszFormat;
02182   while( *s ){
02183     switch( *s++ ){
02184       case 'U': /* undef argument */
02185       case 'u': /* It eats no actual C level caller argument */
02186 
02187       case 'B': /* byte argument   */
02188       case 'b': /* it eats two arguments: a length and the pointer to the byte stream */
02189 
02190       case 'S': /* string argument */
02191       case 's':
02192       case 'I': /* Integer argument */
02193       case 'i':
02194       case 'R': /* Real number argument */
02195       case 'r':
02196         cArgs ++;
02197         break;
02198       default:; /* ignore all non-format characters */
02199       }
02200     }
02201   p = alloc_Alloc(sizeof(SbData)*cArgs,pProgram->pMEM);
02202   if( p == NULL )return NULL;  
02203 
02204   i = 0;
02205   va_start(marker,pszFormat);
02206   s = pszFormat;
02207   while( *s ){
02208     switch( *s++ ){
02209       case 'U':
02210       case 'u':
02211         p[i].type = SBT_UNDEF;
02212         i++;
02213         break;
02214       case 'B': /* byte stream argument */
02215       case 'b':
02216         p[i].type = SBT_STRING;
02217         p[i].size = va_arg(marker, long);
02218         arg = va_arg(marker, char *);
02219         if( arg == NULL && p[i].size != 0 ){
02220           p[i++].type = SBT_UNDEF;
02221           break;
02222           }
02223         p[i].size =  strlen(arg);
02224         if( p[i].size ){
02225           p[i].v.s = alloc_Alloc(p[i].size,pProgram->pMEM);
02226           if( p[i].v.s == NULL ){
02227             while( i ){
02228               if( p[i].type == SBT_STRING && p[i].v.s )alloc_Free(p[i].v.s,pProgram->pMEM);
02229               i--;
02230               }
02231             alloc_Free(p,pProgram->pMEM);
02232             return NULL;
02233             }
02234           memcpy(p[i].v.s,arg,p[i].size);
02235           }else{
02236           p[i].v.s = NULL;
02237           }
02238         i++;
02239         break;
02240       case 'S': /* string argument */
02241       case 's':
02242         p[i].type = SBT_STRING;
02243         arg = va_arg(marker, char *);
02244         if( arg == NULL )arg = "";
02245         p[i].size = strlen(arg);
02246         if( p[i].size ){
02247           p[i].v.s = alloc_Alloc(p[i].size,pProgram->pMEM);
02248           if( p[i].v.s == NULL ){
02249             while( i ){
02250               if( p[i].type == SBT_STRING && p[i].v.s )alloc_Free(p[i].v.s,pProgram->pMEM);
02251               i--;
02252               }
02253             alloc_Free(p,pProgram->pMEM);
02254             return NULL;
02255             }
02256           memcpy(p[i].v.s,arg,p[i].size);
02257           }else{
02258           p[i].v.s = NULL;
02259           }
02260         i++;
02261         break;
02262       case 'I': /* Integer argument */
02263       case 'i':
02264         p[i].type = SBT_LONG;
02265         p[i].v.l = va_arg(marker, long);
02266         i++;
02267         break;
02268       case 'R': /* Real number argument */
02269       case 'r':
02270         p[i].type = SBT_DOUBLE;
02271         p[i].v.d = va_arg(marker, double);
02272         i++;
02273         break;
02274       }
02275     }
02276 
02277   return p;
02278   }
02279 
02280 /*POD
02281 =H scriba_CallArgEx()
02282 
02283 This is the most sophisticated function of the ones that call a ScriptBasic subroutine.
02284 This function is capable handling parameters to scriba subroutines, and returning the
02285 modified argument variables and the return value.
02286 
02287 /*FUNCTION*/
02288 int scriba_CallArgEx(pSbProgram pProgram,
02289                      unsigned long lEntryNode,
02290                      pSbData ReturnValue,
02291                      unsigned long cArgs,
02292                      pSbData Args
02293   ){
02294 /*noverbatim
02295 The arguments:
02296 =itemize
02297 =item T<pProgram> is the program object pointer.
02298 =item T<lEntryNode> is the entry node index where the BASIC subroutine or function starts
02299       (See R<scriba_Call()> note on how to get the entry node value.)
02300 =item T<ReturnValue> is the return value of the function or subroutine
02301 =item T<cArgs> is the number of argments passed to the function
02302 =item T<Args> argument data array
02303 =noitemize
02304 CUT*/
02305   int iError;
02306   VARIABLE vArgs;
02307   VARIABLE vReturn;
02308   unsigned long i;
02309 
02310   if( cArgs )
02311     vArgs = memory_NewArray(pProgram->pEXE->pMo,0,cArgs-1);
02312   else
02313     vArgs = NULL;
02314 
02315   if( vArgs ){
02316     for( i = 0 ; i < cArgs ; i ++ ){
02317       switch( Args[i].type ){
02318         case SBT_UNDEF:
02319           vArgs->Value.aValue[i] = NULL;
02320           break;
02321         case SBT_STRING:
02322           vArgs->Value.aValue[i] = memory_NewString(pProgram->pEXE->pMo,Args[i].size);
02323           memcpy(STRINGVALUE(vArgs->Value.aValue[i]),Args[i].v.s,Args[i].size);
02324           alloc_Free(Args[i].v.s,pProgram->pMEM);
02325           break;
02326         case SBT_LONG: /* Integer argument */
02327           vArgs->Value.aValue[i] = memory_NewLong(pProgram->pEXE->pMo);
02328           LONGVALUE(vArgs->Value.aValue[i]) = Args[i].v.l;
02329           break;
02330         case SBT_DOUBLE: /* Real number argument */
02331           vArgs->Value.aValue[i] = memory_NewDouble(pProgram->pEXE->pMo);
02332           DOUBLEVALUE(vArgs->Value.aValue[i]) = Args[i].v.d;
02333           break;
02334         }
02335       }
02336     }
02337 
02338   execute_ExecuteFunction(pProgram->pEXE,lEntryNode,cArgs,vArgs ? vArgs->Value.aValue : NULL ,&vReturn,&iError);
02339   scriba_UndefSbData(pProgram,ReturnValue);
02340 
02341   if( ! iError && vReturn ){
02342     switch( vReturn->vType ){
02343       case VTYPE_LONG:
02344         ReturnValue->type = SBT_LONG;
02345         ReturnValue->v.l = LONGVALUE(vReturn);
02346         break;
02347       case VTYPE_DOUBLE:
02348         ReturnValue->type = SBT_DOUBLE;
02349         ReturnValue->v.d = DOUBLEVALUE(vReturn);
02350         break;
02351       case VTYPE_STRING:
02352         ReturnValue->type = SBT_STRING;
02353         /* we allocate a one byte longer buffer and append a terminating zero */
02354         ReturnValue->size=STRLEN(vReturn);/* size is w/o the terminating zero */
02355         ReturnValue->v.s = alloc_Alloc(ReturnValue->size+1,pProgram->pMEM);
02356         if( ReturnValue->v.s ){
02357           memcpy(ReturnValue->v.s,STRINGVALUE(vReturn),ReturnValue->size);
02358           ReturnValue->v.s[ReturnValue->size] = (char)0;
02359           }
02360         break;
02361       default:
02362         ReturnValue->type = SBT_UNDEF;
02363         break;
02364       }
02365     }
02366 
02367   if( vArgs && ! iError ){
02368     for( i = 0 ; i < cArgs ; i ++ ){
02369       if( vArgs->Value.aValue[i] == NULL ){
02370         Args[i].type = SBT_UNDEF;
02371         continue;
02372         }
02373       switch( vArgs->Value.aValue[i]->vType ){
02374         case VTYPE_LONG:
02375           Args[i].type = SBT_LONG;
02376           Args[i].v.l = LONGVALUE(vArgs->Value.aValue[i]);
02377           break;
02378         case VTYPE_DOUBLE:
02379           Args[i].type = SBT_DOUBLE;
02380           Args[i].v.d = DOUBLEVALUE(vArgs->Value.aValue[i]);
02381           break;
02382         case VTYPE_STRING:
02383           /* we allocate a one byte longer buffer and append a terminating zero */
02384           Args[i].type = SBT_STRING;
02385           Args[i].size=STRLEN(vArgs->Value.aValue[i]);/* size is w/o the terminating zero */
02386           Args[i].v.s = alloc_Alloc(Args[i].size+1,pProgram->pMEM);
02387           if( Args[i].v.s ){
02388             memcpy(Args[i].v.s,STRINGVALUE(vArgs->Value.aValue[i]),Args[i].size);
02389             Args[i].v.s[Args[i].size] = (char)0;
02390             }
02391           break;
02392         default:
02393           Args[i].type = SBT_UNDEF;
02394           break;
02395         }
02396       }
02397     }
02398 
02399   memory_ReleaseVariable(pProgram->pEXE->pMo,vArgs);
02400   memory_ReleaseVariable(pProgram->pEXE->pMo,vReturn); /*Tomasz Lacki realised its missing*/
02401   return iError;
02402   }
02403 
02404 /*POD
02405 =H scriba_LookupFunctionByName()
02406 
02407 This function should be used to get the entry point of a function
02408 knowing the name of the function. The entry point should not be treated as a
02409 numerical value rather as a handle and to pass it to functions like
02410 R<scriba_CallArgEx()>.
02411 
02412 /*FUNCTION*/
02413 long scriba_LookupFunctionByName(pSbProgram pProgram,
02414                                  char *pszFunctionName
02415   ){
02416 /*noverbatim
02417 The return value of the function is the entry node index of the function named or
02418 zero if the function is not present in the program.
02419 CUT*/
02420   return build_LookupFunctionByName(pProgram->pBUILD,pszFunctionName);
02421   }
02422 
02423 /*POD
02424 =H scriba_LookupVariableByName()
02425 
02426 This function can be used to get the serial number of a global variable
02427 knowing the name of the variable.
02428 
02429 Note that all variables belong to a name space. Therefore if you want to
02430 retrieve the global variable T<foo> you have to name it T<main::foo>.
02431 
02432 /*FUNCTION*/
02433 long scriba_LookupVariableByName(pSbProgram pProgram,
02434                                  char *pszVariableName
02435   ){
02436 /*noverbatim
02437 The return value is the serial number of the global avriable or zero if
02438 there is no variable with that name.
02439 
02440 Note that the second argument, the name of the global variable, is not
02441 going under the usual name space manipulation. You have to specify the
02442 variable name together with the name space. For example the variable T<a> will
02443 not be found, but the variable T<main::a> will be.
02444 CUT*/
02445   if( pProgram->pBUILD == NULL )return 0;
02446   return build_LookupVariableByName(pProgram->pBUILD,pszVariableName);
02447   }
02448 
02449 /*POD
02450 =H scriba_GetVariableType()
02451 
02452 Get the type of the value that a variable is currently holding. This
02453 value can be
02454 
02455 =itemize
02456 =item T<SBT_UNDEF>
02457 =item T<SBT_DOUBLE>
02458 =item T<SBT_LONG>
02459 =item T<SBT_STRING>
02460 =noitemize
02461 
02462 /*FUNCTION*/
02463 long scriba_GetVariableType(pSbProgram pProgram,
02464                             long lSerial
02465   ){
02466 /*noverbatim
02467 The argument T<lSerial> should be the serial number of 
02468 the variable as returned by R<scriba_LookupVariableByName()>.
02469 
02470 If there is no variable for the specified serian mumber (T<lSerial> is not positive
02471 or larger than the number of variables) the function returns T<SBT_UNDEF>.
02472 CUT*/
02473   if( lSerial <= 0 || lSerial > pProgram->pEXE->cGlobalVariables )return SBT_UNDEF;
02474 
02475   if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] == NULL )return SBT_UNDEF;
02476 
02477   switch( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->vType ){
02478     case VTYPE_LONG: return SBT_LONG;
02479     case VTYPE_DOUBLE: return SBT_DOUBLE;
02480     case VTYPE_STRING: return SBT_STRING;
02481     default: return SBT_UNDEF;
02482     }  
02483   }
02484 
02485 /*POD
02486 =H scriba_GetVariable()
02487 
02488 This function retrieves the value of a variable.
02489 A new T<SbData> object is created and the pointer to it
02490 is returned in T<pVariable>. This memory space is automatically
02491 reclaimed when the program object is destroyed or the function
02492 T<DestroySbData> can be called.
02493 
02494 /*FUNCTION*/
02495 int scriba_GetVariable(pSbProgram pProgram,
02496                        long lSerial,
02497                        pSbData *pVariable
02498   ){
02499 /*noverbatim
02500 The argument T<lSerial> should be the serial number of the global variable
02501 as returned by R<scriba_LookupVariableByName()>.
02502 
02503 The funtion returns T<SCRIBA_ERROR_SUCCESS> on success,
02504 
02505 T<SCRIBA_ERROR_MEMORY_LOW> if the data cannot be created or
02506 
02507 T<SCRIBA_ERROR_FAIL> if the parameter T<lSerial> is invalid.
02508 CUT*/
02509 
02510   if( lSerial <= 0 || lSerial > pProgram->pEXE->cGlobalVariables )return SCRIBA_ERROR_FAIL;
02511 
02512   if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] == NULL ){
02513     *pVariable = scriba_NewSbUndef(pProgram);
02514     if( *pVariable )return SCRIBA_ERROR_SUCCESS;
02515     return SCRIBA_ERROR_FAIL;
02516     }
02517 
02518   switch( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->vType ){
02519     case VTYPE_LONG:
02520       *pVariable = scriba_NewSbLong(pProgram,
02521                                     pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.lValue);
02522       if( *pVariable )return SCRIBA_ERROR_SUCCESS;
02523       return SCRIBA_ERROR_MEMORY_LOW;
02524     case VTYPE_DOUBLE:
02525       *pVariable = scriba_NewSbDouble(pProgram,
02526                                       pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.dValue);
02527       if( *pVariable )return SCRIBA_ERROR_SUCCESS;
02528       return SCRIBA_ERROR_MEMORY_LOW;
02529     case VTYPE_STRING:
02530       *pVariable = scriba_NewSbBytes(pProgram,
02531                                              pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Size,
02532                                              pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.pValue);
02533       if( *pVariable )return SCRIBA_ERROR_SUCCESS;
02534       return SCRIBA_ERROR_MEMORY_LOW;
02535     default:
02536       *pVariable = scriba_NewSbUndef(pProgram);
02537       if( *pVariable )return SCRIBA_ERROR_SUCCESS;
02538       return SCRIBA_ERROR_FAIL;
02539     }  
02540   }
02541 
02542 
02543 /*POD
02544 =H scriba_SetVariable()
02545 
02546 This function sets the value of a global BASIC variable. You can call this function after
02547 executing the program before it is reexecuted or after successfull call to R<scriba_NoRun()>.
02548 
02549 /*FUNCTION*/
02550 int scriba_SetVariable(pSbProgram pProgram,
02551                        long lSerial,
02552                        int type,
02553                        long lSetValue,
02554                        double dSetValue,
02555                        char *pszSetValue,
02556                        unsigned long size
02557   ){
02558 /*noverbatim
02559 The argument T<lSerial> should be the serial number of the global variable
02560 as returned by R<scriba_LookupVariableByName()>.
02561 
02562 The argument T<type> should be one of the followings:
02563 
02564 =itemize
02565 =item T<SBT_UNDEF>
02566 =item T<SBT_DOUBLE>
02567 =item T<SBT_LONG>
02568 =item T<SBT_STRING>
02569 =item T<SBT_ZCHAR>
02570 =noitemize
02571 
02572 The function uses one of the arguments T<lSetValue>, T<dSetValue> or T<pszSetValue> and
02573 the other two are ignored based on the value of the argument T<type>.
02574 
02575 If the value of the argument T<type> is T<SBT_UNDEF> all initialization arguments are ignored and the
02576 global variable will get the value T<undef>.
02577 
02578 If the value of the argument T<type> is T<SBT_DOUBLE> the argument T<dSetValue> will be used and the global
02579 variable will be double holding the value.
02580 
02581 If the value of the argument T<type> is T<SBT_LONG> the argument T<lSetValue> will be used and the global
02582 variable will be long holding the value.
02583 
02584 If the value of the argument T<type> is T<SBT_STRING> the argument T<pszSetValue> 
02585 will be used and the global variable will be long holding the value. The length of the string
02586 should in this case be specified by the variable T<size>.
02587 
02588 If the value of the argument T<type> is T<SBT_ZCHAR> the argument T<pszSetValue> 
02589 will be used and the global variable will be long holding the value. The length of the string
02590 is automatically calculated and the value passed in the variable T<size> is ignored. In this case the
02591 string T<pszSetValue> should be zero character terminated.
02592 
02593 The funtion returns T<SCRIBA_ERROR_SUCCESS> on success,
02594 
02595 T<SCRIBA_ERROR_MEMORY_LOW> if the data cannot be created or
02596 
02597 T<SCRIBA_ERROR_FAIL> if the parameter T<lSerial> is invalid. 
02598 CUT*/
02599 
02600   if( lSerial <= 0 || lSerial > pProgram->pEXE->cGlobalVariables )return SCRIBA_ERROR_FAIL;
02601 
02602   if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] ){
02603     memory_ReleaseVariable(pProgram->pEXE->pMo,pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]);
02604     pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] = NULL;
02605     }
02606   if( type == SBT_UNDEF )return SCRIBA_ERROR_SUCCESS;
02607   switch( type ){
02608     case SBT_DOUBLE:
02609          pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] =
02610            memory_NewDouble(pProgram->pEXE->pMo);
02611          if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] == NULL )return SCRIBA_ERROR_MEMORY_LOW;
02612          pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.dValue = dSetValue;
02613          return SCRIBA_ERROR_SUCCESS;
02614     case SBT_LONG:
02615          pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] =
02616            memory_NewLong(pProgram->pEXE->pMo);
02617          if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] == NULL )return SCRIBA_ERROR_MEMORY_LOW;
02618          pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.lValue = lSetValue;
02619          return SCRIBA_ERROR_SUCCESS;
02620     case SBT_ZCHAR:
02621          size = strlen(pszSetValue);
02622          type = SBT_STRING;
02623          /* nobreak flow over */
02624     case SBT_STRING:
02625          pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] =
02626            memory_NewString(pProgram->pEXE->pMo,size);
02627          if( pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1] == NULL )return SCRIBA_ERROR_MEMORY_LOW;
02628          memcpy(pProgram->pEXE->GlobalVariables->Value.aValue[lSerial-1]->Value.pValue,pszSetValue,size);
02629          return SCRIBA_ERROR_SUCCESS;
02630 
02631     default: return SCRIBA_ERROR_FAIL;
02632     }
02633   }
02634 
02635 extern MODLIST StaticallyLinkedModules[];
02636 
02637 /*POD
02638 =H scriba_InitStaticModules()
02639 
02640 This function calls the initialization functions of the modules that are statically linked
02641 into the interpreter. This is essential to call this fucntion from the embedding T<main()> program
02642 in a variation that has one or more external modules staticallyl linked. If this function is not
02643 called the module initialization will not be called, because the module is never actually loaded and
02644 thus the operating system does not call the T<DllMain> or T<_init> function.
02645 
02646 The function has to be called before the first interpreter thread starts. In case of a single
02647 thread variation this means that the function has to be called before the BASIC program starts.
02648 
02649 The function does not take any argument and does not return any value.
02650 
02651 /*FUNCTION*/
02652 void scriba_InitStaticModules(void
02653   ){
02654 /*noverbatim
02655 CUT*/
02656   MODLIST *SLM = StaticallyLinkedModules;
02657   PSLFST slf;
02658   void (*fn)(void);
02659 
02660   while( SLM->name ){
02661     for( slf = (PSLFST)SLM->table ; slf->name ; slf++ ){
02662       if( ! strcmp(slf->name,"_init") && (fn = (void *)slf->function) )fn();
02663       }
02664     SLM++;
02665     }
02666 
02667   }
02668 
02669 /*POD
02670 =H scriba_FinishStaticModules()
02671 
02672 This function calls the finalization functions of the modules that are statically linked
02673 to the interpreter. Such a function for a dynamically loaded module is started by the operating
02674 system. Because the sttaically linked modules are not loaded the T<_fini> function is not called
02675 by the UNIX loader and similarly the function T<DllMain> is not called by Windows NT. Because some
02676 modules depend on the execution of this function this function has to be called after the last
02677 interpreter thread has finished.
02678 
02679 /*FUNCTION*/
02680 void scriba_FinishStaticModules(void
02681   ){
02682 /*noverbatim
02683 CUT*/
02684   MODLIST *SLM = StaticallyLinkedModules;
02685   PSLFST slf;
02686   void (*fn)(void);
02687 
02688   while( SLM->name ){
02689     for( slf = (PSLFST)SLM->table ; slf->name ; slf++ ){
02690       if( ! strcmp(slf->name,"_fini") && (fn = (void *)slf->function) )fn();
02691       }
02692     SLM++;
02693     }
02694 
02695   }

Generated on Sun Mar 12 23:56:31 2006 for ScriptBasic by  doxygen 1.4.6-NO