freemed project API
(c) 1999 by jeff b
Under the GPL/LGPL version 2
..........................................................................
last updated 2000-01-09

                                *****
                                NOTE:
each function includes the file global.var.php3, which contains all of
the package global variables.

                                *****
                          CALENDAR FUNCTIONS

date_in_range (date to check, range begins, range ends)
  location: freemed-calendar-functions.inc
  returns: true if the date is within a range, false if not
  created: 19991116

date_in_the_past (date in YYYY-MM-DD format)
  location: freemed-calendar-functions.inc
  returns: true if the date is in the past, false if not

day_of_the_week (date in YYYY-MM-DD format [, short format?])
  location: freemed-calendar-functions.inc
  returns: text name of the day of the week

fc_check_interference_map (hour, minute, date (YYYY-MM-DD), query)
  checks the current interference map ($current_imap) for an appointment or
  interference at the specified time and date.
    location: freemed-calendar-functions.inc
    returns: true if there is an appointment, false if not

fc_display_day_calendar (date in YYYY-MM-DD format [, query string, privacy?])
  displays a day calendar which is true for "query string". privacy can be
  set so that the names of patients are not displayed, but only their initials.
    location: freemed-calendar-functions.inc
    returns: none

fc_display_week_calendar (date in YYYY-MM-DD format [, querystring, privacy?])
  displays a week calendar, and works about the same way as
  fc_display_day_calendar....
    location: freemed-calendar-functions.inc
    returns: none

fc_generate_interference_map (query, date (YYYY-MM-DD) [, privacy?])
  generates the global interference map in $current_imap for the query and
  date given. this map is used to generate calendars.
    location: freemed-calendar-functions.inc
    returns: none, $current_imap is global variable

fc_ending_hour
  location: freemed-calendar-functions.inc
  returns: ending hour of booking

fc_interference_map_count
  location: freemed-calendar-functions.inc
  returns: the number of appointments, etc, in the current interference map

fc_starting_hour
  location: freemed-calendar-functions.inc
  returns: starting hour of booking

freemed_get_date_prev (date in YYYY-MM-DD format)
  returns: date before provided date

freemed_get_date_next (date in YYYY-MM-DD format)
  returns: date after provided date

                                *****

                          DATABASE FUNCTIONS

freemed_bar_alternate_color (current color [or null])
  for the result bar in such modules as facility, the bar alternates
  color. this function takes the last color used, or null, and returns
  the color to be used for the next bar.
    returns: new color to be used "#xxxxxx"
    created: API epoch or prior (19990609)

function freemed_check_access_for_facility (Login Cookie, facility number)
  checks if the current user has access to facility number specified
  * added fix for facility=0 (19990924)
  * changed checking for root to be user 1 (19990929)
  * fixed checking for -1 as access to all (19991018)
    returns: true or false
    created: 19990818
    modified: 19991018

function freemed_check_access_for_patient (Login Cookie, patient number)
  checks if the current user has access to patient number specified
  * changed checking for root to be user 1 (19990929)
    returns: true or false
    created: 19990817
    modified: 19990929

freemed_close_db
  closes the connection to the MySQL database server (which is usually
  the localhost). should be the last command in a PHP3 script file.
    returns: none
    created: API epoch or prior (19990609)

freemed_config_value (configuration variable)
  retrieves a variable from the configuration db
  * 19991124 -- modified to return NULL if db is not open (bug fix??)
    returns: the value of the configuration variable
    created: API epoch or prior (19990609)
    modified: 19991124

freemed_display_actionbar (current page name, _ref cookie)
  displays "action bar" for db maintenance... has an add function and
  a return to previous menu function. called with the current page
  name and the ref cookie, usually like :
  freemed_display_actionbar ($page_name, $_ref)
  * 19990921 -- can be called with no parameters, and stupid problem
    involving global/local scope resolved
  * 19991129 -- detects $patient variable for "ADD" link
  * 19991227 -- passed $_auth global and better $_ref checking
    returns: none
    created: API epoch or prior (19990609)
    modified: 19991227

freemed_display_banner
  displays banner at the top of a page. should always be called in
  every module.
    returns: none
    created: 19990611

freemed_display_bottom_links ([page natural name, module name, _ref tag])
  displays text links back to the rest of the program at the bottom
  of an HTML page. should be used after the bottom of the box but
  before the bottom of the HTML code. only really used in add/mod/del
  screens.
  * modified to work with no parameters whatsoever (19990924)
    returns: none
    created: 19990615 
    modified: 19990924

freemed_display_box_bottom
  displays screen-enclosing box bottom. see freemed_display_box_top
  for more details about this function.
  * modified to have different enclosing box style (19991022)
  * modified _ref passing code (19991026)
    returns: none
    created: API epoch or prior (19990609)
    modified: 19991026

freemed_display_box_top (box title [, pass _ref])
  displays screen-encloding box top. all information to be displayed
  other than exiting from the current module or aborting (and at some
  point, another menu bar) is displayed in this box. this must be
  closed with a freemed_display_box_bottom, or no HTML text will be
  shown to the user.
  * 19990611 -- box now has optional title, and _ref passing
  * 19991022 -- modified to have different enclosing box style
  * 19991112 -- added icon bar
  * 19991129 -- support for graphics enabled/disabled in icon bar
    returns: none
    created: API epoch or prior (19990609)
    modified: 19991129

freemed_display_cptcodes (selected)
  displays <SELECT>-box style CPT codes pulldown
    returns: none
    created: 19990722

freemed_display_cptmods (selected)
  displays <SELECT>-box style CPT modifiers pulldown
  * 19991224 -- changed order and sorting for ease of use
    returns: none
    created: 19990722
    modified: 19991224

freemed_display_drugs (selected)
  displays <SELECT>-box style formulary (drugs) pulldown
    returns: none
    created: 19990723

freemed_display_facilities (selected [, default value on])
  this displays the innards of a SELECT tag set for the listing of
  facilities. if the optional second parameter is used, it will
  select the cookie'd default facility.
    returns: none
    created: ????
    modified: 19990820

freemed_display_html_bottom
  the companion function to freemed_display_html_top, it replaces
  include "tail.php3" and include "tail.html", and is required for
  the end of almost every page generated by the freemed PHP
  scripts.
    returns: none
    created: 19990610

freemed_display_html_top ([refresh to, page description])
  displays the HTML header of almost every file generated by the
  freemed PHP scripts. the parameters are optional. refresh to is
  the location that this will refresh to. specify this parameter
  if the page is to "roll over" to another (fully qualified URL).
  page description is put on the title bar, and is completely
  optional. replaces include "head.php3" and include "head.html".
  * also generates META tag for ISO set depending on $language,
     from $__ISO_SET__, generated in global.var.inc (19990920)
    returns: none
    created: 19990920

freemed_display_facilities (selected)
  displays the list of facilities available for the innards of a
  <SELECT> tah set. the parameter can be used to select which one of
  the codes is displayed as the default.
    returns: none
    created: 19990614

freemed_display_icdcodes (selected)
  displays the list of ICD9/10 codes for the innards of a <SELECT> tag
  set. the parameter can be used to select which one of the codes is
  displayed as the default.
  * 20000109 -- now has outer tags option so that select tag is internal
    returns: none
    created: API epoch or prior (19990609)
    modified: 20000109

freemed_display_insco (selected)
  displays list of insurance companies for <SELECT> tags...
  * fixed so that param is optional... (19991028)
    returns: none
    created: 19990721
    modified: 19991028

freemed_display_inscogroups (selected)
  displays the list of insurance companies for the innards of a <SELECT>
  tag set. (same as freemed_display_icdcodes).
    returns: none
    created: API epoch or prior (19990609)

freemed_display_phygroups (selected)
  displays the list of physician groups for the innards of a <SELECT> tag
  set. (same as freemed_display_icdcodes).
    returns: none
    created: 19990701

freemed_display_physicians (selected)
  displays the list of physicians for the innards of a <SELECT> tag
  set. the parameter can be used to select which one of the codes is
  displayed as the default. replaces the _doclist.php3 module.
  (same as freemed_display_icdcodes)
    returns: none
    created: 19990610

freemed_display_phystatus (selected)
  displays the list of physician statuses for the innards of a <SELECT>
  tag set. (same as freemed_display_icdcodes).
    returns: none
    created: API epoch or prior (19990609)

freemed_display_phy_degrees (selected)
  displays the list of physician specialties for the innards
  of a tag set. (same as freemed_display_icdcodes). Formerly
  implemented as _specialtylist.php3, and also known as
  freemed_display_phy_specialties
    returns: none
    created: 19990610
    modified: 19990830

freemed_display_phy_specialties (selected)
  displays the list of physician specialties for the innards
  of a tag set.
    returns: none
    created: 19990830

freemed_display_ptstatus (selected[, tag var name])
  displays patient statuses in select tag, and will display the
  tag as well if it is specified
    returns: none
    created: 20000109

freemed_display_rooms (selected)
  displays the list of rooms for the innards of a <SELECT> tag set.
  (same as freemed_display_icdcodes). now modified to check the validity
  of the facility and to only show selected facility rooms if a facility
  is chosen at login.
    returns: none
    created: 19990616
    modified: 19990820

freemed_display_simplereports (selected)
  displays the list of simple report templates from the innards of a <SELECT>
  tag set. 
  (same as freemed_display_icdcodes)
    returns: none
    created: 19990815

freemed_display_tos (selected)
  innards of select tag for type of service
    returns: none
    created: sometime before 19991101

freemed_export_stock_data (table name, [file name])
  exports stock data from the table represented by "table name" and
  puts it in a comma delimited text file called "file name". if no file
  name is given, it defaults to data/(language)/(table).(language).(date)
    returns: true or false, depending on success
    created: 19990818

freemed_get_date_next (timestamp [YYYY-MM-DD])
  returns the next valid date in the format YYYY-MM-DD (MySQL
  standard datestamp type).
    returns: next date (YYYY-MM-DD)
    created: 19990616

freemed_get_date_prev (timestamp [YYYY-MM-DD])
  returns yesterday's date from the timestamp given. same
  restrictions, etc, apply as to freemed_get_date_next.
    returns: previous date (YYYY-MM-DD)
    created: 19990616

freemed_get_link_rec (link number, database name)
  returns a result array comprised of the entire record that is
  referenced by the link "link number" pulled from the database
  "database name".
    returns: relational array ($r["name"] = value;)
    created: API epoch or prior (19990609)

freemed_get_link_field (link number, database name, field name)
  gets the value of a link to another database, and returns a
  specific field from it. very useful for getting names of other
  relational objects, or merely for pulling data across dbs with
  greater ease.
    returns: value of linked value... (skips $r["name"] stage)
    created: API epoch or prior (19990609)

freemed_get_userlevel (login cookie)
  gets the user's access level (0..9) from the central user db
  ($database.user) and returns it. in case of root, function
  returns 9, unknown returns 1. as of the new authentication
  scheme, it requires the login cookie ($LoginCookie).
  * no longer requires LoginCookie -- will import (19990920)
    returns: user level (0..9)
    created: API epoch or prior (19990609)
    modify : 19990920

freemed_inscogroup_display (number of group record)
  displays the text of an insurance groups' name, with the
  record number if in debug mode, and displays NONE SELECTED
  if there is no insurance company group selected.
    returns: none
    created: API epoch or prior (19990609)

freemed_import_stock_data (table name)
  imports a stock set of data from data/(language)/table.(language).data
  from a comma delimited file. this is used for shipping packages with
  data.
    returns: true or false, if successful or not
    created: 19990818

freemed_log (login cookie, database name, record number, comment)
  adds a record of a transaction performed to the database log,
  which should be flushed every day or so. the end of day routine
  should have a call to an export function for this...
    returns: none
    created: 19990721

freemed_multiple_choice (sql query, displayed field, select box name,
                         blob data[, show ALL option])
  generates a multiple choice box, based on an SQL query (such as
  SELECT * FROM $database.db_name ORDER BY field_name). the field
  specified by "displayed field" is displayed in the box, which is
  named by "select box name" and the values selected are specified
  by "blob data".
  * added switch to turn off the "ALL" (-1) option (19991029)
    returns: none
    created: 19990812
    modified: 19991029

freemed_open_db (login cookie)
  opens the database with user name and password provides, and
  generates a screen if there is an error. this is the major
  form of authentication used in this package.
  * user name is passed as $user and password as $pw from the
     results of the results of the cookie (19990701)
  * the $LoginCookie provides name and password (19990820)
    returns: none
    created: API epoch or prior (19990609)
    modify : 19990820

                             *****

                  LOW-LEVEL DATABASE FUNCTIONS

These functions are preveded by fdb_, and comprise the low
level function for manipulating the database backend. They
are mostly wrappers, made to replace the mysql function
calls. - jeff b (19990722)

* fdb_affected_rows
* fdb_close
* fdb_connect
* fdb_create_db
* fdb_drop_db
* fdb_fetch_array
* fdb_last_record
* fdb_num_rows
* fdb_query

                             *****

                         MISC FUNCTIONS

fm_date_assemble (name of date variable[, array index])
  assembles a split date (variable_{m,d,y}) into an SQL-compliant date
  string for use in a query.
  * 19991103 -- added support for arrays
    returns: the concatenated string
    created: 19991101
    modified: 19991103

fm_date_entry (name of date variable[, before epoch?[, array?]])
  shows date entry boxes in the system's date format
  * 19991111 -- added support for pulldown year boxes, which subsequently
    needed an extra parameter for things more than 10 years old
    returns: false if there is an error
    created: 19991101
    modified: 19991111

fm_date_print (the date string (YYYY-MM-DD)[, show text weekdays?])
  displays a properly formatted date string according to the config value
  in the system registry. optionally, a true or false can be used as the
  second parameter to allow the day of the week to be displayed.
    returns: the date, properly formatted
    created: 19991102

fm_eval (original string)
  secures a string, then evaluates it for all internal variables -- mostly
  for use in user-built forms.
    returns: cleaned and evaluated string
    created: 19991022

fm_htmlize_array (name of array, array)
  passes an array as hidden input tags in a form for HTML, with error
  checking
    returns: true if successful, false if some horrible error
    created: 19991026

fm_join_from_array (array)
  creates a colon delimited string from an array of values --
  mostly used in multiple-choice selections.
  * modified for error checking (19991020)
  * replaced count() with !is_array for 1 element checking (19991029)
    returns: string made up of array elements (colon-delimited)
    created: 19990722
    modified: 19991029

fm_number_select (variable name, minimum, maximum[, step [, add zeros]])
  displays a select box for a number, with the variable being selected...
  with a minimum and maximum. add zeroes, if specified as true, adds
  zeros to the beginning of numbers < 10 (9 becomes 09).
  * 19991110 -- added steps (so you can do increases of 5, etc
    returns: none
    created: 19991105
    modified: 19991110

fm_phone_assemble (name of phone # string[, array value])
  assembles a phone number from its parts, if the optional array value is
  specified, it will use that one...
    returns: fully assembled phone #
    created: 19991105

fm_phone_entry (name of phone # string[, array value])
  displays the select tags/text fields/whatever for phone #s to be entered
  in, and the array value (optional) does the same as the one in
  fm_date_entry...
    returns: nothing
    created: 19991105

fm_prep (original string)
  prepares a string to be shown as HTML
    returns: HTMLized string
    created: 19991021

fm_secure (original string)
  internal routine to secure the contents of strings to be evaled (so that
  people don't have report forms printing with the database password or
  anything like that). used by fm_eval
    returns: secured string
    created: 19991022

fm_split_into_array (original argument)
  splits a string into pieces by ":"s -- used in multiple choice
  fields. 
    returns: array containing values specified in original argument
    created: 19990722

fm_value_in_array (array, value)
  searches "array" for matches of "value", and returns true if it
  finds a match, false if not. 
  * 19990812 -- reports correctly on first element (array element 0, not 1)
  * 19991020 -- added error checking/handling
    returns: true if match found
    created: 19990722
    modified: 19991020

fm_value_in_string (string, value)
  same as fm_value_in_array, but works with an unexpanded string
  (i.e. not in array form) -- good for searches without having to
  first expand into an array.
    returns: true if match is found
    created: 19990722
