source: cprs/branches/tmg-cprs/Server_KIDS/TMG-CPRS-TEXTOBJ-FMFLD-1.0-1.TXT@ 1699

$TXT Created by TOPPENBERG,KEVIN at FAMILY PHYSICANS OF GREENEVILLE (KIDS) on Sunday, April 18, 2010
============================================================================
Run Date: APR 18,2010             Designation: TMG-CPRS-TEXTOBJ-FMFLD*1.0*1
Package : TMG - FAMILY PHYSICANS OF GREENEVILLE  Priority: Optional
Version : 1       SEQ #1                       Status: Released
============================================================================


Subject: Patch to provide custom TIU TEXT OJBECT from CPRS

Category:
  - Routine

Dependancies:
============
  1. TMG-CPRS-TEXTOBJ-PARAM*1.0*1 is required for the installation of this patch.
  2. TMG-CPRS version of CPRS client is required.

License:
============
  This patch is copyright 04/18/2010.  GNU Lessor General Public License (LGPL) applies.

Authors:
============
  Kevin Toppenberg, Greeneville Family Physicians, PC

Description:
============
  This patch provides a TIU TEXT object that can be included
on templates in CPRS.  This object will allow fetching the
value of any field from the PATIENT file.

Usage:
   |TMG PATIENT FLD{Field(s)^Flags^FormatString}|

Field(s) -- required.  Options for input:
      -  A single field number or name
      -  A list of field numbers (or names), separated by semicolons
      -  A range of field numbers (or names), in the form M:N,
         where M and N are the end points of the inclusive range.
         All field numbers within this range are retrieved.
      -  A '*' for all fields at the top level (no sub-multiple record).
      -  A '**' for all fields including all fields and data in sub-multiple fields.
      -  Field number (or name) of a multiple followed by an * to indicate all
         fields and records in the sub-multiple for that field.
      Note: Invalid field names will be ignored

Flags -- Optional.
      -  'F' -- include field name in results with value.  e.g. "AGE: 43" instead of
                just "43"
      -         This flag is ignored if a FormatString is provided (see below)
      -  'S' -- Keep all data values on a single line, separated by ';'.
      -         If flag not provided, and multiple data fields are requested,
      -         then the default is that each data value will be separated by a
      -         CRLF [$C(13)_$C(10)]
      -         This flag is ignored if a FormatString is provided (see below)
      -  'R' -- Resolve fields to NAMES, even if a field NUMBER was used for input request
      -         Note: this will affect the sorting order of the output (see
                FormatString info below).  I.e. if R not specified, and field NUMBERS
                are used for input, then results will be returned in numerical field
                number order by default.   
      -         If R is specified, then field numbers are converted to field NAMES,
                and that is used to determine the order of output.
      -  'N' -- Don't return values for empty fields.  This is helpful if ALL fields
      -         were requested via '*'

FormatString -- A string to determine how results are passed back....
      NOTE: without a format string, results will be passed back in the order
            returned by fileman.  I.e. if user requested fields "SEX;.01;AGE", then
            Fileman will place results into an array, which MUMPS will sort
            alphabetically, e.g. .01, then AGE, then SEX.  If "*" fields are
            requested, it would be even more complex.  A format string will
            allow the user to specify ORDER.   
      Format: e.g. "Any arbitrary text %FieldNameOrNum% more text %FieldNameOrNum%..."
              (The goal was to follow the method used by printf in the c language.)
        -  Any arbitrary text can be included.
        -  Field numbers or names should be enclosed by the '%' character
   These will be replaced with actual data values.
        - '\n' can be included to specify line breaks
        - '%%' will be used to show a '%' in the output text
        - Invalid, or non-matching, field names/numbers will be ignored.

Results: returns a string that will be sent back to CPRS, to be included in a text note


Examples of usage from CPRS:
============================
Simple examples:  
  |TMG PATIENT FLD{.01}|     -- returns .01 field, which is the patients NAME, e.g. "SMITH,JOHN A"
  |TMG PATIENT FLD{NAME}|    -- returns same value as above, e.g. "SMITH,JOHN A"
  |TMG PATIENT FLD{NAME^F}|  -- e.g result "NAME: SMITH,JOHN A"

More complex examples:
  |TMG PATIENT FLD{NAME;SEX;AGE^F}| 
        --> "AGE: 34"_$C(13)_$C(10)_"NAME: SMITH,JOHN A"_$C(13)_$C(10)_"SEX: MALE"
        And in CPRS, will show as:
          AGE: 34
          NAME: SMITH,JOHN A
          SEX: MALE
        **Notice that results are returned in alphabetical order, based on field name,
          not on order of requested fields.

  |TMG PATIENT FLD{NAME;SEX;AGE^S}| 
        --> "34; SMITH,JOHN A; MALE"
        **Notice that results are returned in alphabetical order, based on field name

  |TMG PATIENT FLD{NAME;SEX;AGE^^NAME: %NAME%, %AGE% yrs., %SEX%}|
        --> "NAME: SMITH,JOHN A, 34 YRS., MALE"
        **Notice that use of format string allows results to be returned in expected order

NOTE:
============
  The code has been developed on a GT.M mumps system.  Every attempt was made to use coding 
  techniques that would be cross-platform to Cache'.  But the patch has NOT been tested on 'Cache'.
   
INSTALLATION INSTRUCTIONS:
==========================
  This patch should cause minimal impact on live systems, as it provides only 1 routine,
  Installation will take less than 1 minute.  Users may remain on the system in roll-and-
  scroll mode.

  NOTE HOWEVER: All CPRS applications should be exited before installing the patch.  Otherwise
  CPRS users will find that the RPC call has been redirected to a routine that does not yet
  exist in their instance.  In GT.M, recompilation of routines etc only occurrs with a client
  first connects to the server.  We are not sure if this behavior applies to Cache' systems.  But
  the safest approach would be to have all users of CPRS exit their applications, and restart
  after application of the patch.

  Note: the follow instructions were copied from another KIDS install and modified.  There may be
  some discrepancies.

  The following are instructions for those using the Packman method:
  ------------------------------------------------------------------ 
  1.  Use the INSTALL/CHECK MESSAGE option on the PackMan menu.
   
  2.  Review your mapped set.  If any of the routines listed in the
      ROUTINE SUMMARY section are mapped, they should be removed
      from the mapped set at this time.
   
  3.  From the Kernel Installation and Distribution System Menu, select
      the Installation menu.
   
  4.  From this menu, you may elect to use the following options
      (when prompted for INSTALL NAME, enter TMG-CPRS-TEXTOBJ-FMFLD*1.0*1:
          a.  Backup a Transport Global
          b.  Compare Transport Global to Current System
          c.  Verify Checksums in Transport Global
   
  5.  Use the Install Package(s) option and select the package TMG-CPRS-TEXTOBJ-FMFLD*1.0*1
   
  6.  When prompted 'Want KIDS to INHIBIT LOGONs during the install? YES//'
      respond NO.
   
  7.  When prompted 'Want to DISABLE Scheduled Options, Menu Options, and
      Protocols? YES//', respond NO.
   
  8.  If routines were unmapped as part of step 2, they should be returned
      to the mapped set once the installation has run to completion.

  9.  (See step 9 below)

  The following are instructions for those loading the patch via Host File System:
  ---------------------------------------------------------------------------------
  1.  Navigate the menu option path to reach the Kernel Installation and Distribution
      System Menu.  Or, the menu option XPD MAIN may be entered directly.

  2.  Next, at the menu displaying:
          Edits and Distribution ...
          Utilities ...
          Installation ...     <---------- pick this one.

  3.  Next, at the menu displaying the options as below, choose each of the options
      in a step-by-step fashion, in numerical order (i.e. 1, 2, 3 etc.)  Step #1 will
      prompt the user to enter the file path on the host file system where the source
      file is stored.  The filename to enter is TMG-CPRS-TEXTOBJ-FMFLD*1.0*1.KIDS, but add the
      appropriate path.  E.g. /tmp/TMG-CPRS-TEXTOBJ-FMFLD*1.0*1.KIDS

       1      Load a Distribution
       2      Verify Checksums in Transport Global
       3      Print Transport Global
       4      Compare Transport Global to Current System
       5      Backup a Transport Global
       6      Install Package(s)
              Restart Install of Package(s)
              Unload a Distribution

  4.  From this menu, you may elect to use the following options
      (when prompted for INSTALL NAME, enter TMG-CPRS-TEXTOBJ-FMFLD*1.0*1
          a.  Backup a Transport Global
          b.  Compare Transport Global to Current System
          c.  Verify Checksums in Transport Global
   
  5.  Use the Install Package(s) option and select the package TMG-CPRS-TEXTOBJ-FMFLD*1.0*1
   
  6.  When prompted 'Want KIDS to INHIBIT LOGONs during the install? YES//'
      respond NO.
   
  7.  When prompted 'Want to DISABLE Scheduled Options, Menu Options, and
      Protocols? YES//', respond NO.
   
  8.  If routines were unmapped as part of step 2, they should be returned
      to the mapped set once the installation has run to completion.


=============================================================================
User Information:                               
Entered By  : TOPPENBERG,KEVIN            Date Entered : Apr 18,2010
Completed By: TOPPENBERG,KEVIN            Date Completed: Apr 18,2010
Released By : TOPPENBERG,KEVIN            Date Released : Apr 18,2010
=============================================================================

Packman Mail Message:
=====================

$END TXT