5. XAS libraries

This section provides an index of XAS library routines in alphabetic order and by subject, which point to the appropriate syntax description in the relevant library section (XAS libraries are listed also in section 2.7).

Note that in the following sections a consistent notation and color code is used for routine synopsis, with a table entry like the following :

Library list

library namepurpose
fotlib routines specifically used to access SAX telemetry on Final Observation Tapes
general general purpose routines (e.g time-and-date, byteswap etc.)
graphserv low level library for the graphics servers, and the relevant clients
hpgslib routines specific of the SAX HPGSPC instrument
lecslib routines specific of the SAX LECS instrument (unofficially supported)
mecslib routines specific of the SAX MECS instrument
pdslib routines specific of the SAX PDS instrument
vos system dependent routines
xasgraph high level graphics library
xaslib routines independent of SAX data formats, but specific to handle mission-independent XAS data files and features

Routine alphabetic list

A abs_co_be
add_end add_file add_init add_rew_tape add_skip_tape
addhistory
alum
annotate_new annotate_old
area_mr
askbin asktime
B bewin_trasp
bindex
bit_init_handle
blkbincommon blkctxcommon blkhcommon blkpipecommon blksyscommon blkxrcommon
blrng blsel
broad2 buf_read
buildpath
C check_overtrace check_packet checkerr
close_xas_file
coda cofas
collapse
config_read
connectserver conversion_needed copy_table_desc
correct
cpuclk
create_image create_photon create_spectrum create_time
cross_sec
curft
D decodetform
depath depath_1
deregister
detpointing
df_axes df_pen_colours df_viewport df_window
dotproduct
E e2fwhm
edit_cmd
effmed
ein eout escape
exposure_b1s1 exposure_b1s3
extrp extrpd
F f2x
fchi fder
filecorr_read fileinp_read fopen_rmf fopen_rmf
free_lu
fuga fuga_1
G gas_cell
get_datastyle get_global_default get_obs_chain get_start_end get_table_desc
getmisalign gnomonic
H h_add_keyword h_copy_all_header h_current_file h_find_keyword h_flush_header
h_flush_minih h_load_header h_load_minih h_modify_keyword h_next_keyword
h_read_keyword h_update_datasize
hexi4
hp_gain_time hp_keywords hpcorrect
I init_correct init_correct_hp init_correct_le init_correct_me init_correct_me_fast init_correct_pds
init_timewindow
inst_key_copy inst_key_find inst_key_flush inst_key_load inst_key_mult inst_key_read inst_key_set
instr_keywords instrument_keys
interpolate
isregistered
J julia
K kapton2
L lb_axis lb_number lb_tics
le_gain_time lecs_keywords lecscorrect
leftnumber
lexan
lintomm
loadwindow
lowcase
M maketform
matproduct
me_gain_time me_init_map mecs_arf mecs_keywords mecs_matkeywords mecs_rmf mecscorrect
misalign mmtopix
mtinv
multiply_rmfarf
N nice_axes nicer_lin_axes nicer_log_axes
no_keyword
O open_image open_matrix
open_new_xas_file open_old_xas_file
open_photon open_spectrum open_time
open_xas_ascii
openwindow
P pad_table
parameter
pds_arf pds_ein pds_en_resol pds_fotunits pds_freq
pds_keywords pds_matinfo pds_matkeywords pds_matout pds_ogip
pds_opnrmf pds_response pds_wrtrmf pds_wrtrmfebo pds_wrtrmfmat
pdscorrect pdsmat_coef pdsmat_init
pipeexist
pktcap_load pktcap_lookup
plot_xxy_bar plot_xxy_histo plot_xxy_join plot_xy_join
poly poly_carbo
preparse
psf_mir psf_rad
Q
R radecroll
ran1
read_bin read_image
reader reader_1
rearrange_instrec
register
rminmax
S satpointing
sax_acc_b1s1_i sax_acc_b1s1_y sax_acc_b1s2_i sax_acc_b1s2_y sax_acc_b1s3_y sax_acc_b2s1_y
sax_acc_b3s1 sax_acc_b3s2 sax_acc_b3s3 sax_acc_b3s4 sax_acc_b3s5 sax_acc_b3s6
sax_acc_bt_1 sax_acc_bt_2 sax_acc_bt_3
sax_acc_hkrange sax_acc_loop
sax_acc_open_sc_tlm sax_acc_open_tlm
sax_acc_other_range sax_acc_preload sax_acc_range sax_acc_select
sax_df_keywords sax_froot_name sax_open_dir
sax_pcf_load sax_pcf_lookup
sax_pktcap_load
sax_which_data
set_table_desc
shell_fact shell_prob
skytoxy
spread
swapi2 swapi4 swapr8
T tapechar
tetafi_xy
time_1970 time_70s2mjd time_a2mjd time_array time_ascii time_cldj
time_constants_setup
timebin_b1s1
tmed
tofits toqdp
trimroot
true_length
U udouble
unlintomm
upcase
update_start_end
V voserror
W winbe
write_arf write_arf
write_bin
write_rmf write_rmf_ebo write_rmf_ebo write_rmf_mat write_rmf_mat
X x_echo x_echo_error x_prompt x_read
xasmatout
xdofit
xytosky
Y y_clear_viewport y_closeplot y_colour y_coordinates
y_draw y_fill y_get_cursor
y_lines y_move y_openplot
y_page y_readlut y_scale y_text
y_viewport y_width y_window y_write_image y_writelut
Z z_alloc z_aux_envfile
z_break z_channel z_close_stream
z_dealloc z_delete_file z_dieee_to_vms z_dvms_to_ieee
z_exit z_fullname
z_get_command z_get_global z_hostname
z_ieee_to_vms z_initenv z_inquire z_logintime
z_op_sys z_open z_open_stream z_print_file z_read_stream z_rename_file z_run
z_schedule z_seek_stream z_set_global z_spawn z_sys_name z_syserror
z_tape_open z_terminal z_ttyname z_username
z_vms_to_ieee z_write_stream
zc_alloc zc_break zc_cuserid zc_dtime
zc_execvp zc_fclose zc_fopen zc_fork zc_fread zc_free zc_fseek zc_fwrite
zc_getdomainname zc_getenv zc_gethostname
zc_memcpy zc_mknod zc_putenv zc_pwnam
zc_rename zc_stat zc_system
zc_terminal zc_time zc_ttyname zc_unlink zx_get_parameter

Routine subject list

You can locate a routine by subject using the following lookup table. A routine may eventually appear in more than one category. Routines in a category are grouped by further subject, and finally in alphabetic order.

Routines which are similar, or are called exclusively one by another, are listed side by side.

General [files] [type conversion] [string manipulation] [time] [user i/f] [environment] [miscellanea] [initialization]
System [memory] [pipes] [process control] [misc high level VOS] [misc low level VOS] [environment]
XAS file format [files] [binary tables] [keywords]
XAS miscellanea [time window] [attitude]
Graphics [server communication] [high level] [low level]
SAX specific stuff [FOT tape] [FOT telemetry] [support] [accumulation]
SAX instruments
MECS [calibration parameters] [matrix support] [accumulation]
LECS [everything together] NB : unofficially supported
PDS [everything together] NB : code by ITESRE, no full support by the author
HPGSPC [everything together] NB : most code by IFCAI, no full support by the author ; rest of code unofficially supported

general file access

These routines shall be used to deal with generic files (in replacement of the standard Fortran OPEN and INQUIRE calls). Note that for the majority of data files one uses the XAS file routines (which in turn call these as underlying layer).

file opening assign logical unit free_lu
convert sys to VOS filename z_sys_name
open generic file z_open
open ASCII table open_xas_ascii
error handling VOS errors voserror
Fortran errors z_syserror
file status (INQUIRE) z_inquire zc_stat
file handling delete z_delete_file zc_unlink
rename z_rename_file zc_rename

Data type conversion support

XAS data is kept in native binary format. However some programs must (or are capable to) deal with data in foreign binary format. These routines are used to assist in the conversion.

preliminaries operating system identification z_op_sys blksyscommon
identify required conversion conversion_needed
actual conversion IEEE to VMS and v.v. z_ieee_to_vms z_vms_to_ieee z_dieee_to_vms z_dvms_to_ieee
byte swapping (little-big endian and v.v.) swapi2 swapi4 swapr8
miscellanea unsigned DOUBLE PRECISION udouble
hex formatting hexi4

General string manipulation

string length without trailing blanks true_length
remove multiple blanks collapse
smart replacement for INDEX bindex
Case conversion lowcase upcase
unsupported ? trimroot

General date and time handling

time conversion time array to Unix time_1970
Unix to time array time_array
Unix to string time_ascii
System times current time zc_time
time of login z_logintime
Unsupported HPGSPC routines time_70s2mjd time_a2mjd time_cldj

User interface

These routines are used to enforce the XAS user interface reading from standard input, run string or command file. They shall be used as replacement for the WRITE(*,'prompt') and READ(*,*) Fortran idioms.

Basic routines issue prompt x_prompt
read reply x_read
parse string arrays preparse
Low level routines retrieve and parse run string z_get_command zx_get_parameter blkxrcommon
Unsupported PDS routines x_echo x_echo_error

Environment access

These routines are used to access XAS environment variables. The technical implementation of such variables is system dependent : XAS environment variables are accessed without the XAS_ prefix. The system, searching for var looks first for XAS_var, but falls back to the system variable var if not found (system variables are however readonly for what XAS programs are concerned).

Get variable value get_global_default z_get_global zc_getenv
Set variable value z_set_global zc_putenv
Service routines (Unix) z_aux_envfile
z_initenv

General miscellanea

CURFIT fitting package curft fchi fder mtinv
interpolation extrp extrpd interpolate
matrix/vector operations dotproduct matproduct
Random number generator ran1
Bit array handling bit_init_handle

Block data initialization

These BLOCK DATA routines are used/referred to initialize some specific common blocks, described in the include file section.

Binary table descriptors blkbincommon
Current context blkctxcommon
XAS file buffers blkhcommon
for communication channels blkpipecommon
For data conversion blksyscommon
For user interface blkxrcommon

VOS memory allocation

routines are used to allow dynamic memory allocation in f77. z_alloc z_dealloc zc_alloc zc_free

VOS communication channel support

Communication channels are used to allow interprocess communication, typically for graphics servers. The implementation is system dependent :

create/open/delete channel z_channel zc_mknod z_open_stream zc_fopen
close channel z_close_stream zc_fclose
input/output routines z_read_stream zc_fread z_write_stream zc_fwrite
unsupported z_seek_stream zc_fseek

VOS process control

These routines are used either to control the current process, or to generate a new process.

terminate (replaces Fortran STOP) z_exit
Handle interrupt (control-C) z_break zc_break
Chain another process (overlay) z_run zc_execvp
Schedule process in background (no wait) z_spawn zc_fork
Schedule process with wait z_schedule zc_system

VOS misc high level calls

The VOS library groups all system dependent calls. Those which are not listed elsewhere are listed here, limiting however to the routines which are called by user programs directly.

Error handling voserror
Query functions user name (GECOS and account) z_fullname z_username
hostname z_hostname
time of login z_logintime
terminal name and characteristics z_terminal z_ttyname
Debugging utilities checkerr cpuclk
Unsupported (used by non XAS programs) z_print_file z_tape_open

VOS misc low level calls

These are all C routines and all (with one exception) required on Unix only as underlying layer to the VOS high level calls.

support to query calls zc_cuserid zc_getdomainname zc_gethostname zc_pwnam zc_terminal zc_ttyname
miscellanea zc_dtime zc_memcpy

XAS file support

XAS (mission-independent) format data files are accessed via dedicated routines. We list here the general or generic ones, leaving out those related to tabular files and those used for the (common) XAS file header

Path related routines locate path for file buildpath
strip path from filename depath depath_1
generic XAS file create/open open_new_xas_file open_old_xas_file
close close_xas_file
image format files generic images create_image open_image read_image
Response matrices open_matrix
xasmatout

XAS binary table support

Spectra, time profiles and photon lists are XAS files sharing a common tabular format. The related routines are listed here.

file opening creation of new file create_photon create_spectrum create_time
existing file open_photon open_spectrum open_time
read/write a generic record read_bin write_bin
preliminaries handling table descriptors copy_table_desc get_table_desc set_table_desc
space for dummy columns pad_table
service routines for FITS-like TFORM keywords decodetform leftnumber maketform

XAS file header and keyword handling

All XAS file share a common header format, composed of named binary keywords. There are high level routines to manipulate keywords, and low level service ones.

user routines add and format HISTORY keyword addhistory
add/modify keyword h_add_keyword h_modify_keyword
read keyword value h_read_keyword
copy entire header h_copy_all_header
if file size changed h_update_datasize
service routines point to different file h_current_file
load header from disk h_load_header h_load_minih
flush header to disk h_flush_header
h_flush_minih
Keyword seek support h_find_keyword h_next_keyword

Accumulation : time window management

XAS accumulation program are mission dependent (although this is hidden under a mission-independent interface). They however use a common (mission-independent) concept of time windows, therefore the relevant routines are listed here.

prepare to open time window file init_timewindow
open time window file openwindow
read time window file loadwindow

Attitude handling

These routines are designed in a mission-independent way, but are used only by unofficial programs using celestial coordinates

Determine pointing get detector pointing detpointing
get spacecraft pointing satpointing
get/apply misalignments getmisalign misalign
Eulker matrix to sky coordinates radecroll
Coordinate conversion Pixel to mm and v.v. lintomm unlintomm mmtopix
Sky to pixel and v.v. skytoxy xytosky gnomonic

Graphics server (communication)

A graphics server has to be created, and communication has to be set up over a communication channel from server and client sides.

Connection establishment connectserver
verify channel existence pipeexist
server registration isregistered register
deregister
Xlib interface for X window server f2x

High level graphics

This set of routines correspond to relatively complex graphics functions implemented in graphics clients.

plot annotations (two styles) annotate_new annotate_old
Default arrangements axis frame with annotations df_axes
pen colours df_pen_colours
plotting window and viewport df_viewport df_window
Setup from environment clear screen on overtrace check_overtrace
plot style (solid, error bars etc.) get_datastyle
Axis frames labelling routines lb_axis lb_number lb_tics
various axis styles nice_axes nicer_lin_axes nicer_log_axes
Data array plotting various forms plot_xxy_bar plot_xxy_histo plot_xxy_join plot_xy_join

Low level graphics

These routines are implemented at device independent level and send standard opcodes (with operands) on a communication channel to a graphics server (and eventually receive replies).

Establish communication (or close) y_openplot y_closeplot
set up viewport and window y_clear_viewport y_viewport y_window y_page
reference frame y_coordinates y_scale
look and style y_colour y_text y_width
Plotting primitives vector y_draw y_move y_lines
text y_text
image and 2-d y_fill y_readlut y_write_image y_writelut
graphics input y_get_cursor y_readlut

FOT tape access

There is no intrinsic (system and device-dependent) tape handling in XAS. SAX FOT tapes are dealt with via system-specific shell scripts which are generated based on a template file (which can be customized locally) which contains template commands which are adjusted by the following routines.

service functions load template tapechar
begin and end operations add_init add_end
edit template command edit_cmd
handle specific commands file copy add_file
tape functions add_rew_tape add_skip_tape

FOT (telemetry) data reading

SAX data is in form of (FOT reformatted) telemetry data files, or other auxiliary files assimilated to them. This family of low level routines deals with telemetry records (or events in a record) themselves, and are called at a bottom of a sequence of higher level routines by the accumulation programs.
The low level routine may call a front end correction routine (which in turn calls further instrument specific corrections), and do call an instrument-independent "increment routine" which depends on the XAS data type being accumulated.

basic type switching 1 direct mode data (events)
2 indirect (spectra)
3 Housekeeping		 sax_acc_bt_1
sax_acc_bt_2
sax_acc_bt_3
specific type handling 1 direct event handling sax_acc_b1s1_i sax_acc_b1s1_y sax_acc_b1s2_i sax_acc_b1s2_y sax_acc_b1s3_y
exposure computation exposure_b1s1 exposure_b1s3 timebin_b1s1
instrument dep. event correction correct
2 indirect sax_acc_b2s1_y
3 Housekeeping sax_acc_b3s1 sax_acc_b3s2 sax_acc_b3s3 sax_acc_b3s4 sax_acc_b3s5 sax_acc_b3s6
instrument directory record decoding rearrange_instrec

Telemetry data reading support

Accumulation program are mission specific, but try to be as mission-independent and instrument-dependent as possible using external packetcap files to describe the content of telemetry packets and dispatching to the above low level routines according to such description.

which packets are available ? check_packet
load packet info mission-independent i/f pktcap_load pktcap_lookup
SAX specific i/f sax_pktcap_load
HK parameter info similar to above sax_pcf_load sax_pcf_lookup
Open files instrument telemetry sax_acc_open_tlm
spacecraft telemetry sax_acc_open_sc_tlm
directory information sax_open_dir
dispatcher to packet specific routines sax_acc_loop

Accumulation program setup (user dialogue)

The accumulation programs must ask the user about the choice of limits for the accumulation, based on the content and layout of telemetry packets, and also perform other initializations.

operator dialogue choose packet type sax_which_data
load packetcap information sax_acc_preload
select fields and ranges sax_acc_select sax_acc_hkrange sax_acc_other_range sax_acc_range
time profile binning askbin asktime
initializations spacecraft to XAS time time_constants_setup get_start_end update_start_end
obaervation chain get_obs_chain
instrument dep. corrections init_correct
XAS keywords in output instr_keywords sax_df_keywords

MECS calibration parameters

SAX MECS specific routines are presented in a detailed breakdown. A first class is represented by the routines accessing calibration parameters, used mainly for response matrix generation, but not only (e.g. they are also used for the WWW MECS guided tour)

Mirror system area_mr psf_mir psf_rad
Windows and filter incl. materials abs_co_be bewin_trasp alum kapton2 lexan poly poly_carbo
Detector components coda cross_sec escape gas_cell spread

MECS matrix generation support

The MECS matrix generation programs (besides the above "physical" routines) includes some specific service routines.

parameter choices blsel ein eout
service computations mecs_arf mecs_rmf multiply_rmfarf tetafi_xy
Output to XAS or OGIP fopen_rmf mecs_matkeywords write_arf write_rmf write_rmf_ebo write_rmf_mat

MECS data accumulation

Data accumulation programs call instrument specific routines for event corrections, or to add instrument specific keywords to the output files.

corrections init_correct_me init_correct_me_fast me_gain_time me_init_map mecscorrect
keywords mecs_keywords

PDS support

PDS support routines have been written at ITESRE and are unsupported by the author of this document. No detail is given so far.

pds_arf pds_ein pds_en_resol pds_matinfo pds_matkeywords pds_matout pds_ogip pds_opnrmf pds_response pds_wrtrmf pds_wrtrmfebo pds_wrtrmfmat pdsmat_coef pdsmat_init pds_freq
init_correct_pds pdscorrect
inst_key_copy inst_key_find inst_key_flush inst_key_load inst_key_mult inst_key_read inst_key_set
instrument_keys no_keyword pds_keywords
pds_fotunits rminmax sax_froot_name xdofit

LECS support

LECS support is unofficial. The routines below were either been written by the author mimicking the MECS arrangement, or were adapted from SSD routines.

adapted from SSD blrng e2fwhm
MECS-style corrections lecscorrect init_correct_le le_gain_time lecs_keywords

HPGSPC support

HPGSPC is partially unofficial supported by the author, mimicking the MECS arrangement. However most of the routines here were written at IFCAI for the original release of HPGSPC software (and their status of support is unknown).

supplied by IFCAI broad2 cofas fuga fuga_1 shell_fact shell_prob winbe
fopen_rmf reader reader_1 write_arf write_rmf_ebo write_rmf_mat
effmed filecorr_read fileinp_read parameter tmed tofits
buf_read config_read julia toqdp
MECS-style corrections init_correct_hp hpcorrect hp_gain_time hp_keywords

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

sax.iasf-milano.inaf.it/Xashelp/Prog/lib.html :: original creation 2002 Sep 04 18:22:37 CEST :: last edit 2002 Sep 04 18:22:37 CEST