Core API

This is the main FreeMED API, which contains the bulk of FreeMED’s commonly used functions.  The rest of the functions are located in classes which are called dynamically using CreateObject().  It is located in lib/API.php.

Summary
This is the main FreeMED API, which contains the bulk of FreeMED’s commonly used functions.
Query ACL for a particular resource.
Check ACLs, optionally with patient access.
Checks to see if the current user has access to the specified facility.
Checks to see whether the current user has access to the specified patient.
Retrieves a configuration value from FreeMED’s centralized configuration database table.
Check configuration value against user database then system configuration database.
Master function to run authentication routines for the current used.
Determine dates between two YYYY-MM-DD dates.
Creates a drug selection widget.
Get a database table record by its “id” field.
Return a single field from a particular database table from its “id” field.
Set breakpoint for handlers for a certain function
Creates an SQL “WHERE” clause based on search information provided by <freemed::display_itemlist>, as used by most of FreeMED’s modules.
Resolves a stored document’s full path based on the qualifiers presented.
Set key binding for a particular key or set of keys.
Determines whether a module is installed in the system, and optionally whether it is above a certain minimum versioning number.
Check to see if module is allowable via ACLs
Gets a cached module value (such as “MODULE_NAME”, etc) from the module cache.
Gets cached metainformation for the specified module in the module cache.
Provides global access to a PHP.module_list object with cached module information.
Returns the list of modules associated with a certain handler.
Lookup the module name as needed by FreeMED’s module calls, but by the class name of the module.
Registers module or newer version of module in FreeMED’s global module registry.
Get list of tables for modules.
Get table name from module name.
Get the current version number of a particular module in FreeMED from the module database table.
Create a multiple-choice widget
Create a “patient box” with quick access to various patient functions.
Create a patient selection widget
Create XHTML widget to represent printer selection
Dumps the output of an SQL query to a multidimentional hashed array.
Perform internationalization (i18n) on an HTML_QuickForm PEAR object.
Create HL7 v2.3.1 compliant race widget (table 0005)
Creates a rich text editing widget (HTML)
Remove potentially hazardous characters from filenames
Convert an SQL timestamp (such as MySQL timestamps) into a nice-looking date string.
Stores posted file in scanned document image store.
Determines whether the current browser supports DjVu.
Resolve file to existing either in default template or current template.
Determine if a particular user flag is set for the current user.
Determine if the current user has the ability to “override” the locking of a record.
Get log object with caching.
Displays phone number in system format.
Create alternating texts.
Creates the ADD/RETURN TO MENU bar present in most FreeMED modules.
Creates a paginated list display based on formatting data for a particular result set.
Creates an XHTML facility selection widget.
Create an XHTML selection box
Export FreeMED database table to a file
Import an SQL table into FreeMED
Get next valid SQL format date (YYYY-MM-DD)
Get previous date in SQL format (YYYY-MM-DD)
Assemble seperate date fields into single SQL format date hash
Creates XHTML-compliant date selection widget
Create a nicely formatted date display
Convert array to XHTML input type=HIDDEN tags
Create an XHTML compliant number selection widget
Display the current template
Push page onto global history stack.
Pop off page from global history stack.
Push patient onto global history stack.
Get global history list for patients
Get global history list for pages
Contruct a help link from the specified page and section
Check current basic authentication against users in the database.

Functions

freemed:: acl

Query ACL for a particular resource.

Parameters

$categoryWhich category of ARO is being queried.  Examples would be things like ‘admin’, ‘bill’, ‘schedule’, et cetera.
$permissionResource being queried.  This would be things like ‘add’, ‘modify’, ‘view’, ‘delete’, et cetera.
$axo_group(optional) AXO group to be searched on.  Note that valid groups are things like ‘patient’.
$axo_item(optional) AXO item.  This would be the patient ID key for a patient, or something else for another AXO group.

Returns

Boolean, depending on whether the resource is allowed or denied.

freemed:: acl_patient

Check ACLs, optionally with patient access.  Note that this function behaves exactly like freemed::acl if the acl_patient configuration value is disabled.

Parameters

$categoryWhich category of ARO is being queried.  Examples would be things like ‘admin’, ‘bill’, ‘schedule’, et cetera.
$permissionResource being queried.  This would be things like ‘add’, ‘modify’, ‘view’, ‘delete’, et cetera.
$pidPatient id number (record id) for patient being checked.

Returns

Boolean, whether access is granted.

See Also

freemed::acl

freemed:: check_access_for_facility

Checks to see if the current user has access to the specified facility.

Parameters

$facility_numberthe database id of the facility in question

Returns

$accessboolean value, whether access is granted

See Also

freemed::check_access_for_patient

freemed:: check_access_for_patient

Checks to see whether the current user has access to the specified patient.

Parameters

$patient_numberThe database identifier for the patient
$user (optional)The database identifier for the current user.  (This should be used when dealing with XML-RPC or another protocol which does not use cookie-based authentication.

Returns

$accessboolean, whether access is granted

See Also

freemed::check_access_for_facility

freemed:: config_value

Retrieves a configuration value from FreeMED’s centralized configuration database table.

Parameters

$keyThe name of the configuration value desired.

Returns

$valueThe value of the configuration key, or NULL if the key is not found.

freemed:: config_user_value

Check configuration value against user database then system configuration database.

Parameters

$keyThe name of the configuration value desired.

Returns

$valueThe value of the configuration key, or NULL if the key is not found.

See Also

freemed::config_value

freemed:: connect

Master function to run authentication routines for the current used.  This method should be called at the beginning of every standalone FreeMED script when dealing with standard session based authentication.

freemed:: dates_between

Determine dates between two YYYY-MM-DD dates.

Parameters

$startStarting date in YYYY-MM-DD
$endEnding date in YYYY-MM-DD

Returns

Array of dates in YYYY-MM-DD

freemed:: drug_widget

Creates a drug selection widget.

Parameters

$varnameName of the variable which should contain the drug name.
$formname (optional)Name of the form that contains this widget.  Defaults to “myform”.
$submitname (optional)Name of the variable that is used to pass data between the child window and the parent window.  Defaults to “submit_action”.

Returns

$widgetXHTML compliant widget code

freemed:: get_link_rec

Get a database table record by its “id” field.

Parameters

$idValue of the id field requested.
$tableName of the FreeMED database table.

Returns

$recAssociative array / hash containing key and value pairs, where the key is the name of the database table field, and its associated value is the value found in the database.
$force_no_cache(optional) Boolean, allows defeating of automatic caching, which will distrupt sequential operations.  Defaults to false.

See Also

freemed::get_link_field

freemed:: get_link_field

Return a single field from a particular database table from its “id” field.

Parameters

$idValue of the id field requested.
$tableName of the FreeMED database table.
$fieldName of the field in the database table.

Returns

$valScalar value of the database table field.

See Also

freemed::get_link_rec

freemed:: handler_breakpoint

Set breakpoint for handlers for a certain function

Parameters

$nameName of handler (example: MainMenuNotify)
$paramsArray of parameters to be passed to the associated handlers.  None are passed by default.

freemed:: itemlist_conditions

Creates an SQL “WHERE” clause based on search information provided by <freemed::display_itemlist>, as used by most of FreeMED’s modules.

Parameters

$where (optional)Boolean value, whether a “WHERE” should be prepended to the returned query.  Defaults to true.

Returns

$clauseSQL query “WHERE” clause

freemed:: image_filename

Resolves a stored document’s full path based on the qualifiers presented.

Parameters

$patientPatient identifier
$recordRecord identifier of the “images” table
$typeFile type (usually “djvu”)
$img_store (optional)Boolean, whether or not the relative pathname will be prepended (usually “img/store/”).

Returns

The relative path and file name of the image.

freemed:: key_binding

Set key binding for a particular key or set of keys.

Parameters

$bindingAssociative array of key code => binding.

freemed:: module_check

Determines whether a module is installed in the system, and optionally whether it is above a certain minimum versioning number.

Parameters

$moduleName of the module
$minimum_version (optional)The minimum allowable version of the specified module.  If this is not specified, any version will return true.

Returns

$installedBoolean, whether the module is installed

freemed:: module_check_acl

Check to see if module is allowable via ACLs

Parameters

$moduleModule class name
$permissionPermission type (view, add, mod, et cetera)

Returns

Boolean value, true or false

freemed:: module_get_value

Gets a cached module value (such as “MODULE_NAME”, etc) from the module cache.

Parameters

$moduleName of the module
$keyVariable name in question

Returns

$valValue of the variable name in question

See Also

freemed::module_get_meta

freemed:: module_get_meta

Gets cached metainformation for the specified module in the module cache.  Acts as a wrapper for freemed::module_get_value.

Parameters

$moduleName of the module
$keyHash index of the metainformation in question

Returns

$valValue of the metainformation in question

See Also

freemed::module_get_value

freemed:: module_cache

Provides global access to a PHP.module_list object with cached module information.

Returns

$cacheAn object (PHP.module_list) containing the cached module information.

freemed:: module_handler

Returns the list of modules associated with a certain handler.

Parameters

$handlerScalar name of the handler.  This is case sensitive.

Returns

$modulesArray of modules which are associated with the specified handler.  These all will be in lowercase, so remember to use strtolower().

freemed:: module_lookup

Lookup the module name as needed by FreeMED’s module calls, but by the class name of the module.

Parameters

$classClass name of the module

Returns

$moduleMODULE_NAME of the specified module.

freemed:: module_register

Registers module or newer version of module in FreeMED’s global module registry.

Parameters

$moduleName of module (must be resolved using freemed::module_lookup, or by using MODULE_NAME).
$versionVersion of module to register.

freemed:: module_tables

Get list of tables for modules.

Returns

i18n’d associative array

freemed:: module_to_table

Get table name from module name.

Parameters

$moduleModule name (class name)

Returns

SQL table name

freemed:: module_version

Get the current version number of a particular module in FreeMED from the module database table.

Parameters

$moduleName of module (must be resolved using freemed::module_lookup, or by using MODULE_NAME).

freemed:: multiple_choice

Create a multiple-choice widget

Parameters

$sql_query

$display_fieldHash of the field display format, with ‘##’ surrounding the members of the table.  (For example: ‘##phylname##, ##phyfname##’ from a query on the physician table would print their last name and first name separated by a comma.)
$select_nameName of the variable that the widget is specifying.
$blob_dataThe actual compressed data string which contains the array of values.

$display_all (optional)

Returns

XHTML-compliant multiple choice widget code.

freemed:: patient_box

Create a “patient box” with quick access to various patient functions.

Parameters

$patient_objectAn object of type ‘FreeMED.Patient’ which encapsulates the selected patient’s data.

Returns

XHTML compliant patient box widget code.

freemed:: patient_widget

Create a patient selection widget

Parameters

$varnameThe name of the variable that this widget contains data for.
$formname (optional)Name of the form that this widget is contained in.  Defaults to “myform”.
$submitname (optional)The name of the submit button which is passed to the child window that is created.  Defaults to “submit_action”.
$autosubmit(optional) Whether or not to submit on click.  Boolean, defaults to false.

Returns

XHTML compliant patient selection widget code.

freemed:: printers_widget

Create XHTML widget to represent printer selection

Parameters

$varnameName of the variable which will hold the data returned by this widget

Returns

XHTML compliant widget code

freemed:: query_to_array

Dumps the output of an SQL query to a multidimentional hashed array.

Parameters

$queryText SQL query
$single_dimension(optional) Reduce to single array, using k and v table columns as key and value.  Defaults to true.

Returns

Multidimentional hashed array.

freemed:: quickform_i18n

Perform internationalization (i18n) on an HTML_QuickForm PEAR object.

Parameters

&$objectObject reference

freemed:: race_widget

Create HL7 v2.3.1 compliant race widget (table 0005)

Parameters

$varnameName of the variable which contains this data.

Returns

$widgetXHTML compliant race widget code.

freemed:: rich_text_area

Creates a rich text editing widget (HTML)

Parameters

$varnameName of variable to store the data in
$rows(optional) Vertical size of text area.  Defaults to 10 lines.
$cols(optional) Horizontal size of text area.  Defaults to 60 characters.
$force_js(optional) Force Javascript to be displayed every time.  Defaults to false.

Returns

XHTML-compliant rich text area widget

freemed:: secure_filename

Remove potentially hazardous characters from filenames

Parameters

$originalOriginal filename

Returns

$sanitizedSanitized filename

freemed:: sql2date

Convert an SQL timestamp (such as MySQL timestamps) into a nice-looking date string.

Parameters

$dateSQL timestamp string

Returns

Formatted date/time string

freemed:: store_image

Stores posted file in scanned document image store.

Parameters

$patient_idPatient identifier from the patient table.  Do not pass a patient object.
$varnameThe variable name describing the file that was posted using the HTTP POST method.
$type(optional) This is either ‘identification’ in the case of an identifying photograph, or the record number of this document in the scanned documents table
$encoding(optional) Type of DjVu encoding.  Currently ‘cjb2’ and ‘c44’ encodings are supported.

Returns

Name of file if successful.

freemed:: support_djvu

Determines whether the current browser supports DjVu.

Parameters

$browserPHP.browser_detect object.

Returns

Boolean, whether DjVu is supported or not.

freemed:: template_file

Resolve file to existing either in default template or current template.

Parameters

$fileFilename, relative to the template structure (login_form.php would resolve to lib/template/*/login_form.php)

Returns

Fully qualified template path (lib/template/*/*)

freemed:: user_flag

Determine if a particular user flag is set for the current user.

Parameters

$flagThe flag in question.  This should be something like USER_ADMIN, USER_DELETE, etc.

Returns

True if the flag is set for the current user.

freemed:: lock_override

Determine if the current user has the ability to “override” the locking of a record.

Returns

Boolean value, whether or not the user has override permissions.

freemed:: log_object

Get log object with caching.

Returns

FreeMED.Log object

freemed:: phone_display

Displays phone number in system format.

Parameters

$phonePhone number raw

Returns

Formatted phone number for display

freemed_alternate

function freemed_alternate ($_elements)

Create alternating texts.  Used mostly for alternating row displays, either as CLASS tags or as BGCOLOR tags.

Parameters

$elementsArray of elements which are to be alternated between.  Defaults to array (‘cell’, ‘cell_alt’).

Returns

The next element in the circular loop of the presented array.

freemed_display_actionbar

function freemed_display_actionbar ($this_page_name = "",
$__ref = "")

Creates the ADD/RETURN TO MENU bar present in most FreeMED modules.

Parameters

$page_name(optional) Name of the current page.
$ref(optional) Name of the referring page.  If this is not explicitly set, the global variable ‘_ref’ acts as the default value.

Returns

XHTML compliant actionbar widget.

freemed_display_itemlist

function freemed_display_itemlist ($result,  
$page_link,  
$control_list,  
$blank_list,  
$xref_list = "",
$cur_page_var = "this_page",
$index_field = "",
$flags = -1)

Creates a paginated list display based on formatting data for a particular result set.  This should be used in conjunction with freemed::itemlist_conditions to produce a proper SQL query.

Parameters

$resultSQL query passed to the display.
$page_linkCurrent page name.
$control_listList of column names and database table column names, as an associative array.  (Example: array ( __(“Date”) => ‘procdt’, __(“Procedure Code”) => ‘proccpt’ ) )
$blank_listArray of values for the columns describing what a blank entry should be displayed as.
$xref_list(optional) Associative array describing cross table references.  For example, if your column ‘proccpt’ described a CPT code, you could use ‘cpt’ => ‘cptcode’ to describe the table name (‘cpt’) and the column to be displayed name (‘cptcode’), which would be determined by the value of the corresponding column in $control_list.
$cur_page_var(optional) Pagination tracking variable.  The default is ‘this_page’.
$index_field(optional) Currently this is unused, and should be passed as ‘’ or NULL.
$flags(optional) Bitfield of operators, such as ITEMLIST_MOD | ITEMLIST_DEL.

Returns

XHTML compliant item listing with search widgets.

freemed_display_facilities

function freemed_display_facilities ($param = "",
$default_load =  false,
$intext = "",
$by_array = "")

Creates an XHTML facility selection widget.

Parameters

$varnameName of the global variable containing the data for this widget.
$default_load(optional) Depreciated.
$internal_external(optional) Exclusively internal or external facilities.  If this is passed at all, “0” selects internal facilities and “1” selects external facilities.
$by_array(optional) Array of facility id numbers to limit the selection to.

Returns

XHTML compliant facility selection widget.

freemed_display_selectbox

function freemed_display_selectbox ($result,  
$format,  
$param = "",
$size = "")

Create an XHTML selection box

Parameters

$resultSQL query result
$formatFormat hash for the display box (result field names surrounded by ‘##’s)
$varnameName of the variable to store the selected data in.
$size(optional) Size of the box.  Defaults to default size.

Returns

XHTML compliant selection widget.

freemed_export_stock_data

function freemed_export_stock_data ($table_name,  
$file_name = "")

Export FreeMED database table to a file

Parameters

$table_nameName of the SQL table to export

freemed_import_stock_data

function freemed_import_stock_data ($table_name)

Import an SQL table into FreeMED

Parameters

$table_nameName of the SQL table to import

freemed_get_date_next

function freemed_get_date_next ($cur_dt)

Get next valid SQL format date (YYYY-MM-DD)

Parameters

$dateStarting date

Returns

Next date.

freemed_get_date_prev

function freemed_get_date_prev ($cur_dt)

Get previous date in SQL format (YYYY-MM-DD)

Parameters

$dateStarting date

Returns

Previous date.

fm_date_assemble

function fm_date_assemble ($datevarname = "",
$array_index = -1)

Assemble seperate date fields into single SQL format date hash

Parameters

$varnameName of the date variable
$array_index(optional) Array index of $varname that should contain the result data.

Returns

SQL formated date string.

fm_date_entry

function fm_date_entry ($datevarname = "",
$pre_epoch = false,
$arrayvalue = -1)

Creates XHTML-compliant date selection widget

Parameters

$varnameVariable name to contain the result data.
$pre_epoch(optional) Whether the date selection widget should contain years more than 20 in the past.  Defaults to false.
$array_index(optional) Array index for varname to determine which element of the array is being used.  Defaults to no array index.

Returns

XHTML-compliant date selection widget.

fm_date_print

function fm_date_print ($actualdate,  
$show_text_days = false)

Create a nicely formatted date display

Parameters

$dateSQL formated date
$show_text_days(optional) Whether or not to show the day names as text names.  Defaults to false.

Returns

Formatted date display.

fm_htmlize_array

function fm_htmlize_array ($variable_name,
$cur_array)

Convert array to XHTML input type=HIDDEN tags

Parameters

$varnameVariable name to put the data in
$cur_arrayActual data to be stored

Returns

XHTML input type=HIDDEN tags

fm_number_select

function fm_number_select ($varname,  
$min = 0,
$max = 10,
$step = 1,
$addz = false,
$submit_on_blur =  false)

Create an XHTML compliant number selection widget

Parameters

$varnameName of the variable to store this data in
$min(optional) Minimum value.  Defaults to 0.
$max(optional) Maximum value.  Defaults to 10.
$step(optional) Incrementing value.  Defaults to 1.
$add_zero(optional) Prepend zeros to values under 10.  Defaults to false.
$submit_on_blur(optional) Submit the form when focus on the widget is lost.  Defaults to false.

Returns

XHTML-compliant number selection widget

template_display

function template_display ($terminate_on_execute = true)

Display the current template

Parameters

$terminate(optional) End script execution on termination of function.  Defaults to true.

page_push

function page_push ()

Push page onto global history stack.

page_pop

function page_pop ()

Pop off page from global history stack.

patient_push

function patient_push ($patient)

Push patient onto global history stack.

patient_history_list

function patient_history_list ()

Get global history list for patients

Returns

Array of patients in global history list.

page_history_list

function page_history_list ()

Get global history list for pages

Returns

Array of pages in global history list.

help_url

function help_url ($page =  "",
$section =  "")

Contruct a help link from the specified page and section

Parameters

$page(optional) Name of the page that this relates to.
$section(optional) Subsection of the page.

Returns

Fully formed URL to the specified help page.

check_basic_authentication

function check_basic_authentication ()

Check current basic authentication against users in the database.  This function is broken until phpwebtools is upgraded to support MD5-based basic authentication verification.

Returns

Boolean value, whether user is properly authenticated.

function freemed_alternate ($_elements)
Create alternating texts.
function freemed_display_actionbar ($this_page_name = "",
$__ref = "")
Creates the ADD/RETURN TO MENU bar present in most FreeMED modules.
function freemed_display_itemlist ($result,  
$page_link,  
$control_list,  
$blank_list,  
$xref_list = "",
$cur_page_var = "this_page",
$index_field = "",
$flags = -1)
Creates a paginated list display based on formatting data for a particular result set.
function freemed_display_facilities ($param = "",
$default_load =  false,
$intext = "",
$by_array = "")
Creates an XHTML facility selection widget.
function freemed_display_selectbox ($result,  
$format,  
$param = "",
$size = "")
Create an XHTML selection box
function freemed_export_stock_data ($table_name,  
$file_name = "")
Export FreeMED database table to a file
function freemed_import_stock_data ($table_name)
Import an SQL table into FreeMED
function freemed_get_date_next ($cur_dt)
Get next valid SQL format date (YYYY-MM-DD)
function freemed_get_date_prev ($cur_dt)
Get previous date in SQL format (YYYY-MM-DD)
function fm_date_assemble ($datevarname = "",
$array_index = -1)
Assemble seperate date fields into single SQL format date hash
function fm_date_entry ($datevarname = "",
$pre_epoch = false,
$arrayvalue = -1)
Creates XHTML-compliant date selection widget
function fm_date_print ($actualdate,  
$show_text_days = false)
Create a nicely formatted date display
function fm_htmlize_array ($variable_name,
$cur_array)
Convert array to XHTML input type=HIDDEN tags
function fm_number_select ($varname,  
$min = 0,
$max = 10,
$step = 1,
$addz = false,
$submit_on_blur =  false)
Create an XHTML compliant number selection widget
function template_display ($terminate_on_execute = true)
Display the current template
function page_push ()
Push page onto global history stack.
function page_pop ()
Pop off page from global history stack.
function patient_push ($patient)
Push patient onto global history stack.
function patient_history_list ()
Get global history list for patients
function page_history_list ()
Get global history list for pages
function help_url ($page =  "",
$section =  "")
Contruct a help link from the specified page and section
function check_basic_authentication ()
Check current basic authentication against users in the database.
Query ACL for a particular resource.
Checks to see whether the current user has access to the specified patient.
Checks to see if the current user has access to the specified facility.
Retrieves a configuration value from FreeMED’s centralized configuration database table.
Return a single field from a particular database table from its “id” field.
Get a database table record by its “id” field.
Gets cached metainformation for the specified module in the module cache.
Gets a cached module value (such as “MODULE_NAME”, etc) from the module cache.
Creates an SQL “WHERE” clause based on search information provided by freemed::display_itemlist, as used by most of FreeMED’s modules.