fpl.doc

类PASCAL语言的编译器,LINUX环境的,我没试过是否正确.

	FPLTAG_STACKLIMIT.
	  The very largest memory size that FPL is permitted to use as stack.
	  This prevents the user of writing too recursive FPL programs. Try a
	  few programs to see which setting you think fits best in your
	  surrounding. Default is 40000 bytes.

	FPLTAG_MINSTACK.
	  Obsolete!

	FPLTAG_LOCKUSED.
	  This tag makes FPL to keep the lock on a file until it doesn't need
	  the file anymore. Using this tag enables a higher security level of
	  the FPL environment since no files can be removed or changed while
	  they are needed by FPL. Locks will be removed when the program is
	  not necessary any more or when fplFree() is called.

   NOTE
	*WARNING* FPLTAG_INTERNAL_ALLOC and FPLTAG_INTERNAL_DEALLOC can be
	patched run-time. If you do that, memory that has been allocated using
	the first function, might get freed by the new patch. This can be
	looked upon as a bug, but sure as well a feature. THESE TAGS MUST BE
	USED WITH CAUTION!

   RESULT
	Non-zero if everything was ok, otherwise NULL. This return code is used
	as input to all other FPL functions. Don't mess with it!

	The return code will remain the same during the entire FPL session.
	That enables you to store this in a global variable to be able to reach
	it everywhere without problems.

   INPUTS
	long (*function)(struct fplArgument*) - Pointer to the interface
						function.
	unsigned long *tags		      - Taglist pointer!

   SEE ALSO
	fplReset(), fplFree()

fpl.library/fplReset                                    fpl.library/fplReset

   NAME
	fplReset -- reset tags set in the fplInit() call.
	fplResetTags -- reset tags set in the fplInit() call.

   SYNOPSIS
	long fplReset( key, tags );
	D0	       A0   A1

	For SAS/C users:
	long fplResetTags( key, ... );

   FUNCTION
	This function is used to set fplInit() tags, after the fplInit() call.
	If you'd like to change any given data or perhaps add a tag dynamically
	between two FPL runs, this is the function for you!

   TAGS
	All fplInit() tags are available.

   RESULT
	Zero if ok, otherwise a non-zero error code!

   INPUTS
	void *key		- The return code of the initial fplInit().
	unsigned long *tags	- Taglist pointer!

   SEE ALSO
	fplInit()

fpl.library/fplSend                                     fpl.library/fplSend

   NAME
	fplSend -- multi purpose FPL communication.
	fplSendTags -- multi purpose FPL communication.

   SYNOPSIS
	long fplSend( key, tags );				(V3)
	D0            A0   A1

	For SAS/C users:
	long fplSendTags( key, ... );

   FUNCTION
	There is always communication between FPL and the host program. FPL
	communicates by calling the interface function, you answer by calling
	fplSend() with different arguments. This is the general function for
	responding to, or getting information from, FPL.

	To return values to FPL from the interface function use this. Only use
	one of the data sending tags in the same function call (tags marked
	with "**").

	The tags are read in the same order as sent. That means that you can,
	in cases where you should specify several tags, rely on the evaluation
	order and specify them all in one call.



   TAGS
	(Tags marked with two asterisks "**", are mutely exclusive. That means
	you may only specify one of those in each fplSend() call!)

	** FPLSEND_CONFIRM
	  Used to confirm or deny an FPL action. This tag answers TRUE or
	  FALSE. Ex: when a program supplied by you is allowed and about to be
	  flushed, FPL will call you with the FPL_FLUSH_FILE ID and you must
	  return a positive confirmation if you flushed.

	** FPLSEND_STRING
	  Sends a string pointer for FPL to copy. Use this only if the current
	  function is supposed to return a string. See also the FPLSEND_STRLEN
	  tag. A NULL pointer is treated the same as a pointer to a zero length
	  string.

	  FPLSEND_STRLEN
	  Used together with FPLSEND_STRING. This informs FPL about the length
	  of the sent string. If you set this to a negative number (or don't
	  set it at all), FPL will perform a strlen() on the associated string
	  pointer to get the length of it.

	  FPLSEND_DONTCOPY_STRING				(V6)
	  Enter TRUE/FALSE, default is FALSE. Use this tag if the string sent
	  to FPL is allocated with fplAllocString(). That will tell FPL to not
	  duplicated the entered string, but instead using it as it is. Do not
	  modify the string in any way after calling fplSend() with this tag.

	** FPLSEND_INT
	  Sends an integer value to FPL. Use this only if the current function
	  is supposed to return an integer.

	* FPLSEND_FLUSHCACHE
	  Tells FPL to flush (empty) all internal memory caches. This will
	  bring more free memory to the system, but also make FPL require a
	  larger number of allocations.

	* FPLSEND_FLUSHFILE
	  If a file name is specified, that file will be flushed from memory if
	  not in use and not previously flushed. Specifying zero (0) will
	  flush all files in memory that fits the same description. Even files
	  that have been declared to remain cached will be flushed when this is
	  used.

	* FPLSEND_FREEFILE
	  Deletes all functions that are currently associated with the file
	  name you specify as data to this tag.

	* FPLSEND_GETCOLUMN
	  Supply a pointer to a `long' to receive the number of the current
	  column the interpreter is working on.
	  NOTE: If using fplExecuteFile(), the program will always be read as
	  if it was on one single line which will make the column number to be
	  very large sometimes.

	* FPLSEND_GETFUNCTION					(V5)
	  Supply a pointer to a fuunction pointer to receive the pointer to
	  the current interface function.

	* FPLSEND_GETINTERVAL					(V5)
	  Supply a pointer to a fuunction pointer to receive the pointer to
	  the current interval function.	

	* FPLSEND_GETLINE
	  Supply a pointer to a `long' to receive the number of the current
	  line the interpreter is working on.
	  NOTE: If using fplExecuteFile(), the program will always be read as
	  if it was on one single line which will make this tag always return
	  1.

	* FPLSEND_GETNEWLINE_HOOK				(V5)
	  Supply a pointer to a fuunction pointer to receive the pointer to
	  the current newline hook function.	

	* FPLSEND_GETPROG					(V5)
	  Supply a pointer to a char pointer and you'll receive a pointer to
	  the current (now interpreting or last interpreted) program. If the
	  program wasn't accesible by some reason, a NULL pointer will be
	  returned. Use this for e.g. count the lines of a program loaded
	  with fplExecuteFile().

	* FPLSEND_GETPROGNAME
	  Supply a pointer to a char pointer and you'll receive a pointer to
	  the current (now interpreting or last interpreted) program name.
	  (See also the FPLTAG_PROGNAME tag for the fplExecute#? functions.)

	* FPLSEND_GETRESULT
	  Supply a pointer to a 'long' to receive the number returned by the
	  last interval function call.

	* FPLSEND_GETRETURNCODE
	  Supply a pointer to a `long' to receive the value returned in the
	  last return() or exit() call in the FPL program.

	* FPLSEND_GETRETURNINT					(V10)
	  Supply a pointer to a `long *' to receive a pointer to the value
	  returned in the last return() or exit() call in the FPL program.
	  If no value was returned, this will return NULL.

	* FPLSEND_GETSTACKSIZE
	  (Amiga only) Supply a pointer to a `long' to receive the current
	  stack size.

	* FPLSEND_GETSTACKUSED
	  (Amiga only) Supply a pointer to a `long' to receive the current
	  amount stack used.

	* FPLSEND_GETSYMBOL_FUNCTIONS
	  FPLSEND_GETSYMBOL_MYFUNCTIONS
	  FPLSEND_GETSYMBOL_FPLFUNCTIONS
	  FPLSEND_GETSYMBOL_VARIABLES
	  FPLSEND_GETSYMBOL_CACHEDFILES
	  FPLSEND_GETSYMBOL_ALLVARIABLES			(V5)
	  FPLSEND_GETSYMBOL_ALLFUNCTIONS			(V5)

	  Supply a struct fplSymbol ** (pointer to a fplSymbol struct pointer)
	  and receive data about the current FPL status!

	  FUNCTIONS means all exported and external functions
	  MYFUNCTIONS means only all external functions
	  FPLFUNCTIONS means only by FPL exported functions.
	  VARIABLES means all exported variables
	  CACHEDFILES means all cached files' names
	  ALLVARIABLES means *all* current variables even locals
	  ALLFUNCTIONS means *all* current functions even locals

	  FPLSEND_GETSYMBOL_FREE
	  Must be called after each of the above with the fplSymbol pointer as
	  data.

	* FPLSEND_GETUSERDATA
	  Supply a pointer to a `long' to receive the userdata specified in the
	  `FPLTAG_USERDATA' tag's data field in the fplInit() call. If that
	  tag wasn't specified, NULL is returned.

	* FPLSEND_GETVIRLINE					(V5.3)
	  Supply a pointer to a `long' to receive the virtual line number.
	  The virtual line number is in normal cases the desired line number
	  you want. It is simply a counter of the amount of newlines from the
	  top of the file to the current position.

	  See also: #line instruction in FPLuser.guide

	* FPLSEND_GETVIRFILE					(V5.3)
	  Supply a pointer to a char pointer, and you'll receive the virtual
	  file name. The virtual file name is usually the name of the current
	  file. The file name is zero terminated if it's _not_ started with a
	  quotation mark. If a quotation mark is the first character of the
	  file name, the file name is also ended with a quotation mark and
	  not with a zero byte! After a program execution, this will return
	  NULL!

	  See also: #line instruction in FPLuser.guide

	* FPLSEND_PROGRAMFILE
	  When using non-cached files and FPL requires a file using the
	  FPL_FILE_REQUEST, you return the file name where FPL can load the
	  FPl program using this tag. The program must not been changed since
	  FPL played with it last time!
	  The name must be zero terminated.

	** FPLSEND_PROGRAM
	  When using non-cached files and FPL requires a file using the
	  FPL_FILE_REQUEST, you return the program array pointer using this
	  tag. The program must not been changes since FPL played with it last
	  time!

	* FPLSEND_SETPROGNAME
	  Supply a pointer to the new name of the current program.
	  See FPLTAG_PROGNAME.

	* FPLSEND_SETFILENAMEGET
	  Supply a boolean whether FPL can get flushed file from the file named
	  as the program name. See FPLTAG_FILENAMGET.

	* FPLSEND_STEP
	  Moves the current interpret position forward or backward a number of
	  characters. Especially when a FPL_WARNING is received, this function
	  might be useful. For example, if a FPL_MISSING_BRACKET occurs on a
	  line like `foobar[2[="username"'; The warning will appear at the
	  postion 	     ^ and try to continue there if a confirm is sent
	  back. A continuation that will lead to a dead end error if the
	  interpret position isn't moved first one character forward.

	  Using a negative number moves it backwards, positive forwards.

	  If the beginning, or end, of program was reached, FPL_UNEXPECTED_END
	  is returned.

	  WARNING! This must be used with common sense! Moving the interpret
	  position without a reason as above or similar, will deeply confuse
	  FPL, which likely starts reporting mysterious errors and in other
	  ways act strange.

	* FPLSEND_RESULT					(V10)
	  Supply a pointer to a long that fplSend() can use to store extra
	  return code informations in! The adress will be remembered by FPL
	  and repeated calls with the tags that use this do not need to set
	  this!

	* FPLSEND_IS_FILE_CACHED				(V10)
	  Supply a pointer to the program name. The long to which the
	  FPLSEND_RESULT tag points to will hold TRUE if the program is
	  cached, and FALSE if it isn't.

   RESULT
	Zero if ok, otherwise a standard FPL error code.

   INPUTS
	void *key	- The return code of the fplInit() call.
	unsigned long *	- A taglist pointer.

   SEE ALSO

fpl.library/fplAlloc                                 fpl.library/fplAlloc

   NAME
	fplAlloc -- allocate memory and bind to the FPL resource list.

   SYNOPSIS
	void *fplAlloc( key, size );			 (V3)
	D0		A0   D0

   FUNCTION
	This function allocates memory and attaches it to the current internal
	list of memory used in this FPL session. All memory in that list will
	be freed at the fplFree() call. Single memory areas allocated with this
	function can be freed with fplDealloc().

	If you have patched the FPL allocation routine, this will eventually
	call that function to allocate.

	This allocation works like the C language malloc(), which means that it
	always allocates 12 extra bytes to store allocation information in.

	Future versions of FPL might get special fplSend() tags to use if you
	have fplAlloc()'ed memory that you send to it to reduce the situations
	where you allocate memory for a string, send it to FPL which allocates
	again and copies your data, and then you free your memory again... One
	too many allocations I think!

   RESULT
	A pointer to an allocated memory area, or NULL if the allocation
	failed.

   INPUTS
	void *key	- The return code of the fplInit() call.
	unsigned long 	- Size of allocation.

   SEE ALSO
	fplAlloca(), fplDealloc(), fplDealloca()

fpl.library/fplDealloc                                fpl.library/fplDealloc

   NAME
	fplDealloc -- deallocated memory allocate with fplAlloc().

   SYNOPSIS
	void fplDealloc( key, pointer );		 (V3)
			 A0   A1

   FUNCTION
	This function frees memory previously allocated by fplAlloc(). Using
	this on memory allocated by any other memory will trash memory and
	the resulting happenings are really not known!

	If you have patched the FPL deallocation routine, this will eventually
	call that function to free.

   INPUTS
	void *key	- The return code of the fplInit() call.
	void *pointer 	- Pointer to a previosly fplAlloc()'ed memory area.

   SEE ALSO
	fplAlloca(), fplAlloc(), fplDealloca()

fpl.library/fplAlloca                                fpl.library/fplAlloca

   NAME