PRO FXBCREATE, UNIT, FILENAME, HEADER, EXTENSION, ERRMSG=ERRMSG;+; NAME: ;	FXBCREATE; Purpose     : ;	Open a new binary table at the end of a FITS file.; Explanation : ;	Write a binary table extension header to the end of a disk FITS file,;	and leave it open to receive the data.;;	The FITS file is opened, and the pointer is positioned just after the;	last 2880 byte record.  Then the binary header is appended.  Calls to;	FXBWRITE will append the binary data to this file, and then FXBFINISH;	will close the file.;; Use         : ;	FXBCREATE, UNIT, FILENAME, HEADER; Inputs      : ;	FILENAME = Name of FITS file to be opened.;	HEADER	 = String array containing the FITS binary table extension;		   header.; Opt. Inputs : ;	None.; Outputs     : ;	UNIT	 = Logical unit number of the opened file.;       EXTENSION= Extension number of newly created extension.; Opt. Outputs: ;	None.; Keywords    : ;	ERRMSG	  = If defined and passed, then any error messages will be;		    returned to the user in this parameter rather than;		    depending on the MESSAGE routine in IDL.  If no errors are;		    encountered, then a null string is returned.  In order to;		    use this feature, ERRMSG must be defined first, e.g.;;			ERRMSG = '';			FXBCREATE, ERRMSG=ERRMSG, ...;			IF ERRMSG NE '' THEN ...;; Calls       : ;	FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND; Common      : ;	Uses common block FXBINTABLE--see "fxbintable.pro" for more;	information.; Restrictions: ;	The primary FITS data unit must already be written to a file.  The;	binary table extension header must already be defined (FXBHMAKE), and;	must match the data that will be written to the file.; Side effects: ;	None.; Category    : ;	Data Handling, I/O, FITS, Generic.; Prev. Hist. : ;	W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman.;	W. Thompson, Feb 1992, changed from function to procedure.;	W. Thompson, Feb 1992, removed all references to temporary files.; Written     : ;	William Thompson, GSFC, January 1992.; Modified    : ;	Version 1, William Thompson, GSFC, 12 April 1993.;		Incorporated into CDS library.;	Version 2, William Thompson, GSFC, 21 July 1993.;		Fixed bug with variable length arrays.;	Version 3, William Thompson, GSFC, 21 June 1994;		Added ERRMSG keyword.;	Version 4, William Thompson, GSFC, 23 June 1994;               Modified so that ERRMSG is not touched if not defined.;	Version 5, Antony Bird, Southampton, 25 June 1997;		Modified to allow very long tables ; Version     :;	Version 5, 25 June 1997;	Converted to IDL V5.0   W. Landsman   September 1997;       Added EXTENSION parameter, C. Markwardt 1999 Jul 15;       More efficient zeroing of file, C. Markwardt, 26 Feb 2001;-;@fxbintable	ON_ERROR, 2;;  Check the number of parameters.;	IF N_PARAMS() LT 3 THEN BEGIN		MESSAGE = 'Syntax:  FXBCREATE, UNIT, FILENAME, HEADER'		IF N_ELEMENTS(ERRMSG) NE 0 THEN BEGIN			ERRMSG = MESSAGE			RETURN		END ELSE MESSAGE, MESSAGE	ENDIF;;  Get a logical unit number, open the file, and find the end.;	GET_LUN,UNIT       	OPENU, UNIT, FILENAME, /BLOCK	FXFINDEND, UNIT, EXTENSION;;  Store the UNIT number in the common block, and leave space for the other;  parameters.  Initialize the common block if need be.  ILUN is an index into;  the arrays.;	ILUN = FXBFINDLUN(UNIT);;  Store the current position as the start of the header.  Mark the file as;  open for write.;	POINT_LUN,-UNIT,POINTER	MHEADER[ILUN] = POINTER	STATE[ILUN] = 2;;  Determine if an END line occurs, and add one if necessary;	ENDLINE = WHERE(STRMID(HEADER,0,8) EQ 'END     ', NEND)	ENDLINE = ENDLINE[0]	IF NEND EQ 0 THEN BEGIN		MESSAGE,/INF,'WARNING - An END statement has been appended ' +$			'to the FITS header'		HEADER = [HEADER, 'END' + STRING(REPLICATE(32B,77))]		ENDLINE = N_ELEMENTS(HEADER) - 1 	ENDIF	NMAX = ENDLINE + 1		;Number of 80 byte records	NHEAD = FIX((NMAX+35)/36)	;Number of 2880 byte records;;  Convert the header to byte and force into 80 character lines.;WRITE_HEADER:	BHDR = REPLICATE(32B, 80, 36*NHEAD)	FOR N = 0,ENDLINE DO BHDR[0,N] = BYTE( STRMID(HEADER[N],0,80) )	WRITEU, UNIT, BHDR;;  Get the rest of the information, and store it in the common block.;	IF N_ELEMENTS(ERRMSG) NE 0 THEN BEGIN		FXBPARSE,ILUN,HEADER,ERRMSG=ERRMSG		IF ERRMSG NE '' THEN RETURN	END ELSE FXBPARSE,ILUN,HEADER;;  Check the size of the heap offset.  If the heap offset is smaller than the;  table, then reset it to the size of the table.;	DDHEAP = HEAP[ILUN] - NAXIS1[ILUN]*NAXIS2[ILUN]	IF DDHEAP LT 0 THEN BEGIN		MESSAGE,'Heap offset smaller than table size--resetting', $			/CONTINUE		HEAP[ILUN] = NAXIS1[ILUN]*NAXIS2[ILUN]		FXADDPAR,HEADER,'THEAP',HEAP[ILUN]		POINT_LUN, UNIT, MHEADER[ILUN]		GOTO, WRITE_HEADER	ENDIF;;  Fill out the file to size it properly.;        ;; This segment is now optimized to write out more than one        ;; row at a time, which is crucial for tables with many small        ;; rows.  The code heuristically chooses a buffer size which        ;; is 1% of the file, but no bigger than 512k, and always a        ;; multiple of the row size.        BUFSIZE = LONG(NAXIS1[ILUN]*NAXIS2[ILUN]/100) > NAXIS1[ILUN] < 524288L        BUFSIZE = (FLOOR(BUFSIZE/NAXIS1[ILUN])>1) * NAXIS1[ILUN]        BUFFER = BYTARR(BUFSIZE)        TOTBYTES = NAXIS1[ILUN]*NAXIS2[ILUN]        ;; TOTBYTES keeps count of bytes left to write        WHILE TOTBYTES GT 0 DO BEGIN            ;; Case of final rows which might not be EQ BUFSIZE            IF TOTBYTES LT BUFSIZE THEN BUFFER = BYTARR(TOTBYTES)            WRITEU,UNIT,BUFFER            TOTBYTES = TOTBYTES - BUFSIZE        ENDWHILE;;  If there's any extra space before the start of the heap, then write that out;  as well.;	IF DDHEAP GT 0 THEN BEGIN		BUFFER = BYTARR(DDHEAP)		WRITEU,UNIT,BUFFER	ENDIF;;  Initialize DHEAP, and return.;	DHEAP[ILUN] = 0;	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = ''	RETURN	END