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

Last change on this file since 1726 was 735, checked in by Kevin Toppenberg, 15 years ago

Template formulas will calculate even if responses have characters, bug fixes

File size: 18.4 KB
Line 
1$TXT Created by TOPPENBERG,KEVIN at FAMILY PHYSICANS OF GREENEVILLE (KIDS) on Wednesday, 02/18/09
2=============================================================================
3Run Date: MAR 31,2010 Designation: TMG-CPRS-TEXTOBJ-PARAM*1.0*1
4Package : TMG - FAMILY PHYSICANS OF GREENEVILLE Priority: Optional
5Version : 1 SEQ #1 Status: Released
6=============================================================================
7
8Associated patches: None
9
10Subject: Patch to passing parameters to TIU text objects, both from CPRS, but also from
11 other places within VistA
12
13**NOTICE: This patch will replace the routine TIUSRVD in order to provide a
14 custom version of $$BOIL^TIUSRVD. The first two lines of the new
15 routine are below. Before installing this patch, compare this to
16 your particular version of this routine. **If your routine is newer
17 than the one provided, then see instructions below for manually
18 inserting new routine, and DO NOT APPLY THIS PATCH.
19
20 TIUSRVD ; SLC/JER - RPC's for document definition ; 09/12/2003 [6/8/05 8:07am]
21 ;;1.0;TEXT INTEGRATION UTILITIES;**1,7,22,47,103,100,115,164,112,186,201**;Jun 20, 1997
22
23Category:
24 - Routine
25
26Description:
27============
28 This patch provides new functionality, as described below.
29
30 Expanded Template Functions, including math functions and dynamic text objects
31 ------------------------------------------------------------------------------
32 * The traditional CPRS template functionality allowed syntax as below.
33 This is a test template for |PATIENT NAME|
34
35 Enter value: {FLD:NUMB1-16}
36
37 * The above template would result in the patient name, pulled from the server, to be placed in the final document. It would also generate a GUI box with a field that the user can interact with. In the example below, the field "NUMB1-16" happens to be a drop-down box. When the user selects a number and presses [OK], the resulting text is inserted into the note. However, nothing more can be done with the user input inside the template.
38
39 * The new extension allows syntax as below:
40
41 This is a test template for |PATIENT NAME|
42
43 Enter value: {FLD:NUMB1-16}
44 Enter value: {FLD:NUMB1-16}
45
46 Result 1: {FN: [FLD:1:NUMB1-16] + [FLD:2:NUMB1-16] }
47
48 * The above template would present the user with a GUI box containing two drop-down boxes. And the output text would evaluated in a math function. In this case the math function is a simple addition of the two fields. Notice the syntax of how to identify which field is being referred to. So [FLD:1:NUMB1-16] refers to the first instance of the field, and [FLD:2:NUMB1-16] is the second instance of this same field. More details on this syntax below.
49
50 * The following syntax is also allowed. This will cause a text object (in this example it is the object |PATIENT NAME|). By itself, the only difference between this and simply including the object directly into the template is that that text object is not resolved (i.e. value obtained from the server) until after the user presses OK on the GUI box. More below.
51
52 Result 3: {OBJ:PATIENT NAME}
53
54 * If the TMG-CPRS-TEXTOBJ-PARAM patch is installed then one may pass parameters into text objects. And thus one can also use the value from a field as one of the parameters. (The server code supporting the custom text objects must be programmed to accept the custom parameter. Syntax to be detailed further below. ) Examples of syntax:
55
56 This is a sample of a plain text object: |PATIENT NAME|
57
58 And this is an object with a parameter |MY TEXT OBJECT{5}|
59 or another object with a parameter |MY TEXT OBJECT{Some Text}|
60
61 * And now one may see the value of the {OBJ:... syntax Below is an example of a text object being passed with user-generated input as a parameter. The value of the second GUI field is resolved into it's output value, and this is passed as a parameter into the text object.
62
63 Enter value: {FLD:NUMB1-16}
64 Enter value: {FLD:NUMB1-16}
65
66 {OBJ:MY TEXT OBJECT{[FLD:2:NUMB1-16]}}
67
68 So, if the user selected a value of "1" for the first drop-down box, and "9" for the second drop down box, then the object would be resolved as follows:
69
70 {OBJ:MY TEXT OBJECT{9}}
71
72 And the server code might be written to return a value like this:
73
74 "The user entered: 9" (or something more clinically useful)
75
76 * The {OBJ:... syntax may also be used in math formulas. Of course, the output of the text object would have to be text that was only a numeric value. So, we could have a text object that converted weight into a body-mass-index (BMI). And this value could then used in a formula. In the example below, the field WEIGHT-LB provides a text box for the user to enter the patient weight in pounds. (This field would have to be created in CPRS just like all other fields. See standard CPRS documentation for details.) And for the example, we will have a custom text object named "PT WEIGHT TO BMI". (And this text object would have to be defined on the server. More on this further below). There is no clinical reason why one would want to subtracting 5 from a patient�s BMI. But it demonstrates what is possible.
77
78 Enter value: {FLD:WEIGHT-LB}
79 Here is the result of the formula: {FN:[OBJ:PT WEIGHT TO BMI{[FLD:1:WEIGHT-LB]}]-5}
80
81 * Details on referring to fields in functions and text objects. Consider the example template below:
82
83 Enter value: {FLD:NUMB1-16} <--- 1st instance of NUMB1-16
84 Enter Units: {FLD:UNITS}
85 Enter location: {FLD:LOCATION}
86 Enter value: {FLD:NUMB1-16} <--- 2nd instance of NUMB1-16
87 Enter Units: {FLD:UNITS}
88 Enter location: {FLD:LOCATION}
89 Enter value: {FLD:NUMB1-16} <--- 3rd instance of NUMB1-16
90 Enter location: {FLD:LOCATION}
91 Enter Units: {FLD:UNITS}
92
93 To refer to the 3rrd instance of the field NUMB1-16, use this syntax:
94
95 [FLD:3:NUMB1-16]
96
97 Notice that this is not the 3rd field on the form (that actually would be the first instance of the LOCATION field). But it is the 3rd time that NUMB1-16 is used. So the following rules apply:
98 i) Entire reference is enclosed in square brackets ("[", "]")
99 ii) Starts with "FLD:", which must be UPPER CASE
100 iii) Next is an instance number that refers to a particular field,
101 as described above, followed by another ":".
102 iv) And lastly is specified the Field name, which must exactly match
103 in spelling and case-sensitivity.
104 v) Notice the similarity between the declaration and the reference,
105 so as not to get confused.
106
107 {FLD:NUMB1-16} <--- used by CPRS to make a GUI input field for user
108 [FLD:3:NUMB1-16] <--- used, in a FN or OBJ to refer to a field.
109
110 * To refer to an text object in a function, the following syntax rules apply:
111 i) Entire reference is enclosed in square brackets ("[", "]")
112 ii) Starts with "OBJ:", which must be UPPER CASE
113 iii) Next is the name of the text object. This is the name normally
114 placed between "|" characters. The "|" may be included or left off.
115
116 [OBJ:MY OBJECT] <---- Correct
117 [OBJ:|MY OBJECT|] <---- Also correct
118
119 iv) If text object supports passing parameters, they must be surrounded by
120 curly brackets ("{", "}"). E.g.
121
122 [OBJ:MY OBJECT{123}]
123
124 Only one parameter may be passed. If one needs to pass more than one
125 parameter into a function, one may place then all into one long string,
126 separated by some unique character, e.g.
127
128 [OBJ:MY OBJECT{123^ABC}]
129
130 The server-side function would receive this as a parameter and then
131 have to separate the parts itself. It is allowed to use this syntax
132 with multiple field entries. E.g.
133
134 [OBJ:MY OBJECT{[FLD:1:NUMB1-16]^[FLD:3:NUMB1-16]}]
135
136 v) The order of resolution is to first resolve all FLD values, and then resolve
137 OBJ items.
138 vi) Having a text object as the parameter of another text object is allowed. E.g.
139
140 [OBJ:MY OBJECT{[OBJ:ANOTHER OBJECT]}]
141
142 * The syntax for functions is as follows:
143 i) Example function: {FN:(1+5)*3}
144 ii) Entire function is enclosed in curly brackets. ("{", "}").
145 iii) Starts with "FN:" which must be UPPER CASE.
146 iv) All white space between ":" and closing "}" is not significant, and is removed.
147 v) FLD values will be resolved first, then OBJ values, and then the function will
148 be evaluated.
149 vi) The mathematical expression must follow the following rules:
150 (1) The only operators supported are: ^,*,/,+,-
151 (2) There must be the same number of begin and end brackets.
152 (3) Only the round brackets can be used, i.e. "(", ")"
153 (4) All values must be valid constants. A "valid constant," for this program,
154 is defined as a string with:
155 (a) No characters besides "0".."9," up to one ".",
156 (b) Up to one "-" at the beginning
157 (c) The string must be at least one character in length
158 (d) Exponential sections are not supported, ie. "3.14E-10"
159 is not supported.
160 vii) If there is a problem evaluating the mathematical formula, then the output is just
161 the text of the formula, inserted into the note text, without being evaluated.
162
163 * Information for creating custom server-side text objects to accept parameters.
164 i) On the server, in roll-and-scroll mode, go to menu option:
165 TIUF DOCUMENT DEFINITION MGR
166 ii) From there, select option Create Objects [TIUFJ CREATE OBJECTS MGR]
167 iii) From here, one can create text objects. See TIU documentation for details. The
168 key factor is to make an entry into the Object Method field. This should be a
169 function that returns a value for X that will be put into the note in CPRS.
170 Below is an example of the traditional way this is done:
171
172 SET X="This is a test", or
173 SET X=$$GETOBJ^TMGABC
174
175 iv) To accept the passed parameter, one should change the object function to accept a
176 variable X. X is preloaded with the passed parameter. E.g.
177
178 SET X=$$GETOBJ^TMGABC(X)
179
180 v) The above requires a custom version of the function $$BOIL^TIUSRVD, which is supplied
181 in patch TMG-CPRS-TEXTOBJ-PARAM. This can be found here:
182
183 https://trac.opensourcevista.net/browser/cprs/branches/tmg-cprs/Server_KIDS
184
185INSTRUCTIONS FOR MANUALL INSERTING NEW ROUTINE:
186==============================================
187
188This patch will replace the routine TIUSRVD in order to provide a custom version of
189$$BOIL^TIUSRVD. The first two lines of the new routine are below.
190
191TIUSRVD ; SLC/JER - RPC's for document definition ; 09/12/2003 [6/8/05 8:07am]
192;;1.0;TEXT INTEGRATION UTILITIES;**1,7,22,47,103,100,115,164,112,186,201**;Jun 20, 1997
193
194Before installing this patch, compare this to your particular version of this routine.
195**If your routine is newer than the one provided, then see instructions below for manually
196inserting new routine, and DO NOT APPLY THIS PATCH. Otherwise you may **skip this section**.
197
198 1. Open the routine TIUSRVD in an editor.
199 2. Search for tag/label BOIL
200 3. Rename BOIL to BOIL0 as follows
201 BOIL0(LINE,COUNT) ; Execute Boilerplates ;"//kt original function name was BOIL (mod is below)
202 4. Locate the tag/label: CANXEC(TIUODA)
203 5. Insert the code below on the line before CANXEC
204
205------Begin Code Copy Section----------
206 ;
207BOIL(LINE,COUNT) ; Execute Boilerplates ;"//kt modification
208 ;"Purpose: Resolve Text Objects. Function is modified to allow |TEXT OBJECT{Parameters}|
209 ;"Input: LINE -- One line of text that has one or more text objects
210 ;" COUNT -- (not used)
211 ;"Results: Returns line of text with text objects resolved.
212 ;"NOTE: [Parameter] may itself be a nested text object (arbitrary depth allowed)
213 ;"Usage -- in text object definition, code may be like this:
214 ;" S X=$$MYFN^MYMOD(X)
215 ;" The value for X being passed into the object's code will hold the
216 ;" parameter found between { }
217 ;" This is backwards compatible. If no parameter is specified, then X=""
218 N TIUNEWG,TIUNEWR,TIUOLDG,TIUOLDR,TMGX
219 N TIUI,DIC,X,Y,TIUFPRIV S TIUFPRIV=1
220 S DIC=8925.1,DIC(0)="FMXZ"
221 S DIC("S")="I $P($G(^TIU(8925.1,+Y,0)),U,4)=""O"""
222 F TIUI=2:2:$L(LINE,"|") D
223 . NEW SA,SB
224 . SET X=$$MXTRACT(LINE,"|",.SA,.SB)
225 . IF X["{" DO
226 . . NEW X1,X2
227 . . SET TMGX=$$MXTRACT(X,"{",.X1,.X2)
228 . . IF TMGX["|" SET TMGX=$$BOIL(TMGX)
229 . . SET X=X1_X2
230 . ELSE SET TMGX=""
231 . D ^DIC
232 . I +Y>0 DO
233 . . I $D(^TIU(8925.1,+Y,9)),+$$CANXEC(+Y) DO
234 . . . SET X=TMGX ;"Load passed parameter (or "" if none) into X
235 . . . X ^(9)
236 . . . S:X["~@" X=$$APPEND(X)
237 . . E S X="The OBJECT "_X_" is INACTIVE...Contact IRM."
238 . . I X["~@" D
239 . . . I X'["^" D
240 . . . . S TIUOLDR=$P(X,"~@",2),TIUNEWR=TIUOLDR_TIUI
241 . . . . M @TIUNEWR=@TIUOLDR K @TIUOLDR
242 . . . . S $P(X,"~@",2)=TIUNEWR
243 . . . I X["^" D
244 . . . . S TIUOLDG=$P(X,"~@",2),TIUNEWG="^TMP("_"""TIU201"""_","_$J_","_TIUI_")"
245 . . . . M @TIUNEWG=@TIUOLDG K @TIUOLDG
246 . . . . S $P(X,"~@",2)=TIUNEWG
247 . ELSE S X="The OBJECT "_X_" was NOT found...Contact IRM."
248 . SET LINE=SA_X_SB
249 Q LINE
250 ;
251MXTRACT(S,DIVCH,SA,SB,MAP) ;"//kst added this function
252 ;" Extract matched encapsulators
253 ;" NOTE: see TMGSTUTL for a more robust version of function.
254 IF '$DATA(MAP) DO MAPMATCH(S,.MAP)
255 NEW RESULT SET RESULT=""
256 NEW I SET I=0
257 FOR S I=$O(MAP(1,I)) QUIT:(I="")!(RESULT'="") DO
258 . IF DIVCH'=$G(MAP(1,I)) QUIT
259 . NEW P,J
260 . FOR J=1,2 SET P(J)=+$G(MAP(1,I,"P",J))
261 . SET RESULT=$EXTRACT(S,P(1)+1,P(2)-1)
262 . SET SA=$EXTRACT(S,1,P(1)-1),SB=$EXTRACT(S,P(2)+1,9999)
263 IF RESULT="" SET SA=S,SB=""
264 QUIT RESULT
265 ;
266MAPMATCH(S,MAP) ;"//kst added this function
267 ;" Map out a string for matched encapsulators
268 ;" NOTE: see TMGSTUTL.m for a more robust version of function.
269 N MATCH,DEPTH,I,GRP,CH
270 S MATCH("{")="}",MATCH("|")="|"
271 K MAP
272 S DEPTH=0,GRP=1
273 F I=1:1:$L(S) D Q:(GRP>1) ;"Only deal with 1st entry
274 . S CH=$EXTRACT(S,I)
275 . I CH=$G(MAP(GRP,DEPTH,"End")) D QUIT
276 . . S MAP(GRP,DEPTH,"P",2)=I
277 . . K MAP(GRP,DEPTH,"End")
278 . . S DEPTH=DEPTH-1
279 . . I DEPTH=0 S GRP=GRP+1
280 . I $D(MATCH(CH))=0 QUIT
281 . S DEPTH=DEPTH+1
282 . S MAP(GRP,DEPTH)=CH
283 . S MAP(GRP,DEPTH,"End")=MATCH(CH)
284 . S MAP(GRP,DEPTH,"P",1)=I
285 QUIT
286 ;
287------End Code Copy Section----------
288
289AUTOMATIC INSTALLATION INSTRUCTIONS:
290==========================
291 This patch should cause minimal impact on live systems, as it provides only 1 routine,
292 Installation will take less than 1 minute. Users may remain on the system. Note: the
293 follow instructions were copied from another KIDS install and modified. There may be
294 some discrepancies.
295
296 The following are instructions for those using the Packman method:
297 ------------------------------------------------------------------
298 1. Use the INSTALL/CHECK MESSAGE option on the PackMan menu.
299
300 2. Review your mapped set. If any of the routines listed in the
301 ROUTINE SUMMARY section are mapped, they should be removed
302 from the mapped set at this time.
303
304 3. From the Kernel Installation and Distribution System Menu, select
305 the Installation menu.
306
307 4. From this menu, you may elect to use the following options
308 (when prompted for INSTALL NAME, enter TMG-CPRS-TEXTOBJ-PARAM*1.0*1:
309 a. Backup a Transport Global
310 b. Compare Transport Global to Current System
311 c. Verify Checksums in Transport Global
312
313 5. Use the Install Package(s) option and select the package TMG-CPRS-TEXTOBJ-PARAM*1.0*1
314
315 6. When prompted 'Want KIDS to INHIBIT LOGONs during the install? YES//'
316 respond NO.
317
318 7. When prompted 'Want to DISABLE Scheduled Options, Menu Options, and
319 Protocols? YES//', respond NO.
320
321 8. If routines were unmapped as part of step 2, they should be returned
322 to the mapped set once the installation has run to completion.
323
324 9. (See step 9 below)
325
326 The following are instructions for those loading the patch via Host File System:
327 ---------------------------------------------------------------------------------
328 1. Navigate the menu option path to reach the Kernel Installation and Distribution
329 System Menu. Or, the menu option XPD MAIN may be entered directly.
330
331 2. Next, at the menu displaying:
332 Edits and Distribution ...
333 Utilities ...
334 Installation ... <---------- pick this one.
335
336 3. Next, at the menu displaying the options as below, choose each of the options
337 in a step-by-step fashion, in numerical order (i.e. 1, 2, 3 etc.) Step #1 will
338 prompt the user to enter the file path on the host file system where the source
339 file is stored. The filename to enter is TMG-CPRS-TEXTOBJ-PARAM-1.0-1.KIDS, but add the
340 appropriate path. E.g. /tmp/TMG-CPRS-TEXTOBJ-PARAM-1.0-1.KIDS
341
342 1 Load a Distribution
343 2 Verify Checksums in Transport Global
344 3 Print Transport Global
345 4 Compare Transport Global to Current System
346 5 Backup a Transport Global
347 6 Install Package(s)
348 Restart Install of Package(s)
349 Unload a Distribution
350
351 4. From this menu, you may elect to use the following options
352 (when prompted for INSTALL NAME, enter TMG-CPRS-TEXTOBJ-PARAM*1.0*1
353 a. Backup a Transport Global
354 b. Compare Transport Global to Current System
355 c. Verify Checksums in Transport Global
356
357 5. Use the Install Package(s) option and select the package TMG-CPRS-TEXTOBJ-PARAM*1.0*1
358
359 6. When prompted 'Want KIDS to INHIBIT LOGONs during the install? YES//'
360 respond NO.
361
362 7. When prompted 'Want to DISABLE Scheduled Options, Menu Options, and
363 Protocols? YES//', respond NO.
364
365 8. If routines were unmapped as part of step 2, they should be returned
366 to the mapped set once the installation has run to completion.
367
368
369=============================================================================
370User Information:
371Entered By : TOPPENBERG,KEVIN Date Entered : MAR 31,2010
372Completed By: TOPPENBERG,KEVIN Date Completed: MAR 31,2010
373Released By : TOPPENBERG,KEVIN Date Released : MAR 31,2010
374=============================================================================
375
376Packman Mail Message:
377=====================
378
379$END TXT
Note: See TracBrowser for help on using the repository browser.