fpl.doc

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

	fplAlloca -- allocate memory and bind to the FPL program running.

   SYNOPSIS
	void *fplAlloca( key, size );			 (V4)
	D0		 A0   D0

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

	If you have patched the FPL allocation routine, this will eventually
	call that function to allocate, even though this allocation is using
	the internal FPL memory chaches, which might give us memory without
	calling that allocate function!

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

   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
	fplAlloc(), fplDealloc(), fplDealloca()

fpl.library/fplDealloca                              fpl.library/fplDealloca

   NAME
	fplDealloca -- dealloc memory allocated with fplAlloca().

   SYNOPSIS
	void fplDealloca( key, pointer );		 (V4)
			  A0   A1

   FUNCTION
	This function frees memory previously allocated by fplAlloca(). 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 might eventually
	call that function to free if the memory area does not remain in the
	FPL memory cache.

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

   SEE ALSO
	fplAlloca(), fplDealloc(), fplAlloc()

fpl.library/fplAllocString                              fpl.library/fplAllocString

   NAME
	fplAllocString -- allocate memory for an FPL string.

   SYNOPSIS
	void *fplAllocString( key, size);		 (V6)
			      A0   D0

   FUNCTION
	This function allocates memory and prepares the memory block for
	holding an FPL string. Using this to allocate memory and then
	using the 'FPLSEND_DONTCOPY_STRING' tag in the fplSend() call when
	sending the allocated string to FPL, tells FPL not to duplicate
	the sent string, but simply using the supplied one.

	Strings allocated with fplAllocString() should have a matching
	fplFreeString(). Note that when i.g, sending the string to FPL with
	the 'FPLSEND_DONTCOPY_STRING' tag, FPL will do the freeing and
	not the user program!

   INPUTS
	void *key	- The return code of the fplInit() call.
	long size	- The length of the string to create. Which is the
			  same as the size of the memory block to get hands
			  on.

   RESULT
	Returns a pointer to the requested memory area. The memory is set up
	to be used as an FPL string (but you won't notice that).

   EXAMPLE
	Previous code that send a string to FPL could look like:
		{
		  char *data= malloc(1000); /* allocate */
		  strcpy(data, otherdata);  /* copy data *
		  fplSendTags(key, FPLSEND_STRING, data, TAG_DONE);
		  /* FPL duplicates the data sent */
		  free(data); /* free */
		}

	Code using the new fplAllocString() function could replace the
	old one like:
		{
		  char *data = fplAllocString(key, 1000); /* allocate */
		  strcpy(data, otherdata);  /* copy data */
		  fplSendTags(key, FPLSEND_STRING, data,
				   FPLSEND_DONTCOPY_STRING, TRUE,
				   TAG_DONE);
		  /* FPL uses the user's allocation, no extra duplication */
		}

   SEE ALSO
	fplAlloc(), fplFreeString()

fpl.library/fplFreeString                              fpl.library/fplFreeString

   NAME
	fplFreeString -- free FPL string memory.

   SYNOPSIS
	void fplFreeString( key, string);		 (V6)
			     A0   A1

   FUNCTION
	This function frees the memory associated with an FPL string. Other
	memory areas should and can not be freed with this function. Such an
	attempt will most likely damage running programs.

	This function should be called after each call to fplAllocString().

   INPUTS
	void *key	- The return code of the fplInit() call.
	char *string	- The return code an fplAllocString() call.

   EXAMPLE
	When using the fplExecuteScript() tag 'FPLTAG_STRING_RETURN' the
	returned string should be freed using fplFreeString():
		{
		  char *string;
		  fplExecuteScriptTags(key, array, lines,
				       FPLTAG_STRING_RETURN, &string,
				       FPLTAG_DONE);
		  if(string) {
		    printf("The program returned '%s'\n", string);
		    fplFreeString(key, string); /* free string */
		  }
		  else
		    printf("No string returned!\n");
		}

   SEE ALSO
	fplDealloc(), fplAllocString()

fpl.library/fplOpenLib                              fpl.library/fplOpenLib

   NAME
	fplOpenLib -- open funclib.

   SYNOPSIS
	long fplOpenLib( key, funclib, version, flags);		 (V7)
			 A0   A1       D0       D1

   FUNCTION
	Opens a funclib. This does mainly the same as the 'openlib' FPL
	function. Good to use when you want your software to open funclibs
	as default. Funclibs opened with this function can be made impossible
	to close from FPL (see the flags parameter).

	If the funclib is already opened, the open counter is simply
	increased.

   INPUTS
	void *key	- The return code of the fplInit() call.
	char *funclib	- The name of the funclib to open.
	long version	- The lowest acceptable funclib version.
	long flags	- Extra open information. These flags are available:

	FPLLIB_KEEP: A funclib opened with this flag set cannot be closed with
	an ordinary 'closelib' but must be closed using the FPLLIB_FORCE flag
	to fplCloseLib()!

   RESULT
	Zero if ok. If the result is a positive number it is a standard FPL
	error code, and if it is a negative number, it is an error code
	returned from the funclib. The numbers mean:
	-1 = the funclib was called with an illegal parameter
	-2 = funclib internal error
	-3 = failed getting system resource (pipe, message port, etc)
	-4 = out of memory
	-5 = couldn't load funclib (most likely, the funclib is missing)
	-6 = the requested version didn't exist

	More error codes will be added in the future.

   EXAMPLE
	Make your program use the funclib "foobar" version 2 from startup:
		{
		  long success;
		  success = fplOpenLib(key, "foobar", 2, FPLLIB_NONE);
		  if(0 == success)
		    printf("We failed to opened the funclib!\n");
		}

   SEE ALSO
	fplCloseLib()

fpl.library/fplCloseLib                              fpl.library/fplCloseLib

   NAME
	fplCloseLib -- close funclib.

   SYNOPSIS
	long fplCloseLib( key, funclib, flags )			 (V7)
			  A0   A1       D0

   FUNCTION
	Closes a funclib. This does mainly the same as the 'closelib' FPL
	function. Good to use when you want your software to close funclibs.
	Funclibs opened with the FPLLIB_FORCE flag set can only be closed
	using this function.

	The funclib isn't entirely removed until the open counter of the
	funclib has reached zero. To force removal, without considering
	the open counter, the FPLLIB_FORCE flag must be used.

   INPUTS
	void *key	- The return code of the fplInit() call.
	char *funclib	- The name of the funclib to open. If set to NULL,
			  *all* funclib will be closed.
	long flags	- Extra close options. These flags are available:

	FPLLIB_FORCE: A funclib opened with this flag set cannot be closed with
	an ordinary 'closelib' but must be closed using the FPLLIB_FORCE flag
	to fplCloseLib()!

   RESULT
	Zero if ok. If the result is a positive number it is a standard FPL
	error code, and if it is a negative number, it is an error code
	returned from the funclib. See fplOpenLib() for more details.

   EXAMPLE
	Make your program use the funclib "foobar" version 2 from startup:
		{
		  long success;
		  success = fplOpenLib(key, "foobar", 2, FPLLIB_NONE);
		  if(0 == success)
		    printf("We failed to opened the funclib!\n");
		}

   SEE ALSO
	fplCloseLib()

fpl.library/fplReference                            fpl.library/fplReference

   NAME
	fplReference -- handle variable references

   SYNOPSIS
	long fplReference( key, referID, tags)			(V9)
			   A0   A1       A2

	For SAS/C users:
	long fplReferenceTags( key, referID, ...)

   FUNCTION
	Whenever an external function is called (through the regular
	interface function) and one or more of the parameters is a variable
	reference, this function can be used to read and write information
	about that variable.

   TAGS
	FPLREF_TYPE
	  Supply this tag a pointer to a long, and this function will fill in
	  the bits that matches this variable type! The bits that can be
	  filled are:
	  FPLREF_TYPE_STRING	- The symbol is a string
	  FPLREF_TYPE_INTEGER	- The symbol is an integer
	  FPLREF_TYPE_ARRAY	- The symbol is a variable array (V10)

	  (no other are supported today, more are likely to appear in the
	  future)

	FPLREF_NAME
	  Supply this tag a pointer to a char pointer, and FPL will store a
	  pointer to this variable's name in there. The name is a zero
	  terminated string.

	FPLREF_GET_STRING
	  If this variable is a string, supply a pointer to a char pointer,
	  and FPL will store a pointer to this variable's contents in that,
	  or NULL if it was an integer!
	  The pointer will point to a regular FPL string, and the length
	  of it is readable through the FPLSTRLEN() macro as usual.

	FPLREF_SET_STRING
	  If this variable is a string, supply a pointer to a previously
	  fplAllocString() string, and FPL will replace this variable's
	  contents with this new string! The string MUST NOT be deallocated
	  by the program, but FPL will take care of that.

	FPLREF_GET_INTEGER
	  If this variable is an integer, supply a pointer to a long pointer,
	  and FPL will store a pointer to the contents of this variable, or
	  NULL if it wasn't an integer!

	FPLREF_SET_INTEGER
	  If this variable is an integer, supply a long that will be stored
	  as this variable's new contents!

	FPLREF_ARRAY_INFO					(V10)
	  Specify a pointer to a "struct fplRef" and information about the
	  referenced array will be returned.
	  The information pointed to by the 'ArraySize' field is READ-ONLY. Do
	  not mess with that data!

	FPLREF_ARRAY_ITEM					(V10)
	  Suply a pointer to a long array terminated with a '-1' value,
	  holding the array dimension information about which specified
	  array item you wish to read/write. I.e if the array is an integer
	  array declared as 'foobar[10][20]' and your program wants to modify
	  the item 'foobar[5][6]', the array should look like {5, 6, -1}.
	  By setting the array item first in the taglist, you can read and
	  write single items with the usual (pre V10) tags!

	FPLREF_SET_MY_STRING					(V10)
	  Like FPLREF_SET_STRING except that this tag needs a regular char
	  pointer to a regular memory area holding the string, no kind of
	  FPL-string is required. The length of the strint is either read
	  by FPL trough a strlen() call, or set with the tag below, before
	  this tag in the taglist!

	FPLREF_SET_MY_STRLEN					(V10)
	  Supply the length of the string you're about to set with
	  FPLREF_SET_MY_STRING. Use this tag before the strint set tag!

	FPLREF_ARRAY_RESIZE					(V11)
	  Supply a pointer to a filled in fplRef struct, and the referenced
	  array will be resized according to your settings. Note that you
	  are allowed to change number of dimenstions, allthough you're
	  encouraged not to. It would confuse the users a lot!
	  Resizing to smaller arrays may cause a loss of data that will be
	  lost unrecoverable. See further in the keyword 'resize' paragragh!

   INPUTS
	void *key	- The return code of the fplInit() call.
	void *referID	- Reference ID as received in the interface function.
			  This ID should *never* be used in any other way than
			  to be sent to FPL. Don't think that the same
			  variable will have the same ID twice or anything
			  similar.
   RESULT
	Zero if ok, otherwise a standard FPL error code.

   EXAMPLE
	We added a function to FPL with a format string like "R" (one required
	variable reference to a string or an integer). To get the type and the
	name of the received variabl, we use the following code:

	char *name;
	long type;
	lonf *tags[]={
	  FPLREF_TYPE, NULL,	/* get type */
	  FPLREF_NAME, NULL,	/* get name */
	  FPLREF_DONE
	};
	tags[1] = (long)&type;
	tags[3] = (long)&name;
	fplReference(key,		/* fplInit() return code */
		     arg->argv[0],	/* refer ID!             */
		     tags);

	if(type&FPLREF_TYPE_STRING)
	  printf("The variable named '%s' is a string!\n", name);
	if(type&FPLREF_TYPE_INTEGER)
	  printf("The variable named '%s' is an integer!\n", name);


   SEE ALSO
	<FPL/Reference.h>