Extended IDL Help
This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Fri Feb 2 17:44:58 2001.
List of Routines
Routine Descriptions
DBBUILD
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBBUILD
Purpose :
Build a database by appending new values for every item.
Explanation :
Build a database by appending new values for every item. The database
must be opened for update (with DBOPEN) before calling DBBUILD.
Use :
dbbuild, [ v1, v2, v3, v4......v25, NOINDEX = ]
EXAMPLE: Suppose a database named STARS contains the four items
NAME,RA,DEC, and FLUX. Assume that one already has the four vectors
containing the values, and that the database definition (.DBD) file
already exists.
IDL> !PRIV=2 ;Writing to database requires !PRIV=2
IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file
IDL> dbopen,'stars',1 ;Open database for update
IDL> dbbuild,name,ra,dec,flux ;Write 4 vectors into the database
Inputs :
v1,v2....v25 - vectors containing values for all items in the database.
V1 contains values for the first item, V2 for the second, etc.
The number of vectors supplied must equal the number of items
(excluding entry number) in the database. The number of elements
in each vector should be the same. A multiple valued item
should be dimensioned NVALUE by NENTRY, where NVALUE is the number
of values, and NENTRY is the number of entries.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords :
NOINDEX - If this keyword is supplied and non-zero then DBBUILD will
*not* create an indexed file. Useful to save time if
DBBUILD is to be called several times and indexed file need
only be created on the last call
STATUS - Returns a status code denoting whether the operation was
successful (1) or unsuccessful (0). Useful when DBBUILD is
called from within other applications.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, DBCLOSE, DBINDEX, DBWRT, DBXPUT
Common : None.
Restrictions:
Do not call DBCREATE before DBBUILD if you want to append entries to
an existing database
DBBUILD checks that each value vector matches the idl type given in the
database definition (.DBD) file, and that character strings are the
proper length.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
Written W. Landsman March, 1989
Added /NOINDEX keyword W. Landsman November, 1992
User no longer need supply all items W. Landsman December, 1992
Written : W. Landsman, GSFC/UIT, March 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC, 1 April 1994
Added STATUS keyword.
Version : Version 2, 1 April 1994
(See .//dbbuild.pro)
DBCLOSE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBCLOSE
Purpose :
Procedure to close a data base file
Explanation :
Procedure to close a data base file
Use :
dbclose
Inputs : None.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO
Common : DB_COM
Restrictions: None.
Side effects:
The data base files currently opened are closed
Category : Utilities, Database
Prev. Hist. :
version 2 D. Lindler Oct. 1987
For IDL version 2 August 1990
Written : D. Lindler, GSFC/HRS, October 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Version : Version 2, 30 May 1994
(See .//dbclose.pro)
DBCREATE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBCREATE
Purpose :
Create new data base file or modify description.
Explanation :
Create new data base file or modify description. A database
definition file (.dbd) file must already exist.
The default directory must be a ZDBASE: directory.
Use :
dbcreate, name,[ newindex, newdb, maxitems] [,/external]
Inputs :
name- name of the data base (with no qualifier), scalar string.
The description will be read from the file "NAME".dbd
Opt. Inputs :
newindex - if non-zero then a new index file is created,
otherwise it is assumed that changes do not affect the
index file. (default=0)
newdb - if non-zero then a new data base file (.dbf) will
be created. Otherwise changes are assumed not to affect
the file's present format.
maxitems - maximum number of items in data base.
If not supplied then the number of items is
limited to 200.
Outputs : None.
Opt. Outputs: None.
Keywords :
external - If set, then the database is written with an external data
representation. This allows the database files to be used on
any computer platform, e.g. through NFS mounts, but some
overhead is added to reading the files. The default is to
write the data in the native format of the computer being used.
This keyword is only paid attention to if NEWDB and NEWINDEX
are both nonzero. Otherwise, the database is opened to find
out if it uses external representation or not.
Calls : GETLOG, GETTOK, ZPARCHECK
Common : None.
Restrictions:
If newdb=0 is not specified, the changes to the .dbd file can
not alter the length of the records in the data base file.
and may not alter positions of current fields in the file.
permissible changes are:
1) utilization of spares to create a item or field
2) change in field name(s)
3) respecification of index items
4) changes in default print formats
5) change in data base title
6) changes in pointer specification to other data
data bases
!priv must be 2 or greater to execute this routine.
Side effects:
data base description file ZDBASE:name.dbc is created
and optionally ZDBASE:name.dbf (data file) and
ZDBASE.dbx (index file) if it is a new data base.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler OCT, 1987
Modified to work under IDL version 2. M. Greason, STX, June 1990.
Modified to work under Unix D. Neill, ACC, Feb 1991.
Written : D. Lindler, GSFC/HRS, October 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 28 May 1994
Added EXTERNAL keyword.
Version 3, William Thompson, GSFC/CDS (ARC), 29 July 1994
Modified so that EXTERNAL keyword requires both
NEWINDEX and NEWDB to be set.
Version 4, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Version 5, William Thompson, GSFC, 22 December 1994
Incorporated several minor changes made by Wayne
Landsman.
Version : Version 5, 22 December 1994
(See .//dbcreate.pro)
DBDELETE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBDELETE
Purpose :
Deletes specified entries from data base
Explanation :
Deletes specified entries from data base
The procedure is rather slow because the entire database is re-
created with the specified entries deleted.
Use :
DBDELETE, list, [ name ]
EXAMPLE: Delete entries in a database STARS where RA=DEC = 0.0
IDL> !PRIV= 3 ;Set privileges
IDL> dbopen,'STARS',1 ;Open for update
IDL> list = dbfind('ra=0.0,dec=0.0') ;Obtain LIST vector
IDL> dbdelete, list ;Delete specified entries from db
Inputs :
list - list of entries to be deleted, scalar or vector
name - optional name of data base, scalar string. If not specified
then the data base file must be previously opened for update
by DBOPEN.
Opt. Inputs :
Set the non-standard system variable !DEBUG = 2 to obtain
additional diagnostics
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DBCLOSE, DBINDEX, DBOPEN, DBPUT, ZPARCHECK
Common :
DBCOM
Restrictions:
!PRIV must be at least 3 to execute.
Side effects:
The data base file (ZDBASE:name.DBF) is modified by removing the
specified entries and reordering the remaining entry numbers
accordingly (ie. if you delete entry 100, it will be replaced
by entry 101 and the database will contain 1 less entry.
Category : Utilities, Database.
Prev. Hist. :
Version 2 D. Lindler July, 1989
Updated documentation W. Landsman December 1992
Written : D. Lindler, GSFC/HRS, July 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC, 28 February 1995
Fixed bug when external representation used.
Version : Version 2, 28 February 1995
(See .//dbdelete.pro)
DBEDIT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBEDIT
Purpose :
Interactively edit specified fields in a database.
Explanation :
Interactively edit specified fields in a database. The
value of each field is displayed, and the user has the option
of changing or keeping the value. Widgets will be used if they
are available.
(1) Use the cursor and point to the value you want to edit.
(2) Type the new field value over the old field value.
(3) When you are done changing all of the field values for each entry
save the entry to the databases by pressing 'SAVE ENTRY TO DATABASES'.
Here all of the values will be checked to see if they are the correct
data type. If a field value is not of the correct data type, it will
not be saved.
Use the buttons "PREV ENTRY" and "NEXT ENTRY" to move between entry
numbers. You must save each entry before going on to another entry in
order for your changes to be saved.
Pressing "RESET THIS ENTRY" will remove any unsaved changes to the
current entry.
Use :
dbedit, list, [ items ]
EXAMPLE: Suppose one wanted to edit all of the previously unknown moon
angles (assigned a value of -999) the database FRAMES
IDL> !priv=2
IDL> dbopen, 'frames', 1
IDL> list = dbfind( 'moonang = -999.0')
IDL> dbedit, list, 'moonang'
Inputs :
list - scalar or vector of database entry numberss. Set list = 0 to
interactively add a new entry to a database. Set list = -1 to edit
all entries.
Opt. Inputs :
items - list of items to be edited. If omitted, all fields can be
edited.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : DATATYPE, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEDIT_BASIC,
DBINDEX, DBOPEN, DBRD, DBWRT, DBXPUT, DBXVAL, ZPARCHECK
Common :
DB_COM -- contains information about the opened database.
DBW_C -- contains information intrinsic to this program.
Restrictions:
Database must be opened for update prior to running
this program. User must be running DBEDIT from an
account that has write privileges to the databases.
If one is editing an indexed item, then after all edits are complete,
DBINDEX will be called to reindex the entire item. This may
be time consuming.
Side effects:
Will update the database files.
Category : Utilities, Database
Prev. Hist. :
Adapted from Landsman's DBEDIT
added widgets, Melissa Marsh, HSTX, August 1993
do not need to press return after entering each entry,
fixed layout problem on SUN,
Melissa Marsh, HSTX, January 1994
Written : Wayne Landsman, GSFC/UIT (STX).
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC, 1 April 1994
Incorporated following change:
Only updates the fields which are changed. Joel Offenberg, HSTX, Mar 94
Version 3, William Thompson, GSFC, 4 November 1994
Incorporated bugfix by Wayne Landsman.
Version 4, William Thompson, GSFC, 22 December 1994
Incorporated more bugfixes by Wayne Landsman.
Version 5, Trap editing of empty database. C D Pike, RAL
3-Mar-95
Version : Version 5, 3-Mar-95
(See .//dbedit.pro)
DBEDIT_BASIC
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBEDIT_BASIC
Purpose :
Interactively edit specified fields in a database.
Explanation :
Interactively edit specified fields in a database. The
value of each field is displayed, and the user has the option
of changing or keeping the value.
Use :
dbedit_basic, list, [ items ]
The item values for each entry to be edited are first displayed
User is the asked "EDIT VALUES IN THIS ENTRY (Y(es), N(o), or Q(uit))?
If user answers 'Y' or hits RETURN, then each item is displayed
with its current value, which the user can update. If user answered
'N' then DBEDIT_BASIC skips to the next entry. If user answers 'Q'
then DBEDIT will exit, saving all previous changes.
EXAMPLE: Suppose V magnitudes (V_MAG) in a database STARS with unknown
values were assigned a value of 99.9. Once the true values become
known, the database can be edited
IDL> !PRIV=2 & dbopen,'STARS',1 ;Open database for update
IDL> list = dbfind('V_MAG=99.9') ;Get list of bad V_MAG values
IDL> dbedit,list,'V_MAG' ;Interactively insert good V_MAG values
Inputs :
list - scalar or vector of database entry numbers. Set LIST=0
to interactively add a new entry to a database.
Opt. Inputs :
items - list of items to be edited. If not supplied, then the
value of every field will be displayed.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : DATATYPE, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBINDEX, DBOPEN,
DBPRINT, DBRD, DBWRT, DBXPUT, DBXVAL, ZPARCHECK
Common : None.
Restrictions:
(1) Database must be opened for update (dbopen,,1) before
calling DBEDIT_BASIC. User must have write privileges on the database
files.
(2) User gets a second chance to look at edited values, before
they are actually written to the database
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Written W. Landsman STX April, 1989
Rename DBEDIT_BASIC from DBEDIT July, 1993
Written : W. Landsman, GSFC/UIT (STX), April 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version : Version 1, 29 March 1994
(See .//dbedit_basic.pro)
DBEXT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBEXT
Purpose :
Extract values of up to 12 items from data base file.
Explanation :
Procedure to extract values of up to 12 items from
data base file, and place into IDL variables
Use :
dbext,list,items,v1,[v2,v3,v4,v5,v6,v7,v8,v9,v10,v11,v12]
EXAMPLE: Extract all RA and DEC values from the currently opened
database, and place into the IDL vectors, IDLRA and IDLDEC.
IDL> DBEXT,-1,'RA,DEC',idlra,idldec
Inputs :
list - list of entry numbers to be printed, vector or scalar
If list = -1, then all entries will be extracted.
list may be converted to a vector by DBEXT
items - standard item list specification. See DBPRINT for
the 6 different ways that items may be specified.
Opt. Inputs : None.
Outputs :
v1...v12 - the vectors of values for up to 12 items.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT_DBF, DBEXT_IND, ZPARCHECK
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 2 D. Lindler NOV. 1987
check for INDEXED items W. Landsman Feb. 1989
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version : Version 1, 29 March 1994
(See .//dbext.pro)
DBEXT_DBF
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBEXT_DBF
Purpose :
Extract values of up to 12 items -- subroutine of DBEXT
Explanation :
Procedure to extract values of up to 12 items from a data base file.
This is a subroutine of DBEXT, which is the routine a user should
normally use.
Use :
dbext_dbf,list,dbno,sbyte,nbytes,idltype,nval,v1,v2,v3,v4,v5,v6,v7,
v8,v9,v10,v11,v12
Inputs :
list - list of entry numbers to extract desired items. It is the
entry numbers in the primary data base unless dbno is greater
than or equal to -1. In that case it is the entry number in
the specified data base.
dbno - number of the opened db file
if set to -1 then all data bases are included
sbyte - starting byte in the entry. If single data base then it must
be the starting byte for that data base only and not the
concatenation of db records
nbytes - number of bytes in the entry
idltype - idl data type of each item to be extracted
nval - number of values per entry of each item to be extracted
Opt. Inputs : None.
Outputs :
v1...v12 - the vectors of values for up to 12 items
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DBRD
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 1 D. Lindler Nov. 1987
Extract multiple valued entries W. Landsman May 1989
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version : Version 2, 1 June 1994
(See .//dbext_dbf.pro)
DBEXT_IND
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBEXT_IND
Purpose :
routine to read a indexed item values from index file
Explanation :
routine to read a indexed item values from index file
Use :
dbext_ind,list,item,dbno,values
Inputs :
list - list of entry numbers to extract values for
(if it is a scalar, values for all entries are extracted)
item - item to extract
dbno - number of the opened data base
Opt. Inputs : None.
Outputs :
values - vector of values returned as function value
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 1 D. Lindler Feb 88
Faster processing of string values W. Landsman April, 1992
Written : D. Lindler, GSFC/HRS, February 1988
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Version : Version 2, 30 May 1994
(See .//dbext_ind.pro)
DBFIND
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBFIND()
Purpose :
Searches data base for entries with specified characteristics
Explanation :
Function to search data base for entries with specified
search characteristics.
Use :
result = dbfind(spar,[ listin, /SILENT, /FULLSTRING])
Inputs :
spar - search_parameters (string)...each search parameter
is of the form:
option 1) min_val < item_name < max_val
option 2) item_name = value
option 3) item_name = [value_1, value_10]
Note: option 3 is also the slowest.
option 4) item_name > value
option 5) item_name < value
option 6) item_name = value(tolerance) ;eg. temp=25.0(5.2)
option 7) item_name ;must be non-zero
Multiple search parameters are separated by a comma.
eg. 'cam_no=2,14 is interpreted as greater than or equal.
RA and DEC keyfields are stored as floating point numbers
in the data base may be entered as HH:MM:SEC and
DEG:MIN:SEC. Where:
HH:MM:SEC equals HH + MM/60.0 + SEC/3600.
DEG:MIN:SEC equals DEG + MIN/60.0 + SEC/3600.
For example:
40:34:10.5 < dec < 43:25:19 , 8:22:1.0 < ra < 8:23:23.0
Specially encoded date/time in the data base may
be entered by YY/DAY:hr:min:sec which is
interpreted as
YY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600.
For example
85/201:10:35:30
(See .//dbfind.pro)
DBFIND_ENTRY
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBFIND_ENTRY
Purpose :
Performs an entry number search. Subroutine of DBFIND.
Explanation :
This is a subroutine of dbfind and is not a standalone procedure
It performs a entry number search.
Use :
dbfind_entry, type, svals, nentries, values
Inputs :
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
values - array of values to search
Opt. Inputs :
Outputs :
good - indices of good values
!err is set to number of good values
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
D. Lindler July,1987
Written : D. Lindler, GSFC/HRS, July 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version : Version 1, 29 March 1994
(See .//dbfind_entry.pro)
DBFIND_SORT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBFIND_SORT
Purpose :
Limits the search using sorted values. Subroutine of DBFIND.
Explanation :
This is a subroutine of dbfind and is not a standalone procedure
It is used to limit the search using sorted values
Use :
dbfind_sort, it, type, svals, list
Inputs :
it - item number, scalar
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
Opt. Inputs : None.
Outputs :
list - found entries
!err is set to number of good values
!ERR = -2 for an invalid search
Opt. Outputs: None.
Keywords :
FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, DBSEARCH, MATCH
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
D. Lindler July,1987
Written : D. Lindler, GSFC/HRS, July 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Version 3, William Thompson, GSFC, 14 March 1995
Added keyword FULLSTRING
Version : Version 3, 14 March 1995
(See .//dbfind_sort.pro)
DBFPARSE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBFPARSE
Purpose :
Parse the search string. Subroutine of DBFIND.
Explanation :
Parse the search string supplied to DBFIND. Not a standalone routine
Use :
DBFPARSE, [ spar, items, stype, values ]
Inputs :
spar - search parameter specification, scalar string
Opt. Inputs : None.
Outputs :
items - list of items to search on
stype - search type, numeric scalar
0 item=values(j,0)
-1 item>values(j,0)
-2 item
(See .//dbfparse.pro)
DBGET
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBGET()
Purpose :
Find entry number of fields with specified values.
Explanation :
Find entry number of fields which contain specified values in
a specified item. DBGET is an altnerative to DBFIND when the
desired search values are not easily expressed as a string.
Use :
list = dbget( item, values, [ listin ], SILENT = )
EXAMPLE: Get info on selected HD stars in Bright Star catalogue
IDL> dbopen, 'YALE_BS'
IDL> hdno = [1141,2363,3574,4128,6192,6314,6668] ;Desired HD numbers
IDL> list = dbget( 'HD', hdno ) ;Get corresponding entry numbers
Inputs :
item - Item name or number
values - scalar or vector containing item values to search for.
Opt. Inputs :
listin - list of entries to be searched. If not supplied, or
set to -1, then all entries are searched
Outputs :
list - vector giving the entry number of entries containing desired
item values. The number of elements in LIST may be different
from that of VALUE, since a value might be located zero, once,
or many times in the database. Use the function DBMATCH if a
one to one correspondence is desired between VALUES and LIST.
!ERR is set to the number of entries found
Opt. Outputs: None.
Keywords :
SILENT - If this keyword is supplied, then DBGET will not display
the number of entries found
FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT, DBFIND_SORT, DBSEARCH
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Written, W. Landsman STX February, 1989
Written : W. Landsman, GSFC/UIT (STX), February 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 14 March 1995
Added keyword FULLSTRING
Version : Version 2, 14 March 1995
(See .//dbget.pro)
DBHELP
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBHELP
Purpose :
List available databases or items in current database
Explanation :
Procedure to either list available databases (if no database is
currently open) or the items in the currently open database.
If no data base is opened then a list of data bases are
printed, otherwise the items in the open data base are printed.
If a string is supplied for flag and a data base is opened
flag is assumed to be an item name. The information for that
item is printed along with contents in a optional file
zdbase:dbname_itemname.hlp
if a string is supplied for flag and no data base is opened,
then string is assumed to be the name of a data base file.
only information for that file is printed along with an
optional file zdbase:dbname.hlp.
Use :
dbhelp, [ flag , TEXTOUT = ]
Inputs :
flag - (optional) if set to nonzero then item or database
descriptions are also printed
default=0
If flag is a string, then it is interpreted as the
name of a data base (if no data base is opened) or a name
of an item in the opened data base. In this case, help
is displayed only for the particular item or database
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords :
textout Used to determine output device. If not present, the
value of !TEXTOUT system variable is used (see TEXTOPEN )
textout=1 Terminal with /MORE
textout=2 Terminal without /MORE
textout=3 .PRT
textout=4 LASER PRINTER
textout=5 USER MUST OPEN FILE;
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, FDECOMP, GETLOG, TEXTCLOSE,
TEXTOPEN
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Version 2 D. Lindler Nov 1987 (new db format)
Faster printing of title desc. W. Landsman May 1989
Keyword textout added, J. Isensee, July, 1990
Modified to work on Unix, D. Neill, ACC, Feb 1991.
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version 3, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Version 4, Wayne Landsman, GSFC/UIT, December 1994
Remove duplicate database names
Version : Version 4, 19 December 1994
(See .//dbhelp.pro)
DBINDEX
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBINDEX
Purpose :
Procedure to create index file for data base
Explanation :
Procedure to create index file for data base
Use :
dbindex, [ items ]
Inputs : None.
Opt. Inputs :
items - names or numbers of items to be index -- if not supplied,
then all indexed fields will be processed.
Outputs :
Index file .dbx is created on disk location ZDBASE:
Opt. Outputs: None.
Keywords : None.
Calls : BSORT, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT_DBF, DBINDEX_BLK
Common : None.
Restrictions:
Data base must have been previously opened for update
by DBOPEN
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 2 D. Lindler Nov 1987 (new db format)
W. Landsman added optional items parameter Feb 1989
M. Greason converted to IDL version 2. June 1990.
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, Wayne Landsman, GSFC/UIT (STX), 26 May 1994
Miscellaneous changes
Version 3, William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Version 3.1, Dominic Zarro, (ARC/GSFC) 16 December 1994.
Added /INFO to
message, 'ERROR - database contains no entries',/INF
This is to avoid halting MK_DETAILS when a user
deletes all the plan entries (a rare happening).
Version : Version 3.1, 16 December 1994
(See .//dbindex.pro)
DBINDEX_BLK
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBINDEX_BLK()
Purpose :
Set up associated variable in preparation for writing to file.
Explanation :
To set up an associated variable of the correct data-type and offset
into the file by some amount in preparation for writing to the file.
Use :
res = dbindex_blk(unit, nb, bsz, ofb, dtype)
Inputs :
unit The unit number assigned to the file.
nb The number of blocks to offset into the file.
bsz The size of each block, in bytes, to offset into the file.
ofb The offset into the block, in bytes.
dtype The IDL datatype as defined in the SIZE function
Opt. Inputs : None.
Outputs :
res The returned variable. This is an associated variable.
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions:
The file must have been previously opened.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Written by Michael R. Greason, STX, 14 June 1990.
Written : Michael R. Greason, GSFC/UIT (STX), 14 June 1990
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version : Version 1, 29 March 1994
(See .//dbindex_blk.pro)
DBMATCH
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBMATCH()
Purpose :
Find entry number in a database for item values.
Explanation :
Find one entry number in a database for each element in a vector of
item values. DBMATCH is especially useful for finding a one-to-one
correspondence between entries in different databases, and thus to
create the vector needed for database pointers.
DBMATCH is meant to be used for items which do not have duplicate values
in a database (e.g. catalog numbers). If more than one entry is found
for a particular item value, then only the first one is stored in LIST.
Use :
list = DBMATCH( item, values, [ listin ] )
EXAMPLE: Make a vector which points from entries in the Yale Bright
Star catalog to those in the SAO catalog, using the HD number
IDL> dbopen, 'yale_bs' ;Open the Yale Bright star catalog
IDL> dbext, -1, 'HD', hd ;Get the HD numbers
IDL> dbopen, 'sao' ;Open the SAO catalog
IDL> list = dbmatch( 'HD', HD) ;Get entries in SAO catalog
;corresponding to each HD number.
Inputs :
ITEM - Item name or number, scalar
VALUES - scalar or vector containing item values to search for.
Opt. Inputs :
LISTIN - list of entries to be searched. If not supplied, or
set to -1, then all entries are searched
Outputs :
LIST - vector of entry numbers with the same number of elements as
VALUES. Contains a value of 0 wherever the corresponding item
value was not found.
Opt. Outputs: None.
Keywords :
FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
Calls : DATATYPE, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT, DBFIND_SORT
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Written, W. Landsman STX February, 1990
Fixed error when list in parameter used May, 1992
Faster algorithm with sorted item when listin parameter supplied
Nov 1992
Written : W. Landsman, GSFC/UIT (STX), February 1990
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 14 March 1995
Added keyword FULLSTRING
Version 3, William Thompson, GSFC, 15 March 1995
Added check for empty database
Version 4, William Thompson, GSFC, 30 March 1995
Fixed bug with FULLSTRING for non-sorted item.
Version : Version 4, 30 March 1995
(See .//dbmatch.pro)
DBOPEN
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBOPEN
Purpose :
Routine to open an IDL database
Explanation :
Routine to open an IDL database
Use :
dbopen, name, update
Inputs :
name - (Optional) name or names of the data base files to open.
It has one of the following forms:
'name' -open single data base file
'name1,name2,...,nameN' - open N files which are
connected via pointers.
'name,*' -Open the data base with all data
bases connected via pointers
'' -Interactively allow selection of
the data base files.
If not supplied then '' is assumed.
name may optionally be a string array with one name
per element.
update - (Optional) Integer flag specifing openning for update.
0 - Open for read only
1 - Open for update
2 - Open index file for update only
!PRIV must be 2 or greater to open a file for update.
If a file is opened for update only a single data base
can be specified.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords :
UNAVAIL - If present, a "database doesn't exit" flag is returned
through it. 0 = the database exists and was opened (if
no other errors arose). 1 = the database doesn't exist.
Also if present, the error message for non-existant databases
is suppressed. The action, however, remains the same. If
specifiying this, be sure that the variable passed exists
before the call to DBOPEN.
Calls : DB_INFO, DBCLOSE, FDECOMP, GETLOG, GETTOK, SCREEN_SELECT,
ZPARCHECK, LIST_WITH_PATH, FIND_WITH_DEF
Common : DB_COM
Restrictions: None.
Side effects:
The .DBF and .dbx files are opened using unit numbers obtained by
GET_LUN. Descriptions of the files are placed in the common block
DB_COM.
Category : Utilities, Database.
Prev. Hist. :
Version 2, D. Lindler, Nov. 1987
For IDL Version 2 W. Landsman May 1990 -- Will require further
modfication once SCREEN_SELECT is working
Modified to work under Unix, D. Neill, ACC, Feb 1991.
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version 3, William Thompson, GSFC/CDS (ARC), 20 June 1994
Incorporated UNAVAIL keyword, added by M. Greason,
Hughes STX, Feb 1993.
Version 4, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Version : Version 4, 3 November 1994
(See .//dbopen.pro)
DBPRINT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBPRINT
Purpose :
Print specified items from a list of database entries
Explanation :
Procedure to print specified items from a list of database entries
Use :
dbprint, list, [items, FORMS= , TEXTOUT= , NOHeader = ]
Users may want to adjust the default lines_per_page value given at
the beginning of the program for their own particular printer.
Inputs :
list - list of entry numbers to be printed, vector or scalar
if list = -1, then all entries will be printed.
An error message is returned if any entry number is larger
than the number of entries in the database
Opt. Inputs :
items - items to be printed, specified in any of the following ways:
form 1 scalar string giving item(s) as list of names
separated by commas
form 2 string array giving list of item names
form 3 string of form '$filename' giving name
of text file containing items (one item per
line)
form 4 integer scalar giving single item number or
integer vector list of item numbers
form 5 Null string specifying interactive selection. This
is the default if 'items' is not supplied
form 6 '*' select all items, printout will be in
table format.
If items was undefined or a null string on input, then
on output it will contain the items interactively selected.
Output device controlled by non-standard system varaible !TEXTOUT, if
TEXTOUT keyword is not used.
Outputs : None.
Opt. Outputs:
items can also be an output variable--see above.
Keywords :
FORMS The number of printed lines per page. If forms is not
present, output assumed to be in PORTRAIT form, and
a heading and 47 lines are printed on each page, with
a page eject between each page. For LANDSCAPE form with
headings on each page, and a page eject between pages, set
forms = 34. For a heading only on the first page, and no
page eject, set forms = 0. This is the default for output
to the terminal
TEXTOUT Used to determine output device. If not present, the
value of !TEXTOUT system variable is used.
textout=1 Terminal with /MORE
textout=2 Terminal without /MORE
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout = filename (default extension of .prt)
NOHEADER - If this keyword is set, then the column headers will not
be printed
Calls : DATATYPE, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBRD, DBTITLE,
DBXVAL, GETLOG, TEXTCLOSE, TEXTOPEN, ZPARCHECK
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler Nov. 1987 (new db format)
Extra space added at end of printout W. Landsman Nov. 1990
Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991
Apply STRTRIM to free form output W. Landsman Dec 1992
Test for string value of TEXTOUT W. Landsman Feb 1994
Written : D. Lindler, GSFC/HRS, November 1987.
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Version : Version 2, 3 November 1994
(See .//dbprint.pro)
DBPUT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBPUT
Purpose :
Place new value for specified item into a data base file entry.
Explanation :
Procedure to place a new value for a specified item into
a data base file entry.
Use :
dbput, item, val, entry
Inputs :
item - item name or number
val - item value(s)
entry - entry (byte array) or scalar entry number.
if entry is a scalar entry number then the data
base file will be updated. Otherwise the change
will be only made to the entry array which must
be written latter using DBWRT.
Opt. Inputs : None.
Outputs :
entry can also be an output array--see above.
Opt. Outputs: None.
Keywords : None.
Calls : DB_ITEM, DBRD, DBWRT, DBXPUT
Common : None.
Restrictions:
If entry is a scalar entry number or the input file name
is supplied, the entry in the data base will be updated
instead of a supplied entry variable. In this case, !priv
must be greater than 1.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler Feb 1988 (new db formats)
modified to convert blanks into zeros correctly D. Neill Jan 1991
Written : D. Lindler, GSFC/HRS, February 1988.
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version : Version 1, 29 March 1994
(See .//dbput.pro)
DBRD
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBRD
Purpose :
Read an entry from a data base or linked multiple databases.
Explanation :
Procedure to read an entry from a data base file or from
linked multiple databases.
If multiple data base files are opened, the records are
concatenated with each other
Use :
dbrd, enum, entry, [available, dbno]
Inputs :
enum - entry number to read, integer scalar
Opt. Inputs :
dbno - specification of the data base number to return. If
supplied, only the record for the requested data base
number is returned in entry. Normally this input should
not be supplied. dbno is numbered for 0 to n-1 and gives
the number of the data base opened. The data bases are
numbered in the order supplied to dbopen. If dbno is supplied
then the entry number refers to that data base and not the
primary or first data base. If set to -1, then it means all
data bases opened (same as not supplying it)
Outputs :
entry - byte array containing the entry
Opt. Outputs:
available - byte array with length equal to number of data
bases opened. available(i) eq 1 if an entry (pointed
to) is available. It always equals 1 for the first
data base, otherwise it is an error condition.
Keywords : None.
Calls : DB_INFO, DB_ITEM, DBXVAL
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 2 D. Lindler Nov. 1987
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version : Version 2, 1 June 1994
(See .//dbrd.pro)
DBSEARCH
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBSEARCH
Purpose :
Search a vector for specified values. Subroutine of DBFIND.
Explanation :
Search a vector for specified values
This is a subroutine of dbfind and is not a standalone procedure
Use :
dbsearch, type, svals, values, good, FULLSTRING = fullstring
Inputs :
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
values - array of values to search
Opt. Inputs : None.
Outputs :
good - indices of good values
!err is set to number of good values
Opt. Outputs: None.
Keywords :
FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
Calls : None.
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
D. Lindler July,1987
Written : D. Lindler, GSFC/HRS, July 1987
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library.
Version 2, Wayne Landsman, GSFC/UIT (STX), 1 April 1994
Added FULLSTRING keyword.
Version : Version 2, 1 April 1994
(See .//dbsearch.pro)
DBSORT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBSORT()
Purpose :
Routine to sort list of entries in data base
Explanation :
Routine to sort list of entries in data base
The list is sorted such that each item is sorted into
asscending order starting with the last item.
Use :
result = dbsort( list, items , [ REVERSE = ])
EXAMPLE: Sort an astronomical catalog with RA as primary sort, and
declination as secondary sort (used when RA values are equal)
IDL> NEWLIST = DBSORT( -1, 'RA,DEC' )
If for some reason, one wanted the DEC sorted in descending order, but
the RA in ascending order
IDL> NEWLIST = DBSORT( -1, 'RA,DEC', REV = [ 0, 1 ] )
Inputs :
list - list of entry numbers to sort
-1 to sort all entries
items - list of items to sort (up to 9 items)
Opt. Inputs : None.
Outputs :
result - numeric vector giving input list sorted by items
Opt. Outputs: None.
Keywords :
REVERSE - scalar or vector with the same number of elements as the
the number of items to sort. If the corresponding element of REVERSE
is non-zero then that item is sorted in descending rather than
ascending order.
Calls : BSORT, DB_ITEM, DBEXT, ZPARCHECK
Common :
DBCOM
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
VERSION 1 D. Lindler Oct. 86
Added REVERSE keyword W. Landsman August, 1991
Written : D. Lindler, GSFC/HRS, October 1986
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library
Version : Version 1, 28 March 1994
(See .//dbsort.pro)
DBTITLE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBTITLE()
Purpose :
Function to create title line. Subroutine of DBPRINT
Explanation :
Function to create title line for routine dbprint.
This is a subroutine of DBPRINT.
Use :
result = dbtitle( c, f )
Inputs :
c = string array of titles for each item
f = field length of each item
Opt. Inputs : None.
Outputs :
header string returned as function value
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions:
This is a subroutine of DBPRINT.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 1 D. Lindler Sept 86
Written : D. Lindler, GSFC/HRS, September 1986.
Modified : Version 1, William Thompson, GSFC, 28 March 1994.
Incorporated into CDS library
Version : Version 1, 28 March 1994.
(See .//dbtitle.pro)
DBUPDATE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBUPDATE
Purpose :
Update columns of data in a database -- inverse of DBEXT
Explanation :
Update columns of data in a database -- inverse of DBEXT
Database must be open for update before calling DBUPDATE
Use :
dbupdate, list, items, v1, [ v2, v3, v4......v14 ]
EXAMPLES: A database STAR contains RA and DEC in radians, convert to
degrees
IDL> !PRIV=2 & dbopen,'STAR',1 ;Open database for update
IDL> dbext,-1,'RA,DEC',ra,dec ;Extract RA and DEC, all entries
IDL> ra = ra*!RADEG & dec=dec*!RADEG ;Convert to degrees
IDL> dbupdate,-1,'RA,DEC',ra,dec ;Update database with new values
Inputs :
list - entries in database to be updated, scalar or vector
If list=-1 then all entries will be updated
items -standard list of items that will be updated.
v1,v2....v14 - vectors containing values for specified items. The
number of vectors supplied must equal the number of items
specified. The number of elements in each vector should be
the same.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DB_ITEM, DB_ITEM_INFO, DBINDEX, DBRD, DBWRT, DBXPUT
Common : None.
Restrictions:
It is quicker to update several items simultaneously rather than use
repeated calls to DBUPDATE.
It is possible to update multiple valued items. In this case, the
input vector should be of dimension (NVAL,NLIST) where NVAL is the
number of values per item, and NLIST is the number of entries to be
updated. This vector will be temporarily transposed by DBUPDATE but
will be restored before DBUPDATE exits.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
Written W. Landsman STX March, 1989
Work for multiple valued items May, 1991
String arrays no longer need to be fixed length December 1992
Transpose multiple array items back on output December 1993
Written : W. Landsman, GSFC/UIT (STX), March 1989
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library.
Version : Version 1, 28 March 1994
(See .//dbupdate.pro)
DBVAL
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBVAL()
Purpose :
Extract value(s) of an item from a data base file entry.
Explanation :
Procedure to extract value(s) of the specified item from
a data base file entry.
Use :
result = dbval( entry, item )
EXAMPLE: Extract a flux vector from entry 28 of the database FARUV
==> flux = dbval(28,'FLUX')
Inputs :
entry - byte array containing the entry, or a scalar entry number
item - name (string) or number (integer) of the item
Opt. Inputs : None.
Outputs :
the value(s) will be returned as the function value
Opt. Outputs: None.
Keywords : None.
Calls : DB_ITEM, DBRD, DBXVAL
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler Nov, 1987 (new db format)
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 28 March 1994.
Incorporated into CDS library.
Version : Version 1, 28 March 1994
(See .//dbval.pro)
DBWRT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBWRT
Purpose :
Procedure to update or add a new entry to a data base
Explanation :
Procedure to update or add a new entry to a data base
Use :
dbwrt, entry, [ index, append ]
Inputs :
entry - entry record to be updated or added if first
item (entry number=0)
Opt. Inputs :
index - optional integer flag, if set to non zero then index
file is updated. (default=0, do not update index file)
(Updating the index file is time-consuming, and should
normally be done after all changes have been made.
append - optional integer flag, if set to non-zero the record
is appended as a new entry, regardless of what the
entry number in the record is. The entry number will
be reset to the next entry number in the file.
Outputs :
data base file is updated.
If index is non-zero then the index file is updated.
Opt. Outputs: None.
Keywords : None.
Calls : BSORT, DB_INFO, DB_ITEM, DB_ITEM_INFO, DBINDEX_BLK, DBXPUT,
DBXVAL
Common : DB_COM
Restrictions:
!PRIV must be greater than 1 to execute
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler Feb. 1988 (new db format)
converted to IDL Version 2. M. Greason, STX, June 1990.
Written : D. Lindler, GSFC/HRS, February 1988
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC/CDS (ARC), 28 May 1994
Added support for external (IEEE) representation.
Version : Version 2, 28 May 1994
(See .//dbwrt.pro)
DBXPUT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBXPUT
Purpose :
Routine to replace value of an item in a data base entry
Explanation :
Routine to replace value of an item in a data base entry
Use :
dbxput, val, entry, idltype, sbyte, nbytes
Inputs :
val - value(s) to be placed into entry, string values might be
truncated to fit number of allowed bytes in item
entry - entry to be updated
idltype - idl data type for item
sbyte - starting byte in record
nbytes - total number of bytes in value added
Opt. Inputs : None.
Outputs :
entry - (updated)
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions:
This routine assumes that the calling procedure or user
knows what he or she is doing. No validity checks are made
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 1, D. Lindler Aug, 1986
converted to IDL Version 2. M. Greason, STX, June 1990.
Written : D. Lindler, GSFC/HRS, August 1986
Modified : Version 1, William Thompson, GSFC, 28 March 1994
Incorporated into CDS library
Version : Version 1, 28 March 1994
(See .//dbxput.pro)
DBXVAL
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DBXVAL()
Purpose :
Quickly return a value of the specified item number
Explanation :
Procedure to quickly return a value of the specified item number
from the entry.
Use :
result = dbxval( entry, idltype, nvalues, sbyte, nbytes )
Inputs :
entry - entry from data base (bytarr)
idltype - idl data type (obtained with db_item_info)
nvalues - number of values to return (obtained with db_item)
sbyte - starting byte in the entry (obtained with db_item)
nbytes - number of bytes (needed only for string type)
(obtained with db_item)
Opt. Inputs : None.
Outputs :
function value is value of the specified item in entry
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions:
To increase speed the routine assumes that entry and item are
valid and that the data base is already opened using dbopen.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. :
version 2 D. Lindler Nov. 1987 (for new db format)
Written : D. Lindler, GSFC/HRS, November 1987.
Modified : Version 1, William Thompson, GSFC, 28 March 1994.
Incorporated into CDS library.
Version : Version 1, 28 March 1994.
(See .//dbxval.pro)
DB_ENT2EXT
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : DB_ENT2EXT
Purpose : Converts database entry from host to external format.
Explanation : Converts a database entry to external (IEEE) data format prior
to writing it. Called from DBWRT.
Use : DB_ENT2EXT, ENTRY
Inputs : ENTRY = Byte array containing a single record to be written
to the database file.
Opt. Inputs : None.
Outputs : ENTRY = The converted array is returned in place of the input
array.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DBXPUT, DBXVAL, HOST_TO_IEEE
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. : None.
Written : William Thompson, GSFC/CDS (ARC), 1 June 1994
Modified : Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994
Version : Version 1, 1 June 1994
(See .//db_ent2ext.pro)
DB_ENT2HOST
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : DB_ENT2HOST
Purpose : Converts database entry from external to host format.
Explanation : Converts a database entry from external (IEEE) data format to
host format after reading it from the file. Called from DBRD
and DBEXT_DBF.
Use : DB_ENT2HOST, ENTRY, DBNO
Inputs : ENTRY = Byte array containing a single record read from the
database file.
DBNO = Number of the opened database file.
Opt. Inputs : None.
Outputs : ENTRY = The converted array is returned in place of the input
array.
Opt. Outputs: None.
Keywords : None.
Calls : DB_INFO, DBXPUT, DBXVAL, IEEE_TO_HOST
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database.
Prev. Hist. : None.
Written : William Thompson, GSFC/CDS (ARC), 1 June 1994
Modified : Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994
Version : Version 1, 1 June 1994
(See .//db_ent2host.pro)
DB_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DB_INFO()
Purpose :
Function to obtain information on opened data base file(s)
Explanation :
Function to obtain information on opened data base file(s)
Use :
1) result = db_info(request)
2) result = db_info(request,dbname)
Inputs :
(calling sequence 1):
request - string specifying requested value(s)
value of request value returned in result
'open' Flag set to 1 if data base(s) are opened
'number' Number of data base files opened
'items' Total number of items (all db's opened)
'update' update flag (1 if opened for update)
'unit_dbf' Unit number of the .dbf files
'unit_dbx' Unit number of the .dbx files
'entries' Number of entries in the db's
'length' Record lengths for the db's
'external' True if the db's are in external format
(calling sequence 2):
request - string specifying requested value(s)
value of request value returned in result
'name' Name of the data base
'number' Sequential number of the db
'items' Number of items for this db
'item1' Position of item1 for this db
in item list for all db's
'item2' Position of last item for this db.
'pointer' Number of the item which points
to this db. 0 for first or primary
db. -1 if link file pointers.
'length' Record length for this db.
'title' Title of the data base
'unit_dbf' Unit number of the .dbf file
'unit_dbx' Unit number of the .dbx file
'entries' Number of entries in the db
'seqnum' Last sequence number used
'alloc' Allocated space (# entries)
'update' 1 if data base opened for update
'external' True if data base in external format
dbname - data base name or number
Opt. Inputs : None.
Outputs :
Requested value(s) are returned as the function value.
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 1 D. Lindler Oct. 1987
changed type from 1 to 7 for IDLV2, J. Isensee, Nov., 1990
Written : D. Lindler, GSFC/HRS, October 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version 2, William Thompson, GSFC/CDS (ARC), 30 May 1994
Added EXTERNAL request type.
Version : Version 2, 30 May 1994
(See .//db_info.pro)
DB_ITEM
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DB_ITEM
Purpose :
Returns the item numbers and other info. for an item name.
Explanation :
Procedure to return the item numbers and other information
of a specified item name
Use :
db_item, items, itnum, ivalnum, idltype, sbyte, numvals, nbytes
Inputs :
items - item name or number
form 1 scalar string giving item(s) as list of names
separated by commas
form 2 string array giving list of item names
form 3 string of form '$filename' giving name
of text file containing items (one item per
line)
form 4 integer scalar giving single item number or
integer vector list of item numbers
form 5 Null string specifying interactive selection
Upon return items will contain selected items
in form 1
form 6 '*' select all items
Opt. Inputs :
Outputs :
itnum - item number
ivalnum - value(s) number from multiple valued item
idltype - data type(s) (1=string,2=byte,4=i*4,...)
sbyte - starting byte(s) in entry
numvals - number of data values for item(s)
It is the full length of a vector item unless
a subscript was supplied
nbytes - number of bytes for each value
All outputs are vectors even if a single item is requested
Opt. Outputs: None.
Keywords : None.
Calls : DATATYPE, DB_INFO, GETTOK, SCREEN_SELECT, SPEC_DIR
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 2 D. Lindler Oct. 1987
Return selected items in form 5 W. Landsman Jan. 1987
Written : D. Lindler, GSFC/HRS, October 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library
Version : Version 1, 29 March 1994
(See .//db_item.pro)
DB_ITEM_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DB_ITEM_INFO()
Purpose :
Returns information on selected item(s).
Explanation :
Routine to return information on selected item(s) in the opened
data bases.
Use :
result = db_item_info( request, itnums)
Inputs :
request - string giving the requested information.
'name' - item names
'idltype' - IDL data type (integers)
see documentation of intrinsic SIZE funtion
'nvalues' - vector item length (1 for scalar)
'sbyte' - starting byte in .dbf record (use bytepos
to get starting byte in record returned by
dbrd)
'nbytes' - bytes per data value
'index' - index types
'description' - description of the item
'pflag' - pointer item flags
'pointer' - data bases the items point to
'format' - print formats
'flen' - print field length
'headers' - print headers
'bytepos' - starting byte in dbrd record for the items
'dbnumber' - number of the opened data base
'pnumber' - number of db it points to (if the db is
opened)
'itemnumber' - item number in the file
Opt. Inputs :
itnums -(optional) Item numbers. If not supplied info on all items
are returned.
Outputs :
Requested information is returned as a vector. Its type depends
on the item requested.
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : DB_COM
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
version 1 D. Lindler Nov. 1987
Written : D. Lindler, GSFC/HRS, November 1987
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version : Version 1, 29 March 1994
(See .//db_item_info.pro)
DB_OR
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DB_OR()
Purpose :
Combine two vectors of entry numbers, removing duplicates.
Explanation :
Combine two vectors of entry numbers, removing duplicate values.
DB_OR can also be used to remove duplicate values from any longword
vector
DB_OR returns where the histogram of the entry vectors is non-zero
Use :
LIST = DB_OR( LIST1 ) ;Remove duplicate values from LIST1
or
LIST = DB_OR( LIST1, LIST2 ) ;Concatenate LIST1 and LIST2, remove dups
Inputs :
LIST1, LIST2 - Vectors containing entry numbers, must be non-negative
integers or longwords.
Opt. Inputs : None.
Outputs :
LIST - Vector containing entry numbers in either LIST1 or LIST2
Opt. Outputs: None.
Keywords : None.
Calls :
ZPARCHECK - checks parameters
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Database
Prev. Hist. :
Written, W. Landsman February, 1989
Check for degenerate values W.L. February, 1993
Written : W. Landsman, GSFC/UIT, February 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version : Version 1, 29 March 1994
(See .//db_or.pro)
DB_TITLES
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
DB_TITLES
Purpose :
Print database name and title. Called by DBHELP
Explanation :
Print database name and title. Called by DBHELP
Use :
db_titles,fnames,titles
Inputs :
fnames - string array of data base names
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : GETLOG
Common : None.
Restrictions: None.
Side effects:
Database name is printed along with the description in the .DBC file
Category : Utilities, Database
Prev. Hist. :
version 2 W. Landsman May, 1989
modified to work under Unix, D. Neill, ACC, Feb 1991.
Written : W. Landsman, GSFC/UIT, May 1989
Modified : Version 1, William Thompson, GSFC, 29 March 1994
Incorporated into CDS library.
Version 2, William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version 3, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Version : Version 3, 3 November 1994
(See .//db_titles.pro)
FIX_ZDBASE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FIX_ZDBASE()
Purpose : To control the value of env. var. ZDBASE.
Explanation : The environment variable ZDBASE controls access to the
CDS databases. The user may have access to either a private
set of data bases or the 'official' CDS set. This function
allows the uset to set the ZDBASE variable to be the
equivalent of either ZDBASE_CDS or ZDBASE_USER depending
on the database access required. These latter two variables
must be defined before this routine is called. The original
definition of ZDBASE is stored in common and can be restored to
that variable by use of the /ORIGINAL keyword.
Use : IDL> status = fix_zdbase(/user, errmsg=errmsg)
first time used so record the current value of ZDBASE and set
its current value to be that of ZDBASE_USER
IDL> status = fix_zdbase(/cds, errmsg=errmsg)
if not the first time used then just set current ZDBASE
definition to that of ZDBASE_CDS
IDL> status = fix_zdbase(/orig, errmsg=errmsg)
all finished, so restore ZDBASE to its original value.
Note that this routine is more likely to be used within other
procedures rather than at a user level as in the above
example.
Inputs : None (see keywords).
Opt. Inputs : None
Outputs : None (Values in common may change)
Opt. Outputs: None
Keywords : USER - switch ZDBASE to value of ZDBASE_USER
CDS - switch ZDBASE to value of ZDBASE_CDS
ORIGINAL - restore original value of ZDBASE
ERRMSG - if defined on entry any error messages
will be returned in it.
Calls : getenv
setenv
Common : zdbase_def
Restrictions: Uses common block variable to signal whether original value
of ZDBASE has been saved or not. Be careful of the common
block's memory.
Side effects: Environment variable ZDBASE is changed.
Category : Util, database
Prev. Hist. : None
Written : C D Pike, RAL, 17-Jan-95
Modified :
Version : Version 1, 17-Jan-95
(See .//fix_zdbase.pro)
UITDBLIB
[Previous Routine]
[List of Routines]
Project : SOHO - CDS
Name : UITDBLIB
Purpose : Add the system variables used by the UIT database library
Explanation : This routine adds the non-standard system variables used by the
UIT database routines from the IDL Astronomy User's Library.
The non-standard system variables !PRIV, !DEBUG, !TEXTUNIT, and
!TEXTOUT are added using DEFSYSV.
Use : UITDBLIB
Inputs : None.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : None.
Calls : None.
Common : None.
Restrictions: This routine should be called only once, preferably in the
startup procedure.
Side effects: System variables may be changed to their default values.
Category : Utilities, Database
Prev. Hist. : This routine was adapted from ASTROLIB, which had the following
history entries:
Written, Wayne Landsman, July 1986.
Use DEFSYSV instead of ADDSYSVAR December 1990
Written : William Thompson, GSFC, 30 March 1994
Modified : Version 1, William Thompson, GSFC, 30 March 1994
Version : Version 1, 30 March 1994
(See .//uitdblib.pro)