5.3 The xaslib library

Use the subject list in the previous page, or the quick alphabetic index here below to locate the routine of interest.

• addhistory

  Library	xaslib	Fortran code
  Calling sequence	CALL ADDHISTORY(string)
  Arguments	CHARACTER*(*)	STRING

  Category : XAS file header keywords
  This routine writes a sequence of one or more HISTORY keywords splitting the user-supplied STRING into pieces shoter or equal to 68 characters and by repeated calls to h_add_keyword
  Side effects : STRING is modified to collapse multiple blanks, and the in-memory header is entirely flushed to disk (this is considered normal since this should be the last call when processing an output file).

  ---

• askbin

  Category : Accumulation
  These two routines concerning the setup of time profile accumulations are not intended to be called directly, but by satellite specific "range setup" routines like sax_acc_range and alike.

  Library	xaslib	Fortran code
  Calling sequence	CALL ASKBIN(DEFBIN,ZOOM)
  Arguments	INTEGER	DEFBIN
  	INTEGER	ZOOM

  This routine, being passed a default minimum bin size for a time profile DEFBIN (in spacecraft OBT units), asks the user for the wished bin size (in seconds), and returns the corresponding ZOOM factor (as multiple of the default minimum).

• asktime

  Library	xaslib	Fortran code
  Calling sequence	CALL ASKTIME(KEY,TIMED)
  Arguments	CHARACTER*(*)	KEY ('Start'|'End')
  	DOUBLE PRECISION	TIMED

  This routine, being passed a default time TIMED (in spacecraft OBT units ?), asks the user for the wished time (as y m d h m s f time array), and returns the corresponding TIMED as elapsed seconds from a reference time.
  The call must be done separately for start and end times of an accumulation using the appropriate value of KEY

  ---

• blkbincommon

  Library	xaslib	Fortran code
  Calling sequence	EXTERNAL BLKBINCOMMON

  This BLOCK DATA routine is called implicitly by the create or open calls for tabular XAS files (spectra, time profiles or photon lists) to initialize the BINCOMMON common block used to keep track of binary table characteristics.

  ---

• blkctxcommon

  Library	xaslib	Fortran code
  Calling sequence	EXTERNAL BLKCTXCOMMON

  This BLOCK DATA routine is called implicitly by buildpath to initialize a small CTXCOMMON common block containing the current instrument and context codes (the context is the wished type of data to be created, e.g. spectrum, image etc.).

  ---

• blkhcommon

  Library	xaslib	Fortran code
  Calling sequence	EXTERNAL BLKHCOMMON

  This BLOCK DATA routine is called implicitly by header read or modification routines and by the low level XAS file opening routines) to initialize the HCOMMON common block used to keep track of XAS file characteristics, inclusive of the in-memory header buffers.

  ---

• buildpath

  Library	xaslib	Fortran code
  Calling sequence	CALL BUILDPATH(NAMEIN,CODE,NAMEOUT)
  Arguments	CHARACTER*(*)	NAMEIN
  	CHARACTER*(*)	CODE ('FOT'|'DATA'|'PRINT'|'CALIB')
  	CHARACTER*(*)	NAMEOUT

  This widely used call takes a pathless or relative filename NAMEIN and returns a full path NAMEOUT which locates the file in the appropriate directory according to the specification of CODE and also adds the appropriate file extension according to context :
  • if NAMEIN is an absolute path, it is assumed already qualified (only file extension processing)
  • for CODE='DATA' the path is constructed concatenating the environment variables rootdir, datadir, date, target, instrument in the order mandated by order
  • for CODE='FOT' the path is constructed similarly but using also fotdir and fotorder
  • for CODE='PRINT' the path is constructed similarly but using printdir and printorder
  • for CODE='CALIB' the file is searched in the private directory pointed by the user defined environment variable mycaldir and, if such variable is not defined, or the specific file is not present, in the spacecraft and instrument specific subdirectory of the calibration directory

  ---

• close_xas_file

  Library	xaslib	Fortran code
  Calling sequence	CALL CLOSE_XAS_FILE(lu)
  Arguments	INTEGER	LU

  This routine closes the XAS file open on logical unit LU, flushing its header to disk, and freeing the associated memory buffers.
  A call to this routine is not necessary if the header is flushed to disk by other means and the same XAS file number will not be reused in the same program.
  It is recommended to close XAS files in the reverse order in which they were opened (this is a feature of the association between logical units and XAS file numbers).

  ---

• copy_table_desc

  Library	xaslib	Fortran code
  Calling sequence	CALL COPY_TABLE_DESC (in,out)
  Arguments	INTEGER	IN,OUT

  Copies the BINCOMMON table descriptor for table number IN into the one for table number OUT, where IN,OUT are XAS file numbers.

  ---

• create_image

  Library	xaslib	Fortran code
  Calling sequence	CALL CREATE_IMAGE(lu,filename,sizex,sizey,array,nx,ny,type)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	SIZEX,SIZEY
  	any*4	ARRAY
  	INTEGER	NX,NY
  	CHARACTER*(3)	TYPE ('FLO'|'INT')

  This routine creates and writes a new XAS image file with VOS name FILENAME using logical unit LU. It writes an image of logical sizes SIZEX,SIZEY taking it from the array ARRAY of physical sizes NX,NY (the distinction hardly matters if one uses dynamic memory allocation).
  ARRAY is normally REAL (TYPE='FLO'), although the routine will correctly write it even if INTEGER*4, however the TYPE='INT' is not honored at present (the BITPIX keyword is set to -32, i.e. real data).
  An image file written this way shall be immediately usable (has a minimal header), however it is recommended to complete writing of header keywords.

  ---

• create_photon

  Library	xaslib	Fortran code
  Calling sequence	CALL CREATE_PHOTON(lu,filename,nbins,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	NBINS
  	INTEGER	IZOFF

  This routine creates a new XAS photon file with VOS name FILENAME using logical unit LU. It reserves space for NBINS records (photons) and returns the zero-record offset IZOFF to be passed to other calls like write_bin.
  It prepares a minimal header with the binary table keywords according to the content of a table descriptor prepared in advance, but does not write any data.

  ---

• create_spectrum

  Library	xaslib	Fortran code
  Calling sequence	CALL CREATE_SPECTRUM(lu,filename,nbins,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	NBINS
  	INTEGER	IZOFF

  This routine creates a new XAS spectrum file with VOS name FILENAME using logical unit LU. It reserves space for NBINS records (channels) and returns the zero-record offset IZOFF to be passed to other calls like write_bin or used as offset to write records directly.
  It prepares a minimal header with the binary table keywords according to the content of a table descriptor prepared in advance, but does not write any data.

  ---

• create_time

  Library	xaslib	Fortran code
  Calling sequence	CALL CREATE_TIME(lu,filename,nbins,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	NBINS
  	INTEGER	IZOFF

  This routine creates a new XAS time profile with VOS name FILENAME using logical unit LU. It reserves space for NBINS records (time bins) and returns the zero-record offset IZOFF to be passed to other calls like write_bin.
  It prepares a minimal header with the binary table keywords according to the content of a table descriptor prepared in advance, but does not write any data.

  ---

• decodetform

  Library	xaslib	Fortran code
  Calling sequence	CALL DECODETFORM(TFORM,IBIT,N)
  Arguments	CHARACTER*(*)	TFORM
  	INTEGER	IBIT
  	INTEGER	N

  Category: binary table support
  This routines receives a FITS-style TFORM keyword (only 'nB','nI','nJ','nE','nD' are recognised) and returns the corresponding number of bits IBIT (in FITS BITPIX usage, i.e. 8,16,32,-32,-64) and depth (N=n)

  ---

• depath

  Library	xaslib	Fortran code
  Calling sequence	CALL DEPATH(NAME)
  Arguments	CHARACTER*(*)	NAME

  This routine modifies in place the filename NAME stripping its path and the file extension.

• depath_1

  Library	xaslib	Fortran code
  Calling sequence	CALL DEPATH_1(NAME)
  Arguments	CHARACTER*(*)	NAME

  This routine modifies in place the filename NAME stripping its path but leavin the file extension intact.

  ---

• detpointing

  Library	xaslib	Fortran code
  Calling sequence	CALL DETPOINTING(RA,DEC,ROLL)
  Arguments	DOUBLE PRECISION	RA,DEC,ROLL

  Category: attitude
  Side effects: loading info in PIXCOMMON
  This routine returns in radians the detector pointing coordinates RA,DEC and ROLL angle. If they are present in the current image file header, it just returns them.
  Otherwise it calls misalign to get the misalignments, satpointing to get the spacecraft pointing, computes Euler angles and applies the rotation matrix with radecroll

  ---

• get_global_default

  Library	xaslib	Fortran code
  Calling sequence	CALL GET_GLOBAL_DEFAULT(name,default,value)
  Arguments	CHARACTER*(*)	NAME
  	CHARACTER*(*)	DEFAULT
  	CHARACTER*(*)	VALUE

  Category: environment access
  This is the standard recommended way to obtain the VALUE of an enviroment variable of given NAME. It calls the VOS z_get_global routine but, if the variable does not exist, returns the user supplied DEFAULT

  ---

• get_obs_chain

  Library	xaslib	Fortran code
  Calling sequence	CALL GET_OBS_CHAIN(IOBS,KEEP)
  Arguments	INTEGER	IOBS
  	CHARACTER*(5)	KEEP ('Keep'|'Reset'|'Any')

  Category:accumulation support
  This routine is called by (SAX packetcap based) telemetry reading routines to know what is the next observation in the current chain (stored in the environment). The observation number is returned in IOBS, or zero if there is no further observation.
  
  • KEEP='Reset' returns in IOBS the first observation of the chain.
  • KEEP='Keept' returns in IOBS the current observation of the chain and does not advance the observation pointer (the same IOBS will be returned next time)
  • any other value advances the observation pointer

  ---

• get_table_desc

  Library	xaslib	Fortran code
  Calling sequence	CALL GET_TABLE_DESC (table,column,offset,bitpix,dimens)
  Arguments	INTEGER	TABLE
  	INTEGER	COLUMN
  	INTEGER	OFFSET,BITPIX,DIMENS

  Category: binary table support
  This routines returns the characteristics (i.e. the physical column number OFFSET, the bit width in FITS syntaxBITPIX and the depth or dimensionality DIMENS) of the column at logical number COLUMN in the binary table file with XAS file number tt>TABLE, reading it from the BINCOMMON common block.

  ---

• getmisalign

  Library	xaslib	Fortran code
  Calling sequence	CALL GETMISALIGN(ALPHA,BETA,GAMMA)
  Arguments	DOUBLE PRECISION	ALPHA,BETA,GAMMA

  Category: attitude
  This routine returns the Z,Y and X misalignments ALPHA,BETA,GAMMA reading them from the appropriate calibration file or asking the user.
  Side effect: loads instrument focal length in COMMON block.

  ---

• h_add_keyword

  This routine has 5 entry points and is used to add an header keyword of appropriate type, given NAME and VALUE. For all calls one can specify if the keyword is just added to the in-memory copy of the header (FLUSHFLAG=0) or if the header is also flushed to disk (FLUSHFLAG=0). It is suggested to defer flushing only to significant points (adding a complete series of keywords, or closing the file).

  Library	xaslib	Fortran code
  Calling sequence	CALL H_ADD_KEYWORD(name,value,flushflag)
  Arguments	CHARACTER*(*)	NAME
  	CHARACTER*(*)	VALUE
  	INTEGER	FLUSHFLAG (0|1)

  The above call is for CHARACTER keywords (i.e. VALUE is a string)

  Calling sequence	CALL H_ADD_IKEYWORD(name,value,flushflag,n)
  Arguments	INTEGER*2	VALUE(*)
  	INTEGER	N

  The above call is for 16-bit integer keywords (discouraged). See below for the explanation of the extra arguments and above for the common arguments (not shown).

  Calling sequence	CALL H_ADD_JKEYWORD(name,value,flushflag,n)
  Arguments	INTEGER	VALUE(*)
  	INTEGER	N

  The above call is for 32-bit integer keywords. In this case, as for all numeric keywords, the values can be an array VALUE(*) of at least N elements. If VALUE is a scalar, N shall be a variable with value 1. N shall always be a variable.

  Calling sequence	CALL H_ADD_RKEYWORD(name,value,flushflag,n)
  Arguments	REAL	VALUE(*)
  	INTEGER	N

  Similar call for numeric 32-bit floating point REALs

  Calling sequence	CALL H_ADD_DKEYWORD(name,value,flushflag,n)
  Arguments	DOUBLE PRECISION	VALUE(*)
  	INTEGER	N

  Similar call for numeric 64-bit floating point DOUBLE PRECISION values.

  ---

• h_copy_all_header

  Library	xaslib	Fortran code
  Calling sequence	CALL H_COPY_ALL_HEADER(in,out)
  Arguments	INTEGER	IN,OUT

  Copies the in-memory header for XAS file number IN into the one for XAS file number OUT. The headers are not flushed to disk. The destination is overwritten entirely (thus any keyword which shall be different must be saved and restored care of the program).

  ---

• h_current_file

  Library	xaslib	Fortran code
  Calling sequence	CALL H_CURRENT_FILE(XASNO)
  Arguments	INTEGER	XASNO

  Most header operations (typically all keyword access routines) operate on the current XAS file (typically the last one opened). This routine allows to switch future operations to another file identified by its XAS file number XASNO.

  ---

• h_find_keyword

  Library	xaslib	Fortran code
  Calling sequence	CALL H_FIND_KEYWORD(name,found,type,length,nelem,pointer)
  Arguments	CHARACTER*(*)	NAME
  	LOGICAL	FOUND
  	INTEGER	TYPE
  	INTEGER	LENGTH
  	INTEGER	NELEM
  	INTEGER	POINTER

  This dedicated routine is not intended for general use. It locates a kewyord with given NAME in the memory copy of the header. A successful search returns FOUND=.TRUE.. In such case TYPE is the keyword type (0 chracter, 1 INTEGER*2, 2 INTEGER*2, 3 REAL*4, 4 REAL*8 ) LENGTH is the number of bytes occupied by the data field value in the memory buffer, NELEM is the number of elements (in arrays, 1 is scalar) and POINTER is the location of the keyword in the memory buffer
  The scope of the search can be controlled by the HCOMMON_CONTEXT variable (since this is not intended for public use, it is documented only in the code)

  ---

• h_flush_header

  Library	xaslib	Fortran code
  Calling sequence	CALL H_FLUSH_HEADER

  This service routine flushes the in-memory header buffer to disk. Not intended for public use.

  ---

• h_flush_minih

  Library	xaslib	Fortran code
  Calling sequence	CALL H_FLUSH_MINIH(zoff)
  Arguments	INTEGER	ZOFF

  This service routine flushes the file mini-header buffer to disk. Not intended for public use. Called by the previous routine.
  The mini-header is represented by 28 bytes of information which are always stored at the beginning of the file (the remainder of the header is stored after the data, being actually a trailer), and spans ZOFF records (typically 1, but more if the file record length is very short).

  ---

• h_load_header

  Library	xaslib	Fortran code
  Calling sequence	CALL H_LOAD_HEADER

  This service routine reads the in-memory header buffer from disk. Not intended for public use. It takes also care of initial dynamic memory allocation for the header.

  ---

• h_load_minih

  Library	xaslib	Fortran code
  Calling sequence	CALL H_LOAD_MINIH(recl,zoff)
  Arguments	INTEGER	RECL
  	INTEGER	ZOFF

  This service routine reads a file mini-header from disk. Not intended for public use.
  The mini-header is described above and spans ZOFF records. This call is usually the first after a file has been opened (opening makes known the file record length in bytes RECL, required by this routine).

  ---

• h_modify_keyword

  This routine, similary to h_add_keyword, has 5 entry points and is used to modify an header keyword of appropriate type, given NAME and VALUE. The calling sequence is the same used for h_add_keyword, to which one is referred for all details.
  In fact this routine calls h_add_keyword if a keyword with given NAME does not exist. Otherwise it locates the existing keyword and changes its value (but cannot extend the data field length, therefore a string keyword cannot be made longer, and an array keyword cannot have more elements)
  Normal keywords are not "duplicatable". Only a given keyword with a given NAME can be present in a file. There are however some "duplicatable" keywords (namely COMMENT, HISTORY and PARENTS which cannot be modified by this routine (a new keyword will always be added)

  Library	xaslib	Fortran code
  Calling sequence	CALL H_MODIFY_KEYWORD(name,value,flushflag)
  	CALL H_MODIFY_IKEYWORD(name,value,flushflag,n)
  	CALL H_MODIFY_JKEYWORD(name,value,flushflag,n)
  	CALL H_MODIFY_RKEYWORD(name,value,flushflag,n)
  	CALL H_MODIFY_DKEYWORD(name,value,flushflag,n)

  For character, INTEGER*2, INTEGER*4, REAL and DOUBLE PRECISION keywords respectively

  ---

• h_next_keyword

  Library	xaslib	Fortran code
  Calling sequence	CALL H_NEXT_KEYWORD(NAME,NORDER,POINTER)
  Arguments	CHARACTER*(*)	NAME
  	INTEGER	NORDER
  	INTEGER	POINTER

  This dedicated routine is not intended for general use and is used only by some specific programs which need to scan the header from the beginning. It returns the NAME of the next keyword (or a null, i.e. CHAR(0) if there are no more keywords), its sequence number NORDER and the location of the keyword in the memory buffer POINTER.

  ---

• h_read_keyword

  This routine has 5 entry points and is used to retrieve the VALUE of an header keyword of appropriate type, given its NAME. For all calls, if the named keyword is not found, an user supplied DEFAULT is returned in VALUE.

  All calls return also an ERROR code, which is 0 for no errors, 1 for keyword not found, 2 for type mismatch (keyword is not of the type implied by the call), 3 if the header has not yet been loaded from disk, and -1 for a truncation error (the space provided in VALUE is not enough to contain the actual value). Error codes less or equal to zero imply that the partial or full value is returned. Error codes greater than zero imply that DEFAULT is returned in its stead.

  Library	xaslib	Fortran code
  Calling sequence	CALL H_READ_KEYWORD(name,value,default,error)
  Arguments	CHARACTER*(*)	NAME
  	CHARACTER*(*)	VALUE
  	CHARACTER*(*)	DEFAULT
  	INTEGER	ERROR

  The above call is for CHARACTER keywords (i.e. VALUE is a string)

  Calling sequence	CALL H_READ_IKEYWORD(name,value,default,error,n)
  Arguments	INTEGER*2	VALUE(*)
  	INTEGER*2	DEFAULT
  	INTEGER	N

  The above call is for 16-bit integer keywords (discouraged). See below for the explanation of the extra arguments and above for the common arguments (not shown).

  Calling sequence	CALL H_READ_JKEYWORD(name,value,default,error,n)
  Arguments	INTEGER	VALUE(*)
  	INTEGER	DEFAULT
  	INTEGER	N

  The above call is for 32-bit integer keywords. In this case, as for all numeric keywords, the values can be an array VALUE(*) of at least N elements. N shall always be a variable initialized to the number of wished elements to be retrieved. If VALUE is a scalar, N shall be a variable with value 1. This because N is modified by the program which returns the actual number of keywords retrieved : if the array is longer, no more than than the requested N are returned, but if it is shorter only the first actual N are returned. The rest of the VALUE(*) array is filled with the (scalar) DEFAULT (which in case of errors is used to fill the entire array).

  Calling sequence	CALL H_READ_RKEYWORD(name,value,default,error,n)
  Arguments	REAL	VALUE(*)
  	REAL	DEFAULT
  	INTEGER	N

  Similar call for numeric 32-bit floating point REALs

  Calling sequence	CALL H_READ_DKEYWORD(name,value,default,error,n)
  Arguments	DOUBLE PRECISIO	VALUE(*)
  	DOUBLE PRECISIO	DEFAULT
  	INTEGER	N

  Similar call for numeric 64-bit floating point DOUBLE PRECISION values.

  ---

• h_update_datasize

  Library	xaslib	Fortran code
  Calling sequence	CALL H_UPDATE_DATASIZE(NDATA)
  Arguments	INTEGER	NDATA

  This routine shall be used in the following case :
  • one has created a XAS data file reserving space for a number of records (or even for zero records)
  • this has implicitly written to disk the header after the data area for such records (which can also be filled later)
  • one has either written more records, or decided that less records have to be used (in which case the disk header is at the wrong place) where NDATA is the final number of actual records
  • one might have also updated the in-memory copy of the header
  In all this cases one must call this routine to update the 28-byte mini-header, change the NAXIS2 keyword (which for all XAS files is the number of records), and flush the header to disk at the correct place.

  ---

• init_timewindow

  Library	xaslib	Fortran code
  Calling sequence	CALL INIT_TIMEWINDOW(FILE)
  Arguments	CHARACTER*(*)	FILE

  Category: time window / accumulation support
  The routine retrieves the name of the timewindow file from the environment and returns it in FILE (a blank string is returned if no timewindow is defined).
  If a file is defined it calls openwindow and loadwindow to read the file (an ASCII file containing a list of start and end times in time array form) and store the times in a COMMON block in the appropriate time units.

  ---

• leftnumber

  Library	xaslib	Fortran code
  Calling sequence	CHARACTER*3 FUNCTION LEFTNUMBER(N,ISIZE)
  Arguments	INTEGER	N
  	INTEGER	ISIZE

  Category: binary table support
  This function formats a number N (0-999) into a 3-digit left-justified, blank padded string (i.e. '1 ','10 ','100') and returns in ISIZE the number of non-blank digits (in the example respectively 1,2,3), or zero in case of errors (including N out of range) when the string '***' is returned.
  This routine is used by maketform to build FITS-style TFORM values.

  ---

• loadwindow

  Library	xaslib	Fortran code
  Calling sequence	CALL LOADWINDOW(LU,N,START,END)
  Arguments	INTEGER	LU
  	INTEGER	N
  	DOUBLE PRECISION	START(*),END(*)

  Category: time window
  This routine reads from the timewindow file opened by openwindow on logical unit LU a number N of start and end times into the START and END arrays (as a number of seconds since 1970 but in double precision format).

  ---

• maketform

  Library	xaslib	Fortran code
  Calling sequence	CHARACTER*(*) FUNCTION MAKETFORM(IBIT,N)
  Arguments	INTEGER	IBIT
  	INTEGER	N

  Category: binary table support
  This routine receives the number of bits IBIT (in FITS BITPIX usage, i.e. 8,16,32,-32,-64) and depth (N=n) of a binary table column and returns a formatted FITS-style TFORM keyword (only 'nB','nI','nJ','nE','nD' are supported in XAS)

  ---

• misalign

  Library	xaslib	Fortran code
  Calling sequence	CALL MISALIGN(EULER,NEWMAT)
  Arguments	DOUBLE PRECISION	EULER(3,3)
  	DOUBLE PRECISION	NEWMAT(3,3)

  Category: attitude
  This routines takes an input attitude EULER matrix (typically the spacecraft attitude) and rotates it by the Z,Y,X misalignments (retrieved via getmisalign producing a new attitude matrix tt>NEWMAT

  ---

• multiply_rmfarf

  Library	xaslib	Fortran code
  Calling sequence	CALL MULTIPLY_RMFARF(RMF,ARF,ELOW,EUP,NEBN,NEOUT)
  Arguments	REAL	RMF(NEBN,NEOUT)
  	REAL	ARF(NEBN)
  	REAL	ELOW(NEBN),EUP(NEBN)
  	INTEGER	NEBN,NEOUT

  This routine takes a "pure" (adimensional) response matrix function from RMF, and returns in the same RMF the product (cm² keV) of it by the ARF (cm²) and by the energy grid bin width (computed from the lower and upper energy bounds in ELOW and EUP. The units are consistent with the XAS convention for response matrices.
  NEBN is the number of input energies, while NEOUT is the number of PHA channels.

  ---

• open_image

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_IMAGE(lu,filename,sizex,sizey,bitpix,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	BITPIX
  	INTEGER	SIZEX,SIZEY
  	INTEGER	IZOFF

  This routine opens an existing XAS image file with VOS name FILENAME using logical unit LU. It returns the image size SIZEX,SIZEY, the number of bits/pixel BITPIX (in FITS convention, -32 for floating point images is the recommended usage) and the zero-record offset IZOFF to be passed to other calls like read_image.

  ---

• open_matrix

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_MATRIX(lu1,lu2,filename,sizex,sizey,izoff1,izoff2)
  Arguments	INTEGER	LU1,LU2
  	CHARACTER*(*)	FILENAME
  	INTEGER	SIZEX,SIZEY
  	INTEGER	IZOFF1,IZOFF2

  This routine opens simulatenously on logical units LU1,LU2 a response matrix (a floating point XAS image file) with VOS name FILENAME and its associated histogram (the associated histogram is a 1-d XAS image file, containing the input energy grid, and whose name is stored in a keyword in the matrix header). It returns the matrix size SIZEX,SIZEY and the zero-record offsets IZOFF1,IZOFF2 to be passed to other calls like read_image to actually read the matrix and histogram.

  ---

• open_new_xas_file

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_NEW_XAS_FILE(lu,file,type,recl,nrec,xasno,zoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILE
  	CHARACTER*(*)	TYPE
  	INTEGER	RECL
  	INTEGER	NREC
  	INTEGER	XASNO
  	INTEGER	ZOFF

  This routine (normally not called by users, which use the higher level type-specific "create" routines like create_image) creates (associating it with logical unit LU) a new XAS file of name FILE and given TYPE with NREC data records of record length of RECL bytes (the number of actual records is larger, since it includes the header and mini-header). It returns the XAS file number XASNO and the zero-offset record ZOFF after which data can be written.
  Recognised file types are :
  • 'FLO' for normal real images,
  • 'INT' for normal integer images (deperecated)
  • 'MAT' for response matrix images
  • 'SPE' for spectra (binary tables)
  • 'TIM' for time profiles (binary tables)
  • 'PHO' for photon files (binary tables)
  • 'GEN' for generic binary tables

• open_old_xas_file

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_OLD_XAS_FILE(lu,file,type,recl,nrec,xasno,zoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILE
  	CHARACTER*(*)	TYPE
  	INTEGER	RECL
  	INTEGER	NREC
  	INTEGER	XASNO
  	INTEGER	ZOFF

  This routine (normally not called by users, which use the higher level type-specific "open" routines like open_image or open_photon) opens (associating it with logical unit LU) an existing XAS file of name FILE, returning its TYPE, the number of data records NREC records, and the record length of RECL bytes. It returns also the XAS file number XASNO and the zero-offset record ZOFF after which data can be written.
  Note that the syntax (except for the argument intent) is identical to the one of open_new_xas_file to which one is referred (except that any non-matrix image is returned as TYPE='IMG').

  ---

• open_photon

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_PHOTON(lu,filename,recl,nbins,nfields,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	RECL
  	INTEGER	NBINS
  	INTEGER	NFIELDS
  	INTEGER	IZOFF

  This routine opens an existing XAS photon list file with VOS name FILENAME using logical unit LU. It returns the number of photons NBINS, the number of data fields (columns) per event NFIELDS, the record length RECL in bytes, and the zero-record offset IZOFF to be passed to other calls like read_bin. It also loads a table descriptor according to the characteristics of the table columns (fields), in the order in which they appear, ignoring any unnamed physical column (TTYPE blank) which is used for pad columns.

  ---

• open_spectrum

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_SPECTRUM(lu,filename,recl,nbins,nfields,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	RECL
  	INTEGER	NBINS
  	INTEGER	NFIELDS
  	INTEGER	IZOFF

  This routine opens an existing XAS spectrum file with VOS name FILENAME using logical unit LU. It returns the number of channels NBINS, the number of data fields (columns) NFIELDS (usually 4), the record length RECL in bytes, and the zero-record offset IZOFF to be passed to other calls like read_bin or used to read the records directly. It also loads a table descriptor according to the characteristics of the table columns (fields), only for the 4 columns with canonic names in a spectrum.

  ---

• open_time

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_TIME(lu,filename,recl,nbins,nfields,izoff)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	FILENAME
  	INTEGER	RECL
  	INTEGER	NBINS
  	INTEGER	NFIELDS
  	INTEGER	IZOFF

  This routine opens an existing XAS time profile (light curve file) with VOS name FILENAME using logical unit LU. It returns the number of time bins NBINS, the number of data fields (columns) per bin NFIELDS, the record length RECL in bytes, and the zero-record offset IZOFF to be passed to other calls like read_bin. It also loads a table descriptor according to the characteristics of the table columns (fields), assigning logical column numbers only for the those columns actually present whose name is one of the canonic names in a light curve (or in unofficially supported folded light curves).

  ---

• open_xas_ascii

  Library	xaslib	Fortran code
  Calling sequence	CALL OPEN_XAS_ASCII(LU,NAME,NROW,NCOL)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	NAME
  	INTEGER	NROW
  	INTEGER	NCOL

  This routine opens an existing "XAS ASCII" tabular file of given NAME on logical unit LU. Such file is just a plain ASCII file with NROW records with NCOL numeric columns, preceded by as many as wished nh header records in free format, preceded by a single pseudo-miniheader line in the form XAS1ASC2GEN31234 nh nrow ncol. The routine skips the nh+1 header records and stays positioned for reading the first data record, at the same time returning NROW and NCOL.

  There is instead no explicit routine interface to create new "XAS ASCII" tabular files.

  ---

• openwindow

  Library	xaslib	Fortran code
  Calling sequence	CALL OPENWINDOW(LU,NAME,N)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	NAME
  	INTEGER	N

  Category: time window
  This routine is used to open a timewindow file with given NAME on logical unit LU before calling loadwindow. The routine does a consistency format check on the content of each time window. It returns the number of timewindows N or N=0 in case of any error.

  ---

• pad_table

  Library	xaslib	Fortran code
  Calling sequence	CALL PAD_TABLE(TABLE,PADCOL,PADDED)
  Arguments	INTEGER	TABLE
  	INTEGER	PADCOL
  	LOGICAL	PADDED

  This service routine shall be called during creation of new XAS binary table files, to ensure that the record length is padded to a multiple of 4 bytes (constraint imposed for Fortran direct access support on Digital systems). One passes the XAS file number TABLE, and the number of a non-existing free column PADCOL (i.e. the first unused column). The routine reads the table descriptor, adds the column sizes to verify the toal size is a multiple of 4 bytes, and if not adds to the descriptor a pad column of type 1B, 2B or 3B as appropriate. It returns a logical flag PADDED=.TRUE. if the pad column has been added.

  ---

• pipeexist

  Library	xaslib	Fortran code
  Calling sequence	IF( PIPEEXIST(pipe) ) THEN ..
  Arguments	CHARACTER*(*)	PIPE

  This logical function is a convenience utility front end to the VOS z_channel routine to test the existence of a named communication channel PIPE.

  ---

• pktcap_load

  Library	xaslib	Fortran code
  Calling sequence	CALL PKTCAP_LOAD(SATELLITE,INSTRUMENT,MODE,PACKET)
  Arguments	CHARACTER*(*)	SATELLITE
  	CHARACTER*(*)	INSTRUMENT
  	CHARACTER*(*)	MODE
  	CHARACTER*(*)	PACKET

  Category: accumulation support
  This routine is a mission-independent way to load mission-specific information about a named telemetry PACKET. It opens the appropriate packetcap file, whose name is built according to SATELLITE, INSTRUMENT and MODE (typically one of 'DIR'|'INDIR'|'HK'), and which is located in the appropriate calibration directory.

  Side effect:loads in COMMON block PKCOMMON the entire reconstructed content of the packetcap entry for the named PACKET, inclusive of the resolution of any tc reference (similar tp termcap tc capabilities).

  ---

• pktcap_lookup

  Library	xaslib	Fortran code
  Calling sequence	CALL PKTCAP_LOOKUP(FIELD,TYPE,IVAL,STRVAL,FOUND)
  Arguments	CHARACTER*(*)	FIELD
  	INTEGER	TYPE
  	INTEGER	IVAL
  	CHARACTER*(*)	STRVAL
  	LOGICAL	FOUND

  Category: accumulation support
  This routine scans the packetcap entry currently loaded in memory by the last call to pktcap_load for a named FIELD. It returns a TYPE which can be :
  • 0 for a boolean field, in which case FOUND=.TRUE. means the field is set.
  • 1 for a numeric field, in which case the field value is in IVAL
  • 2 for a string field, in which case the field value is in STRVAL
  • -1 in case of errors

  ---

• preparse

  Library	xaslib	Fortran code
  Calling sequence	CHARACTER*(*+2) OUT=PREPARSE(STRING)
  Arguments	CHARACTER*(*)	STRING

  Category: user interface
  This function is widely used after a call to x_read which returns an argument STRING containing one or more blank or comma separated character items. It parses a string of the form AAA,BBB,CCC or AAA BBB CCC returning the corresponding string 'AAA','BBB','CCC' / which is suitable for list-directed reading.
  The receiving variable OUT shall have enough space to contain the expanded value. It is customary to allocate at least two characters more (at least for the blank-slash list-directed terminator added at the end).

  ---

• read_bin

  Library	xaslib	Fortran code
  Calling sequence	CALL READ_BIN(LU,IREC,IZOFF,F1,F2,F3,F4,F5,F6,F7)
  Arguments	INTEGER	LU
  	INTEGER	IREC
  	INTEGER	IZOFF
  	any*4	F1(*),F2(*),F3(*),F4(*),F5(*),F6(*),F7(*)

  Category: binary tables
  This routine reads a generic data record at position IREC (after the zero-offset IZOFF passed by the file opening routine) from the binary table open on logical unit LU. The Fi arguments can be scalar or arrays of any numeric data type, as appropriate according to the type and depth of the corresponding column in the table. All seven variables shall be supplied (seven is the maximum number of columns in a table, if more are required the code shall be recompiled !) but those unused may point to a dummy variable. Only logical columns marked as present in the table descriptor will be returned a value.
  Note that byte and 16-bit columns are always returned in 32-bit INTEGER Fi.

  ---

• read_image

  Library	xaslib	Fortran code
  Calling sequence	CALL READ_IMAGE(lu,array,sizex,sizey,nx,ny,izoff)
  Arguments	INTEGER	LU
  	REAL	ARRAY
  	INTEGER	SIZEX,SIZEY
  	INTEGER	NX,NY
  	INTEGER	IZOFF

  This routine reads an entire XAS image file opened on logical unit LU by open_image which has also passed the zero-offset record IZOFF. It fills an image of logical sizes SIZEX,SIZEY taking it from the array ARRAY of physical sizes NX,NY (the distinction hardly matters if one uses dynamic memory allocation).
  The routine supports only REAL*4 floating point images (other deprecated types can be dealt with by the user directly in Fortran).

  ---

• satpointing

  Library	xaslib	Fortran code
  Calling sequence	CALL SATPOINTING(RA,DEC,ROLL)
  Arguments	DOUBLE PRECISION	RA,DEC,ROLL

  Category: attitude
  This routine returns in radians the satellite pointing coordinates RA,DEC and ROLL angle. If they are present in the current image file header, it just returns them, otherwise asks the user.

  ---

• set_table_desc

  Library	xaslib	Fortran code
  Calling sequence	CALL SET_TABLE_DESC(table,column,offset,bitpix,dimens)
  Arguments	INTEGER	TABLE
  	INTEGER	COLUMN
  	INTEGER	OFFSET,BITPIX,DIMENS

  Category: binary table support
  This routines saves the characteristics (i.e. the physical column number OFFSET, the bit width in FITS syntaxBITPIX and the depth or dimensionality DIMENS) of the column at logical number COLUMN of the binary table file with XAS file number tt>TABLE into a descriptor in the BINCOMMON common block.

  ---

• skytoxy

  Library	xaslib	Fortran code
  Calling sequence	CALL SKYTOXY(TRA,TDEC,ZRA,ZDEC,ZROLL,X,Y)
  Arguments	DOUBLE PRECISION	TRA,TDEC
  	DOUBLE PRECISION	ZRA,ZDEC,ZROLL
  	DOUBLE PRECISION	X,Y

  Category: attitude
  This routine receives (in radians) the celestial coordinates of an object TRA,TDEC and a (detector) attitude ZRA,ZDEC,ZROLL and returns the X,Y coordinates in mm on the focal plane (pixelization is left to the user).
  It firsts converts in gnomonic angular coordinates, then rotates them by the roll angle, and then use the platescale to convert into mm.

  ---

• time_constants_setup

  Library	xaslib	Fortran code
  Calling sequence	CALL TIME_CONSTANTS_SETUP(SCLSB)
  Arguments	INTEGER	SCLSB

  Category: accumulation support
  This routine prepares all quantity necessary for conversion between on board times and meaningful time units (default is seconds, but can be controlled by the timeunits environment variable). Two kind of on board times are dealt with, those in current packet units (whose time resolution is derived internally via a packetcap lookup of the tr field), and those in spacecraft units (whose time resolution is derived by the SCLSB argument (negative, e.g. -16) as 2^SCLSB s) Side effects: stores relevant values in TIMECOMMON
  

  ---

• trimroot

  Library

  xaslib

  Fortran code

  Unsupported (variant of depath ?)

  ---

• update_start_end

  Library	xaslib	Fortran code
  Calling sequence	CALL UPDATE_START_END

  Category: keyword header support
  This routine is called by accumulation program just before writing the HISTORY keyword, to write in the HISTORY the correct start and end times, whose values in COMMON may have been altered during the processing.

  ---

• voserror

  Library	xaslib	Fortran code
  Calling sequence	IF( VOSERROR (ivoserr,isyserr) ) THEN ...
  Arguments	INTEGER	IVOSERR
  	INTEGER	ISYSERR

  This logical function shall be called after each routine which sets a standard error code in VOSCOMMON to branch to an error message or handler in case of error (returns .TRUE. if error occurred). It also returns (extracting it from the common block) the standard (VOS) error code IVOSERR and the corresponding system-dependent code ISYSERR.
  VOS error codes can be looked at in the error code listings.

  ---

• write_bin

  Library	xaslib	Fortran code
  Calling sequence	CALL WRITE_BIN(LU,IREC,IZOFF,F1,F2,F3,F4,F5,F6,F7)
  Arguments	INTEGER	LU
  	INTEGER	IREC
  	INTEGER	IZOFF
  	any*4	F1(*),F2(*),F3(*),F4(*),F5(*),F6(*),F7(*)

  Category: binary tables
  This routine writes a generic data record at position IREC (after the zero-offset IZOFF passed by the file opening routine) into the binary table open on logical unit LU. The Fi arguments can be scalar or arrays as explained for read_bin. Only logical columns marked as present in the table descriptor will be written.
  Note that byte and 16-bit columns are converted care of this routine from 32-bit INTEGER Fi.

  ---

• x_prompt

  Library	xaslib	Fortran code
  Calling sequence	CALL X_PROMPT(string,k)
  Arguments	CHARACTER*(*)	STRING
  	INTEGER	K

  Category: user interface
  This routine is a replacement for the WRITE(*,*)'prompt' idiom to write a terminal prompt. Note that prompts are always echoed to the terminal even if the input is taken from command file or run string arguments, unless the environment variable echo disables it.
  The prompt is passed in STRING and issued without advancing to the next line so that the reply will be on the same line, starting at column K (or immediately after the prompt if K=0). The idiom is :

  WRITE(BUFFER,*)' Enter your value [df=',I,'] '
  CALL X_PROMPT(BUFFER,0)
  

  ---

• x_read

  Library	xaslib	Fortran code
  Calling sequence	CALL X_READ(npar,mpar,string)
  Arguments	INTEGER	NPAR,MPAR
  	CHARACTER*(*)	STRING

  Category: user interface
  This routine is a replacement for the READ(*,*)values idiom to read an user reply to a terminal prompt. The routine can read from the terminal, from a command file, or from the run string positional parameters as controlled by environment variables TBD REF). The user can ask for MPAR parameters (usually 1) asking at a specific position NPAR (or just the next parameter if NPAR=0) and the routine returns the parameters in STRING.
  STRING is suitable for list-directed i/o for numeric values, but must be preparsed for list-directed i/o for string values, specially for multiple strings, which are also allowed, according to the following idioms :

  CALL X_PROMPT('Enter one integer and two reals ',0)
  CALL X_READ(0,3,BUFFER)
  READ(BUFFER,*)I,R1,R2
  
  CALL X_PROMPT('Enter filename ',0)
  CALL X_READ(0,1,BUFFER)
  BUFFER2=PREPARSE(BUFFER)
  READ(BUFFER2,*)NAME
  
  CALL X_PROMPT('Enter two strings ',0)
  CALL X_READ(0,2,BUFFER)
  BUFFER2=PREPARSE(BUFFER)
  READ(BUFFER2,*)STRING1,STRING2
  

  ---

• xasmatout

  Library	xaslib	Fortran code
  Calling sequence	CALL XASMATOUT(LU1,LU2,NAME,RMF,ELOW,EUP,NEBN,NEOUT)
  Arguments	INTEGER	LU1,LU2
  	CHARACTER*(*)	NAME
  	REAL	RMF(NEBN,NEOUT)
  	REAL	ELOW(NEBN),EUP(NEBN)
  	INTEGER	NEBN,NEOUT

  This utility routine writes a XAS response matrix RMF into a .mat file named NAME. It uses two logical units LU1,LU2, where the second is for the associated histogram file which contains the middle points of the energy grid (i.e. the mean of the low and upper bounds ELOW and EUPP). Both files are written via create_image
  NEBN is the number of input energies, while NEOUT is the number of PHA channels.

  ---

• xytosky

  Library	xaslib	Fortran code
  Calling sequence	CALL XYTOSKY(X,Y,ZRA,ZDEC,ZROLL,TRA,TDEC)
  Arguments	DOUBLE PRECISION	X,Y
  	DOUBLE PRECISION	ZRA,ZDEC,ZROLL
  	DOUBLE PRECISION	TRA,TDEC

  Category: attitude
  This routine receives the X,Y coordinates in mm of point on the focal plane (de-pixelization is left to the user) and a (detector) attitude ZRA,ZDEC,ZROLL (in radians) and returns the celestial coordinates of an object TRA,TDEC (also in radians).

  ---

• zx_get_parameter

  Library	xaslib	Fortran code
  Calling sequence	CALL ZX_GET_PARAMETER(npar,string,length)
  Arguments	INTEGER	NPAR
  	CHARACTER*(*)	STRING
  	INTEGER	LENGTH

  ---

  Category: user interface
  This routine is not normally called by users, which use x_read (which calls this) instead (unless they need specific repeated access to a positional parameter on the runstring and are really sure of what they do). The routine retrieves (from runstring, command file or terminal) a single parameter at position NPAR into STRING. It also returns the LENGTH of the string (or zero if the parameter is not present).

[Previous][Next] [Up][Down]